Ripwire Quality Bar

The quality-bar convergence loop

Routing: • PR-submission readiness — tests to run, blast radius, "safe to merge?" → ripwire-change-check — run --quality-delta FIRST, then its --test-gate: clean code that runs the wrong tests still regresses. • Reusing before you write the code in the first place → ripwire-reuse-first. • Wide-angle "where does this still look rotten" read across a whole file/subsystem (not a before/after delta) → the panel below, or ripwire-fresh-eyes for the full six-family breakdown. • You have the measurement and need the FIX — for your own diff or for a subsystem ripwire-fresh-eyes just measured → the shape → refactor playbook, the closed fix loop and the debt fix loop are all on this page, below. • The regression is a MEMORY-layout hypothesis, not one of the 11 quality kinds — --lint's built-in cache-* pack (8 static data-layout checks) is a normal part of a lint pass; --field-affinity[=STRUCT] is the deeper struct-level lens once a profile implicates a specific aggregate → ripwire-perf-target. • Not sure which skill? → ripwire-router.

Don't eyeball quality — measure the delta your change introduced, with a deterministic oracle, in a bounded loop. A file that was already complex is not your regression.

Apply the "non-trivial work" trigger to the LOOP, not the check. --quality-delta warm-runs in well under a second — cheaper than deciding by eye whether a fix "counts" as trivial, and that eyeball judgment is precisely where a leaf-looking edit that quietly changed a signature or added a branch slips through unmeasured. Run it. What a single-line leaf fix that preserves the signature and adds no branch, symbol, dependency, or abstraction gets to skip is everything AFTER a clean run: the drill-down table, --dmm, acking, a second round. This skill (and this file) earns its cost when the one-shot delta actually reports something — a clean gating="0" run on a leaf fix is confirmation, not ceremony you were right to skip.

Before you converge: the wide-angle read — --quality-panel

ripwire <dir> --quality-panel[=strict|default|lenient] --legend=compact is THE SINGLE COMMAND for "does what I just touched still look rotten" — one ranked report over six evidence families (the four --ensemble joins — structural, lexical, confusion, historical — plus colocation and state; the full per-family breakdown lives in ripwire-fresh-eyes). Point it at the file or symbol you just edited for a multi-angle second opinion the single --quality-delta number can't give you on its own.

Read it correctly: it is a lens, never a gate. --help says so in the flag's own text and the contract is enforced in code — --quality-panel exits 0 unconditionally, on every preset, on every repo. It does not compare against a baseline and it cannot fail a commit. The gate for "did MY change make this WORSE" is Step 3 below (--quality-delta) — that is the only pass in this skill (or in ripwire) with an exit code that means something. Run --quality-panel for the wide-angle read, converge with --quality-delta, never the other way round.

Pick the preset by what "rotten" needs to mean right now: lenient (all six families, 1 must agree) is a reading order, roughly a third of any tree; default (all six, 2 must agree) is a review list; strict (only the four families measured stable enough to stand behind repeatedly — historical and colocation are fixed-size worst-40 cuts over a ranking whose population moves, so both re-shuffle release to release on code that never changed) is the rung closest to something CI-shaped, but it is still a lens — nothing here plugs into an exit code the way --quality-delta does.

Read the structural row as a PROFILE — nest= alone is a max, and misleads solo

nest= reports the single deepest line in a function. One line at depth 9 and a thousand lines at depth 9 report the same number, so nest=9 cannot tell a tangled body from a long blocked-sequential one whose max was set by one inner loop nobody has to hold in their head. Acting on nest= alone is how an agent guard-clauses a dispatch table. --metrics (and the structural family's why= string in --quality-panel / --ensemble) now carry the profile beside the max:

<e f="structural" counted="1" why="ccx=724 loc=1244 nest=9 humps=30 deep=308 rrank=1"/>

Every concrete number on this page is ILLUSTRATIVE OF A SHAPE, never a value to expect. The counters themselves are under active calibration — an else-clause over-count fix in flight moves humps= down by a large fraction, and ccx=/nest= with it, on else-heavy functions. What is durable is what you do with the row: humps=1 vs many, the two ratios below, and the semantics (regions vs lines, absence below the bar, deep < humps legal). Read the row in front of you; never carry a remembered number to it.

• humps= — how many maximal control-nesting regions reach the nesting bar (bar_nest= on the panel root; CodeScene's "bumpy road": a rise above the threshold then a fall). One deep tangle is 1; repeated missing abstractions are many. EXACT, not a floor.
• deep= — how many LINES lie inside those regions, read against the loc= already on the row. A disclosed FLOOR (deep_floor="1").
• Both are absent exactly when nest < the bar — not-deep, never a hidden 0.
• deep below humps is legal output, not a defect. deep counts lines and humps counts regions, and two regions can share a line: a one-line if(c){x;}else{y;} at the bar is 2 regions on 1 line. Three reviewers have read that shape as a bug; it isn't.

Two ratios do the actual discriminating, and you compute them yourself from the row:

Three shapes off this repo's own source — read the pattern, not the digits, which move with calibration: a ~1000-line function at a low deep/loc (main, roughly a tenth) sits beside one at ~2.5× that fraction (buildGraph) once loc/nest have declared them equivalent; and a function far too small for any size bar to fire can carry the highest deep/loc in the table (ur_walkTree, loc=87, near half its body deep in a single hump). The first is blocked-sequential, the second tangled, the third dense — three different fixes, one indistinguishable nest=.

locals= rides the same row: the count of local-variable declarations, a FLOOR (locals_floor="1"), C/C++ only and absent — never a bare 0 — for every other language. It measures the working set a reader must hold at once, which is the thing extraction is actually supposed to shrink; a "split" that leaves locals where it was mostly moved braces.

join="deep+untested" on a --quality-panel row is a conjunction of two facts the report already holds — this row carries deep= and no indexed test reaches it — annotated, not a seventh family. It changes nothing: not fam=, not of=, not the ordering, not which rows appear. It is the pair where a refactor is most wanted and least safe, so it routes straight to test first, refactor second in the playbook below. It is suppressed on every row when tested_scope="0", because on a corpus whose tests were never crawled "untested" would be a fact about the crawl, not about the code — read tested_scope= on the root before you read the absence of the annotation as good news. deep_untested= on the root counts them across the WHOLE row set, which the limit= window does not change.

The per-file churn caveat. The historical family's churn= and hrank= are FILE facts, inherited verbatim by every symbol in the file — a symbol in a churny file collects that family without any property of its own. Discount it accordingly: on a row whose other evidence is thin, historical may be saying only "this file is busy", not "this function is." (hrank= is also a relative decile cut over this corpus, so something always fires.)

The loop

1. Zero-setup path: just make your change, then run ripwire <dir> --quality-delta --legend=compact before you call it done — add --legend=compact every time you run this in a loop: on a CLEAN report the legend is nearly the whole payload (2,776 B to 454 B measured on a small fixture, 15,601 B to 8,775 B on a mid-change repo), the rows are byte-identical either way, and you have already read the dictionary — in a git repo it auto-compares the working tree vs git HEAD (<quality-delta baseline="git-HEAD"> confirms it), no start-of-task action needed. Tighter loop on a long change: run ripwire <dir> --quality-baseline FIRST — on a clean tree — to pin an explicit floor (takes precedence over HEAD) so each edit deltas against the original start, not the last commit. On a tree that already differs from HEAD the pin refuses, naming the gating findings it would have swallowed into the floor: commit first, or pass --allow-dirty to pin anyway, which stamps the absorbed count so every later report carries baseline_absorbed="N" and a green exit beside it reads "clean since the pin".

2. Make your change.

3. Measure the delta — ripwire <dir> --quality-delta --legend=compact → only the regressions you introduced, across the 11 kinds in the table below. Each emits <r kind="…" sym=… was=… now=…> (members= for duplication). Test-fixture dirs are exempt from dead-code; short-horizon-churn ignores your own current edit and exempts brand-new symbols/markdown/fixtures. Two exemptions are DISCLOSED on the report rather than silent, and both change how you read a zero: a symbol defined by a self-registering test/benchmark macro (doctest TEST_CASE, gtest TEST/TEST_F/TEST_P, Catch2, Google Benchmark, plus anything in .ripwire_config's register_macros) is never dead-code — a static initializer is invisible to a name-based call graph — and the header's register-macro-excluded="N" counts how many were dropped that way, printed even at 0. A duplication row whose members share only a recognized idiom — a scalar threshold ladder, an enum-to-string switch table, a builder chain — and share no domain identifiers across different scopes is demoted to sev="minor" with idiom="…" and stops gating. The idiom name is there so you can overrule it by reading: a demotion is a judgement the tool is showing its work on, not a row it hid. Watch verbosity hardest — LOC growth is the single most-measured agent failure mode, the one most likely to hide in an otherwise-clean diff.

   Read the exit code correctly — it is narrower than it looks. Findings are sorted on three independent axes, and only one combination gates:

   • acked — suppressed entirely (counted honestly in acked="N").
   • ORIGIN — a symbol that EXISTED at the baseline and got worse is preexisting-worse (no origin= attribute on the row); one that exists only because the code is NEW carries origin="new-symbol".
   • MATERIALITY — a small numeric delta is additionally sev="minor".

   --quality-delta exits 2 ONLY on preexisting-worse AND major AND unacked — exactly the gating="N" count in the header. Read gating=, not regressions=. A real header looks like:

   <quality-delta baseline="git-HEAD" regressions="0" minor="0" acked="0"
                  preexisting-worse="0" new-symbol="0" gating="0" at="f0a45e43d">

   origin="new-symbol" rows are PRINTED but NEVER gate. They are the debt you are adding — read them; nothing else will make you. And --help is explicit that exit 0 means "nothing that already existed got worse", NOT "clean": a change that is entirely new code can add unbounded new-symbol debt and still exit 0. Never report "quality-delta passed" as "no new debt" — open the rows.

   Two more contract details worth knowing: clone kinds classify by member set (a group is new-symbol only if EVERY member is new), and short-horizon-churn is preexisting by construction. LIMIT: origin is canonId (path::scope::name) identity, so a RENAMED or MOVED symbol reads as new — a genuine regression carried in with a move classifies new-symbol and will not gate. If your diff moves code, the exit code is especially weak evidence; read the rows.

4. Fix the REAL ones, re-run, converge. Which fix a row calls for is the shape → refactor playbook below; proving the fix landed is the closed fix loop below that. Repeat until clean or the remainder are conscious trade-offs. Record a trade-off instead of re-reading it forever: ripwire <dir> --quality-ack="why it's accepted" writes the currently-visible findings into .ripwire_quality_acks (committable) — later runs suppress them honestly (acked="N") and a finding REAPPEARS the moment it worsens past its acked size.

   Ack a SUBSET, never the screen. Bare --quality-ack accepts every finding currently visible, so using it to accept one deliberate change silently accepts the rest too — that is how a ratchet turns into a rubber stamp. Narrow it with --ack-only=SUBSTR[,SUBSTR], which matches a finding's kind, its canonical id, or its facet:

   ripwire <dir> --quality-delta --ack-only=contract-change --quality-ack="arity change required by <fix>"

   Prefer the facet over the kind when one exists: api-surface also covers the never-gating new-symbol rows, so acking by kind can sweep in dozens of findings to accept a handful. --ack-only=gating selects exactly what would exit 2. A pattern matching nothing refuses (exit 1) rather than acking everything. Whatever you leave unacked stays visible — that is the point; an exit 2 you have explained in a commit message is worth more than an exit 0 you bought with a blanket ack.

   Sharing the working tree with other sessions? Then --ack-only is not enough — add --scope=. --quality-delta compares the working tree against HEAD, so in a checkout several agents are editing at once, every sibling's uncommitted rows land in your report. Bare --quality-ack there accepts the whole screen, which writes another session's debt into a committed ledger under your reason string: that is how the ratchet becomes a rubber stamp, and no amount of care reading the report prevents it. --scope=GLOB[,GLOB...] files each finding by its p= path:

   ripwire <dir> --quality-delta --legend=compact --scope=src/render,src/render_gl.h             # gate on MY subtree only
   ripwire <dir> --quality-delta --scope=src/render --quality-ack="deliberate"  # …and ack only my rows

   Rows outside the scope are still printed, under an <out-of-scope> element with a do-not-ack banner, and never gate; the header's scoped-out-gating= says how many of them would have gated, so a scoped exit 0 means "nothing of mine is broken", never "the tree is clean". The ack cannot write an out-of-scope row at all, and an --ack-only= that names one refuses (exit 1). Each row you write records by=<scope>, so a later run can flag an ack that suppressed a path its author never owned (foreign-acks=). A pattern with no wildcard is a root-anchored path prefix; */? match the whole path, with * spanning /. A scope that names nothing indexed refuses rather than reporting you clean. One reserved word: --scope=diff is whatever the working tree changed vs the baseline, expanded to one path per changed indexed file. It is sugar for the single-writer case — in the shared tree this flag exists for, a sibling's edits are "changed" too, so name your own paths there.

5. Want ONE number instead of a list — ripwire <dir> --dmm --legend=compact. --quality-delta says which kinds got worse; it has no scale, so "is this change better than my last one?" has no answer. --dmm is that scale: the Delta Maintainability Model (di Biase, Rastogi, Bruntink & van Deursen, TechDebt 2019; thresholds and arithmetic from PyDriller's reference implementation) scores the share of the volume your change moved that landed in — or freed from — risky units.

   <dmm base="2edbb46c…" target="working-tree" available="1" combine="pooled" size_metric="physical-loc"
        dmm="0.436" good="462" bad="597" base_units="4759" target_units="4780">
     <p k="size" dmm="0.184" good="65" bad="288" d_low="65" d_high="288"/>…

   A unit (a function/method definition with a body) is low risk iff loc<=15 (size), cyclomatic<=5 (complexity), params<=2 (interfacing). good = low-risk volume added plus high-risk volume removed; bad = the reverse; dmm = good/(good+bad). Deleting a god function scores 1.000; growing one scores 0.000. The three sub-scores are separately actionable — a low size with a healthy interfacing says split the function, not change the signature.

   Three things to carry. It is a DELTA, never a level: editing bad code without changing its size, complexity or parameter count contributes nothing — you are not punished for touching a mess, which is deliberate. dmm="UNAVAILABLE" is not a score of 1.0 or 0.0 — it means good+bad was 0 (a rename, a literal edit, a comment reflow), i.e. the change is outside what the model measures; the same token can appear per property. And it never gates (always exit 0): use it to trend — --dmm=REV scores one commit against its parent and --dmm=A..B scores a range, so a series of commits is a series of numbers.