Land PRs

Land the open PRs

The goal is every open PR merged, except the ones the user excludes. A PR that cannot merge yet is a problem to fix, not a row to skip: a conflict gets resolved, a dismissed approval gets re-requested, a pending check gets waited for. What this skill does not do is decide on the user's behalf — the stops in Step 6 go back to them.

This skill is project-local and owned here (CLAUDE.md rule 13). Edit it when a new scenario turns up; that is expected.

What this skill never does

• Approve a PR, or merge one that is not approved. CLAUDE.md rule 8: nobody approves their own PR, and for an admin an unapproved merge succeeds silently. The one exception is Step 6's stale change request, and only on the user's explicit instruction; no other --admin.
• Force-push. Conflicts are resolved with a merge commit on top of the PR branch.
• Rewrite a PR's substance. Conflict resolution and mechanical upkeep only — including the narrow adaptations Step 4 names. A finding that needs a code change goes to a unit (Step 6).
• Merge a PR the user excluded, or one whose unit is still working. Ask which are still in progress if you do not know; a PR that is APPROVED can still have an agent pushing to it.

Step 0 — Read the rules back, do not trust this file

gh api repos/{owner}/{repo}/rules/branches/main --jq '.[]|{type, p:.parameters}'

At the time of writing that says: one approving review, dismiss_stale_reviews_on_push: true, required_review_thread_resolution: true, five required contexts (build, build-macos, build-windows, security, e2e-deterministic), and strict_required_status_checks_policy: false. Two consequences shape everything below:

• Branches do not need to be up to date with main. Only a real conflict blocks a merge — not being behind. That is the ruleset; this skill adds the overlap check on top of it (Step 3), because a branch that is behind can still break main when main changed its files.
• Any push to a PR dismisses its approval. Every conflict you resolve costs a re-review, so the order of merges matters (Step 3).

If what you read back differs, trust the API over this paragraph and update it.

Step 1 — Take stock

gh pr list --state open --limit 100 --json number,title,reviewDecision,mergeStateStatus,mergeable,author,headRefName,headRefOid

For each PR, also read its unresolved thread count (GraphQL reviewThreads { isResolved }), its required checks (gh pr checks <n> --required), and its non-required checks (gh pr checks <n>). Then put every PR, minus the user's exclusions, in exactly one bucket:

A non-required check is not a formality. UNSTABLE in mergeStateStatus means one is failing, and GitHub will merge past it. Read why before merging: on 2026-09-27 #1363's advisory desktop-driver failure was the only sign that merging it would re-break the desktop build (Step 3, "main also moves under you"). Merge past a failing or pending non-required check only once you can say it is unrelated to this PR — the same failure on main, a known flake re-run green — and say so in the report. "Unrelated" clears this PR, not the red (CLAUDE.md rule 6): a flake that re-ran green is still a red with no owner unless it is already quarantined or an open PR fixes it. So give it one before you merge past it — hand it to a unit or to the user (Step 6) — and name the owner in the report. The PR itself does not wait for that fix to land: the red is not on its required path, and holding every PR behind every flake is how a backlog stops moving. CLAUDE.md rule 8 covers the same trap for auto-merge.

Address every PR by its PR ref, never by origin/<headRefName>. A fork PR's branch is not on origin, and an origin branch can share a fork's branch name while pointing at unrelated code. Fetch the head the PR will actually merge — with a leading +, so the ref follows a force-push instead of silently keeping the old commit: git fetch origin +pull/<n>/head:refs/remotes/origin/pr-<n>, then confirm git rev-parse origin/pr-<n> equals gh pr view <n> --json headRefOid --jq .headRefOid, and use origin/pr-<n> everywhere below. It also covers the case where git fetch origin <branch> simply fails (seen with a Renovate branch) — never read a failed fetch as "no conflicts".

UNKNOWN is not a bucket. GitHub recomputes mergeability after main moves and reports UNKNOWN for seconds to minutes. Poll until it settles; never read it as blocked or as clean.

Show the user the table before acting, with the exclusions and what you will do per bucket.

Step 2 — Before resolving anything, look for duplicated fixes

When several PRs were dispatched from the same base, they often carry the same fix for a red they each met — measured on 2026-09-26, four PRs carried their own variant of the same remote_tunnel probe-test isolation. The first to merge makes every other copy a conflict. Recognise the pattern up front (the same file conflicting in several PRs), so Step 4 resolves them the same way.

Step 3 — Merge order

Merge one PR at a time, and re-read every remaining PR's mergeable after each merge — a merge can turn a clean PR into a conflicting one.

Decide the order by simulating it, not by guessing from file lists. Two PRs editing the same file usually merge cleanly; guessing from overlap held six approved PRs back for no reason on 2026-09-26. git merge-tree answers it exactly and touches no working tree:

git fetch origin
c=$(git rev-parse origin/main)
# stack EVERY PR you intend to land, in the order it will merge — the ready
# ones first, then the ones awaiting review — so the awaiting ones are tested
# against each other too
for x in <PRs, in merge order>; do
  git fetch -q origin "+pull/$x/head:refs/remotes/origin/pr-$x"
  h=$(git rev-parse "origin/pr-$x")
  [ "$h" = "$(gh pr view "$x" --json headRefOid --jq .headRefOid)" ] || { echo "#$x: fetched ref is not the PR head"; exit 1; }
  # capture first, then test merge-tree's OWN exit status: piping it into
  # `head` would test head's status and let a conflict read as clean
  if out=$(git merge-tree --write-tree "$c" "$h"); then
    c=$(git commit-tree "$(printf '%s\n' "$out" | head -1)" -p "$c" -p "$h" -m "sim #$x")
    echo "#$x stacks cleanly"
  else
    echo "#$x conflicts with what is stacked before it"   # do not stack it; it goes to Step 4
  fi
done
git update-ref refs/heads/sim/integration "$c"

Simulate the awaiting-review PRs in the same stack, not just against the ready ones. Checking each only against the ready stack misses two awaiting PRs that conflict with each other — on 2026-09-26 #1338 and #1331 each merged cleanly on top of the ready stack, and #1331 went CONFLICTING the moment #1338 landed.

A clean merge is not a green merge. merge-tree finds textual conflicts only. Two approved PRs can merge cleanly and still break each other's behaviour — #1340's voice deck-switch test failed after #1334 changed how desktop settings save, with no conflict marker anywhere. Step 4's gates catch that; run them on every branch you merged main into, including the desktop frontend's tests when desktop/ is touched.

Then build and test the stacked result before anyone reviews or merges anything. Check sim/integration — every PR that stacked cleanly, awaiting-review ones included — out detached in the land worktree, and run the full gates on it — rule 2's clippy, cargo test-fast, and the desktop pnpm test plus typecheck. This is the merge queue this repository cannot have (a user-owned repo rejects the merge_queue rule, #1088), run once for the whole batch. It finds the clashes merge-tree cannot see while every PR still has its approval.

Batch what the simulation clears, serialise what it does not. Merging one PR never dismisses another's approval — only a push to that PR does. So every PR that stacks cleanly and passes on the integration build can be reviewed in one sweep and merged back to back with no further pushes. Only the PRs the simulation flags need a push: resolve those one at a time after the PR they collide with, or stack them onto it beforehand so the resolution is done and gated once — after the base lands, one mechanical merge of main and a re-review still remain (item 4 below). Finding collisions during merging instead — what happened on 2026-09-26 — turns every one into a push, a CI run and a re-review, and the next merge can surface the next one.

Then:

1. Merge every ready PR that makes no awaiting-review PR conflict, now. Waiting for the rest gains nothing.
2. A ready PR that would make an awaiting-review PR conflict: if that PR's review is already in flight, hold the ready one until it lands — otherwise the re-review is paid twice. If the other PR has not been sent for review yet, merge the ready one and resolve the other before sending it.
3. Two ready PRs that conflict with each other: merge one, then resolve the other.
4. Stacking does not make the upper PR merge cleanly after a squash. This repository squash-merges, so once A lands, main holds A's version of every hunk A touched while B's branch holds the combined version, and git sees two different edits of the same lines wherever both PRs edited them — measured on 2026-09-27, #1346 went CONFLICTING the moment #1347 (its base) landed. What stacking buys is that the resolution is already known: merge main into B keeping B's side in those hunks (B already contains A's content), check that git diff origin/main HEAD now shows only B's own changes, and re-review B. When main's tree is byte-identical to A's final head (check git rev-parse origin/main^{tree} against git rev-parse <A-head>^{tree} — true when nothing else landed in between), B's current tree already is the right result: git merge -s ours origin/main records main as a parent without changing a file, and cmp <(git diff origin/main HEAD) <(git diff <A-head> <B-head-before>) proves the diff is exactly B's. Nothing was edited, so the gates that passed on that tree still hold. It does not buy a push-free merge. And a stacked PR's diff shows the base's changes, so a reviewer's findings about the base's code land on the upper PR — four of #1346's six threads were about #1347. Route those to the base PR while it is open, or to a follow-up issue once it has merged (#1365), and resolve them on the upper PR with a pointer.
5. A stack moves together. When B is stacked on A (A's branch merged into B's), a change to A — a reviewer's REQUEST_CHANGES, a late finding — means re-merging A's new head into B and re-reviewing B, and so on up the stack. So review the stack bottom-up and hold B's review until A is approved: on 2026-09-27 #1347 drew a REQUEST_CHANGES while #1346 (stacked on it) and #1342 (stacked on #1346) were queued behind it, and reviewing them first would have spent two reviews on heads about to change.
6. A rename or sweep PR (a glossary, a mechanical call-site sweep) lands last. Every PR that merges after it and uses an old name breaks without a conflict marker. Land the others, merge main into the sweep once more, re-run its gates so the rename covers what just arrived, and merge it then.

Run the overlap check right before each merge. The rule is /issue-queue's "The overlap check before a merge" (.claude/skills/issue-queue/SKILL.md), and it applies here as written: list the commits main gained since the PR branched off that touch the files it changes, and when it lists any, update the branch, let CI run on the combined head, get the approval again (Step 5), and check again. One narrowing applies in this skill only: a listed commit that is the squash of a PR stacked before this one in the sim/integration build above, and merged in this run, does not count, because that build already ran the gates on the two together. Any other listed commit counts — one from another session, from Renovate, from the user, or from a PR this run merged without stacking it. The trade is stated rather than hidden: the integration build runs rule 2's clippy, cargo test-fast and the desktop tests on the combined code, not build-macos, build-windows or e2e-deterministic, and the build of main after every batch (below) is what checks the result.

Merge with a squash, matching the repository's history, pinned to the head you checked:

gh pr merge <n> --squash --match-head-commit <sha>   # the sha on the overlap check's `head` line
gh pr view <n> --json state --jq .state   # read it back: MERGED

Take <sha> from the check's output rather than reading the head again now, so a push after the check makes the merge refuse instead of landing a head nobody checked. Decide on the read-back, not on the exit code.

After every batch of merges, build main before doing anything else: git fetch origin, check out origin/main detached in the land worktree, and run rule 2's clippy command (it compiles every target), cargo test-fast, and the desktop tests. Because the ruleset does not require branches to be up to date, two PRs that are each green can merge cleanly and still not compile together. Measured on 2026-09-26: #1335 added a two-argument call in a src/main.rs test, #1341 then gave the function a third parameter, and main stopped compiling its bin tests with neither PR ever red. When it happens, fix main first with its own small PR (it is a red on main, CLAUDE.md rule 6) — every branch you merge main into inherits the break, so its gates prove nothing until then. So does every PR's CI, even on a branch you never touched: a pull_request run builds the PR merged into its base, so a PR whose checks were green goes red on its next push with the same error. Review the fix PR on its own (pr_number=<fix>) rather than in a sweep and merge it. Then merge the fixed main into each affected PR and push — gh run rerun does NOT help, because a re-run rebuilds the same merge commit it built the first time, which still carries the break. Only then sweep; the reviewer will not vote on a PR whose checks are red.

main also moves under you from outside this run — another deck, another session, the user merging by hand. Re-read main before each merge, and when a PR's premise is about main's state (a revert, a fix for a red), re-check that premise first: on 2026-09-27 #1363 was approved to revert the Rust half of a Tauri bump, but #1360 had meanwhile moved the npm half to match, so merging the revert would have re-broken the desktop build. A non-required check that fails on the PR but passes on main is the tell. Rework or close the PR rather than merge it.

Renovate merges some updates itself (its pull_request bypass, CLAUDE.md rule 8), so a Renovate PR can vanish from the list mid-run and change main under you. Re-list open PRs after every batch rather than working from the first listing. On 2026-09-26 #1358 moved the Rust tauri crate to 2.12.0 through that bypass while the npm @tauri-apps/* packages stayed at 2.11 — the npm half is held by pnpm's 24-hour release-age gate and Renovate's 3-day npm delay — and tauri build refuses the mismatch, which breaks the desktop-driver job and the release's desktop bundle. Check that the Tauri crate and npm versions agree on the same minor before cutting a release; do not paper over it with a minimumReleaseAgeExclude without the user's say-so.