docs(skill): add appendix provenance sources, checker and CHANGELOG
SKILL.md claimed its appendix was spliced verbatim from templates/roles/ by a generation script (see CHANGELOG), but the pack contained none of the three. Add the nine role sources (mechanically split from the v0.2 appendix; SKILL.md untouched, zero semantic change), tools/check_appendix.py (verify + --emit, stdlib only, never edits SKILL.md), CHANGELOG.md, and test_skill_appendix_provenance.py (5 tests). Seeding unchanged: skill_seed copies SKILL.md only, so templates/tools/CHANGELOG never reach the tenant home.
This commit is contained in:
1 parent
61e08a1a8c
commit
4e554b5c07
12 files changed
+818
No files matched your search
@@ -0,0 +1,52 @@
|
||||
# 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`(装机路径)未在本条目处理,
|
||||
仍缺失;本条目只补附录溯源,不扩大范围。
|
||||
Reference in new issue
Block a user