Skip to main content
The Verify phase is the quality gate before archiving. /comet-verify runs your tests and build commands, checks that implementation matches design, produces a verification report saved to disk, and then asks you to decide what to do with the feature branch. Nothing advances to archive until both the report exists and the branch is handled — the guard enforces both as hard prerequisites.

​
Trigger

Run /comet-verify directly, or let /comet auto-dispatch when all tasks in tasks.md are checked. Both OpenSpec and Superpowers contribute to this phase.

​
Owner

Both OpenSpec and Superpowers — OpenSpec’s openspec-verify-change skill handles full spec-coverage verification for larger changes; Superpowers’ finishing-a-development-branch skill handles the branch lifecycle. Lightweight verification (small changes) runs inline without loading an external skill.

​
What Happens

1

Scale assessment determines verification mode

The AI runs a scale assessment that counts tasks, delta specs, and changed files to determine whether this is a lightweight (small change) or full verification. The result is written to .comet.yaml as verify_mode. If every task was committed individually, the AI also checks the base-ref commit range for a more accurate picture of change scope.
2

Tests and build commands run

The AI executes your project’s build and test commands. It reads verify_command and build_command from .comet.yaml first; if neither is set, it falls back to auto-detection (npm run build, Maven, Cargo, etc.). Output from failed commands is printed as evidence.
  • Lightweight verification checks: all tasks complete, changed files match task descriptions, build passes, tests pass, no obvious security issues (hardcoded keys, unsafe operations).
  • Full verification additionally loads openspec-verify-change and checks: implementation vs. design.md high-level decisions, implementation vs. Design Doc (technical RFC), all delta spec acceptance scenarios pass, proposal.md goals satisfied, and consistency between delta spec and Design Doc.
3

Verification report is produced and saved

Verification conclusions are written to a report file at docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md. The path is recorded in .comet.yaml as verification_report. This file must exist on disk — the guard checks the path, not just the field value.
4

You choose how to handle the branch (blocking pause)

The AI loads the Superpowers finishing-a-development-branch skill and presents your branch-handling options. You must choose explicitly — the AI will not select based on recommendations or current branch state:
  1. Merge to main branch locally
  2. Push and create a PR
  3. Keep the branch (handle later)
  4. Discard work
Only after you select and the corresponding operation completes is branch_status: handled written to .comet.yaml.
5

Guard validates evidence and advances state

The phase guard checks two hard prerequisites before allowing the transition to archive:
  • verification_report points to an existing file
  • branch_status: handled
When both are satisfied, the guard auto-transitions .comet.yaml to phase: archive, sets verify_result: pass, and records verified_at.

​
Verify Result Values

The verify_result field in .comet.yaml reflects the current verification state:
ValueMeaning
pendingVerification has not yet completed (initial state after build)
passAll verification checks passed and the guard has confirmed evidence
failVerification failed; the workflow has rolled back to phase: build for fixes

​
Verification Failure Handling

Verify failure blocks the workflow. If any check fails, the AI pauses and presents a structured list of failed items — classified as CRITICAL, WARNING, or SUGGESTION — and waits for your explicit decision. You must choose to fix the issues or accept the deviation. The workflow cannot advance until you choose.
  • Fix all: The state rolls back to phase: build via comet-state transition verify-fail, then /comet-build is invoked to make corrections.
  • Handle item by item: CRITICAL failures (build failures, test failures, security issues, core acceptance scenario failures) must be fixed. Non-CRITICAL failures may be accepted with a recorded rationale in the verification report. You cannot skip all fixes when any CRITICAL failure exists.

​
Required Evidence

The guard enforces two conditions as hard prerequisites before verify-pass can be recorded:
  1. verification_report must point to a file that actually exists on disk at the recorded path
  2. branch_status: handled must be set in .comet.yaml
Both must be true simultaneously. Completing verification without saving the report file, or handling the branch without completing verification, will cause the guard to block the transition with a specific error message.

​
Spec Drift Handling

If full verification finds that the delta spec was modified during Phase 3 but the Design Doc doesn’t reflect those changes, the AI pauses and asks you to choose one of three options:
OptionAction
A — Document the divergenceAppend an “Implementation Divergence” section to the Design Doc explaining why the implementation drifted. This is a verify-phase artifact and does not re-trigger dirty-worktree checks.
B — Fix the Design DocRoll back to build phase; the Superpowers brainstorming skill updates the Design Doc and delta spec to reflect the actual implementation.
C — Accept the deviationConfirm the drift is acceptable and continue. The Design Doc will be marked superseded-by-main-spec during archiving.
The AI will not choose for you — the spec drift decision is always a user choice.

​
Context Compaction Recovery

The verify phase may trigger context compaction, especially during full verification of large changes. To recover, run: 
"$COMET_BASH" "$COMET_STATE" check <change-name> verify --recover
The script outputs the current phase, verification status, branch status, and a recommended recovery action. Follow the recovery action to resume from the correct step — for example, if verify_result is already pass and branch_status is handled, the recovery action will direct you straight to the guard for transition.