Back to Details

comet-verify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Comet 阶段 4：验证与收尾（Verify）

Comet Phase 4: Verification and Wrap-up (Verify)

前置条件

Prerequisites

  • 代码已提交（阶段 3 完成）
  • tasks.md 全部任务已完成
  • Code has been submitted (Phase 3 completed)
  • All tasks in tasks.md have been completed

步骤

Steps

0. 入口状态验证（Entry Check）

0. Entry Check

执行入口验证：
bash
COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <change-name> verify
验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
Perform entry verification:
bash
COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <change-name> verify
Proceed to Step 1 after passing verification. The script will output specific failure reasons if verification fails.

1. 改动规模评估

1. Change Scale Assessment

执行规模评估：
bash
bash "$COMET_STATE" scale <change-name>
脚本自动统计任务数、增量规格数、变更文件数，判断使用 light 或 full 验证模式，并设置 verify_mode 字段。
验证开始前，按 
comet/reference/dirty-worktree.md
协议检查并处理未提交改动。verify 阶段的特殊处理：
  1. 若 dirty diff 属于当前 change 且涉及实现、测试、tasks、delta spec 或 design doc 变更，不在 verify 阶段直接修复或提交；先记录失败并回退到 build 阶段
  2. 若 dirty diff 只是 verify 本阶段产物（例如验证报告草稿、分支处理记录），可继续在 verify 阶段完成并记录状态
  3. 若 dirty diff 已实现但 tasks.md 未勾选，视为 build 状态滞后；先记录失败并回退到 build 阶段，由 
    /comet-build
    验证实现、补勾任务并提交
回退到 build 阶段：
bash
bash "$COMET_STATE" transition <change-name> verify-fail
注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 
base-ref
并用提交区间复核：
bash
PLAN=$(bash "$COMET_STATE" get <change-name> plan)
BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
git diff --stat "$BASE_REF"...HEAD
若提交区间显示改动超过轻量阈值（> 5 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
bash
bash "$COMET_STATE" set <change-name> verify_mode full
Perform scale assessment:
bash
bash "$COMET_STATE" scale <change-name>
The script automatically counts the number of tasks, incremental specification items, and changed files, determines whether to use light or full verification mode, and sets the verify_mode field.
Before starting verification, check and handle uncommitted changes according to the 
comet/reference/dirty-worktree.md
protocol. Special handling during the verify phase:
  1. If the dirty diff belongs to the current change and involves changes to implementation, tests, tasks, delta spec, or design doc, do not directly fix or commit during the verify phase; record the failure first and roll back to the build phase
  2. If the dirty diff is only a product of the verify phase (e.g., draft verification report, branch handling records), you can continue to complete it in the verify phase and record the status
  3. If the dirty diff has been implemented but not checked in tasks.md, it is considered that the build status is lagging; record the failure first and roll back to the build phase, then invoke 
    /comet-build
    to verify the implementation, check off the tasks and submit
Roll back to build phase:
bash
bash "$COMET_STATE" transition <change-name> verify-fail
Note: If every task in the build phase has been submitted, the number of files based on the workspace diff calculated by the script may underestimate the scale of changes. In this case, you must read the 
base-ref
in the plan file header and review it using the commit range:
bash
PLAN=$(bash "$COMET_STATE" get <change-name> plan)
BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
git diff --stat "$BASE_REF"...HEAD
If the commit range shows changes exceeding the light threshold (> 5 files, cross-module coordination, or delta spec with more than 1 capability), manually set to full verification:
bash
bash "$COMET_STATE" set <change-name> verify_mode full

2a. 轻量验证（小改动）

2a. Light Verification (Small Changes)

当规模评估结果为"小"时，跳过 
openspec-verify-change
，直接执行以下检查：
  1. tasks.md 全部任务已完成 
    [x]
  2. 改动文件与 tasks.md 描述一致（
    git diff --stat
    / 
    git diff --cached --stat
    / 
    git diff --stat <base-ref>...HEAD
    对照 tasks 内容）
  3. 编译通过（执行项目对应的构建命令，如 
    npm run build
    、
    mvn compile
    、
    cargo build
    等）
  4. 相关测试通过
  5. 无明显安全问题（无硬编码密钥、无新增 unsafe 操作）
通过标准：5 项全部 OK，无 CRITICAL 问题。
不通过时：报告失败项，记录失败并回退到 build 阶段，然后调用 
/comet-build
修复。
bash
bash "$COMET_STATE" transition <change-name> verify-fail
报告格式：简表列出 5 项检查结果 + PASS/FAIL。
跳过项（不在轻量验证中检查）：
  • spec scenario 覆盖率
  • design doc 一致性深度比对
  • code pattern consistency 建议
  • delta spec 与 design doc 漂移检测
When the scale assessment result is "small", skip 
openspec-verify-change
and directly perform the following checks:
  1. All tasks in tasks.md are completed 
    [x]
  2. Changed files match the description in tasks.md (compare with tasks content using 
    git diff --stat
    / 
    git diff --cached --stat
    / 
    git diff --stat <base-ref>...HEAD
    )
  3. Compilation passes (execute the project's corresponding build command, such as 
    npm run build
    , 
    mvn compile
    , 
    cargo build
    etc.)
  4. Relevant tests pass
  5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
Pass Criteria: All 5 items are OK, no CRITICAL issues.
If Not Passed: Report failed items, record the failure and roll back to the build phase, then invoke 
/comet-build
to fix.
bash
bash "$COMET_STATE" transition <change-name> verify-fail
Report Format: A simple table listing the results of the 5 checks + PASS/FAIL.
Skipped Items (not checked in light verification):
  • spec scenario coverage
  • in-depth comparison of design doc consistency
  • code pattern consistency suggestions
  • delta spec and design doc drift detection

2b. 完整验证（大改动）

2b. Full Verification (Large Changes)

当规模评估结果为"大"时：
立即执行： 使用 Skill 工具加载 
openspec-verify-change
技能。禁止跳过此步骤。
技能加载后，按其指引验证。检查项：
  1. tasks.md 全部任务已完成（
    [x]
    ）
  2. 实现符合 design.md 设计决策
  3. 实现符合 brainstorming 设计文档
  4. 能力规格场景全部通过
  5. proposal.md 目标已满足
  6. delta spec 与 design doc 无矛盾（若 Build 阶段有增量修改 spec，检查 design doc 是否有对应记录）
  7. docs/superpowers/specs/
    关联的设计文档可定位（文件存在且与当前 change 相关）
验证不通过时：报告缺失项，记录失败并回退到 build 阶段，然后调用 
/comet-build
补充。
bash
bash "$COMET_STATE" transition <change-name> verify-fail
Spec 漂移处理：
  • 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），提示用户：
    • 选项 A：在 design doc 追加 "Implementation Divergence" 节记录偏差原因
    • 选项 B：回退到 Build 阶段，补充 brainstorming 更新 design doc
    • 选项 C：确认偏差可接受，继续验证（归档时 design doc 将标记为 
      superseded-by-main-spec
      ）
When the scale assessment result is "large":
Immediate Action: Use the Skill tool to load the 
openspec-verify-change
skill. Skipping this step is prohibited.
After loading the skill, verify according to its guidelines. Check items:
  1. All tasks in tasks.md are completed (
    [x]
    )
  2. Implementation complies with design decisions in design.md
  3. Implementation complies with brainstorming design documents
  4. All capability specification scenarios pass
  5. Goals in proposal.md are met
  6. No contradictions between delta spec and design doc (if there are incremental spec modifications in the Build phase, check whether the design doc has corresponding records)
  7. Associated design documents in 
    docs/superpowers/specs/
    are locatable (files exist and are relevant to the current change)
If verification fails: Report missing items, record the failure and roll back to the build phase, then invoke 
/comet-build
to supplement.
bash
bash "$COMET_STATE" transition <change-name> verify-fail
Spec Drift Handling:
  • If contradiction is found in check item 6 (delta spec has content but not reflected in design doc), prompt the user:
    • Option A: Append an "Implementation Divergence" section in the design doc to record the reason for deviation
    • Option B: Roll back to the Build phase, supplement brainstorming and update the design doc
    • Option C: Confirm the deviation is acceptable and continue verification (the design doc will be marked as 
      superseded-by-main-spec
      during archiving)

3. 收尾（Superpowers）

3. Wrap-up (Superpowers)

立即执行： 使用 Skill 工具加载 
superpowers:finishing-a-development-branch
技能。禁止跳过此步骤。
如 
superpowers:finishing-a-development-branch
不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
技能加载后，按其指引收尾。分支处理选项：
  1. 本地合并到主分支
  2. 推送并创建 PR
  3. 保持分支（稍后处理）
  4. 丢弃工作
确认项：
  • 全部测试通过
  • 无硬编码密钥或安全问题
Immediate Action: Use the Skill tool to load the 
superpowers:finishing-a-development-branch
skill. Skipping this step is prohibited.
If 
superpowers:finishing-a-development-branch
is unavailable, stop the process and prompt to install or enable the Superpowers skill; do not replace this step with ordinary dialogue.
After loading the skill, wrap up according to its guidelines. Branch handling options:
  1. Merge locally to the main branch
  2. Push and create a PR
  3. Keep the branch (handle later)
  4. Discard work
Confirmation Items:
  • All tests pass
  • No hardcoded secrets or security issues

4. 记录验证证据

4. Record Verification Evidence

验证报告必须落盘，并在 
.comet.yaml
中记录；分支处理完成后也必须写入状态字段。不要手动设置 
verify_result: pass
，通过 guard 自动流转。
bash
mkdir -p docs/superpowers/reports
The verification report must be saved to disk and recorded in 
.comet.yaml
; branch handling status must also be written to the status field after completion. Do not manually set 
verify_result: pass
; let the guard automatically transition.
bash
mkdir -p docs/superpowers/reports

将本次验证结论写入报告文件，例如：

Write the verification conclusion to the report file, for example:

docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md

docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md

bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md bash "$COMET_STATE" set <change-name> branch_status handled
undefined
bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md bash "$COMET_STATE" set <change-name> branch_status handled
undefined

退出条件

Exit Conditions

  • 验证报告通过
  • 分支已处理
  • .comet.yaml
    中 
    verification_report
    指向已存在的验证报告文件
  • .comet.yaml
    中 
    branch_status: handled
  • 阶段守卫：运行 
    bash "$COMET_GUARD" <change-name> verify --apply
    ，全部 PASS 后通过 
    comet-state transition verify-pass
    自动流转到 
    phase: archive
验证和分支处理均完成后，运行 guard 自动流转：
bash
bash "$COMET_GUARD" <change-name> verify --apply
状态文件自动更新为 
phase: archive
、
verify_result: pass
、
verified_at: YYYY-MM-DD
。
  • Verification report is approved
  • Branch has been handled
  • .comet.yaml
    contains 
    verification_report
    pointing to an existing verification report file
  • .comet.yaml
    contains 
    branch_status: handled
  • Phase Guard: Run 
    bash "$COMET_GUARD" <change-name> verify --apply
    , and after all items PASS, automatically transition to 
    phase: archive
    via 
    comet-state transition verify-pass
After verification and branch handling are completed, run the guard to automatically transition:
bash
bash "$COMET_GUARD" <change-name> verify --apply
The status file will be automatically updated to 
phase: archive
, 
verify_result: pass
, 
verified_at: YYYY-MM-DD
.

自动流转

Automatic Transition

退出条件满足后，无需等待用户再次输入，直接执行下一阶段：
REQUIRED NEXT SKILL: 调用 
comet-archive
skill 进入归档阶段。
After meeting the exit conditions, do not wait for user input again, directly execute the next phase:
REQUIRED NEXT SKILL: Invoke the 
comet-archive
skill to enter the archiving phase.