@azure-id/orc 2.0.2 → 2.1.1

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