技能：代码文档对齐评估（Assess Docs Code Alignment）

目的 (Purpose)

检测代码改动是否有相应文档更新，输出可执行的补文档清单。

---

核心目标（Core Objective）

首要目标：从代码 diff 推断需要更新的文档，并报告未覆盖缺口。

成功标准：

1. ✅ 已解析代码 diff 范围
2. ✅ 已映射代码区域到文档区域
3. ✅ 已输出 missing/partial/covered 对齐结果
4. ✅ 已产出可执行补齐建议
5. ✅ 已写入 docs/calibration/code-doc-alignment.md

---

范围边界（Scope Boundaries）

本技能负责：代码变更与文档变更对齐分析。 本技能不负责：文档规范评估（assess-docs）、链接图（assess-docs-links）、SSOT（assess-docs-ssot）。

---

使用场景（Use Cases）

• PR 合并前文档门禁
• 发版前代码变更回查

---

行为（Behavior）

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

按 specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 的 §8.2 / §8.3 / §8.5 实现：读项目规范若声明了 code-doc-alignment artifact_type 的 path_pattern，则使用项目值；否则 fall through 到技能默认（docs/calibration/code-doc-alignment.md）。本技能为固定路径治理产出，只用 path_pattern 覆盖机制。

阶段 1：代码-文档对齐评估

1. 获取 diff：git diff <base>...HEAD --name-status --diff-filter=MAD
2. 归类代码变更区域
3. 依据映射规则推断“应更新文档”
4. 对比当前分支文档改动
5. 输出 findings 与建议

---

输入与输出 (Input & Output)

输入

• base 或 diff 范围
• docs 根路径（可选）
• 区域映射规则（可选）

输出

• docs/calibration/code-doc-alignment.md

---

限制（Restrictions）

• 不修改代码与文档文件
• 仅输出评估和建议

---

自检（Self-Check）

• 已解析 diff
• 已产出缺口列表与建议
• 已写入单一对齐报告

---

示例（Examples）

• src/api/auth.py 修改但 docs/architecture/api.md 未更新 -> high

---

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

本技能产出 Code-Doc Alignment Report：

元素	格式	必填字段	路径模式
报告主体	Markdown	front-matter；章节：摘要 / 对齐缺口 / 推荐文档更新	docs/calibration/code-doc-alignment.md
缺口条目	列表项	id / category（api_drift / config_drift / behavior_drift / removed_feature）/ code_location / doc_location / evidence / suggested_update	「对齐缺口」节
机器可读块	YAML fenced yaml alignment_gaps:	gaps[] 每项含 id/category/severity/code_ref/doc_ref	报告末尾