@azure-id/orc 0.55.0

package/templates/skills/orc/references/effort-and-mode.md

@@ -0,0 +1,224 @@
+# Reference — Effort, Dispatch Style, and Task Scoring
+
+**Subagents ALWAYS do the work — the orchestrator never implements** (hard
+rule 1). The orchestrator is Opus 4.8 high: it doing implementation is the most
+costly way possible, and it burns the context that must survive the whole run.
+Spawning keeps orchestrator context lean so runs last longer before any pause.
+
+Two INDEPENDENT axes. Never conflate them:
+- **Run-level effort** (low/medium/high) → picks the **dispatch style**
+  (sequential vs parallel), which controls only **intra-wave concurrency** —
+  never WHO does the work, and never WHETHER waves exist.
+- **Per-task score** (0–100) → picks each **worker's model**. Always applies.
+
+A medium run can contain a 30-score task and a 95-score task in the same wave.
+
+## Waves always exist; dispatch style is intra-wave only
+
+**Wave computation runs for every run with ≥2 tasks, sequential included**
+(dependency layers + conflict graph + `max_wave_tasks` cap — see
+`wave-grouping.md`). Dispatch style does NOT decide whether there are waves; it
+decides how a wave's tasks fire:
+
+- **sequential** → a wave's tasks dispatch one at a time, in order; the wave
+  closes when all its tasks close;
+- **parallel** → a wave's non-conflicting tasks dispatch at once (up to
+  `max_wave_tasks`).
+
+The **wave-boundary batch pause binds to wave numbers, identically in both
+styles** — a sequential run is NOT "no waves / per-task pauses". Show the wave
+plan (wave → tasks → pause marks) to the user BEFORE wave 1 in both styles.
+
+## Run-level effort → dispatch style (recommend, user confirms)
+
+- **Low**, or heavy shared data/code → **sequential**: one scored subagent at a
+  time, in dependency order (still grouped into waves). Even a single trivial
+  task = one cheap subagent (typically Sonnet 4.6 medium), never the
+  orchestrator itself.
+- **Medium** → sequential by default; **parallel** intra-wave if 3+ genuinely
+  independent areas.
+- **High** with independent areas → **parallel** waves; consider worktrees for
+  isolation (merge at end).
+
+Always RECOMMEND with a one-line why, and let the user pick. Tell them the
+agent/task/wave counts, each task's scored model, and where batch pauses fall
+BEFORE dispatching.
+
+## Per-task scoring — facet-scored, arithmetic, two-writer
+
+The score is **not judged** from a task title. The **planner** — the one party
+that globbed and read every declared file — emits per-task `facets` (facts). The
+**orchestrator** — who never read the code — computes the number arithmetically
+and audits the facts. No vibes anywhere. Every task is scored, including tiny ones.
+
+**1. Planner-emitted facets** (`planning-output.md` `facets` block, filled during
+grounding — zero extra passes):
+
+| Facet | Values |
+|---|---|
+| `breadth` | `len(declared_files)` — computed, not judged |
+| `novelty` | mechanical · imitate · new-surface · novel-algorithm |
+| `logic` | none · branching · stateful · algorithmic |
+| `test_surface` | none · update-existing · new-tests |
+| `risk` | `[]` or `[{class, cite}]` — class ∈ auth·money·migration·security·concurrency·data-integrity; **each entry MUST cite the file/requirement** |
+| `uncertainty` | low · medium · high (+ one-line reason if not low) |
+
+`fan_in`/`fan_out` are NOT emitted — the orchestrator computes them from
+`depends_on` (forward = fan_in, reverse = fan_out).
+
+**2. Orchestrator validation gate (Phase 2, deterministic — same bounce
+mechanics as grounding):** emit `GATE facet pass|bounce`. Three checks:
+
+- **Recompute** `breadth` (= `len(declared_files)`) and `fan_in`/`fan_out` from
+  the plan itself — a mismatch bounces.
+- **MEMBERSHIP (v0.34.4):** `novelty`, `logic`, `test_surface` and `uncertainty`
+  must each be a member of their CLOSED set above, and every `risk[].class` must
+  be one of the six risk classes. A set lookup, as deterministic as the grounding
+  Glob. This is the check that was missing: the gate validated only the two
+  facets it could recompute and TRUSTED the four it could not, so a planner that
+  invented a `low|medium|high` scale produced an **arithmetically unscorable**
+  plan that passed the stated gate. There is no `N("low")` — and an orchestrator
+  applying `risk != [] -> floor 70` to prose risk strings floors EVERY task, a
+  two-band overshoot caused by a field's shape rather than by the work.
+- **Cite check:** a `risk` entry with no `cite` bounces (unchanged).
+
+A facet-vocabulary miss is a **FIELD-SHAPE bounce**: hand back the miss list and
+say *do not re-plan* — the planner corrects only the offending `facets` blocks.
+(It may also legitimately DROP a risk entry on the correction pass: implementation
+hazards like test seeding or dependency discipline are not risk CLASSES. That
+judgment is the planner's to make and is worth accepting.) Without this clause a
+shape bounce risks costing a correct plan. A plan with no `facets` at all
+(pre-v0.31.0) resumes on the legacy path — never bounced for the missing block.
+
+**3. The fixed formula (the ONLY scoring text — this replaces base+adjusters):**
+
+```
+score = B(breadth) + N(novelty) + L(logic) + T(test_surface)
+        + 5*min(fan_in,3) + 3*min(fan_out,3) + U(uncertainty)
+
+B: 1f=2   2-3f=6   4-5f=10   6+f=15
+N: mechanical=0   imitate=8   new-surface=18   novel-algorithm=30
+L: none=0   branching=8   stateful=16   algorithmic=24
+T: none=0   update-existing=4   new-tests=8
+U: low=0   medium=6   high=12
+
+risk ≠ [] → floor 70 (DERIVED from a cited risk facet, never remembered).
+clamp 0..100 → the RESOLVED table (below).
+```
+
+**Which table (highest wins):** `opus5_only: true` (the 3-band Opus-5-only
+preset: `[0,40)` low · `[40,80)` medium · `[80,100]` high) → `rubric_bands_override`
+(hand-written rows) → the default 8-band table. All three are in `config.md`.
+The formula, the facets and the risk floor are IDENTICAL in every case — only
+the score→agent mapping changes. Three consequences worth stating so nobody
+re-derives them per run:
+
+- **The risk floor still applies** — it raises the SCORE, then the resolved table
+  maps it. Under the Opus-5-only preset a floored task lands `opus-5-med`, not
+  `opus-4-7-high`.
+- **`opus5_only` FORCES** — while on, a hand-written `rubric_bands_override` is
+  ignored, and so is the entire Fable 5 block. It is the one selector that can
+  shadow another; that is deliberate.
+- **`fable5_roles` never covers executors** (analyze/plan/advisor/judge/review
+  only), so those two features are orthogonal and cannot disagree on a band.
+
+Show the user the full table (task, the facet vector, the arithmetic
+`B+N+L+T+fan+U = raw`, any risk floor, final, override+reason if any, dispatched
+model) BEFORE dispatching — an un-shown number is not a scored number. **Head it
+with the RESOLVED table's name** (`8-band default` / `Opus-5-only ladder
+(opus5_only)` / `custom (rubric_bands_override)`): the same logic
+applies to the mapping as to the number.
+
+**Extra (v0.50.0, `extra_enabled`) adds a `via` column and can make the head a
+PAIR.** An Extra route row is an OVERLAY that outranks the tables above **only
+for the scores it covers**, so a run can genuinely be running two tables at once
+and the head names both (`8-band default + extra rows [0,30) [30,70)`). The
+column reads `claude` or `extra:<profile> (<engine>)` and comes from
+`orc extra resolve --json` — the formula, the facets and the risk floor are
+untouched, and **the score is computed before the routing, never after it**. Two
+consequences the table has to show rather than imply: a cited `risk[]` HOLDS THE
+TASK BACK to its Claude band whatever the row says (`extra_risk_tasks: off`), and
+the `model` for a foreign task is the FOREIGN model id, not a Claude tier.
+Canonical: `../../_shared/extra-dispatch.md`.
+
+**4. Consistency check:** two tasks whose facet vectors differ in **≤1 facet must
+land in the same band** — or the SCORE line for the outlier **cites the one
+differing facet**. This is the specific fix for sibling tasks in the same domain
+drifting into three different bands.
+
+**5. Override protocol** (unchanged): you may override the computed score. Record
+`{computed_score, override_score, reason}` in the dispatch log. An override
+without a reason is invalid.
+
+## EVERY dispatch is scored — the fix-cycle rule
+
+Fix-cycle dispatches — review-fix, verify-fix, the Phase-7 P2-batch, and any
+requeue — are scored through the **same formula**, with two floors that stop a
+fix in a risk area from silently dropping to a cheap model:
+
+- **Inherit the ORIGINAL task's `risk` facets** when the fix touches its files —
+  a fix in a risk-floor area keeps the ≥70 floor (a userID/context-key fix can
+  never dispatch below `opus-4-7-high` again);
+- a **P0/P1 fix never dispatches below the band of the task that produced the
+  finding.**
+
+Emit a `SCORE task=fix-<n> …` line for each (they appear in the dispatch log and
+the completion table like any task).
+
+## Worked scoring examples (facet vectors — compare facet-by-facet, not by vibes)
+
+Each row is the facet vector run through the formula. The number is arithmetic;
+the band is what matters. Compare a new task to these facet-by-facet.
+
+| Task | breadth·novelty·logic·test · fan_in/out · unc | Arithmetic | Band |
+|---|---|---|---|
+| Rename a config key across 4 files + its test | 5·mechanical·none·update-existing · 0/0 · low | 10+0+0+4 = **14** | haiku [0,30) |
+| New CRUD endpoint following a sibling route | 3·imitate·branching·new-tests · 1/0 · low | 6+8+8+8+5 = **35** | sonnet-4-6-med [30,40) |
+| Bug fix across 2 files with a repro test | 3·imitate·branching·new-tests · 0/0 · medium | 6+8+8+8+6 = **36** | sonnet-4-6-med [30,40) |
+| Isolated component from the design system | 3·new-surface·branching·new-tests · 0/0 · low | 6+18+8+8 = **40** | sonnet-4-6-high [40,55) |
+| Notification model + enum other tasks consume | 3·new-surface·stateful·new-tests · 0/3 · low | 6+18+16+8+9 = **57** | sonnet-5-high [55,65) |
+| Service-layer refactor behind a stable interface | 5·imitate·stateful·update-existing · 0/3 · medium | 10+8+16+4+9+6 = **53** | sonnet-4-6-high [40,55) |
+| Add role check to payment-refund endpoint | 3·imitate·branching·new-tests · 0/0 · low · **risk=[auth,money]** | 30 raw → **floor 70** | opus-4-7-high [70,80) |
+| Migrate orders table to split-name + backfill | 6·new-surface·stateful·new-tests · 1/3 · high · **risk=[migration,data-integrity]** | 15+18+16+8+5+9+12 = 83 (floor 70) → **83** | opus-4-8-high [80,90) |
+
+Two disciplines the vectors encode: (1) a small diff is NOT a low score when a
+cited `risk` facet forces the floor (the refund row — 30 raw, floored to 70); (2)
+a big-looking task IS low when its facets are mechanical (the rename). The risk
+floor is always DERIVED from a cited facet — the SCORE line names it, never
+applies it silently.
+
+## Model ladder → the single score→model table
+
+The score→model mapping is NOT hardcoded here — it lives in `config.md` as ONE
+canonical 8-band table (there is no longer a narrow/wide preset). Read config at
+run start and map each task's final score through that table (or
+`rubric_bands_override`). The orchestrator dispatches the executor agent BY NAME;
+it does not request a raw model. `rubric_bands` sets only how many bands the
+rubric REPORTS (score granularity), never which table is used.
+
+The 8 bands (see config.md for the exact edges): `haiku-4-5` [0,30) ·
+`sonnet-4-6-med` [30,40) · `sonnet-4-6-high` [40,55) · `sonnet-5-high` [55,65) ·
+`opus-4-7-med` [65,70) · `opus-4-7-high` [70,80) · `opus-4-8-high` [80,90) ·
+`opus-5-high` [90,100]. Effort tiers rank `low < medium < high < xhigh < max`.
+
+## Fixed model assignments (not scored)
+
+- **Orchestrator (you):** Opus 4.8 high — or Opus 5 / Fable 5 at medium+, the
+  two models that clear the guard from medium up. Never downgrade yourself.
+- **Review** — Superpowers path: Sonnet 4.6, medium. OpenSpec/self path:
+  Opus 5, medium (`orc-reviewer-opus-5-med`).
+- **Verify:** Opus 5, medium (`orc-verifier-opus-5-med`).
+- **Analyst:** Opus 5, high. **Planner:** Opus 5, medium. **Test author:**
+  Opus 5, medium. **Combiner:** Opus 5, high. **Ultra advisor/judge:** Opus 5,
+  xhigh — every core fixed role is pinned to Opus 5 as of v0.34.0.
+- **Merge-conflict resolver:** Opus 4.8, medium.
+
+Note: every band in the table above is a real dispatch target (haiku through
+opus-5). If a model tier is unavailable in the environment, fall back UP to the
+next capable tier (never silently substitute a different family/effort).
+
+## Dispatch log (lives in the checkpoint)
+
+Every spawn records: `{task_id, computed_score, override_score|null,
+override_reason|null, model, effort, spawned_at}`. Feeds the usage report at
+every stop.

package/templates/skills/orc/references/house-rules.md

@@ -0,0 +1,20 @@
+# ORC House Rules (standing behavioral card)
+
+Injected LITERALLY into every executor slice as `house_rules` — never a file
+pointer. Keep the card ≤ 10 lines: it rides in EVERY dispatch, so every
+redundant line is paid on every spawn. Do NOT add rules the slice contract
+already enforces (constraints, pattern-matching, stay-in-slice, invariant
+re-check) — duplication dilutes.
+
+## The card (inject exactly the lines between the markers)
+
+<!-- card-start -->
+HOUSE RULES (standing, apply to every change):
+1. Surgical changes only — touch nothing orthogonal to your task, even "easy wins".
+2. Simplicity first — no speculative abstraction, no config for needs that don't exist yet.
+3. No unrequested scope — build exactly what the task asks, nothing extra.
+4. Prefer the boring solution — the obvious approach over the clever one, every time.
+5. Never claim what you haven't observed — name a file/symbol/behavior only after reading it this session; mark inferences as inferences.
+6. An honest partial beats a false done — report what's unmet, never round up.
+7. Never revert, discard or rewrite files you did not write — `git checkout/restore/reset/stash/clean` are forbidden in your slice; an impossible assertion is `unmet`, never something to make true.
+<!-- card-end -->

package/templates/skills/orc/references/intake.md

@@ -0,0 +1,120 @@
+# Reference — Phase 0 Intake
+
+Goal: extract just enough that the intent-spec can't be misread, then get out of
+the way. A wrong understanding parallelized is worse than a wrong understanding
+done serially. Never interrogate; never ask what the repo can tell you.
+
+**Before anything — plan-input trigger (see `plan-handoff.md`):** if the run
+input IS a plan (pasted planning-output, a `plan-{name}.md` path, or an
+`orc/planner/{name}/` checkpoint), do NOT run intake — switch to the plan-handoff
+entry contract (`references/plan-handoff.md`): bootstrap the trace, schema-
+validate, apply the `plan_head` staleness valve, re-run the full Phase 1 exit
+gate in this session, relay `open_questions[]`, then continue at Phase 2. A plain
+prose request is not a plan — run intake normally.
+
+**Before intake questions — analyst auto-trigger (see SKILL.md Phase 0):** if the
+input includes a document OR the requirement is ambiguous/underspecified, dispatch
+the System Analyst FIRST (doc-optional; standard/deep gate; scouts in deep mode).
+It resolves scope + accuracy with evidence-or-mark and recommended-option
+questions before any intent-spec is drafted. When it hands back "take into build",
+its confirmed spec feeds Phase 1 planning.
+
+## Step 0 — Create the run folder FIRST
+
+Before anything else, derive a `{run-slug}` from the user's request (short,
+lowercased, hyphenated intent name, e.g. "merchant-notifications") and create
+`.claude/orc/run/{run-slug}/` (config `run_dir`). ALL run artifacts
+(intent-spec, checkpoint, state-of-play, decision log) live here — never in the
+project root, never loose in run/. If a folder with that slug exists, append a
+short timestamp.
+
+## Step 1 — Rough-size (picks the question tier)
+
+Fast read: how many distinct feature areas does the request imply? Use the
+request text + a quick repo glance. If genuinely unclear, ask ONE sizing
+question ("roughly how big — a small change, a feature, or multiple features?").
+This is a rough size for tier selection only; the REAL effort estimate happens
+in Phase 2 with the intent-spec in hand.
+
+## Step 2 — Tiered questions (ask in ONE batched round)
+
+**Always (even small tasks):**
+1. In one or two sentences, what should exist when this is done that doesn't now?
+2. What's explicitly *out* of scope?
+
+**Add for medium+:**
+3. How will we know it's done — what should work/pass?
+   (→ becomes Phase 6 verify's acceptance criteria)
+4. Anything the code must respect or avoid — patterns to follow, libraries not
+   to add, files not to touch? (→ hard rules in every worker slice)
+
+**Add for high / multi-feature:**
+5. What existing parts of the system does this touch that it must not break?
+   (→ feeds the conflict graph / integration surface)
+6. Anything you're unsure about or expect to change mid-build?
+   (→ pre-empts mid-run escalations)
+
+Infer stack, test framework, file layout, existing patterns from the repo.
+Only intent, scope, and priorities are askable.
+
+## Step 3 — Draft the intent-spec
+
+Write `run/{run-slug}/intent-spec.md` per `schemas/intent-spec.md`. Restate the
+user's intent in YOUR words — restating is what surfaces misreadings.
+
+## Step 3.5 — Repo cross-check of the draft (evidence-or-mark, proportional)
+
+Before showing the spec, cross-check its claims against the repo — the direct
+path (no analyst) is the only lane where a spec can reach planning ungrounded.
+Same vocabulary as the analyst: confirm or tag `UNVERIFIED`, never silently
+assume.
+
+- **What to check:** every file, module, command, or existing behavior the
+  draft NAMES — in Definition of done, Constraints, and Integration surface.
+  A quick Glob/Grep per item; you are confirming the noun exists as described,
+  not analyzing it.
+- **Proportional to the tier:** 2-question tier → check named files/modules
+  only. 4/6-question tiers → full pass over the three sections above.
+- **Anything unconfirmable gets an `UNVERIFIED` tag in the spec** and the tags
+  become ONE batched question in the sign-off round ("These I could not confirm
+  in the repo: … — confirm, correct, or drop?"). Never more than one round.
+- **Escalation valve:** more than 3 tags means the request is under-grounded
+  for a direct intake — stretching intake into a second analyst is the one thing
+  not to do. Two exits, and they answer DIFFERENT questions. Offer them in this
+  order; the user chooses:
+  1. **`/orc-grill`** — when the **intent** is unclear ("I want notifications",
+     "something is wrong with refunds"). A conversation: minutes, no scan, no
+     scout tokens. It comes back with a scoped idea, and its exit 2 feeds
+     `orc-analyze` directly.
+  2. **`/orc-analyze`** (requirement mode) — when the intent is clear but its
+     **grounding in the code** is not. A scan: tokens, evidence, `file:line`.
+
+  Naming them in that order matters: a scan cannot fix a vague intent, it can
+  only re-ask it at scan prices.
+  (The standalone planner has the same valve: a request below its plannable
+  floor routes to the analyst instead of being planned thin — no side door.)
+
+## Question rounds that run long — borrow the interview format
+
+The tiers above are a fixed questionnaire, which is right for a request that
+arrives well-formed. When a tier's round runs long or the answers keep opening
+new questions, switch that round to the frontier format in
+`../../_shared/interview.md`: ask every question whose prerequisites are settled
+in ONE round (never two questions where one depends on the other), each in the
+shape `❓ **Q1** — **<title>**: <body>` with the recommendation alone on a `➡️`
+line. Two rules from that contract still bind here — resolve FACTS yourself
+before asking (wiki → pattern → gotchas), and never adopt a DECISION by default.
+Same primitive, a different front door; do not fork a second version of it.
+
+## Step 4 — Sign-off
+
+Ask: hard gate (nothing proceeds until explicit approval) or soft (proceed
+unless objection)? **Default when unspecified: GATE.**
+Show the spec. Gate mode: wait for approval or edits. Soft: proceed after
+showing unless the user objects.
+
+## Fresh-session reconfirm
+
+When resuming a run in a fresh session, show a ONE-LINE reconfirm of the
+intent-spec's scope ("Resuming: <one-line scope>. Still correct?") before
+continuing. Catches requirements that changed between sessions, costs one line.

package/templates/skills/orc/references/log-protocol.md

@@ -0,0 +1,39 @@
+# Reference — Decision Log Protocol
+
+How workers pass knowledge across waves without peer-to-peer IPC. Load during
+Phase 3.
+
+## What it is
+
+- File: `run/{title}-{subtitle}-{DDMMYY}.md`. Append-only.
+- Workers read a COMPACTED DIGEST at start (via their slice's `log_digest`
+  field) and return `log_entries[]` at end; the ORCHESTRATOR appends them.
+- Holds: cross-cutting decisions, discovered constraints, interface changes,
+  broadcast escalation answers.
+- Deleted on successful completion. (Checkpoint survives; the log does not.)
+- Log = agent knowledge. Checkpoint = orchestration state. Never mix them.
+
+## Write discipline (no corruption)
+
+1. Every entry prefixed with **agent-id + millisecond timestamp**:
+   `[Agent-C | 020726 14:28:41.507] <entry>`
+   Agent-id makes same-millisecond writes still distinct.
+2. Append-only; no edits to existing lines. One logical entry = one atomic append.
+3. Accept a bloated raw log — it's the audit trail. Clarity beats size.
+
+## Compaction (what workers actually read)
+
+1. Before each wave, YOU produce a compacted digest: dedup, sort by timestamp,
+   drop superseded decisions, group by area, keep only what's relevant to the
+   upcoming tasks' areas.
+2. **Compact a COPY** (digest passed inline in slices, or
+   `run/{...}-digest.md` regenerated per wave). NEVER mutate the raw log.
+
+## Entry tags (so the compactor can group and workers can scan)
+
+```
+[Agent-A | 020726 14:25:10.001] DECISION: notification.type enum = {in_app, email, system}.
+[USER via Agent-C | 020726 14:28:41.507] ANSWER: digest send = 07:00 fixed.
+[Agent-D | 020726 14:31:02.118] CONSTRAINT: pref model includes digest_frequency.
+[Agent-B | 020726 14:33:40.020] INTERFACE: NotificationAPI.list(paginated) — consumers use cursor param.
+```

package/templates/skills/orc/references/pattern-gate.md

@@ -0,0 +1,89 @@
+# Reference — Code-Pattern Gate (orchestrator side)
+
+How the full lane resolves, injects, and enforces per-language code-patterns so
+executors MATCH the existing codebase instead of writing generic-template code.
+The engine (playbooks, codifier slice, reconcile rules) is the sibling skill
+`../../orc-pattern/SKILL.md`; this file is the orchestrator's gate + wiring.
+Load at Phase 2 (tagging) and Phase 3 (resolve gate + slice injection).
+
+Principle: **conventions defer to the project; security/correctness invariants
+are always enforced.**
+
+## Phase 2 — Tag each task while scoring
+
+From its `declared_files` extensions + repo deps (see
+`../../orc-pattern/references/INDEX.md`):
+`{domain: FE|BE|null, lang: react|nextjs|vue|fastapi|nestjs|go|…|null}`.
+Tasks with no FE/BE language need no pattern.
+
+**Postgres secondary tag:** on a Postgres project (`pg`/`psycopg`/`asyncpg`/
+`pgx`/`lib/pq`/`Npgsql`/Prisma `postgresql`/`postgrex` in deps), add
+`db: postgres` to any task whose `declared_files` touch the data-access layer
+(repositories/dao/models/queries, `*.sql`, ORM entities/migrations). `db`
+co-applies WITH the framework `lang`, never instead of it — it pulls the
+cross-cutting `postgres` playbook into the same resolve gate.
+
+## Phase 3 — Resolve gate (once, before the first wave)
+
+For each distinct tagged language (including `postgres` when any task is
+`db`-tagged), resolve against the cache `.claude/orc/patterns/<lang>-pattern.md`
+— test existence with the deterministic probe `orc pattern status <lang>`
+(exit 0 = cached; see `../../_shared/detecting-artifacts.md`), never an ad-hoc
+`find`, so a codified pattern is never missed:
+
+Every resolved language prints exactly ONE user-visible line (no cost, no ask —
+visibility only, so the user always knows which house style is in force):
+
+- **Cache hit, no drift** → no ask, no cost, but print
+  `pattern: <lang>-pattern.md applied (cached)`.
+- **Cache miss** → apply config `pattern_findings` (default `ask`):
+  - `ask` → ONE P0 prompt batched across ALL missing languages ("Learn
+    conventions for {…} via orc-pattern, or proceed language-agnostic?");
+  - `on` → codify without asking; print `pattern: <lang> — codifying (cache miss)`;
+  - `off` → agnostic; print `pattern: <lang> — running language-agnostic (no cached pattern)`.
+- **On learn/`on`** → dispatch `orc-pattern-codifier-sonnet-5-high` per missing
+  language (`orc-pattern-codifier-opus-5-med` when `opus5_only` — see
+  `../../_shared/opus5-only.md`; slice per `../../orc-pattern/SKILL.md`
+  Phase 1); YOU write the returned pattern to the cache.
+- **Agnostic fallback** (declined / `off` / no playbook for the language): no
+  codifier, no scan — the executor enforces the universal invariants and
+  imitates the neighbor files it already reads. ~Zero added cost.
+
+Hold the resolved pattern per language in run state (survives
+checkpoint/resume) — it is injected at dispatch and reused at Phase 5/6.
+
+## Slice injection (anti-skip layer 1)
+
+Inject the resolved conventions + blocking invariants + the enforceable
+`validation_gate[]` lines LITERALLY into each FE/BE task's slice as `pattern` —
+never a file pointer. Agnostic tasks get the universal invariants only.
+
+**Gotchas ride BESIDE the pattern block, never inside it** (config `gotchas`;
+canonical `../../_shared/gotchas.md`). Same slice, same literal injection, one
+hard difference: the pattern applies to a LANGUAGE, so it goes to every task
+tagged with that language — a gotcha applies to a `scope` GLOB, so it goes only to
+tasks whose `declared_files` match it, capped at 3, highest `hits` first. Zero
+matches = no gotcha block at all. Never inject unfiltered: a pattern is what this
+project always does, a gotcha is what it got wrong ONCE, somewhere specific.
+
+For a `db:postgres`-tagged task, ALSO merge the resolved `postgres` pattern's
+Conventions + Invariants + gate lines into the SAME `pattern` block (appended
+to the framework pattern, or standalone if the task has no framework lang) —
+query invariants (bound params only, pooled connections, transactional
+multi-writes) ride the same anti-skip path. Record the postgres
+`pattern_version` in run state/log too.
+
+## Return validation (anti-skip layer 2)
+
+A task that was given a `pattern` must return `invariants_checked: true` + a
+`pattern_version` matching what you injected — the single attestation covers a
+merged block. Missing/false attestation = malformed return (requeue). Record
+the applied `pattern_version` in the trace.
+
+## Review/verify re-check (anti-skip layer 3)
+
+- **Phase 5 (review):** pass the resolved pattern as `code_pattern` AND its
+  blocking `invariants[]` + `validation_gate[]` lines for the re-check — don't
+  re-ask the user. An invariant violation or unmet gate line is P0.
+- **Phase 6 (verify):** pass the `validation_gate[]` lines in the slice — each
+  line is an acceptance criterion; an unmet line is P0.

package/templates/skills/orc/references/plan-handoff.md

@@ -0,0 +1,84 @@
+# Reference — Plan Handoff (executing a plan from another session)
+
+The entry contract for the case ORC had no defined path for: **the run input
+IS a plan**, not a request. A plan was produced in one session (or saved to a
+file) and handed to a fresh session to build. Load `references/plan-handoff.md`
+at Phase 0 the moment you recognise a plan input; it turns a pasted plan into a
+real ORC run instead of an ad-hoc task-by-task improvisation.
+
+## Trigger — the input IS a plan
+
+Recognise a plan input when the run starts from any of:
+
+- **pasted planning-output** — a YAML/markdown block matching
+  `schemas/planning-output.md` (has a `tasks:` list with `declared_files`,
+  `depends_on`, `grounding[]`);
+- **a `plan-{name}.md` path** the user points at;
+- **an `orc/planner/{name}/` checkpoint** (the planner's "Save & stop" artifact).
+
+A plain-language feature request is NOT a plan input — that is ordinary Phase 0
+intake. When in doubt (a prose paragraph with no task structure), treat it as a
+request and run intake normally.
+
+## Why this exists (the failure it prevents)
+
+A plan built in session A and executed in session B used to improvise: no spine
+load, no trace protocol (the hook bootstrapped a generic `run-*.txt`), no Phase
+1 exit gate re-run, no Phase 2 scoring or pause schedule, no Phase 3 wave
+grouping. The result was a bare SPAWN/RETURN trace, per-task ad-hoc pauses, and
+**phantom-file drift** — the plan declared a file that never (or no longer)
+existed, invisible because the plan's grounding Glob ran at *planning* time in
+the other session and nothing re-ran it here.
+
+## Mandatory sequence (never execute a plan task-by-task ad hoc)
+
+Do these IN ORDER before any dispatch. Skipping any step is a protocol
+violation.
+
+1. **This IS a run — bootstrap it.** Load the spine (`orc/SKILL.md`) and
+   `references/trace-protocol.md`; 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 (both, or neither — a pointer naming a file that does not
+   exist is what splits a run across two files), store `trace_path` in the
+   checkpoint. Record `PHASE intake start` into this phase's packet.
+2. **Schema-validate against `schemas/planning-output.md`.** Every task needs
+   `declared_files`, `grounding[]`, `depends_on`, `requirements[]`,
+   `acceptance[]`, `owns_area`, `spec_ref`, and the `facets` block (Part D). A
+   malformed plan → show exactly what field is missing and offer a re-plan via
+   `orc-planner` (dispatch it with the miss list). **Never improvise a missing
+   field** — a guessed `declared_files` or an invented `facets` vector defeats
+   the point of consuming a plan.
+3. **Staleness valve (`plan_head`).** The plan carries `plan_head` — HEAD at
+   plan time (the mirror of a requirement-spec's `git_head`). If `plan_head` ≠
+   current HEAD, OR the field is absent (a pre-v0.31.0 plan), the grounding
+   spot-check in step 4 is **compulsory** and its misses are surfaced, not
+   waved through. Matching heads still run the gate — they only lower the
+   suspicion.
+4. **Re-run the FULL Phase 1 exit gate in THIS session** (deterministic — the
+   checks live in `analyst-gates.md`; emit `GATE` lines): Glob every
+   `disposition: exists` path, recompute coverage (no `orphan` requirements),
+   cycle detection over `depends_on`, same-file collision over `declared_files`.
+   This is the deterministic catch for phantom-file drift — a declared path that
+   no longer (or never) existed bounces **before** any dispatch. On a miss,
+   offer a targeted re-ground (one `orc-planner` re-dispatch with the miss list)
+   or a user correction; never dispatch past an unresolved miss.
+5. **Relay unresolved `open_questions[]`** (Part E) in ONE batch before
+   proceeding: blocking questions must be answered; non-blocking show their
+   `proposed_default` for tacit approval. A `plan_confidence: low` plan →
+   recommend stepping back to `orc-analyze` (the user may override).
+6. **Then the NORMAL pipeline.** Emit `PHASE planning end`, then run Phase 2
+   (facet scoring + dispatch-style recommendation + the batch-pause schedule
+   question) → Phase 3 (wave grouping — waves are computed regardless of
+   dispatch style, see `wave-grouping.md`) → review → verify → ship. **A plan
+   input never skips Phase 2/3.** The plan supplied the tasks; the orchestrator
+   still owns scoring, waves, and pauses.
+
+## Not this
+
+- **Not** a re-plan. If the plan validates and grounds clean, DO NOT re-run the
+  planner — the plan is authoritative; you are scoring and scheduling it.
+- **Not** a scope re-litigation. Scope was settled where the plan (or its
+  upstream spec) was produced. The gate checks structural integrity, not intent.
+- **Not** a poly-spec path. A poly-spec (`orc-poly:spec`) is split-and-STOP at
+  Phase 1 (see SKILL.md) — that is a different input than a per-repo
+  planning-output handed here to build.