roam-code 13.6__tar.gz → 13.6.1__tar.gz

{roam_code-13.6/src/roam_code.egg-info → roam_code-13.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 13.6
+Version: 13.6.1
 Summary: Local codebase intelligence for AI coding agents: structural repo map, change-safety gates, MCP security receipts, and tamper-evident ChangeEvidence packets. 100% local, zero API keys, zero network egress.
 Author: Cranot
 License-Expression: Apache-2.0
@@ -218,6 +218,7 @@ spends your tokens only where it wins.
 | "explain the compiler module's architecture" | 13 → **6** | 618K → 240K | $1.85 → $1.01 |
 | "trace how a command becomes an MCP tool" | 12 → **8** | 464K → 303K | $1.25 → $1.01 |
 | security-hook comprehension (hard, multi-file) | 6 → **2** | 267K → 117K | $1.15 → $0.56 |
+| "what are the biggest cycles in this codebase?" (re-measured 06-11) | 6 → **1** | — | $0.65 → **$0.07** |
 | "where is the CLI entry point?" (trivial, re-measured 06-11) | 1 → 1 | 48K → 50K | $0.21 → $0.22 |
 | "write a pytest for X" (generation, re-measured 06-11) | 5 → 7 | 275K → 396K | $0.61 → **$0.45** |
 
@@ -238,14 +239,75 @@ passing — no LLM judging): 20 cells of planted bugs with real tracebacks —
 source around the cited `path:line`, so the typical fix lands within 2
 turns.
 
-**Routing, replayed on 723 real prompts** from live agent sessions: **53%
-route at L1** — the envelope already contains the literal answer — at
-**p50 92 ms / p95 305 ms** compile latency, fully local.
+**Routing, replayed on 723 real prompts** from live agent sessions: **91%
+of envelopes ship pre-executed answers** (L1 probes) — the envelope already
+contains the literal answer — at **p50 0.45 s cold / p50 92 ms live**
+(warm cache) compile latency, fully local. Zero model calls.
+
+**Eval history by version** — re-measured on every kernel change; losses are
+published, attacked, then re-measured (full per-cell history in the repo):
+
+| measured | kernel | what | result |
+|---|---|---|---|
+| Jun 09 | v13.4 | 41-cell nav/comprehension A/B | turns −83%, tokens −80%, cost −63% |
+| Jun 09 | v13.4 | 20-cell ground-truth bugbench | 10/10 both arms, cost −13% |
+| Jun 09 | v13.4 | trivial-prompt cell | **+80% cost — published loss** |
+| Jun 09 | v13.4 | generation cell | **+17% cost — published loss** |
+| Jun 11 | v13.6 | trivial-prompt cell, re-measured n=3 | tie ($0.21 → $0.22) |
+| Jun 11 | v13.6 | generation cell, re-measured n=3 | **−26% cost win** |
+| Jun 11 | v13.6 | "biggest cycles" cell, re-measured n=3 | **−89% cost win** ($0.65 → $0.07, 6→1 turns) |
+| Jun 11 | v13.6 | 723-prompt routing replay | 91% L1, p50 0.45 s cold |
 
 Caveats that always ship with these numbers: trivial prompts the agent
 one-shots anyway gain nothing (now a within-noise tie after the lean/skip
-levers); cells are n=2–3 with medians and ranges. Full run history under
-[Performance](#performance).
+levers); cells are n=2–3 with medians and ranges.
+
+<details>
+<summary><strong>Benchmark archaeology — runs #1–#4 (May 2026), including the honest negative result that drove the fixes</strong></summary>
+
+Two independent A/B runs at different scales — the larger sample inverts the smaller. Reporting both honestly.
+
+**Run #1 (n=3 per cell, 27 cells, $16.88):** compile appeared to dominate (−29% wall vs static). That static prompt included a `"Hard cap: 4 tool calls"` line that turned out to act as a quota.
+
+**Run #2 (n=3–7 per cell, 78 cells, $54.88, "Hard cap" line removed from static):**
+
+| Condition | Mean turns | Mean wall | Mean cost |
+|---|---|---|---|
+| vanilla | 7.0 | 33.2s | $0.68 |
+| **static / roam_agent** | **5.8** | **25.1s** | **$0.66** |
+| compile | 8.2 | 47.9s | $0.78 |
+
+At scale, **static (with the "Hard cap" line removed) is the winner**: −17% turns and −24% wall vs vanilla, with cost within 3%. The compile-mode envelope was **+91% wall vs static on hard structural tasks** — variance probe revealed compile occasionally pushes the agent into over-tool-use (one t1 run hit 41 turns and $2.43). The compile-the-COMMAND itself is robust (250/250 latency cells, 14/15 fuzz, brief mode <300 chars across all 10 procedure families) — the issue is over-direction of the consuming agent, not the compiler.
+
+Private raw cells are retained for audit; the public summary above is the quotable result.
+
+**Run #3 (2026-05-31, n=1, 24 cells, $12.78, on 8-task user-shape corpus after W34→W37 fixes):**
+
+| Condition | Mean turns | Mean wall | Mean cost |
+|---|---|---|---|
+| vanilla | 6.00 | 28.6s | $0.58 (1 cell timed out at 240s) |
+| static / roam_agent | 5.38 | 39.9s | $0.63 |
+| **compile** | **2.75** | 35.6s | **$0.46** |
+
+This run inverts Run #2 on a different corpus. Compile **wins 7/8 shapes** including stack-trace, "what does X do", "what changed recently", `compare files`, `who calls X`, file coupling, and trace-flow. The compiler fix wave between Run #2 and Run #3 added six new probes (stack-trace source slice, body-embed for explain, git-log for history, sibling-test embed, path-comparison diff, symbol-pickaxe) and four real bug fixes (callers-backtick fallback, dead-code wrong CLI, consumer-dict flattening, stack-trace classifier missing PascalCase Errors). Headline win: a "what files are coupled to X" task that took vanilla 20 turns / $1.20 / 64s collapsed to compile's 1 turn / $0.32 / 11s — embedded coupling pairs eliminate 19 turns of exploration. The +24% wall vs vanilla is the envelope cache-creation tax at n=1; expected to amortize at n≥3.
+
+Static remains a non-improvement (0/8 wins vs vanilla, 1/8 marginal vs compile). Caveat: Run #3 is n=1 per cell; n=3 replication ($30-40) is pending.
+
+Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
+
+**Run #4 (2026-05-31, n=1, 24 cells, $13.00, same corpus after W43→W45 polish/improvements/corrections):**
+
+| Condition | Mean turns | Mean wall | Mean cost |
+|---|---|---|---|
+| vanilla | 5.25 | 39.6s | $0.63 |
+| static / roam_agent | 4.75 | 32.8s | $0.61 |
+| **compile** | **1.88** | **25.2s** | **$0.40** |
+
+Compile now **wins 8/8 shapes** and the +24% wall penalty from Run #3 is **gone**: compile is −36% wall vs vanilla. Aggregate **−64% turns / −36% cost / −36% wall** vs vanilla on Opus 4.7. The flip came from three wave-43-to-45 changes: (a) a 60-second bounded cache on `_run_roam` subprocess calls, (b) anti-Read directives in the `stack_trace_fix` and `synthesis_query` answer contracts, and (c) richer enrichment in the `write_pytest` probe (sibling test + source under test + nearest `conftest.py` together). The biggest single delta: `write_pytest` went from 10 vanilla turns to 6 compile turns (−40%, saving $0.29 / cell). Static remains 0/8 wins and should be retired from the default bench-compile conditions in a future release.
+
+Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
+
+</details>
 </details>
 
 Headless for scripts and CI: `roam compile "<task>" --artifact auto`.
@@ -256,27 +318,64 @@ Prefer a dedicated product CLI? The same loop ships as
 ### The verify half of the loop — what runs after every edit
 
 The compile half front-loads facts; the verify half reviews what the agent
-just changed. `roam verify --auto` scopes to the touched files and runs:
+just changed. `roam verify --auto` scopes to the touched files, auto-selects
+the checks that make sense for what changed (Python edits unlock the Python
+checks, source edits unlock naming/duplicates), and runs:
 
 - **naming** — against the codebase's own per-language convention (sampled
   from production code only: test/vendored/generated files neither vote nor
   get flagged, framework lifecycle names like `setUp` are never touched)
-- **imports** — the hallucination firewall: every import must resolve to an
-  indexed symbol
+- **imports** — the hallucination firewall: every import must resolve — to
+  the index, the stdlib, or a declared dependency. A module path that
+  resolves to nothing fails as a likely hallucination; near-miss names get
+  fuzzy did-you-mean candidates
 - **error handling / syntax / complexity / cycles / duplicates** — scoped
   structural review with honest disclosure when any sub-check could not run
 - **secrets** — a leak gate over every touched file: credential shapes
   (cloud keys, tokens, PEM blocks) fail the check, and an optional
   repo-local `.roam-leak-patterns.py` catalogue catches the strings *your*
   project must never publish
-- **patterns** *(advisory)* — the algorithm/idiom catalog scoped to the
-  diff: N+1 query shapes, loop-invariant calls, string-concat loops, each
-  with the better approach and a fix sketch
+- **patterns** *(advisory, `--deep`)* — the algorithm/idiom catalog scoped
+  to the diff: N+1 query shapes, loop-invariant calls, string-concat loops,
+  each with the better approach and a fix sketch
+
+**The fix loop.** Wired via `roam hooks claude --write`, findings come back
+to the agent as an actionable list — *fix or suppress, then re-verify* — and
+the loop re-runs automatically until quiet (bounded rounds). Findings the
+agent disagrees with go to `.roam-suppressions.yml`, keyed by **symbol** so
+a suppression survives refactors that shift line numbers; the file is
+append-only (a suppression is never silently dropped). Everything is
+fail-open and quiet-on-pass: the loop surfaces only real findings, and a
+broken install can never block a turn.
+
+**Scoping and debt control** — the flags that make verify usable on a
+codebase with history:
+
+```bash
+roam verify --auto                      # changed files, auto-selected checks
+roam verify --diff-only                 # only lines you changed vs HEAD
+roam verify --changed-lines cli.py:40-90   # exact ranges (agent harnesses)
+roam verify --baseline-write            # snapshot current findings as accepted debt
+roam verify --new-only                  # then: only NEW findings fail
+roam verify --report --severity fail    # whole-repo ranked punch-list (non-gating)
+roam verify --off / --on               # pause / resume the loop repo-wide
+```
 
-Findings the agent disagrees with go to `.roam-suppressions.yml` — keyed by
-**symbol**, so a suppression survives refactors that shift line numbers.
-Everything is fail-open and quiet-on-pass: the loop surfaces only real
-findings, and a broken install can never block a turn.
+**The commands that run beside it** in the same post-edit stance:
+
+| Command | Role in the loop |
+|---|---|
+| `roam verify-imports <file>` | The hallucination firewall, standalone — validates every import resolves |
+| `roam delete-check --ci` | Gates a deletion diff on surviving references (exit 5 on BREAK-RISK) |
+| `git diff \| roam critique` | Clones-not-edited check + blast radius on the patch (exit 5 on high severity) |
+| `roam verify --report --persist` | Writes findings to the registry so the **compiler** embeds them as `known_findings` in future envelopes — debt gets fixed opportunistically |
+
+**Measured, not asserted.** The detector quality is pinned by three eval
+suites in CI: a planted-issues recall corpus (every category must catch its
+canonical positives), a clean-corpus false-positive lock (dogfooded on this
+repo: the naming rule alone dropped ~2000 FPs when test files stopped
+voting), and an adversarial suppression fuzz suite (suppressions survive
+refactors, never lose entries).
 
 ---
 
@@ -930,72 +1029,9 @@ Tier 2 languages (and `.jsonc` / `.mdx`) get basic symbol extraction via a gener
 
 After the first full index, `roam index` only re-processes changed files (mtime + SHA-256 hash). Detailed indexing benchmarks across Express / Axios / Vue / Laravel / Svelte live in [`benchmarks/`](benchmarks/).
 
-### Compiler — measured A/B (current: June 2026, Claude head-to-head)
-
-The quotable current result — 10-task corpus (3 navigation, 5 exercising the
-newest intent procedures, 2 hard comprehension/synthesis), 41 cells, n=2 per
-cell, offline structural judge, June 2026:
-
-| Condition | Turns (median) | Input tokens (median) | Cost (median) |
-|---|---|---|---|
-| vanilla | 6 | 271K | $1.30 |
-| **compile** | **1** | **53K** | **$0.48** |
-
-**−83% turns / −80% input tokens / −63% cost / −50% wall**, with the same
-shape on Opus (−86% nav turns). On a separate ground-truth-graded bug-fix
-bench (20 cells, planted bugs, failing→passing oracle) compile and vanilla
-both solved 10/10 with compile slightly cheaper — easy bugs with precise
-tracebacks don't discriminate; the compiler's bug-fix edge shows on hard
-multi-step tasks (3/3 vs 1/3, Docker-graded, 2026-06-07). Caveats ship with
-every number: trivial prompts pay a small envelope tax for no gain;
-generation-shaped tasks are neutral; Ns are 2–3 with medians and ranges.
-
-<details>
-<summary><strong>Benchmark history — how the compiler earned these numbers (runs #1–#4, May 2026)</strong></summary>
-
-Two independent A/B runs at different scales — the larger sample inverts the smaller. Reporting both honestly.
-
-**Run #1 (n=3 per cell, 27 cells, $16.88):** compile appeared to dominate (−29% wall vs static). That static prompt included a `"Hard cap: 4 tool calls"` line that turned out to act as a quota.
-
-**Run #2 (n=3–7 per cell, 78 cells, $54.88, "Hard cap" line removed from static):**
-
-| Condition | Mean turns | Mean wall | Mean cost |
-|---|---|---|---|
-| vanilla | 7.0 | 33.2s | $0.68 |
-| **static / roam_agent** | **5.8** | **25.1s** | **$0.66** |
-| compile | 8.2 | 47.9s | $0.78 |
-
-At scale, **static (with the "Hard cap" line removed) is the winner**: −17% turns and −24% wall vs vanilla, with cost within 3%. The compile-mode envelope was **+91% wall vs static on hard structural tasks** — variance probe revealed compile occasionally pushes the agent into over-tool-use (one t1 run hit 41 turns and $2.43). The compile-the-COMMAND itself is robust (250/250 latency cells, 14/15 fuzz, brief mode <300 chars across all 10 procedure families) — the issue is over-direction of the consuming agent, not the compiler.
-
-Private raw cells are retained for audit; the public summary above is the quotable result.
-
-**Run #3 (2026-05-31, n=1, 24 cells, $12.78, on 8-task user-shape corpus after W34→W37 fixes):**
-
-| Condition | Mean turns | Mean wall | Mean cost |
-|---|---|---|---|
-| vanilla | 6.00 | 28.6s | $0.58 (1 cell timed out at 240s) |
-| static / roam_agent | 5.38 | 39.9s | $0.63 |
-| **compile** | **2.75** | 35.6s | **$0.46** |
-
-This run inverts Run #2 on a different corpus. Compile **wins 7/8 shapes** including stack-trace, "what does X do", "what changed recently", `compare files`, `who calls X`, file coupling, and trace-flow. The compiler fix wave between Run #2 and Run #3 added six new probes (stack-trace source slice, body-embed for explain, git-log for history, sibling-test embed, path-comparison diff, symbol-pickaxe) and four real bug fixes (callers-backtick fallback, dead-code wrong CLI, consumer-dict flattening, stack-trace classifier missing PascalCase Errors). Headline win: a "what files are coupled to X" task that took vanilla 20 turns / $1.20 / 64s collapsed to compile's 1 turn / $0.32 / 11s — embedded coupling pairs eliminate 19 turns of exploration. The +24% wall vs vanilla is the envelope cache-creation tax at n=1; expected to amortize at n≥3.
-
-Static remains a non-improvement (0/8 wins vs vanilla, 1/8 marginal vs compile). Caveat: Run #3 is n=1 per cell; n=3 replication ($30-40) is pending.
-
-Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
-
-**Run #4 (2026-05-31, n=1, 24 cells, $13.00, same corpus after W43→W45 polish/improvements/corrections):**
-
-| Condition | Mean turns | Mean wall | Mean cost |
-|---|---|---|---|
-| vanilla | 5.25 | 39.6s | $0.63 |
-| static / roam_agent | 4.75 | 32.8s | $0.61 |
-| **compile** | **1.88** | **25.2s** | **$0.40** |
-
-Compile now **wins 8/8 shapes** and the +24% wall penalty from Run #3 is **gone**: compile is −36% wall vs vanilla. Aggregate **−64% turns / −36% cost / −36% wall** vs vanilla on Opus 4.7. The flip came from three wave-43-to-45 changes: (a) a 60-second bounded cache on `_run_roam` subprocess calls, (b) anti-Read directives in the `stack_trace_fix` and `synthesis_query` answer contracts, and (c) richer enrichment in the `write_pytest` probe (sibling test + source under test + nearest `conftest.py` together). The biggest single delta: `write_pytest` went from 10 vanilla turns to 6 compile turns (−40%, saving $0.29 / cell). Static remains 0/8 wins and should be retired from the default bench-compile conditions in a future release.
-
-Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
-
-</details>
+Compiler A/B results, the per-task gallery, routing stats, and the
+version-keyed eval history live in [The Compiler](#the-compiler--your-agents-first-token-already-knows-the-answer)
+section — one home, no duplicate numbers.
 
 ## How It Works
 

{roam_code-13.6 → roam_code-13.6.1}/README.md

@@ -152,6 +152,7 @@ spends your tokens only where it wins.
 | "explain the compiler module's architecture" | 13 → **6** | 618K → 240K | $1.85 → $1.01 |
 | "trace how a command becomes an MCP tool" | 12 → **8** | 464K → 303K | $1.25 → $1.01 |
 | security-hook comprehension (hard, multi-file) | 6 → **2** | 267K → 117K | $1.15 → $0.56 |
+| "what are the biggest cycles in this codebase?" (re-measured 06-11) | 6 → **1** | — | $0.65 → **$0.07** |
 | "where is the CLI entry point?" (trivial, re-measured 06-11) | 1 → 1 | 48K → 50K | $0.21 → $0.22 |
 | "write a pytest for X" (generation, re-measured 06-11) | 5 → 7 | 275K → 396K | $0.61 → **$0.45** |
 
@@ -172,14 +173,75 @@ passing — no LLM judging): 20 cells of planted bugs with real tracebacks —
 source around the cited `path:line`, so the typical fix lands within 2
 turns.
 
-**Routing, replayed on 723 real prompts** from live agent sessions: **53%
-route at L1** — the envelope already contains the literal answer — at
-**p50 92 ms / p95 305 ms** compile latency, fully local.
+**Routing, replayed on 723 real prompts** from live agent sessions: **91%
+of envelopes ship pre-executed answers** (L1 probes) — the envelope already
+contains the literal answer — at **p50 0.45 s cold / p50 92 ms live**
+(warm cache) compile latency, fully local. Zero model calls.
+
+**Eval history by version** — re-measured on every kernel change; losses are
+published, attacked, then re-measured (full per-cell history in the repo):
+
+| measured | kernel | what | result |
+|---|---|---|---|
+| Jun 09 | v13.4 | 41-cell nav/comprehension A/B | turns −83%, tokens −80%, cost −63% |
+| Jun 09 | v13.4 | 20-cell ground-truth bugbench | 10/10 both arms, cost −13% |
+| Jun 09 | v13.4 | trivial-prompt cell | **+80% cost — published loss** |
+| Jun 09 | v13.4 | generation cell | **+17% cost — published loss** |
+| Jun 11 | v13.6 | trivial-prompt cell, re-measured n=3 | tie ($0.21 → $0.22) |
+| Jun 11 | v13.6 | generation cell, re-measured n=3 | **−26% cost win** |
+| Jun 11 | v13.6 | "biggest cycles" cell, re-measured n=3 | **−89% cost win** ($0.65 → $0.07, 6→1 turns) |
+| Jun 11 | v13.6 | 723-prompt routing replay | 91% L1, p50 0.45 s cold |
 
 Caveats that always ship with these numbers: trivial prompts the agent
 one-shots anyway gain nothing (now a within-noise tie after the lean/skip
-levers); cells are n=2–3 with medians and ranges. Full run history under
-[Performance](#performance).
+levers); cells are n=2–3 with medians and ranges.
+
+<details>
+<summary><strong>Benchmark archaeology — runs #1–#4 (May 2026), including the honest negative result that drove the fixes</strong></summary>
+
+Two independent A/B runs at different scales — the larger sample inverts the smaller. Reporting both honestly.
+
+**Run #1 (n=3 per cell, 27 cells, $16.88):** compile appeared to dominate (−29% wall vs static). That static prompt included a `"Hard cap: 4 tool calls"` line that turned out to act as a quota.
+
+**Run #2 (n=3–7 per cell, 78 cells, $54.88, "Hard cap" line removed from static):**
+
+| Condition | Mean turns | Mean wall | Mean cost |
+|---|---|---|---|
+| vanilla | 7.0 | 33.2s | $0.68 |
+| **static / roam_agent** | **5.8** | **25.1s** | **$0.66** |
+| compile | 8.2 | 47.9s | $0.78 |
+
+At scale, **static (with the "Hard cap" line removed) is the winner**: −17% turns and −24% wall vs vanilla, with cost within 3%. The compile-mode envelope was **+91% wall vs static on hard structural tasks** — variance probe revealed compile occasionally pushes the agent into over-tool-use (one t1 run hit 41 turns and $2.43). The compile-the-COMMAND itself is robust (250/250 latency cells, 14/15 fuzz, brief mode <300 chars across all 10 procedure families) — the issue is over-direction of the consuming agent, not the compiler.
+
+Private raw cells are retained for audit; the public summary above is the quotable result.
+
+**Run #3 (2026-05-31, n=1, 24 cells, $12.78, on 8-task user-shape corpus after W34→W37 fixes):**
+
+| Condition | Mean turns | Mean wall | Mean cost |
+|---|---|---|---|
+| vanilla | 6.00 | 28.6s | $0.58 (1 cell timed out at 240s) |
+| static / roam_agent | 5.38 | 39.9s | $0.63 |
+| **compile** | **2.75** | 35.6s | **$0.46** |
+
+This run inverts Run #2 on a different corpus. Compile **wins 7/8 shapes** including stack-trace, "what does X do", "what changed recently", `compare files`, `who calls X`, file coupling, and trace-flow. The compiler fix wave between Run #2 and Run #3 added six new probes (stack-trace source slice, body-embed for explain, git-log for history, sibling-test embed, path-comparison diff, symbol-pickaxe) and four real bug fixes (callers-backtick fallback, dead-code wrong CLI, consumer-dict flattening, stack-trace classifier missing PascalCase Errors). Headline win: a "what files are coupled to X" task that took vanilla 20 turns / $1.20 / 64s collapsed to compile's 1 turn / $0.32 / 11s — embedded coupling pairs eliminate 19 turns of exploration. The +24% wall vs vanilla is the envelope cache-creation tax at n=1; expected to amortize at n≥3.
+
+Static remains a non-improvement (0/8 wins vs vanilla, 1/8 marginal vs compile). Caveat: Run #3 is n=1 per cell; n=3 replication ($30-40) is pending.
+
+Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
+
+**Run #4 (2026-05-31, n=1, 24 cells, $13.00, same corpus after W43→W45 polish/improvements/corrections):**
+
+| Condition | Mean turns | Mean wall | Mean cost |
+|---|---|---|---|
+| vanilla | 5.25 | 39.6s | $0.63 |
+| static / roam_agent | 4.75 | 32.8s | $0.61 |
+| **compile** | **1.88** | **25.2s** | **$0.40** |
+
+Compile now **wins 8/8 shapes** and the +24% wall penalty from Run #3 is **gone**: compile is −36% wall vs vanilla. Aggregate **−64% turns / −36% cost / −36% wall** vs vanilla on Opus 4.7. The flip came from three wave-43-to-45 changes: (a) a 60-second bounded cache on `_run_roam` subprocess calls, (b) anti-Read directives in the `stack_trace_fix` and `synthesis_query` answer contracts, and (c) richer enrichment in the `write_pytest` probe (sibling test + source under test + nearest `conftest.py` together). The biggest single delta: `write_pytest` went from 10 vanilla turns to 6 compile turns (−40%, saving $0.29 / cell). Static remains 0/8 wins and should be retired from the default bench-compile conditions in a future release.
+
+Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
+
+</details>
 </details>
 
 Headless for scripts and CI: `roam compile "<task>" --artifact auto`.
@@ -190,27 +252,64 @@ Prefer a dedicated product CLI? The same loop ships as
 ### The verify half of the loop — what runs after every edit
 
 The compile half front-loads facts; the verify half reviews what the agent
-just changed. `roam verify --auto` scopes to the touched files and runs:
+just changed. `roam verify --auto` scopes to the touched files, auto-selects
+the checks that make sense for what changed (Python edits unlock the Python
+checks, source edits unlock naming/duplicates), and runs:
 
 - **naming** — against the codebase's own per-language convention (sampled
   from production code only: test/vendored/generated files neither vote nor
   get flagged, framework lifecycle names like `setUp` are never touched)
-- **imports** — the hallucination firewall: every import must resolve to an
-  indexed symbol
+- **imports** — the hallucination firewall: every import must resolve — to
+  the index, the stdlib, or a declared dependency. A module path that
+  resolves to nothing fails as a likely hallucination; near-miss names get
+  fuzzy did-you-mean candidates
 - **error handling / syntax / complexity / cycles / duplicates** — scoped
   structural review with honest disclosure when any sub-check could not run
 - **secrets** — a leak gate over every touched file: credential shapes
   (cloud keys, tokens, PEM blocks) fail the check, and an optional
   repo-local `.roam-leak-patterns.py` catalogue catches the strings *your*
   project must never publish
-- **patterns** *(advisory)* — the algorithm/idiom catalog scoped to the
-  diff: N+1 query shapes, loop-invariant calls, string-concat loops, each
-  with the better approach and a fix sketch
+- **patterns** *(advisory, `--deep`)* — the algorithm/idiom catalog scoped
+  to the diff: N+1 query shapes, loop-invariant calls, string-concat loops,
+  each with the better approach and a fix sketch
+
+**The fix loop.** Wired via `roam hooks claude --write`, findings come back
+to the agent as an actionable list — *fix or suppress, then re-verify* — and
+the loop re-runs automatically until quiet (bounded rounds). Findings the
+agent disagrees with go to `.roam-suppressions.yml`, keyed by **symbol** so
+a suppression survives refactors that shift line numbers; the file is
+append-only (a suppression is never silently dropped). Everything is
+fail-open and quiet-on-pass: the loop surfaces only real findings, and a
+broken install can never block a turn.
+
+**Scoping and debt control** — the flags that make verify usable on a
+codebase with history:
+
+```bash
+roam verify --auto                      # changed files, auto-selected checks
+roam verify --diff-only                 # only lines you changed vs HEAD
+roam verify --changed-lines cli.py:40-90   # exact ranges (agent harnesses)
+roam verify --baseline-write            # snapshot current findings as accepted debt
+roam verify --new-only                  # then: only NEW findings fail
+roam verify --report --severity fail    # whole-repo ranked punch-list (non-gating)
+roam verify --off / --on               # pause / resume the loop repo-wide
+```
 
-Findings the agent disagrees with go to `.roam-suppressions.yml` — keyed by
-**symbol**, so a suppression survives refactors that shift line numbers.
-Everything is fail-open and quiet-on-pass: the loop surfaces only real
-findings, and a broken install can never block a turn.
+**The commands that run beside it** in the same post-edit stance:
+
+| Command | Role in the loop |
+|---|---|
+| `roam verify-imports <file>` | The hallucination firewall, standalone — validates every import resolves |
+| `roam delete-check --ci` | Gates a deletion diff on surviving references (exit 5 on BREAK-RISK) |
+| `git diff \| roam critique` | Clones-not-edited check + blast radius on the patch (exit 5 on high severity) |
+| `roam verify --report --persist` | Writes findings to the registry so the **compiler** embeds them as `known_findings` in future envelopes — debt gets fixed opportunistically |
+
+**Measured, not asserted.** The detector quality is pinned by three eval
+suites in CI: a planted-issues recall corpus (every category must catch its
+canonical positives), a clean-corpus false-positive lock (dogfooded on this
+repo: the naming rule alone dropped ~2000 FPs when test files stopped
+voting), and an adversarial suppression fuzz suite (suppressions survive
+refactors, never lose entries).
 
 ---
 
@@ -864,72 +963,9 @@ Tier 2 languages (and `.jsonc` / `.mdx`) get basic symbol extraction via a gener
 
 After the first full index, `roam index` only re-processes changed files (mtime + SHA-256 hash). Detailed indexing benchmarks across Express / Axios / Vue / Laravel / Svelte live in [`benchmarks/`](benchmarks/).
 
-### Compiler — measured A/B (current: June 2026, Claude head-to-head)
-
-The quotable current result — 10-task corpus (3 navigation, 5 exercising the
-newest intent procedures, 2 hard comprehension/synthesis), 41 cells, n=2 per
-cell, offline structural judge, June 2026:
-
-| Condition | Turns (median) | Input tokens (median) | Cost (median) |
-|---|---|---|---|
-| vanilla | 6 | 271K | $1.30 |
-| **compile** | **1** | **53K** | **$0.48** |
-
-**−83% turns / −80% input tokens / −63% cost / −50% wall**, with the same
-shape on Opus (−86% nav turns). On a separate ground-truth-graded bug-fix
-bench (20 cells, planted bugs, failing→passing oracle) compile and vanilla
-both solved 10/10 with compile slightly cheaper — easy bugs with precise
-tracebacks don't discriminate; the compiler's bug-fix edge shows on hard
-multi-step tasks (3/3 vs 1/3, Docker-graded, 2026-06-07). Caveats ship with
-every number: trivial prompts pay a small envelope tax for no gain;
-generation-shaped tasks are neutral; Ns are 2–3 with medians and ranges.
-
-<details>
-<summary><strong>Benchmark history — how the compiler earned these numbers (runs #1–#4, May 2026)</strong></summary>
-
-Two independent A/B runs at different scales — the larger sample inverts the smaller. Reporting both honestly.
-
-**Run #1 (n=3 per cell, 27 cells, $16.88):** compile appeared to dominate (−29% wall vs static). That static prompt included a `"Hard cap: 4 tool calls"` line that turned out to act as a quota.
-
-**Run #2 (n=3–7 per cell, 78 cells, $54.88, "Hard cap" line removed from static):**
-
-| Condition | Mean turns | Mean wall | Mean cost |
-|---|---|---|---|
-| vanilla | 7.0 | 33.2s | $0.68 |
-| **static / roam_agent** | **5.8** | **25.1s** | **$0.66** |
-| compile | 8.2 | 47.9s | $0.78 |
-
-At scale, **static (with the "Hard cap" line removed) is the winner**: −17% turns and −24% wall vs vanilla, with cost within 3%. The compile-mode envelope was **+91% wall vs static on hard structural tasks** — variance probe revealed compile occasionally pushes the agent into over-tool-use (one t1 run hit 41 turns and $2.43). The compile-the-COMMAND itself is robust (250/250 latency cells, 14/15 fuzz, brief mode <300 chars across all 10 procedure families) — the issue is over-direction of the consuming agent, not the compiler.
-
-Private raw cells are retained for audit; the public summary above is the quotable result.
-
-**Run #3 (2026-05-31, n=1, 24 cells, $12.78, on 8-task user-shape corpus after W34→W37 fixes):**
-
-| Condition | Mean turns | Mean wall | Mean cost |
-|---|---|---|---|
-| vanilla | 6.00 | 28.6s | $0.58 (1 cell timed out at 240s) |
-| static / roam_agent | 5.38 | 39.9s | $0.63 |
-| **compile** | **2.75** | 35.6s | **$0.46** |
-
-This run inverts Run #2 on a different corpus. Compile **wins 7/8 shapes** including stack-trace, "what does X do", "what changed recently", `compare files`, `who calls X`, file coupling, and trace-flow. The compiler fix wave between Run #2 and Run #3 added six new probes (stack-trace source slice, body-embed for explain, git-log for history, sibling-test embed, path-comparison diff, symbol-pickaxe) and four real bug fixes (callers-backtick fallback, dead-code wrong CLI, consumer-dict flattening, stack-trace classifier missing PascalCase Errors). Headline win: a "what files are coupled to X" task that took vanilla 20 turns / $1.20 / 64s collapsed to compile's 1 turn / $0.32 / 11s — embedded coupling pairs eliminate 19 turns of exploration. The +24% wall vs vanilla is the envelope cache-creation tax at n=1; expected to amortize at n≥3.
-
-Static remains a non-improvement (0/8 wins vs vanilla, 1/8 marginal vs compile). Caveat: Run #3 is n=1 per cell; n=3 replication ($30-40) is pending.
-
-Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
-
-**Run #4 (2026-05-31, n=1, 24 cells, $13.00, same corpus after W43→W45 polish/improvements/corrections):**
-
-| Condition | Mean turns | Mean wall | Mean cost |
-|---|---|---|---|
-| vanilla | 5.25 | 39.6s | $0.63 |
-| static / roam_agent | 4.75 | 32.8s | $0.61 |
-| **compile** | **1.88** | **25.2s** | **$0.40** |
-
-Compile now **wins 8/8 shapes** and the +24% wall penalty from Run #3 is **gone**: compile is −36% wall vs vanilla. Aggregate **−64% turns / −36% cost / −36% wall** vs vanilla on Opus 4.7. The flip came from three wave-43-to-45 changes: (a) a 60-second bounded cache on `_run_roam` subprocess calls, (b) anti-Read directives in the `stack_trace_fix` and `synthesis_query` answer contracts, and (c) richer enrichment in the `write_pytest` probe (sibling test + source under test + nearest `conftest.py` together). The biggest single delta: `write_pytest` went from 10 vanilla turns to 6 compile turns (−40%, saving $0.29 / cell). Static remains 0/8 wins and should be retired from the default bench-compile conditions in a future release.
-
-Private per-task tables and raw cells are retained for audit; the public summary above is the quotable result.
-
-</details>
+Compiler A/B results, the per-task gallery, routing stats, and the
+version-keyed eval history live in [The Compiler](#the-compiler--your-agents-first-token-already-knows-the-answer)
+section — one home, no duplicate numbers.
 
 ## How It Works
 

{roam_code-13.6 → roam_code-13.6.1}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "13.6"
+version = "13.6.1"
 description = "Local codebase intelligence for AI coding agents: structural repo map, change-safety gates, MCP security receipts, and tamper-evident ChangeEvidence packets. 100% local, zero API keys, zero network egress."
 readme = "README.md"
 requires-python = ">=3.10"

{roam_code-13.6 → roam_code-13.6.1}/src/roam/catalog/detectors.py

@@ -239,6 +239,29 @@ def list_detector_surface() -> list[dict[str, Any]]:
         # — an expected, non-error state. No lineage needed.
         pass
 
+    try:
+        from roam.catalog.js_idioms import JS_IDIOM_DETECTORS
+        from roam.catalog.versions import detector_version
+
+        for task_id, _way_id, detect_fn in JS_IDIOM_DETECTORS:
+            entries.append(
+                {
+                    "name": getattr(detect_fn, "__name__", ""),
+                    "task_id": task_id,
+                    "languages": ("javascript", "typescript"),
+                    "confidence_basis": CONFIDENCE_HEURISTIC,
+                    "query_cost": QUERY_COST_LOW,
+                    "version": detector_version(task_id),
+                    "source": "js_idioms",
+                }
+            )
+    except ImportError as exc:
+        # Optional-module guard: js_idioms absence just yields fewer surface
+        # entries — logged loud rather than silently swallowed.
+        from roam.observability import log_swallowed
+
+        log_swallowed("detectors.surface.js_idioms_import", exc)
+
     return entries
 
 
@@ -4780,6 +4803,19 @@ def _iter_registered_detectors():
         # lineage needed — expected non-error state.
         pass
 
+    # JS/TS sibling pack — same isolation rationale as python_idioms.
+    try:
+        from roam.catalog.js_idioms import JS_IDIOM_DETECTORS
+
+        for det in JS_IDIOM_DETECTORS:
+            yield det
+    except ImportError as exc:
+        # Optional-module guard: js_idioms absence just yields the built-in
+        # set — logged loud rather than silently swallowed.
+        from roam.observability import log_swallowed
+
+        log_swallowed("detectors.iter.js_idioms_import", exc)
+
     try:
         from roam.plugins import get_plugin_detectors
 
@@ -4884,6 +4920,7 @@ def run_detectors(
     # never leaks into a later unscoped run.
     scope_ids = {int(f) for f in scope_file_ids} if scope_file_ids is not None else None
     _idiom_scope_reset = None  # bound to set_idiom_scope once it's applied
+    _js_idiom_scope_reset = None  # bound to js_idioms.set_idiom_scope once applied
     _catalog_scope_applied = False
     if scope_ids is not None:
         try:
@@ -4893,6 +4930,14 @@ def run_detectors(
             _idiom_scope_reset = set_idiom_scope  # captured for the finally
         except Exception as exc:  # noqa: BLE001
             log.warning("run_detectors: could not apply idiom scope: %s", exc)
+        # The JS pack keeps its own module-global scope; apply it the same way.
+        try:
+            from roam.catalog.js_idioms import set_idiom_scope as set_js_idiom_scope
+
+            set_js_idiom_scope(scope_ids)
+            _js_idiom_scope_reset = set_js_idiom_scope  # captured for the finally
+        except Exception as exc:  # noqa: BLE001
+            log.warning("run_detectors: could not apply js idiom scope: %s", exc)
         # Resolve scope file-ids to paths so the catalog detectors' source-read
         # chokepoint (`_read_symbol_source`) can skip out-of-scope files.
         try:
@@ -5062,6 +5107,8 @@ def run_detectors(
         # that can't raise, so no guard is needed in the finally.
         if _idiom_scope_reset is not None:
             _idiom_scope_reset(None)
+        if _js_idiom_scope_reset is not None:
+            _js_idiom_scope_reset(None)
         # Reset the catalog source-read scope for the same reason.
         if _catalog_scope_applied:
             _DETECTOR_SCOPE_PATHS = None