` one family at full detail. // `--help=all` the whole catalog, exactly as before. // // Tier 2 is what every MACHINE consumer reads (the gates that harvest the advertised surface, // docs/docs_commands_build.py). Tier 1 is what a human or an agent reads. Neither can starve the other: // test/helpbudgetcheck.sh holds tier 1 to a token ceiling AND asserts tier 2 still carries every row. enum class HelpTier : std::uint8_t { Concise, // one line per row Full, // the entire catalog Pick // one flag, or one section }; // A line's role in the catalog, decided by indentation alone — the same contract // docs/docs_commands_build.py's parse_help() parses this text with. // // FOUR SPACES IS THE ONLY INDENT THAT MEANS "THIS ROW EXISTS". Anything deeper is prose, however much // it looks like a row, and tier 1 drops it. v0.6.0 shipped the counter-example: twelve flag rows were // written at SIX spaces to read as sub-flags of the entry above them, this function classified all // twelve as Cont, and fifteen real flags — --and --not --grep-in --grep-scope --grep-context // --grep-before --grep-after --ack-only --scope --edit-payload --edit-target-file --no-post-check // --dry-run --apply --partition — were absent from `--help` while working perfectly. parse_help then // accepted 4..6, so docs/COMMANDS.md listed every one of them and the disagreement had no symptom // there; the only visible edge was `--help=--and` REFUSING with "`ripwire --help` lists every row", // which was a false claim about our own output. // Nest a sub-flag by what its summary SAYS, never by moving it right; test/helpbudgetcheck.sh arm (K) // fails the moment an accepted flag stops being named on the first screen. enum class HelpLine : std::uint8_t { Section, // two spaces then text: a family heading Entry, // four spaces then a flag, or a two-column `label description` row Subhead, // four spaces of prose that is not a row (a mid-section aside) Cont, // five or more spaces: an entry's continuation — tier 2's whole payload Loose // blank, or column-zero prose (preamble, usage block, closing line) }; inline HelpLine classifyHelpLine( std::string_view l ) noexcept { const std::size_t text = l.find_first_not_of( ' ' ); if( text == std::string_view::npos || text == 0 ) { return HelpLine::Loose; } if( text == 2 ) { return HelpLine::Section; } if( text >= 5 ) { return HelpLine::Cont; } // At four: a flag row always starts with '-'; anything else is a row only if it has the // two-column shape (`label` + two-or-more spaces + description), which is how the shared // legend rows — counts_floor="1", pr_iters="N", — earn an entry of their own. if( l[text] == '-' ) { return HelpLine::Entry; } const std::size_t gap = l.find( ' ', text ); if( gap == std::string_view::npos ) { return HelpLine::Subhead; } return gap + 1 < l.size() && l[gap + 1] == ' ' ? HelpLine::Entry : HelpLine::Subhead; } // Strip a flag spelling down to its bare name: leading dashes off, value/alternation suffix off. inline std::string_view helpBareName( std::string_view s ) noexcept { while( !s.empty() && s.front() == '-' ) { s.remove_prefix( 1 ); } const std::size_t cut = s.find_first_of( "=[,| \t" ); return cut == std::string_view::npos ? s : s.substr( 0, cut ); } // Does this entry line answer to `want`? Leading dashes are optional on both sides, and every flag // spelled in the row's LABEL counts — `--grep=STR | --regex=PAT` is one row that two names must reach, // and so is `--limit=N --offset=M`. // // Only the label column is searched, and within it only the leading token and tokens that start with a // dash. Both narrowings are load-bearing. Searching the DESCRIPTION makes `--help=--for` match // --help-task, whose prose reads "recommend ONE executable command for this repository"; matching bare // words makes it match any row that happens to say "for". A row answers to the flags it DEFINES, never // to the flags it mentions. inline bool helpEntryAnswersTo( std::string_view line, std::string_view want ) noexcept { const std::string_view target = helpBareName( want ); if( target.empty() ) { return false; } const std::size_t first = line.find_first_not_of( ' ' ); if( first == std::string_view::npos ) { return false; } // The label column ends at the first two-space run — the gap before the description. A row with no // such gap (the --plan-lanes header line) is all label, and the dash rule below keeps it honest. const std::size_t gap = line.find( " ", first ); const std::size_t limit = gap == std::string_view::npos ? line.size() : gap; for( std::size_t i = first; i < limit; ++i ) { const bool startsToken = i == first || line[i - 1] == ' ' || line[i - 1] == '|'; if( !startsToken ) { continue; } if( i != first && line[i] != '-' ) { continue; } if( helpBareName( line.substr( i, limit - i ) ) == target ) { return true; } } return false; } // A section is picked by any run of its heading — `--help=quality` finds "assess quality / structure". inline bool helpSectionAnswersTo( std::string_view heading, std::string_view want ) noexcept { if( want.size() < 3 || heading.size() < want.size() ) { return false; } const auto lower = []( char c ) noexcept { return c >= 'A' && c <= 'Z' ? char( c + 32 ) : c; }; for( std::size_t i = 0; i + want.size() <= heading.size(); ++i ) { std::size_t k = 0; while( k < want.size() && lower( heading[i + k] ) == lower( want[k] ) ) { ++k; } if( k == want.size() ) { return true; } } return false; } // Streaming state, carried across the three text blocks so an entry that straddles a block boundary // is still one entry. struct HelpFilter { HelpTier tier = HelpTier::Full; std::string_view want; // Pick only bool wantIsSection = false; // Pick: `want` named a heading, so serve to the next one bool serving = false; // Pick: inside the selected entry or section bool hit = false; // Pick: anything served at all }; // The Pick state machine, split out of the emit loop so each stays under the complexity bar and the // selection rule can be read on its own: a SECTION match serves until the next heading, an ENTRY match // serves that entry's continuations, and column-zero prose ends a served entry. inline bool helpPickKeeps( HelpFilter& f, HelpLine kind, std::string_view line ) noexcept { if( kind == HelpLine::Section ) { f.serving = helpSectionAnswersTo( line, f.want ); if( f.serving ) { f.wantIsSection = true; f.hit = true; } } else if( kind == HelpLine::Entry && !f.wantIsSection ) { f.serving = helpEntryAnswersTo( line, f.want ); if( f.serving ) { f.hit = true; } } else if( kind == HelpLine::Loose && !f.wantIsSection ) { f.serving = false; } return f.serving; } inline void emitHelpBlock( std::FILE* out, HelpFilter& f, std::string_view text ) noexcept { while( !text.empty() ) { const std::size_t nl = text.find( '\n' ); const std::size_t take = nl == std::string_view::npos ? text.size() : nl + 1; const std::string_view raw = text.substr( 0, take ); const std::string_view line = nl == std::string_view::npos ? raw : raw.substr( 0, raw.size() - 1 ); text.remove_prefix( take ); const HelpLine kind = classifyHelpLine( line ); const bool keep = f.tier == HelpTier::Full ? true : f.tier == HelpTier::Concise ? kind != HelpLine::Cont : helpPickKeeps( f, kind, line ); if( keep ) { std::fwrite( raw.data(), 1, raw.size(), out ); } } } /// Print the CLI usage and flag catalog to `out` at the requested tier. /// `want` is read only for HelpTier::Pick. Returns false when a Pick matched nothing. inline bool printUsageTier( std::FILE* out, HelpTier tier, std::string_view want ) noexcept { HelpFilter f{ tier, want, false, false, false }; emitHelpBlock( out, f, kHelpHead ); emitHelpBlock( out, f, kHelpPlanLanes ); emitHelpBlock( out, f, kHelpTail ); return tier != HelpTier::Pick || f.hit; } /// Print the authoritative CLI usage and flag catalog to the caller-provided output stream. inline void printUsage( std::FILE* out ) noexcept { printUsageTier( out, HelpTier::Full, {} ); } // `--help=X` — tier 2. Its own function rather than an arm inside parseArgs, which is already the // most complex function in this file and does not need eleven more branches to serve a help selector. [[noreturn]] inline void serveHelpSelector( std::string_view want ) noexcept { if( want == "all" ) { printUsage( stdout ); std::exit( 0 ); } if( want.empty() ) { rw::emitRaw( stderr, "ripwire: --help= needs a flag, a section name, or 'all' (e.g. --help=--for, --help=quality, --help=all)\n" ); std::exit( 2 ); } if( printUsageTier( stdout, HelpTier::Pick, want ) ) { std::exit( 0 ); } // An honest miss names the tier that WOULD have the answer rather than printing it unasked. rw::emitTo( stderr, "ripwire: --help={} matched no flag or section — `ripwire --help` lists every row, `--help=all` is the whole catalog\n", std::string_view( want.data(), want.size() ) ); std::exit( 2 ); } // A parse error is not a request for the catalog. Forgetting the positional is the most likely // first-run mistake there is, and it used to answer with all 185 KB of tier 2 on stderr — ~46 000 // tokens for a typo, when an UNKNOWN FLAG had always cost 32 bytes. The tool already knew the right // shape for a mistake; it just never applied it here. inline void usage() noexcept { rw::emitRaw( stderr, "ripwire: no given — the repository to map is the one required argument.\n ripwire . the ranked map of the current directory\n ripwire . --for=\"TASK\" the task lens: what to read first\n ripwire --help every flag, one line each\n ripwire --help=--for one flag in full (also --help=

, --help=all)\n" ); } // ── the flag tables — the 91 arms that are exactly "set one member" ───────────────────────────────── // House style is declarative tables over scattered switch/if (CLAUDE.md), and this is that rule applied // to the two shapes that make up most of the argv surface: `--x` sets one bool, `--x=V` sets one view. // Config is 71 bool + 54 string_view, so a pointer-to-member is constexpr and well-defined here — no // offsetof, which would be UB on a non-standard-layout type. // // ORDER. The tables are scanned in DECLARATION ORDER, exacts before prefixes, ahead of the hand-written // arms — so the chain's original precedence is preserved only because no literal in the surface shadows // another. That is not asserted, it is re-derived from src/cli.h on every run by test/flagtablecheck.sh: // no table prefix is a prefix of any other arm's literal, and an exact match cannot swallow a longer // argv. Add a flag that violates it and that gate goes red before the parser does anything surprising. // // The `//` note on an arm travels WITH its row — a table row is already less greppable than an inline // equality test, and stripping the prose that explains why a bare flag is legal would make it worse. // (The literal that would have illustrated that is deliberately absent: flagsurfacecheck.sh harvests the // parsed surface from THIS file's string literals, so a fake --flag in a comment reads as a real one.) struct BoolFlag { std::string_view lit; bool Config::* member; }; // §A9 V1-4: `needs`/`example` are the EMPTY-VALUE contract. Non-null `needs` ⇒ `--flag=` with nothing after // the '=' is refused (exit 1) through refuseEmptyValue above, naming this flag and showing `example`. // Left null ⇒ an empty value is meaningful for that flag (a path/label the rest of the parser interprets, // or a value whose own arm already refuses) and the argv reaches the member unchanged. A new value-taking // flag therefore has to state which it is, in the row, at the point the flag is declared. // // OWNER RULING 2026-07-29 (recorded as reversible): NINE rows were // carrying that null by omission rather than by decision — `--since=` `--cache=` `--index-out=` `--scip=` // `--lint-rules=` `--mcp-token=` and the three `--eval-*=` — and downstream every one of them is guarded by // `!cfg.X.empty()`, so the empty value did not reach a member that means anything: the run emitted the // whole default map at exit 0 with nothing on stderr. `--hotspots --since=zzqq9` refuses loudly while // `--hotspots --since=` was silent, one keystroke apart. The ruling is refuse-ALL: every row now states its // domain and an example, including the five config-passthrough paths, so "an empty value is a no-op here" // is no longer expressible by forgetting to fill the columns in. There are now no null-`needs` rows — // leaving one is still legal, but it has to be argued for in the row, which is the whole point of the pair. // §B5 (capture-audit-4, 2026-07-30) — WHAT AN EMPTY VALUE MEANS, as a required table column. // // Last round's refuse-all ruling swept this table's 33 rows and left the 40 hand-written arms in parseArgs // alone, which is trap-ledger #6 in the flesh ("a ruling that produces a table sweeps the table, not the // surface"). The sweep found four arms out there silently accepting an empty value — the sharpest being // `--listen=`, where a `$PORT` that expanded to nothing turned a NETWORK TRANSPORT SELECTOR into a live // stdio MCP server at exit 0, one keystroke from the `--listen=notaspec` form that refuses loudly. // // Adding four more hand-written refusals would have reproduced the bug (36 arms still outside the table), so // instead the arms MOVED IN — every hand-written arm whose whole body was "assign one string_view member, // optionally set one or two companion bools" is now a row here (44 → 17 hand-written). What a table cannot // express honestly stays hand-written: a vector member (--exclude=, --expand=, --outline=), a byte-size or // enum PARSE (--token-budget=, --rank-by=, --format=, --export=, …), the deprecation-warning aliases. // // And the column below is why this class cannot come back. `needs`/`example` alone could only say "refuse"; // they could not tell a row that DELIBERATELY accepts an empty value (`--situ=` means exactly `--situ`) from // a row nobody had thought about — the two looked identical, which is how nine rows shipped with // needs=nullptr last round and four arms shipped with no check at all this one. `EmptyValue` makes the // decision MANDATORY and NAMED, and consteval below enforces that `needs` is present exactly for Refuse. enum class EmptyValue : std::uint8_t { Refuse, // a trailing `=` with nothing after it is a MISTYPED VERB: refuse here, via refuseEmptyValue Meaningful, // "" is a real value for this flag — the bare-or-filter forms, where --flag= ≡ --flag HandlerRefuses, // the verb's own handler refuses it with a verb-specific sentence; recorded so that // "accepted silently" can never hide behind "not in the table". Each such row names // the refusing handler in a trailing comment. }; struct ViewFlag { std::string_view prefix; // "--grep=" — matched by PREFIX, so declaration order matters std::string_view Config::* member; // the value's home EmptyValue onEmpty = EmptyValue::Refuse; const char* needs = nullptr; // the DOMAIN in the refusal's voice — Refuse rows only const char* example = nullptr; // runnable, and inside that domain — Refuse rows only bool Config::* isSetFlag = nullptr; // companion bool the =VALUE form also sets (--owners= ⇒ owners) bool Config::* isSetFlagAlso = nullptr; // a SECOND companion (--quality-ack= ⇒ qualityAck + qualityDelta) // G1/F1: a GENERIC "already given" guard, distinct from isSetFlag's verb-selection meaning — two rows // (--grep= and --regex=) point at the SAME member (Config::grep) and a second occurrence of EITHER used // to silently overwrite the first. When set, a row REFUSES (dupMessage, exit-1-with-example, the house // refusal shape) instead of assigning, the moment `c.*dupGuardFlag` is already true; on a clean first // assignment it flips the flag true so a genuine second occurrence — of either spelling — is caught. bool Config::* dupGuardFlag = nullptr; const char* dupMessage = nullptr; // printed verbatim (with the "ripwire: " lead-in) when dupGuardFlag fires }; inline constexpr BoolFlag kBoolFlags[] = { // map shaping { "--ignore-tests", &Config::ignoreTests }, { "--map-diff", &Config::mapDiff }, // server + self-eval entry points { "--mcp", &Config::mcp }, { "--lsp", &Config::lsp }, { "--allow-remote-edits", &Config::allowRemoteEdits }, { "--eval", &Config::eval }, { "--eval-retrieval", &Config::evalRetrieval }, { "--eval=knownitem", &Config::evalRetrieval }, // alias { "--pack-signatures", &Config::packSignatures }, // ordering (the --order= aliases stay hand-written: they warn) { "--no-stable", &Config::noStable }, { "--no-inventory", &Config::noInventory }, // D7: the default map without its tier // the analysis lenses { "--metrics", &Config::metrics }, { "--deps", &Config::deps }, { "--hotspots", &Config::hotspots }, { "--clones", &Config::clones }, { "--biggest-first", &Config::readability }, // was --readability; the alias is hand-written below (deprecatedReadabilityFlag), kept out of this table by house convention (§ "deprecation-warning aliases") { "--nonlocal-state", &Config::nonlocalState }, { "--ensemble", &Config::ensemble }, { "--context-ratio", &Config::contextRatio }, { "--quality-panel", &Config::qualityPanel }, // bare flag → the `default` preset (the value is an OPTIONAL selection) { "--naming-calibration", &Config::namingCalibration }, { "--naming-consistency", &Config::namingConsistency }, { "--naming-locals", &Config::namingLocals }, { "--comment-coherence", &Config::commentCoherence }, { "--cochange", &Config::cochange }, { "--cochange-groups", &Config::cochangeGroups }, // matched by EQUALITY, scanned before the prefix table, so it can // never shadow --cochange nor be shadowed by --cochange=FILE { "--communities", &Config::communities }, { "--community", &Config::communityFlag }, // bare flag → empty ID → handler refuses loudly. Matched by // EQUALITY and scanned before the prefix table, so it can never // shadow --communities (nor be shadowed by --community=ID). { "--zoom", &Config::zoom }, { "--report", &Config::report }, { "--tree", &Config::tree }, { "--seams", &Config::seams }, { "--mermaid", &Config::mermaid }, // change / blast-radius { "--situ", &Config::situ }, { "--handoff", &Config::handoff }, { "--test-gate", &Config::testGate }, { "--exercises", &Config::exercisesFlag }, // bare flag → empty TESTFILE → handler refuses loudly { "--field-affinity", &Config::fieldAffinity }, // bare flag → whole-repo ranking (the value is an OPTIONAL narrowing) // cache + diagnostics { "--no-cache", &Config::noCache }, { "--no-ignore", &Config::noIgnore }, // §N6-C: crawl gitignored paths too (the pre-2026-09-03 walk) { "--refetch", &Config::refetch }, { "--doctor", &Config::doctor }, { "--skipped", &Config::skippedList }, // output shape { "--json", &Config::json }, // L2: JSON output for the core/CI verbs (see Config::json) { "--dry-run", &Config::editPlanDryRun }, { "--apply", &Config::editPlanApply }, // search { "--no-prefilter", &Config::noPrefilter }, { "--handles", &Config::grepHandles }, { "--lint", &Config::lint }, { "--lint-catalog", &Config::lintCatalog }, // the built-in rule registry — src/lintcatalog.h { "--sarif", &Config::sarif }, // (with --lint / --lint-rules) SARIF 2.1.0 instead of native XML // the --for lens modifiers (each refused alone by validateConfig) { "--anchor", &Config::anchor }, { "--no-route", &Config::noRoute }, { "--adaptive", &Config::adaptive }, { "--no-mention-boost", &Config::noMentionBoost }, { "--cochange-boost", &Config::cochangeBoost }, { "--no-doc-mention", &Config::noDocMention }, { "--signatures-only", &Config::signaturesOnly }, // T3 opt-out: the pre-terminal signatures-only --for bundle { "--auto-bodies", &Config::autoBodies }, // compact-route opt-out: the rank-first body walk, back on the conceptual route // graph surface { "--external-surface", &Config::externalSurface }, { "--include-builtins", &Config::includeBuiltins }, // P4 (L7): --external-surface keeps the sh builtins (echo/printf/cd/…) it drops by default // skills, reports, redaction { "--scan-skills", &Config::scanSkills }, { "--force", &Config::force }, { "--html", &Config::html }, { "--owners", &Config::owners }, { "--compress", &Config::compress }, { "--no-redact", &Config::noRedact }, { "--no-post-check", &Config::noPostCheck }, // P9: the edit receipt's folded verification, opted out // quality + dead code { "--baseline", &Config::baseline }, { "--baseline-update", &Config::baselineUpdate }, { "--dead-code", &Config::deadCode }, { "--quality-baseline", &Config::qualityBaseline }, { "--allow-dirty", &Config::allowDirty }, // H11 modifier: refused alone (validateModifierGuards) { "--quality-delta", &Config::qualityDelta }, { "--show-stale", &Config::showStale }, // idea #11 modifier: refused without --quality-delta (validateModifierGuards) { "--dmm", &Config::dmm }, // bare flag → the working tree vs HEAD (the value is an OPTIONAL rev/range) // review + the cross-branch verbs { "--pr-context", &Config::prContext }, { "--whereis", &Config::whereisFlag }, // bare flag → empty SYM → handler refuses loudly { "--stray-content", &Config::strayContent }, { "--plan", &Config::landingPlan }, // bare flag → refused below without --stray-content { "--abi", &Config::abiFlag }, // bare flag; requires --stray-content, refused below { "--flags", &Config::darkFlags }, { "--flip", &Config::flipFlag }, // bare flag → empty NAME → refused below { "--layout", &Config::layoutFlag }, // bare flag → empty STRUCT → handler refuses loudly { "--plan-lanes", &Config::planLanesFlag }, // bare flag → the --brief form; refused below without --task/--brief { "--doc-drift", &Config::docDrift }, { "--gateability", &Config::gateabilityFlag }, // requires --doc-drift, refused below { "--with-history", &Config::withHistory }, { "--whereis-full-text", &Config::whereisFullText }, // requires --whereis, refused below // notes + packs { "--notes", &Config::notesList }, { "--pack-task", &Config::packTaskFlag }, // bare flag → empty task → handler refuses loudly { "--with-graph", &Config::withGraph }, }; // G1/F1 — shared by both kViewFlags rows that write Config::grep (--grep= and --regex=): a second // occurrence of either used to silently overwrite the pattern from the first (measured: `--grep=foo // --grep=bar` exits 0 with pattern="bar", `foo` discarded, nothing on stderr). The natural spelling an // agent reaches for when it means "AND" is a second --grep=, so the refusal names that spelling directly // rather than a generic "flag given twice". inline constexpr const char* kGrepDupMessage = "--grep given twice; did you mean --grep='A' --and='B'?"; inline constexpr ViewFlag kViewFlags[] = { // server + self-eval inputs { "--mcp-token=", &Config::mcpToken , EmptyValue::Refuse, "a shared bearer token", "--mcp-token=$RIPWIRE_MCP_TOKEN" }, { "--mcp-tools=", &Config::mcpTools , EmptyValue::Refuse, "tool names and/or a profile (core, full)", "--mcp-tools=core" }, { "--agent=", &Config::agent , EmptyValue::Refuse, "codex", "--agent=codex" }, // also accepts claude — see validateAgent { "--eval-mined=", &Config::evalMined , EmptyValue::Refuse, "a minedpair.jsonl file path", "--eval-mined=bench/minedpair.jsonl" }, { "--eval-skills=", &Config::evalSkills , EmptyValue::Refuse, "a labelled TSV file path", "--eval-skills=bench/skillroute.tsv" }, // architecture + graph paths { "--arch=", &Config::archRules , EmptyValue::Refuse, "a layering-rules file path", "--arch=arch_rules.txt" }, { "--path=", &Config::pathSpec , EmptyValue::Refuse, "two symbol names, FROM,TO", "--path=main,rankGraph" }, { "--connect=", &Config::connectSpec , EmptyValue::Refuse, "two or more symbol names, A,B[,C]", "--connect=parseArgs,serialize,rankGraph" }, { "--impact=", &Config::impactSym , EmptyValue::Refuse, "a symbol name", "--impact=parseArgs" }, { "--mentions=", &Config::mentionsSym , EmptyValue::Refuse, "a symbol name", "--mentions=parseArgs" }, { "--affected=", &Config::affectedFiles , EmptyValue::Refuse, "changed files or a symbol name", "--affected=src/cli.h" }, { "--verify=", &Config::verifyClaim , EmptyValue::Refuse, "a claim expression", "--verify='calls(parseArgs, readFile)'" }, { "--help-task=", &Config::helpTask , EmptyValue::Refuse, "a task in words", "--help-task=\"review my changes before push\"" }, // cache, index, history { "--cache=", &Config::cacheFile , EmptyValue::Refuse, "a cache file path", "--cache=.ripwirecache" }, { "--index-out=", &Config::indexOut , EmptyValue::Refuse, "a base path for the index artifacts", "--index-out=.ripwire/index" }, { "--since=", &Config::since , EmptyValue::Refuse, "a git revision or date", "--since=HEAD~20" }, { "--in=", &Config::inDir , EmptyValue::Refuse, "a root-relative directory under the root", "--in=src" }, { "--scip=", &Config::scipIndex , EmptyValue::Refuse, "a SCIP index file path", "--scip=index.scip" }, { "--pin-census=", &Config::pinCensus , EmptyValue::Refuse, "a census output file path", "--pin-census=census.tsv" }, // search and the --for lens { "--query=", &Config::query , EmptyValue::Refuse, "search terms", "--query=\"teleport pagerank\"" }, { "--legend=", &Config::legend , EmptyValue::Refuse, "full or compact", "--legend=compact" }, { "--grep=", &Config::grep , EmptyValue::Refuse, "a literal string to search for", "--grep=parseArgs", nullptr, nullptr, &Config::grepGiven, kGrepDupMessage }, { "--match=", &Config::match , EmptyValue::Refuse, "a tree-sitter s-expression pattern", "--match='(call_expression)'" }, { "--pattern=", &Config::pattern , EmptyValue::Refuse, "a code-shaped pattern", "--pattern='foo($X, ...)'" }, { "--lint-rules=", &Config::lintRulesDir , EmptyValue::Refuse, "a rules directory path", "--lint-rules=lintrules/" }, { "--lint-select=", &Config::lintSelect , EmptyValue::Refuse, "a comma-separated PREFIX list, or '*'", "--lint-select=cache-,goto" }, { "--lint-ignore=", &Config::lintIgnore , EmptyValue::Refuse, "a comma-separated PREFIX list, or '*'", "--lint-ignore=naming-" }, { "--for=", &Config::forTask , EmptyValue::Refuse, "a task in words", "--for=\"add retry to the http client\"" }, { "--sections=", &Config::sections , EmptyValue::Refuse, "lego, compose, or lego,compose", "--sections=lego,compose" }, { "--lego=", &Config::legoType , EmptyValue::Refuse, "an interface or base-type name", "--lego=Shape" }, { "--exemplar=", &Config::exemplar , EmptyValue::Refuse, "what you are about to write", "--exemplar=\"a JSON writer\"" }, { "--recall=", &Config::recall , EmptyValue::Refuse, "a task in words", "--recall=\"how does the cache key work\"" }, // neighborhood + call graph { "--around=", &Config::around , EmptyValue::Refuse, "a symbol name", "--around=parseArgs" }, { "--callers=", &Config::callers , EmptyValue::Refuse, "a symbol name", "--callers=parseArgs" }, { "--callees=", &Config::callees , EmptyValue::Refuse, "a symbol name", "--callees=parseArgs" }, { "--uses=", &Config::usesSym , EmptyValue::Refuse, "a symbol name", "--uses=parseArgs" }, { "--graph-query=", &Config::graphQuery , EmptyValue::Refuse, "a graph-query expression", "--graph-query='callers(parseArgs)'" }, // skills, batch, cross-branch { "--scan-skill=", &Config::scanSkillFile , EmptyValue::Refuse, "a skill file path (any file, not just .md)", "--scan-skill=skills/ripwire-orient/SKILL.md" }, { "--batch=", &Config::batchFile , EmptyValue::Refuse, "a batch file path, or - for stdin", "--batch=queries.txt" }, { "--edit-check=", &Config::editCheckSym , EmptyValue::Refuse, "a symbol name (file:name disambiguates)", "--edit-check=parseArgs" }, { "--safe-delete=", &Config::safeDeleteSym , EmptyValue::Refuse, "a symbol name (file:name disambiguates)", "--safe-delete=parseArgs" }, { "--slice=", &Config::sliceSpec , EmptyValue::Refuse, "SYM (list its locals) or SYM:VAR (slice VAR; file:name:VAR disambiguates)", "--slice=parseArgs:argIndex" }, { "--at=", &Config::atSpec , EmptyValue::Refuse, "FILE:LINE (a 1-based line) — the enclosing-definition chain there", "--at=src/main.cpp:120" }, { "--slice-flow=", &Config::sliceFlow , EmptyValue::Refuse, "a flow direction: back|fwd|both (modifies --slice=SYM:VAR)", "--slice-flow=back" }, { "--replace-symbol-body=", &Config::replaceSymbolBody, EmptyValue::Refuse, "a symbol name", "--replace-symbol-body=parseArgs" }, { "--insert-before-symbol=", &Config::insertBeforeSymbol, EmptyValue::Refuse, "a symbol name", "--insert-before-symbol=parseArgs" }, { "--insert-after-symbol=", &Config::insertAfterSymbol, EmptyValue::Refuse, "a symbol name", "--insert-after-symbol=parseArgs" }, { "--edit-payload=", &Config::editPayload, EmptyValue::Refuse, "a payload file path, or - for stdin", "--edit-payload=replacement.cpp" }, { "--edit-target-file=", &Config::editTargetFile, EmptyValue::Refuse, "a target file-path substring", "--edit-target-file=src/cli.h" }, { "--edit-plan=", &Config::editPlan, EmptyValue::Refuse, "a versioned edit plan JSON file", "--edit-plan=plan.json" }, { "--eval-stray=", &Config::evalStray , EmptyValue::Refuse, "a labelled TSV file path", "--eval-stray=bench/strayverdicts.tsv" }, { "--from-trace=", &Config::fromTrace , EmptyValue::Refuse, "a trace file path, or - for stdin", "--from-trace=crash.txt" }, { "--run-trace=", &Config::runTrace , EmptyValue::Refuse, "a shell command line to execute", "--run-trace=\"make -j\"" }, { "--with-profile=",&Config::withProfile , EmptyValue::Refuse, "a profile report holding a #PROF_TSV block", "--with-profile=report.txt" }, // the lane plan's two inputs (each refused alone by validateConfig) { "--task=", &Config::laneTask , EmptyValue::Refuse, "a goal in words", "--task=\"add a --since filter\"" }, { "--brief=", &Config::laneBrief , EmptyValue::Refuse, "a brief file path", "--brief=lanes_brief.txt" }, // ── §B5: the 23 arms that used to be hand-written in parseArgs ────────────────────────────────────── // Each was exactly "assign one member (+ set one or two companion bools)", which this table can express // once it has the isSetFlag columns. Grouped and ordered as they stood in the chain so a reviewer can // diff the move; the ONLY behaviour that changes is the four §B5 rows marked below. // // Prefix-collision check, done once so it need not be redone per row: no row's prefix is a prefix of // another's (`--scan-skill=` vs `--scan-skills=` differ at the byte after "--scan-skill", so neither // matches the other), and the exact-match kBoolFlags scan runs FIRST, so every bare `--owners` / // `--whereis` / `--flags` / `--situ` / `--html` / ... still lands on its bool row exactly as before. // §B5 FIX - a network TRANSPORT selector. `--listen=` (a $PORT that expanded to nothing) used to become // a live stdio MCP server at exit 0, answering a full tools/call on stdout; `--listen=notaspec` refuses // loudly one keystroke away. Also sets c.mcp: --listen implies --mcp. { "--listen=", &Config::listen , EmptyValue::Refuse, "HOST:PORT, or a bare PORT for loopback", "--listen=127.0.0.1:8765", &Config::mcp }, // §B5 FIX - was byte-identical to bare `--owners`, while `--owners=` reads as "restrict to SYM" and SYM // is missing. The bare form is the kBoolFlags row and stays the way to ask for the whole report. { "--owners=", &Config::ownersSym , EmptyValue::Refuse, "a symbol name (restricts the report to its file)", "--owners=parseArgs", &Config::owners }, // §B5 FIX - was byte-identical to the DEFAULT MAP: a caller asked which findings to ack and got an atlas. // `--ack-only=gating` alone already exits 1, so the empty form was the only unguarded spelling. { "--ack-only=", &Config::qualityAckOnly , EmptyValue::Refuse, "one or more kind/id substrings, comma-separated", "--ack-only=complexity" }, // P1 — same ruling as --ack-only= one line up, for the same reason: an EMPTY scope is the one spelling // that reads as "everything is mine", which is the exact belief this flag exists to stop an agent // holding in a shared tree. `--scope=` (an unset shell variable) must never expand to a blanket ack. { "--scope=", &Config::qualityScope , EmptyValue::Refuse, "one or more path globs, comma-separated", "--scope=src/quality.h" }, // --regex= sets the pattern AND the regex-mode bool; it already called refuseEmptyValue directly and the // table prints the SAME sentence, so this row is byte-identical to the arm it replaces. { "--regex=", &Config::grep , EmptyValue::Refuse, "a regular expression", "--regex='parse[A-Z]'", &Config::grepRegex, nullptr, &Config::grepGiven, kGrepDupMessage }, // M6 (capture-audit 2026-09-04): the bare-or-filter forms used to be EmptyValue::Meaningful — "" was read // as the bare flag, since the value is an OPTIONAL narrowing. The shell is why that reading was wrong: // `--dead-code=$DIR` with an unset $DIR became a repo-wide scan, `--pr-context=$BASE` the working-tree // default, `--stray-content=$REF` a sweep of every ref, each at exit 0 with an empty stderr — a different // question, answered as if it were the one asked. --test-gate= left the block on 2026-08-24 for exactly // this; the rest follow it now. ONLY the bare spelling selects the default. Gate: emptyvaluerefusecheck.sh. { "--cochange=", &Config::cochangeFile , EmptyValue::Refuse, "a changed file path to seed the pair report (bare --cochange ranks every pair)", "--cochange=src/cli.h", &Config::cochange }, { "--situ=", &Config::situFiles , EmptyValue::Refuse, "changed files, F1,F2 (bare --situ reads git diff)", "--situ=src/cli.h", &Config::situ }, // `--test-gate=` left the Meaningful block above on 2026-08-24: "" ≡ the bare git-diff form meant an // unset shell variable silently gated a DIFFERENT question, on a verb whose exit code gates a merge — // the same ruling --dmm=/--quality-delta= below carry for their half-typed ranges. (The unparseable- // FILES refusal itself is per-item, in main's --test-gate arm; gate: testgaterefusecheck.sh.) { "--test-gate=", &Config::testGateFiles , EmptyValue::Refuse, "changed files, F1,F2", "--test-gate=src/cli.h", &Config::testGate }, { "--scan-skills=", &Config::scanSkillsDir , EmptyValue::Refuse, "a skills directory path (bare --scan-skills scans ./.agents/skills and the Claude and Codex skill homes, never the root)", "--scan-skills=skills/", &Config::scanSkills }, { "--dead-code=", &Config::deadCodeDir , EmptyValue::Refuse, "a directory or path substring to scope the candidates (bare --dead-code scans the whole tree)", "--dead-code=src/", &Config::deadCode }, { "--pr-context=", &Config::prContextBase , EmptyValue::Refuse, "a base ref (bare --pr-context reads the working tree)", "--pr-context=main", &Config::prContext }, { "--stray-content=", &Config::strayFilter , EmptyValue::Refuse, "a ref-name substring filter (bare --stray-content sweeps every ref)", "--stray-content=lane/", &Config::strayContent }, { "--flags=", &Config::darkFlagsFilter , EmptyValue::Refuse, "a gate-name substring filter (bare --flags lists every gate)", "--flags=RIPWIRE_", &Config::darkFlags }, { "--doc-drift=", &Config::docDriftFilter , EmptyValue::Refuse, "a document-path substring filter (bare --doc-drift scans every document)", "--doc-drift=README", &Config::docDrift }, // P3.2: unlike --doc-drift's SUBSTR filter, a bare value here is a real usage error — "" cannot name a // plan file, so Refuse (not Meaningful) is the right form, same reasoning --from-trace= already carries. { "--plan-lint=", &Config::planLintFile , EmptyValue::Refuse, "a plan/design markdown file path", "--plan-lint=wave-plan.md" }, // `--field-affinity=STRUCT` narrows to one struct; the bare form (the whole-repo ranking) is the primary way // to ask, and the ONLY spelling that selects it (M6 above). { "--field-affinity=", &Config::fieldAffinityStruct, EmptyValue::Refuse, "a struct or class name (bare --field-affinity ranks every struct)", "--field-affinity=Symbol", &Config::fieldAffinity }, // --dmm= is Refuse, not Meaningful, even though the BARE --dmm is a real form: `--dmm=` is a half-typed // range, and silently running the working-tree comparison for it would answer a question nobody asked. { "--dmm=", &Config::dmmRange, EmptyValue::Refuse, "a commit, or a RANGE A..B (bare --dmm compares the working tree against HEAD)", "--dmm=HEAD~1..HEAD", &Config::dmm }, // R-I: `--quality-delta=` is Refuse for the SAME reason `--dmm=` is — the value is a half-typed range, // and silently running the working-tree-vs-baseline comparison for it would answer a question nobody // asked, on a verb whose exit code gates a merge. Declared AFTER `--quality-panel=` would be harmless // (no shared prefix) but it sits beside --dmm= because the two rows carry the identical grammar. { "--quality-delta=", &Config::qualityDeltaRange, EmptyValue::Refuse, "a commit, or a RANGE A..B of git refs (bare --quality-delta compares the working tree against the baseline)", "--quality-delta=HEAD~1..HEAD", &Config::qualityDelta }, // `--quality-panel=PRESET` selects a preset; the bare form is the `default` preset and the only spelling // that selects it (M6 above). An UNKNOWN value is refused in validateModifierGuards with the supported // list — falling back to a preset the caller did not name would be a silently different report. { "--quality-panel=", &Config::qualityPanelPreset , EmptyValue::Refuse, "a preset name (bare --quality-panel is the default preset)", "--quality-panel=default", &Config::qualityPanel }, // --html=FILE-or-stdout keeps Meaningful on purpose: `--html=` is `--html` (write to stdout) — a VISIBLE, // harmless answer, not a different question, which is the M6 distinction. --quality-ack=REASON is the // same shape with one more rule (H10): the reason-carrying spelling implies the --quality-delta report it // acks (validateConfig sets it, where the bare arm used to), while `--quality-ack=` — a reason-less ack, // exactly the bare spelling — is refused there without an explicit --quality-delta: HandlerRefuses. { "--html=", &Config::htmlFile , EmptyValue::Meaningful, nullptr, nullptr, &Config::html }, { "--quality-ack=", &Config::qualityAckReason, EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::qualityAck }, // validateConfig: "pass --quality-delta with it" // the handler refuses an empty value with its own verb-specific sentence - byte-identical to before the // move, because the row does NOT refuse here. Each names the refusing site so a reader can check it. { "--merge-scout=", &Config::mergeScout , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::mergeScoutFlag }, // "--merge-scout needs REF[,REF...]" { "--whereis=", &Config::whereis , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::whereisFlag }, // "--whereis needs a symbol" { "--exercises=", &Config::exercisesFile , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::exercisesFlag }, // "--exercises needs a test file" { "--community=", &Config::communityId , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::communityFlag }, // "--community needs a module ID" { "--flip=", &Config::flipGate , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::flipFlag }, // validateConfig + the --flags handler { "--layout=", &Config::layoutStruct , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::layoutFlag }, // "--layout needs a struct/class name" { "--note-add=", &Config::noteAdd , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::noteAddFlag }, // "--note-add: want \"TARGET: text\"" { "--pack-task=", &Config::packTask , EmptyValue::HandlerRefuses, nullptr, nullptr, &Config::packTaskFlag }, // "--pack-task: a task string is required" }; // Does THIS build ship the flag spelled `prefix`? Asked by the surfaces that COMPOSE a command for someone // else to run — the task router is the first — because a recommendation carrying a flag the parser it will // be handed to has no row for exits non-zero on the first paste. The table is the only honest answer: a // hand-kept list of "flags we have" is a second source that drifts, which is the disease §B5 above treats. inline constexpr bool shipsViewFlag( std::string_view prefix ) noexcept { return std::ranges::any_of( kViewFlags, [prefix]( const ViewFlag& vf ) { return vf.prefix == prefix; } ); } // §B5 - the column above is only a decision if the build enforces it. `needs`/`example` are the Refuse // sentence's two halves: a Refuse row without them would print "it needs (null)", and a Meaningful or // HandlerRefuses row that carries them is a row whose author wrote a refusal the scan will never print - // both are the "declared one thing, does another" shape this table exists to make impossible. consteval bool viewFlagEmptyPolicyIsWellFormed() noexcept { for( const ViewFlag& vf : kViewFlags ) { const bool hasSentence = vf.needs != nullptr && vf.example != nullptr; if( ( vf.onEmpty == EmptyValue::Refuse ) != hasSentence ) { return false; } if( ( vf.needs == nullptr ) != ( vf.example == nullptr ) ) { return false; // never half a sentence } } return true; } static_assert( viewFlagEmptyPolicyIsWellFormed(), "a kViewFlags row's EmptyValue does not match its needs=/example= columns - EmptyValue::Refuse " "needs both (they ARE the refusal sentence); Meaningful and HandlerRefuses must carry neither, " "or the row claims a refusal applyViewFlag will never print" ); // §B8.2 — the NUMERIC arms, as the third table. `--x=N` is the surface's other repeated shape and it was // still nine hand-written `if` arms, which is exactly how those nine ended up with a refusal DIALECT of // their own: one fixed sentence per flag, printed for every bad value, with neither the offending value // nor an example in it. `--zoom=` and `--zoom=zzq` produced BYTE-IDENTICAL stderr, so a caller whose // $DEPTH expanded to nothing could not tell an unset variable from a typo — while --limit/--offset (one // function away) and the compliant kViewFlags rows both echo the value and show what to type. // // The columns are the whole refusal: `wanted` is the DOMAIN in the refusal's voice, `example` is runnable // and inside that domain, and `most` is the domain's ceiling. A new numeric flag now inherits the shared // sentence by filling those in, the same way a new value-taking flag inherits the empty-value refusal. // // `most` matters for exactly one row today (§B8.1: --connect-radius' 1..12 band); everything else sits at // kIntFlagMax, which is parsePosInt's own ceiling restated, so `v > most` is unreachable there and the // accepted set is bit-for-bit what it was. The parse itself is still parsePosInt/parseNonNegInt — this // table changed which SENTENCE a rejected value gets, never which values are rejected. inline constexpr int kIntFlagMax = 1000000000; // parsePosInt/parseNonNegInt's own overflow ceiling inline constexpr int kConnectRadiusMax = 12; // == connectcfg::kMaxRadius (static_assert at the seam in main.cpp) // --lint-max-per-rule's domain ceiling. The budget is multiplied twice downstream — 20x for the atoms/cache packs' engine // budget (verbs_lint.h lintPackQueryBudget) and 10x more for a floored answer's findings_next= (lintrules.h // lintNextMaxPerRule) — so the ceiling keeps both products representable in std::size_t: == kIntFlagMax wherever size_t is // 64 bits, lower where it is 32 (CodeRabbit 5468003465). Refused above it, never saturated (§B8.1), and the continuation // saturates at this same value so the call it names is always one this table accepts. inline constexpr int kLintMaxPerRuleMost = int( std::min( std::size_t( kIntFlagMax ), std::numeric_limits::max() / 200 ) ); struct IntFlag { std::string_view prefix; int Config::* member; bool isZeroAllowed; // 0 is IN the domain (--top-k=0 = payload only, --detail=0 = off) int most; // domain ceiling — refused, not clamped (§B8.1) const char* wanted; // the domain, worded for the refusal const char* example; // runnable, and inside the domain const char* deprecation = nullptr; // printed on ACCEPT (the flag still works, it is on the way out) int Config::* memberAlso = nullptr; // --grep-context= sets the before AND after windows bool Config::* isSetFlag = nullptr; // companion bool: --zoom= selects the verb, --top-k= records explicitness }; inline constexpr IntFlag kIntFlags[] = { // graph shaping { "--zoom=", &Config::zoomDepth, false, kIntFlagMax, "a positive integer depth", "--zoom=2", nullptr, nullptr, &Config::zoom }, // P4 (L7): how many hierarchy levels --zoom PRINTS from the top (the default is 2, disclosed as levels_shown=); // 0 = every level. isSetFlag records explicitness so the bare modifier can be refused (it shapes --zoom only). { "--zoom-levels=", &Config::zoomLevels, true, kIntFlagMax, "a non-negative integer (0 = every level)", "--zoom-levels=0", nullptr, nullptr, &Config::zoomLevelsSet }, { "--connect-radius=", &Config::connectRadius, false, kConnectRadiusMax, "an integer in 1..12", "--connect-radius=6" }, // budgets + the ranked head { "--max-tokens=", &Config::maxTokens, false, kIntFlagMax, "a positive integer", "--max-tokens=16000" }, // r27-emitters T2: --top-k=0 means "emit NO ranked map, only the explicitly requested payload" // (--expand/--outline/--pack-signatures/--pack-top-n). It used to be refused outright, so a caller // asking for one 1.4 KB body had no way to drop the 22 KB ride-along map and `--top-k=0 --expand=X` // produced ZERO bytes — the requested body vanished with it. isZeroAllowed is that decision; `--top-k=` // (empty) is still rejected, so the old "silently becomes 0 = emit ALL symbols" trap stays closed. { "--top-k=", &Config::topK, true, kIntFlagMax, "a non-negative integer (0 = suppress the ranked map, payload only)", "--top-k=200", nullptr, nullptr, &Config::topKExplicit }, { "--pack-top-n=", &Config::packTopN, false, kIntFlagMax, "a positive integer", "--pack-top-n=10", "ripwire: --pack-top-n is deprecated — use --pack-task/--detail instead (unchanged behavior for now)\n" }, { "--detail=", &Config::detail, true, kIntFlagMax, "a non-negative integer (0 = off)", "--detail=2" }, // knob-honesty-068: the per-rule lint budget (kLintMaxPerRule is the default); a modifier of --lint/--lint-rules, // refused alone (validateLintSelectionModifierGuards) — the floored answer's findings_next= is the call that spells it. { "--lint-max-per-rule=", &Config::lintMaxPerRule, false, kLintMaxPerRuleMost, "a positive integer", "--lint-max-per-rule=50000" }, // --cochange-recur=K: K is a count of SUB-WINDOWS, so it is bounded by kCoRecurSubWindows in practice; // the parser accepts any positive integer and the verb reports zero pairs above the ceiling rather than // refusing — an empty result under a disclosed min_recur= is a truthful answer, not an error. { "--cochange-recur=", &Config::cochangeRecur, false, kIntFlagMax, "a positive integer", "--cochange-recur=2" }, // --slice-depth=N (lane/or-arise rung 2): the --slice-flow BFS depth bound. The 1..32 band is a parse-time // domain (`most`), not a cross-flag contract; needing --slice-flow at all IS cross-flag (validateConfig). { "--slice-depth=", &Config::sliceDepth, false, 32, "an integer in 1..32", "--slice-depth=4" }, // the grep context windows (ripgrep -B/-A/-C) { "--grep-before=", &Config::grepBefore, true, kIntFlagMax, "a non-negative integer", "--grep-before=3" }, { "--grep-after=", &Config::grepAfter, true, kIntFlagMax, "a non-negative integer", "--grep-after=3" }, { "--grep-context=", &Config::grepBefore, true, kIntFlagMax, "a non-negative integer", "--grep-context=3", nullptr, &Config::grepAfter }, // §B8.2 verifier finding N4 (W2FIX-CLI) — the ego graph and the pack-task fan-out/lane-plan forms. // parsePosInt underneath (not parseNonNegInt), same as the rest of this table; `most` stays kIntFlagMax // for --partition/--plan-lanes because their real 2..16 band is a CROSS-FLAG contract (needs --pack-task // / --task first) enforced in validateConfig with its own message, not a parse-time domain. { "--around-depth=", &Config::aroundDepth, false, kIntFlagMax, "a positive integer", "--around-depth=3" }, { "--around-fanout=", &Config::aroundFanout, false, kIntFlagMax, "a positive integer", "--around-fanout=50" }, // --partition=N: the fan-out form of --pack-task (2..16 agents; range checked in validateConfig) { "--partition=", &Config::partitionCount, false, kIntFlagMax, "a positive integer", "--partition=4" }, // sets TWO members: the count here AND the companion bool (the bare `--plan-lanes` --brief form is the // kBoolFlags row above); 2..16 is enforced in validateConfig alongside the task-xor-brief contract. { "--plan-lanes=", &Config::planLaneCount, false, kIntFlagMax, "a positive integer", "--plan-lanes=3", nullptr, nullptr, &Config::planLanesFlag }, // VT-1: --run-trace's command cap in SECONDS (default 600 when unset; the cross-flag "modifies // --run-trace only" contract is validateConfig's, not a parse-time domain — same split as --partition). { "--run-timeout=", &Config::runTimeoutSec, false, kIntFlagMax, "a positive integer (seconds)", "--run-timeout=60" }, }; // Tripwire (house style): the `--` surface is 149 arms. Adding or removing one must move exactly one of // these counters, so a new flag cannot land without a reader deciding — and recording — which shape it // is. kHandWrittenFlagArms counts the arms still spelled out in parseArgs: value-parsing, multi-member, // deprecation-warning and nested-value arms, none of which a table can express honestly. // W2FIX-CLI (§B8.2 finding N4): 44 → 40 — --around-depth=/--around-fanout=/--partition=/--plan-lanes= // moved from hand-written arms into kIntFlags rows (4 fewer hand, 4 more table; kTotalFlagArms unchanged). // // §B5 (capture-audit-4): 40 → 17. The four un-swept arms were the SYMPTOM; the 40-arm surface outside the // table was the disease, so 23 of them became kViewFlags rows (33 → 56) once that table grew the EmptyValue // and isSetFlag columns. kTotalFlagArms is unchanged, which is exactly what this tripwire is for: a move is // a move, and it must not look like an addition. What is LEFT is the honest residue, and each kind is here // because a table row could not hold it without lying: // • a VECTOR member --exclude= (push_back), --expand= / --outline= (comma-split into vector) // • a PARSE, not an assign --token-budget= / --max-file-size= / --pack-budget-bytes= (byte sizes into a // size_t/u64), --limit= / --offset= (their own out-of-range sentence) // • an ENUM value --order= / --rank-by= / --color-by= / --format= / --export= (a value SET, // and a refusal that must list it) // • a WARNING on accept --most-important-last / --stable / --no-auto-order / --readability (deprecated // aliases that warn once per RUN, not per flag — state a BoolFlag row has // nowhere to keep) // • a bare no-op / bare pair --route, --quality-ack (the =REASON form is a kViewFlags row) inline constexpr std::size_t kHandWrittenFlagArms = 26; // +2 lane/lean-answers-068 (2026-10-07): --whereis-listing= and --mcp-legend= (closed-value arms, same shape as --grep-in=); +1 #350 (2026-09-28): --max-memory= (byte-size arm, same shape as --max-file-size=); +1: --color-by= (enum-value arm); +3 G3 (2026-08-15 harvest): --and=/--not=/--grep-scope= (repeatable-value arms, same shape as --exclude=); +1 R-H: --grep-in= (closed-value arm, same shape as --grep-scope=); +1 lane/flag-biggest-first (2026-09-23): --readability (deprecation-warning alias, same shape as --stable/--most-important-last/--no-auto-order) — its kBoolFlags row is renamed to --biggest-first (same Config::readability member), so the old spelling moves OUT of the table and becomes a hand-written arm, per the house rule that deprecation-warning aliases stay hand-written inline constexpr std::size_t kTotalFlagArms = 221; // +1 lane/whereis-lean (2026-10-10, review C1): --whereis-full-text (kBoolFlags row) — the same --whereis page with every t= line whole, the replay; +1 lane/lean-trio (2026-10-10): --show-stale (kBoolFlags row) — prints the stale-ack rows a regression-free --quality-delta collapses; +1 lane/map-inventory-d7 (2026-10-08): --no-inventory (kBoolFlags row) — the default map without its tier; +1 knob-honesty-068 (2026-10-07): --lint-max-per-rule= (kIntFlags row) — the per-rule lint budget a floored answer's findings_next= names; +2 lane/lean-answers-068 (2026-10-07): --whereis-listing= and --mcp-legend= (hand-written closed-value arms, see kHandWrittenFlagArms); +1 lane/mcp-tool-profile-065 (2026-09-26): --mcp-tools= (kViewFlags row) — list only a subset of the MCP tools (names and/or the core/full profiles); +1 #350 (2026-09-28): --max-memory= (hand-written byte-size arm, see kHandWrittenFlagArms); +1 lane/flag-biggest-first (2026-09-23): --readability renamed to --biggest-first, kept working as a hand-written deprecated alias (see kHandWrittenFlagArms); +1 lane/r1-for-sections-stub (2026-09-19, L2/B1): --sections= (kViewFlags row) — the closed-set opt-in that restores the / sections --for collapses to a counted stub by default; +1 --lsp (kBoolFlags row, 2026-09-15): the navigation LSP server stdio entry point — Phase 1 PoC, docs/LSP.md; +1 lane/recent-scope (2026-09-12, C1-b): --in= (kViewFlags row) — the directory-scoped block of --rank-by=churn-decay; +2 P4 (capture-audit 2026-09-04, lane L7): --zoom-levels= (kIntFlags row, the printed-levels ceiling) and --include-builtins (kBoolFlags row, the external-surface builtin opt-in); +1 P9 (capture-audit 2026-09-04, lane L8): --no-post-check (kBoolFlags row, the edit receipt's folded verification opt-out); +1 lane/ca-L2 (2026-09-04, H11): --allow-dirty (kBoolFlags row) — the explicit consent --quality-baseline needs before it pins a floor on a tree that differs from HEAD; +1 lane/n6-c (2026-09-03): --no-ignore (kBoolFlags row, the .gitignore-by-default escape hatch); +1 lane/af-scope (2026-08-29): --scope= (kViewFlags row, the quality-delta ownership partition); +1 --quality-delta= (kViewFlags, R-I ref-pair form); +1 --help-task= (kViewFlags); +2 VT-1: --run-trace= (kViewFlags) and --run-timeout= (kIntFlags); +1: --handoff (kBoolFlags row); +1 --readability (kBoolFlags row); +2 §CLIO: --cochange-groups (kBoolFlags), --cochange-recur= (kIntFlags); +1 --context-ratio (kBoolFlags row); +1 --nonlocal-state (kBoolFlags row); +2 --field-affinity (kBoolFlags) and --field-affinity= (kViewFlags); +1 --comment-coherence (kBoolFlags row); +2 --dmm (kBoolFlags) and --dmm= (kViewFlags); +2 --quality-panel (kBoolFlags) and --quality-panel= (kViewFlags); +1 --naming-consistency (kBoolFlags row); +1 --naming-locals (kBoolFlags row, local-variable-indexing plan Phase 2); +1 --skipped (kBoolFlags row, §P0.5d itemization); +1 --with-profile= (kViewFlags row, the --lint × #PROF_TSV heat join); +1 --color-by= (hand-written enum-value arm); +1 --sarif (kBoolFlags row, W1-SARIF: SARIF 2.1.0 export for --lint); +1 --signatures-only (kBoolFlags row, T3 terminal-by-default --for opt-out); +3 L7: --lint-catalog (kBoolFlags), --lint-select= and --lint-ignore= (kViewFlags); +3 G3 (2026-08-15 harvest): --and=/--not=/--grep-scope= (hand-written arms); +1 R-H: --grep-in= (hand-written arm); +1 R2: --pattern= (kViewFlags row, the code-shaped structural search); +1 lane/safe-delete (2026-08-21): --safe-delete= (kViewFlags row, the composed "can I delete this?" read); +1 lane/compact-conceptual (2026-08-22): --auto-bodies (kBoolFlags row, the compact-conceptual-serving opt-out); +5 CLI edit bridge (2026-08-27): --replace-symbol-body=/--insert-before-symbol=/--insert-after-symbol=/--edit-payload=/--edit-target-file= (kViewFlags rows); +1 --handles (kBoolFlags row, grep edit handles); +1 --legend= (kViewFlags row, compact schema dialect); +3 edit-plan: --edit-plan= (kViewFlags) and --dry-run/--apply (kBoolFlags rows); +1 --agent= (kViewFlags row, the --doctor Codex surface); +1 lane/paper-slice (2026-08-28): --slice= (kViewFlags row, the ARISE-motivated def-use slice); +1 lane/af-planlint (2026-08-29): --plan-lint= (kViewFlags row, the PLAN-format structure gate, P3.2); +2 lane/or-arise (2026-08-30): --slice-flow= (kViewFlags row) and --slice-depth= (kIntFlags row) — the ARISE rung-2 cross-statement data-flow slice; +1 lane/at-seed (2026-08-30): --at= (kViewFlags row) — the FILE:LINE enclosing-chain report, with the @FILE:LINE selector spelling resolved in graph.h (no flag arm of its own); +1 CARD-1 phase 2 (2026-08-31): --pin-census= (kViewFlags row) — the eval-only S6-C silent-pin census, written beside the map and never into it static_assert( std::size( kBoolFlags ) + std::size( kViewFlags ) + std::size( kIntFlags ) + kHandWrittenFlagArms == kTotalFlagArms, "a --flag arm was added or removed without updating the ledger above — count the arms in parseArgs and fix the counter" ); // ── the kViewFlags scan, as its own function ──────────────────────────────────────────────────────── // Three outcomes, named rather than encoded as a bool-plus-side-effect: the argv element is not a view // flag at all; it is one and its value was assigned; or it is one whose value is EMPTY and was refused // (§A9 V1-4). Lifted out of parseArgs because it is a LOOP WITH AN EARLY BAILOUT inside the argv loop // inside the "--" guard — three nesting levels the caller does not otherwise need — and because "which // flag matched, and did its value survive" is one question with one answer. enum class ViewFlagMatch : std::uint8_t { NoMatch, Assigned, Refused }; // The view flags whose value is a PATH (lennix1337's list from PR #44, plus --in=/--doc-drift=/--exclude= added in // the D3 fix round): the one set whose value takes the program's path spelling at intake (os::normalize_path_arg). // A --grep pattern, a symbol or a number must never be rewritten. NOT here, deliberately: --scope= (one or more // comma-separated GLOBS — '\' is the glob escape character, not a separator to rewrite) and --layout= (a struct/class // name, never a path). inline constexpr std::string_view kPathValuePrefixes[] = { "--eval-mined=", "--eval-skills=", "--arch=", "--cache=", "--index-out=", "--scip=", "--pin-census=", "--lint-rules=", "--exercises=", "--cochange=", "--situ=", "--test-gate=", "--scan-skills=", "--dead-code=", "--plan-lint=", "--scan-skill=", "--batch=", "--at=", "--edit-payload=", "--edit-target-file=", "--edit-plan=", "--eval-stray=", "--from-trace=", "--with-profile=", "--brief=", "--html=", "--affected=", "--in=", "--doc-drift=", "--exclude=" }; // intake: a path-valued flag's value takes the program's path spelling here, once (argv storage is mutable, and Config // borrows it as a view, so the rewrite is in place and never longer). POSIX: nothing — os::normalize_path_arg is empty. inline void normalizePathValueAtIntake( std::string_view prefix, std::string_view value ) noexcept { if( std::ranges::find( kPathValuePrefixes, prefix ) != std::ranges::end( kPathValuePrefixes ) ) { os::normalize_path_arg( const_cast( value.data() ) ); } } inline ViewFlagMatch applyViewFlag( std::string_view arg, Config& c ) { for( const ViewFlag& vf : kViewFlags ) { if( !startsWith( arg, vf.prefix ) ) { continue; } const std::string_view value = arg.substr( vf.prefix.size() ); normalizePathValueAtIntake( vf.prefix, value ); // §B5: the EMPTY-value decision is the row's, never this loop's. Refuse prints here; Meaningful and // HandlerRefuses both fall through to the assignment — the difference between them is which code // OWNS the refusal, and the row records it (the consteval floor beside the table pins the columns). if( value.empty() && vf.onEmpty == EmptyValue::Refuse ) { refuseEmptyValue( vf.prefix, vf.needs, vf.example ); return ViewFlagMatch::Refused; } // G1/F1: a repeat of a flag that silently overwrote its own prior value — checked BEFORE the // assignment so the first value is never clobbered on the way to refusing. if( vf.dupGuardFlag != nullptr && c.*vf.dupGuardFlag ) { rw::emitTo( stderr, "ripwire: {}\n", vf.dupMessage ); return ViewFlagMatch::Refused; } c.*vf.member = value; // §B5: the companion bools the migrated arms used to set by hand — `--owners=SYM` selects the verb // AND narrows it, and a table that could only assign the value would have had to leave those 23 arms // outside it. Mirrors kIntFlags' isSetFlag column exactly. if( vf.isSetFlag != nullptr ) { c.*vf.isSetFlag = true; } if( vf.isSetFlagAlso != nullptr ) { c.*vf.isSetFlagAlso = true; } if( vf.dupGuardFlag != nullptr ) { c.*vf.dupGuardFlag = true; } return ViewFlagMatch::Assigned; } return ViewFlagMatch::NoMatch; } // ── the kIntFlags scan ────────────────────────────────────────────────────────────────────────────── // Same three outcomes and the same shape as applyViewFlag, for the same reason: one loop, one early // bailout, one answer. `arg` is an argv element, so the value tail is NUL-terminated and the existing // parse helpers apply to it unchanged — the domain ceiling is checked on TOP of the parse rather than // inside it, because a value outside the band is refused (§B8.1), never clamped. enum class IntFlagMatch : std::uint8_t { NoMatch, Assigned, Refused }; inline IntFlagMatch applyIntFlag( std::string_view arg, Config& c ) { for( const IntFlag& f : kIntFlags ) { if( !startsWith( arg, f.prefix ) ) { continue; } const char* value = arg.data() + f.prefix.size(); int parsed = 0; const bool isValid = ( f.isZeroAllowed ? parseNonNegInt( value, parsed ) : parsePosInt( value, parsed ) ) && parsed <= f.most; if( !isValid ) { // one sentence for empty, garbage and out-of-range alike: they differ only in the echoed value, // which is the difference the caller actually needs to see const std::string_view bare = f.prefix.substr( 0, f.prefix.size() - 1 ); char flag[ 32 ] = {}; rw::formatTo( flag, sizeof( flag ), "{}", std::string_view( bare.data(), bare.size() ) ); refuseFlagValue( flag, f.wanted, value, f.example ); return IntFlagMatch::Refused; } c.*f.member = parsed; if( f.memberAlso != nullptr ) { c.*f.memberAlso = parsed; } if( f.isSetFlag != nullptr ) { c.*f.isSetFlag = true; } if( f.deprecation != nullptr ) { rw::emitTo( stderr, "{}", f.deprecation ); } return IntFlagMatch::Assigned; } return IntFlagMatch::NoMatch; } // ── validateConfig — the cross-flag contract, checked once the argv loop has closed ───────────────── // 20 combination guards, split out of parseArgs so the FLAG SURFACE (what each literal sets) and the // CONTRACT (which combinations are meaningful) read separately. Reads only `c`, writes only `c.ok` and // stderr; it runs after every arm has had its say, so a guard may assume the whole argv has been seen. // // What deliberately did NOT move: the DEFAULTS. `--mcp` implying `--stable` sat inside this block and is // not a validation — it is a value the parser supplies when the user did not. It stays in parseArgs above // the call. A default carried across this boundary would still compile, still exit 0, and quietly change // output ordering, which is why the boundary is named rather than assumed (test/guardmsgcheck.sh pins // both sides: each guard by its own message, and the --mcp/--stable default by the bytes it changes). // --plan-lanes takes its lanes from EXACTLY ONE of two sources. Six guards, split out // of validateConfig rather than appended to it — that function is already the 20-guard combination contract // and one verb owning a third of a seventh of it belongs in its own body. The refusals are the --partition // class: a companion flag that alone would silently no-op on the default map. `--task`/`--brief` are inputs // to this verb and to nothing else, so each is refused alone; the two are refused TOGETHER because "which // source won?" has no defensible default, and a plan carved from the wrong one looks exactly like a plan // carved from the right one. N is a count of worktrees: 1 is not a fan-out and past 16 an orchestrator is // doing something else (the same 2..16 --partition and the multi-root workspace use); in --brief mode it is // the file's non-blank line count instead, so a count on the command line there is the contradiction it says. inline void validatePlanLanes( Config& c ) noexcept { if( !c.laneTask.empty() && !c.planLanesFlag ) { rw::emitRaw( stderr, "ripwire: --task=GOAL is the input to --plan-lanes=N — pass both (e.g. ripwire --plan-lanes=3 --task=\"the goal\")\n" ); c.ok = false; } if( !c.laneBrief.empty() && !c.planLanesFlag ) { rw::emitRaw( stderr, "ripwire: --brief=FILE is the input to --plan-lanes — pass both (e.g. ripwire --plan-lanes --brief=tasks.md)\n" ); c.ok = false; } if( !c.planLanesFlag ) { return; // nothing below is meaningful without the verb itself } if( c.laneTask.empty() && c.laneBrief.empty() ) { rw::emitRaw( stderr, "ripwire: --plan-lanes needs a task to split — pass --plan-lanes=N --task=\"the goal\" (auto-carve), or --plan-lanes --brief=FILE with one non-blank line per lane\n" ); c.ok = false; } if( !c.laneTask.empty() && !c.laneBrief.empty() ) { rw::emitRaw( stderr, "ripwire: --plan-lanes takes --task=GOAL or --brief=FILE, never both — the lanes would come from two different carves and only one of them is the one you meant\n" ); c.ok = false; } if( !c.laneTask.empty() && ( c.planLaneCount < 2 || c.planLaneCount > 16 ) ) { rw::emitTo( stderr, "ripwire: --plan-lanes={} is out of range — N must be 2..16 (1 is not a fan-out)\n", c.planLaneCount ); c.ok = false; } if( !c.laneBrief.empty() && c.planLaneCount > 0 ) { rw::emitTo( stderr, "ripwire: --plan-lanes={} with --brief=FILE is a contradiction — in brief mode the lane count IS the file's non-blank line count; drop the =N\n", c.planLaneCount ); c.ok = false; } } // §P8 — the eleven "(with X)" modifiers the sweep found accepted-and- // silently-ignored, split out of validateConfig for the SAME reason validatePlanLanes above is split out: // one theme owning a chunk of the guard chain belongs in its own body, not appended to the 20-guard // combination contract function. Also keeps these new guards from inflating validateConfig's own complexity/ // verbosity numbers against its pre-existing baseline (--quality-delta measures per-symbol, and a new // function is a new-symbol, never a regression of an old one) — the SAME reasoning every future batch of // guards should follow: land them in a themed helper, not by growing validateConfig line by line forever. // §P8/G2 — the TWENTY-FIVE verbs that actually window their rows for --limit/--offset, in ONE place, adjacent // to the guard that reads it and to the message that prints it. Keeping the list, the predicate and the // refusal text together is the whole point: the previous failure mode was a --help paragraph naming a set // that the code had already outgrown in both directions, with nothing to make the two disagree loudly. // // Membership is a fact about the EMITTER, not a preference: a verb is in this set iff its serializer runs the // row list through pageview.h's pageWindow(). test/pagingsweepcheck.sh (K) proves the set both ways — every // name here exits 0 under --limit=3, and a sample of the outside refuses. // // §P15/§P16 residual + §P16 follow-up: seven more verbs gained a real deterministic row model and joined — // --seams (the seam-PAIR listing), --zoom (the top-level module listing; --zoom --mermaid stays a fixed-shape // diagram, excluded below the same way plain --mermaid is), --external-surface (the referenced-name listing), // --dead-code (the candidate listing), --mentions (the doc-hit listing), --graph-query (the ranked result // set — --limit now overrides its --top-k display cap the same way it overrides --pack-top-n elsewhere), and // --stray-content (the per-ref listing; row order verified byte-stable across repeated runs before migrating // — a cross-branch git verb pages only once its ordering is proven deterministic, not assumed; its two // companion sub-verbs, --plan and --abi, route to landingplan::writePlan / abicheck::writeAbiCheck, neither // of which windows anything, so honorsPaging() excludes both the same way it excludes --zoom --mermaid). // --metrics stays refusing: it is a DECORATOR on the default map's own top-k/--max-tokens-bounded row set, // not an independent row list of its own — the same budget/top-k reasoning that keeps --for/--expand refusing. // §A3a: --test-gate joins here too — its untested-row list was a bare // 25-row literal cap (situ.h kMaxUntestedRows) with no shown=/capped= and a refusal on --limit that FALSELY // claimed "no page to walk" (there were 41 more rows). It now windows through pageview.h like every verb // above, so it belongs in the honoring set, not the refusing one. // 2026-09-10 (C1 F-07/F-10): --flags (with its --flip mode) and --situ join. Both were listing verbs whose // row caps no flag could reach: --flags cut the sites under a gate at 8, --flip cut six listings at // 25, and --situ cut its blast-radius and co-change sections at 8 while REFUSING --limit outright. All of // those listings run through pageWindow() now, which is what membership in this set means. --situ is the // first PROSE member — it has no XML root, so it spells the same shown=/total=/capped= facts in its section // headers (situ.h) and test/pagingsweepcheck.sh (L) reads it as prose rather than parsing a root element. constexpr const char* kPagingHonoringVerbs = "--lint --hotspots --callers --callees --tree --deps --cochange --owners --clones --doc-drift " "--communities --community --whereis --grep/--regex --match --pattern --impact --uses --exercises " "--seams --zoom --external-surface --dead-code --mentions --graph-query --stray-content --test-gate " "--biggest-first --ensemble --quality-panel --context-ratio --nonlocal-state --comment-coherence " "--naming-consistency --safe-delete --pr-context --edit-check --flags --situ --for --lego"; inline bool honorsPaging( const Config& c ) noexcept { return c.lint || !c.lintRulesDir.empty() || c.hotspots || !c.callers.empty() || !c.callees.empty() || c.tree || c.deps || c.cochange || c.owners || c.clones || c.docDrift || c.communities || c.whereisFlag || !c.grep.empty() || !c.match.empty() || !c.pattern.empty() || !c.impactSym.empty() || !c.usesSym.empty() || c.exercisesFlag || c.communityFlag || c.seams || ( c.zoom && !c.mermaid ) || c.externalSurface || c.deadCode || !c.mentionsSym.empty() || !c.graphQuery.empty() || ( c.strayContent && !c.landingPlan && !c.abiFlag ) || c.testGate || c.readability || c.ensemble || c.qualityPanel || c.contextRatio || c.nonlocalState || c.commentCoherence || c.namingConsistency || !c.safeDeleteSym.empty() || c.prContext // P4 (L7): the changed-file window || !c.editCheckSym.empty() // 2026-09-10: --edit-check windows its UNFLAGGED caller rows (editcheck.h) || c.darkFlags // 2026-09-10 (C1 F-07): --flags' per-gate sites, and --flip's six listings || c.situ || !c.situFiles.empty() // 2026-09-10 (C1 F-10): --situ sections [1] and [3] (section [2] is the answer) // --in=DIR is deliberately NOT a member, and was: it is a MODIFIER of the default map, not a verb, and // membership made validateShapingFlagsHonored refuse every --top-k/--max-tokens/--token-budget beside it // with a message that hands the caller a list of VERBS and claims the default map honours the budgets it // had just refused. The scoped ELEMENT pages (validatePagingHonored's carve-out below); the run does not. // L-W (2026-09-12, forpage.h): --for joins ONLY when a window is asked for — --limit/--offset select its // FILE-GRAIN widening page. Membership is conditional on purpose: the bare --for bundle keeps honoring // --token-budget/--max-tokens/--format=candidates --top-k, which validateShapingFlagsHonored refuses on // every paging member — and refuses beside the page too, where no byte ceiling exists to shape against. || ( !c.forTask.empty() && ( c.pageLimit > 0 || c.pageOffset > 0 ) ) // PAGING-POC (issue #294): --pack-task joins ONLY under a budgeted window — its candidate page // mirrors --for's (the shared emitForCandidatePage). The bare --pack-task bundle keeps refusing // the pair (it has no window to serve), and a windowless budget run is untouched. || ( c.packTaskFlag && c.tokenBudget != 0 && ( c.pageLimit > 0 || c.pageOffset > 0 ) ) // lane lego-transitive: --lego=TYPE joins the same CONDITIONAL way — --limit/--offset window its deeper // implementor rows (depth >= 2, serialize.h legoClosurePage); without a window it keeps its kShapingVerbs row, // so `--lego --max-tokens` is still the "not read … nothing was dropped" notice, not a paging-family refusal. || ( !c.legoType.empty() && ( c.pageLimit > 0 || c.pageOffset > 0 ) ); } // --limit/--offset on a verb that windows NOTHING. Same accept-then-silently-ignore class as every guard in // validateModifierGuards below, and by far the largest instance of it: the default map and ~15 report verbs // took both flags and emitted byte-identical output, so a caller could not tell a no-op from a typo, and a // paging loop written against one of them spun forever. Paginating all of them was rejected — most emit a // small FIXED report where a page has no meaning — so the honest move is to refuse. // // The message names BOTH remedies because the two wrong calls have different right answers: on the default // map the row count is bounded by --top-k (the ranked head) and --max-tokens, not by --limit; on a report // verb there is no remedy at all, only the honoring set to redirect to. // // N6 (verifier fold-in, §B2 round): the closing clause used to read "every other verb emits a fixed report // with no page to walk", which stopped being true the moment --recall started honoring --top-k — the one // non-honoring verb with a real remedy was being told it had none. It now names that remedy and claims // only "the rest". // // Scoped OFF for --mcp/--listen, matching how that surface WORKS rather than by exception: the server answers // SUB-QUERIES carrying their own per-request arguments (the MCP verb objects), so a --limit on the outer // command line modifies no "selected verb" — there isn't one — and refusing it would break a legal // invocation. Its own function for the reason validateModifierGuards states in its header: a themed guard // lands in a helper, it does not grow the combination contract line by line forever. // // §A5a: --batch used to be exempt on that same "sub-queries own their arguments" reasoning, but the exemption // did not do what the reasoning implies — a --limit on the outer command line reached NO sub-query, so // `--batch=F --limit=2` exited 0 with the payload unchanged. That is precisely the accept-and-ignore class // §P15.3 declared extinct, and the refusal text three lines below already promised it ("Any verb NOT in that // list REFUSES both flags"). A batch sub-query that wants a page spells it in the batch FILE, on the line // that selects the verb; the outer flag has no honest meaning, so it refuses like every other non-honoring // verb. --mcp keeps its exemption because there the per-request arguments are a real, exercised channel. // §B11.6 (CA4) — the three MODE flags that turn a paging verb into a fixed report. Without this, the refusal // hands the reader a honoring list with THEIR OWN VERB in it and no way to reconcile that with being refused: // `--stray-content --abi --limit=3` is told "--limit/--offset are honored only by: … --stray-content …", // which reads as a contradiction. The cause is never the base verb; it is the mode, and honorsPaging() already // encodes exactly these three exclusions — this reads the same conditions so the two cannot drift. // Returns nullptr when the refusal has no mode cause (the ordinary "this verb pages nothing" case). inline const char* pagingDisablingMode( const Config& c ) noexcept { if( c.strayContent && c.landingPlan ) { return "--plan"; } if( c.strayContent && c.abiFlag ) { return "--abi"; } if( c.zoom && c.mermaid ) { return "--mermaid"; } return nullptr; } inline void validatePagingHonored( Config& c ) noexcept { if( ( c.pageLimit <= 0 && c.pageOffset <= 0 ) || c.mcp || honorsPaging( c ) ) { return; } // C1-b: --in=DIR windows an ELEMENT, not a verb — the map's block is what --limit/--offset // cut, and the run around it is still the default map. That is why --in is not a kPagingHonoringVerbs row (a // row would make the shaping guard refuse the budgets the map does honour): the honoring decision lives here, // where it is about the flags typed, and the refusal above skips it. if( !c.inDir.empty() ) { return; } // §B11.6: name the MODE first when one is what disabled paging — the honoring list below is otherwise // read as self-contradicting, and the remedy ("drop the mode flag") is not derivable from it. if( const char* mode = pagingDisablingMode( c ) ) { rw::emitTo( stderr, "ripwire: {} turns this run into a fixed report, so --limit/--offset have nothing to window — the base verb pages, this mode does not. Drop {} to page it.\n", mode, mode ); } rw::emitTo( stderr, "ripwire: --limit/--offset are honored only by: {}. The default map is bounded by --top-k=N (or --max-tokens=N) and --recall by --top-k=N, not --limit; the rest emit a fixed report with no page to walk\n", kPagingHonoringVerbs ); c.ok = false; } // §A5b — --format=columnar re-serializes a FLAT SYMBOL-ROW listing (a path table + parallel arrays), and only // four verbs produce one. On any other verb it was accepted and silently ignored: --hotspots/--clones/--lint/ // --tree/--grep --format=columnar all emitted byte-identical XML at exit 0, while its two sibling shape // modifiers (--json, --format=candidates) both refused with the flag named. Same class, same remedy — name // the flag, the supported set, and one working example. Its own function for the reason validateModifierGuards // states in its header: a themed guard lands in a helper, it does not grow validateConfig line by line forever. // // §A5c: --pr-context is deliberately NOT in this set. --help and columnar.h both ADVERTISED it and // prcontext.h contains no columnar code at all (a verified no-op on a dirty tree with 12 changed symbols), // so the claim was struck from both rather than implemented — this refusal now covers it like any other // unsupported verb, which is the honest state of the feature. inline void validateColumnarVerb( Config& c ) noexcept { if( !c.columnar ) { return; } if( !c.callers.empty() || !c.callees.empty() || !c.usesSym.empty() || !c.impactSym.empty() ) { return; } rw::emitRaw( stderr, "ripwire: --format=columnar re-serializes the FLAT symbol-row verbs only — supported: --callers/--callees/--uses/--impact (e.g. ripwire --callers=SYM --format=columnar). Every other verb emits a report with no parallel-array row list to re-encode\n" ); c.ok = false; } // §B9 (capture-audit-4, 2026-07-30) — --top-k / --max-tokens on the report/paging family: the exact mirror // of validatePagingHonored above, same family (honorsPaging IS that family — reused directly rather than // re-deriving a second list that could drift out of sync with it, the trap-ledger #6 lesson from the ruling // that produced kPagingHonoringVerbs in the first place), same accept-and-ignore failure, same remedy shape. // // Measured from source (every cfg.topK / cfg.maxTokens read site in main.cpp, repo-wide grep confirms no // other file touches either field): the default map, plain --query, --format=candidates and --recall honor // --top-k directly; --graph-query is the ONE member of the report/paging family that also shapes its own // ranked cap with it (kPagingHonoringVerbs' own comment already says so). Nothing else in that family reads // cfg.topK at all. --max-tokens is honored by the default map, --recall, --connect, --pr-context and // --from-trace — none of them members of the report/paging family — so no member of that family honors it, // full stop. --for/--pack-task/--exemplar/--from-trace/--situ are OUTSIDE the report/paging family (they are // not in honorsPaging, so this guard never fires for them) and --top-k's inertness there is a DIFFERENT, // already-disclosed residual (--help's own --top-k paragraph; R12) — deliberately not re-litigated here. inline bool honorsTopK( const Config& c ) noexcept { return !c.graphQuery.empty(); } // §H4 / V3 M-4 — the THIRD budget flag, and the one the two original guards missed. --token-budget is read in // exactly six places outside cli.h (runForLens + emitForLensJson, runTargetedViews' --recall arm, // runFromTrace, runRunTrace, runPackTask, runDefaultMap — re-derivable with `ripwire . --grep=tokenBudget`), none of them // in the report/paging family. So every member of that family — including four of the five graph-count verbs // this round disclosed — ACCEPTED it at exit 0 with an empty stderr and emitted the full document, while the // default map on the same flag refuses with rc=3 and a withheld_est_tokens= body. Accepted-and-ignored is a // named failure family here, and it was the sharper defect precisely BECAUSE this lane had just claimed the // byte cost was charged: a caller who set a budget to bound the disclosure got no budget and no word about it. // // V4 MED-2 — DEDUPLICATED, not acked. Adding that third guard as its own function made a THREE-body clone // (two gating duplication findings at 46/50 tokens): the three differed only in which flag selects them, one // extra exemption, and four spans of message text. The debt was invisible to a bare `--quality-delta` on a // clean tree, which compares HEAD to itself — it only shows up against an explicit pre-change base, which is // how it was measured here. Now: ONE table of the four differing spans, ONE emitter, ONE guard. // // The message bytes are UNCHANGED by construction — the table splits each sentence at the two points where // kPagingHonoringVerbs is spliced, so the emitter reassembles exactly what the three fprintf calls printed. // That is the point of doing it this way rather than "harmonizing" the wording: a refusal string is a // user-visible contract and argvdiff pins it, so a dedup that also reworded would be two changes wearing one // commit. The `honoredPre` spans are deliberately long and prose-shaped for the same reason. struct PagingFamilyFlagGuard { const char* honoredPre; // the sentence up to and including the "(" that opens the verb list const char* honoredPost; // whatever follows the closing ")" of that list, up to the shared tail const char* lacks; // why THIS flag has nothing to bite on inside the family const char* example; // the runnable --limit=N alternative }; inline constexpr PagingFamilyFlagGuard kTopKGuard { "--top-k narrows only --graph-query within the --limit/--offset-honoring set (", ") — the default map, plain --query, --format=candidates and --recall honor it too, outside that set", "nothing ranked to cap", "ripwire --hotspots --limit=3" }; // H9 (capture-audit 2026-09-04): both sentences must name EVERY kShapingVerbs row that honors the flag. // They did not: `--html` (which renders the map and inherits its ceiling) was missing from the first and // `--handoff` (whose writeHandoffPacket has taken the budget since M4) from the second — so a caller who // hit this refusal was told, in the tool's own words, that a budget it does honor does not exist there. // test/budgetpolicycheck.sh arm (A) re-derives both lists from the table on every run, so the next verb to // grow a budget column cannot leave the sentence behind. inline constexpr PagingFamilyFlagGuard kMaxTokensGuard { "--max-tokens is honored by the default map (and --html, which renders it), --recall, --connect, " "--pr-context, --from-trace and --for --detail=N — none of them, --pr-context aside (it pages AND shapes by budget), in the --limit/--offset-honoring set (", ")", "no byte budget to shape", "ripwire --hotspots --limit=3" }; inline constexpr PagingFamilyFlagGuard kTokenBudgetGuard { "--token-budget is honored by the default map (the CI gate), --for, --pack-task, --recall, " "--handoff, --from-trace, --run-trace and --pr-context — none of them, --pr-context and --for/--pack-task beside an explicit " "--limit/--offset window aside (those page AND shape by budget: the budgeted-bundle candidate page, issue #294), " "in the --limit/--offset-honoring set (", ")", "no byte budget to gate", "ripwire --callers=SYM --limit=3" }; inline void refusePagingFamilyFlag( Config& c, const PagingFamilyFlagGuard& g ) noexcept { rw::emitTo( stderr, "ripwire: {}{}{}. The rest of that set emit a fixed report with {}; narrow it with --limit=N instead (e.g. {})\n", g.honoredPre, kPagingHonoringVerbs, g.honoredPost, g.lacks, g.example ); c.ok = false; } // The ONE guard. Evaluation order is top-k, then --max-tokens, then --token-budget, and it is OBSERVABLE: // a command line setting two of them gets two messages, in this order (`--max-tokens=500 --token-budget=16K` // is a live argvdiff vector). It is the order the three separate calls ran in, preserved deliberately. inline void validateShapingFlagsHonored( Config& c ) noexcept { if( c.mcp || !honorsPaging( c ) ) { return; } if( c.topKExplicit && !honorsTopK( c ) && !c.prContext ) // P4: pr-context's kShapingVerbs row owns its --top-k notice { refusePagingFamilyFlag( c, kTopKGuard ); } // P4 (L7): --pr-context is the one member of the paging set that ALSO shapes by budget (its trim ladder has // taken --max-tokens since R4, and --token-budget since the default 8K ceiling) — the two budget refusals skip it. if( c.maxTokens > 0 && !c.prContext ) { refusePagingFamilyFlag( c, kMaxTokensGuard ); } // PAGING-POC (issue #294): --for/--pack-task under an EXPLICIT --limit/--offset window page their // budgeted bundle (the candidate-offset continuation) — they page AND shape by budget, the same // class --pr-context holds alone today. The refusal skips that combination only; every other // budgeted verb, and the bare bundles, refuse exactly as before. const bool budgetWindowPages = ( !c.forTask.empty() || c.packTaskFlag ) && ( c.pageLimit > 0 || c.pageOffset > 0 ); if( c.tokenBudget != 0 && !c.prContext && !budgetWindowPages ) { refusePagingFamilyFlag( c, kTokenBudgetGuard ); } } // --lsp is a server transport like --mcp/--listen, but unlike those two it is PROBED by // test/shapingflagcheck.sh arm (F) — so it must land in one of that arm's three buckets. A shaping knob // never reaches a cfg read inside an LSP session (every request carries its own arguments), and unlike // the MCP pass-throughs there is no sub-request dialect these could shape, so --lsp REFUSES them outright // rather than accepting-and-ignoring. The head phrases are the pinned REFUSEPAT contract strings — the // same sentences the honorsPaging family refuses with, so a caller sees one vocabulary. inline void refuseLspShapingFlag( Config& c, const char* head ) noexcept { rw::emitTo( stderr, "ripwire: {} — --lsp answers LSP requests with per-request arguments; drop it (e.g. ripwire --callers=SYM --limit=3)\n", head ); c.ok = false; } inline void validateLspShaping( Config& c ) noexcept { if( !c.lsp ) { return; } if( c.topKExplicit ) { refuseLspShapingFlag( c, "--top-k narrows only --graph-query" ); } if( c.maxTokens > 0 ) { refuseLspShapingFlag( c, "--max-tokens is honored by the default map and its shaping riders" ); } if( c.tokenBudget != 0 ) { refuseLspShapingFlag( c, "--token-budget is honored by the default map and the budgeted verbs" ); } } // §B9.2 (capture-audit-4, wave 3) — the shaping flags on verbs OUTSIDE the report/paging family. // // The two guards above are sound WITHIN honorsPaging (22/22 refuse). The wave-2 verifier then found 14 verbs // OUTSIDE it that take --top-k / --max-tokens at exit 0 with byte-identical output, 11 of them disclosed // nowhere at all — so the guard family closed the half it could see and the other half stayed silent. // // DERIVED FROM THE READ SITES, not from measurement. `cfg.topK` and `cfg.maxTokens` are read in exactly nine // and seven places repo-wide, and a verb that never reads the field ignores it for EVERY input — which is the // distinction the verifier's own false start turned on: its first --connect and --pr-context probes looked // like ignores and were INERT (a 705-byte subgraph has nothing for a 200-token ceiling to trim). Measurement // cannot separate those two; the read sites can, and they say --connect/--pr-context/--from-trace DO honour // --max-tokens. test/shapingflagcheck.sh re-derives the read sites from source on every run and fails if this // table disagrees with them, so the list cannot rot the way kPagingHonoringVerbs' prose once did. // // The answer is a NOTICE, not a refusal, and the two differ on purpose. §P15.3's complaint is that a caller // "could not tell a no-op from a typo"; one line on stderr answers exactly that, at the moment the mistake is // made, and better than a --help paragraph nobody re-reads. A refusal would additionally BREAK // `--for=X --max-tokens=5000`, which is a natural thing to type and has exited 0 for the tool's whole life — // and R12 already recorded DISCLOSE (not refuse) as the decision for --for/--pack-task/--exemplar + --top-k. // Nothing here changes an output byte or an exit code. struct ShapingVerb { std::string_view name; // the spelling the notice prints bool Config::* isSelectedFlag = nullptr; // selected by a bool member… std::string_view Config::* isSelectedValue = nullptr; // …or by a non-empty value member (exactly one) bool honorsTopK = false; bool honorsMaxTokens = false; bool honorsTokenBudget = false; // §H4/V3 M-4 — the third budget flag, same ledger }; // Every row here is a verb OUTSIDE honorsPaging that reads NEITHER field, except where a column says // otherwise. --for is the one shape a flat table cannot state: it ignores --max-tokens bare and HONOURS it // under --detail=N (main.cpp's detailBodyBudget), so its row claims no honouring and the guard below carves // that case out by hand, named. // // THE THREE-WAY SPLIT, measured on src/ + the repo root and cross-checked against the read sites. INERT is a // property of the INPUT and never of the verb, which is why it is not a column: a verb that does not read the // field ignores it on every input, and a verb that does read it can still look unchanged on an input too // small to trim. Recorded here because the wave-2 verifier got exactly this wrong the first time. // // HONOURS --max-tokens default map (and everything that rides its serialize path: --query, --metrics, // --map-diff, --expand, --outline, --pack-signatures), --recall, --connect, // --pr-context, --from-trace, --for --detail=N [6 shapes] // HONOURS --top-k default map (+ the same riders), --query, --format=candidates, --recall, // --graph-query, and the MCP/batch/--listen pass-throughs // IGNORES both --pack-task, --exemplar, --around, --path, --lego, --report, // --scan-skills, --merge-scout, and --for for --top-k (R12's residual) // (--situ and --flags LEFT this class on 2026-09-10 (C1 F-07/F-10), the way // --edit-check did: their row listings became windowable, so they joined // honorsPaging and refuse all three like every other member.) // (--edit-check LEFT this class the same day: it joined honorsPaging when its // unflagged caller rows became windowable, so it refuses all three like every // other paging member instead of accepting them and ignoring them. A verb cannot // hold a row in BOTH tables — the header sentence above is the invariant.) // IGNORES --top-k only --connect, --pr-context, --from-trace — the three the verifier first read as // ignoring --max-tokens too. They were INERT on its probes: --connect answered a // 705 B subgraph, so a 200-token ceiling had nothing to trim. On a shape where the // budget binds they all shape (--connect 705->586 B, --pr-context 25413->3697 B, // --from-trace 13606->2590 B), and the read sites agree. // REFUSES all three the honorsPaging members (the set above — counting them here is how this comment went stale once already) — validateShapingFlagsHonored, one guard over the // kTopKGuard / kMaxTokensGuard / kTokenBudgetGuard rows. // // HONOURS --token-budget the default map (the CI gate, runDefaultMap), --for (runForLens + // emitForLensJson), --pack-task (runPackTask), --recall (runTargetedViews) and // --from-trace (runFromTrace). Derived the same way as the other two columns — from // the five read sites outside cli.h, not from measurement. NOTE that --connect and // --pr-context honour --max-tokens but NOT --token-budget: the two flags are not // interchangeable and the columns differ on exactly those two rows, which is the // reason this is a third column rather than an alias of the second. inline constexpr ShapingVerb kShapingVerbs[] = { { "--for", nullptr, &Config::forTask, false, false, true }, // --detail=N carve-out below; --top-k: R12 residual { "--pack-task", &Config::packTaskFlag, nullptr, false, false, true }, { "--exemplar", nullptr, &Config::exemplar }, { "--around", nullptr, &Config::around }, { "--path", nullptr, &Config::pathSpec }, { "--lego", nullptr, &Config::legoType }, { "--report", &Config::report, nullptr }, { "--slice", nullptr, &Config::sliceSpec }, { "--at", nullptr, &Config::atSpec }, { "--handoff", &Config::handoff, nullptr, false, false, true }, // writeHandoffPacket takes the budget { "--scan-skills", &Config::scanSkills, nullptr }, { "--merge-scout", &Config::mergeScoutFlag, nullptr }, { "--connect", nullptr, &Config::connectSpec, false, true }, // packConnect takes the budget { "--pr-context", &Config::prContext, nullptr, false, true, true }, // writePrContext takes the budget; P4 (L7): --token-budget too (the default 8K ceiling's explicit form) { "--from-trace", nullptr, &Config::fromTrace, false, true, true }, // FromTraceInputs::bodyBudgetBytes { "--run-trace", nullptr, &Config::runTrace, false, false, true }, // runRunTrace takes the budget (exec-mode --from-trace) // ── capture-audit 2026-09-04 (H3): the verbs that were in NEITHER guard table ────────────────────── // Eighteen verbs took all three knobs at exit 0 with byte-identical output and an empty stderr — the // table above closed the family it could see, and these were outside both it and honorsPaging. They are // rows now, and test/shapingflagcheck.sh arm (F) sweeps the whole flag universe (test/flaguniverse.py) // so the next verb outside both tables fails the gate by name instead of shipping silent. Every row here // reads none of the three fields (re-derived from the read sites, as the header says) except --html, // which rides the default map's serialize path and honours --top-k/--max-tokens like the map does. { "--html", &Config::html, nullptr, true, true }, { "--verify", nullptr, &Config::verifyClaim }, { "--layout", &Config::layoutFlag, nullptr }, { "--field-affinity", &Config::fieldAffinity, nullptr }, { "--naming-calibration",&Config::namingCalibration, nullptr }, { "--lint-catalog", &Config::lintCatalog, nullptr }, { "--dmm", &Config::dmm, nullptr }, { "--quality-delta", &Config::qualityDelta, nullptr }, // --quality-ack=REASON implies it and lands here too { "--quality-baseline", &Config::qualityBaseline, nullptr }, { "--affected", nullptr, &Config::affectedFiles }, { "--plan-lint", nullptr, &Config::planLintFile }, { "--plan-lanes", &Config::planLanesFlag, nullptr }, { "--help-task", nullptr, &Config::helpTask }, { "--arch", nullptr, &Config::archRules }, { "--mermaid", &Config::mermaid, nullptr }, // plain and `--zoom --mermaid` (the one --zoom shape outside honorsPaging) { "--scan-skill", nullptr, &Config::scanSkillFile }, { "--eval", &Config::eval, nullptr }, { "--eval-retrieval", &Config::evalRetrieval, nullptr }, { "--eval-mined", nullptr, &Config::evalMined }, { "--eval-skills", nullptr, &Config::evalSkills }, { "--eval-stray", nullptr, &Config::evalStray }, { "--export=cc.json", &Config::exportCcJson, nullptr }, { "--index-out", nullptr, &Config::indexOut }, { "--batch", nullptr, &Config::batchFile }, // sub-queries carry their own arguments; the outer knob reaches none of them { "--notes", &Config::notesList, nullptr }, { "--note-add", &Config::noteAddFlag, nullptr }, { "--doctor", &Config::doctor, nullptr }, { "--skipped", &Config::skippedList, nullptr }, { "--edit-plan", nullptr, &Config::editPlan }, { "--replace-symbol-body", nullptr, &Config::replaceSymbolBody }, { "--insert-before-symbol", nullptr, &Config::insertBeforeSymbol }, { "--insert-after-symbol", nullptr, &Config::insertAfterSymbol }, { "--stray-content --plan", &Config::landingPlan, nullptr }, // the two --stray-content sub-modes honorsPaging excludes { "--stray-content --abi", &Config::abiFlag, nullptr }, }; // which row (if any) does this invocation select? First match wins, which mirrors main()'s own dispatch // order closely enough for a message: on a multi-verb command line an earlier verb takes precedence there // too, and naming ONE of them is the point (the note is about the flag, not about the verb ordering). inline const ShapingVerb* selectedShapingVerb( const Config& c ) noexcept { for( const ShapingVerb& v : kShapingVerbs ) { const bool isSelected = v.isSelectedFlag != nullptr ? c.*v.isSelectedFlag : v.isSelectedValue != nullptr ? !( c.*v.isSelectedValue ).empty() : false; if( isSelected ) { return &v; } } return nullptr; } inline void noticeShapingFlagIgnored( const Config& c ) noexcept { if( c.mcp || ( honorsPaging( c ) && !c.prContext ) ) // P4 (L7): pr-context pages AND shapes — its row below speaks { return; // that family REFUSES; two messages would be noise } if( c.topKExplicit == false && c.maxTokens <= 0 && c.tokenBudget == 0 ) { return; } const ShapingVerb* const verb = selectedShapingVerb( c ); if( verb == nullptr ) { return; // the default map (and its riders) honour both } // capture-audit 2026-09-04 (H3, lens 4): two false notices, both on --for. // * `--for --format=candidates --top-k=5` said "--top-k is not read by --for … nothing was dropped" on a // run the candidates export had just CUT to 5 — the export composes with --for and consumes the flag // (--help: "Composes with --top-k"), so when it is present the flag was read and the note is a lie. // * `--for --top-k=0` printed this notice AND the T2 refusal ("--top-k=0 means no ranked map, payload // only") — two sentences about one flag. The T2 guard owns the zero spelling; this note is for a // positive K the verb never looked at. const bool isTopKConsumedBeside = c.candidates || c.topK == 0; if( c.topKExplicit && !verb->honorsTopK && !isTopKConsumedBeside ) { rw::emitTo( stderr, "ripwire: --top-k is not read by {} — it shapes the default map, --query, --format=candidates, --recall and --graph-query. {} emitted its full result (nothing was dropped); narrow it with the verb's own arguments instead\n", std::string_view( verb->name.data(), verb->name.size() ), std::string_view( verb->name.data(), verb->name.size() ) ); } // the --detail carve-out: `--for --detail=N` DOES bound its bodies with --max-tokens, so a note there // would be false. Stated as a condition rather than a table column because it is the one cross-flag case. const bool isForDetailBudget = !c.forTask.empty() && c.detail > 0; if( c.maxTokens > 0 && !verb->honorsMaxTokens && !isForDetailBudget ) { rw::emitTo( stderr, "ripwire: --max-tokens is not read by {} — it shapes the default map, --recall, --connect, --pr-context, --from-trace and --for --detail=N. {} emitted its full result (nothing was dropped)\n", std::string_view( verb->name.data(), verb->name.size() ), std::string_view( verb->name.data(), verb->name.size() ) ); } // §H4 / V3 M-4: the third budget flag reaches the same rows. --edit-check is the graph-count verb this // arm actually covers (the other five are inside honorsPaging and REFUSE), and its warn-and-emit is // deliberate, not an oversight: the boundary is honorsPaging membership, not the five-verb set, and // §B9.2/R12 settled DISCLOSE-not-refuse out here because refusing would break `--for=X --max-tokens=5000`, // a shape that has exited 0 for the tool's whole life. Same treatment, same reason. if( c.tokenBudget > 0 && !verb->honorsTokenBudget ) { rw::emitTo( stderr, "ripwire: --token-budget is not read by {} — it gates the default map and bounds --for, --pack-task, --recall, --from-trace and --run-trace. {} emitted its full result (nothing was withheld)\n", std::string_view( verb->name.data(), verb->name.size() ), std::string_view( verb->name.data(), verb->name.size() ) ); } } // --sarif's four companion guards (src/sarif.h serializes --lint's findings as SARIF instead of the // native XML block). Split out of validateModifierGuards for the same reason the delegated // calls at its top are: one flag's own guard cluster stays one small function instead of growing the // caller's branch count. inline void validateSarifModifierGuards( Config& c ) noexcept { // Modifies --lint / --lint-rules; alone it would silently no-op exactly like --with-profile above. if( c.sarif && !c.lint && c.lintRulesDir.empty() ) { rw::emitRaw( stderr, "ripwire: --sarif modifies --lint or --lint-rules=DIR — pass one (e.g. ripwire --lint --sarif)\n" ); c.ok = false; } // --match takes an entirely different branch of runLint (its own element, no rule/severity // shape at all) and returns before the --lint/--lint-rules findings are even assembled — --sarif // would silently never take effect there. Refuse rather than let it look honored. if( c.sarif && !c.match.empty() ) { rw::emitRaw( stderr, "ripwire: --sarif has no effect with --match — it serializes --lint/--lint-rules findings only\n" ); c.ok = false; } // R2: --pattern is --match's sibling in exactly the way that matters here — its own element, // no rule/severity shape, and an early return from runLint before any finding is assembled. The same // silent no-op, so the same loud refusal; a pairing that looks honored and is not is the shape this // arm exists to prevent, and adding the verb without adding the arm would have reintroduced it. if( c.sarif && !c.pattern.empty() ) { rw::emitRaw( stderr, "ripwire: --sarif has no effect with --pattern — it serializes --lint/--lint-rules findings only\n" ); c.ok = false; } // --with-profile's heat_* join has no SARIF field defined yet (the honesty rule: represent it or // refuse, never drop it silently) — refuse the pairing rather than silently omit the join. if( c.sarif && !c.withProfile.empty() ) { rw::emitRaw( stderr, "ripwire: --sarif does not yet support --with-profile — the heat_* join has no SARIF field; run them separately\n" ); c.ok = false; } // SARIF is meant to be ONE complete document per run (that is what upload-sarif consumes) — a // paginated slice would silently under-report to a consumer that has no paging concept. Refuse // rather than emit a partial document that looks complete. if( c.sarif && ( c.pageLimit > 0 || c.pageOffset > 0 ) ) { rw::emitRaw( stderr, "ripwire: --sarif always emits the full result set — drop --limit=N/--offset=M\n" ); c.ok = false; } } // --lint-select=/--lint-ignore='s ONE companion guard, split out for the same reason // validateSarifModifierGuards is: a flag's own guard cluster stays one small function instead of // growing the caller's branch count. The PREFIX list itself (malformed entries, unresolvable prefixes) // is validated inside runLint, not here — see resolveLintSelection's own header for why. inline void validateLintSelectionModifierGuards( Config& c ) noexcept { if( c.lint || !c.lintRulesDir.empty() ) { return; // every modifier below has its verb } // one row per lint modifier, refused in this order (knob-honesty-068 folded the third into a table, not a third copy) struct LintModifierGuard { bool given; const char* refusal; }; const LintModifierGuard guards[] = { { !c.lintSelect.empty(), "ripwire: --lint-select=PREFIX modifies --lint or --lint-rules=DIR — pass one (e.g. ripwire --lint --lint-select=cache-)\n" }, { !c.lintIgnore.empty(), "ripwire: --lint-ignore=PREFIX modifies --lint or --lint-rules=DIR — pass one (e.g. ripwire --lint --lint-ignore=naming-)\n" }, { c.lintMaxPerRule > 0, "ripwire: --lint-max-per-rule=N modifies --lint or --lint-rules=DIR — pass one (e.g. ripwire --lint --lint-max-per-rule=50000)\n" }, }; for( const LintModifierGuard& g : guards ) { if( g.given ) { rw::emitRaw( stderr, g.refusal ); c.ok = false; } } } // ── THE LEGEND POSTURES (L1, round 1 of the answer-size loop, 2026-09-19) ──────────────────────────────── // One row per posture. The value space is a TABLE, not a two-valued test, because it is meant to grow: round 2's // legend-once-per-session posture (`ref`, A1-3) is one more row here, and every reader — the refusal below, the // flag table's hint, --help — reads the table rather than restating "full or compact". // // THE DEFAULT IS compact (owner decision 09-19, prereg L1 / A1-1). The MCP server has defaulted to compact since // M1 (2026-09-05); the CLI was the one surface still paying ~1.4-5 KB of prose per call, and the callers who pay // it are agents, scripts and harnesses making repeated calls. `--legend=full` restores the full prose legend // byte-for-byte (compactlegendcheck (A) pins it against the pre-L1 bytes). --for is no longer exempt: its compact // header is its own dialect (verbs_for.h), and under a --token-budget it never loses a row --legend=full keeps // (compactlegendcheck (P1) asserts rows(default) ⊇ rows(--legend=full)) — with ONE ruled exemption (knob-honesty-068 round 3, // option B): a default whose header is larger than full's, that fits its budget and paid the row for its (P1-B). inline constexpr std::string_view kLegendPostures[] = { "full", "compact" }; inline constexpr std::string_view kDefaultLegendPosture = "compact"; static_assert( std::ranges::contains( kLegendPostures, kDefaultLegendPosture ), "the default is a registered posture" ); [[nodiscard]] inline bool isLegendPosture( std::string_view v ) noexcept { return std::ranges::contains( kLegendPostures, v ); } // The runs with no XML legend to shape: text/markdown/JSON-native answers, the runs that WRITE, and the servers. // An ASKED --legend refuses on these (a posture flag must never be the reason an edit, a note, a baseline or a // server starts); the DEFAULT posture simply does not apply to them. nullptr = the run answers XML. // The READ surfaces among them — answers already written in the full dialect's own terms (prose, markdown, JSON, text // tables). An asked --legend=full is a no-op there, not a refusal (L1 fix round, rv-r1-L1 MED-6): the release notes tell a // script that parses the full prose to pass --legend=full, and one that appends it to every read call got exit 1 on // exactly the answers that print nothing BUT the full form. nullptr = none of them. [[nodiscard]] inline const char* legendNonXmlReadSurface( const Config& c ) noexcept { const char* nonXml = nullptr; if( c.situ || !c.situFiles.empty() ) { nonXml = "--situ (prose)"; } else if( !c.recall.empty() ) { nonXml = "--recall (markdown bodies)"; } else if( c.report ) { nonXml = "--report (markdown)"; } else if( c.mermaid ) { nonXml = "--mermaid"; } else if( c.html || !c.htmlFile.empty() ) { nonXml = "--html"; } else if( c.planLanesFlag ) { nonXml = "--plan-lanes (JSON-native)"; } else if( c.sarif ) { nonXml = "--sarif (JSON)"; } else if( c.eval || c.evalRetrieval || !c.evalMined.empty() || !c.evalSkills.empty() || !c.evalStray.empty() ) { nonXml = "--eval* (text tables)"; } return nonXml; } // …and the runs that WRITE or SERVE: any asked posture refuses there — a posture flag must never be the reason an edit, a // note, a baseline or a server starts. nullptr = none of them. [[nodiscard]] inline const char* legendWriteOrServeSurface( const Config& c ) noexcept { const char* nonXml = nullptr; if( c.exportCcJson || !c.exportFile.empty() ) { nonXml = "--export (writes a file)"; } else if( !c.noteAdd.empty() ) { nonXml = "--note-add (writes .ripwire_notes)"; } else if( c.qualityBaseline ) { nonXml = "--quality-baseline (writes the sidecar)"; } else if( c.qualityAck || !c.qualityAckReason.empty() || !c.qualityAckOnly.empty() ) { nonXml = "--quality-ack (writes the ledger)"; } else if( !c.indexOut.empty() ) { nonXml = "--index-out (writes an index)"; } // (--pin-census is not here since L1: it writes its census BESIDE the map and the map is this run's answer, so once // the default map is compact, refusing an asked --legend=full would leave no way to read that map's full legend.) else if( c.baseline || c.baselineUpdate ) { nonXml = "--arch --baseline (writes the baseline)"; } else if( !c.replaceSymbolBody.empty() || !c.insertBeforeSymbol.empty() || !c.insertAfterSymbol.empty() || !c.editPlan.empty() ) { nonXml = "the edit verbs (JSON receipts)"; } else if( c.mcp || !c.listen.empty() ) { nonXml = "--mcp/--listen (pass legend:\"compact\" per call instead)"; } else if( c.lsp ) { nonXml = "--lsp (an LSP server over stdio)"; } return nonXml; } [[nodiscard]] inline const char* legendNonXmlSurface( const Config& c ) noexcept { const char* read = legendNonXmlReadSurface( c ); return read != nullptr ? read : legendWriteOrServeSurface( c ); } // THE DEFAULT, RESOLVED ONCE (L1). A run that names no posture gets kDefaultLegendPosture here, so every downstream // reader (--for/--grep/--slice's native dialects, --batch's sub-answers, main.cpp's rewrite layer) asks ONE question — // cfg.legend == "compact" — and cannot disagree about the default. legendDefaulted records that nobody asked: // main.cpp then passes an answer the dialect cannot shape through unchanged instead of refusing it — which is why the // default is NOT withheld from a run carrying a non-XML flag. Dispatch precedence can hand such a run to an XML verb // (`--exemplar=X --recall=Y` answers --exemplar), and that answer must be the one --exemplar alone prints // (dispatchordercheck); a prose/JSON/markdown answer simply passes through. Only three things keep no default: the // servers (--mcp/--listen/--lsp own stdout for their whole life and take the posture per request), and --json, whose // answers carry no legend to shape. static inline void validateLegendModifier( Config& c ) noexcept { const char* nonXml = legendNonXmlSurface( c ); if( c.legend.empty() ) { const bool servesStdout = c.mcp || !c.listen.empty() || c.lsp; if( !servesStdout && !c.json ) { c.legend = kDefaultLegendPosture; c.legendDefaulted = true; } return; } // r2-LO: legend=ref is a SESSION posture — definitions sent once per server process, after the session read the // dictionary (legenddict.h). A CLI run is one answer with no session to have been served anything, so a ref answer // here would point at definitions its reader never received. Refused, naming both places ref and the dictionary live. if( c.legend == "ref" ) { rw::emitRaw( stderr, "ripwire: --legend=ref is the MCP server's session posture (a session that read ripwire://legend-dict gets " "each definition once); a CLI run has no session to hold it — use --legend=compact, and ripwire --legend-dict " "prints every definition\n" ); c.ok = false; return; } if( !isLegendPosture( c.legend ) ) { rw::emitTo( stderr, "ripwire: --legend needs full or compact — got '{}', e.g. --legend=compact\n", std::string_view( c.legend.data(), c.legend.size() ) ); c.ok = false; } // P1 (capture-audit 2026-09-04, L7): every XML verb honors --legend=compact (main.cpp's runWithCompactLegend // + compactlegend.h; --for/--grep/--slice compact natively). The refusal belongs to the runs with nothing to // compact — legendNonXmlSurface above. test/compactlegendcheck.sh (U) sweeps the whole flag universe: XML at // defaults ⇒ compact honored, anything else ⇒ this refusal. if( c.legend == "full" && legendNonXmlReadSurface( c ) != nullptr && legendWriteOrServeSurface( c ) == nullptr ) { return; // the full form is the only form these answers have: accepted, and a no-op (runWithCompactLegend never captures it) } if( nonXml != nullptr ) { rw::emitTo( stderr, "ripwire: --legend={} applies to the XML verbs only — {} has no XML legend to compact; drop --legend (e.g. ripwire --callers=SYM --legend=compact)\n", std::string_view( c.legend.data(), c.legend.size() ), nonXml ); c.ok = false; } } // L2 (round-1 lever B1, lane/r1-for-sections-stub): --sections=lego,compose restores the / // sections the ranked --for lens collapses to a counted stub by default (src/serialize.h sectionStubXml) — // the disclosed §9.3 cut named in the stub's own next=. A CLOSED, comma-separated, order-insensitive set // (each name at most once) so a typo is refused rather than silently read as "nothing restored"; it // modifies --for=TASK only (the sections exist nowhere else). static inline void validateSectionsModifier( Config& c ) noexcept { if( c.sections.empty() ) { return; } if( c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --sections=lego,compose modifies --for=TASK — pass both (e.g. ripwire --for=\"…\" --sections=lego,compose)\n" ); c.ok = false; return; } // EVERY segment is read, the empty one after a trailing comma included (CodeRabbit 4054594298): the loop // ends on "no comma left", not on "nothing left", so `lego,` and `lego,,compose` reach the refusal below. bool sawLego = false, sawCompose = false, bad = false; std::string_view rest = c.sections; for( bool more = true; more; ) { const std::size_t comma = rest.find( ',' ); const std::string_view tok = comma == std::string_view::npos ? rest : rest.substr( 0, comma ); if( tok == "lego" ) { bad = bad || sawLego; sawLego = true; } else if( tok == "compose" ) { bad = bad || sawCompose; sawCompose = true; } else { bad = true; } more = comma != std::string_view::npos; rest = more ? rest.substr( comma + 1 ) : std::string_view(); } if( bad || ( !sawLego && !sawCompose ) ) { rw::emitTo( stderr, "ripwire: --sections needs a comma-separated list of lego and/or compose, each named once — got '{}', e.g. --sections=lego,compose\n", std::string_view( c.sections.data(), c.sections.size() ) ); c.ok = false; } } // P4 (capture-audit 2026-09-04, L7): the two default-ceiling modifiers are inert without their verb — refused, // naming the pairing (M16's rule: a bare modifier never emits the default map at exit 0). static inline void validateDefaultCeilingModifiers( Config& c ) noexcept { if( c.zoomLevelsSet && !c.zoom ) { rw::emitRaw( stderr, "ripwire: --zoom-levels=N modifies --zoom — pass it too (e.g. ripwire --zoom --zoom-levels=0 prints every level)\n" ); c.ok = false; } if( c.includeBuiltins && !c.externalSurface ) { rw::emitRaw( stderr, "ripwire: --include-builtins modifies --external-surface — pass it too (e.g. ripwire --external-surface --include-builtins)\n" ); c.ok = false; } } static inline void validateGrepHandleModifier( Config& c ) noexcept { if( c.grepHandles && c.grep.empty() ) { rw::emitRaw( stderr, "ripwire: --handles modifies --grep=STR or --regex=PAT — pass one too (e.g. ripwire --grep=stale --handles)\n" ); c.ok = false; } } // ── THE --since HOST TABLE (capture-audit verify-wave2 N4, 2026-09-05) ──────────────────────────────── // --since is a GLOBAL flag with five consumers in TWO CLASSES, and the classes ask different questions: // WINDOW hosts ask "how far back does the churn walk go". A value the repo's history never reaches // (--since=1999-01-01) is simply ALL of history, and is answered with the window stamped as given. // BASELINE hosts ask "which COMMIT do I compare against". The same value names no commit, so there is // nothing to diff against and the run refuses. // Both answers are honest, and they are deliberately NOT the same answer — wave 1's N4 was closed at the // SOURCE (one resolver, one sentence) while the behaviours still diverged, and verify-wave2 was right that // "one policy" had not been shown. What makes it one policy is that the CLASS IS DECLARED HERE, once, and // every decision about --since reads this table: the "the flag would do nothing" refusal below, and the // no-baseline refusal in main.cpp — which used to spell its own half as `!cfg.sliceSpec.empty()`, a second // copy of the host list that a sixth consumer could contradict by omission. Now a new host adds one row and // inherits both decisions; a host that forgets the row cannot run with --since at all (the refusal below // fires), so the failure mode is loud rather than a silently wrong class. // Gate: test/sincecheck.sh re-derives these rows FROM THIS TABLE and asserts each one's behaviour on a // reachable value, an unreachable-but-real one, and an impossible one. struct SinceHost { std::string_view flag; bool needsBaseline; // true = compares against a COMMIT; false = walks a WINDOW }; inline constexpr SinceHost kSinceHosts[] = { { "--hotspots", false }, { "--cochange", false }, { "--rank-by=churn", false }, { "--rank-by=churn-decay", false }, { "--slice", true }, }; // --in=DIR's HOSTS, declared the way kSinceHosts declares --since's and for the same reason: --in scopes a // recent-changes BLOCK, and only a verb that HAS such a block can be scoped. Written as a table rather than as // `c.rankBy != RankBy::ChurnDecay` inline so that the planned `--for --in=DIR` is ONE ROW here and inherits // both decisions that read it — this refusal, and main.cpp's derived "did something answer instead" sweep — // instead of a second copy of the host list that a later consumer can contradict by omission. inline constexpr std::string_view kInHosts[] = { "--rank-by=churn-decay" }; // Is this host the one the run selected? One switch, beside the table it switches on, so the two cannot // drift; a flag this function does not know is never active. inline bool sinceHostActive( const Config& c, std::string_view flag ) noexcept { if( flag == "--hotspots" ) { return c.hotspots; } if( flag == "--cochange" ) { return c.cochange; } if( flag == "--rank-by=churn" ) { return c.rankBy == RankBy::Churn; } if( flag == "--rank-by=churn-decay" ) { return c.rankBy == RankBy::ChurnDecay; } if( flag == "--slice" ) { return !c.sliceSpec.empty(); } return false; } // Is one of --in's hosts the verb this run selected? It REUSES the switch above rather than writing a second // one: every kInHosts row is a history-windowed verb, which is the same property kSinceHosts rows have, and // two switches over the same question is the clone --quality-delta catches (it caught exactly that here). // A kInHosts row must therefore also be a kSinceHosts row — true of --rank-by=churn-decay, and true of the // planned --for --in=DIR only once --for takes --since, which is the honest order for both flags anyway. inline bool inHostActive( const Config& c ) noexcept { // The static_assert, not a loop, is what keeps this honest at one row: a loop over a one-row table is a // clone of every other any_of-over-a-table in the tree (--quality-delta paired it with two), and a second // row here must also grow the refusal's prose, which the assert forces someone to notice. static_assert( std::size( kInHosts ) == 1, "--in=DIR reads its single host here and names it in prose below — extend both together" ); return sinceHostActive( c, kInHosts[0] ); } // The two questions asked of this table are the SAME walk over it with one predicate switched, so they are // one function: "is any host selected" and "is the selected host a baseline host". Written as two loops // first, and --quality-delta named the second a 37-token clone of the first the same afternoon. inline bool anySinceHostActive( const Config& c, bool baselineOnly = false ) noexcept { for( const SinceHost& h : kSinceHosts ) { if( ( !baselineOnly || h.needsBaseline ) && sinceHostActive( c, h.flag ) ) { return true; } } return false; } // Does the run's --since host need a COMMIT to compare against? Read by main.cpp beside the M8 shape/range // validation — the one place the no-baseline refusal is decided, now from the one place the class is stated. inline bool activeSinceHostNeedsBaseline( const Config& c ) noexcept { return anySinceHostActive( c, /*baselineOnly=*/true ); } inline void validateModifierGuards( Config& c ) noexcept { validatePagingHonored( c ); // §P8/G2: --limit/--offset on a verb that windows nothing (see its header) validateColumnarVerb( c ); // §A5b: --format=columnar on a verb with no flat row list (see its header) validateShapingFlagsHonored( c ); // §B9 + §H4/M-4: --top-k / --max-tokens / --token-budget on a report/ // paging verb that shapes with none of them (one guard, three rows) noticeShapingFlagIgnored( c ); // §B9.2: the same two flags OUTSIDE that family — a NOTICE, never c.ok validateLspShaping( c ); // the server transport refuses the shaping knobs outright — see its header validateLegendModifier( c ); validateSectionsModifier( c ); // L2 (round-1 lever B1): --sections= modifies --for only, closed set validateGrepHandleModifier( c ); validateDefaultCeilingModifiers( c ); // P4 (L7): --zoom-levels / --include-builtins ride their verb only // --mcp-token/--allow-remote-edits are read ONLY inside the --listen HTTP branch (main.cpp's // McpHttpConfig assembly) — the stdio --mcp path never touches either member, so bare `--mcp --mcp-token=…` // (no --listen) is exactly as inert as no `--mcp` at all. Refuse loudly rather than let a caller believe // they set a token or granted remote-edit access that never reached the server. if( !c.mcpToken.empty() && c.listen.empty() ) { rw::emitRaw( stderr, "ripwire: --mcp-token is read by the --listen HTTP transport only — pass both (e.g. ripwire . --listen=127.0.0.1:8765 --mcp-token=SECRET)\n" ); c.ok = false; } // --mcp-legend= shapes the stdio session's legend posture; the HTTP transport holds no session (every answer inline). if( !c.mcpLegend.empty() && ( !c.mcp || !c.listen.empty() ) ) { rw::emitRaw( stderr, "ripwire: --mcp-legend is read by the stdio MCP server only (--listen holds no legend session) — e.g. ripwire . --mcp --mcp-legend=inline\n" ); c.ok = false; } if( !c.mcpTools.empty() && !c.mcp ) // --listen sets c.mcp, so this covers both transports { rw::emitRaw( stderr, "ripwire: --mcp-tools is read by the MCP server only — pass --mcp (or --listen) too, e.g. ripwire . --mcp --mcp-tools=core\n" ); c.ok = false; } if( c.allowRemoteEdits && c.listen.empty() ) { rw::emitRaw( stderr, "ripwire: --allow-remote-edits is read by the --listen HTTP transport only — pass both (e.g. ripwire . --listen=127.0.0.1:8765 --allow-remote-edits --mcp-token=SECRET)\n" ); c.ok = false; } // --lsp and the MCP transports all own stdin, and --lsp has no socket form in Phase 1 (docs/LSP.md // Non-Goals), so the combination is REFUSED rather than resolved by precedence — the caller must pick // one protocol per stdin rather than discover by silence which one a process actually spoke. if( c.lsp && ( c.mcp || !c.listen.empty() ) ) { rw::emitRaw( stderr, "ripwire: --lsp speaks stdio and --mcp/--listen already own it — one protocol per stdin; drop --mcp/--listen to run the LSP server\n" ); c.ok = false; } // --force is read ONLY by `ripwire wrap ` (src/wrap.h, its OWN raw-argv scan — main() returns from // runWrap before Config/parseArgs even runs). The flag surface still accepts it into Config::force // (kBoolFlags), but nothing ever reads that member outside `wrap`, so `ripwire --force` silently // does nothing for any verb. Refuse — this is a different subcommand, not a missing companion flag. if( c.force ) { rw::emitRaw( stderr, "ripwire: --force only applies to `ripwire wrap ` (proceed past CRITICAL skill findings) — pass it there instead (e.g. ripwire wrap claude --force)\n" ); c.ok = false; } // --run-timeout caps --run-trace's command and reaches nothing anywhere else; alone it would silently // no-op exactly like the modifiers around it. Refuse loudly, naming both flags. if( c.runTimeoutSec > 0 && c.runTrace.empty() ) { rw::emitRaw( stderr, "ripwire: --run-timeout=SECONDS modifies --run-trace — pass it too (e.g. ripwire --run-trace=\"make -j\" --run-timeout=60)\n" ); c.ok = false; } // capture-audit 2026-09-04 (M16): --naming-locals is a --lint MODIFIER (the naming-* rules pointed at local // variables; verbs_lint.h's mergeNamingLens is its only reader) and reaches nothing else. --help called it // "a no-op alone"; a documented no-op is still the accept-and-ignore class every sibling here refuses. if( c.namingLocals && !c.lint ) { rw::emitRaw( stderr, "ripwire: --naming-locals modifies --lint (the naming-* rules over local variables) — pass both (e.g. ripwire --lint --naming-locals)\n" ); c.ok = false; } // M16, the one modifier here that gets a NOTICE and not a refusal, by decision: --no-stable opts out of // the stable ordering --mcp/--listen turn on (parseArgs' tail) and is read nowhere else, so on the CLI it // changes nothing. test/guardmsgcheck.sh pins bare `--no-stable` and `--order=stable --no-stable` as // accepted CLI spellings and ~70 cache-gate invocations pass it bare — a refusal would break a documented // composition. One line on stderr is the honest floor: a caller can tell a no-op from a typo, and no // output byte moves. (--listen= sets c.mcp, so the server transports are both covered by the one test.) if( c.noStable && !c.mcp ) { rw::emitRaw( stderr, "ripwire: --no-stable is read only by --mcp/--listen (it opts out of the stable ordering the server turns on) — it changed nothing here; the CLI map orders important-first unless you pass --order=stable\n" ); } // capture-audit 2026-09-04 (H11): --allow-dirty is the explicit consent --quality-baseline needs before // it pins a floor on a tree that differs from HEAD. It is read at exactly one site (verbs_quality.h's // baseline arm) and reaches nothing else, so alone it is the accept-and-ignore class every modifier // around it refuses. Named with the flag it modifies, because a caller who typed it alone was reaching // for that verb. // idea #11: --show-stale restores the rows a regression-free --quality-delta collapses, and is read nowhere else. if( c.showStale && !c.qualityDelta ) { rw::emitRaw( stderr, "ripwire: --show-stale modifies --quality-delta (it prints the stale-ack rows a regression-free answer collapses) — pass both (e.g. ripwire --quality-delta --show-stale)\n" ); c.ok = false; } if( c.allowDirty && !c.qualityBaseline ) { rw::emitRaw( stderr, "ripwire: --allow-dirty modifies --quality-baseline (it consents to pinning a floor on a tree that differs from HEAD) — pass both (e.g. ripwire --quality-baseline --allow-dirty)\n" ); c.ok = false; } // --with-profile joins measured scope heat onto --lint findings and reaches nothing anywhere else; // alone it would silently no-op exactly like the modifiers around it. Refuse loudly. if( !c.withProfile.empty() && !c.lint ) { rw::emitRaw( stderr, "ripwire: --with-profile=FILE modifies --lint — pass it too (e.g. ripwire --lint --with-profile=report.txt)\n" ); c.ok = false; } validateSarifModifierGuards( c ); // --sarif's four companion guards, split out for the same reason // the rows above it are (see its own header) validateLintSelectionModifierGuards( c ); // --lint-select=/--lint-ignore='s companion guard, same reason // --with-history is the OPT-IN git-history name oracle for --doc-drift and --whereis (src/gitoracle.h) — // main.cpp's buildHistoryIndex() is only ever CALLED from those two verbs' dispatch, so the flag alone // reaches nothing. Alone it silently no-ops exactly like --anchor/--cochange-boost (validateConfig); refuse loudly. if( c.withHistory && !c.docDrift && !c.whereisFlag ) { rw::emitRaw( stderr, "ripwire: --with-history modifies --doc-drift or --whereis=SYM — pass one (e.g. ripwire --doc-drift --with-history)\n" ); c.ok = false; } // --grep-context=N (and its --grep-before=N/--grep-after=N components — all three set the SAME // grepBefore/grepAfter members, see parseArgs) only widens a --grep/--regex hit; alone it silently no-ops // (grepHits is only ever called inside the `!cfg.grep.empty()` branch, main.cpp). Refuse loudly. if( ( c.grepBefore > 0 || c.grepAfter > 0 ) && c.grep.empty() ) { rw::emitRaw( stderr, "ripwire: --grep-context=N (or --grep-before/--grep-after) modifies --grep=STR or --regex=PAT — pass one (e.g. ripwire --grep=STR --grep-context=3)\n" ); c.ok = false; } // --no-prefilter forces a full scan instead of the trigram prefilter — meaningful ONLY inside the same // `!cfg.grep.empty()` branch as --grep-context above. Alone it silently no-ops; refuse loudly. if( c.noPrefilter && c.grep.empty() ) { rw::emitRaw( stderr, "ripwire: --no-prefilter modifies --grep=STR or --regex=PAT — pass one (e.g. ripwire --grep=STR --no-prefilter)\n" ); c.ok = false; } // G3: --and=/--not=/--grep-scope= modify --grep=STR only — literal, not --regex=PAT (a flat substring // term list has no meaning against a regex's own alternation/anchoring, and ugrep's own CNF stays // regex-string-only for the same reason). Alone (no --grep) they would silently no-op like the // modifiers above; combined with --regex they would silently ignore the extra terms. Both refuse loudly. if( ( !c.grepAnd.empty() || !c.grepNot.empty() || !c.grepScope.empty() ) && c.grep.empty() ) { rw::emitRaw( stderr, "ripwire: --and=/--not=/--grep-scope= modify --grep=STR — pass it too (e.g. ripwire --grep=stale --and=mcp)\n" ); c.ok = false; } if( c.whereisFullText && !c.whereisFlag ) { rw::emitRaw( stderr, "ripwire: --whereis-full-text modifies --whereis=SYM — pass it too (e.g. ripwire --whereis=parseArgs --whereis-full-text)\n" ); c.ok = false; } if( !c.whereisListing.empty() && !c.whereisFlag ) { rw::emitRaw( stderr, "ripwire: --whereis-listing=defs|refs|all modifies --whereis=SYM — pass it too (e.g. ripwire --whereis=parseArgs --whereis-listing=all)\n" ); c.ok = false; } // R-H: --grep-in= is the one grep modifier that ALSO applies to --regex (a regex hit lands in a span // exactly like a literal one), so its refusal tests both spellings rather than --grep= alone. if( !c.grepIn.empty() && c.grep.empty() ) { rw::emitRaw( stderr, "ripwire: --grep-in=code|any modifies --grep=STR / --regex=PAT — pass one too (e.g. ripwire --grep=stale --grep-in=any)\n" ); c.ok = false; } if( ( !c.grepAnd.empty() || !c.grepNot.empty() ) && c.grepRegex ) { rw::emitRaw( stderr, "ripwire: --and=/--not= are literal-only and do not apply to --regex=PAT — use --grep=STR --and=... instead, or fold the term into the regex itself (e.g. --regex='A.*B')\n" ); c.ok = false; } // --with-graph splices a mermaid block into ONE bundle's closing — only --for and --pack-task ever // call packGraphBlock (main.cpp); --partition already warns-and-continues (N+1 bundles, no single graph to // splice into) rather than silently dropping it, so it is excluded here on purpose. Alone (no --for/ // --pack-task/--partition) it silently no-ops; refuse loudly. if( c.withGraph && c.forTask.empty() && !c.packTaskFlag && c.partitionCount <= 0 ) { rw::emitRaw( stderr, "ripwire: --with-graph modifies --for=TASK or --pack-task=TASK — pass one (e.g. ripwire --pack-task=\"task\" --with-graph)\n" ); c.ok = false; } // --since scopes --hotspots/--cochange/--rank-by=churn|churn-decay to commits after a point; every other // verb ignores it outright (main.cpp only reads cfg.since inside those paths). Alone it silently no-ops; // refuse loudly. P0-4: churn-decay joins the list — its DEFAULT walk is the whole history (the decay is // the window), and an explicit --since narrows that walk exactly as it narrows churn's. // card A4: --slice=SYM:VAR joins the list — there --since is not a churn WINDOW but the revision whose // def-use slice this one is diffed against (src/slicediff.h). Same flag, same two spellings, and the // same rule as every other pairing: a run where the flag would do nothing refuses instead. if( !c.since.empty() && !anySinceHostActive( c ) ) { rw::emitRaw( stderr, "ripwire: --since=REV|DATE scopes --hotspots/--cochange/--rank-by=churn|churn-decay, and beside --slice=SYM:VAR it names the revision to diff that variable's def-use slice against — pass one (e.g. ripwire --hotspots --since=\"1 week ago\")\n" ); c.ok = false; } // --in=DIR (C1-b, 2026-09-12) scopes a recent-changes BLOCK to one directory, and only a HOST that has such a // block can be scoped — kInHosts above is that list, so this reads the table instead of spelling one host by // hand. Same rule as --since: a run where the flag would do nothing refuses instead, naming the remedy. // // THE REFUSAL SET, in full, because --help and the CHANGELOG state exactly these and nothing more: // not a host (--rank-by is anything but churn-decay, or absent) // multi-root the block --in scopes is single-root only, so there is none to scope // --top-k=N ANY N, not only 0. Under --in the symbol map is a STUB, and --top-k sizes exactly the // rows the stub does not print — so the flag shapes nothing, whatever its value. It used // to be refused only at 0, and at 0 it was refused THREE times over (this arm, plus two // from validateShapingFlagsHonored, which --in has now left — see honorsPaging). // --json named by the --json allow-list walk (jsonUnsupportedVerb), not here. // NOT refused, and documented as composing: --limit/--offset (they window the scoped block — see // validatePagingHonored) and --max-tokens/--token-budget (they shape the document that IS emitted). // // A chain of `else if`, not three independent guards: one bad combination gets one message. The directory // itself is checked twice in main.cpp — against the filesystem (inDirIsUnderRoot, the cheap first reject) and // then against the CRAWL's own spellings, which is the only check that can tell DIR from a typo. if( !c.inDir.empty() ) { if( !inHostActive( c ) ) { // The sentence names the single host in kInHosts (inHostActive's static_assert pins the count). rw::emitTo( stderr, "ripwire: --in=DIR scopes the recent-changes block of {} to one directory — pass it " "(e.g. ripwire --rank-by=churn-decay --in=src)\n", kInHosts[0] ); c.ok = false; } else if( c.roots.size() >= 2 ) { rw::emitRaw( stderr, "ripwire: --in=DIR scopes a single-root map; the block it scopes is absent under multi-root — pass one root (e.g. ripwire --rank-by=churn-decay --in=src)\n" ); c.ok = false; } else if( c.topKExplicit ) { rw::emitRaw( stderr, "ripwire: --in=DIR stubs the symbol map, and --top-k=N sizes exactly the rows the stub does not print — drop one of them " "(e.g. ripwire --rank-by=churn-decay --in=src, or drop --in to size the map). --limit/--offset page the scoped block; " "--max-tokens/--token-budget shape the document that is emitted\n" ); c.ok = false; } } // --cochange-recur=K / --cochange-groups are read ONLY inside the --cochange branch of // runMaintenanceViews (main.cpp). Alone they silently no-op; refuse loudly, exactly like --since above. if( ( c.cochangeRecur > 0 || c.cochangeGroups ) && !c.cochange ) { rw::emitRaw( stderr, "ripwire: --cochange-recur=K and --cochange-groups modify --cochange — pass it (e.g. ripwire --cochange --cochange-recur=2)\n" ); c.ok = false; } // --cochange-groups covers the repo-wide VIOLATING-PAIR set; with --cochange=FILE there is one core file // by construction and the group form has nothing to group. Refusing beats emitting a one-file "group" // that looks like a finding — the honest reading is that the question is not defined for this form. if( c.cochangeGroups && !c.cochangeFile.empty() ) { rw::emitRaw( stderr, "ripwire: --cochange-groups groups the repo-wide violating pairs — it has nothing to group under --cochange=FILE, whose core file is already the one you named (e.g. ripwire --cochange --cochange-groups)\n" ); c.ok = false; } // --baseline/--baseline-update write/merge the `.ripwire_arch_baseline` sidecar — both are read only // inside the `!cfg.archRules.empty()` branch of runArchViews (main.cpp). Alone they silently no-op; refuse // loudly (mirrors --gateability/--abi/--plan's "rides on another verb's sweep" shape, validateConfig below). if( ( c.baseline || c.baselineUpdate ) && c.archRules.empty() ) { rw::emitRaw( stderr, "ripwire: --baseline/--baseline-update writes the --arch=FILE debt sidecar — pass both (e.g. ripwire --arch=rules.yaml --baseline)\n" ); c.ok = false; } // On the --for companion (the ONLY one where --detail is a genuine COUNT rather than a boolean "restore // the full listing" trigger — --owners/--doc-drift/--whereis/--stray-content/--flags all read // `cfg.detail != 0` as a bool, see the writeX(…, cfg.detail ? SIZE_MAX : kCap) call sites in main.cpp), // main.cpp:1622-1634 clamps the body count to std::min(detail, forTopN, corpusSize) with NO signal that a // larger request was truncated — the same "accepted, silently capped" failure --rank-by/--format/--order // avoid by refusing an out-of-range VALUE outright. forTopN (--pack-top-n=N, else 40) is knowable from the // flags alone, before ingest, so this can refuse here rather than clamp silently at dispatch time. if( !c.forTask.empty() ) { const int forTopN = c.packTopN > 0 ? c.packTopN : 40; if( c.detail > forTopN ) { rw::emitTo( stderr, "ripwire: --detail={} exceeds the ranked head — N must be 1..{} (raise the head with --pack-top-n=N, or lower --detail)\n", c.detail, forTopN ); c.ok = false; } } // --compress strips comments from body output — every call site is a body emitter: --expand/--outline // (serialize.h packBodies/packOutline), --for's SERVED bodies (the T3 auto/anchor bundle and --detail's // top-N, both inside the --for branch), --exemplar, --pack-task, and --from-trace (main.cpp // PackTaskInputs/FromTraceInputs). Alone (none of those) it silently no-ops — verified: `ripwire // --compress` is byte-identical to the plain map. Refuse loudly rather than let a caller believe they // compressed something. Bare --for is admitted whole, not only --detail>0 (paper-shape lane, arXiv // 2607.09691: served bodies are the tokens worth compressing): which route serves bodies is a RUN-time // fact, so on the compact (conceptual) route the flag has nothing to strip and no-ops, disclosed by the // absent compress= attribute (gate: test/forcompresscheck.sh, the stated residual). if( c.compress && c.expand.empty() && c.outline.empty() && !c.packTaskFlag && c.fromTrace.empty() && c.exemplar.empty() && c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --compress strips comments from served-body output (expand/outline/for/pack-task/from-trace/exemplar) — pass one (e.g. ripwire --expand=SYM --compress)\n" ); c.ok = false; } // --color-by bakes the initial node-colour mode of the --html page — writeHtml is its only reader. // Alone it silently no-ops; refuse loudly (same shape as --with-graph/--compress above). if( c.colorByExplicit && !c.html ) { rw::emitRaw( stderr, "ripwire: --color-by=MODE colors the --html export — pass both (e.g. ripwire --html=g.html --color-by=community)\n" ); c.ok = false; } } // The three --auto-bodies guards, lifted out of validateConfig, which is already one of the longest // functions in this file and grows by a stanza on every flag added. Same shape as the --signatures-only // pair it sits beside: --auto-bodies opts out of COMPACT conceptual serving, so ALONE it modifies // nothing, and it contradicts BOTH of the other body postures — honoring one of a contradictory pair // silently drops the other's effect with no tell, so the pair is refused loudly instead, each with the // distinction spelled out. It is a PERMANENT posture flag beside --signatures-only and --detail=N, not a // migration aid: a caller who wants inline bodies on conceptual queries stays supported indefinitely. inline void refuseAutoBodiesMisuse( Config& c ) { if( c.autoBodies && c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --auto-bodies modifies --for=TASK — pass both (e.g. ripwire --for=\"task\" --auto-bodies)\n" ); c.ok = false; } if( c.autoBodies && c.signaturesOnly ) { rw::emitRaw( stderr, "ripwire: --auto-bodies contradicts --signatures-only — pass one (--auto-bodies asks for the automatic bodies; --signatures-only means no bodies at all)\n" ); c.ok = false; } if( c.autoBodies && c.detail > 0 ) { rw::emitRaw( stderr, "ripwire: --auto-bodies contradicts --detail=N — pass one (--detail=N is the explicit body knob and already supersedes the automatic pick)\n" ); c.ok = false; } } inline void validateAgent( Config& c ) noexcept { if( !c.agent.empty() && !c.doctor ) { rw::emitRaw( stderr, "ripwire: --agent=codex modifies --doctor — pass both (e.g. ripwire --doctor --agent=codex)\n" ); c.ok = false; } if( !c.agent.empty() && c.agent != "codex" && c.agent != "claude" ) { rw::emitTo( stderr, "ripwire: unsupported --agent value '{}' (supported: codex, claude)\n", std::string_view( c.agent.data(), c.agent.size() ) ); c.ok = false; } } inline void validateConfig( Config& c ) noexcept { if( c.rootPath.empty() && !c.mcp && !c.lsp && !c.scanSkills && c.scanSkillFile.empty() ) // scan / --mcp / --lsp may run without a path { // #350 layer 1: run from a home or system directory, the missing root is the one thing to say — the usage // text would invite `ripwire .`, which from there is exactly the crawl nobody meant (rootguard.h). const std::string noRoot = noProjectRootReason( rootGuardCwd() ); if( noRoot.empty() ) { usage(); } else { rw::emitTo( stderr, "ripwire: {}\n", noRoot ); } c.ok = false; } // The remote HTTP transport pins ONE workspace fixed at startup, so --listen // needs a root on the command line (stdio --mcp does not — its clients name a path per request). if( !c.listen.empty() && c.rootPath.empty() ) { rw::emitRaw( stderr, "ripwire: --listen serves ONE workspace fixed at startup — pass the repo root (e.g. ripwire . --listen=127.0.0.1:8765)\n" ); c.ok = false; } validateAgent( c ); // H10 (capture-audit 2026-09-04): --quality-ack=REASON implies the --quality-delta report it acks. The // implication must be set BEFORE the modifier guards below: noticeShapingFlagIgnored reads c.qualityDelta // to find the verb a stray --top-k/--max-tokens/--token-budget was passed to, and with the implication // set only after it ran, `--quality-ack=why --top-k=1` was the one spelling in the universe that swallowed // a knob SILENTLY (shapingflagcheck (F), red at the wave-1 merge). The reason-less refusal stays below. if( c.qualityAck && !c.qualityAckReason.empty() ) { c.qualityDelta = true; } validateModifierGuards( c ); // §P8: the eleven new "(with X)" companion guards, split out above (see its header) // --anchor is a negative-result experiment (dropped from --help) — gated behind // RIPWIRE_DEV=1 so it stays reachable for continued eval work without advertising it as supported. if( c.anchor && !std::getenv( "RIPWIRE_DEV" ) ) { rw::emitRaw( stderr, "ripwire: --anchor is experimental, set RIPWIRE_DEV=1\n" ); c.ok = false; } // --anchor only modifies the --for lens rank; alone it would silently do nothing — refuse loudly instead. if( c.anchor && c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --anchor modifies --for=TASK — pass both (e.g. ripwire --for=\"task\" --anchor)\n" ); c.ok = false; } // --no-route forces plain subtoken+body on --for/--query (routing is the default); alone it does nothing — refuse loudly. if( c.noRoute && c.forTask.empty() && c.query.empty() ) { rw::emitRaw( stderr, "ripwire: --no-route modifies --for=TASK or --query=TERMS — pass one (e.g. ripwire --for=\"task\" --no-route)\n" ); c.ok = false; } // --adaptive cuts the --for/--query result set at the relevance cliff; alone it does nothing — refuse loudly. if( c.adaptive && c.forTask.empty() && c.query.empty() ) { rw::emitRaw( stderr, "ripwire: --adaptive modifies --for=TASK or --query=TERMS — pass one (e.g. ripwire --for=\"task\" --adaptive)\n" ); c.ok = false; } // --cochange-boost is a negative-result experiment (dropped from --help) — same // RIPWIRE_DEV=1 gate as --anchor. RIPWIRE_COCHANGE=1 (the separate MCP-facing env activation, // main.cpp) is untouched — it is not a --help-advertised flag. if( c.cochangeBoost && !std::getenv( "RIPWIRE_DEV" ) ) { rw::emitRaw( stderr, "ripwire: --cochange-boost is experimental, set RIPWIRE_DEV=1\n" ); c.ok = false; } // --cochange-boost only augments the --for lens; alone it would silently do nothing — refuse loudly. if( c.cochangeBoost && c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --cochange-boost modifies --for=TASK — pass both (e.g. ripwire --for=\"task\" --cochange-boost)\n" ); c.ok = false; } // --no-mention-boost only disables a --for lens behavior; alone it would silently do nothing — refuse loudly. if( c.noMentionBoost && c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --no-mention-boost modifies --for=TASK — pass both (e.g. ripwire --for=\"task\" --no-mention-boost)\n" ); c.ok = false; } // --no-doc-mention only disables a --for lens behavior; alone it would silently do nothing — refuse loudly. // (Same shape/scope as --no-mention-boost above, incl. the same --pack-task-only gap: computeLensRanking // also honors this flag when reached via --pack-task, but the loud-refuse check only reads --for=TASK — // consistent with the pre-existing --no-mention-boost/--cochange-boost validation, not a new gap.) if( c.noDocMention && c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --no-doc-mention modifies --for=TASK — pass both (e.g. ripwire --for=\"task\" --no-doc-mention)\n" ); c.ok = false; } // --signatures-only opts out of --for's terminal-by-default bundle (T3); alone it does nothing — refuse loudly. if( c.signaturesOnly && c.forTask.empty() ) { rw::emitRaw( stderr, "ripwire: --signatures-only modifies --for=TASK — pass both (e.g. ripwire --for=\"task\" --signatures-only)\n" ); c.ok = false; } // --signatures-only ("no bodies") and --detail=N ("these bodies, explicitly") contradict each other — // honoring one silently drops the other's effect with no tell, so the pair is refused loudly instead. if( c.signaturesOnly && c.detail > 0 ) { rw::emitRaw( stderr, "ripwire: --signatures-only contradicts --detail=N — pass one (--detail=N is the explicit body knob; --signatures-only means no bodies at all)\n" ); c.ok = false; } refuseAutoBodiesMisuse( c ); // the three --auto-bodies guards, out of line (see above validateConfig) // L-W (forpage.h): `--for --limit/--offset` is the FILE PAGE, a document of its own with no bundle to shape — // every bundle-shaping flag beside it would be accepted-and-ignored, the named failure family this file // refuses everywhere else (§H4). Named one at a time, so the remedy is the flag to drop. --top-k, // --max-tokens and --token-budget are refused by validateShapingFlagsHonored (the page is a paging member). // #294 review (verbs_for.h:3824): --pack-task beside a budgeted window serves the CANDIDATE page, // and the candidate page (like the file page) is a fixed / shape — bundle-shaping flags // would be accepted-and-ignored there too. Both pages refuse them; the message names the page that // was selected, so the remedy (drop the flag, or the window) reads correctly. const bool forFilePageSelected = !c.forTask.empty() && c.tokenBudget == 0 && ( c.pageLimit > 0 || c.pageOffset > 0 ); const bool forCandidateSelected = ( ( !c.forTask.empty() || c.packTaskFlag ) && c.tokenBudget != 0 && ( c.pageLimit > 0 || c.pageOffset > 0 ) ); if( forFilePageSelected || forCandidateSelected ) { const char* const pageName = forFilePageSelected ? "--for --limit/--offset is the file-grain widening page (one row per file, its own document)" : "--for/--pack-task --token-budget with --limit/--offset is the budgeted-bundle candidate page (one fixed window, its own resumable document)"; struct PageShapeFlag { const char* name; bool set; }; const PageShapeFlag shapeFlags[] = { { "--json", c.json }, { "--format=candidates", c.candidates }, { "--detail=N", c.detail > 0 }, { "--signatures-only", c.signaturesOnly }, { "--auto-bodies", c.autoBodies }, { "--adaptive", c.adaptive }, { "--with-graph", c.withGraph }, { "--compress", c.compress }, { "--pack-top-n=N", c.packTopN > 0 }, { "--anchor", c.anchor }, }; for( const PageShapeFlag& f : shapeFlags ) { if( f.set ) { rw::emitTo( stderr, "ripwire: {} — it has no bundle for {} to shape, so the flag is refused rather than ignored: drop {} for the page, or drop the window for the bundle\n", pageName, f.name, f.name ); // 3 placeholders, 3 args (the #362 review caught a 4th) c.ok = false; } } } // §P6.4: --owners is ALSO a legal --detail=N companion (restores the full per-file listing instead of // the collapse) — stacked as its own `if` rather than folded into the && chain below so this // is a pure ADDITION: that chain was edited by unrelated work inside quality-delta's short-horizon-churn // window, and appending `&& !c.owners` to it would touch that hot line and misclassify this correct, // unrelated addition as thrash. `if( A ) if( B )` short-circuits identically to `if( A && B )` (no dangling // else below to worry about) — the line it guards is otherwise completely unmodified. if( !c.owners ) { // --detail=N (RESEARCH lever 3) folds full bodies onto the --for lens; alone it does nothing — refuse loudly. // The cross-branch verbs (--stray-content/--whereis) reuse it for the SAME meaning — "lift the display cap, show the // rows the ranked head elided" — so they join --for as a legal companion rather than growing a second // spelling of "show me more". --flags/--flip belongs in that list for the same reason and always did: // its handler has read cfg.detail since it shipped (the per-gate site cap), but the guard here never // admitted it, so that branch was unreachable and `--flags --detail=N` refused instead of widening. if( c.detail > 0 && c.forTask.empty() && !c.strayContent && !c.whereisFlag && !c.docDrift && !c.darkFlags ) { rw::emitRaw( stderr, "ripwire: --detail=N modifies --for=TASK — pass both (e.g. ripwire --for=\"task\" --detail=3)\n" ); c.ok = false; } } // --partition=N SPLITS a --pack-task bundle; there is nothing else in the tool it could // split, so alone it would silently no-op on the default map. Refuse loudly (mirrors --detail/--adaptive), // and bound N in the same breath: 1 is just --pack-task, and past kMaxPartitions=16 an orchestrator is // doing something other than a fan-out (the same cap --connect and multi-root use). if( c.partitionCount > 0 && !c.packTaskFlag ) { rw::emitRaw( stderr, "ripwire: --partition=N splits a --pack-task bundle — pass both (e.g. ripwire --pack-task=\"task\" --partition=4)\n" ); c.ok = false; } if( c.partitionCount > 0 && ( c.partitionCount < 2 || c.partitionCount > 16 ) ) { rw::emitTo( stderr, "ripwire: --partition={} is out of range — N must be 2..16 (1 is just --pack-task)\n", c.partitionCount ); c.ok = false; } validatePlanLanes( c ); // the 6 --plan-lanes/--task/--brief guards, split out above (see its header) // --flip=NAME reports the blast radius of ONE gate from the --flags gate table; there is no other verb // in the tool that produces one, so alone it would silently no-op on the default map. Refuse loudly // (mirrors --detail/--partition), and refuse the BARE flag in the same breath — "which gate?" has no // sensible default, and an empty-looking success is the failure mode this verb exists to prevent. if( c.flipFlag && !c.darkFlags ) { rw::emitRaw( stderr, "ripwire: --flip=NAME reports one gate from the --flags table — pass both (e.g. ripwire --flags --flip=CANYON_HARMONY_SFX)\n" ); c.ok = false; } if( c.flipFlag && c.flipGate.empty() ) { rw::emitRaw( stderr, "ripwire: --flip needs a gate name (e.g. --flip=CANYON_HARMONY_SFX) — run `ripwire --flags` to list them\n" ); c.ok = false; } // --plan composes --stray-content's sweep with --merge-scout's overlap oracle; there is nothing else in // the tool it could compose, so alone it would silently no-op on the default map. Refuse loudly (mirrors // --flip/--partition). if( c.landingPlan && !c.strayContent ) { rw::emitRaw( stderr, "ripwire: --plan composes with --stray-content's sweep — pass both (e.g. ripwire --stray-content --plan)\n" ); c.ok = false; } // --abi is the cross-branch ABI-BREAK gate: modelling a struct off ANOTHER ref's blob only makes sense // alongside the ref sweep that finds those blobs, so alone it would silently no-op on the default map. // Refuse loudly (mirrors --flip/--partition/--detail above) rather than let it look like a no-op success. if( c.abiFlag && !c.strayContent ) { rw::emitRaw( stderr, "ripwire: --abi reports the cross-branch ABI-break gate over the --stray-content ref sweep — pass both (e.g. ripwire --stray-content --abi)\n" ); c.ok = false; } // --gateability (r26-stamp Task B) composes with --doc-drift's own report — alone it would silently no-op // on the default map. Refuse loudly (mirrors --plan/--abi immediately above). if( c.gateabilityFlag && !c.docDrift ) { rw::emitRaw( stderr, "ripwire: --gateability reports over --doc-drift's own scan — pass both (e.g. ripwire --doc-drift --gateability)\n" ); c.ok = false; } // --slice-flow (lane/or-arise rung 2) modifies --slice=SYM:VAR only — alone it would silently no-op on // the plain map. Refuse loudly (mirrors --gateability/--abi immediately above), and refuse an unknown // direction with the closed value set (the --grep-scope= shape). The "needs a seed VAR, not the bare // inventory" half lives in runSlice, after the spec split that discovers whether a VAR was given. if( !c.sliceFlow.empty() && c.sliceFlow != "back" && c.sliceFlow != "fwd" && c.sliceFlow != "both" ) { rw::emitTo( stderr, "ripwire: --slice-flow={} — unknown direction (supported: back|fwd|both), e.g. --slice-flow=back\n", std::string_view( c.sliceFlow.data(), c.sliceFlow.size() ) ); c.ok = false; } if( !c.sliceFlow.empty() && c.sliceSpec.empty() ) { rw::emitRaw( stderr, "ripwire: --slice-flow modifies --slice=SYM:VAR — pass both (e.g. ripwire --slice=parseArgs:argIndex --slice-flow=back)\n" ); c.ok = false; } if( c.sliceDepth != 0 && c.sliceFlow.empty() ) { rw::emitRaw( stderr, "ripwire: --slice-depth bounds the --slice-flow BFS — pass both (e.g. ripwire --slice=parseArgs:argIndex --slice-flow=fwd --slice-depth=4)\n" ); c.ok = false; } // H10 (capture-audit 2026-09-04): bare --quality-ack was the ONE modifier that WRITES when alone — it // implied --quality-delta, acked "0 finding(s)" at exit 0 and re-serialised .ripwire_quality_acks, while // its own --ack-only refuses bare. The reason-carrying spelling keeps implying the report it acks (the // documented form: `--quality-ack="why"` names its own accountability); the reason-less spellings // (`--quality-ack`, `--quality-ack=`) need an explicit --quality-delta beside them, like --ack-only and // --scope below. The implication is set above validateModifierGuards (not in the parser arm), so the // knob notice sees the implied verb. if( c.qualityAck && !c.qualityDelta ) { rw::emitRaw( stderr, "ripwire: bare --quality-ack accepts EVERY finding of a --quality-delta report with no reason recorded — pass --quality-delta with it, and say why (e.g. ripwire --quality-delta --quality-ack=\"why this debt is deliberate\")\n" ); c.ok = false; } // --ack-only=SUBSTR narrows WHICH findings --quality-ack accepts; without --quality-ack there is nothing // to narrow, so alone it would silently no-op on the plain map — exit 0, print the ordinary default map, // stderr empty. That is the exact failure --ack-only exists to prevent: a typo'd narrowing (or a bare // invocation the operator believes narrowed something) must never look like a quiet success. Refuse // loudly (mirrors --gateability/--abi/--plan immediately above), naming both flags. if( !c.qualityAckOnly.empty() && !c.qualityAck ) { rw::emitRaw( stderr, "ripwire: --ack-only=SUBSTR narrows --quality-ack — pass both (e.g. ripwire --quality-delta --ack-only=contract-change --quality-ack=\"reason\")\n" ); c.ok = false; } // P1 — --scope=GLOB partitions --quality-delta's findings by ownership, and NOTHING else in the tool // reads it. Alone it would silently no-op on the plain map (exit 0, the ordinary atlas, stderr empty), // which on THIS flag is the worst available failure: the caller's belief is "my report is scoped to my // subtree", and what they got is scoped to nothing at all. Refuse loudly, naming both flags — the same // ruling --ack-only carries immediately above, for the same class of mistake. (The scope's own GRAMMAR // is validated in the verb handler, not here: cli.h is a leaf that includes only ingest.h, and the // vocabulary belongs to quality.h — the same line --quality-panel=PRESET's refusal draws.) if( !c.qualityScope.empty() && !c.qualityDelta ) { rw::emitRaw( stderr, "ripwire: --scope=GLOB partitions --quality-delta by ownership — pass both (e.g. ripwire --quality-delta --scope=src/quality.h)\n" ); c.ok = false; } // --format=candidates is a flat top-K export of a RANKED set — only --for/--query produce one; alone it // would silently no-op on the plain map. Refuse loudly (mirrors --adaptive/--detail). if( c.candidates && c.forTask.empty() && c.query.empty() ) { rw::emitRaw( stderr, "ripwire: --format=candidates exports a --for=TASK or --query=TERMS result — pass one (e.g. ripwire --query=\"terms\" --format=candidates)\n" ); c.ok = false; } // r27-emitters T2: --top-k=0 = "payload only, no ranked map". It is meaningful ONLY when some other flag // supplies the payload; alone it would emit nothing at all, and on a set-returning verb like --graph-query // a 0 would fall into that verb's legacy `topK > 0 ? cap : ALL` arm and dump the whole matched set. Confine // it to the four payload verbs and refuse everywhere else, naming the fix. // // §L10b LOW tail: --recall's OWN help text says --top-k=N "shapes HOW MANY docs are emitted" — a doc // count, never the ranked-map rows the generic T2 wording below promises. The generic refusal used to // fire on `--recall --top-k=0` too and told the reader "no ranked map, payload only", which is a category // error for a verb that never had a ranked map to begin with. Same refusal (0 is still meaningless: it // asks to recall zero documents), wording matched to what --top-k actually means on this verb. if( c.topK == 0 && !c.recall.empty() ) { rw::emitRaw( stderr, "ripwire: --recall --top-k=0 means \"emit zero documents\" — raise it (--top-k=N) or drop it for the default of 8\n" ); c.ok = false; } // C1-b: --in=DIR answers the whole --top-k question in ONE message of its own (validateModifierGuards), so // this generic arm stays quiet beside it — two refusals for one mistake is the shape the review named. else if( c.topK == 0 && c.inDir.empty() && c.expand.empty() && c.outline.empty() && !c.packSignatures && c.packTopN <= 0 ) { rw::emitRaw( stderr, "ripwire: --top-k=0 means \"no ranked map, payload only\" — pass a payload verb (--expand=SYM / --outline=SYM / --pack-signatures / --pack-top-n=N), or use --top-k=1 for the smallest map\n" ); c.ok = false; } } inline Config parseArgs( int argc, char** argv ) noexcept { Config c; // --stable/--most-important-last/--no-auto-order are hidden aliases of --order= now — // still work, dropped from --help, warn ONCE per run (not once per flag) pointing at the replacement. bool orderDeprecWarned = false; auto deprecatedOrderFlag = [&]( const char* oldFlag, const char* newValue ) noexcept { if( orderDeprecWarned ) { return; } orderDeprecWarned = true; rw::emitTo( stderr, "ripwire: {} is deprecated — use --order={} instead\n", oldFlag, newValue ); }; // --readability is a hidden alias of --biggest-first now — same shape as the --order= aliases just // above: still works, dropped from --help, warns ONCE per run pointing at the replacement. Only stderr // carries the notice; --biggest-first and --readability must print byte-identical stdout (readabilitycheck.sh). bool readabilityDeprecWarned = false; auto deprecatedReadabilityFlag = [&]() noexcept { if( readabilityDeprecWarned ) { return; } readabilityDeprecWarned = true; rw::emitTo( stderr, "ripwire: --readability is deprecated — use --biggest-first instead\n" ); }; for( int i = 1; i < argc; ++i ) { const std::string_view a = argv[i]; // argv strings are NUL-terminated // self-doc; first instinct must not error. Bare --help is TIER 1 (one line per row); --help=X // is tier 2 — the whole entry for one flag, one section, or `all` for the entire catalog. if( a == "--help" || a == "-h" ) { printUsageTier( stdout, HelpTier::Concise, {} ); std::exit( 0 ); } if( a.starts_with( "--help=" ) ) { serveHelpSelector( a.substr( 7 ) ); } // never returns // --version — one line, exit 0. Version + compiler come from the SAME generated // version.h --help's "determinism" line points at (single source: project(ripwire VERSION ...) // in CMakeLists.txt), so this can never drift from the CMake version test/versioncheck.sh checks. if( a == "--version" || a == "-v" ) { // §L10b LOW tail: this sha is the commit the BINARY was compiled from, the same fact // --doctor's own built_from= names (verbs_doctor.h; byte-identical, test/doctorcheck.sh arm // H) — labelled the same way here rather than left as a bare "git " a reader could // mistake for the tree's current HEAD (that is --doctor's separate at=, which moves the // moment you commit without rebuilding; this one does not, until the next build). // emit= names the formatted-output path this binary compiled in (infra/emit.h; test/versioncheck.sh // #6, and asserted per CI leg). It precedes built_from= on purpose: test/doctorcheck.sh arm (H) // reads built_from= as everything up to the closing paren, so the sha stays the LAST token. rw::emitTo( stdout, "ripwire {} ({}, {} {}, emit={}, built_from={})\n", kRipwireVersion, kRipwireBuildType, kRipwireCompilerId, kRipwireCompilerVer, rw::kEmitterName, kRipwireGitStamp ); std::exit( 0 ); } if( startsWith( a, "--" ) ) { // ── the table scan (kBoolFlags / kViewFlags / kIntFlags) ─────────────────────────────── // 132 of the 149 `--` arms are exactly "set one member" (plus, for kViewFlags/kIntFlags rows, a // companion bool or two) and live in the tables above. They are // matched here, in declaration order, before the hand-written arms below; a hit `continue`s to // the next argv element so the chain underneath is reached only by the arms a table cannot hold. bool isTableFlag = false; for( const BoolFlag& bf : kBoolFlags ) { if( a == bf.lit ) { c.*bf.member = true; isTableFlag = true; break; } } if( !isTableFlag ) { const ViewFlagMatch vm = applyViewFlag( a, c ); // §A9 V1-4: also owns the empty-value refusal if( vm == ViewFlagMatch::Refused ) { c.ok = false; return c; } isTableFlag = ( vm == ViewFlagMatch::Assigned ); } if( !isTableFlag ) { const IntFlagMatch im = applyIntFlag( a, c ); // §B8.2: owns the bad-value refusal for `--x=N` if( im == IntFlagMatch::Refused ) { c.ok = false; return c; } isTableFlag = ( im == IntFlagMatch::Assigned ); } if( isTableFlag ) { continue; } if( startsWith( a, "--order=" ) ) { const std::string_view v = a.substr( 8 ); if( v == "stable" ) { c.stable = true; } else if( v == "important-last" ) { c.mostImportantLast = true; } else if( v == "important-first" ) { c.noAutoOrder = true; } else { rw::emitTo( stderr, "ripwire: --order: unknown value '{}' (supported: stable|important-first|important-last)\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } } else if( a == "--most-important-last" ) { deprecatedOrderFlag( "--most-important-last", "important-last" ); c.mostImportantLast = true; } else if( a == "--stable" ) { deprecatedOrderFlag( "--stable", "stable" ); c.stable = true; } else if( a == "--no-auto-order" ) { deprecatedOrderFlag( "--no-auto-order", "important-first" ); c.noAutoOrder = true; } else if( a == "--readability" ) { deprecatedReadabilityFlag(); c.readability = true; } // §B8.2 verifier finding N4 (W2FIX-CLI): reuses parseByteSize's N[K|M|G] grammar (K is the // practical case; M/G come free) — a std::size_t BYTE COUNT, so this stays hand-written for the // same reason as --pack-budget-bytes (an `int Config::*` table row would narrow the accepted // range). Only the REFUSAL sentence moves onto the shared dialect; the accept side is untouched. else if( startsWith( a, "--token-budget=" ) ) { if( !parseByteSize( a.data() + 15, c.tokenBudget ) ) { refuseFlagValue( "--token-budget", "a positive token count, plain or with a K/M/G suffix", a.data() + 15, "--token-budget=16000" ); c.ok = false; return c; } } else if( startsWith( a, "--limit=" ) ) { if( !refusePageValue( "--limit", a.data() + 8, /*isZeroAllowed=*/false, c.pageLimit ) ) { c.ok = false; return c; } } else if( startsWith( a, "--offset=" ) ) { if( !refusePageValue( "--offset", a.data() + 9, /*isZeroAllowed=*/true, c.pageOffset ) ) { c.ok = false; return c; } } // §B8.2: --pack-budget-bytes stays hand-written where its nine numeric siblings moved into // kIntFlags — its member is a u64 BYTE COUNT, and an `int Config::*` table row could only hold // it by narrowing the accepted range (a --pack-budget-bytes=5000000000 that parses today would // start refusing). It shares the refusal, which is the half that had drifted. else if( startsWith( a, "--pack-budget-bytes=" ) ) { if( !parsePosU64( a.data() + 20, c.packBudgetBytes ) ) { refuseFlagValue( "--pack-budget-bytes", "a positive integer", a.data() + 20, "--pack-budget-bytes=32768" ); c.ok = false; return c; } rw::emitRaw( stderr, "ripwire: --pack-budget-bytes is deprecated — use --pack-task/--detail instead (unchanged behavior for now)\n" ); } // §B8.2 verifier finding N4 (W2FIX-CLI): same std::size_t-byte-count reasoning as --token-budget // above — stays hand-written, refusal only routed onto the shared sentence. else if( startsWith( a, "--max-file-size=" ) ) { if( !parseByteSize( a.data() + 16, c.maxFileBytes ) ) { refuseFlagValue( "--max-file-size", "a positive byte size, plain or with a K/M/G suffix", a.data() + 16, "--max-file-size=10MB" ); c.ok = false; return c; } } else if( startsWith( a, "--max-memory=" ) ) // #350: same std::size_t byte-count reasoning; the floor is the guard's { if( !parseMemoryLimit( a.data() + 13, c.maxMemoryBytes ) ) { refuseFlagValue( "--max-memory", "a byte size of at least 64M, plain or with a K/M/G suffix", a.data() + 13, "--max-memory=8G" ); c.ok = false; return c; } } else if( startsWith( a, "--exclude=" ) ) { // M6: the one hand-written value arm that accepted an empty value silently — `--exclude=$X` // with an unset $X excluded nothing and said nothing. Same refusal as its table siblings. if( a.size() == 10 ) { refuseEmptyValue( "--exclude=", "a path substring to drop from the crawl", "--exclude=vendor/" ); c.ok = false; return c; } // Windows intake (D3 fix round): hand-written, so it does not ride applyViewFlag's kViewFlags loop — // called explicitly, same as every kPathValuePrefixes row. POSIX: normalizePathValueAtIntake is empty. normalizePathValueAtIntake( "--exclude=", a.substr( 10 ) ); c.excludes.push_back( std::string( a.substr( 10 ) ) ); // r27-emitters T5: a BAD VALUE is not an unknown FLAG. `--rank-by=bogus` used to fall through the // exact-match chain to the generic "unknown flag" arm, which told the agent the flag itself does not // exist — a fabrication the agent then believes. `--order=`/`--export=` already name the value and // list the supported set; these two now do the same. } // G3: repeatable, so a kViewFlags row (one member per flag) cannot hold it — same shape as // --exclude= above. An empty value is refused here rather than silently pushing "" (a term that // is a substring of everything would make --and= vacuous and --not= reject every hit). else if( startsWith( a, "--and=" ) ) { if( a.size() == 6 ) { refuseEmptyValue( "--and=", "a literal string that must ALSO be present", "--and='mcp'" ); c.ok = false; return c; } c.grepAnd.push_back( a.substr( 6 ) ); } else if( startsWith( a, "--not=" ) ) { if( a.size() == 6 ) { refuseEmptyValue( "--not=", "a literal string that must be ABSENT", "--not='deprecated'" ); c.ok = false; return c; } c.grepNot.push_back( a.substr( 6 ) ); } else if( startsWith( a, "--grep-scope=" ) ) { const std::string_view v = a.substr( 13 ); if( v != "line" && v != "file" ) { rw::emitTo( stderr, "ripwire: --grep-scope={} — unknown value (supported: line|file), e.g. --grep-scope=file\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } c.grepScope = v; } else if( startsWith( a, "--mcp-legend=" ) ) { // A closed value set, refused on an unknown value (the --whereis-listing= rule just below). const std::string_view v = a.substr( 13 ); if( v != "session" && v != "inline" ) { rw::emitTo( stderr, "ripwire: --mcp-legend={} — unknown value (supported: session|inline), e.g. --mcp-legend=inline\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } c.mcpLegend = v; } else if( startsWith( a, "--whereis-listing=" ) ) { // A closed value set, refused on an unknown value (the --grep-in= rule): a typo must not quietly read // as the default listing and hide the rows the caller asked for. const std::string_view v = a.substr( 18 ); if( v != "defs" && v != "refs" && v != "all" ) { rw::emitTo( stderr, "ripwire: --whereis-listing={} — unknown value (supported: defs|refs|all), e.g. --whereis-listing=all\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } c.whereisListing = v; } else if( startsWith( a, "--grep-in=" ) ) { // R-H span tiers. Same shape as --grep-scope= above (closed value set, refuse an unknown // value rather than silently defaulting) — a typo here would otherwise read as "code" and // quietly suppress the very rows the user asked to see. const std::string_view v = a.substr( 10 ); if( v != "code" && v != "any" ) { rw::emitTo( stderr, "ripwire: --grep-in={} — unknown value (supported: code|any), e.g. --grep-in=any\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } c.grepIn = v; } else if( startsWith( a, "--rank-by=" ) ) { const std::string_view v = a.substr( 10 ); if( v == "pagerank" ) { c.rankBy = RankBy::PageRank; } else if( v == "authority" ) { c.rankBy = RankBy::Authority; } else if( v == "hub" ) { c.rankBy = RankBy::Hub; } else if( v == "rrf" ) { c.rankBy = RankBy::Rrf; } else if( v == "churn" ) { c.rankBy = RankBy::Churn; } else if( v == "churn-decay" ) { c.rankBy = RankBy::ChurnDecay; // P0-4: the same prior, with each commit weighted 0.5^(age/90d) } else { rw::emitTo( stderr, "ripwire: --rank-by: unknown value '{}' (supported: pagerank|authority|hub|rrf|churn|churn-decay)\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } } else if( startsWith( a, "--color-by=" ) ) { const std::string_view v = a.substr( 11 ); if( v == "lang" ) { c.colorBy = ColorBy::Lang; // explicit lang still requires --html (the modifier guard below) } else if( v == "community" ) { c.colorBy = ColorBy::Community; } else if( v == "cx" ) { c.colorBy = ColorBy::Cx; } else if( v == "churn" ) { c.colorBy = ColorBy::Churn; } else if( v == "tested" ) { c.colorBy = ColorBy::Tested; } else { // An empty value lands here too, on purpose: `--color-by=` is a bad VALUE, not an unknown // FLAG, and the refusal must say which (r27-emitters T5). rw::emitTo( stderr, "ripwire: --color-by: unknown value '{}' (supported: lang|community|cx|churn|tested)\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } // Set ONCE, past the refusal's early return: a mode added above cannot forget it, which is // exactly the way the --html-required guard would go silently dark. c.colorByExplicit = true; } else if( startsWith( a, "--format=" ) ) { const std::string_view v = a.substr( 9 ); if( v == "columnar" ) { c.columnar = true; } else if( v == "rows" ) { c.columnar = true; // alias } else if( v == "xml" ) { c.columnar = false; // explicit default (byte-identical) } else if( v == "candidates" ) { c.candidates = true; // R6: flat top-K export for external rerankers } else { rw::emitTo( stderr, "ripwire: --format: unknown value '{}' (supported: xml|columnar|rows|candidates)\n", std::string_view( v.data(), v.size() ) ); c.ok = false; return c; } } // §A9 V1-4 / §B5: --expand and --outline stay hand-written because they SPLIT A COMMA LIST into a // vector — the one shape kViewFlags cannot hold (--regex= moved into it once the table // grew an isSetFlag column). Both call the SAME refuseEmptyValue rather than growing a second // dialect of it. --outline= was the FOURTH §B5 arm: it had the split and not the refusal, so // `--outline=` emitted the whole default map at exit 0 while its identical sibling --expand= // refused, eleven lines up. else if( a == "--route" ) { /* routing is now the DEFAULT — accept for back-compat, no-op */ } else if( startsWith( a, "--expand=" ) ) { const std::string_view v = a.substr( 9 ); if( v.empty() ) { refuseEmptyValue( "--expand=", "one or more symbol names, comma-separated", "--expand=parseArgs" ); c.ok = false; return c; } for( std::size_t start = 0; start < v.size(); ) { std::size_t comma = v.find( ',', start ); if( comma == std::string_view::npos ) { comma = v.size(); } if( comma > start ) { c.expand.push_back( std::string( v.substr( start, comma - start ) ) ); } start = comma + 1; } } else if( startsWith( a, "--outline=" ) ) { const std::string_view v = a.substr( 10 ); if( v.empty() ) { refuseEmptyValue( "--outline=", "one or more symbol names, comma-separated", "--outline=parseArgs" ); c.ok = false; return c; } for( std::size_t start = 0; start < v.size(); ) { std::size_t comma = v.find( ',', start ); if( comma == std::string_view::npos ) { comma = v.size(); } if( comma > start ) { c.outline.push_back( std::string( v.substr( start, comma - start ) ) ); } start = comma + 1; } } // H10 (capture-audit 2026-09-04): the bare, reason-less spelling no longer IMPLIES --quality-delta — // it used to, and so alone it acked "0 finding(s)" at exit 0 and rewrote the ledger. validateConfig // refuses it without an explicit --quality-delta; --quality-ack=REASON (the kViewFlags row) still // implies the report it acks. else if( a == "--quality-ack" ) { c.qualityAck = true; } else if( startsWith( a, "--export=" ) ) { // --export=cc.json or --export=cc.json:FILE (mirror --html's FILE-or-stdout convention). std::string_view v = a.substr( 9 ); std::string_view fmt = v; std::string_view file; if( const std::size_t colon = v.find( ':' ); colon != std::string_view::npos ) { fmt = v.substr( 0, colon ); file = v.substr( colon + 1 ); } if( fmt == "cc.json" || fmt == "ccjson" ) { c.exportCcJson = true; c.exportFile = file; } else { rw::emitTo( stderr, "ripwire: --export: unknown format '{}' (supported: cc.json)\n", std::string_view( fmt.data(), fmt.size() ) ); c.ok = false; return c; } } else { rw::emitTo( stderr, "ripwire: unknown flag '{}'\n", std::string_view( a.data(), a.size() ) ); c.ok = false; return c; } } else { // every non-flag positional is a crawl root: one = today's behavior // verbatim; 2..kMaxWorkspaceRoots = a multi-root workspace merged into ONE graph. if( c.roots.size() >= kMaxWorkspaceRoots ) { rw::emitTo( stderr, "ripwire: too many roots (max {}): '{}'\n", kMaxWorkspaceRoots, std::string_view( a.data(), a.size() ) ); c.ok = false; return c; } os::normalize_path_arg( const_cast( a.data() ) ); // intake: a root takes the program's path spelling once if( c.rootPath.empty() ) { c.rootPath = a; // roots[0] alias (A1) } c.roots.push_back( a ); } } // P2-C: MCP callers benefit most from a stable, KV-cache-friendly prefix and shouldn't have to remember // the flag — so --mcp turns --stable ON by default, opt out with --no-stable. This is a DEFAULT, not a // validation: it must stay on THIS side of the validateConfig boundary (see that function's header). if( c.mcp && !c.noStable ) { c.stable = true; } validateConfig( c ); return c; } } // namespace rw