@azure-id/orc 0.56.0 → 1.0.0

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

@@ -0,0 +1,48 @@
+# Phase — Summary   (id: `summary`)
+
+> **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 -->
+
+## Summary
+
+Emit `PHASE summary start`. Report: tasks/waves/dispatches (scores + overrides), escalations,
+needs_context events, findings by severity (P0/P1 resolved; P2 itemized; P3
+counted), verify result, authored tests when 6.5 ran, repo state + branch,
+stale_review flags. Then ONE question: **"Apply the P2 fix-batch? The P3
+cosmetics too?"** — never fix unasked. Emit `PHASE summary end`.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Summary
+
+<!-- diy:when summary=off -->
+No summary phase: end after ship with a single line (tasks done / gate color
+/ ship action taken) plus usage, and note which phases this flow skipped.
+<!-- /diy:when -->
+<!-- diy:when summary=short -->
+Short summary: one paragraph — what was built, gate results, ship action,
+skipped phases, and usage. No per-task breakdown.
+<!-- /diy:when -->
+<!-- diy:when summary=full -->
+Full summary exactly as the full lane's final phase: per-task outcomes with
+models used, findings outcomes, verify results, ship action, skipped
+phases, and usage.
+<!-- /diy:when -->
+
+Always name the phases this flow skipped by config — the user must never
+mistake a DIY run for a full-lane run.
+
+<!-- /orc:layer -->

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

@@ -0,0 +1,51 @@
+# Phase — Test authoring (opt-in)   (id: `testgen`)
+
+> **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 -->
+
+## Test Authoring (opt-in; load ../../orc/subskills/orc-testgen/)
+
+Only when `config.generate_tests` is on (confirmed at intake). ORC **writes**
+test cases and **runs nothing** — never gates the ship. Dispatch
+`orc-test-author-opus-5-med` (run's `actual_files`, definition-of-done,
+touched flows, constraints, stack); it returns test files + a `TEST-PLAN.md` + a
+Postman-importable `test-cases.http` (HTTP APIs), the two manual deliverables
+written to **`test-generator/<change-slug>/` at the project root**. Validate the
+returned `test_plan_path`/`curl_bundle_path` are under that folder (else
+malformed → re-dispatch); state the exact path in the summary — discoverability
+is the point.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Test authoring
+
+<!-- diy:when testgen=off -->
+Test authoring is OFF in this flow — skip silently.
+<!-- /diy:when -->
+<!-- diy:when testgen=ask -->
+After verify (or after execution when verify is off), offer test authoring
+once; on yes, run the full lane's Phase 6.5 via
+`.claude/skills/orc/subskills/orc-testgen/SKILL.md` — it WRITES test cases
+and a test plan, never runs them, and never gates the ship.
+<!-- /diy:when -->
+<!-- diy:when testgen=on -->
+After verify (or after execution when verify is off), run the full lane's
+Phase 6.5 without asking via
+`.claude/skills/orc/subskills/orc-testgen/SKILL.md` — it WRITES test cases
+and a test plan, never runs them, and never gates the ship.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

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.