durable-docs-update

持久化文档更新

依次做出两项判断：

判断	问题	回答“否”意味着
清理	这条注释应该存在吗？	删除这条注释。
文档审核	这个事实应该纳入当前指南吗？	删除这个事实。

调用方以内联方式调用此技能，绝不将其作为叶子子 Agent 调用。

输入

通过以下一种模式确定范围：

模式	适用场景	范围与变更内容
A — 会话	在当前工作会话中直接运行。	此 Agent 创建或编辑的文件，依据其 Edit/Write 历史记录；当前状态以及会话中的已知信息。
B — 范围	可用提交范围 A..B。	使用 git diff --name-only A..B 获取文件名；使用 git diff A..B 获取内容。
C — 调用方指定	协调器委派了未提交的编辑。	明确指定文件列表，并使用 git diff -- <those files>。

绝不通过 git status 推断范围；工作树是进程级全局的。模式 C 仅使用调用方指定的文件。

可选输入：

• discoveries — 调用方提供的 Discovery: 条目，已精简为注意事项或耦合关系。
• context — 工作目标与标准。
• spec — 工作的 spec.md；步骤 2 从中提取已锁定的 D-NNN-XX 决策。

协议

步骤 1 — 确定范围与规模

确定模式，列出范围内的变更文件，并对每个文件只计数一次。根据文件数量限制发现和应用子 Agent 的数量：

层级	范围内文件数	每轮子 Agent 数量
小型	1–3	最多 1 个
中型	4–8	最多 2 个
大型	9+	最多 3 个

如果文件之间紧密耦合，则减少子 Agent 数量。按最近的 AGENTS.md 父目录对文件分组，并将每个范围内文件恰好分配给一个发现子 Agent。若范围内没有文件，则继续执行步骤 5 的无操作报告。

• 简报。 向每个发现子 Agent 提供其负责的文件、范围内的差异或当前内容、相关发现、已锁定的决策以及工作背景。
• Git 安全。 将每个子 Agent 的 Git 读取和修改限制在其负责的文件内。绝不允许子 Agent 运行 git stash、git checkout -- .、git reset 或其他会修改整个工作树的命令。
• 发现边界。 发现子 Agent 不得进行任何修改。
• 基线。 使用 git show HEAD:<path> 读取已提交的基线。

步骤 2 — 发现、判断并放置

每个发现子代理都会调用 Skill 工具加载 vet-fact 和 place-fact，然后扫描分配给它的文件及直接相关的指导文档。只有当已更改的代码文件中包含候选注释时，才完整读取该文件；绝不读取整个仓库。

完整读取文件不会扩大范围。只考虑位于已更改代码中、约束已更改代码的注释，或由已通过的发现或决策点名的注释。除非调用方明确扩大范围，否则不要改动无关注释，包括测试分隔符和历史记录。

仅检查相关来源：

• 文件中的注释、祖先目录中的 AGENTS.md 文件，以及 .claude/rules/ 中 paths: glob 与该文件匹配的 Claude 路径规则。

• 只有当更改目的符合其路由条件时，才检查由根目录路由的任务文档。

• place-fact 选定的任何目标；仅仅跨越模块并不会自动选定某个文档。

• 收集。 从注释、传入的 Discovery: 条目、约束范围内文件的已锁定规范决策，以及直接指出受影响行为的现有指导中收集候选项。

• 合并。 将发现与其重述的决策合并，并保留决策中的理由措辞。

• 排除。 排除活动状态文档、注明日期的调查、会话日志、交接文档、流程／工作流文档、.agents/skills/、.claude/skills/、.claude/commands/ 以及无关材料。

• 设计参考：

  • 对影响面向用户 UI 的范围内工作，如果存在 meta/DESIGN.md，请检查受影响的界面和其中的 Maintenance。
  • 只有当工作更改了稳定规则、造成实质性缺口或冲突，或符合列出的刷新触发条件时，才提出刷新建议。常规 CSS 或组件更改不符合条件。

对每个候选项，先应用 WORTH，再应用 PLACE：

1. 使用 vet-fact 判断该事实是否应保留。与当前代码矛盾的注释应执行 UPDATE；未通过 WORTH 的注释应执行 DELETE。
2. 对每条保留的事实使用 place-fact，选定其规范归属位置和交付边界。
3. 对拟议更改分类：ADD 缺失的事实；UPDATE 过时或含糊的事实；TRIM 历史内容或冗余，同时保留事实；DELETE 不再适用的事实；或 MOVE 事实至其规范归属位置。TRIM 时保留任何有效的 Discovered: 新鲜度标记。
4. 对事实、操作和目标均正确的置信度评分，范围为 0.00–1.00。

将 D-NNN-XX 或 AC-NNN-XX id 保留在其标注的事实旁。删除任务 id、波次编号和 F-NNN-XX 发现 id，同时保留它们所遮蔽的任何事实。按 { source: file:line | input, current_text, fact, action, target, proposed_change, confidence } 格式返回提案；除候选项的当前文本外，不得返回其他文件内容。

步骤 3 — 合并、设门槛并分配

主 Agent 合并发现结果，按事实和规范目标去重，并保留置信度最高的副本。分配前解决相互冲突的放置位置。

• 设门槛。 接受所有置信度 ≥ 0.80 的提案；不询问，直接丢弃低于该值的所有提案，无论其来源或操作为何。只将被丢弃的注释提案保留用于步骤 5 的 left alone, unsure 报告。
• 设计参考路由。 对于目标为 meta/DESIGN.md 的已接受提案，主 Agent 通过 Skill 工具调用 map-design-language 技能一次，并提供受影响的界面、范围内的文件或差异，以及已接受的事实，而不是将其分配给应用子代理。该技能只刷新受影响的章节。

在步骤 1 的子代理上限内，将其他所有已接受提案按目标文件分组。每个目标文件只分配给一个应用子代理，并将 MOVE 的两侧分配给同一个子代理。如果没有其他提案留下，且 map-design-language 未更改任何文件，则继续步骤 5。

第 4 步 — 应用、打磨并检查一致性

将每个应用子代理收到的已接受提案原文及第 1 步的 Git 安全规则传递给它。每个子代理：

1. 在打磨文本之前，应用所有分配的提案。
2. 对于创建或经过实质性重塑的每份指令文档，均通过 Skill 工具调用 compress-file 技能。当更改新增、删除或移动了某个章节，或涉及至少三个章节时，文档即为经过实质性重塑。
3. 通过 Skill 工具依次调用 tighten-instruction 技能和 structure-prose 技能，仅处理本次运行更改过的评论和指令。
4. 为每项独立的视角编辑评分，范围为 0.00–1.00；当 c ≥ 0.80 时应用，低于该阈值时暂缓应用。
5. 每个文件返回一行、评论统计（corrected、deleted、tightened），以及已删除评论的详细信息，格式为 { file, line, text, confidence }。

所有应用子代理返回后，主 Agent：

1. 每份更改过的持久文档仅计数一次。若没有此类文档，则跳过一致性子代理；否则，应用第 1 步的层级规则限制其数量。
2. 在新建的一致性子代理之间对相关文档进行分组，并将每份文档分配给且仅分配给一个子代理。
3. 将第 1 步的 Git 安全规则传递给每个一致性子代理。

每个一致性子代理都通过 Skill 工具对每份分配的文档单独调用 check-coherence 技能。

所有一致性子代理返回后，主 Agent 确认最终合并后的差异应用了每项已接受提案，且不包含无关更改。

第 5 步 — 报告

调用方不会重复此报告。

**Docs sync:**
- Comments: [n] corrected, [m] deleted, [k] tightened
  - deleted: [file:line — "text" (0.NN), one per line | none]
  - left alone, unsure: [file:line — "text" (0.NN), one per line | none]
- Docs: [file — what changed, one per line | none needed]
- Dropped: [K] candidates below 0.80
- Instruction delta: [net lines], [artifacts added], [artifacts removed], [always-loaded lines]; review signal only, never a quota