@azure-id/orc 1.9.2 → 2.0.2

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,11 +1,6 @@
 # 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.
+> **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)
@@ -33,13 +28,8 @@ analyze; you only dispatch and relay.
 
 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
+   `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 —
@@ -54,7 +44,7 @@ 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, v0.34.0)
+`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.
 
@@ -93,7 +83,7 @@ proceed-with-flagged.
    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
+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
@@ -101,14 +91,14 @@ proceed-with-flagged.
    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
+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. (Absent on a pre-v0.41.0 plan → derive from `kind`; never bounce an
-     old plan — see the legacy exception below.)
+     → 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
@@ -128,9 +118,8 @@ proceed-with-flagged.
 
 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
+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 -->

package/templates/skills/_shared/phases/house-rules.md

@@ -1,32 +1,27 @@
-# Phase — House rules   (id: `house-rules`)
-
-> **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-fast`, `orc-quick`, `orc-doc`. Layers declared:
-> `core` only — single-layer because it is a standing card injected VERBATIM
-> into a slice — a layered card would be a different card. `orc lane phases
-> <lane> --json` names the file and the layers to read.
-
-<!-- orc:layer core -->
-## 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 -->
-
-<!-- /orc:layer -->
+# Phase — House rules   (id: `house-rules`)
+
+> **Library file** (`orc`, `orc-mini`, `orc-fast`, `orc-quick`, `orc-doc`), `core` only: a standing card injected VERBATIM into a slice — a layered card would be a different card.
+
+<!-- orc:layer core -->
+## 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 -->
+
+<!-- /orc:layer -->