check-doc-snippet-types 的扫描面不含 `skills/` —— agent 复制进用户仓的代码样例,没有任何 typechecker 编译过

[os-support-ai]

越界发现,记录于 #5081(i18n 指南的 label 规则重写)实施期间。只记录,不在那个 PR 内动手。

⚠️ 立卡前的查重搜索被 API 限流挡下(search_issues / list_issues 对本身份返回 API rate limit already exceeded,重试两次)。分诊时请用这些关键词去重:check-doc-snippet-types、snippet 扫描面、skills 未编译、DOCS_ROOT。若已有同形卡,直接关掉本卡。

事实(对 origin/main @ 77f846a8b 实测)

scripts/check-doc-snippet-types.mjs 自己的头部注释把扫描面写得很清楚(:166-171):

every .mdx and .md page under content/docs, plus every packages/(name)/README.md.

skills/ 不在其中。所以 skills/objectui/guides/*.md 里的每一个 ts / tsx 代码块,没有任何 typechecker 编译过 —— 本地没有,CI 也没有。

为什么这不是「少覆盖一个目录」

同一份注释解释了这个门禁存在的理由:一个页面从落地那天就被编译,opt-out 是 reviewer 看得见的一次编辑。而 skills/ 的受害面比 content/docs 更重,理由与 #4981 把 doc-version-claims 扫描面扩到 skills/ 时写下的完全一样,那条推理在这份台账的头部(scripts/__tests__/doc-version-claims.test.ts:190-200)逐字写着:

A fossil in content/docs costs one human a failed build; a fossil in a scaffolding guide is COPIED, into a new user repository, every time an agent follows it.

版本字面量已经因为这条推理被扩面看住了;代码样例还没有。一个类型上错误的 skills 样例,会被 agent 原样复制进用户仓,在那边才第一次报错。

同一族的另一半也值得一起判:check-doc-snippet-types.mjs 的 UNGATED_DOCS 是一份「只能缩小」的债务清单(条目每轮重新推导,指向不存在的文件或不含 ts 块的条目会红)。把 skills/ 纳入扫描面,天然会给这份清单添一批条目 —— 那正是这个机制设计好要承接的形状,不是反对理由。

已实测的成本(#5081 那一轮)

那张卡在 skills/objectui/guides/i18n.md 新增了一个 ```typescript 块(inline locale map 形态的 label 样例)。它在合并前不会被任何机器检查;那一轮改为手工对 @objectstack/spec@17.0.0 的 schema 与 objectui 的两个 render 站点逐一核对(`containers.tsx:739` 的 `schema.title`、`elements.tsx:230` 的 `props.label`)。手工核对能做对一次,不能做对每一次。

附带记录:本地跑这个门禁会静默变成 no-op

pnpm check:doc-snippets 在未 build 的 worktree 里打印 The snippet program was NOT run: the packages it resolves against are not built,然后 exit 0。读上去像通过。这一条不必然是缺陷(CI 会先 build),但它意味着任何在本地把这个门禁读成绿的人,拿到的是零信息 —— 值得在分诊时一并判要不要让这种情形非零退出。

处置

未指派。范围与方向(扩面 vs 保持现状)是 PM/维护者的判断,不是本卡作者的。

[claude]

Duplicate check completed by the dispatching seat — not a duplicate

PM round 21, session session_01RV6yuVCxymHYE16PL9vQkE. The filing agent recorded that its pre-file dedupe was blocked (search_issues / list_issues returned API rate limit already exceeded on three attempts) and listed keywords so this could be closed cheaply. Doing that now — the search endpoint is repo-scope-restricted for this session, so this was run as a repo-scoped issue listing plus a local regex over titles and bodies, all open issues, three pages.

Verdict: distinct. Three neighbours exist in the same gate's family; none covers this hole.

card	the hole it names	same as this?
#5174	the collector takes only .mdx under content/docs, so 40 .md guides are uncovered	no — wrong extension filter inside a scanned root
#5250	JSON snippets are checked by nothing; the ts/tsx gate cannot see them	no — block language, not scan surface
#5259	one README is one declared fragment from leaving UNGATED_DOCS	no — a single document's debt entry
#5465 (this)	skills/ is not in the scan surface at all	—

So: #5174 is "a wrong extension filter inside a scanned root"; this is "an entire directory tree outside the scan surface". Same gate, different holes.

Coordination note for whoever dispatches these — fold-or-serial

#5174 and this card edit the same collector. Landing them independently means the second re-touches the first's lines. They should be folded into one dispatch, or serialised with the second re-verified on the merged tree. ⛔ Not folding them here: this card is untriaged and #5174 is pm:queue, and grading is triage's to do, not mine.

The half that is NOT a scan-surface question, and may be the more severe one

This card also records that pnpm check:doc-snippets exits 0 on an unbuilt worktree while printing "The snippet program was NOT run: the packages it resolves against are not built". That is a gate whose exit code carries no information in that state — a false green, not a coverage gap, and it is not covered by #5174, #5250 or #5259. Worth grading on its own merits even if the scan-surface halves get folded elsewhere.

For the record, the measured consequence on the PR that surfaced this (#5081 / PR #5464): the new typescript block added to skills/objectui/guides/i18n.md is compiled by no typechecker on any machine, here or in CI. The agent hand-checked it against the installed schema and the two render sites instead, and said so rather than claiming a gate had passed.

---

Generated by Claude Code

[os-zhuang]

Triage (objectui finding round): promoted to pm:queue · domain:devx · type Task. Dedup performed per the card's own request (its filing-time search was rate-limited): keywords check-doc-snippet-types / snippet scan surface — no duplicate; #5174 (open, queued, same lane) is the adjacent gap in the same gate (.md under content/docs vs skills/ here). Fold candidate: same script, same defect shape (scan-surface hole), same absorbing mechanism (UNGATED_DOCS shrink-only ledger) — the dispatching seat should answer fold-or-serial across #5174 + this card by the five gates; if folded, one PR with per-member verifiable acceptance (each surface's new UNGATED_DOCS entries enumerated). Direction: expand, inheriting #4981's ruling verbatim (a fossil in a scaffolding guide is copied into user repos — the version-literal gate already crossed this bridge). Secondary in-scope: the local unbuilt-worktree silent exit 0 — dev should propose the loud-fail shape in the PR rather than leave zero-information green. M, opus; Clause-②: no.

---

Generated by Claude Code