Verify & Fix

The verification gate is available after every stage. forge-verify analyzes the current stage’s artifacts for completeness, consistency, and quality, then writes a findings document. forge-fix applies those findings. It’s optional but recommended — especially before Stage 4 and Stage 5.

Verify

/feature-forge:forge-verify <feature-name> [stage]

stage is one of prd, tech, specs, backlog, impl, or epic. If you omit it, the stage is auto-detected from the pipeline state.

What it produces: a findings document at specs/<feature>/.verification/VERIFY-<stage>-<date>.md containing a list of findings and a Fix Execution Plan. The pipeline state records the findings file and count. Findings are categorized by severity:

• gap — missing coverage.
• inconsistency — two artifacts contradict each other.
• improvement — correct, but could be better.
• error — factually wrong.

For large stages (specs, backlog, impl) the checks fan out across parallel verifier instances. Backlog verification also runs the loop runner’s own validate command; specs verification runs a deterministic traceability check.

Fix

/feature-forge:forge-fix <feature-name>

forge-fix reads the most recent findings document and applies its Fix Execution Plan step by step. It:

• prompts you for any “User Decisions Required” items before executing dependent steps;
• verifies each change after applying it;
• tracks progress in the findings document, so an interrupted run can resume without redoing applied steps;
• stops on the first failed step rather than continuing blindly.

Auto-verify

By default you invoke forge-verify yourself, or accept the navigator’s offer to run it. Because verification is clean-room by construction — it runs in a fresh subagent that inherits none of your session’s context — and is rarely worth skipping, you can make it automatic.

Three forge.config.json keys control it (all default off, fully backwards-compatible):

Key	Default	Effect
autoVerify	false	When true, the navigator runs forge-verify automatically after a stage completes — no prompt. It dispatches the fresh subagent and returns only a compact findings digest to your session.
autoVerifyStages	{}	Per-stage overrides, e.g. {"forge-1-prd": false}. The effective value for a stage is autoVerifyStages[stage] if present, otherwise autoVerify. Keys must be one of the five verify-capable stages (forge-1-prd, forge-2-tech, forge-3-specs, forge-4-backlog, forge-5-loop); a typo is reported, not silently ignored.
autoFix	false	When true, chains forge-fix after an auto-verify that finds issues — but only when auto-verify is on for that stage and preconditions hold.

Unconfigured opt-in. With autoVerify unset, the navigator’s advance gate adds an “Auto-verify now” option (recommended). Choosing it runs verify immediately, then asks once whether to persist autoVerify: true to your config — no silent config writes.

Freshness. Auto-verify keys off a version ledger: a verify is considered fresh only while the stage artifact’s version matches what was verified. Revise or hand-edit an artifact and the navigator re-verifies it; leave it unchanged and it won’t needlessly re-run.

Clean-room guarantee. Auto-verify runs unattended only when the fresh forge-verifier subagent can be dispatched. If it can’t (partial install, or a non-Claude host), auto-verify never falls back to running inline in your session — it degrades to the manual verify gate. Verify state stays outstanding, so a stage is never marked verified or advanced on false assurance.

Caution

autoFix is a power-user opt-in: it mutates artifacts without a human read. It’s honored only when auto-verify is on for the stage, and even then only when the findings document has zero unresolved decision points, the working tree is clean, and a mandatory re-verify passes. Any miss — decisions required, a dirty tree, an early stop, or a red re-verify — falls back to the findings digest + prompt. It never applies a silent partial fix.

The loop

A typical gate cycle:

1. forge-verify <feature> → review the findings document.
2. forge-fix <feature> → apply the fixes.
3. forge-verify <feature> again → confirm the issues are resolved.

After applying fixes, forge-fix offers its own one-shot re-verify gate — so step 3 is usually a prompt you accept in place, not a command you retype. The manual re-run above is the fallback when you decline that gate or come back to it later.

Then continue the pipeline. Check overall status anytime with the dashboard.

Notes

• Run forge-verify before forge-fix — forge-fix needs a findings document to apply.
• Verification is read-and-report; it doesn’t change your artifacts. forge-fix is what edits them.
• When the verification or fix touches a stage, re-running the relevant stage may be appropriate if findings are structural.