@azure-id/orc 0.56.1 → 1.0.0

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 -->

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

@@ -0,0 +1,53 @@
+# Phase — Review   (id: `review`)
+
+> **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 -->
+
+## Review (load ../../orc/subskills/orc-review-verify/, spawned)
+
+Emit `PHASE review start`. Superpowers path: its review skill incl. tests
+(Sonnet 4.6 medium). OpenSpec/self path: review worker (Opus 5 medium). Pass the resolved
+`code_pattern` + its invariants + gate lines for the re-check
+(pattern-gate.md); no resolved pattern → FIRST ask for one (paste/md/none).
+FE tasks in run → pass `fe_rules[]` from `../../orc-pattern/references/` fe-a11y
++ fe-perf. Findings arrive on the **P0–P3 ladder** (invariant violation or
+unmet gate line = P0; every P0–P2 carries `file:line` + VERBATIM `quote`;
+unanchored → P3). Apply hard rule 5 INCLUDING the quote spot-check: P0 →
+auto-fix once · P1 → ask, then fix once · P2/P3 → record for Phase 7. Emit
+`FINDING p0=<n> p1=<n> p2=<n> p3=<n>` on the return, then `PHASE review end`.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Review
+
+<!-- diy:when review=off -->
+Code review is DISABLED in this flow. Say so in the run summary line ("review
+skipped by flow config") — never imply the work was reviewed.
+<!-- /diy:when -->
+<!-- diy:when review=on -->
+Dispatch the reviewer exactly as the full lane does — follow the review half
+of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` (reviewer agent
+`orc-reviewer-opus-5-med`; findings ride the severity ladder from the
+locked rules, blocking and advisory findings both surfaced).
+<!-- /diy:when -->
+<!-- diy:when review=blocking-only -->
+Dispatch the reviewer exactly as the full lane does — follow the review half
+of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` — but only
+P0/P1 findings gate anything; P2/P3 findings are listed once in the summary
+and never re-offered as fix-up tasks.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

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

@@ -0,0 +1,65 @@
+# Phase — Effort & scoring   (id: `scoring`)
+
+> **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 -->
+
+## Effort, dispatch style, scoring (load ../../orc/references/effort-and-mode.md)
+
+Emit `PHASE scoring start`. Refine effort; recommend **sequential** vs
+**parallel** dispatch (worktrees for high-effort independent features) — user
+confirms. Dispatch style is **intra-wave concurrency only**: waves are computed
+regardless of style (sequential runs have waves too, see wave-grouping.md), so
+the batch pause always binds to wave numbers. **Batch-pause schedule (deterministic, not a cadence hint):** the plan
+has K waves — ask "pause after every wave / every 2nd / run straight through?"
+and SHOW the resulting stop list ("will pause after waves [list]"); a 2-wave
+plan plainly offers "pause after wave 1". Store it as `pause_schedule`, recompute
+each wave's `is_batch_pause` (last wave never pauses). **Facet-validation gate
+(deterministic):** recompute `breadth` + `fan_in`/`fan_out` from the plan; a
+mismatch or an uncited `risk` entry bounces the plan (grounding mechanics).
+**Score every task** from its `facets` via the fixed formula, map to the model
+ladder, show the facet vector + arithmetic table, and emit `SCORE task=<id>
+score=<n> band=<band> model=<m> facets=<vector> :: <reason>` per task; a score
+override needs a written reason (logged). **With `extra_enabled`** the table gains
+a `via` column and its head can name TWO tables (effort-and-mode.md); a foreign
+task's `SCORE` appends `via=extra:<profile>` and `model=` is the FOREIGN model id.
+**Cited-risk hold-back (deterministic, beside the facet gate):** a foreign-routed
+task with a non-empty `risk[]` is HELD BACK to its Claude band (`extra_risk_tasks`
+defaults to `off`) and every one is LISTED with its cited risk — a silently
+held-back task is indistinguishable from a forgotten one. Use the wiki's "Notes for planning" to sharpen
+core/isolated + risk factors. **Tag each task's pattern domain+language**
+(+ secondary `db: postgres`) per `../../orc/references/pattern-gate.md`. Ask: "Any
+anticipated escalations, or run straight through?" Emit `PHASE scoring end`.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Task scoring → executor selection
+
+<!-- diy:when scoring=on -->
+Score each task 0–100 with the full lane's rubric (see the scoring section of
+`.claude/skills/orc/SKILL.md`), then dispatch the executor agent from THIS
+compiled table — it is already clipped to this flow's session tier; never
+substitute a preset from `config.md`:
+
+{{score_table}}
+<!-- /diy:when -->
+<!-- diy:when scoring=off -->
+Scoring is DISABLED in this flow. Skip the rubric entirely: EVERY execution
+task dispatches to **{{fixed_executor}}**. Wave grouping, declared-files
+conflict rules, and slice construction are unchanged — scoring off changes
+model selection only, never scheduling.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

package/templates/skills/{orc/references → _shared/phases}/security-checklist.md

@@ -1,4 +1,13 @@
-# Reference — Security-Pass Checklist (Phase 5.5, opt-in)
+# Phase — Security pass   (id: `security-checklist`)
+
+> **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 an
+> opt-in pass either runs its checklist or does not run. `orc lane phases
+> <lane> --json` names the file and the layers to read.
+
+<!-- orc:layer core -->
+## Reference — Security-Pass Checklist (Phase 5.5, opt-in)
 
 Loaded ONLY when the Phase 5.5 security pass fires (config `security_review`
 `on`/`ask` + a task scored ≥ 70 in the run). Passed to the reviewer as
@@ -37,3 +46,5 @@ a hardening gap on a touched path = P1 · defense-in-depth suggestions = P2/P3.
     surfaced to callers by the new error handling.
 12. **Crypto misuse** — home-rolled hashing/encryption, weak algorithms (MD5,
     SHA1 for passwords), missing salts, static IVs in the diff.
+
+<!-- /orc:layer -->