automaintainer/ docs
Dashboard →

Gate failures

When the 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 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 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: done = verified, and unverified work is clearly labelled.