Skip to content
Back to search

ripwire

The ripgrep of AI context: a zero-dependency C++23 CLI + MCP server for coding agents. Find what you want without reading the repo, then check you built what you meant — blast radius, tests-to-run, quality deltas. Signatures at 74.7% fewer bytes than bodies; every guess labelled, every loss published. Paddle out with a map.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/redhat-et/ripwire with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/redhat-et/ripwire'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/redhat-et--ripwire/badge.svg)](/listings/redhat-et--ripwire)

HTML

<a href="/listings/redhat-et--ripwire"><img src="/api/listings/redhat-et--ripwire/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<details> <summary><b>Prebuilt binary</b> — macOS on Apple silicon and Linux (arm64 / x86-64, built for <b>RHEL 8+</b>), SHA-256 verified, shipping <b>seventeen agent skills</b> the installer activates for every agent it detects</summary>

**Prebuilt binary** — macOS (arm64; 0.6.1 is the last release with an Intel macOS binary, and an Intel Mac builds later releases from source) and Linux (arm64 / x86-64, built for **RHEL 8+**; every release is smoke-tested on a RHEL 9 userland before it publishes). Downloads the latest [GitHub Release](https://github.com/redhat-et/ripwire/releases), verifies its SHA-256, and installs to `~/.local/bin`. From v0.2.2 the release tarball also ships the seventeen agent skills, and the installer stages them under `~/.local/share/ripwire/skills` **and activates them for every agent it detects** (Claude Code, Codex), printing one line per agent saying what it did. Sixteen of the seventeen are for using the tool; the one about compiling ripwire itself (`ripwire-opt-remarks`, `audience: contributor` in its front matter) stays staged unless you pass `--contributor` to `skills/install.sh`. An agent that is not installed is never given a skills directory, hooks are never registered without an explicit `--hook`, and `RIPWIRE_NO_ACTIVATE=1` stages without activating for image builds. When no agent is detected the activation one-liner is printed instead:

RIPWIRE_REPO=redhat-et/ripwire bash -c "$(curl -fsSL https://raw.githubusercontent.com/redhat-et/ripwire/main/scripts/install.sh)"
export PATH="$HOME/.local/bin:$PATH"      # not on PATH by default on macOS or most Linux shells; add it to your rc file

</details>

<a id="windows"></a> <details> <summary><b>Windows x64 (preview)</b> — a zip with <code>ripwire.exe</code> and the skills, no runtime to install first; a preview until Windows users confirm it</summary>

**Windows x64 — preview.** From 0.6.3 each release carries `ripwire-<version>-windows-x64.zip` and its `.zip.sha256`. It is built with clang-cl against the static C runtime, so it needs no Visual C++ Redistributable, and like the Linux x64 binary it needs an x86-64-v3 (AVX2) CPU. CI unzips and exercises it on every train, including a byte-for-byte comparison of its output with Linux's, but no maintainer runs Windows, so treat it as a preview until Windows users report back. The exe is not code-signed. `Expand-Archive` does not pass the download's Mark-of-the-Web on to the files it extracts, so SmartScreen does not prompt for an exe unpacked this way; no prompt is not a verdict. In PowerShell:

$v = "0.6.3"; $a = "ripwire-$v-windows-x64"; $u = "https://github.com/redhat-et/ripwire/releases/download/v$v"
Invoke-WebRequest "$u/$a.zip" -OutFile "$a.zip"; Invoke-WebRequest "$u/$a.zip.sha256" -OutFile "$a.zip.sha256"
# extracts only when the SHA-256 matches; on a mismatch it throws and nothing is unpacked
if ((Get-FileHash "$a.zip" -Algorithm SHA256).Hash -eq (Get-Content "$a.zip.sha256").Split(" ")[0]) { Expand-Archive "$a.zip" -DestinationPath "$env:LOCALAPPDATA\Programs" } else { throw "SHA-256 mismatch: do not run $a.zip" }
$bin = "$env:LOCALAPPDATA\Programs\$a"
[Environment]::SetEnvironmentVariable("Path", "$bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
$env:Path = "$bin;$env:Path"   # this window too; new windows read the user Path
ripwire --version

- **The hash check** passes because `-eq` ignores case: `Get-FileHash` prints upper-case hex and the `.sha256` file is lower-case. For a case-sensitive compare, use `.Hash.ToLower() -ceq`. - **Comparing two outputs in Git Bash:** use `cmp`. There `fc` is a shell builtin (it replays history) and compares nothing; the Windows tool is `fc.exe`, run as `MSYS_NO_PATHCONV=1 fc.exe /b a b` so `/b` is not rewritten as a path. - **Git for Windows** is needed for the git-history features (churn, `--situ`, the `git` row of `--doctor`) and for the skills installer. The map itself runs without it.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 2,835 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![CI](https://github.com/redhat-et/ripwire/actions/workflows/ci.yml/badge.svg)](https://github.com/redhat-et/ripwire/actions/workflows/ci.yml)
  2. [![Release](https://img.shields.io/github/v/release/redhat-et/ripwire)](https://github.com/redhat-et/ripwire/releases/latest)
  3. [![Licence](https://img.shields.io/badge/licence-Apache%202.0-blue.svg)](LICENSE)
  4. [![Standard](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](CONTRIBUTING.md)
  5. [![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-none-blue.svg)](THIRD_PARTY.md)
  6. [![Slides](https://img.shields.io/badge/slides-the%20showcase%20deck-56d6e8.svg)](present/ripwire-showcase.pdf)
  7. <p align="center"><img src="docs/assets/banner.svg" alt="ripwire — the ripgrep of AI context" width="880"></p>
  8. # Rip'n Fast. Fewer Tokens. Better Code.
  9. **The ripgrep of AI context. A map before your agent reads the repo — and a check on what it writes.**
  10. <p align="center"><a href="https://trendshift.io/repositories/217924?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-217924"><img src="https://trendshift.io/api/badge/trendshift/repositories/217924/weekly?language=C%2B%2B" alt="Trendshift: C++ Repository of the Week badge for redhat-et/ripwire" width="250" height="55"></a></p>
  11. Ranked, deterministic call graph: what to touch, what it breaks, which tests to run. On the edit: blast
  12. radius, tests that reach it, twelve quality kinds reporting only what got worse, forgotten co-changes, fields
  13. read and written, names that resolve more than one way.
  14. **Just want to use it?** Install it with the one line below, then start each coding session by telling your agent to
  15. use it, for example: *"Use ripwire on this repo."* That is all most people need: the install also teaches your agent
  16. when to reach for each command.
  17. **Want every detail?** [The reference guide](#reference-guide) near the bottom covers install, commands, output
  18. format, exit codes and limits. You do not need it to get started.
  19. <details>
  20. <summary><b>Field report: what ripwire contributed to a large multi-agent coding engagement</b> — written by Claude Fable 5.0, the frontier model orchestrating ~20 coding agents over two days on a ~1,500-file C++/Metal codebase. Click for the full report.</summary>
  21. > For a single developer, this tool is a good lookup accelerator. For an *orchestrated fleet*, it's load-bearing: it
  22. > halved the research spend, twice redirected tasks before wasted work, prevented at least one silent-divergence shipped
  23. > bug, and turned code-quality hygiene from a hope into a per-task mechanical gate. Whole-workflow ~2×; per-lookup
  24. > 10–25×; and two moments where one call was worth more than the rest of the session's tooling combined.
  25. >
  26. > — the report's bottom line
  27. <p align="center"><a href="docs/assets/field-report-multi-agent.jpg"><img src="docs/assets/field-report-multi-agent.jpg"
  28. alt="The full field report: what ripwire contributed to a large multi-agent coding engagement — headline numbers, where the value concentrated, the honest boundary, and the bottom line" width="720"></a></p>
  29. <details>
  30. <summary>Text version of the report</summary>
  31. **Field report: what ripwire contributed to a large multi-agent coding engagement**
  32. *Context, genericized: one orchestrating session directing ~20 sequential/parallel coding agents over a ~1,500-file
  33. C++/Metal codebase across two days — a deep architecture audit, then a 14-task feature wave (new subsystems,
  34. measurement infrastructure, a search-archive migration), ending in a verified all-on release flip. Every agent was
  35. instructed to lead with ripwire for orientation and to close with its quality gates.*
  36. **The headline numbers**
  37. - **Roughly half the total token spend of the audit/research phase, saved.** This is the operator's whole-phase
  38. estimate — it includes everything the research agents did, ordinary file reads and all, which makes it conservative
  39. rather than cherry-picked. The per-call factors underneath are much steeper: a single doc-recall call served the
  40. relevant sections of a 164KB planning document in ~6K tokens (~25×), and agents that led with the tool ran ~30–40%
  41. leaner on tool-call counts than agents doing raw read fan-outs over comparable questions.
  42. - **Two tasks had their direction changed by a single call.** One task was chartered to activate a steering behavior
  43. the team believed was in production; one `--callers` query returned **zero production callers**, redirecting the
  44. task to the real gap (the data provider that behavior needed had never been wired anywhere). Another task
  45. refactored a widely-shared computation; `--edit-check` flagged **5 of 6 call sites** as incompatible — sites a text
  46. search had missed — that would otherwise have silently diverged from the canonical path the day the feature was
  47. enabled, surfacing months later as an unexplainable visual bug.
  48. - **A dozen-plus real code-quality defects fixed, not waived, across ~15 implementing agents** — all caught by
  49. `--quality-delta` at each agent's "I think I'm done" moment: a 480-token duplicated routine, a fourth private copy of
  50. a shared RNG utility, a hand-duplicated cost function, a pair of near-identical functions with a flipped sign
  51. (correct at one boundary, quietly wrong at the other), test-fixture duplication across sibling suites, and functions
  52. that had quietly absorbed a second job. None of these would have failed a test; all of them are the sediment that
  53. rots a codebase under high-velocity multi-agent development. The gate made removing them routine instead of heroic.
  54. **Where the value concentrated**
  55. 1. **Orientation and recall (the token win).** Ranked-signature task orientation and section-granular document recall
  56. meant agents started from *answers*, not file dumps. Recall over planning docs was the orchestrator's single
  57. most-used verb — the audit's entire framing came from two calls.
  58. 2. **The contract checker (the shipped-bug preventions).** Beyond the 5-of-6 catch above, `--edit-check` gave
  59. near-free proof-of-contract on every public-symbol change across the wave — the kind of verification that
  60. otherwise simply doesn't happen at agent speed.
  61. 3. **The quality gate as a *protocol*.** The measurable effect wasn't any single catch — it was that fifteen different
  62. agents, none sharing context, all converged on the same "fix or justify with a written reason" discipline, with an
  63. acknowledgments ledger that survived across tasks. Unattended orchestration usually leaks quality; here the
  64. leak-check was mechanized.
  65. 4. **Persistent notes.** Agents left gotcha notes pinned to symbols mid-wave (a caller-wiring law, an arming-rule
  66. invariant), which later agents' lookups surfaced automatically — cheap institutional memory between contexts
  67. that never met.
  68. **The honest boundary**
  69. - **The engagement's deepest findings did not come from the tool.** A structural capacity ceiling, a mis-derived
  70. constant, a floating-point re-association drift of 1 ulp, and a seed-keying bug were all found by *bespoke
  71. measurement the agents built* — baseline worktree diffs over full data fills, multi-arm attribution sweeps,
  72. funnels. The tool is a floor for honesty and orientation, not a substitute for measurement design.
  73. - **Known false-positive mode, handled by its own documentation:** the contract checker's arity heuristic
  74. over-counts on defaulted trailing parameters (one task saw "incompatible=18" that were all fine). The tool's own
  75. trust-calibration notes say to verify by compiling in exactly this case, and agents that followed them lost nothing.
  76. - For broad, common-word conceptual queries, plain grep-and-read still occasionally won — consistent with the tool's
  77. own guidance that it shines on specific technical asks.
  78. **Bottom line**
  79. For a single developer, this tool is a good lookup accelerator. For an *orchestrated fleet*, it's load-bearing: it
  80. halved the research spend, twice redirected tasks before wasted work, prevented at least one silent-divergence shipped
  81. bug, and turned code-quality hygiene from a hope into a per-task mechanical gate. Whole-workflow ~2×; per-lookup
  82. 10–25×; and two moments where one call was worth more than the rest of the session's tooling combined.
  83. </details>
  84. *The model's own report of one engagement, on a version before 0.5; not a controlled measurement. Controlled
  85. measurements are in [docs/EVALS.md](docs/EVALS.md).*
  86. </details>
  87. <details>
  88. <summary><b>Fifty years of software-engineering results, and research from last month.</b> 49 repositories and 79 papers folded — McCabe (1976) through to <b>seven published in the last two months</b> — each row in <a href="docs/LINEAGE.md"><b>docs/LINEAGE.md</b></a> naming the lesson taken and the file it lives in</summary>
  89. Beside those sits a labelled survey of **237 tools** that contributed nothing and says so. The two
  90. sets are disjoint by construction, so they add rather than nest — a tool that gave a lesson is never
  91. counted twice.
  92. **Both halves are load-bearing, and they are doing different jobs.** The settled results are what
  93. make the quality lens trustworthy: McCabe on complexity (1976), Halstead on volume (1977), Spärck
  94. Jones on term specificity (1972), Nagappan & Ball on churn. Fifty years of replication means those
  95. are not opinions, and a tool that measures your code should be built on the ones that survived.
  96. The recent work is what makes it *current*: **seventeen of the folded papers are from 2026, seven
  97. published in the last two months and three in the last thirty days** (dates as of 2026-09-08; every
  98. row carries its arXiv id, so the claim is checkable rather than atmospheric). Retrieval for coding
  99. agents, context-compression cost, placebo-controlled localization — that literature is months old,
  100. not decades, and several rows were folded within weeks of the paper appearing.
  101. Neither half alone would be enough. A tool built only on the classics would not know what an agent
  102. needs; one built only on last month's preprints would have nothing underneath it. And the newest row
  103. is a result that **failed** when it was tested here — which is the point of writing them down. All three counts are re-derived from that document's own tables by
  104. `test/readmedriftcheck.sh` on every run, which fails if this page and those tables disagree, so the
  105. claim cannot quietly drift. The row-by-row ledger is
  106. [`docs/LINEAGE.md`](docs/LINEAGE.md).
  107. </details>
  108. **Languages:** Rust · C++ · Objective-C/C++ · C · Metal · CUDA · Python · Go · Swift · TypeScript ·
  109. JavaScript · Java · Ruby · PHP · Lua · Elixir · Dart · Kotlin · GDScript · Clojure · Bash · C# · Protocol Buffers · JSON · TOML · YAML · Markdown — see
  110. [language support and limits](#languages).
  111. **Latest: 0.6.10** — more complete `--for` answers, warm runs on large repositories that use 35 to 67 % less CPU, and about half the peak memory of an index on macOS. [Release notes](#release-notes) ·
  112. [the presentation](present/ripwire-showcase.pdf) · [the changelog](CHANGELOG.md) — with thanks to the
  113. contributors named there.
  114. ---
  115. <p align="center"><img src="docs/assets/no-deps.svg"
  116. alt="No API key. No embeddings. No index server. No daemon." width="470"></p>
  117. <details>
  118. <summary><b>One process, no server</b> — indexes this repository in <b>0.25 s</b> using <b>6.6 MB</b>, against <b>46.8 s</b> and <b>391 MB</b> for the graph-database MCP server it was measured against; warm queries answer in <b>197 ms</b> to its <b>1,082 ms</b></summary>
  119. Measured on 48 matched questions across django, webpack and this repository. Across all three,
  120. ripwire indexes in **0.25–0.45 s** and **6.6–16.5 MB** against that server's **23–52 s** and
  121. **391–623 MB**. The full method, the wins named one by one and the losses included, is in
  122. [Against the leading graph-database code-context MCP server](#against-the-leading-graph-database-code-context-mcp-server)
  123. and [`docs/EVALS.md`](docs/EVALS.md).
  124. </details>
  125. <details>
  126. <summary>One binary, offline — and the same line <b>activates the skills</b> for every agent it finds: Claude Code · Codex · Cursor · Windsurf · Gemini · opencode · aider</summary>
  127. One self-contained binary on your own machine, offline, installed in one line — and the same line
  128. installs *and activates* the task-shaped skills that teach your agent *when* to reach for it, not
  129. just how, for every agent it finds on the machine. If your
  130. agent can run shell commands — Claude Code, Codex, Cursor, Windsurf, Gemini, opencode, aider — it is
  131. set up the moment the install finishes; [the MCP server is the optional second
  132. interface](#set-it-up-in-your-coding-agent). Install it and ask it something before you finish
  133. reading this page:
  134. </details>
  135. ```bash
  136. RIPWIRE_REPO=redhat-et/ripwire bash -c "$(curl -fsSL https://raw.githubusercontent.com/redhat-et/ripwire/main/scripts/install.sh)"
  137. export PATH="$HOME/.local/bin:$PATH" # where it installed; the installer prints this line if you need it
  138. cd your-repo
  139. ripwire . --for="<the change you are about to make, in words>"
  140. ```
  141. Every install route (prebuilt, from source, per-agent skills, hooks, the MCP server) is in [INSTALL.md](INSTALL.md).
  142. **Reach for the CLI first — it is the cheaper interface.** The MCP server is the optional second
  143. way in, and its convenience has a cost the shell pipe does not carry: its verb schemas sit in your
  144. agent's context every session, whether or not it calls them.
  145. ### The goal: one question, one complete answer.
  146. **Terminality is the objective.** Ask the codebase a question and the answer should carry everything
  147. you need — no follow-on grep, no three more whole-file reads to fill in what it left out. A call
  148. followed by three greps is the same search paid for twice: it does not save you tokens and it does
  149. not make the coding faster.
  150. **Two jobs, one goal.** An agent meeting a codebase does two things, and ripwire is shaped for both:
  151. 1. **Orient — `ripwire .`** One call gives the ranked map: the main subsystems, the program entry points,
  152. the symbols that matter most, and a count of every file the ranking left out. The most important
  153. information about a new tree, in as few calls as possible.
  154. 2. **Ask — `--for`, `--expand`, `--callers`, `--path`, …** After that, each question gets a lean answer:
  155. as few bytes as it can spend while still answering the question fully, so no follow-up grep is needed.
  156. That is the goal, and not every answer reaches it yet; the stair-steps below are how we get there.
  157. <details>
  158. <summary>The two stair-steps that make it reachable — <b>honest about what is missing</b>, <b>priced in what it spends</b></summary>
  159. **Two things make that reachable in practice, and neither is the destination.** Answers are honest
  160. about their own limits — a count that cannot be a total is labelled a floor, a zero means "none
  161. found" and never "none exists", every truncation is disclosed — so an answer never looks more
  162. complete than it is, and the map never degrades the code by guessing. And an answer can be given a
  163. token budget, so what one costs is something you ask for rather than discover; where a complete
  164. answer will not fit, it says it went over rather than silently dropping the row you needed.
  165. Those two are the stair-steps: honest about what is missing, priced in what it spends. The step they
  166. climb toward is a question fully answered in one call, which is not always trivial to reach — and
  167. where it is not, the output says so rather than pretending otherwise.
  168. **How we measure the climb.** A complete answer to every code question is genuinely hard, and it is
  169. reached over many releases rather than in one. Until an answer can be complete, it owes you three
  170. things: it stays bounded in size, it is fully honest about what it does not know, and it gives you a
  171. clue where to look next. So every change is judged on more than "was it right":
  172. - **Complete answers:** the share of questions answered so you can act without re-checking.
  173. - **Honest-partial rate:** how often an incomplete answer says what it is missing, instead of
  174. sounding confident.
  175. - **False-confidence rate:** wrong answers that claim to be complete — the worst case, held near zero.
  176. - **Next-clue usefulness:** for partial and wrong answers, whether following the answer's first
  177. suggested next step reaches what the question needed, within one hop. Graded blind.
  178. - **Recoverability:** for every cut answer, whether following its `next=` returns everything that was cut.
  179. - **Tokens per complete answer:** total tokens an agent spends across a scenario, divided by the questions it got fully answered.
  180. - **Cut-row recoveries:** how often a needed item arrived only through a continuation.
  181. **Answering comes first; efficiency is how we get there.** We aim for answers about as lean as the
  182. leanest tools, but a byte budget is never allowed to cost an answer. We have gone too far toward short
  183. answers before and cut information that was needed, so now every size limit has one of two jobs: a
  184. runaway guard far above typical answers (it catches an output bug, and says so when it trips), or a
  185. stair-step target where anything over it must be explained. A capped answer is always measured
  186. against the same answer uncapped, and the one that answers better wins.
  187. **A cut is only honest if you can get the rest back.** Disclosing a cut is the floor, not the bar: a capped
  188. answer plus the `next=` it prints must return everything the uncapped answer had. A test that checks this for every
  189. budget option on every command is being built, so that "the answer was cut" always comes with "and here is the rest".
  190. **What a budget may spend first.** When a budget is tight, ripwire drops bytes that carry no answer before
  191. it drops answers: repeated legend text, duplicated paths, bodies whose signature already says what you need.
  192. Only then the lowest-ranked rows, each counted. A whole section never disappears without a marker.
  193. **Budgets are yours to set, never ours to impose.** The defaults and the setups `ripwire wrap` writes carry no
  194. budget that cuts a typical answer; a budget is a choice the caller makes, with its cost disclosed.
  195. **Efficiency is counted per complete answer, across the whole task.** Bytes per answer can fall while the task
  196. gets more expensive, if the agent then has to ask again. So the efficiency figure is tokens per complete answer
  197. over a whole scenario — orient, then the questions that follow — not bytes per call.
  198. **Ranking is the tool's best guess; the next= is the safety net — and we measure how often the net is needed.** ripwire cannot always
  199. know which row answers the question; it goes by ranking. When a needed item appears only after following an answer's next=, the
  200. honesty layer saved the answer but the ranking put that item below the cut. We count those per round:
  201. - **Recovered through next=:** the item was cut but recoverable — one extra call. Driving this down is ranking work.
  202. - **Lost:** the item was cut with no marker or no working next= — a bug, fixed first.
  203. </details>
  204. ### Same answer, a fraction of the tokens — read this table first if your agent is on a budget
  205. <details>
  206. <summary>How these ten rows were measured — <b>2026-08-08</b>, figures in ~tokens (≈ bytes/4), every ratio from a real run reproduced by the command in its row</summary>
  207. Ten everyday moments, re-measured on this repository, 2026-08-08. Figures are ~tokens (≈ bytes/4);
  208. every ratio comes from a real run, reproduced by the command in its row — raw byte counts and exact
  209. commands in
  210. [`docs/EVALS.md` §5](docs/EVALS.md#readme-grade-rows-re-measured-on-this-repository-2026-08-08).
  211. </details>
  212. Ordered understand → navigate → review-the-change:
  213. | Ask it | Command | ripwire | naive read | token savings |
  214. | --- | --- | --- | --- | --- |
  215. | "Orient me in this repo" | `ripwire .` | **~5.6K tok** | ~20K–25K tok — read `README.md` (+`docs/ARCHITECTURE.md`) | 3.6×–4.5× |
  216. | "Where is X handled?" | `ripwire . --for="…"` | **~2.1K tok** | ~4.9K–20K tok — `grep -rn <term> src/`, then read the file it points at | 2.3×–9.3× |
  217. | "What do I already know?" | `ripwire . --recall="…"` | **~15K tok** | ~445K tok — read all 119 markdown docs this repo carries | 29.2× |
  218. | "Set me up for this task" | `ripwire . --pack-task="…"` | **~2.1K tok** | ~16K–80K tok — read every relevant file, whole | 7.7×–37.7× |
  219. | "Show me this one function" | `ripwire . --expand=SYM` | **~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× |
  220. | "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× |
  221. | "Is it safe to change this?" | `ripwire . --impact=SYM` + `--uses=SYM` | **~1.3K tok** | ~18K tok — open every direct-use file, whole | 14.4× |
  222. | "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× |
  223. | "I changed these files — tests? blast radius?" | `ripwire . --situ` | **~410 tok** | ~3K–132K tok — `git diff` + `grep -rn <syms> test/`, then open the candidates | 7.3×–324.2× |
  224. | "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× |
  225. <details>
  226. <summary>Same-correct-answer verification, and the honesty line these ratios come with</summary>
  227. **These aren't summaries that gamble with information.** Each row is scored
  228. same-correct-answer-or-it-doesn't-count, and both sides were checked, not assumed: orient surfaces
  229. this repo's own pipeline files (`ingest.cpp`, `graph.h`, `serialize.h`) in the first screen, the same
  230. three `docs/ARCHITECTURE.md` names as central; the `--for` row lands `mcpStale`
  231. (`src/mcpindex.h:633`), the actual staleness check, 5th-ranked; `--recall` lands the container-rule
  232. doc (`AGENTS.md`) that states, verbatim, the same "no `std::map`" rule `CONTRIBUTING.md` explains in
  233. full; `--pack-task` names the same three touch points a human would — `cachelint.h`, `mergeCachePack`
  234. (`src/main.cpp:1787`), the `lintrules.h` helpers it reuses; `--expand` hands back the
  235. requested function's complete, unmodified body — the ranked-neighborhood addition costs the same
  236. ~22.6 KB regardless of which function you ask for, confirmed on two (a fixed floor, not per-function
  237. variance); `--callers` on `langOfPath` names its 2 real callers, the same ones a `grep` hit-list
  238. buries under 5 files of comment-only mentions; `--impact`+`--uses` on `coversOrEquals` names the same
  239. 2 direct call sites `--uses` alone would, plus (disclosed) a transitive reach `--uses` doesn't cover
  240. at all; `--from-trace` resolves all 7 frames of a real call chain by name to the same definitions a
  241. per-frame grep would eventually find, mixed with call sites and comments; `--situ` on a 2-file diff
  242. names the same 6 real test harnesses, 2 of which a filename grep across `test/` cannot find even
  243. after opening every one of its 41 candidates — a completeness gap, not just a byte one; `--pr-context`
  244. surfaces co-change partners (`test/regression.sh`, `src/main.cpp`) a raw `git diff` has no way to
  245. know were usually touched and weren't this time — Fowler's *Shotgun Surgery* checked rather than
  246. merely named (the backtest is in [`docs/EVALS.md`](docs/EVALS.md)). The map ranks and discloses — it never paraphrases
  247. your code — and every truncation is disclosed in the header.
  248. **The honesty line, made concrete:** the same auto-selection behind the `--expand` row also runs the
  249. other way. On a small file (`pageRankDouble` in `src/pagerank.cpp`, 5,559 B) the ranked bundle would
  250. cost 27,916 B — nearly 5× more than the file — so ripwire serves the file itself instead, disclosed
  251. as `mode="whole-file"` on the response, not silently.
  252. [`docs/EVALS.md` §7](docs/EVALS.md#7-honest-counterexamples) lists that and the other counterexamples
  253. this project publishes against itself.
  254. </details>
  255. <details>
  256. <summary><b>Where those savings compound: an orchestrator that matches tasks to models — every lane it spawns starts cold on the same tree.</b> The map is the one artifact that does not have to be rediscovered per agent, and the quality verbs hand a verdict back instead of a pile of files to re-read</summary>
  257. The shape: plan the work, then run a loop that matches each task to the model that fits it. Every
  258. thread it spawns opens with an empty context on a repository it has never seen. **Orienting an empty
  259. context to a large repository is the most repeated cost in the whole system, and the one this tool
  260. was built for** — it is also the cost that grows with the size of the tree, which is why the pattern
  261. matters more the bigger the repository gets.
  262. `--for` and `--pack-task` answer it in a single call, at the per-call rates in the table above,
  263. instead of a grep-and-read tour that every lane pays over again from scratch.
  264. The return path matters as much. `--quality-delta`, `--test-gate` and `--edit-check` answer *what did
  265. I make worse*, *which tests must run*, *did I change a contract* — quantitative answers a lane can
  266. hand back as a verdict, rather than a transcript the orchestrator has to read to find out what
  267. happened.
  268. **What is and is not claimed here.** Every figure on this page is a single-agent measurement. That
  269. the saving compounds with the number of cold orientations follows from the fixed-cost mechanism, but
  270. it is pre-registered and **unrun** — the reason the pattern is worth trying, not a result this
  271. project has published.
  272. </details>
  273. ### See the map — not just the numbers
  274. <p align="center"><img src="docs/assets/graph-cx.png" alt="ripwire --html on Django's migration autodetector: 120 symbols, 183 call edges, arrows pointing caller to callee, nodes coloured by cyclomatic complexity on a five-stop scale running deep blue, mid blue, amber, orange, pale yellow, module outlines drawn as translucent regions, and low-confidence call edges drawn with dashed shafts" width="880"></p>
  275. <p align="center"><sub><b>Django's migration autodetector, coloured by complexity.</b> Thresholds are fixed, so the colour means the same thing on every repo you point it at.</sub></p>
  276. ```bash
  277. ripwire path/to/django/db/migrations --rank-by=rrf --top-k=120 --color-by=cx --html=map.html
  278. ```
  279. <table>
  280. <tr>
  281. <td width="50%"><img src="docs/assets/graph-lens-cx-churn.png" alt="The same graph twice: above coloured by cyclomatic complexity, below by git commit count. Most nodes sit in a different colour band between the two." width="430"></td>
  282. <td width="50%"><img src="docs/assets/graph-uncertainty.png" alt="A close crop showing solid and dashed call edges side by side; dashed shafts mark calls the resolver could not pin to a single target" width="430"></td>
  283. </tr>
  284. <tr>
  285. <td><sub><b>The same graph, re-coloured by git churn.</b> 76% of these nodes move to a different band — structure and history disagree, and one run shows you both.</sub></td>
  286. <td><sub><b>A dashed shaft is a guess.</b> 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.</sub></td>
  287. </tr>
  288. </table>
  289. <details>
  290. <summary>How to read these pictures — the five lenses, the fixed thresholds, and what the renderer refuses to draw</summary>
  291. One 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.
  292. Read from the figures above, which state their own rules in a sidecar saved beside each image:
  293. - **arrow points caller → callee** — the graph is directed, and the page draws it that way.
  294. - **`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.
  295. - **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.
  296. - **shapes: ● fn ■ cls ✚ var** — kind is nominal data on a nominal channel; complexity never uses shape.
  297. - **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.
  298. The `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.
  299. `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.
  300. </details>
  301. One deterministic answer: the relevant symbols, their callers, the change risks, and
  302. the tests that reach them. The task is yours to phrase — ask about *your* code, not ours. Run on this
  303. repository (2026-08-30), `ripwire . --for="incremental cache invalidation"` produced about 4.3K
  304. estimated tokens, not an enforced token budget. It includes:
  305. *This is what the output looks like, not the token-savings recipe.* A bare `--for` on every question
  306. is the most expensive way to use this tool — see [Where it pays most](#where-it-pays-most-and-where-it-does-not)
  307. and the three controls below it.
  308. <details>
  309. <summary>What those <b>4.3K tokens</b> actually contain — ranked symbols with their doc comments quoted in place, risk annotated on every row, one-hop callers, and the answer's own <code>confidence=</code></summary>
  310. - **The ranked symbols, in rank order** — the cache-header constant `kCacheMagic` first (with its doc
  311. comment quoted in place and the one `next=` call that opens it), then `spanTierMemoPath` (the
  312. cache-path composer), `ingestCommitTree`, … `ingest` — each row with its file, line, and signature.
  313. - **Risk, annotated in place** — complexity, git churn (`ingest` shows 128 recent edits),
  314. change amplification (touch `ingest` and 266 graph nodes feel it), purity and test coverage. The
  315. fragile spots are visible *before* anything touches them.
  316. - **One-hop call context** — `spanTierMemoPath` calls `shaKeyedCachePath`, `headSnapRepoHex`,
  317. `exclConfigHex`; no second query needed to see the neighbourhood.
  318. - **Its own confidence** — this answer says `confidence="high"` with the score margin attached; a
  319. flat ranking says `low`, so it reads as a starting point instead of masquerading as an answer.
  320. `confidence=` measures how clearly the ranking separates its head from the rest, not whether the
  321. head is what you meant: ask a repository about a concept it does not contain and the best lexical
  322. matches still rank, confidently. Phrase the task in your code's own words.
  323. </details>
  324. <details>
  325. <summary>The actual wire format — what your agent reads (minified XML; trimmed and line-wrapped here)</summary>
  326. ```xml
  327. <ctx task="incremental cache invalidation" confidence="high" margin_pct="20"
  328. bundle="compact" bodies="0" reason="compact-route" est_tokens="3995">
  329. <sigs shown="23" total="40" capped="1">
  330. <d l="106" n="kCacheMagic" p="src/ingest_cache.h" cx="0" in="0" churn="11" amp="71" pure="1" r="1"
  331. next="--expand=src/ingest_cache.h:kCacheMagic">
  332. <doc>incremental cache (--cache): per-file content hash + raw facts so a
  333. re-run re-parses ONLY …</doc>constexpr std::uint32_t kCacheMagic = …</d>
  334. <d l="1307" n="spanTierMemoPath" p="src/ingest_astquery.h" cx="1" in="2" churn="5" amp="44" r="2"> … </d>
  335. <d l="247" n="ingestCommitTree" p="src/dmm.h" cx="6" in="1" churn="6" amp="27" r="3"> … </d>
  336. …
  337. <d l="191" n="ingest" p="src/ingest.cpp" cx="4" in="14" churn="128" amp="266" tested="1" r="13"> … </d>
  338. … </sigs>
  339. <hops shown="2" total="6" capped="1" noedge="2">
  340. <h l="1307" p="src/ingest_astquery.h" n="spanTierMemoPath">
  341. <calls total="3"><c n="shaKeyedCachePath" l="1621"/> … </calls></h> … </hops>
  342. </ctx>
  343. ```
  344. `cx=` complexity, `churn=` git edit frequency, `amp=` change amplification, `r=` rank; `<hops>` rows
  345. carry the one-hop call context, caps disclosed. The one legend at the top of the real output defines
  346. them — tersely by default, every reading in full with `--legend=full` — and the root self-reports the
  347. bundle's cost — `est_tokens="3995"` here.
  348. </details>
  349. | The agent without a map | The agent with ripwire |
  350. | --- | --- |
  351. | 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) |
  352. | reads whole files to find the symbols that matter | those symbols, with complexity, churn and test coverage inline |
  353. | finds the callers only if it thinks to grep for them too | callers, blast radius and the tests to run, in the same bundle |
  354. | pays for every line it read, right or wrong | **5.0%** of what that grep-and-read pass spends — on a 12-question set where it strictly satisfied **5** to the naive arm's **11** (re-derived 2026-08-23) |
  355. **Both halves of that sentence, because one without the other is an overclaim.** The 5.0% is context
  356. compression, not equal task completion: on the five questions *both* arms strictly satisfied, ripwire
  357. spends **5.2%** of what the naive pass spends. Cheap context that answers less is not a saving if the
  358. agent then retries. The full adjudication, the four ranking defects behind the eleven-to-five gap, and
  359. the run where this number got **worse** are in [Measured](#measured).
  360. <details>
  361. <summary><b>58.3%</b> of instances with <b>all</b> gold files in the top 10 — the best alternative lands <b>40.0%</b>, while indexing in <b>0.31 s</b></summary>
  362. And against five retrieval competitors on a held-out LocBench slice, it finds **all** gold files in
  363. the top 10 on **58.3%** of instances — the best alternative lands 40.0% — while indexing in 0.31 s.
  364. [The full leaderboard, losses included ↓](#graph-ranked-retrieval-it-finds-the-right-files-more-often-than-the-alternatives)
  365. </details>
  366. ### Against the leading graph-database code-context MCP server
  367. **Won 27 · lost 7 · tied 14** on 48 matched questions across django, webpack and this repository,
  368. spending **~77K tokens against its ~486K** for the whole sweep.
  369. <details>
  370. <summary>The full result, how it was measured, and where ripwire still loses</summary>
  371. The 48 questions span symbol lookup, conceptual search, blast radius, and one-call task orientation.
  372. ripwire indexes the same three repositories in 0.25–0.45 s and 6.6–16.5 MB, against that server's
  373. 23–52 s and 391–623 MB, and answers a warm query in a median 197 ms against its 1,082 ms. Its seven
  374. wins are real and named one by one in the method.
  375. Both arms warm with a pre-built index, median of 3 timed calls, stdout to a file rather than a pipe.
  376. The competitor ran in its stronger retrieval configuration; its numbers were recorded once and then
  377. frozen, and ripwire's side was re-run after the fixes the first pass produced. Per class, as a share
  378. of the competitor's bytes on totals: symbol lookup **1.35×**, conceptual search **1.23×**, blast
  379. radius **0.39×**, task orientation **0.06×**.
  380. Where it loses: on a plain one-symbol lookup the competitor answers in about a kilobyte carrying
  381. callers and callees, and ripwire spends roughly three times that to also hand back the body. It
  382. ranks a chunk-id plugin first on one webpack query where ripwire never surfaces the directory at
  383. all — a ranking miss, and a fix for it was built, met its pre-registered band, and was reverted
  384. anyway for failing a separate standing requirement. Its depth-labelled blast radius and its import
  385. edges are both better presentations than ripwire's flat reaching-set.
  386. Full method, pins, per-class tables, the carried-versus-re-judged ledger, and the complete list of
  387. what the competitor does better:
  388. [`docs/EVALS.md` §2](docs/EVALS.md#2-head-to-head-against-other-tools).
  389. </details>
  390. <details>
  391. <summary><b>Nothing it is unsure about reaches your agent unlabelled</b> — unindexed languages named in the map's first line, a parse-health row on any file it cannot vouch for, every skipped file itemized with its reason</summary>
  392. **Nothing it is unsure about reaches your agent unlabelled — and nothing it could not see goes
  393. unnamed.** Every guess is marked in the output, and every mark has a next step — up to handing it a
  394. compiler-grade index. Point it at a repository whose main language it has no grammar for and the
  395. map's first line says so (`unindexed="ml:793,mli:607,…"` on a facebook/infer clone); a file it
  396. indexed but cannot vouch for carries a parse-health row; every file the crawl passed over is
  397. itemized with its reason. A confident-looking map that lies by omission is the failure mode this
  398. tool refuses.
  399. </details>
  400. [What it misses, and what to run next →](#what-it-misses-and-what-to-run-next)
  401. ### Graph-Ranked Retrieval: It finds the right files more often than the alternatives
  402. <details>
  403. <summary><b>58.3% against 40.0%</b> for the best tool tested, and it answers before they finish indexing — N = 60 paired, zero exclusions, every arm re-run on one day</summary>
  404. **58.3% against 40.0% for the best tool tested — and it answers before they finish indexing.** Every
  405. arm below was re-run in full on 2026-08-08 — one ripwire binary (the profile-guided release build
  406. that now ships), one evaluator, one 60-instance held-out LocBench slice: paired, zero exclusions,
  407. same gold set, and the metric code imported unmodified into every arm. *Strict file@10 = **all** gold files inside the top 10*, which is whether
  408. your agent starts in the right place at all.
  409. </details>
  410. | Round 4 — LocBench, Python-dominant | strict file@10 | any@10 | index (median) | query (median) |
  411. | --- | --- | --- | --- | --- |
  412. | **ripwire `--for`** | **58.3%** | **85.0%** | **0.31 s** | 0.108 s |
  413. | codebase-memory-mcp 0.9.0 | 40.0% | 63.3% | 1.24 s | 0.075 s |
  414. | repowise 0.37.0 | 33.3% | 53.3% | 34.0 s | 1.159 s |
  415. | graphify 0.9.34 | 31.7% | 46.7% | 7.82 s | 0.614 s |
  416. | Aider repo-map 0.86.2 | 20.0% | 35.0% | *(inside query)* | 2.920 s |
  417. | codeseek 0.1.31 (better of its two arms) | 15.0% | 20.0% | 3.37 s | 0.040 s |
  418. *Measured 2026-08-08, before the performance work that ships in 0.6.0. ripwire has become faster since — llvm-project's cold parse (182,555 files) fell from 194.1 s to 155.6 s of CPU, and `--pack-task` on a Go repository from 8.13 s to 5.88 s — but these timing columns have not been re-measured.*
  419. <details>
  420. <summary>What this table costs us — six paired losses named, a runner-up we had under-credited at <b>26.7%</b> and corrected to <b>40.0%</b>, and the multi-file stratum no arm solves</summary>
  421. Ripwire leads every arm on both accuracy metrics and in both strata. Paired, the losses are small and
  422. they are published: **2** instances to codebase-memory-mcp, **2** to repowise, **1** each to graphify
  423. and aider. **Cold from nothing to an answer — parse, rank, reply, no cache — ripwire takes 0.213 s**,
  424. against a ~35 s index-then-query for repowise; its worst single index in this run was **352 s**.
  425. Three things this table costs us, said plainly. **codebase-memory-mcp is the real runner-up at 40.0%,
  426. not repowise** — an earlier round credited it with 26.7%, and re-running it fairly raised it. The
  427. margin over the best competitor is therefore **1.46×**, not the 1.75× two separately-dated tables used
  428. to imply. And **multi-file gold is hard for everyone**: ripwire leads the stratum at 21.4% strict, but
  429. its own any@10 there is 78.6% — it finds *a* gold file and misses the siblings, and no arm in this
  430. table solves that.
  431. Held out wider — **243 instances across 78 repositories** — ripwire lands **60.9%** against **27.6%**
  432. for its own pre-routing baseline: **+33.3pp** paired, clustered-bootstrap 95% lower bound **+25.0pp**,
  433. bought for +3.4% warm latency and **−39.4%** tokens. Full provenance, the losing instances one by one,
  434. and a third round against a compression-layer competitor: [Measured](#measured) and
  435. [`bench/headtohead/r4-2026-08-06/`](bench/headtohead/r4-2026-08-06/), whose harness is committed so
  436. anyone can re-run the whole comparison.
  437. Test scaffolding does not pollute the ranking from inside source files either: `#[cfg(test)] mod
  438. tests`, `describe()` blocks, `Test*` classes and `[Fact]` attributes are detected syntactically,
  439. wherever they live — not by file path alone. On an astral-sh/ruff clone (5,945 files),
  440. `--ignore-tests` removes **23,907** test symbols where path rules alone caught 18,532
  441. (`ripwire <ruff> --ignore-tests`, 2026-08-14; the per-language fixtures are pinned by
  442. `test/testscopecheck.sh`).
  443. </details>
  444. ---
  445. *The table above, read two other ways. Every figure in both is one of its measured numbers; only the
  446. manners and the cynicism are editorial. Should the reader find the manners excessive, the author begs
  447. them to recall that the alternative was a second table.*
  448. <details>
  449. <summary>📖 &nbsp;<b>The same table, as narrated by Jane Austen</b></summary>
  450. <br>
  451. *A Survey of the Neighbourhood's Eligible Instruments — being an account of five gentlemen of
  452. retrieval, and one lady of no pretension whatsoever.*
  453. It is a truth universally acknowledged, that an engineer in possession of a large repository must be
  454. in want of a map.
  455. **Mrs. Codebase-Memory** must be named first, for she has risen a great deal in the estimation of the
  456. neighbourhood — two-fifths of her answers entirely correct, which is more than any other caller can
  457. say, and she is ready in a second and a quarter. It must nevertheless be recorded that her card
  458. announces accomplishments in the semantic line; that upon enquiry the semantic line is not at home;
  459. and that the household denies all knowledge of it. One is left with the impression of a capable woman
  460. ill-served by whoever prints her cards.
  461. **Mr. Repowise** is by common consent the most substantial of the party, and no one who has waited
  462. upon him would dispute it. He is possessed of a handsome index and a manner of great thoroughness;
  463. but he must be *seen to*. One does not simply address Mr. Repowise. One sends word, and dresses, and
  464. waits — three-and-thirty seconds on an ordinary morning, and upon one memorable occasion in the
  465. country, seven minutes and four seconds — during which interval a less consequential neighbour has
  466. answered the question, taken her leave, and thought no more about it. He answers creditably when at
  467. last he arrives, one time in three; whether that is worth the toilette, each family must determine
  468. for itself.
  469. **Mr. Graphify** enjoys a great many admirers. He does not rank his acquaintances; he calls upon them
  470. in whatever order his walk happens to take him, and reports the order of the walk as though it were
  471. an opinion. He has been known to arrive carrying a hundred and thirty megabytes of correspondence.
  472. Pressed once for any answer at all, he replied that no matching nodes were found, and considered the
  473. matter closed.
  474. **Mr. Aider** is the most gentlemanly of the company and by far the most difficult to consult. He
  475. cannot be asked a question — the thing is simply not done. One may mention names in his hearing and
  476. hope he takes the hint; he does take it, and is fully ten points the better for it, which says more
  477. about the hint than about Mr. Aider. But he forms his view of the neighbourhood before you speak and
  478. retains it after, and one cannot escape the feeling that the conversation was never truly with you.
  479. **Mr. Codeseek** is a young gentleman of quick habits who suffers from an affliction of address.
  480. Speak to him plainly, in the language of ordinary complaint, and he will regard you with perfect
  481. composure and say nothing whatever — nothing, upon sixty occasions out of sixty. Name a person
  482. precisely as that person is named, and he grows animated directly. It is not stupidity; it is a want
  483. of imagination in the matter of introductions.
  484. And there is **ripwire**, of whom nothing is said in the drawing rooms, because she has already gone
  485. home. She was asked; she answered, in thirteen hundredths of a second; every gold file within the
  486. first ten, in eight-and-fifty cases of the hundred. She keeps no establishment, corresponds with no
  487. distant authority, and has never once been indexed at a party. Mr. Repowise finds her abrupt.
  488. She is.
  489. <sub>Every figure above is a measured number from the round-4 table on this page: the index medians
  490. (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
  491. 0-results-on-60/60 fallback arm, the absent <code>semantic_query</code> tool, graphify's 129 MB
  492. largest graph and its 1-of-60 empty ranking, aider's +10 pp personalization delta, and ripwire's
  493. 0.108 s / 58.3%. Provenance in <a href="bench/headtohead/r4-2026-08-06/">bench/headtohead/r4-2026-08-06/</a>
  494. and <a href="docs/EVALS.md">docs/EVALS.md</a>; only the manners are editorial. These are other
  495. people's real work, and the joke is aimed at the trade-offs, never at the authors.</sub>
  496. </details>
  497. <details>
  498. <summary>🕵️ &nbsp;<b>The same table, worked as a case file</b> — a private eye who trusts no index he didn't build himself</summary>
  499. <br>
  500. *The Long Index — in which a man asks six informants one simple question, and only one of them has
  501. the decency to answer it.*
  502. It was a million lines of somebody else's mistakes, and I needed one file out of it before the coffee
  503. went cold. So I did what you do. I went and talked to the people who say they know the neighborhood.
  504. **Codebase-Memory** had the best record in the room and she knew it — two answers right out of every
  505. five, handed over in a second and a quarter, which in this business is practically a kindness.
  506. Trouble was the card. Right under her name it said *semantic query*, real classy, real
  507. expensive-looking. I asked to see it. She said it wasn't in. I asked the house. The house had never
  508. heard of it. I've known a lot of good people ruined by whoever printed their cards.
  509. **Repowise** was the heavyweight — everybody told me so before I got through the door. Big index,
  510. good tailoring, thorough as a tax man. Only you don't just ask Repowise a question. You send word.
  511. You wait. Thirty-three seconds on a good day, and one bad morning out in the country, seven minutes
  512. and four seconds — long enough to get the same answer somewhere else, drive home, and forget his
  513. name. He came through one time in three. For some outfits that's worth the wait. I've got a
  514. metabolism.
  515. **Graphify** never met a fact he wouldn't hand you. Ask him one thing and he turns up with a hundred
  516. and twenty-nine megabytes of everything, unsorted, in whatever order he tripped over it — and he'll
  517. report that order like it's a considered opinion. It isn't. Leaned on him once for anything at all;
  518. he looked me dead in the eye, said no matching nodes, and figured we were square.
  519. **Aider** was a gentleman, which is another way of saying you couldn't file a straight question into
  520. him in triplicate. Wouldn't be asked. You mention things, loud, and hope — and sure enough, drop the
  521. right names and he's ten points sharper, which tells you everything about the names and nothing about
  522. Aider. He'd made up his mind about the place before I opened mine, and kept it after. You never did
  523. feel the conversation was with you.
  524. **Codeseek** was young and had a condition. Talk to him like a human being — plain, tired, the way a
  525. man actually asks for help — and he'll look clean through you and say nothing. Sixty times out of
  526. sixty, nothing. But name the thing exactly, badge number and all, and the kid lights right up. It
  527. isn't that he's slow. He just never learned how people knock on a door.
  528. And **ripwire**. Nobody at the table brought her up, on account of she'd already left. Took the
  529. question, answered it in thirteen hundredths of a second — every file I needed inside the first ten,
  530. fifty-eight times out of a hundred — keeps no office, wires no head branch, never once got herself
  531. indexed at a party. Repowise says she's abrupt.
  532. She is. That's why I hired her.
  533. <sub>Every figure above is a measured number from the round-4 table on this page: the index medians
  534. (1.24 s, 3.37 s, 34.0 s), repowise's 352 s / six-minute worst case, the 40.0% and 33.3% strict
  535. file@10, codeseek's 0-of-60 plain-language arm, codebase-memory's advertised-but-absent semantic
  536. tool, graphify's 129 MB largest graph and its 1-in-60 empty return, aider's +10 pp name-drop delta,
  537. and ripwire's 0.108 s / 58.3%. Provenance in
  538. <a href="bench/headtohead/r4-2026-08-06/">bench/headtohead/r4-2026-08-06/</a> and
  539. <a href="docs/EVALS.md">docs/EVALS.md</a>; only the cynicism is editorial. These are other people's
  540. real work, and the joke is aimed at the trade-offs, never the authors.</sub>
  541. </details>
  542. ---
  543. <details>
  544. <summary><b>Name a symbol and it is the first hit</b> — routing lifts recall@1 <b>61.1% → 91.3%</b>; route <i>everything</i> to the name lane and prose queries collapse <b>0.967 → 0.016 MRR</b>. Both numbers ship together</summary>
  545. **Name a symbol and it is the first hit — and it is never a mystery which ranker answered.** Every
  546. `--for` query is served by one of three lanes; a confidence-gated router picks by reading the
  547. query's *shape*, discloses its choice on the output (`route=`), and `--no-route` overrides it.
  548. Routing lifts recall@1 on name-shaped queries **61.1% → 91.3%** in `src/`, **59.2% → 85.5%** at the
  549. repository root — and the gate is load-bearing in both directions: route *everything* to the name
  550. lane and prose queries collapse from **0.967 MRR to 0.016**. Both numbers ship together. Reproduce
  551. with `ripwire <dir> --eval-retrieval`, which grades EVERY doc-commented symbol in the corpus and
  552. prints its own `population=`/`scored=`/`rule=`; the full per-ranker tables are in
  553. [`bench/ANSWERQUALITY.md`](bench/ANSWERQUALITY.md#re-measured-2026-09-05--census-sampler-midrank-ties-the-current-numbers).
  554. </details>
  555. | Lane | Built for | Why it wins there | Where it loses |
  556. | --- | --- | --- | --- |
  557. | **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) |
  558. | **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) |
  559. | **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 |
  560. <details>
  561. <summary><b>How each lane finds things, and how the router picks — step by step</b></summary>
  562. <br>
  563. **How the conceptual lane finds what you didn't name.** The subtoken+body lane is why a query with
  564. no symbol name in it still lands:
  565. - **Both sides are split into subtokens.** `SplitChunksPlugin` becomes `split`+`chunks`+`plugin`, and
  566. so does your query — so words match *pieces* of names you never typed.
  567. - **Three evidence fields, not one.** A symbol is scored on its name subtokens, its doc comment, and
  568. its body — vocabulary that only exists in a comment or an implementation still finds its symbol.
  569. - **BM25 with per-query IDF.** Rare, discriminating words dominate the score; words the whole corpus
  570. shares contribute almost nothing. Type the three words only the right function uses and they carry
  571. the query.
  572. - **Lookalikes are down-weighted, not hidden.** Fixture, test-data, and generated paths score at a
  573. fraction, so a test vocabulary-twin cannot outrank the real source (adversarial-class pollution@5:
  574. 28% → 0%, `docs/EVALS.md` §4) — but they stay in the index and are still found when *asked for*.
  575. - **The list ends at a cliff, not a quota.** The cut is adaptive: output stops where the scores drop
  576. off, so a sharp answer is a short list and a diffuse one is disclosed as such, instead of a fixed
  577. top-k padding both.
  578. **How the router picks.** The gate is built on cheap, corpus-derived evidence, and its bias reflects
  579. an asymmetry the table above makes plain: a *missed* name-route costs a few ranks; a *false* one is
  580. catastrophic (0.016 MRR).
  581. 1. **Identifier shape is trusted outright.** A camelCase/snake token — or a short query carrying
  582. one — routes name-exact. Someone who types `chooseForRanker` is naming, not describing.
  583. 2. **The all-words test.** If *every* content word equals some symbol's whole name (`pack task`
  584. where both `pack` and `task` are real symbols), that is strong evidence of a name query.
  585. 3. **The plausibility test.** Present is not enough — each matched name must be *specific*: few
  586. definitions, and not a subtoken carried by half the corpus's symbol names (thresholds derived
  587. from the index itself, not a hardcoded stdlib list). This is what catches `split chunks`:
  588. every word names a symbol, but `split` names a String method defined everywhere — so the route
  589. is **declined** and the conceptual lane runs, which finds `SplitChunksPlugin` easily.
  590. 4. **Every decision is disclosed.** `route=` states the lane that ran; a decline names the anchor
  591. that failed and why. `--no-route` forces the conceptual lane when you disagree.
  592. The proof the gate earns its keep: the routed lane matches the *best* single lane on both query
  593. modes simultaneously — 0.960 MRR on names (equal to forced name-exact) and 0.967 on prose (within
  594. noise of pure subtoken+body, `src/`). No single lane does that.
  595. The honest boundary: the router classifies the query's shape — it cannot rescue vocabulary that is
  596. not in the index. A prose query whose concept lives only in a compound class name
  597. (`SplitChunksPlugin` contains no `splits` subtoken) is correctly sent to the conceptual lane, which
  598. then has little to grab; that gap is measured and recorded in
  599. [docs/EVALS.md §7](docs/EVALS.md), not hidden. Numbers re-derived 2026-08-08 on this tree;
  600. per-lane table and history in [docs/EVALS.md §4](docs/EVALS.md).
  601. </details>
  602. ### Saves Tokens: It answers for a fraction of the context
  603. <details>
  604. <summary><b>5.0%</b> of what a grep-and-read pass spends — <b>5.2%</b> on the questions both arms fully answered, and a dedicated context compressor run over the output saved <b>exactly 0 tokens</b></summary>
  605. On mid-task questions it had never seen, ripwire answers at **5.0%** of what a grep-and-read pass
  606. spends — **5.2%** on the questions both arms fully answered. `--pack-signatures` returns **74.7%
  607. fewer bytes** than full bodies at top-50 (re-derived on this tree, 2026-09-06). The output is already
  608. dense enough that running a dedicated context compressor over it saved **exactly 0 tokens**.
  609. </details>
  610. <details>
  611. <summary>Why both figures are printed — <b>7.3% → 5.0%</b> overall, but <b>1.7% → 5.2%</b> on the questions both arms answered</summary>
  612. Both of those first two figures moved when they were re-derived on 2026-08-23, and they moved in
  613. **opposite** directions — 7.3% → 5.0% overall, but 1.7% → 5.2% on the both-answered subset. Same
  614. frozen questions, same frozen verb ladders, same corpus pin, same tokenizer; the naive arm reproduced
  615. to the token. What changed is where ripwire spends: the compact conceptual route made its *misses*
  616. much cheaper, while richer default bundles made the questions it *answers* dearer. Both numbers are
  617. printed because printing only the one that improved would be the failure this project exists to not
  618. commit. The full per-question re-derivation is in the Round 3 note under [Measured](#measured).
  619. It is also cheap enough to call on reflex: this repository parses in **~0.15 s** cold and **~0.10 s**
  620. warm (`time ./build/ripwire . --no-cache`), so the agent asks instead of guessing.
  621. </details>
  622. ### Where it pays most, and where it does not
  623. <details>
  624. <summary><b>A map is a fixed cost paid once per context — strongest of all under an orchestrator that matches tasks to models: every lane it spawns starts cold on the same tree.</b> It pays again on the checking pass, and it <b>does not pay</b> on a question one <code>grep</code> already answers</summary>
  625. **A map is a fixed cost paid once per context, so it pays in proportion to what that context goes on
  626. to do with it.** Two shapes get the most out of it, and one gets nothing.
  627. - **Orienting a context that does not know the repository.** This is the strongest case, and it is
  628. strongest of all under an orchestrator that matches tasks to models: every lane it spawns starts
  629. cold on the same tree, and each one would otherwise re-derive the same structure from scratch. The
  630. map is the one artifact that does not have to be rediscovered per agent.
  631. - **The checking pass at the end.** `--quality-delta`, `--test-gate` and `--edit-check` answer
  632. questions — *what did I make worse, which tests must run, did I change a contract* — that an agent
  633. cannot answer by reading more source, at any budget.
  634. - **It does not pay on a question one `grep` already answers.** The map is charged whether or not it
  635. was needed, so a narrow lookup in a file you can already name is cheaper without it. `--help-task`
  636. exists to make that call, and a flat ranking says `confidence="low"` rather than pretending.
  637. </details>
  638. **Getting the saving takes three things, and a bare `--for` is none of them.**
  639. <details>
  640. <summary>The three controls that decide what it costs — <b>a budget</b> (<code>--token-budget</code> / <code>--top-k</code>), <b>routing</b> (<code>--help-task</code>), and <b>the skills</b> that teach an agent when <i>not</i> to reach for it</summary>
  641. 1. **A budget.** `--token-budget=N` caps the bundle; `--top-k=N` caps the rows **of the default map,
  642. `--query`, `--format=candidates`, `--recall` and `--graph-query` — it does not shape plain `--for`**.
  643. On `--for`, a *positive, explicit* `--top-k` is read by nothing: the run prints a stderr note
  644. (`--top-k is not read by --for`) and still emits the full bundle. Two neighbours of that shape are
  645. different and neither warns: `--for --format=candidates --top-k=N` *does* consume the flag (the
  646. candidate export composes with it and caps the rows), and `--for --top-k=0` is refused outright by the
  647. payload-only guard (`--top-k=0` needs a payload verb), not warned-and-emitted. Narrow plain `--for`
  648. with its own arguments instead — `--signatures-only`
  649. (drop the auto-bodies), `--token-budget=N` (shapes the bundle to fit), `--detail=N` (full bodies for
  650. just the top N). Unbudgeted `--for` returns
  651. a rich terminal bundle by design — right when it ends the question, wasteful when it does not.
  652. 2. **Routing.** `ripwire . --help-task="<task>"` names the ONE command the task actually wants, and
  653. abstains when the evidence is thin. It is advice, it never runs anything. An answer of "just grep
  654. for it" is a correct answer and the tool will give it.
  655. 3. **The skills.** `skills/install.sh` teaches an agent *when* to reach for which verb. Without them
  656. an agent has 175 flags and no map of which moment each is for, and it will reach for the map every
  657. time — including the times it should not.
  658. </details>
  659. <details>
  660. <summary>The invocations first-time users get wrong — <b>WRONG → RIGHT</b>, each row a real failure reported from the field</summary>
  661. | WRONG | RIGHT | why |
  662. |---|---|---|
  663. | `ripwire . --for="…" --top-k=5` | `ripwire . --for="…" --signatures-only` (or `--token-budget=N`, `--detail=N`) | `--top-k` is inert on `--for`: the run warns on stderr and emits the full bundle anyway, so the agent *believes* it narrowed the output and did not. |
  664. | `ripwire . --query="…"` as the default lens | `ripwire . --for="…"` | `--query` is the raw BM25 ranking — the binary's own help calls it debug and says "use --for". It is the right tool for hunting a vocabulary, the wrong default for a task. |
  665. | `ripwire . --expand=SYM --top-k=0` (a habit from before the lean default) | `ripwire . --expand=SYM` | `--expand` and `--outline` ship no ride-along map whenever every definition asked for is served — one exact match or an ambiguous bare name alike (disclosed as `topk_default="0"`, with `map_next=` naming the call that prints the map if you never oriented). Definitions a byte budget cut are named in `unserved_total=` / `unserved_next=`. An explicit `--top-k=N` still brings the map back. |
  666. | `--callers=<route handler>` expecting routes | find the URL in the project's own docs (e.g. a feature map), then `--expand` the handler | Framework route handlers have no callers in the graph — the decorator reaches them, not project code. Empty `--callers` on a handler is the design, not a bug. |
  667. | `ripwire <dir-of-repos> …` (ONE root that happens to contain checkouts) | `cd` into ONE checkout first | Nothing refuses this: the crawl silently walks the nested repos and merges them into one corpus, so you pay for a map of everything and rank across unrelated codebases. Distinct from the real multi-root feature, which is N **explicit** positional roots (`ripwire dir1 dir2 … <verb>`, 2–16 checkouts merged on purpose). |
  668. **What ripwire does not replace** — reach for `grep`/`read` here even when a verb looks close:
  669. | still use grep/read for | why |
  670. |---|---|
  671. | route → handler lookup from a URL | ripwire ranks symbols, not URLs; it does not know your routes |
  672. | templates, i18n catalogs, SQL migrations | not call-graph territory |
  673. | one exact string in one file you can already name | `--grep=TERM` works, but `rg` is fine too — and the map is a fixed cost you did not need |
  674. | UX flow through frontend event handlers | the JS is in the graph, but the flow needs line context, not a ranking |
  675. </details>
  676. <details>
  677. <summary><b>What is measured and what is not</b> — these are single-agent figures; that the saving grows with the number of cold orientations is pre-registered and <b>unrun</b>, not a published result</summary>
  678. **What is measured and what is not.** The per-question figures above and in [Measured](#measured) are
  679. single-agent measurements. That the saving grows with the number of cold orientations follows from the
  680. fixed-cost mechanism but is **not a published result** — it is pre-registered and unrun. Treat the
  681. single-agent numbers as the measured ones.
  682. </details>
  683. ### Better Code: It automates the review judgments nobody has time to make — every lens from published research
  684. <details>
  685. <summary><b>Six independent evidence families</b>, each implementing published work — the largest correlation between any two is <b>+0.168</b>, which is what makes agreement corroboration rather than one metric counted twice</summary>
  686. `--quality-panel` runs the calls a good reviewer makes by hand — is this function too tangled, is it
  687. named badly, does it hide control flow inside an idiom, does its history say it keeps breaking, must
  688. you read five other files to follow it, does it mutate state three hops away — as **six independent
  689. evidence families**, and ranks by how many of them *agree*, never as one blended score. Each family
  690. implements published work — McCabe on shape, Butler on naming, Gopstein's atoms of confusion on
  691. idiom, Nagappan & Ball on churn, Beck & Diehl on colocation, Henry & Kafura on state — with the
  692. lesson taken from each paper, and the rules measured and *withdrawn*, in
  693. [`docs/LINEAGE.md`](docs/LINEAGE.md). Pooled over five corpora (n = 27,889) the largest correlation
  694. between any two families is **+0.168**: they really are measuring different things, so two families
  695. firing on the same function is corroboration rather than one metric counted twice.
  696. </details>
  697. <details>
  698. <summary>Why this matters most for code an agent wrote — empty-catch masking <b>+47%</b>, rewritten-within-two-weeks <b>+15%</b>, and reuse declining</summary>
  699. That matters most for code an agent wrote. Empty-catch error masking is **+47%** more common in
  700. AI-authored commits, a function rewritten again inside two weeks **+15%** more likely, and reuse is
  701. *declining* as AI's share of commits grows (GitClear, *AI Copilot Code Quality*, 2026). Ten of
  702. `--quality-delta`'s 12 kinds each target one measured mode like those (the eleventh, `placeholder`,
  703. lists the stubs and TODOs a change adds, and never gates; the twelfth, `defect-shape`, catches four
  704. defect shapes review kept finding by hand —
  705. new-symbol rows never gate, except defect-shape format-arity and a new function at the ceiling,
  706. because a format/argument mismatch is a defect, not debt, and a new function at 4x the bar — ccx 60 or 240 lines —
  707. is how a 1,000-line function starts), and it reports **only what your
  708. change made worse** — then `--exemplar` shows the pattern in your own repo to copy, and `--test-gate`
  709. names the tests that must run before "done."
  710. </details>
  711. <details>
  712. <summary>Reproducing all of it — dated, sourced measurements in <code>docs/EVALS.md</code>, each with its instrument, its corpus and its counterexamples, because the losses ship beside the wins</summary>
  713. Tree-local numbers above are reproducible with the commands shown; the rest are dated, sourced
  714. measurements in [`docs/EVALS.md`](docs/EVALS.md) — each with its instrument, its corpus, and its
  715. counterexamples, because the losses ship beside the wins. Zero runtime dependencies, C++23, builds
  716. with the network off.
  717. </details>
  718. Built for **Codex, Claude Code, Cursor, Windsurf, Gemini, opencode, aider**, and any agent that can
  719. call a CLI.
  720. <details>
  721. <summary><b>What comes back</b> — real output from this repository, pretty-printed and trimmed (re-captured 2026-09-05; rows are served in rank order, each naming its file)</summary>
  722. ```xml
  723. <ctx task="incremental cache invalidation" route="subtoken+body" confidence="high" margin_pct="20"
  724. bundle="compact" bodies="0" reason="compact-route" est_tokens="3995">
  725. <sigs shown="23" total="40" capped="1">
  726. <d l="106" n="kCacheMagic" p="src/ingest_cache.h" cx="0" ccx="0" in="0" churn="11" amp="71" pure="1" r="1"
  727. next="--expand=src/ingest_cache.h:kCacheMagic"><doc>incremental cache (--cache): per-file content hash + raw facts so a re-run re-parses ONLY c…</doc>constexpr std::uint32_t kCacheMagic = 0x4b505443</d>
  728. <d l="1307" n="spanTierMemoPath" sc="rw" p="src/ingest_astquery.h" cx="1" ccx="0" in="2" churn="5" amp="44" r="2"><doc>Composed exactly the way every OTHER blob family is (quality.h): one fixed-width identity hex pe…</doc>inline std::string spanTierMemoPath( const std::string&amp; diskPath )</d>
  729. <d l="247" n="ingestCommitTree" sc="rw::dmm" p="src/dmm.h" cx="6" ccx="5" in="1" churn="6" amp="27" r="3"><doc>Ingest the tree at `sha`, materialized out of `root`&apos;s object store. …</doc>inline bool ingestCommitTree( const std::string&amp; root, const std::string&amp; sha, … )</d>
  730. <d l="841" n="mcpRefreshedThisRequest" sc="rw" p="src/mcpindex.h" cx="1" ccx="0" in="2" churn="20" amp="43" r="4"><doc>P1-15 — the `_reingest` envelope field for a response whose handling ran an INCREMENTAL pass, …</doc>inline bool mcpRefreshedThisRequest( std::uint64_t passesAtEntry )</d>
  731. …
  732. </sigs>
  733. <hops shown="2" total="6" capped="1" noedge="2">
  734. <h l="1307" p="src/ingest_astquery.h" n="spanTierMemoPath">
  735. <calls total="3"><c n="shaKeyedCachePath" l="1621"/><c n="headSnapRepoHex" l="1359"/><c n="exclConfigHex" l="1554"/></calls>
  736. </h>
  737. <h l="247" p="src/dmm.h" n="ingestCommitTree">
  738. <calls total="10" shown="7" capped="1">…</calls>
  739. </h>
  740. </hops>
  741. </ctx>
  742. ```
  743. The cache cluster, ranked and annotated in place: `cx`/`ccx` complexity, `in` reuse count, `churn`
  744. recent commits, `amp` change amplification, `tested` coverage — the fragile spots are visible
  745. *before* the agent touches them, in a few thousand tokens (`est_tokens="3995"`, self-reported in the
  746. header) instead of five whole files. This is a *conceptual* query, so the bundle is the **compact**
  747. shape: the ranked map plus one-hop callee edges, no inline bodies, and the root says so rather than
  748. leaving you to notice. Read the map, then `--expand=SYM` the one you want — or pass `--auto-bodies`
  749. to get bodies inline as before.
  750. </details>
  751. <details>
  752. <summary><b>What the quality panel shows</b> — real output from this repository, trimmed (legend comment elided)</summary>
  753. ```xml
  754. $ ripwire . --quality-panel --limit=1
  755. <quality_panel preset="default" families="6" enabled_n="6" cut="2" eligible="6497" ranked="524" …>
  756. <s p="src/graph.h:723" n="buildGraph" fam="4" of="6" fired="structural,confusion,historical,colocation">
  757. <e f="structural" counted="1" why="ccx=764 loc=1368 nest=8 humps=34 deep=315 ev=98 rrank=1"/>
  758. <e f="confusion" counted="1" why="atom-embedded-crement*4"/>
  759. <e f="historical" counted="1" why="hrank=12 churn=36"/>
  760. <e f="colocation" counted="1" why="crank=32"/>
  761. </s>
  762. …
  763. </quality_panel>
  764. ```
  765. Four of six independent evidence families corroborate on `buildGraph`, each with its own reason
  766. shown inline — never a single blended score. `eligible="6497"` narrows to `ranked="524"` (2-of-6
  767. agreement): an **8.1%** shortlist of this repository's own functions, not a guess (re-derived
  768. 2026-08-23 — the corpus grew, the shortlist share did not move). Full six-family breakdown, real
  769. numbers per family → [The quality panel](#the-quality-panel) below.
  770. </details>
  771. Full retrieval tables — including the MRR figures behind the router numbers above — in
  772. [`bench/ANSWERQUALITY.md`](bench/ANSWERQUALITY.md) and [Measured](#measured).
  773. <p align="center">
  774. <a href="present/ripwire-showcase.pdf"><img src="docs/assets/showcase-preview.png" alt="Three slides from the ripwire showcase deck: the head-to-head table, the ten-moments token table, and the quality-panel calibration" width="880"></a>
  775. </p>
  776. <p align="center">
  777. <a href="present/ripwire-showcase.pdf"><b>▶ The whole tool in 39 slides</b></a> — every figure names the instrument that pins it<br>
  778. <sub>renders in your browser · <a href="present/ripwire-showcase.pptx">pptx</a> beside it · <a href="docs/EVALS.md">the numbers behind it</a></sub>
  779. </p>
  780. [What it answers](#what-it-answers) · [Quickstart](#quickstart) ·
  781. [The quality panel](#the-quality-panel) · [Benchmarks](#measured) ·
  782. [Honesty contract](#the-honesty-contract) ·
  783. [Agent setup](#set-it-up-in-your-coding-agent) · [Docs](#documentation)
  784. ---
  785. ## What it answers
  786. <details>
  787. <summary><b>195 long flags</b> across seven families, plus the MCP server — and <code>--help-task</code> names the ONE command a task wants, or abstains honestly when the evidence is too thin</summary>
  788. Around the core sit 195 long flags advertised in `--help`, across seven families — plus an MCP
  789. server, so a coding agent can call any of them mid-task instead of grepping and reading whole files.
  790. `--help` prints one line per flag (~4.5K tokens); `--help=--FLAG` prints that flag's full entry with
  791. every caveat, `--help=SECTION` one family, and `--help=all` the whole catalog.
  792. Not sure which of them fits the task in front of you? `ripwire . --help-task="<task in words>"`
  793. recommends ONE executable command with the evidence behind the pick — advice only, it never runs
  794. the recommendation — and abstains honestly when the evidence is too thin to name a winner.
  795. </details>
  796. <details>
  797. <summary>Which surface is the authority — <code>--help</code> vs <code>docs/COMMANDS.md</code> — and the four reflex verbs worth memorising</summary>
  798. `./build/ripwire --help` is generated from the binary's own flag table and is always the authority;
  799. [`docs/COMMANDS.md`](docs/COMMANDS.md) documents every one of the 176 documented flags — 162 of them
  800. with a real invocation and its recorded output (both counts are reported by the generator that writes the
  801. document, `docs/docs_commands_build.py`, and were re-derived from it on 2026-09-14;
  802. `test/docscommandscheck.sh` fails if that documented set and the binary's own flag table ever disagree). Each family below links there.
  803. Four reflexes worth wiring into muscle memory: `--from-trace=FILE` for an error you have in hand,
  804. `--edit-check=SYM` right after an edit (did the contract change, and which callers are now provably
  805. incompatible), `--merge-scout=REF1,REF2` before landing parallel branches, and `--pack-task="…"` for
  806. ranking, bodies, callers and tests in one budgeted bundle.
  807. </details>
  808. | Family | The question | Representative flags |
  809. | --- | --- | --- |
  810. | [**understand a codebase cold**](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` |
  811. | [**navigate / answer a question**](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` |
  812. | [**zoom the detail ladder**](docs/COMMANDS.md#zoom-the-detail-ladder) | "Show me more — but only where it pays." | `--detail` · `--pack-signatures` · `--outline` · `--expand` · `--compress` |
  813. | [**assess quality / structure**](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` |
  814. | [**self-diagnosis**](docs/COMMANDS.md#self-diagnosis) | "Is my setup actually working?" | `--doctor` |
  815. | [**security**](docs/COMMANDS.md#--scan-skillsdir) | "Is this agent skill file safe to install?" | `--scan-skill` · `--scan-skills` |
  816. | [**knobs / modes**](docs/COMMANDS.md#knobs--modes) | shape, format, cache, budget | `--json` · `--format` · `--mcp` |
  817. ---
  818. ## Quickstart
  819. <details>
  820. <summary><b>Prebuilt binary</b> — macOS on Apple silicon and Linux (arm64 / x86-64, built for <b>RHEL 8+</b>), SHA-256 verified, shipping <b>seventeen agent skills</b> the installer activates for every agent it detects</summary>
  821. **Prebuilt binary** — macOS (arm64; 0.6.1 is the last release with an Intel macOS binary, and an Intel Mac
  822. builds later releases from source) and Linux (arm64 / x86-64, built for **RHEL 8+**;
  823. every release is smoke-tested on a RHEL 9 userland before it publishes). Downloads the latest
  824. [GitHub Release](https://github.com/redhat-et/ripwire/releases), verifies its SHA-256, and installs
  825. to `~/.local/bin`. From v0.2.2 the release tarball also ships the seventeen agent skills, and the
  826. installer stages them under `~/.local/share/ripwire/skills` **and activates them for every agent it
  827. detects** (Claude Code, Codex), printing one line per agent saying what it did. Sixteen of the
  828. seventeen are for using the tool; the one about compiling ripwire itself (`ripwire-opt-remarks`,
  829. `audience: contributor` in its front matter) stays staged unless you pass `--contributor` to
  830. `skills/install.sh`. An agent that is not
  831. installed is never given a skills directory, hooks are never registered without an explicit `--hook`,
  832. and `RIPWIRE_NO_ACTIVATE=1` stages without activating for image builds. When no agent is detected the
  833. activation one-liner is printed instead:
  834. ```bash
  835. RIPWIRE_REPO=redhat-et/ripwire bash -c "$(curl -fsSL https://raw.githubusercontent.com/redhat-et/ripwire/main/scripts/install.sh)"
  836. export PATH="$HOME/.local/bin:$PATH" # not on PATH by default on macOS or most Linux shells; add it to your rc file
  837. ```
  838. </details>
  839. <a id="windows"></a>
  840. <details>
  841. <summary><b>Windows x64 (preview)</b> — a zip with <code>ripwire.exe</code> and the skills, no runtime to install first; a preview until Windows users confirm it</summary>
  842. **Windows x64 — preview.** From 0.6.3 each release carries `ripwire-<version>-windows-x64.zip` and its `.zip.sha256`.
  843. It is built with clang-cl against the static C runtime, so it needs no Visual C++ Redistributable, and like the Linux
  844. x64 binary it needs an x86-64-v3 (AVX2) CPU. CI unzips and exercises it on every train, including a byte-for-byte
  845. comparison of its output with Linux's, but no maintainer runs Windows, so treat it as a preview until Windows users
  846. report back. The exe is not code-signed. `Expand-Archive` does not pass the download's Mark-of-the-Web on to the
  847. files it extracts, so SmartScreen does not prompt for an exe unpacked this way; no prompt is not a verdict. In PowerShell:
  848. ```powershell
  849. $v = "0.6.10"; $a = "ripwire-$v-windows-x64"; $u = "https://github.com/redhat-et/ripwire/releases/download/v$v"
  850. Invoke-WebRequest "$u/$a.zip" -OutFile "$a.zip"; Invoke-WebRequest "$u/$a.zip.sha256" -OutFile "$a.zip.sha256"
  851. # extracts only when the SHA-256 matches; on a mismatch it throws and nothing is unpacked
  852. if ((Get-FileHash "$a.zip" -Algorithm SHA256).Hash -eq (Get-Content "$a.zip.sha256").Split(" ")[0]) { Expand-Archive "$a.zip" -DestinationPath "$env:LOCALAPPDATA\Programs" } else { throw "SHA-256 mismatch: do not run $a.zip" }
  853. $bin = "$env:LOCALAPPDATA\Programs\$a"
  854. [Environment]::SetEnvironmentVariable("Path", "$bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
  855. $env:Path = "$bin;$env:Path" # this window too; new windows read the user Path
  856. ripwire --version
  857. ```
  858. - **The hash check** passes because `-eq` ignores case: `Get-FileHash` prints upper-case hex and the `.sha256` file
  859. is lower-case. For a case-sensitive compare, use `.Hash.ToLower() -ceq`.
  860. - **Comparing two outputs in Git Bash:** use `cmp`. There `fc` is a shell builtin (it replays history) and compares
  861. nothing; the Windows tool is `fc.exe`, run as `MSYS_NO_PATHCONV=1 fc.exe /b a b` so `/b` is not rewritten as a path.
  862. - **Git for Windows** is needed for the git-history features (churn, `--situ`, the `git` row of `--doctor`) and for
  863. the skills installer. The map itself runs without it.
  864. - **`ripwire . --doctor`**: every row should read `ok="1"`. `binary-path` finds `ripwire` the way PowerShell does
  865. (`Path` in order, then `PATHEXT`). When it fails, `which=` names the `ripwire` that `Path` finds first, and
  866. `which_version=` is what that one prints for `--version`. `same_bytes="unknown"` means a copy could not be read;
  867. the row fails as unverified, so compare the two with `Get-FileHash`. The cache lives in `%LOCALAPPDATA%\Temp\ripwire-<uid>`
  868. (your `TEMP`). With `TMPDIR`, `TEMP` and `TMP` all unset, Windows' own temp-directory rule falls back to your profile
  869. folder, so the cache is `%USERPROFILE%\ripwire-<uid>`; the `cache-dir` row names the directory either way.
  870. - **Checking cache reuse:** in PowerShell `$env:RIPWIRE_CACHE_STATS=1; ripwire . > $null` (in Git Bash
  871. `RIPWIRE_CACHE_STATS=1 ripwire . > /dev/null`) prints one `cache-stats` line on stderr. Run it twice with no other ripwire build in between: `reparsed=0` and `reused=` equal to `files=` mean every
  872. file came from the cache. `warm_growths=` is a performance counter, not a reuse fact: it counts how often a worker
  873. thread's buffer had to grow, which depends on how the threads split the files, so it varies from run to run by design.
  874. - **Agent skills** (Claude Code, Codex): from Git Bash, in the unzipped folder, `bash skills/install.sh` (Claude Code)
  875. or `bash skills/install.sh --codex`. From PowerShell, name Git Bash by full path,
  876. `& "C:\Program Files\Git\bin\bash.exe" skills/install.sh`: a bare `bash` there is often WSL's
  877. (`C:\Windows\System32\bash.exe`), which installs into the WSL home, where Windows agents never look. Or copy them by hand in PowerShell:
  878. `New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Copy-Item -Recurse -Force "$bin\skills\ripwire-*" "$HOME\.claude\skills\"`
  879. (Codex reads `$HOME\.agents\skills`). `--hook` is untested on Windows, and `scripts/install.sh` (the curl installer) does not run there.
  880. </details>
  881. **Building it yourself needs CMake 3.24+ and a C++23 compiler, and nothing else installed first** —
  882. every dependency is vendored in-tree, so the build completes with the network off.
  883. ```bash
  884. git clone https://github.com/redhat-et/ripwire.git
  885. cd ripwire
  886. cmake -S . -B build && cmake --build build -j
  887. ./build/ripwire . # orient once: the ranked map of an unfamiliar repo (add --max-tokens=N only if your context is tight — it cuts the map and says so)
  888. ```
  889. <details>
  890. <summary>Why there is no download step — vendored grammars, the offline-build proof, the languages parsed, and putting it on <code>PATH</code></summary>
  891. **Or build from source.** Requirements: CMake 3.24+ and a C++23 compiler — that means clang 16+ /
  892. AppleClang 15+ (Xcode 15) / gcc 13+, and if your distro's CMake is older than 3.24,
  893. `pip install cmake` or `brew install cmake` gets a current one everywhere. Nothing else —
  894. tree-sitter's core, the grammars listed in [THIRD_PARTY.md](THIRD_PARTY.md) and the test framework are vendored under `third_party/deps`,
  895. so there is no download step and no package manager to satisfy. Prove that with the network off:
  896. add `-DFETCHCONTENT_FULLY_DISCONNECTED=ON` and the build still completes.
  897. Two builds, two jobs — pick by what you are doing:
  898. ```bash
  899. # building to USE it — the fast binary (Release implies LTO; scripts/pgobuild.sh adds PGO, what CI ships)
  900. cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release && cmake --build build-release -j
  901. # building to WORK ON it — plain configure, no build type (why that matters: the trap, under the fold below)
  902. cmake -S . -B build && cmake --build build -j
  903. ```
  904. See [Languages](#languages) for supported source and document formats.
  905. To put it on `PATH`, `./install.sh` builds and atomically installs the binary plus the matching
  906. `skills/` and `hooks/` assets into a detected prefix (Homebrew's if present, `~/.local` otherwise;
  907. override with `RIPWIRE_INSTALL_PREFIX`). Set `RIPWIRE_ACTIVATE_CODEX=1` to also refresh Codex's skill
  908. links and advisory hooks from that same staged version; activation is otherwise explicit.
  909. </details>
  910. Wiring it into your agent takes one more minute — `wrap` **prints** the recipe for your client, it
  911. never edits your config:
  912. ```bash
  913. ripwire wrap claude # prints the wiring: the CLI call first, `claude mcp add` as the alternative
  914. ripwire wrap --all # detect every installed agent, print each one's recipe
  915. skills/install.sh --codex # Codex CLI: the task-shaped skills that say when to query — and when to stop
  916. ```
  917. Four commands worth learning first:
  918. ```bash
  919. ripwire . # orient once: the ranked map of an unfamiliar repo (add --max-tokens=N only if your context is tight — it cuts the map and says so)
  920. ripwire . --for="incremental cache invalidation" # the task lens: what to touch, ranked
  921. ripwire . --callers=someFunction # who calls it
  922. ripwire . --test-gate # before you commit: which tests must run
  923. ```
  924. > **Written for your agent.** By default, every command prints compact XML sized for an AI agent to read, not for a person
  925. > scanning a terminal. Human-readable output is on the roadmap.
  926. <details>
  927. <summary>CLI or MCP, the <code>-DCMAKE_BUILD_TYPE=Release</code> trap, and the honesty contract in one line</summary>
  928. The CLI is the recommended baseline because it works in every shell-capable agent; the MCP server is
  929. optional, for agents whose workflow benefits from persistent tool registration. Full walkthrough,
  930. all six clients: [Agent setup](#set-it-up-in-your-coding-agent).
  931. > **The trap, spelled out:** never configure the *dev* tree (`build/`) with
  932. > `-DCMAKE_BUILD_TYPE=Release`. Release defines `NDEBUG`, which compiles the degrade-path alerts out
  933. > and blinds the gates that assert them — and every gate and bench number is measured against
  934. > `build/`, so changing that tree's flavour silently moves all of them at once. Release belongs in
  935. > its own tree (`build-release/` above; `./install.sh` builds its own `build-install/` the same way).
  936. > CI builds both flavours on purpose — see [`CONTRIBUTING.md`](CONTRIBUTING.md).
  937. **The honesty contract, in one line:** every count ripwire cannot prove is a total ships labelled a
  938. floor, every truncation is disclosed where it happens, and a zero means *none found* — never *none
  939. exists*. Two runs over the same tree are byte-identical, and a warm run equals a cold one, except where a
  940. git history walk hits its time budget on a slow repository: that cut is disclosed in the answer, and the
  941. prefix it keeps moves with machine load, so two runs can differ. That is a
  942. contract, gated on every pull request and every push to main, not a tendency.
  943. [The full discipline — and the losses published next to the wins →](#the-honesty-contract)
  944. </details>
  945. <!-- The name is the design: rip-grep for the retrieval half — a zero-runtime-dependency C++23
  946. binary that crawls a tree, extracts symbols with tree-sitter, resolves references into a call
  947. graph, ranks it with Personalized PageRank, and streams a deterministic minified XML map to
  948. stdout — and trip-wire for the honesty half. -->
  949. ---
  950. ## The quality panel
  951. <details>
  952. <summary><b>4,956</b> eligible functions on this repository, and 2-of-6 agreement leaves <b>401</b> worth a second look — an <b>8.1%</b> shortlist</summary>
  953. **Six independent evidence families, ranked by how many of them agree — never one blended score.**
  954. Pointed at this repository's **4,956** eligible functions, 2-of-6 agreement leaves **401** worth a
  955. second look: an **8.1%** shortlist. Pooled over five corpora (n = 27,889) no two families correlate
  956. above **+0.168**, which is what makes agreement corroboration rather than one metric counted twice.
  957. </details>
  958. What each family actually looks at — on this repository's own source, not a synthetic example:
  959. | Family | Question | Backing verb | On this repo |
  960. | --- | --- | --- | --- |
  961. | **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 |
  962. | **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 |
  963. | **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 |
  964. | **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 |
  965. | **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 |
  966. | **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 |
  967. <details>
  968. <summary>How the six families are joined, the churn caveat, and the <code>nest=</code> profile deep-dive</summary>
  969. `--quality-panel` joins **six independent evidence families** (structural shape, lexical naming,
  970. syntactic-confusion idioms, git churn history, cross-file colocation, and non-local mutable state)
  971. and ranks by the *count* of families agreeing, never a weighted composite — averaging correlated
  972. metrics and calling it several is the Maintainability Index's well-known failure mode. On this
  973. repository the panel measures **4,956** eligible functions and narrows them to **401** worth a
  974. second look at 2-of-6 agreement — an **8.1%** shortlist, not a guess — and the largest correlation
  975. between any two families, pooled across five independent corpora (n = 27,889), is **+0.168**: the
  976. families really are measuring different things. The six-family table above shows what each finds on
  977. this repository's own source; the sections below are the parts that need more than a row.
  978. ### `nest=` is a max, so it cannot tell a long function from a tangled one
  979. The structural family's `nest=` reports the single deepest line in a function. One line at depth 9 and
  980. a thousand lines at depth 9 produce the same number — which means a long **blocked-sequential** body (a
  981. run of shallow scoped steps, its max set by one inner loop nobody has to hold in their head) is
  982. indistinguishable from a **tangled** one that sustains depth for hundreds of lines. Every consumer of
  983. `nest=` inherited that blindness: the panel's structural family, `--biggest-first`'s rank, the ensemble join.
  984. `--metrics` now emits the **profile** beside the max — `humps=` (how many maximal regions reach the
  985. nesting bar, CodeScene's "bumpy road": a rise above the threshold then a fall, so repeated missing
  986. abstractions read differently from one deep tangle) and `deep=` (how many lines lie inside them, against
  987. the `loc=` already on the row). Both come from the same fused walk that already computes `ccx`/`nest`, at
  988. zero extra parsing cost; `deep=` is a disclosed floor (`deep_floor="1"`). Both are **absent** exactly when
  989. `nest <` the bar — not-deep, never a hidden `0`. `deep` counts **lines** and `humps` counts **regions**,
  990. and two regions can share a line — a one-line `if(c){x;}else{y;}` at the bar is two regions on one line —
  991. so `deep` below `humps` is legal output rather than a defect. On this repository's own source:
  992. | function | `loc` | `nest` | `humps` | `deep` | deep/loc | reading |
  993. | --- | --- | --- | --- | --- | --- | --- |
  994. | `ingest` (`src/ingest.cpp`) | 1632 | 8 | 25 | 467 | **29%** | genuinely tangled |
  995. | `buildGraph` (`src/graph.h`) | 1244 | 9 | 30 | 308 | **25%** | genuinely tangled |
  996. | `main` (`src/main.cpp`) | 1061 | 6 | 29 | 111 | **10%** | long, mostly shallow steps |
  997. | `dispatchMcpLine` (`src/mcp.h`) | 1099 | 7 | 22 | 102 | **9%** | a dispatch table, not a tangle |
  998. | `runDefaultMap` (`src/main.cpp`) | 650 | 4 | 7 | 15 | **2%** | blocked-sequential |
  999. | `ur_walkTree` (`src/ingest.cpp`) | 87 | 7 | 1 | 43 | **49%** | *small* and tangled |
  1000. `loc` and `nest` alone rank `main` and `dispatchMcpLine` beside `ingest` and `buildGraph`; the profile
  1001. separates them, and it promotes `ur_walkTree` — 87 lines, so no size bar fires, yet proportionally the
  1002. densest thing in the table. **This changes no ranking**: `humps > 0` is exactly `nest >= bar`, which is
  1003. precisely when the `nest` bar already fired, so the family count and the panel's shortlist are untouched.
  1004. It is strictly more evidence on rows that already appear — a reader can tell the two shapes apart without
  1005. opening the file.
  1006. The panel also carries **one join, and it is deliberately not a seventh family**: a row whose structural
  1007. evidence includes `deep=` (a body that *sustains* depth at the nesting bar) and that no indexed test
  1008. reaches is annotated `join="deep+untested"` — the pair where a refactor is most wanted and least safe,
  1009. put side by side because both facts are already on the row. It changes nothing: not `fam=`, not `of=`,
  1010. not the order, not which rows appear (counting it would be the structural family wearing a second hat).
  1011. The root reports `tested_scope=` (symbols any indexed test reaches — the join's honest denominator) and
  1012. `deep_untested=` (rows carrying the annotation across the whole row set); at `tested_scope="0"` no
  1013. indexed test reaches *anything* here, so "untested" would be a fact about what was crawled rather than
  1014. about the code, and the annotation is emitted on **no** row.
  1015. </details>
  1016. **Five lenses sit *beside* the six-family join — deliberately outside its vote.** Each is out for a
  1017. stated reason, not an oversight:
  1018. | Lens | Asks | Why beside the join | On this repo |
  1019. | --- | --- | --- | --- |
  1020. | `--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 |
  1021. | `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) |
  1022. | `--biggest-first` (was `--readability`) | orders by Halstead volume, Posnett sigmoid (a size proxy — the readability-ordering claim is withdrawn) | 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 |
  1023. | `--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 |
  1024. | `--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 |
  1025. <details>
  1026. <summary>The depth on each lens — citations, caveats, and the withdrawn-rule note</summary>
  1027. **Two verbs sit *beside* the panel, not inside its six-family join** — worth knowing the boundary
  1028. rather than blurring it:
  1029. - **`--field-affinity`** (cache-friendly co-access) is explicitly **not** a panel family, by unit: it
  1030. measures which struct fields are read together but declared far apart, and its subject is a *type*,
  1031. not a function — attributing a struct's finding to the functions that touch it would be a claim the
  1032. lens itself never makes (`docs/EVALS.md` §9.9.2). `MainDispatch` (`src/main.cpp:1335`, the 144-byte
  1033. struct threaded through nearly every verb) still carries **12** real findings against a separation
  1034. cost of **92.88** — fields read together in the same call routinely cross cache-line boundaries.
  1035. Chilimbi, Davidson & Larus's cache-conscious structure definition (PLDI 1999), validated on real
  1036. hardware counters; the advice-not-transform posture (report a split, never auto-reorder a struct)
  1037. follows Hundt, Mannarswamy & Chakrabarti (CGO 2006). **This is a genuinely rare kind of tool**: code
  1038. review catches cache-unfriendly patterns constantly, but every adjacent tool that reasons about
  1039. memory-access shape (Intel Advisor's pattern classifier, DMon, PerfLint) does it by *running the
  1040. program first* — a two-round adversarial literature and patent search found no shipping tool and no
  1041. published work that does this **statically, before a line executes** (tier: RARE BUT REAL, the full
  1042. citation trail and hedged claim wording in [`docs/LINEAGE.md`](docs/LINEAGE.md)). The same verb now
  1043. also classifies each loop's access shape — `index`/handle-based (predictable, the hardware
  1044. prefetcher can hide the latency) vs. pointer-chase (data-dependent, no struct layout fixes an
  1045. unhideable per-hop stall) — and, for genuine chases, checks whether the pointer you dereference to
  1046. *reach* the next node sits next to the payload you're about to read, since that cache-line fetch is
  1047. unavoidable and colocating there is a strictly higher-value fix than generic field reordering. On
  1048. this repository: **1,374** loops classified, **5** genuine pointer-chases found in a codebase
  1049. deliberately built handle-based rather than pointer-linked (guardrail G2) — the lens staying quiet
  1050. on code written to avoid the problem is itself a check that it isn't firing at random. **Ships
  1051. entirely report-only**: an A/B benchmark against a real 64 MB shuffled linked list measured a
  1052. mostly-null result, so the ranking-affecting half of this feature is a provable no-op until a
  1053. blind real-corpus validation session clears it — reported here at the same honesty level as
  1054. everything else in this table, not oversold ahead of the evidence.
  1055. - **The `cache-*` lint pack + `--with-profile`** (cache-friendly *access patterns* — the other half
  1056. of the locality story, shipped 2026-08-07/08) covers what `--field-affinity` deliberately does not:
  1057. eight AST shapes practitioners agree hurt — node-based containers, `vector<T*>`/vector-of-indirect
  1058. (the "matrix as vector of vectors"), heap allocation inside loops, `p = p->next` chase advances,
  1059. `a[b[i]]` gather subscripts, by-value `shared_ptr` parameters, and existing manual prefetches
  1060. flagged for re-measurement — loop-fenced by span algebra, C-family only, facts never verdicts. The
  1061. honesty numbers, both directions: on this repository the aggressive rules fire **only in benches
  1062. and test fixtures, zero in shipping `src/`** (guardrail G2 holding is itself the check the rules
  1063. aren't firing at random), and a 13-agent adversarial triage of all 327 findings confirmed **zero**
  1064. as fix-worthy — every plausible refactor died on "win unmeasurable without a profile". That gap is
  1065. exactly what **`--lint --with-profile=FILE`** closes: it joins a `RIPWIRE_PROFILE` build's own
  1066. per-scope hardware counters (`#PROF_TSV`) onto findings, so a row carries `heat_total_ms` /
  1067. `heat_l1d_mpki` from a real run — static shape × measured PMU weight, the two halves of SYZYGY's
  1068. advice mode (Hundt, CGO 2006) finally in one command. Worked example: the one surviving refactor
  1069. candidate (flattening the Louvain adjacency) was settled by its new `PROFILE_SCOPE` in a single
  1070. measured run — **5.2 ms, 5.9% of the verb** — a wasted afternoon prevented by a number
  1071. ([`docs/CACHELINT.md`](docs/CACHELINT.md) holds the full catalog, the wave-2 specs, and the
  1072. compiler-handled myths deliberately *not* checked).
  1073. - **`--biggest-first`** (renamed from `--readability`, which still works — a stderr note points scripts at
  1074. the new spelling) is a sibling lens, not a panel family either — the one classic model in the tree
  1075. with a published closed form: Halstead volume (Halstead, *Elements of Software Science*, 1977) and
  1076. the Posnett/Hindle/Devanbu sigmoid fit (MSR 2011, [doi:10.1145/1985441.1985454](https://doi.org/10.1145/1985441.1985454)),
  1077. fitted on snippets of 20 lines or fewer — past that the fitted score saturates and only the
  1078. *ordering* stays meaningful, which is exactly how the verb is used: largest-first, never as a
  1079. grade. Halstead's volume specifically (not the later, less-trusted difficulty/effort derivatives) is
  1080. among the metrics shown to track measured cognitive load directly (Peitek, Apel, Parnin, Brechmann &
  1081. Siegmund, ICSE 2021, [doi:10.1109/ICSE43902.2021.00056](https://doi.org/10.1109/ICSE43902.2021.00056)) —
  1082. `--biggest-first` emits volume and stops there; difficulty and effort are computed nowhere in this
  1083. tree. **A ranking lens, never a grade, and here is what it actually orders:** on ripwire's own
  1084. history at the pinned `v0.6.2` tag (412 function pairs mined from 80 refactor/simplify/cleanup
  1085. commits), the order between two versions of a function followed the sign of its token-count change
  1086. in 96.0% of pairs — read a move as *more or fewer tokens*, not as *more or less readable*. Of the 412,
  1087. 154 (37.4%) ran the commit's implied direction and 258 (62.6%) ran opposite it; Halstead volume drove
  1088. 91.1% of those 258; a separate self-consistency check confirms the formula
  1089. computes exactly what it says it computes, so this is a construct-validity finding about the
  1090. ordering claim, not an arithmetic bug. (First recorded as 484 pairs / 30.2% from an unpinned `git
  1091. log --all` walk that does not reproduce — full derivation, the instrument fix and the retracted
  1092. figure: [`docs/EVALS.md` §8](docs/EVALS.md).) **WITHDRAWN:** the ordering claim is withdrawn —
  1093. stratified into narrow token-count bands, the later-fix association disappears in 8 of 10 deciles
  1094. (CIs include 1), so the order this verb produces is better explained as a residual size proxy,
  1095. measured in the lens's own units, than as an independent readability signal (derivation:
  1096. [`docs/EVALS.md` §8](docs/EVALS.md)). The lens's computation is unchanged pending a proper human
  1097. study, and `--help=--biggest-first` carries the same figures where a CLI reader meets them.
  1098. - **`--naming-consistency`** is the *lexical* family's one exception to "evidence, never advice": every
  1099. other lens in this panel tells you WHAT is wrong, never a computed fix. Case-style consistency is
  1100. the one property with a corpus-derivable answer — on this repository's `src/`, camelCase is the
  1101. dominant convention at **1,677/1,803 (93.0%)** agreement, and the verb flags **136** off-convention
  1102. names with a mechanically recombined `propose=` value for each (no dictionary, no synonym judgment —
  1103. see [What it answers](#what-it-answers)).
  1104. - **`--lint --naming-locals`** points those same naming rules at local variable names — the thing a
  1105. human reviewer flags immediately in a sprawling function and no static tool measured until this
  1106. session. Opt-in, off by default: on this repository, a plain `--lint` finds **2,225** findings;
  1107. adding `--naming-locals` finds **3,198** — **973 findings that were structurally invisible**
  1108. a moment ago, scoped tightly (only inside functions already flagged large/complex, only locals
  1109. nested two blocks deep for the short-name rule) so it doesn't just relabel every loop counter in
  1110. the tree. Ships disabled by default on purpose: this repository's own history includes a naming
  1111. rule that shipped on plausibility and was later measured to flag its *best*-named functions — see
  1112. the withdrawn-rule note below — so a rule this new stays opt-in until a real-corpus audit clears it.
  1113. </details>
  1114. <details>
  1115. <summary>The full citation table, the evidence tiers, and the naming rule that was <b>withdrawn</b> for flagging this repository's best-named functions</summary>
  1116. Full citation table, evidence tiers, and what got measured and *withdrawn* (a naming rule that
  1117. flagged this repository's best-named functions, kept as the standing argument for measuring before
  1118. shipping) → [`docs/LINEAGE.md`](docs/LINEAGE.md).
  1119. </details>
  1120. ---
  1121. > **Want to help?** Start anywhere on the spectrum. At the ready-made end, open problems — languages,
  1122. > resolver bugs, fuzzers, docs — are written up as starter kits: the research is done, the file and line pointers
  1123. > are in the prompt, and **each prompt writes a plan and stops**, so we can agree the approach before you write any
  1124. > code.
  1125. >
  1126. > ```bash
  1127. > git clone https://github.com/redhat-et/ripwire && cd ripwire
  1128. > cmake -S . -B build && cmake --build build -j # plain build, no build type
  1129. > ls prompts/help-wanted/ # pick one
  1130. > claude "follow prompts/help-wanted/zig-language.md" # or your agent of choice
  1131. > ```
  1132. >
  1133. > In the middle, a few prompts hand your agent the whole repository and a job to do:
  1134. >
  1135. > - **[Full audit](prompts/full-audit.md)** — six independent lenses over the codebase; take one, or all six.
  1136. > - **[Add a language](prompts/add-a-language.md)** — a vendored grammar, extraction and gates, start to finish.
  1137. > - **[Use it for real, log every gap](prompts/dogfood-gaps.md)** — do an actual task with ripwire and write down
  1138. > every place it let you down.
  1139. >
  1140. > At the other end, bring your own:
  1141. >
  1142. > - research an idea you have been turning over
  1143. > - bring in a paper that deserves to be in a tool
  1144. > - show how AI agents could read and write better code
  1145. > - automate something decades of software engineering already know
  1146. > - check software algorithmically — a smell nobody measures yet, a way to prove an answer is complete, a bug class
  1147. > a tool could catch before a reviewer does
  1148. >
  1149. > Open an issue; we want to hear it. The part we would most like help thinking about is the quality lens: measuring
  1150. > what a change makes *worse*, and handing that back while the code is still being written.
  1151. >
  1152. > [help wanted](https://github.com/redhat-et/ripwire/labels/help%20wanted) ·
  1153. > [good first issue](https://github.com/redhat-et/ripwire/labels/good%20first%20issue) ·
  1154. > [all the prompts](prompts/help-wanted/)
  1155. ---
  1156. ## Real runs
  1157. <details>
  1158. <summary><b>Four real invocations</b> against this repository, printed as the binary actually prints them — including why <code>--callers</code>' count is a floor and what <code>amb=</code> admits</summary>
  1159. **Four real invocations against this repository**, each printed as the binary actually prints it:
  1160. `--callers` (and why its count is a floor), the default ranked map (and what `amb=` admits),
  1161. `--test-gate` (exit 4 while obligations remain), and `--from-trace` (feed it the error itself, not a
  1162. paraphrase of one).
  1163. </details>
  1164. <details>
  1165. <summary>How these excerpts were edited — minified output wrapped for reading, and exactly which numbers are elided</summary>
  1166. Output is minified — one line, no whitespace between tags — so the excerpts below are wrapped for
  1167. reading, and each one's leading legend comment is elided. Nothing else is edited, except that
  1168. corpus-size numbers (file/symbol/edge counts, the ranked-map header's token/ambiguity tallies,
  1169. PageRank `k=` values, and the test-gate example's
  1170. `script_gates_unmodelled=` — a count of the script runners under `test/`, recursively) drift as this repository
  1171. grows: **the ranked map** elides those specifically, and says so again at the point of use, and **the
  1172. test gate** additionally trims its `<u>` rows down to 2 of the 25 the real run prints, behind a
  1173. trailing `…`.
  1174. </details>
  1175. <details>
  1176. <summary><code>--callers</code> — a call graph built on the spot, and why <code>count="7"</code> ships labelled a floor</summary>
  1177. **Ten seconds, no index server, no embeddings, no API key** — a parse and a call graph, built on the
  1178. spot. The rows below are a real capture: the callers and their files are gate-held current
  1179. (`test/readmeexamplecheck.sh`), the `:line` suffixes were true when captured and drift as the files
  1180. grow — nothing can keep a line number true in a document, so it is not claimed here. `p=` is where each caller is
  1181. defined; `sites_at=` lists its call sites as pasteable `file:line` tokens, so the lines to edit come with the first answer.
  1182. ```
  1183. $ ripwire . --callers=rankGraphTeleport
  1184. <callers of="rankGraphTeleport" defs="1" count="7" root="." hop_tested="0" hop_untested="7" counts_floor="1">
  1185. <s t="fn" n="getIndex" p="src/mcpindex.h:1165" sites_at="src/mcpindex.h:1268"/>
  1186. <s t="fn" n="rankGraph" p="src/graph.h:7965" sites_at="src/graph.h:7968"/>
  1187. <s t="fn" n="anchoredLexicalRank" p="src/graph.h:8611" sites_at="src/graph.h:8662"/>
  1188. <s t="fn" n="runEval" p="src/eval.h:171" sites_at="src/eval.h:325"/>
  1189. <s t="fn" n="churnDecayRanking" p="src/main.cpp:1383" sites_at="src/main.cpp:1397"/>
  1190. <s t="fn" n="churnRankedGraph" p="src/main.cpp:1422" sites_at="src/main.cpp:1436 src/main.cpp:1437 src/main.cpp:1451"/>
  1191. <s t="fn" n="runDefaultMap" p="src/main.cpp:1632" sites_at="src/main.cpp:1752"/>
  1192. </callers>
  1193. ```
  1194. `counts_floor="1"` is the point. Call edges are extracted from source text by name, so dynamic
  1195. dispatch contributes no edge (a call through a function pointer or callback is an edge only when
  1196. ONE function is bound to that variable in scope and the variable never escapes — its address taken
  1197. or reference-bound — and a macro-generated call site — tagged
  1198. `role="macro"` — only when its function-like `#define` is indexed): `count="7"` is a **floor**,
  1199. and the element says so before you read a single row.
  1200. </details>
  1201. <details>
  1202. <summary>The default ranked map — <code>--top-k=3</code>, and what <code>amb="2"</code> admits about a resolver guess</summary>
  1203. **The ranked map** — the default run, capped to three symbols so it fits here:
  1204. ```
  1205. $ ripwire . --top-k=3
  1206. <!-- files=… symbols=… edges=… shown=3 est_tokens=… ambiguous=… unresolved=…
  1207. precise=… skipped_oversize=… order=important-first -->
  1208. <r est_tokens="435">
  1209. <f p="./src/infra/svector.h" layer="infra">
  1210. <s t="method" n="size" sc="svector" k="…"></s>
  1211. <s t="method" n="push_back" sc="svector" amb="2" k="…">
  1212. <c n="buf" l="…,…"/><c n="grow" l="…"/></s>
  1213. </f>
  1214. <f p="./src/scipoverlay.h">
  1215. <s t="method" n="empty" sc="ScipOverlay" k="…"></s>
  1216. </f>
  1217. </r>
  1218. ```
  1219. `files=`/`symbols=`/`edges=` and the `k=` rank values are elided: this repository is the corpus here,
  1220. so they move every time README.md itself gains or loses a line, which is not what the example
  1221. demonstrates. The rest of the header measures the whole corpus, not the excerpt — the `ambiguous=` tally is
  1222. the call-graph completeness gauge, and `amb="2"` on a row says two of that symbol's calls hit a name
  1223. with several definitions and the resolver guessed. Read the source when which-target matters.
  1224. </details>
  1225. <details>
  1226. <summary><code>--test-gate</code> — exit 4 while obligations remain, and why <code>script_gates_unmodelled="332"</code> stays nonzero on a clean clone</summary>
  1227. **The test gate** — `--test-gate` names the obligations and exits 4 while any remain. Captured with an
  1228. uncommitted change in the tree: `changed="1"` and the rows below appear only because something was
  1229. actually pending. A clean clone exits 0 with every changed/impacted/test count at zero. The structural
  1230. counts describe the tree, not git status, so they stay nonzero even then: `script_gates_unmodelled=`
  1231. (script-to-binary test runners the call graph cannot see), `script_gates_registered=`,
  1232. `script_gates_mapped=` and `script_gates_unresolved_dynamic=` (the suite's registered shell gates, and how
  1233. many of them map to their dependencies), and the resolver gauges `graph_ambiguous=`, `graph_unresolved=`
  1234. and `graph_unindexed=`. The capture below predates the `script_gates_*` registry counts and those gauges:
  1235. ```
  1236. $ ripwire . --test-gate # exit code: 4
  1237. <test-gate changed="1" impacted="80" tests="2" untested="76" shown_tests="2" tests_capped="0"
  1238. shown_untested="25" untested_capped="1" script_gates_unmodelled="332" at="9cf0b16f3+dirty">
  1239. <t p="./test/adaptivecutshapefix/adaptive_cut_shape_test.cpp" run="bash test/adaptivecutshapecheck.sh"/>
  1240. <t p="./test/verify_radix.cpp" run_unknown="1"/>
  1241. <u sym="buildGraph" p="./src/graph.h" ccx="712"/>
  1242. <u sym="dispatchMcpLine" p="./src/mcp.h" ccx="428"/>
  1243. …
  1244. </test-gate>
  1245. ```
  1246. A `run=` attribute appears only when a runner is derivable from real evidence — a test-dir script
  1247. whose stem matches the harness, or whose text names it; for TypeScript/JavaScript, a file already
  1248. recognized as test code (`test/`/`tests/`/`__tests__/`, or a `_test./.test./_spec./.spec.` name, or a `.e2e-spec./.perf-spec.` name — the
  1249. `__tests__/` directory convention is shared with every language, the rest are TS/JS's own) whose name
  1250. ALSO matches vitest/jest's own test-name shape (`.test.`/`.spec.`, or living under `__tests__/` at
  1251. all, jest's own two default conventions — never a `.d.ts` declaration file) — whose nearest
  1252. `package.json` names `vitest`, `jest`, or node's own test runner. Its own `package.json` is
  1253. AUTHORITATIVE for the whole subtree below it: a non-empty, non-placeholder `scripts.test` entry
  1254. decides the runner (or decides none — a same-named dependency never overrides it, whether that
  1255. dependency sits in the same manifest or a parent one), and only a manifest with NEITHER a real
  1256. `scripts.test` NOR a `vitest`/`jest` dependency is skipped in favour of one further up. A TS/JS file
  1257. with no manifest evidence of its own still falls back to the SAME test-dir shell/Python driver search
  1258. every other language uses — a named driver beats an
  1259. unguessed default. A row with none says so — `run_unknown="1"`, never a guessed suite command — and a
  1260. `<t>` or `<g>` row carries one or the other, never neither. A
  1261. `<g hops="2" n="3" p="a,b,c" run_unknown="1"/>` row is **two or more contiguous runner-less rows whose
  1262. attributes are byte-identical**, served as one: `n=` is how many, `p=` is their paths verbatim in list
  1263. order, and the disclosure is paid once per group rather than once per row. Everything else stays its own
  1264. row — a row with a `run=`, a row whose attributes differ from its neighbour's, and a path containing a
  1265. comma, which is never grouped at all, so `p=` splits on `,` into exactly `n=` paths. A `shown=`/`total=`
  1266. over these rows counts test FILES: a `<g>` row is `n=` of them.
  1267. `script_gates_unmodelled="332"` is the same discipline: script-to-binary is not a call edge, so those
  1268. gates are invisible to this walk, and the number says so rather than letting `tests="2"` read as
  1269. complete. The `<u>` rows are the untested blast radius: impacted symbols that no test in the corpus
  1270. reaches — never a file's own `<file-scope>` module scope (a top-level statement or anonymous-callback
  1271. body), since nothing in any language can name it and no test could ever be written for it; it still
  1272. counts toward `impacted=` when it is a real caller in the blast radius, just never as an obligation.
  1273. Those excluded owners are counted, not dropped without a trace: `untested_modscope="N"` (always
  1274. present, alongside `untested=`) says how many, so a change whose only reader is an untestable
  1275. entrypoint discloses why `untested=` reads zero instead of looking like there was nothing to find.
  1276. The capture above predates that attribute (and a few other root attributes added since), so its root
  1277. lacks it; today's root carries `untested_modscope="N"` immediately after `untested=`.
  1278. A TS/JS file with NO manifest evidence of its own (no `package.json` anywhere in the crawl boundary, or
  1279. the nearest one decides nothing) still gets one more chance before falling to the shell/Python driver
  1280. search above: its own bytes are read for a `node:test` import or require — `import test from "node:test"`,
  1281. `import { test, describe } from "node:test"`, `require("node:test")`, single or double quoted (#60). This
  1282. is a real parse, not a substring scan: a `"node:test"` mention inside a comment or an unrelated string
  1283. literal is not evidence. An explicit `package.json` `scripts.test` (or `vitest`/`jest` dependency) still
  1284. wins over this — including an authoritative-but-unrecognized script, which is a decided "no" — so the
  1285. import fallback only ever fires on what was previously `run_unknown="1"`.
  1286. For a `.ts`/`.mts`/`.cts` file — whether the runner was named by `scripts.test: "node --test"` or inferred
  1287. from the import above — a `run=` command is spelled only where the checks below find nothing that makes Node
  1288. refuse to start it. They are read off the repository's own bytes, so they cannot see the Node that will run
  1289. it, and a refusal is `run_unknown="1"`, never a guess:
  1290. - **`.tsx` and `.jsx` never get a command.** Node's type stripping does not cover `.tsx` at all
  1291. (`ERR_UNKNOWN_FILE_EXTENSION`), and plain `node` cannot load a `.jsx` file at all, on any Node version —
  1292. both stay `run_unknown="1"` unconditionally.
  1293. - **Every relative import/require must resolve exactly as written, in the test file and in every local
  1294. TypeScript module it reaches.** Node's module resolver, under type stripping, never probes an extension
  1295. and never maps a `.js` specifier onto a `.ts` source — the exact shapes tsc-, tsx- and bundler-run TS code
  1296. uses to import its own siblings. So a command is spelled only when every relative (`./`/`../`) static
  1297. `import`/`export … from` specifier or `require(...)` argument names a file that exists on disk at that
  1298. exact path. The walk follows each specifier that lands on a `.ts`/`.mts`/`.cts` file, reads at most 64
  1299. modules, and a walk cut at that bound stays `run_unknown="1"` too.
  1300. - **No module on that walk may use syntax type stripping cannot erase.** Node strips types and rewrites
  1301. nothing, so an `enum`, a `namespace` with runtime code (or holding only `declare` statements), the legacy
  1302. `module M {}` keyword, a constructor parameter property, an import alias (`import A = B.C`,
  1303. `import x = require(…)`), `export =`, an angle-bracket assertion `<T>x` or a decorator stops it with
  1304. `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` (or a parse error) before any test runs; any of them outside a
  1305. `declare` stays `run_unknown="1"`. A type-only namespace and a `declare enum` are erased and do not count.
  1306. - **The command is additionally Node-version-aware, from `engines.node`.** `--experimental-strip-types`
  1307. itself exists from Node 22.6 only (an older Node refuses to start at all with it); stripping is ON BY
  1308. DEFAULT — the flag becomes a harmless no-op — from Node 22.18 and separately from Node 23.6 (two floors,
  1309. not one continuous range: 23.6 turned it on first, the 22.x line got it later by backport, and a bare
  1310. 23.0–23.5 does not have it). This tool cannot see which
  1311. Node will run the emitted command, so it reads `engines.node` from the nearest manifest: the bare
  1312. `node --test <file>` when that range proves every satisfying Node has stripping on by default; the
  1313. flagged `node --experimental-strip-types --test <file>` when it proves >= 22.6 but not provably
  1314. default-on, or when there is no manifest at all (a stated assumption of a Node that strips types with the
  1315. flag, not a guess at an unseen runtime); and `run_unknown="1"` when the range admits ANY Node below 22.6
  1316. (a plain `>=18`/`^20`, or a compound range like `>=24 || ^20`, where every `||` alternative must pass on
  1317. its own) or cannot be read with confidence at all. Each alternative is read for its upper bound too,
  1318. because the default-on versions have a gap: `^22.18.0` gets the bare form, but `>=22.18` also admits
  1319. 23.0–23.5 and keeps the flag.
  1320. Every node:test file, `.js` or TypeScript, must also load as the module kind its own syntax needs. A file
  1321. with a static ES `import`/`export` runs as an ES module only as `.mjs`/`.mts`, under `"type": "module"` in
  1322. its nearest `package.json`, or on a Node with default module-syntax detection (22.7 and later, 20.19 on the
  1323. 20.x line). Without one of those the command stays `run_unknown="1"`: an explicit `"type": "commonjs"` (or a
  1324. `.cjs`/`.cts` file) turns detection off, and with no `"type"` the `engines.node` range must prove detection —
  1325. `>=22.7` does, `>=20.19` does not, since it admits 21.x. With no `engines.node` at all, a TypeScript file keeps
  1326. the stated assumption above and a `.js` file stays `run_unknown="1"`, since its command otherwise rests on
  1327. no assumption at all. A CommonJS file (`require`, no ES `import`/`export`) runs either way.
  1328. `.js`/`.mjs`/`.cjs` never need the flag. Their one version question is the runner itself: the `--test` flag
  1329. exists from Node 18.1 and, by backport, 16.17 — never on 17.x, and 18.0 has the `node:test` module but not
  1330. the flag. So `engines.node` must not admit a Node below 18 without it: `^16.17.0`, `>=18` and `>=18.1` get the bare
  1331. form, while `>=16`, `>=16.17` and `16.17 - 18` (they reach 17.x) stay `run_unknown="1"`, and so does a range confined
  1332. to 18.0.x such as `18.0.x`. A hyphen range `A - B` is bounded by B. `>=18` is accepted although it admits 18.0:
  1333. that is one release from April 2022, the command fails loudly there, and refusing the most common spelling would make
  1334. the answer useless on most projects. No `engines.node` at all keeps the bare form.
  1335. A TS/JS `run_unknown="1"` can still mean the manifest genuinely names nothing recognized (and the test file
  1336. itself names no `node:test` import either), one of the refusals above, or a real runner this tool does not
  1337. yet derive: node's own test runner invoked through `tsx` (when neither the manifest nor the test file's own
  1338. bytes name `node:test` directly) and `bun`'s test runner. These stay an honest unknown rather than a guess;
  1339. `pnpm`/`yarn`-prefixed test scripts derive correctly today (spelled `npx …`, which finds a local binary
  1340. first).
  1341. </details>
  1342. <details>
  1343. <summary><code>--from-trace</code> — hand it the stack trace, sanitizer report or compiler error itself, not a paraphrase</summary>
  1344. **From an error, not a paraphrase of one** — `--from-trace` takes a stack trace, sanitizer report or
  1345. compiler error on stdin or from a file, maps its frames onto indexed symbols innermost-first, and
  1346. returns the innermost in-corpus body with them:
  1347. ```bash
  1348. ./build/ripwire . --from-trace=asan_report.txt
  1349. cmake --build build 2>&1 | ./build/ripwire . --from-trace=-
  1350. ```
  1351. </details>
  1352. ---
  1353. ## Measured
  1354. ### Working toward the best code helper for agents
  1355. Our goal is for ripwire to be the best tool an agent can have for understanding and changing code: complete answers, nothing stated wrongly, and as few bytes as possible. We measure every release against that goal. Each release answers the same questions with the same commands, graded the same way. These are **in-sample** questions: ripwire was developed against them, so the table shows progress between releases, not held-out performance. A held-out comparison comes with 0.7.0.
  1356. | | 0.6.5 | 0.6.7 | 0.6.8 | 0.6.9 | 0.6.10 |
  1357. |---|---|---|---|---|---|
  1358. | Everyday code questions (163): complete / partial / none | 50 / 69 / 44 | 81 / 57 / 25 | 112 / 38 / 13 | 129 / 31 / 3 | **132 / 27 / 4** |
  1359. | Questions whose answer spans several files (39) | 4 / 26 / 9 | 4 / 27 / 8 | 5 / 27 / 7 | 12 / 23 / 4 | **19 / 19 / 1** |
  1360. | Questions on large repositories (56) | 2 / 35 / 19 | 5 / 38 / 13 | 14 / 37 / 5 | 23 / 29 / 4 | **30 / 25 / 1** |
  1361. | Everyday answers that stated something wrong | 3 | 0 | 0 | 0 | **0** |
  1362. | Bytes per complete answer (everyday / large repos) | 22.5 KB / 182 KB | 14.8 KB / 123 KB | 16.5 KB / 91 KB | 15.1 KB / 60 KB | **18.0 KB / 66 KB** |
  1363. | Bytes per required item delivered (everyday) | 1.7 KB | 1.4 KB | 1.7 KB | 1.7 KB | **2.1 KB** |
  1364. | Newly complete (everyday): questions, median size | 50, 4.7 KB | +31, 4.6 KB | +31, 16.8 KB | +18, 11.9 KB | **+4, 25.5 KB** |
  1365. | Size change, questions already complete (everyday) | — | +4 % | 0 % | +1 % | **0 %** |
  1366. Harder questions take more bytes to answer. 0.6.5 already answered questions such as *Where is the `Compositor` class defined?* (one definition, 3.2 KB). The questions that first became complete in 0.6.8 and 0.6.9 include *How does Hono choose its router, and how does SmartRouter work?* (16.8 KB), *Who calls `options_get_number`?* (all 121 direct callers, 11.5 KB) and *How does a message get from `post_message` to a handler method like `on_button_pressed`?* (14.0 KB): several functions across files, or a long list. That is why the newly complete questions need more bytes while questions already complete stay about the same size.
  1367. *Complete* means every required item is in the answer; *partial*, at least one but not every required item, and nothing wrong; *none*, no required item, or something wrong. A bare name printed next to its file or qualifier counts. Large repositories: envoy, nushell, terraform, cpython, vscode, cockroach and zed. There was no 0.6.6. Bytes per complete answer fell from 0.6.5 to 0.6.9, from 22.5 KB to 15.1 KB on everyday questions and from 182 KB to 60 KB on large repositories, and rose in 0.6.10 to 18.0 KB and 66 KB: 0.6.10 answers are larger (everyday answers total 2.37 MB against 1.95 MB with the median answer unchanged at about 10.7 KB; multi-file 722 KB against 536 KB; large repositories 1.97 MB against 1.38 MB) and the extra bytes bought 10 more required items on everyday questions, 30 more on multi-file questions and 16 more on large repositories. *Bytes per required item delivered* divides all answer bytes by the required items credited, partial answers included (682 items in 0.6.5, 1,142 in 0.6.9, 1,152 in 0.6.10). *Newly complete* counts the questions a release answered completely for the first time (for 0.6.5, all its complete answers): the harder questions that became complete later need more bytes. *Size change* is the median per-question change on questions complete in both this and the previous release. Earlier release notes quoted a 173-question set that included 10 held-out questions, graded with the rules of that time (0.6.8: 50, 83, 98 complete under the stricter method); this table re-runs every release on the 163 in-sample questions with today's grader, so its numbers differ. A grader input lost in a cleanup was restored (GRADER-FIX-1107), so the 0.6.9 and 0.6.10 columns are graded by the same scripts and read as shown. One everyday question that read complete in 0.6.9 reads none in 0.6.10: textual-09, whose `--impact` answer now names the test file that exercises one of the eight definitions called `arrange`, which the mechanical wrong-name check counts as a wrong name (read in the source, that test edge is true, so the question is counted in *none* but not in the wrong-answer row). hono-17, a dead-code question with no required item, stays complete: its answer grew from 1.0 KB to 3.4 KB by also listing eight exported functions marked `unknown`, which the rule for exports flagged as public API accepts. The 0.6.5 to 0.6.8 columns are the numbers published with those releases; the scripts as they run now read them 2, 1 and 1 partial answers lower (50 / 67 / 46, 81 / 56 / 26, 112 / 37 / 14 for 0.6.5, 0.6.7, 0.6.8). The multi-file and large-repository columns are unaffected.
  1368. <details>
  1369. <summary><b>Read this first if you are here to check whether the tool is oversold</b> — every number with its instrument and corpus, plus the claims this project deliberately does <i>not</i> publish</summary>
  1370. Every published number lives in **[`docs/EVALS.md`](docs/EVALS.md)** with the instrument that produced
  1371. it, the corpus it ran on, and the in-tree file that pins it — alongside a counterexample section and a
  1372. list of the claims this project deliberately does *not* publish. Read those first if you are here to
  1373. check whether the tool is oversold.
  1374. </details>
  1375. ### Against other tools
  1376. <details>
  1377. <summary><b>Round 4: 58.3% against 40.0%</b> — a <b>1.46×</b> margin at a <b>0.31 s</b> index; N = 60 paired, zero exclusions, all arms re-run 2026-08-08</summary>
  1378. **Round 4 (re-run in full 2026-08-08): 58.3% strict file@10 against 40.0% for the best competitor —
  1379. a 1.46× margin, at a 0.31 s index.** N = 60 paired instances, zero exclusions, one binary (the
  1380. profile-guided release build that now ships), one evaluator, all arms re-run on the same day.
  1381. *Strict file@10 = all gold files inside the top 10.*
  1382. </details>
  1383. | Arm | strict file@10 | any@10 | index (median) | query (median) |
  1384. | --- | --- | --- | --- | --- |
  1385. | **ripwire `--for`** | **58.3%** | **85.0%** | **0.31 s** | 0.108 s |
  1386. | codebase-memory-mcp 0.9.0 | 40.0% | 63.3% | 1.24 s | 0.075 s |
  1387. | repowise 0.37.0 (MCP `search_codebase`, LLM-free wiki) | 33.3% | 53.3% | 34.0 s¹ | 1.159 s¹ |
  1388. | graphify 0.9.34 (`--code-only --no-cluster`, keyless) | 31.7% | 46.7% | 7.82 s | 0.614 s |
  1389. | Aider repo-map 0.86.2 (ident-personalized) | 20.0% | 35.0% | *(inside query)* | 2.920 s |
  1390. | Aider repo-map 0.86.2 (no-personalization control) | 10.0% | 25.0% | *(inside query)* | 0.818 s |
  1391. | codeseek 0.1.31 (ident-mention convention arm) | 15.0% | 20.0% | 3.37 s | 0.040 s |
  1392. | codeseek 0.1.31 (raw issue text, keyless fallback) | 0.0%² | 0.0% | 3.37 s | 0.024 s |
  1393. *Measured 2026-08-08, before the performance work that ships in 0.6.0. ripwire has become faster since — llvm-project's cold parse (182,555 files) fell from 194.1 s to 155.6 s of CPU, and `--pack-task` on a Go repository from 8.13 s to 5.88 s — but these timing columns have not been re-measured.*
  1394. <details>
  1395. <summary>Round-4 method and the paired losses — one binary, one evaluator, what re-running cost us, and the three limits that travel with this table</summary>
  1396. **Round 4 (first run 2026-08-06; re-run in full 2026-08-08 on the profile-guided release build) —
  1397. N = 60 paired instances, zero exclusions, one binary, one evaluator.** Every
  1398. competitor was re-run on the same day against the same ripwire binary
  1399. and the same evaluator, so the arms are directly comparable to each other. Earlier rounds could not
  1400. say that: r1 (2026-07-13/14) and r2 (2026-08-03) each scored a different subset against a different
  1401. binary, which is why this page used to print two tables and ask the reader not to compare them.
  1402. *Strict file@10 = **all** gold files inside the top 10.* Harness, per-instance JSONL, and a
  1403. reproduction recipe: [`bench/headtohead/r4-2026-08-06/`](bench/headtohead/r4-2026-08-06/).
  1404. Paired, ripwire's losses are **2** instances to codebase-memory-mcp, **2** to repowise, **1** each to
  1405. graphify and aider; codeseek never beat it. **Cold from nothing to an answer** — parse, rank, reply,
  1406. no cache — ripwire takes **0.213 s**, against a ~34 s index-then-query for repowise, whose worst
  1407. single index in this run was **352 s**. That comparison is only possible because ripwire's own index
  1408. was measured this round; r2 recorded competitor index walls and deliberately refused to tabulate
  1409. them, since a one-sided cost table is not evidence.
  1410. **What re-running cost us, stated because it is the reason to re-run at all.**
  1411. **codebase-memory-mcp is the true runner-up at 40.0%** — r1 credited it with 26.7%, and scoring it
  1412. fairly against today's binary raised it. graphify rose 21.7% → 31.7% and aider 13.3% → 20.0% the same
  1413. way. The margin over the best competitor is therefore **1.46×**, not the 1.75× that two
  1414. separately-dated tables implied; the old framing flattered us by comparing today's ripwire against
  1415. year-old competitor runs.
  1416. Three limits travel with this table. ¹ repowise's walls include a fresh MCP-server spawn per query;
  1417. resident-server usage is faster. ² codeseek's raw row returned **0 results on 60/60 queries** — its
  1418. keyless fallback matches function names only, so that row measures a query-protocol boundary, not its
  1419. embedder-backed shipping mode (unbenchmarked here). And the slice is **Python-dominant** — 107 of 134
  1420. gold files are `.py` — so this measures Python localization, not every [supported language](#languages).
  1421. **Vexp and CodeIndexer were excluded, not beaten**: their free tiers (node/project/chunk caps) cannot
  1422. run a fair 60-instance sweep. An independent adversarial pass attacked the r2 comparison's design, and
  1423. its findings and dispositions ship with that report
  1424. ([`VERIFIER.md`](bench/headtohead/r2-2026-08-03/VERIFIER.md)); r1's and r2's tables remain in their own
  1425. directories as the historical record.
  1426. </details>
  1427. <details>
  1428. <summary>The open problem — multi-file gold: 21.4% strict against 78.6% any@10, and four pre-registered fixes rejected at ±0.00pp</summary>
  1429. **Multi-file gold is hard for every arm, including ours, and four attempts have failed to fix it.**
  1430. ripwire leads the stratum at 21.4% strict — but its own any@10 there is 78.6%: it finds *a* gold file
  1431. and misses the siblings. If each gold file were an independent draw at the single-file rate (90.6%),
  1432. multi-file would score 71.2%; it scores 21.4%, so the failures are strongly correlated. The mechanism
  1433. is that a sibling is a file which changed *because* the primary changed — the primary carries the
  1434. issue's vocabulary, the siblings carry the consequences. Four pre-registered rounds
  1435. (`r1_anchorhop`, `r1cpp_anchorhop`, `r4_siblift`, `r5_pooling`) have now been rejected at ±0.00pp
  1436. against it, each archived with its grid and its verdict under
  1437. [`bench/locbench/results/`](bench/locbench/results/).
  1438. </details>
  1439. <details>
  1440. <summary>Round 3 (2026-08-03) — headroom, the compression-layer competitor: 0 tokens saved on ripwire's output, and 5/12 losses published first</summary>
  1441. **Round three (2026-08-03): headroom — the compression-layer competitor.** headroom
  1442. (`headroom-ai==0.33.0`, 64k★) compresses context an agent already fetched; it retrieves nothing —
  1443. so this round's instrument is **tokens-to-correct-answer** on 12 pre-registered mid-task questions
  1444. (django @ pinned commit, five arms, one tokenizer), not file@k. **ripwire won every measure the two
  1445. tools share.** headroom's default config passed every code chunk through **byte-identical** — its
  1446. own protective guards fired throughout, netting −410 tokens on a 685,682-token workload (its own
  1447. limitations page says "Code — Passthrough"; this run confirms it live) — and stacking it on
  1448. ripwire's output added **exactly 0 tokens** of savings: the map is already past the density
  1449. compression targets. As measured then, ripwire answered at **7.3%** of the naive grep-and-read
  1450. baseline's tokens (**1.7%** on the subset both arms fully answered), warm in ~0.14 s per verb. Those
  1451. two figures were re-derived on 2026-08-23 and now read **5.0%** and **5.2%** — the block below.
  1452. **The losses in this
  1453. round are ripwire's own, and they are published first**: under the frozen no-human verb ladders it
  1454. strictly satisfied only **5/12** questions vs the naive baseline's 11/12 — four ranking defects,
  1455. one missing symbol kind, two harness artifacts, each bucketed with its fix disposition in the
  1456. report. What the round does **not** show: headroom's home turf (JSON/log tool-output compression,
  1457. provider-cache economics) was deliberately not measured — ripwire does not compete there.
  1458. Provenance: [`docs/EVALS.md` §2](docs/EVALS.md), full record + adversarial verification (which
  1459. materially corrected the draft's arithmetic in headroom's favor) in
  1460. [`bench/headtohead/r3-headroom-2026-08-03/`](bench/headtohead/r3-headroom-2026-08-03/).
  1461. </details>
  1462. <details>
  1463. <summary>Round 3, re-derived 2026-08-23 — one headline improved, the other got worse, and both are printed</summary>
  1464. The 2026-08-03 round is frozen; this is the same instrument pointed at today's binary. Arms **A**
  1465. (idealized grep-and-read) and **C** (ripwire's pre-registered verb ladders) were re-run from the
  1466. committed `harness.py`, importing its metric functions unmodified — same `questions.json`, same
  1467. frozen `arms_spec.json` ladders, same `tiktoken cl100k_base` counter, same corpus pin
  1468. (`django/django @ 70f39e46`). The headroom arms (B/B′/D) were not re-run; they contribute nothing to
  1469. the ripwire-vs-naive ratio, and the round's finding about them is a passthrough result that does not
  1470. depend on ripwire's side.
  1471. **The naive arm reproduced exactly** — all 12 questions token-for-token, 685,682 t in total — which
  1472. is what makes the comparison a measurement of ripwire's change and not of drift somewhere else.
  1473. Satisfaction did not move either: **5/12** for ripwire, **11/12** for naive, and the both-satisfied
  1474. set is the identical `{q02, q03, q04, q05, q11}`.
  1475. | | 2026-08-03 | 2026-08-23 | |
  1476. | --- | ---: | ---: | --- |
  1477. | naive (arm A) total | 685,682 t | 685,682 t | reproduced to the token |
  1478. | ripwire (arm C) total | 50,138 t | **33,948 t** | −32.3% |
  1479. | **overall ripwire ÷ naive** | **7.3%** | **5.0%** | **better** |
  1480. | both-satisfied, naive | 219,223 t | 219,223 t | same 5 questions |
  1481. | both-satisfied, ripwire | 3,775 t | **11,471 t** | +204% |
  1482. | **both-satisfied ripwire ÷ naive** | **1.7% (58×)** | **5.2% (19×)** | **worse** |
  1483. | ripwire tokens spent on its own misses | 92.5% | 66.2% | |
  1484. **Why they moved apart.** The compact conceptual route made the seven questions ripwire *misses*
  1485. dramatically cheaper — `q07` 13,198 → 4,416 t, `q08` 11,192 → 2,016 t, `q01` 11,974 → 3,045 t — which
  1486. is what pulls the overall share down. On the five it *answers*, richer default bundles cost more:
  1487. `q05` 522 → 6,736 t and `q11` 280 → 1,373 t dominate that column. The 58× figure was always the
  1488. flattering framing of a 5-of-12 result, and the honest reading of the pair is that ripwire got much
  1489. better at being wrong cheaply and somewhat more expensive at being right. Nothing about the four
  1490. ranking defects, the missing symbol kind or the two harness artifacts in the original loss buckets
  1491. has been re-adjudicated here — the satisfaction column is unchanged, so those losses stand.
  1492. </details>
  1493. <details>
  1494. <summary><b>LocBench held-out, N = 243 across 78 repositories</b> — strict file@10 <b>60.9%</b> against <b>27.6%</b> pre-routing, a paired <b>+33.33pp</b>, bought for <b>−39.4%</b> on the token ceiling</summary>
  1495. **LocBench held-out, N = 243 across 78 repositories.** Strict file@10 **60.9%**, against **27.6%** for
  1496. the pre-routing baseline — a paired **+33.33pp** with a clustered-bootstrap 95% lower bound of
  1497. **+25.00pp**, bought for +3.4% warm latency and **−39.4%** on the production token ceiling. More
  1498. accurate *and* cheaper, which is why it shipped.
  1499. </details>
  1500. ### What it saves you, in tokens
  1501. Context is the budget an agent actually spends. Three measurements, each with the instrument that
  1502. pins it:
  1503. | Where the saving comes from | Measured | Pinned by |
  1504. | --- | --- | --- |
  1505. | `--pack-signatures` — body-elided declaration skeletons instead of full bodies | **81.8% fewer element bytes** at top-50 (89.5% at top-10, 84.3% at top-100) — re-derived 2026-09-10 | `test/showcasecapturecheck.sh`, re-derived from this repo every run |
  1506. | Query-shape routing, on the production token ceiling | **−39.4%** p50, while strict file@10 rose +33.33pp | `bench/locbench/`, [EVALS §3](docs/EVALS.md) |
  1507. | A whole-question bundle against a naive agent read | **96.0% fewer tokens (24.9×)** — 14,758 against 367,192, tiktoken `cl100k_base`, six realistic questions | `bench/BENCHMARK.md` — *historical, private corpus, not reproducible from this tree* |
  1508. <details>
  1509. <summary>Read this before quoting those numbers — root-neutralised bytes, the private-corpus caveat, and the two verbs where the saving inverts</summary>
  1510. Read the first row's methodology before quoting it: element bytes are counted **root-neutralised**,
  1511. with the corpus-root prefix subtracted from both sides, because the root repeats inside every element,
  1512. is charged in both forms, and is not what this verb elides. Quote the top-50 figure — the signature
  1513. payload is top-50 whatever `--top-k` says, and top-10 is a ten-symbol sample that one one-line
  1514. accessor can move several points. The gate fails if the documentation drifts more than 1.5 points from
  1515. the binary.
  1516. And the third row's caveat is not small: it was measured 2026-06-20 on a large private C++ corpus, it
  1517. is not publicly reproducible from this tree, and it proves *cheaper and faster*, not *better
  1518. outcomes*.
  1519. **The losses ship next to the wins.** `--grep`'s 2026-06 anti-headline (+19.7% / −11.2% vs raw grep)
  1520. was re-derived 2026-08-15 after the emission overhaul: the **un-tiered view** — `--grep-in=any`, which
  1521. was the default when this was measured — lands at **−1.9% / +4.3%**
  1522. of a clean grep dump while carrying enclosing symbols and in-band honesty grep cannot give — one term
  1523. either side of parity, which is not a headline in either direction — but an uncapped dump of that same
  1524. un-tiered view remains token-negative (**+150% / +214%**), and this project still says so. (Span tiers
  1525. landed 2026-08-19 and made the *default* a filtered view of the same scan; every byte number on this
  1526. page is the un-tiered one, deliberately — the instrument may not move under a display change — so none
  1527. of them describes today's default. See `docs/EVALS.md` §grep.) Nor is that the worst
  1528. regime: on *small-hit uncapped* answers the fixed per-answer legend is not amortized over anything, and
  1529. a gated set of twelve such queries on this repository runs **+65.1% median, larger than plain grep on
  1530. 12 of 12**. When the agent knows a second term, `--grep=A --and=B` flips hard positive (**−77.7%**
  1531. measured, complete both sides). `--pack-signatures` inverts on a short symbol: 303 bytes of
  1532. signature-plus-doc-comment against a 158-byte body. The headline is a property of large result sets,
  1533. and [the full counterexample list](#in-the-numbers) is part of the contract, not an appendix — the
  1534. four-fact grep re-derivation lives in [`docs/EVALS.md` §5](docs/EVALS.md).
  1535. </details>
  1536. ---
  1537. ### Where its own cycles go — hardware counters, per scope
  1538. <details>
  1539. <summary><b>3.2–3.5 instructions per cycle</b> across parse and query, and the <b>≈167×</b> fewer instructions a warm run retires</summary>
  1540. **Every pipeline phase is bracketed by two hardware-counter reads, and the numbers say what
  1541. wall-clock cannot.** Parse and query retire **3.2–3.5 instructions per cycle**; the graph phases
  1542. stream at 32–35 L1D MPKI and still hold IPC above 3.1 (guardrail G2 doing its visible job); and a
  1543. warm run replaces the dominant phase's 8.74 B instructions with a 52.3 M-instruction cache load,
  1544. **≈167× fewer**. Two opt-in builds go faster still — PGO by **14–25% cold** — with **byte-identical**
  1545. output on every one.
  1546. </details>
  1547. <details>
  1548. <summary>How the self-profiler measures — kperf / <code>perf_event_open</code>, the per-scope counter table, and the three things it says that wall-clock cannot</summary>
  1549. The self-profiler (`-DRIPWIRE_PROFILE=ON`; `src/infra/profileScope.h` + `profilePmc.h`) brackets every
  1550. pipeline phase with two hardware-counter reads — kperf on Apple Silicon, a pinned `perf_event_open`
  1551. group on Linux. Below: ripwire mapping **its own public tree** on an Apple M5 Pro, cold
  1552. (`--no-cache`) except the last row. Counters are raw integers, never scaled; reproduce steps in
  1553. [`bench/PROFILE.md`](bench/PROFILE.md) (arming needs root; unprivileged runs print the same table
  1554. with timing columns only — the honest degrade). The report renders on **stderr**; stdout stays the
  1555. deterministic XML map, so redirects and `| xmllint` pipes behave the same in the profile flavour.
  1556. | scope | calls | instructions | IPC | L1D MPKI | wall |
  1557. | --- | --- | --- | --- | --- | --- |
  1558. | tree-sitter parse | 803 | 8.74 B | 3.52 | 4.0 | 731 ms |
  1559. | tags query exec + captures | 803 | 8.65 B | 3.22 | 3.0 | 635 ms |
  1560. | resolve refs + build CSR | 1 | 54.6 M | 3.27 | 35.4 | 3.6 ms |
  1561. | PageRank (power iteration) | 1 | 13.7 M | 3.17 | 32.4 | 0.93 ms |
  1562. | serialize ranked map | 1 | 3.24 M | 2.43 | 6.1 | 0.29 ms |
  1563. | **warm run** — loadCache (read + deserialize) | 1 | 52.3 M | 3.18 | 7.5 | 3.6 ms |
  1564. Three things the counters say that wall-clock alone cannot. The parse/query phases are
  1565. compute-dense, not stall-bound: 3.2–3.5 instructions retired per cycle at ~3–4 L1D misses per
  1566. thousand. The graph phases stream hard — 32–35 L1D MPKI — yet hold IPC above 3.1, which is the
  1567. DOD/SoA/CSR layout (G2) doing its visible job. And the auto-cache's whole story in two rows: a warm
  1568. run replaces the dominant phase's 8.74 B instructions with a 52.3 M-instruction cache load, ≈167×
  1569. fewer instructions. Caveats travel with the table: counters are per-thread and aggregated per
  1570. scope, so rows must not be summed across scopes (a recursive site samples only its outermost
  1571. frame); one machine, one corpus — re-run on yours. Backend contract is gated by
  1572. [`test/pmccheck.sh`](test/pmccheck.sh); M5 Pro event names verified (the last-level alias resolves
  1573. via `PL2_CACHE_MISS_LD`).
  1574. </details>
  1575. <details>
  1576. <summary>The two opt-in faster builds — LTO on by default, PGO at 14–25% cold, and why the output stays byte-identical</summary>
  1577. **Every number on this page is the DEFAULT build — and there is a faster one you can opt into.** A
  1578. clang optimization-remarks pass over `src/` (`-DRIPWIRE_OPT_REMARKS=ON`; the whole triage is in
  1579. [`docs/OPTREMARKS.md`](docs/OPTREMARKS.md)) found that the phases above spend their time calling
  1580. tree-sitter's C API across a translation-unit boundary — 831 of 1,437 distinct `inline/NoDefinition`
  1581. sites in the hot TU name a `ts_*` accessor. Two build options answer that, both **off by default**:
  1582. | build | cold | warm | |
  1583. | --- | --- | --- | --- |
  1584. | `-DRIPWIRE_LTO=OFF` | baseline | baseline | the fast edit loop, not the fast binary |
  1585. | **default** (`cmake -S . -B build`, LTO on) | 1–6% faster | 0–3% faster | |
  1586. | `scripts/pgobuild.sh` (PGO on top of LTO) | **14–25% faster** (6–16% over the default) | 5–10% faster | the fastest binary this tree can produce |
  1587. Measured by interleaved A/B (`A,B,A,B,…`, median **and** min, 9–31 runs per arm, repeated) on this
  1588. repository *and* on a ~2000-file C++ tree that appears in no training run — the held-out corpus shows
  1589. the same or larger gain, which is what rules out training on the benchmark. **Output is
  1590. byte-identical** on all three builds and on both corpora, and the determinism gate passes on every
  1591. tree; these options change how fast the answer arrives, never what it is. Cold gains 2–3× more than
  1592. warm because cold is a branchy walk over tree-sitter's parse tree, while warm already runs in the
  1593. cache-tuned CSR/SoA/B+tree structures G2 exists to produce. **LTO is on by default** — it costs link
  1594. time and nothing else, and link time is not what this tool is optimized for. PGO needs a training
  1595. run, so it stays a driven build (`scripts/pgobuild.sh`) rather than something a bare
  1596. `cmake --build` does behind your back.
  1597. </details>
  1598. <details>
  1599. <summary>On a vPMU-less cloud VM the columns don't vanish — software counters, a G2 witness at zero page faults, and the 2.17 s subprocess they exposed</summary>
  1600. **And on machines with no PMU at all — most cloud VMs and CI boxes — the counter columns no longer
  1601. vanish.** A kernel that refuses every hardware event (`ENOENT`; no vPMU is the common cloud case)
  1602. still offers software counters, so the Linux backend's per-event graceful skip now extends to the
  1603. group leader and falls through to two `PERF_TYPE_SOFTWARE` rows — `task-clock` (on-CPU ns) and
  1604. `page-faults` — under their own column names, never as a stand-in for the hardware counts. Below,
  1605. ripwire mapping its own tree, cold, on the 2-vCPU vPMU-less Intel Xeon VM this was validated live
  1606. on:
  1607. | scope | calls | wall | task-clock (on-CPU) | page-faults |
  1608. | --- | --- | --- | --- | --- |
  1609. | tree-sitter parse | 799 | 1,773 ms | 1,134 ms | 6.4 k |
  1610. | tags query exec + captures | 799 | 1,084 ms | 1,071 ms | 6.7 k |
  1611. | doc post-pass (main-thread wait on the pool) | 1 | 2,174 ms | 0.50 ms | 0 |
  1612. | resolve refs + build CSR | 1 | 12.32 ms | 12.31 ms | 7 |
  1613. Four things this buys that wall-clock alone cannot say. The wall−task-clock gap is *off-CPU time*:
  1614. the parse phase's 36% gap is 2-vCPU oversubscription made visible (a pool parsing 799 files on two
  1615. cores). The CSR row is a live cross-check: `task-clock` is the kernel's clock, the wall column is
  1616. the profiler's own — two independent clocks agreeing to 0.05% on a single-threaded scope. (Short
  1617. hot scopes diverge by the documented read-bracket overhead instead: the counter bracket encloses
  1618. the tick bracket.) The `page-faults` column is a **G2 witness**: PageRank's power iteration retires
  1619. with **zero** page faults and the CSR build with **7**, against ~3,100 in the allocation-heavy
  1620. model-build scopes — the no-allocation rule inside the ranked loop, watchable on a box with no PMU.
  1621. And the doc post-pass row caught something real: 2.17 s of wall on **0.5 ms** of CPU is work
  1622. happening *outside the process* — with `markitdown` installed, the showcase PDF and PPTX are
  1623. re-extracted by subprocess on **every** run, cache or no cache, which on this box is ~97% of a warm
  1624. run's wall (2.05 s of 2.11 s); child CPU is invisible to every per-thread counter, and the
  1625. wall-vs-task-clock gap is precisely the signature that flags it. (The extraction is already
  1626. documented in-tree as a pure function of the file bytes — a cache candidate, now measured.) Only a
  1627. kernel that offers nothing at all — `perf_event_paranoid>=3`, seccomp — still degrades to
  1628. timing-only, and `pmccheck`'s inactive arm now proves that was truly the case.
  1629. </details>
  1630. ## Standing on the whole field
  1631. <details>
  1632. <summary>49 repositories, 79 papers and a 237-tool survey — and the study where search over a pre-built index beats a delegating planner <b>65.2% to 46.2%</b>, at under half the cost</summary>
  1633. Almost none of the ideas here are new; the combination and the constraints are. Lessons folded from
  1634. **49 repositories and 79 papers** into one deterministic executable, alongside a labelled
  1635. survey of 237 tools that folded nothing and are catalogued separately — the two sets are disjoint,
  1636. so they add rather than nest. The row-by-row ledger, each with the lesson taken and where it lives, is
  1637. [`docs/LINEAGE.md`](docs/LINEAGE.md). Those three counts are derived from that document's own tables
  1638. by `test/readmedriftcheck.sh`, which fails if this sentence and those tables disagree.
  1639. One of those papers measures the alternative architecture directly: an independent study found a
  1640. planner that delegates exploration to a sub-agent in an isolated context window losing to search over
  1641. a pre-built index — 65.2% vs 46.2% accuracy, at less than half the cost — with 41.8% of the delegated
  1642. arm's failures happening silently at the planner→sub-agent hand-off

Lines 2,001–2,835 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.