@azure-id/orc 2.1.0 → 2.2.0

package/templates/skills/_shared/pr-templates.md

@@ -1,106 +1,108 @@
-# Shared contract — PR-description template resolution (stacked + regular)
-
-Canonical, single-copy rule for WHERE a PR body comes from. Read by ORC's
-ship-phase stack gate (`orc/subskills/orc-pr/stack-gate.md`), `orc-pr-setup`
-(which records the resolved source in the plan) and `orc-pr-driver` (which fills
-it per layer). A stacked PR without a real template is a wall of prose in N
-copies — so template resolution is a **gate**, not a nicety.
-
-## Resolution order (first hit wins — probe, never guess)
-
-1. **ORC template** — `.claude/skills/orc/subskills/orc-pr/pr.md`. Counts as
-   available only when the team REPLACED it: if the file still contains its
-   `PLACEHOLDER` marker, treat it as **not available** and keep looking.
-2. **Project template** — first existing of
-   `.github/pull_request_template.md` · `.github/PULL_REQUEST_TEMPLATE.md` ·
-   any `.github/PULL_REQUEST_TEMPLATE/*.md` (more than one → ask which) ·
-   `docs/pull_request_template.md` · a `docs/**` file whose name contains both
-   `pr`/`pull-request` and `template`.
-3. **CLAUDE.md** — a PR-template section in the repo's `CLAUDE.md` (a heading
-   matching `PR template` / `pull request template`, or a fenced block labelled
-   as one). Use the section body verbatim as the template.
-4. **Nothing found → RECOMMEND, one question, three options** (below). The user
-   picks one, pastes their own, or declines.
-5. **User declines every option → the stacked PR is SKIPPED.** Say so in one
-   line and push/PR the change **regularly**, as one PR. Never invent a house
-   template and never stack without one — a template is what makes N layer
-   bodies readable.
-
-Record the winner as `pr template:` in the stack plan
-(`orc | project:<path> | claude.md | picked:<name>`) so the driver never
-re-resolves and the two lanes cannot disagree.
-
-## The three recommended options (offer all three, with this framing)
-
-### Option A — `minimal` (fastest to review; good default for small teams)
-
-```markdown
-## What
-<one paragraph — what this PR changes>
-
-## Why
-<the ticket's intent in one or two lines>
-
-## How to verify
-<commands or steps a reviewer runs>
-```
-
-### Option B — `context-first` (best for stacked PRs — carries the layer's place in the chain)
-
-```markdown
-## Summary
-<what this layer does, one paragraph>
-
-## Why this layer exists
-<purpose + value class; for FOUNDATION, name the consumer layer>
-
-## Not in this PR
-<what a reviewer might expect but will find in another layer> → layer <n>
-
-## Verification
-- build: <command + result>
-- tests: <command + result>
-- lint: <command + result>
-
-## Notes for reviewers
-<excluded-from-budget files, risks, rollback>
-```
-
-### Option C — `risk-and-rollback` (best for payment/data paths and regulated changes)
-
-```markdown
-## Change
-<what changes, in behavioral terms>
-
-## Blast radius
-<surfaces, consumers, data touched>
-
-## Risk & mitigation
-<what can go wrong; what guards it>
-
-## Rollback
-<exact revert/flag-off procedure>
-
-## Evidence
-build · tests · lint · manual checks (commands + results)
-```
-
-On a pick, offer once to save it as `.github/pull_request_template.md` (a repo
-change — never write it unasked). Declined → the template is used for this stack
-only and lives in the plan.
-
-## Per-layer fill rules (stacked PRs)
-
-Whatever template wins, every layer's body ALSO carries these four facts —
-appended if the template has no home for them:
-
-- **Layer `n` of `N`** + the ticket, and the stack map GitHub renders above it.
-- **Purpose + value class** (`USER | OPERATOR | CONTRACT | FOUNDATION`, with the
-  consumer layer named for FOUNDATION).
-- **Deliberately NOT here** → the layer that has it. This is what stops a
-  reviewer from rejecting a layer for something the next layer fixes.
-- **Excluded-from-budget files**, listed — generated/vendored/lockfiles that the
-  numbers ignore but the reviewer should still see.
-
-Regular (unstacked) PRs use the same resolution order and none of the four
-layer facts.
+# Shared contract — PR-description template resolution (stacked + regular)
+
+Canonical, single-copy rule for WHERE a PR body comes from. Read by ORC's
+ship-phase stack gate (`orc/subskills/orc-pr/stack-gate.md`), `orc-pr-setup`
+(which records the resolved source in the plan) and `orc-pr-driver` (which fills
+it per layer). A stacked PR without a real template is a wall of prose in N
+copies — so template resolution is a **gate**, not a nicety.
+
+## Resolution order (first hit wins — probe, never guess)
+
+1. **ORC template** — `.claude/skills/orc/subskills/orc-pr/pr.md`. Counts as
+   available only when the team REPLACED it: if the file still contains its
+   `PLACEHOLDER` marker, treat it as **not available** and keep looking.
+2. **Project template** — first existing of
+   `.github/pull_request_template.md` · `.github/PULL_REQUEST_TEMPLATE.md` ·
+   any `.github/PULL_REQUEST_TEMPLATE/*.md` (more than one → ask which) ·
+   `docs/pull_request_template.md` · a `docs/**` file whose name contains both
+   `pr`/`pull-request` and `template`.
+3. **CLAUDE.md** — a PR-template section in the repo's `CLAUDE.md` (a heading
+   matching `PR template` / `pull request template`, or a fenced block labelled
+   as one). Use the section body verbatim as the template.
+4. **Nothing found → RECOMMEND, one question, three options** (below). The user
+   picks one, pastes their own, or declines.
+5. **User declines every option → the stacked PR is SKIPPED.** Say so in one
+   line and push/PR the change **regularly**, as one PR. Never invent a house
+   template and never stack without one — a template is what makes N layer
+   bodies readable.
+
+Record the winner as `pr template:` in the stack plan
+(`orc | project:<path> | claude.md | picked:<name>`) so the driver never
+re-resolves and the two lanes cannot disagree.
+
+## The three recommended options (offer all three, with this framing)
+
+### Option A — `minimal` (fastest to review; good default for small teams)
+
+```markdown
+## What
+<one paragraph — what this PR changes>
+
+## Why
+<the ticket's intent in one or two lines>
+
+## How to verify
+<commands or steps a reviewer runs>
+```
+
+### Option B — `context-first` (best for stacked PRs — carries the layer's place in the chain)
+
+```markdown
+## Summary
+<what this layer does, one paragraph>
+
+## Why this layer exists
+<purpose + value class; for FOUNDATION, name the consumer layer>
+
+## Not in this PR
+<what a reviewer might expect but will find in another layer> → layer <n>
+
+## Verification
+- build: <command + result>
+- tests: <command + result>
+- lint: <command + result>
+
+## Notes for reviewers
+<excluded-from-budget files, risks, rollback>
+```
+
+### Option C — `risk-and-rollback` (best for payment/data paths and regulated changes)
+
+```markdown
+## Change
+<what changes, in behavioral terms>
+
+## Blast radius
+<surfaces, consumers, data touched>
+
+## Risk & mitigation
+<what can go wrong; what guards it>
+
+## Rollback
+<exact revert/flag-off procedure>
+
+## Evidence
+build · tests · lint · manual checks (commands + results)
+```
+
+On a pick, offer once to save it as `.github/pull_request_template.md` (a repo
+change — never write it unasked). Declined → the template is used for this stack
+only and lives in the plan: `picked:<name>` records the NAME only; a template the
+user pasted goes VERBATIM in one fenced block under `## PR template`, so the
+probe never reads its `<…>` slots.
+
+## Per-layer fill rules (stacked PRs)
+
+Whatever template wins, every layer's body ALSO carries these four facts —
+appended if the template has no home for them:
+
+- **Layer `n` of `N`** + the ticket, and the stack map GitHub renders above it.
+- **Purpose + value class** (`USER | OPERATOR | CONTRACT | FOUNDATION`, with the
+  consumer layer named for FOUNDATION).
+- **Deliberately NOT here** → the layer that has it. This is what stops a
+  reviewer from rejecting a layer for something the next layer fixes.
+- **Excluded-from-budget files**, listed — generated/vendored/lockfiles that the
+  numbers ignore but the reviewer should still see.
+
+Regular (unstacked) PRs use the same resolution order and none of the four
+layer facts.

package/templates/skills/_shared/read-ladder.md

@@ -18,7 +18,13 @@ Escalate one step at a time. Stop at the step that answers the question.
 
 ## Step 0 — ask the graph (always first; the CLI decides if it is on)
 
-Before step 1, run `orc graph ctx <symbol|file[:line]> --if-enabled --json --brief`
+Your slice carries `graph_anchors` (up to 12 `path:a-b` ranges, one `read all:` command and, when present, a fenced block with the code of every range) →
+`graph_anchors` may carry the code of its ranges inline — use it as already read; do NOT read those ranges again. Without the code, your FIRST call prints every range (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle.
+Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. A file you will EDIT is still read in full first (exception 1). The inline code and the ranges are real bytes of the current blob. Then
+`orc graph ctx <name> --source --if-enabled --json --brief` for a symbol the anchors do not cover.
+Never read again a range the anchors printed.
+
+With no `graph_anchors`, before step 1, run `orc graph ctx <symbol|file[:line]> --if-enabled --json --brief`
 yourself. You do not need to know whether the graph is on. Exit 0 → the card
 answers step 1 and step 2 together: where the symbol is, its line range, who
 calls or uses it, what it calls, and which effects it has. Then continue at
@@ -46,7 +52,7 @@ list of candidates. Without an LSP tool, or with `lsp_at: null`, the ladder
 continues as before.
 
 Exit 3 (off) → skip step 0 for the rest of the task. Exit 1 (no index) or 4 (not
-in the graph) → step 1 as before. Name the card targets you used in
+in the graph) → step 1 as before. Name the pack or card targets you used in
 `graph_used`. Both exceptions below apply unchanged.
 Canonical: `code-graph.md`.
 

package/templates/skills/_shared/return-validation.md

@@ -6,7 +6,7 @@ a failure (requeue/re-dispatch with reason — lane sets the retry cap).
 
 **Read the SECTION, not the file.** Every return: §1–§3. Then ONLY the § of
 each field the slice carried — §4 `pattern`, §5 `tdd_spec`, §5b wiki, §5b.1
-graph cards, §5c the rules card, §5d `repro`. §2b only for a foreign return. §0
+the graph pack, §5c the rules card, §5d `repro`. §2b only for a foreign return. §0
 only before a re-dispatch. §6 only after a wave. §7 only on a repair loop. The §
 numbers are anchors: never renumber or rename a § heading.
 
@@ -141,15 +141,19 @@ shipped into every slice and read by nobody is the failure mode this field
 exists to make visible, and it is invisible if `none` is quietly dropped. Absent
 on a slice that carried wiki material is malformed. Not required otherwise.
 
-## 5b.1 Graph attestation (when code-graph cards were injected — v1.8.0)
+## 5b.1 Graph attestation (when the slice carried `graph_anchors` — v2.2.0)
 
-A task whose slice carried `orc graph ctx` cards must return **`graph_used`** —
-`{targets, generation}`: the card targets it ACTUALLY used (or `none`), and the `generation`
-the cards carried. The same honesty rule as `wiki_used`: `none` is informative (the cards did
-not help), absent is malformed, and a lane never drops it. A `generation` lower than the one
+A task whose slice carried `graph_anchors` (or that ran `orc graph ctx` itself) must return
+**`graph_used`** — `{targets, generation}`: the anchors (`path:a-b`) it ACTUALLY used
+(or `none`), and the `generation` of the anchors call. The same honesty rule as `wiki_used`: `none`
+is informative (the anchors did not help), absent is malformed, and a lane never drops it. A `generation` lower than the one
 `orc graph status` reports now means the agent acted on an OLD index — record it, do not
 re-run the task for it alone. Canonical: `code-graph.md`.
 
+A planner task MAY carry `precedent[]` — read-only files this task copies behaviour or style
+from (max 5). It is OPTIONAL: absent is fine and never makes a plan malformed. When present, the
+lane passes it as the pack's `--refs=`.
+
 ## 5c. Rules attestation (when the anti-slop card was injected — v1.7.0)
 
 A slice assembled by `orc rules slice` (`phases/rules.md`) must return three

package/templates/skills/_shared/review-slice.md

@@ -65,7 +65,7 @@ that changed files re-runs it first.
 | `previous_findings[]` | the checkpoint, on a re-review ONLY (R9), each with its outcome |
 | `mode` | `review` · `disprove` · `security` |
 
-- **`graph_changes`** (`code-graph.md` §7): the symbols THIS diff's hunks overlap,
+- **`graph_changes`** (`code-graph.md` §0 step 4, §7): the symbols THIS diff's hunks overlap,
   each with its callers, its tests and a risk word that carries its own reason.
   The reviewer is handed `symbols[].caller_files` and reads them.
 It replaces a whole-file `orc graph impact` here: a file card reports every symbol in

package/templates/skills/_shared/stack-plan.md

@@ -1,135 +1,135 @@
-# Shared contract — the stack plan (`stack-plan.md`) + the `STACK-FROM` handoff
-
-Canonical, single-copy contract for stacked pull requests. `orc-pr-setup` WRITES
-the plan; `orc-pr-driver` READS it; ORC's ship-phase stack gate
-(`orc/subskills/orc-pr/stack-gate.md`) hands off to one or the other. All three
-read this file — the schema is never remembered.
-
-## Location (one path, no ambiguity)
-
-```
-stacked-pr/<slug>/stack-plan.md
-```
-
-Project root, visible, **committed** — same class of deliverable as
-`poly-repo-implementation/` and `test-generator/`. Never inside `.claude/`,
-never inside the run folder (the installer replaces skill dirs; a plan there
-would vanish on `orc update`). `<slug>` is kebab-case from the change or the
-ticket (`[a-z0-9-]`, ≤32 chars). The `orc pr stack template [<slug>]` CLI writes
-the same path, so a hand-filled plan and a generated one are indistinguishable
-to the driver.
-
-## Existence probe (deterministic — never an ad-hoc `find`)
-
-`orc pr stack status [<slug>]` — exit **0** = a READY plan (exists, no unfilled
-`<...>` placeholders, ≥2 layers), exit **1** = absent or unfilled. Same
-exit-code convention as `orc pattern status <lang>` and `orc diy status`. Run it
-FIRST; do not second-guess a positive probe.
-
-## Budget mechanics (measured, not estimated)
-
-Per layer: `git diff --numstat <that layer's base>..<layer head>`.
-
-- **LoC = additions + deletions** over non-excluded files.
-- **Excluded from LoC AND from the file count:** generated code (`*.pb.go`,
-  `*_gen.go`, mocks, openapi/swagger output), lockfiles (`go.sum`,
-  `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`,
-  `poetry.lock`), `vendor/`, `node_modules/`, `testdata/` fixtures, and pure
-  renames/moves with no content change. Excluded files are still **LISTED in the
-  PR body** — a reviewer must know they exist.
-- **Tests COUNT** toward the budget (they are reviewable code). A layer over
-  budget *only* because of tests may split its tests into their own layer rather
-  than splitting logic badly.
-- **Ceilings** come from config (`orc/config.md`): `stacked_pr_loc` (default
-  1000) is the per-layer LoC hard max; `stacked_pr_files` (default 20) is the
-  hard max file count, with **half of it the soft target**. Over either → split,
-  or the user explicitly overrides and the override is logged under
-  `## Accepted exceptions`.
-- **Sizing beats budget-gaming.** A 999-LoC / 20-file layer that mixes handler +
-  migration is a FAIL even though it is under budget. The budget is a ceiling,
-  not a definition of a good layer.
-- **Unsplittable atom:** when the smallest coherent unit alone exceeds a ceiling,
-  do NOT fake-split it — flag it, state why, and ask the user to accept the
-  oversized layer (the P0 gate path).
-- **Layer cap** `stacked_pr_max_layers` (default 6): ≤ cap proceed · cap+1..cap+2
-  warn and require an explicit user override · beyond that **STOP** and
-  recommend multiple stacks or a phased release. N layers = N full CI runs.
-
-## Schema (the contract between the lanes)
-
-```markdown
-# Stack plan: <feature>
-
-- ticket: <TICKET-123>            # REQUIRED — branch names and layer titles derive from it
-- repo: <owner/name>              # same repo for every layer (cross-fork is unsupported)
-- trunk: <main>                   # the bottom layer's base
-- entry mode: greenfield | orc-run   # orc-run = ORC already built the change (file-granular split)
-- pr template: <resolved source>  # orc | project:<path> | claude.md | picked:<name>
-- totals: <LoC> LoC · <n> files · <n> layers
-
-## Layers
-| # | branch | purpose (1 line) | value class | files | LoC | depends on | build-alone? |
-|---|--------|------------------|-------------|-------|-----|------------|--------------|
-
-## Layer <n> — <title>
-- Purpose: <one line — no purpose means it is not a layer>
-- Value class: USER | OPERATOR | CONTRACT | FOUNDATION (+ consumer layer if FOUNDATION)
-- Files: <explicit list — every path, no globs>
-- Excluded-from-budget files: <listed, uncounted>
-- Deliberately NOT here: <what a reviewer might expect> → layer <m>
-- Green-gate commands: build · test scope · lint scope (`--new-from-rev <this layer's base>`)
-- Gate status: GREEN | RED <step> | NOT RUN
-- Risk / rollback: <one line>
-
-## Decisions
-<every P0 gate answer: boundary, the options offered, what the user chose, why>
-
-## Accepted exceptions
-<over-budget layers, oversize atoms, FOUNDATION chains, layer-cap overrides>
-```
-
-**Driver hard gate:** a plan with an unanswered UNCERTAIN, a missing ticket, a
-layer with no purpose or no value class, a FOUNDATION layer naming no consumer,
-or fewer than 2 layers is **not runnable**. The driver says which field is
-missing and stops — it never fills a field in for the user.
-
-## The `STACK-FROM` handoff block
-
-Written into the stack-plan folder as `stacked-pr/<slug>/STACK-FROM.md` by
-whoever hands off (ORC's ship gate, or `orc-pr-setup` → `orc-pr-driver`). Same
-shape as `_shared/fallback-handoff.md`: the writer announces one line, writes the
-block, then invokes the reader pointing at it.
-
-```
-STACK-FROM: orc-ship | orc-pr-setup
-TICKET: <TICKET-123>
-SLUG: <kebab-slug>
-PLAN: stacked-pr/<slug>/stack-plan.md   # or "none — plan the layers first"
-ENTRY-MODE: greenfield | orc-run
-PR-TEMPLATE: orc | project:<path> | claude.md | picked:<name>
-CHANGE: <one-line description of the change being stacked>
-SURFACE: <n> files · <n> LoC (excluded paths already removed)
-RUN-DIR: <.claude/orc/run/{run-slug}/ if an ORC run produced the change, else "none">
-BUILD-GREEN: true | false          # false is a hard stop — never stack a red build
-```
-
-**Reader side.** Acknowledge the source + ticket in one line, run the existence
-probe, and skip anything already carried: an attached PLAN replaces the planner
-lane entirely; `ENTRY-MODE: orc-run` means the code is ALREADY in the worktree,
-so the driver splits what exists (file-granular, below) instead of writing code;
-a `RUN-DIR` gives the driver the run's task graph, acceptance criteria, and
-verify evidence for free.
-
-## Entry modes (exactly two)
-
-- **`greenfield`** — nothing is written yet. Plan the layers up front, then build
-  layer by layer. The cheapest, cleanest path.
-- **`orc-run`** — an ORC build already produced the whole change in the worktree.
-  The split is **FILE-GRANULAR ONLY**: each changed file belongs to exactly one
-  layer, and ORC's per-task `declared_files` is the seam evidence. **Hunk surgery
-  is forbidden** — a file whose content belongs in two layers is an UNCERTAIN, and
-  the default answer offered is "the whole file lands in the LOWEST layer that
-  needs it".
-
-Splitting an already-open fat PR (the retro case, `gh stack link`) is **out of
-scope**: say so and ship the change as one regular PR instead.
+# Shared contract — the stack plan (`stack-plan.md`) + the `STACK-FROM` handoff
+
+Canonical, single-copy contract for stacked pull requests. `orc-pr-setup` WRITES
+the plan; `orc-pr-driver` READS it; ORC's ship-phase stack gate
+(`orc/subskills/orc-pr/stack-gate.md`) hands off to one or the other. All three
+read this file — the schema is never remembered.
+
+## Location (one path, no ambiguity)
+
+```
+stacked-pr/<slug>/stack-plan.md
+```
+
+Project root, visible, **committed** — same class of deliverable as
+`poly-repo-implementation/` and `test-generator/`. Never inside `.claude/`,
+never inside the run folder (the installer replaces skill dirs; a plan there
+would vanish on `orc update`). `<slug>` is kebab-case from the change or the
+ticket (`[a-z0-9-]`, ≤32 chars). The `orc pr stack template [<slug>]` CLI writes
+the same path, so a hand-filled plan and a generated one are indistinguishable
+to the driver.
+
+## Existence probe (deterministic — never an ad-hoc `find`)
+
+`orc pr stack status [<slug>]` — exit **0** = a READY plan (exists, no unfilled
+`<...>` placeholder outside an HTML comment or a fenced block, ≥2 layers), exit **1** = absent or unfilled. Same
+exit-code convention as `orc pattern status <lang>` and `orc diy status`. Run it
+FIRST; do not second-guess a positive probe.
+
+## Budget mechanics (measured, not estimated)
+
+Per layer: `git diff --numstat <that layer's base>..<layer head>`.
+
+- **LoC = additions + deletions** over non-excluded files.
+- **Excluded from LoC AND from the file count:** generated code (`*.pb.go`,
+  `*_gen.go`, mocks, openapi/swagger output), lockfiles (`go.sum`,
+  `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`,
+  `poetry.lock`), `vendor/`, `node_modules/`, `testdata/` fixtures, and pure
+  renames/moves with no content change. Excluded files are still **LISTED in the
+  PR body** — a reviewer must know they exist.
+- **Tests COUNT** toward the budget (they are reviewable code). A layer over
+  budget *only* because of tests may split its tests into their own layer rather
+  than splitting logic badly.
+- **Ceilings** come from config (`orc/config.md`): `stacked_pr_loc` (default
+  1000) is the per-layer LoC hard max; `stacked_pr_files` (default 20) is the
+  hard max file count, with **half of it the soft target**. Over either → split,
+  or the user explicitly overrides and the override is logged under
+  `## Accepted exceptions`.
+- **Sizing beats budget-gaming.** A 999-LoC / 20-file layer that mixes handler +
+  migration is a FAIL even though it is under budget. The budget is a ceiling,
+  not a definition of a good layer.
+- **Unsplittable atom:** when the smallest coherent unit alone exceeds a ceiling,
+  do NOT fake-split it — flag it, state why, and ask the user to accept the
+  oversized layer (the P0 gate path).
+- **Layer cap** `stacked_pr_max_layers` (default 6): ≤ cap proceed · cap+1..cap+2
+  warn and require an explicit user override · beyond that **STOP** and
+  recommend multiple stacks or a phased release. N layers = N full CI runs.
+
+## Schema (the contract between the lanes)
+
+```markdown
+# Stack plan: <feature>
+
+- ticket: <TICKET-123>            # REQUIRED — branch names and layer titles derive from it
+- repo: <owner/name>              # same repo for every layer (cross-fork is unsupported)
+- trunk: <main>                   # the bottom layer's base
+- entry mode: greenfield | orc-run   # orc-run = ORC already built the change (file-granular split)
+- pr template: <resolved source>  # orc | project:<path> | claude.md | picked:<name>
+- totals: <LoC> LoC · <n> files · <n> layers
+
+## Layers
+| # | branch | purpose (1 line) | value class | files | LoC | depends on | build-alone? |
+|---|--------|------------------|-------------|-------|-----|------------|--------------|
+
+## Layer <n> — <title>
+- Purpose: <one line — no purpose means it is not a layer>
+- Value class: USER | OPERATOR | CONTRACT | FOUNDATION (+ consumer layer if FOUNDATION)
+- Files: <explicit list — every path, no globs>
+- Excluded-from-budget files: <listed, uncounted>
+- Deliberately NOT here: <what a reviewer might expect> → layer <m>
+- Green-gate commands: build · test scope · lint scope (`--new-from-rev <this layer's base>`)
+- Gate status: GREEN | RED <step> | NOT RUN
+- Risk / rollback: <one line>
+
+## Decisions
+<every P0 gate answer: boundary, the options offered, what the user chose, why>
+
+## Accepted exceptions
+<over-budget layers, oversize atoms, FOUNDATION chains, layer-cap overrides>
+```
+
+**Driver hard gate:** a plan with an unanswered UNCERTAIN, a missing ticket, a
+layer with no purpose or no value class, a FOUNDATION layer naming no consumer,
+or fewer than 2 layers is **not runnable**. The driver says which field is
+missing and stops — it never fills a field in for the user.
+
+## The `STACK-FROM` handoff block
+
+Written into the stack-plan folder as `stacked-pr/<slug>/STACK-FROM.md` by
+whoever hands off (ORC's ship gate, or `orc-pr-setup` → `orc-pr-driver`). Same
+shape as `_shared/fallback-handoff.md`: the writer announces one line, writes the
+block, then invokes the reader pointing at it.
+
+```
+STACK-FROM: orc-ship | orc-pr-setup
+TICKET: <TICKET-123>
+SLUG: <kebab-slug>
+PLAN: stacked-pr/<slug>/stack-plan.md   # or "none — plan the layers first"
+ENTRY-MODE: greenfield | orc-run
+PR-TEMPLATE: orc | project:<path> | claude.md | picked:<name>
+CHANGE: <one-line description of the change being stacked>
+SURFACE: <n> files · <n> LoC (excluded paths already removed)
+RUN-DIR: <.claude/orc/run/{run-slug}/ if an ORC run produced the change, else "none">
+BUILD-GREEN: true | false          # false is a hard stop — never stack a red build
+```
+
+**Reader side.** Acknowledge the source + ticket in one line, run the existence
+probe, and skip anything already carried: an attached PLAN replaces the planner
+lane entirely; `ENTRY-MODE: orc-run` means the code is ALREADY in the worktree,
+so the driver splits what exists (file-granular, below) instead of writing code;
+a `RUN-DIR` gives the driver the run's task graph, acceptance criteria, and
+verify evidence for free.
+
+## Entry modes (exactly two)
+
+- **`greenfield`** — nothing is written yet. Plan the layers up front, then build
+  layer by layer. The cheapest, cleanest path.
+- **`orc-run`** — an ORC build already produced the whole change in the worktree.
+  The split is **FILE-GRANULAR ONLY**: each changed file belongs to exactly one
+  layer, and ORC's per-task `declared_files` is the seam evidence. **Hunk surgery
+  is forbidden** — a file whose content belongs in two layers is an UNCERTAIN, and
+  the default answer offered is "the whole file lands in the LOWEST layer that
+  needs it".
+
+Splitting an already-open fat PR (the retro case, `gh stack link`) is **out of
+scope**: say so and ship the change as one regular PR instead.

package/templates/skills/_shared/wait.md

@@ -132,14 +132,23 @@ no model runs during it.
 
 ```
 1. Write the hand-back for the mode (above).
+1a. `orc wait start <spec> --mode <m> --trigger <user|gate>`
 2. remaining = the requested time, or resets_at - now
 3. hop = min(wait_hop_minutes, remaining)
 4. Run a DETACHED command that waits hop seconds.
 5. On wake: `orc usage check --json`
 6. Exit 0, or the requested time has elapsed → continue. Else go to 3.
 7. wait_max_hops reached → stop, keep the hand-back, say why.
+8. `orc wait end --reason <elapsed|recovered|cancelled|max-hops>`
 ```
 
+Steps 1a and 8 are how the CLI knows a wait is running: `orc wait start` records
+it in `wait.json` and `orc wait end` closes it. The computed gate passes
+`--trigger gate`. With no run in flight, `start` records nothing and answers
+`recorded: false`; that is an answer, and the wait continues. A wait's activity
+is COMPUTED from its start and the clock, so a wait that a dead session left
+open reads `stale` in `orc wait status`, never `waiting`.
+
 **A hop is short on purpose.** Each wake-up is session activity, and session
 activity is the only thing that makes the statusline run again — so each hop
 buys a fresh reading. A single long sleep wakes into a reading as stale as the
@@ -233,10 +242,13 @@ in the trace enum and has no `run-<lane>-<slug>` pointer — the `/orc-explain`
 precedent, a stated blind spot rather than an oversight.
 
 ```
-WAIT   mode=hard requested=30m start=18:44 end=19:14 hops=1/4 trigger=user
-WAIT   block reason="window resets in 5m, task needs 10" by=user
+WAIT   mode=hard requested=30m start=18:44 end=19:14 hops=1/5 trigger=user
+WAIT   end :: done=1/1 reason=elapsed
+WAIT   block :: reason="window resets in 5m, task needs 10" by=user
 WAIT   unblock
 ```
 
+`hops=` is planned hops / `wait_max_hops`.
+
 A wait that leaves no line cannot be counted, and a block that leaves no line
 hides the fact that a run continued through a gate on the user's authority.

package/templates/skills/context-combiner/SKILL.md

@@ -184,8 +184,8 @@ Full lane only. `orc-analyze-mini` / `orc-mini` do not use the combiner.
 
 ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
 
-- **Calls:** `orc lane calls context-combiner --json` names every call and its exit codes.
-  **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
+- **Calls:** `orc lane calls context-combiner --json` names shared calls and exit codes.
+  **An exit code is an ANSWER where it says so, not a failure.** Own calls are here; make no other.
 - **Config:** `orc lane config context-combiner --json`. Obey `effective`. Never merge
   `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`). Nothing
   here is contested, gated or a stop: no preflight line, no gate to honour.