{"slug": "ripwire-ripgrep-of-ai-context-cli-mcp-giving-coding-agents-a-map-of-any-repo", "title": "ripwire: ripgrep of AI context (CLI+MCP) giving coding agents a map of any repo", "summary": "Red Hat's Emerging Technologies group released ripwire, an open-source CLI and MCP server that generates a ranked, deterministic call graph for coding agents, aiming to replace grep-based exploration with token-budgeted answers about which symbols to touch, what breaks, and which tests to run. The tool supports 21 languages via vendored tree-sitter grammars and installs in one line, activating task-shaped skills for agents like Claude Code, Codex, Cursor, Windsurf, Gemini, opencode, and aider. On a sample repository, ripwire answered an incremental cache invalidation query in about 4.3K tokens, listing ranked symbols with risk annotations, one-hop call context, and confidence scores.", "body_md": "**ripwire is the ripgrep of AI context.** Point it at any repository and your agent gets a ranked,\ndeterministic call graph — what to touch, what it breaks, which tests to run — instead of grepping\naround and reading whole files.\n\n**Languages:** Rust · C++ · Objective-C/C++ · C · Metal · CUDA · Python · Go · Swift · TypeScript ·\nJavaScript · Java · Ruby · PHP · Lua · Bash · C# · JSON · TOML · YAML · Markdown — [twenty-one\nvendored grammars](#languages), and adding another is a vendored tree-sitter grammar plus one row in a\ndeclarative table.\n\nOne self-contained binary on your own machine, offline, installed in one line — and the same line\ninstalls *and activates* the task-shaped skills that teach your agent *when* to reach for it, not\njust how, for every agent it finds on the machine. If your\nagent can run shell commands — Claude Code, Codex, Cursor, Windsurf, Gemini, opencode, aider — it is\nset up the moment the install finishes; [the MCP server is the optional second\ninterface](#set-it-up-in-your-coding-agent). Install it and ask it something before you finish\nreading this page:\n\n```\nRIPWIRE_REPO=redhat-et/ripwire bash -c \"$(curl -fsSL https://raw.githubusercontent.com/redhat-et/ripwire/main/scripts/install.sh)\"\nripwire . --for=\"incremental cache invalidation\"\n```\n\nOne deterministic, token-budgeted answer: the relevant symbols, their callers, the change risks, and the tests that reach them. Run on this repository (2026-08-30), that second line answers in about 4.3K tokens with:\n\n- **The ranked symbols, in rank order** — the cache-header constant`kCacheMagic` first (with its doc\ncomment quoted in place and the one`next=` call that opens it), then`spanTierMemoPath` (the\ncache-path composer),`ingestCommitTree` , …`ingest` — each row with its file, line, and signature.\n- **Risk, annotated in place** — complexity, git churn (`ingest` shows 128 recent edits),\nchange amplification (touch`ingest` and 266 graph nodes feel it), purity and test coverage. The\nfragile spots are visible*before* anything touches them.\n- **One-hop call context** —`spanTierMemoPath` calls`shaKeyedCachePath` ,`headSnapRepoHex` ,`exclConfigHex` ; no second query needed to see the neighbourhood.\n- **Its own confidence** — this answer says`confidence=\"high\"` with the score margin attached; a\nflat ranking says`low` , so it reads as a starting point instead of masquerading as an answer.\n\nEvery number on this page is a measurement on a corpus we happen to have. **Yours is one we don't.**\n\nAfter you have actually used it on your own repository for a while, hand your agent\n[`prompts/improve-for-my-language.md`](/redhat-et/ripwire/blob/main/prompts/improve-for-my-language.md). It harvests that\nsession's own transcript — where ripwire answered, where it missed, where you fell back to grep —\nand every finding it produces has to cite the moment it came from: what you asked, which command\nran, what came back. Open an issue with the result.\n\nThat is worth more to this project than a bug report, because it arrives in the form the project already runs on: evidence with its provenance attached, not an impression. Several languages here are one contributor's corpus away from being measurably better, and we cannot see your code.\n\n## The actual wire format — what your agent reads (minified XML; trimmed and line-wrapped here)\n\n```\n\n \n \n incremental cache (--cache): per-file content hash + raw facts so a\n re-run re-parses ONLY …constexpr std::uint32_t kCacheMagic = …\n … \n … \n …\n … \n … \n \n \n … … \n\n```\n\n`cx=` complexity, `churn=` git edit frequency, `amp=` change amplification, `r=` rank; `` rows\ncarry the one-hop call context, caps disclosed. Every attribute is defined in the one legend at the\ntop of the real output, which also self-reports the bundle's cost — `est_tokens=\"3995\"` here.\n\n| The agent without a map | The agent with ripwire | \n|---|---|\n| greps a common word, gets hundreds of hits across dozens of files | one ranked answer — `est_tokens=\"3995\"` on this repository (re-derived 2026-09-05, the run above) | \n| reads whole files to find the symbols that matter | those symbols, with complexity, churn and test coverage inline | \n| finds the callers only if it thinks to grep for them too | callers, blast radius and the tests to run, in the same bundle | \n| pays for every line it read, right or wrong | measured at **5.0%** of what that grep-and-read pass spends (re-derived 2026-08-23) | \n\nAnd against five retrieval competitors on a held-out LocBench slice, it finds **all** gold files in\nthe top 10 on **58.3%** of instances — the best alternative lands 40.0% — while indexing in 0.31 s.\n[The full leaderboard, losses included ↓](#graph-ranked-retrieval-it-finds-the-right-files-more-often-than-the-alternatives)\n\n**Django's migration autodetector, coloured by complexity.** Thresholds are fixed, so the colour means the same thing on every repo you point it at.\n\n```\nripwire path/to/django/db/migrations --rank-by=rrf --top-k=120 --color-by=cx --html=map.html\n```\n\n| **The same graph, re-coloured by git churn.** 76% of these nodes move to a different band — structure and history disagree, and one run shows you both. | **A dashed shaft is a guess.** 31 of 183 edges here are one arm of a split the resolver could not choose between. No other tool marks which of its arrows it is unsure about. | \n\n## How to read these pictures — the five lenses, the fixed thresholds, and what the renderer refuses to draw\n\nOne self-contained HTML file (`--html[=FILE]`), no server, no CDN, no external asset. `--color-by=lang|community|cx|churn|tested` sets the initial colour; the page embeds all five and keeps a live selector, so switching lens costs no second run.\n\nRead from the figures above, which state their own rules in a sidecar saved beside each image:\n\n- **arrow points caller → callee** — the graph is directed, and the page draws it that way.\n- **`31 of 183 shafts dashed in this view = the resolver could not choose between same-name definitions and split the call over all of them`** — per*edge* , not per symbol. A symbol-level \"this function makes some ambiguous calls\" would mark every one of its edges, which would be a lie about most of them.\n- **labels: top 24 by in-view degree, one per name** — one label per distinct name, so a picture of a container class stops crowding out the functions you asked about.\n- **shapes: ● fn ■ cls ✚ var** — kind is nominal data on a nominal channel; complexity never uses shape.\n- **module outlines: `7 of 12 modules with 3+ nodes in view (cap 12; 3 dropped as too thin to read as a region; 2 dropped as enclosing mostly other modules)`** — three separate truncations, each with its own count and its own reason.\n\nThe `cx` and `churn` ramps share one five-stop scale, ordered so lightness rises with the value — it survives greyscale printing, and every adjacent pair stays separable under protanopia, deuteranopia and tritanopia. Thresholds are fixed rather than per-corpus quantiles, so a hot node cannot be manufactured by a cold repository.\n\n`churn` needs real git history: a shallow clone reports every file as one commit, and a directory with no repository says `churn unavailable` rather than drawing zeros.\n\nTen everyday moments, re-measured on this repository, 2026-08-08. Figures are ~tokens (≈ bytes/4);\nevery ratio comes from a real run, reproduced by the command in its row — raw byte counts and exact\ncommands in\n[`docs/EVALS.md` §5](/redhat-et/ripwire/blob/main/docs/EVALS.md#readme-grade-rows-re-measured-on-this-repository-2026-08-08).\n\nOrdered understand → navigate → review-the-change:\n\n| Ask it | Command | ripwire | naive read | token savings | \n|---|---|---|---|---|\n| \"Orient me in this repo\" | `ripwire .` | **~5.6K tok** | ~20K–25K tok — read `README.md` (+`docs/ARCHITECTURE.md` ) | 3.6×–4.5× | \n| \"Where is X handled?\" | `ripwire . --for=\"…\"` | **~2.1K tok** | ~4.9K–20K tok — `grep -rn src/` , then read the file it points at | 2.3×–9.3× | \n| \"What do I already know?\" | `ripwire . --recall=\"…\"` | **~15K tok** | ~445K tok — read all 119 markdown docs this repo carries | 29.2× | \n| \"Set me up for this task\" | `ripwire . --pack-task=\"…\"` | **~2.1K tok** | ~16K–80K tok — read every relevant file, whole | 7.7×–37.7× | \n| \"Show me this one function\" | `ripwire . --expand=SYM --top-k=0` | **~260–16.5K tok** body (+~5.7K for the ranked-neighborhood bundle) | ~43K–174K tok — read the whole file it lives in | 2.6×–670× | \n| \"Who calls this function?\" | `ripwire . --callers=SYM` | **~580 tok** | ~40K–52K tok — `grep -rn SYM src/` (mostly noise), then open 2–3 files to sort real calls from mentions | 69.2×–89.1× | \n| \"Is it safe to change this?\" | `ripwire . --impact=SYM` +`--uses=SYM` | **~1.3K tok** | ~18K tok — open every direct-use file, whole | 14.4× | \n| \"I have a stack trace\" | `ripwire . --from-trace=FILE` | **~1.4K tok** | ~124K–298K tok — grep all 7 frame names, then open the innermost file(s) | 86.9×–208.6× | \n| \"I changed these files — tests? blast radius?\" | `ripwire . --situ` | **~410 tok** | ~3K–132K tok — `git diff` +`grep -rn test/` , then open the candidates | 7.3×–324.2× | \n| \"Review this PR/diff\" | `ripwire . --pr-context=REF` | **~1.9K tok** | ~4.8K–51K tok — `git diff REF` , then open the touched files | 2.6×–27.5× | \n\n## Same-correct-answer verification, and the honesty line these ratios come with\n\n**These aren't summaries that gamble with information.** Each row is scored\nsame-correct-answer-or-it-doesn't-count, and both sides were checked, not assumed: orient surfaces\nthis repo's own pipeline files (`ingest.cpp`, `graph.h`, `serialize.h`) in the first screen, the same\nthree `docs/ARCHITECTURE.md` names as central; the `--for` row lands `mcpStale`\n(`src/mcpindex.h:633`), the actual staleness check, 5th-ranked; `--recall` lands the container-rule\ndoc (`AGENTS.md`) that states, verbatim, the same \"no `std::map`\" rule `CONTRIBUTING.md` explains in\nfull; `--pack-task` names the same three touch points a human would — `cachelint.h`, `mergeCachePack`\n(`src/main.cpp:1787`), the `lintrules.h` helpers it reuses; `--expand --top-k=0` hands back the\nrequested function's complete, unmodified body — the ranked-neighborhood addition costs the same\n~22.6 KB regardless of which function you ask for, confirmed on two (a fixed floor, not per-function\nvariance); `--callers` on `langOfPath` names its 2 real callers, the same ones a `grep` hit-list\nburies under 5 files of comment-only mentions; `--impact`+`--uses` on `coversOrEquals` names the same\n2 direct call sites `--uses` alone would, plus (disclosed) a transitive reach `--uses` doesn't cover\nat all; `--from-trace` resolves all 7 frames of a real call chain by name to the same definitions a\nper-frame grep would eventually find, mixed with call sites and comments; `--situ` on a 2-file diff\nnames the same 6 real test harnesses, 2 of which a filename grep across `test/` cannot find even\nafter opening every one of its 41 candidates — a completeness gap, not just a byte one; `--pr-context`\nsurfaces co-change partners (`test/regression.sh`, `src/main.cpp`) a raw `git diff` has no way to\nknow were usually touched and weren't this time. The map ranks and discloses — it never paraphrases\nyour code — and every truncation is disclosed in the header.\n\n**The honesty line, made concrete:** the same auto-selection behind the `--expand` row also runs the\nother way. On a small file (`pageRankDouble` in `src/pagerank.cpp`, 5,559 B) the ranked bundle would\ncost 27,916 B — nearly 5× more than the file — so ripwire serves the file itself instead, disclosed\nas `mode=\"whole-file\"` on the response, not silently.\n[`docs/EVALS.md` §7](/redhat-et/ripwire/blob/main/docs/EVALS.md#7-honest-counterexamples) lists that and the other counterexamples\nthis project publishes against itself.\n\n**Won 27 · lost 7 · tied 14** on 48 matched questions across django, webpack and this repository,\nspending **~77K tokens against its ~486K** for the whole sweep.\n\n## The full result, how it was measured, and where ripwire still loses\n\nThe 48 questions span symbol lookup, conceptual search, blast radius, and one-call task orientation. ripwire indexes the same three repositories in 0.25–0.45 s and 6.6–16.5 MB, against that server's 23–52 s and 391–623 MB, and answers a warm query in a median 197 ms against its 1,082 ms. Its seven wins are real and named one by one in the method.\n\nBoth arms warm with a pre-built index, median of 3 timed calls, stdout to a file rather than a pipe.\nThe competitor ran in its stronger retrieval configuration; its numbers were recorded once and then\nfrozen, and ripwire's side was re-run after the fixes the first pass produced. Per class, as a share\nof the competitor's bytes on totals: symbol lookup **1.35×**, conceptual search **1.23×**, blast\nradius **0.39×**, task orientation **0.06×**.\n\nWhere it loses: on a plain one-symbol lookup the competitor answers in about a kilobyte carrying callers and callees, and ripwire spends roughly three times that to also hand back the body. It ranks a chunk-id plugin first on one webpack query where ripwire never surfaces the directory at all — a ranking miss, and a fix for it was built, met its pre-registered band, and was reverted anyway for failing a separate standing requirement. Its depth-labelled blast radius and its import edges are both better presentations than ripwire's flat reaching-set.\n\nFull method, pins, per-class tables, the carried-versus-re-judged ledger, and the complete list of\nwhat the competitor does better:\n[`docs/EVALS.md` §2](/redhat-et/ripwire/blob/main/docs/EVALS.md#2-head-to-head-against-other-tools).\n\n**Nothing it is unsure about reaches your agent unlabelled — and nothing it could not see goes\nunnamed.** Every guess is marked in the output, and every mark has a next step — up to handing it a\ncompiler-grade index. Point it at a repository whose main language it has no grammar for and the\nmap's first line says so (`unindexed=\"ml:793,mli:607,…\"` on a facebook/infer clone); a file it\nindexed but cannot vouch for carries a parse-health row; every file the crawl passed over is\nitemized with its reason. A confident-looking map that lies by omission is the failure mode this\ntool refuses.\n[What it misses, and what to run next →](#what-it-misses-and-what-to-run-next)\n\n**58.3% against 40.0% for the best tool tested — and it answers before they finish indexing.** Every\narm below was re-run in full on 2026-08-08 — one ripwire binary (the profile-guided release build\nthat now ships), one evaluator, one 60-instance held-out LocBench slice: paired, zero exclusions,\nsame gold set, and the metric code imported unmodified into every arm. *Strict file@10 = **all** gold files inside the top 10*, which is whether\nyour agent starts in the right place at all.\n\n| Round 4 — LocBench, Python-dominant | strict file@10 | any@10 | index (median) | query (median) | \n|---|---|---|---|---|\n| **ripwire `--for`** | **58.3%** | **85.0%** | **0.31 s** | 0.108 s | \n| codebase-memory-mcp 0.9.0 | 40.0% | 63.3% | 1.24 s | 0.075 s | \n| repowise 0.37.0 | 33.3% | 53.3% | 34.0 s | 1.159 s | \n| graphify 0.9.34 | 31.7% | 46.7% | 7.82 s | 0.614 s | \n| Aider repo-map 0.86.2 | 20.0% | 35.0% | *(inside query)* | 2.920 s | \n| codeseek 0.1.31 (better of its two arms) | 15.0% | 20.0% | 3.37 s | 0.040 s | \n\nRipwire leads every arm on both accuracy metrics and in both strata. Paired, the losses are small and\nthey are published: **2** instances to codebase-memory-mcp, **2** to repowise, **1** each to graphify\nand aider. **Cold from nothing to an answer — parse, rank, reply, no cache — ripwire takes 0.213 s**,\nagainst a ~35 s index-then-query for repowise; its worst single index in this run was **352 s**.\n\nThree things this table costs us, said plainly. **codebase-memory-mcp is the real runner-up at 40.0%,\nnot repowise** — an earlier round credited it with 26.7%, and re-running it fairly raised it. The\nmargin over the best competitor is therefore **1.46×**, not the 1.75× two separately-dated tables used\nto imply. And **multi-file gold is hard for everyone**: ripwire leads the stratum at 21.4% strict, but\nits own any@10 there is 78.6% — it finds *a* gold file and misses the siblings, and no arm in this\ntable solves that.\n\nHeld out wider — **243 instances across 78 repositories** — ripwire lands **60.9%** against **27.6%**\nfor its own pre-routing baseline: **+33.3pp** paired, clustered-bootstrap 95% lower bound **+25.0pp**,\nbought for +3.4% warm latency and **−39.4%** tokens. Full provenance, the losing instances one by one,\nand a third round against a compression-layer competitor: [Measured](#measured) and\n[`bench/headtohead/r4-2026-08-06/`](/redhat-et/ripwire/blob/main/bench/headtohead/r4-2026-08-06), whose harness is committed so\nanyone can re-run the whole comparison.\n\nTest scaffolding does not pollute the ranking from inside source files either: `#[cfg(test)] mod tests`, `describe()` blocks, `Test*` classes and `[Fact]` attributes are detected syntactically,\nwherever they live — not by file path alone. On an astral-sh/ruff clone (5,945 files),\n`--ignore-tests` removes **23,907** test symbols where path rules alone caught 18,532\n(`ripwire --ignore-tests`, 2026-08-14; the per-language fixtures are pinned by\n`test/testscopecheck.sh`).\n\n*The table above, read two other ways. Every figure in both is one of its measured numbers; only the\nmanners and the cynicism are editorial.*\n\n## 📖 **The same table, as narrated by Jane Austen**\n\n*A Survey of the Neighbourhood's Eligible Instruments — being an account of five gentlemen of\nretrieval, and one lady of no pretension whatsoever.*\n\nIt is a truth universally acknowledged, that an engineer in possession of a large repository must be in want of a map.\n\n**Mrs. Codebase-Memory** must be named first, for she has risen a great deal in the estimation of the\nneighbourhood — two-fifths of her answers entirely correct, which is more than any other caller can\nsay, and she is ready in a second and a quarter. It must nevertheless be recorded that her card\nannounces accomplishments in the semantic line; that upon enquiry the semantic line is not at home;\nand that the household denies all knowledge of it. One is left with the impression of a capable woman\nill-served by whoever prints her cards.\n\n**Mr. Repowise** is by common consent the most substantial of the party, and no one who has waited\nupon him would dispute it. He is possessed of a handsome index and a manner of great thoroughness;\nbut he must be *seen to*. One does not simply address Mr. Repowise. One sends word, and dresses, and\nwaits — three-and-thirty seconds on an ordinary morning, and upon one memorable occasion in the\ncountry, seven minutes and four seconds — during which interval a less consequential neighbour has\nanswered the question, taken her leave, and thought no more about it. He answers creditably when at\nlast he arrives, one time in three; whether that is worth the toilette, each family must determine\nfor itself.\n\n**Mr. Graphify** enjoys a great many admirers. He does not rank his acquaintances; he calls upon them\nin whatever order his walk happens to take him, and reports the order of the walk as though it were\nan opinion. He has been known to arrive carrying a hundred and thirty megabytes of correspondence.\nPressed once for any answer at all, he replied that no matching nodes were found, and considered the\nmatter closed.\n\n**Mr. Aider** is the most gentlemanly of the company and by far the most difficult to consult. He\ncannot be asked a question — the thing is simply not done. One may mention names in his hearing and\nhope he takes the hint; he does take it, and is fully ten points the better for it, which says more\nabout the hint than about Mr. Aider. But he forms his view of the neighbourhood before you speak and\nretains it after, and one cannot escape the feeling that the conversation was never truly with you.\n\n**Mr. Codeseek** is a young gentleman of quick habits who suffers from an affliction of address.\nSpeak to him plainly, in the language of ordinary complaint, and he will regard you with perfect\ncomposure and say nothing whatever — nothing, upon sixty occasions out of sixty. Name a person\nprecisely as that person is named, and he grows animated directly. It is not stupidity; it is a want\nof imagination in the matter of introductions.\n\nAnd there is **ripwire**, of whom nothing is said in the drawing rooms, because she has already gone\nhome. She was asked; she answered, in thirteen hundredths of a second; every gold file within the\nfirst ten, in eight-and-fifty cases of the hundred. She keeps no establishment, corresponds with no\ndistant authority, and has never once been indexed at a party. Mr. Repowise finds her abrupt.\n\nShe is.\n\nEvery figure above is a measured number from the round-4 table on this page: the index medians\n(1.24 s, 34.0 s, 3.37 s) and repowise's 352 s worst case, the 40.0% and 33.3% strict file@10, the\n0-results-on-60/60 fallback arm, the absent `semantic_query` tool, graphify's 129 MB\nlargest graph and its 1-of-60 empty ranking, aider's +10 pp personalization delta, and ripwire's\n0.108 s / 58.3%. Provenance in [bench/headtohead/r4-2026-08-06/](/redhat-et/ripwire/blob/main/bench/headtohead/r4-2026-08-06)\nand [docs/EVALS.md](/redhat-et/ripwire/blob/main/docs/EVALS.md); only the manners are editorial. These are other\npeople's real work, and the joke is aimed at the trade-offs, never at the authors.\n\n## 🕵️ **The same table, worked as a case file** — a private eye who trusts no index he didn't build himself\n\n*The Long Index — in which a man asks six informants one simple question, and only one of them has\nthe decency to answer it.*\n\nIt was a million lines of somebody else's mistakes, and I needed one file out of it before the coffee went cold. So I did what you do. I went and talked to the people who say they know the neighborhood.\n\n**Codebase-Memory** had the best record in the room and she knew it — two answers right out of every\nfive, handed over in a second and a quarter, which in this business is practically a kindness.\nTrouble was the card. Right under her name it said *semantic query*, real classy, real\nexpensive-looking. I asked to see it. She said it wasn't in. I asked the house. The house had never\nheard of it. I've known a lot of good people ruined by whoever printed their cards.\n\n**Repowise** was the heavyweight — everybody told me so before I got through the door. Big index,\ngood tailoring, thorough as a tax man. Only you don't just ask Repowise a question. You send word.\nYou wait. Thirty-three seconds on a good day, and one bad morning out in the country, seven minutes\nand four seconds — long enough to get the same answer somewhere else, drive home, and forget his\nname. He came through one time in three. For some outfits that's worth the wait. I've got a\nmetabolism.\n\n**Graphify** never met a fact he wouldn't hand you. Ask him one thing and he turns up with a hundred\nand twenty-nine megabytes of everything, unsorted, in whatever order he tripped over it — and he'll\nreport that order like it's a considered opinion. It isn't. Leaned on him once for anything at all;\nhe looked me dead in the eye, said no matching nodes, and figured we were square.\n\n**Aider** was a gentleman, which is another way of saying you couldn't file a straight question into\nhim in triplicate. Wouldn't be asked. You mention things, loud, and hope — and sure enough, drop the\nright names and he's ten points sharper, which tells you everything about the names and nothing about\nAider. He'd made up his mind about the place before I opened mine, and kept it after. You never did\nfeel the conversation was with you.\n\n**Codeseek** was young and had a condition. Talk to him like a human being — plain, tired, the way a\nman actually asks for help — and he'll look clean through you and say nothing. Sixty times out of\nsixty, nothing. But name the thing exactly, badge number and all, and the kid lights right up. It\nisn't that he's slow. He just never learned how people knock on a door.\n\nAnd **ripwire**. Nobody at the table brought her up, on account of she'd already left. Took the\nquestion, answered it in thirteen hundredths of a second — every file I needed inside the first ten,\nfifty-eight times out of a hundred — keeps no office, wires no head branch, never once got herself\nindexed at a party. Repowise says she's abrupt.\n\nShe is. That's why I hired her.\n\nEvery figure above is a measured number from the round-4 table on this page: the index medians\n(1.24 s, 3.37 s, 34.0 s), repowise's 352 s / six-minute worst case, the 40.0% and 33.3% strict\nfile@10, codeseek's 0-of-60 plain-language arm, codebase-memory's advertised-but-absent semantic\ntool, graphify's 129 MB largest graph and its 1-in-60 empty return, aider's +10 pp name-drop delta,\nand ripwire's 0.108 s / 58.3%. Provenance in\n[bench/headtohead/r4-2026-08-06/](/redhat-et/ripwire/blob/main/bench/headtohead/r4-2026-08-06) and\n[docs/EVALS.md](/redhat-et/ripwire/blob/main/docs/EVALS.md); only the cynicism is editorial. These are other people's\nreal work, and the joke is aimed at the trade-offs, never the authors.\n\n**Name a symbol and it is the first hit — and it is never a mystery which ranker answered.** Every\n`--for` query is served by one of three lanes; a confidence-gated router picks by reading the\nquery's *shape*, discloses its choice on the output (`route=`), and `--no-route` overrides it.\nRouting lifts recall@1 on name-shaped queries **61.1% → 91.3%** in `src/`, **59.2% → 85.5%** at the\nrepository root — and the gate is load-bearing in both directions: route *everything* to the name\nlane and prose queries collapse from **0.967 MRR to 0.016**. Both numbers ship together. Reproduce\nwith `ripwire --eval-retrieval`, which grades EVERY doc-commented symbol in the corpus and\nprints its own `population=`/` scored=`/` rule=`; the full per-ranker tables are in\n[`bench/ANSWERQUALITY.md`](/redhat-et/ripwire/blob/main/bench/ANSWERQUALITY.md#re-measured-2026-09-05--census-sampler-midrank-ties-the-current-numbers).\n\n| Lane | Built for | Why it wins there | Where it loses | \n|---|---|---|---|\n| **name-exact** | identifier-shaped queries ( `chooseForRanker` ,`pack task` ) | whole-name match ignores body noise: **91.3%** recall@1,**0.960** MRR in`src/` | scores zero on any word that is not literally a name — forced onto prose it dies ( **0.016** MRR) | \n| **subtoken+body** | prose and task queries (\"where is the content hash computed\") | the only lane that matches vocabulary living in doc comments and bodies | exact names drown in shared subtokens ( **61.1%** recall@1 on name queries) | \n| **mention anchor** | a pasted path, `Type.method` , or issue URL | a literal mention is lifted above any score — paste the ticket, don't paraphrase it | adds nothing when the query names no artifact | \n\n## **How each lane finds things, and how the router picks — step by step**\n\n**How the conceptual lane finds what you didn't name.** The subtoken+body lane is why a query with\nno symbol name in it still lands:\n\n- **Both sides are split into subtokens.**`SplitChunksPlugin` becomes`split` +`chunks` +`plugin` , and\nso does your query — so words match*pieces* of names you never typed.\n- **Three evidence fields, not one.** A symbol is scored on its name subtokens, its doc comment, and\nits body — vocabulary that only exists in a comment or an implementation still finds its symbol.\n- **BM25 with per-query IDF.** Rare, discriminating words dominate the score; words the whole corpus\nshares contribute almost nothing. Type the three words only the right function uses and they carry\nthe query.\n- **Lookalikes are down-weighted, not hidden.** Fixture, test-data, and generated paths score at a\nfraction, so a test vocabulary-twin cannot outrank the real source (adversarial-class pollution@5:\n28% → 0%,`docs/EVALS.md` §4) — but they stay in the index and are still found when*asked for* .\n- **The list ends at a cliff, not a quota.** The cut is adaptive: output stops where the scores drop\noff, so a sharp answer is a short list and a diffuse one is disclosed as such, instead of a fixed\ntop-k padding both.\n\n**How the router picks.** The gate is built on cheap, corpus-derived evidence, and its bias reflects\nan asymmetry the table above makes plain: a *missed* name-route costs a few ranks; a *false* one is\ncatastrophic (0.016 MRR).\n\n1. **Identifier shape is trusted outright.** A camelCase/snake token — or a short query carrying\none — routes name-exact. Someone who types`chooseForRanker` is naming, not describing.\n2. **The all-words test.** If*every* content word equals some symbol's whole name (`pack task` where both`pack` and`task` are real symbols), that is strong evidence of a name query.\n3. **The plausibility test.** Present is not enough — each matched name must be*specific* : few\ndefinitions, and not a subtoken carried by half the corpus's symbol names (thresholds derived\nfrom the index itself, not a hardcoded stdlib list). This is what catches`split chunks` :\nevery word names a symbol, but`split` names a String method defined everywhere — so the route\nis**declined** and the conceptual lane runs, which finds`SplitChunksPlugin` easily.\n4. **Every decision is disclosed.**`route=` states the lane that ran; a decline names the anchor\nthat failed and why.`--no-route` forces the conceptual lane when you disagree.\n\nThe proof the gate earns its keep: the routed lane matches the *best* single lane on both query\nmodes simultaneously — 0.960 MRR on names (equal to forced name-exact) and 0.967 on prose (within\nnoise of pure subtoken+body, `src/`). No single lane does that.\n\nThe honest boundary: the router classifies the query's shape — it cannot rescue vocabulary that is\nnot in the index. A prose query whose concept lives only in a compound class name\n(`SplitChunksPlugin` contains no `splits` subtoken) is correctly sent to the conceptual lane, which\nthen has little to grab; that gap is measured and recorded in\n[docs/EVALS.md §7](/redhat-et/ripwire/blob/main/docs/EVALS.md), not hidden. Numbers re-derived 2026-08-08 on this tree;\nper-lane table and history in [docs/EVALS.md §4](/redhat-et/ripwire/blob/main/docs/EVALS.md).\n\nOn mid-task questions it had never seen, ripwire answers at **5.0%** of what a grep-and-read pass\nspends — **5.2%** on the questions both arms fully answered. `--pack-signatures` returns **74.7%\nfewer bytes** than full bodies at top-50 (re-derived on this tree, 2026-09-06). The output is already\ndense enough that running a dedicated context compressor over it saved **exactly 0 tokens**.\n\nBoth of those first two figures moved when they were re-derived on 2026-08-23, and they moved in\n**opposite** directions — 7.3% → 5.0% overall, but 1.7% → 5.2% on the both-answered subset. Same\nfrozen questions, same frozen verb ladders, same corpus pin, same tokenizer; the naive arm reproduced\nto the token. What changed is where ripwire spends: the compact conceptual route made its *misses*\nmuch cheaper, while richer default bundles made the questions it *answers* dearer. Both numbers are\nprinted because printing only the one that improved would be the failure this project exists to not\ncommit. The full per-question re-derivation is in the Round 3 note under [Measured](#measured).\n\nIt is also cheap enough to call on reflex: this repository parses in **~0.15 s** cold and **~0.10 s**\nwarm (`time ./build/ripwire . --no-cache`), so the agent asks instead of guessing.\n\n### Better Code: It automates the review judgments nobody has time to make — every lens from published research\n\n`--quality-panel` runs the calls a good reviewer makes by hand — is this function too tangled, is it\nnamed badly, does it hide control flow inside an idiom, does its history say it keeps breaking, must\nyou read five other files to follow it, does it mutate state three hops away — as **six independent\nevidence families**, and ranks by how many of them *agree*, never as one blended score. Each family\nimplements published work — McCabe on shape, Butler on naming, Gopstein's atoms of confusion on\nidiom, Nagappan & Ball on churn, Beck & Diehl on colocation, Henry & Kafura on state — with the\nlesson taken from each paper, and the rules measured and *withdrawn*, in\n[`docs/LINEAGE.md`](/redhat-et/ripwire/blob/main/docs/LINEAGE.md). Pooled over five corpora (n = 27,889) the largest correlation\nbetween any two families is **+0.168**: they really are measuring different things, so two families\nfiring on the same function is corroboration rather than one metric counted twice.\n\nThat matters most for code an agent wrote. Empty-catch error masking is **+47%** more common in\nAI-authored commits, a function rewritten again inside two weeks **+15%** more likely, and reuse is\n*declining* as AI's share of commits grows (GitClear, *AI Copilot Code Quality*, 2026). Each of\n`--quality-delta`'s 10 kinds targets one measured mode like those, and it reports **only what your\nchange made worse** — then `--exemplar` shows the pattern in your own repo to copy, and `--test-gate`\nnames the tests that must run before \"done.\"\n\nTree-local numbers above are reproducible with the commands shown; the rest are dated, sourced\nmeasurements in [`docs/EVALS.md`](/redhat-et/ripwire/blob/main/docs/EVALS.md) — each with its instrument, its corpus, and its\ncounterexamples, because the losses ship beside the wins. Zero runtime dependencies, C++23, builds\nwith the network off.\n\nBuilt for **Codex, Claude Code, Cursor, Windsurf, Gemini, opencode, aider**, and any agent that can\ncall a CLI.\n\n## **What comes back** — real output from this repository, pretty-printed and trimmed (re-captured 2026-09-05; rows are served in rank order, each naming its file)\n\n```\n\n \n incremental cache (--cache): per-file content hash + raw facts so a re-run re-parses ONLY c…constexpr std::uint32_t kCacheMagic = 0x4b505443\n Composed exactly the way every OTHER blob family is (quality.h): one fixed-width identity hex pe…inline std::string spanTierMemoPath( const std::string& diskPath )\n Ingest the tree at `sha`, materialized out of `root`'s object store. …inline bool ingestCommitTree( const std::string& root, const std::string& sha, … )\n P1-15 — the `_reingest` envelope field for a response whose handling ran an INCREMENTAL pass, …inline bool mcpRefreshedThisRequest( std::uint64_t passesAtEntry )\n …\n \n \n \n \n \n \n …\n \n \n\n```\n\nThe cache cluster, ranked and annotated in place: `cx`/` ccx` complexity, `in` reuse count, `churn`\nrecent commits, `amp` change amplification, `tested` coverage — the fragile spots are visible\n*before* the agent touches them, in a few thousand tokens (`est_tokens=\"3995\"`, self-reported in the\nheader) instead of five whole files. This is a *conceptual* query, so the bundle is the **compact**\nshape: the ranked map plus one-hop callee edges, no inline bodies, and the root says so rather than\nleaving you to notice. Read the map, then `--expand=SYM` the one you want — or pass `--auto-bodies`\nto get bodies inline as before.\n\n## **What the quality panel shows** — real output from this repository, trimmed (legend comment elided)\n\n``` bash\n$ ripwire . --quality-panel --limit=1\n\n\n\n\n\n\n\n…\n\n```\n\nFour of six independent evidence families corroborate on `buildGraph`, each with its own reason\nshown inline — never a single blended score. `eligible=\"6497\"` narrows to `ranked=\"524\"` (2-of-6\nagreement): an **8.1%** shortlist of this repository's own functions, not a guess (re-derived\n2026-08-23 — the corpus grew, the shortlist share did not move). Full six-family breakdown, real\nnumbers per family → [The quality panel](#the-quality-panel) below.\n\nFull retrieval tables — including the MRR figures behind the router numbers above — in\n[`bench/ANSWERQUALITY.md`](/redhat-et/ripwire/blob/main/bench/ANSWERQUALITY.md) and [Measured](#measured).\n\n[**▶ The whole tool in 29 slides**](/redhat-et/ripwire/blob/main/present/ripwire-showcase.pdf) — every figure names the instrument that pins it\n\nrenders in your browser · [pptx](/redhat-et/ripwire/blob/main/present/ripwire-showcase.pptx) beside it · [the numbers behind it](/redhat-et/ripwire/blob/main/docs/EVALS.md)\n\n[What it answers](#what-it-answers) · [Quickstart](#quickstart) ·\n[The quality panel](#the-quality-panel) · [Benchmarks](#measured) ·\n[Honesty contract](#the-honesty-contract) ·\n[Agent setup](#set-it-up-in-your-coding-agent) · [Docs](#documentation)\n\nAround the core sit 179 long flags advertised in `--help`, across seven families — plus an MCP\nserver, so a coding agent can call any of them mid-task instead of grepping and reading whole files.\nNot sure which of them fits the task in front of you? `ripwire . --help-task=\"\"`\nrecommends ONE executable command with the evidence behind the pick — advice only, it never runs\nthe recommendation — and abstains honestly when the evidence is too thin to name a winner.\n\n## Which surface is the authority — `--help` vs `docs/COMMANDS.md` — and the four reflex verbs worth memorising\n\n`./build/ripwire --help` is generated from the binary's own flag table and is always the authority;\n[`docs/COMMANDS.md`](/redhat-et/ripwire/blob/main/docs/COMMANDS.md) documents every one of the 145 documented flags — 94 of them\nwith a real invocation and its recorded output (counts re-derived 2026-08-23; `test/docscommandscheck.sh`\nfails if that documented set and the binary's own flag table ever disagree). Each family below links there.\n\nFour reflexes worth wiring into muscle memory: `--from-trace=FILE` for an error you have in hand,\n`--edit-check=SYM` right after an edit (did the contract change, and which callers are now provably\nincompatible), `--merge-scout=REF1,REF2` before landing parallel branches, and `--pack-task=\"…\"` for\nranking, bodies, callers and tests in one budgeted bundle.\n\n| Family | The question | Representative flags | \n|---|---|---|\n| [**understand a codebase cold**](/redhat-et/ripwire/blob/main/docs/COMMANDS.md#understand-a-codebase-cold) | \"What is this repo, and what matters in it?\" | `--for` ·`--help-task` ·`--tree` ·`--lego` ·`--exemplar` ·`--recall` ·`--top-k` ·`--token-budget` ·`--max-tokens` | \n| [**navigate / answer a question**](/redhat-et/ripwire/blob/main/docs/COMMANDS.md#navigate--answer-a-question) | \"Who calls this? Is it safe to change? Which tests?\" | `--callers` ·`--callees` ·`--uses` ·`--impact` ·`--path` ·`--connect` ·`--affected` ·`--situ` ·`--test-gate` ·`--grep` | \n| [**zoom the detail ladder**](/redhat-et/ripwire/blob/main/docs/COMMANDS.md#zoom-the-detail-ladder) | \"Show me more — but only where it pays.\" | `--detail` ·`--pack-signatures` ·`--outline` ·`--expand` ·`--compress` | \n| [**assess quality / structure**](/redhat-et/ripwire/blob/main/docs/COMMANDS.md#assess-quality--structure) | \"Where is the risk, and did I just add some?\" | `--quality-panel` ·`--hotspots` ·`--clones` ·`--metrics` ·`--deps` ·`--lint` ·`--quality-delta` ·`--dmm` ·`--edit-check` ·`--pr-context` ·`--merge-scout` | \n| [**self-diagnosis**](/redhat-et/ripwire/blob/main/docs/COMMANDS.md#self-diagnosis) | \"Is my setup actually working?\" | `--doctor` | \n| [**security**](/redhat-et/ripwire/blob/main/docs/COMMANDS.md#--scan-skillsdir) | \"Is this agent skill file safe to install?\" | `--scan-skill` ·`--scan-skills` | \n| [**knobs / modes**](/redhat-et/ripwire/blob/main/docs/COMMANDS.md#knobs--modes) | shape, format, cache, budget | `--json` ·`--format` ·`--mcp` | \n\n**Prebuilt binary** — macOS (arm64 / x86-64) and Linux (arm64 / x86-64, built for **RHEL 8+**;\nevery release is smoke-tested on a RHEL 9 userland before it publishes). Downloads the latest\n[GitHub Release](https://github.com/redhat-et/ripwire/releases), verifies its SHA-256, and installs\nto `~/.local/bin`. From v0.2.2 the release tarball also ships the eighteen agent skills, and the\ninstaller stages them under `~/.local/share/ripwire/skills` **and activates them for every agent it\ndetects** (Claude Code, Codex), printing one line per agent saying what it did. An agent that is not\ninstalled is never given a skills directory, hooks are never registered without an explicit `--hook`,\nand `RIPWIRE_NO_ACTIVATE=1` stages without activating for image builds. When no agent is detected the\nactivation one-liner is printed instead:\n\n```\nRIPWIRE_REPO=redhat-et/ripwire bash -c \"$(curl -fsSL https://raw.githubusercontent.com/redhat-et/ripwire/main/scripts/install.sh)\"\n```\n\n**Building it yourself needs CMake 3.24+ and a C++23 compiler, and nothing else installed first** —\nevery dependency is vendored in-tree, so the build completes with the network off.\n\n```\ngit clone https://github.com/redhat-et/ripwire.git\ncd ripwire\ncmake -S . -B build && cmake --build build -j\n./build/ripwire . # the ranked map — start here on an unfamiliar repo\n```\n\n## Why there is no download step — vendored grammars, the offline-build proof, the languages parsed, and putting it on `PATH`\n\n**Or build from source.** Requirements: CMake 3.24+ and a C++23 compiler — that means clang 16+ /\nAppleClang 15+ (Xcode 15) / gcc 13+ / MSVC 19.36+, and if your distro's CMake is older than 3.24,\n`pip install cmake` or `brew install cmake` gets a current one everywhere. Nothing else —\ntree-sitter's core, all 21 grammars and the test framework are vendored under `third_party/deps`,\nso there is no download step and no package manager to satisfy. Prove that with the network off:\nadd `-DFETCHCONTENT_FULLY_DISCONNECTED=ON` and the build still completes.\n\nTwo builds, two jobs — pick by what you are doing:\n\n```\n# building to USE it — the fast binary (Release implies LTO; scripts/pgobuild.sh adds PGO, what CI ships)\ncmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release && cmake --build build-release -j\n\n# building to WORK ON it — plain configure, no build type (why that matters: the trap, under the fold below)\ncmake -S . -B build && cmake --build build -j\n```\n\nParses **C/C++, Objective-C/C++, Python, TypeScript, JavaScript, Java, Ruby, PHP, Lua, Bash, Go,\nRust, Swift, C#** — plus JSON/TOML/YAML config keys, markdown sections, Metal, and CUDA (`<<<>>>`\nlaunches are call edges).\n\nTo put it on `PATH`, `./install.sh` builds and atomically installs the binary plus the matching\n`skills/` and `hooks/` assets into a detected prefix (Homebrew's if present, `~/.local` otherwise;\noverride with `RIPWIRE_INSTALL_PREFIX`). Set `RIPWIRE_ACTIVATE_CODEX=1` to also refresh Codex's skill\nlinks and advisory hooks from that same staged version; activation is otherwise explicit.\n\nWiring it into your agent takes one more minute — `wrap` **prints** the recipe for your client, it\nnever edits your config:\n\n```\nripwire wrap claude # prints: claude mcp add ripwire -- ripwire --mcp\nripwire wrap --all # detect every installed agent, print each one's recipe\nskills/install.sh --codex # Codex CLI: the task-shaped skills that say when to query — and when to stop\n```\n\nFour commands worth learning first:\n\n```\nripwire . # the ranked map — start here\nripwire . --for=\"incremental cache invalidation\" # the task lens: what to touch, ranked\nripwire . --callers=someFunction # who calls it\nripwire . --test-gate # before you commit: which tests must run\n```\n\n## CLI or MCP, the `-DCMAKE_BUILD_TYPE=Release` trap, and the honesty contract in one line\n\nThe CLI is the recommended baseline because it works in every shell-capable agent; the MCP server is\noptional, for agents whose workflow benefits from persistent tool registration. Full walkthrough,\nall six clients: [Agent setup](#set-it-up-in-your-coding-agent).\n\n**The trap, spelled out:** never configure the *dev* tree (`build/`) with\n`-DCMAKE_BUILD_TYPE=Release`. Release defines `NDEBUG`, which compiles the degrade-path alerts out\nand blinds the gates that assert them — and every gate and bench number is measured against\n`build/`, so changing that tree's flavour silently moves all of them at once. Release belongs in\nits own tree (`build-release/` above; `./install.sh` builds its own `build-install/` the same way).\nCI builds both flavours on purpose — see [`CONTRIBUTING.md`](/redhat-et/ripwire/blob/main/CONTRIBUTING.md).\n\n**The honesty contract, in one line:** every count ripwire cannot prove is a total ships labelled a\nfloor, every truncation is disclosed where it happens, and a zero means *none found* — never *none\nexists*. Two runs over the same tree are byte-identical, and a warm run equals a cold one. That is a\ncontract, gated on every pull request and every push to main, not a tendency.\n[The full discipline — and the losses published next to the wins →](#the-honesty-contract)\n\n**Six independent evidence families, ranked by how many of them agree — never one blended score.**\nPointed at this repository's **4,956** eligible functions, 2-of-6 agreement leaves **401** worth a\nsecond look: an **8.1%** shortlist. Pooled over five corpora (n = 27,889) no two families correlate\nabove **+0.168**, which is what makes agreement corroboration rather than one metric counted twice.\nWhat each family actually looks at — on this repository's own source, not a synthetic example:\n\n| Family | Question | Backing verb | On this repo | \n|---|---|---|---|\n| **structural** | shape: complexity, size, nesting *and how much of the body is deep* , params, local-variable count — absolute bars, not a ranking | `--metrics` | `buildGraph` (`src/graph.h:462` ):`ccx=698 loc=1244 nest=8 humps=30 deep=283 locals=114` —**114 local variables invisible to every quality lens until this session** , because naming/size analysis has always stopped at a function's signature;`locals=` is a disclosed floor (`locals_floor=\"1\"` ), threaded through the same walk that already computes`ccx` /`nest` , at zero extra parsing cost | \n| **lexical** | identifier text: the 10 `naming-*` lint rules (short, wordy, case-mixed, uninformative, …) | `--lint` ,`--naming-consistency` ,`--lint --naming-locals` | see below — the one family with a fix, not just evidence | \n| **confusion** | syntactic idiom: the 7 `atom-*` rules (implicit predicates, nested ternaries, embedded`++` /`--` , …) | `--lint` | corpus-wide finding counts, not a per-function claim to spotlight here | \n| **historical** | git change frequency — `score = churn × cognitive complexity` | `--hotspots` | `src/main.cpp` :`churn=42 ccx=3387 score=142254` — top of`--hotspots` ' ranking, and its own worst function (`main` ,`ccx=387` ) is where developers keep working*and* the code is hardest. One caveat the panel's own legend states and this table must too: churn is measured**per file** , so every symbol in a file carries that file's`churn=` /`hrank=` verbatim — this family is file evidence*inherited* by the row, never the row's own history | \n| **colocation** (local reasoning) | how much you must read that isn't in front of you | `--context-ratio` | `computeQualityDelta` (`src/mcpverbs.h:2031` ), ~50 lines,**87.0%** of its distinct references resolve outside its own file — by the tokens a reader must actually read,**99.6%** . A refinement of Beck & Diehl's per-class congruence (FSE 2011); Martin's instability`I = Ce/(Ca+Ce)` is its cruder ancestor | \n| **state** (unintended side effects) | mutable state a change here can perturb, that `--impact` (who calls you) never asks about | `--nonlocal-state` | `ensure_global_init` (`src/infra/profilePmc.h:288` ) reaches 3 distinct global/static cells through its own body and callees — a tiny, innocent-looking call site can still break state three hops away. Unsound by construction (no pointer aliasing, no indirect calls), so every count is a floor | \n\n## How the six families are joined, the churn caveat, and the `nest=` profile deep-dive\n\n`--quality-panel` joins **six independent evidence families** (structural shape, lexical naming,\nsyntactic-confusion idioms, git churn history, cross-file colocation, and non-local mutable state)\nand ranks by the *count* of families agreeing, never a weighted composite — averaging correlated\nmetrics and calling it several is the Maintainability Index's well-known failure mode. On this\nrepository the panel measures **4,956** eligible functions and narrows them to **401** worth a\nsecond look at 2-of-6 agreement — an **8.1%** shortlist, not a guess — and the largest correlation\nbetween any two families, pooled across five independent corpora (n = 27,889), is **+0.168**: the\nfamilies really are measuring different things. The six-family table above shows what each finds on\nthis repository's own source; the sections below are the parts that need more than a row.\n\nThe structural family's `nest=` reports the single deepest line in a function. One line at depth 9 and\na thousand lines at depth 9 produce the same number — which means a long **blocked-sequential** body (a\nrun of shallow scoped steps, its max set by one inner loop nobody has to hold in their head) is\nindistinguishable from a **tangled** one that sustains depth for hundreds of lines. Every consumer of\n`nest=` inherited that blindness: the panel's structural family, `--readability`'s rank, the ensemble join.\n\n`--metrics` now emits the **profile** beside the max — `humps=` (how many maximal regions reach the\nnesting bar, CodeScene's \"bumpy road\": a rise above the threshold then a fall, so repeated missing\nabstractions read differently from one deep tangle) and `deep=` (how many lines lie inside them, against\nthe `loc=` already on the row). Both come from the same fused walk that already computes `ccx`/` nest`, at\nzero extra parsing cost; `deep=` is a disclosed floor (`deep_floor=\"1\"`). Both are **absent** exactly when\n`nest <` the bar — not-deep, never a hidden `0`. `deep` counts **lines** and `humps` counts **regions**,\nand two regions can share a line — a one-line `if(c){x;}else{y;}` at the bar is two regions on one line —\nso `deep` below `humps` is legal output rather than a defect. On this repository's own source:\n\n| function | `loc` | `nest` | `humps` | `deep` | deep/loc | reading | \n|---|---|---|---|---|---|---|\n| `ingest` (`src/ingest.cpp` ) | 1632 | 8 | 25 | 467 | **29%** | genuinely tangled | \n| `buildGraph` (`src/graph.h` ) | 1244 | 9 | 30 | 308 | **25%** | genuinely tangled | \n| `main` (`src/main.cpp` ) | 1061 | 6 | 29 | 111 | **10%** | long, mostly shallow steps | \n| `dispatchMcpLine` (`src/mcp.h` ) | 1099 | 7 | 22 | 102 | **9%** | a dispatch table, not a tangle | \n| `runDefaultMap` (`src/main.cpp` ) | 650 | 4 | 7 | 15 | **2%** | blocked-sequential | \n| `ur_walkTree` (`src/ingest.cpp` ) | 87 | 7 | 1 | 43 | **49%** | *small* and tangled | \n\n`loc` and `nest` alone rank `main` and `dispatchMcpLine` beside `ingest` and `buildGraph`; the profile\nseparates them, and it promotes `ur_walkTree` — 87 lines, so no size bar fires, yet proportionally the\ndensest thing in the table. **This changes no ranking**: `humps > 0` is exactly `nest >= bar`, which is\nprecisely when the `nest` bar already fired, so the family count and the panel's shortlist are untouched.\nIt is strictly more evidence on rows that already appear — a reader can tell the two shapes apart without\nopening the file.\n\nThe panel also carries **one join, and it is deliberately not a seventh family**: a row whose structural\nevidence includes `deep=` (a body that *sustains* depth at the nesting bar) and that no indexed test\nreaches is annotated `join=\"deep+untested\"` — the pair where a refactor is most wanted and least safe,\nput side by side because both facts are already on the row. It changes nothing: not `fam=`, not `of=`,\nnot the order, not which rows appear (counting it would be the structural family wearing a second hat).\nThe root reports `tested_scope=` (symbols any indexed test reaches — the join's honest denominator) and\n`deep_untested=` (rows carrying the annotation across the whole row set); at `tested_scope=\"0\"` no\nindexed test reaches *anything* here, so \"untested\" would be a fact about what was crawled rather than\nabout the code, and the annotation is emitted on **no** row.\n\n**Five lenses sit *beside* the six-family join — deliberately outside its vote.** Each is out for a\nstated reason, not an oversight:\n\n| Lens | Asks | Why beside the join | On this repo | \n|---|---|---|---|\n| `--field-affinity` | which struct fields are read together but declared far apart; each loop's access shape (index vs pointer-chase) | its subject is a **type** , not a function — attributing a struct's finding to the functions touching it is a claim the lens never makes | `MainDispatch` :**12** findings at separation cost**92.88** ;**1,374** loops classified,**5** genuine pointer-chases | \n| `cache-*` lint rules +`--with-profile` | cache-hostile access shapes (alloc-in-loop, `p=p->next` ,`a[b[i]]` , node containers, …), then which are*measured* hot | rows are facts about **sites** , joined to per-scope hardware counters — not per-function evidence a family vote could count | aggressive rules: **0** hits in shipping`src/` ;**327** findings adversarially triaged →**0** fix-worthy; the one open refactor settled by measurement (5.2 ms) | \n| `--readability` | least-readable-first ordering (Halstead volume, Posnett sigmoid) | the fitted score **saturates past 20 lines** — only the ordering is meaningful, and an ordering cannot vote in a count | ordering only, never a grade | \n| `--naming-consistency` | off-convention names, each with a computed `propose=` | the one lens that emits **advice** — a fix is not evidence, so it does not vote | camelCase dominant at **93.0%** ;**136** names flagged with proposals | \n| `--lint --naming-locals` | the naming rules pointed at local variables inside already-flagged functions | **opt-in and unvalidated** — stays outside any join until a real-corpus audit clears it (the withdrawn-rule lesson) | + **973** findings that were structurally invisible before | \n\n## The depth on each lens — citations, caveats, and the withdrawn-rule note\n\n**Two verbs sit *beside* the panel, not inside its six-family join** — worth knowing the boundary\nrather than blurring it:\n\n- **`--field-affinity`** (cache-friendly co-access) is explicitly**not** a panel family, by unit: it\nmeasures which struct fields are read together but declared far apart, and its subject is a*type* ,\nnot a function — attributing a struct's finding to the functions that touch it would be a claim the\nlens itself never makes (`docs/EVALS.md` §9.9.2).`MainDispatch` (`src/main.cpp:1335` , the 144-byte\nstruct threaded through nearly every verb) still carries**12** real findings against a separation\ncost of**92.88** — fields read together in the same call routinely cross cache-line boundaries.\nChilimbi, Davidson & Larus's cache-conscious structure definition (PLDI 1999), validated on real\nhardware counters; the advice-not-transform posture (report a split, never auto-reorder a struct)\nfollows Hundt, Mannarswamy & Chakrabarti (CGO 2006).**This is a genuinely rare kind of tool** : code\nreview catches cache-unfriendly patterns constantly, but every adjacent tool that reasons about\nmemory-access shape (Intel Advisor's pattern classifier, DMon, PerfLint) does it by*running the\nprogram first* — a two-round adversarial literature and patent search found no shipping tool and no\npublished work that does this**statically, before a line executes** (tier: RARE BUT REAL, the full\ncitation trail and hedged claim wording in[`docs/LINEAGE.md`](/redhat-et/ripwire/blob/main/docs/LINEAGE.md) ). The same verb now\nalso classifies each loop's access shape —`index` /handle-based (predictable, the hardware\nprefetcher can hide the latency) vs. pointer-chase (data-dependent, no struct layout fixes an\nunhideable per-hop stall) — and, for genuine chases, checks whether the pointer you dereference to*reach* the next node sits next to the payload you're about to read, since that cache-line fetch is\nunavoidable and colocating there is a strictly higher-value fix than generic field reordering. On\nthis repository:**1,374** loops classified,**5** genuine pointer-chases found in a codebase\ndeliberately built handle-based rather than pointer-linked (guardrail G2) — the lens staying quiet\non code written to avoid the problem is itself a check that it isn't firing at random.**Ships\nentirely report-only** : an A/B benchmark against a real 64 MB shuffled linked list measured a\nmostly-null result, so the ranking-affecting half of this feature is a provable no-op until a\nblind real-corpus validation session clears it — reported here at the same honesty level as\neverything else in this table, not oversold ahead of the evidence.\n- **The `cache-*` lint pack + `--with-profile`** (cache-friendly*access patterns* — the other half\nof the locality story, shipped 2026-08-07/08) covers what`--field-affinity` deliberately does not:\neight AST shapes practitioners agree hurt — node-based containers,`vector` /vector-of-indirect\n(the \"matrix as vector of vectors\"), heap allocation inside loops,`p = p->next` chase advances,`a[b[i]]` gather subscripts, by-value`shared_ptr` parameters, and existing manual prefetches\nflagged for re-measurement — loop-fenced by span algebra, C-family only, facts never verdicts. The\nhonesty numbers, both directions: on this repository the aggressive rules fire**only in benches\nand test fixtures, zero in shipping `src/`** (guardrail G2 holding is itself the check the rules\naren't firing at random), and a 13-agent adversarial triage of all 327 findings confirmed**zero** as fix-worthy — every plausible refactor died on \"win unmeasurable without a profile\". That gap is\nexactly what**`--lint --with-profile=FILE`** closes: it joins a` RIPWIRE_PROFILE` build's own\nper-scope hardware counters (`#PROF_TSV` ) onto findings, so a row carries`heat_total_ms` /`heat_l1d_mpki` from a real run — static shape × measured PMU weight, the two halves of SYZYGY's\nadvice mode (Hundt, CGO 2006) finally in one command. Worked example: the one surviving refactor\ncandidate (flattening the Louvain adjacency) was settled by its new`PROFILE_SCOPE` in a single\nmeasured run —**5.2 ms, 5.9% of the verb** — a wasted afternoon prevented by a number\n([`docs/CACHELINT.md`](/redhat-et/ripwire/blob/main/docs/CACHELINT.md) holds the full catalog, the wave-2 specs, and the\ncompiler-handled myths deliberately*not* checked).\n- **`--readability`** is a sibling lens, not a panel family either — the one classic model in the tree\nwith a published closed form: Halstead volume (Halstead,*Elements of Software Science* , 1977) and\nthe Posnett/Hindle/Devanbu sigmoid fit (MSR 2011,[doi:10.1145/1985441.1985454](https://doi.org/10.1145/1985441.1985454) ),\nfitted on snippets of 20 lines or fewer — past that the fitted score saturates and only the*ordering* stays meaningful, which is exactly how the verb is used: least-readable-first, never as a\ngrade. Halstead's volume specifically (not the later, less-trusted difficulty/effort derivatives) is\namong the metrics shown to track measured cognitive load directly (Peitek, Apel, Parnin, Brechmann &\nSiegmund, ICSE 2021,[doi:10.1109/ICSE43902.2021.00056](https://doi.org/10.1109/ICSE43902.2021.00056) ) —`--readability` emits volume and stops there; difficulty and effort are computed nowhere in this\ntree.\n- **`--naming-consistency`** is the*lexical* family's one exception to \"evidence, never advice\": every\nother lens in this panel tells you WHAT is wrong, never a computed fix. Case-style consistency is\nthe one property with a corpus-derivable answer — on this repository's`src/` , camelCase is the\ndominant convention at**1,677/1,803 (93.0%)** agreement, and the verb flags**136** off-convention\nnames with a mechanically recombined`propose=` value for each (no dictionary, no synonym judgment —\nsee[What it answers](#what-it-answers) ).\n- **`--lint --naming-locals`** points those same naming rules at local variable names — the thing a\nhuman reviewer flags immediately in a sprawling function and no static tool measured until this\nsession. Opt-in, off by default: on this repository, a plain`--lint` finds**2,225** findings;\nadding`--naming-locals` finds**3,198** —**973 findings that were structurally invisible** a moment ago, scoped tightly (only inside functions already flagged large/complex, only locals\nnested two blocks deep for the short-name rule) so it doesn't just relabel every loop counter in\nthe tree. Ships disabled by default on purpose: this repository's own history includes a naming\nrule that shipped on plausibility and was later measured to flag its*best* -named functions — see\nthe withdrawn-rule note below — so a rule this new stays opt-in until a real-corpus audit clears it.\n\nFull citation table, evidence tiers, and what got measured and *withdrawn* (a naming rule that\nflagged this repository's best-named functions, kept as the standing argument for measuring before\nshipping) → [`docs/LINEAGE.md`](/redhat-et/ripwire/blob/main/docs/LINEAGE.md).\n\n**Four real invocations against this repository**, each printed as the binary actually prints it:\n`--callers` (and why its count is a floor), the default ranked map (and what `amb=` admits),\n`--test-gate` (exit 4 while obligations remain), and `--from-trace` (feed it the error itself, not a\nparaphrase of one).\n\n## How these excerpts were edited — minified output wrapped for reading, and exactly which numbers are elided\n\nOutput is minified — one line, no whitespace between tags — so the excerpts below are wrapped for\nreading, and each one's leading legend comment is elided. Nothing else is edited, except that\ncorpus-size numbers (file/symbol/edge counts, the ranked-map header's token/ambiguity tallies,\nPageRank `k=` values, and the test-gate example's\n`script_gates_unmodelled=` — a count of the script runners under `test/`, recursively) drift as this repository\ngrows: **the ranked map** elides those specifically, and says so again at the point of use, and **the\ntest gate** additionally trims its `` rows down to 2 of the 25 the real run prints, behind a\ntrailing `…`.\n\n## `--callers` — a call graph built on the spot, and why `count=\"6\"` ships labelled a floor\n\n**Ten seconds, no index server, no embeddings, no API key** — a parse and a call graph, built on the\nspot:\n\n``` bash\n$ ripwire . --callers=rankGraphTeleport\n\n\n\n\n\n\n\n\n```\n\n`counts_floor=\"1\"` is the point. Call edges are extracted from source text by name, so dynamic\ndispatch contributes no edge (a call through a function pointer or callback is an edge only when\nONE function is bound to that variable in scope and the variable never escapes — its address taken\nor reference-bound — and a macro-generated call site — tagged\n`role=\"macro\"` — only when its function-like `#define` is indexed): `count=\"6\"` is a **floor**,\nand the element says so before you read a single row.\n\n## The default ranked map — `--top-k=3`, and what `amb=\"2\"` admits about a resolver guess\n\n**The ranked map** — the default run, capped to three symbols so it fits here:\n\n``` bash\n$ ripwire . --top-k=3\n\n\n\n\n\n\n\n