@azure-id/orc 0.56.1 → 1.1.0

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

@@ -1,156 +1,181 @@
----
-name: orc-learn
-description: >
-  Per-feature onboarding docs for the LOCAL project. Use for "/orc-learn",
-  "help me learn feature X", "onboard me to this feature", or "orc-learn
-  refresh". Runs INDEPENDENTLY — no orchestrator, no run folder. Picks one
-  feature (wiki topics first), then generates learning-docs/<feature>/ with
-  learning.md (pedagogy: mental model, walkthrough, recipes, FAQ) and
-  knowledge.md (reference: file:line-anchored functions & flow, contracts,
-  fingerprints). Output is LOCAL and git-ignored — each dev regenerates their
-  own. Refresh lists every generated feature with a computed freshness flag
-  and regenerates only what the user picks. The skill dispatches the pinned
-  orc-learn-writer-opus-5-low agent — it never writes the docs itself.
----
-
-# ORC-LEARN (standalone)
-
-Teach a developer ONE feature of the local repo well enough to safely extend
-it — the human-onboarding lane. It is NOT the wiki: the wiki grounds the
-*pipeline* (repo-wide, contract-level); orc-learn goes one level deeper for a
-*person* — function-level, full-flow, pedagogical. Target is always
-`<repo root>/learning-docs/<feature-slug>/` (git-ignored, local per dev).
-
-**Dispatch, don't do.** Whatever model this chat runs on, the skill only picks
-the topic/mode and spawns `orc-learn-writer-opus-5-low` (the pinned
-engine) — the deepening scan + all writes run at Opus 5 low regardless of
-the caller's tier. The skill's only self-writes are the behavior-trace
-markers around the spawn. Interactivity is DELIBERATELY minimal but non-zero
-(unlike orc-claude): exactly one question per mode — "which feature?" (INIT)
-or "which to refresh?" (REFRESH). Never more.
-
-**Grounding precedence** (constellation rule, unchanged):
-`code > fresh wiki > stale wiki (hints) > model priors`. The writer re-verifies
-every wiki claim it uses against the code; on conflict the code wins.
-
-**Worked example** (orient only — never execute from it):
-`examples/learn-run-mock.md`.
-
-## The two modes (auto-selected by argument)
-
-1. **INIT** (default: `/orc-learn`, optional `focus=<hint>`) — pick ONE
-   feature, generate `learning-docs/<slug>/learning.md` + `knowledge.md`,
-   derive `learning-docs/INDEX.md`.
-2. **REFRESH** (`/orc-learn refresh`) — list every generated feature with a
-   computed freshness flag; regenerate only the ones the user picks.
-   Protocol: `references/refresh.md`.
-
-Not inside a git repo / no project root findable → say so and stop.
-
-## Mode A — INIT
-
-Behavior-trace logging is permanent (always on). Resolve `log_dir`
-(`../orc/config.md` default + `.claude/orc.config.yaml`) at start and follow
-`../orc/references/trace-protocol.md`; the marker set is in "Behavior trace"
-below. Weave the **Trace:** steps in as each event happens.
-
-1. **Topic pick (wiki-first).** Read `wiki/INDEX.md` +
-   `.claude/orc/wiki-meta.json` and compute the freshness tier
-   (`../orc-wiki/references/staleness.md` — computed on read, never stored).
-   **Trace:** `WIKI-CONSULT tier=<FRESH|AGING|STALE|none> :: topic-pick`
-   (emitted even when the wiki is absent, with `none`).
-   - Wiki FRESH/AGING → present its feature areas as a pick-list; the chosen
-     area's `covers` globs seed the writer's file set.
-   - No wiki / STALE / topic not covered → ask the user to point at the
-     feature (a directory or a `focus=` hint); the writer will do a
-     **targeted** scan of just those files — never repo-wide. A stale wiki
-     doc may still ride along as hints (precedence above).
-   - Ask which feature as ONE question (one feature per invoke). Derive
-     `feature_slug` (kebab-case) from the chosen topic/area.
-2. **Trace:** write `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt` and
-   `touch the trace file` of that name in the SAME step, BEFORE the spawn (a
-   pointer to a missing file reads as dangling and the hook rotates away).
-3. Spawn `orc-learn-writer-opus-5-low` with: `mode=init`, `repo_root`,
-   `feature_slug`, `topic_area`, `covers[]` (from wiki or user pointer),
-   `wiki_tier`, `focus_hint|null`, and the paths to
-   `references/deepen.md`, `references/template-learning.md`,
-   `references/template-knowledge.md`. **Trace:**
-   `DISPATCH orc-learn-writer :: init <slug> expect=opus-5/low` just
-   before the spawn (the hook adds `SPAWN`/`RETURN` on its own).
-4. On return, check `actual_model`/`actual_effort` against the pinned tier —
-   mismatch → prepend a tier-downgrade warning to the report. **Trace:**
-   `VERIFY writer actual=<model>/<effort> ✅ MATCH` (or
-   `⛔ DOWNGRADE expected=opus-5/low`).
-5. Relay the writer's report verbatim. If `learning-docs/` is not in
-   `.gitignore`, offer the line (`learning-docs/`) — append only on an
-   explicit yes; never edit silently. **Trace:** `FINISH :: init <slug>`,
-   then delete `log_dir/.current`. Stop. The skill NEVER writes the docs
-   itself — not even a "trivial" INDEX touch.
-
-## Mode B — REFRESH
-
-1. No `learning-docs/` (or no feature folders inside) → "nothing generated
-   yet; run `/orc-learn` first." Stop — no trace run needed.
-2. Read every `learning-docs/<feature>/knowledge.md` fingerprint header
-   (`source_commit` + per-file hashes) and compute FRESH/AGING/STALE per
-   feature — `references/refresh.md`. Freshness is computed on read, never
-   stored as a status.
-3. Present the FULL list, each with its computed flag; the user
-   multi-selects which to regenerate (one question, multi-select). Nothing
-   selected → stop, no writes.
-4. **Trace:** write `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt`. For each
-   selected feature, spawn the writer with `mode=refresh` and that feature's
-   slice (re-deepen just that feature; a FRESH/AGING wiki may again seed the
-   boundary — emit one `WIKI-CONSULT tier=<tier> :: refresh` when the wiki is
-   read). One `DISPATCH`/`VERIFY` pair per feature, same markers as INIT.
-5. The (last) writer re-derives `learning-docs/INDEX.md` from all current
-   feature headers. Relay the combined report. **Trace:**
-   `FINISH :: refresh <n> features`, then delete `log_dir/.current`.
-
-## Behavior trace (PERMANENT — minimal dispatch-lane protocol; always on)
-
-orc-learn owns the trace for its run like every trace-owning lane, but it is
-a dispatch-only lane: it emits ONLY markers it can truthfully witness — no
-phase/score/finding/verdict markers (deepening and writing happen inside the
-writer, which self-traces nothing and only returns `actual_model`/
-`actual_effort`). The marker set, in order (actor `orc`, plus the hook's
-`SPAWN`/`RETURN`):
-
-1. `WIKI-CONSULT tier=<tier> :: <topic-pick|refresh>` — at every wiki read
-   (orc-learn is a wiki-grounding lane; the consult is always traced, absent
-   wiki included).
-2. `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt` — before the first spawn.
-3. `DISPATCH orc-learn-writer :: <mode> <slug> expect=opus-5/low` — one
-   per spawn; REFRESH runs one per selected feature.
-4. `VERIFY writer actual=<model>/<effort> ✅ MATCH` or
-   `⛔ DOWNGRADE expected=opus-5/low` — from the returned
-   `actual_model`/`actual_effort` (this lane's honesty signal for
-   `/orc-retro`).
-5. `FINISH :: <init <slug>|refresh <n> features>`, then delete `.current`.
-
-Narration is **dispatched, never remembered**: record each marker with its REAL
-timestamp as its event happens, then — as a single-dispatch lane — dispatch the
-trace writer ONCE with the whole event list plus `decisions` (the WHY: which
-feature was picked and why, the user's answer verbatim) after the writer return
-validates and BEFORE you delete `.current`. Stamps are the run's timeline, never
-the write time, and a run that
-ends with zero new trace lines is a protocol violation.
-
-## Boundaries
-
-- **Writes ONLY** under `learning-docs/` (via the writer) and, on an explicit
-  yes, one `.gitignore` line. Never edits source code, never commits, never
-  pushes.
-- **One question per mode, ever.** Which feature (INIT); which to refresh
-  (REFRESH). Everything else is decided or reported, never asked.
-- `learning-docs/` is LOCAL — git-ignored, regenerated per dev, never a
-  committed shared artifact. A stale copy costs one regeneration, nothing
-  more.
-- `INDEX.md` is DERIVED by the writer from the feature headers in the same
-  dispatch — never hand-maintained, never edited by the skill.
-- The wiki is consumed read-only as a boundary source; orc-learn never
-  writes wiki files, never triggers a wiki scan, never treats "not in the
-  wiki" as a blocker (it falls back to a targeted scan of user-pointed
-  files).
-- Reminder: to see usage limits, tell the user to run `/usage` (never invoke
-  it programmatically).
+---
+name: orc-learn
+description: >
+  Per-feature onboarding docs for the LOCAL project. Use for "/orc-learn",
+  "help me learn feature X", "onboard me to this feature", or "orc-learn
+  refresh". Runs INDEPENDENTLY — no orchestrator, no run folder. Picks one
+  feature (wiki topics first), then generates learning-docs/<feature>/ with
+  learning.md (pedagogy: mental model, walkthrough, recipes, FAQ) and
+  knowledge.md (reference: file:line-anchored functions & flow, contracts,
+  fingerprints). Output is LOCAL and git-ignored — each dev regenerates their
+  own. Refresh lists every generated feature with a computed freshness flag
+  and regenerates only what the user picks. The skill dispatches the pinned
+  orc-learn-writer-opus-5-low agent — it never writes the docs itself.
+---
+
+# ORC-LEARN (standalone)
+
+Teach a developer ONE feature of the local repo well enough to safely extend
+it — the human-onboarding lane. It is NOT the wiki: the wiki grounds the
+*pipeline* (repo-wide, contract-level); orc-learn goes one level deeper for a
+*person* — function-level, full-flow, pedagogical. Target is always
+`<repo root>/learning-docs/<feature-slug>/` (git-ignored, local per dev).
+
+**Dispatch, don't do.** Whatever model this chat runs on, the skill only picks
+the topic/mode and spawns `orc-learn-writer-opus-5-low` (the pinned
+engine) — the deepening scan + all writes run at Opus 5 low regardless of
+the caller's tier. The skill's only self-writes are the behavior-trace
+markers around the spawn. Interactivity is DELIBERATELY minimal but non-zero
+(unlike orc-claude): exactly one question per mode — "which feature?" (INIT)
+or "which to refresh?" (REFRESH). Never more.
+
+**Grounding precedence** (constellation rule, unchanged):
+`code > fresh wiki > stale wiki (hints) > model priors`. The writer re-verifies
+every wiki claim it uses against the code; on conflict the code wins.
+
+**Worked example** (orient only — never execute from it):
+`examples/learn-run-mock.md`.
+
+## The two modes (auto-selected by argument)
+
+1. **INIT** (default: `/orc-learn`, optional `focus=<hint>`) — pick ONE
+   feature, generate `learning-docs/<slug>/learning.md` + `knowledge.md`,
+   derive `learning-docs/INDEX.md`.
+2. **REFRESH** (`/orc-learn refresh`) — list every generated feature with a
+   computed freshness flag; regenerate only the ones the user picks.
+   Protocol: `references/refresh.md`.
+
+Not inside a git repo / no project root findable → say so and stop.
+
+## Phases
+
+`orc lane phases orc-learn --json` is this lane's pipeline: the ordered list, where
+each phase lives, and how much of it to read. **The CLI owns the order** — never
+derive it from the headings below, and never renumber or rename one without the
+manifest, because a `read: section` pointer names a HEADING and a renamed heading
+is a pointer into nothing.
+
+## Mode A — INIT
+
+Behavior-trace logging is permanent (always on). Resolve `log_dir`
+(`../orc/config.md` default + `.claude/orc.config.yaml`) at start and follow
+`../_shared/phases/trace.md`; the marker set is in "Behavior trace"
+below. Weave the **Trace:** steps in as each event happens.
+
+1. **Topic pick (wiki-first).** Read `wiki/INDEX.md` +
+   `.claude/orc/wiki-meta.json` and compute the freshness tier
+   (`../orc-wiki/references/staleness.md` — computed on read, never stored).
+   **Trace:** `WIKI-CONSULT tier=<FRESH|AGING|STALE|none> :: topic-pick`
+   (emitted even when the wiki is absent, with `none`).
+   - Wiki FRESH/AGING → present its feature areas as a pick-list; the chosen
+     area's `covers` globs seed the writer's file set.
+   - No wiki / STALE / topic not covered → ask the user to point at the
+     feature (a directory or a `focus=` hint); the writer will do a
+     **targeted** scan of just those files — never repo-wide. A stale wiki
+     doc may still ride along as hints (precedence above).
+   - Ask which feature as ONE question (one feature per invoke). Derive
+     `feature_slug` (kebab-case) from the chosen topic/area.
+2. **Trace:** write `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt` and
+   `touch the trace file` of that name in the SAME step, BEFORE the spawn (a
+   pointer to a missing file reads as dangling and the hook rotates away).
+3. Spawn `orc-learn-writer-opus-5-low` with: `mode=init`, `repo_root`,
+   `feature_slug`, `topic_area`, `covers[]` (from wiki or user pointer),
+   `wiki_tier`, `focus_hint|null`, and the paths to
+   `references/deepen.md`, `references/template-learning.md`,
+   `references/template-knowledge.md`. **Trace:**
+   `DISPATCH orc-learn-writer :: init <slug> expect=opus-5/low` just
+   before the spawn (the hook adds `SPAWN`/`RETURN` on its own).
+4. On return, check `actual_model`/`actual_effort` against the pinned tier —
+   mismatch → prepend a tier-downgrade warning to the report. **Trace:**
+   `VERIFY writer actual=<model>/<effort> ✅ MATCH` (or
+   `⛔ DOWNGRADE expected=opus-5/low`).
+5. Relay the writer's report verbatim. If `learning-docs/` is not in
+   `.gitignore`, offer the line (`learning-docs/`) — append only on an
+   explicit yes; never edit silently. **Trace:** `FINISH :: init <slug>`,
+   then delete `log_dir/.current`. Stop. The skill NEVER writes the docs
+   itself — not even a "trivial" INDEX touch.
+
+## Mode B — REFRESH
+
+1. No `learning-docs/` (or no feature folders inside) → "nothing generated
+   yet; run `/orc-learn` first." Stop — no trace run needed.
+2. Read every `learning-docs/<feature>/knowledge.md` fingerprint header
+   (`source_commit` + per-file hashes) and compute FRESH/AGING/STALE per
+   feature — `references/refresh.md`. Freshness is computed on read, never
+   stored as a status.
+3. Present the FULL list, each with its computed flag; the user
+   multi-selects which to regenerate (one question, multi-select). Nothing
+   selected → stop, no writes.
+4. **Trace:** write `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt`. For each
+   selected feature, spawn the writer with `mode=refresh` and that feature's
+   slice (re-deepen just that feature; a FRESH/AGING wiki may again seed the
+   boundary — emit one `WIKI-CONSULT tier=<tier> :: refresh` when the wiki is
+   read). One `DISPATCH`/`VERIFY` pair per feature, same markers as INIT.
+5. The (last) writer re-derives `learning-docs/INDEX.md` from all current
+   feature headers. Relay the combined report. **Trace:**
+   `FINISH :: refresh <n> features`, then delete `log_dir/.current`.
+
+## Behavior trace (always on)
+
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
+the file and the layers). Lane token `learn`, tier **Single-dispatch** —
+exactly ONE end-of-run packet, dispatched solo after the writer return
+validates and BEFORE `.current` is deleted.
+At run start write `log_dir/.current` = `run-learn-<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`.
+
+Dispatch-only lane: emit ONLY the markers it can truthfully witness — no
+`PHASE`/`SCORE`/`FINDING`/`VERDICT`, because deepening and writing happen
+inside the writer, which self-traces nothing and returns only
+`actual_model`/`actual_effort`. The marker set, in order (actor `orc`, plus the
+hook's `SPAWN`/`RETURN`): `WIKI-CONSULT tier=<tier> :: <topic-pick|refresh>` at
+every wiki read · `DISPATCH orc-learn-writer :: <mode> <slug> expect=opus-5/low`
+per spawn (REFRESH runs one per selected feature) · `VERIFY writer
+actual=<model>/<effort>` · `FINISH :: <init <slug>|refresh <n> features>`.
+`decisions` carries which feature was picked and why, plus the user's answer
+verbatim.
+
+## Boundaries
+
+- **Writes ONLY** under `learning-docs/` (via the writer) and, on an explicit
+  yes, one `.gitignore` line. Never edits source code, never commits, never
+  pushes.
+- **One question per mode, ever.** Which feature (INIT); which to refresh
+  (REFRESH). Everything else is decided or reported, never asked.
+- `learning-docs/` is LOCAL — git-ignored, regenerated per dev, never a
+  committed shared artifact. A stale copy costs one regeneration, nothing
+  more.
+- `INDEX.md` is DERIVED by the writer from the feature headers in the same
+  dispatch — never hand-maintained, never edited by the skill.
+- The wiki is consumed read-only as a boundary source; orc-learn never
+  writes wiki files, never triggers a wiki scan, never treats "not in the
+  wiki" as a blocker (it falls back to a targeted scan of user-pointed
+  files).
+- Reminder: to see usage limits, tell the user to run `/usage` (never invoke
+  it programmatically).
+
+## Config
+
+Resolve with `orc lane config orc-learn --json` and obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
+say so and use `../_shared/config-precedence.md`'s documented defaults, out
+loud. Nothing this lane reads is contested, gated or a stop, so it owes no
+preflight line and has no gate to honour.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-learn --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.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **none** · safe point **single dispatch**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

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

@@ -35,7 +35,7 @@ a read-only build+test run, not implementation — you still never write code.
 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
-   `../orc/references/intake.md`); skip the high tier (Q5/Q6). Run the Step
+   `../_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
@@ -52,7 +52,7 @@ 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 (../orc/references/house-rules.md,
+         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
@@ -111,20 +111,18 @@ 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 (PERMANENT — same rule as full; always on)
-
-Mini does NOT drop the trace. Follow `../orc/references/trace-protocol.md` (load
-at run start): create `log_dir`, write `.current` =
-`run-mini-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
-in the SAME step, store `trace_path`. Narration is
-**dispatched, never remembered**: record each event with its REAL timestamp into
-a packet (`PHASE`, `DISPATCH`, `VERIFY` per return — `actual_model`/
-`actual_effort` vs expected, surface any ⛔ DOWNGRADE — `OUTCOME … band=mini`,
-`VERDICT`, plus `decisions` = the WHY), then dispatch
-`orc-trace-writer-haiku-4-5` PAIRED with the next dispatch; mini batches to
-**3 packets** (intake+plan, execution, ship). A phase with
-zero new trace lines is a protocol violation — dispatch its packet NOW.
-Run end: the `FINISH` packet returns, then delete `log_dir/.current`.
+## 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)
 
@@ -163,12 +161,32 @@ Models pinned in `.claude/agents/`; look up here, never reconstruct a name (agen
 
 ## Config
 
-Resolve at run start: `../orc/config.md` defaults merged with
-`.claude/orc.config.yaml` — read `generate_tests` (the Phase T offer default),
-`mock_example`, `tdd_loop_max`, and `log_dir`. Wave/scoring/scout keys never
-apply to mini — never render or ask them.
+**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.
+
+## 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)
 
-**TDD (ONE intake question — mini's whole TDD policy):** at intake ask once:
+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
@@ -188,7 +206,7 @@ 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
-`../orc/references/analyst-gates.md`; emit `GATE` trace lines).** On
+`../_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
@@ -199,7 +217,7 @@ escalate). At dispatch, append the task's `spec_invariants` to the slice's
 
 ## Wiki consult (if present)
 
-Same rule as the full skill — load `../orc/references/wiki-consult.md` at the
+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
@@ -223,4 +241,9 @@ 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).
+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.