Verification & Retries

The verification gate is what makes Merlin different from a "shell out to an LLM and pray" agent. Tasks aren't reported complete until verification passes.

The Gate

When verify_before_complete = true (the default), after the LLM finishes a turn that does not request more tool calls, the agent:

1. Transitions to AgentState::Verifying.
2. Runs fledge lanes run verify --ni.
3. Emits an AgentEvent::VerifyResult { success, output }.
4. If verification passed, transitions to Reporting, saves a memory, and returns a TaskResult { verified: true, ... }.
5. If verification failed, the verifier's stdout/stderr is fed back to the LLM as a user message:

   Verification failed. Fix these errors and try again:

6. The loop continues -- same task, but the LLM now sees the failure.

Retry Limit

Verification failures consume retries, bounded by max_retries (default 3). If retries exceed the limit, run_task returns an error containing the last verifier output, and the CLI exits non-zero.

What's in the Verify Lane

By default, fledge.toml configures:

[lanes.verify]
steps = ["fmt-check", "lint", "test", "integration-test", "spec-check"]

Step	Tool	What it catches
fmt-check	cargo fmt --all -- --check	Formatting drift
lint	cargo clippy --workspace -- -D warnings	Lint violations
test	cargo test --workspace --lib --bins	Unit + binary tests
integration-test	cargo test --test integration_agent -p merlin-core	End-to-end agent loop tests
spec-check	fledge spec check	Stale specs, missing required sections, drift between specs and code

You can add or remove steps; the agent always runs the full lane.

Disabling Verification

For quick prototyping or when you trust the LLM more than the lane:

merlin --no-verify "scratch some experimental code"

TaskResult.verified will still be true in this case (verification was skipped, not failed), but no gate was applied. Don't ship code this way.

Manual Run

Inside the REPL, /verify runs the lane on demand. Useful when you've made manual changes and want to know if they pass before asking the agent to continue.

Implementation

See Agent::run_verification in crates/merlin-core/src/agent.rs. The internal VerifyOutcome enum (Passed, FailedRetrying, Cancelled) keeps the run_task loop body declarative.