文档治理
Wow 只在最小且明确的权威位置维护当前文档。实施计划不是长期文档，Git 历史就是归档；实验材料只有在其他贡献者能够复现或校验时才保留。
document/ 与 docs/superpowers/ 中仍受跟踪的旧文件都是待迁移项，不是事实来源。清理 PR 会先把唯一且仍有效的知识或可复现实验证据迁到规范归属，再删除旧文件。
规范目录
| 内容 | 规范位置 | 规则 |
|---|---|---|
| 项目入口 | README.md、README.zh-CN.md | 只保留最短且有用的项目说明，并链接文档站 |
| 仓库治理 | 根目录 CONTRIBUTING.md、SECURITY.md、CODE_OF_CONDUCT.md、AGENTS.md、CLAUDE.md | 只保留仓库级政策与 Agent 指令 |
| 产品、架构、迁移、运维与参考文档 | documentation/docs/{en,zh}/ | 唯一长期文档主站；公开页面保持双语结构对称 |
| 文档静态资产 | documentation/docs/public/ | 只保留当前文档引用的资产 |
| Mermaid 无法表达的图源 | documentation/diagrams/ | PlantUML 只用于用例图等不支持的图形 |
| 可复现性能证据 | wow-benchmarks/results/ | 证据归属能够解释它的 Benchmark 模块 |
| Agent 能力 | skills/ | Skill 指令、引用和资产作为可执行能力就近保留 |
| 已发布模块用法 | <module>/README* | 模块 README 与它说明的制品放在一起 |
长期文档不得放在 document/ 或 docs/superpowers/。docs/superpowers/ 可以继续作为 ignored 的本地 Agent 工作区，但禁止 force-add 其中的 Spec、Plan、报告或 review package。
文档生命周期
长期文档
长期文档定义当前合同、架构边界、受支持迁移、运维过程或精确参考。直接更新规范页面，不要创建带日期的后继文件。公开文档变更必须保持中英文结构和技术语义对齐。
就近文档
模块 README 与 Skill 指令不是第二套文档站。它们只解释本地制品或可执行 Agent 能力，更广泛的概念应链接 VitePress。不要在这些文件中复制完整架构、迁移或配置指南。
可复现实验证据
实验材料只有同时记录以下信息才保留：
- 被测 commit 或不可变源码版本；
- 精确命令与参数；
- 相关运行时、依赖和环境事实；
- 足以校验结论的原始或派生结果；
- 打包资产的校验和或其他完整性机制。
保留的性能证据迁到 wow-benchmarks/results/。重复资产、不可验证实验，以及当前文档或 Benchmark 报告已不再使用的证据直接删除。
临时工作材料
Spec、实施计划、review 记录、临时 QA 对比和已完成 rewrite plan 都是工作材料。工作期间放在 ignored 的本地工作区；长期结论合并进规范页面后删除这些材料，Git 历史与 Pull Request 保留实施记录。
何时判定为过期
满足任一条件即可判定文档过期：
- 规范 VitePress 页面已经拥有相同结论；
- 文档描述的 API、版本、类型、路由、配置或架构已经删除；
- 文档只描述一个已完成变更的实施过程，不再定义当前合同；
- 实验证据无法复现或校验；
- 新事实来源已经拥有同一主题，旧文件没有额外的受支持差异。
不要仅按日期删除。删除前必须检查入站链接，并与当前源码、测试和规范文档比较。若文件仍包含唯一且有效的知识，先迁移知识，再在同一 PR 删除旧文件。
目标迁移策略
文档清理的目标是让当前站点只保留通往当前主版本的直接路径，以及仍有效的运维迁移。Wow V9 的目标形态是完整 V8→V9 路径，加上当前运行时与传统架构迁移；更早的迁移链路随后归属对应 Release Tag。
当前站点仍发布 V6→V8，已有 V8→V9 文档也只覆盖 Query，而不是完整迁移路径。完整替代页面发布前必须保持这些链接有效；只有在同一 PR 发布并接入完整替代路径时，才能删除 V6→V8 导航与内容。
图表与资产
- Mermaid 支持的图全部使用 fenced Mermaid。
- 不在 Mermaid 源旁提交生成 SVG。
- PlantUML 只保留 Mermaid 不支持的用例图等类型，并集中到
documentation/diagrams/。 - 只有文档运行时无法渲染规范图源时才保留渲染资产。
- 删除无引用截图与重复资产；logo、徽章和当前产品截图放在
documentation/docs/public/。
清理流程
文档清理拆成可独立评审的 PR：
- 盘点受跟踪文档、资产、链接和归属；
- 把每项标记为保留、迁移、归位或删除；
- 删除旧来源前先迁移唯一且有效的知识；
- 把可复现实验证据归位到所属模块；
- 删除过期链接、导航、重复资产和旧迁移页面；
- 在 PR 正文列出迁移与删除路径，不再提交另一份清理报告；
- 每批完成构建和 review 后再开始下一批。
最终状态会删除整个 document/，并清空所有受跟踪的 docs/superpowers/ 文件。
计划中的自动检查
后续独立 PR 会为相关 Pull Request 增加文档布局检查。启用后，遇到以下情况失败：
document/或docs/superpowers/出现受跟踪文件；- Markdown 出现在未批准位置，而不是根治理文件、
documentation/docs/、skills/、wow-benchmarks/或模块 README； - Mermaid 支持的图新增 PlantUML 或生成的图表 SVG；
- 使用锁定依赖无法构建 VitePress 站点。
检查复用仓库脚本和现有工具链，不增加另一套文档框架或归档目录。
该 PR 合并前由 reviewer 人工执行治理规则；本文不声称当前 CI 已经能够拒绝布局违规。
Review 清单
- 当前主题是否只有一个权威页面？
- 中英文公开页面是否结构对齐？
- 模块 README 与 Skill 是否通过链接复用，而不是复制广泛指南？
- 每个保留实验是否可复现并归属
wow-benchmarks？ - 被删除路径是否已无入站链接？
- PR 是否避免提交 Plan、生成构建输出和本地 Agent 状态？
- 文档布局检查、VitePress 构建和
git diff --check是否通过？