finding(devx): `check-doc-snippet-types.mjs --build-filter` prints a build command that silently leaves part of the tree unbuilt

[claude]

check-doc-snippet-types.mjs --build-filter 打印的构建命令按设计只建一个闭包（今天实测：40 个包里建成 34 个，留下 @object-ui/plugin-ai 与 @object-ui/plugin-tree），但它没有说这一点。照着它敲的人会得到一棵半建成的树，并以为自己已经"建好了"。

出处

由 objectui#7460 的实现析出。那张卡记录的是后果——check-readme-exports.test.ts 在这一档树上变红——而 PR #7794 把测试改成了按包判断，所以那个后果没有了。本卡记录的是成因侧的人机工程缺口，它在 #7460 关闭后不会自己消失。

⚠️ 立卡而非在 #7460 上留言的理由：#7460 由 Fixes 关闭后就退出所有 pm:queue 扫描，写在那里的记录会随之不可见 —— 这正是本仓反复付账的"发现随卡关闭而丢失"形状。

测量（objectui#7460 实现期，origin/main abdcd189c）

pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) --concurrency=2

跑完之后 census.packagesUnbuilt = 2 of 40，未建成的是 packages/plugin-ai 与 packages/plugin-tree。该 filter 覆盖的是被判文档 import 的那些包（当时 26 个），这是有意为之，不是缺陷。

修法建议（方向，不是命令）

在打印那条命令的地方多打一行，说明这个闭包是按被判文档的 import 面裁剪的、不等于整棵树，并点名它不会建的包（或至少说明"其余包保持未建成"）。

⚠️ 这是人机工程改进，不是缺陷修复：

• ⛔ 不要改 --build-filter 去建整棵树 —— 裁剪是那道门的设计意图，扩大它会把每个人的本地循环拖慢。
• ⛔ 不要在别处再写一份"哪些包会被建"的清单 —— 那会立刻腐烂。提示应当从同一份 filter 派生。

现状

⚠️ 严重性已经因 PR #7794 而下降：check-readme-exports.test.ts 现在按包判断，在这一档树上不再变红，并且它的失败信息会主动点名 census.packagesUnbuilt。⇒ 半建成态今天已经不再产生假红，本卡剩下的只是"命令没告诉你它做了什么"。

Refs: objectui#7460 · PR #7794 · scripts/check-doc-snippet-types.mjs

---

Generated by Claude Code

[claude]

Claim: PM loop, round 6 — all-opus lane (Clause-② no)
Session: session_01KbJQ1y1J12nZxYzFWhP8Q3
Branch: claude/issue-7795-build-filter-closure-hint
Worktree: objectui-issue-7795
Domain: domain:devx
File surface: scripts/check-doc-snippet-types.mjs（仅打印 --build-filter 那条命令的地方）· 其 scripts/__tests__/ pin（若该提示需要钉住）· 若判词要求，本卡自己的 .changeset/*.md. ⛔ Stop on breach: 任何对 --build-filter 本身选包逻辑的改动、任何 packages/*/src 的改动、任何 .github/workflows/ 的写入。Explain in the report.
Container & model: S, mode:subagent, model: opus
Clause-②: no — 一条打印出来的提示文本。不改变契约接受/拒绝行为，不扩大公开面，也不改变那道门判什么或建什么。⚠️ Void condition: 任何让 --build-filter 选出的包集合发生变化的改动 —— 停下上报。
Serial constraints cleared: 无在飞 PR 触碰 scripts/check-doc-snippet-types.mjs。⚠️ 在飞的 #7802（packages/plugin-view/src/__tests__/）与 #7798（两个 packages/*/src 文档块）都不相交。⚠️ PR #7805（卡 #7753）在队列中，它往 scripts/ 加了新门与 ci.yml 一条步骤 —— 与本卡不同文件，但若你也要碰 ci.yml（本卡不应该碰），先 git fetch origin main。

---

缺陷 —— 一条命令没说自己做了什么

check-doc-snippet-types.mjs 在未建成树上打印：

pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) --concurrency=2

那个 filter 按设计只建一个闭包（被判文档 import 的那些包）。实测（objectui#7460 实现期，origin/main abdcd189c）：跑完之后 40 个包里建成 34 个，census.packagesUnbuilt = 2，未建成的是 packages/plugin-ai 与 packages/plugin-tree。

⇒ 照着这条命令敲的人得到一棵半建成的树，并以为自己已经建好了 —— 因为命令没说。

⚠️ 严重性已经下降，本卡只剩人机工程那一半

⭐ PR #7794（卡 #7460）已落地：check-readme-exports.test.ts 现在按包判断，在这一档树上不再变红，而且它的失败信息会主动点名 census.packagesUnbuilt。⇒ 半建成态今天已经不产生假红。

⇒ 本卡剩下的只是「命令没告诉你它做了什么」。⛔ 不要把它当成一个还在造成红的缺陷去修。

修法方向（方向，不是命令）

在打印那条命令的地方多打一行，说明这个闭包是按被判文档的 import 面裁剪的、不等于整棵树，并（若可行）点名它不会建的包。

⛔ 三条禁止：

1. ⛔ 不要改 --build-filter 去建整棵树。 裁剪是那道门的设计意图；扩大它会拖慢每个人的本地循环。这是作废条件。
2. ⛔ 不要在别处再写一份「哪些包会被建」的清单 —— 那会立刻腐烂。⭐ 提示里的包名（如果你要打）必须从同一份 filter 派生，与那条命令用的是同一个数据源。
3. ⛔ 不要顺手去改 check-readme-exports.test.ts 或任何测试 —— 那是 finding(scripts): check-readme-exports.test.ts reds on a HALF-built tree — and another gate’s own printed build command is what produces one #7460 的面，已落地。

⭐ 顺带一条本轮刚立下的原则，直接适用：委托，不要摘要。 若你打算在提示里复述"哪些包不建"，那份复述必须是算出来的，不能是写死的；否则它就是又一份会腐烂的摘要（见 objectui#7765 的落地记录）。

验收

• 点亮控制：在未建成的树上跑 node scripts/check-doc-snippet-types.mjs（触发它打印那条命令的那条路径），确认输出里确实出现了你新加的那一行，并把原文贴进报告。⛔ 不要用「我改了字符串所以它会打印」当结论 —— 那正是本轮反复拒绝的形状。
• ⚠️ 若你做不到在本地造出触发该打印的状态，明说做不到，改为给出「该字符串确实在那条输出路径上」的静态证据（指出它拼进的正是被打印的那段，并给行号）。
• --build-filter 的输出必须逐字节不变：把改动前后的 node scripts/check-doc-snippet-types.mjs --build-filter 输出各存一份，diff 为空。⭐ 这是「没有改选包逻辑」的可核证明。
• 该门的常规读数（pnpm check:doc-types 或它在 package.json 里的脚本名）与 pnpm type-check:scripts，报出 exit code。
• 若你为提示加了 pin，报出 pin 的文件数/用例数。

变更集

只动 scripts/ ⇒ 大概率不欠。⛔ 不要凭规则推断：跑 node scripts/check-changeset-presence.mjs，判词原样抄进报告，按判词行事。⛔ 永不写 major。

⚠️ 五个仪器陷阱（今天各席实测）

1. 裸 tsc --noEmit 不是本仓的门 —— turbo type-check dependsOn ^build 且结构上到不了非包目录；scripts/ 用 pnpm type-check:scripts。⚠️ 构建前跑出的 TS2882 是未满足的前提，不是结果。
2. ⛔ 本容器没有「未认证的探测」 —— 代理注入凭据，匿名样子的 POST 是真写入。探通道只用 GET。
3. ⚠️ scripts/__tests__/check-doc-links.test.ts 共享盒上 15s 超时是已知 flake。
4. ⛔ new URL(rel, import.meta.url) 被 Vite 重写成 http://localhost:3000/@fs/…。路径派生用从 import.meta.url 逐段上溯（PR fix(fields): root the capability spec-parity pin at the file, not the cwd (objectui#7791) #7796 / fix(test-infra): 13 package tests root their repo reads at the test file, not at the cwd #7806 同一拼法）。
5. ⭐ ⛔ 不要用两点式 origin/main..HEAD 报「本 PR 改了几个文件」 —— 并发落地会虚报（实测 4 vs 真实 2）。以记录的 base 或 GitHub 的 changed_files 为准。

契约复审

Clause-② 是 no ⇒ 不排在契约复审后面。

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 7795,
  "status": "done",
  "branch": "claude/issue-7795-build-filter-closure-hint",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7812",
  "premise_still_valid": true,
  "summary": "The precondition path of scripts/check-doc-snippet-types.mjs now prints one paragraph under the build command it already printed: that build is SCOPED (the packages the covered documents import plus each one's dependency closure), what it leaves unbuilt afterwards is the designed end state rather than a build that half-failed, and the exact selection is obtained by appending --dry=text to that same command. Both counts in the sentence are derived from what the gate already read (26 packages named by --build-filter, 40 under packages/) — analyze() now also returns the packageDirOf inventory it had read — and the text names no package on purpose, so there is no second list to rot; five pins hold that, one of them failing if a package name ever appears. The package selection is untouched: --build-filter's output is byte-identical before and after (empty diff, identical md5, same 891 bytes / 26 filter words), so the Clause-2 void condition was never approached. No test other than the gate's own suite was touched, and check-readme-exports.test.ts was only run, never edited.",
  "tests": "Union re-run at final HEAD 6d6f71ad9 (clean tree), heavy legs through the shared verify lock (VERDICT lines read, never a bare $?). LIT CONTROL (the card's first acceptance item, reached for real): the fresh worktree was unbuilt, so `node scripts/check-doc-snippet-types.mjs` opened the precondition path on its own — exit 2, and stderr ends with the new paragraph verbatim: 'That build is SCOPED, and it is not a whole-tree build: --build-filter names the 26 package(s) the covered documents import (packages/ holds 40) plus each one's dependency closure, and every package outside that closure is left exactly as it was. An unbuilt package still sitting there when the build finishes is this gate's designed end state, not a build that half-failed - building the whole tree for a documentation check would slow every local loop. For the exact set, ask that same filter rather than a list written down somewhere else: append --dry=text to the command above and read its \"Packages in scope\" line.' Full six-line before/after excerpt is in the PR body. BYTE PROOF: filter.before.txt vs filter.after.txt, `diff` exit 0, md5 845e14005cecf500866cfa1b2307ec26 both sides. CROSS-CHECK of the two printed counts against turbo on the same tree: --dry=text reports 'Running build in 35 packages' from those 26 names, and the 5 packages under packages/ it never names are create-plugin, plugin-ai, plugin-tree, runner, object-ui (this is why the notice delegates instead of restating: the complement is turbo's answer, not the gate's). GATES: pnpm check:doc-snippets after building the filter's closure (turbo: 34 successful, 34 total, 16 cached, 2m24s on a shared box) exit 0 — '456 of 456 block(s) judged, 0 failed'; pnpm type-check:scripts exit 0, and `tsc -p tsconfig.scripts.json --listFiles` confirms both edited files are in the program (1 hit each), so that 0 is a reading about them and not a vacuous pass; pnpm lint:root exit 0 (33 pre-existing warnings, 0 errors, none of them in the two edited files — narrowed eslint --format json over just those files reports 2 files, 0 errors, 0 warnings); pnpm check:control-bytes exit 0 (6357 tracked text files) plus a self-scan `grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]'` over both files with no hits; node scripts/check-governed-queue-guard.mjs --test on both paths: 'NOT GOVERNED'. TESTS: pnpm exec vitest run scripts/__tests__/check-doc-snippet-types.test.ts — 1 file, 75 tests passed (5 of them new); the 5 suites that name this gate by filename (check-doc-snippet-types, check-doc-component-types, check-doc-fence-languages, check-readme-exports, check-skill-examples) — 5 files, 324 tests passed. MUTATION CONTROL, two legs, each committed-first, each confirmed on disk before running and restored after: (a) the scopedBuildNotice(...) call deleted from the precondition path — grep count 2 to 1 — vitest exit 1, 1 failed / 74 passed, the failing case being 'is printed on the precondition path, not merely defined'; (b) the count hard-coded — `${named} package(s)` occurrences 1 to 0, 'the 26 package(s)' 0 to 1 — vitest exit 1, 1 failed / 74 passed, failing case 'interpolates the counts it is handed'; restored control 75 passed. Restoration was proved, not assumed: `git checkout HEAD -- ABSOLUTE_PATH` from an EXIT/INT/TERM trap, then `git diff HEAD` empty and `git hash-object` equal to the HEAD blob f2d8c70f73579410430f68daca5fca93868ef222 after each leg; final `git status --porcelain` empty. No dist/rebuild dimension applies to this ablation and none is claimed: the suite imports ../check-doc-snippet-types.mjs directly, so no package's dist stands between the mutation and the assertion. CHANGESET, verdict line verbatim: 'Compared the working tree with a617bb8d3 (merge-base with origin/main): 2 file(s) changed, 0 of them published source of a package the release covers, 0 of them a manifest whose published contract moved, 0 under a package changesets ignores, 0 changeset(s) added.' / '(green check) No source or published contract of a released package changed in this range, so no changeset is owed.' — acted on: no changeset added, and per this repo's rule the skip-changeset label was NOT applied here (in objectui nothing reads it). File count for the PR is 2, from that merge-base line and from GitHub's own changed_files on PR 7812 — no two-dot diff was used. NOT RUN, stated rather than implied: the full `pnpm test` and the Doc Snippet Type Check workflow are left to CI; no CI conclusion was waited for.",
  "mcp_calls": "1 — a single mcp__github__search_issues for the dedupe of the out-of-scope finding, which returned no data at all ('API rate limit already exceeded for user ID 318158314'). Channel switch declared: every other GitHub read and write in this run went through repo-scoped REST (issue body and comments, label-scoped issue listings, the issue creation, the PR creation and its read-back), which this container answers 200; REST /search/issues is 403 here by the proxy's path whitelist, so the dedupe was done with two label-scoped REST listings paged to exhaustion (domain:devx 79 issues, finding 163 across 2 pages, page 3 empty) plus a known-hit control (issue 7795 itself appeared in the domain:devx listing), and no candidate matched.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #7811: scripts/check-skill-examples.mjs prints the same unscoped 'turbo run build $(... --build-filter)' command at two precondition sites (lines 1285 and 1721) with no word that the closure is trimmed — same defect class as this card, but outside the declared file surface (the claim bounds me to scripts/check-doc-snippet-types.mjs), so it was filed with labels finding + domain:devx, no assignee, carrying this PR's shape as its repair direction rather than being fixed in passing"
  ]
}

---

Generated by Claude Code