@azure-id/orc 2.1.1 → 2.2.0

package/templates/skills/_shared/lane-contract.md

@@ -10,13 +10,17 @@ those values, and a spine never restates this file.
 ## Calls
 
 **ONE catalogue, and it is not you:** `orc lane calls <lane> --json` names every
-CLI call the lane makes. Each row gives the exit-code contract, the cost, when
-to run the call, and what an EMPTY answer means.
+SHARED CLI call (a call that two or more lanes make). Each row gives the
+exit-code contract, the cost, when to run the call, and what an EMPTY answer
+means.
 
+- A call that only this lane makes is not in the catalogue. Its spelling and its
+  exit codes are in the lane's own skill files.
 - Never invent a spelling. Never re-word an exit code.
 - Never re-derive a state word. The CLI's state words are the only state words.
 - **An exit code is an ANSWER wherever that contract says so, not a failure.**
-- A call that the answer does not name is a call the lane does not make.
+- A call that neither the answer nor the lane's own skill files name is a call
+  the lane does not make.
 - The catalogue itself exits ≠ 0 → say that the CLI is unavailable. Before you
   run a command, name it out loud.
 

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

@@ -1,137 +1,137 @@
-# Shared contract — Opus-5-only dispatch mode (hard-gated, forcing)
-
-Canonical rule for routing EVERY dispatched role to Opus 5. Consumed by the full
-orc spine, the ultra lane, and every lane with a fixed-role dispatch; the lint
-pins the `opus5-only.md` pointer into each of them.
-
-## The gate
-
-Read the resolved config at run start (`config.md` defaults ← `orc.config.yaml`).
-The mode is **hard-gated**: absolutely nothing changes unless `opus5_only: true`.
-When it is false (the default), dispatch every role exactly as today — this file
-is inert.
-
-## The mapping (only when `opus5_only: true`)
-
-**Scored executors** — one model, EFFORT as the cost dial, replacing the 5-band
-mixed-model table:
-
-| Score | Executor agent |
-|-----------|---------------------------|
-| `[0,90)`   | `orc-executor-opus-5-low`  |
-| `[90,100]` | `orc-executor-opus-5-med`  |
-
-Two bands, sharing the 90 edge with the default table's top two rows. Since
-v1.0.0 the default table's high end is ALREADY Opus 5.5 with effort as the dial,
-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
-agent: same task slice, same return contract, same phase.
-
-| Role | Default agent | Opus-5-only variant |
-|------|---------------|---------------------|
-| mini executor | `orc-executor-sonnet-5-high` | `orc-executor-opus-5-low` |
-| fast executor | `orc-executor-sonnet-5-med` | `orc-executor-opus-5-low` |
-| mini analyze | `orc-analyze-mini-sonnet-5-high` | `orc-analyze-mini-opus-5-med` |
-| 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-sonnet-5-high` (light) | `orc-wiki-scanner-opus-5-low` |
-| retro mine | `orc-retro-sonnet-5-high` | `orc-retro-opus-5-med` |
-
-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) 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
-
-- **`orc-trace-writer-haiku-4-5` stays Haiku 4.5.** It transcribes a packet the
-  orchestrator hands it — no reasoning, no source reads. It is never in the
-  roster.
-- **`orc-graph-noter-sonnet-4-6-med` is not dispatched at all.** It has no Opus 5.5
-  variant: under the mode a code lane skips graph notes and prints
-  `graph notes: skipped (opus5_only)` (`code-graph.md` §6). The graph's structure
-  layer costs no model, so nothing else about the graph changes.
-- **`orc-diy`.** Its score table is compile-owned (`orc diy compile` →
-  `flow.lock.json`); a DIY flow dispatches whatever its lock says. Re-compile to
-  change it.
-- **`orc-quick` — the ONE exception to the flat precedence below.** Its dispatch
-  gate asks the USER which agent to spawn before every single dispatch, and that
-  hard gate is the lane's entire premise. A forcing mode that collapsed the menu
-  to one option would silently delete it, so the mode is fully INERT there:
-  `opus5_only` is neither read nor honored by `orc-quick`. When the mode is on,
-  the lane SAYS so at the gate (`orc-quick ignores opus5_only — both options are
-  live`), because a shadowed setting must never be silent in either direction.
-- **`/orc-challenge` — UNAFFECTED, not exempt.** All three of its agents are
-  already `claude-opus-5-5` (judge high, advisor medium, reader low), so the mode
-  has nothing to force: zero new pairs, no rename churn, no roster row. The
-  reader's `low` effort is a MEASUREMENT choice, not a cost one — a
-  harder-thinking cold reader reasons around exactly the gaps D4 exists to find
-  — so nothing may ever "upgrade" it.
-  See `orc-quick/references/dispatch-gate.md`.
-
-## It FORCES — precedence is flat while ON
-
-`opus5_only: true` outranks every other dispatch selector:
-
-- each role's default frontmatter pin;
-- **`rubric_bands_override`** — a hand-written executor table is ignored while
-  the mode is on.
-
-Turning the mode off restores both. `rubric_bands` remains granularity
-only, never a preset selector, in both modes.
-
-The forcing is flat across every lane that HONORS the mode — `orc-quick` does
-not, per "Out of scope" above.
-
-### `orc extra` sits ABOVE the mode, and it is not a fourth thing it overrides
-
-Extra decides **whether a Claude agent runs at all**. `opus5_only` and the score
-tables only decide WHICH Claude agent runs where extra did not take it. So the
-mode is neither shadowed nor shadowing — it is simply **NOT CONSULTED** for the
-work extra took:
-
-- **a scored task** — an extra route row covering that score outranks the mode;
-  every score no row covers still resolves on the Opus 5.5 ladder.
-- **a POSITION** (v0.55.0 — `quick-executor`, `fast-executor`, `doc-writer`,
-  `doc-checker`, `wiki-scanner-deep`, `wiki-scanner-light`) — an extra slot row
-  holding that position outranks the mode's variant of that slot's agent; **a
-  position with no row is fully governed by the mode.** With `doc-writer` routed
-  and `doc-checker` not, `opus5_only` is entirely live for the checker.
-
-"Not consulted for that slot" and "inert" are different claims, and only the
-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-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.
-
-## Tier honesty
-
-A subagent can never outrank the main session. With the mode ON, EVERY dispatch
-needs an Opus 5.5 main session — not just the top executor band. On a lower
-session every role silently falls back to the session model and the tier-honesty
-rule (`return-validation.md`) reports a downgrade on **every** return. That is
-correct behavior, not a bug: hooks cannot block on model, only on effort, so the
-`orc config set opus5_only true` notice is the only up-front warning.
-
-This also means `orc-fast`'s "the orchestrator runs fine at Sonnet medium" holds
-only while the mode is OFF. The effort guard is unchanged — it still matches the
-exact skill name `orc`, and orc-fast is never added to it.
-
-## Trace
-
-Phase 1's `CONFIG` line always records the resolved `opus5_only`, so
-`/orc-retro` can segment per-band outcomes BY dispatch mode.
+# Shared contract — Opus-5-only dispatch mode (hard-gated, forcing)
+
+Canonical rule for routing EVERY dispatched role to Opus 5. Consumed by the full
+orc spine, the ultra lane, and every lane with a fixed-role dispatch; the lint
+pins the `opus5-only.md` pointer into each of them.
+
+## The gate
+
+Read the resolved config at run start (`config.md` defaults ← `orc.config.yaml`).
+The mode is **hard-gated**: absolutely nothing changes unless `opus5_only: true`.
+When it is false (the default), dispatch every role exactly as today — this file
+is inert.
+
+## The mapping (only when `opus5_only: true`)
+
+**Scored executors** — one model, EFFORT as the cost dial, replacing the 5-band
+mixed-model table:
+
+| Score | Executor agent |
+|-----------|---------------------------|
+| `[0,90)`   | `orc-executor-opus-5-low`  |
+| `[90,100]` | `orc-executor-opus-5-med`  |
+
+Two bands, sharing the 90 edge with the default table's top two rows. Since
+v1.0.0 the default table's high end is ALREADY Opus 5.5 with effort as the dial,
+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
+agent: same task slice, same return contract, same phase.
+
+| Role | Default agent | Opus-5-only variant |
+|------|---------------|---------------------|
+| mini executor | `orc-executor-sonnet-5-high` | `orc-executor-opus-5-low` |
+| fast executor | `orc-executor-sonnet-5-med` | `orc-executor-opus-5-low` |
+| mini analyze | `orc-analyze-mini-sonnet-5-high` | `orc-analyze-mini-opus-5-med` |
+| 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-sonnet-5-high` (light) | `orc-wiki-scanner-opus-5-low` |
+| retro mine | `orc-retro-sonnet-5-high` | `orc-retro-opus-5-med` |
+
+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) 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
+
+- **`orc-trace-writer-haiku-5-high` stays Haiku 4.5.** It transcribes a packet the
+  orchestrator hands it — no reasoning, no source reads. It is never in the
+  roster.
+- **`orc-graph-noter-haiku-5-high` is not dispatched at all.** It has no Opus 5.5
+  variant: under the mode a code lane skips graph notes and prints
+  `graph notes: skipped (opus5_only)` (`code-graph.md` §6). The graph's structure
+  layer costs no model, so nothing else about the graph changes.
+- **`orc-diy`.** Its score table is compile-owned (`orc diy compile` →
+  `flow.lock.json`); a DIY flow dispatches whatever its lock says. Re-compile to
+  change it.
+- **`orc-quick` — the ONE exception to the flat precedence below.** Its dispatch
+  gate asks the USER which agent to spawn before every single dispatch, and that
+  hard gate is the lane's entire premise. A forcing mode that collapsed the menu
+  to one option would silently delete it, so the mode is fully INERT there:
+  `opus5_only` is neither read nor honored by `orc-quick`. When the mode is on,
+  the lane SAYS so at the gate (`orc-quick ignores opus5_only — both options are
+  live`), because a shadowed setting must never be silent in either direction.
+- **`/orc-challenge` — UNAFFECTED, not exempt.** All three of its agents are
+  already `claude-opus-5-5` (judge high, advisor medium, reader low), so the mode
+  has nothing to force: zero new pairs, no rename churn, no roster row. The
+  reader's `low` effort is a MEASUREMENT choice, not a cost one — a
+  harder-thinking cold reader reasons around exactly the gaps D4 exists to find
+  — so nothing may ever "upgrade" it.
+  See `orc-quick/references/dispatch-gate.md`.
+
+## It FORCES — precedence is flat while ON
+
+`opus5_only: true` outranks every other dispatch selector:
+
+- each role's default frontmatter pin;
+- **`rubric_bands_override`** — a hand-written executor table is ignored while
+  the mode is on.
+
+Turning the mode off restores both. `rubric_bands` remains granularity
+only, never a preset selector, in both modes.
+
+The forcing is flat across every lane that HONORS the mode — `orc-quick` does
+not, per "Out of scope" above.
+
+### `orc extra` sits ABOVE the mode, and it is not a fourth thing it overrides
+
+Extra decides **whether a Claude agent runs at all**. `opus5_only` and the score
+tables only decide WHICH Claude agent runs where extra did not take it. So the
+mode is neither shadowed nor shadowing — it is simply **NOT CONSULTED** for the
+work extra took:
+
+- **a scored task** — an extra route row covering that score outranks the mode;
+  every score no row covers still resolves on the Opus 5.5 ladder.
+- **a POSITION** (v0.55.0 — `quick-executor`, `fast-executor`, `doc-writer`,
+  `doc-checker`, `wiki-scanner-deep`, `wiki-scanner-light`) — an extra slot row
+  holding that position outranks the mode's variant of that slot's agent; **a
+  position with no row is fully governed by the mode.** With `doc-writer` routed
+  and `doc-checker` not, `opus5_only` is entirely live for the checker.
+
+"Not consulted for that slot" and "inert" are different claims, and only the
+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-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.
+
+## Tier honesty
+
+A subagent can never outrank the main session. With the mode ON, EVERY dispatch
+needs an Opus 5.5 main session — not just the top executor band. On a lower
+session every role silently falls back to the session model and the tier-honesty
+rule (`return-validation.md`) reports a downgrade on **every** return. That is
+correct behavior, not a bug: hooks cannot block on model, only on effort, so the
+`orc config set opus5_only true` notice is the only up-front warning.
+
+This also means `orc-fast`'s "the orchestrator runs fine at Sonnet medium" holds
+only while the mode is OFF. The effort guard is unchanged — it still matches the
+exact skill name `orc`, and orc-fast is never added to it.
+
+## Trace
+
+Phase 1's `CONFIG` line always records the resolved `opus5_only`, so
+`/orc-retro` can segment per-band outcomes BY dispatch mode.

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

@@ -27,10 +27,10 @@ the codifier); hold resolved patterns in run state.
 1. Dispatch EVERY task as a spawned subagent (emit `DISPATCH <agent> :: <task>
    expect=<model>/<effort>` BEFORE the Task call; subagent wrapper framing + the
    task's INPUT SLICE per orc-execution/core.md + its scored model). Every
-   slice carries ONE `orc graph ctx --for-slice <the task's declared_files> --if-enabled --json --brief`
-   `card` as its `graph` block (`../code-graph.md` §7; exit 3 = off → no block) —
-   the OUTSIDE view only, because the executor reads each declared file in full
-   itself,
+   slice that writes code carries `graph_anchors` from ONE anchors call —
+   `orc graph ctx --for-slice <the task's declared_files> --focus=<the planning words> [--refs=<task.precedent>] --anchors --if-enabled --json --brief` (a request that names one symbol: `ctx <symbol> --anchors` gives the card and the anchors in one call)
+   (`../code-graph.md` §0 step 3, §7): print its `line`; paste its `card` into
+   the slice VERBATIM as `graph_anchors`, with its `read all: …` line and its code block — never shorten it; exit 3 or 4 → none. With `graph_anchors` in the slice, list at most ONE wiki page path (the one about the feature's intent), not 1–3. No anchors when the change stays inside ONE file the user named and nothing outside it changes (no signature change, no new export) — the executor reads that file anyway. The slice also carries
    the task's `acceptance[]`, its `tdd_spec` tests (the executor
    implements to green: implement→test→repair, cap `tdd_loop_max`, emitting
    `TDD-RED`/`TDD-GREEN` per iteration; cap hit → STOP SEQUENCE + honest red
@@ -71,13 +71,14 @@ the codifier); hold resolved patterns in run state.
    `unmet[]` is `partial`.
 4. **Post-wave worktree audit (GATE, `_shared/return-validation.md` §6):** diff `git status --short` before/after the wave — a changed path in NO task's `declared_files`, INCLUDING one that became less modified (the revert signature), blocks the close until named and decided.
    Overlap → `failure_reason: "file-collision:<file> with <agent>"`, requeue later wave.
-4a. **Code graph (`../code-graph.md` §5–§6):** after the audit, ONE call —
+4a. **Code graph (`../code-graph.md` §5–§6):** ONLY when `probes["graph-status"].update_step`
+   is `lane` (else the hook already did it — no call): after the audit, ONE call —
    `orc graph update --notes-pending --files <the wave's changed paths> --at wave --if-enabled --json --brief`
    (emit `GRAPH-UPDATE`; the answer's `notes_pending` is the notes half):
-   `notes_pending.exit` 0 → dispatch `orc-graph-noter-sonnet-4-6-med` (slice = paths only) in the
+   `notes_pending.exit` 0 → dispatch `orc-graph-noter-haiku-5-high` (slice = paths only) in the
    SAME tool block as the next wave's first dispatch; 3 or 5 → nothing, the
    symbols wait for a later batch. The noter returns ONE line (emit `GRAPH-NOTES`) —
-   never pull its notes into this context. A slice that carried cards gets a
+   never pull its notes into this context. A slice that carried `graph_anchors` gets a
    `graph:` continuation on its `DISPATCH` line and a `graph_used` return.
 5. Append worker `log_entries` to the decision log; regenerate the digest.
    **Gotcha capture (`gotchas: on`):** a return that CLOSED a repair loop carries
@@ -139,11 +140,12 @@ outside `declared_files` (a revert included) gates the wave close.
 <!-- /diy:when -->
 
 <!-- diy:when code_graph=on -->
-Code graph cache (never skipped): each slice gets ONE `orc graph ctx --for-slice <the task's
-declared_files> --if-enabled --json --brief` `card` as its `graph` block, and the return
-carries `graph_used`. After each wave's worktree audit run ONE call —
+Code graph anchors (never skipped): each slice that writes code carries `graph_anchors` (the `card`, inline) from
+ONE call — `orc graph ctx --for-slice <the task's declared_files> --focus=<the planning words> [--refs=<task.precedent>] --anchors --if-enabled --json --brief`
+(print its `line`; exit 3 or 4 → none), and the return carries `graph_used`. ONLY when
+`update_step` is `lane`, after each wave's worktree audit run ONE call —
 `orc graph update --notes-pending --files <the wave's changed paths> --at wave --if-enabled --json --brief`
-(copy its `trace` verbatim); `notes_pending.exit` 0 → dispatch `orc-graph-noter-sonnet-4-6-med` paired
+(copy its `trace` verbatim); `notes_pending.exit` 0 → dispatch `orc-graph-noter-haiku-5-high` paired
 with the next wave's first dispatch, exit 3 or 5 → nothing. Canonical:
 `.claude/skills/_shared/code-graph.md`.
 <!-- /diy:when -->

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

@@ -20,20 +20,22 @@ task (advisory) and print + emit `CROSSLINK <state> :: boundaries=<n> peers=<nam
 only pre-built needs/cache, never peer source live). **Gotchas (repair memory,
 config `gotchas`):** probe ONCE with `orc gotcha status` (exit 0 = entries exist,
 1 = none — never a `find`); canonical `_shared/gotchas.md`.
-**Code graph (`../code-graph.md` §3b and §7):** with the graph on, run
-`orc graph map --focus <every file or symbol the request NAMES> --if-enabled --json --brief`
+**Code graph (`../code-graph.md` §0 step 2, §3b):** with the graph on, run
+`orc graph map --focus=<3–6 words from the request> --budget 800 --if-enabled --json --brief`
 **FIRST, once** — before any Glob and before `impact`. It ranks the repository
-around the request and names the files worth reading, which is the question
-`impact` cannot answer because `impact` needs the files already chosen. Print its
+around the request and names the files worth reading; `impact` cannot answer that,
+because it needs the files already chosen. Print its
 `line` and emit `GRAPH-MAP`. Rank is a HINT about where to look first, never
 proof a file matters — and never a reason to skip reading a range you will edit.
-Exit 1 or 3 → orient exactly as before. Then run
+Never call `map` twice. Exit 1 or 3 → orient exactly as before. Then run
 `orc graph impact <candidate declared_files> --if-enabled --json --brief` and hand its
 callers to the planner — they sharpen `declared_files` and the `fan` and risk
-facets. Also run `orc graph cochange <each candidate file> --if-enabled --json --brief`:
-it answers "what else will I have to touch" from HISTORY, which a static edge
-cannot see. Co-change is a HINT about people, never a dependency — exit 4 means
-this file changes alone, which is an answer. Exit 3 or 4 → plan exactly as before.
+facets. `/orc`, `/orc-ultra` and `/orc-diy` also run
+`orc graph cochange <each candidate file> --if-enabled --json --brief`: it answers
+"what else will I have to touch" from HISTORY. Co-change is a HINT about people,
+never a dependency. A short history answers exit 4 at once — this file changes
+alone, which is an answer. Exit 3 or 4 → plan exactly as before. A task's optional
+`precedent[]` (the planner's copy-from files) becomes that task's pack `--refs=`.
 **Pact / boundary / aftermath / wiki debt (all CONSUMED here, never
 written here):** probe `orc pact status --json` (`pact_gate`, default `warn`),
 `orc boundary status --json` (`boundary_gate`, default `warn`), `orc wiki debt
@@ -136,4 +138,20 @@ TDD is ON for this flow: the plan must carry a `tdd_spec` per requirement
 project → whole-run exemption, stated once at preflight.
 <!-- /diy:when -->
 
+<!-- diy:when code_graph=on -->
+Code graph — consult (before the first dispatch): print `probes["graph-status"].line` from
+`orc lane config orc-diy --json`. Run `orc graph status --if-enabled --heal --json --brief` only
+when `heal_needed` is true. Put the `trace` (`GRAPH-CONSULT …`) in the next packet as it is.
+Exit 3 (`off` or `semi`) → make NO other graph call in this run.
+
+Code graph — orient (once, before the planner chooses files): run
+`orc graph map --focus=<3–6 words from the request> --budget 800 --if-enabled --json --brief`
+FIRST, once; print its `line` and emit `GRAPH-MAP`. Rank is a HINT about where to look first,
+never proof a file matters. Never call `map` twice. Then run
+`orc graph impact <candidate declared_files> --if-enabled --json --brief` and hand its callers to
+the planner. Also run `orc graph cochange <each candidate file> --if-enabled --json --brief`:
+a HINT about people, never a dependency; a short history answers exit 4 at once. Exit 3 or 4 →
+plan exactly as before. A task's optional `precedent[]` becomes that task's pack `--refs=`.
+Canonical: `.claude/skills/_shared/code-graph.md`.
+<!-- /diy:when -->
 <!-- /orc:layer -->

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

@@ -81,9 +81,9 @@ that the line is printed and when.
 dispatch — never skipped. Run `orc graph status --if-enabled --heal --json --brief`
 only when `heal_needed` is true (it builds or updates the graph, free). Put the
 `trace` (`GRAPH-CONSULT …`) in the next packet as it is — never as a `GATE` line
-in your own words. While the graph is
-on, `orc lane config` prints the three graph steps in `announce[]` (`../code-graph.md`
-§0). **The lane reads no `code_graph` key:** `--if-enabled`
+in your own words. Exit 3 (`off`, or `semi` — kept current, never read) → make no other
+graph call in this run. While the graph is on, `orc lane config` prints the four graph
+touchpoints in `announce[]` (`../code-graph.md` §0). **The lane reads no `code_graph` key:** `--if-enabled`
 makes the CLI decide, which is how `/orc-quick` takes part while its step 1 still
 reads `log_dir` and nothing else. A graph that cannot be built never stops a run,
 and `/orc-fast` gains no third gate. Every other lane prints nothing.

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

@@ -53,9 +53,10 @@ P0/P1 findings gate anything; P2/P3 findings are listed once in the summary
 and never re-offered as fix-up tasks.
 <!-- /diy:when -->
 <!-- diy:when code_graph=on -->
-With the code graph on, the reviewer also gets the callers from
-`orc graph changes --if-enabled --json` — an unchanged caller of a
-changed signature is a finding candidate (`.claude/skills/_shared/code-graph.md` §7).
+With the code graph on, run ONCE
+`orc graph changes --files=<the changed paths> --if-enabled --json --brief`: print its `tests_line`,
+run its `tests[]` first, print its `blast_line`, and hand the reviewer its callers — an unchanged
+caller of a changed signature is a finding candidate (`.claude/skills/_shared/code-graph.md` §0 step 4).
 <!-- /diy:when -->
 
 <!-- /orc:layer -->

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

@@ -41,14 +41,10 @@ wiki now?"** (H `orc.phase-8.wiki-refresh`); on "later" print the prominent stal
 usage report — /usage limits + the full dispatch log (model/effort/score per
 subagent). The user must always know what the run cost. A `proposal` in
 `habits{}` → its ONE line joins that report (`../habits.md` §3). **Code graph
-(`../code-graph.md` §5–§6):** run `orc graph update --if-enabled` once more —
-fix rounds move code — and emit `GRAPH-UPDATE`; then run `orc graph notes pending
---files <every path the run changed> --at end --if-enabled` — exit 0 → one noter
-dispatch, exit 3 or 5 → nothing. Then ONE line, once, copied VERBATIM from
-`orc graph gain --run <this run's trace name> --if-enabled --json --brief` (emit
-`GRAPH-GAIN`): what the graph put in, and an ESTIMATE of the retrieval it kept
-out. Exit 1 or 3 → no line. **Never restate it as one number** — the range and
-the word "estimate" are the claim. Finally emit
+(`../code-graph.md` §5–§6):** ONLY when `probes["graph-status"].update_step` is
+`lane`, run `orc graph update --notes-pending --files <every path the run changed> --at end --if-enabled --json --brief`
+once more — fix rounds move code — and emit `GRAPH-UPDATE`; `notes_pending.exit` 0 →
+one noter dispatch, 3 or 5 → nothing. No lane calls `orc graph gain`. Finally emit
 `PHASE ship end`, then the one-line `STATS lane=… dispatches=… downgrades=…`
 summary (trace.md — what `orc stats` reads), then `FINISH :: <detail>`,
 and in ONE step delete BOTH `log_dir/.current` and the run's `RESUME.md` (that
@@ -64,8 +60,9 @@ State the current branch and the change summary BEFORE any git action, and
 never ship on a red build (locked rule).
 
 <!-- diy:when code_graph=on -->
-Before the ship action, run `orc graph update --if-enabled` once more — fix rounds
-move code (`.claude/skills/_shared/code-graph.md` §5).
+Before the ship action, ONLY when `update_step` is `lane`, run
+`orc graph update --notes-pending --files <every path the run changed> --at end --if-enabled --json --brief`
+once more — fix rounds move code (`.claude/skills/_shared/code-graph.md` §5).
 <!-- /diy:when -->
 <!-- diy:when ship_mode=ask -->
 Ask the user how to ship: commit, PR (via

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

@@ -54,7 +54,7 @@ entry that wrote code. Every detail goes BELOW the card, never above it.
 ✅ Fixed the null charge on guest checkout — 3 files, tests 14 passed (2 affected first)
    review   2 findings · 1 fixed · 1 disputed (recorded)      gotchas  1 recorded (G-044)
    risk     low — callers 3 in 2 files, tests reach 2          habits   1 proposal below
-   flaky    1 test passed on the re-run (no repair round)      graph    <gain line>
+   flaky    1 test passed on the re-run (no repair round)      graph    <pack line>
    undo     orc undo --run <run-slug>                          next     commit? (your usual: review → commit)
 ```
 
@@ -69,5 +69,4 @@ entry that wrote code. Every detail goes BELOW the card, never above it.
   `undo  none — no snapshot`. The command only PRINTS the undo; `--apply` runs
   it. The lane never runs it itself.
 - **Copy the CLI's words.** `risk` is the `blast_line` with its `why`;
-  `graph` is the `orc graph gain` `line`, VERBATIM — an estimate with a range,
-  never restated as a saving. `flaky` is the `GATE flaky` tests.
+  `graph` is the last pack call's `line`, VERBATIM (no lane calls `orc graph gain`). `flaky` is the `GATE flaky` tests.

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

@@ -19,14 +19,15 @@ owner is this file has its detail in "Verb detail" below.
 | `CONFIG <key=value …>` | orc → writer | Phase 1 — the resolved config values this run will consume, ALWAYS with opus5_only | `_shared/phases/trace-verbs.md` |
 | `WIKI-CONSULT <fresh\|aging\|stale\|absent\|empty> :: docs=<list\|none>` | orc → writer | project wiki consulted for grounding, with its staleness tier | `_shared/phases/wiki-consult.md` |
 | `CROSSLINK <cached\|configured-no-cache\|none> :: boundaries=<n> peers=<names> · CROSSLINK inject task=<id> :: <boundary>` | orc → writer | cross-repo peer-knowledge state at the consult point; `inject` when a slice receives a linked contract | `_shared/phases/wiki-consult.md` |
-| `GRAPH-CONSULT <fresh\|updated\|built\|drifted\|none\|off> :: files=<n> symbols=<n>[ density=<n>[ thin=1]] · GRAPH-CONSULT card task=<id> :: targets=<…>` | orc → writer | the code graph's preflight state, copied VERBATIM from the CLI `trace` field | `_shared/code-graph.md` |
+| `GRAPH-CONSULT <fresh\|updated\|built\|drifted\|none\|semi\|off\|pack\|anchors> :: files=<n> symbols=<n>[ density=<n>[ thin=1]] · GRAPH-CONSULT card task=<id> :: targets=<…> · GRAPH-CONSULT pack :: files=<n> refs=<n> excerpts=<n> tokens=<n> gen=<n> · GRAPH-CONSULT anchors :: ranges=<n> files=<n> gen=<n>` | orc → writer | the code graph's preflight state, copied VERBATIM from the CLI `trace` field | `_shared/code-graph.md` |
 | `GRAPH-UPDATE <state> :: parsed=<n> reused=<n> deleted=<n> gen=<n> route=<n> ms=<n>` | orc → writer | one graph update, the `trace` field of `orc graph update --json`, verbatim | `_shared/phases/trace-verbs.md` |
 | `GRAPH-MAP <repo\|focused> :: files=<shown>/<total> [focus=<a,b>] gen=<n>` | orc → writer | ONE line at the start of planning, the `trace` field of `orc graph map --json`, verbatim | `_shared/phases/trace-verbs.md` |
 | `GRAPH-CHANGES <found\|none> :: symbols=<n> high=<n> medium=<n> low=<n> gen=<n>` | orc → writer | one line at review, the `trace` field of `orc graph changes --json`, verbatim | `_shared/phases/trace-verbs.md` |
 | `GRAPH-COMPLEXITY <mini-ok\|recommend-orc> :: files=<n> callers=<n> caller_files=<n> maybe=<n> tests=<n> risk=<n> cochange=<n> gen=<n>` | orc → writer | one line per /orc-mini run, the `trace` field of the `--complexity` impact call, verbatim | `_shared/phases/trace-verbs.md` |
-| `GRAPH-COCHANGE <found\|none> :: rows=<n> commits=<n>` | orc → writer | one line per planning batch, for the file that produced the widest answer | `_shared/phases/trace-verbs.md` |
+| `GRAPH-COCHANGE <found\|none> :: rows=<n> commits=<n> · GRAPH-COCHANGE none :: history=<n>` | orc → writer | one line per planning batch, for the file that produced the widest answer | `_shared/phases/trace-verbs.md` |
+| `GRAPH-COVERAGE <clean\|gaps> :: paths=<n> gaps=<n> gen=<n>` | orc → writer | the `trace` field of `orc graph coverage --json` — which files a card's silence can be trusted on | `_shared/phases/trace-verbs.md` |
 | `GRAPH-HINT injected=<n> subagent_start=<n> read_notes=<n> updates=<n>` | orc → writer | ONE line per phase close, the graph hook's counters; omitted when the counter file does not exist | `_shared/phases/trace-verbs.md` |
-| `GRAPH-GAIN paid=<n> low=<n> high=<n> calls=<n>` | orc → writer | ONE line per run at ship; `paid` is exact, `low`/`high` are an estimate never collapsed into one number | `_shared/phases/trace-verbs.md` |
+| `GRAPH-GAIN paid=<n> low=<n> high=<n> calls=<n>` | orc → writer | OLD traces only — no lane emits it now (`orc graph gain` is a user command); `paid` is exact, `low`/`high` are an estimate never collapsed into one number | `_shared/phases/trace-verbs.md` |
 | `GRAPH-NOTES <applied\|below-min\|none\|deferred\|off\|skipped> :: <detail>` | orc → writer | one notes batch; `applied` copies the noter's one-line return verbatim | `_shared/phases/trace-verbs.md` |
 | `SPAWN <agent>` | hook | an agent dispatch was observed (skeleton) | `hooks/orc-trace.js` |
 | `RETURN <agent> :: <desc> dur=<m>m<s>s [model=<id>]` | hook | a subagent finished (skeleton) — not an orchestrator obligation; the model check is VERIFY | `hooks/orc-trace.js` |
@@ -44,17 +45,19 @@ owner is this file has its detail in "Verb detail" below.
 | `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 (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` |
+| `FIX source=<sonar\|ci\|defect\|pr\|review> 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 — `source` is the FILED kind: a class `other` is filed as `defect` | `orc-fix/SKILL.md` |
+| `WAIT mode=<safe\|soft\|hard> requested=<n>m start=<HH:MM> end=<HH:MM> hops=<planned>/<max> trigger=<user\|gate> · WAIT end :: done=<k>/<planned> reason=<elapsed\|recovered\|cancelled\|max-hops> · WAIT block :: reason="<why>" by=user · WAIT unblock` | cli | a wait started, ended, blocked or unblocked — `orc wait` writes it into the open trace, never a packet | `_shared/wait.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` |
 | `TDD-GREEN task=<id> iter=<n>` | executor→orc → writer | the task's TDD acceptance tests pass | `_shared/phases/trace-verbs.md` |
 | `REPRO red\|green :: <cmd> exit=<n> · REPRO none :: <reason>` | executor→orc → writer | a DEFECT task's reproduction: RED before the fix, GREEN after | `_shared/return-validation.md` |
-| `NOTE :: <decisions>` | writer | the packet's `decisions` field — the WHY layer; one line, only when non-empty | `agents/orc-trace-writer-haiku-4-5.md` |
+| `NOTE :: <decisions>` | writer | the packet's `decisions` field — the WHY layer; one line, only when non-empty | `agents/orc-trace-writer-haiku-5-high.md` |
 | `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 summary line per run, in the FINISH packet, immediately BEFORE the FINISH line | `_shared/phases/trace-verbs.md` |
 | `PACT <state> :: <ids> · PACT inject task=<id> :: <PACT-id> · PACT recheck pass\|fail :: <ids>` | orc → writer | invariant-ledger state at the Phase-1 probe, a promise injected into a task, the Phase-6 recheck | `orc-pact/references/gate.md` |
 | `BOUNDARY <EXECUTE\|ESCALATE\|REFUSE\|unknown> task=<id> :: <area> · BOUNDARY lift task=<id> :: <area>` | orc → writer | per-task boundary verdict; an uncarded area is `unknown`, never REFUSE | `orc-boundary/references/gate.md` |
 | `CHALLENGE iter=<n> findings=P0:<n>/P1:<n>/P2:<n> coverage=<n>% verdict=PASS\|FAIL · CHALLENGE accept\|rebut :: <id> · CHALLENGE regoal\|retemplate :: v<n>` | orc → writer | one line per completed /orc-challenge iteration — `orc challenge record`'s `trace_line`, verbatim | `orc-challenge/SKILL.md` |
+| `DOC cycle=<n> sections=<k>/<m>[ wave=<k>/<n>]` | orc → writer | one line per completed /orc-doc cycle — a completed WAVE is a completed cycle | `orc-doc/SKILL.md` |
 | `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 · EXTRA fallback task=<id> :: <reason> → <agent> · EXTRA substitution task=<id> :: requested=<m> reported=<m> · EXTRA reroute task=<id> :: <providers> · EXTRA resume task=<id> attempt=<n> :: from=<reason> attribution=<verdict> target=<extra:profile\|agent> files_preexisting=<n> · EXTRA orphan task=<id> :: attempt=<n> lease-expired files_changed=<n> state=<state> · EXTRA demote run=<slug> :: profile=<p> reason=<consecutive-stall\|stale-live-attempt\|manual> n=<k> → <ladder>` | orc → writer | one line per FOREIGN dispatch — `orc extra dispatch`'s `trace_line`, verbatim | `_shared/extra-dispatch.md` |
 | `FINISH :: <detail>` | orc → writer | run ended — mandatory, even on an abort | `_shared/phases/trace.md` |
 
@@ -98,17 +101,19 @@ reaches the file through a packet — you never append lines by hand.
   `orc graph status --heal --json --brief` (`code-graph.md` §4). `density=` is
   the named symbols per file, and `thin=1` means most files hold none, so most
   questions asked of the graph will not find one (v1.9.1). A `GATE` line that
-  describes the graph in other words does not replace it. The `card` form is the
-  `trace` of `orc graph ctx --json`, with `task=` added, when a slice receives
-  cards.
-- **`GRAPH-UPDATE`.** One graph update at a wave close, a green smoke gate, a
-  code-writing `/orc-quick` request, or ship. The graph HOOK writes its own
+  describes the graph in other words does not replace it. The `anchors` form is the
+  `trace` of the anchors call (`orc graph ctx --for-slice … --anchors --json --brief`),
+  with `task=` added, when a slice receives `graph_anchors`. The `card` form is the
+  `trace` of a plain `orc graph ctx --json` (an orient call).
+- **`GRAPH-UPDATE`.** One lane graph update — ONLY when `update_step` is `lane` — at a
+  wave close, a green smoke gate, a code-writing `/orc-quick` request, or ship. The graph HOOK writes its own
   `GRAPH-UPDATE … :: by=hook …` lines directly; never copy one of those, it is
   already in the file.
 - **`GRAPH-MAP`.** Also at a `/orc-quick` Q1 look that had no file to name.
   `files=` is how many the budget SHOWED over how many the repository has, so a
   short map can be told from a small repository. `focused` means `--focus`
-  re-ranked the repository around what the request named. RANK is a hint about
+  re-ranked the repository around the files the focus RESOLVED to (`repo` when
+  nothing resolved). RANK is a hint about
   where to look first and the trace never says more than that.
 - **`GRAPH-CHANGES`.** `high` counts symbols that are exported, have three or
   more callers and NO test reaching them.
@@ -119,13 +124,13 @@ reaches the file through a packet — you never append lines by hand.
   the USER chose after the offer.
 - **`GRAPH-COCHANGE`.** Not per file — the `trace` field of
   `orc graph cochange --json` for the file that produced the widest answer.
+- **`GRAPH-COVERAGE`.** One line per `coverage` call. `gaps` counts files the
+  extractor did not finish; a gap is an answer, never an error.
 - **`GRAPH-HINT`.** Not one per hint — the counters `orc-graph-hook.js` keeps in
   `<log_dir>/<run>.graph-hook.json`. Omitted when the file does not exist (the
   hook is off, or it never had anything to say).
-- **`GRAPH-GAIN`.** The `trace` field of `orc graph gain --run <trace name>
-  --json`, verbatim. `paid` is exact (the tokens the graph put in); `low`/`high`
-  are an ESTIMATE of the retrieval it kept out. Omitted when the ledger is empty
-  or the graph is off.
+- **`GRAPH-GAIN`.** Kept so OLD traces still parse. No lane emits it now: `orc graph gain`
+  is a user command. `paid` is exact; `low`/`high` are an ESTIMATE.
 - **`GRAPH-NOTES`.** The `trace` field of `orc graph notes pending --json` when
   it exited 3 or 5; `skipped` under the Opus-5-only mode.
 - **`RETURN`.** The hook attributes the RETURN to the finishing agent from the
@@ -282,7 +287,7 @@ for every run even if the orchestrator never writes a rich marker. Only
   formats — the two halves agree by construction. An unknown verb, a missing or
   "now" `ts`, or a parse error exits 2 and writes NOTHING; a missing `.current`
   on a later packet exits 3. Only on exit ≠ 0 does the lane dispatch
-  `orc-trace-writer-haiku-4-5` with the SAME packet (the fallback).
+  `orc-trace-writer-haiku-5-high` with the SAME packet (the fallback).
 - **Pairing rule (the anti-forget mechanism).** The write 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