# The Verification Gate

The Verification Gate is what separates Automaintainer from a slop machine.
**No change becomes a merge‑ready PR until it passes an objective check you
define.** It's the product's core promise: *done = verified, not just written*.

## Set the gate

In **Repo settings → Verify command**, set a shell command that exits `0` only
when the work is correct. Examples:

```bash
npm ci && npm run test:unit
cargo test
pytest -q
go test ./... && go vet ./...
ruff check . && pytest -q
```

## How it runs

1. Agents implement and commit.
2. AM runs your `verify_cmd` **from the repo root** in the run's worktree.
3. **Pass (exit 0)** → push + open a normal PR.
4. **Fail** → a fixer agent attempts a repair and AM re‑verifies, up to a small
   iteration cap (with no‑progress and identical‑error guards). If it's still red,
   the PR opens as a **draft** marked *needs work*, with the failing output
   attached — so you see the work without it pretending to be ready.

## Writing a good gate

- **Run from the repo root, relative paths only.** Each run uses a fresh
  worktree; absolute paths and `cd /some/abs/path` will not exist. Don't prefix
  with `cd`.
- **Be self‑contained / env‑clean.** Prefer commands that set up their own env
  (`npm ci`, `cargo build`) over ones that assume a pre‑activated venv or a
  globally‑installed toolchain.
- **Fast and decisive.** A focused unit‑test or lint command beats a 30‑minute
  full suite for cadence.
- **Real signal.** It should *fail* when the work is wrong — a gate that always
  passes verifies nothing.

> **Gotcha — environment failures.** If the gate can't even start (missing
> toolchain, no venv), AM recognises that as an *environment* problem, not a code
> failure, and records a lesson in [memory](/docs/memory) so the next run accounts
> for it. Fix the gate to be env‑clean, or use a lighter one.

## Auto‑detection

If you leave the verify command empty, AM tries to detect a sensible default for
common stacks. Setting it explicitly is always more reliable.

## Related

- [How it works](/docs/how-it-works) · [Memory](/docs/memory)
- [Gate failures](/docs/gate-failures)