@azure-id/orc 1.7.0 → 1.8.1

package/templates/skills/orc-mini/SKILL.md

@@ -1,259 +1,267 @@
----
-name: orc-mini
-description: >
-  Lightweight ORC for fast implementation. Use for
-  "use orc-mini to implement X" or "/orc-mini". Same
-  intake → intent-spec → planning → dispatch → smoke-gate → ship spine as the full
-  orchestrator, but SKIPS full code review, verification, and the summary phase.
-  Dispatches ONE Sonnet 5 high-effort subagent for implementation, then runs a
-  build+test smoke gate (blocks ship on red) and offers opt-in test authoring.
-  Switchable to full flow mid-run. The orchestrator never implements — it spawns.
----
-
-# ORC-MINI
-
-A trimmed orchestrator for when you want speed over the full quality pipeline.
-Everything in the main spine (`../orc/SKILL.md`) applies EXCEPT the
-differences below. Load the main skill's references and schemas by path — the
-HOT-PATH essentials (dispatch names, return-contract fields, artifact path)
-are inlined here so nothing is reconstructed from "full minus deltas."
-
-Run as **Opus 4.8 high**, or Opus 5 / Fable 5 at medium+ (as full; never downgrade).
-**You never implement — you spawn.** The one exception is the **smoke gate**:
-a read-only build+test run, not implementation — you still never write code.
-
-**Worked example** (orient only — never execute from it): `examples/mini-run-mock.md`.
-
-## Differences from the full orchestrator
-
-1. **Skip full Phase 5 (Review), Phase 6 (Verify), and Phase 7 (Summary).**
-   Instead: the **smoke gate** after execution, then the opt-in
-   **test-authoring ask**, then ship.
-2. **Implementation is ONE subagent, Sonnet 5, high effort.** No waves. **No
-   scoring table** — replace it with a **one-line complexity read** (mini-ok?
-   or recommend switching to full); log that line, never render the matrix.
-3. **No dispatch-style and no batch-pause questions** — a single subagent
-   makes both meaningless; never ask them.
-4. **Lighter intake.** Ask only the **Always + medium tier** (Q1–Q4 in
-   `../_shared/phases/intake.md`); skip the high tier (Q5/Q6). Run the Step
-   3.5 repo cross-check at NAMES-ONLY depth (Glob/Grep-confirm what the draft
-   names, tag the rest `UNVERIFIED`, resolve tags in the sign-off line; >3
-   tags → recommend the full flow or `orc-analyze`). Sign-off **defaults to
-   SOFT**, not GATE.
-5. **Still write tests** if the project has a test setup (the executor
-   creates/updates them in its task).
-6. **Everything else is identical:** run folder + intent-spec, planning,
-   checkpoint/state-of-play, stop sequence, usage reminder, ship flow.
-
-## Mini flow (the phase set)
-
-```
-Phase 0  intake (Q1–Q4, soft sign-off) + run folder + intent-spec
-Phase 1  planning (dispatch orc-planner-mini; analyst first only on real docs)
-         → one-line complexity read (mini-ok? or recommend switch-to-full)
-Phase 3  dispatch ONE executor (orc-executor-sonnet-5-high) — slice carries
-         the standing `house_rules` card (../_shared/phases/house-rules.md,
-         injected literally) + the cached `postgres` pattern on a data-access
-         task (cache HIT only) — collect + validate return
-Phase M  SMOKE GATE — run build+test → GREEN proceed · RED block ship + surface
-Phase X  MOCK EXAMPLE (config mock_example) — offer/build after a GREEN gate
-Phase T  TEST-AUTHORING ASK (opt-in) — offer to write test cases (never run them)
-Phase 8  ship (commit / push / PR — never stages mock-examples/)
-```
-(No Phase 2 scoring table, no dispatch-style/batch-pause asks, no full
-review/verify/summary.)
-
-**Postgres query grounding.** On a Postgres project, if the task touches the
-data-access layer AND `orc pattern status postgres` reports cached (the
-deterministic probe in `../_shared/detecting-artifacts.md`, never an ad-hoc
-`find` for `.claude/orc/patterns/postgres-pattern.md`), inject it LITERALLY into
-the slice (conventions + blocking query invariants).
-Cache MISS → skip — mini never codifies (that's the full lane /
-`/orc-pattern`); universal invariants + neighbor imitation still cover it.
-
-**Gotchas (repair memory; config `gotchas`) — mini READS and WRITES.** Probe at
-Phase 1 (`orc gotcha status`, one row, never silent), inject the SCOPE-MATCHING
-entries into the Phase 3 slice (cap 3; zero matches = no block, never
-unfiltered), and append a returned `gotcha_recorded` YOURSELF after the return.
-Trimmed mechanics + `.claude/orc/gotchas.md`: `../_shared/gotchas.md` §10.
-
-## Phase M — Smoke gate (build + test; blocks ship on red)
-
-After the executor return validates (`../_shared/return-validation.md` —
-including `done` with non-empty `unmet[]` = partial, and §6's worktree delta: a path changed outside `declared_files` is a violation whatever the return said), YOU run the smoke gate
-per `../_shared/smoke-gate.md`: read-only build+test. **GREEN** →
-test-authoring ask, then ship. **RED** → never offer commit/ship; one repair
-re-dispatch, second red → STOP and surface. Docs-only → gate N/A, say so.
-`orc run inflight` FIRST — exit 2 REFUSES, because
-`a lane that re-dispatches over a live attempt` has broken the contract
-(`../_shared/return-validation.md` §0).
-
-## Phase X — Mock example + drift recovery (config `mock_example`, default ask)
-
-Canonical: `../_shared/drift-recovery.md` — load it when the phase fires. After
-a GREEN Phase M, before ship: `ask` → MANDATORY offer (never silently
-skipped/run) · `on` → build · `off` → skip. Deliverable
-`mock-examples/<change-slug>/` at project root (EXAMPLE.md + one runnable
-mocked artifact) — **never committed, never staged** (no `.gitignore` edit).
-One question after the user runs it: matches expectation? [yes / drift:
-<describe>]. Drift → `DRIFT-FROM` handoff (gap analysis → patch plan → dispatch
-→ re-gate → re-offer), hard cap 2 loops, then an honest unresolved report.
-Trace: `PHASE mock-example`, `DRIFT loop=<n>`.
-
-## Phase T — Test-authoring ask (opt-in; writes tests, never runs them)
-
-Same opt-in as full Phase 6.5 — mini **only asks** (never gates the ship).
-Default from `config.generate_tests`; at the end of a GREEN run ask: *"Write
-test cases for these changes? (I'll author them — automated files +
-TEST-PLAN.md + a curl bundle for HTTP APIs — but never run them; you test
-manually.)"* Yes → dispatch `orc-test-author-opus-5-med` (subskill
-`../orc/subskills/orc-testgen/`) with the run's `actual_files`,
-definition-of-done, touched flows, constraints, stack; the two manual
-deliverables land in **`test-generator/<change-slug>/` at the project root**.
-Validate the returned `test_plan_path`/`curl_bundle_path` are under that folder
-(else malformed → re-dispatch); relay + state the exact path (committed on ship,
-not gitignored). No → ship. Either way this NEVER runs tests.
-
-## Behavior trace (always on)
-
-`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
-the file and the layers). Lane token `mini`, tier **Build lanes** —
-per phase, batched to **3 packets** (intake+plan · execution · ship), each
-paired with the next phase's first dispatch.
-At run start write `log_dir/.current` = `run-mini-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
-`touch the trace file` of that name in the SAME step.
-Nothing else about the protocol is restated here; a phase that ends with
-`zero new trace lines is a protocol violation`.
-
-Mini does NOT drop the trace. `OUTCOME … band=mini` per task.
-
-## Complexity read (replaces the scoring table)
-
-ONE judgment before dispatch: is this genuinely mini-sized (single coherent
-area, low interdependency, low blast radius)? State it in one line and log it.
-Complex/high-risk (many interdependencies, core/shared surface,
-security-sensitive) → **recommend switching to full** — let the user choose.
-
-## Fallback intake (arriving from orc-fast)
-
-orc-fast falls back HERE whenever its prerequisites fail — never by stopping
-the chat. Follow the reader side of `../_shared/fallback-handoff.md`: the
-`FALLBACK-FROM` block in the shared run folder names the reason; acknowledge
-it in one line, skip re-deriving whatever is carried, reuse the run folder.
-
-## Switching to full flow mid-run
-
-On "switch to full" (or when the complexity read / a mid-run surprise clearly
-needs review/verify): the run folder, checkpoint, and intent-spec already live
-in the shared `.claude/orc/run/{run-slug}/` format, so the full flow resumes from
-the current checkpoint and adds the phases mini skipped. Record the switch in
-the decision log.
-
-## Dispatch via named agents (canonical name-map — dispatch BY these names)
-
-Models pinned in `.claude/agents/`; look up here, never reconstruct a name (agent = skill-name + model-effort suffix). See `.claude/agents/MODEL-MAPPING.md`. `opus5_only: true` FORCES the right column and needs an Opus 5 main session — mini's cheap-lane premise is off while it is on (`../_shared/opus5-only.md`).
-
-**Extra (`extra_enabled`, `../_shared/extra-dispatch.md`):** mini's ONE executor may run off Claude. It has no score, so resolve the pinned executor's **BAND, both edges, and require them to agree** — a partially covering row keeps the run on Claude and the preflight says so. Print the `extra:` line at intake whenever the gate is on (P0: `a lane that sends work off Claude without saying so`); dispatch via `orc extra dispatch --task <file> --json` with the IDENTICAL slice; validate with `return-validation.md` **§2b, not §2** (⛔ SUBSTITUTION replaces the downgrade check); a failure runs `orc extra reconcile <task_id>` FIRST — a worktree that moved is RESUMED, never re-done — then falls back to the pinned Claude agent, announced. A cited-risk change never leaves Claude (`extra_risk_tasks`, default `off`) — and mini's complexity read is not a substitute for that gate.
-
-| Role | Agent (dispatch this) | Model / effort | When `opus5_only` |
-|------|-----------------------|----------------|-------------------|
-| mini analysis (docs only) | `orc-analyze-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-analyze-mini-opus-5-med` |
-| mini planning | `orc-planner-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-planner-mini-opus-5-med` |
-| mini execution | `orc-executor-sonnet-5-high` | claude-sonnet-5 / high | `orc-executor-opus-5-low` |
-| test authoring (opt-in) | `orc-test-author-opus-5-med` | claude-opus-5 / medium | unchanged |
-
-## Config
-
-**ONE resolver, and it is not you:** `orc lane config orc-mini --json`. Obey
-`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
-`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
-from `.claude/orc.config.yaml` — a key this lane does not read is not in the
-answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
-the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
-documented defaults, out loud. Priorities and families:
-`../_shared/config-precedence.md`.
-
-Wave/scoring/scout keys never apply to mini — and they are not in the answer,
-so there is nothing to render or ask.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-mini --json` is the ONLY assembler; never build
-the card here. It rides under the house rules and above the task —
-**house rules > your project's rules > ORC's own packs** — and its `line` prints
-VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
-never a silent choice) and `rules_overridden[]`.
-## Calls
-
-**ONE catalogue, and it is not you:** `orc lane calls orc-mini --json` names every
-CLI call this lane makes, each with its exit-code contract, its cost, when to run
-it, and what an EMPTY answer means. Never invent a spelling, never re-word an
-exit code, and never re-derive a state word — the CLI's state words are the only
-state words, and **an exit code is an ANSWER wherever that contract says so, not
-a failure**. A call the answer does not name is a call this lane does not make.
-Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
-
-## TDD (ONE intake question — mini's whole TDD policy)
-
-At intake ask once:
-*"Anchor this in plan-time acceptance tests (TDD — red tests first, implement
-to green)? [yes/no]"*. Yes → the planner slice carries `tdd: on` (the mini
-planner authors `tdd_spec` per requirement, **scoped by the same `disposition` set the full lane uses** — `new-surface | behavior-change | covered-by-existing | no-behavior | no-runner`, derived from the `facets`, same safety floor: a cited `risk[]` is never scoped out, so a constant or a translation string gets no test but an auth change always does). Mini keeps its SINGLE executor — no paired TDD task; that executor materializes the failing tests FIRST, then implements to green
-(implement→test→repair, cap `tdd_loop_max`; emit `TDD-RED`/`TDD-GREEN` per
-iteration; cap hit → STOP + honest red report), and Phase M's smoke gate runs
-the TDD suite as part of build+test. Scoped-out requirements are named with their
-reason at preflight — never silent. No → skip entirely; never re-ask.
-
-## Analyst & planner (mini lane)
-
-orc-mini dispatches the FAST variants (Sonnet 5 high): `orc-analyze-mini` and
-`orc-planner-mini` — same artifacts and output contracts as full, trimmed
-depth. The mini analyst is **doc-optional**: on real doc input it runs first,
-then the mini planner; on a merely ambiguous request, prefer one inline
-clarifying question over a cold analyst spawn. Always single-pass — **no deep
-mode, no scouts**; it escalates to `/orc-analyze` deep on its concrete
-thresholds and the user chooses. You never analyze or plan yourself.
-
-**Mini-lane gates (yours, deterministic — same as full; full detail in
-`../_shared/phases/analyst-gates.md`; emit `GATE` trace lines).** On
-mini-analyst return: evidence spot-check + derivation lint; refuse
-take-into-build on open `UNVERIFIED`/missing `scope_closed`; `git_head` ≠
-HEAD at plan time → re-run the spot-check first. On mini-planner return: Glob
-every `disposition: exists` path, recompute coverage (no orphan
-requirements), cycle + collision checks. Any miss → bounce (one retry, then
-escalate). At dispatch, append the task's `spec_invariants` to the slice's
-`constraints[]` verbatim.
-
-## Wiki consult (if present)
-
-Same rule as the full skill — load `../_shared/phases/wiki-consult.md` at the
-planning/complexity-read step: compute the FRESH / AGING / STALE tier from
-`.claude/orc/wiki-meta.json`, pull the relevant pages (incl. cross-cutting
-maps like `orc-reference-api-surface` when their domain applies), apply
-`code > fresh wiki > stale wiki (hints) > model priors`, and **emit
-`WIKI-CONSULT <tier> :: docs=<pages pulled>`**. Crosslink: a task touching a
-boundary in `.claude/orc/crosslink/needs.json` gets the cached contract
-injected per that reference — advisory, never blocking. Mini never generates
-the wiki; after a code-changing run apply the passive stale-flag note only
-(the post-ship refresh ASK is full-lane/ultra behavior).
-
-## Shared artifacts
-
-Writes to the SAME location as the full skill
-(`.claude/orc/run/{run-slug}/`) — a switch needs no migration.
-
-## What mini still enforces (from the main hard rules)
-
-Never implement yourself (the smoke gate is read-only, not implementation) ·
-all RUN-STATE artifacts in the run subfolder, never project root (the one
-exception is the opt-in `test-generator/<change-slug>/` self-QA deliverable,
-which lands at the project root by design) · validate every
-subagent return (malformed = failure) · report the dispatch log + remind the
-user to run `/usage` (never invoke it programmatically) · **never offer commit
-on a red build** (enforced by Phase M).
-
-## Waiting mid-run (`/orc-wait`)
-
-Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
-Checkpoint **full** · safe point **after the executor returns**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+---
+name: orc-mini
+description: >
+  Lightweight ORC for fast implementation. Use for
+  "use orc-mini to implement X" or "/orc-mini". Same
+  intake → intent-spec → planning → dispatch → smoke-gate → ship spine as the full
+  orchestrator, but SKIPS full code review, verification, and the summary phase.
+  Dispatches ONE Sonnet 5 high-effort subagent for implementation, then runs a
+  build+test smoke gate (blocks ship on red) and offers opt-in test authoring.
+  Switchable to full flow mid-run. The orchestrator never implements — it spawns.
+---
+
+# ORC-MINI
+
+A trimmed orchestrator for when you want speed over the full quality pipeline.
+Everything in the main spine (`../orc/SKILL.md`) applies EXCEPT the
+differences below. Load the main skill's references and schemas by path — the
+HOT-PATH essentials (dispatch names, return-contract fields, artifact path)
+are inlined here so nothing is reconstructed from "full minus deltas."
+
+Run as **Opus 4.8 high**, or Opus 5 / Fable 5 at medium+ (as full; never downgrade).
+**You never implement — you spawn.** The one exception is the **smoke gate**:
+a read-only build+test run, not implementation — you still never write code.
+
+**Worked example** (orient only — never execute from it): `examples/mini-run-mock.md`.
+
+## Differences from the full orchestrator
+
+1. **Skip full Phase 5 (Review), Phase 6 (Verify), and Phase 7 (Summary).**
+   Instead: the **smoke gate** after execution, then the opt-in
+   **test-authoring ask**, then ship.
+2. **Implementation is ONE subagent, Sonnet 5, high effort.** No waves. **No
+   scoring table** — replace it with a **one-line complexity read** (mini-ok?
+   or recommend switching to full); log that line, never render the matrix.
+3. **No dispatch-style and no batch-pause questions** — a single subagent
+   makes both meaningless; never ask them.
+4. **Lighter intake.** Ask only the **Always + medium tier** (Q1–Q4 in
+   `../_shared/phases/intake.md`); skip the high tier (Q5/Q6). Run the Step
+   3.5 repo cross-check at NAMES-ONLY depth (Glob/Grep-confirm what the draft
+   names, tag the rest `UNVERIFIED`, resolve tags in the sign-off line; >3
+   tags → recommend the full flow or `orc-analyze`). Sign-off **defaults to
+   SOFT**, not GATE.
+5. **Still write tests** if the project has a test setup (the executor
+   creates/updates them in its task).
+6. **Everything else is identical:** run folder + intent-spec, planning,
+   checkpoint/state-of-play, stop sequence, usage reminder, ship flow.
+
+## Mini flow (the phase set)
+
+```
+Phase 0  intake (Q1–Q4, soft sign-off) + run folder + intent-spec
+Phase 1  planning (dispatch orc-planner-mini; analyst first only on real docs)
+         → one-line complexity read (mini-ok? or recommend switch-to-full)
+Phase 3  dispatch ONE executor (orc-executor-sonnet-5-high) — slice carries
+         the standing `house_rules` card (../_shared/phases/house-rules.md, literal)
+         + the `rules_card` under it (`orc rules slice` → `text`, verbatim) + the
+         cached `postgres` pattern on a data-access task (cache HIT only) + `orc graph ctx` cards when the graph is on — collect + validate return
+Phase M  SMOKE GATE — run build+test → GREEN proceed · RED block ship + surface
+Phase X  MOCK EXAMPLE (config mock_example) — offer/build after a GREEN gate
+Phase T  TEST-AUTHORING ASK (opt-in) — offer to write test cases (never run them)
+Phase 8  ship (commit / push / PR — never stages mock-examples/)
+```
+(No Phase 2 scoring table, no dispatch-style/batch-pause asks, no full
+review/verify/summary.)
+
+**Postgres query grounding.** On a Postgres project, if the task touches the
+data-access layer AND `orc pattern status postgres` reports cached (the
+deterministic probe in `../_shared/detecting-artifacts.md`, never an ad-hoc
+`find` for `.claude/orc/patterns/postgres-pattern.md`), inject it LITERALLY into
+the slice (conventions + blocking query invariants).
+Cache MISS → skip — mini never codifies (that's the full lane /
+`/orc-pattern`); universal invariants + neighbor imitation still cover it.
+
+**Gotchas (repair memory; config `gotchas`) — mini READS and WRITES.** Probe at
+Phase 1 (`orc gotcha status`, one row, never silent), inject the SCOPE-MATCHING
+entries into the Phase 3 slice (cap 3; zero matches = no block, never
+unfiltered), and append a returned `gotcha_recorded` YOURSELF after the return.
+Trimmed mechanics + `.claude/orc/gotchas.md`: `../_shared/gotchas.md` §10.
+
+## Code graph cache — consult, build, use, update (`../_shared/code-graph.md` §0)
+
+Never skipped. Every call carries `--if-enabled`: exit 3 = off → print `graph: off` once, make no other graph call.
+Print each JSON `line` in chat; put each `trace` in the next packet VERBATIM.
+1. **Preflight, with the probes, before the planner:** `orc graph status --if-enabled --heal --json` — it builds or updates the cache itself.
+2. **Phase 3 slice:** ONE `orc graph ctx <declared_files> --if-enabled --json` → its `card` is the `graph` block; the return carries `graph_used`.
+3. **Phase M GREEN:** `orc graph update --if-enabled --json`, then one `orc graph notes pending` batch (§6) — the next run starts from this cache.
+
+## Phase M — Smoke gate (build + test; blocks ship on red)
+
+After the executor return validates (`../_shared/return-validation.md` —
+including `done` with non-empty `unmet[]` = partial, and §6's worktree delta: a path changed outside `declared_files` is a violation whatever the return said), YOU run the smoke gate
+per `../_shared/smoke-gate.md`: read-only build+test. **GREEN** → code-graph step 3 (above) →
+test-authoring ask, then ship. **RED** → never offer commit/ship; one repair
+re-dispatch, second red → STOP and surface. Docs-only → gate N/A, say so.
+`orc run inflight` FIRST — exit 2 REFUSES, because
+`a lane that re-dispatches over a live attempt` has broken the contract
+(`../_shared/return-validation.md` §0).
+
+## Phase X — Mock example + drift recovery (config `mock_example`, default ask)
+
+Canonical: `../_shared/drift-recovery.md` — load it when the phase fires. After
+a GREEN Phase M, before ship: `ask` → MANDATORY offer (never silently
+skipped/run) · `on` → build · `off` → skip. Deliverable
+`mock-examples/<change-slug>/` at project root (EXAMPLE.md + one runnable
+mocked artifact) — **never committed, never staged** (no `.gitignore` edit).
+One question after the user runs it: matches expectation? [yes / drift:
+<describe>]. Drift → `DRIFT-FROM` handoff (gap analysis → patch plan → dispatch
+→ re-gate → re-offer), hard cap 2 loops, then an honest unresolved report.
+Trace: `PHASE mock-example`, `DRIFT loop=<n>`.
+
+## Phase T — Test-authoring ask (opt-in; writes tests, never runs them)
+
+Same opt-in as full Phase 6.5 — mini **only asks** (never gates the ship).
+Default from `config.generate_tests`; at the end of a GREEN run ask: *"Write
+test cases for these changes? (I'll author them — automated files +
+TEST-PLAN.md + a curl bundle for HTTP APIs — but never run them; you test
+manually.)"* Yes → dispatch `orc-test-author-opus-5-med` (subskill
+`../orc/subskills/orc-testgen/`) with the run's `actual_files`,
+definition-of-done, touched flows, constraints, stack; the two manual
+deliverables land in **`test-generator/<change-slug>/` at the project root**.
+Validate the returned `test_plan_path`/`curl_bundle_path` are under that folder
+(else malformed → re-dispatch); relay + state the exact path (committed on ship,
+not gitignored). No → ship. Either way this NEVER runs tests.
+
+## Behavior trace (always on)
+
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
+the file and the layers). Lane token `mini`, tier **Build lanes** —
+per phase, batched to **3 packets** (intake+plan · execution · ship), each
+paired with the next phase's first dispatch.
+At run start write `log_dir/.current` = `run-mini-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
+`touch the trace file` of that name in the SAME step.
+Nothing else about the protocol is restated here; a phase that ends with
+`zero new trace lines is a protocol violation`.
+
+Mini does NOT drop the trace. `OUTCOME … band=mini` per task.
+
+## Complexity read (replaces the scoring table)
+
+ONE judgment before dispatch: is this genuinely mini-sized (single coherent
+area, low interdependency, low blast radius)? State it in one line and log it.
+Complex/high-risk (many interdependencies, core/shared surface,
+security-sensitive) → **recommend switching to full** — let the user choose.
+
+## Fallback intake (arriving from orc-fast)
+
+orc-fast falls back HERE whenever its prerequisites fail — never by stopping
+the chat. Follow the reader side of `../_shared/fallback-handoff.md`: the
+`FALLBACK-FROM` block in the shared run folder names the reason; acknowledge
+it in one line, skip re-deriving whatever is carried, reuse the run folder.
+
+## Switching to full flow mid-run
+
+On "switch to full" (or when the complexity read / a mid-run surprise clearly
+needs review/verify): the run folder, checkpoint, and intent-spec already live
+in the shared `.claude/orc/run/{run-slug}/` format, so the full flow resumes from
+the current checkpoint and adds the phases mini skipped. Record the switch in
+the decision log.
+
+## Dispatch via named agents (canonical name-map — dispatch BY these names)
+
+Models pinned in `.claude/agents/`; look up here, never reconstruct a name (agent = skill-name + model-effort suffix). See `.claude/agents/MODEL-MAPPING.md`. `opus5_only: true` FORCES the right column and needs an Opus 5 main session — mini's cheap-lane premise is off while it is on (`../_shared/opus5-only.md`).
+
+**Extra (`extra_enabled`, `../_shared/extra-dispatch.md`):** mini's ONE executor may run off Claude. It has no score, so resolve the pinned executor's **BAND, both edges, and require them to agree** — a partially covering row keeps the run on Claude and the preflight says so. Print the `extra:` line at intake whenever the gate is on (P0: `a lane that sends work off Claude without saying so`); dispatch via `orc extra dispatch --task <file> --json` with the IDENTICAL slice; validate with `return-validation.md` **§2b, not §2** (⛔ SUBSTITUTION replaces the downgrade check); a failure runs `orc extra reconcile <task_id>` FIRST — a worktree that moved is RESUMED, never re-done — then falls back to the pinned Claude agent, announced. A cited-risk change never leaves Claude (`extra_risk_tasks`, default `off`) — and mini's complexity read is not a substitute for that gate.
+
+| Role | Agent (dispatch this) | Model / effort | When `opus5_only` |
+|------|-----------------------|----------------|-------------------|
+| mini analysis (docs only) | `orc-analyze-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-analyze-mini-opus-5-med` |
+| mini planning | `orc-planner-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-planner-mini-opus-5-med` |
+| mini execution | `orc-executor-sonnet-5-high` | claude-sonnet-5 / high | `orc-executor-opus-5-low` |
+| test authoring (opt-in) | `orc-test-author-opus-5-med` | claude-opus-5 / medium | unchanged |
+
+## Config
+
+**ONE resolver, and it is not you:** `orc lane config orc-mini --json`. Obey
+`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
+`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
+from `.claude/orc.config.yaml` — a key this lane does not read is not in the
+answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
+the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
+documented defaults, out loud. Priorities and families:
+`../_shared/config-precedence.md`.
+
+Wave/scoring/scout keys never apply to mini — and they are not in the answer,
+so there is nothing to render or ask.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-mini --json` is the ONLY assembler; never build
+the card here. It rides under the house rules and above the task —
+**house rules > your project's rules > ORC's own packs** — and its `line` prints
+VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
+never a silent choice) and `rules_overridden[]`.
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-mini --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+state words, and **an exit code is an ANSWER wherever that contract says so, not
+a failure**. A call the answer does not name is a call this lane does not make.
+Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
+command you are about to run, out loud, before running it.
+
+## TDD (ONE intake question — mini's whole TDD policy)
+
+At intake ask once:
+*"Anchor this in plan-time acceptance tests (TDD — red tests first, implement
+to green)? [yes/no]"*. Yes → the planner slice carries `tdd: on` (the mini
+planner authors `tdd_spec` per requirement, **scoped by the same `disposition` set the full lane uses** — `new-surface | behavior-change | covered-by-existing | no-behavior | no-runner`, derived from the `facets`, same safety floor: a cited `risk[]` is never scoped out, so a constant or a translation string gets no test but an auth change always does). Mini keeps its SINGLE executor — no paired TDD task; that executor materializes the failing tests FIRST, then implements to green
+(implement→test→repair, cap `tdd_loop_max`; emit `TDD-RED`/`TDD-GREEN` per
+iteration; cap hit → STOP + honest red report), and Phase M's smoke gate runs
+the TDD suite as part of build+test. Scoped-out requirements are named with their
+reason at preflight — never silent. No → skip entirely; never re-ask.
+
+## Analyst & planner (mini lane)
+
+orc-mini dispatches the FAST variants (Sonnet 5 high): `orc-analyze-mini` and
+`orc-planner-mini` — same artifacts and output contracts as full, trimmed
+depth. The mini analyst is **doc-optional**: on real doc input it runs first,
+then the mini planner; on a merely ambiguous request, prefer one inline
+clarifying question over a cold analyst spawn. Always single-pass — **no deep
+mode, no scouts**; it escalates to `/orc-analyze` deep on its concrete
+thresholds and the user chooses. You never analyze or plan yourself.
+
+**Mini-lane gates (yours, deterministic — same as full; full detail in
+`../_shared/phases/analyst-gates.md`; emit `GATE` trace lines).** On
+mini-analyst return: evidence spot-check + derivation lint; refuse
+take-into-build on open `UNVERIFIED`/missing `scope_closed`; `git_head` ≠
+HEAD at plan time → re-run the spot-check first. On mini-planner return: Glob
+every `disposition: exists` path, recompute coverage (no orphan
+requirements), cycle + collision checks. Any miss → bounce (one retry, then
+escalate). At dispatch, append the task's `spec_invariants` to the slice's
+`constraints[]` verbatim.
+
+## Wiki consult (if present)
+
+Same rule as the full skill — load `../_shared/phases/wiki-consult.md` at the
+planning/complexity-read step: compute the FRESH / AGING / STALE tier from
+`.claude/orc/wiki-meta.json`, pull the relevant pages (incl. cross-cutting
+maps like `orc-reference-api-surface` when their domain applies), apply
+`code > fresh wiki > stale wiki (hints) > model priors`, and **emit
+`WIKI-CONSULT <tier> :: docs=<pages pulled>`**. Crosslink: a task touching a
+boundary in `.claude/orc/crosslink/needs.json` gets the cached contract
+injected per that reference — advisory, never blocking. Mini never generates
+the wiki; after a code-changing run apply the passive stale-flag note only
+(the post-ship refresh ASK is full-lane/ultra behavior).
+
+## Shared artifacts
+
+Writes to the SAME location as the full skill
+(`.claude/orc/run/{run-slug}/`) — a switch needs no migration.
+
+## What mini still enforces (from the main hard rules)
+
+Never implement yourself (the smoke gate is read-only, not implementation) ·
+all RUN-STATE artifacts in the run subfolder, never project root (the one
+exception is the opt-in `test-generator/<change-slug>/` self-QA deliverable,
+which lands at the project root by design) · validate every
+subagent return (malformed = failure) · report the dispatch log + remind the
+user to run `/usage` (never invoke it programmatically) · **never offer commit
+on a red build** (enforced by Phase M).
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **full** · safe point **after the executor returns**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.