@azure-id/orc 1.8.2 → 1.9.1

package/bin/cli.js

@@ -180,8 +180,10 @@ function writeStdoutSync(str) {
 }
 
 // Print the object and (optionally) exit with the human path's code.
-function emitJson(obj, exitCode) {
-  writeStdoutSync(JSON.stringify(obj, null, 2) + "\n");
+// `compact` (v1.9.1 B1) writes the answer with no indentation: a `--brief`
+// answer is read by a model, and the card inside it carries its own newlines.
+function emitJson(obj, exitCode, compact) {
+  writeStdoutSync((compact ? JSON.stringify(obj) : JSON.stringify(obj, null, 2)) + "\n");
   if (exitCode !== undefined) process.exit(exitCode);
 }
 
@@ -3182,9 +3184,10 @@ function laneAnnounce(lane, map, claudeDir, families) {
   const graphOn = String(Object.prototype.hasOwnProperty.call(map, "code_graph") ? map.code_graph : metaFor("code_graph").def) === "on";
   if (graphOn && LANE_CALLS["graph-status"].lanes.includes(lane))
     out.push(
-      "graph: on — use the code-graph cache: (1) now: `orc graph status --if-enabled --heal --json` (builds or updates it); " +
-        "(2) every code-writing slice: `orc graph ctx <declared files> --if-enabled --json` cards; " +
-        "(3) after every code change: `orc graph update --if-enabled --json` (keeps it for the next run). Copy each `line` and `trace` verbatim"
+      "graph: on — use the code-graph cache: (1) now: `orc graph status --if-enabled --heal --json --brief` (builds or updates it); " +
+        "(2) every code-writing slice: `orc graph ctx <declared files> --if-enabled --json --brief` cards; " +
+        "(3) after every code change: `orc graph update --if-enabled --json --brief` (keeps it for the next run). " +
+        "Copy each `line` and `trace` verbatim; `--brief` drops the rows you never print"
     );
   // A shadowed setting must never be silent, and neither must an inert one.
   const shadowed = [];
@@ -3347,7 +3350,10 @@ const LANE_CALLS = {
     on_absent: "`none` means absent; say so in ONE user line and continue — a missing wiki is never a blocker",
     canonical: "_shared/detecting-artifacts.md",
     never: "never second-guess a positive probe with a raw `find` (the wiki lives under a dot-dir), and never compute the tier yourself — this command is its only executor",
-    lanes: ["orc", "orc-boundary", "orc-brainstorm", "orc-fast", "orc-grill", "orc-poly", "orc-quick", "orc-route", "orc-wiki"],
+    // v1.9.0: /orc-mini joins. It always consulted the wiki; it now selects PAGE
+    // PATHS for its slices instead of reading page bodies into its own context,
+    // and the tier this command computes is what that selection rests on.
+    lanes: ["orc", "orc-boundary", "orc-brainstorm", "orc-fast", "orc-grill", "orc-mini", "orc-poly", "orc-quick", "orc-route", "orc-wiki"],
   },
   "pattern-status": {
     cmd: "orc pattern status <lang>",
@@ -3423,11 +3429,11 @@ const LANE_CALLS = {
     exits: { 0: "answered \u2014 ALWAYS, when a graph exists", 1: "no graph index", 3: "off \u2014 `code_graph` is off" },
     states: null,
     cost: "free",
-    when: "ONCE, at the START of planning \u2014 before any Glob and before `impact`, which needs the files already chosen. Planning ONLY: DE-H gated the analyst and /orc-quick on M2 showing 3 or more answerable calls per run and it measured 0.39",
+    when: "ONCE, at the START of planning \u2014 before any Glob and before `impact`, which needs the files already chosen. Planning ONLY, and v1.9.0 widens what counts as planning rather than the rule: /orc-quick's Q1 when the request NAMES NO FILE, and /orc-mini's intake before the tiered round, are the same question asked by a lane with no planner. DE-H's 0.39 answerable calls per run measured the analyst asking it AFTER the files were known, which is the case this row still refuses",
     on_absent: "exit 1 or 3 \u2192 orient with Glob and Read exactly as before the map existed",
     canonical: "_shared/code-graph.md",
-    never: "never read RANK as importance to THIS change \u2014 it is a hint about where to look first, computed from the whole repository, and a low-ranked file that the change reaches is still a file you must read",
-    lanes: ["orc", "orc-diy"],
+    never: "never read RANK as importance to THIS change \u2014 it is a hint about where to look first, computed from the whole repository, and a low-ranked file that the change reaches is still a file you must read. Never call it a SECOND time in one run: the ranking does not move because you read it",
+    lanes: ["orc", "orc-diy", "orc-mini", "orc-quick"],
   },
   "graph-impact": {
     cmd: "orc graph impact <file…> --if-enabled [--depth N] [--json]",
@@ -3439,7 +3445,7 @@ const LANE_CALLS = {
     on_absent: "exit 3 or 4 → plan or review exactly as before; AMBIGUOUS callers are counted, never followed",
     canonical: "_shared/code-graph.md",
     never: "never treat an empty impact as proof nothing depends on the change — dynamic dispatch is invisible to the graph",
-    lanes: ["orc", "orc-diy"],
+    lanes: ["orc", "orc-diy", "orc-mini"],
   },
   // EW5 — the cheap signals. All three read what is already on disk (the index,
   // and git's own history), so all three cost zero model tokens.
@@ -3453,7 +3459,7 @@ const LANE_CALLS = {
     on_absent: "exit 1 or 3 → read the source, exactly as before the graph existed",
     canonical: "_shared/code-graph.md",
     never: "never read `no recorded gap` as proof of completeness — a file marked `full` was fully PARSED, not fully understood",
-    lanes: ["orc", "orc-diy"],
+    lanes: ["orc", "orc-diy", "orc-quick"],
   },
   "graph-changes": {
     cmd: "orc graph changes [--base <ref>] --if-enabled [--json]",
@@ -3465,7 +3471,7 @@ const LANE_CALLS = {
     on_absent: "exit 1 or 3 → review from the diff alone, exactly as before",
     canonical: "_shared/code-graph.md",
     never: "never report `risk` without the `why` beside it — a rating nobody can check is a rating nobody should act on",
-    lanes: ["orc", "orc-diy"],
+    lanes: ["orc", "orc-diy", "orc-mini", "orc-quick"],
   },
   "graph-cochange": {
     cmd: "orc graph cochange <file> --if-enabled [--json]",
@@ -3477,8 +3483,37 @@ const LANE_CALLS = {
     on_absent: "exit 4 is an ANSWER, not a miss — plan exactly as before",
     canonical: "_shared/code-graph.md",
     never: "never read a co-change as a DEPENDENCY — it says what people changed together, never what needs what",
+    // v1.9.1: mini no longer calls it. `impact --complexity` answers the same
+    // question inside the SAME process, against the same per-HEAD cache.
     lanes: ["orc", "orc-diy"],
   },
+  // v1.9.1 A2 — a USER command. `lanes: []` is the contract: nothing a lane
+  // does is made better by an audit, and a lane that ran one would pay for an
+  // answer about the PARSER in a context that is about the code.
+  "graph-audit": {
+    cmd: "orc graph audit [--top=N] --if-enabled [--json]",
+    what: "WHY the map is thin — density by language, which extractor read each one, the files the parser read as EMPTY longest first, and what their first declaration looks like",
+    exits: { 0: "answered", 1: "no index yet", 3: "off — `code_graph` is off" },
+    states: null,
+    cost: "free",
+    when: "by hand, after `orc graph status` says THIN — never in a lane",
+    on_absent: "exit 1 means there is no graph to audit; build one first",
+    canonical: "_shared/code-graph.md",
+    never: "never read an empty file as a defect — a component with no named function is a file the parser read correctly; only a shape marked `parser gap` is worth an issue",
+    lanes: [],
+  },
+  "graph-gain": {
+    cmd: "orc graph gain --run <trace name> --if-enabled [--json]",
+    what: "what the graph cost this run and what it plausibly avoided — three halves kept apart: paid (recorded) · avoided (an ESTIMATE, always a range) · measured (silent below three runs per group)",
+    exits: { 0: "a line", 1: "no ledger, or no rows yet", 3: "off" },
+    states: null,
+    cost: "free",
+    when: "ONCE, at the close of a code-writing request (quick) or after a green smoke gate (mini)",
+    on_absent: "exit 1 is an ANSWER — there is nothing to report yet, so report nothing",
+    canonical: "_shared/code-graph.md",
+    never: "never restate the line as a saving, never drop the word estimate or the range, and never let this call block or fail a run",
+    lanes: ["orc-mini", "orc-quick"],
+  },
   "graph-notes-pending": {
     cmd: "orc graph notes pending --files <a,b> [--at wave|end] --if-enabled [--json]",
     what: "which changed functions have no note for their current body — the input to one notes batch",
@@ -3489,7 +3524,11 @@ const LANE_CALLS = {
     on_absent: "exit 5 is an ANSWER — the symbols wait for a later batch and nothing is lost",
     canonical: "_shared/code-graph.md",
     never: "never paste notes into your own context — the noter pipes them to `orc graph notes apply -` and returns one line",
-    lanes: ["orc", "orc-diy", "orc-fast", "orc-mini", "orc-quick"],
+    // v1.9.0: /orc-quick and /orc-mini left this row. Neither lost the notes —
+    // both stopped making a SECOND call for them: each now runs
+    // `update --notes-pending`, which answers the update and the pending batch
+    // in one, and still dispatches the noter when the answer has rows.
+    lanes: ["orc", "orc-diy", "orc-fast"],
   },
   "gotcha-list": {
     cmd: "orc gotcha list [--archived] [--json]",
@@ -4415,10 +4454,14 @@ const LANE_OWN_PHASES = {
     { ord: 6, id: "phase-s6", file: "orc-pr-setup/SKILL.md", heading: "## Phase S6 — Emit the plan, then stop", read: "section", trace_verbs: [] },
   ],
   "orc-quick": [
-    { ord: 0, id: "q0", file: "orc-quick/SKILL.md", heading: "## Q0 — Preflight (ONE time per session, silent, nothing can stop the run)", read: "section", trace_verbs: ["GATE"] },
-    { ord: 1, id: "q1", file: "orc-quick/SKILL.md", heading: "## Q1 — LOOK (silent — no questions here)", read: "section", trace_verbs: ["GATE", "WIKI-CONSULT"] },
+    // v1.9.0 — the verbs the lane already owed, plus the graph-first look and
+    // the defect reproduction. The HEADINGS are unchanged: a `read: section`
+    // pointer names a heading byte-for-byte, and a payload test asserts each
+    // one still exists in the spine.
+    { ord: 0, id: "q0", file: "orc-quick/SKILL.md", heading: "## Q0 — Preflight (ONE time per session, silent, nothing can stop the run)", read: "section", trace_verbs: ["GATE", "GRAPH-CONSULT"] },
+    { ord: 1, id: "q1", file: "orc-quick/SKILL.md", heading: "## Q1 — LOOK (silent — no questions here)", read: "section", trace_verbs: ["GATE", "WIKI-CONSULT", "GRAPH-CONSULT", "GRAPH-MAP"] },
     { ord: 2, id: "q2", file: "orc-quick/SKILL.md", heading: "## Q2 — ASK (ONE user turn: questions + the gate together)", read: "section", trace_verbs: [] },
-    { ord: 3, id: "q3", file: "orc-quick/SKILL.md", heading: "## Q3 — DO (dispatch → build/test → write the doc → offer)", read: "section", trace_verbs: ["FINISH", "OUTCOME", "VERIFY"] },
+    { ord: 3, id: "q3", file: "orc-quick/SKILL.md", heading: "## Q3 — DO (dispatch → build/test → write the doc → offer)", read: "section", trace_verbs: ["DISPATCH", "VERIFY", "REPRO", "GRAPH-CHANGES", "GRAPH-UPDATE", "GRAPH-NOTES", "GRAPH-GAIN", "OUTCOME", "FINISH"] },
   ],
   "orc-wiki": [
     { ord: 0, id: "phase-0", file: "orc-wiki/references/phases/phase-0.md", layers: ["full"], trace_verbs: [] },
@@ -4514,6 +4557,9 @@ const PHASE_KIND = {
   combine: "look",
   // waiting on the user
   intake: "ask",
+  // v1.9.0 — /orc-quick's read-only half. It LOOKS: one question, answered
+  // with evidence, and nothing written.
+  recon: "look",
   // deciding what to do and in what order
   planning: "plan",
   "plan-handoff": "plan",
@@ -4593,7 +4639,7 @@ function railKind(row) {
 // This is a MIRROR of that hook's `roleFamily()`, and it is the one new drift
 // surface this feature adds — a golden test compares the two by source text,
 // the way the `OPUS5_BANDS` alias is asserted.
-const TRACE_FAMILIES = ["combine", "analysis", "planning", "execution", "review", "verify", "testgen", "ultra-gate"];
+const TRACE_FAMILIES = ["recon", "combine", "analysis", "planning", "execution", "review", "verify", "testgen", "ultra-gate"];
 
 // The whole object, deterministic from the registries above. `--json is not a
 // summary`: this is what the file holds and what `orc lane rails` prints.
@@ -8716,6 +8762,14 @@ function gainRowFor(sub, Q, model, operands, r, ms, forSlice) {
     paid.source = K.tok(r.source.text);
     paid.card = Math.max(0, paid.card - paid.source);
   }
+  // R1 (v1.9.1): the callers' blocks are source the same way — exactly the
+  // lines a range read of each caller would have returned.
+  const callerBlocks = Array.isArray(r.callers_source) ? r.callers_source : [];
+  if (callerBlocks.length) {
+    const t = callerBlocks.reduce((a, b) => a + K.tok(b.text || ""), 0);
+    paid.source += t;
+    paid.card = Math.max(0, paid.card - t);
+  }
   const base = { cmd: sub, targets: operands.slice(0, 5), gen, ms, paid };
 
   if (sub === "impact" || (sub === "ctx" && forSlice)) {
@@ -8747,6 +8801,7 @@ function gainRowFor(sub, Q, model, operands, r, ms, forSlice) {
     const hits = Q.nameHits(model, r.target.qname);
     const c = K.ctxSymbol(model, r.target, hits, (r.callers || []).map((x) => x.file));
     if (r.source) c.avoided = addAvoided(c.avoided, K.sourceAvoided(model, r.source.file, r.source.from, r.source.to));
+    for (const b of callerBlocks) c.avoided = addAvoided(c.avoided, K.sourceAvoided(model, b.file, b.from, b.to));
     return { ...base, ...c };
   }
   return { ...base, avoided: { low: 0, high: 0, calls_low: 0, calls_high: 0 }, basis: { files: [], grep_hits: 0 } };
@@ -8789,23 +8844,79 @@ function graphGainAppend(claudeDir, row) {
 // A thin router. The engine is `bin/graph.js`; this function resolves the
 // config (the engine never reads it) and owns the human lines. The exit code is
 // the same on the human path and the `--json` path (S7).
+// ── B1 (v1.9.1): the BRIEF answer ─────────────────────────────────────────
+// The orchestrator reads a graph answer on the main-session surface, where it
+// is re-sent on every later turn — and it prints the `card`, never the rows.
+// Measured on this tree the rows are 4 to 8 times the card. `--brief` keeps
+// every fact a lane prints and drops every row array it does not.
+//
+// Two rules, in this order:
+//   1. an array NAMED here is dropped (`calls[]` and `names[]` are strings, and
+//      they are still rows);
+//   2. any other array OF OBJECTS is dropped, unless it IS the answer
+//      (`nearest[]` and `candidates[]` on an exit-4; `cards[]` on a multi-target
+//      `ctx`, whose rows are three scalars each).
+// Every drop leaves its COUNT behind, at the level it was dropped from, except
+// where the answer already carries that count under another name.
+const GRAPH_BRIEF_DROP = new Set(["callers", "calls", "effects", "symbols", "imports", "importers", "blocks", "names", "rows", "chain", "waiting"]);
+const GRAPH_BRIEF_KEEP = new Set(["nearest", "candidates", "cards"]);
+// V2/V3 answers that ARE the answer: `complexity` and `facts` are ten rows at
+// most, and they are the whole reason the call was made. They pass through
+// whole, never walked.
+const GRAPH_BRIEF_WHOLE = new Set(["complexity", "facts"]);
+const GRAPH_BRIEF_NO_COUNT = { impact: ["callers"], map: ["files"], changes: ["symbols"] };
+
+function briefOf(sub, obj) {
+  const noCount = new Set(GRAPH_BRIEF_NO_COUNT[sub] || []);
+  const walk = (o) => {
+    const out = {};
+    const counts = {};
+    for (const [k, v] of Object.entries(o)) {
+      if (Array.isArray(v)) {
+        const rows = GRAPH_BRIEF_DROP.has(k) || (!GRAPH_BRIEF_KEEP.has(k) && v.length > 0 && v[0] !== null && typeof v[0] === "object");
+        if (!rows) out[k] = v;
+        else if (!noCount.has(k)) counts[k] = v.length;
+        continue;
+      }
+      if (k === "source" && v && typeof v === "object") {
+        const from = Number(v.from);
+        const to = Number(v.to);
+        counts.source_lines = Number.isFinite(from) && Number.isFinite(to) ? Math.max(0, to - from + 1) : 0;
+        continue;
+      }
+      out[k] = v && typeof v === "object" && !GRAPH_BRIEF_WHOLE.has(k) ? walk(v) : v;
+    }
+    if (Object.keys(counts).length) out.counts = { ...(out.counts || {}), ...counts };
+    return out;
+  };
+  return walk(obj);
+}
+
 function graphCmd() {
   const usage =
-    "Usage: orc graph status [--heal] | update [--notes-pending --files <a,b>] | gc\n" +
-    "       orc graph ctx <symbol|file[:line]>… [--source [N]] | ctx --for-slice <file…> | impact <file…> | path <from> <to>\n" +
-    "       orc graph coverage <file…> | changes [--base <ref>] | cochange <file>\n" +
+    "Usage: orc graph status [--heal] | update [--notes-pending --files <a,b>] | gc | audit [--top=N]\n" +
+    "       orc graph ctx <symbol|file[:line]>… [--source [N]] [--callers-source] | ctx --for-slice <file…> | impact <file…> | path <from> <to>\n" +
+    "       orc graph coverage <file…> | changes [--base <ref>] [--files=<a,b>] | cochange <file>\n" +
     "       orc graph map [--focus <file|name,…>] [--budget N]\n" +
     "       orc graph gain [--run <name>] [--since 7d] [--history [--limit 40]] [--measured] [--reset --yes]\n" +
     "       orc graph notes pending --files <a,b> [--cap 40] [--min 5] [--with-source] | notes apply <file|->\n" +
-    "       [--if-enabled] [--depth N] [--budget TOKENS] [--format prose|tree] [--offset N] [--json] [--dir <path>]\n" +
+    "       [--if-enabled] [--depth N] [--budget TOKENS] [--format prose|tree] [--offset N] [--json] [--brief] [--dir <path>]\n" +
+    "  --brief  with --json: the card, the line, the trace, every scalar and every count — and none of the row\n" +
+    "           arrays a lane never prints. Compact output. Without --brief, --json is unchanged.\n" +
     "  status   exit 0 FRESH · 1 NONE · 2 DRIFTED · 3 OFF  (--heal builds or updates a NONE/DRIFTED graph first)\n" +
     "  update   exit 0 done · 1 unavailable or locked · 3 off (with --if-enabled)\n" +
     "           --notes-pending adds the `notes pending` answer to the SAME call (one process, one lock)\n" +
     "  gc       exit 0 done · 1 no index or locked\n" +
+    "  audit    exit 0 answered · 1 no index · 3 off (with --if-enabled)   WHY the map is thin: density by language,\n" +
+    "           the files the parser read as EMPTY, longest first, and what their first declaration looks like\n" +
     "  ctx      exit 0 found · 1 no graph · 3 off (with --if-enabled) · 4 not found or ambiguous\n" +
     "           --source [N] appends the target's own lines (default 80, cap 200), charged to the same budget\n" +
+    "           --callers-source appends 6 lines around each CONFIDENT call site (≤ 5, never the target's own\n" +
+    "           file), charged to the same budget after everything else; symbol cards only\n" +
     "           --for-slice prints only the OUTSIDE view of each declared file — no symbol table\n" +
     "  impact   exit 0 found · 1 no graph · 3 off (with --if-enabled) · 4 none of the files is in the graph\n" +
+    "           --complexity [--risk=<class>[@<file:line>],…] adds the ONE line that says whether this change\n" +
+    "           fits one executor, with the numbers behind it — impact and co-change in ONE call\n" +
     "  path     exit 0 found · 1 no graph · 3 off (with --if-enabled) · 4 no confident path, or an unknown end\n" +
     "  map      exit 0 always when a graph exists · 1 no graph · 3 off (with --if-enabled)   the files by RANK, most\n" +
     "           connected first, each with its top symbols; --focus re-ranks the repository around those files or names\n" +
@@ -8826,6 +8937,16 @@ function graphCmd() {
   const root = repoRootOf(claudeDir);
   const sub = positionals()[1];
   const asJson = wantsJson();
+  // B1: a BARE switch, read from `args`. `flag()` reads the next word as a
+  // value, so `--brief` there would swallow the first operand.
+  let briefOn = args.includes("--brief");
+  // Every flag this release adds that carries a VALUE is written
+  // `--name=value`, for the same reason: one word, so a CLI that does not
+  // know the flag skips it whole instead of losing an operand behind it.
+  const eqFlag = (name) => {
+    const hit = args.find((a) => a.startsWith(name + "="));
+    return hit === undefined ? undefined : hit.slice(name.length + 1);
+  };
   const ovr = readOverride(claudeDir).map;
   const cfg = (k) => (Object.prototype.hasOwnProperty.call(ovr, k) ? ovr[k] : metaFor(k).def);
   const enabled = String(cfg("code_graph")) === "on";
@@ -8904,7 +9025,12 @@ function graphCmd() {
       return null;
     }
   };
-  const finish = (r, line, trace, jsonLine = true) => {
+  // B3 (v1.9.1): the ledger append moved INSIDE `finish`, because the one
+  // number the meter called EXACT — the card — was 4 to 8 times too small. The
+  // ENVELOPE is everything the answer carries beyond its card, and it can only
+  // be counted once the text that will be written exists. The append is still
+  // fail-quiet and still happens after the answer is built, never before it.
+  const finish = (r, line, trace, jsonLine = true, gainRow = null) => {
     const { exit, ...obj } = r;
     if (obj.generation === undefined) {
       const m = metaNow();
@@ -8913,7 +9039,19 @@ function graphCmd() {
         obj.gen_id = m.gen_id || null;
       }
     }
-    if (asJson) emitJson({ ...obj, ...(line && jsonLine ? { line } : {}), ...(trace ? { trace } : {}) }, exit);
+    const full = { ...obj, ...(line && jsonLine ? { line } : {}), ...(trace ? { trace } : {}) };
+    const payload = asJson && briefOn ? briefOf(sub, full) : full;
+    if (gainRow) {
+      try {
+        const K = require("./graph-gain.js");
+        const text = asJson ? (briefOn ? JSON.stringify(payload) : JSON.stringify(payload, null, 2)) : String(line || "");
+        if (gainRow.paid) gainRow.paid.envelope = Math.max(0, K.tok(text) - K.tok(obj.card || line || ""));
+        graphGainAppend(claudeDir, gainRow);
+      } catch (_) {
+        // K6: the meter is never allowed to fail the read it is measuring.
+      }
+    }
+    if (asJson) emitJson(payload, exit, briefOn);
     if (line) console.log(line);
     process.exit(exit);
   };
@@ -8936,6 +9074,32 @@ function graphCmd() {
     r.auto_update = autoUpdate;
     r.notes = String(cfg("code_graph_notes"));
     if (healed) r.healed = healed;
+    // A1 (v1.9.1): the density, and the BACKFILL for a store built before
+    // this release. A FRESH store never updates, so waiting for the next real
+    // update would leave a long-lived graph without the line forever. It runs
+    // under `--heal` only, once, and it is bounded by the same cap every heal
+    // obeys — the index did not change, so `generation` and `gen_id` do not.
+    const SIGD = require("./graph-signals.js");
+    let meta = metaNow();
+    if (flag("--heal") === true && enabled && meta && !meta.density && r.exists) {
+      const capMs = Number(cfg("code_graph_heal_ms")) || 0;
+      if (!capMs || !meta.update_ms || meta.update_ms <= capMs) {
+        try {
+          const p = G.graphPaths(claudeDir);
+          const idx = JSON.parse(fs.readFileSync(p.index, "utf8"));
+          const fl = JSON.parse(fs.readFileSync(p.files, "utf8"));
+          meta.density = G.densityOf(idx, fl);
+          G.atomicWrite(p.meta, JSON.stringify(meta, null, 2) + "\n");
+          r.density_backfilled = true;
+        } catch (_) {
+          meta = metaNow();
+        }
+      }
+    }
+    if (meta && meta.density) {
+      r.density = meta.density;
+      r.thin = SIGD.isThin(meta.density, r.files);
+    }
     const b = r.behind || {};
     const lines = {
       off: "graph: off",
@@ -8949,6 +9113,12 @@ function graphCmd() {
     };
     let line = lines[r.state];
     let consult = r.state;
+    // The density rides on the line a lane already prints, never on a line of
+    // its own: a second line is a second thing to skip.
+    const densityText = r.density
+      ? ` · ${r.density.symbols_per_file} symbols/file` +
+        (r.thin ? ` · THIN (${Math.round(r.density.zero_share * 100)} % of files have no symbol) — run: orc graph audit` : "")
+      : "";
     if (healed && healed.parsed !== undefined) {
       const moved = healed.added + healed.changed + healed.deleted;
       const size = `${plural(r.files, "file")} · ${plural(r.symbols, "symbol")}`;
@@ -8960,7 +9130,15 @@ function graphCmd() {
             ? `graph: index upgraded to the new engine → updated (${healed.ms} ms) — ${size}`
             : `graph: ${plural(moved, "file")} changed outside ORC → updated (${healed.ms} ms) — ${size}`;
     } else if (healed) line += ` · could not heal: ${healed.reason}`;
-    return finish(r, line, consult === "off" ? "GRAPH-CONSULT off" : `GRAPH-CONSULT ${consult} :: files=${r.files} symbols=${r.symbols} gen=${r.generation}`);
+    if (densityText && ["fresh", "drifted", "built", "updated"].includes(consult)) line += densityText;
+    return finish(
+      r,
+      line,
+      consult === "off"
+        ? "GRAPH-CONSULT off"
+        : `GRAPH-CONSULT ${consult} :: files=${r.files} symbols=${r.symbols} gen=${r.generation}` +
+          (r.density ? ` density=${r.density.symbols_per_file}${r.thin ? " thin=1" : ""}` : "")
+    );
   }
 
   if (sub === "update") {
@@ -9124,8 +9302,11 @@ function graphCmd() {
     const SIG = require("./graph-signals.js");
     if (sub === "changes") {
       const base = typeof flag("--base") === "string" ? flag("--base") : null;
+      // V1: the lane hands the files it just wrote, and the rows for every
+      // other file never leave this process.
+      const onlyFiles = String(eqFlag("--files") || "").split(",").map((x) => x.trim()).filter(Boolean);
       const healed = healOnRead(SIG.changedPaths(root, base));
-      const r = SIG.graphChanges(claudeDir, root, { base });
+      const r = SIG.graphChanges(claudeDir, root, { base, files: onlyFiles });
       if (healed) r.healed = healed;
       if (r.exit !== 0) return finish(r, r.reason === "no-index" ? "graph: none — no index yet (run: orc graph update)" : `graph: unavailable — ${r.reason}`);
       const c = r.counts;
@@ -9137,6 +9318,7 @@ function graphCmd() {
         : `graph changes vs ${r.base} — no indexed symbol was touched${r.not_in_graph.length ? ` (changed, but not in the graph: ${r.not_in_graph.join(", ")})` : ""}`;
       // K1/K2: `changes` avoids one Grep per touched symbol. The diff itself
       // is NOT counted — the reviewer reads it either way.
+      let gainRow = null;
       if (r.symbols.length) {
         try {
           const K = require("./graph-gain.js");
@@ -9145,11 +9327,11 @@ function graphCmd() {
           if (m) {
             const hits = r.symbols.reduce((a, x) => a + Q.nameHits(m, x.qname), 0);
             const callerFiles = r.symbols.flatMap((x) => (x.callers || []).map((cc) => cc.file || cc));
-            graphGainAppend(claudeDir, { cmd: "changes", targets: [r.base], gen: r.generation, ms: r.ms || 0, paid: { card: K.tok(line), source: 0, hints: 0 }, ...K.changesCost(m, r.symbols.length, hits, callerFiles) });
+            gainRow = { cmd: "changes", targets: [r.base], gen: r.generation, ms: r.ms || 0, paid: { card: K.tok(line), source: 0, hints: 0 }, ...K.changesCost(m, r.symbols.length, hits, callerFiles) };
           }
         } catch (_) {}
       }
-      return finish(r, line, `GRAPH-CHANGES ${r.symbols.length ? "found" : "none"} :: symbols=${r.symbols.length} high=${c.high} medium=${c.medium} low=${c.low} gen=${r.generation}`);
+      return finish(r, line, `GRAPH-CHANGES ${r.symbols.length ? "found" : "none"} :: symbols=${r.symbols.length} high=${c.high} medium=${c.medium} low=${c.low} gen=${r.generation}`, true, gainRow);
     }
     const file = plain[2];
     if (!file) return finish({ ok: false, reason: "missing-operand", usage, exit: 1 }, usage);
@@ -9164,6 +9346,18 @@ function graphCmd() {
     return finish(r, line, `GRAPH-COCHANGE ${r.rows.length ? "found" : "none"} :: rows=${r.rows.length} commits=${r.commits}`);
   }
 
+  // A2 (v1.9.1) — `orc graph audit`. A THIN line says the map is thin; this
+  // says WHY, and it is a USER command: no lane runs it (`LANE_CALLS` pins
+  // `lanes: []`). It reads the index, the file table and the first lines of
+  // each empty file. It never parses, never writes, and costs no model tokens.
+  if (sub === "audit") {
+    if (!enabled && flag("--if-enabled") === true) return finish({ ok: true, enabled: false, state: "off", exit: 3 }, "graph: off");
+    const A = require("./graph-audit.js");
+    const r = A.audit(claudeDir, root, { top: eqFlag("--top") });
+    if (r.exit === 1) return finish(r, "graph: none — no index yet (run: orc graph update)");
+    return finish(r, r.line, r.trace, false);
+  }
+
   if (sub === "gc") {
     const r = G.graphGc(claudeDir);
     const line =
@@ -9263,16 +9457,21 @@ function graphCmd() {
     if (flag("--history") !== undefined) {
       const r = K.history(claudeDir, { limit: flag("--limit") });
       if (!r.ok) return finish(r, "graph gain: no calls recorded yet");
+      // `--history` IS its rows. Dropping them would leave an answer with
+      // nothing in it, so the switch is refused here — out loud.
+      const briefAsked = briefOn;
+      briefOn = false;
       const line =
         `graph gain — last ${r.rows.length} of ${r.total} call(s), newest first\n` +
         r.rows
           .map(
             (x) =>
               `  ${x.at}  ${String(x.cmd).padEnd(10)} ${String((x.targets || []).join(",")).slice(0, 40).padEnd(40)}` +
-              ` paid ${String(x.paid.card + x.paid.source + x.paid.hints).padStart(6)}  avoided ~${rng(x.avoided.low, x.avoided.high)}`
+              ` paid ${String(x.paid.card + x.paid.source + x.paid.hints + (x.paid.envelope || 0)).padStart(6)}  avoided ~${rng(x.avoided.low, x.avoided.high)}`
           )
           .join("\n") +
-        "\n  `avoided` is an ESTIMATE of retrieval the ladder would have paid for — never a bill";
+        "\n  `avoided` is an ESTIMATE of retrieval the ladder would have paid for — never a bill" +
+        (briefAsked ? " (--brief ignored on --history)" : "");
       return finish(r, line);
     }
 
@@ -9292,11 +9491,21 @@ function graphCmd() {
     const scope = r.run ? `run ${r.run}` : r.since ? `last ${r.since}` : "this project";
     const line =
       U.header(`graph gain — ${scope} · ${plural(r.calls_recorded, "call")} · ${plural(r.runs, "run")}${g ? ` · gen ${g[0]}${g[1] !== g[0] ? `–${g[1]}` : ""}` : ""}`) +
-      `\n  paid       ${kTok(r.paid.total).padStart(10)} tokens   (cards ${kTok(r.paid.card)} · source ${kTok(r.paid.source)} · hints ${kTok(r.paid.hints)})` +
+      `\n  paid       ${kTok(r.paid.total).padStart(10)} tokens   (cards ${kTok(r.paid.card)} · source ${kTok(r.paid.source)} · hints ${kTok(r.paid.hints)} · envelope ${kTok(r.paid.envelope)})` +
       `\n  avoided    ~${rng(r.avoided.low, r.avoided.high)} tokens   (estimate — the read ladder done well … done badly)` +
       `\n  net        ~${rng(r.net.low, r.net.high)} tokens · ~${r.calls.low} – ${r.calls.high} tool calls` +
       (byCmd ? `\n  by command ${byCmd}` : "") +
       `\n  hints      ${r.hints.injected} injected · ${r.hints.read_notes} read notes · ${r.hints.updates} hook updates` +
+      // R2 (v1.9.1): the reads the `on,read` hint would have named ranges for.
+      // A COUNT, printed only when there is one — it is the data DE-8 waits
+      // for, and nothing changes a setting because of it.
+      (r.hints.wide_unhinted
+        ? `\n  wide reads   ${r.hints.wide_unhinted} whole-file reads of files with ${require("./graph-resolve.js").WIDE_MIN}+ symbols were not hinted — \`code_graph_hooks: on,read\` names their ranges`
+        : "") +
+      // M2: a read nobody made is a fact about this project, printed with no
+      // advice after it. The graph is not wrong for holding an answer nobody
+      // asked for, and the meter does not tell anyone to start asking.
+      (r.never_called && r.never_called.length ? `\n  never called  ${r.never_called.join(" · ")}` : "") +
       (r.unsized ? `
   ${plural(r.unsized, "row")} answered from SHARDS, where the size of the search replaced cannot be known — their estimate leaves it out` : "") +
       "\n  an estimate of avoided RETRIEVAL, never a bill — searches are a fraction of a percent of a session" +
@@ -9339,8 +9548,8 @@ function graphCmd() {
     // gets it too. Appending it here would have shown it only to a human.
     const line = r.card;
     const trace = `GRAPH-MAP ${focus.length ? "focused" : "repo"} :: files=${r.shown}/${r.total_files}${focus.length ? ` focus=${r.focus.join(",")}` : ""} gen=${r.generation}`;
-    if (r.exit === 0) graphGainAppend(claudeDir, gainRowFor("map", Q, model, focus, r, Date.now() - t0, false));
-    return finish(r, line, trace, false);
+    const gainRow = r.exit === 0 ? gainRowFor("map", Q, model, focus, r, Date.now() - t0, false) : null;
+    return finish(r, line, trace, false, gainRow);
   }
 
   if (sub === "ctx" || sub === "impact" || sub === "path") {
@@ -9365,6 +9574,8 @@ function graphCmd() {
     // D2 is a SWITCH, so it is read from `args` — `flag()` would read the first
     // declared file as its value.
     const forSlice = args.includes("--for-slice");
+    // R1 (v1.9.1): a SWITCH too — six lines around each confident call site.
+    const callersSource = args.includes("--callers-source");
     // `path` names two symbols, not files, so it has nothing cheap to check —
     // it reads whatever generation is on disk, like every other command did
     // before EW3.
@@ -9385,7 +9596,7 @@ function graphCmd() {
     let fast = null;
     if (sub === "ctx" && !forSlice && operands.length === 1) {
       try {
-        fast = require("./graph-shard.js").fastModel(claudeDir, root, operands[0]);
+        fast = require("./graph-shard.js").fastModel(claudeDir, root, operands[0], { callersSource });
       } catch (_) {
         fast = null;
       }
@@ -9413,6 +9624,7 @@ function graphCmd() {
       format: String(flag("--format") || "prose") === "tree" ? "tree" : "prose",
       offset: flag("--offset"),
       source: sourceLines,
+      callersSource,
       wikiDocsFor,
     };
     let r;
@@ -9472,11 +9684,22 @@ function graphCmd() {
     } else if (sub === "impact") {
       if (!operands.length) return finish({ ok: false, reason: "missing-operand", usage, exit: 1 }, usage);
       r = Q.impact(model, operands, opts);
+      // V2/V3 (v1.9.1): the complexity read, and the `graph_facts` the
+      // planner pastes — computed here, in ONE process, from the model this
+      // call already loaded. Mini used to run `impact` plus one `cochange`
+      // per declared file and count the rows in its own context.
+      if (args.includes("--complexity") && r.exit === 0) {
+        const SIG = require("./graph-signals.js");
+        const cx = SIG.complexityOf(claudeDir, root, model, r.files, { risk: eqFlag("--risk"), tests: r.tests });
+        r.complexity = { verdict: cx.verdict, why: cx.why, numbers: cx.numbers, line: cx.line, thresholds: cx.thresholds };
+        r.facts = cx.facts;
+      }
     } else {
       if (operands.length < 2) return finish({ ok: false, reason: "missing-operand", usage, exit: 1 }, usage);
       r = Q.pathBetween(model, operands[0], operands[1]);
     }
     let line = r.card;
+    if (line && r.complexity) line = `${line}\n  ${r.complexity.line}`;
     if (!line && r.state === "not-found") {
       const near = (r.nearest || []).map((s) => `${s.qname} (${s.file}:${s.lines[0]})`);
       line = r.missing
@@ -9500,21 +9723,26 @@ ${line || ""}`;
 ` +
         (line || "");
     }
+    const cx = r.complexity || null;
     const trace =
-      sub === "ctx" && r.exit === 0
+      cx
+        ? `GRAPH-COMPLEXITY ${cx.verdict} :: files=${cx.numbers.files} callers=${cx.numbers.callers_outside} caller_files=${cx.numbers.caller_files_outside}` +
+          ` maybe=${cx.numbers.maybe} tests=${cx.numbers.tests_reaching} risk=${cx.numbers.risk.length} cochange=${cx.numbers.cochange_missing.length} gen=${r.generation || (r.facts && r.facts.generation) || 0}`
+        : sub === "ctx" && r.exit === 0
         ? `GRAPH-CONSULT ${r.view === "for-slice" ? "slice" : "card"} :: targets=${(r.view === "for-slice" ? r.files : r.cards ? r.cards.filter((c) => c.state === "found").map((c) => c.query) : [operands[0]]).join(",")}` +
           (healed && healed.state && healed.state !== "skipped" ? ` healed=${healed.trigger}` : "")
         : null;
+    let gainRow = null;
     if (r.exit === 0) {
       try {
-        graphGainAppend(claudeDir, gainRowFor(sub, Q, model, operands, r, Date.now() - t0, forSlice));
+        gainRow = gainRowFor(sub, Q, model, operands, r, Date.now() - t0, forSlice);
       } catch (_) {
         // K6: the meter is never allowed to fail the read it is measuring. The
         // append was already fail-quiet; the PRICING was not, because it was an
         // argument to it.
       }
     }
-    return finish(r, line, trace, !r.card);
+    return finish(r, line, trace, !r.card, gainRow);
   }
 
   if (asJson) emitJson({ ok: false, reason: "unknown-subcommand", usage }, 1);
@@ -44482,6 +44710,29 @@ function rulesLine(packs, blocks, overrides) {
 // body and PURPOSE/LOCK rules carry one line each plus the file to open when one
 // applies. That is the read-ladder discipline this repo already runs on, applied
 // to a standing card.
+// v1.9.0 - the COMPACT form, and the CLI decides it, never the lane.
+// `_shared/phases/rules.md` names `rulesSlice()` as the only lever on the
+// card's cost, so a lane that wanted a smaller card had no honest way to ask
+// for one. /orc-quick is the lane with the SMALLEST tasks under the LARGEST
+// fixed card: the full card measured 13,874 chars, re-sent on every executor
+// turn, for a task that often edits one file. Compact keeps every HARD rule's
+// ID and its first line - the instruction - and drops the worked examples,
+// which are what a rule's body is mostly made of. Nothing is hidden: the pack
+// file is named beside the rules, exactly as the light tiers already are.
+const RULES_COMPACT_LANES = new Set(["orc-quick"]);
+
+// One line out of a rule body: the first paragraph, whitespace collapsed, cut
+// at a word boundary. A rule whose instruction does not survive that is a rule
+// whose body is an example, and the pack file is one Read away.
+function rulesOneLine(body, max) {
+  const first = String(body || "").split(/\n[ \t]*\n/)[0] || "";
+  const flat = first.replace(/\s+/g, " ").trim();
+  if (flat.length <= max) return flat;
+  const cut = flat.slice(0, max);
+  const at = cut.lastIndexOf(" ");
+  return (at > max * 0.6 ? cut.slice(0, at) : cut).replace(/[ ,;:.]+$/, "") + " …";
+}
+
 function rulesSlice(claudeDir, lane, extraPacks) {
   const packs = rulesReadPacks(claudeDir);
   const led = userRulesRead(claudeDir);
@@ -44489,6 +44740,7 @@ function rulesSlice(claudeDir, lane, extraPacks) {
   const overridden = new Set(overrides.filter((o) => o.known).map((o) => o.id));
   const want = new Set([...(RULE_LANE_PACKS[lane] || []), ...(extraPacks || [])]);
   const chosen = packs.packs.filter((p) => want.has(p.id));
+  const compact = RULES_COMPACT_LANES.has(lane);
 
   const L = [];
   if (!led.empty) {
@@ -44501,19 +44753,26 @@ function rulesSlice(claudeDir, lane, extraPacks) {
   if (chosen.length) {
     L.push(
       `ORC RULES — the anti-slop baseline. Shipped with ORC, read-only. ${packs.count} rules, ${plural(chosen.length, "pack")} in this slice.`,
-      "Source: petergyang/no-ai-slop · miqdadbadjuber/anti-slop · ehmo/slopkit · BioInfo/slopless · Karpathy · Matty Cartwright. Full credits: `orc rules credits`.",
+      // The credits line is a CREDIT, not an instruction, and `orc rules
+      // credits` prints it in full. It is the one line a compact card can drop
+      // without dropping a rule.
+      ...(compact ? [] : ["Source: petergyang/no-ai-slop · miqdadbadjuber/anti-slop · ehmo/slopkit · BioInfo/slopless · Karpathy · Matty Cartwright. Full credits: `orc rules credits`."]),
       "HARD = absolute · PURPOSE = allowed with a written one-line reason · LOCK = consistency, reported never blocking.",
+      ...(compact ? ["Each line below is a rule ID and its instruction. Credits: `orc rules credits`."] : []),
       ""
     );
     for (const p of chosen) {
       L.push(`[${p.title}]`);
       for (const r of p.rules) {
         if (overridden.has(r.id)) continue; // the user replaced it
-        if (r.tier === "HARD") L.push(`${r.id} HARD · ${r.title}`, r.body, "");
+        if (r.tier === "HARD" && compact) L.push(`${r.id} HARD · ${r.title} — ${rulesOneLine(r.body, 62)}`);
+        else if (r.tier === "HARD") L.push(`${r.id} HARD · ${r.title}`, r.body, "");
         else L.push(`${r.id} ${r.tier} · ${r.title}`);
       }
       const light = p.rules.filter((r) => r.tier !== "HARD" && !overridden.has(r.id)).length;
-      if (light) L.push("", `${plural(light, "rule")} above are one-liners — open ${p.file} when one of them applies.`, "");
+      if (compact)
+        L.push("", `Every rule above is one line — open ${p.file} for the body and the worked examples of any that applies.`, "");
+      else if (light) L.push("", `${plural(light, "rule")} above are one-liners — open ${p.file} when one of them applies.`, "");
     }
   }
   if (overrides.length) {
@@ -44531,6 +44790,9 @@ function rulesSlice(claudeDir, lane, extraPacks) {
   return {
     lane,
     packs: chosen.map((p) => p.id),
+    // `compact` is REPORTED, never asked for. A reader that cannot tell a short
+    // card from a stripped one cannot trust either.
+    compact,
     text: L.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\s+$/, ""),
     overrides,
     line: rulesLine(packs, led.blocks, overrides),