Beat change 已完成并准备归档时，检查完成度…

当 Beat change 已实现或已提炼并验证、准备归档时，执行完成检查、feature 同步、glossary/ADR 清扫、移动到 archive 并引导分支收尾。

适用场景

解决思路

1. HARD-GATE：archive 完成后必须调用 superpowers:finishing-a-development-branch 引导 merge/PR/cleanup；若不可用（未安装），跳过并只显示 summary；绝不能因为自己判断工作流完成而不调用。
2. HARD-GATE：归档前必须检查 status.yaml 顶层 verification 字段；若缺失或 issues-found，与用户确认——告知并确认，绝不阻塞。
3. HARD-GATE：当 gherkin status 为 done 时，必须在归档前同步 features。
4. HARD-GATE：同步前必须扫描将要同步的 features 中尚未在 beat/CONTEXT.md 定义的项目特定术语，并提示用户添加。
5. HARD-GATE：移动到 archive 前必须运行 last-mile ADR sweep；如果此 change 写入零个 ADR，归档前提示一次；无论 features 是否同步都适用。
6. HARD-GATE：不要因为用户想要速度而跳过任何这些检查。
7. Prerequisites：在归档完成后调用 finishing-a-development-branch，优先级 MUST；如果不可用（skill 未安装），跳过并只显示 archive summary。
8. 防止合理化：不要认为 change 已归档后 finishing-a-development-branch 是可选清理；没有分支指导归档会留下 orphan branches 和未提交工作，该技能确保不遗漏。
9. 防止合理化：不要只告诉用户手动创建 PR；finishing-a-development-branch 提供结构化选项（merge、PR、cleanup）并适应当前状态，手动建议会漏上下文。
10. 防止合理化：不要跳过 sync 以为用户以后可运行；没有单独 sync 技能，archive 是 features 被同步的唯一地方，跳过意味着 features 从 living documentation 丢失。
11. 防止合理化：不要留 .orig 备份以后清理；孤立的 .orig 文件会永久对 BDD runners 隐藏 scenarios，清理是 archive 的一部分，不是单独步骤。
12. 防止合理化：不要认为 glossary terms 可以以后再添加，这只是文档；一旦 features 同步进 beat/features/，未定义术语变成用户可见 living documentation，未来读者分不清 canonical vs ad hoc；扫描并提示只需两分钟，应在 sync 前做。
13. 防止合理化：不要因为 design.md 捕获一切就不写 ADR；design.md 随 change 归档，跨 change 决策需要放在 docs/adr/；last-mile sweep 只是一个提示，若没有合格项不成本。
14. 防止合理化：不要假设 verify 曾在某时运行；status.yaml 记录它，如果 verification 字段缺失，verify 从未运行，归档未验证工作正是此检查要关闭的缺口；一个确认提示，绝不阻塞。
15. Red Flags：如果发现自己在完成 archive 时没有调用 finishing-a-development-branch，必须 STOP。
16. Red Flags：如果发现自己在未检查 gherkin 是否 done 时跳过 sync 步骤，必须 STOP。
17. Red Flags：如果 features 存在时移动 archive 前没有询问用户 capability mapping，必须 STOP。
18. Red Flags：如果 beat/features/ 中仍有 .feature.orig 文件时完成 archive，必须 STOP。
19. Red Flags：如果同步 features 前未先扫描 beat/CONTEXT.md 中缺失的项目特定术语，必须 STOP。
20. Red Flags：如果归档零 ADR 的 change 时未运行 last-mile sweep prompt，必须 STOP。
21. Red Flags：如果归档没有 verification 记录（或 status: issues-found）的 change 时未经用户确认，必须 STOP。
22. 输入：可选指定 change 名称；如果省略，从上下文推断或提示。
23. 步骤 1 Select change：如果未提供名称，查找 beat/changes/ 目录（排除 archive/）；如果只有一个存在，使用它；如果多个存在，使用 AskUserQuestion tool 让用户选择；只显示 active（非归档）changes。
24. 步骤 2 Check artifact completion：读 beat/changes/<name>/status.yaml（schema：references/status-schema.md）；检查哪些 artifacts 是 done vs pending（不是 skipped）。
25. 步骤 2 后续：如果任何非 skipped artifacts 仍为 pending，显示警告列出未完成 artifacts；用 AskUserQuestion tool 确认用户是否继续；如果用户确认则继续。
26. 步骤 3 Check task completion（如果 tasks.md 存在）：读 tasks.md；计数 - [ ] 不完整 vs - [x] 完成。
27. 步骤 3 后续：如果发现不完整任务，显示警告「N/M tasks incomplete」；用 AskUserQuestion tool 确认；如果用户确认则继续。
28. 步骤 3b Check verification ran：读 status.yaml 顶层 verification 字段。Absent：警告此 change 从未验证（/beat:verify 尚未运行）；用 AskUserQuestion tool 确认是否仍然归档。status: issues-found：警告验证发现 N 个 critical issue(s) 于 <date>；用 AskUserQuestion tool 确认。status: passed：静默继续。告知并确认——绝不阻塞。
29. 步骤 4 Sync features to living documentation：检查 status.yaml。如果 gherkin status 是 skipped：跳过 sync（没有 features 可同步），进入步骤 4b。
30. 步骤 4 如果 gherkin status 是 done：从 beat/changes/<name>/ 读取 features/*.feature（所有 Gherkin 文件）、proposal.md（如果存在）、design.md（如果存在）。
31. 步骤 4：如果没有 feature 文件，跳过 sync，进入步骤 4b。
32. 步骤 4：读 beat/config.yaml 如果存在（schema：references/config-schema.md）；使用 language 作为 README 内容语言。
33. 步骤 4：确定 capability mapping：用 AskUserQuestion tool 询问每个 feature 应同步到哪里，已有 capabilities 来自 beat/features/，或输入新名称；如果只有一个 feature 文件且映射明显，建议默认。
34. 步骤 4：扫描 features 中未定义术语（Layer 1 living-doc enforcement）：读 beat/CONTEXT.md 如果存在（schema：references/context-format.md）；glossary 是 lazy，可能不存在如果这是项目第一次同步 change。
35. 步骤 4：扫描将要同步的 feature files 中 bolded 项目特定术语。对每个术语：如果存在于 beat/CONTEXT.md，继续；如果不存在，用 AskUserQuestion tool 提示该 term 出现在 scenarios 但不在 beat/CONTEXT.md 中，询问现在是否添加；选项：Yes（推荐）：提供一句话定义，Beat 追加它；Skip this term；Skip all remaining（记录数量用于 summary）。
36. 步骤 4：当用户添加术语时，按 references/context-format.md 结构追加到 beat/CONTEXT.md（一句话定义，可选 _Avoid_ aliases）；如果 beat/CONTEXT.md 不存在，懒创建。如果扫描的 features 中没有项目特定 bolded terms，静默跳过此子步骤。
37. 步骤 4：同步文件：如果 beat/features/ 不存在，创建：mkdir -p beat/features。
38. 步骤 4：按映射表同步：features/*.feature -> beat/features/<capability>/：添加或更新 feature files；proposal.md -> beat/features/<capability>/proposal.md：复制到 capability；design.md -> beat/features/<capability>/design.md：复制到 capability。
39. 步骤 4：当 features 映射到多个 capabilities 时，复制 proposal.md 和 design.md 到 primary capability only（接收最多 feature files 的那个）；如果平局，询问用户哪个 capability 拥有它们；不要跨 capabilities 复制它们。
40. 步骤 4：处理 .orig 备份（当 status.yaml 有 gherkin.modified）：对 gherkin.modified 中每个路径：1) 修改版本在 changes/<name>/features/，同步它到 beat/features/<capability>/（与新 features 相同，统一流程）；2) 从 beat/features/ 删除 .feature.orig 备份；3) 如果项目使用 pytest-bdd，更新测试文件中的 @scenario 装饰器路径（从 beat/changes/.../x.feature -> beat/features/<capability>/x.feature）。
41. 步骤 4：继续前验证 beat/features/ 中无 .feature.orig 文件残留。
42. 步骤 4：如果 beat/features/<capability>/README.md 不存在，创建（placeholder description）；创建或更新 beat/features/README.md 带全局导航；更新 status.yaml phase 为 sync。
43. 步骤 4b Last-mile ADR sweep（Layer 2 living-doc enforcement）：在每条路径运行——无论 features 是否同步或跳过同步。统计此 change 写入或引用的 ADR 文件：检查 docs/adr/ 中自 change 开始以来创建的文件（git diff against change 的 base commit）；扫描 design.md 和 tasks.md 中的 docs/adr/NNNN- 交叉引用。
44. 步骤 4b：如果此 change 至少有一个 ADR，静默跳过 sweep；较早触发器（在 /beat:design、/beat:plan、/beat:apply 中）已捕获候选。
45. 步骤 4b：如果此 change 零个 ADR，用 AskUserQuestion tool 提示一次：没有为此 change 记录 ADR，是否有 hard-to-reverse + surprising + real-trade-off 决策值得在归档前记录；选项：No, none qualified；Yes, let me describe it now。
46. 步骤 4b：如果用户描述一个，运行 references/adr-format.md 中的三条件门禁；如果三个条件都成立，用下一个顺序编号写入 docs/adr/ 下的 ADR；如果并非三个条件都成立，记录跳过；无论哪种，继续归档。
47. 步骤 5 Perform archive：更新 status.yaml：设置 phase 为 archive；运行 mkdir -p beat/changes/archive；生成目标名称：YYYY-MM-DD-<change-name>。
48. 步骤 5：检查目标是否已存在：如果存在，报错并建议重命名；如果不存在，移动目录：mv beat/changes/<name> beat/changes/archive/YYYY-MM-DD-<name>。
49. 步骤 6 Show summary：显示 archive summary，包含 Change、Archived to、Verification（passed / issues-found (N critical) / never run (user confirmed)）、Features（Synced to beat/features/ 或 Sync skipped 或 No features to sync）、Glossary（N terms added to beat/CONTEXT.md 或 no changes 或 M terms skipped）、ADRs（N written to docs/adr/ 或 none recorded — last-mile sweep declined）、Artifacts（N done, M skipped）、Tasks（X/Y complete 或 No tasks file）。
50. 步骤 7 Finish the development branch：显示 summary 后，调用 superpowers:finishing-a-development-branch（如果可用）引导用户完成 merge、PR creation 或 cleanup；如果不可用，跳过此步骤。
51. Guardrails：始终在未提供时提示 change selection；不要因 warnings 阻塞 archive——告知并确认；在归档前内联同步 features；显示清晰的发生了什么总结；如果 archive target 已存在，不要覆盖。

适用边界 · 注意事项

• 不用于验证实现是否符合 spec；应使用 /beat:verify。
• 不用于实现剩余任务；应使用 /beat:apply。
• 不用于创建或修改 spec artifacts；应使用 /beat:design。