@azure-id/orc 0.56.1 → 1.1.0

package/templates/skills/_shared/config-precedence.md

@@ -0,0 +1,198 @@
+# Shared contract — config precedence: ranks, families, and one resolver per lane
+
+Canonical rule for how EVERY ORC lane learns what it is configured to do.
+Consumed by every lane that reads a setting; the lint pins the
+`config-precedence.md` pointer into each of them.
+
+Two sentences carry the whole file:
+
+> **ONE resolver, and it is not you:** `orc lane config <lane> --json`.
+>
+> **Read a family top-down and stop at the first rank that resolves.**
+
+---
+
+## 1. The resolver
+
+A lane never reads `.claude/orc.config.yaml`. It runs
+`orc lane config <lane> --json` once, at preflight, and obeys the answer.
+
+| field | what a lane does with it |
+|---|---|
+| `effective` | the flat answer. Obey it and reason about nothing. |
+| `announce[]` | print every line VERBATIM at preflight, before the first dispatch |
+| `stops[]` | every value that can HARD-STOP this run; honour each before wave 1 |
+| `keys[]` | per key: `value`, `default`, `prio`, `family`, `state`, `is_shadowed` / `shadow_reason`, `is_inert` / `inert_reason` |
+| `families{}` | which rank answered each question, and why the rest were not read |
+| `not_read[]` | the keys this lane deliberately ignores |
+
+`not_read[]` is an ANSWER, not a gap. "This lane does not read `doc_language`"
+is information, and it is what makes the two-way registry lint possible.
+
+**Never re-derive a value, a precedence, or an inertness.** A key this lane does
+not read is not in the answer; a key another key shadows comes back already
+marked, with the sentence already worded. A lane that reasons *"`opus5_only` is
+on, so the fable block must be inert"* has forked the resolver — it reads
+`is_shadowed` and prints `shadow_reason`.
+
+---
+
+## 2. Ranks, and the rule that makes them mean something
+
+Every key declares `answers[]`: which FAMILY question it answers, at which
+RANK (`P0` · `P1` · `P2` · `P3`), in which MODE.
+
+> **Read a family top-down and stop at the first rank that resolves.**
+> If the P0 key of a family resolves, P1, P2 and P3 of that family are **not
+> read at all** — not consulted, not defaulted, not mentioned as a fallback. A
+> rank below a resolved rank has no effect and no meaning for this decision.
+
+**A rank compares only INSIDE its family.** `log_dir` being P2 and `opus5_only`
+being P1 says nothing whatever: they never compete. A family whose keys do not
+compete has every key at P2, the neutral rank, and the lint asserts it — rank
+distinctness is required only where a family is declared contested.
+
+| `mode` | resolves when | effect on the ranks below it |
+|---|---|---|
+| `replace` | the key is set to a truthy / non-default value | every lower rank is shadowed, entirely |
+| `overlay` | the key is on **and** at least one row applies to THIS decision | lower ranks are shadowed only for the ranges or slots it covers |
+| `gate` | — | it never resolves the family; it makes its own dependants **inert** (§4) |
+
+An `overlay` resolves PARTIALLY, so the honest report is WHICH ranges and WHICH
+positions it took — never a single word. The ranges it did not take fall through
+to the next rank normally. That is what lets "cheap work goes to a foreign
+worker, hard work stays on Opus 5" be two rows rather than a table rewrite.
+
+**The lowest rank of a contested family is TOTAL.** Something must answer when
+nothing above resolved, so that terminal row is the shipped default and it is
+declared as a row, not as a key — a fall-through is not a setting.
+
+---
+
+## 3. The two contested families
+
+Everything else is uncontested: one question, no competition, every key P2.
+
+**`executor-band` — which model executes a SCORED task**
+
+| rank | key | mode | |
+|---|---|---|---|
+| P0 | `extra_enabled` | overlay | a route row covering this score sends it off Claude |
+| P1 | `opus5_only` | replace | the fixed 2-band Opus 5 ladder |
+| P2 | `rubric_bands_override` | replace | hand-edited, registry-less by design; resolves on PRESENCE |
+| P3 | — | terminal | the shipped score→model table |
+
+**`fixed-role-model` — which model runs a role that has no score**
+
+| rank | key | mode | |
+|---|---|---|---|
+| P0 | `extra_enabled` | overlay | a slot row holds that POSITION |
+| P1 | `opus5_only` | replace | the shipped Opus 5 variant of that position's agent |
+| P2 | — | terminal | the agent shipped for that position |
+
+Said once, for both shapes: **extra decides whether a Claude agent runs at all;
+`opus5_only` and the score tables only decide WHICH Claude agent runs where
+extra did not take it.** Under a taken band or a taken slot, `opus5_only` is
+**not consulted** — not "inert" — and it stays fully live everywhere else.
+
+---
+
+## 4. A gate is not a rank — it is inertness
+
+`extra_enabled: false` does not lose a precedence contest. It means **no
+`extra_*` key is consulted at all**. A key declares `gated_by`, inherits its
+gate's row, and comes back `inert` with the reason already worded.
+
+Lane-level inertness is a THIRD thing, with nothing in the config file involved:
+
+| lane | inert | reason (must not be softened) |
+|---|---|---|
+| `/orc-quick` | `opus5_only`, `rubric_bands_override`, `extra_*` | this lane asks WHICH AGENT before every dispatch — a config that silently answered that question would break the lane's entire premise |
+| `/orc-challenge` | `opus5_only` | every agent in this lane is already `claude-opus-5` — a **no-op; the lane is unaffected, not exempt** |
+| `/orc-doc` | `opus5_only` | the same — unaffected, not exempt |
+
+**"Unaffected, not exempt"** survives verbatim. A generic "not applicable" loses
+the fact that turning the key on breaks nothing here.
+
+---
+
+## 5. `announce[]` — and its exact boundary
+
+A shadowed setting must never be silent, and work must never leave Claude
+without the run saying so. Those lines are computed, worded once by the CLI, and
+printed by the lane verbatim.
+
+| goes in `announce[]` | stays with the lane |
+|---|---|
+| anything derivable from config + disk the CLI already reads: the wiki tier, pattern-cache presence, crosslink state, extra route rows and taken slots, pact / boundary / challenge state, which keys are shadowed or inert, the resolved scan tier, a run-scoped demotion | anything needing a per-task or per-run value the CLI cannot know: a task's score, a task id, a slug, a file count, a forecast number, a wave index |
+
+A line needing a runtime value is **not** emitted as a template with holes. Half
+a sentence from the CLI and half from the model is worse than either — it is a
+sentence nobody owns. Those lines stay with the lane.
+
+---
+
+## 6. The ladder can move at runtime
+
+A profile that stalls twice in one run, or holds one live attempt quiet past
+`extra_demote_stale_min`, is DEMOTED to the bottom of its families for the rest
+of that run — so the next rank down becomes the effective P0. The verdict is
+recomputed from disk on every read and never stored; it is run-scoped and never
+touches the config file; it is never promoted back on its own; and it is
+ANNOUNCED, because the mirror of sending work off Claude silently is quietly
+stopping. Full rule: `extra-dispatch.md`.
+
+---
+
+## 7. When the CLI is not there
+
+Exit ≠ 0, or the command is not found:
+
+1. **Say so, in one line.** Fail open with the failure stated.
+2. Use the documented defaults below.
+3. Treat **every P0 forcing mode as OFF**.
+4. Never guess a user override, and never present a default as a resolved value.
+
+The floor is the keys a run cannot start without — `max_wave_tasks: 3` ·
+`batch_pause_every: 2` · `rubric_bands: 5` · `max_scouts: 3` ·
+`default_analysis_depth: standard` · `generate_tests: false` ·
+`pattern_findings: ask` · `security_review: off`.
+
+Every other key's default is the CLI's to state. **A lane never guesses one** —
+if a decision needs a key not on that list and the CLI cannot answer, the lane
+says which key it could not resolve and stops, rather than inventing a value the
+user may have overridden.
+
+---
+
+## 8. The `## Config` section every lane carries
+
+Verbatim, and identical in every lane but its own name:
+
+```markdown
+## Config
+
+**ONE resolver, and it is not you:** `orc lane config <lane> --json`. Obey
+`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
+`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
+from `.claude/orc.config.yaml` — a key this lane does not read is not in the
+answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
+the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
+documented defaults, out loud. Priorities and families:
+`../_shared/config-precedence.md`.
+```
+
+---
+
+## 9. The file the user edits
+
+`.claude/orc.config.yaml` holds only the keys the user changed, sits outside
+`templates/` (so `orc update` never clobbers it), and is written exclusively by
+`orc config set`. It is grouped by the QUESTION each key answers, ordered by
+rank only inside a contested family.
+
+`orc config set` regenerates its own group comments on every write and
+**never rewrites a value it was not given**: a comment the user wrote stays with
+the key it sits above, and a hand-edited multi-line block survives byte for
+byte. A key written under a retired spelling is rebuilt under its current name —
+a renamed mechanism must never be a silent revert.

package/templates/skills/_shared/drift-recovery.md

@@ -29,7 +29,7 @@ never in `.claude/`, never in the run folder):
 **Who builds it: NOT you.** The example is DISPATCHED like any task (orc hard
 rule 1 — the orchestrator never implements, not even the smallest task). It is
 an orchestrator-SYNTHESIZED task, so it is scored from a DERIVED vector, never a
-judged one — see `orc/references/wave-grouping.md` "Orchestrator-synthesized
+judged one — see `_shared/phases/wave-grouping.md` "Orchestrator-synthesized
 tasks".
 
 **Git: NEVER committed.** The ship phase explicitly excludes `mock-examples/`

package/templates/skills/_shared/extra-dispatch.md

@@ -169,7 +169,7 @@ A slot is a **point**, not an interval, so the band table's overlap refusal has
 no analogue here and none is invented. `orc extra role set` on an occupied slot
 REPLACES, and says what it replaced.
 
-### The nine hold-backs, each answered by name
+### The ten hold-backs, each answered by name
 
 1. **unknown slot** — refused, exit 2, listing the six.
 2. **`extra_enabled` false** — claude. The master gate.
@@ -191,6 +191,11 @@ REPLACES, and says what it replaced.
    preflight` STOPS the run. `extra_on_failure` never covers it: that key is
    about an endpoint that failed, and a deadline you set 30 days ago deserves a
    stop.
+10. **the profile is DEMOTED in this run** (v1.0.0) — claude, named, with the
+    promote command. The tenth hold-back and the only one that is about the RUN
+    rather than about the row: two consecutive stalls, a 20-minute stale live
+    attempt, or a human running `orc extra demote`. The position falls through
+    to the SAME pinned Claude agent it always had.
 
 ### What it hands back
 
@@ -202,7 +207,7 @@ REPLACES, and says what it replaced.
 | `band` | the ROUTE row's band, not the Claude band. On a slot answer it is the string **`slot:<slot>`** — the field NAME is unchanged, so the trace parser, the eight-field dedupe and the ` :: ` tolerance keep working untouched |
 | `slot` · `lane` · `asks` | present on a slot answer only. `score` is `null` there, and **is not derived from anything** |
 | `claude` | `{via, band, agent, table}` — **always present**, on both answers. It is the fall-through target AND the fallback target, so nothing ever needs a second lookup |
-| `held_back` | `null` · `role` · `risk` · `boundary` · `missing-profile` · `unverified` |
+| `held_back` | `null` · `role` · `risk` · `boundary` · `missing-profile` · `unverified` · `demoted` |
 | `verify_state` · `needs_reping` | `FRESH` / `STALE`. **A STALE profile still routes** — a stale check is not a failed one |
 | `model_known` | whether the routed model id was in the last ping's `models_seen`. `false` is a WARNING, never a block: the list is a cache, not an authority |
 | `credential` | `{source, key_name, present}` — never a value |
@@ -228,7 +233,7 @@ One sentence, and it is the same sentence for both shapes:
 an extra route row covering this score      (only for the scores it covers)
   > opus5_only
   > rubric_bands_override
-  > the default 8-band table
+  > the default 6-band table
 ```
 
 **A slot**, highest wins:
@@ -260,7 +265,7 @@ it, `orc extra route set` names the Claude band each new row displaces, and
 `orc config list --json`'s `score_table.active` can read `extra+opus5_only` —
 a composite, because the truth is a composite and a single word would be a lie.
 
-**`/orc-quick` is a GATED CHOICE, not a route.** `opus5_only`, `fable5_*`,
+**`/orc-quick` is a GATED CHOICE, not a route.** `opus5_only`,
 `rubric_bands_override` and `extra_resume` stay INERT there — that lane asks
 *which agent* before every dispatch, so a config that silently answered that
 question, or that silently continued the previous foreign worker's half-finished
@@ -686,7 +691,7 @@ only moment anyone can act on it is now.
 
 The trace line is still yours to relay, and it still matters: it is the
 human-readable narrative of the run, it is what `/orc-retro` reads, and the
-trace-cadence rule in `references/trace-protocol.md` still binds every phase.
+trace-cadence rule in `phases/trace.md` still binds every phase.
 What changed is that the SPEND no longer depends on it.
 
 One `EXTRA` line per foreign dispatch, plus its continuations. **Copy
@@ -1056,6 +1061,146 @@ used. A CLI ping is not a cheap ping — say so.
 
 ---
 
+## The demotion — the ladder moves at runtime (v1.0.0)
+
+### `a lane that keeps paying a provider that stopped working` has broken this contract
+
+`extra_stall_s` stops ONE dispatch. It has nothing to say about the second one,
+or the third. A provider that goes quiet twice in a row is not having a bad
+minute — it is costing you a wave and buying nothing — and ORC used to keep
+handing it the next task anyway, because nothing counted.
+
+So it counts now. **Two consecutive `stalled` dispatches on one profile inside
+one run, or one live attempt with no observable progress for 20 minutes, drop
+that profile to the BOTTOM of its families for the rest of the run.**
+`opus5_only` — or the shipped score→model table — becomes the effective P0, and
+the work stays on Claude.
+
+### It writes no new measurement, and it is never remembered
+
+Every fact the trigger reads already shipped: `EXTRA_FAILURES.stalled` and the
+`timeline` block (v0.56.1), and the extra journal written by `orc extra dispatch`
+itself before the first byte leaves the machine (v0.54.0). The demotion READS
+the journal and decides — **computed by the CLI from disk on every read, never
+stored as a verdict and never carried in your head.** That is the lesson this
+repo has now lost to four times: v0.32.0 narration, v0.49.5 the hand-back,
+v0.53.2 the spend log, v0.54.0 the journal. **A fact relayed through a model's
+memory is a fact this repo has already lost.**
+
+The only thing written to disk is the HUMAN half — a promote or a manual demote,
+with its reason — under `{run_dir}/{slug}/extra-demotion.json`, beside
+`RESUME.md`. That is a decision, not a verdict, and it is deleted with the run.
+
+### The two clocks measure different things and stay two clocks
+
+```
+demote(profile, run) ⇔
+      consecutive_stalls(profile, run) >= extra_demote_after         (default 2)
+   OR a LIVE attempt quiet for >= extra_demote_stale_min minutes     (default 20)
+```
+
+- **The consecutive clock is about attempts that ENDED.** A stall is a stall
+  whether its resume succeeded or not: a profile that needs a continuation twice
+  in a row is costing more than it saves.
+- **The stale clock is about an attempt that has NOT ended.** `extra_stall_s`
+  already stops one dispatch after 180 seconds of silence. This one is about the
+  RUN — two workers in flight, both quiet, and a wave that is going nowhere.
+  Different question, different budget, its own key and its own off value.
+  **Neither is a simplification of the other**, and merging them "for
+  simplicity" is the failure this paragraph exists to prevent.
+- **The counter is per PROFILE**, not per provider and not global. Two profiles
+  on one provider can hold different keys, different models and different
+  reliability.
+- **A resume of the same stalled attempt is the SAME stall.** It neither
+  increments the counter nor resets it.
+- **`consecutive` resets on a completed dispatch that was not a stall** —
+  including a 401.
+- **ONLY `stalled` counts.** Not `timeout` (the budget was the operator's
+  choice), not `rate_limit`, not `authentication_failed`. Each of those has its
+  own answer — `extra_on_failure`, the vault, `extra_resume` — and **a demotion
+  triggered by a 401 would hide a credential problem behind a routing change**,
+  where the user would never see the real fault.
+- **`extra_stall_s: 0` silently turns the consecutive clock off too:** no
+  dispatch is ever classified `stalled`, so the counter can never move and only
+  the stale clock remains. `orc extra demotion` says so rather than reporting a
+  clock that cannot fire.
+
+### The four things it must never do
+
+1. **It never writes your config.** Run-scoped, like `/orc-ultra`'s
+   `ultra_mode`. A run that had a bad afternoon must not silently turn off a
+   subsystem you paid to set up.
+2. **It never auto-promotes inside the run.** Two stalls is evidence, and a
+   timer that re-arms a provider spends money on the evidence it already has.
+   `orc extra promote <run> --reason "<why>"` is a human action and the reason is
+   stored verbatim — the `/orc-pact` retirement rule. **A promote is a
+   WATERMARK, not a mute:** it forgives the evidence it saw, and two fresh stalls
+   after it demote again.
+3. **It never changes WHAT.** The score does not move, `declared_files` is not
+   widened, `acceptance[]` is not touched — `extra_fallback_agent`'s rule
+   inherited verbatim. **A demotion changes WHERE the work runs and nothing
+   else**, and the task lands on the SAME Claude agent it would have had.
+4. **It never abandons the position.** A demoted run still goes
+   `orc extra reconcile` → `orc extra resume-slice` → an ordinary Claude
+   dispatch. `a lane that re-does work the worktree already contains` applies
+   here exactly as it applies to the fallback, and it is the same code path.
+
+### It is ANNOUNCED, and that is not optional
+
+The mirror of `a lane that sends work off Claude without saying so` is **a lane
+that quietly STOPS.** A user who connected a provider deserves to be told the
+run left it. The line is CLI-worded (`announce` on the demotion state), it
+arrives in `orc lane config`'s `announce[]`, and it must be printed **before the
+next dispatch**. `orc lane config` renders the overlay rank as `state:
+"demoted"` — its own word, keeping its slot, because rendering it as
+`extra: off` would make *"I turned this off"* and *"this run left your provider
+after two stalls"* look identical.
+
+The trace verb is **CLI-composed and copied verbatim**, because **a demotion
+that leaves no line cannot be counted** (the v0.53.2 rule, restated):
+
+```
+EXTRA demote run=<slug> :: profile=<p> reason=<consecutive-stall|stale-live-attempt|manual> n=<k> → <the ladder that answers now>
+```
+
+### The three commands
+
+| command | exit codes | notes |
+|---|---|---|
+| `orc extra demotion [<run>] [--json]` | `0` armed · `1` demoted · `2` unknown run | a READ, and the exit code is the answer. `--json is not a summary`: it carries both clocks, the counter, the evidence task ids, the ladder before and after, and the announce line |
+| `orc extra promote <run> --reason "<why>"` | `0` promoted · `1` nothing was demoted · `2` unknown run | the reason is REQUIRED and stored verbatim |
+| `orc extra demote <run> --reason "<why>"` | `0` demoted · `2` unknown run | the manual half. Somebody who knows the provider is down should not have to wait for two stalls |
+
+`orc extra preflight` **reports a live demotion and does not move its exit
+code** — a demotion is a finding, not a stop, the `extra-orphan-dispatch`
+precedent. `orc doctor` gains **`extra-demoted-run`**, routed to the Extra
+panel's Recovery tab, which is where `orc extra promote` lives.
+
+`orc extra stats` aggregates it **per profile across every run the journal still
+holds** — a provider that demotes in every run is a pattern; one that demoted
+once is an afternoon, and the difference is only visible if somebody counts.
+There is **no rate below 3 runs**, the `extra-profile-unreliable` restraint
+verbatim.
+
+### The keys, and the two that were refused
+
+| key | default | off |
+|---|---:|---|
+| `config.extra_demote_after` | `2` | `0` — never demote on consecutive stalls |
+| `config.extra_demote_stale_min` | `20` | `0` — never demote on a stale live attempt |
+
+Both gated by `extra_enabled`. **Setting both to `0` is the honest off switch**,
+which is why there is no third key:
+
+- **REFUSED — `extra_demote` (`on`/`off`).** The two zeros already are it, and a
+  master switch over two numbers is a third spelling of one thing — the drift
+  this subsystem lints for everywhere else.
+- **REFUSED — `extra_promote_after` (an auto re-promote timer).** A timer that
+  re-arms a provider which stalled twice is a timer that spends money on the
+  evidence it already has. Promotion is a human decision with a recorded reason.
+
+---
+
 ## Who picks the task up — `extra_fallback_agent` (v0.56.1)
 
 `fallback_to` has always carried the band's (or the slot's) own Claude agent.
@@ -1094,19 +1239,24 @@ Three rules hold it together.
    slice. This is the `extra resume-slice` rule applied to the fallback.
 
 **`/orc-quick` is INERT here too,** and announces it at the agent gate — beside
-`extra_enabled`, `extra_on_failure`, `extra_resume`, `opus5_only`, `fable5_*` and
+`extra_enabled`, `extra_on_failure`, `extra_resume`, `opus5_only` and
 `rubric_bands_override`. That lane asks which agent before every dispatch, so a
 config that pre-answered it would be the exact failure the gate exists to
 prevent.
 
 ---
 
-## The config surface — thirteen keys, and the count is still the point
+## The config surface — fifteen keys, and the count is still the point
 
 The combinatorial part — providers × models × bands **× positions** — is a
 **ledger with a CLI and a panel** (`orc extra`), not a YAML block nobody can hold
 in their head.
 
+**v1.0.0 added TWO** — `extra_demote_after` and `extra_demote_stale_min` — and
+both are NUMBERS WITH A DOCUMENTED OFF VALUE rather than a switch, because the
+two zeros already are the off switch and a master key over them would be a third
+spelling of one thing. Two more were refused and are written down above.
+
 **v0.56.1 added TWO**, and both come from the same observed failure: a foreign
 worker that goes quiet mid-task. Three more were refused and are written down so
 nobody proposes them again — **a stdin nudge** (`opencode run` is not an
@@ -1141,6 +1291,8 @@ of being a string nobody checked).
 | `config.extra_resume` | `on` | Whether a partial or crashed foreign dispatch is RESUMED rather than re-done. **Default `on`, because `off` is what is broken.** INERT in `/orc-quick`. |
 | `config.extra_resume_max` | `2` | Resume attempts per task before P6 takes over. The cap STOPS with an honest report naming the Claude agent — never a silent third loop, the same shape as every other bounded repair loop in ORC. |
 | `config.extra_stall_s` | `180` | Seconds a foreign worker may produce NOTHING before the dispatch is stopped as `stalled`. Reset by observable progress — the worker's stream, its stderr, or a declared file that changed on disk — so it never fires on a worker that is merely slow. `0` disables and the wall clock is the only stop again. **Clamped below `extra_timeout_s`**, because a budget that can never fire is worse than none. Engine `cli` only. |
+| `config.extra_demote_after` | `2` | Consecutive `stalled` dispatches on ONE profile inside one run before that profile is DEMOTED to the bottom of the ladder for the rest of the run. Only `stalled` counts; a resume of the same stall is the same stall; a completed dispatch that was not a stall resets it. Run state — it never writes your config, it is ANNOUNCED, and it is never promoted back on its own. `0` turns this clock off. |
+| `config.extra_demote_stale_min` | `20` | Minutes a LIVE attempt may show no observable progress before its profile is demoted. A different question from `extra_stall_s`, which stops ONE dispatch: this clock is about the RUN. `0` turns this clock off. |
 | `config.extra_fallback_agent` | `band` | WHICH Claude agent picks up a task the foreign worker could not finish. `band` is the pre-v0.56.1 behaviour. `ask` STOPS and puts the menu to the user. Any installed agent name pins one. It changes WHO, never the score, the declared files or the acceptance criteria. INERT in `/orc-quick`. |
 
 **Keys deliberately NOT added, and why each one would be a trap:**

package/templates/skills/_shared/interview.md

@@ -3,7 +3,7 @@
 Canonical file: `_shared/interview.md`. THE canonical way any ORC lane
 interrogates a human until an idea is sharp enough to act on. Load it wherever a
 lane must ask more than a fixed questionnaire's worth of questions: `/orc-grill`
-runs it end to end, and `references/intake.md` borrows its round format when a
+runs it end to end, and `phases/intake.md` borrows its round format when a
 tier's question set runs long.
 
 This is not "ask good questions". It is a specific mechanic with a termination

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

@@ -13,14 +13,18 @@ is inert.
 
 ## The mapping (only when `opus5_only: true`)
 
-**Scored executors** — one model, EFFORT as the cost dial, replacing the 8-band
+**Scored executors** — one model, EFFORT as the cost dial, replacing the 6-band
 mixed-model table:
 
 | Score | Executor agent |
 |-----------|---------------------------|
-| `[0,40)`   | `orc-executor-opus-5-low`  |
-| `[40,80)`  | `orc-executor-opus-5-med`  |
-| `[80,100]` | `orc-executor-opus-5-high` |
+| `[0,90)`   | `orc-executor-opus-5-low`  |
+| `[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,
+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
 agent: same task slice, same return contract, same phase.
@@ -77,12 +81,10 @@ exists to prevent. Ladder: `../orc-wiki/references/partial-refresh.md`.
 `opus5_only: true` outranks every other dispatch selector:
 
 - each role's default frontmatter pin;
-- **`fable5_enabled` / `fable5_roles`** — the Fable 5 role override is fully
-  INERT while the mode is on (`../_shared/fable5-override.md` does not apply);
 - **`rubric_bands_override`** — a hand-written executor table is ignored while
   the mode is on.
 
-Turning the mode off restores all three. `rubric_bands` remains granularity
+Turning the mode off restores both. `rubric_bands` remains granularity
 only, never a preset selector, in both modes.
 
 The forcing is flat across every lane that HONORS the mode — `orc-quick` does

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

@@ -0,0 +1,82 @@
+# `_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` |
+
+`orc lane phases --all --json` is the authoritative list; this table is a
+human index of it.

package/templates/skills/{orc/references → _shared/phases}/analyst-gates.md

@@ -1,9 +1,19 @@
-# Reference — Analyst, Combiner & Plan Gates (orchestrator side)
+# 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
-`../subskills/orc-planner/SKILL.md` — this file is what YOU do around their
+`../../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.
@@ -113,7 +123,7 @@ proceed-with-flagged.
    - `new-surface` / `behavior-change` missing `skeleton` or `given_when_then`
      → miss.
    - A disposition that DEVIATES from the derivation table in
-     `../schemas/planning-output.md` without a `reason` → miss. The derivation
+     `../../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
@@ -122,3 +132,5 @@ 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 -->