ADR-0015: PR-gated agent autonomy

Status: Accepted
Date: 2026-07-30
Supersedes: —
Superseded by: —
Amended by: ADR-0018 — the branch-protection consequence below turned out to be unachievable on GitHub’s free tier for private repositories. The rule stands; the enforcement does not exist. Read ADR-0018 before relying on it.

Context

This project is built by agents running the loop in docs/standards/the-loop.md. The question is where human judgement enters.

The failure mode being designed against is confident false completion — an agent reporting success it did not achieve. Automated gates catch a great deal of that, but not everything: a test can be green and the feature still wrong, or the Definition of Done itself can have been subtly rewritten to fit what was built.

Decision

Agents have full autonomy on a branch and no autonomy to merge.

Agents run the entire loop unattended: spec, branch, red tests, implement, verify, document, self-review, open the PR.
Agents never push to main and never merge.
A human reviews the PR — with the gate output and the ticked Definition of Done as evidence — and merges.

Rationale

Branch work is cheap and reversible; merging is neither. Placing the human at exactly one point buys review of the thing that matters while leaving the expensive, repetitive work fully automated.

Reviewing a PR that arrives with a green gate and per-line DoD evidence is fast. Reviewing every loop stage is not, and would make the human the bottleneck — losing most of the value of looping.

Consequences

Branch protection on main: no direct pushes, PR required, gate must pass. ⚠️ Not actually enforceable — see ADR-0018. A committed pre-push hook mitigates accidents; nothing prevents a deliberate push.
The PR body is the review surface, so its quality is load-bearing. The template (.github/pull_request_template.md) requires gate output and DoD evidence per line, not adjectives.
Work items must be small enough to review in one sitting. Anything larger gets split — this is the real constraint on work item sizing.
Combined with the stop conditions in the loop, an agent that cannot proceed halts and asks rather than merging something uncertain.

Revisiting

Auto-merge on green CI becomes reasonable once the gate genuinely covers the ground — realistically after M1, when the schema and domain model have settled. That would be a superseding ADR, not an informal change of practice.

Alternatives considered

Auto-merge on green CI. Fastest throughput. Rejected for now: the gates would carry all the weight while the domain model is still moving.

Approval at each loop stage. Catches drift earliest. Rejected: makes the human the bottleneck and forfeits the point of looping.