活文档治理（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/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 保存带来源的健康快照，相关实现或验收条件变化后标待复验，不把旧绿色结果延续为当前结论；无法确认版本或范围时明确写未验证。

ARCHITECTURE.md 的 Module 架构契约（按需）

当项目已经出现多个长期 Module，并开始发生跨 Module 修改、状态互相改写或依赖方向说不清时，按 templates/ARCHITECTURE.example.md 创建根目录 ARCHITECTURE.md，让它成为当前架构的唯一说明入口。CLAUDE_MAP.md 只留一行链接，不复制表格或图。ARCHITECTURE 回答六件事：

1. Module 权责：每个关键 Module 只用一句话说明唯一职责；能从文件名和文件头稳定推出的普通目录不要逐项登记。
2. 状态归属：共享可变状态只指定一个主要拥有者；其他 Module 必须通过它的 Interface 请求读写，不能越过 Interface 直接修改实现细节。
3. Interface 与 Seam：只写调用方必须知道的 Interface 名称、入口和约束载体；字段、错误码、枚举等细节继续留在 CONTRACT.md、代码 Interface 或专门规格中，ARCHITECTURE 只挂链接，避免双源真相。
4. 依赖方向：用一张小型 Mermaid 图或一行规则表示允许的代码依赖，并明确禁止的反向依赖。依赖图的箭头必须始终表示“源代码依赖目标”，每条边都应有 import、调用、注册或配置证据。
5. 核心流转：仅当运行时消息/数据链路不直观时，再画一到三条主链路。流转图必须标明箭头表示运行时数据或事件，不能拿它代替依赖图；数据可以往返，代码依赖仍可保持单向。
6. Adapter 关系：只有确实存在多个实现或明确替换点时，才标出 Interface 后面的 Adapter；不要为了图看起来完整而制造没有消费者的假 Seam。

判断一个 Module 是否清楚，依次问：它只负责什么、拥有什么状态、向外暴露哪个 Interface、允许依赖谁、禁止谁绕过 Interface。内部实现改变而 Interface 不变时，调用方原则上不应跟着修改——这就是架构图要保护的局部性。

生成或更新时必须先读真实代码，不能凭目录名猜：

• 权责、状态拥有者或依赖证据不足 → 标“未验证”或暂不落图，不编造完整架构。
• 小项目、单文件工具、只有两个直观目录 → 不创建 ARCHITECTURE.md，保留最小 MAP。
• ARCHITECTURE 开始过长 → 拆出下级架构文档，但根 ARCHITECTURE.md 仍保留总图和索引；不要把细节塞回 MAP。
• 审计时抽查表格、两类箭头和真实代码是否一致；发现跨层直连、状态多头修改、绕过 Interface 或已删除 Module 仍留在图里，按漂移报告。

可选架构、上下文、决策与排期

• Module 权责、状态归属、代码依赖方向或核心流转开始需要团队共享时，才创建根目录 ARCHITECTURE.md；它只记录当前结构，不记录选择理由、Interface 字段、任务或历史。MAP 只指向它。
• 稳定领域术语、概念关系和歧义反复影响协作时，才创建根目录 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。
• 改了 Module 权责、状态归属、Interface、代码依赖方向或核心流转 → 同一次改动里更新 ARCHITECTURE.md（若已启用）；若尚未启用但跨 Module 结构已不直观，按模板创建并从 MAP 挂入口。
• 指标越过阈值，或你故意删了某文件 → 更新 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/product-evolution/SKILL.md。完整 setup 建立或补齐产品入口、十阶段导航、PRD／Spec 基线与来源关系；已有阶段材料只映射，不复制。新阶段写真实状态和待补问题，不输出空模板或虚构调研／验收。该步骤返回实际路径、修订、未决项；入口写入与最终审计交回编排者。只批准入口配置时跳过产品写入并说明边界。

4. 按需补治理载体，再配置入口。 按本文渐进条件与授权补充 MAP、STATUS、LOG 等载体，不预建空目录或整套四件套。将真实项目事实、验证入口、保留的规则和已存在的产品／治理路径交给 skills/agent-entrypoints/SKILL.md，维护共享主文件及所需宿主桥接；已有主源不能改成空桥接。专项 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 后，先按分级读序侦察真实入口、模块、测试、依赖和现有文档；按渐进采用条件选择载体，不因文件缺失就补齐四件套。尚未配置且需要先确定写入范围时，转到“统一 setup”。
• 当前真相增量编辑，LOG 只追加；Module 架构达到条件才创建 ARCHITECTURE 并从 MAP 挂入口。其余可选载体按本文职责路由。
• 项目使用 Codex 或已有 AGENTS 时，按 agent-entrypoints 维护实际入口与共享主源。指定子目录时只更新对应导航与健康；log: 一句话 模式只追加一个标准格式事件。
• 未配置 pre-commit 时，提出是否采用模板护栏；用户已授权则安装。遵循“统一 setup”中的真实 hook 路径与不覆盖约束。
• 收尾按同步矩阵核对职责、路径、已测指标和文档长度；运行日志 status。超过阈值先建议复盘，未经确认不归档。
• 报告实际增改文件、证据、验证结果与待确认项，不把占位符或未验证指标写成已完成事实。

只读审计

默认范围 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 的权责、状态归属、代码依赖和运行时流转是否有真实 import/调用/注册/状态写入证据；证据不足标未验证。README、过期文档、误导目录与当前代码冲突时报告。
• CONTEXT 是否只管稳定领域语言；必要时读 context-and-decisions 检查 accepted ADR 冲突、替代关系、理由、后果和退出路径。
• 契约存在时读 contract-first：检查唯一机器来源、消费方与提供方证据、版本与真实序列化结果，不把手写字段表或内部类型检查当联调。
• 依同步矩阵查漏；活跃 Spec/Issue 的成功标准是否连到实现、TEST-ID/人工出口和交付证据，归档内容是否仍被误当当前依据。Issue Tracker 不可访问时，任务状态与排期标未验证。
• 检查全部文档可达性与职责下沉；确定性孤儿提示只是候选，不能证明从脊柱可达。TEST-ID 字符串出现不等于必要测试点已有完整证据。
• 存在 .claude/ 时检查死配置、模糊命名、个人偏好混入团队、空目录及规则过载。针对具体变更时再按 change-impact 检查超范围改动、迁移尾项和遗留临时代码。

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

阶段同步

采用 PR 护栏的项目，在创建或更新 PR 前必须运行 scripts/check-pr-docs.py --base <实际目标分支>，非零先修复，不继续提交 PR。已推送分支也要执行。推送钩子和 PR CI 调用同一入口，安装与参数见 references/document-policy.md。根据项目已有模块同步表配置 change_rules，按输出核对本次改动影响的文档；确定性通过后仍做上述语义审计，在 PR 说明记录同步情况、无需同步的理由及未验证项。不能仅凭文档被改过就判为一致。

按 references/governance-sync-matrix.md 执行：用本阶段说明、会话记录和实际 diff 列出应同步载体，确定的当前真相直接增量更新；未知项列待确认。重点对象（如 contract）用于缩小范围，不改变文件职责。

核对 change-impact 的计划与实际影响、成功标准及验证证据；LOG 只追加，归档仍遵守事件阈值和确认边界。交付列出每份文档的实际变化、理由、未验证项和待确认项。

日志复盘

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

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

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