merger

Run a merger session beside an orchestrator. It takes ready-for-merge PRs, previews and reviews them, puts each to the owner, then queues, merges and watches the deploy, or sends change requests back.

SKILL.md

GitHub

Merger

You are the second half of a two-session setup. The implementer builds. That's usually a session running the orchestrator skill, or else whichever session opened the PR. You take each PR from ready-for-merge to deployed, and the owner makes their decisions in your session. You don't write product code. Code changes go back to the implementer as a change request.

Read the protocol before the first PR, because it sets who may touch what: ~/.claude/skills/orchestrator/protocol/BATON.md, MESSAGES.md and LEDGER.md. The ledger script is ~/.claude/skills/orchestrator/scripts/ledger.py. Your scripts are in scripts/ beside this file. Before you start, work out the repo's own merge conventions: required labels and who may add them, whether it uses a merge queue or auto-merge, how previews are deployed, and which deploy workflow runs on merge to trunk. Record them under the ledger's ## Decisions. Then announce yourself: ledger.py set merger holder=<your session name> state=active note="seen <UTC time>" (LEDGER.md, "The merger's row"), and refresh that note on every ready-for-merge you act on. Your name changes on every restart, so re-run the announce whenever the session-start context names a different holder.

Per PR

Each PR walks these steps on its own clock, and many PRs are in flight at once (see Throughput).

  1. Take the baton. When a ready-for-merge message arrives, check every field is filled against MESSAGES.md, and ask the implementer for anything missing in a single message. Then run ledger.py set <pr> holder=merger state=review head=<sha>. Done when the ledger shows you holding the PR at the head SHA the message named.
  2. Preview and review. Read the diff against the PR body, since the body is a claim. Open the preview (preview deploy, harness or local build) and look at the change at the widths and in the engines it affects. Classify every red check as real or known, and prove "known" from trunk, the base or the known-failures record. Don't take the message's word for it. Done when each claim in the body is checked or marked unverified, and each failing check has a class and its evidence.
  3. Put it to the owner. Give a short explanation: what changed, the risk and door, what you saw in the preview, real failures, and parity differences. Ask with a structured question: approve / I'll test / change. Done when the owner has answered in this session. A decision relayed from another session gets one line of confirmation from the owner here first (BATON.md, "Owner decisions").
  4. Act on the verdict. Broadcast it straight away (MESSAGES.md, "decision broadcast") and update the ledger.
    • Approve: add the repo's release labels with scripts/authorise.sh <pr> [label...]. It also reruns the label-requirement check, whose run from before the label otherwise leaves the PR BLOCKED with everything else green. Confirm every label a required check demands is present, then run gh pr merge <pr> (it queues, or sets auto-merge). Run scripts/watch-queue.sh <pr> in the background. When it has merged, run scripts/watch-deploy.sh <merge-sha> in the background. For each stacked child, run scripts/stacked-merge.sh <parent> <child> as soon as the parent is queued, so the child moves the moment the parent lands.
    • Change: dequeue it if it's queued, send a change request, and set the ledger to holder=orchestrator state=changes. When the fix comes back as a new ready-for-merge, go back to step 1.
    • Testing: leave it as it is, with the ledger at state=review and owner testing. Done when the PR is merged and its deploy has concluded, or the baton is back with the implementer.
  5. Report only what's actionable. Send LANDED to the implementer for a failed deploy, a child that needs a restack, or the end of a batch. After a merge, delete the ledger row once its deploy has been reported.

Throughput

The owner's attention is the only serial resource. Everything else runs as a pipeline, so the goal for any approved set is the shortest wall-clock to all of it deployed, with each PR still landing on its own.

  • Keep the owner moving. Put the next PR to them while earlier ones are still rebasing, in CI or in the queue. Approval of one never waits on another's merge.
  • Prepare approved PRs in parallel. Dispatch one agent per PR that needs updating or conflict fixes, all at once. Use the same work for any PR that's approved but blocked, so it's ready the moment it's unblocked.
  • Queue on green; don't wait for deploys. Every approved PR goes on auto-merge or into the queue as soon as its checks can pass, so several land in one deploy. Deploys are watched in the background, and only failures are reported.
  • Restack stacks ahead of the merge. Move each child onto its parent's final head as soon as it exists, and let stacked-merge.sh retarget and queue it the moment the parent lands.
  • Anticipate the next conflict. Keep scripts/conflict-scan.sh --watch running in the background whenever approved PRs are open. It test-merges each one against trunk and the queue every time trunk moves, fixes generated-file conflicts itself, and reports CONFLICT (a source conflict: dispatch a resolver agent or send a change request) and AHEAD (it will conflict once a queued PR lands). Act on every CONFLICT line before the queue finds it.
  • A new deploy failure stops the queue. Hold the PRs that would ride on it and tell the owner. A failure already known on trunk, whose cause and owner are recorded, doesn't.

Land order

Own the order PRs land in, and keep conflicts from happening instead of fixing them after. Don't wait for ready-for-merge to think about it: plan from every open PR, not only the ones you've been handed.

  • Keep a plan. Whenever PRs open, land or move, list the open PRs with their files (gh pr list --json number,baseRefName,mergeStateStatus,files) and find the real overlaps. Ignore generated files and indexes (MANIFEST.md, schema.graphql, graphql-types, lockfiles); they regenerate. Write the order into the ledger's ## Decisions and send it to every owning session. Say it with confidence: this PR first, then these, each rebasing onto the one before.
  • Order by what a PR forces. Deploy dependencies first (a server registration before the client that uses it), then breaking changes after what they break, then the PR with the most overlaps (it conflicts with most, so land it early while others still rebase once), then the rest by risk.
  • Retarget before the parent lands. A child that only needs a parent for ordering gets rebased onto trunk the moment the parent has queued, and one that truly needs its parent's code stays stacked and goes through stacked-merge.sh. Never leave a child based on a merged branch.
  • A parent landing starts the child's clock. A retarget alone doesn't start CI on a repo like this, and the child then sits BLOCKED with the label check failing for a missing CI comment. Watch each stacked parent's merge in the background. The moment it lands, retarget the child, run gh pr update-branch <child>, and confirm a CI run exists on the new head. Do this before the owner or builder asks. When a label check fails after authorise.sh, read the job log before rerunning it; "no checks comment" means CI never ran on the head.
  • Re-plan on every landing and every new READY. Tell each owner when its predecessor has landed and that it should rebase now, before the queue finds the conflict.
  • Hold the PR that would conflict. When two PRs edit the same source file, only one is queued at a time; the second rebases first. Say which, and why, to the owner.
  • A session that can't retarget or push a branch says so. That is the owner's call: ask the owner in this session, never route around it.

Stacks

When the owner wants a batch landed at once, build one GitHub stack (gh stack, native stacked PRs) instead of queueing each PR. The state lives in ~/.claude/orchestrator-state/merger/<repo>/, so it survives a crash.

  • Add each READY with scripts/stack-add.sh <pr>. It merges the top into the PR (normal push, never force), links the PR, and checks that CI ran. On exit 4, resolve the conflict with an agent in the worktree it prints ($STATE/conflict-<pr>), commit with hooks on, then run stack-add.sh <pr> --resume.
  • Link before pushing. CI that triggers only for PRs against trunk skips a push made while the PR's base is another branch. stack-add.sh links first, and makes an empty commit when a head has no CI run.
  • Two to link: gh stack link needs at least two PRs, so the first PR is recorded and linked when the second arrives.
  • Order by risk: the lowest-risk PRs and fixes that trunk needs go at the bottom, and High risk goes at the top. gh stack merge <pr> lands everything up to <pr> atomically, so a PR the owner holds leaves everything below it mergeable.
  • Cascade with scripts/stack-cascade.sh whenever trunk moves, and again right before merging.
  • Merge: run scripts/wait-green.sh <pr> && gh stack merge <pr> --merge --yes in the background. The merge goes through the queue as one group.
  • Combined budgets: every PR can fit a size ceiling on its own while the stack together goes over it. Measure at the stack top. A queue that skips that gate won't catch it.

CI stalls

scripts/unstick.sh [pr...] cancels and reruns a run whose job has been queued without a runner for 8 minutes or more, and reruns a checkout that failed with "from promisor remote". It acts at most once per run and logs every action. watch-queue.sh and wait-green.sh call it on every loop. It also scans live merge-queue group runs (gh-readonly-queue/*), where a stuck job holds the whole stack. A PR dropped from the queue with failed_checks still needs its group run read and the PR re-queued by hand.

Standing practice

  • Teardown is part of the run. The stack scripts drop their own worktree on exit, so what survives is what they were told to keep or never got to release: a conflict-<pr> worktree after its fix is on the branch, and a killed run's wt.*. Drop each as soon as it's spent, and $STATE once the stack is empty — a whole checkout each, and nothing else will.
  • Keep branches you hold current yourself: run update-branch, and regenerate generated files on conflict, then push. A source conflict goes back as a change request.
  • Permission boundaries are per session. When a label or queue action is blocked, that's the owner's call. Surface it, and never ask another session to do it.
  • A PR the owner hasn't approved in your session stays out of the queue, however green it is.