@azure-id/orc 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -10,6 +10,380 @@ Format: `### v<version> — <title> _(<date>)_`.
 
 ---
 
+### v2.2.0 — one graph contract for every coding lane, a graph that reads Vue, and Haiku 5.5 _(2026-10-11)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+This is a minor release. The code graph changes its index shape. Every project
+rebuilds its graph ONE time (cold). Three agents get new names.
+
+EVAL: real company Vue 2.7 repo, /orc-quick, graph OFF vs ON, medians. RMT2
+(change one helper and every caller, N=3/3): cost −2.0 %, time −8.6 %, tokens
+−4.2 %, grade equal (86). RMT1 (build step 1 of a create-transaction flow from a
+requirement, N=3 ON / 5 OFF): cost −9.6 %, time −28.4 %, tokens −15.8 %, grade
+equal (84), e2e 12/12 in every run. RMT3 (build step 2 on the built step 1, N=2/2, means): cost −8.9 %, tokens −14.0 %, time +4.0 %. RMT4 (a cross-file change inside the built page, stored notes on ON, N=2/2, means): no gain — cost +7.7 %, time +45.5 %, tokens +4.4 %; the executor explored only about 4 calls in either arm, so the graph and the stored notes had nothing to save. Details: guides/code-graph-benefit.md.
+
+When the code graph helps, with live numbers: [guides/code-graph-benefit.md](guides/code-graph-benefit.md)
+
+- **New guide:** `guides/code-graph-benefit.md` tells when the code graph helps, with live OFF / ON numbers.
+
+**1. Code graph quality on Vue / JS**
+
+- The `@/` alias resolves. The order is: `jsconfig` / `tsconfig` `paths` (and
+  `baseUrl`) nearest the importer, then the `'@'` alias in the vue / webpack /
+  vite config, then the nearest `src/`, then the repo-root `src/`.
+- The template of a Vue SFC makes edges. Handlers, bindings and component tags
+  are callers. One `<Comp>.template` symbol owns them.
+- `props`, `emits` and `inject` are symbols (`prop`, `emit`, `inject`). A card
+  shows the contract of the component.
+- `() => import('x')` is an import, not a function. SPA route records are
+  `route` symbols (`VIEW /path`). `$router.push({ name })` and
+  `router-link :to` make a route-name edge.
+- `this.$x` built-ins (`$t`, `$router`, …) make no edge.
+- A caller that is not a test never resolves into a test file.
+- `orc graph map --focus`: no word is dropped (IDF weight). Path segments
+  match first. Hubs are damped. Every file is ranked.
+- `orc graph ctx` accepts a bare file name.
+- `orc graph path` can end at a file.
+- `orc graph impact` shows a tests row.
+
+**2. One graph contract for every coding lane**
+
+- Every coding lane uses the same four touchpoints: consult (probe) · orient
+  one time · anchors per code dispatch · affected tests with `changes`.
+- The `graph-status` probe of `orc lane config` has a new field
+  `update_step` (`none` · `hook` · `lane` · `preflight`). A lane runs
+  `orc graph update` only when it is `lane`.
+- Lanes do not call `orc graph gain`.
+- New: `orc graph ctx --for-slice … --anchors`. It gives up to 12
+  `path:a-b` lines and ONE `read all:` command. The slice carries it as
+  `graph_anchors`. The executor runs that command first. This replaces the
+  card in the slice.
+- Declared files can be joined with commas. `ctx --for-slice a.js,b.vue` is
+  the same as `ctx --for-slice a.js b.vue`. A wrong path prints
+  `not found: <path>` on the anchors line. Before, the full list was one
+  missing path, and the slice got no anchors.
+- Focus callees. When a focus word names an exported function or method of a
+  declared file, the anchors are its definition and up to 8 call sites
+  (declared files included). Callers of other exports are dropped. One-word
+  member hits are dropped. A Vue component is never a focus callee.
+- One look-time card. `orc graph ctx <symbol>` also lists the tests that reach
+  a caller (by call, import or name) and a coverage verdict. With `--anchors`
+  it also gives the slice anchors (`anchors_card`). One call replaces grep,
+  the test search, `coverage` and a separate `--for-slice` call. The
+  lane-config announce lines 2/4 and 3/4 name this path.
+- The graph hook speaks to the main session (graph `on` only). (a) A
+  main-session Grep, Glob or shell search of a known symbol gets the ctx card.
+  Compound commands are included. The hook uses the matched name with the
+  highest fan-in, and never a name with fan-in 0. It gives one card per name
+  and 3 cards per run at most. (b) When an ORC executor returns, a new
+  PostToolUse(Task|Agent) hook entry injects the `changes` card (affected
+  tests and risk). The lane then does not call `orc graph changes`.
+  `orc init` and `orc update` add the new hook entry. `orc doctor` counts 6
+  hook entries.
+- `--pack=` stays for users. No lane uses it.
+
+**3. New: `code_graph: semi`**
+
+- The preflight heal and the SubagentStop hook keep the graph current.
+- Every lane read with `--if-enabled` exits 3 (the same as `off`). The trace
+  says `mode=semi`. No hint goes into a context.
+- A read that you type without `--if-enabled` answers from the index.
+- The status line and `orc doctor` show `semi`. The `orc ui` Code graph tab
+  shows a `SEMI` chip.
+
+**4. Gain meter fixes**
+
+- The run match is normalised.
+- `changes` prices only old symbols with callers outside the diff, one time
+  per diff.
+- Every ledger row has an `outcome` field.
+- The heal line is correct.
+- `cochange` says when the history is too short.
+- The parse coverage line uses clearer words.
+
+**5. Trace friction**
+
+- `orc lane phases <lane> --json` has `trace_grammar` and `ask_ids` at the
+  top level.
+- A refused packet names PHASE / NOTE / ASK and the verbs of the lane.
+- A parse error quotes the bad line and shows an example packet.
+
+**6. Models**
+
+- `orc-executor-haiku-4-5` and `orc-executor-sonnet-4-6-med` become ONE
+  agent: `orc-executor-haiku-5-high` (`claude-haiku-5-5`, high).
+- `orc-trace-writer-haiku-4-5` → `orc-trace-writer-haiku-5-high`.
+- `orc-graph-noter-sonnet-4-6-med` → `orc-graph-noter-haiku-5-high`.
+- An old name in your config still works. ORC prints ONE line:
+  `agent <old> is now <new> (2.2.0)`.
+- `bin/pricing.json` has a `claude-haiku-5-5` row (input 0.1, cache write
+  0.125, cache read 0.01, output 0.5; context 1M).
+
+**7. Executor coverage rule**
+
+- The executor runs coverage one time for its own files, with a text report.
+  It does not probe lcov, the jest cache or the transformer. It runs a second
+  time at most. The rest goes to `unmet[]`.
+
+**8. Engine `graph@7`**
+
+- `graph@7` / `heuristic@7` / `RESOLVE_SCHEMA 4`. The first `orc graph update`
+  after the upgrade rebuilds the index cold, one time.
+
+**What you have to do:** run `orc update` once. Then run `orc graph update`
+one time if `code_graph` is `on` or `semi`.
+
+### v2.1.2 — a typed /orc meets the effort guard, and the budget uses each model's price _(2026-10-03)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+This is a fix release. It closes gaps between what the lanes say and what the
+CLI does. It adds two commands (`orc wait start`, `orc wait end`) and two flags
+(`orc doc parts --checked`, `--findings`).
+
+**1. The effort guard for a typed `/orc`**
+
+- The effort guard did not run when you typed `/orc` or `/orc-diy`. A typed
+  command does not cause a `PreToolUse` Skill call. Now a second event,
+  `UserPromptExpansion`, runs the same guard. A session below the necessary
+  effort is stopped at $0.
+- `orc update` and `orc doctor --fix` add ONE `settings.json` entry:
+  `hooks.UserPromptExpansion`, matcher `orc|orc-diy`. A hand-edited matcher is
+  repaired.
+- `orc doctor` shows `typed /orc + /orc-diy gate wired`. It warns
+  `typed-gate-unwired` or `typed-gate-matcher`. The fix for each is `orc update`.
+- A typed `/orc-diy` with no compiled flow is refused at $0.
+- The status-line bridge (`session-model.json`) has a new `session_id` field. A
+  bridge that v2.1.1 wrote still gives the `PreToolUse` medium allowance. A
+  bridge from a different session does not.
+- **Limits you must know.** The guard fails open on each error. The typed gate
+  reads the bridge that the ORC status line writes. Where the ORC status line
+  does not run, the typed gate lets the prompt through. This is possible in the
+  desktop app Code tab, and it is not checked yet. The behaviour on an older
+  Claude Code build that does not know the `UserPromptExpansion` event is not
+  verified. If you change the model or the effort with a key shortcut, a false
+  block is possible until the status line shows again.
+
+**2. Budget pricing**
+
+- `orc budget` priced each token at the Opus 4.8 rate. Now each row uses the
+  rate of its pinned model. The USD figures for forecast and actual are lower.
+  Tokens, weighted tokens and quota do not change.
+- `bands[]` and `fixed_roles[]` have a new `model` field.
+- With `extra_enabled` on and an empty provider rate table, USD is `null` in
+  `--json` and "unavailable" in the text.
+- Calibration now joins a point release to its family (`opus-5/low` and
+  `claude-opus-5-5`). The `unattributed` figure is lower.
+- The pinned model id is correct for each shipped agent. This moves the context
+  window figure, the `orc wiki plan` price and the document cost.
+- `orc budget forecast` with no plan exits 3 (it exited 1) and prints one
+  `--json` object.
+
+**3. `orc wait start` and `orc wait end`**
+
+- No command recorded a wait that started. Two new commands do:
+  `orc wait start <spec> --mode <safe|soft|hard> [--trigger user|gate] [--run <slug>] [--hop] [--max-hops] [--json]`
+  and
+  `orc wait end [<slug>] --reason <elapsed|recovered|cancelled|max-hops> [--json]`.
+- `orc wait start` exits 0 when it records the wait, and also when there is no
+  run (`recorded:false reason:no-run`). It exits 1 for `no-mode`, `bad-trigger`,
+  `already-waiting` or a spec it cannot parse. It exits 2 for `no-reading`.
+- `orc wait end` exits 0. It exits 1 for `no-run`, `no-wait` or `no-reason`.
+- The trace has the lines
+  `WAIT mode=… requested=…m start=HH:MM end=HH:MM hops=<planned>/<max> trigger=…`
+  and `WAIT end :: done=k/n reason=…`. A block writes
+  `WAIT block :: reason=… by=user`, and its end writes `WAIT unblock`.
+- `orc wait status --json` has a new `stale` field. `waiting` and `hops_done`
+  come from the clock. `orc wait cancel` refuses a stale wait.
+- An old `wait.json` that holds only a block reads as "not waiting".
+- **Known limits.** A wait that `max_hops` cuts short keeps its full `ends_at`,
+  so `status` shows `waiting` until `orc wait end` runs. A spec token that is
+  equal to a `--mode`, `--trigger` or `--run` value is ambiguous.
+
+**4. orc-doc: `--checked` and `--findings`**
+
+- No CLI path marked a section as checked, so `orc doc next` named the paid
+  check again. Two new flags record the check:
+  `orc doc parts <slug> --checked <ids>` and `--findings <id>=<n>,…`.
+- A refusal exits 1 with `not-confirmed`, `no-such-section` or `bad-findings`,
+  and writes nothing.
+- `orc doc parts --json` has new fields: `checked[]`,
+  `flagged[{id,findings}]` and `edit_rounds`. In `doc.json`, a section has
+  `checked_cycle` and `edit_rounds`.
+- `orc doc next` has a new action, `plan-edit`. After 2 edit rounds on one
+  section it stops and asks you.
+- The lane text says that a checker reads only the bounded part files of one
+  slice. The request log runs after the slug exists. An edit does not leave the
+  section as `user-edited`.
+- **Known limits.** `edit_rounds` does not reset. `--confirm` and `--checked`
+  in one call are not atomic.
+
+**5. The graph word focus**
+
+- `orc graph map --focus <word>` ignored a plain word and said
+  "focus not in the graph". Now a word resolves to the files that hold it.
+- `orc graph map --json` has new fields: `focus_words` and `focus_common`.
+- The trace says `repo` when nothing resolved. `focus=` shows a maximum of 8
+  files, then `,+N`.
+
+**6. `/orc-fix`: the host run and the FIX source**
+
+- A stale `.current` (older than 6 hours), or a bootstrap `.current` with no
+  lane, was read as a host run. Now it gives `mode: may-fix`, `host: null`, no
+  `FIX` line and no `fix_run`.
+- The classify JSON has a new `open_run` field.
+- The `FIX` trace line and the stored row now show the same source.
+
+**7. Boundary block lists**
+
+- `orc boundary status` read only inline lists. It now reads block lists
+  (`- item` lines) also.
+- A REFUSE card that uses a block list exits 2. It exited 3 (MALFORMED).
+- Staleness counts only the commits that touch an anchored file.
+- A field that is not a list gives this text:
+  "`<field>` is not a list — write `- item` lines or [a, b]".
+- The header parser: ` #` inside quotes is text, and a comma inside quotes does
+  not split an inline item. The wiki documents use the same parser.
+
+**8. Pact, aftermath and stack status**
+
+- `orc pact`: the DRIFTED reason counted each anchor. Now it reads
+  "N commits since X touched K of M anchored files (a, b)". Each row has a new
+  `touched_files` field.
+- `orc aftermath status` graded the open trace of its own lane. The open run
+  now has no row. A project that has only the open run exits 3 with `shallow`.
+- `orc pr stack status`: `<n>` and `<m>`, a hole of 120 characters or less, and
+  a paragraph that is only a placeholder count as not filled. Comments, code
+  fences, generics and inline tags do not count. **A plan that v2.1.1 showed as
+  READY can show NOT READY.**
+- The PR split does not pull. It runs
+  `git merge-base --is-ancestor <trunk> $SNAPSHOT` and stops when the trunk
+  moved. A pull that moved the trunk caused a silent revert.
+
+**9. The call catalogue and the trace verbs**
+
+- `orc lane calls`: the catalogue rows that listed only exit 0 now list each
+  exit code. The `budget-forecast` row has the correct codes. The catalogue
+  gaps are closed.
+- The trace accepts three more verbs: `DOC`, `WAIT` and `GRAPH-COVERAGE`. The
+  `orc-mini` and `orc-fast` trace grammar includes the `GRAPH-*` verbs.
+- `orc-learn` and `orc-poly` do not write a `WIKI-CONSULT` head that is not
+  declared.
+
+**10. Small text and CLI fixes**
+
+- Four refusals for a human reader crashed because a status mark was not
+  defined. They print the refusal now.
+- The lexicon escape does not insert a stray comment line.
+- `orc_wiki_pattern_findings`: the skills and the CLI use the same value.
+- The `/orc-fast` text names the executor that it dispatches,
+  `orc-executor-sonnet-5-med`. Its `opus5_only` twin is `orc-executor-opus-5-low`
+  in the CLI also.
+- `/orc-test`: the text names the server that `orc test env up` leaves running.
+- `/orc-challenge` does not point its intake at the build-lane intake file.
+- `/orc-export`: the text is correct for the challenge cycle source, for
+  `--check` with a hand-written `AGENTS.md`, and for the import of commands.
+- The code-graph text says that the gain meter cannot see `graph_used: none`
+  yet, so `avoided` still counts that card.
+- 9 `expect=` spellings in the templates changed to the pinned model ids.
+
+**Changed behaviour**
+
+- `orc budget forecast` with no plan: exit 3 (was 1).
+- `orc budget`: lower USD figures; `model` in `bands[]` and `fixed_roles[]`;
+  USD `null` / "unavailable" with `extra_enabled` and no provider rates.
+- `orc boundary status`: a block-list REFUSE card exits 2 (was 3); the new
+  "is not a list" text; staleness counts anchored-file commits only.
+- `orc pact`: new DRIFTED `why` text; `touched_files` in each row.
+- `orc pr stack status`: a READY plan from v2.1.1 can show NOT READY.
+- `orc aftermath status`: no row for the open run; exit 3 `shallow` when that
+  is the only run.
+- `/orc-fix`: `mode: may-fix` and `host: null` for a stale or lane-less
+  `.current`; `open_run` in the classify JSON.
+- `orc graph map --focus <word>`: a word now focuses; `focus_words` and
+  `focus_common` in `--json`.
+- `orc wait status --json`: `stale`; `cancel` refuses a stale wait; an old
+  block-only `wait.json` reads as not waiting.
+- `orc doc parts --json`: `checked[]`, `flagged[]`, `edit_rounds`; `orc doc
+  next` can return `plan-edit`.
+- `session-model.json`: `session_id`.
+
+**What you have to do:** run `orc update` once. It adds the
+`UserPromptExpansion` entry to `settings.json`.
+
+---
+
+### v2.1.1 — the quick and fast lanes move to Sonnet 5 _(2026-10-02)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+This release changes the models that `/orc-quick`, `/orc-fast` and `orc extra`
+use. Sonnet 4.6 leaves the coding lanes. Sonnet 5 (`claude-sonnet-5-5`) replaces it.
+
+**1. The quick dispatch gate**
+
+- Code entries: `orc-executor-sonnet-5-med` or `orc-executor-opus-5-low`. The
+  default suggestion for a mechanical edit is `orc-executor-sonnet-5-med`.
+- Read-only entries: `orc-recon-sonnet-5-med` or `orc-recon-opus-5-low`.
+- An agent's model change is a rename:
+  `orc-recon-sonnet-4-6-med` → `orc-recon-sonnet-5-med`. The agent count stays 51.
+
+**2. orc extra**
+
+- The `quick-executor` slot uses `orc-executor-sonnet-5-med`.
+- `extra_fallback_agent` options and the fallback menu show
+  `orc-executor-sonnet-5-high`. They showed `orc-executor-sonnet-4-6-high`. A
+  config that names the old agent is still accepted.
+
+**3. /orc-fast**
+
+- The one executor is `orc-executor-sonnet-5-med`. It was
+  `orc-executor-sonnet-4-6-high`. The `fast-executor` extra slot, `orc budget`
+  and the `opus5_only` table use the new name. Under `opus5_only` it is still
+  `orc-executor-opus-5-low`.
+- Run the lane from a Sonnet 5 (or higher) main session. A Sonnet 4.6 session is
+  below the executor's pin.
+
+**4. Text and examples**
+
+- `/orc`: the "even the smallest task gets a cheap subagent" rule names Sonnet 5
+  low. The examples dispatch Sonnet 5 high for scores 31–40.
+- `/orc-grill`: the recon line names `claude-sonnet-5-5 / medium`.
+
+**Not changed:** Sonnet 4.6 stays for the graph noter, the scout, the `orc diy`
+choices and the opt-in executors (`orc-executor-sonnet-4-6-med`,
+`orc-executor-sonnet-4-6-high`).
+
+**What you have to do:** `orc update --prune`. If a script names
+`orc-recon-sonnet-4-6-med`, change it to `orc-recon-sonnet-5-med`.
+
+---
+
 ### v2.1.0 — the review counts, the score table moves up, and old logs can go _(2026-10-02)_
 
 **Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`

package/README.md

@@ -7,14 +7,14 @@
 *Intake → analyze → plan → score → parallel subagents → review → verify → ship.*
 
 ![npm](https://img.shields.io/npm/v/%40azure-id%2Forc?style=for-the-badge&color=cb3837&logo=npm)
-![Version](https://img.shields.io/badge/version-2.1.0-blue.svg?style=for-the-badge)
+![Version](https://img.shields.io/badge/version-2.2.0-blue.svg?style=for-the-badge)
 ![License](https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=for-the-badge)
 ![Claude Code](https://img.shields.io/badge/Claude_Code-Skills-purple.svg?style=for-the-badge)
 ![Dependencies](https://img.shields.io/badge/dependencies-zero-lightgrey.svg?style=for-the-badge)
 ![GitHub stars](https://img.shields.io/github/stars/azure-id/orc?style=for-the-badge&color=yellow)
 
-**Latest: v2.1.0** · updated 02-10-2026 · [full changelog](CHANGELOG.md)
+**Latest: v2.2.0** · updated 11-10-2026 · [full changelog](CHANGELOG.md)
 
 **On npm: [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc)** — `npm i -g @azure-id/orc`
 
@@ -266,7 +266,7 @@ ORC have terminal hook to see: Context Window %, 5 Hour usage %, Weekly usage %
 | **`/orc-grill`** | You have one idea and it is still vague. It asks rounds of questions, **looks facts up itself** instead of making you recite your own codebase, and never answers its own question. Ends when *you* say the idea matches what you meant. | [see it](mock-run/orc-grill.md) |
 | **`/orc-analyze`** | A document or a request → a scope-bounded, code-grounded spec. Every claim carries `file:line` evidence or becomes a question. Deep mode adds parallel scouts. | [see it](templates/skills/orc-analyze/examples/analyze-mock.md) |
 | **`/orc-plan`** | A request or a spec → a real task plan: grounded files, dependencies, facets, and a test disposition per task. | [see it](mock-run/orc-plan.md) |
-| **`/orc-doc`** | Writes the long document — a PRD, a TSD, a cross-team agreement, a status report or a runbook — as portable Markdown that imports cleanly into Notion, Obsidian, Docs, Coda, Craft and GitHub. **ORC never reads the document body**: each section is its own file under `sections/`, each writer owns exactly one of them, each checker reads one bounded part, and `document.md` is a build artifact rebuilt for free. Every wave is a stop you can walk away from, and it resumes months later without you explaining anything twice. | [see it](mock-run/orc-doc.md) |
+| **`/orc-doc`** | Writes the long document — a PRD, a TSD, a cross-team agreement, a status report or a runbook — as portable Markdown that imports cleanly into Notion, Obsidian, Docs, Coda, Craft and GitHub. **ORC never reads the document body**: each section is its own file under `sections/`, each writer owns exactly one of them, each checker reads only the bounded part files of one slice, and `document.md` is a build artifact rebuilt for free. Every wave is a stop you can walk away from, and it resumes months later without you explaining anything twice. | [see it](mock-run/orc-doc.md) |
 | **`/orc-route`** | You have a plan — which lane should build it? It names one lane, the runners-up with what each costs you, and any lane that is impossible with the condition blocking it. **It refuses to route a sentence**, because that would be guessing. | [see it](mock-run/orc-route.md) |
 | **`/orc-explain`** | "Wait, what?" It says the last message again: the point first, then the background it assumed, then every ORC-only word defined in your project's terms. | [see it](mock-run/orc-explain.md) |
 | **`/orc-poly`** | One change across two or more repos, without drift. Peer source is read-only; it freezes the shared boundary into a contract and writes one plan per repo. It never builds. | [see it](templates/skills/orc-poly/examples/poly-run-mock.md) |
@@ -387,7 +387,7 @@ and its headings become the outline.
 A local map of how your code is connected. It is **off by default**.
 
 ```bash
-orc config set code_graph on          # code lanes build and use the map (free)
+orc config set code_graph on          # code lanes build and use the map (free); `semi` = keep it current, no lane reads it
 orc config set code_graph_notes wave  # optional: one-sentence notes (costs tokens)
 orc graph map                         # the repository ranked, before you know a file name
 orc graph ctx OrderService.create     # a card: callers, calls, SQL/HTTP/env effects
@@ -419,8 +419,8 @@ orc graph gain                        # what the map put in, and an estimate of
   prints only the OUTSIDE view of a file an agent is about to read in full.
   `--format tree` names each column once instead of on every row.
 - **`orc graph map` answers "which files matter here"** before you know a file
-  name, inside a budget. `--focus` re-ranks the whole repository around the files
-  or names your request already mentioned. **Rank is a hint about where to look
+  name, inside a budget. `--focus` re-ranks the whole repository around the files,
+  names or plain words your request already mentioned. **Rank is a hint about where to look
   first**, never proof that a file matters to a change.
 - **It shows where code is. It does not replace reading it.** Agents still read
   the line range before they act. A card header says `coverage partial 327-466`
@@ -698,6 +698,7 @@ Some lanes ship a full how-to next to the skill, in plain language:
 | [Rules](guides/rules.md) | you want the 65 anti-slop rules, the precedence ladder and the lint |
 | [Configuration](guides/configuration.md) · [Model selection](guides/model-selection.md) | you want every key, or the scoring bands |
 | [Habits and gotchas](guides/habits-and-gotchas.md) | you want to know how a habit is proposed, how to import Sonar, SARIF or PR history, and how to undo |
+| [Code graph benefit](guides/code-graph-benefit.md) | you want to know when the code graph helps, with live numbers |
 | [Other AI models](guides/extra-models.md) | you want part of the ladder to run somewhere other than Claude |
 
 Every skill also ships its own `SKILL.md` and `references/`. The guides above are
@@ -741,39 +742,51 @@ a current audit: [EVAL-REPORT.md](EVAL-REPORT.md).
 **Full history: [CHANGELOG.md](CHANGELOG.md)** — or `orc changelog`, which prints
 only what is newer than the version you have.
 
-### v2.1.0 — the review counts, the score table moves up, and old logs can go _(2026-10-02)_
-
-- **A new score table with five bands.** Scores 0–40 go to Sonnet 5 (low,
-  medium, high). Scores 41–89 go to Opus 5.5 low, and 90–100 to Opus 5.5 medium.
-  Haiku is no longer in the table. **Every band from 41 needs an Opus 5.5 main
-  session.**
-- **Sonnet 5 runs on `claude-sonnet-5-5`.** The price table is correct again.
-- **The reviewer is `orc-reviewer-opus-5-low`.** In the live eval, low effort
-  found every seeded defect that was still in the diff.
-- **The wiki scanner and the CLAUDE.md writer use Opus 5.5 low** (they used Opus
-  4.8).
-- **Review quality no longer says "0 so far" after real reviews.** It counts
-  reviews from the traces. A clean review counts too.
-- **Your project's own review rule.** When CLAUDE.md or AGENTS.md asks for a
-  different review (for example `/code-review`), the lanes ask "ORC review, that
-  review, or skip". `orc review policy` shows what ORC found.
-- **New lane `/orc-fix`.** It records a fix after a review (Sonar, a red CI, a
-  bug) and who added the bug. The reviewer card shows it, and the panel shows
-  "Fixes after review".
-- **`orc clear logs`** shows old traces and run folders. `--apply` deletes them.
-  Nothing is deleted automatically unless you set `log_retention_auto: on`.
-- **The status line timer:** 1, 2, 3, 5 or 10 seconds. Below 1 second is refused,
-  because Claude Code does not support it.
-- **Behaviour tab fixes:** with `habits: off` you still see Review quality and
-  Gotchas, `/orc-fast` records your answers, and the answer log shows the question.
-
-**What you have to do:** `orc update`. If you compiled an `orc diy` flow, run
-`orc diy compile`. If a script names `orc-reviewer-opus-5-med`, change it to
-`orc-reviewer-opus-5-low`. The cost changes: read the CHANGELOG.
+### v2.2.0 — one graph contract for every coding lane, a graph that reads Vue, and Haiku 5.5 _(2026-10-11)_
+
+- **The code graph reads Vue / JS.** The `@/` alias, template edges, props /
+  emits / inject, lazy imports, SPA routes and route-name edges. `$` built-ins
+  make no edge. A test file never takes a non-test caller.
+- **One graph contract for every coding lane.** Four touchpoints. The new
+  `update_step` probe field says who updates the graph. Lanes do not call
+  `gain`. The slice gets `graph_anchors` (`ctx --for-slice --anchors`): up to
+  12 ranges and one `read all:` command. Declared files can be joined with
+  commas. A focus word that names an exported function gives its definition
+  and up to 8 call sites.
+- **One look-time card.** `orc graph ctx <symbol>` also lists the tests that
+  reach a caller and a coverage verdict. With `--anchors` it also gives the
+  slice anchors. One call replaces grep, the test search, `coverage` and
+  `--for-slice`.
+- **The graph hook speaks to the main session** (graph `on` only). A search
+  of a known symbol gets its card (3 per run at most). When an executor
+  returns, a new hook entry gives the `changes` card. `orc doctor` counts 6
+  hook entries.
+- **New: `code_graph: semi`.** The graph stays current. No lane reads it.
+- **Gain meter fixes:** run match, `changes` pricing, the `outcome` field, the
+  heal line, short `cochange` history.
+- **Trace friction:** `orc lane phases --json` gives `trace_grammar` and
+  `ask_ids`. A refused or bad packet tells you what to correct.
+- **Haiku 5.5.** The Haiku 4.5 and Sonnet 4.6-medium agents become
+  `*-haiku-5-high`. An old name in your config still works, with one notice.
+- **Engine `graph@7`.** The index rebuilds cold one time.
+
+EVAL: real company Vue 2.7 repo, /orc-quick, graph OFF vs ON, medians. RMT2
+(change one helper and every caller, N=3/3): cost −2.0 %, time −8.6 %, tokens
+−4.2 %, grade equal (86). RMT1 (build step 1 of a create-transaction flow from a
+requirement, N=3 ON / 5 OFF): cost −9.6 %, time −28.4 %, tokens −15.8 %, grade
+equal (84), e2e 12/12 in every run. RMT3 (build step 2 on the built step 1, N=2/2, means): cost −8.9 %, tokens −14.0 %, time +4.0 %. RMT4 (a cross-file change inside the built page, stored notes on ON, N=2/2, means): no gain — cost +7.7 %, time +45.5 %, tokens +4.4 %; the executor explored only about 4 calls in either arm, so the graph and the stored notes had nothing to save. Details: guides/code-graph-benefit.md.
+
+When the code graph helps, with live numbers: [guides/code-graph-benefit.md](guides/code-graph-benefit.md)
+
+**What you have to do:** run `orc update` once. Then run `orc graph update`
+one time if `code_graph` is `on` or `semi`.
 
 <details>
-<summary><strong>Earlier releases</strong> — 127 of them, titles only. Full text in <a href="CHANGELOG.md">CHANGELOG.md</a>.</summary>
+<summary><strong>Earlier releases</strong> — 130 of them, titles only. Full text in <a href="CHANGELOG.md">CHANGELOG.md</a>.</summary>
 
+- **v2.1.2** — a typed /orc meets the effort guard, and the budget uses each model's price · _2026-10-03_
+- **v2.1.1** — the quick and fast lanes move to Sonnet 5 · _2026-10-02_
+- **v2.1.0** — the review counts, the score table moves up, and old logs can go · _2026-10-02_
 - **v2.0.4** — design the status line to the last cell · _2026-09-30_
 - **v2.0.3** — the status line you designed is the status line you see · _2026-09-30_
 - **v2.0.2** — the lanes record what you answered, and the reviewer always gets the card · _2026-09-28_

package/bin/build-agents.js

@@ -36,7 +36,7 @@ const OUT_DIR = path.join(ROOT, "templates", "agents");
 //
 // v1.0.0 W4 — the table was SIX bands, not eight, and the `opus5_only` ladder is
 // TWO, not three. v2.1.0 made the table FIVE bands (Sonnet 5 low/med/high, then
-// Opus 5.5 low/med). Seven of these agents are named by NO default row:
+// Opus 5.5 low/med). Six of these agents are named by NO default row:
 // names them, and they ship anyway (D14). They stay reachable through
 // `rubric_bands_override`, `orc diy` `fixed_executor` and `extra_fallback_agent`,
 // and deleting a generated file that no row happens to name today would be a
@@ -52,8 +52,10 @@ const VARIANTS = [
   // NAMED BY NO BAND since v1.0.0 W4 / v2.1.0 (D14) — kept on disk, dispatched
   // only when a user names one explicitly.
   { name: "orc-executor-sonnet-4-6-high", model: "claude-sonnet-4-6", effort: "high",  band: "none (opt-in only, see MODEL-MAPPING.md)" },
-  { name: "orc-executor-sonnet-4-6-med", model: "claude-sonnet-4-6", effort: "medium", band: "none (opt-in only, see MODEL-MAPPING.md)" },
-  { name: "orc-executor-haiku-4-5",      model: "claude-haiku-4-5",  effort: null,     band: "none (opt-in only, see MODEL-MAPPING.md)" },
+  // v2.2.0 — `haiku-4-5` and `sonnet-4-6-med` were RENAMED into this one row
+  // (an identical twin would have been the result). cli.js LEGACY_AGENTS maps
+  // the old names for configs that still write them.
+  { name: "orc-executor-haiku-5-high",   model: "claude-haiku-5-5",   effort: "high",   band: "none (opt-in only, see MODEL-MAPPING.md)" },
   { name: "orc-executor-opus-5-high",    model: "claude-opus-5-5",    effort: "high",   band: "none (opt-in only, see MODEL-MAPPING.md)" },
   { name: "orc-executor-opus-4-8-high",  model: "claude-opus-4-8",  effort: "high",   band: "none (opt-in only, see MODEL-MAPPING.md)" },
   { name: "orc-executor-opus-4-7-high",  model: "claude-opus-4-7",  effort: "high",   band: "none (opt-in only, see MODEL-MAPPING.md)" },
@@ -87,8 +89,8 @@ const TWINS = [
       desc: "ORC Pattern Codifier — claude-opus-5-5, medium effort. Dispatched by orc-pattern, instead of orc-pattern-codifier-sonnet-5-high when `opus5_only: true`." },
   ] },
   { family: "recon", variants: [
-    { name: "orc-recon-sonnet-4-6-med", model: "claude-sonnet-4-6", effort: "medium", who: "Sonnet 4.6, medium",
-      desc: "ORC Recon — claude-sonnet-4-6, medium effort. Dispatched by /orc-quick at the dispatch gate, for a read-only question. It never edits." },
+    { name: "orc-recon-sonnet-5-med", model: "claude-sonnet-5-5", effort: "medium", who: "Sonnet 5, medium",
+      desc: "ORC Recon — claude-sonnet-5-5, medium effort. Dispatched by /orc-quick at the dispatch gate, for a read-only question. It never edits." },
     { name: "orc-recon-opus-5-low", model: "claude-opus-5-5", effort: "low", who: "Opus 5.5, low",
       desc: "ORC Recon — claude-opus-5-5, low effort. Dispatched by /orc-quick at the dispatch gate, for a WIDE or SUBTLE read-only question. It never edits." },
   ] },