feat(automerge): refuse auto-merge on non-default bases, with a selftest

[topcoder1]

TL;DR

Auto-merge may now only target the ref a branch ruleset actually protects. Non-default bases refuse by default and need an explicit per-PR opt-in label; a base that is another open PR's head refuses unconditionally. Ships with selftest/test_automerge_base_gate.sh (15 behavioural cases + 8 structural pins), verified non-vacuous against origin/main.

Fleet impact: none for the overwhelmingly common path. A PR targeting the default branch behaves exactly as before and the gate costs zero API calls.

Why this is a gate, not a routing preference

whois-api-llc/wxa-jake-ai#1027 (2026-07-28): a PR opened against another open PR's head branch squash-merged 68 seconds after creation, growing that PR's diff from 6 files to 8 after its 4-round codex review had completed. The human then clicks merge on a diff nobody reviewed.

Branch rulesets are conventionally scoped to the default branch (ref_name: ~DEFAULT_BRANCH), so a feature-branch base has no required status checks and gh pr merge --auto merges on the spot rather than waiting.

That detail is the whole finding. Every other protection in this lane is latency-shaped — the caller-side classification gate, this workflow's own hold read — and silently assumes there is a wait to lose. In #1027 the disarm that would have caught it began 7 seconds after the merge had already landed. Remove the wait and an unguarded arm always wins, which is why "the hold label protects main-targeted PRs" was true only by accident of timing.

Policy

Base	Behaviour
== default branch	unchanged — and costs no API calls
is another open PR's head	refused, not liftable by the opt-in label
any other non-default base	refused unless nonmain_base_optin_label (default auto-merge-nonmain) is present

Opting into a plain integration branch is a routing choice. Opting into rewriting an under-review PR's diff is not one a label should be able to make — hence the asymmetry.

Fail-closed throughout: an unreadable PR listing or label set is an unknown base state and must never read as "no refusal". A refusal revokes an existing arm, and the always() error-revoke now counts a failed base read (a fail-closed read must also disarm a PR armed by an earlier run).

Arm-time re-binding. --match-head-commit binds the arm to the head SHA, but the base, the opt-in label, and whether the base is an open PR's head all mutate without moving that SHA — and opening the parent PR fires no event for the child at all. So the arm re-reads all three immediately before firing, and every pre-arm rejection disarms rather than merely declining to re-arm.

Selftest

selftest/test_automerge_base_gate.sh follows test_automerge_hold_gate.sh conventions exactly: extract the shipped bash from the YAML, execute it against a stubbed gh, assert behaviour and fail-closed contracts. Registered in test_workflow_guards.py so tests-runner.yml enforces it, and documented in selftest/README.md.

15 behavioural cases, including the #1027 replay, the opt-in that must not lift the open-head refusal, exact-match/substring semantics, multi-page listings, and four fail-closed paths. 8 structural pins cover interpolation-freedom, pagination, non-aggregating jq, the same-repo head filter, arm-time re-binding, and "no pre-arm rejection exits without disarming".

Non-vacuity verified: every structural pin fails when run against origin/main's workflow. uv run pytest -q → 46 passed. actionlint clean.

Codex pre-review

Codex rounds: 6. Findings 1–5 fixed; round 6 declined with reasoning:

Round	Finding	Outcome
1	P1 verdict not bound to mutable base/label at the arm	fixed
2	P1 base can become an open PR's head; opening the parent fires no event for the child	fixed (re-list at arm time)
3	P1 pre-arm rejection exits without disarming an existing arm	fixed (disarm_then_exit)
4/5	P2 a stale refusal can revoke a newer run's valid arm	fixed (live-base ownership guard)
6	P1 arm still not atomic with its inputs	declined — no GitHub primitive provides this; the window is now sub-second, down from minutes
6	P2 error-revoke needs the same ownership guard	declined — a failed base gate means the base is unknown, so no ownership claim can be made; that path's documented contract is fail-toward-safety

One deliberate asymmetry is documented inline because it reads like an inconsistency: the pre-arm disarm stays unconditional on a base change (the run holds a live read proving its arm was validated against a base that is no longer current, and a retarget re-gates nothing), while the refusal-revoke skips on a base change (there the verdict is the stale artifact). Also documented inline: why the open-head check is scoped to non-default bases — in a main → release train the default branch is itself an open PR's head, and checking it there would disable auto-merge fleet-wide for the life of that release PR.

Follow-up (not in this PR)

Callers subscribe to [opened, synchronize, reopened, ready_for_review, labeled]. A base retarget emits edited, so a retarget currently fires no run anywhere. Adding edited to caller trigger types is the structural fix for that class; it changes run volume across 44+ callers and belongs in its own change rather than bundled into a security fix.

Auto-merge rationale

Manual merge. PRs to topcoder1/ci-workflows are always manual-merge per fleet policy, and this changes the auto-merge decision path for every @main caller. Opened as a draft with manual-merge. Default behaviour for default-branch PRs is unchanged; the only behaviour change is that non-default bases now refuse without an opt-in — deliberately failing closed.

🤖 Generated with Claude Code

[github-actions]

Coverage Floor — mode: enforce

metric	value
measured	100.0%
floor (current)	99.0%
target	100.0%
last bumped	2026-05-12

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[github-actions]

Risk class: blocked — manual merge required.

This PR touches one of the blocked path categories from .github/risk-paths.yml (Dockerfiles, docker-compose, .github/workflows/**, **/.env*, **/secrets*, infra/, terraform/, k8s/, or the classifier config itself).

Auto-merge is refused by claude-author-automerge.yml. A maintainer should review the diff and click "Squash and merge" themselves.

(This is a policy notice, not a code-quality failure. The classify job itself does not fail — required CI checks remain authoritative for "is the code green.")

[claude]

No issues found. Base-gate logic is fail-closed and consistent (null handling, non-aggregating pagination, exact-match labels, arm re-binding); selftest covers the new branches. Behavior change to refuse non-default bases is the deliberate, documented intent.