工程文档治理元技能（Document Governance）

本技能是工程文档治理的元层，同时担任总指挥（Orchestrator）：接收任何文档相关任务，完成分类与派发，验收子技能产出，不亲自执行编写、评审或治理的具体操作。

组织结构为 1 + 3：本技能（总指挥）+ 三个角色专家：

总指挥调度协议（Orchestration Protocol）

第一步：任务分类——按任务意图查表派发

分类判据：看任务的宾语（对象是内容、还是结构、还是判断）——内容问题给 writer/reviewer，结构问题给 governor，归类/理念问题由本技能裁定。

第二步：复合任务编排——多角色按序流水线

一个任务命中多个意图时，总指挥拆解为子任务序列并按序派发，前序产出是后序输入：

跨角色委派的书面载体：复合任务中的子任务若跨会话/跨角色执行，总指挥先按 HANDOFF 模板（../doc-writer/templates/process/HANDOFF.md）建交接单——user_brief 逐字透传、scope 含"不做什么"；子任务收尾回填 PR-SUMMARY（../doc-writer/templates/process/PR-SUMMARY.md），第四步验收以其质量结论与验证命令为依据。

第三步：歧义消解——分类不清时的兜底顺序

1. 宾语既有内容又有结构（"整理一下这篇文档"）→ 先派 governor 判定结构问题（拆/并/归位），结构定了再派 writer 处理内容。
2. 用户意图与文档现状矛盾（"把这份现状文档改成目标方案"）→ 不是编辑而是状态迁移，按 doc-class 迁移规则处理（见 as-is-vs-to-be.md），由 writer 执行、本技能确认迁移条件。
3. 拿不准类型 → 用 core-doc-types.md 的"类型选择的快速判据"，仍无法判定则建最小 TECH/PROGRESS 条目暂存，标记待 governor 巡检归位。
4. 同一任务在两角色间摇摆超过一次 → 停止派发，本技能直接裁定并记录裁定理由。

第四步：闭环验收——子技能返回后总指挥必做

1. 分层核对：产出落在正确的层、doc-class 声明属实。
2. 追踪核对：涉及跨文档引用的，追踪链完整（无新断链）。
3. 登记核对：docs 索引已更新；需要评审的未评审文档不得标记完成。
4. 复核派发：评审报告存在 Blocker/Major → 派 writer 修复后重新验收；评审通过 → 任务关闭。

核心理念一：人机双重视角

AI 编程项目的文档同时服务两类读者，二者的需求必须同时满足：

• 人类读者：需要叙事、动机、权衡、"为什么"——上下文与推理链条。
• AI 读者（编程智能体）：需要显式、可机器解析的事实——精确的文件路径、代码符号、稳定 ID、结构化元数据、无歧义引用。

由此推出的强制规则：

1. 每篇文档必须带 YAML frontmatter（doc-type / layer / doc-class / status / owner 等），供机器检索与路由。
2. 引用必须精确：写 src/services/auth/token.ts，不写"认证模块那边"；写 ADR-0007，不写"之前那个决策"。
3. 需求、决策、任务必须带稳定 ID（FR-xxx、ADR-NNNN），供跨文档追踪。
4. 叙事段落面向人类，结构化区块（表格、清单、frontmatter）面向机器；同一信息不得只以一种形式存在关键事实。
5. 禁止"见上文/如前所述"式引用——使用锚点、ID 或链接。
6. 文档中的技术事实（路径、接口、配置）会被 AI 字面执行，错误的技术事实比缺失更危险。

核心理念二：三层记录模型

所有工程文档按记录目的分为三层，层决定文档的生命周期、更新频率与质量标准。

关键机制——层间流动：

• 过程层产出必须向项目层/知识层沉淀：RETRO 的结论 → ADR（新决策）/ ROADMAP（新计划）/ TECH（新知识）；PROGRESS 中反复出现的手工操作 → RUNBOOK。
• 项目层向知识层沉淀：某个方案解决过程被抽象、去项目化后 → TECH。
• 禁止反向：知识层/项目层文档不得写成流水账（那是过程层的事）。

详见 references/three-layer-model.md。

核心理念三：现状文档与规范文档强制区分

每篇文档必须在 frontmatter 中用 doc-class 声明其性质：

• as-is（现状文档）：描述当前实际存在的系统/流程/事实。必须与现实一致，漂移即缺陷。DESIGN（实现后）、RUNBOOK、TECH、PERSONA。
• to-be（规范文档）：规定应当达到的目标、标准与计划。PRD、ROADMAP、规范类 DESIGN（实现前）。
• history（历史记录）：不可变的过程快照。ADR、PROGRESS、RETRO。

强制规则：

1. 同一章节内禁止混写现状与目标——"系统目前…"与"系统应当…"必须分节。
2. 现状文档中的技术事实必须可验证、可核对（评审专家负责交叉验证）。
3. 规范落地后，对应文档状态必须迁移（如 DESIGN 从 to-be 转 as-is；ROADMAP 待办移入当前迭代）。
4. ADR 是历史记录：它记录"当时的决策"，不代表当前约束；当前有效约束 = 全部 accepted/deprecated 状态 ADR 的聚合。

详见 references/as-is-vs-to-be.md。

核心理念四：五类核心文档 + 知识笔记

本体系的文档类型标准为五类核心 + TECH 知识笔记，辅以三种支撑文档：

各类型的完整定义、受众、质量标准与触发时机见 references/core-doc-types.md。模板与编写规范在 ../doc-writer/templates/。

通用文档规则（所有角色必须遵守）

1. frontmatter 必填：doc-type、layer、doc-class、status、owner；现状类另加 last-verified。
2. 命名规范：ADR 用 NNNN-kebab-title.md 递增编号；PROGRESS/RETRO 用 YYYY-iterN.md；其余用全大写类型名或 kebab-case。
3. 单一职责：一篇文档回答一个核心问题；ADR 一决策一篇；TECH 一主题一篇。
4. 可追踪：跨文档引用一律用稳定 ID + 相对链接；每篇文档可在 docs 索引中被找到。
5. 诚实原则：不确定的事实标注 TODO(验证)，不编造；过时内容归档或删除，不保留"文档坟场"。

使用流程（总指挥视角）

1. 接收任务 → 按「调度协议·第一步」分类；单意图直接派发对应子技能。
2. 复合任务 → 按「第二步」编排流水线，逐个子任务派发并串联产出。
3. 涉及类型选择/分层/as-is 归属争议时，先读 references/core-doc-types.md、references/three-layer-model.md、references/as-is-vs-to-be.md 由本技能裁定。
4. 子技能返回 → 按「第四步」闭环验收，未通过则按报告继续派发修复，通过后任务关闭。