@azure-id/orc 2.0.2 → 2.1.1

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

@@ -1,208 +1,210 @@
----
-name: orc-fast
-description: >
-  Fastest ORC lane — knowledge-gated single-executor implementation, with no
-  analyst and no planner. Use for "use orc-fast to implement X" or "/orc-fast".
-  Requires TWO prerequisites: a fresh project wiki (orc-wiki) AND a cached
-  code-pattern for the request's language. If either is missing, it falls back
-  to orc-mini. One Sonnet 4.6 high executor, a build+test smoke gate, one repair
-  round, ship.
----
-
-# ORC-FAST
-
-The speed lane: precomputed knowledge instead of pipeline phases — the wiki
-supplies grounding, the pattern cache supplies house style, so fast pays for
-neither an analyst nor a planner. That trade only holds when both exist and
-the wiki is fresh, so the two prerequisite gates below are hard: fail either →
-**fall back to orc-mini** carrying whatever intake was done. Fallback is the
-router — orc-fast is always safe to try.
-
-Runs fine with the orchestrator at **Sonnet 4.6 / Sonnet 5, medium effort** —
-no scoring, no planning judgment (the effort guard only gates the full `orc`
-skill). **You never implement — you spawn.**
-
-## What fast deliberately does NOT have
-
-No analyst, planner, scoring, waves, reviewer, verifier, test-author, or
-summary. One executor, one smoke gate, one repair round. More than that → the
-fit gate hands it to orc-mini.
-
-## Phases
-
-`orc lane phases orc-fast --json` is this lane's pipeline. **The CLI owns the order**:
-never derive it from the headings below, and never rename or renumber one
-without the manifest (`../_shared/lane-contract.md` §Phases).
-
-## Phase F0 — Preflight (the two prerequisite gates; no spawn)
-
-Emit a `GATE` trace line per check.
-
-**a. Wiki gate.** Decide existence with `orc wiki status` — the deterministic
-probe in `../_shared/detecting-artifacts.md`, never an ad-hoc `find` (`.claude`
-is hidden). `none` = gate FAILED → fallback; else read the tier from
-`orc wiki status --json` → `.tier` (FRESH / AGING / STALE; the CLI computes
-it — never recompute it by hand).
-- **FRESH** → proceed silently. **AGING** → one-line notice, proceed.
-- **STALE** → the user judges. Ask (H `fast.f0.stale-wiki`) with exactly these options:
-  1. **Refresh wiki, then continue fast** *(recommended)* — run orc-wiki's
-     incremental refresh (diff since `scan_commit`, re-scan only affected
-     docs), then re-enter this preflight.
-  2. **Drop to orc-mini** *(preferable if in a hurry — mini grounds itself)*.
-  3. **Continue fast anyway** *(not recommended — the executor may follow
-     stale claims)* — proceed and stamp `wiki_stale_override: true` in the
-     checkpoint so /orc-retro can correlate outcomes with overrides.
-
-**b. Pattern gate.** Detect the request's language (file extensions / repo
-deps, same signals as the full lane's tagging) and confirm the cache with
-`orc pattern status <lang>` (exit 0 = cached — the deterministic probe in
-`../_shared/detecting-artifacts.md`, never an ad-hoc `find`). Absent for the
-language in play → gate FAILED → fallback. (A request touching no FE/BE language — pure docs/
-config — passes this gate as N/A.) The cross-cutting `postgres` pattern is
-NEVER a gate prerequisite — it is bonus-only (injected at F2 on a cache HIT),
-so a missing `postgres-pattern.md` never fails the gate or forces a fallback.
-
-**Any gate FAILED** → announce which prerequisite failed in one line, then
-hand off to orc-mini via the fallback contract below. Never stop the chat.
-
-**c. Gotchas — NOT a gate.** Two prerequisites stay two: a missing `.claude/orc/gotchas.md` never forces a fallback. Fast READS repair memory (`orc gotcha status`, then inject the SCOPE-MATCHING entries into the F2 slice, cap 3) and never WRITES it — `../_shared/gotchas.md` §10. The code graph is NOT a gate either (e. below).
-
-**e. Code graph cache — NOT a gate, and never skipped** (`../_shared/code-graph.md` §0). Every call carries
-`--if-enabled`: exit 3 = off → print `graph: off` once, make no other graph call. Print each JSON `line`; put
-each `trace` in the next packet VERBATIM. (1) **Here:** `orc graph status --if-enabled --heal --json --brief` builds or
-updates the cache itself. (2) **F2 slice:** ONE `orc graph ctx <declared files> --if-enabled --json --brief` → its `card`
-is the `graph` block; the return carries `graph_used`. (3) **F3 GREEN:** `orc graph update --if-enabled --json --brief`,
-then one `orc graph notes pending` batch — the next run starts from this cache. A missing graph never falls back.
-
-**d. Extra — a PROBE, not a gate (P0).** Run `orc extra resolve --slot fast-executor --json` (0 = extra, 1 = Claude) — **a gate that is never probed is a gate that is always off**, and without this step the lane silently runs on Claude however `extra_enabled` and `orc extra role` were set. `extra` → print the `extra:` line HERE and carry the answer into F2; `claude` → print nothing, never fall back, never stop.
-
-The SHAPE of these steps — the order, and the four rules that make it worth
-having — is `../_shared/phases/preflight.md` (`core`). The probes
-themselves are this lane's own and stay here.
-
-## Phase F1 — Fit gate + micro-intake (one pass, ONE user round-trip)
-
-Draft a 3–5 line intent spec + 2–3 acceptance bullets. Judge fit: more than
-one real task, ~5+ files, or core/security-sensitive surface → fallback to
-orc-mini WITH the intent spec attached (no rework); emit a `GATE` line for the
-verdict. Then the lane's ONLY pre-spawn ask — one combined confirmation:
-preflight result + intent spec + acceptance bullets + "proceed?" (soft
-sign-off; never split into multiple questions). Create the run folder
-(`.claude/orc/run/{run-slug}/` — shared format, so fallback needs no
-migration) and write the intent-spec + a minimal checkpoint.
-
-## Phase F2 — Slice build + dispatch (ONE executor)
-
-Build one slice for `orc-executor-sonnet-4-6-high` (dispatch BY NAME; model
-pinned in the agent file). **Under `opus5_only` it is `orc-executor-opus-5-low`** — forced, and while that mode is on this lane needs an Opus 5.5 main session, so the "runs fine at Sonnet medium" premise applies only with it off (`../_shared/opus5-only.md`).
-
-**Extra (`extra_enabled`, `../_shared/extra-dispatch.md`):** the same slice may run off Claude. **This lane has no score at all, so it holds a POSITION, not a band:** resolve `orc extra resolve --slot fast-executor --json` (set with `orc extra role set fast-executor <profile>/<model>`). No row on that slot = Claude, and that is an answer, not a gap. The `extra:` line joins the F0 preflight (P0, printed whenever the gate is on) and NAMES the agent it displaces — `orc-executor-sonnet-4-6-high`; dispatch through `orc extra dispatch --task <file> --json` with `slot: "fast-executor"` and **no `score`** (both is refused by name); validate with `return-validation.md` **§2b, not §2**; a failure runs `orc extra reconcile <task_id>` FIRST — a worktree that moved is RESUMED, never re-done — then falls back to that same pinned agent BY NAME, announced. Extra is orthogonal to the knowledge gate — a fresh wiki and a cached pattern are still required, and a foreign worker gets the same pointers-not-content slice.
-
-- the task (intent spec) + acceptance bullets as definition-of-done
-- **wiki pointers, not content** (fast's lane-delta in
-  `../_shared/phases/wiki-consult.md`): the PATHS of 1–3 relevant pages
-  selected from `wiki/INDEX.md` by keyword match — prefer the cross-cutting
-  maps (`orc-reference-api-surface` etc.) when the domain matches. Instruct
-  the executor to READ them first, and include the precedence line verbatim:
-  `code > fresh wiki > stale wiki (hints) > model priors`. Never paste wiki
-  bodies into the slice (a Sonnet-medium orchestrator curating wiki prose
-  defeats the lane). **Emit `WIKI-CONSULT <tier> :: docs=<the selected pointer
-  paths>`** (tier from the F0 gate; `docs=none` if no pages fit) — the F0
-  `GATE` line captured the gate *decision*; this captures which pages grounded
-  the run.
-- the cached pattern injected LITERALLY (same `pattern` slice contract as
-  full; the pattern file is small by design)
-- **crosslink (cross-repo, advisory):** a task touching a boundary in
-  `.claude/orc/crosslink/needs.json` gets the cached linked contract injected
-  as `crosslink` ("hints, not verified") — advisory, never blocks, never
-  outranks local code.
-- **`db:postgres` bonus:** a data-access task with
-  `.claude/orc/patterns/postgres-pattern.md` CACHED merges it into the same
-  `pattern` slice (query invariants). Cache MISS → skip silently — fast never
-  codifies and never falls back on this.
-- **the read ladder** (`../_shared/read-ladder.md`): read only as far up as the
-  question needs — a file the task will EDIT is read in full first. Precomputed
-  knowledge REPLACING exploration is this lane; a directory sweep is not. With the graph on, `orc graph ctx` cards locate first.
-- the standing `house_rules` card (`../_shared/phases/house-rules.md`, literal,
-  same as full/mini) + the `rules_card` under it (`orc rules slice` → `text`, verbatim)
-- constraints from the intent spec
-- **terse-return rule:** standard contract fields, NO narrative prose — files
-  changed, one-line diff summary, smoke-relevant notes only.
-
-Validate the return per `../_shared/return-validation.md` §1–§3 + the § of
-each field you injected — `unmet[]`
-honesty, `pattern_version` + `invariants_checked` attestation, `actual_model`
-/ `actual_effort` downgrade check (emit the `VERIFY` trace line), and §6's worktree delta (`git status --short` before/after; a path changed outside `declared_files` is a violation whatever the return said). Malformed
-return = failure (one re-dispatch, then fallback offer).
-
-**Before any re-dispatch, run `orc run inflight`**. A Task error does not kill the agent behind it, and exit 2 REFUSES by default — `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `../_shared/return-validation.md`.
-
-## Phase F3 — Smoke gate (build + test; blocks ship on red)
-
-Run the gate per `../_shared/smoke-gate.md`, sourcing commands **from
-`wiki-meta.json`'s `commands` block** (recorded at wiki scan — don't
-rediscover tooling; manifest lacks them → detect once and say so). **GREEN**
-→ code-graph step e.(3) (never a gate) → ship. **RED** → the flaky check, then one repair round; second red → STOP and offer: escalate to
-orc-mini (reason `smoke-red-escalation`) / switch to full `/orc` / stop.
-Docs-only → gate N/A, say so.
-
-## Phase F3.5 — Mock example (config `mock_example`, default ask)
-
-After a GREEN F3, before ship (H `fast.f3-5.mock`): follow `../_shared/drift-recovery.md` (load on
-fire) — the `mock-examples/<change-slug>/` deliverable, the `DRIFT-FROM` loop and
-its cap. Trace: `PHASE mock-example`, `DRIFT loop=<n>`.
-
-## Phase F4 — Ship
-
-Offer commit (H `fast.f4.ship` · `any.ship.review-before-push`; push if asked; never stage `mock-examples/`). Append the final markers to the checkpoint, emit
-`OUTCOME task=… band=fast model=… retries=… unmet=…` + `FINISH`, show the
-dispatch line (model/effort actually used) + the `/usage` reminder. Every end — ship
-or a red STOP — prints the card (`../_shared/phases/summary.md` §End-of-run card). Fast never
-triggers the post-ship wiki refresh ask (preflight polices freshness on the
-way in) — the passive stale-flag note still applies to touched covered files.
-
-## Fallback contract (orc-fast → orc-mini)
-
-Follow the writer side of `../_shared/fallback-handoff.md`: announce the
-failed gate in one line, write the `FALLBACK-FROM` block into the run folder
-(REASON: wiki-absent | wiki-stale-user-choice | pattern-absent | fit-gate |
-smoke-red-escalation), and invoke orc-mini pointing at it. The run folder is
-already in the shared format — no migration.
-
-## Behavior trace (always on)
-
-`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases orc-fast --json` →
-`trace_grammar` gives the verbs). Lane token `fast`, tier
-**Build lanes** — batched to **2 packets** (preflight+dispatch ·
-gate+ship) → `orc trace write --packet -`. At run start write `log_dir/.current` =
-`run-fast-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
-in the SAME step. A phase that ends with `zero new trace lines is a protocol violation`.
-
-## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
-
-- **Calls:** `orc lane calls orc-fast --json` names every call and its exit codes.
-  **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
-- **Config:** `orc lane config orc-fast --json`. Obey `effective`, print every line
-  in `announce[]` VERBATIM at preflight, and honour `stops[]` before wave 1.
-  Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
-- **Rules:** `orc rules slice --lane orc-fast --json` is the ONLY assembler
-  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
-
-Fast has no config key of its own — command-entry only; wave/scoring/review
-keys never apply, and the tier edges the F0 gate reads arrive resolved.
-
-## Checkpoint (minimal, append-only)
-
-One `fast-checkpoint.md` in the run folder: GATE results (+ any
-`wiki_stale_override`), the dispatch, smoke verdicts, OUTCOME — enough for
-/orc-retro mining and fresh-session resume, nothing more.
-
-## What fast still enforces
-
-All artifacts in the run subfolder, never project root · never offer commit on
-a red build · never invoke `/usage` programmatically.
-
-## 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**.
+---
+name: orc-fast
+description: >
+  Fastest ORC lane — knowledge-gated single-executor implementation, with no
+  analyst and no planner. Use for "use orc-fast to implement X" or "/orc-fast".
+  Requires TWO prerequisites: a fresh project wiki (orc-wiki) AND a cached
+  code-pattern for the request's language. If either is missing, it falls back
+  to orc-mini. One Sonnet 5 medium executor, a build+test smoke gate, one repair
+  round, ship.
+---
+
+# ORC-FAST
+
+The speed lane: precomputed knowledge instead of pipeline phases — the wiki
+supplies grounding, the pattern cache supplies house style, so fast pays for
+neither an analyst nor a planner. That trade only holds when both exist and
+the wiki is fresh, so the two prerequisite gates below are hard: fail either →
+**fall back to orc-mini** carrying whatever intake was done. Fallback is the
+router — orc-fast is always safe to try.
+
+Runs fine with the orchestrator at **Sonnet 5, medium effort** (a Sonnet 4.6 main session is below the executor pin) —
+no scoring, no planning judgment (the effort guard only gates the full `orc`
+skill). **You never implement — you spawn.**
+
+## What fast deliberately does NOT have
+
+No analyst, planner, scoring, waves, reviewer, verifier, test-author, or
+summary. One executor, one smoke gate, one repair round. More than that → the
+fit gate hands it to orc-mini.
+
+## Phases
+
+`orc lane phases orc-fast --json` is this lane's pipeline. **The CLI owns the order**:
+never derive it from the headings below, and never rename or renumber one
+without the manifest (`../_shared/lane-contract.md` §Phases).
+
+## Phase F0 — Preflight (the two prerequisite gates; no spawn)
+
+Emit a `GATE` trace line per check.
+
+**0. Config, FIRST.** `orc lane config orc-fast --json`: obey `effective`, print
+`announce[]` VERBATIM, honour `stops[]`; never merge `.claude/orc.config.yaml`
+(`../_shared/config-precedence.md`). **`habits{}` in it → print `habits.line`,
+read `../_shared/habits.md` NOW.**
+
+**a. Wiki gate.** Decide existence with `orc wiki status` — the deterministic
+probe in `../_shared/detecting-artifacts.md`, never an ad-hoc `find` (`.claude`
+is hidden). `none` = gate FAILED → fallback; else read the tier from
+`orc wiki status --json` → `.tier` (FRESH / AGING / STALE; the CLI computes
+it — never recompute it by hand).
+- **FRESH** → proceed silently. **AGING** → one-line notice, proceed.
+- **STALE** → the user judges. Ask (H `fast.f0.stale-wiki`) with exactly these options:
+  1. **Refresh wiki, then continue fast** *(recommended)* — run orc-wiki's
+     incremental refresh (diff since `scan_commit`, re-scan only affected
+     docs), then re-enter this preflight.
+  2. **Drop to orc-mini** *(preferable if in a hurry — mini grounds itself)*.
+  3. **Continue fast anyway** *(not recommended — the executor may follow
+     stale claims)* — proceed and stamp `wiki_stale_override: true` in the
+     checkpoint so /orc-retro can correlate outcomes with overrides.
+
+**b. Pattern gate.** Detect the request's language (file extensions / repo
+deps, same signals as the full lane's tagging) and confirm the cache with
+`orc pattern status <lang>` (exit 0 = cached — the deterministic probe in
+`../_shared/detecting-artifacts.md`, never an ad-hoc `find`). Absent for the
+language in play → gate FAILED → fallback. (A request touching no FE/BE language — pure docs/
+config — passes this gate as N/A.) The cross-cutting `postgres` pattern is
+NEVER a gate prerequisite — it is bonus-only (injected at F2 on a cache HIT),
+so a missing `postgres-pattern.md` never fails the gate or forces a fallback.
+
+**Any gate FAILED** → announce which prerequisite failed in one line, then
+hand off to orc-mini via the fallback contract below. Never stop the chat.
+
+**c. Gotchas — NOT a gate.** Two prerequisites stay two: a missing `.claude/orc/gotchas.md` never forces a fallback. Fast READS repair memory (`orc gotcha status`, then inject the SCOPE-MATCHING entries into the F2 slice, cap 3) and never WRITES it — `../_shared/gotchas.md` §10. The code graph is NOT a gate either (e. below).
+
+**e. Code graph cache — NOT a gate, and never skipped** (`../_shared/code-graph.md` §0). Every call carries
+`--if-enabled`: exit 3 = off → print `graph: off` once, make no other graph call. Print each JSON `line`; put
+each `trace` in the next packet VERBATIM. (1) **Here:** `orc graph status --if-enabled --heal --json --brief` builds or
+updates the cache itself. (2) **F2 slice:** ONE `orc graph ctx <declared files> --if-enabled --json --brief` → its `card`
+is the `graph` block; the return carries `graph_used`. (3) **F3 GREEN:** `orc graph update --if-enabled --json --brief`,
+then one `orc graph notes pending` batch — the next run starts from this cache. A missing graph never falls back.
+
+**d. Extra — a PROBE, not a gate (P0).** Run `orc extra resolve --slot fast-executor --json` (0 = extra, 1 = Claude) — **a gate that is never probed is a gate that is always off**, and without this step the lane silently runs on Claude however `extra_enabled` and `orc extra role` were set. `extra` → print the `extra:` line HERE and carry the answer into F2; `claude` → print nothing, never fall back, never stop.
+
+Their shape and four rules: `../_shared/phases/preflight.md` (`core`). The
+probes are this lane's own.
+
+## Phase F1 — Fit gate + micro-intake (one pass, ONE user round-trip)
+
+Draft a 3–5 line intent spec + 2–3 acceptance bullets. Judge fit: more than
+one real task, ~5+ files, or core/security-sensitive surface → fallback to
+orc-mini WITH the intent spec attached (no rework); emit a `GATE` line for the
+verdict. Then the lane's ONLY pre-spawn ask — one combined confirmation:
+preflight result + intent spec + acceptance bullets + "proceed?" (soft
+sign-off; never split into multiple questions). Create the run folder
+(`.claude/orc/run/{run-slug}/` — shared format, so fallback needs no
+migration) and write the intent-spec + a minimal checkpoint.
+
+## Phase F2 — Slice build + dispatch (ONE executor)
+
+Build one slice for `orc-executor-sonnet-5-med` (dispatch BY NAME; model
+pinned in the agent file). **Under `opus5_only` it is `orc-executor-opus-5-low`** — forced, and while that mode is on this lane needs an Opus 5.5 main session, so the "runs fine at Sonnet medium" premise applies only with it off (`../_shared/opus5-only.md`).
+
+**Extra (`extra_enabled`, `../_shared/extra-dispatch.md`):** the same slice may run off Claude. **This lane has no score at all, so it holds a POSITION, not a band:** resolve `orc extra resolve --slot fast-executor --json` (set with `orc extra role set fast-executor <profile>/<model>`). No row on that slot = Claude, and that is an answer, not a gap. The `extra:` line joins the F0 preflight (P0, printed whenever the gate is on) and NAMES the agent it displaces — `orc-executor-sonnet-4-6-high`; dispatch through `orc extra dispatch --task <file> --json` with `slot: "fast-executor"` and **no `score`** (both is refused by name); validate with `return-validation.md` **§2b, not §2**; a failure runs `orc extra reconcile <task_id>` FIRST — a worktree that moved is RESUMED, never re-done — then falls back to that same pinned agent BY NAME, announced. Extra is orthogonal to the knowledge gate — a fresh wiki and a cached pattern are still required, and a foreign worker gets the same pointers-not-content slice.
+
+- the task (intent spec) + acceptance bullets as definition-of-done
+- **wiki pointers, not content** (fast's lane-delta in
+  `../_shared/phases/wiki-consult.md`): the PATHS of 1–3 relevant pages
+  selected from `wiki/INDEX.md` by keyword match — prefer the cross-cutting
+  maps (`orc-reference-api-surface` etc.) when the domain matches. Instruct
+  the executor to READ them first, and include the precedence line verbatim:
+  `code > fresh wiki > stale wiki (hints) > model priors`. Never paste wiki
+  bodies into the slice (a Sonnet-medium orchestrator curating wiki prose
+  defeats the lane). **Emit `WIKI-CONSULT <tier> :: docs=<the selected pointer
+  paths>`** (tier from the F0 gate; `docs=none` if no pages fit) — the F0
+  `GATE` line captured the gate *decision*; this captures which pages grounded
+  the run.
+- the cached pattern injected LITERALLY (same `pattern` slice contract as
+  full; the pattern file is small by design)
+- **crosslink (cross-repo, advisory):** a task touching a boundary in
+  `.claude/orc/crosslink/needs.json` gets the cached linked contract injected
+  as `crosslink` ("hints, not verified") — advisory, never blocks, never
+  outranks local code.
+- **`db:postgres` bonus:** a data-access task with
+  `.claude/orc/patterns/postgres-pattern.md` CACHED merges it into the same
+  `pattern` slice (query invariants). Cache MISS → skip silently — fast never
+  codifies and never falls back on this.
+- **the read ladder** (`../_shared/read-ladder.md`): read only as far up as the
+  question needs — a file the task will EDIT is read in full first. Precomputed
+  knowledge REPLACING exploration is this lane; a directory sweep is not. With the graph on, `orc graph ctx` cards locate first.
+- the standing `house_rules` card (`../_shared/phases/house-rules.md`, literal,
+  same as full/mini) + the `rules_card` under it (`orc rules slice` → `text`, verbatim)
+- constraints from the intent spec
+- **terse-return rule:** standard contract fields, NO narrative prose — files
+  changed, one-line diff summary, smoke-relevant notes only.
+
+Validate the return per `../_shared/return-validation.md` §1–§3 + the § of
+each field you injected — `unmet[]`
+honesty, `pattern_version` + `invariants_checked` attestation, `actual_model`
+/ `actual_effort` downgrade check (emit the `VERIFY` trace line), and §6's worktree delta (`git status --short` before/after; a path changed outside `declared_files` is a violation whatever the return said). Malformed
+return = failure (one re-dispatch, then fallback offer).
+
+**Before any re-dispatch, run `orc run inflight`**. A Task error does not kill the agent behind it, and exit 2 REFUSES by default — `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `../_shared/return-validation.md`.
+
+## Phase F3 — Smoke gate (build + test; blocks ship on red)
+
+Run the gate per `../_shared/smoke-gate.md`, sourcing commands **from
+`wiki-meta.json`'s `commands` block** (recorded at wiki scan — don't
+rediscover tooling; manifest lacks them → detect once and say so). **GREEN**
+→ code-graph step e.(3) (never a gate) → ship. **RED** → the flaky check, then one repair round; second red → STOP and offer: escalate to
+orc-mini (reason `smoke-red-escalation`) / switch to full `/orc` / stop.
+Docs-only → gate N/A, say so.
+
+## Phase F3.5 — Mock example (config `mock_example`, default ask)
+
+After a GREEN F3, before ship (H `fast.f3-5.mock`): follow `../_shared/drift-recovery.md` (load on
+fire) — the `mock-examples/<change-slug>/` deliverable, the `DRIFT-FROM` loop and
+its cap. Trace: `PHASE mock-example`, `DRIFT loop=<n>`.
+
+## Phase F4 — Ship
+
+Offer commit (H `fast.f4.ship` · `any.ship.review-before-push`; push if asked; never stage `mock-examples/`). Append the final markers to the checkpoint, emit
+`OUTCOME task=… band=fast model=… retries=… unmet=…` + `FINISH`, show the
+dispatch line (model/effort actually used) + the `/usage` reminder. Every end — ship
+or a red STOP — prints the card (`../_shared/phases/summary.md` §End-of-run card). Fast never
+triggers the post-ship wiki refresh ask (preflight polices freshness on the
+way in) — the passive stale-flag note still applies to touched covered files.
+
+## Fallback contract (orc-fast → orc-mini)
+
+Follow the writer side of `../_shared/fallback-handoff.md`: announce the
+failed gate in one line, write the `FALLBACK-FROM` block into the run folder
+(REASON: wiki-absent | wiki-stale-user-choice | pattern-absent | fit-gate |
+smoke-red-escalation), and invoke orc-mini pointing at it. The run folder is
+already in the shared format — no migration.
+
+## Behavior trace (always on)
+
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases orc-fast --json` →
+`trace_grammar` gives the verbs). Lane token `fast`, tier
+**Build lanes** — batched to **2 packets** (preflight+dispatch ·
+gate+ship) → `orc trace write --packet -`. At run start write `log_dir/.current` =
+`run-fast-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step. A phase that ends with `zero new trace lines is a protocol violation`.
+
+## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
+
+- **Calls:** `orc lane calls orc-fast --json` names every call and its exit codes.
+  **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
+- **Config:** F0 step 0.
+- **Rules:** `orc rules slice --lane orc-fast --json` is the ONLY assembler
+  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
+
+Fast has no config key of its own — command-entry only; wave/scoring/review
+keys never apply, and the tier edges the F0 gate reads arrive resolved.
+
+## Checkpoint (minimal, append-only)
+
+One `fast-checkpoint.md` in the run folder: GATE results (+ any
+`wiki_stale_override`), the dispatch, smoke verdicts, OUTCOME — enough for
+/orc-retro mining and fresh-session resume, nothing more.
+
+## What fast still enforces
+
+All artifacts in the run subfolder, never project root · never offer commit on
+a red build · never invoke `/usage` programmatically.
+
+## 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**.

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

@@ -0,0 +1,110 @@
+---
+name: orc-fix
+description: >
+  Say "this is a fix, and here is what it fixes". Use for "/orc-fix", "this
+  fixes Sonar typescript:S3776", "ORC caused this defect", "this bug came from
+  AI-generated code", "record this fix". It classifies the fix from evidence,
+  asks once, and records it so the next review sees it. A rider: it opens no
+  run and returns to exactly where the run was. With no run open it can also
+  make the fix, like /orc-quick.
+---
+
+# ORC — the fix record
+
+A RIDER lane, like `/orc-wait` and `/orc-explain`. It opens no run of its own,
+writes no `run-<lane>-<slug>` pointer and never writes `.current`. The user can
+call it at any time — also while another lane waits at a question.
+
+## What this lane never does
+
+- It never begins between a dispatch and its validated return.
+- It never changes the host run: no re-plan, no re-score, no new task. A
+  suspend does not widen anyone's authority.
+- With a run open, it never writes code. The host lane makes the fix — two
+  writers on one tree is the conflict `/orc-wait` forbids (DE-12).
+- It never sets `miss` itself, and never records `author: orc`. The CLI does
+  the first, and refuses the second.
+
+## F0 — look (silent)
+
+Run `orc fix classify --text "<the user's words>" --json`. The CLI reads the
+git state, `git blame` on the named lines, the traces and the host run, and
+proposes ONE class on two axes:
+
+- `source` (what found it): `sonar` · `ci` · `defect` · `pr` · `review` · `other`
+- `introduced_by` (who wrote the bad lines): `orc` · `ai` · `human` · `unknown`
+
+| exit | meaning | what you do |
+|---|---|---|
+| 0 | classified | go to F1 |
+| 1 | a dispatch is in flight | say so, wait for its return, then run F0 again |
+| 2 | no text | ask what the fix fixes |
+
+Never classify in your head. The user's three cases: "a SonarQube fix" →
+`source: sonar`; "a defect caused by ORC" → `source: defect, introduced_by:
+orc`; "a bug caused by AI-generated code" → `introduced_by: ai`.
+
+## F1 — ask once (H `fix.f1.class`)
+
+Show the proposed class, every `evidence` line and the file, then:
+
+```text
+This fix:  source sonar · introduced by ORC (run-mini-total-290926)
+  - a Sonar rule key (typescript:S3776)
+  - git blame → 4c1e2a9: the commit falls inside the run's trace window ...
+  1. confirm   2. change the class   3. cancel
+```
+
+The user's word wins over the evidence. A changed class goes into the record
+as `class_by: "user"`; a confirmed one as `class_by: "evidence"`. Cancel →
+nothing is written; return to the run.
+
+## F2 — record
+
+Pipe the classify answer's `record` object (with the user's class and
+`class_by`) to `orc fix record - --json`. The CLI:
+
+1. writes ONE observation through the gotcha store — with a Sonar issue key it
+   uses the importer's own id, so a later `gotcha sync` completes the same row;
+2. computes `miss` from the stored review scopes;
+3. writes ONE `FIX` line into the HOST run's trace, when one is open;
+4. prints ONE line. Show it VERBATIM, then stop.
+
+Exit 1 → a dispatch started meanwhile; nothing was written. Wait, then F2 again.
+
+## No run open — offer the fix (DE-12)
+
+`mode: may-fix` from F0 → offer to make the fix before F2, like `/orc-quick`:
+
+1. The user picks the executor at the `/orc-quick` dispatch gate (that lane's
+   `dispatch-gate.md` reference, "Writing code") — nothing spawns without a yes.
+2. The slice carries `orc rules slice --lane orc-fix --json` (below).
+3. The smoke gate (`../_shared/smoke-gate.md`): red blocks the record.
+4. F2 with `outcome: "addressed"` and `via: "orc-fix"`.
+
+The user can also say "record only" — then F2 at once.
+
+## Config
+
+`orc lane config orc-fix --json`, obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-fix --json` is the ONLY assembler. It rides only in
+an executor slice of the no-run fix.
+
+## Habits and trace
+
+**Habits:** the host run had `habits{}` in its config answer → read
+`../_shared/habits.md`; its next packet takes the `ASK` for `fix.f1.class`
+(class `never`: a fact is never a habit). No `habits{}` → ignore `(H …)`.
+
+**Trace:** the CLI writes the `FIX` line itself. You do not narrate it and you
+do not repeat it. With no run open, nothing is traced — the record is the
+observation.
+
+## 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 **after the record is written**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking.