创建时间：2026-07-16 最后更新：2026-07-16 状态：📋 待启动 触发：用户发现历史文档，尤其是过细的 handover、应急和执行记录，会被 Codex / Claude 当成当前事实，反而误导决策；仓库无法保证所有叙述实时同步。 相关历史：文档体系治理 · 开发流程 Harness 优化
现有文档治理主要解决了“文件放错目录”和“链接失效”，但没有解决更危险的问题：内容仍然存在、链接仍然有效，却已经不代表当前系统。
最近已经出现多次真实误导：历史 assignment 被当成当前实现、已完成命令仍被状态表写成待做、审计总数被直接抄进收口账目、过期审查快照被拿来评价当前 HEAD。机械健康不等于语义可信。
本计划不追求让所有文档实时更新。目标是让人和 Agent 一眼知道：
- 哪份文档可以用于当前决策。
- 哪份只解释稳定原理。
- 哪份只是历史证据，使用前必须回到当前事实源核验。
不做“旧文档全部归档后重写”的大搬家。 归档不会自动阻止 Agent 检索旧内容，还会制造断链、丢失仍有效的设计理由，并把一次语义治理变成大规模文件迁移。
采用“先分类、再压缩、最后按需归档”的渐进方案。优先处理最可能直接影响操作和安全判断的文档，research、insights、completed plans 暂不重写，只明确降权。
| 类型 | 可以承载什么 | 不可以承载什么 | Agent 使用规则 |
|---|---|---|---|
| Current authority | 当前不变量、操作入口、现场验证方法 | 重复的实施历史、容易变化的固定计数 | 可用于当前决策，但动态事实仍应执行验证命令 |
| Reference | 稳定架构、设计理由、术语和边界 | 当前阶段、当前状态、当前文件数量 | 只能辅助理解，不能单独证明系统现状 |
| Historical snapshot | 旧计划、审查报告、事故记录、历史 assignment | “现在仍然如此”的暗示 | 默认不作为当前事实；引用时必须给出当前代码、命令、issue 或 current authority 的交叉证据 |
每份 Current authority / Reference 文档使用最小元信息，不堆叠长模板：
Authority: current | reference
Source of truth: 当前代码、命令或状态入口
Last verified: 日期 + commit
Review trigger: 哪些路径或合同变化时必须复核
Supersedes: 被替代文档（如有）
Historical snapshot 只要求首屏明确显示历史身份、快照日期和当前替代入口。
| Phase | 内容 | 状态 | 用户能看到什么 |
|---|---|---|---|
| Phase 0 | 清单与风险分级 | 📋 待开始 | 一张文档清单说明谁是当前权威、谁是参考、谁是历史 |
| Phase 1 | Handover / 应急文档试点 | 📋 待开始 | 最常用文档变成短导航和可执行恢复步骤 |
| Phase 2 | 历史降权与引用闭环 | 📋 待开始 | 旧文档不会再伪装成当前说明，当前文档不隐式依赖历史快照 |
| Phase 3 | 复核机制与 Agent 规则 | 📋 待开始 | 改动触发复核，Agent 使用历史材料前必须交叉验证 |
一份可审查清单，至少覆盖：
AGENTS.md、CLAUDE.md、ARCHITECTURE.mddocs/handover/- 应急、恢复、运行手册
docs/guardrails/docs/rules/
每份文件标注权威类型、当前 source of truth、重复事实和建议动作。风险优先级按“错误后果”排序，不按行数排序。
- 不在清单阶段批量移动、删除或重写文件。
- 不把 research、insights、completed plans 逐篇重新审阅。
- 不用“最近修改时间”代替语义核验。
- 所有操作型文档都有明确权威类型。
- 能列出重复陈述同一动态事实的位置。
- 能回答“Agent 当前应该先读哪一份”，且每个主题只有一个答案。
Handover 从“完整历史叙述”收敛为系统地图：边界、入口、事实源、验证方式、深入阅读链接。
应急文档统一收敛为：
症状 -> 立即停止条件 -> 诊断 -> 恢复 -> 成功判据 -> 升级路径
命令必须可执行；背景、事故时间线和修复历史移到 Historical snapshot，只保留链接。
- 不为了缩短行数删除安全边界和恢复判据。
- 不把所有 handover 强行压成同一个模板。
- 不把动态状态改写成另一份需要人工同步的摘要。
- 随机选择三个常见操作问题，Agent 能在一个 current 入口内找到答案。
- 随机选择一个故障场景，按文档可以完成诊断并判断是否恢复。
- 文档不手抄能由 CLI、代码、issue 或 Project 现场查询的状态。
历史材料仍然保留，但首屏明确写明“这是快照，不代表当前状态”，并指向当前入口。需要归档的文件分批移动，每批同时修复入链和索引。
- 不一次性归档全部旧文档。
- 不因为已有 Git 历史就无差别删除有价值的设计理由。
- 不允许 current 文档用普通链接暗示 historical 文档仍是权威来源。
- Current authority 指向历史材料时，链接文案明确标注“历史依据”或“事故记录”。
- Historical snapshot 都能找到当前替代入口，找不到的明确写“无当前替代，不得据此推断现状”。
- 文件移动后相对链接、索引和反链全部闭合。
文档准确性不再依赖“记得定期通读全部文档”。复核分成两类：
- 事件驱动：关键代码路径、命令、状态机、owner 或事实源变化时，提醒复核相关 current 文档。
- 定期抽样：优先抽查 handover、应急和 guardrails；历史文档只检查身份标记、链接和替代关系。
- 不承诺自动理解所有自然语言语义。
- 不把
Last verified变成无人核验却定期自动刷新的假时间戳。 - 不因为 lint 通过就宣称文档内容真实。
- 审查请求必须携带明确 commit hash，reviewer 只对该基线给结论。
- Agent 引用 Historical snapshot 做当前判断时，必须同时给出当前事实源证据；缺证据则明确报告“不确定”。
- 对一组真实问题执行盲测，Codex / Claude 的答案与当前代码、命令和运行状态一致。
可自动化检查：
- 相对链接、绝对路径和归档入链。
- authority 元信息是否缺失。
- Historical snapshot 是否缺少替代入口或“不得推断现状”声明。
- review 请求是否包含 commit hash。
- Current authority 是否链接到已移动或 superseded 的入口。
不能仅靠 lint 判断：
- 文档描述是否仍符合产品行为。
- 设计理由是否仍适用。
- 某条命令虽然存在，是否仍能安全恢复系统。
这些必须由事件触发的人工或 Agent 复核、测试和真实 smoke 共同完成。
- 每个关键主题只有一个 Current authority 入口。
- Handover 和应急文档不再兼任实施历史账本。
- 动态事实优先现场查询，文档只说明来源和验证方法。
- Historical snapshot 默认不参与当前决策。
- 文档审查绑定明确 commit hash，不再出现审计快照错位。
- 新机制不会削弱安全、权限、数据库、Runtime 和发布 guardrail。
- 第一批试点验证有效后，才决定是否扩展到 research、insights 和 completed plans。
本计划主要是文档与流程治理。只有执行真实故障恢复、Agent 盲测或运行态查询时才登记；纯链接扫描不冒充 smoke。
| Date | Runtime | Provider | Model | 凭据形态 | 场景 | Result | Evidence |
|---|---|---|---|---|---|---|---|
| 待执行 | n/a | n/a | n/a | n/a | Agent 使用 current / historical 文档回答真实问题 | 待验证 | commit hash + 问题集 + 当前事实源 |
- 2026-07-16：用户提出历史细文档正在误导 Codex / Claude，且全量实时维护不可行；决定建立独立治理任务。
- 2026-07-16：不采用“旧文档全部归档重写”。原因是归档不等于检索隔离，且会扩大断链和信息损失风险。
- 2026-07-16：治理优先级从“文档放在哪个目录”升级为“文档是否有资格参与当前决策”；机械健康与语义可信分开验收。
- 2026-07-16：第一批只处理 handover、应急/运行手册、guardrails 和顶层入口；research、insights、completed plans 先降权，不做大规模重写。