@azure-id/orc 2.1.1 → 2.2.0

package/templates/agents/MODEL-MAPPING.md

@@ -1,176 +1,176 @@
-# ORC Agents — Roster, Model Mapping & Verification
-
-Single-role, model-specific agents. The orchestrator dispatches BY AGENT NAME —
-model is pinned in frontmatter, not requested in prose. No agent is multi-role.
-
-## Executors (score-mapped by the single 5-band table in config.md)
-
-| Score band | Agent | Model | Effort |
-|-----------|-------|-------|--------|
-| [0,21)   | orc-executor-sonnet-5-low    | claude-sonnet-5-5 | low |
-| [21,31)  | orc-executor-sonnet-5-med    | claude-sonnet-5-5 | medium |
-| [31,41)  | orc-executor-sonnet-5-high   | claude-sonnet-5-5 | high |
-| [41,90)  | orc-executor-opus-5-low      | claude-opus-5-5   | low |
-| [90,100] | orc-executor-opus-5-med      | claude-opus-5-5   | medium |
-
-Score→executor mapping lives in config.md (one canonical 5-band table;
-`rubric_bands` is granularity only, not a preset selector).
-
-**Executors no band names — they still ship.**
-`orc-executor-haiku-4-5`, `orc-executor-sonnet-4-6-med`,
-`orc-executor-sonnet-4-6-high`, `orc-executor-opus-4-7-med`,
-`orc-executor-opus-4-7-high`, `orc-executor-opus-4-8-high` and
-`orc-executor-opus-5-high` — seven agents — are still generated
-and still installed. They are reachable only when a user names one
-explicitly: `rubric_bands_override`, `orc diy`'s `fixed_executor`, or
-`extra_fallback_agent`. They are not deleted because a table change is not a
-model change, and an agent's model change is always a RENAME.
-
-## Fixed-role agents
-
-| Agent | Model | Effort | Role |
-|-------|-------|--------|------|
-| orc-system-analyst-opus-5-high | claude-opus-5-5 | high | doc analysis |
-| orc-planner-opus-5-med | claude-opus-5-5 | medium | planning |
-| orc-reviewer-opus-5-low | claude-opus-5-5 | low | review (medium until v2.1.0; renamed from orc-reviewer-opus-5-med) |
-| orc-verifier-opus-5-med | claude-opus-5-5 | medium | verify (+ /orc-verify) |
-| orc-test-author-opus-5-med | claude-opus-5-5 | medium | test authoring (opt-in Phase 6.5; writes tests, never runs) |
-| orc-analyze-mini-sonnet-5-high | claude-sonnet-5-5 | high | mini analysis |
-| orc-planner-mini-sonnet-5-high | claude-sonnet-5-5 | high | mini planning |
-| orc-scout-sonnet-4-6-high | claude-sonnet-4-6 | high | deep-analysis code scout (read-only) |
-| orc-recon-sonnet-5-med | claude-sonnet-5-5 | medium | answer ONE repository question with file:line evidence (/orc-quick read-only entries; never edits, never plans) |
-| orc-recon-opus-5-low | claude-opus-5-5 | low | the same contract for a WIDE or SUBTLE question — a blast radius across areas, a defect with no obvious anchor |
-| orc-context-combiner-opus-5-high | claude-opus-5-5 | high | combine 2+ related analyses (full lane) |
-| orc-pattern-codifier-sonnet-5-high | claude-sonnet-5-5 | high | reconcile per-language playbook vs. project files → cached code-pattern (opt-in) |
-| orc-retro-sonnet-5-high | claude-sonnet-5-5 | high | mine behavior traces → calibration report (/orc-retro; read-only) |
-| orc-wiki-scanner-opus-5-low | claude-opus-5-5 | low | scan ONE wiki coverage area → evidence-anchored doc body + crosslink tags (/orc-wiki only; read-only against the project). The DEEP half of the tier ladder: first scan · STRUCTURAL · wide delta · a new exported symbol |
-| orc-wiki-scanner-sonnet-5-high | claude-sonnet-5-5 | high | the LIGHT half of the same ladder — an existing doc whose covered files moved by a small, no-new-surface delta. IDENTICAL return contract; it escalates with `needs_context` rather than under-delivering. Never used for a first scan |
-| orc-executor-opus-5-med | claude-opus-5-5 | medium | the `[90,100]` band in BOTH tables |
-| orc-executor-opus-5-low | claude-opus-5-5 | low | the default table's `[41,90)`, `opus5_only`'s `[0,90)`, and the forced mini/fast executor |
-| orc-advisor-opus-5-xhigh | claude-opus-5-5 | xhigh | ultra Phase U0 advisory brief + rubric + clarification questions (read-only; /orc-ultra only) |
-| orc-judge-opus-5-xhigh | claude-opus-5-5 | xhigh | ultra judgment gates — analysis / plan / implementation (read-only; /orc-ultra only) |
-| orc-learn-writer-opus-5-low | claude-opus-5-5 | low | deepen ONE feature → learning-docs/<slug>/ (/orc-learn only; git-ignored output) |
-| orc-claude-writer-opus-5-low | claude-opus-5-5 | low | scan repo → write/refresh the local CLAUDE.md (/orc-claude only; zero questions) |
-| orc-challenge-judge-opus-5-high | claude-opus-5-5 | high | grade ONE finished artifact against a FROZEN goal + template (/orc-challenge only; read-only). It reports findings and can never declare a pass — `orc challenge record` computes that |
-| orc-challenge-advisor-opus-5-med | claude-opus-5-5 | medium | turn a FAILED verdict into a remediation strategy — root-cause groups, an order with reasons, the decisions that are not defects (/orc-challenge only; read-only, no prose, no diffs) |
-| orc-challenge-reader-opus-5-low | claude-opus-5-5 | low | the COLD READ: answer questions from ONE artifact with `Read` and nothing else (/orc-challenge only). LOW ON PURPOSE — a harder-thinking reader reasons around the gaps D4 exists to find, so a stronger configuration is a worse instrument |
-| orc-challenge-contrarian-opus-5-high | claude-opus-5-5 | high | THE COUNCIL: start from "this has a fatal flaw" and go find it — load-bearing claim, then unhappy path, then second-order (/orc-challenge only; read-only). HIGH IS THE INSTRUMENT: a shallow contrarian returns the three surface complaints the free lint already caught |
-| orc-challenge-outsider-opus-5-low | claude-opus-5-5 | low | THE COUNCIL: what does this page assume you already know? The TIGHTEST slice in the lane — the artifact and this protocol, `Read` only, no goal, no audience, no template (/orc-challenge only). LOW IS A MEASUREMENT, NOT A COST CHOICE: a harder-thinking outsider reasons its way around an unexplained acronym and reports the document is fine. NOTHING MAY UPGRADE IT |
-| orc-challenge-executor-opus-5-med | claude-opus-5-5 | medium | THE COUNCIL: can this be started on Monday, and where is the first step? Returns D6/D2 findings plus the literal `monday_morning` list — or the point at which writing it becomes impossible (/orc-challenge only; read-only, `Bash` to CHECK a prerequisite, never to change anything). Not an ORC build executor — it writes nothing |
-| orc-challenge-principles-opus-5-high | claude-opus-5-5 | high | THE COUNCIL: the ONLY role allowed to say the frozen goal is wrong. Returns `premise` objects — no severity, never in findings[], never near the pass gate — and its report NEVER reaches the judge (/orc-challenge only; read-only). HIGH because rebuilding a problem statement from the ground up is the deepest reasoning in the lane |
-| orc-challenge-expansionist-opus-5-med | claude-opus-5-5 | medium | THE COUNCIL: the only lens not looking for a defect — what is being undervalued? Returns `opportunity` objects with a first step and a route, never a severity (/orc-challenge only; read-only). MEDIUM because it is pattern work against a concrete artifact, the same class as the advisor |
-| orc-doc-writer-opus-5-med | claude-opus-5-5 | medium | write ONE part file of a long document from a slice of sections (/orc-doc only). It writes to `.work/<id>.md` and NEVER opens document.md — that is what makes parallel writing safe here |
-| orc-doc-checker-opus-5-low | claude-opus-5-5 | low | read ONE LINE RANGE of a document and report anchored findings (/orc-doc only; read-only). LOW ON PURPOSE — the same reasoning that pins the challenge cold reader: a harder-thinking checker reasons its way past a gap a real reader would trip on |
-| orc-test-designer-opus-5-high | claude-opus-5-5 | high | fill the GAPS the free case matrix could not derive, and author the front-end journey SCRIPT (/orc-test only). HIGH IS THE INSTRUMENT: a shallow designer returns the three obvious cases the deterministic expansion already covered, which is the one output that costs money and adds nothing |
-| orc-test-interpreter-opus-5-low | claude-opus-5-5 | low | read ONLY a run’s evidence files and say whether what is in them is a finding (/orc-test only; SEALED slice, `Read` and nothing else). LOW IS A MEASUREMENT CHOICE, NOT A COST ONE, and nothing may ever upgrade it: a harder-thinking interpreter reasons its way to why a leaked stack trace is probably fine in staging |
-| orc-trace-writer-haiku-4-5 | claude-haiku-4-5 | — (no ladder) | append one phase block of behavior-trace narration from an orchestrator packet (every trace-owning lane; append-only, never reads source) |
-| orc-graph-noter-sonnet-4-6-med | claude-sonnet-4-6 | medium | write ONE sentence per changed function for the local code graph (`orc graph` Layer 2). Reads line RANGES only, pipes its notes to `orc graph notes apply -` (the CLI validates and stores), returns ONE line. Dispatched by code-changing lanes only when `code_graph_notes` is on and a batch reaches its minimum |
-
-## Opus-5-only mode agents (hard-gated; dispatched only when `opus5_only: true`)
-
-`opus5_only` FORCES every dispatched role onto `claude-opus-5-5`, with effort as
-the only cost dial. Each agent below replaces its default with the same slice
-and the same return contract. Effort is PINNED per role — no CLI rewrites
-these. Full mapping + precedence:
-`../skills/_shared/opus5-only.md`.
-
-| Agent | Model | Effort | Replaces |
-|-------|-------|--------|----------|
-| orc-executor-opus-5-low | claude-opus-5-5 | low | the `[0,90)` band · orc-mini's and orc-fast's fixed executor |
-| orc-executor-opus-5-med | claude-opus-5-5 | medium | the `[90,100]` band |
-| orc-analyze-mini-opus-5-med | claude-opus-5-5 | medium | orc-analyze-mini-sonnet-5-high |
-| orc-planner-mini-opus-5-med | claude-opus-5-5 | medium | orc-planner-mini-sonnet-5-high |
-| orc-scout-opus-5-low | claude-opus-5-5 | low | orc-scout-sonnet-4-6-high |
-| orc-pattern-codifier-opus-5-med | claude-opus-5-5 | medium | orc-pattern-codifier-sonnet-5-high |
-| orc-wiki-scanner-opus-5-low | claude-opus-5-5 | low | orc-wiki-scanner-sonnet-5-high |
-| orc-retro-opus-5-med | claude-opus-5-5 | medium | orc-retro-sonnet-5-high |
-
-The eleven roles already on `claude-opus-5-5` — analyst, planner, reviewer,
-verifier, test-author, combiner, learn-writer, advisor, judge, CLAUDE.md
-writer, deep wiki scanner — dispatch
-unchanged under this mode. **Never forced:** `orc-trace-writer-haiku-4-5` (it
-transcribes a packet, no reasoning) and orc-diy (its table is compile-owned).
-**Not dispatched at all:** `orc-graph-noter-sonnet-4-6-med` has NO Opus 5.5
-variant. Under this mode a lane skips graph notes and prints
-`graph notes: skipped (opus5_only)` — a one-sentence summary does not justify an
-Opus 5.5 dispatch, and the graph's structure layer costs no model at all.
-
-Mini execution reuses orc-executor-sonnet-5-high. Fast-lane (orc-fast)
-execution reuses orc-executor-sonnet-5-med — no dedicated agent. Under
-`opus5_only` both reuse orc-executor-opus-5-low.
-
-## orc-quick — the user picks, and no config can override it
-
-`/orc-quick` has NO dedicated agent and NO score table. It asks the USER which
-agent to spawn before EVERY dispatch, and reuses shipped agents:
-
-| Dispatch kind | Offered | Hook-traced |
-|---|---|---|
-| writes code | orc-executor-sonnet-5-med · orc-executor-opus-5-low | yes |
-| read-only recon | orc-recon-sonnet-5-med · orc-recon-opus-5-low · or `other — name a model` | yes · yes · no |
-| review | orc-reviewer-opus-5-low · or ad-hoc | yes / no |
-
-The only dispatch it does not re-ask is build-repair rounds 1–2, which reuse the
-executor the user already chose for that entry; round 3 asks again.
-
-**`opus5_only` and `rubric_bands_override` are both INERT in this lane** — they would silently collapse the user's choice. It is
-the one exception to `opus5_only`'s otherwise flat precedence. See
-`skills/_shared/opus5-only.md` and `skills/orc-quick/references/dispatch-gate.md`.
-
-**Recon is a pinned PAIR; `other` is the ad-hoc escape hatch.** The
-pair exists because the trace hook only sees an agent whose name starts with
-`orc-`: an ad-hoc recon writes no SPAWN/RETURN, is invisible to
-`orc run inflight`, and cannot be counted by `/orc-retro`. The two files share
-ONE return contract, so the choice is a model choice and nothing else.
-
-The escape hatch names **a model only**. The Agent tool takes a per-call model
-and has no per-call effort knob, so the old "ad-hoc model + effort" menu offered
-a setting that did not exist; effort follows the session. An `other` dispatch is
-still not hook-traced — the lane writes its own `DISPATCH … adhoc=true` /
-`VERIFY` lines and still runs the downgrade check from the agent's self-reported
-`actual_model`, and only `/orc-retro` aggregation misses it.
-
-The scout is dispatched only in the System Analyst's DEEP mode: the orchestrator
-fans out ≤`config.max_scouts` (default 3) parallel scouts, one per coverage area
-from the analyst's scout plan, and feeds their evidence bundles back to the
-analyst for pass 2. Scouts are read-only and never analyze/plan/edit.
-
-The orchestrator (main session) is NOT an agent file.
-
-## ⚠ VERIFY IN YOUR ENVIRONMENT
-
-Model IDs use the Platform/API dateless format (confirmed at
-platform.claude.com/docs/en/about-claude/models/model-ids-and-versions):
-claude-haiku-4-5, claude-sonnet-4-6, claude-sonnet-5-5, claude-opus-4-7,
-claude-opus-4-8 and claude-opus-5-5 (the top executor band + the core fixed
-roles). **Sonnet 5 runs on `claude-sonnet-5-5` since v2.1.0** — the agent names
-keep `-sonnet-5-` (a point release in one family keeps the name, as Opus did in
-v1.9.2), and `claude-sonnet-5` stays a valid config value.
-
-1. **Run `/agents`** to confirm Claude Code accepts these full IDs in agent
-   frontmatter — in particular `claude-haiku-4-5` and `claude-opus-5-5`. If it
-   wants short aliases (opus/sonnet/haiku) or dated IDs, adjust
-   each `model:` field. The full IDs are valid at the API level but Claude Code
-   may normalize differently.
-2. **Confirm `effort:` is a valid CLI frontmatter field.** If the CLI ignores
-   it, effort must be conveyed in the dispatched prompt instead.
-3. **Run `/doctor`** for duplicate-name or load errors after any edit.
-
-## ⚠ COST-TIER FALLBACK (the original "wrong model" bug)
-
-A subagent's model cannot exceed the MAIN session's cost tier — request pricier
-and it silently falls back to the main model. **Run your main Claude Code
-session on Opus** or every opus-* agent downgrades to Sonnet. Every executor
-band from score 41 (`[41,90)` and `[90,100]`) AND every core fixed role (analyst, planner, reviewer,
-verifier, test author, combiner, learn writer, ultra advisor/judge) are pinned
-to **claude-opus-5-5** — on an Opus 4.8 session they all land on Opus 4.8. Verify by
-expanding a subagent's tool-call in the transcript to see the model it ran.
-
-## How dispatch works
-
-- Score a task → config preset maps score to an executor agent → dispatch that
-  agent BY NAME with the task slice.
-- Fixed roles dispatch their named agent directly (analyst/planner/reviewer/
-  verifier, mini variants).
-- Every agent is single-role and self-contained (embedded procedure), so a
-  dispatched agent needs no external skill-loading to function.
+# ORC Agents — Roster, Model Mapping & Verification
+
+Single-role, model-specific agents. The orchestrator dispatches BY AGENT NAME —
+model is pinned in frontmatter, not requested in prose. No agent is multi-role.
+
+## Executors (score-mapped by the single 5-band table in config.md)
+
+| Score band | Agent | Model | Effort |
+|-----------|-------|-------|--------|
+| [0,21)   | orc-executor-sonnet-5-low    | claude-sonnet-5-5 | low |
+| [21,31)  | orc-executor-sonnet-5-med    | claude-sonnet-5-5 | medium |
+| [31,41)  | orc-executor-sonnet-5-high   | claude-sonnet-5-5 | high |
+| [41,90)  | orc-executor-opus-5-low      | claude-opus-5-5   | low |
+| [90,100] | orc-executor-opus-5-med      | claude-opus-5-5   | medium |
+
+Score→executor mapping lives in config.md (one canonical 5-band table;
+`rubric_bands` is granularity only, not a preset selector).
+
+**Executors no band names — they still ship.**
+`orc-executor-haiku-5-high`,
+`orc-executor-sonnet-4-6-high`, `orc-executor-opus-4-7-med`,
+`orc-executor-opus-4-7-high`, `orc-executor-opus-4-8-high` and
+`orc-executor-opus-5-high` — six agents — are still generated
+and still installed. They are reachable only when a user names one
+explicitly: `rubric_bands_override`, `orc diy`'s `fixed_executor`, or
+`extra_fallback_agent`. They are not deleted because a table change is not a
+model change, and an agent's model change is always a RENAME.
+
+## Fixed-role agents
+
+| Agent | Model | Effort | Role |
+|-------|-------|--------|------|
+| orc-system-analyst-opus-5-high | claude-opus-5-5 | high | doc analysis |
+| orc-planner-opus-5-med | claude-opus-5-5 | medium | planning |
+| orc-reviewer-opus-5-low | claude-opus-5-5 | low | review (medium until v2.1.0; renamed from orc-reviewer-opus-5-med) |
+| orc-verifier-opus-5-med | claude-opus-5-5 | medium | verify (+ /orc-verify) |
+| orc-test-author-opus-5-med | claude-opus-5-5 | medium | test authoring (opt-in Phase 6.5; writes tests, never runs) |
+| orc-analyze-mini-sonnet-5-high | claude-sonnet-5-5 | high | mini analysis |
+| orc-planner-mini-sonnet-5-high | claude-sonnet-5-5 | high | mini planning |
+| orc-scout-sonnet-4-6-high | claude-sonnet-4-6 | high | deep-analysis code scout (read-only) |
+| orc-recon-sonnet-5-med | claude-sonnet-5-5 | medium | answer ONE repository question with file:line evidence (/orc-quick read-only entries; never edits, never plans) |
+| orc-recon-opus-5-low | claude-opus-5-5 | low | the same contract for a WIDE or SUBTLE question — a blast radius across areas, a defect with no obvious anchor |
+| orc-context-combiner-opus-5-high | claude-opus-5-5 | high | combine 2+ related analyses (full lane) |
+| orc-pattern-codifier-sonnet-5-high | claude-sonnet-5-5 | high | reconcile per-language playbook vs. project files → cached code-pattern (opt-in) |
+| orc-retro-sonnet-5-high | claude-sonnet-5-5 | high | mine behavior traces → calibration report (/orc-retro; read-only) |
+| orc-wiki-scanner-opus-5-low | claude-opus-5-5 | low | scan ONE wiki coverage area → evidence-anchored doc body + crosslink tags (/orc-wiki only; read-only against the project). The DEEP half of the tier ladder: first scan · STRUCTURAL · wide delta · a new exported symbol |
+| orc-wiki-scanner-sonnet-5-high | claude-sonnet-5-5 | high | the LIGHT half of the same ladder — an existing doc whose covered files moved by a small, no-new-surface delta. IDENTICAL return contract; it escalates with `needs_context` rather than under-delivering. Never used for a first scan |
+| orc-executor-opus-5-med | claude-opus-5-5 | medium | the `[90,100]` band in BOTH tables |
+| orc-executor-opus-5-low | claude-opus-5-5 | low | the default table's `[41,90)`, `opus5_only`'s `[0,90)`, and the forced mini/fast executor |
+| orc-advisor-opus-5-xhigh | claude-opus-5-5 | xhigh | ultra Phase U0 advisory brief + rubric + clarification questions (read-only; /orc-ultra only) |
+| orc-judge-opus-5-xhigh | claude-opus-5-5 | xhigh | ultra judgment gates — analysis / plan / implementation (read-only; /orc-ultra only) |
+| orc-learn-writer-opus-5-low | claude-opus-5-5 | low | deepen ONE feature → learning-docs/<slug>/ (/orc-learn only; git-ignored output) |
+| orc-claude-writer-opus-5-low | claude-opus-5-5 | low | scan repo → write/refresh the local CLAUDE.md (/orc-claude only; zero questions) |
+| orc-challenge-judge-opus-5-high | claude-opus-5-5 | high | grade ONE finished artifact against a FROZEN goal + template (/orc-challenge only; read-only). It reports findings and can never declare a pass — `orc challenge record` computes that |
+| orc-challenge-advisor-opus-5-med | claude-opus-5-5 | medium | turn a FAILED verdict into a remediation strategy — root-cause groups, an order with reasons, the decisions that are not defects (/orc-challenge only; read-only, no prose, no diffs) |
+| orc-challenge-reader-opus-5-low | claude-opus-5-5 | low | the COLD READ: answer questions from ONE artifact with `Read` and nothing else (/orc-challenge only). LOW ON PURPOSE — a harder-thinking reader reasons around the gaps D4 exists to find, so a stronger configuration is a worse instrument |
+| orc-challenge-contrarian-opus-5-high | claude-opus-5-5 | high | THE COUNCIL: start from "this has a fatal flaw" and go find it — load-bearing claim, then unhappy path, then second-order (/orc-challenge only; read-only). HIGH IS THE INSTRUMENT: a shallow contrarian returns the three surface complaints the free lint already caught |
+| orc-challenge-outsider-opus-5-low | claude-opus-5-5 | low | THE COUNCIL: what does this page assume you already know? The TIGHTEST slice in the lane — the artifact and this protocol, `Read` only, no goal, no audience, no template (/orc-challenge only). LOW IS A MEASUREMENT, NOT A COST CHOICE: a harder-thinking outsider reasons its way around an unexplained acronym and reports the document is fine. NOTHING MAY UPGRADE IT |
+| orc-challenge-executor-opus-5-med | claude-opus-5-5 | medium | THE COUNCIL: can this be started on Monday, and where is the first step? Returns D6/D2 findings plus the literal `monday_morning` list — or the point at which writing it becomes impossible (/orc-challenge only; read-only, `Bash` to CHECK a prerequisite, never to change anything). Not an ORC build executor — it writes nothing |
+| orc-challenge-principles-opus-5-high | claude-opus-5-5 | high | THE COUNCIL: the ONLY role allowed to say the frozen goal is wrong. Returns `premise` objects — no severity, never in findings[], never near the pass gate — and its report NEVER reaches the judge (/orc-challenge only; read-only). HIGH because rebuilding a problem statement from the ground up is the deepest reasoning in the lane |
+| orc-challenge-expansionist-opus-5-med | claude-opus-5-5 | medium | THE COUNCIL: the only lens not looking for a defect — what is being undervalued? Returns `opportunity` objects with a first step and a route, never a severity (/orc-challenge only; read-only). MEDIUM because it is pattern work against a concrete artifact, the same class as the advisor |
+| orc-doc-writer-opus-5-med | claude-opus-5-5 | medium | write ONE part file of a long document from a slice of sections (/orc-doc only). It writes to `.work/<id>.md` and NEVER opens document.md — that is what makes parallel writing safe here |
+| orc-doc-checker-opus-5-low | claude-opus-5-5 | low | read ONE LINE RANGE of a document and report anchored findings (/orc-doc only; read-only). LOW ON PURPOSE — the same reasoning that pins the challenge cold reader: a harder-thinking checker reasons its way past a gap a real reader would trip on |
+| orc-test-designer-opus-5-high | claude-opus-5-5 | high | fill the GAPS the free case matrix could not derive, and author the front-end journey SCRIPT (/orc-test only). HIGH IS THE INSTRUMENT: a shallow designer returns the three obvious cases the deterministic expansion already covered, which is the one output that costs money and adds nothing |
+| orc-test-interpreter-opus-5-low | claude-opus-5-5 | low | read ONLY a run’s evidence files and say whether what is in them is a finding (/orc-test only; SEALED slice, `Read` and nothing else). LOW IS A MEASUREMENT CHOICE, NOT A COST ONE, and nothing may ever upgrade it: a harder-thinking interpreter reasons its way to why a leaked stack trace is probably fine in staging |
+| orc-trace-writer-haiku-5-high | claude-haiku-5-5 | high | append one phase block of behavior-trace narration from an orchestrator packet (every trace-owning lane; append-only, never reads source) |
+| orc-graph-noter-haiku-5-high | claude-haiku-5-5 | high | write ONE sentence per changed function for the local code graph (`orc graph` Layer 2). Reads line RANGES only, pipes its notes to `orc graph notes apply -` (the CLI validates and stores), returns ONE line. Dispatched by code-changing lanes only when `code_graph_notes` is on and a batch reaches its minimum |
+
+## Opus-5-only mode agents (hard-gated; dispatched only when `opus5_only: true`)
+
+`opus5_only` FORCES every dispatched role onto `claude-opus-5-5`, with effort as
+the only cost dial. Each agent below replaces its default with the same slice
+and the same return contract. Effort is PINNED per role — no CLI rewrites
+these. Full mapping + precedence:
+`../skills/_shared/opus5-only.md`.
+
+| Agent | Model | Effort | Replaces |
+|-------|-------|--------|----------|
+| orc-executor-opus-5-low | claude-opus-5-5 | low | the `[0,90)` band · orc-mini's and orc-fast's fixed executor |
+| orc-executor-opus-5-med | claude-opus-5-5 | medium | the `[90,100]` band |
+| orc-analyze-mini-opus-5-med | claude-opus-5-5 | medium | orc-analyze-mini-sonnet-5-high |
+| orc-planner-mini-opus-5-med | claude-opus-5-5 | medium | orc-planner-mini-sonnet-5-high |
+| orc-scout-opus-5-low | claude-opus-5-5 | low | orc-scout-sonnet-4-6-high |
+| orc-pattern-codifier-opus-5-med | claude-opus-5-5 | medium | orc-pattern-codifier-sonnet-5-high |
+| orc-wiki-scanner-opus-5-low | claude-opus-5-5 | low | orc-wiki-scanner-sonnet-5-high |
+| orc-retro-opus-5-med | claude-opus-5-5 | medium | orc-retro-sonnet-5-high |
+
+The eleven roles already on `claude-opus-5-5` — analyst, planner, reviewer,
+verifier, test-author, combiner, learn-writer, advisor, judge, CLAUDE.md
+writer, deep wiki scanner — dispatch
+unchanged under this mode. **Never forced:** `orc-trace-writer-haiku-5-high` (it
+transcribes a packet, no reasoning) and orc-diy (its table is compile-owned).
+**Not dispatched at all:** `orc-graph-noter-haiku-5-high` has NO Opus 5.5
+variant. Under this mode a lane skips graph notes and prints
+`graph notes: skipped (opus5_only)` — a one-sentence summary does not justify an
+Opus 5.5 dispatch, and the graph's structure layer costs no model at all.
+
+Mini execution reuses orc-executor-sonnet-5-high. Fast-lane (orc-fast)
+execution reuses orc-executor-sonnet-5-med — no dedicated agent. Under
+`opus5_only` both reuse orc-executor-opus-5-low.
+
+## orc-quick — the user picks, and no config can override it
+
+`/orc-quick` has NO dedicated agent and NO score table. It asks the USER which
+agent to spawn before EVERY dispatch, and reuses shipped agents:
+
+| Dispatch kind | Offered | Hook-traced |
+|---|---|---|
+| writes code | orc-executor-sonnet-5-med · orc-executor-opus-5-low | yes |
+| read-only recon | orc-recon-sonnet-5-med · orc-recon-opus-5-low · or `other — name a model` | yes · yes · no |
+| review | orc-reviewer-opus-5-low · or ad-hoc | yes / no |
+
+The only dispatch it does not re-ask is build-repair rounds 1–2, which reuse the
+executor the user already chose for that entry; round 3 asks again.
+
+**`opus5_only` and `rubric_bands_override` are both INERT in this lane** — they would silently collapse the user's choice. It is
+the one exception to `opus5_only`'s otherwise flat precedence. See
+`skills/_shared/opus5-only.md` and `skills/orc-quick/references/dispatch-gate.md`.
+
+**Recon is a pinned PAIR; `other` is the ad-hoc escape hatch.** The
+pair exists because the trace hook only sees an agent whose name starts with
+`orc-`: an ad-hoc recon writes no SPAWN/RETURN, is invisible to
+`orc run inflight`, and cannot be counted by `/orc-retro`. The two files share
+ONE return contract, so the choice is a model choice and nothing else.
+
+The escape hatch names **a model only**. The Agent tool takes a per-call model
+and has no per-call effort knob, so the old "ad-hoc model + effort" menu offered
+a setting that did not exist; effort follows the session. An `other` dispatch is
+still not hook-traced — the lane writes its own `DISPATCH … adhoc=true` /
+`VERIFY` lines and still runs the downgrade check from the agent's self-reported
+`actual_model`, and only `/orc-retro` aggregation misses it.
+
+The scout is dispatched only in the System Analyst's DEEP mode: the orchestrator
+fans out ≤`config.max_scouts` (default 3) parallel scouts, one per coverage area
+from the analyst's scout plan, and feeds their evidence bundles back to the
+analyst for pass 2. Scouts are read-only and never analyze/plan/edit.
+
+The orchestrator (main session) is NOT an agent file.
+
+## ⚠ VERIFY IN YOUR ENVIRONMENT
+
+Model IDs use the Platform/API dateless format (confirmed at
+platform.claude.com/docs/en/about-claude/models/model-ids-and-versions):
+claude-haiku-5-5, claude-sonnet-4-6, claude-sonnet-5-5, claude-opus-4-7,
+claude-opus-4-8 and claude-opus-5-5 (the top executor band + the core fixed
+roles). **Sonnet 5 runs on `claude-sonnet-5-5` since v2.1.0** — the agent names
+keep `-sonnet-5-` (a point release in one family keeps the name, as Opus did in
+v1.9.2), and `claude-sonnet-5` stays a valid config value.
+
+1. **Run `/agents`** to confirm Claude Code accepts these full IDs in agent
+   frontmatter — in particular `claude-haiku-5-5` and `claude-opus-5-5`. If it
+   wants short aliases (opus/sonnet/haiku) or dated IDs, adjust
+   each `model:` field. The full IDs are valid at the API level but Claude Code
+   may normalize differently.
+2. **Confirm `effort:` is a valid CLI frontmatter field.** If the CLI ignores
+   it, effort must be conveyed in the dispatched prompt instead.
+3. **Run `/doctor`** for duplicate-name or load errors after any edit.
+
+## ⚠ COST-TIER FALLBACK (the original "wrong model" bug)
+
+A subagent's model cannot exceed the MAIN session's cost tier — request pricier
+and it silently falls back to the main model. **Run your main Claude Code
+session on Opus** or every opus-* agent downgrades to Sonnet. Every executor
+band from score 41 (`[41,90)` and `[90,100]`) AND every core fixed role (analyst, planner, reviewer,
+verifier, test author, combiner, learn writer, ultra advisor/judge) are pinned
+to **claude-opus-5-5** — on an Opus 4.8 session they all land on Opus 4.8. Verify by
+expanding a subagent's tool-call in the transcript to see the model it ran.
+
+## How dispatch works
+
+- Score a task → config preset maps score to an executor agent → dispatch that
+  agent BY NAME with the task slice.
+- Fixed roles dispatch their named agent directly (analyst/planner/reviewer/
+  verifier, mini variants).
+- Every agent is single-role and self-contained (embedded procedure), so a
+  dispatched agent needs no external skill-loading to function.

package/templates/agents/{orc-executor-haiku-4-5.md → orc-executor-haiku-5-high.md}

@@ -1,8 +1,9 @@
 ---
-name: orc-executor-haiku-4-5
+name: orc-executor-haiku-5-high
 description: >
-  ORC executor — claude-haiku-4-5 (no effort ladder). Dispatched by the build lanes at execution for ONE task, score band none (opt-in only, see MODEL-MAPPING.md).
-model: claude-haiku-4-5
+  ORC executor — claude-haiku-5-5, high effort. Dispatched by the build lanes at execution for ONE task, score band none (opt-in only, see MODEL-MAPPING.md).
+model: claude-haiku-5-5
+effort: high
 tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
@@ -53,6 +54,10 @@ never spawn other agents, never work outside your task slice.
   absent. Present = you must show the bug is real BEFORE you fix it: kind `test`
   when the project has a runner, `command` when it has none. Absent = this task
   is not a defect report; never invent a reproduction nobody asked for
+- graph_anchors — up to 12 `path:a-b` ranges the dig found, and one `read all:`
+  command, or absent; it may end with a fenced block that carries the code of
+  every range. Present → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. A file you will EDIT is still read in
+  full first (read-ladder exception 1). The inline code and the ranges are real bytes of the current blob.
 - worktree_path — work here if set, else the current tree
 
 ## Procedure (embedded — self-contained)
@@ -60,7 +65,8 @@ never spawn other agents, never work outside your task slice.
 2. Read spec_ref if provided.
 2a. Read discipline — `.claude/skills/_shared/read-ladder.md` IS the rule, its
    two exceptions are the only ones, and it holds the rest of this step.
-   - Step 0 before any Grep: `orc graph ctx <symbol|file> --if-enabled --json --brief`;
+   - Step 0: the slice carries `graph_anchors` → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. Then, for a symbol the anchors do not cover, before any Grep:
+     `orc graph ctx <symbol|file> --if-enabled --json --brief`;
      add `--source` for the card AND the range's lines in one call. A file you
      will EDIT is still read IN FULL with Read first. Exit 3 = graph off, skip
      step 0 for the rest of the task.
@@ -89,6 +95,12 @@ never spawn other agents, never work outside your task slice.
 4. Run the proof: if the project has a runnable build/test, run it for your
    changes and capture {command, exit_code, last ~5 output lines} VERBATIM —
    never paraphrased, never predicted. No runner → no_runner_detected: true.
+   Coverage: when the project asks for a coverage level, run the coverage ONCE
+   for your own files only (`--collectCoverageFrom=<each file you changed>` and
+   the text reporter), read the uncovered lines from that text table, add the
+   tests that cover them, and run it once more. Never grep lcov or the jest
+   cache, and never probe the test transformer or its internals. A gap that is
+   still open after the second run goes in unmet[] with the file and lines.
 5. Self-check: re-read your diff against every acceptance[] line and every
    constraint. Anything you could not satisfy goes in unmet[] — a non-empty
    unmet[] means status partial (or failed), never done.
@@ -128,12 +140,13 @@ never spawn other agents, never work outside your task slice.
   did, never what you were handed. `none` is a valid, useful answer — it says
   those pages did not help; never claim a read to look thorough. Omit only when
   the slice carried no wiki material.
-- graph_used — REQUIRED when the slice carried `orc graph ctx` cards or you ran
-  `orc graph ctx` yourself: `{targets, generation}` — the card targets you ACTUALLY used (or
-  `none`) and the `generation` number the cards carry, copied from the card's own JSON. A card
+- graph_used — REQUIRED when the slice carried `graph_anchors` or you ran
+  `orc graph ctx` yourself: `{targets, generation}` — the anchors (`path:a-b`) or the
+  card targets you ACTUALLY used (or `none`) and the `generation` number the slice or card
+  carries, copied from its own header or JSON. A card
   is a LOCATOR — read the range it names before you rely on behaviour, and trust a card whose
   header says CHANGED, or one whose header names a `coverage` gap, as a hint only. `none` is a
-  valid answer; never claim a card helped to look thorough. Omit only when the slice carried no cards.
+  valid answer; never claim anchors or a card helped to look thorough. Omit only when the slice carried no anchors and you ran no `ctx`.
 - repro — REQUIRED when the slice carried `repro.required: true`; absent
   otherwise. Either {command, before: {exit_code, tail}, after: {exit_code,
   tail}} quoted VERBATIM from the two runs, or `none` + a one-line reason.

package/templates/agents/orc-executor-opus-4-7-high.md

@@ -54,6 +54,10 @@ never spawn other agents, never work outside your task slice.
   absent. Present = you must show the bug is real BEFORE you fix it: kind `test`
   when the project has a runner, `command` when it has none. Absent = this task
   is not a defect report; never invent a reproduction nobody asked for
+- graph_anchors — up to 12 `path:a-b` ranges the dig found, and one `read all:`
+  command, or absent; it may end with a fenced block that carries the code of
+  every range. Present → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. A file you will EDIT is still read in
+  full first (read-ladder exception 1). The inline code and the ranges are real bytes of the current blob.
 - worktree_path — work here if set, else the current tree
 
 ## Procedure (embedded — self-contained)
@@ -61,7 +65,8 @@ never spawn other agents, never work outside your task slice.
 2. Read spec_ref if provided.
 2a. Read discipline — `.claude/skills/_shared/read-ladder.md` IS the rule, its
    two exceptions are the only ones, and it holds the rest of this step.
-   - Step 0 before any Grep: `orc graph ctx <symbol|file> --if-enabled --json --brief`;
+   - Step 0: the slice carries `graph_anchors` → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. Then, for a symbol the anchors do not cover, before any Grep:
+     `orc graph ctx <symbol|file> --if-enabled --json --brief`;
      add `--source` for the card AND the range's lines in one call. A file you
      will EDIT is still read IN FULL with Read first. Exit 3 = graph off, skip
      step 0 for the rest of the task.
@@ -90,6 +95,12 @@ never spawn other agents, never work outside your task slice.
 4. Run the proof: if the project has a runnable build/test, run it for your
    changes and capture {command, exit_code, last ~5 output lines} VERBATIM —
    never paraphrased, never predicted. No runner → no_runner_detected: true.
+   Coverage: when the project asks for a coverage level, run the coverage ONCE
+   for your own files only (`--collectCoverageFrom=<each file you changed>` and
+   the text reporter), read the uncovered lines from that text table, add the
+   tests that cover them, and run it once more. Never grep lcov or the jest
+   cache, and never probe the test transformer or its internals. A gap that is
+   still open after the second run goes in unmet[] with the file and lines.
 5. Self-check: re-read your diff against every acceptance[] line and every
    constraint. Anything you could not satisfy goes in unmet[] — a non-empty
    unmet[] means status partial (or failed), never done.
@@ -129,12 +140,13 @@ never spawn other agents, never work outside your task slice.
   did, never what you were handed. `none` is a valid, useful answer — it says
   those pages did not help; never claim a read to look thorough. Omit only when
   the slice carried no wiki material.
-- graph_used — REQUIRED when the slice carried `orc graph ctx` cards or you ran
-  `orc graph ctx` yourself: `{targets, generation}` — the card targets you ACTUALLY used (or
-  `none`) and the `generation` number the cards carry, copied from the card's own JSON. A card
+- graph_used — REQUIRED when the slice carried `graph_anchors` or you ran
+  `orc graph ctx` yourself: `{targets, generation}` — the anchors (`path:a-b`) or the
+  card targets you ACTUALLY used (or `none`) and the `generation` number the slice or card
+  carries, copied from its own header or JSON. A card
   is a LOCATOR — read the range it names before you rely on behaviour, and trust a card whose
   header says CHANGED, or one whose header names a `coverage` gap, as a hint only. `none` is a
-  valid answer; never claim a card helped to look thorough. Omit only when the slice carried no cards.
+  valid answer; never claim anchors or a card helped to look thorough. Omit only when the slice carried no anchors and you ran no `ctx`.
 - repro — REQUIRED when the slice carried `repro.required: true`; absent
   otherwise. Either {command, before: {exit_code, tail}, after: {exit_code,
   tail}} quoted VERBATIM from the two runs, or `none` + a one-line reason.

package/templates/agents/orc-executor-opus-4-7-med.md

@@ -54,6 +54,10 @@ never spawn other agents, never work outside your task slice.
   absent. Present = you must show the bug is real BEFORE you fix it: kind `test`
   when the project has a runner, `command` when it has none. Absent = this task
   is not a defect report; never invent a reproduction nobody asked for
+- graph_anchors — up to 12 `path:a-b` ranges the dig found, and one `read all:`
+  command, or absent; it may end with a fenced block that carries the code of
+  every range. Present → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. A file you will EDIT is still read in
+  full first (read-ladder exception 1). The inline code and the ranges are real bytes of the current blob.
 - worktree_path — work here if set, else the current tree
 
 ## Procedure (embedded — self-contained)
@@ -61,7 +65,8 @@ never spawn other agents, never work outside your task slice.
 2. Read spec_ref if provided.
 2a. Read discipline — `.claude/skills/_shared/read-ladder.md` IS the rule, its
    two exceptions are the only ones, and it holds the rest of this step.
-   - Step 0 before any Grep: `orc graph ctx <symbol|file> --if-enabled --json --brief`;
+   - Step 0: the slice carries `graph_anchors` → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. Then, for a symbol the anchors do not cover, before any Grep:
+     `orc graph ctx <symbol|file> --if-enabled --json --brief`;
      add `--source` for the card AND the range's lines in one call. A file you
      will EDIT is still read IN FULL with Read first. Exit 3 = graph off, skip
      step 0 for the rest of the task.
@@ -90,6 +95,12 @@ never spawn other agents, never work outside your task slice.
 4. Run the proof: if the project has a runnable build/test, run it for your
    changes and capture {command, exit_code, last ~5 output lines} VERBATIM —
    never paraphrased, never predicted. No runner → no_runner_detected: true.
+   Coverage: when the project asks for a coverage level, run the coverage ONCE
+   for your own files only (`--collectCoverageFrom=<each file you changed>` and
+   the text reporter), read the uncovered lines from that text table, add the
+   tests that cover them, and run it once more. Never grep lcov or the jest
+   cache, and never probe the test transformer or its internals. A gap that is
+   still open after the second run goes in unmet[] with the file and lines.
 5. Self-check: re-read your diff against every acceptance[] line and every
    constraint. Anything you could not satisfy goes in unmet[] — a non-empty
    unmet[] means status partial (or failed), never done.
@@ -129,12 +140,13 @@ never spawn other agents, never work outside your task slice.
   did, never what you were handed. `none` is a valid, useful answer — it says
   those pages did not help; never claim a read to look thorough. Omit only when
   the slice carried no wiki material.
-- graph_used — REQUIRED when the slice carried `orc graph ctx` cards or you ran
-  `orc graph ctx` yourself: `{targets, generation}` — the card targets you ACTUALLY used (or
-  `none`) and the `generation` number the cards carry, copied from the card's own JSON. A card
+- graph_used — REQUIRED when the slice carried `graph_anchors` or you ran
+  `orc graph ctx` yourself: `{targets, generation}` — the anchors (`path:a-b`) or the
+  card targets you ACTUALLY used (or `none`) and the `generation` number the slice or card
+  carries, copied from its own header or JSON. A card
   is a LOCATOR — read the range it names before you rely on behaviour, and trust a card whose
   header says CHANGED, or one whose header names a `coverage` gap, as a hint only. `none` is a
-  valid answer; never claim a card helped to look thorough. Omit only when the slice carried no cards.
+  valid answer; never claim anchors or a card helped to look thorough. Omit only when the slice carried no anchors and you ran no `ctx`.
 - repro — REQUIRED when the slice carried `repro.required: true`; absent
   otherwise. Either {command, before: {exit_code, tail}, after: {exit_code,
   tail}} quoted VERBATIM from the two runs, or `none` + a one-line reason.

package/templates/agents/orc-executor-opus-4-8-high.md

@@ -54,6 +54,10 @@ never spawn other agents, never work outside your task slice.
   absent. Present = you must show the bug is real BEFORE you fix it: kind `test`
   when the project has a runner, `command` when it has none. Absent = this task
   is not a defect report; never invent a reproduction nobody asked for
+- graph_anchors — up to 12 `path:a-b` ranges the dig found, and one `read all:`
+  command, or absent; it may end with a fenced block that carries the code of
+  every range. Present → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. A file you will EDIT is still read in
+  full first (read-ladder exception 1). The inline code and the ranges are real bytes of the current blob.
 - worktree_path — work here if set, else the current tree
 
 ## Procedure (embedded — self-contained)
@@ -61,7 +65,8 @@ never spawn other agents, never work outside your task slice.
 2. Read spec_ref if provided.
 2a. Read discipline — `.claude/skills/_shared/read-ladder.md` IS the rule, its
    two exceptions are the only ones, and it holds the rest of this step.
-   - Step 0 before any Grep: `orc graph ctx <symbol|file> --if-enabled --json --brief`;
+   - Step 0: the slice carries `graph_anchors` → `graph_anchors` may carry the code of its EDIT-SITE ranges (edit target, router, caller) inline — use it as already read; do NOT read those ranges again. Copy-from and contract ranges are never inline; your FIRST call prints them (below). With `graph_anchors`, a wiki page is OPTIONAL: read it only for a business rule that the requirement, the anchors and the code do not settle. Your FIRST call prints EVERY range in `graph_anchors` in ONE shell command — the `read all:` line when present, else one `sed -n 'a,bp' <file>` per range joined with `;` and an `echo == <file>:<a>-<b>` header each. Then read further only for what those ranges do not show; do not `cat` a whole anchored file over 150 lines. Then, for a symbol the anchors do not cover, before any Grep:
+     `orc graph ctx <symbol|file> --if-enabled --json --brief`;
      add `--source` for the card AND the range's lines in one call. A file you
      will EDIT is still read IN FULL with Read first. Exit 3 = graph off, skip
      step 0 for the rest of the task.
@@ -90,6 +95,12 @@ never spawn other agents, never work outside your task slice.
 4. Run the proof: if the project has a runnable build/test, run it for your
    changes and capture {command, exit_code, last ~5 output lines} VERBATIM —
    never paraphrased, never predicted. No runner → no_runner_detected: true.
+   Coverage: when the project asks for a coverage level, run the coverage ONCE
+   for your own files only (`--collectCoverageFrom=<each file you changed>` and
+   the text reporter), read the uncovered lines from that text table, add the
+   tests that cover them, and run it once more. Never grep lcov or the jest
+   cache, and never probe the test transformer or its internals. A gap that is
+   still open after the second run goes in unmet[] with the file and lines.
 5. Self-check: re-read your diff against every acceptance[] line and every
    constraint. Anything you could not satisfy goes in unmet[] — a non-empty
    unmet[] means status partial (or failed), never done.
@@ -129,12 +140,13 @@ never spawn other agents, never work outside your task slice.
   did, never what you were handed. `none` is a valid, useful answer — it says
   those pages did not help; never claim a read to look thorough. Omit only when
   the slice carried no wiki material.
-- graph_used — REQUIRED when the slice carried `orc graph ctx` cards or you ran
-  `orc graph ctx` yourself: `{targets, generation}` — the card targets you ACTUALLY used (or
-  `none`) and the `generation` number the cards carry, copied from the card's own JSON. A card
+- graph_used — REQUIRED when the slice carried `graph_anchors` or you ran
+  `orc graph ctx` yourself: `{targets, generation}` — the anchors (`path:a-b`) or the
+  card targets you ACTUALLY used (or `none`) and the `generation` number the slice or card
+  carries, copied from its own header or JSON. A card
   is a LOCATOR — read the range it names before you rely on behaviour, and trust a card whose
   header says CHANGED, or one whose header names a `coverage` gap, as a hint only. `none` is a
-  valid answer; never claim a card helped to look thorough. Omit only when the slice carried no cards.
+  valid answer; never claim anchors or a card helped to look thorough. Omit only when the slice carried no anchors and you ran no `ctx`.
 - repro — REQUIRED when the slice carried `repro.required: true`; absent
   otherwise. Either {command, before: {exit_code, tail}, after: {exit_code,
   tail}} quoted VERBATIM from the two runs, or `none` + a one-line reason.