# software-engineering 技能 CHANGELOG

## 说明

本文件新建于 2026-10-31（附录溯源一轨）。此前 SKILL.md 正文（v0.2，
2026-10-30）已引用同目录 `CHANGELOG.md`，但包内并无此文件，因此
v0.1 → v0.2 的 5 个 P0 缺口明细无法从本文件追溯，本文件不编造
那段历史；以下只记录 2026-10-31 起可核实、可复查的条目。

## 2026-10-31：附录溯源补齐（SKILL.md 未动，零语义改动）

此前缺失：SKILL.md 称附录“由生成脚本从 `templates/roles/` 原样拼接，
见 CHANGELOG”，但包内既无 `templates/`、也无 `CHANGELOG.md`、更无
生成脚本，附录 9 章内容不可验——附录与源不一致时无从发现。

本次补齐：

- 新增 `templates/roles/` 下 9 个编辑源文件（`00-coordinator.md` 至
  `08-shared-core.md`），内容由现行 v0.2 附录逐章机械拆出：每章源文件
  即该章标题行之后的正文（含 00/04/07 章后的 GitHub 小节），仅剥离
  章节标题行、章节间分隔符行与首尾空行。SKILL.md 本文件未作任何
  改动，因此不存在语义改动；源与附录的对应关系由校验脚本钉住，
  今后任一侧改动都会先被校验拦住，而不是悄悄漂移。
- 新增 `tools/check_appendix.py`（仅标准库，不改 SKILL.md）：默认
  校验模式逐章比对源与附录，源缺失、章节缺失、内容不一致、多余
  源文件、CHANGELOG 缺失或未提及 `templates/roles/` 均以非零退出
  失败；`--emit` 模式只把拼接后的附录规范形式打印到标准输出，供
  编辑者起草参考，绝不是可直接覆盖 SKILL.md 的字节补丁（分隔符与
  空行见脚本注释的允许差异清单）。
- 新增 `cloud/tests/test_skill_appendix_provenance.py`：钉住源与附录
  一致、源缺失即失败、脚本 `--emit` 输出与源一致。

播种行为不变：`cloud/skill_seed.py` 只复制各技能的 `SKILL.md` 一个
文件，`templates/`、`tools/`、`CHANGELOG.md` 均不进入租户目录（该行
为已由 `test_skill_seed_pinning.py` 钉住，见其“仅复制 SKILL.md”一
项）。因此源文件进技能包不改变租户可见内容：租户任务内仍只能
看到 SKILL.md 随附的附录全文，附录仍是租户侧的权威版本。

## 已知边界（未改行为，另起设计时再动）

- 租户已删 `SKILL.md` 会在下次播种时重建（missing 即复制），这是
  现有播种语义，不是删除保留；要保留删除需 tombstone 设计，须另
  起一轨，不在本条目悄悄改播种行为。
- 校验的允许差异只有三项：章节标题行本身、至多一枚章节间分隔符
  行、标题与章末的空行。现行 SKILL.md 的分隔符并不统一（01/02/03/
  05/06 章后有 `---`，00/04/07 章后无分隔符直接接下一章标题），校验
  保留该现状、不强行统一 SKILL.md。

## 未动项

- SKILL.md 同样引用的同目录 `README.md`（装机路径）未在本条目处理，
  仍缺失；本条目只补附录溯源，不扩大范围。