@azure-id/orc 1.9.1 → 2.0.2

package/templates/skills/_shared/opus5-only.md

@@ -22,11 +22,11 @@ mixed-model table:
 | `[90,100]` | `orc-executor-opus-5-med`  |
 
 Two bands, sharing the 90 edge with the default table's top two rows. Since
-v1.0.0 the default table's high end is ALREADY Opus 5 with effort as the dial,
+v1.0.0 the default table's high end is ALREADY Opus 5.5 with effort as the dial,
 so this mode differs from it only below 65 — a third band here would be a
 distinction the default table stopped making.
 
-**Fixed roles** — dispatch the Opus 5 variant **instead of** the default role
+**Fixed roles** — dispatch the Opus 5.5 variant **instead of** the default role
 agent: same task slice, same return contract, same phase.
 
 | Role | Default agent | Opus-5-only variant |
@@ -41,14 +41,14 @@ agent: same task slice, same return contract, same phase.
 | claude write | `orc-claude-writer-opus-4-8-high` | `orc-claude-writer-opus-5-med` |
 | retro mine | `orc-retro-sonnet-5-high` | `orc-retro-opus-5-med` |
 
-The nine roles already pinned to `claude-opus-5` — analyst, planner, reviewer,
+The nine roles already pinned to `claude-opus-5-5` — analyst, planner, reviewer,
 verifier, test-author, combiner, learn-writer, advisor, judge — are already
 compliant and dispatch unchanged (their efforts are NOT rewritten by this mode).
 
 **The wiki scan tier ladder (v0.46.0) adds NO row here, and needs no new pair.**
 Off, the ladder picks deep or light per delta. ON, this mode already forces the
 wiki scanner to `orc-wiki-scanner-opus-5-med` — so **both tiers collapse onto that
-one shipped agent** and the ladder simply stops applying. A cheaper Opus 5 scanner
+one shipped agent** and the ladder simply stops applying. A cheaper Opus 5.5 scanner
 variant for the light tier does not exist and must never be added: a pair for a
 tier that cannot occur while the flag is on is exactly the phantom this table
 exists to prevent. Ladder: `../orc-wiki/references/partial-refresh.md`.
@@ -58,7 +58,7 @@ exists to prevent. Ladder: `../orc-wiki/references/partial-refresh.md`.
 - **`orc-trace-writer-haiku-4-5` stays Haiku 4.5.** It transcribes a packet the
   orchestrator hands it — no reasoning, no source reads. It is never in the
   roster.
-- **`orc-graph-noter-sonnet-4-6-med` is not dispatched at all.** It has no Opus 5
+- **`orc-graph-noter-sonnet-4-6-med` is not dispatched at all.** It has no Opus 5.5
   variant: under the mode a code lane skips graph notes and prints
   `graph notes: skipped (opus5_only)` (`code-graph.md` §6). The graph's structure
   layer costs no model, so nothing else about the graph changes.
@@ -73,7 +73,7 @@ exists to prevent. Ladder: `../orc-wiki/references/partial-refresh.md`.
   the lane SAYS so at the gate (`orc-quick ignores opus5_only — both options are
   live`), because a shadowed setting must never be silent in either direction.
 - **`/orc-challenge` — UNAFFECTED, not exempt.** All three of its agents are
-  already `claude-opus-5` (judge high, advisor medium, reader low), so the mode
+  already `claude-opus-5-5` (judge high, advisor medium, reader low), so the mode
   has nothing to force: zero new pairs, no rename churn, no roster row. The
   reader's `low` effort is a MEASUREMENT choice, not a cost one — a
   harder-thinking cold reader reasons around exactly the gaps D4 exists to find
@@ -102,7 +102,7 @@ mode is neither shadowed nor shadowing — it is simply **NOT CONSULTED** for th
 work extra took:
 
 - **a scored task** — an extra route row covering that score outranks the mode;
-  every score no row covers still resolves on the Opus 5 ladder.
+  every score no row covers still resolves on the Opus 5.5 ladder.
 - **a POSITION** (v0.55.0 — `quick-executor`, `fast-executor`, `doc-writer`,
   `doc-checker`, `wiki-scanner-deep`, `wiki-scanner-light`) — an extra slot row
   holding that position outranks the mode's variant of that slot's agent; **a
@@ -121,7 +121,7 @@ POSITION, not the model.
 ## Tier honesty
 
 A subagent can never outrank the main session. With the mode ON, EVERY dispatch
-needs an Opus 5 main session — not just the top executor band. On a lower
+needs an Opus 5.5 main session — not just the top executor band. On a lower
 session every role silently falls back to the session model and the tier-honesty
 rule (`return-validation.md`) reports a downgrade on **every** return. That is
 correct behavior, not a bug: hooks cannot block on model, only on effort, so the

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

@@ -1,83 +1,142 @@
-# `_shared/phases/` — one copy of a phase, and a manifest per lane
-
-This directory is NOT a skill and NOT a lane. It holds the single canonical copy
-of a phase that **two or more lanes run**. A lane's spine keeps its identity, its
-trigger, its own hard rules and its own phases — and for a shared phase it keeps
-only a POINTER plus that lane's own deltas.
-
-**The CLI owns the pipeline, not the prose.** `orc lane phases <lane> [--json]`
-is the manifest: the ordered phase list, the file each phase lives in, the layers
-that lane reads, the catalogued calls it makes, and when to read it. A skill
-never derives the phase list or its order from these filenames — the same rule
-the Flow stepper follows, for the same reason: *a second idea of the pipeline is
-the drift this exists to make impossible.*
-
-## What belongs here — the rule is mechanical
-
-> A file under `templates/skills/<lane>/` that a file in a DIFFERENT lane already
-> points at belongs here. **A file with exactly one consumer stays home.**
-
-That is auditable by grep, which is what makes it a lint rather than an opinion.
-`bin/verify-contracts.js` asserts both halves: nothing under a lane folder may be
-pointed at from another lane, and every file here must be claimed by **≥2 lanes**.
-
-Centralizing a one-consumer file is centralizing for its own sake, and it costs a
-lane its own wording for nothing.
-
-## The layer set is CLOSED
-
-A phase file may be cut into layers with the same marker grammar `orc diy
-compile` already parses (`<!-- diy:when key=value -->`):
-
-```markdown
-<!-- orc:layer core -->
-Every lane that runs this phase does this. Never optional.
-<!-- /orc:layer -->
-
-<!-- orc:layer trim -->
-orc-mini / orc-fast: ONE executor, no waves. This is a REDUCTION and it is
-deliberate — do not read the `full` layer here.
-<!-- /orc:layer -->
-```
-
-| Layer | Read by | Meaning |
-|---|---|---|
-| `core` | every lane running this phase | the invariant. Never optional |
-| `full` | `/orc`, `/orc-ultra` | the complete procedure |
-| `trim` | `orc-mini`, `orc-fast` | an explicit REDUCTION, stated as one |
-| `composed` | `orc-diy` | what `orc diy compile` stitches |
-
-**Four names, closed. A fifth layer is a lint failure, not a feature** — free
-markers are drift with extra steps. A lane reads `core` plus at most one other
-layer, and `orc lane phases` tells it which.
-
-**Why the set exists at all:** the single biggest way this library breaks ORC is
-`orc-mini` reading a shared `review.md` written for the full lane and starting to
-do a full code review. Mini's product promise is that it *skips* review.
-Centralizing without layers does not just cost tokens — it changes behaviour. So
-**a `trim` layer must say what it drops and that dropping it is deliberate.**
-
-**A single-layer file is a legitimate answer.** `trace.md` and `stop-resume.md`
-declare `core` only: their procedure really is identical in every lane that runs
-them, and what varies is DATA (the tier table, the lane token), not prose. Cutting
-them into layers to look symmetrical would be inventing structure the phase does
-not have.
-
-## Pointer discipline
-
-Every pointer a spine adds declares `when` and `read` — the partial-read rules in
-`../read-ladder.md`. `on-phase` is the default; `always` must be justified in the
-release's findings; a `read:` names a HEADING and **never a line number**
-(`/orc-doc` rule 2 — a stored line number is a wrong line number one edit later).
-
-## What is here
-
-| File | id | Layers | Lanes |
-|---|---|---|---|
-| `trace.md` | `trace` | `core` | every trace-owning lane (28) |
-| `preflight.md` | `preflight` | `core`, `full` | the silent-probe lanes (15) |
-| `stop-resume.md` | `stop-resume` | `core` | `orc`, `orc-wiki`, `orc-diy` |
-| `rules.md` | `rules` | `core` | every lane that writes words or code (28) — **never `orc-doc`** |
-
-`orc lane phases --all --json` is the authoritative list; this table is a
-human index of it.
+# `_shared/phases/` — one copy of a phase, and a manifest per lane
+
+This directory is NOT a skill and NOT a lane. It holds the single canonical copy
+of a phase that **two or more lanes run**. A lane's spine keeps its identity, its
+trigger, its own hard rules and its own phases — and for a shared phase it keeps
+only a POINTER plus that lane's own deltas.
+
+**The CLI owns the pipeline, not the prose.** `orc lane phases <lane> [--json]`
+is the manifest: the ordered phase list, the file each phase lives in, the layers
+that lane reads, the catalogued calls it makes, and when to read it. A skill
+never derives the phase list or its order from these filenames — the same rule
+the Flow stepper follows, for the same reason: *a second idea of the pipeline is
+the drift this exists to make impossible.*
+
+## What belongs here — the rule is mechanical
+
+> A file under `templates/skills/<lane>/` that a file in a DIFFERENT lane already
+> points at belongs here. **A file with exactly one consumer stays home.**
+
+That is auditable by grep, which is what makes it a lint rather than an opinion.
+`bin/verify-contracts.js` asserts both halves: nothing under a lane folder may be
+pointed at from another lane, and every file here must be claimed by **≥2 lanes**.
+
+Centralizing a one-consumer file is centralizing for its own sake, and it costs a
+lane its own wording for nothing.
+
+## The layer set is CLOSED
+
+A phase file may be cut into layers with the same marker grammar `orc diy
+compile` already parses (`<!-- diy:when key=value -->`):
+
+```markdown
+<!-- orc:layer core -->
+Every lane that runs this phase does this. Never optional.
+<!-- /orc:layer -->
+
+<!-- orc:layer trim -->
+orc-mini / orc-fast: ONE executor, no waves. This is a REDUCTION and it is
+deliberate — do not read the `full` layer here.
+<!-- /orc:layer -->
+```
+
+| Layer | Read by | Meaning |
+|---|---|---|
+| `core` | every lane running this phase | the invariant. Never optional |
+| `full` | `/orc`, `/orc-ultra` | the complete procedure |
+| `trim` | `orc-mini`, `orc-fast` | an explicit REDUCTION, stated as one |
+| `composed` | `orc-diy` | what `orc diy compile` stitches |
+
+**Four names, closed. A fifth layer is a lint failure, not a feature** — free
+markers are drift with extra steps. A lane reads `core` plus at most one other
+layer, and `orc lane phases` tells it which.
+
+**Why the set exists at all:** the single biggest way this library breaks ORC is
+`orc-mini` reading a shared `review.md` written for the full lane and starting to
+do a full code review. Mini's product promise is that it *skips* review.
+Centralizing without layers does not just cost tokens — it changes behaviour. So
+**a `trim` layer must say what it drops and that dropping it is deliberate.**
+
+**A single-layer file is a legitimate answer.** `trace.md` and `stop-resume.md`
+declare `core` only: their procedure really is identical in every lane that runs
+them, and what varies is DATA (the tier table, the lane token), not prose. Cutting
+them into layers to look symmetrical would be inventing structure the phase does
+not have.
+
+## Pointer discipline — the partial-read rules (v1.0.0 W10)
+
+Every pointer a spine adds declares `when` and `read`. `on-phase` is the
+default; `always` must be justified in the release's findings; a `read:` names
+a HEADING and **never a line number** (`/orc-doc` rule 2 — a stored line number
+is a wrong line number one edit later). **Rule of 2.0.0:** every new shared file
+is `on-phase` or `on-demand`, never `always`, and a new CLI answer is brief by
+default (the full rows only on request). This section is for the
+ORCHESTRATOR; an executor or a recon agent reads only `../read-ladder.md`.
+
+### Reading ORC's own payload
+
+The read ladder (`../read-ladder.md`) is about reading the PROJECT. It
+applies unchanged to reading ORC's own files, and it has to: a lane manifest of
+pointers that every lane dutifully reads whole is MORE round-trips than the prose it replaced, for the
+same bytes. Centralizing prose and then reading all of it is a slower payload,
+not a smaller one.
+
+So every pointer a lane carries declares three things.
+
+| Declaration | Values | Means |
+|---|---|---|
+| `when` | `always` · `on-phase` · `on-state` · `on-demand` · `compile-time` | WHETHER to open it at all |
+| `read` | `layer` · `section` · `whole` | HOW MUCH to open |
+| `layers` | `core` · `full` · `trim` · `composed` | WHICH part, when `read: layer` |
+
+#### The five rules that make it honest
+
+1. **`on-phase` is the default, and `always` must be justified.** A file every
+   lane always loads has saved nothing by moving. Each `always` pointer is
+   named in the wave that adds it.
+2. **`read: section` names a HEADING, never a line number.** A stored line
+   number is a wrong line number one edit later; a heading anchor survives an
+   edit above it. This is why a shared file's headings are part of its
+   contract — renaming one breaks every pointer into it.
+3. **A trimmed lane reads `core` plus its OWN layer, and never the `full`
+   layer.** Reading a neighbouring layer "for context" is the bleed this rule
+   exists to stop: the layer boundary is the product promise, not a suggestion.
+4. **The two exceptions of `../read-ladder.md` carry over unchanged.** A file
+   you will EDIT is read in full, first, always; and output a gate parses is read whole.
+5. **`compile-time` is not a run-time read at all.** `orc-diy` is a declared
+   reader of ten shared phases and opens none of them during a run: the `orc
+   diy compile` CLI reads their `composed` layer once and stitches it into
+   `FLOW-COMPILED.md`, which is the only spine that run then follows. Saying
+   `on-phase` there would describe a read that never happens, and a manifest
+   that describes a run nobody performs is the drift it exists to prevent
+   (v1.0.0 W13).
+
+#### The honest limit
+
+A partial read saves round-trips and bytes for the lanes that SKIP a phase. It
+does **not** make a phase cheaper for the lane that runs it — that lane reads
+its layers whole. Any claim otherwise has to show the measurement.
+
+### Why the ladder exists
+
+ORC's cost is dominated by parallel reading, not by thinking: up to `max_scouts`
+scouts at once, a wiki scan that is expensive by design, and every executor in a
+wave opening its declared files. A role that opens a 900-line file to learn one
+function's shape has spent the run's budget on bytes nobody needed. Reading more
+is not understanding more.
+
+What a lane INVOKES, and what each exit code means, is not in this file: that is
+`orc lane calls <lane> --json`, whose catalogue is the one copy of every call
+two or more lanes share.
+
+## What is here
+
+| File | id | Layers | Lanes |
+|---|---|---|---|
+| `trace.md` | `trace` | `core` | every trace-owning lane (28) |
+| `preflight.md` | `preflight` | `core`, `full` | the silent-probe lanes (15) |
+| `stop-resume.md` | `stop-resume` | `core` | `orc`, `orc-wiki`, `orc-diy` |
+| `rules.md` | `rules` | `core` | every lane that writes words or code (28) — **never `orc-doc`** |
+
+`orc lane phases --all --json` is the authoritative list; this table is a
+human index of it.

package/templates/skills/_shared/phases/analyst-gates.md

@@ -1,136 +1,125 @@
-# Phase — Analyst & plan gates   (id: `analyst-gates`)
-
-> **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-analyze`, `orc-mini`. Layers declared: `core` only — single-
-> layer because these are the orchestrator-side gates on a returned analysis
-> or plan, and a trimmed lane runs fewer of them rather than different ones.
-> `orc lane phases <lane> --json` names the file and the layers to read.
-
-<!-- orc:layer core -->
-## Reference — Analyst, Combiner & Plan Gates (orchestrator side)
-
-The orchestrator's deterministic gates around the analyst, the
-context-combiner, and the planner. The roles themselves are defined in
-`../../orc-analyze/SKILL.md`, `../../context-combiner/SKILL.md`, and
-`../../orc/subskills/orc-planner/SKILL.md` — this file is what YOU do around their
-dispatches and returns. Load at Phase 0 (analyst dispatch) and Phase 1
-(planner return). Emit a `GATE` trace line (pass|bounce) per check when
-logging.
-
-## Deep-mode scout dispatch (yours)
-
-When the analyst runs in deep mode it returns a `scout_plan` (pass 1). You then
-dispatch ≤ `config.max_scouts` (default 3) parallel
-`orc-scout-sonnet-4-6-high` agents (`orc-scout-opus-5-low` when `opus5_only`
-— `../../_shared/opus5-only.md`; scouts fan out in PARALLEL, so this is the
-mode's largest single cost multiplier) — one coverage area each, read-only — and
-re-dispatch the analyst WITH their evidence bundles for pass 2. Same "return a
-request → you re-slice → re-dispatch" shape as `needs_context`. You never
-analyze; you only dispatch and relay.
-
-## Analyst-return gates (deterministic, before any build option)
-
-1. **Evidence spot-check:** Glob every `files[]` path in the spec +
-   Grep-verify the quoted snippet on **EVERY quote-anchored ref, whatever its
-   `status`** (v0.34.6). It used to check only `exists|conflict` — but the two
-   statuses a GOOD audit most often produces are `resolved` (a challenged row
-   the user decided) and `buildable` (the actual work), so a correctly-triaged
-   analysis was the one the gate barely checked: a real spec had zero
-   `exists|conflict` rows, so the mandated verification covered 0 of 5 refs and
-   a `file:5` citing a quote that lives at `file:4` went through. It is one
-   Grep per ref, and it is the ONLY mechanical defence against a wrong line
-   number reaching the planner. Note the causal shape: that ref started as a
-   line RANGE with no quote (auto-UNVERIFIED per hard rule 2); narrowing it to
-   one line + quote was the CORRECT fix and is what introduced the off-by-one —
-   tightening evidence granularity is itself an error surface, so the gate has
-   to be what catches it.
-2. **Derivation lint:** R# ids, statuses, and context-anchor set must match
-   between report.md and requirement-spec.md.
-
-Any miss → bounce to the analyst with the miss list (one retry, then escalate
-to the user). Refuse take-into-build when the spec has open `UNVERIFIED` or
-lacks `scope_closed: true` (a one-Grep check).
-
-## Combiner tracking (yours; full lane only)
-
-`context-combiner` (`orc-context-combiner-opus-5-high` — Opus 5 high, v0.34.0)
-merges 2+ RELATED, already-confirmed
-analyses from the same run into ONE combined requirement-spec before build.
-
-- **Track the analysis set:** hold the confirmed spec paths of every analysis
-  this run in run state (survives checkpoint/resume).
-- When the user picks "pass to context-combiner" at orc-analyze's Phase F
-  branch menu (offered only once 2+ analyses exist), dispatch
-  `orc-context-combiner-opus-5-high` with that list.
-- The return carries `combined_spec_path` + `coverage_pct` (conservation
-  proof — every source requirement accounted for; must be 100) + `dropped[]` +
-  `stale_evidence[]` + `handoff_ready` — or `combined: false` if the user chose
-  keep-separate at the combiner's relatedness challenge (then fall back to
-  per-analysis stop/build).
-- Offer the build option ONLY when `handoff_ready` is true (the combiner sets
-  it false when `coverage_pct` < 100 OR a conflict is open). On build, continue
-  at Phase 1 with the combined spec exactly like a single requirement-spec.
-
-You never combine; you only track, dispatch, and relay.
-
-## Spec staleness valve (Phase 1, before dispatching the planner)
-
-If the requirement-spec's `git_head` ≠ current HEAD (analysis and build in
-different sessions), re-run the analyst evidence spot-check (paths + quotes)
-BEFORE dispatching the planner; on misses offer re-analyze vs
-proceed-with-flagged.
-
-## Phase 1 exit gate (deterministic, before scoring)
-
-1. **Grounding spot-check:** Glob every path the plan marks
-   `disposition: exists`. A task whose declared paths lack `grounding[]`
-   entries counts as a miss.
-2. **Coverage check:** recompute the planner's coverage echo — every in-scope
-   spec R# / intent-spec DoD line must appear in ≥ 1 task's `requirements[]`;
-   an `orphan` requirement is a miss (the user may explicitly descope instead).
-3. **Graph checks:** cycle detection over `depends_on` + same-file collision
-   over `declared_files` (two tasks sharing a file need a serializing dep or a
-   merge). Both trivial at ≤ 20 tasks — never trust the planner's self-check
-   alone.
-4. **TDD/test-task collision (v0.34.4):** a `tdd_spec` entry whose target file
-   is in the `declared_files` of a task whose `facets.test_surface` is
-   `new-tests` is a miss. The paired TDD task materializes `tdd_spec` BEFORE the
-   task it guards, so that task's planned work is already on disk and
-   green by the time its wave opens — leaving only bad options (dispatch a
-   no-op, silently drop promised coverage, or re-slice mid-run). The planner
-   authored both mechanisms and folds them together itself: extend the
-   materialized file, never re-author it.
-5. **TDD disposition gate (v0.41.0)** — this gate is what lets TDD be skipped
-   safely. Skipping a test is cheap to claim and expensive to get wrong, so
-   every skip must be checkable, and it is checked in BOTH directions: a rule
-   that only ever prevents tests is a rule that deletes coverage.
-   - `disposition` outside the closed set
-     `new-surface | behavior-change | covered-by-existing | no-behavior | no-runner`
-     → miss. (Absent on a pre-v0.41.0 plan → derive from `kind`; never bounce an
-     old plan — see the legacy exception below.)
-   - `covered-by-existing` **without a resolvable `covered_by`** → miss. Glob the
-     cited `path` exactly as check 1 does for `disposition: exists`. "A test
-     already covers this" is the one claim that, if false, silently removes
-     coverage the run promised.
-   - `no-behavior` whose task has `facets.test_surface != none` → miss
-     (self-contradiction: the planner said the surface is testable and that it
-     isn't).
-   - **Safety floor:** any entry that is `covered-by-existing` or `no-behavior`
-     on a task with non-empty `facets.risk[]` → miss, no exceptions. Auth,
-     money, migration, security, concurrency and data-integrity requirements do
-     not ride on another test's coincidence.
-   - `new-surface` / `behavior-change` missing `skeleton` or `given_when_then`
-     → miss.
-   - A disposition that DEVIATES from the derivation table in
-     `../../orc/schemas/planning-output.md` without a `reason` → miss. The derivation
-     is the default; departing from it is the thing that needs justifying.
-
-Any miss → the plan is malformed: bounce it back to the planner WITH the miss
-list (one retry), then escalate to the user. **Legacy exception:** a
-pre-v0.7.0 plan resumed from an old checkpoint has no `grounding[]`
-(pre-v0.9.0: no `requirements[]`/`spec_invariants[]`; pre-v0.41.0: no
-`disposition`) — resume it without the
-missing checks; never bounce an old plan.
-
-<!-- /orc:layer -->
+# Phase — Analyst & plan gates   (id: `analyst-gates`)
+
+> **Library file** (`orc`, `orc-analyze`, `orc-mini`), `core` only: the orchestrator-side gates on a returned analysis or plan — a trimmed lane runs fewer of them, never different ones.
+
+<!-- orc:layer core -->
+## Reference — Analyst, Combiner & Plan Gates (orchestrator side)
+
+The orchestrator's deterministic gates around the analyst, the
+context-combiner, and the planner. The roles themselves are defined in
+`../../orc-analyze/SKILL.md`, `../../context-combiner/SKILL.md`, and
+`../../orc/subskills/orc-planner/SKILL.md` — this file is what YOU do around their
+dispatches and returns. Load at Phase 0 (analyst dispatch) and Phase 1
+(planner return). Emit a `GATE` trace line (pass|bounce) per check when
+logging.
+
+## Deep-mode scout dispatch (yours)
+
+When the analyst runs in deep mode it returns a `scout_plan` (pass 1). You then
+dispatch ≤ `config.max_scouts` (default 3) parallel
+`orc-scout-sonnet-4-6-high` agents (`orc-scout-opus-5-low` when `opus5_only`
+— `../../_shared/opus5-only.md`; scouts fan out in PARALLEL, so this is the
+mode's largest single cost multiplier) — one coverage area each, read-only — and
+re-dispatch the analyst WITH their evidence bundles for pass 2. Same "return a
+request → you re-slice → re-dispatch" shape as `needs_context`. You never
+analyze; you only dispatch and relay.
+
+## Analyst-return gates (deterministic, before any build option)
+
+1. **Evidence spot-check:** Glob every `files[]` path in the spec +
+   Grep-verify the quoted snippet on **EVERY quote-anchored ref, whatever its
+   `status`** — `resolved` and `buildable` included: they are the rows a GOOD
+   audit produces most. It is one Grep per ref, and it is the ONLY mechanical defence against a wrong line
+   number reaching the planner. Note the causal shape: that ref started as a
+   line RANGE with no quote (auto-UNVERIFIED per hard rule 2); narrowing it to
+   one line + quote was the CORRECT fix and is what introduced the off-by-one —
+   tightening evidence granularity is itself an error surface, so the gate has
+   to be what catches it.
+2. **Derivation lint:** R# ids, statuses, and context-anchor set must match
+   between report.md and requirement-spec.md.
+
+Any miss → bounce to the analyst with the miss list (one retry, then escalate
+to the user). Refuse take-into-build when the spec has open `UNVERIFIED` or
+lacks `scope_closed: true` (a one-Grep check).
+
+## Combiner tracking (yours; full lane only)
+
+`context-combiner` (`orc-context-combiner-opus-5-high` — Opus 5.5 high)
+merges 2+ RELATED, already-confirmed
+analyses from the same run into ONE combined requirement-spec before build.
+
+- **Track the analysis set:** hold the confirmed spec paths of every analysis
+  this run in run state (survives checkpoint/resume).
+- When the user picks "pass to context-combiner" at orc-analyze's Phase F
+  branch menu (offered only once 2+ analyses exist), dispatch
+  `orc-context-combiner-opus-5-high` with that list.
+- The return carries `combined_spec_path` + `coverage_pct` (conservation
+  proof — every source requirement accounted for; must be 100) + `dropped[]` +
+  `stale_evidence[]` + `handoff_ready` — or `combined: false` if the user chose
+  keep-separate at the combiner's relatedness challenge (then fall back to
+  per-analysis stop/build).
+- Offer the build option ONLY when `handoff_ready` is true (the combiner sets
+  it false when `coverage_pct` < 100 OR a conflict is open). On build, continue
+  at Phase 1 with the combined spec exactly like a single requirement-spec.
+
+You never combine; you only track, dispatch, and relay.
+
+## Spec staleness valve (Phase 1, before dispatching the planner)
+
+If the requirement-spec's `git_head` ≠ current HEAD (analysis and build in
+different sessions), re-run the analyst evidence spot-check (paths + quotes)
+BEFORE dispatching the planner; on misses offer re-analyze vs
+proceed-with-flagged.
+
+## Phase 1 exit gate (deterministic, before scoring)
+
+1. **Grounding spot-check:** Glob every path the plan marks
+   `disposition: exists`. A task whose declared paths lack `grounding[]`
+   entries counts as a miss.
+2. **Coverage check:** recompute the planner's coverage echo — every in-scope
+   spec R# / intent-spec DoD line must appear in ≥ 1 task's `requirements[]`;
+   an `orphan` requirement is a miss (the user may explicitly descope instead).
+3. **Graph checks:** cycle detection over `depends_on` + same-file collision
+   over `declared_files` (two tasks sharing a file need a serializing dep or a
+   merge). Both trivial at ≤ 20 tasks — never trust the planner's self-check
+   alone.
+4. **TDD/test-task collision:** a `tdd_spec` entry whose target file
+   is in the `declared_files` of a task whose `facets.test_surface` is
+   `new-tests` is a miss. The paired TDD task materializes `tdd_spec` BEFORE the
+   task it guards, so that task's planned work is already on disk and
+   green by the time its wave opens — leaving only bad options (dispatch a
+   no-op, silently drop promised coverage, or re-slice mid-run). The planner
+   authored both mechanisms and folds them together itself: extend the
+   materialized file, never re-author it.
+5. **TDD disposition gate** — this gate is what lets TDD be skipped
+   safely. Skipping a test is cheap to claim and expensive to get wrong, so
+   every skip must be checkable, and it is checked in BOTH directions: a rule
+   that only ever prevents tests is a rule that deletes coverage.
+   - `disposition` outside the closed set
+     `new-surface | behavior-change | covered-by-existing | no-behavior | no-runner`
+     → miss. (No `disposition` on an entry → derive it from `kind`; never bounce
+     the plan — see the legacy exception below.)
+   - `covered-by-existing` **without a resolvable `covered_by`** → miss. Glob the
+     cited `path` exactly as check 1 does for `disposition: exists`. "A test
+     already covers this" is the one claim that, if false, silently removes
+     coverage the run promised.
+   - `no-behavior` whose task has `facets.test_surface != none` → miss
+     (self-contradiction: the planner said the surface is testable and that it
+     isn't).
+   - **Safety floor:** any entry that is `covered-by-existing` or `no-behavior`
+     on a task with non-empty `facets.risk[]` → miss, no exceptions. Auth,
+     money, migration, security, concurrency and data-integrity requirements do
+     not ride on another test's coincidence.
+   - `new-surface` / `behavior-change` missing `skeleton` or `given_when_then`
+     → miss.
+   - A disposition that DEVIATES from the derivation table in
+     `../../orc/schemas/planning-output.md` without a `reason` → miss. The derivation
+     is the default; departing from it is the thing that needs justifying.
+
+Any miss → the plan is malformed: bounce it back to the planner WITH the miss
+list (one retry), then escalate to the user. **Legacy exception:** a
+plan resumed from an old checkpoint may lack `grounding[]`,
+`requirements[]`/`spec_invariants[]` or `disposition` — resume it without the
+missing checks; never bounce an old plan.
+
+<!-- /orc:layer -->

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

@@ -1,16 +1,6 @@
 # Phase — Execution   (id: `execution`)
 
-> **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.
+> **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 -->
 
@@ -60,8 +50,12 @@ the codifier); hold resolved patterns in run state.
    `trace_extras[]` entry VERBATIM into the packet — the CLI composes them, and the
    hook emits NO `SPAWN`/`RETURN` for a foreign worker, so they are the whole record.
 2. Record worker milestone pings (they bound what a mid-wave stop can save).
-3. Collect returns; VALIDATE each (emit `VERIFY <task> actual=<model>/<effort>`
-   ✅ MATCH / ⛔ DOWNGRADE per return — surface any downgrade to the user).
+3. Collect returns; VALIDATE each — read `_shared/return-validation.md` §1–§3,
+   then ONLY the § of each field the slice carried (§4 `pattern`, §5 `tdd_spec`,
+   §5b wiki, §5b.1 graph, §5c `rules_card`, §5d `repro`); §0 only before a
+   re-dispatch, §6 only after the wave, §7 only on a repair loop. Emit
+   `VERIFY <task> actual=<model>/<effort>` ✅ MATCH / ⛔ DOWNGRADE per return —
+   surface any downgrade to the user.
    **A FOREIGN return runs `_shared/return-validation.md` §2b INSTEAD of §2** — it
    has no injected model-id line, so it cannot carry `actual_model` and faking one
    claims evidence that does not exist; ⛔ SUBSTITUTION replaces the downgrade
@@ -106,7 +100,7 @@ invalidates a DONE task → re-run once, then set every reverse-`depends_on`
 consumer to `stale_review`. **Worker failure/garbage/timeout:** flag +
 continue the wave; audit and re-dispatch at the next batch checkpoint
 
-**Before any re-dispatch, run `orc run inflight`** (0 clear · 1 in-flight · 2 unknown). 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: `../return-validation.md`.
+**Before any re-dispatch, run `orc run inflight`** (0 clear · 1 in-flight · 2 unknown). 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: `../return-validation.md` §0.
 (`requeued`, retry_count++). Hard retry cap 2 → STOP and surface.
 
 <!-- /orc:layer -->