@azure-id/orc 0.56.1 → 1.1.0

package/templates/skills/{orc/references/trace-protocol.md → _shared/phases/trace.md}

@@ -1,4 +1,14 @@
-# Reference — Behavior-Trace Protocol
+# Phase — Behavior trace   (id: `trace`)
+
+> **Library file.** Canonical since v1.0.0 W11; it was
+> the `orc` skill's own `trace-protocol` reference, and 26 lanes reached
+> across into one lane's private folder to read it. Layers declared: `core` only — the protocol
+> is identical in every lane that traces, and this phase's per-lane variation is
+> the TIER TABLE below, which is DATA, not a layer. `orc lane phases <lane>
+> --json` names the file and the layers to read; `README.md` in this folder
+> holds the closed layer set.
+
+<!-- orc:layer core -->
 
 How ORC records its own behavior for later review. **Behavior-trace logging is
 PERMANENT (always on) — there is no config toggle.** Every ORC run traces.
@@ -88,7 +98,7 @@ decisions: >              # free text — the WHY layer
 | Multi-dispatch | `orc-wiki`, `orc-pr-driver` (lane `prdriver`) | orc-wiki: one per scan-batch boundary (the points that already run the registration sync / offer the pause) + the end-of-run packet. orc-pr-driver: one per LAYER boundary (each layer's green gate closes) + the end-of-run packet |
 | Composed | `orc-diy` | one packet per ENABLED phase group, **minimum 2** — the flow shape is user-composed, so the count is too (the compiled flow carries this block automatically) |
 | Iterative | `orc-quick`, `orc-challenge` (lane `challenge`), `orc-doc` (lane `doc`) | **one packet per completed numbered entry** + the end-of-run `FINISH` packet — the lane loops on user requests, so the count follows entries, not phases. For `orc-challenge` the unit is one completed ITERATION (C2→C8), and the packet goes out at the stop; on a PASS it is the `FINISH` packet. **Several trace files for one cycle is CORRECT** — several sessions ran, and `orc stats` counts several. For `orc-doc` the unit is one completed WAVE, and the packet is the LAST step of the stop sequence |
-| Single-dispatch | `orc-claude`, `orc-plan`, `orc-analyze` (+ mini), `orc-pattern`, `orc-verify`, `orc-learn`, `orc-poly`, `orc-pr-setup` (lane `prsetup`), `orc-grill`, `orc-route`, `orc-brainstorm` (lane `brainstorm`), `orc-pact` (lane `pact`), `orc-boundary` (lane `boundary`), `orc-handoff` (lane `handoff`), `orc-budget` (lane `budget`), `orc-aftermath` (lane `aftermath`), `orc-export` (lane `export`) | **exactly ONE mandatory end-of-run packet** |
+| Single-dispatch | `orc-claude`, `orc-plan`, `orc-analyze` + `orc-analyze-mini` (both lane token `analyze`), `orc-pattern`, `orc-verify`, `orc-learn`, `orc-poly`, `orc-pr-setup` (lane `prsetup`), `orc-grill`, `orc-route`, `orc-brainstorm` (lane `brainstorm`), `orc-pact` (lane `pact`), `orc-boundary` (lane `boundary`), `orc-handoff` (lane `handoff`), `orc-budget` (lane `budget`), `orc-aftermath` (lane `aftermath`), `orc-export` (lane `export`) | **exactly ONE mandatory end-of-run packet** |
 
 **`context-combiner` is NOT a lane — it is a PHASE inside the analyze run.** It
 has no slash command and no entry point of its own: `orc-analyze` Phase F
@@ -218,9 +228,9 @@ supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
 |------|-----------|---------|
 | `PHASE <name> start\|end` | orc → writer | phase transition |
 | `PHASE-EDGE <role-family> :: first=<agent>` | hook | **deterministic phase inference.** ORC agent names encode their role, so when a SPAWN's role family differs from the previous SPAWN's, the hook segments the run itself — families: `analyst\|scout → analysis`, `planner → planning`, `executor → execution`, `reviewer → review`, `verifier → verify`, `test-author → testgen`, `advisor\|judge → ultra-gate` (the trace writer never opens an edge). Zero model dependence: even a run where every writer dispatch was forgotten still reads planning → execution → review → verify, and `/orc-retro` computes NARRATION COVERAGE from edges with vs without a writer `SPAWN` between them |
-| `CONFIG <key=value …>` | orc → writer | Phase 1 — the resolved config values this run will consume (incl. `fable5_*` when enabled, and ALWAYS `opus5_only` — it selects the executor table AND every fixed role, so retro can segment outcomes by dispatch mode). Runtime proof that the run honored the config; `/orc-retro` audits it against behavior |
+| `CONFIG <key=value …>` | orc → writer | Phase 1 — the resolved config values this run will consume (ALWAYS `opus5_only` — it selects the executor table AND every fixed role, so retro can segment outcomes by dispatch mode). Runtime proof that the run honored the config; `/orc-retro` audits it against behavior |
 | `WIKI-CONSULT <tier> :: docs=<list>` | orc → writer | project wiki consulted for grounding (full/mini at planning; fast at slice-build) — tier ∈ `fresh` \| `aging` \| `stale` \| `absent` \| `empty`; `docs=` the pages pulled/handed to the executor (comma list) or `none`. Records whether the run grounded in the wiki and whether it was stale (surfaces grounding + staleness for later audit) |
-| `CROSSLINK <state> :: boundaries=<n> peers=<names>` | orc → writer | cross-repo peer-knowledge state at the consult point — state ∈ `cached` (peer cache present) \| `configured-no-cache` (crosslink configured but the cache is not built) \| `none`. Per-task `CROSSLINK inject task=<id> :: <boundary>` when a slice receives a linked contract. Records whether peer contracts were injected this run (full orc consumes only the pre-built crosslink cache — it never reads peer source live; mechanism in `references/wiki-consult.md`) |
+| `CROSSLINK <state> :: boundaries=<n> peers=<names>` | orc → writer | cross-repo peer-knowledge state at the consult point — state ∈ `cached` (peer cache present) \| `configured-no-cache` (crosslink configured but the cache is not built) \| `none`. Per-task `CROSSLINK inject task=<id> :: <boundary>` when a slice receives a linked contract. Records whether peer contracts were injected this run (full orc consumes only the pre-built crosslink cache — it never reads peer source live; mechanism in `wiki-consult.md`) |
 | `SPAWN <agent>` | hook | an agent dispatch was observed (skeleton) |
 | `RETURN <agent> :: <desc> dur=<m>m<s>s [model=<id>]` | hook | a subagent finished (skeleton). The hook attributes the RETURN to the finishing agent from the SubagentStop payload (`~<agent>` = approximate FIFO match on older Claude Code that omits `agent_type`; `~agent :: unattributed` = ≥2 agents in flight, so it deliberately claimed NO pending record rather than starve the right one), echoes the SPAWN's desc + wall-clock duration, and appends `model=<id>` when the return's `actual_model` is visible in the last message. A duplicate stop for an agent whose record was already consumed is DROPPED, never written as a desc-less RETURN. Still hook-written skeleton — NOT an orchestrator obligation; the authoritative model check is the `VERIFY` line |
 | `DISPATCH <agent> :: <task> expect=<model>/<effort>` | orc → writer | orchestrator dispatched a named agent (the claim). **A FOREIGN dispatch appends `via=extra:<profile>`** and its `expect=` names the profile's model rather than a Claude tier — additive, the way `/orc-doc`'s `sections=` was. A foreign worker is not a Claude subagent, so the hook emits NO `SPAWN` and NO `RETURN` for it (P7, the `/orc-quick` ad-hoc-recon precedent): this line and `EXTRA` are the whole record, which is why neither is optional. **The `/orc-doc` lane's tail NAMES ITS SECTIONS** (v0.49.2) — `doc write sections=03-scope,04-risks part=sections/03-scope.md`, `doc check sections=03-goals`, `doc digest source=<path>` — which is the only thing that makes `orc doc cost`'s per-section attribution honest rather than a guess. It is additive: the tail was already captured whole |
@@ -243,7 +253,7 @@ supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
 | `PACT <state> :: <ids>` | orc → writer | invariant-ledger state at the Phase-1 probe (`pact_gate`), and `PACT inject task=<id> :: <PACT-id>` when a DRIFTED/BROKEN promise is appended to a task's `constraints[]`. `PACT recheck pass\|fail :: <ids>` at Phase 6. Records whether last month's decisions constrained this month's plan |
 | `BOUNDARY <verdict> task=<id> :: <area>` | orc → writer | per-task boundary verdict (verdict ∈ `EXECUTE` \| `ESCALATE` \| `REFUSE` \| `unknown` — an uncarded area is UNKNOWN, never REFUSE), plus `BOUNDARY lift task=<id> :: <area>` when `boundary_gate: block` removes ONE task from a wave (the wave still runs). `/orc-retro` reads these to answer the question the lane exists for: how much work did we stop attempting, and was that right |
 | `CHALLENGE iter=<n> findings=P0:<n>/P1:<n>/P2:<n> coverage=<n>% verdict=PASS\|FAIL` | orc → writer | one line per completed `/orc-challenge` iteration boundary. **Copy `orc challenge record`'s `trace_line` verbatim** — the CLI assembles it so the lane never composes a second wording for the same number. Plus `CHALLENGE accept :: <id>` and `CHALLENGE rebut :: <id>` when an escape valve is used, and `CHALLENGE regoal\|retemplate :: v<n>` on a re-freeze. `/orc-retro` reads the sequence to answer whether a cycle converged or stalled |
-| `EXTRA <profile>/<model> engine=<api\|claude-shim\|cli> task=<id> band=[lo,hi) tok=in/cw/cr/out outcome=<done\|partial\|failed\|fallback> dur=<m>m<s>s` | orc → writer | one line per FOREIGN dispatch — a slice that executed on a non-Claude worker (`_shared/extra-dispatch.md`). **Copy `orc extra dispatch`'s `trace_line` verbatim** — the CLI assembles it, exactly as `orc challenge record` does, so the lane never composes a second wording for the same numbers. Plus `EXTRA fallback task=<id> :: <reason> → <agent>` when a failed foreign dispatch re-dispatches to Claude (P6), `EXTRA substitution task=<id> :: requested=<m> reported=<m>` / `EXTRA reroute task=<id> :: <providers>` when the endpoint answered with a different model, or the same model served by a different company, and — v0.54.0 — `EXTRA resume task=<id> attempt=<n> :: from=<reason> attribution=<verdict> target=<extra:profile\|agent> files_preexisting=<n>` when a dispatch CONTINUES a position an earlier attempt left on disk, plus `EXTRA orphan task=<id> :: attempt=<n> lease-expired files_changed=<n> state=<state>` when preflight reports a dispatch that never reported back. **A resume that leaves no line cannot be counted** — neither `orc extra stats` nor `/orc-retro` can then learn whether resuming works, or which providers ignore the resume preamble. `EXTRA resume` rides in the resumed dispatch's own `trace_extras[]`; `EXTRA orphan` is the LANE's to emit after it reports, the same ownership rule as `EXTRA fallback`. **`tok=none` is a real value** and the ONLY correct one when the worker reported no counts (engine `cli` often does not): `tok=0/0/0/0` would tell `/orc-budget` the run was free, while a measured zero — engine `api`'s `cw`, always — is a different fact. **On a lane with no score `band=` carries `slot:<slot>`** (v0.55.0 — `slot:doc-writer`, `slot:wiki-scanner-light`): the field NAME is unchanged, so this parser, the eight-field dedupe and the ` :: ` tolerance are untouched, and `orc extra stats` gives each POSITION its own row for free. This is the verb `/orc-retro` reads to answer the only question that matters: is the cheap model actually cheaper once you count the repairs |
+| `EXTRA <profile>/<model> engine=<api\|claude-shim\|cli> task=<id> band=[lo,hi) tok=in/cw/cr/out outcome=<done\|partial\|failed\|fallback> dur=<m>m<s>s` | orc → writer | one line per FOREIGN dispatch — a slice that executed on a non-Claude worker (`_shared/extra-dispatch.md`). **Copy `orc extra dispatch`'s `trace_line` verbatim** — the CLI assembles it, exactly as `orc challenge record` does, so the lane never composes a second wording for the same numbers. Plus `EXTRA fallback task=<id> :: <reason> → <agent>` when a failed foreign dispatch re-dispatches to Claude (P6), `EXTRA substitution task=<id> :: requested=<m> reported=<m>` / `EXTRA reroute task=<id> :: <providers>` when the endpoint answered with a different model, or the same model served by a different company, and — v0.54.0 — `EXTRA resume task=<id> attempt=<n> :: from=<reason> attribution=<verdict> target=<extra:profile\|agent> files_preexisting=<n>` when a dispatch CONTINUES a position an earlier attempt left on disk, plus `EXTRA orphan task=<id> :: attempt=<n> lease-expired files_changed=<n> state=<state>` when preflight reports a dispatch that never reported back, and — v1.0.0 — `EXTRA demote run=<slug> :: profile=<p> reason=<consecutive-stall\|stale-live-attempt\|manual> n=<k> → <ladder>` when this run DROPS a foreign profile to the bottom of the ladder after two consecutive stalls, a stale live attempt, or `orc extra demote`. **A demotion that leaves no line cannot be counted** either — copy `orc extra demotion`’s `trace_line` VERBATIM and emit it before the next dispatch, beside the mandatory announce line. A demotion is RUN state: it never writes the config and it is never promoted back on its own. **A resume that leaves no line cannot be counted** — neither `orc extra stats` nor `/orc-retro` can then learn whether resuming works, or which providers ignore the resume preamble. `EXTRA resume` rides in the resumed dispatch's own `trace_extras[]`; `EXTRA orphan` is the LANE's to emit after it reports, the same ownership rule as `EXTRA fallback`. **`tok=none` is a real value** and the ONLY correct one when the worker reported no counts (engine `cli` often does not): `tok=0/0/0/0` would tell `/orc-budget` the run was free, while a measured zero — engine `api`'s `cw`, always — is a different fact. **On a lane with no score `band=` carries `slot:<slot>`** (v0.55.0 — `slot:doc-writer`, `slot:wiki-scanner-light`): the field NAME is unchanged, so this parser, the eight-field dedupe and the ` :: ` tolerance are untouched, and `orc extra stats` gives each POSITION its own row for free. This is the verb `/orc-retro` reads to answer the only question that matters: is the cheap model actually cheaper once you count the repairs |
 | `FINISH :: <detail>` | orc → writer | run ended |
 
 `SPAWN`/`RETURN`/`PHASE-EDGE` come from the hook automatically. Every other verb
@@ -294,7 +304,7 @@ For each spawn the orchestrator:
 ## Announce-on-spawn
 
 When dispatching, announce the model to the user, derived from the agent NAME
-(e.g. "Spawning orc-executor-opus-4-7-high → claude-opus-4-7 / high"). Derive it
+(e.g. "Spawning orc-executor-opus-5-low → claude-opus-5 / low"). Derive it
 from the name — do NOT pass the coarse `sonnet|opus|haiku` dispatch arg, which
 cannot express 4-7 vs 4-8 and would override the frontmatter pin.
 
@@ -312,3 +322,36 @@ orc's plus the U0/judge ones.
 - Append-only; one whole block per append (never edit prior lines).
 - The trace records behavior faithfully — including the ugly bits (over-asking,
   downgrades, failed waves). That honesty is the whole value.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Behavior trace (PERMANENT — always on, no flow key)
+
+Tracing is NOT composable: every ORC run traces, this one included. Follow
+`.claude/skills/_shared/phases/trace.md` (load it at run start) — this
+block is stitched into every compiled flow so a user-composed pipeline can never
+be the one lane that runs blind.
+
+**Run start:** create `log_dir`, write `log_dir/.current` =
+`run-diy-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step (a pointer naming a file that does not exist reads as dangling —
+the hook rotates away from it and the run splits across two files), then store
+`trace_path` in the checkpoint. The lane token is `diy`, whatever the flow is
+named.
+
+**Narration is dispatched, never remembered:** record each event with its REAL
+timestamp into a phase packet (`PHASE`, `DISPATCH`/`VERIFY` per spawn —
+`actual_model`/`actual_effort` vs expected, surface any ⛔ DOWNGRADE to the user
+— `SCORE`, `OUTCOME`, `GATE`, `FINDING`/`VERDICT` for whichever gates this flow
+enabled, `FINISH`, plus `decisions` = the WHY), then dispatch
+`orc-trace-writer-haiku-4-5` with it, PAIRED with the next phase's first
+dispatch. **One packet per ENABLED phase group, minimum 2** — the flow shape is
+composed, so the packet count is too; a phase this flow turned OFF owes nothing.
+A phase ending with `zero new trace lines is a protocol violation`.
+
+**Run end:** the `FINISH` packet goes out and RETURNS, then delete
+`log_dir/.current`.
+
+<!-- /orc:layer -->

package/templates/skills/_shared/phases/verify.md

@@ -0,0 +1,70 @@
+# Phase — Verify — TDD gate + adversarial review   (id: `verify`)
+
+> **Shared phase file.** Moved out of `orc/SKILL.md` at v1.0.0 W12, and into
+> this library at W13 when `orc-diy` became its second reader. A spine is loaded
+> IN FULL when its skill activates; this is loaded when the phase fires, and most
+> runs skip most phases.
+>
+> **Two layers, and a lane reads exactly one.** `full` is `/orc`'s procedure.
+> `composed` is what `orc diy compile` stitches — the same phase expressed as
+> `<!-- diy:when -->` variants over a composed flow, NOT a second copy of the
+> procedure. Reading the wrong one is the failure `README.md` names: a lane
+> doing a phase its product promise says it does differently.
+> `orc lane phases <lane> --json` names the layer for each lane.
+
+<!-- orc:layer full -->
+
+## Verify: TDD gate + adversarial review (same subskill, phase=verify)
+
+Emit `PHASE verify start`. TWO halves in the SAME dispatched verifier slot
+(../../orc/subskills/orc-review-verify/ — Phase 5's reviewer stays separate):
+**1) TDD gate (deterministic):** run the plan's TDD suite — green IS the
+definition-of-done for non-exempt requirements; red → repair loop (implement→
+test→repair, cap `tdd_loop_max`; cap hit → STOP SEQUENCE + honest red report).
+**2) Adversarial review:** attack the green implementation — edge cases the
+spec missed, error paths, contract violations, race/ordering, workflow breaks
+(dead wiring, broken commands) — findings on the existing P0–P3 ladder. The
+verifier also checks the intent-spec's
+definition-of-done PLUS the pattern's `validation_gate[]` lines (each a
+criterion; unmet = P0). The return carries `criteria[]` {criterion, pass|fail,
+evidence} — every criterion needs evidence. Quote spot-check P0/P1 first, then:
+P0 → auto-fix once → re-verify once → second failure STOPS; P1 → ask before the
+one fix attempt, then re-verify (same single-retry cap).
+**Pact recheck (`pact_recheck_on_verify`, default true; emit `PACT recheck`):**
+after GREEN, run `orc pact check` scoped to the promises whose anchors intersect
+this run's CHANGED files. A promise that flips to BROKEN is a **P1 finding with its
+check output** — reported, never an automatic abort: the ledger may simply have
+outgrown the code, and that is the user's call. Emit
+`VERDICT pass|fail :: <detail>`, then `PHASE verify end`.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Verify
+
+<!-- diy:when verify=off -->
+Verification is DISABLED in this flow. The build+test evidence in each
+executor return is the only green signal; say "verify skipped by flow
+config" in the summary. Never claim criteria were verified.
+<!-- /diy:when -->
+<!-- diy:when verify=smoke -->
+Run a SMOKE verify only: dispatch the verifier
+(`orc-verifier-opus-5-med`) with an explicitly narrowed scope — build +
+full test suite, red/green verdict, NO per-criterion definition-of-done
+sweep. Red blocks ship exactly as a full verify would.
+<!-- /diy:when -->
+<!-- diy:when verify=full -->
+Dispatch verification exactly as the full lane does — follow the verify half
+of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` (build + tests +
+every acceptance criterion checked against the definition of done).
+<!-- /diy:when -->
+<!-- diy:when tdd=on -->
+TDD gate (rides the verify slot): the verifier slice carries the plan's
+`tdd_suite[]`; green is the definition-of-done for non-exempt requirements,
+red → the repair loop capped at `tdd_loop_max` (cap hit → STOP + honest red
+report). The adversarial half of the verify pass applies as the full lane
+defines it.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

package/templates/skills/{orc/references → _shared/phases}/wave-grouping.md

@@ -1,4 +1,14 @@
-# Reference — Wave Grouping & Conflict Graph
+# 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.
 
@@ -41,7 +51,7 @@ negotiated at runtime.
    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-and-resume.md), not
+   in the checkpoint. A pause so marked is a HARD gate (stop-resume.md), not
    an orchestrator judgment call.
 
 ## Same-feature collision
@@ -119,3 +129,5 @@ after every task returns, then diff the two:
   `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/{orc/references → _shared/phases}/wiki-consult.md

@@ -1,4 +1,14 @@
-# Reference — Wiki Consult (shared by orc / orc-mini / orc-fast)
+# 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.
+
+<!-- orc:layer core -->
+## Reference — Wiki Consult (shared by orc / orc-mini / orc-fast)
 
 The ONE canonical description of how a lane grounds itself in the project wiki.
 Load at the consult point (full/mini: Phase 1 planning; fast: F0 gate + F2
@@ -175,3 +185,5 @@ After a run that changed code, flag (do NOT re-scan) any wiki docs whose
 covered files this run changed and point the user at `/orc-wiki`. Mini/fast
 keep this passive note only; the full/ultra post-ship refresh ASK is defined in
 `../../orc-wiki/references/staleness.md`.
+
+<!-- /orc:layer -->

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

@@ -47,8 +47,56 @@ 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 —
 that is `detecting-artifacts.md` — and it never overrides precedence:
 `code > fresh wiki > stale wiki (hints) > 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.

package/templates/skills/_shared/wait.md

@@ -0,0 +1,240 @@
+# Shared contract — the WAIT (`/orc-wait`, and the computed gate)
+
+Canonical file: `_shared/wait.md`. THE canonical mechanic for a lane that must
+**stop where it stands, wait for wall-clock time to pass, and carry on from the
+same place**. Load it wherever a lane can be interrupted by a wait — which,
+since v1.1.0, is every lane in the table below.
+
+## Why a wait is not a suspend and not a fallback
+
+ORC already has two shapes for leaving a run. This is a third, and conflating
+them loses work.
+
+| | `FALLBACK-FROM` | `RETURN-TO` | **WAIT** |
+|---|---|---|---|
+| Why it leaves | it cannot proceed | another lane must settle something | **wall-clock time must pass** |
+| Who finishes | the receiver | the sender, after coming back | **the same lane, same run** |
+| Another lane runs | yes | yes | **no — nothing runs** |
+| Traces | one | two | **one** |
+
+A wait dispatches nothing and decides nothing. It is the only ORC mechanic
+whose entire purpose is that **no model is running**.
+
+## The one rule
+
+> **`a lane that waits without a hand-back` has broken this contract.**
+
+A wait is a stop. Every stop in ORC writes its hand-back before it ends, because
+the thing that resumes the run may not be this session — the user can close the
+terminal, the machine can sleep, and the wake-up message is a Claude Code
+behaviour ORC cannot promise. `RESUME.md` on disk is what makes a lost wake-up
+cost nothing.
+
+This is `_shared/phases/stop-resume.md` applied to a stop nobody asked a
+question about. It does not replace that phase; it scales it.
+
+## The three modes
+
+A wait is requested with a mode. The modes differ in ONE thing: how much the
+lane finishes before it stops.
+
+| Mode | Stops at | Hand-back | Dispatches | Can lose |
+|---|---|---|---|---|
+| `safe` | the next **safe point** | full stop sequence | yes (checkpoint) | nothing |
+| `soft` | the next **model turn** | full stop sequence, **forced** | yes (checkpoint) | an in-flight return |
+| `hard` | the next **model turn** | `RESUME.md` only, best effort | **no** | an in-flight return, the checkpoint, the phase's trace packet |
+
+**`soft` is forced.** On a lane the table below marks as checkpointing, `soft`
+does not merely attempt the hand-back: if the checkpoint write fails, **`soft`
+does not stop**. It reports the failure and stays in the run. That is
+`stop-resume.md` step 2 unchanged — *stopping without a good checkpoint is the
+one thing that loses work* — and it is the whole reason the mode exists.
+
+**`hard` is the dispatch-free stop.** It writes only what ORC can write with its
+own hand (`RESUME.md`, per stop-resume step 3b — never a dispatched agent). It
+is fast BECAUSE it dispatches nothing, not in spite of it. It is the one mode
+that can lose work, and it says so every time it runs.
+
+### "the next model turn" is the honest promise
+
+A typed message reaches ORC at a turn boundary. `hard` therefore **cannot**
+interrupt a dispatch that is already in flight. What it promises is:
+
+> stop at the first moment ORC can act, and do not wait for the current wave,
+> phase or gate to finish.
+
+Never write "immediately". A user who reads "immediately" and sees a wave finish
+believes the command failed.
+
+## Safe points
+
+A safe point is a place where the run can stop with no loss. `safe` waits for
+one. `soft` and `hard` do not — that is what they are for, and what they risk.
+
+**Never begin a wait at any of these, in any mode:**
+
+- between a dispatch and its validated return
+- inside the stop sequence itself
+- during a file write, a `splice`, or a wiki registration write
+- before the smoke gate has reported
+
+These are not a style preference. Each one leaves an artifact that no resume can
+reconstruct.
+
+## Which lanes support a wait
+
+The machine-readable copy of this table is `WAIT_LANE_SHAPES` in `bin/cli.js`,
+rendered by `orc wait lanes`. A golden test compares the two IN BOTH DIRECTIONS
+— the `EXTRA_LANE_SHAPES` / `DIY_STEPS` precedent. A lane added to one and not
+the other fails the suite.
+
+| Lane | Checkpoint | Safe point |
+|---|---|---|
+| `/orc` | full | wave or phase edge |
+| `/orc-ultra` | full | wave or judge gate |
+| `/orc-mini` | full | after the executor returns |
+| `/orc-fast` | full | after the executor returns |
+| `/orc-diy` | full | compiled phase edge |
+| `/orc-doc` | full | wave edge |
+| `/orc-wiki` | full | scan-task boundary |
+| `/orc-analyze` | full | after the analyst returns |
+| `/orc-poly` | docset | after a per-repo plan is written |
+| `/orc-quick` | entry | after an entry closes |
+| `/orc-challenge` | cycle | after a cycle records |
+| `/orc-brainstorm` | snapshot | phase edge |
+| `/orc-grill` | snapshot | round edge |
+| `/orc-learn` | none | single dispatch |
+| `/orc-plan` | none | single dispatch |
+| `/orc-verify` | none | single dispatch |
+| `/orc-pattern` | none | single dispatch |
+| `/orc-claude` | none | single dispatch |
+| `/orc-explain` | none | read-only, seconds long |
+| `/orc-route` | none | read-only, seconds long |
+| `/orc-boundary` | none | read-only, seconds long |
+| `/orc-budget` | none | read-only, seconds long |
+| `/orc-aftermath` | none | read-only, seconds long |
+| `/orc-export` | none | read-only, seconds long |
+| `/orc-retro` | none | read-only, seconds long |
+| `/orc-pact` | none | read-only, seconds long |
+
+**`checkpoint: none` is an ANSWER, not a gap.** A single-dispatch lane has
+nothing to checkpoint, so a wait there is a plain wait and the message says so.
+On such a lane `safe`, `soft` and `hard` are the SAME thing, and
+`orc wait lanes` states that rather than pretending to a distinction. A row that
+reads `none` must never render like a row that is missing.
+
+## The hop loop
+
+The lane does not sleep. A **detached** command sleeps. It costs zero tokens and
+no model runs during it.
+
+```
+1. Write the hand-back for the mode (above).
+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.
+```
+
+**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
+sleep was long.
+
+## After the wait — ORC does not drag a large context forward
+
+`stop-resume.md` step 6 already requires offering both continue paths. This
+decides which one ORC takes without asking:
+
+- **context small** → continue here, and say so in one line.
+- **context large** → STOP and offer both paths, recommending the fresh session.
+
+A wait longer than one hour has already expired the prompt cache, so continuing
+in-session re-reads the whole context at full input price — exactly when quota
+is lowest. Auto-continuing into a bloated context is the cost the wait existed
+to avoid.
+
+**ORC cannot clear its own context.** `/clear` is the user's action. The wait
+offers the swap; it never performs it.
+
+## The computed gate (`usage_gate`)
+
+The same engine, triggered by the CLI instead of by a typed command. It is
+**`off` by default** — nothing below happens until the user turns it on.
+
+Check **before a wave, never during one**: `orc usage check --json`.
+
+| exit | state | `warn` | `stop` | `wait` |
+|---|---|---|---|---|
+| 0 | ok | continue | continue | continue |
+| 1 | low | print and continue | hand back and stop | hand back, hop, come back |
+| 2 | unknown | print and continue | print and continue | print and continue |
+
+**Exit 2 never stops a run**, in any mode. An absent reading is absent, not low:
+older Claude Code sends no usage headers, and a long dispatch leaves the reading
+stale by exactly its own length. A gate that blocks on a missing number is a
+gate people switch off.
+
+**The worst window decides.** `orc usage check` already resolves that; never
+re-derive it from one window.
+
+A computed stop offers the cheaper answers before the expensive one — a lower
+band for this wave, or `orc extra` if a profile is ready — because a wait is the
+only one of them that costs wall-clock time.
+
+**A typed `/orc-wait` is never suppressed by any of this**, and a computed wait
+is suppressed entirely while a block is active.
+
+## The block — the user's veto
+
+`/orc-wait block <reason>` suppresses every COMPUTED wait for the rest of the
+run. It is for the case where stopping costs more than continuing: the window
+resets in five minutes and the task needs ten.
+
+1. **The reason is REQUIRED.** A block with no reason is refused by name. The
+   recorded reason is what makes the risk demonstrably the user's — the same
+   `--reason` rule the run-close and doc-ship writers already use.
+2. **Run-scoped. It NEVER writes the user's config.** The same rule the ultra
+   lane's forced run-scoped mode already follows. A veto set today must not
+   apply to a run started next month.
+3. **It is ANNOUNCED at every gate it suppresses, with its age.** A shadowed
+   setting must never be silent. There is no auto-expiry — ORC does not decide
+   that a user's reason stopped being true — so the age is what keeps an old
+   block from applying invisibly.
+4. **It blocks what ORC COMPUTES, never what the user TYPES.** A typed
+   `/orc-wait 30 hard` still waits while a block is active. `/orc-boundary`'s
+   rule, unchanged: a gate constrains ORC's own dispatch, never an explicit
+   instruction.
+5. It survives a resume, and is re-announced on the first gate after it.
+
+`orc wait cancel` is a DIFFERENT command: it ends a wait that is already
+running. Block is before, cancel is during. Never conflate them in prose or in a
+menu.
+
+## What a wait never does
+
+- It never dispatches an agent to do the waiting. An agent runs on the same
+  account and consumes the same window the wait exists to protect.
+- It never runs another lane.
+- It never writes the user's config.
+- It never widens or narrows the work: the same tasks, the same slice, the same
+  agent resolve after the wait as before it.
+- It never decides on its own that a user's block has expired.
+
+## Trace
+
+The wait writes CLI-composed lines into the trace that is ALREADY open, and
+nothing when no run is active. `/orc-wait` opens no run, so it is **not a lane**
+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   unblock
+```
+
+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.