# Gate failures

When the [Verification Gate](/docs/verification-gate) stays red, the run ends as
**`verify_failed`** and AM opens a **draft** PR marked *needs work* with the
failing output attached. There are two very different causes.

## 1. Real failure — the change is wrong

The agent's work genuinely doesn't pass your tests/lint. AM already tried to fix
it (bounded fix loop) and couldn't. Review the draft PR's output, then either:

- Refine the [focus](/docs/focus) and re‑run, or
- Take over the draft branch yourself.

## 2. Environment failure — the gate can't even run

The verify command fails to *start* — missing toolchain, no virtualenv, a path
that doesn't exist in a fresh worktree. AM detects this as an **environment**
problem (not a code failure) and records a [memory](/docs/memory) lesson so the
next run accounts for it.

Common signs: *command not found*, *no such file or directory*, *failed to run the
interpreter*, references to a `.venv` or toolchain that isn't set up.

**Fix the gate to be env‑clean:**

- Run from the repo root with **relative paths only** — no `cd /abs/path`.
- Let it set up its own environment (`npm ci`, `cargo build`, create/activate a
  venv inside the command) rather than assuming one exists.
- Or switch to a lighter gate (e.g. `cargo fmt --check` instead of a full build).
- **Keep the gate to pass/fail commands — don't bolt on reporting tools the
  worker may not have.** A common trap is coverage tooling: `go test -cover` /
  `go tool cover` / `covdata` can fail with *covdata: tool not found* even when
  every test passed, marking the run `verify_failed` for no real reason. Coverage
  in a gate that doesn't assert a threshold adds nothing — use plain
  `go test ./...`. (Same idea for any lint/coverage extra that isn't gating.)

## Why drafts, not silent failure

A red gate never produces a merge‑ready PR — but you still get the work as a draft
so nothing is hidden. That's the [core promise](/docs/how-it-works): *done =
verified*, and unverified work is clearly labelled.

## Related

- [The Verification Gate](/docs/verification-gate) · [Memory](/docs/memory)
- [Reading a run](/docs/reading-runs)