跳到主要内容

仓库级重组整改 Playbook

跨区域、一次性的知识库重组操作手册。提炼自 2026-06-11 ~ 06-12 FinBayes 知识治理库重组实战（W1-W9：232 份文档盘点、84 份过程产物归档、19 → 3 值 status 词表迁移并立法、生态层 L3 对齐、全面 review 修复波）。

1. 什么时候用​

与 项目整改清单 的分工：

项目整改清单本 playbook
范围单项目 projects/<id>/，例行跨区域（projects + governance/workstreams + ecosystem + commons），一次性重组
审批L1，Controller 自走按触及区域分级（最高可至 L4），owner 拍板后执行
形态打勾 checklist盘点 → 提案 → 分波执行 → review

触发信号（任一出现即值得启动盘点）：

  • owner 反映「分不清哪个最新、哪个废、哪个工作中」
  • frontmatter status 取值失控（词表外值大量出现）
  • 已收尾 workstream 的过程产物仍堆在活跃树里，淹没 canonical 文档
  • landing / README 与实际文档树脱节（新增 canonical 文档从入口不可达）

2. 前置条件​

  1. 读 变更协议 §1 分级表；跨目录改动取最高级
  2. 与 owner 确认本轮约束清单：哪些目录不动、commit / push 权限分离（惯例：Agent 可 commit，push 由 owner 手动触发）
  3. 校验工具可用：npm run verify:kb / npm run build / npm run derive:check

3. 步骤​

Phase A · 盘点（只读，不改任何文件）​

  1. 脚本提取全仓（或目标范围）.md 的 frontmatter，落成一份 inventory 总账，放在不入 git 的工作目录（如 .agents/<task>/）
  2. 按区域分桶计数；统计 status 值分布——值的种类数本身就是诊断指标
  3. 逐个 workstream 判定是否已收尾。注意状态分裂：status.md 标完成不等于目录可整体归档，可能仍有活线文件（milestone 事实源、持续追加的 decisions/）需要单独剥离保留

Phase B · 诊断​

  1. 把 owner 的症状映射到根因（典型四类：词表混乱 / landing 失能 / 同概念双源 / 收尾未归档）
  2. 形成问题表：每个问题标注影响与修复点，修复点编号供 Phase C 引用

Phase C · 提案（owner 签字门，过此门才能动文件）​

  1. 给每份文档明确处置：保留 / 归档 / 迁移 / 改 status
  2. 删除、移动、批量改 status 都是不可逆高后果操作，必须先提案、owner 签字后执行
  3. 判断题显式列出请 owner 拍板（词表取值、归档范围、生态层是否纳入本轮），不要替 owner 默认
  4. 分级落点：触及 ecosystem/ → L3 立 ADR；词表等跨项目协议 → L4 立 ADR + 7 天公示（参见 ADR-0003 词表立法的实例）

Phase D · 分波执行​

  1. 波次排序：owner 痛点直击的波次放最前（如 landing 重写），归档与批量迁移随后
  2. 每波独立 commit；波间 npm run verify:kb 全绿才进下一波
  3. 归档用 git mv 保 rename detection；归档前 grep 入站引用，归档后逐处修复指针
  4. 引用修复遵守仓库呈现层规则：_archive/** 不可做 Markdown 链接（verify 规则拦截），改为行内路径提及并注明「已归档」；dot-prefix 文件公开站不渲染，同样不可链接
  5. L3 / L4 改动先出草稿（放不入 git 的工作目录）给 owner 通审，通过后才 commit 落地

Phase E · 收尾​

  1. 重跑 npm run derive，派生差异随波 commit；在项目状态记录（dot-prefix 整改记录文件）追加波次表：每波 commit hash + 内容一行
  2. push 由 owner 触发，Agent 不推

Phase F · 全面 review（重组规模大时强烈建议）​

  1. 多路并行 review agent 分维度审查（landing 准确性 / 归档完整性 / 治理质量）+ 机械扫描（旧路径残留、断链、frontmatter 合规）
  2. agent 报告逐条交叉验证后才动手修：计数用 git diff --name-status -M 实测；「断链」以 npm run build 的 broken-links 检查为准；「某波次降级了状态」以 git show <commit>^:<path> 查证历史
  3. 确认项打包为单独的修复波 commit；误报也要留档（写进状态记录），防止下次 review 重复误修

4. 验证​

  • 每波：npm run verify:kb 全绿
  • 收尾：npm run build 断链 / 断锚为零；npm run derive:check 通过
  • 文档中所有计数声明（「归档 N 份」「共 M 份 ADR」）以 git rename 实测为准，不引用记忆值

5. 回滚​

  • 每波独立 commit → git revert 单波即可，互不牵连
  • push 尚未发生时发现问题：直接追加修复 commit（历史未发布，无需改写）
  • 归档误移：git mv 回原位并恢复入站引用，作为独立修复 commit

6. 反模式（实战教训，每条都付过学费）​

  • ❌ 凭记忆或 agent 口头报数写进文档——实战中两处归档计数（25 vs 实测 23、63 vs 实测 61）即此来源
  • ❌ review agent 结论不验证直接修——实战中 3 例误报（误判断链、误判状态降级、误报垃圾文件）全靠交叉验证拦下
  • ❌ 自检声明「N 处全部修复」却不做收尾复扫——实战中「29 处全修」后仍漏 8 处旧路径
  • ❌ 触碰约束清单外的文件不报备——必要连带（如迁移文件后派生脚本的引用必须跟着改）可以做，但必须在状态记录中显式报备
  • ❌ 把过程性公告写成仓内新文档——git log + 状态记录已经足够

7. 关联​