---
name: living-docs-governance
description: >-
  把长期项目的文档当成一个小系统来维护，防止文档腐烂——四份各司其职的脊柱文件（CLAUDE.md 共享章程 / CLAUDE_MAP.md 地图 / PROJECT_STATUS.md 健康仪表盘 / PROJECT_LOG.md 流水账）+ Codex 的 AGENTS.md 入口桥接 + 固定读序，并按需连接 ARCHITECTURE、CONTEXT、ADR、契约、测试、回归和 Issue Tracker。用于治理初始化、只读审计、阶段同步、LOG 复盘与超过 200 条事件后的归档索引。中文触发：文档治理、活文档、防文档漂移、治理初始化、治理审计、治理同步、治理复盘、AGENTS.md、项目状态追踪、项目地图、架构图、模块流转图、健康仪表盘、流水账、日志归档、长期项目治理。English triggers: living documentation, docs governance, governance init, governance audit, governance sync, governance retrospective, AGENTS.md bridge, architecture document, module flow diagram, prevent doc rot, project status dashboard, project map, append-only changelog, project log archive.
metadata:
  origin: ECC
---

# 活文档治理（Living Docs Governance）

长期项目最先腐烂的是文档层：README 在撒谎、架构笔记描述着一次从没上线的重构、每次进会话 agent 都在重新推导本该一读就懂的上下文。**活文档治理**把项目文档当成一个小的、各司其职的**系统**，而不是一堆散文件：四份互相链接的文档，每份只干一件事，外加一个 agent 进会话时读它们的固定顺序。

本技能覆盖**首次 setup 与后续维护**。setup 把真实项目资料接成可维护的文档入口；维护让它在几个月的改动后依然为真。只想了解陌生代码库、不准备配置文档时，用代码库 onboarding 类技能。

> 在 Claude Code 中，可由配套的 `docs-governor` / `docs-auditor` agent 执行；在 Codex 或没有这些自定义 agent 的宿主中，由当前 agent 直接按本 skill 执行，必要时再使用宿主提供的只读探索或执行型子 agent。本 skill 始终是方法论唯一来源。

## 什么时候启用

满足任一条就启用：

- 项目长过几个模块，文档开始和代码漂移。
- agent 或队友在会话之间丢失上下文，反复重新发现同一套结构。
- 没人能从单一位置回答"这项目现在健康度如何？""上周改了啥？"。
- 死文件和废弃实验堆积，偶尔被误重建。
- 你想给一个单人/小团队项目一层耐用、低开销的治理，又不想上大型多人仓库那套重 CI 机器。

**不要**在用完即弃的脚本、或活不过这周的仓库上用——那是过度治理。

## 渐进式采用：从最小开始，但提前看到下一级

别一上来铺满四件套——那本身就是过度治理。从最小起步，**真正关键的不是"按需补"，是提前认出"下一级快需要了"的预警信号**，在它真痛之前就备好。等漂移出事（STATUS 撒谎、重建已删文件）才补，文档已经烂了一轮、返工已经发生——治理的价值在防患，不在救火。

| 当前规模 | 该有 | 下一级的预警信号（看到就准备上） |
|---|---|---|
| 单文件 / 用完即弃 | 什么都不用 | —— |
| 长过几个模块、要维护一阵 | **CLAUDE.md**（几条硬规则 + 路标） | 开始有人问"这项目现在健康吗" → 备 STATUS |
| 有健康 / 风险 / 待删要追 | + **PROJECT_STATUS.md** | AI/新人开始"找不到某功能""改错地方" → 备 MAP |
| 找东西 / 跨 Module 改开始费劲 | + **CLAUDE_MAP.md** | Module 权责、状态归属、依赖或主流程开始说不清 → 备 ARCHITECTURE |
| Module 架构需要共享 | + **ARCHITECTURE.md**（可选血肉） | 反复问“为什么这样设计” → 备 ADR；要追历史 → 备 LOG |
| 要追溯决策与历史 | + **PROJECT_LOG.md**（四件套齐） | 分出前后端、接口字段对不上 → 备 CONTRACT |
| 分前后端 / 多服务 | + **CONTRACT.md**（见 `contract-first`） | —— |

预警信号的意义：让你在**痛之前**上对应那一级，而不是等它腐烂出事再救火。

## 团队共享 vs 个人：治理文件放哪一层

四件套是**项目级、团队共享**的——进 git，所有协作者 / agent 共用，写的是"团队共识的真相"。**个人临时偏好别塞进去**（会污染团队视图）：那些放 `CLAUDE.local.md`（同目录、不提交）或 `~/.claude/`（全局个人）。判据一句话：**帮整个团队一致 → 进项目四件套；只是你一个人的习惯 → 进 `.local` / 全局。**

## 怎么运作

这套系统 = **四份脊柱文档**（角色严格分离）+ **分级读取协议** + 让它们保持最新的**更新规则** + 阶段收尾时的**查漏补缺矩阵**。`CONTEXT.md`、`docs/adr/`、契约、测试和回归台账都是按真实需要长出的血肉，不是第五到第九份必建脊柱。

本文以插件现有的 CLAUDE 主源布局说明文档角色；项目若已有 AGENTS 主源，沿用其约定。入口具体写什么、依据什么事实生成、如何精简与检查，统一执行 `skills/documentation/agent-entrypoints/SKILL.md`；本文继续负责其他载体及读序。审计脚本和模板仍有 CLAUDE 默认布局，采用不同布局时按目标项目核对适配，不自动迁移规则主源。

### Claude Code / Codex 入口适配

两端共用本 skill，不复制方法论：

| 用户意图 | Claude Code 入口 | Codex / ChatGPT 入口 | 详细执行流程 |
|---|---|---|---|
| 新项目、讨论后项目或已有项目首次配置 | `/governance-setup`（`/governance-init` 为兼容别名） | `$living-docs-governance` + “setup 当前项目” | 本文“统一 setup”执行模式 |
| 已有项目治理 | `/governance` | `$living-docs-governance` + “治理当前项目” | 本文“已有项目治理”执行模式 |
| 只读审计 | `/governance-audit` | `$living-docs-governance` + “只读审计” | 本文“只读审计”执行模式 |
| 阶段同步 | `/governance-sync` | `$living-docs-governance` + “阶段收尾同步” | 本文“阶段同步”执行模式 |
| LOG 复盘 | `/governance-retro` | `$living-docs-governance` + “复盘 PROJECT_LOG” | 本文“日志复盘”执行模式 |

所有宿主直接执行本文对应模式。Claude commands/agents 只选择模式和执行角色；Codex / ChatGPT 由当前 agent 执行，不反向读取 commands/agents。只读审计、只读复盘保持只读。

审计支持 `spine`、`context`、`adr`、`artifacts`、`full` 五种范围。先运行 `scripts/audit-cheap.sh <scope>` 做确定性检查；断链失败就短路，只有通过后才进入语义判断。默认只读；只有用户明确要求保存时，才把报告写入 `docs/audits/YYYY-MM-DD-*.md`。

### 四份文档与各自的职责

| 文档 | 唯一职责 | 该放什么 | 绝不能放什么 |
|---|---|---|---|
| `CLAUDE.md` | 宪法：永远生效的硬规则和路标 | 不可妥协的约定、读序、指向其他文档的路标 | 长篇解释（链接出去）、实时状态、历史 |
| `CLAUDE_MAP.md` | 地图：只记**文件树看不出来**的导航语义 | 非显然定位跳转表、架构/决策/契约等知识入口、"树真实但误导"清单（废弃/生成物/兼容目录）、别动区 | 目录树镜像（`ls` 就有）、Module 权责与流程图（属 ARCHITECTURE）、接口字段细节（属 CONTRACT/代码 Interface）、健康指标（属 STATUS）、历史（属 LOG） |
| `PROJECT_STATUS.md` | 健康仪表盘：当前状态一眼看清 | 指标对阈值、删除区（故意删掉别重建的文件）、未决违规、P0 行动 | 项目是什么（属 MAP）、发生了什么的叙事（属 LOG） |
| `PROJECT_LOG.md` | 流水账：只追加的历史 | 每件有意义的事一行（`## [日期] 类型 \| 摘要`），新条目追加到底 | 当前状态（属 STATUS）、结构（属 MAP）；永不改/删旧行 |

让它生效的纪律是**非重叠**：每个事实只有一个权威来源，其他载体只引用。"auth 模块在哪？"→ 地图。"覆盖率现在健康吗？"→ STATUS。"旧解析器啥时候删的、为啥？"→ LOG。每份只干一件事，就不会一起烂。

事实按类型认来源：规则、决策与历史由相应文档维护，接口字段由唯一机器契约定义；测试与审查结论引用实际运行的版本、范围、结果和证据位置。项目已有工程 Skill 继续负责代码审查，治理层只核对与引用其证据。STATUS 保存带来源的健康快照，相关实现或验收条件变化后标待复验，不把旧绿色结果延续为当前结论；无法确认版本或范围时明确写未验证。

### 可选文档与排期

- 需要判断项目是否应建立架构文档，或生成、完善、审查现有架构说明 → `skills/documentation/architecture-docs/SKILL.md`；返回必要性、依据和主记录位置。
- 稳定领域术语、概念关系和歧义反复影响协作时，才创建根目录 `CONTEXT.md`；它不写实现、状态、任务、需求全文或决策。具体边界见 `context-and-decisions`。
- 出现架构、数据库、认证、部署、数据模型或 API 版本等难回退决策时，才创建 `docs/adr/README.md` 和一项决策一个 ADR 文件。MAP 只指向 ADR 索引，不枚举所有决策。
- 任务、负责人、阻塞和项目排期由 GitHub Issues、Linear 或项目已有 Tracker 管理；没有外部 Tracker 时再采用本地 `.scratch/`。`PROJECT_STATUS.md` 只保留当前健康快照，不承担排期。

### 分级读取协议（按需读，但红线常驻）

不要每次进会话把四份全量灌进上下文——那是把"文档存在"当成"此刻相关"。读取按**分级**，判别只有一句话：**需求会不会自己报到？**

- **会自己报到的**（bug 跳出来、要定位某文件、要查健康度）→ 触发时才读，按需。
- **不会报到、却会悄悄咬人的**（你正要重建一个故意删掉的文件，没任何信号提醒你）→ 必须常驻，不能等触发。

按这个分，四份文档各自的读取策略：

| 文档 | 进会话默认读 | 何时读完整 |
|---|---|---|
| `CLAUDE.md` | **全文必读**（小、是规则，违章无信号） | —— |
| `PROJECT_STATUS.md` | **只读顶部红线块**：删除区 + 未决 P0/违规（几行；危险不报到） | 需要看健康度/指标时，读其余部分 |
| `CLAUDE_MAP.md` | **默认不读**（它只记树里看不出来的导航、误导清单和别动区；目录树本身按需 `ls`） | 找不到东西、要跨 Module 改、**新建/删/重命名文件前**，读它 |
| `ARCHITECTURE.md`（若存在） | **默认不读** | 要理解整体结构、改变 Module 权责/状态/Interface/依赖/核心流转，或做跨 Module 设计时，读它 |
| `PROJECT_LOG.md` | **不读**（transcript） | 排查 bug、追溯"为什么删 / 为什么这么做"时，`grep` 或读尾部 |

使用 Codex 或多个宿主时，由 `agent-entrypoints` 确定实际入口与共享主源，并挂上本文的分级读取路标。项目以 CLAUDE 为主源时才使用 `templates/AGENTS.example.md` 薄桥接；已有完整 AGENTS 主源时保留正文，不套桥接模板覆盖。

常驻成本压到最小：CLAUDE 全文 + STATUS 红线几行。大头（完整 MAP、ARCHITECTURE、STATUS 指标、整本 LOG）全按需。LOG 之外的当前真相载体是 **projection**（决定此刻喂什么），LOG 是 **transcript**（记录发生了什么）。

**两条护栏（防"该读没读"——这是按需读唯一的真风险）：**

1. **不确定就升级全读。** 拿不准这次要不要读完整 MAP/STATUS → **默认读全**，不要为省 token 赌一把。省 token 是小钱；在过期地图上铺代码、重建已删文件是大坑。
2. **动手改文件前必读，不只是进会话时。** 真正的危险不在进会话，在你准备**新建 / 删除 / 重命名文件、跨目录改动**那一刻——这些操作**强制**先读完整 `CLAUDE_MAP.md` 对应段 + `PROJECT_STATUS.md` 删除区，确认没踩禁区、没复活已删文件。

> **LOG 防腐：按事件计数 + 复盘 + 可重建索引。** `PROJECT_LOG.md` 的事件格式是 `## [日期] 类型 | 摘要`；阈值按事件数计算，不按原始行数。活跃事件不超过 200 条时只用 Markdown；超过 200 条后：
> 1. **先只读复盘**：识别重复问题和应下沉的 lint / TEST-ID / 回归保护。
> 2. **经用户确认再归档**：运行 `python3 <插件目录>/scripts/project-log-index.py archive --root <项目根> --yes`。旧事件原样进入 `PROJECT_LOG.archive.md`，活跃 LOG 默认保留最近 100 条；归档是受控压缩例外，不得手工删改历史。
> 3. **建立派生索引**：脚本从活跃 LOG + archive 重建 `.governance/project-log.sqlite`。数据库默认进 `.gitignore`，不是唯一事实源；损坏或删除后运行 `rebuild` 即可恢复。
> 4. **分类不猜**：类型取事件头；模块只在明确写出或能从真实路径解析时登记，否则为 `unclassified`；引用只提取 commit、TEST-ID、ADR、CONTRACT 和明确路径。内容哈希保证幂等。
> 5. **失败不伤原文**：解析、归档或建库失败时，不得留下被截断的 `PROJECT_LOG.md`。审计以活跃文件和 archive 的事件合集判断只追加完整性。
> 6. **目录 + 内容分层**：主 LOG 只当**目录**——每条一行（`## [日期] 类型 | 一句话`），需要长详情（完整审计报告、大段修复记录）时下沉到独立文件（如 `docs/log-details/2026-07-03-audit.md`），目录行尾挂链接。主 LOG 永远短、可整读；详情按需点开。这就是「脊柱保持瘦、血肉下沉」用在 LOG 自己身上。
> 7. **复盘统计**（LOG 不只是负担，是资产）：归档前跑一次 `/governance-retro`，统计哪个模块出错最多、哪类错误重复出现、标准变更了几次——**重复 TOP 的错误 = "该下沉成 lint / 回归测试"的候选清单**（见 `module-regression` 铁律"坑必下沉"）。同一个坑在 LOG 里出现第二次，说明它还没被机器接管。

### 防腐烂的更新规则

- 改了路径、入口、知识载体或误导区 → **同一次改动**里更新 `CLAUDE_MAP.md`。
- 模块分工、状态、接口、依赖或核心流程变化 → 同次按 `architecture-docs` 核对受影响的架构记录。
- 指标越过阈值，或你故意删了某文件 → 更新 `PROJECT_STATUS.md`，并把路径加进删除区，免得被重建。
- 有意义的变更、决策或验证结果 → 往 `PROJECT_LOG.md` 追加一行，说明结果与必要理由；写入前按阶段归纳，不为重复读取、重试或相同结论另写流水账。已有提交护栏仍按项目约定执行。
- `AGENTS.md` / `CLAUDE.md` 的长度与精简按 `agent-entrypoints` 第 1 条执行，每份不超过 200 行；关键约束留在入口，细节下沉并保留路标。
- **标准变更留痕**：任何验收阈值 / 联动规则 / 契约字段的修改（如 `<0.01` 放宽到 `<0.1`、REGRESSION 联动规则改松），必须在 `PROJECT_LOG.md` 追加一条「标准变更：旧值 → 新值 + 理由」。审计时对照 Git 历史检查标准变化和对应记录；缺失时报告具体变化、可能影响和待补依据，按下述规则分级，不直接认定为 P0。

### 风险分级与维护成本

- 优先沿用项目已定义的严重级别。未定义时，P0 用于有证据表明必须立即阻止的严重损害（如正在发生的数据丢失或越权）；P1 用于已确认会误导实现或阻塞关键路径、需要优先修复的问题；P2 用于一般维护改进。证据不足时标“待核实”，写清可能影响和缺少的证据。
- 覆盖率、测试数量、审计间隔和一般文档行数是检查线索，阈值由项目约束决定；Agent 入口另有 `agent-entrypoints` 的 200 行硬验收，不能降为建议。越线不凭单一数值自动定为 P0，严重级别仍看实际影响；普通验证缺口和维护建议放按需读取区，任务安排仍归 Issue Tracker。
- 只更新本次变更实际影响的文档。业务项目试点时，可在现有审计或复盘记录中观察接手耗时、重复解释、提前发现的问题和文档维护成本；没有测量就标未知，不另建一套指标台账。

### 阶段收尾同步

当用户说"同步一下"、"整理文档"、"收尾"、"这个阶段做完了"、"新人能接手"，或运行 `/governance-sync` 时，不要只追加 `PROJECT_LOG.md`。先按 `references/governance-sync-matrix.md` 判断本次变化应该影响哪份治理文档：

- 路径、入口、知识载体、误导区、跳转表 → `CLAUDE_MAP.md`
- Module 权责、状态归属、Interface、代码依赖方向、核心流转 → `ARCHITECTURE.md`（若已启用或已达到启用条件）
- 风险、测试缺口、指标、待删区 → `PROJECT_STATUS.md`
- 长期硬规则、读序、不可妥协约定 → `CLAUDE.md`
- 重要历史事件 → `PROJECT_LOG.md`（只追加）
- 前后端接口字段 → `CONTRACT.md`（若项目有契约治理）
- 领域术语或关系变化 → `CONTEXT.md`（若存在且证据已确认）
- 难回退技术决策 → `docs/adr/`（若触发 ADR）
- 产品十阶段产物、PRD 基线、需求评审和运营反馈 → `product-evolution`；复用 docs 下产品入口，任务状态留在 Tracker

关键区别：`PROJECT_LOG.md` 是记录员，只追加历史；`CLAUDE_MAP.md` / `ARCHITECTURE.md` / `PROJECT_STATUS.md` / `CLAUDE.md` 是编辑过的当前真相，发现旧事实过期要修正、合并或删除。

## 文档角色分层（管 4 件套之外的全部文档）

四件套是**脊柱**，但真实项目还有规范、设计记录、参考、审计产物等一大堆**血肉**文档。治理纪律（一文一职、非重叠、按需读、防漂移）对全体文档都适用，不止四份。给任意一份文档定位，用**一条判据 + 三条纪律**。

### 判据：一份文档属于哪层 = 它回答 AI 的哪个问题

| 它回答 | 角色 | 谁来当 |
|---|---|---|
| 该遵守什么（永久铁律） | 宪法 | `CLAUDE.md`（脊柱） |
| 在哪找、树看不出的语义 | 地图 | `CLAUDE_MAP.md`（脊柱） |
| 当前 Module 怎么分工、怎样依赖和流转 | 架构 | `ARCHITECTURE.md`（按需血肉） |
| 现在健康吗、啥是禁区 | 仪表盘 | `PROJECT_STATUS.md`（脊柱） |
| 发生过什么 | 流水账 | `PROJECT_LOG.md`（脊柱） |
| 要做什么 / 怎么做 | 规范 | spec / plan / 模块规则 |
| 为什么这么做 | 决策 / 修复记录 | `docs/adr/` / FIX- / CHECK- |
| 照着抄的真相 | 参考 / 契约 | 数据源图 / `CONTRACT.md` / references |
| 某次结果 | 产物 / 审计 | 带日期的审计或报告 |
| 过期但留着 | 归档 | `*/archive/` |

前 4 行是**脊柱（固定 4 份，每次进会话相关）**，后面是**血肉（按项目长，不限层数）**。判据是"它回答哪个问题"，不是"必须凑成 N 层"。

### 三条管理纪律

1. **一文一职**：一份只回答一个问题，回答俩就拆。（把"非重叠"从 4 份扩到全体文档）
2. **可达性（防孤儿）**：每份血肉必须能从脊柱顺着指路牌走到——脊柱是入口树的根。走不到的 = 孤儿文档，要么挂链接、要么归档。**没人指向 = 没人读 = 必烂。**
3. **脊柱保持瘦（防漏）**：脊柱只放「索引 + 指路牌 + 不读会悄悄出事的红线」。任何细节 / 历史 / 产物，**脊柱里只留一行链接，正文下沉到对应层**。

## 模板

四份文档的可直接套用模板在 `templates/` 下，按项目实情填括号/示例部分：

- `templates/CLAUDE.example.md`
- `templates/CLAUDE_MAP.example.md`
- `templates/ARCHITECTURE.example.md`（多个长期 Module 且架构不再直观时才用）
- `templates/PROJECT_STATUS.example.md`
- `templates/PROJECT_LOG.example.md`
- `templates/context.example.md`（稳定领域语言出现时才用）
- `templates/adr-index.example.md` / `templates/adr.example.md`（难回退决策出现时才用）

## PROJECT_STATUS 示例

按 `templates/PROJECT_STATUS.example.md` 填写实际指标、风险影响和删除理由；模板示例不代表项目已发生对应问题或必须采用其数值。

## 例子

- **文档和代码漂移了**：一个半年前的数据工具，README 还在描述 v1 管线。采用四件套后，MAP 指向当前结构入口，ARCHITECTURE 写出真实 Module 布局，STATUS 标记 README 过期；此后路径变化更新 MAP，Module 结构变化更新 ARCHITECTURE。
- **agent 反复丢上下文**：每次进会话都重新 grep 学布局。采用读序后，会话开头四次短读重建上下文，不再重复发现。
- **删掉的文件老回来**：一个死的 `legacy_parser.py` 被删两次、重建两次。把它记进 STATUS 删除区（连同原因和替代物），循环就断了。

## 相关

- `docs-governor` agent —— 照本方法论去扫项目、生成/更新四件套的执行者。
- `docs-auditor` agent —— 照本方法论只读审计四件套是否漂移、重复、虚构路径或指标未验证。
- `references/governance-sync-matrix.md` —— 阶段收尾时判断"本次变化应同步哪份治理文档"的影响矩阵。
- `contract-first` skill —— 当项目分前后端两层、需要防接口字段漂移时，那套契约方法论的姊妹篇。
- `context-and-decisions` skill —— 管稳定领域语言与架构/数据库等难回退决策。
- `change-impact` skill —— 修改前收集影响证据，实施后对照实际 diff、验证与文档同步。


## 共享执行模式

以下流程是两端共用的唯一执行规则；命令参数由宿主适配层转成模式、范围、日期或本阶段说明。

### 统一 setup

为新项目、已讨论项目和已有代码项目配置产品文档包与 Agent 入口，不实现业务功能。Claude Code 由 `docs-governor` 编排，Codex / ChatGPT 由当前 Agent 编排；按下面顺序读取并执行专项 Skill，不复制其方法论。旧“空项目初始化”“已有项目首次接入”都进入本模式；日常维护走下一节。

1. **只读识别项目。** 定位目标根与 Git 边界，读取现有规则主源、文档入口、已确认讨论及 PRD／Spec、代码与包配置、验证命令、Tracker、hooks／CI 和治理配置。先核对已有资料，再判断场景：

   | 场景 | 配置依据与结果 |
   |---|---|
   | 从零开始，尚无已确认规格 | 用用户已给的目标、对象与约束建立产品草稿；缺失的目标或范围影响建档时才问，未知技术栈、方案和命令明确待定 |
   | 已讨论或已有 PRD／Spec，尚未实现 | 复用已确认来源与验收条件，登记生效范围和未决项；不重新发明需求，不将计划标为已实现 |
   | 已有代码／文档 | 将现有产品资料、实现与验证证据映射进文档包；保留原路径与主源，冲突标待核实，不用代码现状反向批准需求 |

2. **确认文件范围。** 给出“保留”“新增／更新”“不创建”清单，注明每项职责、依据和验证方式。复用用户对同一对象与范围的明确授权；尚未授权的文件先确认，部分批准就只做该部分。“看看怎么接入”保持只读。setup 本身不授权 Git 初始化、提交、推送、依赖安装或 hooks／位置护栏配置。
3. **产品文档先行。** 将目标根、来源、确认范围、现有主记录和获准文件清单交给 `skills/documentation/product-evolution/SKILL.md`。完整 setup 建立或补齐产品入口、十阶段导航、PRD／Spec 基线与来源关系；已有阶段材料只映射，不复制。新阶段写真实状态和待补问题，不输出空模板或虚构调研／验收。该步骤返回实际路径、修订、未决项；入口写入与最终审计交回编排者。只批准入口配置时跳过产品写入并说明边界。
4. **按需补治理载体，再配置入口。** 按本文渐进条件与授权补充 MAP、STATUS、LOG 等载体，不预建空目录或整套四件套。将真实项目事实、验证入口、保留的规则和已存在的产品／治理路径交给 `skills/documentation/agent-entrypoints/SKILL.md`，维护共享主文件及所需宿主桥接；采用本插件开发流程时，由该 Skill 接入总路由的“模块变更流程”指针。已有主源不能改成空桥接。专项 Skill 不可用时报告该步未完成，不用临时复制的方法论冒充调用成功。
5. **验证并交接。** 对实际写入的每份入口执行 `agent-entrypoints` 的检查；运行 `python3 <插件目录>/scripts/audit-docs.py --root <目标根> --scope full`。非零先处理，布局不受检查器支持时报告限制，不为消警报造空文件。安全且在授权内的项目验证按真实命令运行，未运行就标未验证。交付项目场景、复用／增改文件、PRD／Spec 与十阶段入口、实际验证结果和待决项；仅部分配置不能称完整 setup。重复运行应复用既有来源、编号和路径，不增建另一套文档。未实测宿主加载时不声称 slash command 或 hook 端到端通过。

专项调用只处理传入范围后返回，不递归启动 setup。可选 hooks 仅在明确授权后安装：检查 `core.hooksPath`，否则用 `git rev-parse --git-path hooks/pre-commit` 定位，尊重 worktree 和既有 hook；不得覆盖已有脚本。

### 已有项目治理

尚未建立文档体系时执行“统一 setup”；已有体系的日常更新转交 `skills/documentation/docs-maintenance/SKILL.md`，传递项目根、任务范围、实际 base/head、读写权限与已有证据。只读请求转“只读审计”；日志归档仍按本文日志管理执行。

### 只读审计

默认范围 full；支持 spine/context/adr/artifacts。先执行 `bash <插件目录>/scripts/audit-cheap.sh <范围>`，任何非零退出码都先报告并短路；只有通过后进入语义审计。指定对象时在选定范围内重点核对，仍保持只读。

日志默认比较工作区与 HEAD。审查已提交变更时必须指定原始基线：`python3 <插件目录>/scripts/audit-docs.py --root <项目根> --scope full --base-ref <基线提交>`；Shell 入口可用 `DOCS_GOVERNANCE_BASE_REF`。PR 使用目标分支基线，push 使用推送前提交。显式基准不可解析时失败；无 Git 历史时标未验证。

工具需要复用结果时加 `--format json`，读取 `references/audit-result-format.md`。同一检查结果可渲染为文字或 JSON；按 `check`、`status`、`evidence` 读取，不解析中文提示。退出码 1 表示已发现文档问题，2 表示检查未完成；0 仍可能包含警告或未验证项，继续按覆盖范围做语义核对。

可选的代码路径引用按行声明：`<!-- governance: optional=CONTEXT.md,ARCHITECTURE.md -->`。只豁免列出的路径尚不存在，不豁免文件已存在后的内容检查。活动文件和普通 Markdown 链接不得用可选标记隐藏断链。删除区使用标题以“删除区”开头的章节；表格第一列为已删路径，替代物放后续列；列表每行只列一个删除目标。

语义层按范围检查：

- 四件套是否各司其职、是否重复或矛盾；MAP 是否复制架构或目录树，STATUS 指标是否实际量过，LOG 是否只承担历史。AGENTS / CLAUDE 的内容、主源、加载与可执行性按 `agent-entrypoints` 只读检查。
- 架构说明按 `architecture-docs` 只读审查；README、过期文档、误导目录与当前代码冲突时报告。
- CONTEXT 是否只管稳定领域语言；必要时读 `context-and-decisions` 检查 accepted ADR 冲突、替代关系、理由、后果和退出路径。
- 契约存在时读 `contract-first`：检查唯一机器来源、消费方与提供方证据、版本与真实序列化结果，不把手写字段表或内部类型检查当联调。
- 依同步矩阵查漏；活跃 Spec/Issue 的成功标准是否连到实现、TEST-ID/人工出口和交付证据，归档内容是否仍被误当当前依据。Issue Tracker 不可访问时，任务状态与排期标未验证。
- 检查全部文档可达性与职责下沉；确定性孤儿提示只是候选，不能证明从脊柱可达。TEST-ID 字符串出现不等于必要测试点已有完整证据。
- 存在 `.claude/` 时检查死配置、模糊命名、个人偏好混入团队、空目录及规则过载。针对具体变更时执行 `skills/engineering/change-impact/SKILL.md` 的“按事实核对文档”，并检查超范围改动、迁移尾项和遗留临时代码。

输出总体可信度、P0/P1/P2 发现、具体证据、影响、建议、通过项及待人工确认项。未测量不背书，建议不写成已修复。默认在回复输出，用户要求保存时才写审计报告。

### 阶段同步

执行 `skills/documentation/docs-maintenance/SKILL.md`，传递项目根、阶段说明、实际 base/head、读写权限和已有证据；由它同步主记录、验证并说明剩余差异。只读请求不写文件。

采用 PR 护栏的项目仍须在创建或更新 PR 前运行 `scripts/check-pr-docs.py --base <实际目标分支>`；非零先修复。安装与参数见 `references/document-policy.md`。

### 日志复盘

默认只读全量；指定起始日期时仅统计该日期起的事件。先运行 `project-log-index.py status --root <项目根>`，再读活跃 LOG；全量模式存在 archive 时一并读。索引可辅助查询，证据必须能回到 Markdown；LOG 不存在时报告缺失。

按真实类型和明确路径统计模块 fix 热点前五、出现至少两次的错误类型、标准变更的旧值/新值/理由和审计间隔；对照期间 commit 数，不凭目录名猜模块。连续放宽标准要提示；重复错误提出回归测试/lint/schema 的下沉候选，并关联 `test-collaboration`。

输出分布、重复错误、标准审查和候选清单。修复、补测及经确认归档是后续写入动作，不混入只读复盘；不把任务排期写入 SQLite。