Turning a map into a safer change loop

Ripwire becomes most useful when a coding agent stops asking only “where is the code?” and starts asking “what will this change disturb?” This chapter follows the project through that maintenance lifecycle: prioritize risk before editing, identify impact and tests, compare the result with a baseline, account for hidden historical coupling, and use a guarded edit only when the target is fresh and unambiguous. The aim is not one master score. It is a set of distinct evidence questions that can be used together without pretending they measure the same thing.

The change loop has different states. Before an edit, the agent needs a map of the target and its dependencies. During an edit, the relevant identity and file bytes must remain stable. After an edit, the agent needs evidence about what got worse and which tests or related files still matter. A clean result at one state does not automatically certify the next state.

Before editing: corroborate risk without inventing a score

A function can look risky for several unrelated reasons. It may be deeply nested, unusually long, named inconsistently, full of confusing syntax, frequently changed, dependent on many files, or able to reach mutable state outside its own file. Treating all of those observations as one numerical quality score would make the output compact, but it would hide which evidence actually fired.

Ripwire’s --quality-panel takes the opposite approach. It joins six evidence families and ranks a symbol by the count of distinct families that agree. The structural family considers shape such as cognitive complexity, size, nesting, parameters, and local variables. The lexical family considers identifier naming. The confusion family looks for syntactic idioms that can mislead readers. The historical family uses Git change frequency. The colocation family estimates how much of what a reader must understand lives outside the current file. The state family looks at a function’s own access to non-local mutable state.

Each family contributes a reason, not just a point. A row might be structurally complex and historically active; another might be modest in shape but unusually dependent on definitions in other files. Those are different maintenance situations. The panel makes the distinction inspectable instead of reducing it to “quality: 4.” On the project’s pooled calibration corpora, no two families correlated above +0.168, which supports using agreement as corroboration rather than counting one underlying signal several times.

The panel’s presets express different decisions. A lenient view is a reading order: one family can put a symbol on the list. The default view asks for agreement from at least two of the six families. A strict view retains only families whose behavior was stable enough in the project’s calibration to stand behind a gate. Historical churn and colocation are excluded from that strict set because their fixed-size worst-case rankings can move when the repository population changes, even when a particular function does not.

That exclusion is an important design boundary. An evidence family can be useful for prioritization without being stable enough for enforcement. Similarly, a family that cannot be evaluated is marked unavailable rather than treated as a family that did not fire.