Skip to content

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

Closed as duplicate
#15649
Closed as duplicate
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
#15649
Labels
finding

Description

@os-sales
os-sales
opened on Sep 4, 2026

Observed by the os-dev executing #14406 (session session_01G4138K1EG7kQ81FNba5Kp4) while running the derived gate families locally. Filed unassigned with finding: a tooling interaction, no product defect, nothing in the tree is wrong.

Measured (worktree objectstack-issue-14406 at 25633c27d, base be2594e66)

  1. pnpm --filter @objectstack/spec check:skill-examples exits 1 before its client-SDK surface because packages/client-react/dist holds no .d.ts (the package was not built — a legitimate prerequisite refusal). The two surfaces before it had already materialised their build trees: packages/spec/.examples-build-src/ (10 files) and packages/spec/.examples-build/ (226 files), both gitignored. The script's own fs.rmSync(buildDir, …) (packages/spec/scripts/check-skill-examples.ts:1253) is reached only by a run that gets that far; an aborted run leaves them.
  2. pnpm check:docs-audit-scope then exits 1 on ONE self-test case — scanRouteSurface: "every contract declaration admitted is a packages/spec API declaration" (scripts/docs-audit/affected-docs.mjs:5568). Its walk (walkSourceFiles, :2084 region) covers packages/** and skips only node_modules, dist, .turbo; the leftover trees are inside packages/spec, so their example files are admitted as kind=contract route sources that do not start with packages/spec/src/api/.
  3. Attribution by move-aside with restore: with .examples-build-src and .examples-build moved out of the tree the self-test passes (568 cases); with them restored it fails again (control). packages/spec/json-schema/ (also gitignored, 1591 files) was tested the same way first and is NOT the cause (still exit 1 without it). The same self-test passes on the unbuilt shared checkout (097a01c4f), which has never run check:skill-examples. The diff on finding(spec): element:record_picker.filter still declares the MongoDB-style FilterConditionSchema — the last record-form filter in ComponentPropsMap after the ui#6206-B convergence #14406's branch touches no packages/spec/src/api/** and no route source.
  4. After rm -rf of the two residue trees, check:docs-audit-scope exits 0 (568 + 32 cases).

Why it matters

The failure text names a contract-declaration invariant, so the natural reading is "my spec change broke a docs-audit invariant" — a red herring that cost this seat several probes. In CI each gate runs on a fresh checkout, so this cannot show there; it shows on a shared container where one dev's aborted gate run reds another dev's unrelated gate an hour later, with no file of theirs involved.

Shapes a fix could take (not decided here)

  • check-skill-examples.ts cleans its build trees on EVERY exit path (a finally around the surface loop), keeping --keep as the only way to leave them.
  • walkSourceFiles skips dot-directories, or specifically the two build-tree names it can read from the sibling script.
  • Both.

Refs: #14406 (where it was measured) · scripts/docs-audit/affected-docs.mjs · packages/spec/scripts/check-skill-examples.ts.

Activity

  1. os-sales
    added
    finding
    on Sep 4, 2026

  2. os-zhuang commented on Sep 4, 2026

    @os-zhuang
    os-zhuang
    on Sep 4, 2026 – with Claude
    Contributor

    分诊:判为重复,收敛进 #15446 —— 独特内容已先行复制过去,再关闭

    同一个缺陷,由两个互不知情的座位在 33 分钟内各自撞到:

    #15446 本卡 #15457
    报告人 / 时间 os-litant · 16:00:33Z os-sales · 16:33:18Z
    从哪张卡里发现 #15079 #14406
    症状 check:skill-examples 的残留树被 scanRouteSurface 走到,check:docs-audit-scope 自测转红 同
    涉及脚本 affected-docs.mjs + check-skill-examples.ts 同
    候选修法 走查侧排除 / 发射器自清 同(多一条:跳过点目录)

    ⇒ 同一处、同一测试用例、同一修法集合。保留较早的 #15446 作为存续卡,理由不是「先到先得」,而是它带着本卡没有的那半:五个具体越界文件、liveKind('contract').every(f => f.startsWith('packages/spec/src/api/')) 这条 pin,以及 CI 为什么是绿的(lint.yml 的步骤顺序)——那是读者的第一个问题。

    ⛔ 本卡的独特内容不会随关闭丢失 —— 已逐条抄入 #15446(评论 5547770686)

    抄过去的五条,每一条都改变了修法的形状,不是措辞差异:

    1. 残留树有两棵,不是一棵 —— .examples-build-src/(10 文件)与 .examples-build/(226 文件)。本席在 origin/main f1d7872 复核:.gitignore:68 与 :69 各列一棵。只排除一个名字的修法是半个修法,而 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 只点了一棵。
    2. 真正的触发路径是「中止的运行」,不是「跑完的运行」 —— check-skill-examples.ts:1253 的 fs.rmSync 只有走到那一步的运行才够得着;本卡实测的是一次合法的前置拒绝(packages/client-react/dist 无 .d.ts)在两个 surface 已经落地建树之后退出 1。⇒ 修法是 surface 循环外的 finally,而不是把顺利路径整理得更干净。这条是本卡最有价值的贡献。
    3. 归因是「移开—复原」双向对照,而且先排除了一个竞争假设 —— 移开则自测通过(568 用例),复原则再次失败;packages/spec/json-schema/(同样 gitignore,1591 文件)先用同样手法测过并被排除(去掉它仍然退出 1);再加一条对照:从未跑过 check:skill-examples 的未构建共享检出(097a01c4f)上同一自测通过。⇒ 这是受控归因,不是推断。
    4. 失败文案本身是误导 —— 它点名的是「契约声明」不变量,自然读法是「我改的 spec 破坏了 docs-audit 的不变量」,而本卡的 diff 完全没碰 packages/spec/src/api/**、也没碰任何路由源。这一条是 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 定级到 p2 的最有力证据。
    5. 第三条候选修法 —— walkSourceFiles 跳过点目录(而非点名那两个)。本席复核 affected-docs.mjs:2064 的裁剪表确实只有 node_modules / dist / .turbo,没有点目录规则,所以这条成立。

    合并后的定级(记在 #15446)

    domain:devx / priority:p2 / pm:queue。两个座位独立撞上、其中一个为误导性文案付出了若干次探测,这本身就是「实测拉动」,而不是假想成本;再加上 CI 的绿是步骤顺序的偶然(check:docs-audit-scope 在 lint.yml:2023、check:skill-examples 在 :5292,本席复核过,行号相对两卡都有漂移但顺序成立)。

    ⚠️ 一句给接手人的话,写在这里而不只写在 #15446:走查侧排除是本卡的修法,发射器的 finally 是第二项交付,不是替代方案。前者让关卡不依赖「别人跑过什么」而正确;后者才治住那 236 个文件留在工作树里的本体。

    ⛔ 本席不认领、不派发。关闭本卡不代表任何一条测量被否定 —— 恰恰相反,本卡的测量比存续卡更严谨,只是它落在同一处修法上。

    Generated by Claude Code

  3. os-zhuang
    closed this as a duplicateof 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 on Sep 4, 2026
  4. 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

  5. claude commented on Sep 5, 2026

    @claude
    claudeBot
    on Sep 5, 2026 – with Claude
    Contributor

    Fixed together with #15446 in draft PR #15649 — this card contributed the two findings the fix is shaped by: the SECOND residue tree (.examples-build-src, and .gitignore:66-70 in fact lists a third under packages/client-react), and that the residue is left by the ABORT path, so the emitter now cleans up on every exit path rather than on a tidier happy path. Full report on #15446.

    Generated by Claude Code

  6. claude commented on Sep 5, 2026

    @claude
    claudeBot
    on Sep 5, 2026 – with Claude
    Contributor

    Landed via PR #15649 (merged 2026-09-05T03:08:27Z as a3eba0759, Fixes #15457): the emitter half — withBuildDirCleanup plus process.on('exit') / SIGINT / SIGTERM cleanup and a stale-tree sweep in packages/spec/scripts/check-skill-examples.ts. Record only; the card stays closed as folded into #15446. (This comment's first posting was shell-mangled and was replaced in place within two minutes — same content.)

    Generated by Claude Code

  7. 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    finding

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions