doc-version-claims 的 SCAN_ROOTS 不含 skills/:agent 面的 4 处版本字面量从未被任何门禁读过(实测 1–2 个 major 化石)

[yinlianghui]

越界发现,记录于 #4961(plugin 骨架补 @vitejs/plugin-react)实施期间 —— 为了做「规则消费半径」扫描而 grep 全仓 @vitejs/plugin-react 拼写时扫到的。#4961 的完成范围是 content/docs/guide/plugins.md 那一行 + 一条 KNOWN_CLAIMS 条目,这一条在另一个扫描面上,故只记录。

事实(对 origin/main @ 7d1017790,即 #4963 落地后实测)

scripts/__tests__/doc-version-claims.test.ts:274 的扫描面是两条:

const SCAN_ROOTS = ['content/docs', 'packages/*/README.md'] as const;

skills/ 不在其中。而 skills/objectui/guides/ 下有两份带 package.json 代码块的脚手架指南,共 4 处版本字面量,没有任何门禁读过它们:

位置	该页教的	仓内实测	差距
skills/objectui/guides/project-setup.md:51	typescript ^5.0.0	^6.0.3	1 个 major
skills/objectui/guides/project-setup.md:52	vite ^6.0.0	^8.2.1	2 个 major
skills/objectui/guides/project-setup.md:53	@vitejs/plugin-react ^4.0.0	^6.0.5(19/19 plugin 包)	2 个 major
skills/objectui/guides/plugin-development.md:329	lucide-react ^0.400.0	^1.31.0(9 个包一致)	跨 major(0.x → 1.x)

同页的 react/react-dom ^19.0.0 与 ^18.0.0 || ^19.0.0、tailwindcss/@tailwindcss/vite ^4.0.0 与仓内同 major,不在此列(判据同 #3827 / #3855:peer 说「能接受什么」;tailwind 同 major 不算化石)。

没有别的门禁兜住:scripts/check-skills-paths.mjs 确实扫 skills/,但它判的是路径/链接,不读版本;check-type-check-coverage.mjs 提到 skills 也与版本无关。grep 全部 scripts/ 后,读版本字面量的只有 doc-version-claims 一个,而它的 SCAN_ROOTS 排除了这里。

为什么这不只是「又一处化石」

skills/ 是给 agent 读的面。content/docs 化石的受害者是照抄的人类读者(#3855 / #3645 那一族);skills/objectui/guides/project-setup.md 化石的受害者是照它生成项目的 AI,产物再被提交进用户仓库。同一个数字错一次,前者是一个人构建失败,后者是每次脚手架都复制一遍。

这也正是 #3855 那半个交付物(把值接到锚上,而不是只改值)想解决的失效模式,只是它当时的扫描面到不了这里。

修法(两个方向,交 PM 定;不在本卡内做判断)

1. 扩 SCAN_ROOTS 到 skills/,再按 content/docs/guide/plugins.md 的示例 package.json 里 vite ^5.0.0 / typescript ^5.0.0 落后仓内三个与一个 major(#3709 同族化石,文档面最后两处) #3855/content/docs/guide/plugins.md 的插件骨架:step 5 的 vite.config.ts import 了 @vitejs/plugin-react,step 6 的 devDependencies 从未声明它(照抄即构建失败) #4961 的 skeletonDep 机制给能锚的行入锚(typescript/vite/@vitejs/plugin-react 三条锚现成且一致;lucide-react 在 9 个包上一致)。注意 project-setup.md 教的是独立项目而非 in-workspace 插件,所以 skeletonDep 现有的「锚 = 19 个 plugin 清单」判据未必直接适用 —— 这一点需要先想清楚再动,否则会把一个正当的 sample 误判成 anchored。
2. 去掉这些字面量,改为指向真源(根 engines、包自己的清单),即 PR docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688 / docs(cli): 兼容表两行失真 —— Node 行改指根 engines,删掉 CLI 并不依赖的 spec 兼容行 #3698 对 36 个 README 和 CLI 页做过的那一手。

同形先例

• check-doc-links 扫描面漏掉包内非 README markdown:15 个文件的链接从未被任何门禁解析过(实测 1 条死链) #4938(open,finding)—— 完全同一形状的另一个门禁:check-doc-links 的扫描面漏掉包内非 README markdown,15 个文件的链接从未被解析,实测 1 条死链。那条是链接门的扫描面洞,这条是版本门的扫描面洞。不是重复,也不是 Blocked-by —— 两个不同的 gate、不同的文件集合,但值得一起看:两次都说明「门禁的 SCAN_ROOTS 是手写清单」这件事本身有系统性风险。
• content/docs/guide/plugins.md 的示例 package.json 里 vite ^5.0.0 / typescript ^5.0.0 落后仓内三个与一个 major(#3709 同族化石,文档面最后两处) #3855 / content/docs 三处版本宣称失真:architecture-overview 的 @objectstack/spec ^4.0.x(差 13 个大版本)与 architecture.md 的 TypeScript 5.0+ #3708 / 站点文档 content/docs/utilities/cli.mdx 的兼容表有两行失真:@objectstack/spec ^3.3.0(实为 ^17.0.0-rc.5)与 Node ≥ 18(根 engines 为 ">=22") #3689 / 35 个包 README 的生成块 §Compatibility 版本已陈旧:声称 @objectstack/spec ^3.3.0,实际全仓锁 ^17.0.0-rc.5;部分包还列了自己并不依赖的 @objectstack/client #3645 —— content/docs 与 README 面的同族化石,均已修;它们是这条门禁存在的原因。

[os-zhuang]

Triage: pm:queue, type Task. Route both halves, split into two PRs by merge policy:

1. Content fix — the 4 fossil literals in skills/objectui/guides/*. Diff lands in skills/** ⇒ human-merge lane (review verdict on the issue, PR left visibly awaiting the maintainer — same handling as skill 入口 SKILL.md 与 evals/project-setup.json 仍在教/评分「加 @source 扫 ObjectUI 包」—— #4858 修正后的残留 #4865).
2. Gate fix — scripts/__tests__/doc-version-claims.test.ts: extend SCAN_ROOTS to skills/, anchor the three lines with existing consistent anchors (typescript / vite / @vitejs/plugin-react), and carry lucide-react via a KNOWN_CLAIMS entry if the skeletonDep anchor set doesn't safely apply — the card's own caveat (standalone-project guide vs in-workspace plugin anchors) is real; prefer a plain claim entry over a wrong anchor. Direction 2 (delete literals, point at the true source, the docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688/docs(cli): 兼容表两行失真 —— Node 行改指根 engines,删掉 CLI 并不依赖的 spec 兼容行 #3698 move) stays available if anchoring proves unsound — report the fork, don't force it.

Sibling #4938 (check-doc-links scan-surface hole) noted: same class, different gate — not folded, not blocking.

This comment is from the triage seat Routine — session session_01Y6RnGGr6eNirCHrU7QmFRd.

---

Generated by Claude Code