文档治理策略

放置规则

• designs/：架构决策、方案、权衡和接口设计。
• product-specs/：用户问题、范围、非目标和验收标准。
• execution-plans/：按 active/、completed/、tech-debt/ 管理的实施计划。
• references/：稳定操作资料、外部协议和长期说明。
• generated/：脚本产物，文档内必须说明生成命令。
• 顶层领域文档：当前系统基线，避免为同一主题创建第二个“总说明”。

生命周期

新需求先补产品规格或设计，再建立执行计划；实施中持续更新计划进度和决策日志；完成后记录验收与遗留风险并归档。仍对当前决策有解释价值的历史资料标为 archived 或 needs-review；已被当前真源替代、一次性且没有被现行计划引用的快照从 docs/ 删除，通过 Git 历史回溯。

应用或插件源码旁的 README.md、CHANGELOG.md、DEVELOPMENT.md 只说明该模块的安装、接口或维护方式，可与代码同放；跨模块的方案、台账、验收记录和运行知识必须进入 docs/。

可验证性

catalog.json 列出非索引文档的路径、状态、简介和复核期限。pnpm run docs:check 必须在合并前通过；pnpm run docs:freshness 用于例行扫描。Markdown 使用相对链接，不链接本机绝对路径，不把凭据写入文档。

生成与更新

生成物只能从源脚本更新。涉及路由、数据库结构、部署方式、接口契约或用户流程的代码改动，必须同步复核相关记录；若无文档变更，在执行计划或 PR 中说明理由。任何旧快照生成器不得覆盖当前真源。