@azure-id/orc 1.9.2 → 2.0.2

package/templates/skills/_shared/phases/intake.md

@@ -1,133 +1,127 @@
-# Phase — Intake   (id: `intake`)
-
-> **Library file.** Canonical since v1.0.0 W12; it was under the `orc` skill's
-> private `references/`, and other lanes already reached across into it. Read
-> by `orc`, `orc-mini`, `orc-diy`, `orc-challenge`. Layers: `core` and `full`
-> — `core` is the intake procedure every lane runs; `full` is /orc's own Phase
-> 0, which adds the analyst branch, the poly-spec split-and-STOP and the run-
-> folder open. `orc lane phases <lane> --json` names the file and the layers
-> to read.
-
-<!-- orc:layer core -->
-## 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 (`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.
-
-<!-- /orc:layer -->
+# Phase — Intake   (id: `intake`)
+
+> **Library file** (`orc`, `orc-mini`, `orc-diy`, `orc-challenge`). `core` = the intake every lane runs; `full` = /orc's Phase 0 (adds the analyst branch, the poly-spec split-and-STOP and the run-folder open).
+
+<!-- orc:layer core -->
+## 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 (`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.
+
+<!-- /orc:layer -->

package/templates/skills/_shared/phases/mock-example.md

@@ -1,56 +1,46 @@
-# Phase — Mock example + drift recovery   (id: `mock-example`)
-
-> **Shared phase file.** Moved out of `orc/SKILL.md` at v1.0.0 W12, and into
-> this library at W13 when `orc-diy` became its second reader. A spine is loaded
-> IN FULL when its skill activates; this is loaded when the phase fires, and most
-> runs skip most phases.
->
-> **Two layers, and a lane reads exactly one.** `full` is `/orc`'s procedure.
-> `composed` is what `orc diy compile` stitches — the same phase expressed as
-> `<!-- diy:when -->` variants over a composed flow, NOT a second copy of the
-> procedure. Reading the wrong one is the failure `README.md` names: a lane
-> doing a phase its product promise says it does differently.
-> `orc lane phases <lane> --json` names the layer for each lane.
-
-<!-- orc:layer full -->
-
-## Mock example + drift recovery (config `mock_example`)
-
-Load `../drift-recovery.md` (canonical). Only after a GREEN Phase 6,
-before ship: `ask` (default) → the offer is MANDATORY (never silently skipped,
-never silently run); `on` → build; `off` → skip. Deliverable:
-`mock-examples/<change-slug>/` at the project root (`EXAMPLE.md` + one minimal
-runnable artifact; mocked inputs only) — **NEVER committed**. After the user
-runs it, ONE question: matches expectation? [yes / drift: <describe>]. On
-drift → `DRIFT-FROM` handoff → analyze-mini gap analysis → mini planner patch
-plan → scored dispatch → re-verify → re-offer; **hard cap 2 loops**, then an
-honest unresolved report. Emit `DRIFT loop=<n>` per loop; end-of-phase packet.
-
-<!-- /orc:layer -->
-
-<!-- orc:layer composed -->
-
-## Phase: Mock example (after a green verify, before ship)
-
-<!-- diy:when mock_example=off -->
-The mock-example phase is DISABLED in this flow. Skip silently.
-<!-- /diy:when -->
-<!-- diy:when mock_example=ask -->
-After the verify/smoke gate is GREEN and BEFORE any ship action, the offer is
-MANDATORY (never silently skipped, never silently run): follow
-`.claude/skills/_shared/drift-recovery.md` — build
-`mock-examples/<change-slug>/` (EXAMPLE.md + one minimal runnable mocked
-artifact) only on a yes. After the user runs it, ask the one drift question;
-on drift run the `DRIFT-FROM` recovery loop (hard cap 2, then an honest
-unresolved report). `mock-examples/` is NEVER staged by the ship phase.
-<!-- /diy:when -->
-<!-- diy:when mock_example=on -->
-After the verify/smoke gate is GREEN and BEFORE any ship action, build the
-mocked example without asking, per
-`.claude/skills/_shared/drift-recovery.md`: `mock-examples/<change-slug>/`
-(EXAMPLE.md + one minimal runnable mocked artifact; mocked inputs only). Then
-ask the one drift question; on drift run the `DRIFT-FROM` recovery loop (hard
-cap 2). `mock-examples/` is NEVER staged by the ship phase.
-<!-- /diy:when -->
-
-<!-- /orc:layer -->
+# Phase — Mock example + drift recovery   (id: `mock-example`)
+
+> **Shared phase file** — read when the phase fires. A lane reads ONE layer: `full` (`/orc`) or `composed` (the `<!-- diy:when -->` variants `orc diy compile` stitches). `orc lane phases <lane> --json` names it.
+
+<!-- orc:layer full -->
+
+## Mock example + drift recovery (config `mock_example`)
+
+Load `../drift-recovery.md` (canonical). Only after a GREEN Phase 6,
+before ship: `ask` (default) → the offer (H `orc.phase-6-7.mock`) is MANDATORY (never silently skipped,
+never silently run); `on` → build; `off` → skip. Deliverable:
+`mock-examples/<change-slug>/` at the project root (`EXAMPLE.md` + one minimal
+runnable artifact; mocked inputs only) — **NEVER committed**. After the user
+runs it, ONE question: matches expectation? [yes / drift: <describe>]. On
+drift → `DRIFT-FROM` handoff → analyze-mini gap analysis → mini planner patch
+plan → scored dispatch → re-verify → re-offer; **hard cap 2 loops**, then an
+honest unresolved report. Emit `DRIFT loop=<n>` per loop; end-of-phase packet.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Mock example (after a green verify, before ship)
+
+<!-- diy:when mock_example=off -->
+The mock-example phase is DISABLED in this flow. Skip silently.
+<!-- /diy:when -->
+<!-- diy:when mock_example=ask -->
+After the verify/smoke gate is GREEN and BEFORE any ship action, the offer is
+MANDATORY (never silently skipped, never silently run): follow
+`.claude/skills/_shared/drift-recovery.md` — build
+`mock-examples/<change-slug>/` (EXAMPLE.md + one minimal runnable mocked
+artifact) only on a yes. After the user runs it, ask the one drift question;
+on drift run the `DRIFT-FROM` recovery loop (hard cap 2, then an honest
+unresolved report). `mock-examples/` is NEVER staged by the ship phase.
+<!-- /diy:when -->
+<!-- diy:when mock_example=on -->
+After the verify/smoke gate is GREEN and BEFORE any ship action, build the
+mocked example without asking, per
+`.claude/skills/_shared/drift-recovery.md`: `mock-examples/<change-slug>/`
+(EXAMPLE.md + one minimal runnable mocked artifact; mocked inputs only). Then
+ask the one drift question; on drift run the `DRIFT-FROM` recovery loop (hard
+cap 2). `mock-examples/` is NEVER staged by the ship phase.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

package/templates/skills/_shared/phases/plan-handoff.md

@@ -1,97 +1,91 @@
-# Phase — Plan handoff   (id: `plan-handoff`)
-
-> **Library file.** Canonical since v1.0.0 W12; it was under the `orc` skill's
-> private `references/`, and another lane already reached across into it. Read
-> by `orc`, `orc-route`. Layers declared: `core` only — single-layer because
-> executing a plan another session wrote is the same procedure wherever it is
-> done, and /orc-route reads it to DEFINE what a plan is (v0.42.0 — a second
-> definition is drift the lint cannot see). `orc lane phases <lane> --json`
-> names the file and the layers to read.
-
-<!-- orc:layer core -->
-## 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 `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
-   `../../_shared/phases/trace.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.
-
-<!-- /orc:layer -->
+# Phase — Plan handoff   (id: `plan-handoff`)
+
+> **Library file** (`orc`, `orc-route`), `core` only: executing another session's plan is one procedure, and /orc-route reads this file to DEFINE a plan — a second definition is drift.
+
+<!-- orc:layer core -->
+## 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 `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
+   `../../_shared/phases/trace.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.
+
+<!-- /orc:layer -->