orc-pr-driver

name

orc-pr-driver

description

Stacked-PR DRIVER. Use for "/orc-pr-driver", "build the stacked PRs", "submit the stack", "restack / sync / merge my stack". Takes an approved stacked-pr/<slug>/stack-plan.md — written by /orc-pr-setup, generated by `orc pr stack template` and filled in by hand, or handed over by ORC's ship phase — and executes it: one branch per layer, only that layer's files, a MANDATORY per-layer green gate (build + tests + lint scoped to the layer's own base + the repo's own hooks, never --no-verify), then `gh stack submit`, PR bodies from the resolved template, and the ongoing sync / rebase / conflict / bottom-up merge care. Refuses to run on a plan with unanswered uncertainties, a missing ticket or a red build.

ORC-PR-DRIVER (stacked-PR driver)

The half that touches git. orc-pr-setup decides WHERE the cut lines go; this lane makes the layers real and keeps the stack healthy until every layer is merged.

Its whole discipline is one sentence: no layer is submitted, pushed or merged until its own gate is green at its own base. A layer that only builds when the whole stack is applied is not a reviewable layer, and merging the layer below it breaks the trunk.

Tier. Not effort-gated (the guard matches the exact skill name orc), so it runs at whatever tier the chat is on.

Human guide: this skill's own README.md (step-by-step walkthrough, the green gate per language, merge order, troubleshooting table) — point the USER there when they ask how any of this works; never load it to drive the run.

Load at their phase, never preloaded: ../_shared/stack-plan.md (plan schema, probe, budgets, STACK-FROM, entry modes) · ../_shared/gh-stack-commands.md (preflight + command surface) · ../_shared/pr-templates.md (per-layer body rules) · references/green-gate.md (the mandatory ladder) · references/orc-run-split.md (splitting an already-built worktree, file-granular) · references/conflict-playbook.md (sync, rebase, modify, merge).

Hard rules

1. Never git commit --no-verify. The repo's hooks ARE the gate; bypassing them means the PR cannot land anyway.
2. Never gh stack submit over a red layer, and never push one.
3. Green means green at the layer's OWN base — not "green once the whole stack is applied".
4. After ANY lower-layer change, re-run the full ladder at every tip above it, bottom-up. "It was green when I cut it" is not evidence — a rebase rewrites every upper branch.
5. Merge bottom-up only. Never merge a middle layer while an unmerged layer sits below it.
6. Hunk surgery is forbidden. Splits are file-granular; a file that seems to belong in two layers is a question, not a manual diff edit.
7. Never fabricate a green. No //nolint, no fake caller, no deleted identifier to silence a linter (references/green-gate.md — that is a P0 question about the seam).
8. The plan is the contract. Re-cutting a seam mid-run means updating the plan file (and its ## Decisions) in the same step.

Phases

orc lane phases orc-pr-driver --json is this lane's pipeline: the ordered list, where each phase lives, and how much of it to read. The CLI owns the order — never derive it from the headings below, and never renumber or rename one without the manifest, because a read: section pointer names a HEADING and a renamed heading is a pointer into nothing.

Phase D0 — Read the plan + hard gate

1. Probe, do not search: orc pr stack status [<slug>] — exit 0 = READY, exit 1 = absent or unfilled (../_shared/stack-plan.md). Exit 1 → say which it is and offer /orc-pr-setup (plan it) or orc pr stack template (skeleton to fill in by hand).
2. Read stacked-pr/<slug>/stack-plan.md, plus stacked-pr/<slug>/STACK-FROM.md when present (source, ticket, entry mode, template, run dir, BUILD-GREEN).
3. REFUSE to run — name the exact missing field, then stop — on: an unanswered UNCERTAIN in ## Decisions, a missing ticket, a layer with no purpose or no value class, a FOUNDATION layer naming no consumer, fewer than 2 layers, or BUILD-GREEN: false. Never fill a field in for the user.
4. Re-validate the budgets against the real numbers (git diff --numstat, exclusions applied). A layer that grew past a ceiling since planning → surface it and ask: split it here, or log an accepted exception.
5. Preflight per ../_shared/gh-stack-commands.md (gh · auth · extension · not a fork · trunk · protections · merge queue). A hard fail → one regular PR, and say so plainly.

Phase D1 — Snapshot (entry mode orc-run only)

The change already exists in the worktree, so preserve it before touching branches — references/orc-run-split.md is the exact procedure: commit the whole change to a scratch snapshot branch, verify the snapshot contains every changed path from git status --short, and only then move to the trunk. Every layer is later materialized with git checkout <snapshot> -- <that layer's files>; deletions are applied as git rm. The snapshot branch stays until the last layer merges — it is the undo button.

greenfield skips this phase: each layer's code is written in its own layer.

Phase D2 — Build the stack, layer by layer

gh stack init -b <trunk> → then, per layer, bottom-up:

1. gh stack add -m "<ticket> <layer title>" (branch name from the plan).
2. Materialize only that layer's files — git checkout <snapshot> -- <files> (orc-run) or write them (greenfield). Nothing from another layer, ever.
3. Run the FULL green-gate ladder (references/green-gate.md): build → tests (the layer's scope) → lint attributed to this layer's base → the repo's own pre-commit hooks, unbypassed. Any step red → stop, fix, re-run the ladder from step 1 for that layer. Do not proceed, do not push.
4. Commit through the hooks. Record the layer's gate status (GREEN) back into the plan file.
5. Report one line per layer to the user: L<n> <branch> — <files> files, <LoC> LoC — GATE GREEN.

A layer that cannot go green alone is a seam defect, not a lint problem: stop and ask (merge it into its consumer · land the first caller here · accept with an explicit, reason-carrying suppression — user's call only), then record the answer in the plan's ## Decisions.

Phase D3 — Submit

1. gh stack submit → then verify with gh stack view --json: the bases chain correctly (bottom → trunk, each upper → the branch below) and each PR's diff really is only its own layer.
2. Fill each PR body from the resolved template per ../_shared/pr-templates.md, including the four per-layer facts: layer n of N + ticket · purpose + value class · deliberately NOT here → which layer has it · excluded-from-budget files, listed.
3. Show the user the stack map, each PR's URL, and the review order hint.

Phase D4 — Maintain

references/conflict-playbook.md. In short: gh stack sync after the trunk moves · gh stack rebase --upstack after amending a lower layer, then re-run the ladder at every tip above, bottom-up (hard rule 4) · gh stack modify to insert / reorder / drop / combine when review demands it (prefer it, and fixup-on-top, over history rewrites mid-review — a force-push destroys a reviewer's in-progress context).

Phase D5 — Merge (bottom-up, gated)

Before each gh stack merge: confirm via gh stack view --json + gh pr view <n> --json statusCheckRollup that that layer's own CI is green. After each merge: confirm the upper layers auto-retargeted and their CI re-ran. Never merge a middle layer with unmerged layers below it. When the last layer lands, delete the snapshot branch (ask first) and report the final state.

Behavior trace (always on)

../_shared/phases/trace.md (core, at run start; orc lane phases names the file and the layers). Lane token prdriver, tier Multi-dispatch — one packet per LAYER boundary (each layer's green gate closes) + the end-of-run packet. At run start write log_dir/.current = run-prdriver-<slug>-<DDMMYY>-<HHMMSS>.txt AND touch the trace file of that name in the SAME step. Nothing else about the protocol is restated here; a phase that ends with zero new trace lines is a protocol violation.

Events: PHASE D0..D5, GATE layer-green pass|bounce :: L<n> <step>, QUESTION count=<n>, GATE stack-certainty on a mid-run re-cut, FINISH; decisions carries the WHY (seam calls, accepted exceptions, the user's answers verbatim).

Boundaries

• Never plans the layering. No plan → /orc-pr-setup or orc pr stack template. It executes a plan; it does not invent one.
• Never bypasses a gate — no --no-verify, no red submit, no red merge.
• Never rewrites the user's work silently: the snapshot branch exists before any branch switch, and it survives until the stack is merged.
• Out of scope: cross-repo stacks (unsupported by GitHub) and retrofitting an already-open PR into a stack.
• Reminder: to see usage limits, tell the user to run /usage (never invoke it programmatically).

Config

Resolve with orc lane config orc-pr-driver --json and obey effective. Never merge .claude/orc.config.yaml yourself, and never re-derive a precedence. Exit ≠ 0 → say so and use ../_shared/config-precedence.md's documented defaults, out loud. Nothing this lane reads is contested, gated or a stop, so it owes no preflight line and has no gate to honour.

Calls

ONE catalogue, and it is not you: orc lane calls orc-pr-driver --json names every CLI call this lane makes, each with its exit-code contract, its cost, when to run it, and what an EMPTY answer means. Never invent a spelling, never re-word an exit code, and never re-derive a state word — the CLI's state words are the only state words, and an exit code is an ANSWER wherever that contract says so, not a failure. A call the answer does not name is a call this lane does not make. Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the command you are about to run, out loud, before running it.