doc-governance

Doc Governance (文档治理)

文档是负债，不是资产。每份文档都在向每次改动收税——税就是"同步它"的认知成本。 治理的目标不是"文档好看"，而是让文档的税最低：进场的人 5 分钟看懂现状，改动的人不用为文档付双重成本。

核心理念（先于一切方法）

1. 真值单源 (Single Source of Truth)：可验证的事实（版本、路径、模型、命令、测试数）只写在一个文件里（如 AGENTS.md / FACTS.md），其他文档一律指针引用，不复制。复制 = 漂移，漂移 = 未来某天 AI 按错的数字干活。
2. 按生命周期分层，不按主题分层：文档按"它回答什么问题"归类——当前真理 / 实战经验 / 验证基线。不要按"系统模块"或"业务域"分类，那是代码的活。
3. 项目内容与系统文档分离：docs/ 只放系统/管线文档。项目生产内容（剧本、分镜、对白、系列设定）归 projects/<项目>/docs/，跟着项目走，不进系统文档空间。
4. 死文档直接删除，不建 archive：git 历史就是存档。只有极少数有独立审计/决策价值的才保留，其余 git rm 干净利落。
5. 诚实标注，禁止膨胀文案：mock 测试就是 mock，写 UNIT_ONLY；冻结就是冻结，写 FROZEN 之后不许再改。文档吹的每一句牛，都会变成后人踩的坑。

治理流程（Audit → Design → Converge）

Mode 1: Audit（只审不改）

A. 找事实漂移（最优先，P0）：

• 文档声称的数字 vs 实测：跑测试、跑 git log、数文件，拿证据对质文档。
• 例：AGENTS.md 写 "45/45 全通"，实测 50 个 —— 多源事实已经各说各话。
• 例：BUILD_INFO 写 "50_PASSED_REAL_INTEGRATION"，实测 0.76s 的 mock 测试 —— 膨胀文案。

B. 找幽灵引用：

• grep 文档/CLI 里提到的文件名，ls 看是否真实存在。
• 例：CLI choices 接受 fast_preview，但 pipelines/ 下根本没有这个文件 —— 幽灵选项。

C. 找冻结失效：

• 声明 "FROZEN" 后 git log 是否还有功能性提交？有 = 冻结是装饰，不是状态。

D. 找重复与混层：

• 同名/近名文档并存（如 ARCHITECTURE.md vs system_architecture.md）—— 确认是"当前实现 vs 长期愿景"还是纯重复，重复就合并。
• 当前真理文档里混着执行历史/日期日志 —— 拆出去。
• 过程记录（迁移说明、施工过程、原始参考）躺在主目录 —— 标记为死文档。

输出：审计报告（P0/P1/P2 分级 + 每项证据：文件:行号）。

Mode 2: Design（设计目标结构）

生命周期分层模型（核心理念，非强制目录名）：

docs/
├── README.md        # 导航索引：组织理念 + 使用约定 + 目录路由
├── 01-<当前真理>/    # 活的契约：架构、规范、标准、路线图（现在是什么）
├── 02-<经验沉淀>/    # 实战教训、学习笔记（我们学到什么）
└── 03-<验证基线>/    # 测试报告、上游快照、审计记录（我们验证过什么）

约束：

• 目录只建"有真实边界"的：单份文档不建目录；空目录/单文件目录拍平。
• README 只导航不复制内容：路由读者到文件，不重复文件内容。
• 语言/命名跟仓库走：仓库是中文就中文，别硬套英文编号。
• 复刻理念，不复刻目录：别的仓库的 02-项目架构/03-功能模块/ 是它的项目结构，你的项目结构要由你的内容决定。用户说"参考理念"，不是让你抄文件夹名。

Mode 3: Converge（执行收敛）

1. 改代码：删幽灵选项/特判（CLI choices、registry 别名），先让代码和现实一致。
2. 收敛真值：选定一个真值文件，其余文档改指针引用；测试数这类会漂移的数字改成"pytest 全绿"这类不再漂移的表述。
3. 合并重复：确认重复后合并成一份，git rm 另一份。
4. 删死文档：git rm 过程记录，不留 archive 目录（git 历史就是 archive）。
5. 分离项目内容：项目文档 git mv 到 projects/<项目>/docs/。
6. 同步所有引用：README、AGENTS.md、CLAUDE.md 的路径/数字一起改，不留断链。