fix(tooling): 发布说明页留在审计范围内,降级为只读通道 —— 报 finding,不改盘 (#4920)

[xuyushun441-sys]

Fixes #4920

维护者裁决:采纳议题推荐项 B —— content/docs/releases/** 留在审计范围内,但交付物从「就地改写」降级为「立 issue」。本 PR 实现该裁决。

冲突的形状

docs-accuracy-audit 的 RULES 第 1 条是 "Edit the doc FILE IN PLACE with Edit/Write. The edits to disk are the real deliverable",而它的范围(#4851 后从目录派生)包含 content/docs/releases/** 9 页。AGENTS.md:339 的 Documentation Guardrails 那一行说的是相反的话:

content/docs/releases/ | RELEASE-OWNED | ❌ Never edit in a code PR.

也就是说,一轮 full audit 的产物就是那条 guardrail 存在的理由所要拦下的 PR。

为什么不是「从范围里删」

议题里的 A 案(排除)会同时买下两样东西:读者最多的 9 页永远没人审,以及在刚刚生成化的清单之外再造一份「这个工作流覆盖哪些文档」的定义。#4851 的账单正是「一个主体两份手写清单」—— 两个方向同时腐烂,两个方向都不出声。所以范围一个字没动,只有交付物分叉。

分叉的判据必须在工作流 VM 内可判定(无 fs、无 require —— #4921 已探明),路径前缀满足这一点。并且这个前缀不是对 guardrail 的二次归纳,它就是 guardrail 路径列的原文,所以「release-owned」仍然只有一个定义。

两条通道

	可写文档(169)	release-owned(9)
prompt	审计 + 就地改	评审,禁改
输出 schema	fixesApplied / fixCount	findings[] + filesEdited
对抗验证 agent	有 —— 复核已落盘的编辑	无 —— 没有编辑可复核
交付物	diff	findings → 立 issue

READONLY_RULES 是独立文本而不是 RULES 加一条例外:同时收到「你必须改」和「你不许改」的 agent 会按自己的方式消解矛盾。

每条 finding 带 kind(never-true / no-longer-true / ambiguous)—— 发布说明是历史记录,「当前 API 不一样」本身不构成失准,这三种要的修法不同,而只有读过证据的 agent 分得清。加上 location / inaccuracy / suggestedFix / evidence(file:line),让立 issue 的人不必重做调研。

finding schema 刻意不带 fixCount 这类自报计数:数组长度就是数量,单一真相。也刻意不带 fixesApplied —— 「0 fixes」正是 #4851 证明过的、与「那里什么都没有」长得一模一样的值。

沉默跳过被同样否掉

裁决否掉的是「把 9 页从范围里删」,而一轮什么都不说的运行就是那个选项,只是靠意外抵达的。所以三处判红:

1. 只读页产出零结果(results.filter(Boolean) 会让它无声消失)→ 按名 throw;
2. agent 自陈 filesEdited: true → 点名文件 throw,并给出 git checkout -- 的话术;VM 看不见工作树,这是自陈,但自陈的违规也比在 review 里被发现(或没被发现)强;
3. 汇总恒定输出 releases (read-only): N finding(s) — file issues, do not edit —— N=0 也输出,因为「审过了,干净」是一个结果,而不是一段空白。

perDoc 里两种通道形状不同:只读条目没有 fixes 键可以被读成 0。

自检:检查项本身被证明会红

check:docs-audit-scope 新增四件事,前三件是结构性的(AGENTS.md 仍标 RELEASE-OWNED / 工作流常量仍等于该行 / 范围里仍有 releases 页),第四件是行为性的 —— 用 stub agent 真跑一遍工作流,看每篇文档实际拿到的 prompt 和 schema。刻意不用文本匹配:一个只读源码关键词的检查,会在「保留了词、丢掉了行为」的重构上判绿。

self-test 随后把分流从内存副本里删掉,要求该检查判红。四种 mutation 的实测输出(未合入,仅验证):

### routing removed
   - content/docs/releases/v9.mdx was given the EDITABLE audit prompt ("Edit the doc FILE IN PLACE") …
   - content/docs/releases/v9.mdx was given the edit-log schema (fixesApplied), not the finding schema (filesEdited)
   - content/docs/releases/v9.mdx is not marked channel:"read-only" in perDoc (got "edit")
   - a release page whose review returned nothing did not fail the run …
   （共 8 条)
### headline removed
   - no run-summary line "releases (read-only): 0 finding(s) — file issues, do not edit" …
### skip-throw removed
   - a release page whose review returned nothing did not fail the run — it was silently dropped …
### filesEdited-throw removed
   - a read-only agent reporting filesEdited:true did not fail the run naming the page …
### unmutated -> []

验证

$ pnpm check:docs-audit-scope
✓ affected-docs self-test: 32 cases pass.
✓ check-audit-scope self-test: 22 cases pass.          # 13 -> 22
✓ docs-accuracy-audit scope is in sync with content/docs/: 178 hand-written doc(s).
✓ release-owned pages are in scope and read-only: 9 page(s) under content/docs/releases/ review-only (findings → issues, never edited).

$ npx eslint .claude/workflows/docs-accuracy-audit.js scripts/docs-audit/check-audit-scope.mjs --no-inline-config
exit=0

$ pnpm check:doc-authoring
✓ doc authoring guard: 360 files clean.

$ node scripts/docs-audit/check-audit-scope.mjs --write && diff <(before) <(after)
（无差异 —— 生成块一个字节没动,本 PR 的改动全在 marker 之外)

$ git status --porcelain content/ | wc -l
0     # 本 PR 没有碰任何一页文档,包括那 9 页

package.json / lint.yml 未改动 —— 新检查跑在既有的 check:docs-audit-scope 里,自动进 CI。

一处口径说明(留给 review)

release-owned 页不跑对抗验证 agent:验证者的职责是复核已落盘的编辑并修复过度纠正,而这条通道没有编辑。对 finding 质量的约束改为「必须带 file:line 证据」+「立 issue 前有人读」。这同时把这 9 页的成本从 2 agent/页降到 1。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 12:33am

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅