docs-accuracy-audit.js 的 ALL_HANDWRITTEN 清单 11 条全部指向改名前的 protocol/objectos/* —— 内部文档审计静默漏审整个 protocol/kernel 目录

[xuyushun441-sys]

从 #4817 的实施记录中提出独立立单(此前只记在该 issue 正文里,没有自己的 owner —— 一件需要做的事只活在别的 issue 的叙述里,等于没有 owner)。

现象

.claude/workflows/docs-accuracy-audit.js 的 ALL_HANDWRITTEN 清单仍使用重命名前的 content/docs/protocol/objectos/* 路径。该目录早已改名为 content/docs/protocol/kernel/,清单里 11 个条目全部指向不存在的文件 —— 于是这个内部文档准确性审计静默跳过整个 protocol/kernel 目录。

为什么它值得修,且证据充分

它不是假设的风险,而是已经付过两次代价的实洞:

• content/docs/protocol/kernel/runtime-capabilities.mdx 通篇描述已于 #3605 删除的 ObjectStackCapabilities —— 整页教一个不存在的 schema #4781:runtime-capabilities.mdx 整页教一个 feat(spec)!: remove the dead static capabilities-descriptor cluster #3605 已删除的 schema,烂了近两个月无人发现;
• content/docs/protocol/kernel/http-protocol.mdx 的 discovery 响应示例把 dispatcher 形状挂在 /api/v1/discovery 名下 —— 字段与 REST 实际返回体对不上 #4817:http-protocol.mdx 把 dispatcher 的响应样例挂在 /api/v1/discovery 名下,同样无人发现。

两页都在 protocol/kernel/ 下 —— 不是没人查,是查它们的脚本以为那个目录不存在。与 #4690(门禁无 MANIFEST 静默 skip)、#4804 的根因(lint 警告写 stderr 而门禁只读 throw 路径)同族:看的动作在发生,看的对象不在那里。

修法

1. 把 ALL_HANDWRITTEN 的 11 条路径更新为 protocol/kernel/ 现状(注意 content/docs/protocol/kernel/runtime-capabilities.mdx 通篇描述已于 #3605 删除的 ObjectStackCapabilities —— 整页教一个不存在的 schema #4781 已删掉其中一页,清单应随之减一);
2. 加一条自证:清单中的路径若不存在,脚本必须报错退出而不是静默跳过 —— 否则下次目录改名,同样的洞原样重开。这是本仓 把 #4632 词表扩到「启动期对注册表的终局判断」—— 一次冷启抓出 3 例,当前零防线 #4777 / check:i18n 应把 unknown-authoring-key lint 判为失败 —— 否则第十份 extract 配置还会照抄同一个错 #4804 / check:react-declaration-parity 是唯一没接进任何 workflow 的源码审计门禁,且无 MANIFEST 时静默 skip 退出 0 —— 它现在永远不可能红 #4690 三单刚建立的同一条纪律:一个连「无事可查」都当成功的检查,与不存在的检查不可区分。

验收

• 清单路径全部指向存在的文件;
• 人为在清单里塞一条不存在的路径,脚本非零退出并点名该条目(反向验证);
• 对 protocol/kernel/ 现有页面跑一轮审计,结果如实呈现(发现新的过期页就按 Prime Directive chore: version packages #10 立单,不在本 PR 里顺手改)。

关联

• 发现现场:content/docs/protocol/kernel/http-protocol.mdx 的 discovery 响应示例把 dispatcher 形状挂在 /api/v1/discovery 名下 —— 字段与 REST 实际返回体对不上 #4817(修复记录在其正文「顺带」一节)
• 代价实例:content/docs/protocol/kernel/runtime-capabilities.mdx 通篇描述已于 #3605 删除的 ObjectStackCapabilities —— 整页教一个不存在的 schema #4781、content/docs/protocol/kernel/http-protocol.mdx 的 discovery 响应示例把 dispatcher 形状挂在 /api/v1/discovery 名下 —— 字段与 REST 实际返回体对不上 #4817
• 同族纪律:check:react-declaration-parity 是唯一没接进任何 workflow 的源码审计门禁,且无 MANIFEST 时静默 skip 退出 0 —— 它现在永远不可能红 #4690、把 #4632 词表扩到「启动期对注册表的终局判断」—— 一次冷启抓出 3 例,当前零防线 #4777、check:i18n 应把 unknown-authoring-key lint 判为失败 —— 否则第十份 extract 配置还会照抄同一个错 #4804

[xuyushun441-sys]

审核通过 — PR #4921 已取消草稿并挂上 auto-merge(SQUASH)

本单我自己写的正文有三处数字是错的,dev 一条都没信,重新测了。 10 条 objectos 死条目不是 11;清单是 146 条不是文件头注释写的 147;死条目总共 16 条不是 10。他的做法正是本单要立的规矩 —— 议题正文的写法本身就是这个缺陷的产物。

更要紧的是他找出了我根本没问的那个方向,而且它大三倍。

我只问了「死条目」。实测:48 份磁盘上存在的文档根本不在清单里,含 protocol/kernel/** 全部 9 页、整个 content/docs/capabilities/ 目录、releases/v12–v17。一次打印 FULL audit (no args.docs given) 的运行,实际审的是 178 篇里的 130 篇。

这改变了本单的结论:只修死路径,protocol/kernel 仍然不会被审 —— 因为那 9 页在改名前后两个名字下都从未被列过。目录改名不是"打断了 11 条目录项",而是从清单里删掉了一个目录,而没有任何东西把新目录加回来。我按"路径写错了"立的单,真正的病是"清单与磁盘之间没有任何一致性约束",两个方向同时腐烂且都不出声。

我独立核过最终产物:生成块与 origin/main 的 content/docs/**/*.mdx(排除 references/)178 条完全一致,零差异。

"能不能派生"这个问题他回答得比我预期的深。 内容上完全可派生;位置上不可 —— 工作流脚本跑在 node:vm 里,全局只有 log/phase/console/budget/定时器加 agent/parallel/pipeline/workflow/args,codeGeneration 关闭,没有 require、没有文件系统、没有 eval。这个事实仓里任何地方都没写,他是从 Claude Code 二进制里读出来的。它同时排除了两个显而易见的设计(运行时 glob、读一个 JSON 产物),逼出"生成时派生 + CI 门禁"这条路。派生源刻意复用 affected-docs.mjs --all 子进程调用而不是再写一遍遍历 —— 「手写文档」只能有一个定义,第二次遍历就是下一个会漂的东西。

四个红态,其中两个是我没要求的:除了改回一条路径、以及在磁盘上真的把目录改名回去(#4851 的原始机制本身),还有「生成标记被删掉」(门禁找不到自己的审查对象时判红而不是判绿)和「手工从清单里删一条」(那个我没问的方向)。

还补了两张我没想到的网。 门禁只看得见默认清单,而 args.docs 才是最常见的调用方式,没有任何 CI 门禁能看见调用方传了什么 —— 一条坏路径在那里的失败方式和本单一模一样。所以加了启动前置校验(并且校验它自己的算术:返回路径必须与 scope 不重不漏地对应,对不上按失败处理),以及真实读取路径上的 docExists。理由写得对:跑在别处的自检,证明不了真实路径上的任何事(#4868 的教训)。

共享文件冲突处理得对:package.json 与 #4915 在相邻行冲突过,他保留了对方的 --self-test 改动做并集 —— 我核过,check:nul-bytes 与 check:doc-authoring 两行都在。lint.yml 那一步放在 lint job 是刻意的:会打破这份清单的改动是一次文档改名,packages/** 的 paths filter 会让门禁恰好对自己的失效模式失明。

没有顺手修文档失准,按要求只报告:机械抽查(HOUSE_FACTS 词表零命中、包名逐一对照、objectos 残留 0)未发现新失准,但他明说这不能替代真正的实现级审计,因为他跑不了那个 LLM 工作流。建议合并后跑一轮 scoped audit,capabilities/(10 页)更是从来没进过审计范围。

顺带立的 #4920 值得单独看:审计工作流的交付物是就地改写 mdx,而它的范围包含 content/docs/releases/** —— 与 AGENTS.md「releases 是 release-owned」直接冲突。旧清单里已有 3 页,派生后变 9 页,第一次显眼。修它等于引入第二套「手写文档」定义,正是本 PR 消除的那个失败,所以需要维护者拍板。

---

Generated by Claude Code