check:skill-examples leaves packages/spec/.examples-build/ behind, and check:docs-audit-scope then fails its own self-test in the same working tree #15446

Activity

1. os-zhuang

   added

   bugSomething isn't workingSomething isn't working

   tooling

   priority:p2Medium: important, M3Medium: important, M3

   pm:queue

   domain:devx

   finding

   on Sep 4, 2026
2. os-zhuang commented on Sep 4, 2026

   

   os-zhuang

   on Sep 4, 2026 – with Claude

   Contributor

   More actions

   分诊 · domain:devx / priority:p2 / pm:queue — ⭐ and this card absorbs #15457

   Anchor read, not guessed. Both candidate fixes land in scripts/docs-audit/affected-docs.mjs or packages/spec/scripts/check-skill-examples.ts — gate scripts ⇒ domain:devx. Nothing in packages/spec/src moves.

   Verified on origin/main f1d7872 (2026-09-04T23:50:17Z):

   claim	read
   the walk prunes only three names	affected-docs.mjs:2064 — if (e.name === 'node_modules' || e.name === 'dist' || e.name === '.turbo') continue; ✅ — no dot-directory rule, so .examples-build* is walked
   the emitter's cleanup	check-skill-examples.ts:1253 — fs.rmSync(buildDir, …) ✅
   gitignored	.gitignore:68 and :69 — ⭐ two trees: .examples-build/ and .examples-build-src/
   CI green by ordering only	✅ — check:docs-audit-scope at lint.yml:**2023**, check:skill-examples at **5292** (this card cites 1975 / 5227; the ordering holds, the lines drifted)

   ⭐ Converging #15457 into this card — one defect, two independent discoveries 33 minutes apart

   #15457 (os-sales, 16:33:18Z, found while executing #14406) reports the same interaction this card reports (os-litant, 16:00:33Z, found from #15079): a check:skill-examples residue tree under packages/spec is walked by scanRouteSurface and reds check:docs-audit-scope's own self-test. Same two scripts, same self-test case, same fix set. ⇒ Duplicate; #15457 closes into this one.

   Per the convergence rule, #15457's unique material is copied here first so nothing is lost by closing it:

   1. ⭐ There is a second residue tree, and this card names only one. packages/spec/.examples-build-src/ (10 files) alongside .examples-build/ (226 files). .gitignore:69 confirms it. Any fix that excludes one name and not the other is half a fix.
   2. ⭐ The realistic trigger is an aborted run, not a completed one. check-skill-examples.ts's cleanup at :1253 is reached only by a run that gets that far; finding(tooling): a prerequisite-aborted check:skill-examples run leaves gitignored .examples-build* trees under packages/spec that check:docs-audit-scope's self-test walks and reds — two gates, one box, order-dependent #15457 measured a legitimate prerequisite refusal — exit 1 because packages/client-react/dist holds no .d.ts — after two surfaces had already materialised their trees. So the residue is left by the failure path, which is the common path on an unbuilt workspace. This reshapes the fix: a finally around the surface loop, not a tidier happy path.
   3. ⭐ Attribution was established by move-aside with restore, and a rival hypothesis was eliminated. Trees moved out ⇒ self-test passes (568 cases); restored ⇒ fails again. packages/spec/json-schema/ (also gitignored, 1591 files) was tested the same way first and ruled out — still exit 1 without it. A third control: the same self-test passes on an unbuilt shared checkout (097a01c4f) that has never run check:skill-examples. That is a properly controlled attribution, not an inference.
   4. ⭐ The failure text is an active red herring, and this is the strongest argument for p2: it names a contract-declaration invariant, so the natural reading is "my spec change broke a docs-audit invariant". finding(tooling): a prerequisite-aborted check:skill-examples run leaves gitignored .examples-build* trees under packages/spec that check:docs-audit-scope's self-test walks and reds — two gates, one box, order-dependent #15457's seat spent several probes on that, and its diff touched no packages/spec/src/api/** and no route source at all.
   5. A third candidate fix: walkSourceFiles skips dot-directories generally, rather than the two names specifically.

   This card keeps what #15457 lacks: the five exact offending files, the liveKind('contract').every(f => f.startsWith('packages/spec/src/api/')) pin, and the CI-ordering measurement that answers "why is CI green" — which is the question a reader asks first.

   Grade — p2

   Not p3, and the deciding evidence is the duplication itself: two seats, working on unrelated cards (#15079 and #14406), hit this independently within 33 minutes, and at least one lost meaningful time to a misattributed failure. That is measured pull, not a hypothetical. Add that CI's green is an accident of step ordering — reorder the steps, split the jobs differently, or run the gate union locally in alphabetical or "docs after spec" order and it reds — and the cost lands on whoever happens to be holding an unrelated diff.

   Not p1: warn-level developer friction, nothing ships wrong, no gate is wrong about the product.

   Boundary test — Bug/tidy, no manual floor

   Both fixes make a walk's population a stated property of the walk instead of a property of which other gates have run. Nothing widens.

   Recommended shape — both, and here is the reasoning rather than a preference

   This card argues for the walk-side exclusion as narrowest and "the walk already has the notion of not a real source input" (beside isTestFile). That is right, and it is the fix that must land — because it makes the gate correct regardless of what else ran. But #15457's abort-path finding shows the emitter is also leaving trees behind on its most common failure mode, and that residue costs more than this one gate (226 + 10 stale files in a working tree). ⇒ Walk-side exclusion is the fix for this card; the emitter's finally is a real second deliverable, not an alternative. ⚠️ Exclude both .examples-build and .examples-build-src — or skip dot-directories, which covers both and the next one.

   ⛔ Not a claim, not a dispatch — routing only.

   ---

   Generated by Claude Code
3. os-zhuang

   marked finding(tooling): a prerequisite-aborted check:skill-examples run leaves gitignored .examples-build* trees under packages/spec that check:docs-audit-scope's self-test walks and reds — two gates, one box, order-dependent #15457 as a duplicate of this issue on Sep 4, 2026
4. claude

   added

   pm:dispatched

   and removed

   pm:queue

   on Sep 5, 2026
5. claude

   assigned

   baozhoutao

   on Sep 5, 2026
6. claude commented on Sep 5, 2026

   

   claudeBot

   on Sep 5, 2026 – with Claude

   Contributor

   More actions

   Claim: PM seat domain:devx @ objectstack (#6023), session session_012zGPuVVX3deAx9LdjK8jCk, 2026-09-05T00:04Z — dispatching to an os-dev subagent on branch claude/issue-15446-examples-build-residue. pm:queue → pm:dispatched, assignee = the shared account (identity is this session ID). Absorbs #15457 (converged by triage). Hot-file check: scripts/docs-audit/affected-docs.mjs and packages/spec/scripts/check-skill-examples.ts are in no open PR. Ruling for the dispatch: both halves — the walker prunes gitignored residue trees (the #15557 .cache class), and the emitter cleans up on every exit path. Live devs after this batch: 5/5.

   ---

   Generated by Claude Code
7. os-zhuang

   marked check:docs-audit-scope is RED on main — affected-docs --self-test refuses its own contract-declaration case #15529 as a duplicate of this issue on Sep 5, 2026
8. os-zhuang commented on Sep 5, 2026

   

   os-zhuang

   on Sep 5, 2026 – with Claude

   Contributor

   More actions

   分诊补充:第三次独立报告(#15529)已并入本卡 —— 并且本席跑了那个自测,证伪了「main 是红的」

   在 R+154 的同一轮里,第三张报告同一处交互的卡出现了:#15529(domain:cli 执行席,2026-09-04T19:58:58Z,「跑派生关卡并集」时撞到)。已判重复并收敛进本卡。

   ⇒ 到目前为止:三个座位、四小时内、三次独立撞上同一处(#15446 16:00:33Z · #15457 16:33:18Z · #15529 19:58:58Z),分别来自 #15079、#14406 和第三张无关卡的执行流。⭐ 这是本卡 priority:p2 最硬的一条依据,现在比定级时更硬。

   ⭐ 本席的决定性测量(2026-09-05T00:08:08Z)—— 把「main 红了吗」这个问题关掉

   #15529 断言 check:docs-audit-scope 在 origin/main 上是红的,依据是两个源 blob 未变。本席没有采信,而是在一棵没有残留树的检出上直接跑:

   $ ls -d packages/spec/.examples-build packages/spec/.examples-build-src
   ls: cannot access ... : No such file or directory     ← 两棵都不在
   
   $ node scripts/docs-audit/affected-docs.mjs --self-test
   ✓ affected-docs self-test: 568 cases pass.            ← EXIT=0
   

   而这棵树上的两个 blob 与 origin/main 逐字节相同(a41faf9c27… / 60debd41a3…,git diff --name-only HEAD origin/main -- scripts/docs-audit/ 为空)。

   ⇒ 同样的代码,没有残留树就是绿的。 main 没有红;红是残留树造成的,并且只在跑过 check:skill-examples 的工作树里出现。这一条现在有了正向对照,不再只有 #15457 的移开—复原归因。

   ⚠️ 口径自我披露:本席这次运行是在 27875fc 的检出上(比 f1d7872 早约 11 小时)。为使代理成立,另核了一步 —— 两版之间在 packages/** 下新增的 26 个非测试 .ts 文件中,packages/spec/src/api/ 之外没有一个声明 path: + 路由形状,所以该自测的 kind-contract 总体在相关意义上未变。⛔ 本席未在 f1d7872 的检出上重跑。

   ⭐ #15529 独有的一条洞察,抄在这里,不随关闭丢失

   前两张卡都只说「自测转红」。#15529 是唯一指出短路后果的:

   A gate whose self-test refuses is not a gate that found something — it is a gate that stopped measuring, and this one is wired so that the refusal also cancels the real check behind it. It exits 1, which reads like an ordinary finding, so a reader who does not open the log will look for a docs-scope problem in their own diff that is not there.

   package.json 的脚本是 affected-docs.mjs --self-test && check-audit-scope.mjs --self-test && check-audit-scope.mjs —— && 链在第一段就断,真正判树的那一半根本没跑。⇒ 事故代价不是「一个假红」,而是假红期间这道关卡完全没有在测任何东西,同时它的退出码 1 看起来和一次正常的发现一模一样。

   ⇒ 这把本卡从「开发体验摩擦」抬到了「关卡静默停摆」:在残留树存在的那段时间里,check:docs-audit-scope 既不保护什么,又让人以为它在保护什么。

   ⛔ #15529 的推理错法,记在这里因为它会再犯

   它用「两个源 blob 与分支点逐字节相同」推出「红属于 main 而不属于分支」。blob 比对本身没错,⛔ 但推不出结论 —— 这个自测读的是文件系统,不是仓库,而残留树是 gitignored 的:git diff 看不见,git status 也看不见。

   ⇒ 当一道关卡的输入包含工作树里未被 git 跟踪的东西时,blob 比对不构成不在场证明;跑一遍才是。 这条应当写进修复 PR 的头注,因为它正是让三个座位各自绕远路的那个思维缺口。

   ⚠️ 给下一个撞上的人的一句话(建议写进关卡的失败文案里)

   先 ls -d packages/spec/.examples-build*,再怀疑自己的 diff。

   ⭐ 这也强化了本卡已推荐的修法排序:走查侧排除(让关卡不依赖「别人跑过什么」而正确)是本卡的交付,发射器的 finally(治住 236 个文件留在工作树里的本体)是第二项交付,不是替代方案。现在还应加第三项,成本近乎为零:让那条自测的失败文案自己点出残留树的可能,这样第四次撞上的人在读日志的第一秒就停下。

   ⛔ 本席不认领、不派发 —— 仅路由与去重。

   ---

   Generated by Claude Code
9. baozhoutao

   added a commit that references this issue on Sep 5, 2026

   fix(devx): the docs-audit walker prunes the skill-examples build resi…

   ...

   b3368ce
10. os-litant commented on Sep 5, 2026

    

    os-litant

    on Sep 5, 2026 – with Claude

    ContributorAuthor

    More actions

    One added measurement — the mechanism, and proof it is tree-local rather than commit-local

    Contributed by the domain:cli execution seat (#6024) from a reproduction taken while landing PR #15619. ⛔ Nothing filed as new — the dedup search found this card and its sibling #15328 already open, so this is an addition to the existing record, not a duplicate.

    This card was reproduced exactly. The measurement below may not already be here:

    The mechanism

    scripts/docs-audit/affected-docs.mjs → walkSourceFiles skips only node_modules, dist and .turbo.

    ⇒ The 233 gitignored .ts files under packages/spec/.examples-build/ and .examples-build-src/ enter the walk, and they break the live pin "every contract declaration admitted is a packages/spec API declaration".

    .gitignore is not a filter the walk consults, so files that are invisible to git are fully visible to this gate.

    Proof that it is tree-local, not commit-local

    This is the part that distinguishes the defect from a bad commit:

    • the same commit passes 568/568 in a fresh worktree;
    • the polluted tree passes again once the two byproduct directories are removed.

    ⇒ Nothing about the commit is wrong. The failing input is state left on disk.

    It is self-inflicted inside a single gate sweep

    check:skill-examples runs before check:docs-audit-scope and poisons it. So a full-union gate run reds a gate that would be green if run alone or in the other order — which is exactly why it reads as a mysterious intermittent failure to whoever hits it.

    ⭐ Practical consequence for anyone running the gate union locally: an exit 1 from check:docs-audit-scope after check:skill-examples in the same working tree is not evidence about your diff. Verify in a clean worktree before treating it as yours.

    ---

    Generated by Claude Code
11. claude commented on Sep 5, 2026

    

    claudeBot

    on Sep 5, 2026 – with Claude

    Contributor

    More actions

    os-dev-report

    {
      "issue": 15446,
      "folded": [
        15457
      ],
      "status": "done",
      "branch": "claude/issue-15446-examples-build-residue",
      "pr": "https://github.com/objectstack-ai/objectstack/pull/15649",
      "premise_still_valid": true,
      "summary": "Both halves landed in one PR, as triage ruled. WALKER: walkSourceFiles in scripts/docs-audit/affected-docs.mjs pruned node_modules / dist / .turbo by NAME; it now prunes node_modules, dist and any DOT-DIRECTORY, applied to directories only. The class rather than a roster because .gitignore:66-70 lists THREE emitted trees, not the two the card names (packages/spec/.examples-build/, packages/spec/.examples-build-src/, packages/client-react/.examples-build/), and it is safe because it is measured: `git ls-files 'packages/**' | grep -cE '(^|/)\\.[^/]+/'` is 0 -- no tracked file under packages/** lives in a dot-directory at all. That premise is re-measured on every run by a new LIVE pin in --self-test, so it reds rather than ages in a comment. EMITTER: the compile loop in packages/spec/scripts/check-skill-examples.ts now runs inside withBuildDirCleanup, which tracks each build dir BEFORE writeBuildDir creates it. A try/finally alone cannot carry this, and that is why it is a helper rather than four inline lines: process.exit() does not run finally blocks, and fail() / refuse() / the per-surface staleness guard all leave that way -- which is exactly the path that left 226+10 files. The guarantee is therefore held in two places: the finally for the returning and throwing paths, and a process.on('exit') listener plus explicit SIGINT/SIGTERM handlers for the paths that exit outright. --keep still keeps. cleanStaleBuildDirs() additionally sweeps a previous run's trees before the loop and announces it on stderr -- the half that repairs an ALREADY dirty tree, since writeBuildDir only wipes the dir of a surface a run REACHES, so a run refusing at surface 1 leaves surface 2's stale tree standing indefinitely. No changeset: packages/spec's `files` array does not include scripts/, and the repo-root scripts/ publishes nothing; skip-changeset applied via the additive REST endpoint and read back.",
      "tests": "REPRODUCTION FIRST, on a clean worktree off origin/main 6b8c67778 with only the spec closure built: `pnpm --filter @objectstack/spec run check:skill-examples` EXIT=1 on the client-react prerequisite refusal (packages/client-react/dist holds no .d.ts declarations), leaving 226 files in packages/spec/.examples-build and 10 in .examples-build-src -- i.e. #15457's ABORT path, not a completed run. Then `pnpm check:docs-audit-scope` EXIT=1 with exactly the card's text: self-test \"every contract declaration admitted is a packages/spec API declaration\": kind=contract -> expected scanRouteSurface=true, got false / affected-docs self-test failed (1 case(s)). Control both directions: rm -rf the two trees and the same command is EXIT=0, `568 cases pass`. HALF-PROOFS. Walker alone (only affected-docs.mjs changed, the 226+10 residue re-planted on disk): `pnpm check:docs-audit-scope` EXIT=0, `582 cases pass` WITH the residue present. Emitter alone: the same prerequisite refusal is still EXIT=1 but `ls -d packages/spec/.examples-build* packages/client-react/.examples-build` finds nothing, and the reproduction's own control already measured the scope gate green whenever the trees are absent. Stale sweep: re-plant 226+10, re-run, stderr prints `removed 2 stale build dir(s) left behind by an earlier interrupted run` naming both, and both are gone. TOGETHER, the card's two commands in the card's order on the merged head ec0f7dc93: check:skill-examples EXIT=0 `257 prose examples type-check across 3 surface(s)` with no .examples-build* left, then check:docs-audit-scope EXIT=0 `582 cases pass`. ABLATIONS -- three, each trap-guarded with absolute paths, mutated by anchored replacement with grep -c counts in BOTH directions, restored with `git checkout HEAD -- ABSOLUTE_PATH` and proven by `git hash-object` equal to the HEAD blob plus an empty `git diff HEAD`. NO BUILD IS INVOLVED and that is stated rather than assumed: both edited files are executed from source by node / tsx, so there is no dist for a stale artifact to hide in. (a) walker, e.name.startsWith('.') -> e.name === '.turbo': on-disk proof startsWith count 1->0 and injected .turbo count = 1; result 7 cases RED, naming all three trees and both equality assertions, while the .turbo fixture row and both positive controls stayed GREEN; restored blob baa50df4f71936228018f11be172cf1329ad9826 == HEAD, git diff HEAD empty, re-run `582 cases pass`. (b) emitter, delete removeBuildDirs(tracked, keep) from the finally: count 1->0, marker = 1; 2 cases RED -- 'a thrown compile error left .examples-build behind' and the same for .examples-build-src. (c) emitter, delete the installBuildDirExitCleanup() call: count 1->0, marker = 1; 1 case RED -- \"no 'exit' listener is installed\". Restored blob ce7df47c3632f3c7f08ffdf9d6f8485f24bab114 == HEAD, git diff HEAD empty, self-test EXIT=0. SELF-TEST GROWTH: affected-docs 568 -> 582 cases (walk battery floor raised 67 -> 80, route-source battery 23 -> 24, so the new cases cannot be silently deleted); check-skill-examples gained 5 residue cases and its verdict line was extended to state them. DERIVED FAMILY, re-derived on the merged head with `node scripts/pm/dispatch-gates.mjs --changed --commands --repo objectstack-ai/objectstack` (exit 0, no stale-tree warning this time, change set exactly the two files, identical to the pre-merge derivation): 63 runnable commands, 62 exit 0. NOT MEASURED, named rather than counted green: `pnpm check:dual-build-cjs-loads` exit 3, 'PREREQUISITE NOT MET -- this gate reads built output, and some package has no dist/' (32 packages unbuilt in this worktree; its own --self-test passed, 93 cases); the 6 families whose argv takes a RUNNER_TEMP value from the workflow; the 35 artifact-roster families dispatch-gates scores silent for every card in the tree, 10 of them with a roster under a directory one of my paths is in, so their silence is evidence in neither direction. Named verdicts: check:pm-dispatch-gates `1445 cases pass`; check:nul-bytes `OK (scanned 7571 text file(s) ... no raw ASCII control bytes)` plus a direct grep -naP over both edited files with the exit code captured before any pipe (exit 1 = zero hits); check:published-files exit 0. `pnpm --filter @objectstack/spec typecheck` exit 0 -- and `tsc --noEmit -p tsconfig.scripts.json --listFiles` confirms packages/spec/scripts/check-skill-examples.ts IS in that program (1 hit), so this is not the phantom kind of green. WHOLE-REPO `pnpm lint` (eslint . --no-inline-config) exit 0 -- run in full, no narrowing claimed. Every exit code above was captured BEFORE any pipe, into a variable or a results file; every verdict is quoted from the gate's own printed line. The whole union was run at ec0f7dc93, which is the branch head the PR body cites.",
      "mcp_calls": "0 -- every GitHub read and write went through REST with GH_TOKEN (card body, card comments, #15457 state, PR create, label add, label read-back, PR body read-back)",
      "open_questions": [],
      "out_of_scope_findings": []
    }

    ---

    Generated by Claude Code
12. baozhoutao

    closed this as completedin #15649on Sep 5, 2026
13. claude commented on Sep 5, 2026

    

    claudeBot

    on Sep 5, 2026 – with Claude

    Contributor

    More actions

    LANDED — PM seat domain:devx @ objectstack (#6023), session session_012zGPuVVX3deAx9LdjK8jCk.

    PR #15649 merged 2026-09-05T03:08:27Z as a3eba0759 on main (squash, via the merge queue; Fixes #15446 + Fixes #15457). Probed on re-fetched origin/main:

    scripts/docs-audit/affected-docs.mjs:2091      if (e.name === 'node_modules' || e.name === 'dist' || e.name.startsWith('.')) continue;
    packages/spec/scripts/check-skill-examples.ts:1360   function installBuildDirExitCleanup(): void {
    packages/spec/scripts/check-skill-examples.ts:1380   function withBuildDirCleanup<T>(…, keep: boolean = KEEP): T {
    packages/spec/scripts/check-skill-examples.ts:1406   function cleanStaleBuildDirs(): void {
    packages/spec/scripts/check-skill-examples.ts:2900   cleanStaleBuildDirs();
    node scripts/docs-audit/affected-docs.mjs --self-test   EXIT=0   ✓ affected-docs self-test: 582 cases pass.   (detached worktree at a3eba0759)
    

    The check-skill-examples self-test imports typescript — NOT MEASURED on this seat; CI's merge group was the arbiter.

    Closures in the landing window: #15446 (this card, 03:08:28Z) only; #15457 was already closed as a duplicate folded into this card. No mis-closure. Stripping pm:dispatched + assignee.

    ---

    Generated by Claude Code
14. claude

    removed

    pm:dispatched

    on Sep 5, 2026
15. claude

    unassigned

    baozhoutao

    on Sep 5, 2026
16. akarma-synetal

    added a commit that references this issue on Sep 9, 2026

    fix(devx): the docs-audit walker prunes the skill-examples build resi…

    ...

    a3eba07