技能：文档治理审计（Audit Docs）

目的 (Purpose)

用只读方式整合文档治理现状，输出统一审计报告与行动路线图，不执行结构改造或规范落盘。

---

核心目标（Core Objective）

首要目标：产出可直接执行的治理审计报告（问题、优先级、路由），而不是直接改仓库。

成功标准（必须全部满足）：

1. ✅ 已完成模式对应的只读评估编排
2. ✅ 已汇总核心 findings 与风险优先级
3. ✅ 已输出明确的下一步技能路由
4. ✅ 已生成单一统一报告 docs/calibration/audit-docs.md
5. ✅ 未执行整理、迁移、规范落盘等写入操作

验收测试：团队是否能仅凭报告决定“下一步调用哪些技能”，且无需担心被隐式改仓库？

---

范围边界（Scope Boundaries）

本技能负责：

• 按模式编排只读评估技能
• 聚合评分、风险和行动优先级
• 生成统一治理报告

本技能不负责：

• 建立或更新规范文件（define-docs-norms）
• 仓库整理或文件迁移（tidy-repo）
• 自动接受并应用任何修改

交接点：报告完成后，交由用户选择是否执行创建/整理类技能。

---

使用场景（Use Cases）

• 新项目治理基线检查
• 发布前治理审计
• PR 合并前文档门禁
• 周期性治理体检

---

行为（Behavior）

阶段 0：Norms Resolution（v2.1 新增）

按 specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 的 §8.2 / §8.3 / §8.5 实现：读项目规范若声明了 audit-docs artifact_type 的 path_pattern，则使用项目值；否则 fall through 到技能默认（docs/calibration/audit-docs.md）。本技能为固定路径治理产出（orchestrator 角色），只用 path_pattern 覆盖机制；所依赖的子技能各自执行其 Stage 0。

模式定义

• quick：仅 assess-docs（核心评估）
• full：assess-docs + assess-docs-links + assess-docs-ssot
• code-review：assess-docs + assess-docs-code-alignment

执行步骤

1. 预检查：git 仓库可访问、docs 路径可读
2. 规范检查：若缺失 docs/ARTIFACT_NORMS.md，仅记录风险并路由 discover-docs-norms/define-docs-norms
3. 按模式执行只读评估技能并收集输出
4. 汇总评分（结构、就绪、链接、SSOT、代码对齐）
5. 生成 docs/calibration/audit-docs.md

---

输入与输出 (Input & Output)

输入

• 项目路径（默认 CWD）
• 模式：quick|full|code-review
• 可选 code-diff（用于 code-review）

输出

• docs/calibration/audit-docs.md
• 引用的下游报告（按模式）：
  • docs/calibration/doc-assessment.md
  • docs/calibration/doc-link-health.md
  • docs/calibration/ssot-integrity-audit.md
  • docs/calibration/code-doc-alignment.md

---

限制（Restrictions）

硬边界（Hard Boundaries）

• 不执行 tidy-repo --apply 或等价改写操作
• 不执行 define-docs-norms 落盘
• 不自动接受规范推导结果

技能边界 (Skill Boundaries)

不要做这些（其他技能负责）：

• 规范发现：discover-docs-norms
• 规范落盘：define-docs-norms
• 仓库整理：tidy-repo

---

自检（Self-Check）

• 模式对应编排正确
• 已汇总下游报告结论
• 已输出优先级路线图
• 未触发任何结构/规范写入
• 审计报告已落盘

---

示例（Examples）

示例 1：full 审计

• 执行：assess-docs + assess-docs-links + assess-docs-ssot
• 输出：audit-docs.md + 路由建议

示例 2：code-review 审计

• 执行：assess-docs + assess-docs-code-alignment
• 输出：聚焦 PR 的文档门禁建议

---

附录：输出合约 (Appendix: Output Contract)

本技能为 read-only 审计聚合器，产出统一报告：

元素	格式	必填字段	路径模式
报告主体	Markdown	front-matter；章节：执行摘要 / 子审计聚合（assess-docs / assess-docs-links / assess-docs-ssot / assess-docs-code-alignment）/ 优先动作 / 技能路由	docs/calibration/audit-docs.md
优先动作	表格	rank / issue / target_artifact / recommended_skill / rationale	「优先动作」节
技能路由	列表项	skill_id / invocation_hint / scope / expected_output_artifact	「技能路由」节
机器可读块	YAML fenced yaml audit_summary:	counts、top_actions[] 每项含 rank/skill/artifact	报告末尾