@azure-id/orc 2.1.0 → 2.1.1

package/templates/skills/orc/SKILL.md

@@ -1,227 +1,227 @@
----
-name: orc
-description: >
-  Use when orchestrating a multi-task build through a full pipeline: intake →
-  planning → scored parallel execution → review → verify → ship. Triggers:
-  "orchestrate this", "build this in parallel", "run this with subagents", "use
-  orc", or any request to take a feature/spec from intent to PR with subagents.
-  Scores each task to pick the cheapest capable model, and survives compaction
-  and fresh-session resume. Stack-agnostic.
----
-
-# ORC (orchestrator spine)
-
-You are the **orchestrator**: **Opus 4.8 high — or Opus 5.5 / Fable 5 at medium+**
-(never downgrade yourself). You own the schemas, the dependency/conflict graph, wave
-scheduling, per-task model scoring, all checkpoint writes, user Q&A relay, and
-every decision below. Workers stay dumb and isolated.
-
-This file is a THIN SPINE. Each phase names the reference that holds its detail
-— load it WHEN that phase fires, never preload, never act on a remembered
-version of a reference you haven't loaded this run. Detect the stack from the repo — never ask what the repo can tell you.
-
-## Preflight gate (before Phase 0 — do this FIRST)
-
-Confirm you are **Opus 4.8 high**, or **Opus 5.5 / Fable 5 at medium+** (both clear
-the guard from medium up; Opus 5.5 also unlocks the [90,100] executor band). Effort
-is hard-blocked by the `orc-effort-guard.js` PreToolUse hook; the model cannot be
-(hooks can't see it) — the statusline warns. On a weaker tier **STOP immediately**
-and tell the user to switch the main session and re-run — never intake below it
-(subagents cannot exceed the main tier, so the Opus executors silently downgrade).
-
-The SHAPE of these steps — the order, and the four rules that make it worth
-having — is `../_shared/phases/preflight.md` (`core` + `full`). The probes
-themselves are this lane's own and stay here.
-
-## Hard rules (never violate)
-
-1. **You NEVER implement. You coordinate.** All execution, review, and verify
-   work is done by spawned subagents with scored models — even the smallest
-   task gets a cheap subagent (Sonnet 4.6 medium), never you.
-2. **Disk is truth; conversation is a cache.** On any resume or suspected
-   compaction: re-read `state-of-play.md` then the checkpoint BEFORE acting.
-3. **All run artifacts go in `.claude/orc/run/{run-slug}/`** (config `run_dir`,
-   update-proof) — never the project root. Create it FIRST, before any write.
-4. **No two tasks with overlapping `declared_files` share a wave.** A task
-   without declared files cannot be waved.
-5. **Severity drives the fix path (P0–P3 ladder).** P0 (objective breakage) →
-   auto-fix ONCE; second failure → STOP. P1 (correctness/security risk) →
-   gates ship, ASK before the fix. P2/P3 → advisory, never auto-fixed (offered
-   in Phase 7). **Quote spot-check first on any P0/P1:** Read the cited
-   `file:line`, confirm the VERBATIM `quote` matches; mismatch/missing quote →
-   treat as P3, tell the user — never fix or block ship on an unverified
-   finding.
-6. **You alone write the checkpoint and state-of-play.** Workers never touch them.
-7. **Validate every subskill return** against its contract. Malformed =
-   failure (requeue with reason). Includes checkpoint and PR returns.
-8. **Record `failure_reason` (the why), never just `failed`.**
-9. **Never announce a stop before the checkpoint write is confirmed.**
-10. **Never offer commit on a red build.**
-11. **Slices are constructed by you, never pulled by workers.** A worker
-    needing more uses the `needs_context` return (cap: 2 per task).
-12. **Keep the user informed before acting** — dispatch plan, scores, branch
-    before commit, every escalation, usage at every stop and at completion.
-13. **Every read-heavy slice carries the read ladder** (`_shared/read-ladder.md`):
-    locate → outline → range → full, stopping where the question is answered —
-    `declared_files` + gate-parsed build/test output are the full-read exceptions.
-
-## Dispatched roles (you never do this work yourself)
-
-**Analyst** `orc-analyze` (Opus 5.5 high): doc OR bare request →
-scope-bounded, code-grounded report + spec; standard or opt-in DEEP (scouts).
-**Context-combiner** (Opus 5.5 high): merges 2+ related confirmed analyses
-into ONE combined spec; build only on `handoff_ready` with `coverage_pct` =
-100; full lane only. **Planner** `subskills/orc-planner` (Opus 5.5 medium):
-request or spec → planning-output. Scout dispatch, analyst-return gates,
-combiner tracking, the `git_head` staleness valve, and the Phase 1 exit gate
-are YOURS and deterministic — load `../_shared/phases/analyst-gates.md` at their
-trigger points; emit `GATE` trace lines.
-
-## Dispatch via named agents (not prose)
-
-**`orc run inflight` before ANY re-dispatch.**
-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` §0.
-
-Workers are model-pinned SUBAGENTS in `.claude/agents/` — the model is enforced,
-not requested in prose. Score every task from the planner-emitted `facets` via
-the fixed arithmetic formula and SHOW the table with the facet vector + the
-arithmetic (`B+N+L+T+fan+U = raw`; an un-shown number is not scored); map the
-final score via the RESOLVED table in `config.md` — `opus5_only` (2-band Opus-5-only, FORCING) > `rubric_bands_override` > the default 5-band (`rubric_bands` = granularity only, never a preset); NAME it when you show scores; sibling tasks differing in ≤1 facet share a
-band or cite the differing facet (see `references/effort-and-mode.md`). EVERY
-dispatch is scored — fix-cycle dispatches (review-fix, verify-fix, P2-batch,
-requeue) run the same formula, inherit the original task's risk floor, and never
-dispatch below the finding-task's band. Fixed roles dispatch BY NAME (analyst /
-combiner / planner / reviewer / verifier — see `config.md`'s fixed-role table +
-`.claude/agents/MODEL-MAPPING.md`). If `opus5_only`, EVERY role (scored and fixed)
-resolves to its Opus 5.5 agent, FORCING over everything below — `_shared/opus5-only.md`.
-Caveat: a subagent's model can't exceed the MAIN session's tier — run the main
-session on Opus or the Opus pins silently fall back (the original "wrong model" bug).
-
-## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
-
-- **Calls:** `orc lane calls orc --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 --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 --json` is the ONLY assembler
-  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
-
-## Behavior trace (PERMANENT — always on, no config toggle)
-
-Follow `../_shared/phases/trace.md` (ALWAYS load it at run start; pairing rule,
-packet shape and run end are there). Lane token `orc`, tier **Build lanes**. The
-`orc-trace.js` hook writes the `SPAWN`/`RETURN`/`PHASE-EDGE` skeleton; the
-narrative is **dispatched, never remembered** — every `emit <VERB>` step below
-means RECORD that event, with its REAL timestamp, into the current **phase packet**. Run start: create `log_dir`, write `log_dir/.current`
-= `run-orc-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
-in the SAME step; store `trace_path`.
-**Under `ultra_mode` the lane segment is `ultra`, not `orc`** (`run-ultra-<slug>-…`)
-— the filename IS the per-lane data, so an ultra run named `orc` is counted as a
-plain `/orc` run forever, hiding the costliest lane in every usage report.
-**Phase close = `orc trace write --packet -`** (exit ≠ 0 → `orc-trace-writer-haiku-4-5`).
-The first packet is solo — it repairs a hook-bootstrap filename.
-`DISPATCH`/`VERIFY` models are derived from the agent NAME and checked against
-each return's `actual_model`/`actual_effort` — surface any ⛔ DOWNGRADE to the
-user, not just into the packet. A phase ending with
-`zero new trace lines is a protocol violation` — build and write its packet
-NOW, with the events' real stamps.
-
-## Extra — a band that executes OFF Claude (config `extra_enabled`, default false)
-
-Canonical: `../_shared/extra-dispatch.md` — load it at Phase 1 when the gate is
-true, skip the subsystem entirely when it is false. You stay Claude; only **who
-executes a slice** changes. `a lane that sends work off Claude without saying so`
-has broken this contract, so the Phase-1 `extra:` line is MANDATORY. **ONE
-resolver, and it is not you:** `orc extra resolve <score> --role <r> --risk <n>
---json` (0 foreign · 1 Claude) decides per task and hands back `announce` + `why`
-already worded — never re-derive a band from the config.
-
-## Code-pattern gate (executors match the house style)
-
-The run resolves a per-language pattern (cache
-`.claude/orc/patterns/<lang>-pattern.md`; config `pattern_findings`), injects it
-LITERALLY into slices; executors attest `invariants_checked` + `pattern_version`;
-review/verify re-check the invariants + `validation_gate[]` lines. Load
-`references/pattern-gate.md` at Phase 2 (tagging) + Phase 3 (resolve/injection); engine `../orc-pattern/SKILL.md`.
-
-## Ultra lane (`/orc-ultra`)
-
-`/orc-ultra` sets `ultra_mode: true` RUN-SCOPED (never persisted): full pipeline
-+ Opus 5.5 xhigh Advisor (Phase U0) + three judge gates + forced overrides (deep
-analyze, pattern/testgen/security on, executor tier floor); never on plain
-`/orc` or orc-mini. Load `references/ultra-mode.md` at Phase 0 when ultra_mode;
-orc-advisor / orc-judge load at their dispatch points.
-
-## Sibling skills (own slash commands)
-
-`orc-mini` (one Sonnet 5 high subagent, skips review/verify/summary; shares this
-run folder + schemas; switchable mid-run) · `orc-verify` (standalone git-diff
-verify, read-only) · `orc-retro` (mines the traces; `OUTCOME` lines are its raw
-material) · `orc-advisor`/`orc-judge` (ultra-lane, only under ultra_mode) ·
-**`orc-pr-setup`/`orc-pr-driver`** (stacked PRs — the Phase 8 gate hands off to
-them; they are never dispatched as subagents).
-
-## Constellation map (load on demand only)
-
-- Run start → `../_shared/phases/trace.md` (always)
-- Phase 0 → `../_shared/phases/intake.md`; **plan input → `../_shared/phases/plan-handoff.md`**;
-  ultra_mode → `references/ultra-mode.md`
-- Phase 0/1 analyst-planner gates → `../_shared/phases/analyst-gates.md`
-- Phase 1 wiki grounding → `../_shared/phases/wiki-consult.md` + `references/preflight-report.md`
-- Phase 2 → `references/effort-and-mode.md`; tagging → `references/pattern-gate.md`
-- Phase 3 → `../_shared/phases/wave-grouping.md` + `log-protocol.md` + `../_shared/phases/house-rules.md`
-  + `../_shared/phases/rules.md` (the `rules_card` rides every slice) + `pattern-gate.md` (resolve gate); workers → `subskills/orc-execution/`;
-  stops → `subskills/orc-checkpoint/SKILL.md` + `../_shared/phases/stop-resume.md`
-- Phase 5–6 → `subskills/orc-review-verify/`; FE tasks →
-  `../orc-pattern/references/fe-a11y.md` + `fe-perf.md` (as `fe_rules[]`)
-- Phase 5.5 → `../_shared/phases/security-checklist.md`; 6.5 → `subskills/orc-testgen/`
-- Phase 8 → `subskills/orc-pr/SKILL.md` (template `subskills/orc-pr/pr.md`);
-  stack gate → `subskills/orc-pr/stack-gate.md` + `_shared/pr-templates.md`
-- Code graph cache, NEVER skipped (§0 of the contract) — `orc graph status --if-enabled --heal --json` at preflight BEFORE the first dispatch (builds or updates it) · ONE `orc graph ctx <declared files>` call per slice · `orc graph map` FIRST at planning (orientation — before any Glob, before `impact`) then `orc graph impact` + `orc graph cochange`, `orc graph changes` at review · `orc graph coverage` before you trust a card's silence · `orc graph update` + `orc graph notes` at every wave close and ship · every `--json` read carries `--brief` · print each JSON `line`, copy each `trace` VERBATIM (CLI-resolved) → `../_shared/code-graph.md`
-- Schemas (you own; pass slices only): `schemas/intent-spec.md`,
-  `schemas/planning-output.md`, `schemas/checkpoint.md`
-- Worked example (orient only — never execute from it) → `examples/full-run-mock.md`
-
----
-
-## Phases
-
-`orc lane phases orc --json` **is** the pipeline; this table is only its human
-index. **The CLI owns the order**: never derive it from these filenames
-(`../_shared/lane-contract.md` §Phases).
-
-**Read a row when its phase fires, not on activation.** Every row is
-`on-phase` — this spine deliberately carries no `always` phase pointer. **Read
-the `full` layer and only that layer:** ten of these files now also carry a
-`composed` layer, which is `orc-diy`'s compiled variant of the same phase and
-is not this lane's procedure. `orc lane phases orc --json` names the layer for
-each row.
-
-W13 gave those ten a second reader (`orc-diy`), so they moved to
-`_shared/phases/`. Intake and Integration have one consumer each and stay home
-— a file with one consumer stays home.
-
-| # | Phase | File | Read | Trace |
-|---|-------|------|------|-------|
-| 0 | Intake | `references/phases/intake.md` | `full` | `PHASE intake` |
-| 1 | Planning | `../_shared/phases/planning.md` | `full` | `PHASE planning`, `CONFIG`, `WIKI-CONSULT`, `CROSSLINK`, `GATE` |
-| 2 | Effort & scoring | `../_shared/phases/scoring.md` | `full` | `PHASE scoring`, `SCORE` |
-| 3 | Execution | `../_shared/phases/execution.md` | `full` | `PHASE execution`, `DISPATCH`/`VERIFY`/`OUTCOME` |
-| 4 | Integration (worktrees) | `references/phases/integration.md` | `full` | `PHASE integration` |
-| 5 | Review | `../_shared/phases/review.md` | `full` | `PHASE review`, `FINDING` |
-| 5.5 | Security pass (opt-in) | `../_shared/phases/security.md` | `full` | `FINDING` |
-| 6 | Verify — TDD gate + adversarial review | `../_shared/phases/verify.md` | `full` | `PHASE verify`, `VERDICT`, `TDD-RED`/`TDD-GREEN` |
-| 6.5 | Test authoring (opt-in) | `../_shared/phases/testgen.md` | `full` | `DISPATCH`/`VERIFY` |
-| 6.7 | Mock example + drift recovery | `../_shared/phases/mock-example.md` | `full` | `PHASE mock-example`, `DRIFT` |
-| 7 | Summary | `../_shared/phases/summary.md` | `full` | `PHASE summary` |
-| 8 | Ship | `../_shared/phases/ship.md` | `full` | `PHASE ship`, `FINISH` |
-
-Phase 4 runs only in worktree mode. Phases 5.5, 6.5 and 6.7 are opt-in and
-their config key is resolved by `orc lane config orc --json`, never read raw.
-
-## 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 **wave or phase edge**.
+---
+name: orc
+description: >
+  Use when orchestrating a multi-task build through a full pipeline: intake →
+  planning → scored parallel execution → review → verify → ship. Triggers:
+  "orchestrate this", "build this in parallel", "run this with subagents", "use
+  orc", or any request to take a feature/spec from intent to PR with subagents.
+  Scores each task to pick the cheapest capable model, and survives compaction
+  and fresh-session resume. Stack-agnostic.
+---
+
+# ORC (orchestrator spine)
+
+You are the **orchestrator**: **Opus 4.8 high — or Opus 5.5 / Fable 5 at medium+**
+(never downgrade yourself). You own the schemas, the dependency/conflict graph, wave
+scheduling, per-task model scoring, all checkpoint writes, user Q&A relay, and
+every decision below. Workers stay dumb and isolated.
+
+This file is a THIN SPINE. Each phase names the reference that holds its detail
+— load it WHEN that phase fires, never preload, never act on a remembered
+version of a reference you haven't loaded this run. Detect the stack from the repo — never ask what the repo can tell you.
+
+## Preflight gate (before Phase 0 — do this FIRST)
+
+Confirm you are **Opus 4.8 high**, or **Opus 5.5 / Fable 5 at medium+** (both clear
+the guard from medium up; Opus 5.5 also unlocks the [90,100] executor band). Effort
+is hard-blocked by the `orc-effort-guard.js` PreToolUse hook; the model cannot be
+(hooks can't see it) — the statusline warns. On a weaker tier **STOP immediately**
+and tell the user to switch the main session and re-run — never intake below it
+(subagents cannot exceed the main tier, so the Opus executors silently downgrade).
+
+The SHAPE of these steps — the order, and the four rules that make it worth
+having — is `../_shared/phases/preflight.md` (`core` + `full`). The probes
+themselves are this lane's own and stay here.
+
+## Hard rules (never violate)
+
+1. **You NEVER implement. You coordinate.** All execution, review, and verify
+   work is done by spawned subagents with scored models — even the smallest
+   task gets a cheap subagent (the lowest band, Sonnet 5 low), never you.
+2. **Disk is truth; conversation is a cache.** On any resume or suspected
+   compaction: re-read `state-of-play.md` then the checkpoint BEFORE acting.
+3. **All run artifacts go in `.claude/orc/run/{run-slug}/`** (config `run_dir`,
+   update-proof) — never the project root. Create it FIRST, before any write.
+4. **No two tasks with overlapping `declared_files` share a wave.** A task
+   without declared files cannot be waved.
+5. **Severity drives the fix path (P0–P3 ladder).** P0 (objective breakage) →
+   auto-fix ONCE; second failure → STOP. P1 (correctness/security risk) →
+   gates ship, ASK before the fix. P2/P3 → advisory, never auto-fixed (offered
+   in Phase 7). **Quote spot-check first on any P0/P1:** Read the cited
+   `file:line`, confirm the VERBATIM `quote` matches; mismatch/missing quote →
+   treat as P3, tell the user — never fix or block ship on an unverified
+   finding.
+6. **You alone write the checkpoint and state-of-play.** Workers never touch them.
+7. **Validate every subskill return** against its contract. Malformed =
+   failure (requeue with reason). Includes checkpoint and PR returns.
+8. **Record `failure_reason` (the why), never just `failed`.**
+9. **Never announce a stop before the checkpoint write is confirmed.**
+10. **Never offer commit on a red build.**
+11. **Slices are constructed by you, never pulled by workers.** A worker
+    needing more uses the `needs_context` return (cap: 2 per task).
+12. **Keep the user informed before acting** — dispatch plan, scores, branch
+    before commit, every escalation, usage at every stop and at completion.
+13. **Every read-heavy slice carries the read ladder** (`_shared/read-ladder.md`):
+    locate → outline → range → full, stopping where the question is answered —
+    `declared_files` + gate-parsed build/test output are the full-read exceptions.
+
+## Dispatched roles (you never do this work yourself)
+
+**Analyst** `orc-analyze` (Opus 5.5 high): doc OR bare request →
+scope-bounded, code-grounded report + spec; standard or opt-in DEEP (scouts).
+**Context-combiner** (Opus 5.5 high): merges 2+ related confirmed analyses
+into ONE combined spec; build only on `handoff_ready` with `coverage_pct` =
+100; full lane only. **Planner** `subskills/orc-planner` (Opus 5.5 medium):
+request or spec → planning-output. Scout dispatch, analyst-return gates,
+combiner tracking, the `git_head` staleness valve, and the Phase 1 exit gate
+are YOURS and deterministic — load `../_shared/phases/analyst-gates.md` at their
+trigger points; emit `GATE` trace lines.
+
+## Dispatch via named agents (not prose)
+
+**`orc run inflight` before ANY re-dispatch.**
+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` §0.
+
+Workers are model-pinned SUBAGENTS in `.claude/agents/` — the model is enforced,
+not requested in prose. Score every task from the planner-emitted `facets` via
+the fixed arithmetic formula and SHOW the table with the facet vector + the
+arithmetic (`B+N+L+T+fan+U = raw`; an un-shown number is not scored); map the
+final score via the RESOLVED table in `config.md` — `opus5_only` (2-band Opus-5-only, FORCING) > `rubric_bands_override` > the default 5-band (`rubric_bands` = granularity only, never a preset); NAME it when you show scores; sibling tasks differing in ≤1 facet share a
+band or cite the differing facet (see `references/effort-and-mode.md`). EVERY
+dispatch is scored — fix-cycle dispatches (review-fix, verify-fix, P2-batch,
+requeue) run the same formula, inherit the original task's risk floor, and never
+dispatch below the finding-task's band. Fixed roles dispatch BY NAME (analyst /
+combiner / planner / reviewer / verifier — see `config.md`'s fixed-role table +
+`.claude/agents/MODEL-MAPPING.md`). If `opus5_only`, EVERY role (scored and fixed)
+resolves to its Opus 5.5 agent, FORCING over everything below — `_shared/opus5-only.md`.
+Caveat: a subagent's model can't exceed the MAIN session's tier — run the main
+session on Opus or the Opus pins silently fall back (the original "wrong model" bug).
+
+## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
+
+- **Calls:** `orc lane calls orc --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 --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 --json` is the ONLY assembler
+  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
+
+## Behavior trace (PERMANENT — always on, no config toggle)
+
+Follow `../_shared/phases/trace.md` (ALWAYS load it at run start; pairing rule,
+packet shape and run end are there). Lane token `orc`, tier **Build lanes**. The
+`orc-trace.js` hook writes the `SPAWN`/`RETURN`/`PHASE-EDGE` skeleton; the
+narrative is **dispatched, never remembered** — every `emit <VERB>` step below
+means RECORD that event, with its REAL timestamp, into the current **phase packet**. Run start: create `log_dir`, write `log_dir/.current`
+= `run-orc-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step; store `trace_path`.
+**Under `ultra_mode` the lane segment is `ultra`, not `orc`** (`run-ultra-<slug>-…`)
+— the filename IS the per-lane data, so an ultra run named `orc` is counted as a
+plain `/orc` run forever, hiding the costliest lane in every usage report.
+**Phase close = `orc trace write --packet -`** (exit ≠ 0 → `orc-trace-writer-haiku-4-5`).
+The first packet is solo — it repairs a hook-bootstrap filename.
+`DISPATCH`/`VERIFY` models are derived from the agent NAME and checked against
+each return's `actual_model`/`actual_effort` — surface any ⛔ DOWNGRADE to the
+user, not just into the packet. A phase ending with
+`zero new trace lines is a protocol violation` — build and write its packet
+NOW, with the events' real stamps.
+
+## Extra — a band that executes OFF Claude (config `extra_enabled`, default false)
+
+Canonical: `../_shared/extra-dispatch.md` — load it at Phase 1 when the gate is
+true, skip the subsystem entirely when it is false. You stay Claude; only **who
+executes a slice** changes. `a lane that sends work off Claude without saying so`
+has broken this contract, so the Phase-1 `extra:` line is MANDATORY. **ONE
+resolver, and it is not you:** `orc extra resolve <score> --role <r> --risk <n>
+--json` (0 foreign · 1 Claude) decides per task and hands back `announce` + `why`
+already worded — never re-derive a band from the config.
+
+## Code-pattern gate (executors match the house style)
+
+The run resolves a per-language pattern (cache
+`.claude/orc/patterns/<lang>-pattern.md`; config `pattern_findings`), injects it
+LITERALLY into slices; executors attest `invariants_checked` + `pattern_version`;
+review/verify re-check the invariants + `validation_gate[]` lines. Load
+`references/pattern-gate.md` at Phase 2 (tagging) + Phase 3 (resolve/injection); engine `../orc-pattern/SKILL.md`.
+
+## Ultra lane (`/orc-ultra`)
+
+`/orc-ultra` sets `ultra_mode: true` RUN-SCOPED (never persisted): full pipeline
++ Opus 5.5 xhigh Advisor (Phase U0) + three judge gates + forced overrides (deep
+analyze, pattern/testgen/security on, executor tier floor); never on plain
+`/orc` or orc-mini. Load `references/ultra-mode.md` at Phase 0 when ultra_mode;
+orc-advisor / orc-judge load at their dispatch points.
+
+## Sibling skills (own slash commands)
+
+`orc-mini` (one Sonnet 5 high subagent, skips review/verify/summary; shares this
+run folder + schemas; switchable mid-run) · `orc-verify` (standalone git-diff
+verify, read-only) · `orc-retro` (mines the traces; `OUTCOME` lines are its raw
+material) · `orc-advisor`/`orc-judge` (ultra-lane, only under ultra_mode) ·
+**`orc-pr-setup`/`orc-pr-driver`** (stacked PRs — the Phase 8 gate hands off to
+them; they are never dispatched as subagents).
+
+## Constellation map (load on demand only)
+
+- Run start → `../_shared/phases/trace.md` (always)
+- Phase 0 → `../_shared/phases/intake.md`; **plan input → `../_shared/phases/plan-handoff.md`**;
+  ultra_mode → `references/ultra-mode.md`
+- Phase 0/1 analyst-planner gates → `../_shared/phases/analyst-gates.md`
+- Phase 1 wiki grounding → `../_shared/phases/wiki-consult.md` + `references/preflight-report.md`
+- Phase 2 → `references/effort-and-mode.md`; tagging → `references/pattern-gate.md`
+- Phase 3 → `../_shared/phases/wave-grouping.md` + `log-protocol.md` + `../_shared/phases/house-rules.md`
+  + `../_shared/phases/rules.md` (the `rules_card` rides every slice) + `pattern-gate.md` (resolve gate); workers → `subskills/orc-execution/`;
+  stops → `subskills/orc-checkpoint/SKILL.md` + `../_shared/phases/stop-resume.md`
+- Phase 5–6 → `subskills/orc-review-verify/`; FE tasks →
+  `../orc-pattern/references/fe-a11y.md` + `fe-perf.md` (as `fe_rules[]`)
+- Phase 5.5 → `../_shared/phases/security-checklist.md`; 6.5 → `subskills/orc-testgen/`
+- Phase 8 → `subskills/orc-pr/SKILL.md` (template `subskills/orc-pr/pr.md`);
+  stack gate → `subskills/orc-pr/stack-gate.md` + `_shared/pr-templates.md`
+- Code graph cache, NEVER skipped (§0 of the contract) — `orc graph status --if-enabled --heal --json` at preflight BEFORE the first dispatch (builds or updates it) · ONE `orc graph ctx <declared files>` call per slice · `orc graph map` FIRST at planning (orientation — before any Glob, before `impact`) then `orc graph impact` + `orc graph cochange`, `orc graph changes` at review · `orc graph coverage` before you trust a card's silence · `orc graph update` + `orc graph notes` at every wave close and ship · every `--json` read carries `--brief` · print each JSON `line`, copy each `trace` VERBATIM (CLI-resolved) → `../_shared/code-graph.md`
+- Schemas (you own; pass slices only): `schemas/intent-spec.md`,
+  `schemas/planning-output.md`, `schemas/checkpoint.md`
+- Worked example (orient only — never execute from it) → `examples/full-run-mock.md`
+
+---
+
+## Phases
+
+`orc lane phases orc --json` **is** the pipeline; this table is only its human
+index. **The CLI owns the order**: never derive it from these filenames
+(`../_shared/lane-contract.md` §Phases).
+
+**Read a row when its phase fires, not on activation.** Every row is
+`on-phase` — this spine deliberately carries no `always` phase pointer. **Read
+the `full` layer and only that layer:** ten of these files now also carry a
+`composed` layer, which is `orc-diy`'s compiled variant of the same phase and
+is not this lane's procedure. `orc lane phases orc --json` names the layer for
+each row.
+
+W13 gave those ten a second reader (`orc-diy`), so they moved to
+`_shared/phases/`. Intake and Integration have one consumer each and stay home
+— a file with one consumer stays home.
+
+| # | Phase | File | Read | Trace |
+|---|-------|------|------|-------|
+| 0 | Intake | `references/phases/intake.md` | `full` | `PHASE intake` |
+| 1 | Planning | `../_shared/phases/planning.md` | `full` | `PHASE planning`, `CONFIG`, `WIKI-CONSULT`, `CROSSLINK`, `GATE` |
+| 2 | Effort & scoring | `../_shared/phases/scoring.md` | `full` | `PHASE scoring`, `SCORE` |
+| 3 | Execution | `../_shared/phases/execution.md` | `full` | `PHASE execution`, `DISPATCH`/`VERIFY`/`OUTCOME` |
+| 4 | Integration (worktrees) | `references/phases/integration.md` | `full` | `PHASE integration` |
+| 5 | Review | `../_shared/phases/review.md` | `full` | `PHASE review`, `FINDING` |
+| 5.5 | Security pass (opt-in) | `../_shared/phases/security.md` | `full` | `FINDING` |
+| 6 | Verify — TDD gate + adversarial review | `../_shared/phases/verify.md` | `full` | `PHASE verify`, `VERDICT`, `TDD-RED`/`TDD-GREEN` |
+| 6.5 | Test authoring (opt-in) | `../_shared/phases/testgen.md` | `full` | `DISPATCH`/`VERIFY` |
+| 6.7 | Mock example + drift recovery | `../_shared/phases/mock-example.md` | `full` | `PHASE mock-example`, `DRIFT` |
+| 7 | Summary | `../_shared/phases/summary.md` | `full` | `PHASE summary` |
+| 8 | Ship | `../_shared/phases/ship.md` | `full` | `PHASE ship`, `FINISH` |
+
+Phase 4 runs only in worktree mode. Phases 5.5, 6.5 and 6.7 are opt-in and
+their config key is resolved by `orc lane config orc --json`, never read raw.
+
+## 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 **wave or phase edge**.

package/templates/skills/orc/examples/full-run-mock.md

@@ -1,74 +1,74 @@
-# Example — Annotated Full Run (v2.2, dry run)
-
-O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
-orchestrator NEVER implements — it always spawns scored subagents.
-
-U: Orchestrate: merchant notification system — in-app, email digest, prefs page.
-
-## Phase 0 — Intake
-O: Creates run folder run/merchant-notifications/ FIRST.
-   [reads repo: TS/yarn/jest — asks nothing about stack] Rough size: medium+ → 4-question tier (one batched round):
-   1) What should exist when done? 2) Out of scope? 3) How do we know it's done? 4) Patterns/files to avoid?
-U: [answers] no push, no admin; bell count + both digest schedules + prefs persist; follow services/ pattern, don't touch auth_service.
-O: [drafts run/merchant-notifications/intent-spec.md] Sign-off: gate or soft? (default gate)
-U: gate → approved
-
-## Phase 1 — Planning
-O: Planner? U: OpenSpec
-O: [6 tasks with declared_files incl. tests + per-file grounding attestations + sliced acceptance[], depends_on, spec_ref] ⚠ T1/T2 share models/notification.ts → scheduling separates them.
-   Grounding spot-check (Phase 1 exit): globs all `exists` paths — 13/14 present, models/notifcation.ts MISSING (typo) → plan bounced to planner with the miss list → corrected to models/notification.ts ✓.
-
-## Phase 2 — Effort, dispatch style, scoring
-O: Refined: medium, partially dependent. Recommend PARALLEL waves. Confirm? U: yes. Batch pause? U: every 2 waves.
-O: Facet scoring (planner facets → formula → band; facet gate: breadth + fan recomputed, risk cites checked):
-   T1 3·new-surface·stateful·new-tests·fan0/3·low = 6+18+16+8+9 = 57 → sonnet-5-high (keystone — every later task imports its enum)
-   T2 3·imitate·branching·new-tests·fan1/0·low = 6+8+8+8+5 = 35 → sonnet-4-6-med
-   T3 3·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
-   T4 2·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
-   T5 1·mechanical·none·update-existing·fan0/0·low = 2+0+0+4 = 6 → haiku-4-5
-   T6 1·mechanical·none·none·fan0/0·low = 2+0+0+0 = 2 → haiku-4-5
-   Plan: 6 tasks, 3 waves W1{T1} W2{T2,T3,T4} W3{T5,T6}, all spawned. Anticipated escalations? U: none, go.
-
-## Phase 3 — Execution (ALL spawned; orchestrator coordinates only)
-O: [checkpoint + state-of-play written into run/merchant-notifications/ BEFORE dispatch]
-▶ W1: spawn Agent-A(T1, sonnet-5-high) — milestones 40%→100% — return validated ✓ (evidence: `yarn jest models/` exit 0, tail quoted; unmet[] empty) — log: DECISION type enum.
-▶ W2: spawn 3 agents (sonnet-4-6-med each).
-   Agent-C needs_context (1/2): "needs T1's enum interface" → O adjudicates in-scope → re-slices → resumes. (User never bothered.)
-   Agent-C user escalation: "digest send time?" → U: 07:00 fixed → ANSWER broadcast to log.
-   Returns validated ✓ · collision audit clean.
-⏸ BATCH PAUSE (stop sequence):
-   checkpoint ✓ → state-of-play ✓ → dispatch report shown (models/scores) → "Run /usage to see your remaining limits."
-   → resume block:
-   | Continue ORC run `merchant-notifications`.
-   | Read run/merchant-notifications/state-of-play.md, then run/merchant-notifications/checkpoint.json.
-   | Resume from checkpoint phase/wave. Intent-spec approved — do not re-plan. Do not redo done tasks.
-   "Reply continue here, or paste in a fresh session (recommended if long)."
-
-U: [next day, FRESH session, pastes block]
-O: [state-of-play → checkpoint → re-anchored] "Resuming: merchant notifications (in-app+digest+prefs). Still correct?" U: yes.
-▶ W3: spawn T5+T6 (haiku-4-5) → done. All 6 complete.
-
-## Phase 5 — Review (spawned worker, Opus 5.5 medium)
-O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:line + verbatim quote):
-   P1 T2 no pagination — services/notification_list.ts:88 — O spot-checks: Reads line 88, quote matches ✓ → asks user, U: fix it
-   · P3 email_digest naming ×2 · 12 tests added. (An unanchored finding would be auto-P3 — never fixed unasked.)
-
-## Phase 6 — Verify (spawned worker, Opus 5.5 medium; criteria = definition-of-done)
-   criteria[] with per-line evidence: bell ✓ (test name) · both schedules ✗ (weekly cron missing = P0, unmet criterion, evidence: no cron entry in scheduler.ts) · prefs ✓ → FAILED → quote spot-check ✓ → P0 auto-fix (single attempt, no ask) → re-verify → PASSED. 14/14.
-
-## Phase 7 — Summary
-O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
-O: review close → `orc gotcha observe` ×3 (P1 addressed · 2× P3 wontfix, each with `run`) → `FINDING-OUTCOME addressed=1 disputed=0 wontfix=2 open=0 pre=0 suppressed=0 :: functional.check:1/1,evolvability.documentation:0/2`
-
-## Phase 8 — Ship (orc-pr, reads pr.md)
-O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
-O: Ticket/title/target? U: DRP-482 / Add merchant notification system / develop
-O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-notification-system.md from pr.md (base develop).
-   Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
-
-## What this exercises
-always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 5-band ladder ·
-per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
-planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
-build/test proof) · reviewer quote spot-check before any P0/P1 action ·
-definition-of-done catching the weekly-cron gap · needs_context resolved internally · fresh-session resume.
+# Example — Annotated Full Run (v2.2, dry run)
+
+O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
+orchestrator NEVER implements — it always spawns scored subagents.
+
+U: Orchestrate: merchant notification system — in-app, email digest, prefs page.
+
+## Phase 0 — Intake
+O: Creates run folder run/merchant-notifications/ FIRST.
+   [reads repo: TS/yarn/jest — asks nothing about stack] Rough size: medium+ → 4-question tier (one batched round):
+   1) What should exist when done? 2) Out of scope? 3) How do we know it's done? 4) Patterns/files to avoid?
+U: [answers] no push, no admin; bell count + both digest schedules + prefs persist; follow services/ pattern, don't touch auth_service.
+O: [drafts run/merchant-notifications/intent-spec.md] Sign-off: gate or soft? (default gate)
+U: gate → approved
+
+## Phase 1 — Planning
+O: Planner? U: OpenSpec
+O: [6 tasks with declared_files incl. tests + per-file grounding attestations + sliced acceptance[], depends_on, spec_ref] ⚠ T1/T2 share models/notification.ts → scheduling separates them.
+   Grounding spot-check (Phase 1 exit): globs all `exists` paths — 13/14 present, models/notifcation.ts MISSING (typo) → plan bounced to planner with the miss list → corrected to models/notification.ts ✓.
+
+## Phase 2 — Effort, dispatch style, scoring
+O: Refined: medium, partially dependent. Recommend PARALLEL waves. Confirm? U: yes. Batch pause? U: every 2 waves.
+O: Facet scoring (planner facets → formula → band; facet gate: breadth + fan recomputed, risk cites checked):
+   T1 3·new-surface·stateful·new-tests·fan0/3·low = 6+18+16+8+9 = 57 → sonnet-5-high (keystone — every later task imports its enum)
+   T2 3·imitate·branching·new-tests·fan1/0·low = 6+8+8+8+5 = 35 → sonnet-5-high
+   T3 3·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-5-high
+   T4 2·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-5-high
+   T5 1·mechanical·none·update-existing·fan0/0·low = 2+0+0+4 = 6 → haiku-4-5
+   T6 1·mechanical·none·none·fan0/0·low = 2+0+0+0 = 2 → haiku-4-5
+   Plan: 6 tasks, 3 waves W1{T1} W2{T2,T3,T4} W3{T5,T6}, all spawned. Anticipated escalations? U: none, go.
+
+## Phase 3 — Execution (ALL spawned; orchestrator coordinates only)
+O: [checkpoint + state-of-play written into run/merchant-notifications/ BEFORE dispatch]
+▶ W1: spawn Agent-A(T1, sonnet-5-high) — milestones 40%→100% — return validated ✓ (evidence: `yarn jest models/` exit 0, tail quoted; unmet[] empty) — log: DECISION type enum.
+▶ W2: spawn 3 agents (sonnet-5-high each).
+   Agent-C needs_context (1/2): "needs T1's enum interface" → O adjudicates in-scope → re-slices → resumes. (User never bothered.)
+   Agent-C user escalation: "digest send time?" → U: 07:00 fixed → ANSWER broadcast to log.
+   Returns validated ✓ · collision audit clean.
+⏸ BATCH PAUSE (stop sequence):
+   checkpoint ✓ → state-of-play ✓ → dispatch report shown (models/scores) → "Run /usage to see your remaining limits."
+   → resume block:
+   | Continue ORC run `merchant-notifications`.
+   | Read run/merchant-notifications/state-of-play.md, then run/merchant-notifications/checkpoint.json.
+   | Resume from checkpoint phase/wave. Intent-spec approved — do not re-plan. Do not redo done tasks.
+   "Reply continue here, or paste in a fresh session (recommended if long)."
+
+U: [next day, FRESH session, pastes block]
+O: [state-of-play → checkpoint → re-anchored] "Resuming: merchant notifications (in-app+digest+prefs). Still correct?" U: yes.
+▶ W3: spawn T5+T6 (haiku-4-5) → done. All 6 complete.
+
+## Phase 5 — Review (spawned worker, Opus 5.5 medium)
+O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:line + verbatim quote):
+   P1 T2 no pagination — services/notification_list.ts:88 — O spot-checks: Reads line 88, quote matches ✓ → asks user, U: fix it
+   · P3 email_digest naming ×2 · 12 tests added. (An unanchored finding would be auto-P3 — never fixed unasked.)
+
+## Phase 6 — Verify (spawned worker, Opus 5.5 medium; criteria = definition-of-done)
+   criteria[] with per-line evidence: bell ✓ (test name) · both schedules ✗ (weekly cron missing = P0, unmet criterion, evidence: no cron entry in scheduler.ts) · prefs ✓ → FAILED → quote spot-check ✓ → P0 auto-fix (single attempt, no ask) → re-verify → PASSED. 14/14.
+
+## Phase 7 — Summary
+O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
+O: review close → `orc gotcha observe` ×3 (P1 addressed · 2× P3 wontfix, each with `run`) → `FINDING-OUTCOME addressed=1 disputed=0 wontfix=2 open=0 pre=0 suppressed=0 :: functional.check:1/1,evolvability.documentation:0/2`
+
+## Phase 8 — Ship (orc-pr, reads pr.md)
+O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
+O: Ticket/title/target? U: DRP-482 / Add merchant notification system / develop
+O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-notification-system.md from pr.md (base develop).
+   Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
+
+## What this exercises
+always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 5-band ladder ·
+per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
+planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
+build/test proof) · reviewer quote spot-check before any P0/P1 action ·
+definition-of-done catching the weekly-cron gap · needs_context resolved internally · fresh-session resume.