@azure-id/orc 2.0.2 → 2.1.0

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

@@ -13,7 +13,7 @@ is inert.
 
 ## The mapping (only when `opus5_only: true`)
 
-**Scored executors** — one model, EFFORT as the cost dial, replacing the 6-band
+**Scored executors** — one model, EFFORT as the cost dial, replacing the 5-band
 mixed-model table:
 
 | Score | Executor agent |
@@ -23,7 +23,7 @@ mixed-model table:
 
 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.5 with effort as the dial,
-so this mode differs from it only below 65 — a third band here would be a
+so this mode differs from it only below 41 — a third band here would be a
 distinction the default table stopped making.
 
 **Fixed roles** — dispatch the Opus 5.5 variant **instead of** the default role
@@ -37,21 +37,21 @@ agent: same task slice, same return contract, same phase.
 | mini plan | `orc-planner-mini-sonnet-5-high` | `orc-planner-mini-opus-5-med` |
 | scout | `orc-scout-sonnet-4-6-high` | `orc-scout-opus-5-low` |
 | pattern codify | `orc-pattern-codifier-sonnet-5-high` | `orc-pattern-codifier-opus-5-med` |
-| wiki scan | `orc-wiki-scanner-opus-4-8-high` (deep) **or** `orc-wiki-scanner-sonnet-5-high` (light) | `orc-wiki-scanner-opus-5-med` |
-| claude write | `orc-claude-writer-opus-4-8-high` | `orc-claude-writer-opus-5-med` |
+| wiki scan | `orc-wiki-scanner-sonnet-5-high` (light) | `orc-wiki-scanner-opus-5-low` |
 | retro mine | `orc-retro-sonnet-5-high` | `orc-retro-opus-5-med` |
 
-The nine roles already pinned to `claude-opus-5-5` — analyst, planner, reviewer,
-verifier, test-author, combiner, learn-writer, advisor, judge — are already
+The eleven roles already pinned to `claude-opus-5-5` — analyst, planner, reviewer,
+verifier, test-author, combiner, learn-writer, advisor, judge, CLAUDE.md writer
+(`orc-claude-writer-opus-5-low`), deep wiki scanner (`orc-wiki-scanner-opus-5-low`)
+— 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.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`.
+**The wiki scan tier ladder (v0.46.0) needs no new pair.**
+Off, the ladder picks deep or light per delta. ON, this mode flips the light tier
+to `orc-wiki-scanner-opus-5-low`. The deep tier is already that agent. So **both
+tiers collapse onto that one shipped agent** and the ladder simply stops applying.
+Do not add a second Opus 5.5 scanner variant. 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`.
 
 ## Out of scope — never forced
 
@@ -114,7 +114,7 @@ first one is true. `orc config list` and `orc config set` NAME the taken bands
 AND the taken positions for exactly that reason: a shadowed setting must never
 be silent, and neither must a partly shadowed one.
 
-Both wiki slots collapse onto `orc-wiki-scanner-opus-5-med` while the mode is on,
+Both wiki slots collapse onto `orc-wiki-scanner-opus-5-low` while the mode is on,
 which is why the slot table adds **no agent and no pair**. A slot names the
 POSITION, not the model.
 

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

@@ -10,7 +10,7 @@ Emit `PHASE review start`. **Build the slice from `../review-slice.md`** — its
 §1 free check FIRST, then its §2 fields (with the graph on, `graph_changes` keeps
 its rows: no `--brief` here). Superpowers path: its review skill incl. tests
 (Sonnet 4.6 medium), then `../review-slice.md` §3 on its findings — no second
-dispatch. OpenSpec/self path: review worker (Opus 5.5 medium). Pass the resolved
+dispatch. OpenSpec/self path: review worker (Opus 5.5 low). Pass the resolved
 `code_pattern` + its invariants + gate lines for the re-check
 (pattern-gate.md); no resolved pattern → FIRST ask for one (paste/md/none) (H `orc.phase-5.pattern-missing`).
 FE tasks in run → pass `fe_rules[]` from `../../orc-pattern/references/` fe-a11y
@@ -41,7 +41,7 @@ skipped by flow config") — never imply the work was reviewed.
 <!-- diy:when review=on -->
 Dispatch the reviewer exactly as the full lane does — follow the review half
 of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` (reviewer agent
-`orc-reviewer-opus-5-med`; findings ride the severity ladder from the
+`orc-reviewer-opus-5-low`; findings ride the severity ladder from the
 locked rules, blocking and advisory findings both surfaced). Build its slice
 from `.claude/skills/_shared/review-slice.md` (§1 free check, §3 after-filter).
 <!-- /diy:when -->

package/templates/skills/_shared/phases/trace-verbs.md

@@ -42,7 +42,9 @@ owner is this file has its detail in "Verb detail" below.
 | `JUDGE <analysis\|plan\|implementation> <verdict> round=<n> blocking=<n> advisory=<n> downgraded=<n>` | orc → writer | ultra judgment verdict | `orc/references/ultra-mode.md` |
 | `OUTCOME task=<id> score=<n> band=<range> model=<m> retries=<n> requeues=<n> needs_context=<n> unmet=<n>` | orc → writer | task closed — links the scoring band to what it actually took | `_shared/phases/execution.md` |
 | `FINDING p0=<n> p1=<n> p2=<n> p3=<n>[ pre=<n> suppressed=<n> folded=<n>]` | reviewer→orc → writer | review outcome (P0–P3 severity ladder); the tail counts the after-filter's buckets | `_shared/phases/review.md` |
-| `FINDING-OUTCOME addressed=<n> disputed=<n> wontfix=<n> open=<n> pre=<n> suppressed=<n> :: <cat>:<addressed>/<total>,…` | orc → writer | ONE line at review close — what became of each finding; `orc gotcha quality` reads it | `_shared/phases/trace-verbs.md` |
+| `FINDING-OUTCOME addressed=<n> disputed=<n> wontfix=<n> open=<n> pre=<n> suppressed=<n> :: <cat>:<addressed>/<total>,…` | orc → writer | ONE line at review close (a clean review too) — what became of each finding; `orc gotcha quality` counts it as a review | `_shared/phases/trace-verbs.md` |
+| `REVIEW-WHICH chose=<orc\|project\|skip> name=<the review the rule names> by=<user\|ledger\|learned> :: <file:line of the rule>` | orc → writer | the answer to §0 "which review" when the project names its own review — written ALWAYS, also under habits off; the FINISH nudge reads it | `_shared/phases/trace-verbs.md` |
+| `FIX source=<sonar\|ci\|defect\|pr\|review\|other> introduced_by=<orc\|ai\|human\|unknown> by=<user\|evidence> obs=<id8>[ missed_by=<run>] :: <path:lines> <rule or finding>` | cli | one fix recorded by `orc fix record` (/orc-fix) into the HOST run's trace — the CLI writes it, never a packet | `orc-fix/SKILL.md` |
 | `VERDICT pass\|fail :: <detail>` | verifier→orc → writer | verification outcome | `_shared/phases/verify.md` |
 | `DRIFT loop=<n> :: <user description, compressed>` | orc → writer | mock-example drift-recovery loop opened (hard cap 2 loops) | `_shared/drift-recovery.md` |
 | `TDD-RED task=<id> iter=<n> :: <failing tests>` | executor→orc → writer | TDD repair-loop iteration — the plan's acceptance tests still red | `_shared/phases/trace-verbs.md` |
@@ -170,6 +172,16 @@ reaches the file through a packet — you never append lines by hand.
   the user said "not a problem here" = disputed; declined with no reason = wontfix.
   `pre` and `suppressed` copy the after-filter's buckets; they never gate. The
   `FINDING` tail `pre= suppressed= folded=` is additive (the `sections=` precedent).
+- **`REVIEW-WHICH`** (v2.1.0). ONE line, before ship, in every coding lane that
+  changed code, when the `review-policy` probe says `policy: project`
+  (the review slice, §0). It is written ALWAYS — habits off too — because it is a
+  record of what ran, not a habit. The `ASK any.review.which` line is written in
+  addition only when habits is on. A run that changed code under `policy:
+  project` with no `REVIEW-WHICH` line gets one nudge at FINISH.
+- **`FIX`** (v2.1.0). Written by `orc fix record` ITSELF into the run in flight
+  (`/orc-fix`, a rider that opens no run). A packet that carries it is refused.
+  A lane never narrates it and never repeats it; `orc stats` and `/orc-retro`
+  read it like any other line.
 - **`DRIFT`.** `PHASE mock-example`; canonical `_shared/drift-recovery.md`.
 - **`TDD-RED` / `TDD-GREEN`.** Cap `tdd_loop_max`; a paired TDD task's red proof
   also emits iter=0. `TDD-GREEN` is the non-exempt definition-of-done.
@@ -334,8 +346,10 @@ trace and never emit `SPAWN`/`RETURN`.
 
 ### Files & lifecycle
 
-- Folder: `log_dir` (default `.claude/orc/logs/`). Persistent — **never deleted**
-  (deliberate opposite of the decision log). Top level holds the run `.txt` plus
+- Folder: `log_dir` (default `.claude/orc/logs/`). Persistent (deliberate
+  opposite of the decision log): kept until you run `orc clear logs --apply`, or
+  until the automatic sweep removes it (`log_retention_auto: on`, older than
+  `log_retention_days`). Top level holds the run `.txt` plus
   its sidecars (`.pending.json`, `.jsonl`); generated reports live in
   subfolders (`retro/`).
 - One file per run: **`run-<lane>-<slug>-<DDMMYY>-<HHMMSS>.txt`**, append-only.

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

@@ -1,136 +1,136 @@
-# Phase — Behavior trace   (id: `trace`)
-
-> **Library file.** `orc lane phases <lane> --json` → `trace_grammar` gives this lane's verbs. **A verb not in `trace_grammar` → read `trace-verbs.md`** (the CLOSED set, on demand). Never invent a verb.
-
-<!-- orc:layer core -->
-
-**Behavior-trace logging is PERMANENT (always on) — there is no config toggle.**
-Every ORC run traces, to a **persistent** file that is NOT the decision log. The
-`orc-trace.js` hook bootstraps `log_dir` + the run pointer on the first ORC-agent
-dispatch and writes the `SPAWN`/`RETURN`/`PHASE-EDGE` skeleton itself. Only
-`log_dir` (default `.claude/orc/logs`) is configurable.
-
-## Narration is WRITTEN BY THE CLI, not remembered (v2.0.0 — the core rule)
-
-> **Phase close = pipe the phase packet to `orc trace write --packet -`.**
-> Exit ≠ 0 → dispatch `orc-trace-writer-haiku-4-5` with the SAME packet.
-
-You supply the facts; the CLI holds the pen. You never append lines by hand.
-
-- **Pairing rule.** The write for phase N goes **in the same tool block as
-  phase N+1's first dispatch**. A phase with no next dispatch (FINISH, an
-  abort, a pure-question phase) writes SOLO, before its user-facing output.
-- **First write is solo** — before the planner/analyst goes out. It carries
-  `run_meta`.
-- **Last write (run end).** The FINISH packet is written BEFORE you delete
-  `.current`. It carries ONE `STATS` line immediately BEFORE `FINISH`.
-
-### Phase packet (the command's stdin — small, plain YAML or JSON)
-
-```yaml
-phase: execution wave 2
-run_meta:                 # FIRST packet of the run ONLY; omit thereafter
-  lane: orc               # orc | ultra | mini | fast | diy | wiki | analyze |
-                          # plan | claude | poly | learn | verify | pattern |
-                          # prsetup | prdriver | quick | grill | route |
-                          # brainstorm | pact | boundary | handoff | budget |
-                          # aftermath | export | challenge | doc | test
-  slug: cas-multi-exchange-withdrawal
-  trace_path: .claude/orc/logs/run-orc-cas-multi-exchange-withdrawal-240726-002352.txt
-events:                   # each {ts, verb, tail}; verb = the WHOLE head (`GATE grounding pass`), tail = detail only
-  - {ts: "240726 00:30:39.881", verb: "VERIFY T2", tail: "actual=claude-sonnet-4-6/high ✅ MATCH"}
-decisions: >              # free text — the WHY layer
-  User answered "no new deps" verbatim; rejected the adapter split.
-```
-
-- Build it from the phase's **actual working state as the phase closes**, never
-  from memory later. `ts` is each event's REAL time. An absent field is omitted.
-- Subagent-returned markers (`QUESTION`, `FINDING`, `VERDICT`, a return's
-  `actual_model`) are folded into the NEXT packet, never written directly.
-
-### How many packets per lane (three tiers — EVERY trace-owning lane narrates)
-
-| Tier | Lanes | Packets |
-|------|-------|---------|
-| Build lanes | `orc` (incl. ultra), `orc-mini`, `orc-fast` | per phase — full orc ≈ 7–9 (ultra adds U0 + judge packets); orc-mini batches to 3, orc-fast to 2 |
-| Multi-dispatch | `orc-wiki`, `orc-pr-driver` | one per scan-batch (wiki) or LAYER (pr-driver) boundary + the end-of-run packet |
-| Composed | `orc-diy` | one per ENABLED phase group, **minimum 2** |
-| Iterative | `orc-quick`, `orc-challenge`, `orc-doc`, `orc-test` | **one per completed unit** (entry · iteration · wave · cycle — each spine names its unit) + the end-of-run `FINISH` packet. Several trace files for one cycle is CORRECT |
-| Single-dispatch | `orc-claude`, `orc-plan`, `orc-analyze`, `orc-analyze-mini`, `orc-pattern`, `orc-verify`, `orc-learn`, `orc-poly`, `orc-pr-setup`, `orc-grill`, `orc-route`, `orc-brainstorm`, `orc-pact`, `orc-boundary`, `orc-handoff`, `orc-budget`, `orc-aftermath`, `orc-export` | **exactly ONE mandatory end-of-run packet** |
-
-**The single-packet obligation is defined HERE, once.** That packet goes out
-SOLO after the main return validates and BEFORE `.current` is deleted, with
-`run_meta` plus the whole event list (intake decisions, the user's answers,
-`DISPATCH`/`VERIFY`, gate/verdict lines, `FINISH`). `context-combiner` is a
-PHASE of the analyze run, not a lane. `/orc-retro` writes no trace.
-
-## Files & lifecycle
-
-- `log_dir` is **never deleted**. One append-only file per run:
-  **`run-<lane>-<slug>-<DDMMYY>-<HHMMSS>.txt`** — `lane` from the enum above,
-  `slug` `[a-z0-9-]`, ≤32 chars, no trailing hyphen.
-- Run pointer: at run start, write `log_dir/.current` containing just the trace
-  filename **and `touch the trace file` of that name in the SAME step**. Both, or
-  neither — a pointer to a missing file reads as dangling and splits the run.
-  A lane that writes code also runs `orc run snapshot --run <run-slug>` in that
-  step (what `orc undo` goes back to). Delete the pointer at run end (success or abort).
-- **A SUSPENDED lane re-writes its pointer on RESUME** (`_shared/lane-suspend.md`,
-  `RETURN-TO`): the receiving lane deletes `.current` at its `FINISH`, so the
-  suspending lane re-writes `.current` and must `touch the trace file` it names,
-  in the SAME step.
-
-## Write cadence — append AS THE RUN GOES, never in one batch at the end
-
-Each phase's packet goes out AT that phase's close, with that phase's events
-and the decisions behind them.
-
-**Self-check:** a phase that ends with
-`zero new trace lines is a protocol violation`.
-If a phase went by without its packet, write it NOW with the events'
-real timestamps — a block stamped "now" is a FALSE record. Never batch
-everything at `FINISH`. **A run with no `FINISH` counts as unfinished,
-permanently** — `FINISH` is mandatory even on an abort.
-
-## Model check, announce, compaction
-
-- **Claimed vs actual.** Compare each return's `actual_model` / `actual_effort`
-  with the pair the agent NAME implies; put a `VERIFY` line in the next packet
-  and surface a ⛔ DOWNGRADE to the user in chat.
-- **Announce-on-spawn** from the agent NAME ("Spawning orc-executor-opus-5-low →
-  claude-opus-5-5 / low"); never pass the coarse `sonnet|opus|haiku` arg.
-- **Compaction.** The checkpoint carries `logging_enabled` + `trace_path`; on
-  resume, keep writing to the same file. `/orc-ultra` = `orc` + `ultra_mode: true`.
-- Append-only, one whole block per append. Record the ugly bits too.
-
-<!-- /orc:layer -->
-
-<!-- orc:layer composed -->
-
-## Behavior trace (PERMANENT — always on, no flow key)
-
-Tracing is NOT composable: every ORC run traces, this one included. Follow
-`.claude/skills/_shared/phases/trace.md` (load it at run start) — this
-block is stitched into every compiled flow so a user-composed pipeline can never
-be the one lane that runs blind.
-
-**Run start:** create `log_dir`, write `log_dir/.current` =
-`run-diy-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
-in the SAME step (a pointer naming a file that does not exist reads as dangling —
-the hook rotates away from it and the run splits across two files), then store
-`trace_path` in the checkpoint and run `orc run snapshot --run <run-slug>`. The lane token is `diy`, whatever the flow is
-named.
-
-**Narration is written by the CLI, never remembered:** record each event with
-its REAL timestamp into a phase packet (`PHASE`, `DISPATCH`/`VERIFY` per spawn —
-`actual_model`/`actual_effort` vs expected, surface any ⛔ DOWNGRADE to the user
-— `SCORE`, `OUTCOME`, `GATE`, `FINDING`/`VERDICT` for whichever gates this flow
-enabled, `FINISH`, plus `decisions` = the WHY), then pipe it to
-`orc trace write --packet -` (exit ≠ 0 → `orc-trace-writer-haiku-4-5`), PAIRED
-with the next phase's first dispatch. **One packet per ENABLED phase group, minimum 2** — the flow shape is
-composed, so the packet count is too; a phase this flow turned OFF owes nothing.
-A phase ending with `zero new trace lines is a protocol violation`.
-
-**Run end:** write the `FINISH` packet, then delete
-`log_dir/.current`.
-
-<!-- /orc:layer -->
+# Phase — Behavior trace   (id: `trace`)
+
+> **Library file.** `orc lane phases <lane> --json` → `trace_grammar` gives this lane's verbs. **A verb not in `trace_grammar` → read `trace-verbs.md`** (the CLOSED set, on demand). Never invent a verb.
+
+<!-- orc:layer core -->
+
+**Behavior-trace logging is PERMANENT (always on) — there is no config toggle.**
+Every ORC run traces, to a **persistent** file that is NOT the decision log. The
+`orc-trace.js` hook bootstraps `log_dir` + the run pointer on the first ORC-agent
+dispatch and writes the `SPAWN`/`RETURN`/`PHASE-EDGE` skeleton itself. Only
+`log_dir` (default `.claude/orc/logs`) is configurable.
+
+## Narration is WRITTEN BY THE CLI, not remembered (v2.0.0 — the core rule)
+
+> **Phase close = pipe the phase packet to `orc trace write --packet -`.**
+> Exit ≠ 0 → dispatch `orc-trace-writer-haiku-4-5` with the SAME packet.
+
+You supply the facts; the CLI holds the pen. You never append lines by hand.
+
+- **Pairing rule.** The write for phase N goes **in the same tool block as
+  phase N+1's first dispatch**. A phase with no next dispatch (FINISH, an
+  abort, a pure-question phase) writes SOLO, before its user-facing output.
+- **First write is solo** — before the planner/analyst goes out. It carries
+  `run_meta`.
+- **Last write (run end).** The FINISH packet is written BEFORE you delete
+  `.current`. It carries ONE `STATS` line immediately BEFORE `FINISH`.
+
+### Phase packet (the command's stdin — small, plain YAML or JSON)
+
+```yaml
+phase: execution wave 2
+run_meta:                 # FIRST packet of the run ONLY; omit thereafter
+  lane: orc               # orc | ultra | mini | fast | diy | wiki | analyze |
+                          # plan | claude | poly | learn | verify | pattern |
+                          # prsetup | prdriver | quick | grill | route |
+                          # brainstorm | pact | boundary | handoff | budget |
+                          # aftermath | export | challenge | doc | test
+  slug: cas-multi-exchange-withdrawal
+  trace_path: .claude/orc/logs/run-orc-cas-multi-exchange-withdrawal-240726-002352.txt
+events:                   # each {ts, verb, tail}; verb = the WHOLE head (`GATE grounding pass`), tail = detail only
+  - {ts: "240726 00:30:39.881", verb: "VERIFY T2", tail: "actual=claude-sonnet-4-6/high ✅ MATCH"}
+decisions: >              # free text — the WHY layer
+  User answered "no new deps" verbatim; rejected the adapter split.
+```
+
+- Build it from the phase's **actual working state as the phase closes**, never
+  from memory later. `ts` is each event's REAL time. An absent field is omitted.
+- Subagent-returned markers (`QUESTION`, `FINDING`, `VERDICT`, a return's
+  `actual_model`) are folded into the NEXT packet, never written directly.
+
+### How many packets per lane (three tiers — EVERY trace-owning lane narrates)
+
+| Tier | Lanes | Packets |
+|------|-------|---------|
+| Build lanes | `orc` (incl. ultra), `orc-mini`, `orc-fast` | per phase — full orc ≈ 7–9 (ultra adds U0 + judge packets); orc-mini batches to 3, orc-fast to 2 |
+| Multi-dispatch | `orc-wiki`, `orc-pr-driver` | one per scan-batch (wiki) or LAYER (pr-driver) boundary + the end-of-run packet |
+| Composed | `orc-diy` | one per ENABLED phase group, **minimum 2** |
+| Iterative | `orc-quick`, `orc-challenge`, `orc-doc`, `orc-test` | **one per completed unit** (entry · iteration · wave · cycle — each spine names its unit) + the end-of-run `FINISH` packet. Several trace files for one cycle is CORRECT |
+| Single-dispatch | `orc-claude`, `orc-plan`, `orc-analyze`, `orc-analyze-mini`, `orc-pattern`, `orc-verify`, `orc-learn`, `orc-poly`, `orc-pr-setup`, `orc-grill`, `orc-route`, `orc-brainstorm`, `orc-pact`, `orc-boundary`, `orc-handoff`, `orc-budget`, `orc-aftermath`, `orc-export` | **exactly ONE mandatory end-of-run packet** |
+
+**The single-packet obligation is defined HERE, once.** That packet goes out
+SOLO after the main return validates and BEFORE `.current` is deleted, with
+`run_meta` plus the whole event list (intake decisions, the user's answers,
+`DISPATCH`/`VERIFY`, gate/verdict lines, `FINISH`). `context-combiner` is a
+PHASE of the analyze run, not a lane. `/orc-retro` writes no trace.
+
+## Files & lifecycle
+
+- `log_dir` stays until `orc clear logs --apply` or the `log_retention_auto`
+  sweep. One append-only file per run:
+  **`run-<lane>-<slug>-<DDMMYY>-<HHMMSS>.txt`** — `lane` from the enum above,
+  `slug` `[a-z0-9-]`, ≤32 chars, no trailing hyphen.
+- Run pointer: at run start, write `log_dir/.current` containing just the trace
+  filename **and `touch the trace file` of that name in the SAME step**. Both, or
+  neither — a pointer to a missing file reads as dangling and splits the run.
+  A lane that writes code also runs `orc run snapshot --run <run-slug>` in that
+  step (what `orc undo` goes back to). Delete the pointer at run end (success or abort).
+- **A SUSPENDED lane re-writes its pointer on RESUME** (`_shared/lane-suspend.md`,
+  `RETURN-TO`): the receiving lane deleted `.current`, so re-write it and
+  `touch the trace file` it names, in the SAME step.
+
+## Write cadence — append AS THE RUN GOES, never in one batch at the end
+
+Each phase's packet goes out AT that phase's close, with that phase's events
+and the decisions behind them.
+
+**Self-check:** a phase that ends with
+`zero new trace lines is a protocol violation`.
+If a phase went by without its packet, write it NOW with the events'
+real timestamps — a block stamped "now" is a FALSE record. Never batch
+everything at `FINISH`. **A run with no `FINISH` counts as unfinished,
+permanently** — `FINISH` is mandatory even on an abort.
+
+## Model check, announce, compaction
+
+- **Claimed vs actual.** Compare each return's `actual_model` / `actual_effort`
+  with the pair the agent NAME implies; put a `VERIFY` line in the next packet
+  and surface a ⛔ DOWNGRADE to the user in chat.
+- **Announce-on-spawn** from the agent NAME ("Spawning orc-executor-opus-5-low →
+  claude-opus-5-5 / low"); never pass the coarse `sonnet|opus|haiku` arg.
+- **Compaction.** The checkpoint carries `logging_enabled` + `trace_path`; on
+  resume, keep writing to the same file. `/orc-ultra` = `orc` + `ultra_mode: true`.
+- Append-only, one whole block per append. Record the ugly bits too.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Behavior trace (PERMANENT — always on, no flow key)
+
+Tracing is NOT composable: every ORC run traces, this one included. Follow
+`.claude/skills/_shared/phases/trace.md` (load it at run start) — this
+block is stitched into every compiled flow so a user-composed pipeline can never
+be the one lane that runs blind.
+
+**Run start:** create `log_dir`, write `log_dir/.current` =
+`run-diy-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step (a pointer naming a file that does not exist reads as dangling —
+the hook rotates away from it and the run splits across two files), then store
+`trace_path` in the checkpoint and run `orc run snapshot --run <run-slug>`. The lane token is `diy`, whatever the flow is
+named.
+
+**Narration is written by the CLI, never remembered:** record each event with
+its REAL timestamp into a phase packet (`PHASE`, `DISPATCH`/`VERIFY` per spawn —
+`actual_model`/`actual_effort` vs expected, surface any ⛔ DOWNGRADE to the user
+— `SCORE`, `OUTCOME`, `GATE`, `FINDING`/`VERDICT` for whichever gates this flow
+enabled, `FINISH`, plus `decisions` = the WHY), then pipe it to
+`orc trace write --packet -` (exit ≠ 0 → `orc-trace-writer-haiku-4-5`), PAIRED
+with the next phase's first dispatch. **One packet per ENABLED phase group, minimum 2** — the flow shape is
+composed, so the packet count is too; a phase this flow turned OFF owes nothing.
+A phase ending with `zero new trace lines is a protocol violation`.
+
+**Run end:** write the `FINISH` packet, then delete
+`log_dir/.current`.
+
+<!-- /orc:layer -->

package/templates/skills/_shared/review-slice.md

@@ -5,7 +5,31 @@
 > `/orc-quick` review offer, the `/orc-mini` risk-high option, the `/orc-pr-driver`
 > per-layer gate, `/orc-ultra` gate 3). One slice, so a review in quick is the
 > same review as in `/orc`. The procedure and the return live in the agent file
-> (`.claude/agents/orc-reviewer-opus-5-med.md`), never here.
+> (`.claude/agents/orc-reviewer-opus-5-low.md`), never here.
+
+## §0 Which review — only when the project names its own (v2.1.0)
+
+When the `review-policy` probe of the lane config (or `orc review policy
+--json`) says `policy: project`, a coding lane that changed code asks this ONCE
+before ship — also `/orc-fast`, and `/orc-mini` without a risk-high row (DE-8).
+A CLAUDE.md line never picks the reviewer: it adds an OPTION (H `any.review.which`).
+
+```text
+Which review for this change?
+  1. ORC review — orc-reviewer-opus-5-low (traced, gotcha card, Review Quality)
+  2. <name> — the review <file>:<line> asks for            ← recommended
+  3. Skip review (not recommended: <file>:<line> asks for one)
+```
+
+- Write `REVIEW-WHICH chose=<orc|project|skip> name=<the named review> by=user ::
+  <file>:<line>` ALWAYS (habits off too) — and ONLY under `policy: project`. With habits on, also the ASK line.
+- **1** → this slice, as the lane already does. **2** → run the named skill or
+  command (the Skill tool takes both), then §3 on its findings with
+  `reviewer: "<name>"` on each observation — no ORC reviewer is dispatched.
+  **3** → no review; the summary says the project asked for one.
+- An external review has no hook trace, no gotcha card and no required
+  `category`/`scenario`/`pre_existing`: §3 fills `category: uncategorized` where
+  it cannot map one, and Review Quality counts it in its own line.
 
 Slice fields: changed_files[] · diff_ranges[] · acceptance_criteria[] · constraints[] · code_pattern · invariants[] · validation_gate[] · fe_rules[] · security_checklist[] · graph_changes · tool_findings[] · gotcha_card · rules_card · previous_findings[] · mode
 
@@ -74,6 +98,9 @@ The reviewer reports EVERY finding. Then, before the ladder acts:
 5. At review close, record one observation per finding and emit the
    `FINDING-OUTCOME` line — `gotchas.md` §10 "Review close" (`/orc` Phase 7,
    `/orc-mini` after its risk option, `/orc-quick` after the review offer).
+6. In the same step, store the reviewed ranges (`diff_ranges`) with ONE
+   `orc gotcha observe -` call, body `{"kind": "review-scope", run, commit,
+   files}` (DE-13, "Review close"). The CLI computes a later fix's `miss` from it.
 
 **Superpowers path** (DE-13): after the Superpowers review skill returns, run
 this §3 on its findings too, outcomes included — never a second reviewer dispatch.

package/templates/skills/_shared/wait.md

@@ -110,6 +110,7 @@ the other fails the suite.
 | `/orc-pattern` | none | single dispatch |
 | `/orc-claude` | none | single dispatch |
 | `/orc-explain` | none | read-only, seconds long |
+| `/orc-fix` | none | after the record is written |
 | `/orc-route` | none | read-only, seconds long |
 | `/orc-boundary` | none | read-only, seconds long |
 | `/orc-budget` | none | read-only, seconds long |

package/templates/skills/orc/README.md

@@ -97,8 +97,8 @@ codifier: 9 language playbooks + a11y/perf rule packs), `context-combiner`
   even for tiny tasks.** Orchestrator (Opus 4.8 high, or Opus 5.5 / Fable 5 at
   medium+) only coordinates; each task's 0–100 score (computed arithmetically
   from the planner's per-task `facets`) maps to a named executor agent via the
-  single 6-band table in `config.md` (`rubric_bands` = report granularity only),
-  Haiku 4.5 [0,30) → Opus 5.5 low [65,90) → Opus 5.5 medium [90,100].
+  single 5-band table in `config.md` (`rubric_bands` = report granularity only),
+  Sonnet 5 low [0,21) → Opus 5.5 low [41,90) → Opus 5.5 medium [90,100].
 - **Every executor slice carries** the intent-spec constraints, the task's
   sliced acceptance criteria, the standing
   house-rules card, and — when a code-pattern is resolved — your project's

package/templates/skills/orc/SKILL.md

@@ -87,7 +87,7 @@ Workers are model-pinned SUBAGENTS in `.claude/agents/` — the model is enforce
 not requested in prose. Score every task from the planner-emitted `facets` via
 the fixed arithmetic formula and SHOW the table with the facet vector + the
 arithmetic (`B+N+L+T+fan+U = raw`; an un-shown number is not scored); map the
-final score via the RESOLVED table in `config.md` — `opus5_only` (2-band Opus-5-only, FORCING) > `rubric_bands_override` > the default 6-band (`rubric_bands` = granularity only, never a preset); NAME it when you show scores; sibling tasks differing in ≤1 facet share a
+final score via the RESOLVED table in `config.md` — `opus5_only` (2-band Opus-5-only, FORCING) > `rubric_bands_override` > the default 5-band (`rubric_bands` = granularity only, never a preset); NAME it when you show scores; sibling tasks differing in ≤1 facet share a
 band or cite the differing facet (see `references/effort-and-mode.md`). EVERY
 dispatch is scored — fix-cycle dispatches (review-fix, verify-fix, P2-batch,
 requeue) run the same formula, inherit the original task's risk floor, and never

package/templates/skills/orc/config.md

@@ -26,32 +26,30 @@ the `announce[]` boundary and the CLI-absent floor:
 ## Score → model table (executor agent dispatched by name)
 
 The orchestrator scores each task 0–100, then maps to a model via this SINGLE
-canonical 6-band table, and dispatches the matching **executor agent**.
+canonical 5-band table, and dispatches the matching **executor agent**.
 `rubric_bands` sets scoring granularity only — it never selects a table.
 
 | Score | Model | Effort | Executor agent |
 |-------|-------|--------|----------------|
-| [0,30)   | claude-haiku-4-5  | —      | orc-executor-haiku-4-5 |
-| [30,40)  | claude-sonnet-4-6 | medium | orc-executor-sonnet-4-6-med |
-| [40,55)  | claude-sonnet-4-6 | high   | orc-executor-sonnet-4-6-high |
-| [55,65)  | claude-sonnet-5   | high   | orc-executor-sonnet-5-high |
-| [65,90)  | claude-opus-5-5     | low    | orc-executor-opus-5-low |
-| [90,100] | claude-opus-5-5     | medium | orc-executor-opus-5-med |
-
-(Haiku has no effort ladder — that agent carries no `effort:` field.) The risk
-floor (≥70) lands `orc-executor-opus-5-low` at minimum in THIS table. Above ~65
-the useful dial stopped being the model GENERATION and became the EFFORT, which
-is why the old four Opus rows are two. **Every band from 65 needs an Opus 5.5 MAIN
-session** or it silently falls back to the session model (the tier-honesty rule
-reports the downgrade) — two bands where it used to be one, and that is the cost
-of this table.
-
-**Four executors are named by NO band** — `orc-executor-opus-4-7-med`,
-`orc-executor-opus-4-7-high`, `orc-executor-opus-4-8-high` and
-`orc-executor-opus-5-high`. They still ship, reachable through
-`rubric_bands_override`, `orc diy`'s `fixed_executor` and `extra_fallback_agent`.
-Not deleted, because this is a TABLE change and not a model change — and an
-agent's model change is always a rename.
+| [0,21)   | claude-sonnet-5-5 | low    | orc-executor-sonnet-5-low |
+| [21,31)  | claude-sonnet-5-5 | medium | orc-executor-sonnet-5-med |
+| [31,41)  | claude-sonnet-5-5 | high   | orc-executor-sonnet-5-high |
+| [41,90)  | claude-opus-5-5   | low    | orc-executor-opus-5-low |
+| [90,100] | claude-opus-5-5   | medium | orc-executor-opus-5-med |
+
+The risk floor (≥70) lands `orc-executor-opus-5-low` at minimum in THIS table.
+Above ~65 the useful dial stopped being the model GENERATION and became the
+EFFORT, which is why the old four Opus rows are two. **Every band from score 41
+needs an Opus 5.5 MAIN session** or it silently falls back to the session model
+(the tier-honesty rule reports the downgrade) — that is the cost of this table.
+
+**Seven executors are named by NO band** — `orc-executor-haiku-4-5`,
+`orc-executor-sonnet-4-6-med`, `orc-executor-sonnet-4-6-high`,
+`orc-executor-opus-4-7-med`, `orc-executor-opus-4-7-high`,
+`orc-executor-opus-4-8-high` and `orc-executor-opus-5-high`. They still ship,
+reachable through `rubric_bands_override`, `orc diy`'s `fixed_executor` and
+`extra_fallback_agent`. Not deleted, because this is a TABLE change and not a
+model change — and an agent's model change is always a rename.
 
 ### The Opus-5-only ladder (`opus5_only`, default **false**)
 
@@ -64,10 +62,10 @@ One model, EFFORT as the cost dial. Off by default; nothing changes until set.
 
 Two bands, sharing the 90 edge with the default table's top two rows. That
 symmetry is the point: once the default table's high end is already Opus 5.5 with
-effort as the dial, this mode differs from it only BELOW 65, so a third band
+effort as the dial, this mode differs from it only BELOW 41, so a third band
 would be a distinction the default table stopped making.
 
-**Tier cost:** today TWO bands in six need an Opus 5.5 main session; with this on,
+**Tier cost:** today two bands in five, from score 41, need an Opus 5.5 main session; with this on,
 EVERY dispatch does, so a lower session downgrades every task (warn-only — a
 hook can gate effort, never model). **Scope:** it is NOT executor-only — it also
 forces every fixed role below, across every lane. orc-diy's table
@@ -84,7 +82,7 @@ un-shown number.
 |------|-------|
 | System Analyst | orc-system-analyst-opus-5-high |
 | Requirement Planner | orc-planner-opus-5-med |
-| Reviewer | orc-reviewer-opus-5-med |
+| Reviewer | orc-reviewer-opus-5-low |
 | Verifier | orc-verifier-opus-5-med |
 | Mini analyst | orc-analyze-mini-sonnet-5-high |
 | Mini planner | orc-planner-mini-sonnet-5-high |
@@ -95,7 +93,7 @@ un-shown number.
 
 Under `opus5_only`, every role above that is not already `claude-opus-5-5`
 dispatches its Opus 5.5 variant instead — plus the roles owned by other lanes
-(scout, wiki scanner, CLAUDE.md writer, retro miner, fast executor).
+(scout, wiki scanner, retro miner, fast executor).
 
 ## Where each subsystem's rule is written down
 
@@ -120,7 +118,7 @@ value participates in, and each has exactly one canonical copy.
 | Foreign dispatch | `extra_enabled` and the `extra_*` block; every armed run prints its `extra:` line at Phase 1 | `../_shared/extra-dispatch.md` |
 | Stacked PRs | the `stacked_pr*` keys gate the Phase 8 stack (full `/orc` + `/orc-ultra` only) | `../orc-pr-setup/SKILL.md` |
 | Retro | `retro_repo` is where `/orc-retro` files its report; it hard-gates on a delivery channel and does not run at all without one | `../orc-retro/SKILL.md` |
-| Paths | `log_dir` (traces, NEVER auto-deleted), `run_dir` (`.claude/orc/run` — outside the installer's blast radius), and the analyst/planner/report dirs | `../_shared/config-precedence.md` |
+| Paths | `log_dir` (traces — kept until you run `orc clear logs --apply`, or until the automatic sweep removes them: `log_retention_auto: on`, older than `log_retention_days`), `run_dir` (`.claude/orc/run` — outside the installer's blast radius), and the analyst/planner/report dirs | `../_shared/config-precedence.md` |
 | Ultra | **no config key at all** — `/orc-ultra` forces its overrides RUN-SCOPED and never writes them to `orc.config.yaml` | `references/ultra-mode.md` |
 
 **TDD — Lane policy (fixed, not configurable).** Full orc + ultra always on ·

package/templates/skills/orc/examples/full-run-mock.md

@@ -58,6 +58,7 @@ O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:l
 
 ## Phase 7 — Summary
 O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
+O: review close → `orc gotcha observe` ×3 (P1 addressed · 2× P3 wontfix, each with `run`) → `FINDING-OUTCOME addressed=1 disputed=0 wontfix=2 open=0 pre=0 suppressed=0 :: functional.check:1/1,evolvability.documentation:0/2`
 
 ## Phase 8 — Ship (orc-pr, reads pr.md)
 O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
@@ -66,7 +67,7 @@ O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-
    Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
 
 ## What this exercises
-always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 6-band ladder ·
+always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 5-band ladder ·
 per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
 planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
 build/test proof) · reviewer quote spot-check before any P0/P1 action ·