@azure-id/orc 0.55.0

package/templates/skills/orc/references/trace-protocol.md

@@ -0,0 +1,314 @@
+# Reference — Behavior-Trace Protocol
+
+How ORC records its own behavior for later review. **Behavior-trace logging is
+PERMANENT (always on) — there is no config toggle.** Every ORC run traces.
+
+Purpose: capture the flow of a run — phases, spawns, the model that actually
+answered, scoring decisions, user questions, review/verify outcomes — so the
+skills can be improved from real traces. This is NOT the decision log
+(`run/…md`, agent knowledge, deleted on success). The trace is a separate,
+**persistent** artifact and the two never mix.
+
+## Always on
+
+There is no gate. Behavior-trace logging is PERMANENT — every run traces. The
+`orc-trace.js` hook is the deterministic guarantee: on the first ORC-agent
+dispatch it bootstraps `log_dir` + the run pointer itself, so a `.txt` is created
+for every run even if the orchestrator never writes a rich marker. Only
+`log_dir` (default `.claude/orc/logs`) is configurable.
+
+## Narration is DISPATCHED, not remembered (v0.32.0 — the core rule)
+
+Two earlier fixes bet on the orchestrator remembering to append rich lines; both
+failed under real load (long runs, compaction, parallel waves), leaving traces
+with nothing but the hook's `SPAWN`/`RETURN` skeleton. The one behavior a run
+performs reliably is **dispatching agents**. So narration moved onto it:
+
+> **Phase close = build the phase packet + dispatch `orc-trace-writer-haiku-4-5`.**
+
+The orchestrator supplies the facts; the pinned Haiku writer holds the pen and
+appends the block. Three properties make this hold:
+
+- **Pairing rule (the anti-forget mechanism).** The writer dispatch for phase N
+  is issued **in the same tool block as phase N+1's first dispatch** — logging
+  piggybacks on the very action the model reliably performs. A phase with no next
+  dispatch (FINISH, an abort, a pure-question phase) dispatches the writer SOLO,
+  before printing that phase's user-facing output.
+- **First dispatch is solo and synchronous** — before the planner/analyst goes
+  out. It carries `run_meta` and performs the rename repair (below) while nothing
+  else is in flight.
+- **Last dispatch (run end).** The FINISH packet (final report summary, ship
+  state, verdict totals) goes out and RETURNS before you delete `.current`.
+
+The writer's own `SPAWN`/`RETURN` are logged like any `orc*` agent — deliberately:
+**a writer SPAWN per phase is the deterministic proof that narration happened**,
+and that is exactly what `/orc-retro` audits (narration coverage).
+
+### Phase packet (passed inline in the dispatch prompt — small, plain YAML)
+
+```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
+                          # (`ultra` = an /orc-ultra run; the ONLY lane the orc
+                          #  spine can emit besides `orc`. No other value here
+                          #  is legal — a lane no entry point opens is a lane
+                          #  every counting tool reports as permanently zero.)
+  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 from the CLOSED set below
+  - {ts: "240726 00:28:16.220", verb: "DISPATCH orc-executor-sonnet-4-6-high",
+     tail: "T2 pairs expect=claude-sonnet-4-6/high"}
+  - {ts: "240726 00:30:39.881", verb: "VERIFY T2", tail: "actual=claude-sonnet-4-6/high ✅ MATCH"}
+decisions: >              # free text — the WHY layer
+  T2 kept at band [40,55) despite fan_out=3: the three consumers are
+  generated. User answered "no new deps" verbatim; rejected the adapter split.
+```
+
+- The packet is built from the phase's **actual working state as the phase
+  closes** — never reconstructed later from memory.
+- `ts` is each event's REAL time. The writer stamps nothing itself: the block is
+  a faithful late append of events that happened seconds ago, not an end-of-run
+  summary. Retro sorts by stamp, not by file order.
+- Subagent-returned markers (`QUESTION`, `FINDING`, `VERDICT`, a return's
+  `actual_model`) are folded into the NEXT packet, never written directly.
+- `VERIFY` stays an orchestrator OBLIGATION — you compare claimed vs actual and
+  surface any ⛔ DOWNGRADE to the user in chat; only the LINE travels by packet.
+- The writer NEVER invents: an absent field is omitted, never guessed.
+
+### 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 (intake+plan, execution, ship); orc-fast to 2 (preflight+dispatch, gate+ship) |
+| Multi-dispatch | `orc-wiki`, `orc-pr-driver` (lane `prdriver`) | orc-wiki: one per scan-batch boundary (the points that already run the registration sync / offer the pause) + the end-of-run packet. orc-pr-driver: one per LAYER boundary (each layer's green gate closes) + the end-of-run packet |
+| Composed | `orc-diy` | one packet per ENABLED phase group, **minimum 2** — the flow shape is user-composed, so the count is too (the compiled flow carries this block automatically) |
+| Iterative | `orc-quick`, `orc-challenge` (lane `challenge`), `orc-doc` (lane `doc`) | **one packet per completed numbered entry** + the end-of-run `FINISH` packet — the lane loops on user requests, so the count follows entries, not phases. For `orc-challenge` the unit is one completed ITERATION (C2→C8), and the packet goes out at the stop; on a PASS it is the `FINISH` packet. **Several trace files for one cycle is CORRECT** — several sessions ran, and `orc stats` counts several. For `orc-doc` the unit is one completed WAVE, and the packet is the LAST step of the stop sequence |
+| Single-dispatch | `orc-claude`, `orc-plan`, `orc-analyze` (+ mini), `orc-pattern`, `orc-verify`, `orc-learn`, `orc-poly`, `orc-pr-setup` (lane `prsetup`), `orc-grill`, `orc-route`, `orc-brainstorm` (lane `brainstorm`), `orc-pact` (lane `pact`), `orc-boundary` (lane `boundary`), `orc-handoff` (lane `handoff`), `orc-budget` (lane `budget`), `orc-aftermath` (lane `aftermath`), `orc-export` (lane `export`) | **exactly ONE mandatory end-of-run packet** |
+
+**`context-combiner` is NOT a lane — it is a PHASE inside the analyze run.** It
+has no slash command and no entry point of its own: `orc-analyze` Phase F
+dispatches it while `.current` still points at that run's `run-analyze-…` file.
+So it never writes a pointer, never touches a trace file, and never emits its own
+`FINISH`; its `DISPATCH`/`RETURN`, its Phase D challenge verdicts and its
+conservation-gate result all fold into **orc-analyze's** end-of-run packet. The
+hook agrees — `context-combiner` maps to its own `PHASE-EDGE` role family
+(`combine`), which segments the phase *within* that trace. Listing it as a lane
+(as this table did before v0.42.0) declared a run nothing could ever open.
+
+**The single-packet obligation is defined HERE, once** (every trace-owning lane
+already loads this reference) — micro-lane spines keep only their existing trace
+pointer. That packet is dispatched SOLO after the lane's main return validates
+and BEFORE `.current` is deleted; it carries `run_meta` (so the rename repair
+works there too) plus the lane's whole event list: intake decisions, the user's
+answers, `DISPATCH`/`VERIFY`, gate/verdict lines, `FINISH`. One Haiku call per
+run buys the WHY layer for every lane. Haiku cost is noise against any run's
+executor spend.
+
+`/orc-retro` is the ONE exception: it mines traces and writes none (its hard
+rule 4). The hook enforces this — `orc-retro-*` dispatches never bootstrap a
+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
+  its sidecars (`.pending.json`, `.jsonl`); generated reports live in
+  subfolders (`retro/`).
+- One file per run: **`run-<lane>-<slug>-<DDMMYY>-<HHMMSS>.txt`**, append-only.
+  - `lane` — the trace-owning skill's short name (`orc`, `ultra`, `mini`, `fast`,
+    `diy`, `wiki`, `analyze`, `plan`, `claude`, `poly`, `learn`, `verify`,
+    `pattern`, `prsetup`, `prdriver`, `quick`, `grill`, `route`,
+    `brainstorm`, `challenge`). Every value
+    here is a lane some entry point actually opens — keep it that way: this
+    list IS the lane vocabulary `orc stats` and `/orc-retro` count against.
+  - `slug` — kebab-cased short user context from the intent (`[a-z0-9-]`, ≤32
+    chars, filesystem-safe, no trailing hyphen) — same derivation as the
+    run-folder slug.
+  - `HHMMSS` — so two same-day runs never collide.
+  - e.g. `run-orc-cas-multi-exchange-withdrawal-240726-002352.txt`.
+  - The name is DATA: `/orc-retro` aggregates per lane straight from it, without
+    parsing content.
+- 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 naming a file that does not exist yet is indistinguishable
+  from a dangling one by content alone, and that is what used to split a run
+  across two files (a generic bootstrap holding the hook skeleton + a rich file
+  holding every narrated line, each looking correct alone). Delete the pointer at
+  run end (success or abort). The `orc-trace.js` hook reads it to know which file
+  to append to, and since v0.34.2 it also honors a POINTER whose mtime is fresh
+  even when the file is not there yet — the two fixes are independent on purpose.
+- **A SUSPENDED lane re-writes its pointer on RESUME.** When a lane hands control
+  to another lane and expects it back (`_shared/lane-suspend.md`, `RETURN-TO`),
+  the receiving lane DELETES `.current` at its own `FINISH`. So on return the
+  suspending lane re-writes `.current` and must `touch the trace file` it names,
+  in the SAME step — both, or neither. Otherwise every line it writes after the
+  return goes nowhere: the v0.34.2 split-run signature, reached by a different
+  road. Two traces for a suspend is CORRECT — two lanes ran, and `orc stats`
+  counts two.
+- **Rename repair (deterministic-with-repair, not memory-only).** When no usable
+  pointer exists as the first ORC-agent dispatch fires, the hook creates the
+  folder + a generic `run-<DDMMYY>-<HHMMSS>.txt` and points at it. The FIRST
+  writer dispatch repairs that. **The trigger is a DISK COMPARISON, not a
+  remembered state:** repair when `.current` on disk DISAGREES with the packet's
+  `run_meta.trace_path` — a rich packet name beside a generic pointer IS the
+  clobber signature, every time — regardless of whether the pointer was ever
+  missing. (Stated the old way — "if the pointer is missing" — writers correctly
+  declined to repair, because that is not the state the hook actually leaves.)
+  The repair is a **MOVE** of the `.txt` plus its `.pending.json` / `.jsonl`
+  siblings, then a rewrite of `.current` — never a fresh create beside the
+  bootstrap file, which splits the run's evidence in two. Non-ORC Tasks never
+  trace — the hook only bootstraps for agent names starting with `orc`.
+
+## Structured companion (`<trace>.jsonl`)
+
+The `.txt` stays the canonical, human-skimmable trace. The writer ALSO appends
+each packet event as one JSON line to `<trace>.jsonl`:
+`{ts, actor, phase, verb, tail, …verb-specific fields}`. `/orc-retro` mines the
+`.jsonl` when present — `SCORE`/`OUTCOME`/`VERIFY` aggregation becomes robust
+without regex over free tail text — and falls back to `.txt` parsing for older
+traces. Hook lines stay `.txt`-only; the two are read together.
+
+## Write cadence — append AS THE RUN GOES, never in one batch at the end
+
+The trace is a **running record**, not an end-of-run report. Each phase's packet
+goes out AT that phase's close — coupled to the next phase's first dispatch:
+
+| Moment | Packet carries |
+|--------|----------------|
+| a phase closes | that phase's events + the decisions behind them |
+| dispatching an agent | the `DISPATCH` line (folded into the closing phase's packet) |
+| a return validates | its `VERIFY` + any subagent-returned marker |
+| a task closes | its `OUTCOME` |
+| review/verify verdict | `FINDING` / `VERDICT` |
+| run end | `FINISH` — dispatched SOLO and returned before `.current` is deleted |
+
+**Self-check:** a phase that ends with
+`zero new trace lines is a protocol violation`.
+The failure this prevents is a fully-executed run behind a one-line trace. If a
+phase went by without its packet, dispatch the writer NOW with the events' real
+timestamps rather than skipping them — a late block with true stamps is a late
+record; a block stamped "now" is a FALSE one. Batching everything at `FINISH` is
+the classic failure: by then the run's context is compacted and the detail is gone.
+
+## Line format
+
+`[DDMMYY HH:MM:SS.mmm] <actor>  <VERB> :: <free tail>`
+
+Fixed columns → human-skimmable now, column-parseable by a future mining tool.
+Actors: `hook`, `orc` (the default for a packet event with no actor), a role/agent
+short name (`analyst`, `planner`, `reviewer`, `verifier`, `T<n>` for an executor
+task), or `writer` — which means the narration agent speaking for ITSELF (its
+`NOTE` line), never a blanket stamp on events it was handed. **The actor is
+per-EVENT.** The writer copies `events[].actor` into both the `.txt` column and
+the `.jsonl` `actor` field, so the pair can never disagree about the same event
+(they did, and retro reads the `.jsonl` first).
+
+## Verb set (CLOSED — never invent new verbs)
+
+"Emitted by" now reads **orc → writer** for the narrated verbs: the orchestrator
+supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
+`PHASE-EDGE` stay hook-owned and need no cooperation at all.
+
+| Verb | Emitted by | Meaning |
+|------|-----------|---------|
+| `PHASE <name> start\|end` | orc → writer | phase transition |
+| `PHASE-EDGE <role-family> :: first=<agent>` | hook | **deterministic phase inference.** ORC agent names encode their role, so when a SPAWN's role family differs from the previous SPAWN's, the hook segments the run itself — families: `analyst\|scout → analysis`, `planner → planning`, `executor → execution`, `reviewer → review`, `verifier → verify`, `test-author → testgen`, `advisor\|judge → ultra-gate` (the trace writer never opens an edge). Zero model dependence: even a run where every writer dispatch was forgotten still reads planning → execution → review → verify, and `/orc-retro` computes NARRATION COVERAGE from edges with vs without a writer `SPAWN` between them |
+| `CONFIG <key=value …>` | orc → writer | Phase 1 — the resolved config values this run will consume (incl. `fable5_*` when enabled, and ALWAYS `opus5_only` — it selects the executor table AND every fixed role, so retro can segment outcomes by dispatch mode). Runtime proof that the run honored the config; `/orc-retro` audits it against behavior |
+| `WIKI-CONSULT <tier> :: docs=<list>` | orc → writer | project wiki consulted for grounding (full/mini at planning; fast at slice-build) — tier ∈ `fresh` \| `aging` \| `stale` \| `absent` \| `empty`; `docs=` the pages pulled/handed to the executor (comma list) or `none`. Records whether the run grounded in the wiki and whether it was stale (surfaces grounding + staleness for later audit) |
+| `CROSSLINK <state> :: boundaries=<n> peers=<names>` | orc → writer | cross-repo peer-knowledge state at the consult point — state ∈ `cached` (peer cache present) \| `configured-no-cache` (crosslink configured but the cache is not built) \| `none`. Per-task `CROSSLINK inject task=<id> :: <boundary>` when a slice receives a linked contract. Records whether peer contracts were injected this run (full orc consumes only the pre-built crosslink cache — it never reads peer source live; mechanism in `references/wiki-consult.md`) |
+| `SPAWN <agent>` | hook | an agent dispatch was observed (skeleton) |
+| `RETURN <agent> :: <desc> dur=<m>m<s>s [model=<id>]` | hook | a subagent finished (skeleton). The hook attributes the RETURN to the finishing agent from the SubagentStop payload (`~<agent>` = approximate FIFO match on older Claude Code that omits `agent_type`; `~agent :: unattributed` = ≥2 agents in flight, so it deliberately claimed NO pending record rather than starve the right one), echoes the SPAWN's desc + wall-clock duration, and appends `model=<id>` when the return's `actual_model` is visible in the last message. A duplicate stop for an agent whose record was already consumed is DROPPED, never written as a desc-less RETURN. Still hook-written skeleton — NOT an orchestrator obligation; the authoritative model check is the `VERIFY` line |
+| `DISPATCH <agent> :: <task> expect=<model>/<effort>` | orc → writer | orchestrator dispatched a named agent (the claim). **A FOREIGN dispatch appends `via=extra:<profile>`** and its `expect=` names the profile's model rather than a Claude tier — additive, the way `/orc-doc`'s `sections=` was. A foreign worker is not a Claude subagent, so the hook emits NO `SPAWN` and NO `RETURN` for it (P7, the `/orc-quick` ad-hoc-recon precedent): this line and `EXTRA` are the whole record, which is why neither is optional. **The `/orc-doc` lane's tail NAMES ITS SECTIONS** (v0.49.2) — `doc write sections=03-scope,04-risks part=sections/03-scope.md`, `doc check sections=03-goals`, `doc digest source=<path>` — which is the only thing that makes `orc doc cost`'s per-section attribution honest rather than a guess. It is additive: the tail was already captured whole |
+| `SCORE task=<id> score=<n> band=<range> model=<m> facets=<compact-vector> :: <reason>` | orc → writer | scoring decision (tunes the rubric). **A task the resolver sent foreign appends `via=extra:<profile>`**, and `model=` is the foreign model id — so `/orc-retro` can segment a band's outcomes by WHO ran it. `facets=` is the planner-emitted vector (breadth·novelty·logic·test·fan·unc·risk) the score was computed from — `/orc-retro` reads it to recalibrate the formula. Fix-cycle dispatches emit `SCORE task=fix-<n> …` the same way |
+| `VERIFY <task> actual=<model>/<effort> ✅ MATCH` / `⛔ DOWNGRADE expected=<m>/<e>` | orc → writer | claimed-vs-actual model check (the COMPARISON stays the orchestrator's obligation — surface a downgrade to the user, not just the trace) |
+| `QUESTION count=<n> :: <topic>` | subagent→orc → writer | stopped to ask the user |
+| `CONTEXT-GAP :: <what was already known>` | subagent→orc → writer | asked/re-derived something already in context |
+| `REPLAN wave=<n> :: <reason>` | orc → writer | re-planned after a conflict/failure |
+| `GATE <name> pass\|bounce\|escalate :: <detail>` | orc → writer | exit-gate result — name ∈ grounding \| coverage \| graph \| evidence \| derivation \| facet (the plan's facet-vocabulary check, `effort-and-mode.md`) \| schema (the plan-handoff schema check) \| judgment (ultra; `escalate` is judgment-only) \| wave-boundary \| budget (the Phase-1 `run_budget_dispatches` forecast gate — `pass` or the `stop` that blocks wave 1; emitted only when the key is > 0) \| stack-gate (Phase 8 stacked-PR threshold + handoff) \| stack-certainty (a stacked-PR seam decision) \| layer-green (one layer's green-gate ladder). The shared-band SIBLING-CONSISTENCY determination is NOT a gate name — carry it in the packet's `decisions`, never as an invented verb. Bounce detail lists the misses (feeds `/orc-retro` gate-bounce rates) |
+| `ADVISE :: brief=<path> questions=<n>` | orc → writer | ultra Phase U0 — advisor brief received, clarification round relayed |
+| `JUDGE <gate> <verdict> round=<n> blocking=<n> advisory=<n> downgraded=<n>` | orc → writer | ultra judgment verdict (gate ∈ analysis \| plan \| implementation) |
+| `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 (feeds `/orc-retro` calibration) |
+| `FINDING p0=<n> p1=<n> p2=<n> p3=<n>` | reviewer→orc → writer | review outcome (P0–P3 severity ladder) |
+| `VERDICT pass\|fail :: <detail>` | verifier→orc → writer | verification outcome |
+| `DRIFT loop=<n> :: <user description, compressed>` | orc → writer | mock-example drift-recovery loop opened (`PHASE mock-example`; canonical `_shared/drift-recovery.md`; hard cap 2 loops) |
+| `TDD-RED task=<id> iter=<n> :: <failing tests>` | executor→orc → writer | TDD repair-loop iteration — the plan's acceptance tests still red (cap `tdd_loop_max`; a paired TDD task's red proof also emits iter=0) |
+| `TDD-GREEN task=<id> iter=<n>` | executor→orc → writer | the task's TDD acceptance tests pass (the non-exempt definition-of-done) |
+| `NOTE :: <decisions>` | writer | the packet's `decisions` field — the WHY layer (scoring rationale, user answers verbatim, what was rejected). One line per packet, only when `decisions` is non-empty |
+| `STATS lane=<l> slug=<s> dispatches=<n> waves=<n> tasks=<n> bands=<h:n,m:n,l:n> downgrades=<n> duration_ms=<n>` | orc → writer | ONE deterministic summary line per run, in the `FINISH` packet, immediately BEFORE the `FINISH` line. This is what `orc stats` reads — one line per file, never a parse of the whole trace. Omit a field you genuinely do not have (a lane with no waves omits `waves=`); never guess one. Every trace-owning lane emits it, not just `orc` |
+| `PACT <state> :: <ids>` | orc → writer | invariant-ledger state at the Phase-1 probe (`pact_gate`), and `PACT inject task=<id> :: <PACT-id>` when a DRIFTED/BROKEN promise is appended to a task's `constraints[]`. `PACT recheck pass\|fail :: <ids>` at Phase 6. Records whether last month's decisions constrained this month's plan |
+| `BOUNDARY <verdict> task=<id> :: <area>` | orc → writer | per-task boundary verdict (verdict ∈ `EXECUTE` \| `ESCALATE` \| `REFUSE` \| `unknown` — an uncarded area is UNKNOWN, never REFUSE), plus `BOUNDARY lift task=<id> :: <area>` when `boundary_gate: block` removes ONE task from a wave (the wave still runs). `/orc-retro` reads these to answer the question the lane exists for: how much work did we stop attempting, and was that right |
+| `CHALLENGE iter=<n> findings=P0:<n>/P1:<n>/P2:<n> coverage=<n>% verdict=PASS\|FAIL` | orc → writer | one line per completed `/orc-challenge` iteration boundary. **Copy `orc challenge record`'s `trace_line` verbatim** — the CLI assembles it so the lane never composes a second wording for the same number. Plus `CHALLENGE accept :: <id>` and `CHALLENGE rebut :: <id>` when an escape valve is used, and `CHALLENGE regoal\|retemplate :: v<n>` on a re-freeze. `/orc-retro` reads the sequence to answer whether a cycle converged or stalled |
+| `EXTRA <profile>/<model> engine=<api\|claude-shim\|cli> task=<id> band=[lo,hi) tok=in/cw/cr/out outcome=<done\|partial\|failed\|fallback> dur=<m>m<s>s` | orc → writer | one line per FOREIGN dispatch — a slice that executed on a non-Claude worker (`_shared/extra-dispatch.md`). **Copy `orc extra dispatch`'s `trace_line` verbatim** — the CLI assembles it, exactly as `orc challenge record` does, so the lane never composes a second wording for the same numbers. Plus `EXTRA fallback task=<id> :: <reason> → <agent>` when a failed foreign dispatch re-dispatches to Claude (P6), `EXTRA substitution task=<id> :: requested=<m> reported=<m>` / `EXTRA reroute task=<id> :: <providers>` when the endpoint answered with a different model, or the same model served by a different company, and — v0.54.0 — `EXTRA resume task=<id> attempt=<n> :: from=<reason> attribution=<verdict> target=<extra:profile\|agent> files_preexisting=<n>` when a dispatch CONTINUES a position an earlier attempt left on disk, plus `EXTRA orphan task=<id> :: attempt=<n> lease-expired files_changed=<n> state=<state>` when preflight reports a dispatch that never reported back. **A resume that leaves no line cannot be counted** — neither `orc extra stats` nor `/orc-retro` can then learn whether resuming works, or which providers ignore the resume preamble. `EXTRA resume` rides in the resumed dispatch's own `trace_extras[]`; `EXTRA orphan` is the LANE's to emit after it reports, the same ownership rule as `EXTRA fallback`. **`tok=none` is a real value** and the ONLY correct one when the worker reported no counts (engine `cli` often does not): `tok=0/0/0/0` would tell `/orc-budget` the run was free, while a measured zero — engine `api`'s `cw`, always — is a different fact. **On a lane with no score `band=` carries `slot:<slot>`** (v0.55.0 — `slot:doc-writer`, `slot:wiki-scanner-light`): the field NAME is unchanged, so this parser, the eight-field dedupe and the ` :: ` tolerance are untouched, and `orc extra stats` gives each POSITION its own row for free. This is the verb `/orc-retro` reads to answer the only question that matters: is the cheap model actually cheaper once you count the repairs |
+| `FINISH :: <detail>` | orc → writer | run ended |
+
+`SPAWN`/`RETURN`/`PHASE-EDGE` come from the hook automatically. Every other verb
+reaches the file through a packet — you never append lines by hand.
+
+### Why `STATS` exists as its own line (v0.42.0)
+
+`orc stats` counts usage from these files. Lane and date are free — they are in
+the filename, which is already DATA. Everything else would cost a full parse of
+a 20-minute trace, per run, forever. One deterministic line at a step that
+already exists makes the depth free instead: `orc stats` reads the tail of each
+file and nothing more.
+
+Two consequences to keep true, because a counting tool built on a drifting log
+produces confident WRONG numbers, which is worse than no numbers:
+
+- **A run with no `FINISH` is counted as unfinished, permanently.** That is
+  correct behaviour and it is why `FINISH` is mandatory even on an abort.
+- **A trace older than v0.42.0 has no `STATS` line.** `orc stats` falls back to
+  counting `DISPATCH` lines — orchestrator-written and present in every lane
+  (including `/orc-quick`, whose ad-hoc recon emits no `SPAWN`/`RETURN`). Old
+  traces still count, with less detail. Never back-fill a `STATS` line into an
+  old trace: the numbers would be invented, and the trace is append-only.
+
+**Skeleton caveat (read every retro metric with it):** the hook only sees a NEW
+dispatch. CONTINUING an already-running agent fires no PreToolUse/SubagentStop
+pair, so a lane driven by continuing one agent produces fewer `SPAWN`/`RETURN`
+lines than it did real work. The skeleton is a FLOOR on dispatch volume, never a
+census — narration coverage computed from it reads low, not wrong.
+
+## Model source of truth — the claimed-vs-actual check
+
+A hook cannot read a subagent's model id (it lives only in the subagent's system
+prompt). So each dispatched agent returns two fields (see each agent's return
+contract):
+
+- `actual_model` — **quoted verbatim** from the agent's injected system-prompt
+  model-id line ("The exact model ID is …"). Never a guess; `unknown` if absent.
+- `actual_effort` — the value of `$CLAUDE_EFFORT` (env var, read via Bash).
+
+For each spawn the orchestrator:
+1. Derives the **expected** `(model, effort)` from the dispatched agent NAME via
+   the `config.md` score→model table / `MODEL-MAPPING.md`.
+2. Compares against the returned `actual_*` and puts a `VERIFY` line in the next
+   packet — `✅ MATCH` or `⛔ DOWNGRADE`. A downgrade (the harness capped a high
+   pin to the main-session tier) is surfaced to the user, not just logged.
+
+## Announce-on-spawn
+
+When dispatching, announce the model to the user, derived from the agent NAME
+(e.g. "Spawning orc-executor-opus-4-7-high → claude-opus-4-7 / high"). Derive it
+from the name — do NOT pass the coarse `sonnet|opus|haiku` dispatch arg, which
+cannot express 4-7 vs 4-8 and would override the frontmatter pin.
+
+## Compaction safety
+
+The checkpoint carries `logging_enabled` + `trace_path`. On resume, re-read them
+and continue dispatching packets against the same file. The hook backbone keeps
+emitting `SPAWN`/`RETURN`/`PHASE-EDGE` regardless of orchestrator memory, so a
+compacted run is never blind — at worst it loses the WHY layer for one phase.
+`/orc-ultra` is the `orc` skill with `ultra_mode: true`; its packets are just
+orc's plus the U0/judge ones.
+
+## Write discipline
+
+- Append-only; one whole block per append (never edit prior lines).
+- The trace records behavior faithfully — including the ugly bits (over-asking,
+  downgrades, failed waves). That honesty is the whole value.

package/templates/skills/orc/references/ultra-mode.md

@@ -0,0 +1,123 @@
+# Reference — Ultra Lane (load only when `ultra_mode: true`)
+
+`/orc-ultra` runs the FULL pipeline with maximum rigor for complex and
+ultra-complex requests. Everything in SKILL.md still applies; this file adds
+the ultra deltas. Ultra exists ONLY here — never in orc-mini, never on a plain
+`/orc` run.
+
+Cost stance: ultra is costly by definition. State it once at intake
+("ultra adds an Opus 5 xhigh advisor + up to 3 judge dispatches + revision
+loops"), then never prompt about cost again.
+
+## Forced overrides (run-scoped — NEVER written to the user's config file)
+
+Apply at Phase 0, on top of the normal config resolution:
+- analysis depth = **deep**, no ask (the analyst's standard/deep gate is
+  bypassed; `default_analysis_depth` is ignored; scouts dispatch as usual).
+- `pattern_findings` = on · `generate_tests` = on · `security_review` = on.
+- Executor **tier floor**: remap the resolved score→model table so no task
+  dispatches below `orc-executor-sonnet-5-high`; bands at/above the preset's
+  opus boundary rise to at least `orc-executor-opus-4-8-high` — the floor only
+  ever raises a band, so the top `[90,100]` band keeps `orc-executor-opus-5-high`.
+  **Under `opus5_only` the floor raises EFFORT, not model** (every band
+  is already Opus 5, so there is no model left to raise): the `[0,40)` band rises
+  low → medium, and the other two are already at/above it. It is still a floor —
+  it never lowers a band, and it never raises `[80,100]` past high.
+  Show the remapped table with the Phase 2 scoring table.
+
+> Opus-5-only mode: if `opus5_only`, every role this lane dispatches is already
+> Opus 5 (advisor and judge are pinned there by default) and the scouts rise to
+> `orc-scout-opus-5-low`. It FORCES — the Fable 5 note below does not apply
+> while it is on. See `../../_shared/opus5-only.md`.
+
+> Fable 5 role override: (INERT while `opus5_only`) if `fable5_enabled` and
+> `advisor` / `judge` are in `fable5_roles`, dispatch the `orc-advisor-fable-5` /
+> `orc-judge-fable-5` variant instead of the Opus 5 xhigh default — same slice,
+> same contract. See `../../_shared/fable5-override.md`.
+
+## Phase U0 — Advisor (after intake sign-off, before the analyst)
+
+Dispatch `orc-advisor-opus-5-xhigh` (see `../../orc-advisor/SKILL.md`) with
+the request, the run-folder path, and the detected stack. Validate the return
+(`brief_path`, `open_questions[]`, `assumptions[]`, actual model/effort
+fields). Then:
+
+1. Relay `open_questions[]` to the user in ONE batched round. Fold answers
+   into the intent-spec; unanswered questions fall back to the advisor's
+   proposed default and enter the ledger as UNCONFIRMED.
+2. Create `run/{run-slug}/ultra/assumption-ledger.md` from `assumptions[]`.
+   Every later phase appends: `assumption → confirmed-by-user |
+   confirmed-by-code-evidence (anchor) | UNCONFIRMED`. You alone write it
+   (workers return candidate entries; you record them).
+3. Inject the brief VERBATIM (never a pointer) into the analyst slice, the
+   planner slice, every judge slice, and — as advisory notes — every executor
+   slice. The rubric section is what the judges score against.
+
+The advisor runs once; it is never re-dispatched. Record `ADVISE` into the U0
+packet — ultra adds ONE writer packet for U0 and one per judge gate on top of
+orc's phase packets (`../references/trace-protocol.md`), so the advisory brief,
+the questions relayed, and each verdict round are narrated like any other phase.
+
+## The three judgment gates (dispatch `orc-judge-opus-5-xhigh`)
+
+Shared mechanics — verdict validation, blocking-finding downgrade enforcement,
+REVISE loops (author echo `finding_id → resolution`, re-judge convergence
+rule, hard cap 2 per gate), the ESCALATE menu, advisory carry-forward, verdict
+persistence (`run/{run-slug}/ultra/verdict-<gate>-<round>.md`), and the
+`JUDGE` / `GATE judgment` trace events (packet-carried) — live in
+`../../orc-judge/SKILL.md`.
+Load it at the first gate. Loop counters + the ultra artifact paths go in the
+checkpoint (`ultra` block) so a resumed run continues mid-loop.
+
+Judge slices ALWAYS carry: the advisor brief (with rubric), the original
+request, the assumption ledger, and gate-specific evidence below. Never the
+author's reasoning or self-assessment.
+
+- **Gate 1 (analysis)** — after the analyst-return deterministic gates pass
+  (evidence spot-check + derivation lint) and the user's challenge round is
+  resolved. Slice adds: report + spec paths. REVISE → bounce to the analyst.
+  Gate approval does NOT replace the user's take-into-build choice.
+- **Gate 2 (plan)** — after the Phase 1 exit gate passes. FIRST build the
+  **blast-radius map** (deterministic, yours): for each task's declared
+  files, Grep the importers/callers of the symbols it touches; list any
+  caller file no task covers. Slice adds: planning-output + the map. REVISE →
+  bounce to the planner. Gate approval does not replace plan sign-off.
+- **Gate 3 (implementation)** — after Phase 6 (and 6.5). FIRST build two
+  deterministic inputs:
+  1. **Traceability matrix** (`run/{run-slug}/ultra/traceability-matrix.md`):
+     `R# → task → declared files → actual diff hunks (git diff) → verify
+     evidence`. An R# with an EMPTY diff column is a deterministically caught
+     missing implementation — dispatch the fix wave directly, no judge needed
+     for that miss.
+  2. **Static analysis**: run the project's own tooling on the changed files
+     when the stack detection found any (linter, sonar-scanner,
+     type-checker) — never install tooling. Inject results into the slice;
+     tool findings on changed lines are blocking input the judge triages.
+  Slice adds: matrix, changed-file LIST (never an inlined diff — the judge
+  reads matrix-guided via its own Read/Grep), verify report, static-analysis
+  results, the resolved pattern's blocking invariants. REVISE → scored
+  executor **fix wave** for only the affected tasks (findings verbatim in
+  slices) → re-verify → re-judge. All clear → Phase 7.
+
+## Verdict contract cross-check (validate like any worker return)
+
+`verdict` ∈ APPROVE|REVISE|ESCALATE · every blocking finding has a verbatim
+anchor + class-appropriate justification (`failure_consequence` for
+correctness/security; named category + concrete alternative for
+smell/simplification/placement) · `rubric_items_checked[]` covers the gate's
+rubric lines · `unconfirmed_assumptions_touched[]` present. Malformed →
+requeue the judge once, then escalate. Security findings with a concrete
+consequence are always blocking. APPROVE with zero findings is legitimate.
+
+## Phase 6.7 / 7 / 8 deltas
+
+The mock-example phase (spine Phase 6.7, `../../_shared/drift-recovery.md`)
+runs in ultra too — AFTER Gate 3 approves (an example of an unapproved
+implementation would demo drift the judge already caught); same `mock_example`
+config, same never-committed rule, same 2-loop drift cap. A drift-recovery
+patch wave re-enters Gate 3 (a changed implementation is re-judged).
+
+The summary additionally reports: per-gate verdicts + rounds, findings by
+severity and class, auto-downgrades, the assumption ledger's final state
+(UNCONFIRMED entries highlighted), and the traceability matrix path. Ship is
+unchanged — but never offer commit while a gate is unresolved.

package/templates/skills/orc/references/wave-grouping.md

@@ -0,0 +1,121 @@
+# Reference — Wave Grouping & Conflict Graph
+
+Turn the tagged task list into conflict-free waves. Load during Phase 3.
+
+## Waves are computed for EVERY run — dispatch style is intra-wave only
+
+Wave computation is NOT a parallel-mode concern. It runs for **every run with ≥2
+tasks, sequential included** (dependency layers + conflict graph +
+`max_wave_tasks` cap). **Dispatch style controls only INTRA-WAVE concurrency:**
+
+- **parallel** → a wave's non-conflicting tasks dispatch at once (up to
+  `max_wave_tasks`);
+- **sequential** → the SAME waves, but a wave's tasks dispatch one at a time, in
+  order; the wave still closes only when all its tasks close.
+
+Either way the **wave-boundary gate fires identically** (the deterministic batch
+pause below binds to wave numbers, not to a dispatch style). A sequential run
+therefore never degenerates to "no waves / per-task pauses" — a 5-task plan
+becomes e.g. `[T1] [T2 T3 T4] [T5]`, not five ad-hoc stops. **Show the wave plan
+(wave → tasks → pause marks) to the user BEFORE wave 1 in BOTH styles.**
+
+## The principle
+
+Two tasks may share a wave ONLY if their `declared_files` don't overlap AND
+neither depends on the other. Conflicts are designed out by scheduling — never
+negotiated at runtime.
+
+## Algorithm
+
+1. **Dependency edges:** a task's earliest wave = max(wave of its deps) + 1.
+2. **Conflict edges:** for every pair, mark conflict if `declared_files` globs
+   intersect (expand against the repo tree; unresolvable globs conflict on
+   their literal prefix).
+3. **Assign greedily in topological order:** place each task in the earliest
+   wave where (a) all deps are earlier and (b) nothing in that wave conflicts.
+   Otherwise open a new wave.
+4. **Cap concurrency at `config.max_wave_tasks`** (default 3): a wave NEVER
+   exceeds this many tasks, even if more are conflict-free. Overflow moves to the
+   next wave. This is the efficiency cap — 3 parallel subagents by default.
+5. **Mark batch pauses:** compute the pause schedule from the user's Phase 2
+   answer — mark `is_batch_pause: true` on wave W when `W % N == 0` AND a later
+   wave exists (`W < total_waves`); the last wave is NEVER a pause (nothing
+   remains to gate). The resulting wave indices are the `pause_schedule` stored
+   in the checkpoint. A pause so marked is a HARD gate (stop-and-resume.md), not
+   an orchestrator judgment call.
+
+## Same-feature collision
+
+If two tasks own the same feature/files with no dependency between them, the
+graph auto-serializes them — but that's a planning smell. Surface it: suggest
+merging them into one task rather than silently serializing duplicate work.
+
+## TDD tasks are ORDINARY tasks (v0.41.0)
+
+TDD red proofs are **planner-emitted tasks**, not an orchestrator-synthesized
+Wave 0. Each one materializes the `tdd_spec` entries of the implementation task
+it guards, and that task lists it in `depends_on`. Nothing here special-cases
+them:
+
+- they enter the same conflict graph via their `declared_files` (their test
+  files), so **independent TDD tasks share a wave and run in parallel** — the
+  red proofs for two unrelated features are one wave, not two;
+- `depends_on` guarantees **a red proof is always in an earlier wave than the
+  code it proves** — a proof can never land beside its implementation;
+- they are scored from **their own planner-emitted `facets`**, like any task, so
+  no derived-vector rule is needed;
+- `max_wave_tasks`, `is_batch_pause` and `pause_schedule` bind to them unchanged.
+
+**A TDD task does NOT inherit the risk floor** of the task it guards: it
+transcribes planner-authored skeletons, writes no production code, and its output
+is asserted RED before anything is believed. The planner reflects that in the
+task's own facets (`novelty: mechanical`, `logic: none`, `risk: []`). Stated here
+so it is not re-litigated per run — the alternative is a Haiku-sized
+transcription job dispatched at floor 70 because the requirement it proves is
+auth-flavoured.
+
+**If no task carries `new-surface` or `behavior-change` entries, no TDD task
+exists and no extra wave is created.**
+
+## Orchestrator-synthesized tasks (the mock example, any future one)
+
+Some dispatched tasks appear in no `tasks[]` because the ORCHESTRATOR synthesized
+them — the mock example (`_shared/drift-recovery.md`). They still obey hard rule
+1: **dispatched like any other task, never done by you.** But they have no
+planner-emitted `facets`, and the orchestrator is by definition the party that
+did NOT read the code — inventing a vector for them is judgment wearing
+arithmetic's clothes, the exact thing the facet redesign removed.
+
+So their vector is **DERIVED, never judged**:
+
+| Facet | Value |
+|---|---|
+| `breadth` | `len(files the synthesized task will touch)` |
+| `novelty` | `mechanical` — it transcribes planner-authored material |
+| `logic` | `none` |
+| `test_surface` | per the task |
+| `risk` | `[]` — unless the synthesized task itself inherits a CITED risk |
+
+## Post-wave worktree audit (a GATE, not a report)
+
+Declarations can be wrong, and a return can be honest and still miss what
+happened. Capture `git status --short` BEFORE the wave dispatches and again
+after every task returns, then diff the two:
+- **Any path whose state changed and is in NO task's `declared_files`** → name
+  the path and the likely task, and get an explicit user decision BEFORE the
+  wave closes. A wave never closes over an unexplained worktree delta.
+- **A file that became LESS modified is as much a violation as one that became
+  more modified.** That is the revert signature — an executor made an
+  unsatisfiable assertion true by `git checkout`-ing another task's completed
+  work, returned a literally-true report, and left a CLEAN tree. Nothing that
+  reads returns can see it.
+- **Stray files count** — a path that appears at the repo root (a stdout dump, a
+  mangled-path artifact) is undeclared output, not noise to ignore.
+- Two agents in one wave touched the same undeclared file → record
+  `failure_reason: "file-collision:<file> with <agent>"`, set the
+  later-finishing task to `requeued`, re-dispatch in a later wave so it sees
+  the other's committed changes.
+- Declarations are the plan, `actual_files` is the ATTESTATION, and
+  `git status` is the AUDIT — same instruction → contract → attestation →
+  spot-check pattern the plan applies to `grounding[]`.
+- Canonical cross-lane wording: `_shared/return-validation.md` §6.