跳转到主要内容
Verify phase 是 archiving 前的 quality gate。/comet-verify 会运行 tests 和 build commands，检查 implementation 是否匹配 design，产出并保存 verification report，然后询问你如何处理 feature branch。在 report 存在且 branch 已处理前，任何内容都不会推进到 archive；guard 会将二者作为 hard prerequisites 强制执行。

​
Trigger

直接运行 /comet-verify，或在 tasks.md 中所有 tasks 已勾选时让 /comet 自动分发。OpenSpec 和 Superpowers 都会参与此 phase。

​
Owner

OpenSpec 和 Superpowers 共同负责 — OpenSpec 的 openspec-verify-change skill 负责较大 changes 的 full spec-coverage verification；Superpowers 的 finishing-a-development-branch skill 负责 branch lifecycle。Lightweight verification（小变更）会 inline 运行，不加载外部 skill。

​
会发生什么

1

Scale assessment 决定 verification mode

AI 会运行 scale assessment，统计 tasks、delta specs 和 changed files，以判断这是 lightweight（小变更）还是 full verification。结果会作为 verify_mode 写入 .comet.yaml。如果每个 task 都单独提交，AI 还会检查 base-ref commit range，以更准确地了解 change scope。
2

运行 tests 和 build commands

AI 会执行项目的 build 和 test commands。它会先从 .comet.yaml 读取 verify_command 和 build_command；如果二者都未设置，则回退到 auto-detection（npm run build、Maven、Cargo 等）。失败命令的输出会作为 evidence 打印。
  • Lightweight verification 检查：所有 tasks 完成、changed files 匹配 task descriptions、build 通过、tests 通过、无明显 security issues（hardcoded keys、不安全操作）。
  • Full verification 额外加载 openspec-verify-change 并检查：implementation vs. design.md high-level decisions、implementation vs. Design Doc（technical RFC）、所有 delta spec acceptance scenarios 通过、proposal.md goals 满足，以及 delta spec 和 Design Doc 一致。
3

产出并保存 verification report

Verification conclusions 会写入 docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md report file。该路径会作为 verification_report 记录在 .comet.yaml 中。此文件必须真实存在于磁盘上；guard 检查的是路径，而不只是字段值。
4

你选择如何处理 branch（blocking pause）

AI 会加载 Superpowers finishing-a-development-branch skill，并展示 branch-handling options。你必须明确选择，AI 不会根据推荐或当前 branch state 替你选择：
  1. 本地 merge 到 main branch
  2. Push 并创建 PR
  3. 保留 branch（稍后处理）
  4. 丢弃 work
只有你选择并完成相应操作后，branch_status: handled 才会写入 .comet.yaml。
5

Guard 验证 evidence 并推进 state

允许 transition 到 archive 前，phase guard 会检查两个 hard prerequisites：
  • verification_report 指向现有文件
  • branch_status: handled
两者都满足时，guard 会自动将 .comet.yaml transition 到 phase: archive，设置 verify_result: pass，并记录 verified_at。

​
Verify Result Values

.comet.yaml 中的 verify_result 字段反映当前 verification state：
Value含义
pendingVerification 尚未完成（build 后的初始状态）
pass所有 verification checks 均通过，且 guard 已确认 evidence
failVerification 失败；workflow 已回滚到 phase: build 进行修复

​
Verification Failure Handling

Verify failure 会阻塞 workflow。 如果任何检查失败，AI 会暂停并展示结构化 failed items 列表，按 CRITICAL、WARNING 或 SUGGESTION 分类，然后等待你的明确决策。你必须选择修复问题或接受 deviation。你选择之前，workflow 不能推进。
  • Fix all：state 通过 comet-state transition verify-fail 回滚到 phase: build，然后调用 /comet-build 进行修正。
  • Handle item by item：CRITICAL failures（build failures、test failures、security issues、core acceptance scenario failures）必须修复。Non-CRITICAL failures 可以在 verification report 中记录 rationale 后接受。当存在任何 CRITICAL failure 时，不能跳过所有修复。

​
Required Evidence

记录 verify-pass 前，guard 会强制两个 conditions 作为 hard prerequisites：
  1. verification_report 必须指向记录路径上真实存在的文件
  2. branch_status: handled 必须设置在 .comet.yaml 中
两者必须同时为真。如果完成 verification 但未保存 report file，或处理 branch 但未完成 verification，guard 都会用明确 error message 阻止 transition。

​
Spec Drift Handling

如果 full verification 发现 delta spec 在 Phase 3 中被修改，但 Design Doc 没有反映这些 changes，AI 会暂停并要求你从三个选项中选择：
Option操作
A — Document the divergence向 Design Doc 追加 “Implementation Divergence” section，说明 implementation drift 的原因。这是 verify-phase artifact，不会重新触发 dirty-worktree checks。
B — Fix the Design Doc回滚到 build phase；Superpowers brainstorming skill 会更新 Design Doc 和 delta spec，以反映实际 implementation。
C — Accept the deviation确认 drift 可接受并继续。Archive 期间，Design Doc 会被标记为 superseded-by-main-spec。
AI 不会替你选择，spec drift decision 始终是用户选择。

​
Context Compaction Recovery

Verify phase 可能触发 context compaction，尤其是在大型 changes 的 full verification 期间。若要恢复，请运行： 
"$COMET_BASH" "$COMET_STATE" check <change-name> verify --recover
脚本会输出当前 phase、verification status、branch status 和推荐 recovery action。按照 recovery action 从正确步骤恢复。例如，如果 verify_result 已是 pass 且 branch_status 是 handled，recovery action 会直接引导你运行 guard 进行 transition。