Auto Drive To Merge
Build the thing, satisfy the maintainer's proxy, satisfy every merge-ready criterion, then merge. Three phases, two loops, one gate.
flowchart TD
A[task] --> P0{criterion 1 needs gadugi?<br/>Node repo, or AUTODRIVE_QA_SCENARIO_DIR}
P0 -->|no: Rust CLI, Python| B[Phase 1: BUILD<br/>default-workflow, no_merge=true]
P0 -->|yes| P{gadugi-test on PATH?}
P -->|no| STOP0[stop: gadugi-test-not-installed]
P -->|yes| B
B --> C{PR exists?}
C -->|no| STOP1[stop: nothing to review]
C -->|yes| D[Phase 2: CRUSTY LOOP]
D --> D1[crusty-old-engineer reviews the PR]
D1 --> D2[structured verdict:<br/>CLEAN / MINOR_ONLY / CONCERNS]
D2 -->|CONCERNS: any blocking, major<br/>or unknown severity| D3[address every concern, commit, push]
D3 --> D4[loop-health-evaluator]
D2 -->|CLEAN| D4
D2 -->|MINOR_ONLY: every finding minor| D4
D4 -->|CONTINUE| D1
D4 -->|STUCK| STOP2[stop + escalate<br/>nothing merged]
D4 -->|DONE + verdict CLEAN or MINOR_ONLY| D5[file one follow-up issue<br/>per minor finding, linked to the plan task]
D5 -->|cannot file| STOP4[stop: followup-create-failed<br/>or followup-task-unresolved<br/>not READY, nothing merged]
D5 -->|filed, or none to file| E[Phase 3: MERGE-READY LOOP]
E --> E0[code commits since the clean crusty round?<br/>re-run the crusty loop at phase 2's depth]
E0 --> E1[sync base, run the repository's tests<br/>and, where required, gadugi scenarios,<br/>wait for CI to a terminal state]
E1 --> E2[merge-ready skill criteria]
E2 --> E3[structured verdict:<br/>MERGE_READY / NOT_MERGE_READY]
E3 -->|NOT_MERGE_READY| E4[clear blockers, commit, push]
E4 --> E5[loop-health-evaluator]
E3 -->|MERGE_READY| E5
E5 -->|CONTINUE| E0
E5 -->|STUCK| STOP2
E5 -->|DONE + verdict MERGE_READY| E6[file follow-ups from crusty re-reviews]
E6 --> F[MERGE GATE]
F --> F1{every criterion re-verified<br/>in THIS run, bound to ONE sha?<br/>every minor finding has a follow-up issue?}
F1 -->|no| STOP3[NOT_MERGED + evidence bundle]
F1 -->|yes| G[gh pr merge --squash --delete-branch<br/>--match-head-commit sha]
G --> H{platform confirms MERGED?}
H -->|no| STOP3
H -->|yes| I[MERGED]
Prerequisites
| Tool | Why | Install |
|---|---|---|
gadugi-test, only where criterion 1 needs it |
Merge-ready criterion 1 follows qa-team's repo-type table. A Node repository runs its qa-team scenarios with gadugi-test. So does any repository where the operator sets AUTODRIVE_QA_SCENARIO_DIR. A Rust CLI repository runs cargo test, a Python repository runs pytest, and neither needs gadugi-test. autodrive_gadugi_required in autodrive_trust.sh makes this decision for every step. Where gadugi-test is needed, amplihack install does not install it, and no agent can. The recipe's first step, autodrive-prerequisites, stops the run with ERROR: gadugi-test-not-installed before the build when it is missing, so the missing tool costs seconds rather than a build and a crusty loop. The install is pinned to the gadugi-agentic-test commit auto-drive was tested with, because auto-drive depends on how gadugi-test 1.0.x behaves: one --scenario per run (gadugi-agentic-test #207) and a scenario decided by its commands' exit codes alone. |
npm install -g github:rysweet/gadugi-agentic-test#6c120657798995b1b53399a5acf3693d418a2d8b |
gh, authenticated |
Platform facts, CI, review threads and the merge itself. | GitHub CLI |
Invoking it
# From a task description — builds the PR, then drives it.
amplihack recipe run auto-drive-to-merge \
-c task_description="Add rate limiting to the public API" \
-c repo_path=/home/user/src/myproject
# Against a PR that already exists — phase 1 becomes a no-op.
amplihack recipe run auto-drive-to-merge -c pr_number=1234 -c repo_path=.
# Verify everything, report what it WOULD merge, merge nothing.
amplihack recipe run auto-drive-to-merge -c pr_number=1234 -c autodrive_dry_run=true
| Context var | Default | Meaning |
|---|---|---|
task_description |
"" |
What to build. Passed to default-workflow. Also the last place the plan task id is looked for (Closes #N, Fixes #N or Resolves #N). |
plan_task_id |
"" |
The plan task each follow-up issue is linked to, such as 1979, #1979 or plan/17.104. When empty, the first Closes #N, Fixes #N or Resolves #N in the PR body is used, then the same in task_description. Needed only when minor findings are filed. |
requirements |
"" |
Extra requirements, passed through. |
repo_path |
. |
Repository to work in. |
existing_branch / pr_number |
"" |
Point the workflow at work that already exists. Whether the PR came from pr_number or from phase 1, every evidence step runs in the worktree that has the PR branch checked out, and the run refuses if no worktree, or more than one, has it checked out, or that worktree is not at the PR head (see PR head and worktree resolution). |
autodrive_state_dir |
derived | Durable state root for resumability. |
autodrive_dry_run |
"false" |
Verify everything, merge nothing. Files no follow-up issue, so a drive with minor findings ends NOT_MERGED with followup-missing:<id>. |
autodrive_budget_loop_rounds |
12 |
Rounds either loop may run in total, across every run on the same state directory. 0 or empty means unlimited. |
autodrive_budget_total_rounds |
20 |
Rounds both loops together may run. 0 or empty means unlimited. |
autodrive_budget_wall_seconds |
14400 |
Seconds that rounds, before-round steps and evaluator runs may take in total. 0 or empty means unlimited. |
Why there is no iteration cap
Neither loop has a max_rounds or a backstop integer.
An integer cap fails in both directions: it cuts off the round that was about
to converge, and it lets a genuinely stuck loop burn the whole budget before
the counter fires. The signal worth acting on is absence of progress, not
number of attempts — a loop on round 2 that produced nothing twice is stuck; a
loop on round 12 that is still resolving findings is fine.
So each round ends with the loop-health-evaluator contract (issue #1337),
which stops and looks at the measured data — what the round actually produced,
which findings are new / recurring / resolved, whether test and CI signals
moved — and answers CONTINUE, DONE, or STUCK.
Two stops are decided in code before the evaluator runs, and only for a round that is not clean:
- No progress. When the PR head SHA, the sorted set of open items and the
CI signal are all the same as in the loop's previous round, and CI is not
still pending, the loop stops as
STUCKwithout asking the evaluator. Open items are crusty's findings for the crusty loop and the merge round's blockers for the merge-ready loop. - Usage budget. Each run has a cost ceiling set by the operator, in rounds
per loop, total rounds and wall seconds. When a limit is reached the loop
stops as
BUDGET_EXHAUSTED, which is never success. The budget is checked again before every round, so an exhausted run starts no agent. Relaunching with a higher limit, for example-c autodrive_budget_loop_rounds=20, resumes from the recorded round.
The budget is not the convergence terminator: a loop still ends DONE only
through the evaluator, and there is still no iteration cap on convergence. See
No-progress stop and usage budget.
Host safety was never this workflow's job and still is not. It is enforced
structurally one layer down by #1327 (sealed recursion ceiling) and
#1332 (width cap + free-memory floor), both refusing with exit code 79
before a child runs. Rounds here run sequentially at constant session
depth — each child inherits the same AMPLIHACK_SESSION_DEPTH — so a long
loop never walks toward that ceiling. No round recipe starts a loop: when
commits made after the clean crusty round need crusty again, the merge-ready
loop runs the crusty loop before its next round, from its own shell, at the
depth phase 2's crusty loop runs at. Started from inside a merge round, that
loop would be one recipe runner deeper and refused with exit 79. AMPLIHACK_MAX_DEPTH is propagated
untouched and is never raised; the loop driver aborts if it changes.
Structured verdicts only
No phase advances on a model's prose impression. Every gate reads a structured
field through the repo's canonical pipeline
(extract-json --require-field … | extract-field --default …, see
Structured Verdict & Intent Parsing),
matched against an exact-token allow-list:
| Signal | Field | Clean token | Fail-safe default |
|---|---|---|---|
| Crusty review | crusty_verdict |
CLEAN; MINOR_ONLY also ends the crusty loop |
CONCERNS |
| Merge-ready assessment | merge_ready_verdict |
MERGE_READY |
NOT_MERGE_READY |
| Loop health | loop_verdict |
DONE |
STUCK |
A missing or unparseable verdict is never the permissive one. A verdict
that cannot be read means "we do not know", and "we do not know" does not
advance a phase and does not merge.
--require-field selects the last JSON object carrying the field rather
than the first parseable object of any shape. Without it a reviewer that quotes
its own output contract — a ```json example of a CLEAN verdict — hands
that example to the parser instead of its real verdict, and nothing downstream
re-measures crusty's judgement the way phase 3 re-measures CI.
Minor findings end the crusty loop
Crusty emits CLEAN or CONCERNS. When a CONCERNS verdict lists at least
one finding and every finding is a valid minor one, the round recipe records
MINOR_ONLY, skips the address and fix-check steps, and the loop may end on
it as on CLEAN. The findings are not dropped:
- Before the
crusty-loopmarker is written, the loop files one follow-up issue for each minor finding withgh issue create. The issue names the plan task id and the finding id, and its number is recorded infollowups.tsvin the drive's state directory. - Minor findings from crusty re-reviews in the merge-ready loop are filed the same way, just before the merge gate.
- The merge gate refuses to merge with
ERROR: followups-unfiledwhile any minor finding has no recorded issue. A drive whose issues cannot be filed is never READY. - Merging the PR closes the plan task's issue when the PR body says
Closes #N, while its follow-up issues stay open. So when the task is an issue, the drive posts one comment on it listing the follow-ups, and the merge gate refuses (followup-parent-uncommented) until that comment is recorded. Auto-drive files and lists the follow-ups; it does not track them to completion.
A finding counts as minor only when its severity is exactly minor, its id
is valid and was never major in an earlier round, and neither the id nor its
text names a security subject such as secrets, tokens, injection,
authentication or permissions. A minor finding that recurs as minor does not
keep the loop running; a major one downgraded to minor does. A missing or
unknown severity counts as major. Any blocking or
major finding keeps the round CONCERNS, and the loop continues as before.
See Minor findings end the crusty loop.
A MERGE_READY verdict is additionally downgraded by measurement: if the
recorded qa_status is not PASS, ci_status is not GREEN, a conflict is
present, or review threads are unresolved, the verdict becomes
NOT_MERGE_READY regardless of what the assessment said.
Two absolute prohibitions
- Never skip hooks on a commit. No
--no-verify, no-nshorthand, on any commit this workflow makes. If a hook fails, fix what it is complaining about. - Never bypass branch protection. No
--adminongh pr merge, and no other bypass of required checks, required reviews, or the strict up-to-date policy. If a check fails, fix the cause.
These are not advice. The merge gate builds its gh argv as a fixed literal
list and accepts no flags from any caller, so there is no argument through
which a bypass could be threaded. A guard test
(forbidden_flags_never_appear_in_an_executable_position) fails the build if
either string ever shows up in an executable position anywhere in this
workflow's recipes, tools, or skill.
No silent merge
The merge gate does not trust the loop that preceded it. In the run that
merges, it re-verifies — and writes down, before merging — the head SHA, draft
state, mergeability and merge-state, review decision, unresolved review
threads, the full CI rollup, the qa-team evidence, and the merge-ready round
record. It also checks, without a network call, that every minor crusty
finding has a filed follow-up issue. Everything is bound to one head SHA, and the merge itself passes
--match-head-commit, so GitHub refuses the merge if the head moved after the
evidence was captured.
An unreadable criterion is a failure, never a pass. Unreadable CI, zero
reported checks, unreadable review threads, missing qa-team evidence, an
absent round record — each is a blocker. After the merge, the platform must
confirm MERGED; a gh success that the platform does not confirm is
reported as not merged.
Merges outside the gate are refused
Only autodrive_merge_gate.sh merges. Auto-drive runs with a gh shim first
on PATH that refuses gh pr merge, the merge API and the GraphQL merge
mutations with exit 3, unless its direct parent is the installed gate run as
/bin/bash -p from a clean environment. Agents are told the same in an
[amplihack:no-merge] line. The runner's BASH_ENV file puts the shim back
first after a shell profile reorders PATH, and the pre-tool-use hook refuses
gh pr merge and gh api on a merge endpoint by program word. Leave the PR
open. A PR found MERGED after phase 1 or phase 2 ends the run with exit 1.
Deliberate evasion with the same token (curl, a script file, an alias) is a
non-goal: branch protection is the boundary and the MERGED checks the backstop
(details).
The parent check needs Linux /proc and a root-owned /bin/bash, so
amplihack recipe run stops an auto-drive run at launch on macOS or without
/bin/bash, before any phase runs
(#1646).
Exit code 79 is terminal
Exit 79 (and BLOCKED_TERMINAL) is a final answer from a structural guard,
not an infrastructure hiccup. It is surfaced, it stops the run, and it is
never retried into — not at a deeper level, not with a raised ceiling. The
loop driver propagates 79 as its own exit code so a parent sees the refusal
rather than a generic failure.
Resumability
A run that dies partway is re-runnable. Nothing merged is redone and no resolved concern is reopened:
- The platform is the authority on whether the PR is merged. A merged PR short-circuits every phase.
- An open PR for the branch makes phase 1 a no-op — it is never rebuilt.
- Completed phases are recorded in
${AMPLIHACK_STATE_DIR:-~/.amplihack/state}/auto-drive/<key>/, written only by the host that ran them. There is deliberately no pull-request-comment ledger: a PR comment is writable by anyone who can comment, and a forged one could mark the crusty loop complete or seed the resolved-concern list, skipping the review entirely on a fresh host. A fresh host redoes the phase instead — that is the cheaper mistake. - Concern ids that a previous run resolved and had confirmed clean by a later round are handed back to crusty, which may still re-raise one — but only with new evidence.
Local state is a cache, never a claim. The merge gate re-verifies everything regardless of what any state file says.
No short timeouts
No step in this workflow declares a timeout or timeout_seconds, and no
recipe declares a default_step_timeout. CI polling waits on a 60-second
interval until CI reaches a terminal state or becomes unreadable — bounded by
the build finishing, not by a stopwatch. Test suites, builds, and model calls
run to their natural end. A false timeout costs more than a slow run.
What it composes
| Piece | Role |
|---|---|
default-workflow |
Phase 1: builds and publishes the PR. |
crusty-old-engineer |
Phase 2 reviewer, standing in for the maintainer. Emits the opt-in structured verdict. |
merge-ready |
Phase 3 criteria and guardrails. |
qa-team |
Outside-in scenarios that must actually run and pass. |
loop-health-evaluator |
The agentic terminator for both loops (issue #1337, PR #1347). |
Recipes and tools
| File | Role |
|---|---|
amplifier-bundle/recipes/auto-drive-to-merge.yaml |
Thin composer over the three phases. |
amplifier-bundle/recipes/autodrive-build.yaml |
Phase 1. |
amplifier-bundle/recipes/autodrive-crusty-round.yaml |
One crusty round. |
amplifier-bundle/recipes/autodrive-crusty-loop.yaml |
Phase 2 loop. |
amplifier-bundle/recipes/autodrive-merge-evidence.yaml |
Measured evidence for one merge round. |
amplifier-bundle/recipes/autodrive-merge-round.yaml |
One merge-ready round. |
amplifier-bundle/recipes/autodrive-merge-loop.yaml |
Phase 3 loop + merge gate. |
amplifier-bundle/tools/autodrive_loop.sh |
The uncapped, agentically-terminated loop driver. |
amplifier-bundle/tools/autodrive_merge_gate.sh |
The evidence gate and the fixed merge argv. |
amplifier-bundle/tools/autodrive_followups.sh |
Classifies minor-only rounds, files the follow-up issues and lists them on the plan task issue. |
amplifier-bundle/tools/autodrive_followups_check.sh |
The check and gate commands: the merge gate's offline follow-up check. |
amplifier-bundle/tools/autodrive_finding_rules.sh |
The minor-finding rules and text sanitising used by autodrive_followups.sh, for auto-drive-to-merge and auto-drive-light alike. |
amplifier-bundle/tools/autodrive_state.sh |
Resumable local state; platform truth for merged-ness. |
Full reference: Auto Drive To Merge.