# ripwire — every flag, generated from the binary **This file is generated. Do not hand-edit it.** Regenerate with: ```bash python3 docs/docs_commands_build.py --bin build/ripwire ``` The flag surface below is read from `ripwire --help`, so it cannot disagree with the shipped binary. `test/docscommandscheck.sh` fails if it ever does — in either direction. Sample output is lifted from a real recorded run (`docs/captures/COMMANDS_showcase_2026-09-07.md`), trimmed to the first few lines and scrubbed of local paths. It is illustrative, not a golden: run the command yourself for the current shape. > ripwire — the "ripgrep of AI context": parse a codebase, rank symbols by Personalized PageRank, > stream a deterministic minified XML map to stdout. Zero runtime deps. Languages: C++, C, ObjC/ObjC++, > Metal (MSL, .metal — C++ grammar), CUDA (.cu/.cuh — tree-sitter-cuda, <<<>>> launches are call edges), > Python, TypeScript, JavaScript, Java, Ruby, PHP (.php/.phtml), Lua, Elixir (.ex/.exs), Bash, Go, Rust, Swift, C#; > JSON, TOML, YAML (config keys); Markdown (.md/.markdown — headings are section symbols with spans). > usage: ripwire [flags] # default = the ranked map of on stdout ## How to read a section - **Answers** — the question this flag exists to answer. - **Try it** — a real invocation and the real output it produced. - **Shaped by** — other flags that change what this one emits. - **Caveats** — the limits the binary itself states for this flag. They are extracted from its own help text, so they cannot drift from the code. Two limits apply to nearly everything here and are not repeated in every section: 1. **Call edges are heuristic and name-based.** Dynamic dispatch, callbacks and macro-generated call sites produce no edge, so counts on the graph verbs carry `counts_floor="1"`. **Read a 0 as "none found", never as "none exists."** 2. **A symbol's `amb="K"`** means K of its calls hit a name with several definitions and the resolver split the weight rather than choosing. Read the source when which-target matters. ## Contents **understand a codebase cold** — [`--top-k`](#top-k-n) · [`--max-tokens`](#max-tokens-n) · [`--token-budget`](#token-budget-n-k-m-g) · [`--help-task`](#help-task-task) · [`--for`](#for-task) · [`--signatures-only`](#signatures-only) · [`--auto-bodies`](#auto-bodies) · [`--no-route`](#no-route) · [`--adaptive`](#adaptive) · [`--no-mention-boost`](#no-mention-boost) · [`--no-doc-mention`](#no-doc-mention) · [`--lego`](#lego-type) · [`--exemplar`](#exemplar-task-kind) · [`--recall`](#recall-task) · [`--tree`](#tree) · [`--html`](#html-file) · [`--color-by`](#color-by-mode) · [`--order`](#order-mode) · [`--no-stable`](#no-stable) **navigate / answer a question** — [`--around`](#around-sym) · [`--callers`](#callers-sym) · [`--callees`](#callees-sym) · [`--uses`](#uses-sym) · [`--graph-query`](#graph-query-expr) · [`--external-surface`](#external-surface) · [`--path`](#path-src-dst) · [`--connect`](#connect-a-b-c) · [`--impact`](#impact-sym) · [`--verify`](#verify-claim) · [`--mentions`](#mentions-sym) · [`--affected`](#affected-f1-f2-sym) · [`--exercises`](#exercises-testfile) · [`--situ`](#situ-f1-f2) · [`--handoff`](#handoff) · [`--test-gate`](#test-gate-f1-f2) · [`--grep`](#grep-str-regex-pat) · [`--grep-context`](#grep-context-n-grep-before-n-grep-after-n) · [`--and`](#and-str) · [`--not`](#not-str) · [`--grep-scope`](#grep-scope-line-file) · [`--grep-in`](#grep-in-code-any) · [`--handles`](#handles) · [`--match`](#match-query) · [`--pattern`](#pattern-pat) · [`--query`](#query-terms) **zoom the detail ladder** — [`--detail`](#detail-n) · [`--pack-signatures`](#pack-signatures) · [`--outline`](#outline-a-b) · [`--expand`](#expand-a-b) · [`--compress`](#compress) · [`--pack-top-n`](#pack-top-n-n) · [`--no-redact`](#no-redact) **assess quality / structure** — [`--metrics`](#metrics) · [`--deps`](#deps) · [`--hotspots`](#hotspots) · [`--clones`](#clones) · [`--readability`](#readability) · [`--nonlocal-state`](#nonlocal-state) · [`--ensemble`](#ensemble) · [`--quality-panel`](#quality-panel-preset) · [`--context-ratio`](#context-ratio) · [`--naming-calibration`](#naming-calibration) · [`--naming-consistency`](#naming-consistency) · [`--naming-locals`](#naming-locals) · [`--comment-coherence`](#comment-coherence) · [`--cochange`](#cochange-file) · [`--cochange-recur`](#cochange-recur-k) · [`--cochange-groups`](#cochange-groups) · [`--since`](#since-rev-date) · [`--arch`](#arch-file) · [`--arch`](#arch-file-baseline) · [`--arch`](#arch-file-baseline-update) · [`--lint`](#lint) · [`--lint-catalog`](#lint-catalog) · [`--lint-rules`](#lint-rules-dir) · [`--lint-select`](#lint-select-prefix) · [`--lint-ignore`](#lint-ignore-prefix) · [`--sarif`](#sarif) · [`--with-profile`](#with-profile-file) · [`--communities`](#communities) · [`--community`](#community-id) · [`--zoom`](#zoom-depth) · [`--report`](#report) · [`--seams`](#seams) · [`--mermaid`](#mermaid) · [`--owners`](#owners-sym) · [`--dead-code`](#dead-code-dir) · [`--quality-baseline`](#quality-baseline) · [`--allow-dirty`](#allow-dirty) · [`--quality-delta`](#quality-delta) · [`--quality-delta`](#quality-delta-rev-a-b) · [`--dmm`](#dmm-rev-a-b) · [`--quality-ack`](#quality-ack-reason) · [`--ack-only`](#ack-only-substr-substr) · [`--scope`](#scope-glob-glob) · [`--edit-check`](#edit-check-sym) · [`--replace-symbol-body`](#replace-symbol-body-target) · [`--insert-before-symbol`](#insert-before-symbol-target) · [`--insert-after-symbol`](#insert-after-symbol-target) · [`--edit-payload`](#edit-payload-file) · [`--edit-target-file`](#edit-target-file-path) · [`--no-post-check`](#no-post-check) · [`--edit-plan`](#edit-plan-file) · [`--dry-run`](#dry-run-apply) · [`--safe-delete`](#safe-delete-sym) · [`--slice`](#slice-sym-var) · [`--slice-flow`](#slice-flow-back-fwd-both) · [`--slice-depth`](#slice-depth-n) · [`--at`](#at-file-line) · [`--pr-context`](#pr-context-baseref) · [`--merge-scout`](#merge-scout-ref-ref) · [`--plan-lanes`](#plan-lanes-n-task-goal) · [`--plan-lanes`](#plan-lanes-brief-file) · [`--stray-content`](#stray-content-substr) · [`--plan`](#plan) · [`--abi`](#abi) · [`--whereis`](#whereis-sym) · [`--flags`](#flags-substr) · [`--flip`](#flip-name) · [`--layout`](#layout-struct) · [`--field-affinity`](#field-affinity-struct) · [`--doc-drift`](#doc-drift-substr) · [`--doc-drift`](#doc-drift-gateability) · [`--with-history`](#with-history) · [`--plan-lint`](#plan-lint-file) · [`--from-trace`](#from-trace-file) · [`--run-trace`](#run-trace-cmd) · [`--run-timeout`](#run-timeout-seconds) · [`--note-add`](#note-add-target-text) · [`--notes`](#notes) · [`--pack-task`](#pack-task-task) · [`--partition`](#partition-n) · [`--with-graph`](#with-graph) · [`--export`](#export-cc-json-file) · [`--batch`](#batch-file) **self-diagnosis** — [`--doctor`](#doctor) · [`--agent`](#agent-codex-claude) · [`--skipped`](#skipped) **security — scan skill files for injection / exfiltration patterns (exit 2 = CRITICAL, 1 = WARN,** — [`--scan-skill`](#scan-skill-file) · [`--scan-skills`](#scan-skills-dir) · [`--force`](#force) **knobs / modes** — [`--rank-by`](#rank-by-pagerank-authority-hub-rrf-churn-churn-decay) · [`--format`](#format-xml-columnar-rows) · [`--format`](#format-candidates) · [`--legend`](#legend-full-compact) · [`--json`](#json) · [`--limit`](#limit-n-offset-m) · [`--exclude`](#exclude-substr) · [`--map-diff`](#map-diff) · [`--cache`](#cache-path) · [`--index-out`](#index-out-base) · [`--no-cache`](#no-cache) · [`--no-ignore`](#no-ignore) · [`--max-file-size`](#max-file-size-n-k-m-g) · [`--refetch`](#refetch) · [`--scip`](#scip-index-scip) · [`--pin-census`](#pin-census-file) · [`--mcp`](#mcp) · [`--listen`](#listen-host-port) · [`--mcp-token`](#mcp-token-t) · [`--allow-remote-edits`](#allow-remote-edits) · [`--eval-stray`](#eval-stray-file) · [`--eval`](#eval) · [`--eval-retrieval`](#eval-retrieval) · [`--eval-mined`](#eval-mined-file) · [`--eval-skills`](#eval-skills-file) · [`-h`](#h-help) · [`-v`](#v-version) --- ## understand a codebase cold ### `--top-k=N` **Answers:** keep the N highest-ranked symbols (default 200) — applies to the default map, plain --query, and --format=candidates (incl. with --for). --for's OWN signature/lego/compose bundle self-limits via --pack-top-n instead — --top-k is INERT there (documented, not fixed — a real fix is a behavior change). --pack-task/--from-trace/--run-trace/--situ self-budget via --token-budget, not --top-k. --top-k=0 emits NO ranked map at all — ONLY the payload you asked for (--expand/--outline/--pack-signatures/--pack-top-n). Use it when you want the body and not the ~200-symbol map that otherwise rides along with it; the root then carries est_tokens= (the payload's price, the number --token-budget gates on), since no map header is there to carry it. **Try it** _Same map, capped to the 5 highest-ranked symbols._ ``` $ ./build/ripwire . --top-k=5 ... [6 more line(s); run it to see the whole thing] ``` **Shaped by:** `--token-budget`, `--recall`, `--graph-query`, `--pack-signatures`, `--expand`, `--from-trace`, `--run-trace`, `--format` **Caveats (stated by the binary):** - --for's OWN signature/lego/compose bundle self-limits via --pack-top-n instead — --top-k is INERT there (documented, not fixed — a real fix is a behavior change). ### `--max-tokens=N` **Answers:** budget the map to ~N tokens (binary-search top-K) — SHAPES the map to fit. THE FIT IS A BYTE CEILING, and it is deliberately CONSERVATIVE: N is converted at 2.36 B/tok (the densest calibrated language, so N holds for any corpus) times a 0.90 headroom factor. The map's own est_tokens uses THIS corpus's language-weighted rate instead, so a conformant fit REPORTS a number below the N you asked for — expect ~10-20% of N unused. The shaped map discloses both: max_tokens=N (asked) and fit_bytes=B (honoured). Consequence for composing it with --token-budget=N below: the two Ns are different units, so the same N on both is NOT a tautology. At a SMALL N the map's fixed floor (envelope + legend) can exceed fit_bytes with even one symbol emitted — that map says over_ceiling=1 rather than overshoot in silence, and its est_tokens can then exceed N. XML only: the --json map carries no max_tokens=/fit_bytes= keys yet, and its fit is measured in XML bytes. On --recall it SHAPES the doc bundle, and the ceiling is SPLIT ACROSS the docs rather than handed to the top hit: the budget serves the longest rank PREFIX it can give each doc a readable slice, then divides the bytes equally — a doc needing LESS than its share takes only what it needs and the surplus flows to the ones needing more. One long top hit no longer erases the rest of the corpus, and a bigger ceiling never returns FEWER docs. Docs past the prefix are dropped from the BOTTOM of the ranking; selection ORDER never changes. Every cut is DISCLOSED (header total=/shown=/capped=/truncated=/share_bytes=, a per-doc [truncated: X of Y bytes] marker, and a closing (capped: …) note); share_bytes= is that per-doc ceiling and is ABSENT when it bound no doc. **Try it** _SHAPE the map to fit ~1500 tokens (binary-search top-K)._ ``` $ ./build/ripwire . --max-tokens=1500 ... [17 more line(s); run it to see the whole thing] ``` **Shaped by:** `--token-budget`, `--recall`, `--detail`, `--pr-context`, `--from-trace`, `--run-trace`, `--limit` **Caveats (stated by the binary):** - THE FIT IS A BYTE CEILING, and it is deliberately CONSERVATIVE: N is converted at 2.36 B/tok (the densest calibrated language, so N holds for any corpus) times a 0.90 headroom factor. - Consequence for composing it with --token-budget=N below: the two Ns are different units, so the same N on both is NOT a tautology. - At a SMALL N the map's fixed floor (envelope + legend) can exceed fit_bytes with even one symbol emitted — that map says over_ceiling=1 rather than overshoot in silence, and its est_tokens can then exceed N. ### `--token-budget=N[K|M|G]` **Answers:** two personalities depending on the verb: - default map / --query / --recall: a CI GATE — exit 3 if the emitted DOCUMENT's est_tokens exceeds N. That is the map PLUS every block appended after it (///), each charged from the bytes it actually emits at the calibrated rate for what those bytes are — so --pack-top-n=3 --token-budget=600 gates on the ~67KB it would stream, not on the map alone. (test/tokenbudgetcheck.sh reports the live MAPE vs tiktoken o200k when tiktoken is installed; the estimate is calibrated, never exact — Claude's tokenizer is not public.) Within budget: exit 0, output unchanged. ASSERTS and fails, vs --max-tokens which shapes to fit — composable: set neither, either, or both (e.g. --max-tokens=16000 --token-budget=16K), but see --max-tokens above: the two Ns are measured in different units. Over budget, nothing of the artifact reaches stdout — only a small record naming withheld_est_tokens= vs budget=, the same vocabulary --recall uses, since est_tokens= is normatively about what a run PRINTED. On --recall the check likewise runs BEFORE a byte of the bundle is emitted: stdout gets the header line naming what was withheld, never the artifact just rejected. --json GATES AT A DIFFERENT NUMBER for the same request, and NOT by a fixed factor: the flag measures the DOCUMENT that was emitted, and whether JSON or XML is smaller flips with RESULT SIZE on this corpus. Small: JSON wins (MEASURED on src --top-k=20: est_tokens 1146 XML vs 899 JSON, ~22% smaller). Large: XML wins instead (MEASURED on src --top-k=200: est_tokens 9405 XML vs 9724 JSON, ~3% LARGER) — the crossover sits near top-k~100-150 here, so the same N can pass or fail differently under --json depending on dialect AND size — never assume one direction, measure the request you actually gate. - --for / --pack-task / --from-trace / --run-trace: SHAPES instead of gating — overrides that lens's own default payload budget and trims to fit, always exit 0. --for's header reports est_tokens="N" so its fit is checkable; --pack-task/--from-trace report their budget ledger in the header report line instead. On --for's auto bundle the ceiling is SPLIT, not handed to the signatures first: the sig side's claim caps at the default sig budget and the rest flows to the inline bodies, so a wider ceiling never serves fewer of them (see --for below). Its VERBATIM task echo is bytes no trim can shrink, so past some task length the header floor alone exceeds the ceiling: the lens drops the comment's DUPLICATE echo first (task_echo: dropped (ceiling); task= keeps the verbatim copy), then labels it over_ceiling (--recall: over_ceiling=1) — never a trim it did not actually do. **Try it** _GATE form: exit 3 if the map's own est_tokens exceeds the budget (over-budget failure shape)._ ``` $ ./build/ripwire . --token-budget=100 ``` **Shaped by:** `--top-k`, `--max-tokens`, `--for`, `--recall`, `--handoff`, `--pr-context`, `--from-trace`, `--run-trace` **Caveats (stated by the binary):** - That is the map PLUS every block appended after it (///), each charged from the bytes it actually emits at the calibrated rate for what those bytes are — so --pack-top-n=3 --token-budget=600 gates on the ~67KB it would stream, not on the map alone. - the estimate is calibrated, never exact — Claude's tokenizer is not public.) Within budget: exit 0, output unchanged. - On --recall the check likewise runs BEFORE a byte of the bundle is emitted: stdout gets the header line naming what was withheld, never the artifact just rejected. ### `--help-task=TASK` **Answers:** deterministic enhanced help: recommend ONE executable Ripwire CLI command for this repository and task, or abstain when evidence/applicability is insufficient. Reports the intent, integer score/margin and repository facts; never calls a model, executes the recommendation, or accesses the network. Structured claims/traces/symbols outrank lexical cues. Recommendation only; pipe trace text to stdin for --from-trace=-. **Try it** _The honest half of the contract: a task with no ripwire-shaped evidence ABSTAINS with zero commands rather than guessing._ ``` $ ./build/ripwire . --help-task="write a cheerful release announcement" ``` **Caveats (stated by the binary):** - never calls a model, executes the recommendation, or accesses the network. ### `--for=TASK` **Answers:** the task lens: ranked signatures + metrics framed for reuse. The bundle enforces a ~7.5KB default payload budget (tail entries trim first; marks it: T rows handed to the trim, S printed). The r=1 (top-ranked) row carries next="--expand=FILE:NAME" — the one pasteable follow-up, the body that ends the search (defined here, not in the bundle's own header, which the token ladder does not charge). An explicit --token-budget=N overrides the default at the conservative byte rate (SHAPES, exit 0; see --token-budget above) and the header reports the delivered est_tokens. TERMINAL BY DEFAULT: after the signatures, the top-ranked symbols' FULL bodies ride inline (CDATA + callee signatures, the --expand shape) under a fixed extra body allowance — whole-body-or-not-at-all, rank-first, capped at the --pack-task candidate cap (6). The root discloses it: bundle="auto" bodies="N" (bodies="0" reason="budget" when none fit) — on EVERY auto-mode run: a ceiling the signatures alone exhaust still carries the attribute (legend and empty shell dropped there; only the attribute has reserved bytes), and --for --json, which serves no bodies by design, says so with "bundle":"sigs". Only the caller-chosen postures (--signatures-only, --detail=N) are attribute-free. ANCHOR-ONLY when the route names one: a query that NAMES a symbol gets THAT symbol's own body or NO body — never a same-named doc section, type stub or re-export shim from another file standing in for it. If the anchor's own body does not fit, the bundle serves nothing and says so, and the per-item over-budget comment names what was dropped. COMPACT ON THE CONCEPTUAL ROUTE: a query that anchors nothing (subtoken+body) gets the ranked map plus a section — the same candidate head's ONE-HOP callee signatures, the block a body carries — and NO body CDATA, disclosed as bundle="compact" bodies="0" reason="compact-route". Read the map, then --expand=SYM the one you want. --auto-bodies restores the body walk there. That shape discloses on every run too: a ceiling the signatures alone exhaust carries bundle="compact" bodies="0" reason="budget" — three distinct reasons, never collapsed (compact-route = the route chose edges, no_candidates = nothing scored, budget = the ceiling was spent). An explicit --token-budget=N is a hard ceiling, split so a wider ceiling never buys less: the signature side's claim is capped at the DEFAULT ~7.5KB sig budget and every byte beyond it flows to the enrichment — at any ceiling at or above the default's effective total the block is byte-identical to the default run's, so every body (or hop row) the default serves still fits. An explicit --pack-top-n is an explicit SIG posture and keeps the whole-ceiling sig claim. --compress composes: the served bodies (auto/anchor and --detail=N alike) go through the same comment-strip --expand uses, disclosed as compress="1" on the element (nothing to strip on the compact route). RANKING CONFIDENCE, disclosed not scored: the root always carries confidence="high|low" margin_pct="N" — derived from the SAME relevance-cliff gap statistic --adaptive cuts at (no new scorer, no behavior change; the --json dialect carries the same two keys). low means the ranking is FLAT (no material score cliff and more positive matches than the head shows) — treat the set as a starting point, not an answer; high means a material cliff inside the served head (margin_pct= is that drop as a whole percent) or every positive match already shown **Try it** _Name-shaped query: the router picks name-exact BM25 (header says which/why)._ ``` $ ./build/ripwire . --for="rankGraphTeleport" PageRank with an explicit teleport / personalization vector p (Σp = 1). The prior is name-quality-biased through biasPrior() so all rank modes share one weighting seam; the transition matrix (edgesinline RankedGraph rankGraphTeleport( const Graph& g, const std::vector<float>&am … [line truncated: 31 more bytes on this line] #### The convergence disclosure contract … [line truncated: 85 more bytes on this line] ... [18 more line(s); run it to see the whole thing] ``` **Shaped by:** `--top-k`, `--token-budget`, `--signatures-only`, `--auto-bodies`, `--no-route`, `--adaptive`, `--no-mention-boost`, `--no-doc-mention` **Caveats (stated by the binary):** - marks it: T rows handed to the trim, S printed). - TERMINAL BY DEFAULT: after the signatures, the top-ranked symbols' FULL bodies ride inline (CDATA + callee signatures, the --expand shape) under a fixed extra body allowance — whole-body-or-not-at-all, rank-first, capped at the --pack-task candidate cap (6). - ANCHOR-ONLY when the route names one: a query that NAMES a symbol gets THAT symbol's own body or NO body — never a same-named doc section, type stub or re-export shim from another file standing in for it. ### `--signatures-only` **Answers:** (with --for) opt out of the terminal-by-default bundle: no auto bodies, no bundle="auto" attribute — the signatures-only lens exactly as before. Contradicts --detail=N (refused together); --detail=N remains the explicit body knob and supersedes the automatic pick **Try it** _T3 opt-out: the signatures-only lens (no auto bodies, no bundle="auto" attribute) — contrast with the terminal default above._ ``` $ ./build/ripwire . --for="rankGraphTeleport" --signatures-only PageRank with an explicit teleport / personalization vector p (Σp = 1). The prior is name-quality-biased through biasPrior() so all rank modes share one weighting seam; the transition matrix (edgesinline RankedGraph rankGraphTeleport( const Graph& g, const std::vector<float>&am … [line truncated: 31 more bytes on this line] #### The convergence disclosure contract … [line truncated: 85 more bytes on this line] ``` **Shaped by:** `--for`, `--auto-bodies` **Caveats (stated by the binary):** - Contradicts --detail=N (refused together); ### `--auto-bodies` **Answers:** (with --for) opt out of COMPACT conceptual serving: restore the rank-first auto walk on the subtoken+body route (bundle="auto", up to 6 full bodies) instead of the edge section. Inert on the name-exact route, where the allowance already runs. Contradicts --signatures-only and --detail=N (refused with either) **Try it** _Opt OUT of compact conceptual serving: restore the rank-first auto walk (bundle="auto")._ ``` $ ./build/ripwire . --for="tree-sitter parse of a source file" --auto-bodies The crawl's per-file byte ceiling. A text file larger than this is skipped: at this size it is o…constexpr std::size_t kDefaultMaxFileBytes = 4u * 1024u * 1024u TSTree* parseTree( TSParser* parser, std::string_view src ) inline DoctorGrammarProbe doctorProbeGrammars() errNodes/errBytes are a PARSER-STATE fact, never a syntax verdict: tree-sitter error recovery fi…struct FileHealth enum class AstWalk : std::uint8_t ... [20 more line(s); run it to see the whole thing] ``` **Shaped by:** `--for` **Caveats (stated by the binary):** - Inert on the name-exact route, where the allowance already runs. - Contradicts --signatures-only and --detail=N (refused with either) ### `--no-route` **Answers:** (with --for/--query) force plain subtoken+body BM25. Routing is now the DEFAULT: a deterministic, confidence-gated query-shape router picks name-exact BM25 when the query NAMES a symbol (identifier syntax, or every content word is a symbol name) else subtoken+body, and prints which/why in the header. It only routes with a query (the plain map is unaffected). --no-route restores the old behavior. A name-exact header also names its EVIDENCE: anchors: word(defining/file) per anchoring word, +N when N further definitions share that name, or word(syntax) when the word routed on camel/snake SHAPE and names nothing. Paths deeper than two segments print top/.../basename. Discount a one-use test helper yourself. Routing also carries the QUERY-SHAPE document demotion: when the task text parses as a stack trace, sanitizer report or compiler diagnostic, or as a pasted issue-template form, the DOCUMENT tier scores down (repo meta-prose - issue templates, CONTRIBUTING, changelogs - twice as hard) and route= names the shape, its evidence and both factors. Demotion, never exclusion, and the mention anchor still lifts a document the task NAMES. --no-route has no route= to disclose it in, so it does not demote either. **Try it** _Same query with routing forced OFF (plain subtoken+body BM25) — contrast with the routed run._ ``` $ ./build/ripwire . --for="rankGraphTeleport" --no-route uniform-teleport PageRank (the defaultinline RankedGraph rankGraph( const Graph& g, float alpha = 0.85f ) PageRank with an explicit teleport / personalization vector p (Σp = 1). The prior is name-quali…inline RankedGraph rankGraphTeleport( const Graph& g, const std::vector<float>& p, float alpha = 0.85f ) inline ChurnRanking churnRankedGraph( const MainDispatch& d ) L10 (2026-09-04): the old wording claimed "the same corpus ranked by pagerank orders differently…inline constexpr const char* kChurnRankLegend = " ``` **Caveats (stated by the binary):** - emits fixed repair commands and never prints config contents or shell command lines. ### `--skipped` **Answers:** WHY the index does not contain a file, and which files it DOES contain but cannot vouch for. per DROPPED file: why=oversize (limit= names the ceiling — --max-file-size, or the fixed .json/.yaml config ceilings it does not raise), why=excluded (--exclude hit), why=unsupported-ext (ext= has no grammar in this build — the class that hides a whole LANGUAGE). per INDEXED-but-suspect file, nothing dropped: why=degraded-parse (the parse holds ERROR/MISSING nodes — a parser-state fact, never a syntax verdict) and/or why=minified-suspect (ws_freq under 0.070 over the leading 4KB). per unindexed extension — what the map header rolls up as unindexed=. per LANGUAGE this build DID extract from — the mirror of unindexed= (which names what it could NOT read at all); sorted files DESC then name ASC, absent means the language contributed nothing, never a printed zero; files= is a floor (a file with zero extracted symbols is not attributed to any language), symbols= is exact. The root states the ACCOUNTING INVARIANT indexed= + oversize= + excluded= = the enumerated candidate population, plus unsupported_ext=, excluded_dirs= (SUBTREES --exclude pruned: contents UNKNOWN, not zero), pruned_dirs= (SUBTREES this build always prunes by policy — the committed noise/vendor/build denylist and any dir holding a CMakeCache.txt — contents likewise UNKNOWN), degraded_parse=, minified_suspect=, unmeasured= (indexed files this run never parsed) and the effective ceilings, so a zero-row report still states its bounds. rows_capped="1" ⇒ rows are a sample of an exact count. Rows sort by path; composes with --max-file-size/--exclude and multi-root (rows carry the / spelling). Read-only; exit 0 always: a report, not a gate. **Try it** _WHY a file is not in the index (oversize / excluded / unsupported-ext / gitignored) and which indexed files it cannot vouch for (degraded-parse, minified-suspect), plus the per-language census._ ``` $ ./build/ripwire . --skipped ... [17 more line(s); run it to see the whole thing] ``` **Shaped by:** `--no-ignore` **Caveats (stated by the binary):** - WHY the index does not contain a file, and which files it DOES contain but cannot vouch for. - per DROPPED file: why=oversize (limit= names the ceiling — --max-file-size, or the fixed .json/.yaml config ceilings it does not raise), why=excluded (--exclude hit), why=unsupported-ext (ext= has no grammar in this build — the class that hides a whole LANGUAGE). - per INDEXED-but-suspect file, nothing dropped: why=degraded-parse (the parse holds ERROR/MISSING nodes — a parser-state fact, never a syntax verdict) and/or why=minified-suspect (ws_freq under 0.070 over the leading 4KB). --- ## security — scan skill files for injection / exfiltration patterns (exit 2 = CRITICAL, 1 = WARN, ### `--scan-skill=FILE` **Answers:** scan a single skill file before installing (any file, not just .md) **Try it** _Scan a single skill file for injection/exfiltration patterns before installing._ ``` $ ./build/ripwire --scan-skill=skills/ripwire-orient/SKILL.md ``` ### `--scan-skills[=DIR]` **Answers:** scan DIR (or .agents/skills/ + ~/.claude/skills/ + ${CODEX_HOME:-~/.codex}/skills/). EVERY text file, .md and .sh alike — a skill dir's executables are the files most worth scanning. skipped= counts what it could not scan (binary content, or unreadable); denylisted subtrees (.git, node_modules, build, ...) are not descended and the stderr tally says how many for vulnerabilities **Try it** _Scan a whole skills directory (exit 2 = CRITICAL, 1 = WARN). Explicit-DIR form only._ ``` $ ./build/ripwire --scan-skills=skills ``` **Caveats (stated by the binary):** - skipped= counts what it could not scan (binary content, or unreadable); ### `--force` **Answers:** (wrap) proceed even if CRITICAL findings are found --- ## knobs / modes ### `--rank-by=pagerank|authority|hub|rrf|churn|churn-decay` **Answers:** ranking signal (churn = git change-frequency prior, and stamps its own map with rank_by/window/at so it cannot pass for the structural one; churn-decay = the same prior with each commit weighted 0.5^(age_days/90) instead of counted equally, so recent edits outweigh old ones. Its age clock is HEAD's OWN commit timestamp, never the wall clock, so the default (whole-history) run is byte-stable for a fixed tree; the half-life is disclosed in window=. default pagerank) **Try it** _Rank by git change-frequency prior instead of PageRank._ ``` $ ./build/ripwire . --rank-by=churn --top-k=5 ... [10 more line(s); run it to see the whole thing] ``` **Shaped by:** `--since` **Caveats (stated by the binary):** - ranking signal (churn = git change-frequency prior, and stamps its own map with rank_by/window/at so it cannot pass for the structural one; - Its age clock is HEAD's OWN commit timestamp, never the wall clock, so the default (whole-history) run is byte-stable for a fixed tree; ### `--format=xml|columnar|rows` **Answers:** output shape for the FLAT list verbs (--callers/--callees/--uses/--impact): xml (default, byte-identical) or columnar (a table + parallel arrays: fields= path,name,line,kind on --callers/--callees/--impact, path,line,role,in_id on --uses — the emitted block's own legend states the zip/n=/,-escape contract; ~15-60% fewer tokens on multi-row results, by de-duplicating the repeated per-row markup + paths; results of a few rows can be LARGER — the paths/cols scaffold has a fixed cost). rows is an alias for columnar. Any OTHER verb refuses (exit 1) — it has no row list to re-encode. Map is unaffected. **Try it** _An unknown --format value REFUSES (exit 1), named, with the supported set listed._ ``` $ ./build/ripwire . --callers=rankGraphTeleport --format=bogus (empty) ``` **Shaped by:** `--top-k`, `--pack-signatures`, `--json`, `--limit` **Caveats (stated by the binary):** - Any OTHER verb refuses (exit 1) — it has no row list to re-encode. ### `--format=candidates` **Answers:** (with --for/--query) a FLAT top-K export for an EXTERNAL reranker: one .. row per result — identity + score + signature only, no lens/quality extras, no doc bodies. Composes with --top-k. **Try it** _An unknown --format value REFUSES (exit 1), named, with the supported set listed._ ``` $ ./build/ripwire . --callers=rankGraphTeleport --format=bogus (empty) ``` **Shaped by:** `--top-k`, `--pack-signatures`, `--json`, `--limit` ### `--legend=full|compact` **Answers:** output legend posture for EVERY XML verb. full is byte-identical to the default. compact keeps every row byte and every data/completeness attribute (counts_floor= capped= shown= total= has_more= next_offset= est_tokens= at= root= graph_ambiguous= …), adds a versioned schema id on the root (schema="ripwire./v1") and replaces the explanatory prose with ONE <=400 B legend naming those attributes — the meanings live here and in the full legend. DATA comments stay (the map header, pack-task's body-omitted rows, +more). Per call this drops 2.9-5.2 KB on the navigation verbs (--edit-check 5.2 KB -> <0.4 KB); the MCP twin is the argument legend: on every XML-answering verb, where compact is the DEFAULT and legend:"full" restores this prose (M1, 2026-09-05: the ten-verb MCP edit loop pays 2,866 B of legend instead of 30,839 B). The CLI default stays full. Runs with nothing to compact refuse it, naming the verb: prose/markdown/JSON answers (--situ --recall --report --mermaid --html --plan-lanes --sarif --eval*) and the writers (edit verbs, --note-add, --quality-baseline/--quality-ack, --index-out, --export). **Try it** _The same gating report under --legend=compact — same rows, same exit 2, schema="ripwire.quality-delta/v1", ~4 KB of legend down to one comment: the shape an agent's edit loop should run._ ``` $ ./build/ripwire . --quality-delta --legend=compact ... [24 more line(s); run it to see the whole thing] ``` **Caveats (stated by the binary):** - Runs with nothing to compact refuse it, naming the verb: prose/markdown/JSON answers (--situ --recall --report --mermaid --html --plan-lanes --sarif --eval*) and the writers (edit verbs, --note-add, --quality-baseline/--quality-ack, --index-out, --export). ### `--json` **Answers:** machine-parseable JSON instead of XML, keys mirror the XML attr names 1:1. Every ROOT attribute survives; a verb that serves fewer SECTIONS than its XML form NAMES them in lens= on the root (--for --json: lens="compose,lego,routes,docs" — their *_total counts are there, their rows are not) — supported for the default map, --for, --pack-task, --callers/--callees/ --impact, --quality-delta, --test-gate, --metrics (the CI/scripting verbs), plus --plan-lanes which is JSON-native. That set is an ALLOW-list: every other verb (and --format=columnar/candidates, --detail, --map-diff, --scip composed with it) refuses loudly on stderr + exit 1 rather than silently falling back to XML — a verb added tomorrow refuses by default. Deterministic: same 2-run byte-diff + stable key order contract as the XML. **Try it** _JSON refusal shape: an unsupported verb refuses loudly instead of silently falling back to XML._ ``` $ ./build/ripwire . --hotspots --json (empty) ``` **Shaped by:** `--max-tokens`, `--token-budget`, `--for` **Caveats (stated by the binary):** - That set is an ALLOW-list: every other verb (and --format=columnar/candidates, --detail, --map-diff, --scip composed with it) refuses loudly on stderr + exit 1 rather than silently falling back to XML — a verb added tomorrow refuses by default. ### `--limit=N --offset=M` **Answers:** paginate a high-cardinality verb. HONORED by: --deps --callers --callees --tree --lint --hotspots --clones --cochange --owners --communities --community --doc-drift --whereis --grep/--regex --match --pattern --impact --uses --exercises --seams --zoom --external-surface --dead-code --mentions --graph-query --stray-content --test-gate --readability --ensemble --quality-panel --context-ratio --nonlocal-state --comment-coherence --naming-consistency --safe-delete --pr-context. Emit at most N rows, skipping the first M; N overrides the verb's own display cap (40 hotspot files, 30 co-change pairs, 60 whereis hits, 100 grep/match hits, 40 impact rows, 20 seam pairs, 40 readability rows, 40 ensemble symbol rows, 40 context-ratio symbol rows, 40 nonlocal-state rows, 200 graph-query rows / --top-k). With --offset alone (no --limit) the verb's own default page size applies and the root discloses limit="0" — on OUTPUT that 0 means 'no explicit --limit', never a zero-row page (the flag itself refuses --limit=0). A BARE run whose default cap cut rows (capped="1") carries the same limit="0" and the whole paging block below, so you can page from the first answer without guessing. Deterministic seams (rows are already sorted) so --offset=N is the exact continuation of the previous --limit=N page. The root element then carries shown= capped= total= has_more= next_offset= offset= limit= — loop until has_more="0". capped= compares the PAGE to the total (1 ⇔ shown < total), so a page past the end reads shown="0" capped="1" has_more="0": nothing was cut, the offset skipped everything — EXCEPT the verbs with TWO INDEPENDENT listings, which carry the noun-prefixed form instead (one shown= could only describe one): --test-gate shown_tests=/tests_capped= + shown_untested=/untested_capped=, --communities shown_modules=/modules_capped= + shown_bridges=/bridges_capped=, --ensemble and --context-ratio shown_syms=/syms_capped= + shown_files=/files_capped=; the window takes the PRIMARY listing (--test-gate's rows; its rows repeat on every page, complete). Any verb NOT in that list REFUSES both flags (exit 1) rather than accepting and ignoring them: budget/top-k verbs (--for/--recall/--pack-task/--from-trace/ --expand/--outline/--pack-signatures/--format=candidates) are shaped by --top-k/--max-tokens/--token-budget, not a page; the rest (--path/--connect/ --around/--exemplar/--report/--mermaid/--map-diff/--metrics and the default map) answer with a single fixed-shape result that has no row list to window at all. **Try it** _The family join: per function, which of four orthogonal evidence families fire, ranked by how many agree._ ``` $ ./build/ripwire . --ensemble --limit=8 ... [17 more line(s); run it to see the whole thing] ``` **Shaped by:** `--tree`, `--graph-query`, `--external-surface`, `--exercises`, `--community`, `--zoom`, `--pr-context` **Caveats (stated by the binary):** - Emit at most N rows, skipping the first M; - With --offset alone (no --limit) the verb's own default page size applies and the root discloses limit="0" — on OUTPUT that 0 means 'no explicit --limit', never a zero-row page (the flag itself refuses --limit=0). - A BARE run whose default cap cut rows (capped="1") carries the same limit="0" and the whole paging block below, so you can page from the first answer without guessing. ### `--exclude=SUBSTR` **Answers:** drop matching paths (repeatable) --ignore-tests **Try it** _Drop matching paths (repeatable) before ranking._ ``` $ ./build/ripwire . --exclude=present --exclude=bench --top-k=5 ... [6 more line(s); run it to see the whole thing] ``` **Shaped by:** `--skipped`, `--index-out` ### `--map-diff` **Answers:** the FULL map, re-ranked with a PageRank teleport toward git-changed files (working tree vs HEAD) — changed files and their neighbours float up, but every file can still appear; this is NOT a filter to only-changed symbols. changed="N" in the header names the seed file count (0 on a clean tree or no-git — teleport degrades to uniform; ranked CONTENT is then identical to the plain default map, but not byte-identical: the map-diff header keeps its changed= and at= stamp). Want only-changed instead? --pr-context. **Try it** _Full map re-ranked with teleport toward git-changed files — recorded against a DIRTY tree, so changed= counts the working copy's files and the teleport is live._ ``` $ ./build/ripwire . --map-diff --top-k=5 ... [7 more line(s); run it to see the whole thing] ``` **Shaped by:** `--json`, `--limit` **Caveats (stated by the binary):** - this is NOT a filter to only-changed symbols. - changed="N" in the header names the seed file count (0 on a clean tree or no-git — teleport degrades to uniform; ### `--cache=PATH` **Answers:** incremental cache at PATH (re-parse only changed files) **Try it** _Explicit incremental cache at a path OUTSIDE the repo (first call writes it)._ ``` $ ./build/ripwire . --cache=/aux/warm2.ripwirecache --top-k=3 ... [4 more line(s); run it to see the whole thing] ``` **Shaped by:** `--doctor`, `--index-out` ### `--index-out=BASE` **Answers:** CI generate-and-exit: cold-parse the tree and write the committable index artifact, then exit 0 with NO map on stdout. Writes BOTH families — BASE.lean.ripwirecache (map/ nav/--pr-context) and BASE.rich.ripwirecache (--for/--exemplar/--metrics/--uses are RICH, a lean-only artifact leaves them cold). Consume in a PR job with --cache=BASE.lean.ripwirecache (or .rich.). --exclude shapes the crawl and therefore the blob content. Same-architecture speed cache: consumed on a different arch it self-heals to a full cold parse (correct, slower). NOT byte-identical run-to-run (the header stamps the blob write time); the contract is RESTORE-EQUIVALENCE (a --cache restore == a cold parse), never blob-byte-identity. **Try it** _CI generate-and-exit: cold-parse and write BOTH committable cache families (lean + rich), no map on stdout._ ``` $ ./build/ripwire . --index-out=/aux/ci_index (empty) ``` **Shaped by:** `--doctor`, `--legend` **Caveats (stated by the binary):** - the contract is RESTORE-EQUIVALENCE (a --cache restore == a cold parse), never blob-byte-identity. ### `--no-cache` **Answers:** disable the warm-by-default per-root TMPDIR cache (forces a cold parse) **Try it** _Force a cold parse (bypass the warm TMPDIR cache) — shows the cold-vs-warm cost._ ``` $ ./build/ripwire . --no-cache --top-k=3 ... [4 more line(s); run it to see the whole thing] ``` **Shaped by:** `--doctor` ### `--no-ignore` **Answers:** crawl paths the repository's own .gitignore covers. DEFAULT: in a git work tree the crawl honours git's ignore rules (node_modules/, .venv/, target/, build/, dist/ — whatever the repo declared), and the header discloses ignored_files= / ignored_dirs= when it dropped anything. A non-git root, a missing git binary, or a root that is ITSELF inside an ignored subtree all keep the full walk; --skipped's ignore_mode= says which of the four applied, and rows the ignored set. **Try it** _Crawl paths the repo's own .gitignore covers (default honours it and discloses ignored_files=/ignored_dirs= only when it dropped anything — this repo's crawl drops nothing, so the header is identical to the default map's; --skipped's ignore_mode= says which rule applied)._ ``` $ ./build/ripwire . --no-ignore --top-k=3 ... [4 more line(s); run it to see the whole thing] ``` **Caveats (stated by the binary):** - --skipped's ignore_mode= says which of the four applied, and rows the ignored set. ### `--max-file-size=N[K|M|G]` **Answers:** skip files larger than N bytes (default 4MB; raise for repos with big hand-authored source, e.g. --max-file-size=100M; suffix = 1024^n). .json carries a SECOND, fixed 256KB ceiling this flag does not raise (that size of .json is data, not config, and explodes the symbol table); files it drops are counted in the header's skipped_oversize= **Try it** _Skip files above a size bound before parsing (note the corpus shrink in the header)._ ``` $ ./build/ripwire . --max-file-size=8K --top-k=3 ... [4 more line(s); run it to see the whole thing] ``` **Shaped by:** `--skipped` **Caveats (stated by the binary):** - skip files larger than N bytes (default 4MB; - files it drops are counted in the header's skipped_oversize= ### `--refetch` **Answers:** when the root is a git URL, force a fresh clone instead of reusing the cached one (default: reuse forever; stderr notes the cached clone's age) ### `--scip=index.scip` **Answers:** consume a SCIP index as a PRECISION overlay: precise call edges replace name-based guesses (tagged prov="scip"), ambiguous= drops. Missing/corrupt index → degrades to name-based (never fails). Zero deps (hand-rolled reader). **Try it** _SCIP overlay with a missing index REFUSES (exit 1) naming the file — never silently serves the name-based map you named a precision index to improve on (it used to degrade in silence)._ ``` $ ./build/ripwire . --scip=does_not_exist.scip --callers=rankGraphTeleport (empty) ``` **Shaped by:** `--json`, `--pin-census` **Caveats (stated by the binary):** - consume a SCIP index as a PRECISION overlay: precise call edges replace name-based guesses (tagged prov="scip"), ambiguous= drops. - Missing/corrupt index → degrades to name-based (never fails). ### `--pin-census=FILE` **Answers:** eval-only: write a per-call-site census of WHICH mechanism resolved each call (unique/qualified/receiver-rule/cone/arity/locality/split/scip/binding) and the canonical id of every surviving target — the identity omits. Under --scip it also writes the index's covered sites, so a precision join needs no protobuf reader. stdout is byte-identical with or without it. **Try it** _Eval-only: a per-call-site census of WHICH mechanism resolved each call, and the canonical id of every surviving target._ ``` $ ./build/ripwire . --pin-census=/aux/pin_census.tsv --top-k=3 ... [4 more line(s); run it to see the whole thing] ``` ### `--mcp` **Answers:** persistent index server (parse once, many warm queries) over stdio **Try it** _initialize + tools/list: the manifest an agent host loads at session start — every verb's name, description and input schema._ ``` $ ./build/ripwire '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize"}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | ./build/ripwire --mcp {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","serverInfo":{"name":"ripwire","version":"1.0"},"capabilities":{"tools":{}},"instructions":"Map before reading files. Start a new task with explore; use from_trace for an error; use impact plus uses before changing a symbol; run edit_c … [line truncated: 368 more bytes on this line] {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"analyze","description":"Architecture map for a directory: signatures and the call graph for the top symbols. Use when landing cold in a repo or subdir, before reading files; for a task-scoped inventory use 'for', for one symbol's neighborhood find_ … [line truncated: 729 more bytes on this line] {"name":"find_symbol","description":"A symbol's 1-hop neighborhood: the symbol (with a fetch_body handle) plus direct callers (calledBy) and callees (calls). Full transitive reach: 'impact'. Read/write/import sites, not just calls: 'uses'. JSON {symbol, calledBy, calls, defs, count, hop_tested, hop_ … [line truncated: 1095 more bytes on this line] {"name":"find_referencing_symbols","description":"Direct (1-hop) callers of a symbol, each with a fetch_body handle. For the full transitive blast radius use 'impact', for read/write/import sites 'uses'. JSON {symbol, calledBy, defs, count, hop_tested, hop_untested, counts_floor}; calledBy is a FLOO … [line truncated: 797 more bytes on this line] ... [30 more line(s); run it to see the whole thing] ``` **Shaped by:** `--no-stable`, `--no-redact`, `--agent`, `--listen` ### `--listen=HOST:PORT` **Answers:** serve the MCP server over Streamable HTTP instead of stdio (implies --mcp). Binds 127.0.0.1 by default (bare PORT = loopback); one listener serves ONE workspace fixed at startup. A non-loopback host (e.g. 0.0.0.0:8080) REQUIRES --mcp-token and refuses to start without it. No TLS — reverse-proxy it. **Shaped by:** `--no-stable`, `--allow-remote-edits` **Caveats (stated by the binary):** - 0.0.0.0:8080) REQUIRES --mcp-token and refuses to start without it. ### `--mcp-token=T` **Answers:** shared bearer token gating every HTTP request (or set RIPWIRE_MCP_TOKEN); a missing/wrong token gets a 401. Required for a non-loopback bind. **Shaped by:** `--listen` ### `--allow-remote-edits` **Answers:** permit the edit verbs over --listen (refused by default: a remote file-writer is a different trust contract); forces the token requirement even on loopback **Caveats (stated by the binary):** - permit the edit verbs over --listen (refused by default: a remote file-writer is a different trust contract); ### `--eval-stray=FILE` **Answers:** labelled verdict-accuracy eval for --stray-content: FILE is TSV `refverdict` (merged|superseded|unmerged, '#' comments ok). Emits per-case want=/got= plus an accuracy, and exits 3 if any labelled case regressed — MEASURE a supersession- threshold change against real labels instead of eyeballing it. A ref absent from the report scores as merged (merged refs are omitted by design). **Try it** _Labelled verdict-accuracy eval for --stray-content — three labels over REAL local refs (names resolved at capture time); exit 3 when accuracy is under the floor. Read got= against v= in the stray-content run: a ref the verb could not analyse (unknown) must never be credited as a merged hit._ ``` $ ./build/ripwire . --eval-stray=/aux/stray_labels2.tsv # refverdict labels for --eval-stray (the first three local branches, resolved at capture time; a missing branch is padded with a nonexistent name on purpose) audit/stranger-install-2026-09-06 merged backup/rc-C2-preclean unmerged backup/rc-D-preclean merged ``` ### `--eval` **Answers:** self-eval (co-change recall vs BM25) **Try it** _Self-eval: co-change recall vs BM25._ ``` $ ./build/ripwire . --eval ripwire --eval (co-change recovery, averaged over 80 historical commits) ranker recall@5 recall@10 recall@20 ripwire 2.4% 6.2% 8.8% BM25 14.0% 18.0% 22.3% BM25sub 18.7% 22.5% 28.1% BM25body 32.1% 37.5% 45.1% fused 8.3% 21.9% 26.7% anchored 31.2% 38.7% 45.1% same-dir 3.3% 3.6% 4.7% random 0.3% 0.6% 1.2% <- floor (random ranking over F=1616 files) note: `ripwire` here is the DEFAULT MAP's structural-only PageRank (importance, not relatedness) — it is NOT what a --for/--query retrieval call ranks with. BM25 / BM25sub / BM25body are QUERY-TIME lexical rankers (whole-name / subtoken / subtoken+body); fused = RRF(ripwire, BM25sub); anchored = BM25body + anchored PPR ... [5 more line(s); run it to see the whole thing] ``` **Shaped by:** `--legend` ### `--eval-retrieval` **Answers:** known-item retrieval eval: for symbols WITH a doc-comment, query by NAME and by a doc-comment PHRASE; reports MRR + recall@1/5/10 per ranker (subtoken+body, name-exact, anchored, routed) per query-mode. Validates query-TIME ranker choice. **Try it** _Known-item retrieval eval: MRR + recall@k per ranker per query mode._ ``` $ ./build/ripwire . --eval-retrieval ripwire --eval-retrieval (known-item, 3562 doc-commented symbols; gold is in-corpus by construction) sample: population=3562 scored=3562 rule=exhaustive (every qualifying symbol; path- and order-independent) ingest: lex=rich (persisted subtoken stats; no per-query corpus re-tokenize) ranker query-mode MRR recall@1 recall@5 recall@10 subtoken name 0.724 59.2% 88.9% 93.5% subtoken doc-phrase 0.931 91.0% 95.3% 96.0% name-exact name 0.922 85.5% 97.6% 98.3% name-exact doc-phrase 0.017 0.6% 2.6% 3.4% anchored name 0.725 60.2% 87.7% 92.1% anchored doc-phrase 0.926 90.1% 95.0% 95.9% routed name 0.923 85.5% 97.6% 98.4% routed doc-phrase 0.930 91.0% 95.2% 95.8% note: routing chose name-exact on 3560/3562 NAME queries (a NAME query is always identifier-shaped); the confidence gate routes doc-phrase queries to name-exact ONLY when EVERY content word names a symbol ... [4 more line(s); run it to see the whole thing] ``` ### `--eval-mined=FILE` **Answers:** session-trace-mined retrieval eval: consumes a minedpair.jsonl artifact from bench/mine_traces.py (real (query, gold-files) pairs mined from local Claude Code session transcripts) and reports recall@5/10/20 + Acc@k + MRR per arm (for/query/anchor/random), assisted vs unassisted. ### `--eval-skills=FILE` **Answers:** labelled skill-ROUTING eval: ROOT is a skills directory (one SKILL.md per subdir); FILE is TSV `promptskill[,skill]|noneprovenance`. Scores deterministic selectors (keyword overlap = the trivial baseline, BM25 over descriptions/full text, name match, the routed --for ranker) on top-1-in- permitted-set plus positive/negative separation (AUC) — does the right skill fire, does every skill stay quiet on off-topic prompts. Ambiguous moments carry a permitted SET; `none` rows are first-class. **Try it** _Labelled skill-ROUTING eval over the repo's own skills/ directory (4 hand-labelled prompts)._ ``` $ ./build/ripwire skills --eval-skills=/aux/skills_labels2.tsv orient in an unfamiliar codebase fast ripwire-orient judged who calls this function and what is the blast radius ripwire-navigate judged plan parallel worktrees so the lanes do not collide ripwire-change-check judged what is the weather in Paris none neg ``` **Caveats (stated by the binary):** - Ambiguous moments carry a permitted SET; ### `-h, --help` **Answers:** this catalog **Shaped by:** `--html`, `--color-by`, `--around`, `--callers`, `--callees`, `--affected`, `--expand`, `--metrics` ### `-v, --version` **Answers:** print the version + short build info, exit 0 **Try it** _Version + short build info._ ``` $ ./build/ripwire --version ripwire 0.4.0 (dev, AppleClang 21.0.0.21000101, built_from=5ca98897b) ``` **Shaped by:** `--impact`, `--verify`, `--metrics`, `--deps`, `--naming-locals`, `--arch`, `--dry-run`, `--doc-drift` --- _Generated by `docs/docs_commands_build.py`. See `docs/README.md` for the documentation index._