@azure-id/orc 1.7.0 → 1.8.1

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

@@ -1,135 +1,142 @@
-# 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 -->
+# 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`.
+**Code graph (`../code-graph.md` §7):** with the graph on, run
+`orc graph impact <candidate declared_files> --if-enabled --json` and hand its
+callers to the planner — they sharpen `declared_files` and the `fan` and risk
+facets. Also run `orc graph cochange <each candidate file> --if-enabled --json`:
+it answers "what else will I have to touch" from HISTORY, which a static edge
+cannot see. Co-change is a HINT about people, never a dependency — exit 4 means
+this file changes alone, which is an answer. Exit 3 or 4 → plan exactly as before.
+**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

@@ -1,118 +1,132 @@
-# 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.
-
-## The rules line (v1.7.0) — printed by every lane that runs the `rules` phase
-
-`orc rules slice --lane <lane> --json` returns a `line`. Print it VERBATIM:
-
-```
-rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 9 lines (P0 4 · P1 2 · P2 3) · 1 override
-rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
-```
-
-**Both spellings are mandatory in their state.** `yours none` says the project
-has not written its own rules — a different fact from the CLI failing to look,
-and the line is what keeps the two apart. Never compute the counts here.
-
-Where the lane's preflight prints a REPORT rather than a bare line, the report
-names each override under it. An override the user cannot see is an override
-they cannot audit. The rest of the mechanic is `./rules.md`.
-
-`/orc-doc` prints `house rules: …` instead, from `orc doc rules`. The two
-surfaces are different files and never mix.
-
-## The usage line (v1.1.0) — printed whenever `usage_gate` is armed
-
-`usage_gate` resolves in step 1 like any other key. When it is anything but
-`off`, run `orc usage check --json` in step 3 and print ONE line:
-
-```
-usage:    5h 71% · wk 38% · gate at 10% left · warn
-usage:    unknown (no reading in the last 30 minutes) · a run is never stopped on this
-```
-
-Both spellings are mandatory in their state. A gate that prints only when it
-fires is a gate the user cannot tell from a gate that is not running — and the
-`unknown` line is what stops someone believing they are protected when Claude
-Code is sending no usage headers at all.
-
-**Exit 2 (`unknown`) NEVER stops a run.** Absent is not low.
-
-A `blocked` run (`orc wait status --json`) prints the block and its AGE here too,
-and again at every gate it suppresses. The rest of the mechanic — the modes, the
-hops, what `stop` and `wait` actually do — is `../wait.md`; this file only says
-that the line is printed and when.
-
-<!-- /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 -->
+# 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.
+
+## The rules line (v1.7.0) — printed by every lane that runs the `rules` phase
+
+`orc rules slice --lane <lane> --json` returns a `line`. Print it VERBATIM:
+
+```
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 9 lines (P0 4 · P1 2 · P2 3) · 1 override
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
+```
+
+**Both spellings are mandatory in their state.** `yours none` says the project
+has not written its own rules — a different fact from the CLI failing to look,
+and the line is what keeps the two apart. Never compute the counts here.
+
+Where the lane's preflight prints a REPORT rather than a bare line, the report
+names each override under it. An override the user cannot see is an override
+they cannot audit. The rest of the mechanic is `./rules.md`.
+
+`/orc-doc` prints `house rules: …` instead, from `orc doc rules`. The two
+surfaces are different files and never mix.
+
+## The usage line (v1.1.0) — printed whenever `usage_gate` is armed
+
+`usage_gate` resolves in step 1 like any other key. When it is anything but
+`off`, run `orc usage check --json` in step 3 and print ONE line:
+
+```
+usage:    5h 71% · wk 38% · gate at 10% left · warn
+usage:    unknown (no reading in the last 30 minutes) · a run is never stopped on this
+```
+
+Both spellings are mandatory in their state. A gate that prints only when it
+fires is a gate the user cannot tell from a gate that is not running — and the
+`unknown` line is what stops someone believing they are protected when Claude
+Code is sending no usage headers at all.
+
+**Exit 2 (`unknown`) NEVER stops a run.** Absent is not low.
+
+A `blocked` run (`orc wait status --json`) prints the block and its AGE here too,
+and again at every gate it suppresses. The rest of the mechanic — the modes, the
+hops, what `stop` and `wait` actually do — is `../wait.md`; this file only says
+that the line is printed and when.
+
+## The graph line (v1.8.0) — code-changing lanes only
+
+`/orc`, `/orc-ultra`, `/orc-diy`, `/orc-mini`, `/orc-fast` and `/orc-quick` run
+`orc graph status --if-enabled --heal --json` in step 3, BEFORE the first
+dispatch — never skipped. `--heal` builds a missing graph and updates a drifted
+one in the same call (it is free), so there is no second call to forget. Print
+its `line` (`off` included) and put its `trace` (`GRAPH-CONSULT …`) in the next
+packet as it is — never as a `GATE` line in your own words. While the graph is
+on, `orc lane config` prints the three graph steps in `announce[]` (`../code-graph.md`
+§0). **The lane reads no `code_graph` key:** `--if-enabled`
+makes the CLI decide, which is how `/orc-quick` takes part while its step 1 still
+reads `log_dir` and nothing else. A graph that cannot be built never stops a run,
+and `/orc-fast` gains no third gate. Every other lane prints nothing.
+
+<!-- /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 -->