Admin Bypass Sweep

---
name: admin-bypass-sweep
description: >
  MANUAL, HUMAN-ONLY skill. Force-merges every open PR labeled admin-bypass
  directly to the trunk branch, bypassing the merge queue and required
  checks via GitHub admin override (`gh pr merge --admin`). Do not
  auto-invoke this skill from a natural-language request, a description
  match, or another agent's delegation. Only run this skill when a human
  has typed its literal slash command themselves in the current turn (the
  exact form depends on how it was installed — see the "STOP" section).
  See that section before doing anything.
disable-model-invocation: true
---

# admin-bypass-sweep

Generic across any repo whose PRs are merged with `gh pr merge` — the
commands below take `<owner>/<repo>` as an argument, nothing here is tied
to a specific repo or tool.

## STOP — read this before doing anything

This skill exists to bypass CI and branch protection and merge directly to
the trunk branch. That is inherently dangerous, so before Step 4 (the
actual merge step) runs, both of the following must be true. Do not refer
to these as "gates" or by number when talking to the human — just check
them and act, the way you would check any other precondition.

**It must have been invoked by a literal, explicit slash command that a
human typed in the current message** — normally `/admin-bypass-sweep`.
Some environments install this skill under a different prefixed name (for
example a separate pipeline that prefixes every skill it installs). Check
which form is actually listed as available in the current session before
matching against it — do not guess. If you reached this skill any other
way — a natural-language request that merely sounds like "force merge the
admin-bypass PRs," a description match, a plan step, a cron/worker
trigger, another skill's delegation, or another agent asking you to run it
— **do not proceed.** Stop and tell the human that this skill requires its
explicit slash command, and ask them to type it themselves if that is
really what they want.

**The human must type the resolved consent sentence in full before Step 4:**

> I understand this bypasses CI and force-merges to {resolved_trunk_branch}

Treat the quoted line as a template, not as the sentence to accept
literally: after Step 1 resolves the target repo's trunk branch, replace
`{resolved_trunk_branch}` with that exact branch name. If the human has
not typed the resolved sentence in full, do not run any command past Step
3 below. Ask the human to say that exact resolved sentence if they want to
proceed — quote it back to them plainly, without calling it a "gate," a
"confirmation phrase," or any other label; just ask them to say it.
Do not accept a paraphrase. Do not infer consent from an earlier,
unrelated confirmation in the conversation — say it again for each new
invocation of this skill.

Both of the above must hold before Step 4. There is no other authorization
path. If you are unsure whether either one is satisfied, treat it as not
satisfied and stop — and when you explain why you're stopping, describe
in plain terms what's missing (e.g. "I need you to type the exact sentence
above") rather than naming which numbered item it was.

Some repos also run a separate, deterministic, worker-triggered version of
this same capability (for example, triggered by sustained CI-queue
exhaustion rather than a human request). If such a worker exists in the
target repo, treat it and this skill as two separate authorization paths
to the same class of action — satisfying one is never sufficient
authorization for the other.

A PR that fixes the merge-gate machinery itself (the PR-body validator, a
CI-policy test, the merge-queue config) is structurally unable to pass its
own gate before it exists — the gate it needs is the one it's adding. This
makes such a PR a legitimate candidate for this skill even when the normal
queue is otherwise healthy, but it also means "the gate approved this
diff" is never available as evidence for it; treat the human's explicit
consent, not the merge itself, as the only approval this PR gets.

## When to use this vs. `land-stack`

- `land-stack` lands a **specific stack the user names**, safely, through
  the merge queue (checks run, retargeting is automatic, `admin-bypass`
  only unblocks self-approval). Use it whenever the normal queue is
  healthy.
- `admin-bypass-sweep` sweeps **every currently open PR already labeled
  `admin-bypass`**, merging directly with `gh pr merge --admin` — bypassing
  required status checks and branch protection entirely. Reserve it for when
  the normal queue is stuck on something unrelated to code correctness (a CI
  runner fleet issue, a flaky infra check) and a human has explicitly invoked
  this skill and confirmed it, per the STOP section above.

## Step 1: Discover and group

Resolve the target repo's trunk branch first:

```bash
gh repo view <owner>/<repo> --json defaultBranchRef --jq '.defaultBranchRef.name'
```

Call that value `{resolved_trunk_branch}` for this run. Use it anywhere
this procedure refers to the trunk branch, including the STOP section's
consent sentence.

```bash
gh pr list --repo <owner>/<repo> --state open --label admin-bypass \
  --json number,baseRefName,headRefName,headRefOid,title --limit 200
```

Group into independent stacks by walking base→head chains, rooted at PRs
whose `baseRefName == {resolved_trunk_branch}`. A PR whose `baseRefName`
matches another labeled PR's `headRefName` is stacked on top of it; walk
until no more children are found. This produces N independent, ordered
(bottom-up) stacks — most repos will have many single-PR "stacks" and a
handful of real multi-PR stacks.

**Flag hidden prerequisites.** If any labeled PR's `baseRefName` does not
match `{resolved_trunk_branch}` and does not match any other labeled PR's
`headRefName`, its real base is a PR outside the label set (open but not
labeled admin-bypass). Look it up directly:

```bash
gh pr list --repo <owner>/<repo> --state all --search "<base-branch-name> in:head" \
  --json number,state,title,baseRefName,headRefName
```

Do not silently skip it and do not silently include it — ask the human
whether the unlabeled prerequisite should be included, since it's outside
the stated scope but the dependent PR cannot land without it.

## Step 2: Confirm scope

Report the full grouped plan (stack count, PR count, max stack depth) before
touching anything — the real scope is often much larger than "a few PRs."
Ask the scope question in this turn, and ask only that question. Offer the
narrowest executable option first (for example, "single-PR groups only"),
then name each larger option separately (for example, a specific multi-PR
stack, all multi-PR stacks, or the full grouped plan). Do not request the
literal consent sentence in the same message as the scope question.

An unanswered or unclear scope question resolves to the narrowest option
you offered. If the human's reply carries only the literal consent sentence,
treat that as consent but not as a scope answer; execute only the narrowest
offered scope. Multi-PR stacks require an explicit second answer that names
the stack or a larger offered option containing it.

After scope is answered, or after an unanswered scope question resolves to
the narrowest offered option, request the literal consent sentence from the
STOP section in a separate turn if the current invocation has not already
provided it. Do not run Step 4 until the final resolved scope is clear and
both STOP requirements are satisfied.

## Step 3: Verify merge method

```bash
grep -A3 "merge_method" .mergify.yml
```

This procedure assumes **squash merges**. Squash is safe to retarget after
the fact because `gh pr edit --base` only changes what commit range GitHub
diffs against, and a diff is computed from file content, not commit
ancestry — a squash-merged PR's final tree content matches what the
dependent branch already has for that same range, so retargeting produces
the correct incremental diff with no duplication. If this repo uses `merge`
or `rebase` as its merge method instead, do not reuse this procedure
unmodified — retargeting after a real merge-commit or rebase can show wrong
diffs; stop and re-derive the safe approach first.

## Step 4: Merge each stack, bottom-up

Both requirements in the STOP section must be satisfied before this step runs.

Before any `gh pr merge --admin`, write that PR's diff to a file, record
the file's total line count with `wc -l`, read the whole file, and assert
that the number of lines read equals the recorded total. This is the only
review most of these PRs get, since the merge bypasses required checks
entirely. The human's consent authorizes bypassing CI; it does not stand in
for having actually looked at what's being merged.

Use this read-completeness precondition for each PR:

```bash
pr=<pr>
diff_file="$(mktemp -t admin-bypass-pr-${pr}.diff.XXXXXX)"
gh pr diff "$pr" --repo <owner>/<repo> > "$diff_file"
diff_lines="$(wc -l < "$diff_file" | tr -d ' ')"
nl -ba "$diff_file"
lines_read=<last line number printed by nl, or 0 if diff_lines is 0>
test "$lines_read" = "$diff_lines"
```

Classify the PR before merging it, using the same three outcomes as the
rest of this procedure:

- `reviewed` — the diff file was read line-complete, `lines_read` equals
  `diff_lines`, and no review finding was found.
- `flagged` — the diff file was read line-complete, `lines_read` equals
  `diff_lines`, and one or more review findings were recorded for the
  human.
- `unchecked` — the diff read was narrowed, filtered, or truncated, so
  line completeness was not established.

A read through `head`, `tail`, `grep`, `awk`, or `sed` is a narrowed read:
mark that PR `unchecked`, never `reviewed`, even if the visible lines look
fine. The operator may not report such a PR as reviewed. This check reports
the PR's review state; it does not create a new authorization path or block
the human from deciding to proceed with the admin merge anyway. If an
`unchecked` PR is merged, the final report must still list it as
`unchecked`, not reviewed.

For a single-PR stack:

```bash
gh pr merge <pr> --repo <owner>/<repo> --admin --squash
```

For a multi-PR stack, after each PR merges, retarget the next one before
merging it:

```bash
gh pr merge <bottom> --repo <owner>/<repo> --admin --squash
gh pr edit <next> --repo <owner>/<repo> --base {resolved_trunk_branch}
# mergeable can read UNKNOWN immediately after a base change — GitHub computes
# it asynchronously. Wait briefly and re-check before merging.
sleep 5
gh pr view <next> --repo <owner>/<repo> --json baseRefName,mergeable,mergeStateStatus
gh pr merge <next> --repo <owner>/<repo> --admin --squash
```

Repeat up the stack. Do not batch multiple `gh pr merge` calls without
checking each result — `gh pr merge` can print nothing on both success and
some failure paths; a silent-looking run is not proof of a merge.

## Step 5: Never guess at real conflicts

If `mergeable` reads `CONFLICTING` (not the transient `UNKNOWN` from Step 4),
that PR has a genuine content conflict against the current trunk — most likely
because trunk moved significantly from other merges landing during this
same sweep. Do not attempt to resolve it by picking a side. Stop that
stack's chain at the conflicting PR (its children can't land either), record
it as blocked, and continue with the other independent stacks. Report all
blocked PRs clearly at the end rather than silently dropping them.

## Step 5a: Rule out a stale mergeability check before giving up

`CONFLICTING` can mean two different things, and only one of them needs a
human:

1. **Genuine content conflict** — the PR's changes truly collide with
   something new on the trunk branch.
2. **Stale mergeability** — GitHub computed `CONFLICTING` against the PR's
   original merge-base, from before this same sweep's lower stack PRs
   squash-merged. The PR's actual diff has no real problem; GitHub just
   hasn't recomputed against current trunk content yet.

These are mechanically distinguishable, and only the first one is the
"real conflict" Step 5 means. Before recording a `CONFLICTING` PR as
blocked, run the rebase probe outside the human's main checkout — never
touch their primary working tree's branch or uncommitted state to do this:

```bash
git fetch origin {resolved_trunk_branch}
scripts/pr/probe_branch_rebase.sh origin/<pr-head-branch> origin/{resolved_trunk_branch}
```

- **Exit 0, `OK`** — the PR rebases cleanly onto the current trunk, so this was
  stale mergeability rather than Step 5's real-conflict case. Wait for
  GitHub to recompute (`sleep 5`), confirm `mergeable` now reads
  `MERGEABLE`, then continue this PR (and its children) through Step 4 as
  normal.
- **Exit 1, `FAIL`** — the probe ran and found a real content conflict.
  Follow Step 5 as written: stop the chain, record as blocked, and move on.
  Do not attempt to resolve the markers by picking a side — that part of
  Step 5 still applies.
- **Exit 3, `UNCHECKED`** — the probe could not run, so nothing is proven.
  Do not treat this as stale mergeability and do not treat it as Step 5's
  real-conflict case; report the unchecked PR separately for manual retry
  or setup repair.

## Step 6: Prove the final state

Before reporting results, re-query every PR number touched — do not trust
running tallies kept during execution. A merged tally may not be computed
from `gh pr view` state alone; GitHub's PR state is not proof that the PR's
merge commit reached the trunk.

```bash
verify="engine/hooks/gh-write-verification/verify_pr_landed_on_trunk.sh"
trunk="{resolved_trunk_branch}"

for pr in <all touched PR numbers>; do
  title="$(gh pr view "$pr" --repo <owner>/<repo> --json number,title \
    --jq '"#\(.number)\t\(.title)"')" || title="#${pr}\t<title unavailable>"

  verifier_status=0
  verifier_output="$("$verify" --repo <owner>/<repo> "$pr" "$trunk" 2>&1)" || verifier_status=$?

  case "$verifier_status" in
    0)
      printf '%s\tmerged\t%s\n' "$title" "$verifier_output"
      ;;
    1)
      printf '%s\tmerged-but-not-on-trunk\t%s\n' "$title" "$verifier_output"
      ;;
    3)
      printf '%s\tunchecked\t%s\n' "$title" "$verifier_output"
      ;;
    *)
      printf '%s\tunchecked\tverify_pr_landed_on_trunk.sh exited %s: %s\n' \
        "$title" "$verifier_status" "$verifier_output"
      ;;
  esac
done
```

Branch only on `engine/hooks/gh-write-verification/verify_pr_landed_on_trunk.sh`
exit codes: exit 0 is `merged`, exit 1 is `merged-but-not-on-trunk`, and
exit 3 is `unchecked`. Exit 3 is never reported as merged. Only exit 0
increments the merged count; exit 1 and exit 3 must be counted in their own
buckets and named with their PR numbers/titles.

Report merged count, merged-but-not-on-trunk count, unchecked count, blocked
count, and the specific PR numbers/titles in each bucket — a summary count
alone hides which specific work is still stuck.

## Why this exists

Landing a batch of admin-bypass PRs across many independent stacks by hand
each time — discovery, stack grouping, retargeting, conflict triage — is
exactly the kind of repeated manual process that should be codified. The
STOP section's two requirements exist because this class of action is easy
to reach for as a shortcut when a queue is stuck; the discipline keeps it
a deliberate, human-invoked, human-reviewed action rather than one an
agent can drift into on its own.