从 #4851 的实施中发现,不在该 PR 内顺手改(改它等于在本仓引入第二套「hand-written doc」定义,是一个需要维护者拍板的口径决定)。
现象
docs-accuracy-audit 工作流的交付物是就地编辑 mdx(RULES 第 1 条:"Edit the doc FILE IN PLACE with Edit/Write. The edits to disk are the real deliverable"),而它的审计范围定义是 content/docs/**/*.mdx 减去 references/ —— 这个集合包含 content/docs/releases/**。
AGENTS.md 的 Documentation Guardrails 与 CLAUDE.md 的三条硬规则之一说的是相反的话:
content/docs/releases/ | RELEASE-OWNED | 不要在代码 PR 中编辑。发布说明在发布时集中撰写,由 changeset + ADR-0087 registries 编译而来。
也就是说:跑一轮 full audit,LLM agent 会去改发布说明页,然后按 scripts/docs-audit/README.md 第 4 节的流程开 PR —— 正是 guardrail 要禁止的那种 PR。
数量
#4851 之前,那份手写清单里恰好只有 3 页 releases(index、implementation-status、v9),纯属清单烂掉的副产品(v12–v17 当时根本不在清单里)。#4851 把清单改为从目录派生后,范围变成 9 页(补齐 v12–v17)。所以这不是 #4851 引入的新冲突,但它把冲突从 3 页放大到 9 页,并且第一次让它变得显眼。
需要拍板的问题
审计范围要不要排除 content/docs/releases/**?
- A. 排除:
releases/ 是 release-owned,审计器不该有编辑它的权限。代价是「hand-written doc」出现两个口径 —— affected-docs.mjs(只读、映射用,包含 releases 是无害甚至有用的)与审计范围(可写)。需要把这个区分明确写进 scripts/docs-audit/,否则下一个人会把它当成漂移又"修"回去。
- B. 不排除,改为只报不改:让审计器对
releases/** 只产出 residualInaccuracies,不落盘编辑。保持单一范围口径,但审计器要区分「可写」与「只读」两类目标。
- C. 维持现状:接受 full audit 会改发布说明,靠 PR review 兜住。
倾向 B:它保住了单一的范围定义(#4851 刚刚证明了双口径清单会烂),同时让 guardrail 变成结构性约束而不是靠人记得 —— 审计器根本没有写 releases/ 的路径,而不是"约定上不写"。A 的长期代价是两份定义要各自维护;C 把 guardrail 留在「声明了但没执行」的状态,正是本仓反复付费修的那一类。
关联
从 #4851 的实施中发现,不在该 PR 内顺手改(改它等于在本仓引入第二套「hand-written doc」定义,是一个需要维护者拍板的口径决定)。
现象
docs-accuracy-audit工作流的交付物是就地编辑 mdx(RULES第 1 条:"Edit the doc FILE IN PLACE with Edit/Write. The edits to disk are the real deliverable"),而它的审计范围定义是content/docs/**/*.mdx减去references/—— 这个集合包含content/docs/releases/**。AGENTS.md 的 Documentation Guardrails 与 CLAUDE.md 的三条硬规则之一说的是相反的话:
也就是说:跑一轮 full audit,LLM agent 会去改发布说明页,然后按
scripts/docs-audit/README.md第 4 节的流程开 PR —— 正是 guardrail 要禁止的那种 PR。数量
#4851 之前,那份手写清单里恰好只有 3 页 releases(
index、implementation-status、v9),纯属清单烂掉的副产品(v12–v17 当时根本不在清单里)。#4851 把清单改为从目录派生后,范围变成 9 页(补齐 v12–v17)。所以这不是 #4851 引入的新冲突,但它把冲突从 3 页放大到 9 页,并且第一次让它变得显眼。需要拍板的问题
审计范围要不要排除
content/docs/releases/**?releases/是 release-owned,审计器不该有编辑它的权限。代价是「hand-written doc」出现两个口径 ——affected-docs.mjs(只读、映射用,包含 releases 是无害甚至有用的)与审计范围(可写)。需要把这个区分明确写进scripts/docs-audit/,否则下一个人会把它当成漂移又"修"回去。releases/**只产出residualInaccuracies,不落盘编辑。保持单一范围口径,但审计器要区分「可写」与「只读」两类目标。倾向 B:它保住了单一的范围定义(#4851 刚刚证明了双口径清单会烂),同时让 guardrail 变成结构性约束而不是靠人记得 —— 审计器根本没有写
releases/的路径,而不是"约定上不写"。A 的长期代价是两份定义要各自维护;C 把 guardrail 留在「声明了但没执行」的状态,正是本仓反复付费修的那一类。关联
content/docs/releases/in a code PR」