verify

Verify implementation against change artifacts across five dimensions. Uses independent subagents to eliminate context bias.

<decision_boundary>

Use for:

• Validating implementation completeness against spec artifacts before archive
• Verifying distilled specs match current code behavior (accuracy mode, source: distill)
• Independent verification via subagents to catch context bias
• Surfacing living-doc drift (Layer 1/2/3) as advisory findings

NOT for:

• Creating or modifying spec artifacts (use /beat:design)
• Writing tasks (use /beat:plan)
• Running implementation (use /beat:apply)
• Archiving the change (use /beat:archive)

Trigger examples:

• "Verify the change" / "Check implementation against spec" / "Run verification"
• Should NOT trigger: "design a feature" / "implement the change" / "archive it"

</decision_boundary>

<HARD-GATE> You MUST dispatch independent subagents for verification — NEVER verify implementation yourself in the main session. The main session has context bias from the conversation history.

Dispatch the verification subagent AND code-reviewer in parallel — they are independent checks.

If a subagent fails, proceed with findings from the other. If BOTH fail, report the failure — do NOT fall back to self-verification.

After presenting the combined report: you MUST record the outcome in the top-level verification field of status.yaml (see step 6). If verification could not run at all (both subagents failed), do NOT record — a failed run is not a verification outcome. </HARD-GATE>

Rationalization Prevention

Red Flags — STOP if you catch yourself:

• Verifying any dimension yourself instead of dispatching a subagent
• Dispatching subagents sequentially instead of in parallel
• Skipping code-reviewer because "the code is simple"
• Claiming verification passed without reading the subagent reports
• Editing code or artifacts during verification (the ONLY write is the verification record in status.yaml)
• Presenting the report without recording the outcome in status.yaml
• Falling back to self-verification because a subagent failed

Process Flow

digraph verify {
    "Select change" [shape=box];
    "Read artifacts +\ntesting context" [shape=box];
    "Parallel dispatch" [shape=box, style=bold];
    "Verification\nsubagent" [shape=box];
    "Code-reviewer\nsubagent" [shape=box];
    "tests available?" [shape=diamond];
    "Run automated tests" [shape=box];
    "Present combined report" [shape=box];
    "Record verification\nin status.yaml" [shape=doublecircle];

    "Select change" -> "Read artifacts +\ntesting context";
    "Read artifacts +\ntesting context" -> "Parallel dispatch";
    "Parallel dispatch" -> "Verification\nsubagent";
    "Parallel dispatch" -> "Code-reviewer\nsubagent";
    "Verification\nsubagent" -> "tests available?";
    "Code-reviewer\nsubagent" -> "tests available?";
    "tests available?" -> "Run automated tests" [label="yes"];
    "tests available?" -> "Present combined report" [label="no"];
    "Run automated tests" -> "Present combined report";
    "Present combined report" -> "Record verification\nin status.yaml";
}

Input: Optionally specify a change name. If omitted, infer from context or prompt.

Steps

1. Select the change

If no name provided:

• Look for beat/changes/ directories (excluding archive/)
• If only one exists, use it
• If multiple exist, use AskUserQuestion tool to let user select

1. Read all artifacts and determine testing context

Read from beat/changes/<name>/:

• status.yaml (schema: references/status-schema.md)
• features/*.feature (all Gherkin files, if gherkin status is done)
• proposal.md (if exists)
• design.md (if exists)
• tasks.md (if exists)

Read beat/config.yaml (if exists, schema: references/config-schema.md).

Determine drive mode:

• If gherkin status is done → Gherkin-driven verification
• If gherkin status is skipped → Proposal-driven verification

Determine testing context (three-layer priority: tag > source > config):

• Config layer: Is testing.required set to false? If yes, skip test existence checks globally.
• Source layer: Does status.yaml contain source: distill? If yes, Dimension 1 switches to accuracy mode (see below).
• Tag layer: Every scenario in a .feature file is expected to have a corresponding test (in TDD mode).
• Modified files: Does status.yaml have gherkin.modified? If yes, collect the listed paths and their .feature.orig backup paths — the verification subagent needs them for semantic verification (Dimension 1B+).

1. Dispatch verification subagent AND code-reviewer in parallel

Launch BOTH agents simultaneously using a single message with two Agent tool calls:

Agent A — Verification subagent (subagent_type: Explore): Read verification-subagent-prompt.md for the complete subagent prompt.

Provide ONLY:

• All artifact contents (features, proposal, design, tasks)
• Testing context (drive mode, testing config, source flag, tag counts)
• Modified files list from gherkin.modified with their .feature.orig backup paths (if any)
• Do NOT pass conversation history or session context.

Agent B — Code quality review (subagent_type: general-purpose): Read code-reviewer-prompt.md for the complete subagent prompt.

Provide:

• The change name and description (from proposal or status.yaml)
• List of files created/modified during apply
• The planning document (tasks.md or proposal.md) as the "original plan"
• The git range (base..head SHAs) if available, so the reviewer can read the diff

This reviews: code quality, architecture, naming, error handling, test quality, security, and plan alignment. Its output is Dimension 4, classified in Beat's CRITICAL/WARNING/SUGGESTION vocabulary.

Fallback: If one agent fails, proceed with the other's findings. If BOTH fail, report failure — do NOT self-verify.

1. Run automated tests if available

Detect and run the project's test suite:

• Behavior tests: run using testing.behavior framework (or auto-detect)
• E2E tests: run using testing.e2e framework (or auto-detect). If beat/changes/<name>/features/ contains feature files, combine BDD feature paths: beat/features/ + beat/changes/<name>/features/
• Report behavior and e2e results separately

1. Present combined verification report

Combine both subagent reports:

• Dimensions 1-3 from verification subagent (spec alignment)
• Dimension 4 from code-reviewer (code quality)
• Dimension 5 from verification subagent (living docs sync — Layer 1/2/3, advisory only)
• Step 4 test results (if available)

1. Record the outcome in status.yaml

Read beat/changes/<name>/status.yaml (read before write — preserve existing fields), then set the top-level verification field per references/status-schema.md:

   verification: { status: passed, critical: 0, date: YYYY-MM-DD }

• status: passed when zero CRITICAL findings; issues-found otherwise
• critical: the CRITICAL count from the combined report, including failing automated tests from step 4
• Do NOT advance phase — verification outcome lives only in this field
• Skip recording entirely if verification could not run (both subagents failed) — report the failure instead

This is the only file verify writes. /beat:archive uses it to warn when archiving an unverified change. Re-running verify after fixes overwrites the field.

Issue Classification

• CRITICAL: Must fix (missing scenario test [in coverage mode], inaccurate scenario [in accuracy mode], unimplemented goal, design violation, security vulnerability, failing automated test from step 4)
• WARNING: Should fix (partial coverage, possible divergence, non-executable test, Gherkin quality issues, code quality concerns, living-doc drift — Layer 1/2/3 sync gaps)
• SUGGESTION: Nice to fix (pattern inconsistency, minor improvement, missing test in distill mode, module without README)

Dimension 5 is advisory — its findings classify as WARNING or SUGGESTION only, never CRITICAL. The user decides whether to act before archiving; living-doc drift never blocks the archive.

Graceful Degradation

• Gherkin skipped: skip Dimension 1, strengthen Dimension 2 (proposal alignment)
• Only features exist: verify Gherkin coverage only
• Features + proposal: verify coverage + alignment
• Features + proposal + design: verify all five dimensions (Dimension 5 only when living docs exist)
• Always note which checks were skipped and why