@azure-id/orc 0.55.0

package/templates/skills/orc-poly/references/poly-spec.md

@@ -0,0 +1,84 @@
+# orc-poly — the source-of-truth doc set
+
+Load at Phase P3. All three files live in the HOST repo under
+`poly-repo-implementation/<slug>/` — a visible, committed deliverable, never
+inside `.claude/`. Together they are the carried source of truth: the context a
+human reads, the boundary both repos are pinned to, and the machine-readable
+spec the planner splits on.
+
+## `poly-context.md` — the human-readable understanding
+
+Free-form but structured. Cover:
+
+- **Change** — one paragraph on what is being built across the repos.
+- **Repos & roles** — a row per repo: name, absolute path, role
+  (`host` | `peer`), the side of the boundary it owns or consumes.
+- **Per-repo touch points** — the real files/dirs each repo changes (anchored
+  to paths that actually exist — confirmed in P2), plus a one-line note of how
+  the local conventions do this kind of change.
+- **Decisions** — the ambiguities resolved during the P2 question loop, each
+  with the answer that was pinned.
+
+## `interface-contract.md` — the FROZEN boundary
+
+The anti-drift core. This is the one artifact every repo's plan is pinned to,
+so it must be exact and self-contained. Cover the shared seam precisely:
+
+- **Endpoint / RPC / event** — method + path, or RPC name, or event topic.
+- **Request** — every field: name, type, nullability, constraints; auth
+  header/token.
+- **Response** — success shape (every field, type, nullability), pagination if
+  any.
+- **Errors** — each status/error code and when it is returned.
+- **Auth & access** — who may call it and how.
+- **Versioning** — additive vs breaking; compatibility notes for existing
+  consumers.
+
+Once frozen (the user picks "pass to orc-plan"), treat it as immutable for the
+run: if a later iteration changes the boundary, it is a NEW freeze — rewrite the
+contract and re-split, never let a repo's plan diverge from it silently.
+
+## `poly-spec.md` — the machine-readable handoff
+
+Carries the marker `orc-poly:spec` on its first line so the planner
+self-activates poly mode. Shape:
+
+```
+orc-poly:spec v1
+slug: <slug>
+contract: interface-contract.md        # the frozen boundary, relative to this file
+git_head:                              # HOST HEAD short-sha at freeze time (staleness stamp)
+repos:
+  - name: <host-repo>
+    role: host
+    path: <absolute path>
+    in_scope[]: <files/dirs this repo changes>
+    requirements[]:
+      - id: R1
+        text: <what this repo must do>
+        contract_ref: <section of interface-contract.md it depends on>
+  - name: <peer-repo>
+    role: peer
+    path: <absolute path>
+    in_scope[]: ...
+    requirements[]: ...
+```
+
+Rules:
+
+- Every requirement cites a `contract_ref` — a requirement that does not touch
+  the boundary still names why it is in this poly change.
+- `in_scope[]` paths are the ones confirmed to exist in P2 (new files are
+  allowed, marked as such — the planner grounds them like any new path).
+- One `repos[]` entry per repo. N peers are allowed; the planner produces one
+  plan per entry.
+
+## How the planner consumes it (P5)
+
+The shared planner (`orc-planner-opus-5-med`), on seeing `orc-poly:spec`,
+produces **one planning-output per `repos[]` entry**, each scoped to that
+repo's `in_scope[]` and each embedding the frozen `interface-contract.md`
+verbatim so the later per-repo `/orc` build cannot drift from the boundary. The
+HOST plan is written under `poly-repo-implementation/<slug>/`; each PEER plan is
+written into that peer repo at the same relative path (the only write orc-poly
+ever makes into a peer).

package/templates/skills/orc-pr-driver/README.md

@@ -0,0 +1,349 @@
+# ORC-PR-DRIVER — build and ship your stacked pull requests
+
+**Guide for humans.** Plain, simple English. This skill takes a stack plan and
+makes it real: one branch per layer, one PR per layer, each one tested on its
+own.
+
+Read the planning guide first if you have not:
+**[ORC-PR-SETUP README](../orc-pr-setup/README.md)** — it explains what a stack
+is, and it writes the plan this skill needs.
+
+---
+
+## 1. The short version
+
+```
+stack-plan.md ──▶ /orc-pr-driver ──▶ branch per layer
+                                     ↳ build + test + lint each layer ALONE
+                                     ↳ gh stack submit  → 3–6 small PRs
+                                     ↳ sync / rebase / merge from the bottom up
+```
+
+Run it with:
+
+```
+/orc-pr-driver
+```
+
+**The one rule that matters:** a layer is never pushed, submitted, or merged
+until it is green **on its own base**. Not "green when all layers are applied
+together". Green alone. Because you may merge layer 1 today and layer 2 next
+week — and layer 1 alone must not break your main branch.
+
+---
+
+## 2. Before you start: is the plan ready?
+
+The plan lives at `stacked-pr/<slug>/stack-plan.md`. Check it:
+
+```bash
+orc pr stack status              # or: orc pr stack status my-feature
+```
+
+| Result | Meaning | What to do |
+|---|---|---|
+| `✓ READY` (exit 0) | the plan is complete | run `/orc-pr-driver` |
+| `✗ absent` (exit 1) | there is no plan | run `/orc-pr-setup`, or `orc pr stack template <slug>` |
+| `✗ NOT READY` (exit 1) | the plan still has `<...>` gaps | fill them in; the message lists what is missing |
+
+**The driver refuses to run** when the plan has any of these problems. It tells
+you exactly which one, and it never fills in a value for you:
+
+- a question in `## Decisions` that you never answered,
+- no ticket number,
+- a layer with no purpose, or no value class,
+- a `FOUNDATION` layer that does not name the layer using it,
+- fewer than 2 layers (that is not a stack — just open one PR),
+- the build was red when the change was handed over.
+
+It also re-checks the tools: `gh` version 2.0+, logged in,
+`github/gh-stack` installed, and **your repo is not a fork** (GitHub cannot stack
+across forks). If a check fails, it says so and recommends one normal PR.
+
+---
+
+## 3. Your work is protected first (the snapshot)
+
+If your code already exists in your working tree — the normal case when `/orc`
+hands the change over — the driver **saves everything before it touches any
+branch**:
+
+```bash
+git status --short > list-of-changed-files        # the authoritative list
+git checkout -b orc-stack-snapshot/<slug>         # your files stay as they are
+git add -A && git commit -m "<TICKET> snapshot"   # now your work lives in a commit
+```
+
+Then it checks that the snapshot really contains every changed file. If one file
+is missing, it stops. It never starts branch work with a partial snapshot.
+
+That snapshot branch:
+
+- is **never pushed** and never becomes a PR,
+- stays until the last layer is merged — it is your undo button,
+- is deleted only after asking you.
+
+Every layer is then filled from the snapshot, file by file:
+
+```bash
+git checkout <snapshot> -- path/to/file.go        # add/modify files of THIS layer
+git rm path/to/deleted_file.go                   # deletions of THIS layer
+```
+
+**Files are moved whole.** The driver never cuts a file in half (no
+"hunk surgery", no `git add -p`). If one file's content seems to belong in two
+layers, that is a question for you — and the usual answer is "put the whole file
+in the lowest layer that needs it".
+
+Before submitting anything, it proves nothing was lost:
+
+```bash
+# file list of the top layer  ==  file list of the snapshot   → must be identical
+```
+
+If they differ, a file was dropped or duplicated, and it stops. A silently
+missing file is exactly the accident stacking is meant to prevent.
+
+---
+
+## 4. What happens, step by step
+
+| Phase | What it does |
+|---|---|
+| **D0 Read the plan** | probe, read, refuse if incomplete, re-measure the real sizes, check the tools |
+| **D1 Snapshot** | save your work (section 3). Skipped when the code is not written yet |
+| **D2 Build the layers** | `gh stack init` → per layer: `gh stack add`, put that layer's files in, **run the green gate**, commit through your repo's hooks |
+| **D3 Submit** | `gh stack submit`, then verify with `gh stack view --json` that each PR's base and diff are correct, and fill in every PR body |
+| **D4 Maintain** | keep the stack healthy while review happens: `sync`, `rebase --upstack`, `modify` |
+| **D5 Merge** | merge from the **bottom up**, checking each layer's own CI first |
+
+After each layer it prints one line, for example:
+
+```
+L2 PAY-4211-store — 9 files, 640 LoC — GATE GREEN
+```
+
+---
+
+## 5. The green gate (the part people get wrong)
+
+Every layer runs four steps, in order. All four are required.
+
+| Step | What | Why |
+|---|---|---|
+| 1 | **build** at this layer's base | the layer must compile alone |
+| 2 | **tests** for this layer's code | the layer must pass alone |
+| 3 | **lint, compared to this layer's own base** | so layer 4 is not blamed for layer 1's code |
+| 4 | **your repo's own pre-commit hooks** — unbypassed | those hooks are the real gate; if they fail, the PR cannot land |
+
+Common commands per language:
+
+| Language | build | tests | lint |
+|---|---|---|---|
+| Go | `go build ./...` | `go test ./<pkgs>/...` | `golangci-lint run --new-from-rev <base>` |
+| Node / TypeScript | `npm run build` | `npm test -- <paths>` | `eslint <changed files>` |
+| Java / Kotlin | `./gradlew compileJava` | `./gradlew test --tests …` | checkstyle / detekt |
+| Python | type-check / compile | `pytest <paths>` | `ruff check <paths>` |
+| Rust | `cargo build` | `cargo test <filter>` | `cargo clippy -- -D warnings` |
+
+Your project's own scripts always win over these examples. If your project
+generates code (`mockery`, `go generate`, `protoc`, `npm run codegen`), that runs
+first — a missing generated file looks like a compile error and sends you
+hunting the wrong problem.
+
+**If any step is red:** stop, fix it, and run **all four steps again from the
+start** for that layer. Do not continue to the next layer. Do not push.
+
+**`git commit --no-verify` is forbidden.** Skipping the hooks does not make the
+PR mergeable; it only hides the problem until CI finds it.
+
+### The lint trap that only happens with stacks
+
+Many projects tell their linter to check "new code since `origin/main`". In a
+stack, that makes layer 4 look like it contains layers 1–3's code too — noisy and
+wrong. The driver overrides the baseline per layer
+(`--new-from-rev <that layer's base>`), so each layer is judged on **its own**
+changes.
+
+### "unused function" on a low layer — a question, not a lint fix
+
+Your storage layer adds `FindByRef()`. Only the handler layer (higher up) calls
+it. Linters like Go's `unused`, TypeScript's `noUnusedLocals`, or Rust's
+`dead_code` will mark it as dead code and the layer goes red.
+
+That red is **useful information**: as a standalone PR, this layer really does
+add unused code. So the driver stops and asks you:
+
+```
+[a] merge the storage layer into the handler layer   (recommended — no dead code)
+[b] keep both layers, move the first caller down into the storage layer
+[c] accept it: add one suppression comment that names the layer which will use it
+    (your decision only)
+```
+
+It never adds a suppression by itself, never invents a fake caller, and never
+deletes your code to make the linter quiet. Your answer goes into the plan's
+`## Decisions`.
+
+### Code-quality scans (SonarQube and similar)
+
+If your scan analyzes the project without pull-request decoration, layer 3's
+scan measures layers 1+2+3 **together**, not layer 3 alone. So:
+
+- do not trust "new code coverage" as a per-layer number — check coverage
+  locally, per layer,
+- treat the scan as a **whole-stack** gate,
+- a scan reported as `SKIPPED` usually means the test job failed first. Read it
+  as red, not as a flaky tool.
+
+This is also why each layer keeps **its own tests with its own code**: a layer
+with no tests can fail a coverage rule all by itself.
+
+---
+
+## 6. PR descriptions
+
+Every PR body comes from the template chosen in the plan (`pr template:`). On top
+of that template, every layer's body always shows four facts:
+
+1. **Layer 2 of 4** + the ticket number (GitHub also draws the stack map).
+2. **Purpose and value class** — why this layer exists, who it helps.
+3. **Deliberately NOT here → layer 3.** This is important: it stops a reviewer
+   from rejecting your layer for something the next layer fixes.
+4. **Files excluded from the size count** — generated code, lock files, vendored
+   folders. The numbers ignore them, but reviewers should still know they exist.
+
+---
+
+## 7. Keeping the stack healthy during review
+
+Reviews take days. The trunk moves. Things need updating. Four events, four
+answers:
+
+| Event | Command | Then, always |
+|---|---|---|
+| the trunk moved | `gh stack sync` | run the green gate again at **every** layer, bottom to top |
+| you changed a lower layer | `gh stack rebase --upstack` | run the green gate again from that layer upward |
+| review asks for a structural change | `gh stack modify` (drop / combine / insert / reorder / rename) | update the plan file, then re-run the gate from the lowest changed layer |
+| a layer was merged | nothing — GitHub retargets automatically | confirm the layers above retargeted and their CI re-ran |
+
+**Why re-run the gate:** changing a lower layer rewrites every branch above it.
+A layer that was green yesterday can be red now. "It was green when I made it" is
+not evidence.
+
+### Conflicts during a rebase
+
+1. Fix the conflict **inside the layer where it appears**. Never pull content
+   down from a higher layer — that silently moves code between layers.
+2. If two layers really own the same file, the cut line was wrong. Stop, decide
+   with the skill (merge the layers, or move the whole file down), write the
+   decision into the plan, and re-cut.
+3. `gh stack rebase --continue` after each fix. `--abort` is always allowed and
+   is better than a guessed fix.
+
+### About force-pushes
+
+Changing a lower layer force-pushes every branch above it, and reviewers lose
+their in-progress review (comments detach, "viewed" marks reset). So while a
+layer is under review, prefer:
+
+- a new small commit on top of that layer instead of amending it,
+- `gh stack modify` instead of hand-made history rewrites,
+- and if a force-push cannot be avoided, leave a comment saying which layers
+  moved and why.
+
+---
+
+## 8. Merging (order is not optional)
+
+Merge **from the bottom up**. For each layer, in order:
+
+```bash
+gh pr view <n> --json statusCheckRollup     # is THIS layer's CI green?
+# reviewers approved?
+gh stack merge <n> --squash                 # or --merge / --rebase
+# then confirm: layers above retargeted, their CI re-ran
+```
+
+- Merging the **top ready layer** lands every unmerged layer below it in one
+  action. Convenient — but only when all of those layers are green and approved.
+- **Never** merge a middle layer while an unmerged layer is still below it.
+- Merge queues for stacked PRs are still rolling out at GitHub. The skill checks
+  whether your repo has one; it never assumes.
+
+When the last layer is merged, the driver offers to delete the snapshot branch.
+
+---
+
+## 9. Troubleshooting
+
+| You see | What it means | Fix |
+|---|---|---|
+| `✗ absent — no stacked-pr/...` | no plan file | `/orc-pr-setup`, or `orc pr stack template <slug>` |
+| `✗ NOT READY — 12 unfilled placeholders` | the skeleton is not filled in | fill in each `<...>`; the message shows examples |
+| "2 stack plans — name one: a, b" | more than one plan exists | add the slug: `orc pr stack status a` |
+| "refusing to overwrite a plan" | a plan with that slug already exists | edit it, use another slug, or pass `--force` |
+| "this repo is a fork" | stacks cannot cross forks | use one normal PR |
+| `gh: unknown command "stack"` | the extension is missing | `gh extension install github/gh-stack` |
+| lint flags code from lower layers | the baseline is the trunk, not your layer | the driver sets `--new-from-rev <layer base>`; check your CI does the same |
+| "unused" on a low layer | as a standalone PR, that code has no caller | answer the question in section 5 — never add a blind suppression |
+| a layer was green, now it is red | a lower layer changed and rewrote this branch | fix, then re-run the gate at every layer above the change |
+| `scan SKIPPED` in CI | the test job failed before the scan | treat as red; fix the tests |
+| the file lists do not match at the end | a file was dropped or duplicated between layers | the driver stops; fix the layer file lists in the plan |
+
+---
+
+## 10. What this skill never does
+
+- Never plans the layers. No plan → it sends you to `/orc-pr-setup` or the
+  template command.
+- Never bypasses a gate: no `--no-verify`, no red push, no red submit, no red
+  merge.
+- Never cuts a file in half.
+- Never touches your work without a snapshot first.
+- Never merges out of order.
+- Never builds a "manual stack" by pushing branches and editing bases by hand
+  when the extension is missing — nothing would retarget on merge, and a
+  half-built stack is worse than one honest big PR.
+
+---
+
+## 11. FAQ
+
+**Can I start here without `/orc-pr-setup`?**
+Yes. That is a supported path. Run `orc pr stack template <slug>`, fill in the
+file, then run this skill.
+
+**What if I want to stop in the middle?**
+The layers that are already green stay as normal branches/PRs. Your snapshot
+branch still holds everything. `gh stack unstack` removes the stack tracking and
+keeps the branches.
+
+**Do I need to run CI myself?**
+The green gate runs locally, per layer, before anything is pushed. GitHub then
+runs your normal CI on each PR. Both matter: local gate finds problems in
+seconds, CI is the official record.
+
+**How many layers is too many?**
+Above 6 you get a warning, above 8 the planner stops. Each layer is a full CI
+run and one more review context.
+
+**Can I use this for a change across two repositories?**
+No. GitHub stacks live in one repository. Use `/orc-poly` for cross-repo
+planning.
+
+**Does this work with squash merges?**
+Yes — `gh stack merge` supports merge, squash, and rebase.
+
+---
+
+## 12. Reference files (the skill loads these when it needs them)
+
+| File | Contains |
+|---|---|
+| `references/green-gate.md` | the four-step ladder, the lint baseline trap, the dead-code question, re-verification rules |
+| `references/orc-run-split.md` | the exact snapshot and file-by-file split procedure |
+| `references/conflict-playbook.md` | sync / rebase / modify / merge, conflicts, force-push etiquette |
+| `../_shared/stack-plan.md` | the plan format, size rules, the handoff file |
+| `../_shared/gh-stack-commands.md` | every `gh stack` command, and what to do if GitHub renames one |
+| `../_shared/pr-templates.md` | how a PR description is chosen, plus three ready-made templates |

package/templates/skills/orc-pr-driver/SKILL.md

@@ -0,0 +1,167 @@
+---
+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.
+
+## 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 (PERMANENT — every ORC entry point traces; always on)
+
+Resolve `log_dir` (`../orc/config.md` default ← `.claude/orc.config.yaml`) at
+start and follow `../orc/references/trace-protocol.md`: write
+`log_dir/.current` = `run-prdriver-<slug>-<DDMMYY>-<HHMMSS>.txt` and
+`touch the trace file` of that name in the SAME step, first. Narration is
+dispatched, not remembered: dispatch the trace writer at every **layer
+boundary** (one packet per layer close, per the multi-dispatch tier) and once at
+run end. Events with their REAL timestamps: `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). A phase ending
+with `zero new trace lines is a protocol violation`.
+
+## 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).

package/templates/skills/orc-pr-driver/references/conflict-playbook.md

@@ -0,0 +1,78 @@
+# Reference — stack maintenance & conflict playbook
+
+Loaded at Phase D4/D5. A stack is a living chain: the trunk moves, review demands
+changes, layers merge. Every one of those events rewrites branches above the
+change, so every one of them ends with the same obligation — **re-run the green
+gate at every tip above it, bottom-up** (`green-gate.md`).
+
+## The four events and their exact response
+
+| Event | Command | Then |
+|---|---|---|
+| the trunk moved | `gh stack sync [--prune]` | re-run the ladder at EVERY layer tip, bottom-up |
+| you amended layer N | `gh stack rebase --upstack` | re-run the ladder from layer N upward |
+| review wants a structural change | `gh stack modify` (drop / combine / insert / reorder / rename) | update the plan file + `## Decisions`, then re-run the ladder from the lowest touched layer |
+| a layer merged | (automatic retarget) | confirm the upper layers retargeted and their CI re-ran |
+
+`gh stack rebase` also takes `--downstack`, `--no-trunk`, `--continue`,
+`--abort` — see `../../_shared/gh-stack-commands.md`.
+
+## Conflict resolution during a rebase
+
+1. **Resolve in the layer where the conflict appears**, never by pulling content
+   down from a higher layer — that silently moves code between layers and breaks
+   the plan's file list.
+2. If the conflict shows that two layers genuinely own the same file, that is a
+   **seam defect**: stop, ask (merge the layers · move the file wholesale to the
+   lower one), record the answer in the plan, and re-cut.
+3. `gh stack rebase --continue` after each resolution; `--abort` to get back to a
+   known state — aborting is always allowed and always better than a guessed
+   resolution.
+4. After the rebase completes, the ladder runs at every tip above the conflict.
+   A conflict resolution is a code change like any other.
+
+## Force-push discipline
+
+Amending a lower layer force-pushes every branch above it, and reviewers lose
+in-progress review context (comments detach, "viewed" marks reset). So:
+
+- prefer **fixup-on-top** (a new commit in the same layer) over an amend while a
+  layer is under active review;
+- prefer `gh stack modify` over hand-rolled history rewrites;
+- when a force-push is unavoidable, tell the reviewers in a PR comment which
+  layers moved and why.
+
+## Merge sequence (bottom-up, non-negotiable)
+
+```
+for L in bottom..top:
+    gh pr view <L> --json statusCheckRollup     # this layer's own CI green?
+    reviewers approved?
+    gh stack merge <L> [--squash|--merge|--rebase]
+    confirm: upper layers retargeted, their CI re-ran
+```
+
+- Merging the **top ready layer** lands every unmerged layer below it in one
+  operation — convenient, but only when every one of those layers is green and
+  approved. Otherwise merge one at a time.
+- Never merge a middle layer while an unmerged layer sits below it.
+- A merge queue may or may not be enabled for stacked PRs on a given repo —
+  **probe, never assume** (`../../_shared/gh-stack-commands.md`).
+
+## Abandoning a stack
+
+`gh stack unstack [<stack-no>] [--local]` removes tracking (and the stack on
+GitHub). The branches survive. If the plan turned out wrong, this plus the
+snapshot branch (`orc-run-split.md`) is a clean reset: unstack, re-plan with
+`/orc-pr-setup`, re-cut from the snapshot.
+
+## When the preview breaks under you
+
+Stacked PRs are a GitHub **public preview**. If a command in
+`../../_shared/gh-stack-commands.md` is renamed or removed:
+
+1. Do NOT hand-roll the stack with bare `git push` + manual base edits — nothing
+   retargets on merge and a half-built stack is worse than one honest big PR.
+2. Say what broke, and fall back to a single regular PR (or leave the already-
+   submitted layers as plain PRs, merged bottom-up by hand).
+3. The fix is one file: update the command table.