doc-governance

文档治理

docs/ 与 rules/ 定位

维度	docs/ 设计文档	.cursor/rules/ 规则
本质	项目知识资产（What/Why）	AI 行为指令（How）
读者	人 + AI	AI

灰色地带优先放 docs/，rules 简短引用。

内容策略

• 语言：公开设计文档与贡献说明以中文为准；根 README 可保留一句英文产品介绍（检索 / 跨工具 AI）。不维护完整英文 docs。
• 文档是现状说明书，不是变更日志——变更历程交给 git。推广到所有现行通道（提示词、对用户的结论、规则、注释、记忆条目）→ 现行信息。
• 出门检验：改完的现行文须仍会改变以后怎么做（同上）；落地同一改动把已完成阶梯、废名二选一、施工日记带出权威文。
• 只记录代码看不出来的东西：决策与理由、被否决方案、约束边界、跨系统集成点。
• 检验标准：「AI 读完代码后还缺什么信息？」缺的才写。
• 主循环归属：新增 / 改写 docs/ 专题时，开头写一行「主循环归属」——服务主循环（说·组·看·拍·收 + 记）哪一拍。答不出的须标明是平台底座、工程内务还是实验项目，这三类不进产品叙事、不进路线图产品方向表。判据全文 → 定位 §二；docs/03 已全篇覆盖，可抄格式。

现状目录 vs 规划目录

• 公开边界：公开仓只 track docs/01–05（及 索引.md 等公开入口）。规划目录 docs/06-规划/ 可存在于维护者本地磁盘，但不入公开树（gitignore；与 README / AGENTS.md / 索引一致）。公开 clone 勿依赖该目录存在。
• 现状目录 = 已落地现状 + 已确认的目标架构蓝图：既写代码已实现的行为/契约/决策理由/约束，也可保留已确认但未落地的目标设计（用 ⏳ 标注未落地部分）——蓝图本身是 01–05 的价值。
• 🗂️ 纯讨论提案不进 01–05：未定稿的提案/草案/讨论记录只放维护者本地的 06-规划；公开现状目录如需提及，只留短说明「详细提案不在公开仓 / 维护者本地」，或链到已公开替代（如 产品路线图摘要），禁止留下指向 docs/06-规划/ 的可点击死链。
• 文档滞后即修正：标 ⏳ 但代码其实已实现 = 文档没更新，就地改写为现状（标 ✅）、留在 01–05，不要迁走。
• 状态标记：🗂️ 仅用于维护者本地规划稿；⏳ 可出现在 01–05，但仅限已确认的目标设计（非提案）。
• 落地即更新：⏳ 项代码落地后，把对应 01–05 段落由 ⏳ 改写为现状。
• 不设归档子目录：docs/ 下禁止 归档/ 或同类「已落地副本」目录；变更历史以 git 为准。
• 规划文档落地后（维护者）：结论迁入 01–05 对应现状文档 → 本地 06-规划 原文可删，并在本地规划索引「已退役系列」记一行结论去向即可；公开读者以 01–05 + 路线图摘要为准。
• 禁止「移入归档保留全文」——若决策理由写不进 01–05，说明尚未真正落地，应留在维护者本地 06 标 ⏳/🗂️，而非归档进公开树。

同步规则

• 必须同步更新：架构变更、接口契约变更、核心依赖变更、数据模型变更。
• 不需更新：纯重构、不改行为的 Bug 修复、样式/文案微调。
• 发现不准确：立即暂停 → 指出不一致 → 提议修正 → 等人确认。

生命周期

• 删减处标一个 → 见代码: {单指针}；禁止清单式罗列。
• 被否决方案留一行「方案 + 否决理由」；已撤销决策只留「现状 X、因 Y」。
• 方案被替代：迁移记录到新文档 → 删旧文档，不留废弃文档。

权威与防回潮

• 一文一权威：同一决策只在一篇写满；他文一句 + 链接。新决策先定权威文，再改 related / 路线图一行。
• 热区权威（现行）：Stop / 姿势 A → 执行引擎；PermissionAxes → 安全；交付验收 / 拦截定案 → 编排器；提示词写什么 → 上下文工程 · 提示词设计原则（How → prompt-design.mdc）；什么信息留在现行通道 → 现行信息；勿增实体 → 定位 §二；BrowserSession → 前端技术 §9.12；断线只读 → 双模式；多 worker/Redis → 部署拓扑 §六。
• frontmatter status：与文内 ⏳ 正交——landed = 主体已落地；reference = 入口/地图/手册；blueprint = 主体仍是未落地目标设计（少用）。定义见 索引。
• 禁止「远期规划 §x」孤儿引用：公开仓写「详细提案不在公开仓」或链 路线图摘要；代码注释同规，禁硬链 docs/06-规划/。
• 跨文章节指针写「§编号 + 完整章节名」：pnpm check:doc-sections（CI contracts + release:gate）只校验章节名与目标文 ## N、名 逐字相等的复合指针。缩写成「§五 客户端架构」（真名带「（桌面 + 手机）」）即掉出守卫范围；纯编号「§十二」完全不被守——曾有约 20 处因该文重编号整批失效且长期无人发现。要提高覆盖就把标题写全，别去放宽检查器（放宽即引入误报，噪一次就会被关掉）。§9.12 这类决策号不是章节号，本就不在守卫面内。
• 契约变更 PR：必须触权威 docs（本规则「同步规则」）；权威不明时先在索引/分区地图补行再改专题。