[Decision] 新增任何手写文档页都必须改一个 `.claude/` 生成物，于是每张文档卡都变成人工合并 —— 这一条要不要开机械化例外

[os-elon]

Surfaced while reviewing #10211 / PR #10273 (epic #10206). Measured, not suspected.

The collision

scripts/docs-audit/check-audit-scope.mjs keeps ALL_HANDWRITTEN — the docs-accuracy-audit's scope list — inline inside .claude/workflows/docs-accuracy-audit.js, and it has to: a workflow script runs in a node:vm with codeGeneration disabled and no filesystem, so it cannot enumerate content/docs/** itself and cannot read a JSON artifact either (the file's own docblock says so, citing #4851). The scope is exactly content/docs/**/*.mdx minus references/**, and the gate fails in both directions the moment the list and the tree disagree.

check:docs-audit-scope is on the gate list for any content/docs card. So:

adding a hand-written docs page ⇒ regenerating a .claude/ file ⇒ the PR's path surface hits the governed surface ⇒ human-merge-only.

The two acts cannot be split into separate PRs: split them and the docs half is red.

Blast radius, counted

PR #10273 is the first instance. Seven more are already queued or in flight under #10206 — #10210, #10213, #10215, #10216, #10218, #10222, #10237 — every one of which adds at least one page. #10209 escaped only because it adds a nav line and no .mdx. Beyond this epic it applies to every future docs page the project ever adds.

The governed-merge discipline exists so an agent cannot quietly rewrite its own instructions. What is actually landing in these diffs is a machine-regenerated sorted list of doc paths inside a block that is itself labelled // GENERATED — do not hand-edit. That is not the risk the rule was written for — but the rule is deliberately non-proportional ("一条命中就分叉, ⛔ 不按比例判"), and I am not going to reinterpret it myself.

• 项目长远合理性：现状让「治理面」和「派生产物」共用一个路径谓词。每加一页文档就要人工合并一次，久了必然出现两种坏结果之一——要么维护者被无意义的合并请求淹没而开始盲签（治理形同虚设），要么文档页因为等不到人而积压。把判据从「路径命中」收窄到「这个 diff 是不是纯粹的生成块重算」是缩小特例、不是增生特例。
• 实际业务拉动：今天就撞上了，不是假想。PR docs(automation): add scheduled jobs and email templates guides #10273 已经在等人工合并，同一 epic 下还有 7 张卡会依次撞上同一堵墙；这是本轮唯一一个会阻塞交付的结构性问题。
• 防 AI 犯错：选项 C 比现状更能防错，因为它把「只许重算、不许手改」变成机器判据：闸门验证该文件的 diff 只落在 GENERATED 块内、且与 --write 的输出逐字节一致，任何真正改 workflow 行为的编辑照旧落进人工合并。现状是「一律人工」，靠人眼在 439 行 diff 里认出那 2 行是不是生成的——这恰恰是响亮拒绝优于人工容忍的场景。
• 创业阶段不扩散：选项 C 是给已有闸门加一个可判定的谓词，不新增能力面、不新增标签、不新增流程；选项 B 要重构 workflow 的取值通道，那才是扩散。

推荐：C。 把 governed 判据从「文件 .claude/workflows/docs-accuracy-audit.js 被碰到」收窄为「该文件被碰到，且 diff 不完全等于 node scripts/docs-audit/check-audit-scope.mjs --write 的输出」。纯重算放行进队列，任何其它编辑照旧人工合并。这是机械可判的，不依赖任何人的判断。

选项

• A — 维持现状。 每个新增文档页的 PR 人工合并。零改动，代价是 8 个 PR 排队等你，且这是永久成本。
• B — 把清单移出 .claude/。 但 workflow 读不了文件系统，所以得改由 args 注入或 CI 预注入 —— 动的是 workflow 的取值通道，工作量和风险都远大于问题本身。
• C（推荐）— 给这一个生成块开机械化例外，判据如上。
• D — 放宽闸门本身：让 check:docs-audit-scope 在新增方向只告警、由定期任务批量补齐。⛔ 我不建议：这正是 docs-accuracy-audit.js 的 ALL_HANDWRITTEN 清单 11 条全部指向改名前的 protocol/objectos/* —— 内部文档审计静默漏审整个 protocol/kernel 目录 #4851 关掉的那个洞（清单双向静默漂移），而且削弱门禁属于人工地板，无论如何都得你拍板。

本分析看不见什么：我没有量过维护者实际的合并延迟——如果你本来就每天扫一遍 Review-requested 队列，A 的代价可能比我估计的小得多，那 C 就只是省事而不是必要。我也没有验证 --write 的输出在所有情况下都是确定性的（排序稳定、无时间戳）；C 的闸门依赖这一点，落地前必须先测。

Routing

domain:skills — the governed-surface definition lives in .claude/skills/pm-dispatch/ and AGENTS.md, and any change to it is skills-class. Filed by a maintainer-directed PM session under the standing direct-dispatch channel; not auto-adjudicated: it sits on the human floor twice over (governed-surface definition = ADR/skills class, and any gate-weakening reading is a 门禁削弱 decision).

Meanwhile PR #10273 is parked correctly — draft, review requested from os-zhuang, not queued. No work is lost either way you rule.

[os-elon]

四维分析（完整版，替换正文里的压缩块）

先补三个测量——正文的「本分析看不见什么」里有两条现在已经关闭，一条仍然开着。

① --write 的确定性：已关闭，是的。 renderBlock 的实现是 [...docs].sort() + 固定注释头 + 逐条 JSON.stringify，无时间戳、无环境输入、无 Date/random。输出是文档集合的纯函数。check-audit-scope.mjs --self-test 有 24 条用例钉住 parser / renderer / differ，本轮实跑通过。选项 C 的闸门可实现，这一条不再是风险。

② 维护者当前的人工合并队列深度：3 个 PR（is:open review-requested:os-zhuang），其中一个就是本案的 #10273。没有淹。 对照吞吐：近 7 天合并 886 个 PR（约 127/天），今天 governed 合并 10 笔（约占 8%）。

③ 历史新增文档页速率：测不出来，本地是浅克隆（50 个 commit），git log --diff-filter=A 会把初始提交里的全部页算成"新增"（得出 177 这个假数），我拒绝引用它。唯一的弱信号：check:docs-audit-scope 今天报 182 篇手写文档，而 #4851 的 docblock 写作时是 178 篇——四个月/四周/四天不知道。这一条仍然开着，见文末。

---

轴一：实际业务需求（今天谁撞上）

撞上了，但不是我原先说的那种撞法，测量 ② 纠正了我。队列只有 3 个、维护者在清，所以"PR 会烂在队列里"不成立，A 的代价不是积压。

真实的拉力是另一回事，而且更值得处理：这个 epic 会连续产生 8 个几乎一模一样的橡皮图章。每一个都要求维护者打开一个 439 行的文档 diff，去确认其中 2 行是机器生成的。那不是审核，那是验证码。

governed 合并纪律自己写明了它的判据是什么——「Every entry below should correspond to a merge the maintainer performed or ordered in person. An entry the maintainer does not recognise is the violation signal」。这条判据依赖维护者对每一条都保有识别能力。往这个清单里灌入例行重算，降低的正是这条判据的信噪比。这才是今天的业务拉力：不是队列长度，是审计信号的稀释。

判定：有真实拉力，中等强度，且性质是治理质量而非交付速度。

轴二：项目长远合理性

现状把两样东西压在同一个路径谓词下：治理面（agent 指令、策略、门禁本身）和恰好住在治理路径下的派生产物。

.claude/workflows/docs-accuracy-audit.js 两者都是。它整体是一个可执行的 workflow 脚本——手改它确实是指令类改动，确实该人工审；但它内部有一个自我标注 // GENERATED — do not hand-edit 的块，块里是排序过的文档路径清单，零指令语义。路径粒度分不开这两者，内容粒度分得开。

选项 C 把谓词从「文件被碰到」收窄成「文件被碰到，且 diff ≠ --write 输出」——这是缩小特例，不是增生特例，符合 contract-first / no-workaround。

必须写下的反面考虑：每一个例外本身都成为要维护的东西，而且这个例外的闸门是安全相关的。它写错了，真正的指令编辑就会溜进合并队列。落地时必须满足两条：闸门用 PR 自己那棵树 现算 --write 输出来比对（不能比对存量 baseline，否则可被构造）；比对是逐字节，不是"看起来像生成的"。

判定：C 方向正确，但它把一部分治理强度从「人的注意力」转移到「一段代码的正确性」上，这段代码必须自带 self-test。

轴三：防 AI 犯错（C 在这一轴上最强，也是我改变看法的地方）

现状的最后一道防线是人眼在大 diff 里区分生成行与手改行。这正是这条轴指名的失败形状：消费端宽容（靠人工判断兜底）对上契约收紧（机器判据）。而且它还有一个自我拆台的性质——本次变更即将往这道防线上灌 8 次噪音，正是在削弱它自己依赖的那个能力。

选项 C 把它变成机器可判：该文件的 diff 必须与 --write 的输出逐字节相等，否则响亮拒绝、落人工地板。对一个粗心或恶意的 agent 编辑，C 比现状更严，不是更松。

这一轴上还有一个现状看不见的风险：#10249 记录了 next dev 会在 apps/docs/ 下写出未 gitignore 的 AGENTS.md / CLAUDE.md。在 A 之下，「文档 PR 碰 governed 面」是常态，于是这种意外卷入的 governed 文件混在常态里不显眼；在 C 之下它会立刻变红，因为它不等于 --write 的输出。

判定：C 明确优于 A，且理由不是省事，是可判定性。

轴四：创业阶段不扩散

• C：给已有闸门加一个谓词。不新增能力面、不新增标签、不新增流程、不新增座位职责。最小。
• B（把清单移出 .claude/）：workflow 跑在无文件系统的 node:vm 里，要改就得改它的取值通道（args 注入或 CI 预注入）。为一个不是关于 workflow 的问题重构 workflow —— 典型的扩散。
• D（放宽 check:docs-audit-scope，新增方向只告警）：⛔ 直接反对。这正是 docs-accuracy-audit.js 的 ALL_HANDWRITTEN 清单 11 条全部指向改名前的 protocol/objectos/* —— 内部文档审计静默漏审整个 protocol/kernel 目录 #4851 关掉的洞——清单双向静默漂移，16 条指向已删除文件、48 篇文档不在清单里，而"FULL audit"在整个期间报绿，两个真实的准确性缺陷因此躺了约两个月。而且削弱门禁本身就是人工地板。
• A：零改动。代价是永久的、随文档页数线性增长的审计信号稀释。

判定：C 最小，D 出局，B 不成比例。

---

推荐：C

把 governed 判据对这一个文件收窄为「diff ≠ node scripts/docs-audit/check-audit-scope.mjs --write 在本 PR 树上的输出 ⇒ 人工合并；逐字节相等 ⇒ 正常入队」。确定性已实测，闸门可实现，且它比现状更能防错。

会让我改推荐的两件事（不是修辞，是真的判据）：

1. 如果你人工合并文档 PR 的目的本来就包含"我想看一眼新文档页" ——即那道人工合并对你而言在做的是文档评审而不是治理审计——那 A 是对的，C 解决的是个假问题。这一点只有你知道，我从任何读数里都看不出来。
2. 如果 .claude/workflows/ 近期本来就要因别的原因重构，那就等那次一起做，别单开。

仍然开着的置信缺口：我测不出历史新增文档页的速率（浅克隆）。这直接决定 A 的真实代价——是"8 个 PR 然后每月 1 个"，还是"8 个 PR 然后每天 1 个"。178 → 182 这个弱信号倾向于慢，但时间跨度未知。在有完整历史的检出上跑 git log --diff-filter=A --since=90.days -- 'content/docs/**/*.mdx'（排除 references/）就能关掉它。如果答案是"每月 1 个"，A 的代价小到 C 只是省事而非必要，我的推荐强度会从"建议"降到"随你"。

---

Generated by Claude Code

[os-elon]

维护者裁定 — 选项 C

出处原话（2026-08-20，本会话，维护者直接对本卡）：「10277 同意 C」

鲜度门：录入前重读了晚于正文最后编辑的评论——只有本席的四维分析一条，无修正，正文与结论一致，无需调和。
状态转换同笔：needs-user-decision → pm:queue，domain:skills 保留。
Blocked-by: 活性：本卡无 blocker。
条件已判即判：四维分析里唯一开着的置信缺口（历史新增文档页速率，浅克隆测不出）不阻塞本裁决 —— 它只影响选项 A 的代价估计，而 A 已被否决；C 的可实现性依赖的是 --write 确定性，那一条已实测关闭（renderBlock 是纯函数，24 条 self-test 钉住）。不留悬置条件。

---

落地规格（裁决的机械化形式，实施者按此做，不得重裁）

判据变更。 governed-surface 对 .claude/workflows/docs-accuracy-audit.js 的谓词，从

该文件出现在 PR 的 path surface 中 ⇒ 人工合并

收窄为

该文件出现在 PR 的 path surface 中 且 其 diff 不完全等于 node scripts/docs-audit/check-audit-scope.mjs --write 在该 PR 自己那棵树上产生的输出 ⇒ 人工合并。逐字节相等 ⇒ 该文件不触发 governed 分叉。

四条承重约束，缺一条这个例外就是个洞：

1. 现算，不比对存量。 比对基准必须是在 PR 自己的树上跑 --write 得到的输出。比对任何存量 baseline 或缓存都可被构造。
2. 逐字节，不是"看起来像生成的"。 不做启发式，不做「只改了 ALL_HANDWRITTEN 块所以放行」的形状判断——只有与 --write 输出完全相等才算。
3. 只对这一个文件。 .claude/** 的其余部分、skills/**、AGENTS.md、CLAUDE.md、docs/adr/** 的判据一个字不动。这是一条具名例外，不是一类例外。
4. 例外自带 self-test。 这段判据现在是安全相关代码——它错了，真正的指令编辑会溜进合并队列。按 check-audit-scope.mjs --self-test 的同族做法钉住，至少覆盖：纯重算放行、手改块内一行拒绝、块外任意改动拒绝、文件同时含重算与手改时拒绝。

混合 diff 的判定不变。 一个 PR 若既含合格重算、又碰了别的 governed 路径，照旧整体分叉——本例外只把这一个文件从"命中"名单里摘掉，不改变「一条命中就分叉、⛔ 不按比例判」。

实施者注意：改动落在 .claude/skills/pm-dispatch/**（governed-surface 定义）与门禁脚本，因此本卡自己的 PR 必然是人工合并。这是对的，不要试图绕过——一个改治理判据的 PR 正是人工合并存在的意义。

验收：一个只含合格 --write 重算的文档 PR 不再被判 governed；任何对该文件的手改仍被判 governed；self-test 覆盖上述四种情形并在 CI 中运行。

解除的下游

本卡落地后，#10206 下 7 张新增页的卡（#10210 / #10213 / #10215 / #10216 / #10218 / #10222 / #10237）与已停放的 PR #10273 恢复正常入队。⚠️ 但 #10273 不等本卡 —— 它现在就在 os-zhuang 的 Review-requested 队列里，人工合并它是随时可以的，先落先了。

---

Generated by Claude Code

[os-elon]

Closed as a duplicate of #9866 — the ruling is preserved, not lost.

#9866 was filed 2026-08-19 and records the same collision with harder evidence than this card had: four page-adding docs PRs, each a +1/-0 edit to .claude/workflows/docs-accuracy-audit.js (#6891, #8964, #9449, #9860), three of which merged with nobody recording that the fence had been crossed. That last fact is the sharper statement of the defect — a fence that fires on routine traffic trains every seat to read past it — and this card did not have it.

Its candidate shape 2 is this card's option C, word for word.

This is a duplicate-check miss on my part. I ran a duplicate sweep at the start of the round, but scoped to the epic's own subject (docs coverage, nav, react pages). When PR #10273's governed-surface fork surfaced mid-round I filed a decision card without searching for that problem specifically. #9866 would have come up.

What moved to #9866 (see #9866 (comment)): the maintainer's ruling with the verbatim quote, the four load-bearing implementation constraints, and the measured --write determinism result that makes the exception implementable. Those are net additions over #9866's original text.

What did not move, and stays open on #9866: its own question — whether ruling 5 was ever meant to cover generated artifacts under .claude/. This card never put that question to the maintainer, so the ruling here answered the mechanism, not the original intent. Not answered by proxy.

No work is lost and nothing is unblocked or re-blocked by this closure: #9866 already carries pm:queue + domain:skills and sits in the skills seat's queue.

---

Generated by Claude Code