@azure-id/orc 1.9.2 → 2.1.0

package/templates/skills/_shared/phases/wave-grouping.md

@@ -1,133 +1,128 @@
-# Phase — Wave grouping   (id: `wave-grouping`)
-
-> **Library file.** Canonical since v1.0.0 W12; it was under the `orc` skill's
-> private `references/`, and another lane already reached across into it. Read
-> by `orc`, `orc-diy`. Layers declared: `core` only — single-layer because the
-> conflict graph is arithmetic, and a lane that groups waves at all groups
-> them this way. `orc lane phases <lane> --json` names the file and the layers
-> to read.
-
-<!-- orc:layer core -->
-## Reference — Wave Grouping & Conflict Graph
-
-Turn the tagged task list into conflict-free waves. Load during Phase 3.
-
-## Waves are computed for EVERY run — dispatch style is intra-wave only
-
-Wave computation is NOT a parallel-mode concern. It runs for **every run with ≥2
-tasks, sequential included** (dependency layers + conflict graph +
-`max_wave_tasks` cap). **Dispatch style controls only INTRA-WAVE concurrency:**
-
-- **parallel** → a wave's non-conflicting tasks dispatch at once (up to
-  `max_wave_tasks`);
-- **sequential** → the SAME waves, but a wave's tasks dispatch one at a time, in
-  order; the wave still closes only when all its tasks close.
-
-Either way the **wave-boundary gate fires identically** (the deterministic batch
-pause below binds to wave numbers, not to a dispatch style). A sequential run
-therefore never degenerates to "no waves / per-task pauses" — a 5-task plan
-becomes e.g. `[T1] [T2 T3 T4] [T5]`, not five ad-hoc stops. **Show the wave plan
-(wave → tasks → pause marks) to the user BEFORE wave 1 in BOTH styles.**
-
-## The principle
-
-Two tasks may share a wave ONLY if their `declared_files` don't overlap AND
-neither depends on the other. Conflicts are designed out by scheduling — never
-negotiated at runtime.
-
-## Algorithm
-
-1. **Dependency edges:** a task's earliest wave = max(wave of its deps) + 1.
-2. **Conflict edges:** for every pair, mark conflict if `declared_files` globs
-   intersect (expand against the repo tree; unresolvable globs conflict on
-   their literal prefix).
-3. **Assign greedily in topological order:** place each task in the earliest
-   wave where (a) all deps are earlier and (b) nothing in that wave conflicts.
-   Otherwise open a new wave.
-4. **Cap concurrency at `config.max_wave_tasks`** (default 3): a wave NEVER
-   exceeds this many tasks, even if more are conflict-free. Overflow moves to the
-   next wave. This is the efficiency cap — 3 parallel subagents by default.
-5. **Mark batch pauses:** compute the pause schedule from the user's Phase 2
-   answer — mark `is_batch_pause: true` on wave W when `W % N == 0` AND a later
-   wave exists (`W < total_waves`); the last wave is NEVER a pause (nothing
-   remains to gate). The resulting wave indices are the `pause_schedule` stored
-   in the checkpoint. A pause so marked is a HARD gate (stop-resume.md), not
-   an orchestrator judgment call.
-
-## Same-feature collision
-
-If two tasks own the same feature/files with no dependency between them, the
-graph auto-serializes them — but that's a planning smell. Surface it: suggest
-merging them into one task rather than silently serializing duplicate work.
-
-## TDD tasks are ORDINARY tasks (v0.41.0)
-
-TDD red proofs are **planner-emitted tasks**, not an orchestrator-synthesized
-Wave 0. Each one materializes the `tdd_spec` entries of the implementation task
-it guards, and that task lists it in `depends_on`. Nothing here special-cases
-them:
-
-- they enter the same conflict graph via their `declared_files` (their test
-  files), so **independent TDD tasks share a wave and run in parallel** — the
-  red proofs for two unrelated features are one wave, not two;
-- `depends_on` guarantees **a red proof is always in an earlier wave than the
-  code it proves** — a proof can never land beside its implementation;
-- they are scored from **their own planner-emitted `facets`**, like any task, so
-  no derived-vector rule is needed;
-- `max_wave_tasks`, `is_batch_pause` and `pause_schedule` bind to them unchanged.
-
-**A TDD task does NOT inherit the risk floor** of the task it guards: it
-transcribes planner-authored skeletons, writes no production code, and its output
-is asserted RED before anything is believed. The planner reflects that in the
-task's own facets (`novelty: mechanical`, `logic: none`, `risk: []`). Stated here
-so it is not re-litigated per run — the alternative is a Haiku-sized
-transcription job dispatched at floor 70 because the requirement it proves is
-auth-flavoured.
-
-**If no task carries `new-surface` or `behavior-change` entries, no TDD task
-exists and no extra wave is created.**
-
-## Orchestrator-synthesized tasks (the mock example, any future one)
-
-Some dispatched tasks appear in no `tasks[]` because the ORCHESTRATOR synthesized
-them — the mock example (`_shared/drift-recovery.md`). They still obey hard rule
-1: **dispatched like any other task, never done by you.** But they have no
-planner-emitted `facets`, and the orchestrator is by definition the party that
-did NOT read the code — inventing a vector for them is judgment wearing
-arithmetic's clothes, the exact thing the facet redesign removed.
-
-So their vector is **DERIVED, never judged**:
-
-| Facet | Value |
-|---|---|
-| `breadth` | `len(files the synthesized task will touch)` |
-| `novelty` | `mechanical` — it transcribes planner-authored material |
-| `logic` | `none` |
-| `test_surface` | per the task |
-| `risk` | `[]` — unless the synthesized task itself inherits a CITED risk |
-
-## Post-wave worktree audit (a GATE, not a report)
-
-Declarations can be wrong, and a return can be honest and still miss what
-happened. Capture `git status --short` BEFORE the wave dispatches and again
-after every task returns, then diff the two:
-- **Any path whose state changed and is in NO task's `declared_files`** → name
-  the path and the likely task, and get an explicit user decision BEFORE the
-  wave closes. A wave never closes over an unexplained worktree delta.
-- **A file that became LESS modified is as much a violation as one that became
-  more modified.** That is the revert signature — an executor made an
-  unsatisfiable assertion true by `git checkout`-ing another task's completed
-  work, returned a literally-true report, and left a CLEAN tree. Nothing that
-  reads returns can see it.
-- **Stray files count** — a path that appears at the repo root (a stdout dump, a
-  mangled-path artifact) is undeclared output, not noise to ignore.
-- Two agents in one wave touched the same undeclared file → record
-  `failure_reason: "file-collision:<file> with <agent>"`, set the
-  later-finishing task to `requeued`, re-dispatch in a later wave so it sees
-  the other's committed changes.
-- Declarations are the plan, `actual_files` is the ATTESTATION, and
-  `git status` is the AUDIT — same instruction → contract → attestation →
-  spot-check pattern the plan applies to `grounding[]`.
-- Canonical cross-lane wording: `_shared/return-validation.md` §6.
-
-<!-- /orc:layer -->
+# Phase — Wave grouping   (id: `wave-grouping`)
+
+> **Library file** (`orc`, `orc-diy`), `core` only: the conflict graph is arithmetic, and every lane that groups waves groups them this way.
+
+<!-- orc:layer core -->
+## Reference — Wave Grouping & Conflict Graph
+
+Turn the tagged task list into conflict-free waves. Load during Phase 3.
+
+## Waves are computed for EVERY run — dispatch style is intra-wave only
+
+Wave computation is NOT a parallel-mode concern. It runs for **every run with ≥2
+tasks, sequential included** (dependency layers + conflict graph +
+`max_wave_tasks` cap). **Dispatch style controls only INTRA-WAVE concurrency:**
+
+- **parallel** → a wave's non-conflicting tasks dispatch at once (up to
+  `max_wave_tasks`);
+- **sequential** → the SAME waves, but a wave's tasks dispatch one at a time, in
+  order; the wave still closes only when all its tasks close.
+
+Either way the **wave-boundary gate fires identically** (the deterministic batch
+pause below binds to wave numbers, not to a dispatch style). A sequential run
+therefore never degenerates to "no waves / per-task pauses" — a 5-task plan
+becomes e.g. `[T1] [T2 T3 T4] [T5]`, not five ad-hoc stops. **Show the wave plan
+(wave → tasks → pause marks) to the user BEFORE wave 1 in BOTH styles.**
+
+## The principle
+
+Two tasks may share a wave ONLY if their `declared_files` don't overlap AND
+neither depends on the other. Conflicts are designed out by scheduling — never
+negotiated at runtime.
+
+## Algorithm
+
+1. **Dependency edges:** a task's earliest wave = max(wave of its deps) + 1.
+2. **Conflict edges:** for every pair, mark conflict if `declared_files` globs
+   intersect (expand against the repo tree; unresolvable globs conflict on
+   their literal prefix).
+3. **Assign greedily in topological order:** place each task in the earliest
+   wave where (a) all deps are earlier and (b) nothing in that wave conflicts.
+   Otherwise open a new wave.
+4. **Cap concurrency at `config.max_wave_tasks`** (default 3): a wave NEVER
+   exceeds this many tasks, even if more are conflict-free. Overflow moves to the
+   next wave. This is the efficiency cap — 3 parallel subagents by default.
+5. **Mark batch pauses:** compute the pause schedule from the user's Phase 2
+   answer — mark `is_batch_pause: true` on wave W when `W % N == 0` AND a later
+   wave exists (`W < total_waves`); the last wave is NEVER a pause (nothing
+   remains to gate). The resulting wave indices are the `pause_schedule` stored
+   in the checkpoint. A pause so marked is a HARD gate (stop-resume.md), not
+   an orchestrator judgment call.
+
+## Same-feature collision
+
+If two tasks own the same feature/files with no dependency between them, the
+graph auto-serializes them — but that's a planning smell. Surface it: suggest
+merging them into one task rather than silently serializing duplicate work.
+
+## TDD tasks are ORDINARY tasks (v0.41.0)
+
+TDD red proofs are **planner-emitted tasks**, not an orchestrator-synthesized
+Wave 0. Each one materializes the `tdd_spec` entries of the implementation task
+it guards, and that task lists it in `depends_on`. Nothing here special-cases
+them:
+
+- they enter the same conflict graph via their `declared_files` (their test
+  files), so **independent TDD tasks share a wave and run in parallel** — the
+  red proofs for two unrelated features are one wave, not two;
+- `depends_on` guarantees **a red proof is always in an earlier wave than the
+  code it proves** — a proof can never land beside its implementation;
+- they are scored from **their own planner-emitted `facets`**, like any task, so
+  no derived-vector rule is needed;
+- `max_wave_tasks`, `is_batch_pause` and `pause_schedule` bind to them unchanged.
+
+**A TDD task does NOT inherit the risk floor** of the task it guards: it
+transcribes planner-authored skeletons, writes no production code, and its output
+is asserted RED before anything is believed. The planner reflects that in the
+task's own facets (`novelty: mechanical`, `logic: none`, `risk: []`). Stated here
+so it is not re-litigated per run — the alternative is a Haiku-sized
+transcription job dispatched at floor 70 because the requirement it proves is
+auth-flavoured.
+
+**If no task carries `new-surface` or `behavior-change` entries, no TDD task
+exists and no extra wave is created.**
+
+## Orchestrator-synthesized tasks (the mock example, any future one)
+
+Some dispatched tasks appear in no `tasks[]` because the ORCHESTRATOR synthesized
+them — the mock example (`_shared/drift-recovery.md`). They still obey hard rule
+1: **dispatched like any other task, never done by you.** But they have no
+planner-emitted `facets`, and the orchestrator is by definition the party that
+did NOT read the code — inventing a vector for them is judgment wearing
+arithmetic's clothes, the exact thing the facet redesign removed.
+
+So their vector is **DERIVED, never judged**:
+
+| Facet | Value |
+|---|---|
+| `breadth` | `len(files the synthesized task will touch)` |
+| `novelty` | `mechanical` — it transcribes planner-authored material |
+| `logic` | `none` |
+| `test_surface` | per the task |
+| `risk` | `[]` — unless the synthesized task itself inherits a CITED risk |
+
+## Post-wave worktree audit (a GATE, not a report)
+
+Declarations can be wrong, and a return can be honest and still miss what
+happened. Capture `git status --short` BEFORE the wave dispatches and again
+after every task returns, then diff the two:
+- **Any path whose state changed and is in NO task's `declared_files`** → name
+  the path and the likely task, and get an explicit user decision BEFORE the
+  wave closes. A wave never closes over an unexplained worktree delta.
+- **A file that became LESS modified is as much a violation as one that became
+  more modified.** That is the revert signature — an executor made an
+  unsatisfiable assertion true by `git checkout`-ing another task's completed
+  work, returned a literally-true report, and left a CLEAN tree. Nothing that
+  reads returns can see it.
+- **Stray files count** — a path that appears at the repo root (a stdout dump, a
+  mangled-path artifact) is undeclared output, not noise to ignore.
+- Two agents in one wave touched the same undeclared file → record
+  `failure_reason: "file-collision:<file> with <agent>"`, set the
+  later-finishing task to `requeued`, re-dispatch in a later wave so it sees
+  the other's committed changes.
+- Declarations are the plan, `actual_files` is the ATTESTATION, and
+  `git status` is the AUDIT — same instruction → contract → attestation →
+  spot-check pattern the plan applies to `grounding[]`.
+- Canonical cross-lane wording: `_shared/return-validation.md` §6.
+
+<!-- /orc:layer -->

package/templates/skills/_shared/phases/wiki-consult.md

@@ -1,11 +1,6 @@
 # Phase — Wiki consult   (id: `wiki-consult`)
 
-> **Library file.** Canonical since v1.0.0 W12; it was under the `orc` skill's
-> private `references/`, and other lanes already reached across into it. Read
-> by `orc`, `orc-mini`, `orc-fast`, `orc-wiki`. Layers declared: `core` only —
-> single-layer because the precedence ladder (`code > fresh wiki > stale wiki
-> > model priors`) does not bend for a faster lane. `orc lane phases <lane>
-> --json` names the file and the layers to read.
+> **Library file** (`orc`, `orc-mini`, `orc-fast`, `orc-wiki`), `core` only: the ladder `code > fresh wiki > stale wiki > model priors` does not bend for a faster lane.
 
 <!-- orc:layer core -->
 ## Reference — Wiki Consult (shared by orc / orc-mini / orc-fast)
@@ -148,6 +143,15 @@ actually read, or `none`. `none` on a slice that carried docs is a REAL signal
 It is the only thing that distinguishes a wiki that is working from one that is
 merely being shipped.
 
+**orc-mini only** (moved here from its spine at v2.0.0):
+
+**`none` is an answer — record it, never drop it.** `wiki_used: none` and
+`graph_used: none` from ANY return go into the checkpoint and the ship line
+(`knowledge: wiki 2 pages offered · used none · graph card 2 targets · used
+none`). Two runs in a row with `wiki_used: none` on FRESH pages → one line:
+`wiki: the selected pages were not used in 2 runs — check their TL;DRs
+(/orc-wiki)`. A signal, never a gate, never dropped for looking null.
+
 ## Scoring bonus (full lane, Phase 2)
 
 If a non-empty `wiki/` is present, use its overviews' "Notes for planning" to

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

@@ -5,14 +5,6 @@ about to edit: scouts, wiki scan-tasks, the analyst, the reviewer, and every
 executor reading a file for context rather than for change. Load this wherever
 a slice tells an agent to go read something.
 
-## Why this exists
-
-ORC's cost is dominated by parallel reading, not by thinking: up to `max_scouts`
-scouts at once, a wiki scan that is expensive by design, and every executor in a
-wave opening its declared files. A role that opens a 900-line file to learn one
-function's shape has spent the run's budget on bytes nobody needed. Reading more
-is not understanding more.
-
 ## The ladder
 
 Escalate one step at a time. Stop at the step that answers the question.
@@ -88,50 +80,6 @@ is a `needs_context` return, not permission to keep going.
    lint results — the smoke gate, the TDD gate, the verifier and orc-quick's
    build loop decide red vs green from those exact bytes. Read them whole.
 
-## Reading ORC's own payload — the partial-read discipline (v1.0.0 W10)
-
-Everything above is about reading the PROJECT. It applies unchanged to reading
-ORC's own files, and it has to: a lane manifest of pointers that every lane
-dutifully reads whole is MORE round-trips than the prose it replaced, for the
-same bytes. Centralizing prose and then reading all of it is a slower payload,
-not a smaller one.
-
-So every pointer a lane carries declares three things.
-
-| Declaration | Values | Means |
-|---|---|---|
-| `when` | `always` · `on-phase` · `on-state` · `on-demand` · `compile-time` | WHETHER to open it at all |
-| `read` | `layer` · `section` · `whole` | HOW MUCH to open |
-| `layers` | `core` · `full` · `trim` · `composed` | WHICH part, when `read: layer` |
-
-### The four rules that make it honest
-
-1. **`on-phase` is the default, and `always` must be justified.** A file every
-   lane always loads has saved nothing by moving. Each `always` pointer is
-   named in the wave that adds it.
-2. **`read: section` names a HEADING, never a line number.** A stored line
-   number is a wrong line number one edit later; a heading anchor survives an
-   edit above it. This is why a shared file's headings are part of its
-   contract — renaming one breaks every pointer into it.
-3. **A trimmed lane reads `core` plus its OWN layer, and never the `full`
-   layer.** Reading a neighbouring layer "for context" is the bleed this rule
-   exists to stop: the layer boundary is the product promise, not a suggestion.
-4. **The two exceptions above carry over unchanged.** A file you will EDIT is
-   read in full, first, always; and output a gate parses is read whole.
-5. **`compile-time` is not a run-time read at all.** `orc-diy` is a declared
-   reader of ten shared phases and opens none of them during a run: the `orc
-   diy compile` CLI reads their `composed` layer once and stitches it into
-   `FLOW-COMPILED.md`, which is the only spine that run then follows. Saying
-   `on-phase` there would describe a read that never happens, and a manifest
-   that describes a run nobody performs is the drift it exists to prevent
-   (v1.0.0 W13).
-
-### The honest limit
-
-A partial read saves round-trips and bytes for the lanes that SKIP a phase. It
-does **not** make a phase cheaper for the lane that runs it — that lane reads
-its layers whole. Any claim otherwise has to show the measurement.
-
 ## Handoff
 
 The ladder governs HOW MUCH to read. It never decides WHETHER knowledge exists —
@@ -140,6 +88,5 @@ that is `detecting-artifacts.md` — and it never overrides precedence:
 the same order gains two rungs and loses none:
 `code > graph structure (current blob) > fresh wiki > stale wiki (hints) > graph notes and doc notes > model priors`.
 
-What a lane INVOKES, and what each exit code means, is not here either: that is
-`orc lane calls <lane> --json`, whose catalogue is the one copy of every call
-two or more lanes share.
+An orchestrator reading ORC's OWN payload follows the partial-read rules in
+`phases/README.md` (§Pointer discipline).

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

@@ -4,22 +4,20 @@ Canonical procedure for validating a spawned agent's return. Every ORC lane
 (full, mini, fast, wiki, diy) runs this on EVERY return; a malformed return is
 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
+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.
+
 ## 0. Is the previous attempt still ALIVE? (v1.2.0) — BEFORE anything else
 
 > **`a lane that re-dispatches over a live attempt` has broken this contract.**
 
 **A Task error does not kill the agent behind it.** Claude Code's tool call can
 fail, time out, or be cut off mid-turn while the subagent it started keeps
-running — and keeps writing files. Every rule below this line ends in
-"re-dispatch", and every one of them silently assumed a failed call meant a dead
-agent. It does not.
-
-What that costs, measured: one graded `/orc-quick` entry put THREE
-`orc-executor-opus-5-low` agents on the SAME task — 50m19s, 115m22s and
-100m53s, **266 minutes of Opus 5.5 for one authorised dispatch**, all editing the
-same files, inside a 2h04m window. The second was dispatched 4m19s after the
-first, while the first was still working. The hook had recorded all three; no
-lane had ever read that record.
+running — and keeps writing files. Every rule below ends in "re-dispatch";
+none of them may assume that a failed call means a dead agent.
 
 ### The rule
 
@@ -49,8 +47,7 @@ A usage limit, an API error, a dropped connection or a `Ctrl+C` between a
 dispatch and its return says **nothing** about the agent. Treat it as §0 exit 2
 and ask. A lane that classifies an interruption as a failure re-dispatches into
 a live agent, gets interrupted again sooner because it is now paying twice, and
-the loop tightens on itself — which is exactly how the 266-minute entry
-happened.
+the loop tightens on itself.
 
 ### What refusing looks like
 
@@ -102,64 +99,14 @@ is on the wrong model.)
 
 ## 2b. A FOREIGN return — the SUBSTITUTION check (v0.50.0)
 
-A foreign worker (`orc extra dispatch`, `_shared/extra-dispatch.md`) is not a
-Claude subagent. It has no injected system-prompt model-id line, so **it cannot
-carry `actual_model`** — and §2 must not be faked for it. A foreign return that
-claimed an `actual_model` would be claiming evidence that does not exist.
-
-It carries instead, and every one of these is quoted from the wire rather than
-assumed:
-
-- `engine` (`api` | `claude-shim` | `cli`), `provider`, `profile`
-- `model_requested` — what the route row asked for
-- **`model_reported`** — the `model` field the endpoint echoed back
-- `usage` — the four token kinds, never blended, **or `null`**
-
-**`model_reported != model_requested` is ⛔ SUBSTITUTION**, surfaced to the user
-exactly as ⛔ DOWNGRADE is today and never silently accepted. It is the only
-defence against an aggregator quietly serving something else. `unknown` is a
-valid, honest value and is reported as `unknown` — **never as a match**.
-
-**A clean model check is not a clean answer.** An aggregator's *provider-level*
-fallback is on by default and it PRESERVES the model id, so the substitution
-check reads clean while the code went to a different company. Engine `api`
-records the response's `provider` echo and reports **⚠ REROUTE**; the other two
-engines cannot see it at all, and their `served_by_note` says so. An absent
-measurement is never a pass.
-
-**`usage: null` is not four zeros.** A worker that reported no token counts
-(engine `cli` frequently) returns `null` plus a note. `{0,0,0,0}` would tell
-`/orc-budget` the run was free. Engine `api`'s `cache_write: 0` is the opposite
-case — a real measurement — so the two must never be normalised together.
-
-**The fence is per-engine, and the return says which one it had.** Engine `api`
-ENFORCES `declared_files`; engines `claude-shim` and `cli` ASK. A return
-carrying `fence: {declared_files: false}` means the list was an instruction, not
-a rule — treat §6 below as the only real check, and say so to the user rather
-than reporting a constraint that was never applied.
-
-**A RESUMED foreign dispatch owes three more fields** (v0.54.0). The dispatch
-return sets `resume_expected: true`, so the obligation is never inferred:
-
-- **`resume_state`** — `continued` · `restarted` · `no-op`. Absent on a slice
-  with no `resumed_from` is correct; **absent on a resume slice is MALFORMED.**
-  A return claiming `restarted` while `preexisting[]` was non-empty is a
-  FINDING, not a failure — it is how `/orc-retro` learns which providers ignore
-  a resume preamble, so surface it rather than treating it as a bad return.
-- **`preexisting_read[]`** — which pre-existing files the worker actually
-  opened. Quoted like `wiki_used`: **what it did, never what the dispatcher
-  assumed.** An EMPTY list on a resume whose `preexisting[]` was not empty is an
-  honest and informative return — it says the worker ignored the preamble — and
-  it must be surfaced, never dropped.
-- **`journal_fidelity`** — relayed from the dispatch return (`per-turn` |
-  `streamed-opaque`), so a validator never reports `streamed-opaque` evidence as
-  if it had per-turn tool attribution.
-
-Everything else in this file applies to a foreign return unchanged: the
-honest-status rules, the pattern attestation, the TDD attestation, the wiki
-attestation, and above all **§6, the worktree delta** — which is engine-blind
-because it reads the worktree rather than the return, and is therefore what
-makes a foreign executor safe at all.
+Read this § only when `extra_enabled` and the return came from `orc extra
+dispatch`. A foreign worker has no system-prompt model-id line, so **it cannot
+carry `actual_model`** — never fake §2 for it. **`model_reported !=
+model_requested` is ⛔ SUBSTITUTION**, surfaced exactly as ⛔ DOWNGRADE. A
+RESUMED foreign dispatch also owes `resume_state`, `preexisting_read[]` and
+`journal_fidelity`. The full check — the wire fields, ⚠ REROUTE, `usage: null`,
+the per-engine fence and the resume fields — is `extra-dispatch.md`
+§The return contract delta. Every other § of this file applies unchanged.
 
 ## 3. Honest-status rules (executor returns)
 

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

@@ -0,0 +1,106 @@
+# The review slice — the ONE shape every lane uses
+
+> **On demand.** Read this file ONLY when a review dispatch is about to be built
+> (`/orc` Phase 5 and its composed DIY layer, `orc-review-verify/core.md`, the
+> `/orc-quick` review offer, the `/orc-mini` risk-high option, the `/orc-pr-driver`
+> per-layer gate, `/orc-ultra` gate 3). One slice, so a review in quick is the
+> same review as in `/orc`. The procedure and the return live in the agent file
+> (`.claude/agents/orc-reviewer-opus-5-low.md`), never here.
+
+## §0 Which review — only when the project names its own (v2.1.0)
+
+When the `review-policy` probe of the lane config (or `orc review policy
+--json`) says `policy: project`, a coding lane that changed code asks this ONCE
+before ship — also `/orc-fast`, and `/orc-mini` without a risk-high row (DE-8).
+A CLAUDE.md line never picks the reviewer: it adds an OPTION (H `any.review.which`).
+
+```text
+Which review for this change?
+  1. ORC review — orc-reviewer-opus-5-low (traced, gotcha card, Review Quality)
+  2. <name> — the review <file>:<line> asks for            ← recommended
+  3. Skip review (not recommended: <file>:<line> asks for one)
+```
+
+- Write `REVIEW-WHICH chose=<orc|project|skip> name=<the named review> by=user ::
+  <file>:<line>` ALWAYS (habits off too) — and ONLY under `policy: project`. With habits on, also the ASK line.
+- **1** → this slice, as the lane already does. **2** → run the named skill or
+  command (the Skill tool takes both), then §3 on its findings with
+  `reviewer: "<name>"` on each observation — no ORC reviewer is dispatched.
+  **3** → no review; the summary says the project asked for one.
+- An external review has no hook trace, no gotcha card and no required
+  `category`/`scenario`/`pre_existing`: §3 fills `category: uncategorized` where
+  it cannot map one, and Review Quality counts it in its own line.
+
+Slice fields: changed_files[] · diff_ranges[] · acceptance_criteria[] · constraints[] · code_pattern · invariants[] · validation_gate[] · fe_rules[] · security_checklist[] · graph_changes · tool_findings[] · gotcha_card · rules_card · previous_findings[] · mode
+
+## §1 R1 — the free check (before ANY review dispatch)
+
+The free check always runs before the paid one. On the changed files only:
+
+1. Run the project's OWN lint and type check. Take the commands from
+   `wiki-meta.json` `commands`; else the `package.json` scripts named `lint` /
+   `typecheck`; else the `pyproject` / `Makefile` targets of those names; else
+   `sonar-scanner` when the project already has it. **Never invent a command.
+   Never install tooling.** No command found → `tool_findings[]` is empty; say so
+   in one line.
+2. Run `orc rules lint --diff` (free, zero tokens).
+3. Keep only the output lines that land on a changed file → `tool_findings[]`
+   (`{tool, location, message}`). **The reviewer must not re-report them.**
+
+`/orc-ultra` gate 3 reuses this step (it does not run a second copy); a fix wave
+that changed files re-runs it first.
+
+## §2 The fields
+
+| Field | Source |
+|---|---|
+| `changed_files[]`, `diff_ranges[]` | git — `diff_ranges` are the changed line ranges per file (R2) |
+| `acceptance_criteria[]`, `constraints[]` | the plan / the quick entry |
+| `code_pattern`, `invariants[]`, `validation_gate[]` | the pattern cache (or null / empty) |
+| `fe_rules[]`, `security_checklist[]` | FE diffs / `mode: security` only, else empty |
+| `graph_changes` | `orc graph changes --if-enabled --json` — **keeps its rows: no `--brief` here** |
+| `tool_findings[]` | §1 |
+| `gotcha_card` | `orc gotcha card --files <changed csv> --lane <lane> --json` → `text` |
+| `rules_card` | `orc rules slice --lane <lane> --json` → `text` (a lane with no rules → null) |
+| `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,
+  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
+a touched file, and a symbol nobody edited is not a finding. An unchanged caller of
+a changed signature is a finding candidate, anchored like any other.
+- **`gotcha_card` is ALWAYS built** when anything matches — no switch removes it
+  (`gotcha_card_budget` is only its size). Exit 1 (no match) → null, the normal
+  case. Its header counts what the budget dropped; never cut it silently.
+  The session hook ALSO hands it to every `orc-reviewer-*`, `orc-verifier-*` and
+  `orc-judge-*` at `SubagentStart` (v2.0.2), so a slice that forgot it still has it.
+  Before the card, run `orc gotcha sync --json` (it is due at most once per
+  `gotcha_sync_hours`); exit 2 (a CLI that has no `sync`) or any failure → go on.
+- **`mode: disprove`** carries only the P0/P1 findings to test and their files.
+
+## §3 After the return — the after-filter (R10)
+
+The reviewer reports EVERY finding. Then, before the ladder acts:
+
+1. Pipe the findings to `orc gotcha filter --findings - --json`. It drops P2/P3
+   that a `suppress` gotcha names, folds P3 above 5 into `+N similar`, and applies
+   the category noise budget. **It never removes a P0 or P1.** Keep its `kept`;
+   list its `removed[]` (each with the `by` id) in the run summary — a count is
+   not consent.
+2. `pre_existing: true` findings (on a line outside `diff_ranges`) go to their own
+   bucket. They never gate.
+3. A P0/P1 with no `scenario`, or with `confidence: low`, becomes P2.
+4. Findings that share a `group` are ONE fix: the P0 fix, the P1 ask and the P2
+   batch are made per group (R7).
+
+5. At review close, record one observation per finding and emit the
+   `FINDING-OUTCOME` line — `gotchas.md` §10 "Review close" (`/orc` Phase 7,
+   `/orc-mini` after its risk option, `/orc-quick` after the review offer).
+6. In the same step, store the reviewed ranges (`diff_ranges`) with ONE
+   `orc gotcha observe -` call, body `{"kind": "review-scope", run, commit,
+   files}` (DE-13, "Review close"). The CLI computes a later fix's `miss` from it.
+
+**Superpowers path** (DE-13): after the Superpowers review skill returns, run
+this §3 on its findings too, outcomes included — never a second reviewer dispatch.