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.

If the user explicitly asks you to skip the subagents, say that a main-session check carries context bias and is not a verification, confirm once, and if they insist do the quick check they asked for — but write nothing to the verification field. Only a subagent run is an outcome.

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

Thought	Reality
"The change is small, I can verify it myself"	Self-verification creates confirmation bias. You saw the implementation — you can't objectively verify it.
"I already reviewed the code during apply"	That's exactly why you need an independent verifier. Familiarity breeds blind spots.
"Running two subagents is overkill for this"	Code quality and spec alignment are independent dimensions. A single agent conflates them.
"I'll just run the tests, that's verification enough"	Tests verify behavior but not spec alignment, design adherence, or code quality.
"The user told me not to dispatch agents, so a quick look counts as verify"	It counts as a quick look. Say so, confirm once, do it — and leave verification unset, so archive still warns that this change was never verified.
"I'll dispatch them sequentially to save context"	They're independent — parallel dispatch is faster and prevents one report from biasing the other.
"The report is delivered, the status.yaml write is just bookkeeping"	The verification field is how archive knows verify ran. Skip it and archive warns "never verified" on a verified change. Ten seconds — write it.

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

2. 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+).

3. 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.

4. 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

5. 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)

6. 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