@azure-id/orc 0.56.0 → 1.0.0

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

@@ -0,0 +1,82 @@
+# `_shared/phases/` — one copy of a phase, and a manifest per lane
+
+This directory is NOT a skill and NOT a lane. It holds the single canonical copy
+of a phase that **two or more lanes run**. A lane's spine keeps its identity, its
+trigger, its own hard rules and its own phases — and for a shared phase it keeps
+only a POINTER plus that lane's own deltas.
+
+**The CLI owns the pipeline, not the prose.** `orc lane phases <lane> [--json]`
+is the manifest: the ordered phase list, the file each phase lives in, the layers
+that lane reads, the catalogued calls it makes, and when to read it. A skill
+never derives the phase list or its order from these filenames — the same rule
+the Flow stepper follows, for the same reason: *a second idea of the pipeline is
+the drift this exists to make impossible.*
+
+## What belongs here — the rule is mechanical
+
+> A file under `templates/skills/<lane>/` that a file in a DIFFERENT lane already
+> points at belongs here. **A file with exactly one consumer stays home.**
+
+That is auditable by grep, which is what makes it a lint rather than an opinion.
+`bin/verify-contracts.js` asserts both halves: nothing under a lane folder may be
+pointed at from another lane, and every file here must be claimed by **≥2 lanes**.
+
+Centralizing a one-consumer file is centralizing for its own sake, and it costs a
+lane its own wording for nothing.
+
+## The layer set is CLOSED
+
+A phase file may be cut into layers with the same marker grammar `orc diy
+compile` already parses (`<!-- diy:when key=value -->`):
+
+```markdown
+<!-- orc:layer core -->
+Every lane that runs this phase does this. Never optional.
+<!-- /orc:layer -->
+
+<!-- orc:layer trim -->
+orc-mini / orc-fast: ONE executor, no waves. This is a REDUCTION and it is
+deliberate — do not read the `full` layer here.
+<!-- /orc:layer -->
+```
+
+| Layer | Read by | Meaning |
+|---|---|---|
+| `core` | every lane running this phase | the invariant. Never optional |
+| `full` | `/orc`, `/orc-ultra` | the complete procedure |
+| `trim` | `orc-mini`, `orc-fast` | an explicit REDUCTION, stated as one |
+| `composed` | `orc-diy` | what `orc diy compile` stitches |
+
+**Four names, closed. A fifth layer is a lint failure, not a feature** — free
+markers are drift with extra steps. A lane reads `core` plus at most one other
+layer, and `orc lane phases` tells it which.
+
+**Why the set exists at all:** the single biggest way this library breaks ORC is
+`orc-mini` reading a shared `review.md` written for the full lane and starting to
+do a full code review. Mini's product promise is that it *skips* review.
+Centralizing without layers does not just cost tokens — it changes behaviour. So
+**a `trim` layer must say what it drops and that dropping it is deliberate.**
+
+**A single-layer file is a legitimate answer.** `trace.md` and `stop-resume.md`
+declare `core` only: their procedure really is identical in every lane that runs
+them, and what varies is DATA (the tier table, the lane token), not prose. Cutting
+them into layers to look symmetrical would be inventing structure the phase does
+not have.
+
+## Pointer discipline
+
+Every pointer a spine adds declares `when` and `read` — the partial-read rules in
+`../read-ladder.md`. `on-phase` is the default; `always` must be justified in the
+release's findings; a `read:` names a HEADING and **never a line number**
+(`/orc-doc` rule 2 — a stored line number is a wrong line number one edit later).
+
+## What is here
+
+| File | id | Layers | Lanes |
+|---|---|---|---|
+| `trace.md` | `trace` | `core` | every trace-owning lane (28) |
+| `preflight.md` | `preflight` | `core`, `full` | the silent-probe lanes (15) |
+| `stop-resume.md` | `stop-resume` | `core` | `orc`, `orc-wiki`, `orc-diy` |
+
+`orc lane phases --all --json` is the authoritative list; this table is a
+human index of it.

package/templates/skills/{orc/references → _shared/phases}/analyst-gates.md

@@ -1,9 +1,19 @@
-# Reference — Analyst, Combiner & Plan Gates (orchestrator side)
+# Phase — Analyst & plan gates   (id: `analyst-gates`)
+
+> **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-analyze`, `orc-mini`. Layers declared: `core` only — single-
+> layer because these are the orchestrator-side gates on a returned analysis
+> or plan, and a trimmed lane runs fewer of them rather than different ones.
+> `orc lane phases <lane> --json` names the file and the layers to read.
+
+<!-- orc:layer core -->
+## Reference — Analyst, Combiner & Plan Gates (orchestrator side)
 
 The orchestrator's deterministic gates around the analyst, the
 context-combiner, and the planner. The roles themselves are defined in
 `../../orc-analyze/SKILL.md`, `../../context-combiner/SKILL.md`, and
-`../subskills/orc-planner/SKILL.md` — this file is what YOU do around their
+`../../orc/subskills/orc-planner/SKILL.md` — this file is what YOU do around their
 dispatches and returns. Load at Phase 0 (analyst dispatch) and Phase 1
 (planner return). Emit a `GATE` trace line (pass|bounce) per check when
 logging.
@@ -113,7 +123,7 @@ proceed-with-flagged.
    - `new-surface` / `behavior-change` missing `skeleton` or `given_when_then`
      → miss.
    - A disposition that DEVIATES from the derivation table in
-     `../schemas/planning-output.md` without a `reason` → miss. The derivation
+     `../../orc/schemas/planning-output.md` without a `reason` → miss. The derivation
      is the default; departing from it is the thing that needs justifying.
 
 Any miss → the plan is malformed: bounce it back to the planner WITH the miss
@@ -122,3 +132,5 @@ pre-v0.7.0 plan resumed from an old checkpoint has no `grounding[]`
 (pre-v0.9.0: no `requirements[]`/`spec_invariants[]`; pre-v0.41.0: no
 `disposition`) — resume it without the
 missing checks; never bounce an old plan.
+
+<!-- /orc:layer -->

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

@@ -0,0 +1,143 @@
+# Phase — Execution   (id: `execution`)
+
+> **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 -->
+
+## Execution (load wave-grouping.md + log-protocol.md)
+
+Emit `PHASE execution start`. Build the conflict graph from `declared_files` →
+group waves (cap `max_wave_tasks`, mark `is_batch_pause` from `pause_schedule`;
+waves are computed for BOTH dispatch styles — sequential fires a wave's tasks
+one at a time, parallel fires them together) → SHOW the wave plan (wave → tasks →
+pause marks) to the user BEFORE wave 1 → write checkpoint + state-of-play BEFORE
+dispatching. **Boundary gate, per wave (`boundary_gate`; emit `BOUNDARY`):**
+`warn` prints each task's verdict; `block` additionally LIFTS a REFUSE task out of
+the wave — **the wave still runs the rest** — and hands it back with its checklist
+plus the "not blocked for you" line (it gates ORC's dispatch, never an explicit
+instruction). ESCALATE dispatches but gates ship on the named human, riding the
+EXISTING pause machinery. An uncarded area is `unknown`, never REFUSE. **Pattern-resolve gate
+(once, before the first wave):** resolve each tagged language per
+`../../orc/references/pattern-gate.md` and report ONE user line per language (cache hit →
+apply cached; miss → codify/agnostic per `pattern_findings`; learn → dispatch
+the codifier); hold resolved patterns in run state.
+
+**TDD red proof — PAIRED TASKS, not a Wave 0 (v0.41.0):** TDD tasks are ORDINARY planner-emitted tasks the impl task `depends_on`, so they wave and score like any other (mechanics in `wave-grouping.md`); no `new-surface`/`behavior-change` entries → no TDD task at all. Each materializes its skeletons into real FAILING tests and returns the red evidence; emit `TDD-RED task=<id> iter=0` per requirement.
+**Pre-implementation green is read per `disposition`:** a `new-surface` entry that PASSES is a spec bug → block that requirement's dispatch and surface it; a `behavior-change` regression-guard passing is EXPECTED and blocks nothing; anything else → adjudicate with the user, recorded in `decisions`. Then per implementation wave:
+1. Dispatch EVERY task as a spawned subagent (emit `DISPATCH <agent> :: <task>
+   expect=<model>/<effort>` BEFORE the Task call; subagent wrapper framing + the
+   task's INPUT SLICE per orc-execution/core.md + its scored model). Every
+   slice carries the task's `acceptance[]`, its `tdd_spec` tests (the executor
+   implements to green: implement→test→repair, cap `tdd_loop_max`, emitting
+   `TDD-RED`/`TDD-GREEN` per iteration; cap hit → STOP SEQUENCE + honest red
+   report) and the `house_rules` card lines
+   (`house-rules.md`, injected LITERALLY — read once per run, never
+   a pointer); FE/BE and `db:postgres` tasks get the resolved `pattern`
+   injected literally (pattern-gate.md), and — with `gotchas: on` — the
+   SCOPE-MATCHING gotchas beside it (glob vs this task's `declared_files`, cap 3,
+   highest `hits` first; zero matches = NO block, never an empty one — NEVER
+   inject unfiltered: `_shared/gotchas.md` §7).
+   **A FOREIGN task uses Bash, not the Task tool:** write the IDENTICAL slice to a
+   file and run `orc extra dispatch --task <file> --json` (exit codes + the
+   fallback procedure: `../extra-dispatch.md`). Append `via=extra:<profile>`
+   to the `DISPATCH` line and copy the return's `trace_line` + every
+   `trace_extras[]` entry VERBATIM into the packet — the CLI composes them, and the
+   hook emits NO `SPAWN`/`RETURN` for a foreign worker, so they are the whole record.
+2. Record worker milestone pings (they bound what a mid-wave stop can save).
+3. Collect returns; VALIDATE each (emit `VERIFY <task> actual=<model>/<effort>`
+   ✅ MATCH / ⛔ DOWNGRADE per return — surface any downgrade to the user).
+   **A FOREIGN return runs `_shared/return-validation.md` §2b INSTEAD of §2** — it
+   has no injected model-id line, so it cannot carry `actual_model` and faking one
+   claims evidence that does not exist; ⛔ SUBSTITUTION replaces the downgrade
+   check. A failure runs the fallback procedure, which BEGINS with a free
+   `orc extra reconcile <task>` — a worktree that moved is RESUMED, never re-done
+   — then re-dispatches or STOPs, announced, with the `EXTRA fallback` line.
+   `needs_context` → adjudicate → re-slice
+   (cap 2 per task, then escalate). A `pattern` task must return
+   `invariants_checked: true` + the matching `pattern_version`. **Evidence
+   check:** `status=done` on a stack with a runnable build/test REQUIRES
+   `evidence` {command, exit_code, tail} — a missing block or false
+   `no_runner_detected` is malformed (requeue); `done` with non-empty
+   `unmet[]` is `partial`.
+4. **Post-wave worktree audit (GATE, `_shared/return-validation.md` §6):** diff `git status --short` before/after the wave — a changed path in NO task's `declared_files`, INCLUDING one that became less modified (the revert signature), blocks the close until named and decided.
+   Overlap → `failure_reason: "file-collision:<file> with <agent>"`, requeue later wave.
+5. Append worker `log_entries` to the decision log; regenerate the digest.
+   **Gotcha capture (`gotchas: on`):** a return that CLOSED a repair loop carries
+   `gotcha_recorded` (`_shared/return-validation.md` §7) — dedupe on
+   `symptom`+`scope` (a match bumps `hits`/`last_seen` and appends nothing), else
+   append the block to `.claude/orc/gotchas.md`. YOU write it, never a subagent;
+   a capped-and-stopped loop records NOTHING.
+6. Update checkpoint + state-of-play; emit `OUTCOME task=<id> score=<n>
+   band=<range> model=<m> retries=<n> requeues=<n> needs_context=<n> unmet=<n>`
+   as each task closes.
+7. **Wave-boundary gate (deterministic — NOT judgment):** after wave W, if the
+   wave's `is_batch_pause` is true (W in `pause_schedule`) AND a later wave
+   remains, emit `GATE wave-boundary :: wave=W of K → STOP (batch_pause_every=N)`
+   and run the MANDATORY STOP SEQUENCE — never dispatch wave W+1 past an
+   unacknowledged boundary. Token pressure → same STOP SEQUENCE (judgment).
+   Last wave closes → emit `PHASE execution end`. (stop-resume.md)
+
+**User escalations:** relay question → broadcast answer to log; an answer that
+invalidates a DONE task → re-run once, then set every reverse-`depends_on`
+consumer to `stale_review`. **Worker failure/garbage/timeout:** flag +
+continue the wave; audit and re-dispatch at the next batch checkpoint
+(`requeued`, retry_count++). Hard retry cap 2 → STOP and surface.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Execution (waves)
+
+Run execution exactly as the full lane's execution subskill defines it —
+follow `.claude/skills/orc/subskills/orc-execution/SKILL.md` (slices
+constructed by you, standing rules injected, evidence-bearing returns
+validated against the contract) with these compiled overrides:
+
+- Max parallel tasks per wave: **{{max_wave_tasks}}** (hard cap; overflow →
+  next wave; wave grouping per
+  `.claude/skills/_shared/phases/wave-grouping.md`).
+- Stop-and-continue pause every **{{batch_pause_every}}** waves (checkpoint
+  confirmed BEFORE announcing any stop; resume per
+  `.claude/skills/_shared/phases/stop-resume.md`).
+- Executor selection comes from this flow's scoring section above — never
+  from the shipped presets.
+
+<!-- diy:when tdd=on -->
+TDD execution: `tdd_spec` is SCOPED by each entry's `disposition` — only
+`new-surface` and `behavior-change` get tests; `covered-by-existing` (cited
+existing test) and `no-behavior` (constants, translation strings, docs, config)
+get none, and a task with cited `risk[]` is never scoped out. A PAIRED TDD task
+(never a Wave 0) materializes the remaining skeletons into real
+FAILING tests (red proven before implementation; a `new-surface` pre-implementation
+pass is a spec bug → block that requirement). Each implementation slice carries its
+`tdd_spec`; executors implement to green (implement→test→repair, cap
+`tdd_loop_max`; `TDD-RED`/`TDD-GREEN` per iteration) and return `tdd_state`
+per `.claude/skills/_shared/return-validation.md` — including §6's worktree
+delta: `git status --short` before/after each dispatch, any changed path
+outside `declared_files` (a revert included) gates the wave close.
+<!-- /diy:when -->
+
+<!-- diy:when gotchas=on -->
+Repair memory: probe `orc gotcha status` once at preflight (exit 0 = entries,
+1 = none — never a `find`) and print one line either way. Inject the
+SCOPE-MATCHING entries into each slice beside `pattern` — glob vs that task's
+`declared_files`, cap 3, highest `hits` first; zero matches = NO block, never an
+empty one, and NEVER unfiltered. A return that CLOSED a repair loop carries
+`gotcha_recorded`; dedupe it on `symptom`+`scope` (a match bumps `hits` and
+`last_seen`) and append it to `.claude/orc/gotchas.md` YOURSELF — a subagent never
+writes that file, and a loop that hit its cap and stopped records nothing. Full
+contract: `.claude/skills/_shared/gotchas.md`.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

package/templates/skills/{orc/references → _shared/phases}/house-rules.md

@@ -1,4 +1,14 @@
-# ORC House Rules (standing behavioral card)
+# Phase — House rules   (id: `house-rules`)
+
+> **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-quick`, `orc-doc`. Layers declared:
+> `core` only — single-layer because it is a standing card injected VERBATIM
+> into a slice — a layered card would be a different card. `orc lane phases
+> <lane> --json` names the file and the layers to read.
+
+<!-- orc:layer core -->
+## ORC House Rules (standing behavioral card)
 
 Injected LITERALLY into every executor slice as `house_rules` — never a file
 pointer. Keep the card ≤ 10 lines: it rides in EVERY dispatch, so every
@@ -18,3 +28,5 @@ HOUSE RULES (standing, apply to every change):
 6. An honest partial beats a false done — report what's unmet, never round up.
 7. Never revert, discard or rewrite files you did not write — `git checkout/restore/reset/stash/clean` are forbidden in your slice; an impossible assertion is `unmet`, never something to make true.
 <!-- card-end -->
+
+<!-- /orc:layer -->

package/templates/skills/{orc/references → _shared/phases}/intake.md

@@ -1,4 +1,15 @@
-# Reference — Phase 0 Intake
+# Phase — Intake   (id: `intake`)
+
+> **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-diy`, `orc-challenge`. Layers: `core` and `full`
+> — `core` is the intake procedure every lane runs; `full` is /orc's own Phase
+> 0, which adds the analyst branch, the poly-spec split-and-STOP and the run-
+> folder open. `orc lane phases <lane> --json` names the file and the layers
+> to read.
+
+<!-- orc:layer core -->
+## Reference — Phase 0 Intake
 
 Goal: extract just enough that the intent-spec can't be misread, then get out of
 the way. A wrong understanding parallelized is worse than a wrong understanding
@@ -7,7 +18,7 @@ done serially. Never interrogate; never ask what the repo can tell you.
 **Before anything — plan-input trigger (see `plan-handoff.md`):** if the run
 input IS a plan (pasted planning-output, a `plan-{name}.md` path, or an
 `orc/planner/{name}/` checkpoint), do NOT run intake — switch to the plan-handoff
-entry contract (`references/plan-handoff.md`): bootstrap the trace, schema-
+entry contract (`plan-handoff.md`): bootstrap the trace, schema-
 validate, apply the `plan_head` staleness valve, re-run the full Phase 1 exit
 gate in this session, relay `open_questions[]`, then continue at Phase 2. A plain
 prose request is not a plan — run intake normally.
@@ -118,3 +129,5 @@ showing unless the user objects.
 When resuming a run in a fresh session, show a ONE-LINE reconfirm of the
 intent-spec's scope ("Resuming: <one-line scope>. Still correct?") before
 continuing. Catches requirements that changed between sessions, costs one line.
+
+<!-- /orc:layer -->

package/templates/skills/_shared/phases/mock-example.md

@@ -0,0 +1,56 @@
+# Phase — Mock example + drift recovery   (id: `mock-example`)
+
+> **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 -->
+
+## Mock example + drift recovery (config `mock_example`)
+
+Load `../drift-recovery.md` (canonical). Only after a GREEN Phase 6,
+before ship: `ask` (default) → the offer is MANDATORY (never silently skipped,
+never silently run); `on` → build; `off` → skip. Deliverable:
+`mock-examples/<change-slug>/` at the project root (`EXAMPLE.md` + one minimal
+runnable artifact; mocked inputs only) — **NEVER committed**. After the user
+runs it, ONE question: matches expectation? [yes / drift: <describe>]. On
+drift → `DRIFT-FROM` handoff → analyze-mini gap analysis → mini planner patch
+plan → scored dispatch → re-verify → re-offer; **hard cap 2 loops**, then an
+honest unresolved report. Emit `DRIFT loop=<n>` per loop; end-of-phase packet.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Mock example (after a green verify, before ship)
+
+<!-- diy:when mock_example=off -->
+The mock-example phase is DISABLED in this flow. Skip silently.
+<!-- /diy:when -->
+<!-- diy:when mock_example=ask -->
+After the verify/smoke gate is GREEN and BEFORE any ship action, the offer is
+MANDATORY (never silently skipped, never silently run): follow
+`.claude/skills/_shared/drift-recovery.md` — build
+`mock-examples/<change-slug>/` (EXAMPLE.md + one minimal runnable mocked
+artifact) only on a yes. After the user runs it, ask the one drift question;
+on drift run the `DRIFT-FROM` recovery loop (hard cap 2, then an honest
+unresolved report). `mock-examples/` is NEVER staged by the ship phase.
+<!-- /diy:when -->
+<!-- diy:when mock_example=on -->
+After the verify/smoke gate is GREEN and BEFORE any ship action, build the
+mocked example without asking, per
+`.claude/skills/_shared/drift-recovery.md`: `mock-examples/<change-slug>/`
+(EXAMPLE.md + one minimal runnable mocked artifact; mocked inputs only). Then
+ask the one drift question; on drift run the `DRIFT-FROM` recovery loop (hard
+cap 2). `mock-examples/` is NEVER staged by the ship phase.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

package/templates/skills/{orc/references → _shared/phases}/plan-handoff.md

@@ -1,8 +1,19 @@
-# Reference — Plan Handoff (executing a plan from another session)
+# Phase — Plan handoff   (id: `plan-handoff`)
+
+> **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-route`. Layers declared: `core` only — single-layer because
+> executing a plan another session wrote is the same procedure wherever it is
+> done, and /orc-route reads it to DEFINE what a plan is (v0.42.0 — a second
+> definition is drift the lint cannot see). `orc lane phases <lane> --json`
+> names the file and the layers to read.
+
+<!-- orc:layer core -->
+## Reference — Plan Handoff (executing a plan from another session)
 
 The entry contract for the case ORC had no defined path for: **the run input
 IS a plan**, not a request. A plan was produced in one session (or saved to a
-file) and handed to a fresh session to build. Load `references/plan-handoff.md`
+file) and handed to a fresh session to build. Load `plan-handoff.md`
 at Phase 0 the moment you recognise a plan input; it turns a pasted plan into a
 real ORC run instead of an ad-hoc task-by-task improvisation.
 
@@ -36,7 +47,7 @@ Do these IN ORDER before any dispatch. Skipping any step is a protocol
 violation.
 
 1. **This IS a run — bootstrap it.** Load the spine (`orc/SKILL.md`) and
-   `references/trace-protocol.md`; create `log_dir`, write `log_dir/.current` =
+   `../../_shared/phases/trace.md`; create `log_dir`, write `log_dir/.current` =
    `run-orc-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
    in the SAME step (both, or neither — a pointer naming a file that does not
    exist is what splits a run across two files), store `trace_path` in the
@@ -82,3 +93,5 @@ violation.
 - **Not** a poly-spec path. A poly-spec (`orc-poly:spec`) is split-and-STOP at
   Phase 1 (see SKILL.md) — that is a different input than a per-repo
   planning-output handed here to build.
+
+<!-- /orc:layer -->

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

@@ -0,0 +1,135 @@
+# Phase — Planning   (id: `planning`)
+
+> **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 -->
+
+## Planning
+
+Emit `PHASE planning start`, then emit ONE `CONFIG <key=value …>` line with the
+resolved values of every config key this run will consume (ALWAYS `opus5_only` — it selects the executor table AND every fixed role, so retro can segment per-band outcomes BY dispatch mode) — the runtime
+proof `/orc-retro` audits that the run honored the config.
+**Wiki consult (load `wiki-consult.md`;
+always report — no tier is silent):** read the FRESH/AGING/STALE tier from
+**`orc wiki status`** (v0.41.0 — deterministic; never hand-compute it from `wiki-meta.json`), pull the relevant pages (incl. cross-cutting maps like `orc-reference-api-surface`), apply
+`code > fresh wiki > stale wiki (hints) > model priors`, emit
+`WIKI-CONSULT <tier> :: docs=<pages>`, print the one-line tier report (every tier, `absent` included), and attribute per-dispatch too — `wiki:` on the `DISPATCH` line + a `wiki_used` return (wiki-consult.md Step 5). **Crosslink:** per wiki-consult.md, inject
+the cached `.claude/orc/crosslink/needs.json` contract into any boundary-touching
+task (advisory) and print + emit `CROSSLINK <state> :: boundaries=<n> peers=<names>`
+— `configured-no-cache` prints the "cache not built" warning (full orc reads
+only pre-built needs/cache, never peer source live). **Gotchas (repair memory,
+config `gotchas`):** probe ONCE with `orc gotcha status` (exit 0 = entries exist,
+1 = none — never a `find`); canonical `_shared/gotchas.md`.
+**Pact / boundary / aftermath / wiki debt (v0.46.0 — all CONSUMED here, never
+written here):** probe `orc pact status --json` (`pact_gate`, default `warn`),
+`orc boundary status --json` (`boundary_gate`, default `warn`), `orc wiki debt
+--json`, and — only to decide whether the preflight's `after:` line fires at all —
+`orc aftermath status --json`. Print each probe's own `line` VERBATIM; never
+recount or re-word one. Gates: `../../orc-pact/references/gate.md` +
+`../../orc-boundary/references/gate.md`. **Challenge (v0.47.0, `challenge_gate`,
+default `warn`):** when the run's INPUT DOCUMENT has a cycle, print
+`orc challenge status <slug> --json`'s `preflight_line` verbatim — building from
+a document that has not passed its own review is worth one line. There is no
+`block` mode (the `/orc-pact` precedent). **Extra (v0.50.0, `extra_enabled`) —
+resolved HERE, announced HERE, never silent:** load `../extra-dispatch.md`;
+per task run `orc extra resolve <score> --role executor --risk <n> --json`, and
+before wave 1 settle its two pre-dispatch states, both PRINTED — a `needs_reping`
+profile (re-ping; a STALE profile still routes) and a vaulted credential, which is
+**LOCKED AT DISPATCH TIME whatever `credential.present` says** and falls back to
+Claude rather than stopping the run. **Preflight:** print the compact block per
+`../../orc/references/preflight-report.md` once wiki + crosslink (+ pattern/waves) resolve.
+
+Ask which planner: **Superpowers / OpenSpec / Requirement Planner / ORC
+(self)**. With an analyst requirement-spec present, the Requirement Planner
+is the natural choice (consumes the spec; does NOT re-question scope); apply
+the `git_head` staleness valve first (analyst-gates.md). Dispatch the planner
+as a subagent — never plan yourself.
+
+**CRITICAL — planning always hands back here.** However a plan was produced,
+control returns to THIS orchestrator, which runs Phase 2 → 3 → … → 8 — never
+jump from a plan straight to implementation. **ONE exception — a poly-spec
+(`orc-poly:spec`, from `/orc-poly`):** the planner runs poly-split mode (one
+plan per repo, each pinned to the frozen contract, each written into its own
+repo); present the per-repo plans + build handoff and STOP — a poly-spec is the
+only input that does NOT proceed to Phase 2 (each repo builds later, in its own
+`/orc` session). The plan must satisfy
+`../../orc/schemas/planning-output.md` (per-task `declared_files` incl. tests,
+`grounding[]`, `acceptance[]`, `requirements[]`, `spec_invariants[]`,
+`depends_on`, `owns_area`, `spec_ref`, + a `coverage` echo, + `tdd_spec` —
+TDD is ALWAYS ON in full orc/ultra but **SCOPED to what can actually fail (v0.41.0)**: a `disposition` per entry (`new-surface | behavior-change | covered-by-existing | no-behavior | no-runner`) DERIVED from the planner's facets — constants/translations/file-splits get NO test, a cited `risk[]` is never scoped out, and a PAIRED task materializes it, never a Wave 0 (schema notes 7-8; gate check 5);
+missing declared files → extract and confirm before leaving this phase.
+
+**Phase 1 exit gate** (deterministic — full checks in analyst-gates.md; emit
+`GATE` lines): Glob every `disposition: exists` path, recompute coverage (no
+`orphan` requirements), cycle + same-file collision checks. Any miss →
+bounce to the planner (one retry), then escalate. **After the gate passes,
+relay the plan's `open_questions[]` in ONE batch:** blocking questions must be
+answered before Phase 2; non-blocking show their `proposed_default` for tacit
+approval. **Step-back valve:** `plan_confidence: low` OR >3 blocking questions →
+recommend stepping back to `orc-analyze` (user may override and proceed).
+**Pact injection (`pact_gate: warn`) — the payoff, and it happens HERE:** a
+DRIFTED or BROKEN promise whose `anchors` intersect a task's `declared_files` is
+appended VERBATIM to that task's `constraints[]` (the `spec_invariants[]`
+channel — no new plumbing) and PRINTED per task. HOLDING entries are never
+injected. Last month's decision constrains this month's plan, automatically. On
+pass, emit `PHASE planning end`.
+
+**Then print the `forecast:` block, BEFORE the Phase-2 pause question**
+(`../../orc/references/preflight-report.md`) — tasks · waves · estimated subagents · model
+mix · a measured time RANGE · one cheaper lane and what it costs. This is the
+earliest instant every number is real and the last cheap moment to walk away.
+Presentation only, no new probes. When `config.run_budget_dispatches` > 0 and the
+forecast exceeds it, this is a **hard stop** with the batch pause's discipline
+(`GATE budget stop`) offering proceed · cheaper lane · re-plan smaller — never
+dispatch wave 1 past it.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Planning
+
+<!-- diy:when planning=auto -->
+Route planning exactly as the full lane does — Superpowers plan, OpenSpec
+change, or ORC's own planner, chosen by what exists in the project. Follow
+`.claude/skills/orc/subskills/orc-planner/SKILL.md` for the own-planner path
+and validate the planning output against
+`.claude/skills/orc/schemas/planning-output.md`.
+<!-- /diy:when -->
+<!-- diy:when planning=own-planner -->
+Always use ORC's own Requirement Planner, even when Superpowers/OpenSpec
+artifacts exist: follow `.claude/skills/orc/subskills/orc-planner/SKILL.md`
+and validate the planning output against
+`.claude/skills/orc/schemas/planning-output.md`.
+<!-- /diy:when -->
+<!-- diy:when planning=superpowers -->
+Plan via Superpowers: require a Superpowers-written plan as planning input
+(ask the user to produce one if absent), then convert it to ORC planning
+output validated against `.claude/skills/orc/schemas/planning-output.md` —
+same conversion the full lane applies on its Superpowers route.
+<!-- /diy:when -->
+<!-- diy:when planning=openspec -->
+Plan via OpenSpec: require an OpenSpec change as planning input (ask the user
+to produce one if absent), then convert it to ORC planning output validated
+against `.claude/skills/orc/schemas/planning-output.md` — same conversion the
+full lane applies on its OpenSpec route.
+<!-- /diy:when -->
+<!-- diy:when tdd=on -->
+TDD is ON for this flow: the plan must carry a `tdd_spec` per requirement
+(given/when/then + a runnable skeleton in the project's test framework, or
+`tdd: exempt — <reason>`; schema in
+`.claude/skills/orc/schemas/planning-output.md`). No test runner in the
+project → whole-run exemption, stated once at preflight.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

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

@@ -0,0 +1,76 @@
+# Phase — Preflight   (id: `preflight`)
+
+> **Library file.** New at v1.0.0 W11, distilled from the eleven lane preflight
+> sections that had independently converged on the same four steps in the same
+> order. Layers: `core` (every lane with a silent preflight) and `full`
+> (`/orc` and `/orc-ultra`, whose preflight also PRINTS a report).
+>
+> **What is NOT here:** the probes themselves. Which artifacts a lane probes, and
+> which config keys it reads, are the lane's own — they are in the lane's spine
+> and in `orc lane config <lane> --json`. This file is the SHAPE: the order, and
+> the four rules that make the shape worth having.
+
+<!-- orc:layer core -->
+
+## The order is the contract
+
+Four steps, always in this order, and a lane adds its own probes to step 3 —
+never a fifth step before step 2.
+
+1. **Config.** Resolve every key this lane reads through **one** resolver:
+   `orc lane config <lane> --json`. Never merge `.claude/orc.config.yaml`
+   yourself. Print every line of `announce[]` VERBATIM — *a shadowed setting must
+   never be silent*, and a lane that resolves silently cannot tell the user why
+   the thing they configured did not happen. Precedence, gates, inertness and the
+   CLI-absent floor are all in `../config-precedence.md`.
+
+2. **Trace.** Write `log_dir/.current` = `run-<lane>-<slug>-<DDMMYY>-<HHMMSS>.txt`
+   AND `touch the trace file` of that name in the SAME step. **Both, or neither.**
+   A pointer naming a file that does not exist is indistinguishable from a
+   dangling one — that split fifteen graded runs across two files each. The rest
+   of the protocol is `trace.md`.
+
+3. **Probes.** Use `../detecting-artifacts.md` — **never a raw `find`**, because
+   `.claude/` is hidden and a filesystem search false-negatives a real artifact
+   from the wrong CWD. Every probe is a documented exit-code contract, listed
+   once in `orc lane calls <lane>`. Treat a positive probe as the source of truth
+   and never second-guess it.
+
+4. **One line each.** Print one line per probe, per resolved gate, per tier.
+   **A probe whose answer is silent is a probe that gets skipped** — by the next
+   maintainer, and eventually by the model. An empty result is an ANSWER and
+   still gets its line.
+
+## The four rules
+
+- **Preflight is SILENT in the sense that it asks nothing** — it prints, it never
+  interviews. A question in preflight is a question asked before the lane knows
+  enough to ask it well.
+- **Nothing here stops a run unless the lane's own spine says it does.** Most
+  lanes treat missing knowledge as a helpful extra: it means more of the work is
+  a question instead of a lookup. `/orc-fast` is the exception, and it says so.
+- **ONCE per run** (`/orc-quick`: once per session). A preflight that re-runs is
+  a preflight nobody reads.
+- **An exit code is an answer, not a failure.** `orc pact status` exit 3 is "no
+  ledger yet, this is a first run"; `orc gotcha status` exit 1 is an empty
+  ledger. Say what it means, not that it failed.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer full -->
+
+## `/orc` and `/orc-ultra` — preflight also REPORTS
+
+The full lane's preflight does everything in `core` and then prints the
+**preflight report**: tasks · waves · estimated subagents · model mix · the wiki
+tier · the resolved pattern · crosslink state · the pause schedule · the run
+budget. That format, its `GATE budget stop|pass` line and the FLOOR rule (repairs
+push the real count up, never down) live in the `orc` skill's own
+`references/preflight-report.md` — read it relative to that skill. It has ONE
+consumer, so it stays home rather than moving here.
+
+A trimmed lane must **not** read that file. `orc-mini` and `orc-fast` print their
+resolved lines and go; there is no forecast to report because there are no waves
+to forecast.
+
+<!-- /orc:layer -->