@azure-id/orc 2.1.1 → 2.2.0

package/bin/webui/fixtures/flow.js

@@ -31,7 +31,7 @@ const diy = {
     { key: "planning", value: "own-planner", default: "auto", is_set: true, desc: "Planning route.", options: ["auto", "own-planner", "superpowers", "openspec"] },
     { key: "pattern", value: "ask", default: "ask", is_set: false, desc: "Code-pattern gate on a cache miss.", options: ["ask", "off", "on"] },
     { key: "scoring", value: "on", default: "on", is_set: false, desc: "Rubric scoring.", options: ["on", "off"] },
-    { key: "fixed_executor", value: "", default: "", is_set: false, desc: "Executor used for every task when scoring is off.", options: ["orc-executor-haiku-4-5", "orc-executor-sonnet-4-6-med", "orc-executor-sonnet-5-high", "orc-executor-opus-4-8-high", "orc-executor-opus-5-high"] },
+    { key: "fixed_executor", value: "", default: "", is_set: false, desc: "Executor used for every task when scoring is off.", options: ["orc-executor-haiku-5-high", "orc-executor-sonnet-5-high", "orc-executor-opus-4-8-high", "orc-executor-opus-5-high"] },
     { key: "review", value: "blocking-only", default: "full", is_set: true, desc: "Review phase depth.", options: ["on", "off", "blocking-only"] },
     { key: "security", value: "off", default: "off", is_set: false, desc: "Security pass.", options: ["off", "ask", "on", "always"] },
     { key: "verify", value: "smoke", default: "full", is_set: true, desc: "Verification depth.", options: ["full", "off", "smoke"] },

package/bin/webui/fixtures/index.js

@@ -21,7 +21,7 @@
 // case here; it is never an edit to a 1 700-line module.
 const { PROJECT, doctor, where } = require("./shell.js");
 const { config } = require("./settings.js");
-const { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph, graphGain, graphGainMeasured } = require("./knowledge.js");
+const { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph, graphSemi, graphGain, graphGainMeasured } = require("./knowledge.js");
 const { runs, runDetail, runDetailClosed, aftermath } = require("./runs.js");
 const { stats, budgetForecast, budgetRates } = require("./stats.js");
 const { pact } = require("./pact.js");
@@ -309,7 +309,7 @@ module.exports.get = function get(route, q) {
       return wikiImpact;
     // v1.8.0 — the code graph, DRIFTED (the state the card must be designed for).
     case "/api/graph":
-      return graph;
+      return q && q.mode === "semi" ? graphSemi : graph;
     // v1.8.2 W4b — the gain meter, and the A/B behind its second button.
     case "/api/graph/gain":
       return graphGain;

package/bin/webui/fixtures/knowledge.js

@@ -309,6 +309,8 @@ const graph = {
   generation: 42,
   gen_id: "c878981d",
   state: "drifted",
+  // v2.2.0 — the configured `code_graph`, added by the API (not by the CLI).
+  mode: "on",
   behind: { added: 1, changed: 3, deleted: 0 },
   engine_stale: false,
   auto_update: true,
@@ -334,6 +336,11 @@ const graph = {
 
 // v1.8.2 W4b — `orc graph gain --json`. The fixture carries the ESTIMATE word
 // and a RANGE, because those are the two things the card must never lose.
+// v2.2.0 — the same index under `code_graph: semi`. `graph status` (no
+// --if-enabled) answers the index state; the API adds `mode` from the config.
+// Served on /api/graph?mode=semi so the default tab stays DRIFTED.
+const graphSemi = { ...graph, state: "fresh", behind: { added: 0, changed: 0, deleted: 0 }, mode: "semi" };
+
 const graphGain = {
   ok: true,
   state: "rows",
@@ -376,4 +383,4 @@ const graphGainMeasured = {
     "executor windows and session totals are kept apart: the main session is 74–80% of a run and the graph never touches it. Every delta is printed beside the OFF group's own spread — a delta smaller than that spread is noise, not a result.",
 };
 
-module.exports = { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph, graphGain, graphGainMeasured };
+module.exports = { wiki, wikiDocs, wikiShow, wikiCoverage, wikiCoverageFull, wikiUnregistered, wikiPlan, wikiDebt, wikiUsage, patterns, patternShow, gotchas, gotchasArchived, gotchaPrunePreview, wikiImpact, graph, graphSemi, graphGain, graphGainMeasured };

package/bin/webui/fixtures/pact.js

@@ -1,111 +1,112 @@
-"use strict";
-/* fixtures/pact.js — canned data for `orc ui --fixtures`.
-   The invariant ledger, carrying one of each state — BROKEN, DRIFTED,
-   UNCHECKABLE, HOLDING.
-
-   THE RULE FOR EVERY FILE IN HERE: carry ONE OF EVERY STATE, including the
-   ugly ones. You cannot DESIGN a STALE chip on a fresh wiki, and a state
-   with no fixture is a state nobody has ever looked at. A per-state count
-   test asserts this, so a new state cannot ship without one.
-
-   Shapes MUST match what `bin/cli.js --json` really emits — a drifted
-   fixture is worse than no fixture. */
-
-const { PROJECT } = require("./shell.js");
-
-const pact = {
-  ok: true,
-  ledger: PROJECT + "/.claude/orc/pact/ledger.json",
-  doc: PROJECT + "/PACT.md",
-  doc_exists: true,
-  entries: 5,
-  retired: 1,
-  counts: { HOLDING: 2, DRIFTED: 1, UNCHECKABLE: 1, BROKEN: 1 },
-  line: "pact: 2 holding · 1 drifted · 1 uncheckable · 1 BROKEN",
-  rows: [
-    {
-      id: "PACT-014",
-      statement: "A payment is never written to the ledger twice for one idempotency key.",
-      origin: { lane: "orc-grill", run: "run-grill-checkout-100826-141130", kind: "constraint" },
-      anchors: ["src/payments/ledger.ts:88", "src/payments/idempotency.ts"],
-      check: { kind: "test", ref: "npm test -- idempotency" },
-      verified_commit: "8a62b4f1c9",
-      confidence: "high",
-      last_check: { status: "fail", commit: "8a62b4f1c9", at: "09-08-2026 11:20:04", ref: "npm test -- idempotency" },
-      // A real-looking failure, not a placeholder: the panel has to lay out a
-      // multi-line check output that does not fit its card.
-      history: [
-        { at: "09-08-2026 11:20:04", status: "fail", commit: "8a62b4f1c9" },
-        { at: "02-08-2026 09:14:51", status: "pass", commit: "c273793aa1" },
-      ],
-      retired: false,
-      state: "BROKEN",
-      why: "check failed at 8a62b4f1 (09-08-2026 11:20:04)",
-      distance: 3,
-    },
-    {
-      id: "PACT-002",
-      statement: "Refund windows are configured, never hardcoded.",
-      origin: { lane: "orc-brainstorm", run: "run-brainstorm-refunds-010826-101010", kind: "constraint" },
-      anchors: ["src/billing/refund.ts"],
-      check: { kind: "grep", ref: "REFUND_WINDOW_DAYS" },
-      verified_commit: "c273793aa1",
-      confidence: "medium",
-      last_check: { status: "pass", commit: "c273793aa1", at: "01-08-2026 10:11:02", ref: "REFUND_WINDOW_DAYS" },
-      history: [{ at: "01-08-2026 10:11:02", status: "pass", commit: "c273793aa1" }],
-      retired: false,
-      state: "DRIFTED",
-      why: "6 commits since c273793a touched 1 anchored file",
-      distance: 6,
-    },
-    {
-      id: "PACT-007",
-      statement: "The admin export never contains a raw email address.",
-      origin: { lane: "user", run: null, kind: "constraint" },
-      anchors: ["src/admin/export.ts"],
-      check: { kind: "manual", ref: null },
-      verified_commit: "783f6971aa",
-      confidence: "low",
-      last_check: null,
-      history: [],
-      retired: false,
-      state: "UNCHECKABLE",
-      // The long day count: an UNCHECKABLE promise nobody has looked at for
-      // months is the case this state exists to make visible.
-      why: "no cheap check exists — this promise is held by review, not by a runner",
-      distance: null,
-    },
-    {
-      id: "PACT-001",
-      statement: "Every outbound webhook is signed with the tenant's current secret.",
-      origin: { lane: "orc", run: "run-orc-webhooks-120726-084500", kind: "constraint" },
-      anchors: ["src/webhooks/sign.ts:40"],
-      check: { kind: "command", ref: "npm run test:webhooks" },
-      verified_commit: "e9dad01bb2",
-      confidence: "high",
-      last_check: { status: "pass", commit: "e9dad01bb2", at: "05-08-2026 16:02:11", ref: "npm run test:webhooks" },
-      history: [{ at: "05-08-2026 16:02:11", status: "pass", commit: "e9dad01bb2" }],
-      retired: false,
-      state: "HOLDING",
-      why: "verified at e9dad01b; no commit since has touched its anchors",
-      distance: 0,
-    },
-    {
-      id: "PACT-009",
-      statement: "Session cookies are always SameSite=Lax.",
-      origin: { lane: "orc-grill", run: "run-grill-auth-200626-113000", kind: "constraint" },
-      anchors: ["src/auth/session.ts"],
-      check: { kind: "grep", ref: "SameSite=Lax" },
-      verified_commit: "cc4778e0aa",
-      confidence: "high",
-      last_check: { status: "pass", commit: "cc4778e0aa", at: "21-06-2026 09:00:00", ref: "SameSite=Lax" },
-      history: [{ at: "21-06-2026 09:00:00", status: "pass", commit: "cc4778e0aa" }],
-      retired: false,
-      state: "HOLDING",
-      why: "verified at cc4778e0; no commit since has touched its anchors",
-      distance: 0,
-    },
-  ],
-};
-
-module.exports = { pact };
+"use strict";
+/* fixtures/pact.js — canned data for `orc ui --fixtures`.
+   The invariant ledger, carrying one of each state — BROKEN, DRIFTED,
+   UNCHECKABLE, HOLDING.
+
+   THE RULE FOR EVERY FILE IN HERE: carry ONE OF EVERY STATE, including the
+   ugly ones. You cannot DESIGN a STALE chip on a fresh wiki, and a state
+   with no fixture is a state nobody has ever looked at. A per-state count
+   test asserts this, so a new state cannot ship without one.
+
+   Shapes MUST match what `bin/cli.js --json` really emits — a drifted
+   fixture is worse than no fixture. */
+
+const { PROJECT } = require("./shell.js");
+
+const pact = {
+  ok: true,
+  ledger: PROJECT + "/.claude/orc/pact/ledger.json",
+  doc: PROJECT + "/PACT.md",
+  doc_exists: true,
+  entries: 5,
+  retired: 1,
+  counts: { HOLDING: 2, DRIFTED: 1, UNCHECKABLE: 1, BROKEN: 1 },
+  line: "pact: 2 holding · 1 drifted · 1 uncheckable · 1 BROKEN",
+  rows: [
+    {
+      id: "PACT-014",
+      statement: "A payment is never written to the ledger twice for one idempotency key.",
+      origin: { lane: "orc-grill", run: "run-grill-checkout-100826-141130", kind: "constraint" },
+      anchors: ["src/payments/ledger.ts:88", "src/payments/idempotency.ts"],
+      check: { kind: "test", ref: "npm test -- idempotency" },
+      verified_commit: "8a62b4f1c9",
+      confidence: "high",
+      last_check: { status: "fail", commit: "8a62b4f1c9", at: "09-08-2026 11:20:04", ref: "npm test -- idempotency" },
+      // A real-looking failure, not a placeholder: the panel has to lay out a
+      // multi-line check output that does not fit its card.
+      history: [
+        { at: "09-08-2026 11:20:04", status: "fail", commit: "8a62b4f1c9" },
+        { at: "02-08-2026 09:14:51", status: "pass", commit: "c273793aa1" },
+      ],
+      retired: false,
+      state: "BROKEN",
+      why: "check failed at 8a62b4f1 (09-08-2026 11:20:04)",
+      distance: 3,
+    },
+    {
+      id: "PACT-002",
+      statement: "Refund windows are configured, never hardcoded.",
+      origin: { lane: "orc-brainstorm", run: "run-brainstorm-refunds-010826-101010", kind: "constraint" },
+      anchors: ["src/billing/refund.ts"],
+      check: { kind: "grep", ref: "REFUND_WINDOW_DAYS" },
+      verified_commit: "c273793aa1",
+      confidence: "medium",
+      last_check: { status: "pass", commit: "c273793aa1", at: "01-08-2026 10:11:02", ref: "REFUND_WINDOW_DAYS" },
+      history: [{ at: "01-08-2026 10:11:02", status: "pass", commit: "c273793aa1" }],
+      retired: false,
+      state: "DRIFTED",
+      why: "6 commits since c273793a touched 1 of 1 anchored file (src/billing/refund.ts)",
+      distance: 6,
+      touched_files: ["src/billing/refund.ts"],
+    },
+    {
+      id: "PACT-007",
+      statement: "The admin export never contains a raw email address.",
+      origin: { lane: "user", run: null, kind: "constraint" },
+      anchors: ["src/admin/export.ts"],
+      check: { kind: "manual", ref: null },
+      verified_commit: "783f6971aa",
+      confidence: "low",
+      last_check: null,
+      history: [],
+      retired: false,
+      state: "UNCHECKABLE",
+      // The long day count: an UNCHECKABLE promise nobody has looked at for
+      // months is the case this state exists to make visible.
+      why: "no cheap check exists — this promise is held by review, not by a runner",
+      distance: null,
+    },
+    {
+      id: "PACT-001",
+      statement: "Every outbound webhook is signed with the tenant's current secret.",
+      origin: { lane: "orc", run: "run-orc-webhooks-120726-084500", kind: "constraint" },
+      anchors: ["src/webhooks/sign.ts:40"],
+      check: { kind: "command", ref: "npm run test:webhooks" },
+      verified_commit: "e9dad01bb2",
+      confidence: "high",
+      last_check: { status: "pass", commit: "e9dad01bb2", at: "05-08-2026 16:02:11", ref: "npm run test:webhooks" },
+      history: [{ at: "05-08-2026 16:02:11", status: "pass", commit: "e9dad01bb2" }],
+      retired: false,
+      state: "HOLDING",
+      why: "verified at e9dad01b; no commit since has touched its anchors",
+      distance: 0,
+    },
+    {
+      id: "PACT-009",
+      statement: "Session cookies are always SameSite=Lax.",
+      origin: { lane: "orc-grill", run: "run-grill-auth-200626-113000", kind: "constraint" },
+      anchors: ["src/auth/session.ts"],
+      check: { kind: "grep", ref: "SameSite=Lax" },
+      verified_commit: "cc4778e0aa",
+      confidence: "high",
+      last_check: { status: "pass", commit: "cc4778e0aa", at: "21-06-2026 09:00:00", ref: "SameSite=Lax" },
+      history: [{ at: "21-06-2026 09:00:00", status: "pass", commit: "cc4778e0aa" }],
+      retired: false,
+      state: "HOLDING",
+      why: "verified at cc4778e0; no commit since has touched its anchors",
+      distance: 0,
+    },
+  ],
+};
+
+module.exports = { pact };

package/bin/webui/fixtures/stats.js

@@ -82,7 +82,7 @@ const budgetForecast = {
   fixed_roles: [
     { role: "orc-system-analyst-opus-5-high", samples: 11, p50: { input: 6100, cache_write: 41000, cache_read: 82000, output: 9000 }, p90: { input: 8600, cache_write: 58000, cache_read: 116000, output: 13000 } },
     { role: "orc-planner-opus-5-med", samples: 11, p50: { input: 5000, cache_write: 33000, cache_read: 68000, output: 7400 }, p90: { input: 7100, cache_write: 47000, cache_read: 96000, output: 10500 } },
-    { role: "orc-trace-writer-haiku-4-5", samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 } },
+    { role: "orc-trace-writer-haiku-5-high", samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 } },
   ],
   low_confidence_bands: 1,
   min_samples: 5,
@@ -117,7 +117,7 @@ const budgetRates = {
   },
   roles: {
     "orc-system-analyst-opus-5-high": { samples: 11, p50: { input: 6100, cache_write: 41000, cache_read: 82000, output: 9000 }, p90: { input: 8600, cache_write: 58000, cache_read: 116000, output: 13000 }, peak_p50: 88000, peak_p90: 131000 },
-    "orc-trace-writer-haiku-4-5": { samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 }, peak_p50: 9000, peak_p90: 14000 },
+    "orc-trace-writer-haiku-5-high": { samples: 41, p50: { input: 900, cache_write: 3000, cache_read: 5400, output: 700 }, p90: { input: 1300, cache_write: 4400, cache_read: 7800, output: 1000 }, peak_p50: 9000, peak_p90: 14000 },
   },
   lanes: {},
   unattributed: { blocks: 12, tokens: { input: 900, cache_write: 12000, cache_read: 24000, output: 1100 } },

package/bin/webui/i18n/en/knowledge.json

@@ -5,6 +5,8 @@
   "knowledge.graph.unknownHint": "The CLI did not answer. Run the command in a terminal to see why.",
   "knowledge.graph.off": "The code graph is off.",
   "knowledge.graph.offHint": "It is off by default. When it is on, code lanes build a local map of the code for free and keep it current.",
+  "knowledge.graph.semi": "semi — kept current, lanes do not read it",
+  "knowledge.graph.semiHint": "The graph is kept current, but no lane reads it. To enable reading, run this command:",
   "knowledge.graph.none": "The graph is on, but no index exists yet. The next code lane builds it, or press the button.",
   "knowledge.graph.files": "Files",
   "knowledge.graph.symbols": "Symbols",

package/bin/webui/i18n/id/knowledge.json

@@ -5,6 +5,8 @@
   "knowledge.graph.unknownHint": "CLI tidak menjawab. Jalankan perintahnya di terminal untuk melihat penyebabnya.",
   "knowledge.graph.off": "Graf kode mati.",
   "knowledge.graph.offHint": "Default-nya mati. Jika menyala, lane kode membuat peta kode lokal secara gratis dan menjaganya tetap baru.",
+  "knowledge.graph.semi": "semi — selalu diperbarui, lane tidak membacanya",
+  "knowledge.graph.semiHint": "Graph selalu diperbarui, tetapi tidak ada lane yang membacanya. Untuk mengaktifkan pembacaan, jalankan perintah ini:",
   "knowledge.graph.none": "Graf menyala, tetapi indeksnya belum ada. Lane kode berikutnya akan membuatnya, atau tekan tombolnya.",
   "knowledge.graph.files": "File",
   "knowledge.graph.symbols": "Simbol",

package/bin/webui/js/panels/knowledge.js

@@ -149,6 +149,19 @@ function knowledgeHeaderStrip(d) {
   return strip;
 }
 
+/* v2.2.0 — code_graph: semi. `graph status` answers the INDEX state, and
+   the API adds the configured `mode`. A semi graph is kept current but no lane
+   reads it, so the panel says so next to the state, with the one command that
+   enables reading. The mode word is a config VALUE — never translated. */
+function graphSemiNote(g) {
+  if (!g || g.mode !== "semi") return null;
+  const box = el("div", "cg-semi");
+  const row = el("div", "row-actions");
+  row.append(chip("SEMI", "idle"), el("span", "note", t("knowledge.graph.semi")));
+  box.append(row, el("div", "note", t("knowledge.graph.semiHint")), el("pre", "cmd", "orc config set code_graph on"));
+  return box;
+}
+
 /* THE CODE GRAPH CARD (v1.8.0). Every value is `orc graph status --json`'s, and
    the state word is never replaced by a friendlier synonym. An update is FREE
    (parser only, no model), so it is a button; an OFF graph shows the one config
@@ -167,6 +180,8 @@ function graphCard(g, body, gain, exact) {
     return c;
   }
   if (exact) c.append(el("div", "note", t("knowledge.cg.exact.lead")));
+  const semiG = graphSemiNote(g);
+  if (semiG && !exact) c.append(semiG);
   const head = el("div", "row-actions");
   head.append(chip(String(g.state).toUpperCase(), g.state === "fresh" ? "ok" : g.state === "drifted" ? "warn" : "idle", g.state === "drifted"));
   const upd = el("button", "btn btn-sm", "orc graph update");
@@ -1228,6 +1243,8 @@ function cgStateCard(g, body) {
     return c;
   }
   c.append(el("div", "note", t("knowledge.cg.state.lead")));
+  const semiS = graphSemiNote(g);
+  if (semiS) c.append(semiS);
   const ladder = el("div", "cg-ladder");
   const steps = [
     ["OFF", t("knowledge.cg.state.off"), t("knowledge.cg.state.toNone")],

package/guides/code-graph-benefit.md

@@ -0,0 +1,116 @@
+# When the code graph helps (with live numbers)
+
+Short version: **the code graph saves search work when the task must find code
+or follow a change across files.** It does not help a change inside one file
+that you already named. It gives no benefit until it has its data.
+
+---
+
+## 1. What the code graph does for you
+
+The code graph is a structure index of your project: files, symbols, callers,
+imports, routes and tests. The lanes read it when they plan and slice a task.
+The graph hook reads it when the main session searches for a known symbol.
+The key `code_graph` sets the mode: `off`, `semi` or `on`.
+
+---
+
+## 2. Before you see a benefit: the graph needs its data
+
+> [!NOTE]
+> - Run `orc graph update` ONE time first. This is a cold build. In the eval
+>   repo (a company Vue repo: 799 files, 8,531 symbols) it took about 3.5 s.
+>   With no index, every graph read answers "no index". The lane then works as
+>   with the graph off.
+> - After that, the hooks keep the index current: after each executor, and on
+>   read. `orc graph status` shows `fresh`.
+> - The 2.2.0 upgrade rebuilds the index one time (engine `graph@7`).
+> - Notes (one sentence per function) are OPTIONAL stored knowledge. A noter
+>   dispatch writes them, and that dispatch costs tokens. The structure layer
+>   is free.
+
+---
+
+## 3. The evidence (real repo, live runs)
+
+How we measured:
+
+- The repo is a real company Vue 2.7 dashboard repo.
+- The lane is `/orc-quick`. The main session is Opus 5.5 medium. The executor
+  is pinned to `orc-executor-opus-5-low`.
+- Each task ran with the graph OFF and with the graph ON. The table shows
+  medians (or means where it says so).
+- We checked each run: lint, jest, and a Playwright journey where the task has
+  a UI. The same grader graded each run against the same lane dossier.
+
+| Task | What it is | Runs (OFF / ON) | Cost | Time | Tokens | Grade |
+|---|---|---|---|---|---|---|
+| RMT1 | Build step 1 of a new 4-step flow from a requirement document (route shell, API call, i18n, journey spec) | 5 / 3 | −9.6 % | −28.4 % | −15.8 % | equal (84) |
+| RMT2 | Change one helper's signature and every caller (5 caller files, 1 test) | 3 / 3 | −2.0 % | −8.6 % | −4.2 % | equal (86) |
+| RMT3 | Build step 2 on top of the built step 1 | 2 / 2 (means) | −8.9 % | +4.0 % | −14.0 % | 80 vs 85 (one ON run missed a display detail) |
+| RMT4 | Change behaviour across the built step 1 + step 2 page; ON had stored notes | 2 / 2 (means) | +7.7 % | +45.5 % | +4.4 % | 77 vs 85.5 (one ON run 66 for stray git-hook files, the other 88) |
+
+e2e: every RMT1/RMT3/RMT4 run that passed reached every journey step in both
+arms.
+
+N = 2–5 per arm. A difference under about 10 % is inside the run-to-run noise
+of one task.
+
+---
+
+## 4. Where the graph helps
+
+- **Finding the code to copy or to change.** The executor's exploration fell
+  40–74 % (RMT1, RMT3 phase split).
+- **Changes that ripple across files.** Callers, props / emits, routes and the
+  tests that reach a caller come in one card. This card replaces a grep, a
+  test hunt and a coverage check.
+- **The main session's own search.** The hook answers a search for a known
+  symbol with its callers, tests and coverage (one time per name, 3 per run at
+  most). When an executor returns, the hook gives the affected tests.
+- **Time.** The clearest win is on new-feature work (RMT1 −28 %).
+
+---
+
+## 5. Where it does not help (or helps very little)
+
+RMT4 is the live example. It is a small follow-up change inside a page that
+the agent reads in a few calls. There was no gain, also with stored notes.
+
+- **A change inside ONE named file with no outside effect.** Both arms read
+  that file. ORC skips the anchors.
+- **Very small tasks.** The lane's own overhead (config, trace, questions) is
+  most of the cost. The graph is break-even.
+- **Test writing and coverage work.** The graph does not write tests. A
+  project rule such as "> 90 % branch coverage" can cost more than all that the
+  graph saves. We saw this in both arms.
+- **No index, or a stale index.** The lane falls back to Grep. There is no
+  harm and no gain.
+
+---
+
+## 6. Turn it on
+
+```bash
+orc config set code_graph on
+orc graph update
+```
+
+Run `orc graph update` one time. The modes are:
+
+- `on` — the hooks keep the graph current, and the lanes read it.
+- `semi` — the hooks keep the graph current. No lane reads it.
+- `off` — nothing.
+
+For the other keys (`code_graph_notes`, `code_graph_card_budget` and more),
+see [configuration](configuration.md).
+
+---
+
+## 7. What it costs
+
+- **Structure:** zero tokens. Local files under `.claude/orc/graph/`. No
+  background process.
+- **Cards:** a few hundred tokens each, with a cap.
+- **Hook cards:** 3 per run at most in the main session.
+- **Notes:** optional. Each batch costs a noter dispatch.