@azure-id/orc 0.56.0 → 1.0.0

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

@@ -1,167 +1,196 @@
----
-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).
+---
+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.

package/templates/skills/orc-pr-driver/references/orc-run-split.md

@@ -35,7 +35,7 @@ Any path in `git status --short` that is missing from that diff → **STOP**. Do
 proceed with a partial snapshot.
 
 Note the excluded-but-listed paths (generated code, lockfiles, vendored trees —
-`../_shared/stack-plan.md`): they are still real files that must land in some
+`../../_shared/stack-plan.md`): they are still real files that must land in some
 layer, they just do not count toward a budget.
 
 ## Step 2 — start the stack from the trunk