Safe subtraction

A pivot has a visible half and a quiet half. The visible half is the replacement plan. The quiet half is everything the rejected route already created: an adapter, a draft projection, temporary scaffolding, an old reference, or a component that no longer has a role.

Keeping all of that feels cautious, but it makes later work carry paths the project already rejected. Deleting it because the new plan no longer mentions it is not caution either. The file may still be an entry point, dynamically selected, or owned by a consumer outside the repository.

Safe subtraction separates two questions: can deadness be established from the available evidence, and does this session own the judgment to remove the candidate?

[Visual 6.3 — The bottom band of the section frame, enlarged. One card labelled "candidate left by the rejected path" moves through three individual gates in order: "1. zero live references", "2. not a route, command, hook, public API, fixture or test", and "3. not selected by configuration, registration, reflection or a string key". Every gate has a side exit labelled "cannot prove: keep and queue or checkpoint". A candidate that passes all three reaches a provenance fork. Upper branch: "created by this session solely for the rejected path" to "remove, record, and rely on git for recovery". Lower branch: "older, pre-existing or foreign" to "present the evidence to the human". A final bracket under both branches reads "deadness and permission are separate decisions".]

The three deadness checks

A candidate is treated as dead only when all three checks pass:

1. No live reference to it can be found.
2. It is not an entry point.
3. It is not reached dynamically.

The first check includes repository search or a language server's reference search. It asks whether live code, tests, configuration or documentation still names the candidate. A result of zero is necessary and insufficient.

The second check looks for roles that ordinary reference counts can hide. A route, command, hook target, exported public API, fixture or test can be invoked by its environment rather than by an ordinary call site. A file can have no internal import and still be the thing the runtime starts.

The third check covers indirection. Registration tables, configuration names, reflection, plugin loaders and string-keyed dispatch can connect a caller to a candidate without a static reference that a simple search recognises.

Each check fails closed. "I could not find a caller" is not equivalent to "there is no caller." If one condition cannot be established, the candidate is retained and the uncertainty becomes open work or, where resolving it needs human knowledge, a checkpoint.

Deadness is evidence, not permission

Passing all three checks establishes the product's deadness standard at the repository boundary. It still does not answer who should make the deletion.

Coldstart uses provenance for that second decision.

Current-session exhaust is material the session itself created solely for the route it has now rejected. The session knows why the candidate exists, what replaced it, and which diff introduced it. When all three deadness checks pass, the design permits the session to remove the candidate, record the deletion in its outcome, and use version control as the recovery net.

Older or foreign material predates the active pivot or has ownership the session cannot establish. Even when it appears dead inside the repository, it can have a consumer or history the current context does not reveal. The session gathers the same evidence and presents the candidate to the human. Finding the file, editing a nearby file, or being able to delete it does not transfer ownership.

This provenance fork makes the method deliberately asymmetric. It is more willing to clean up its own abandoned attempt than to interpret someone else's absence of references as consent.

Why version control matters, and what it does not solve

Version control makes a wrong deletion recoverable. The removed file and exact prior contents remain available in the commit history, and a focused removal can be reverted. That fact counters the default habit of keeping every abandoned path "just in case."

Recovery is not the same as safety. Reverting after an external consumer breaks may still cost time or data, and version control does not reveal that consumer before deletion. Git therefore supports the provenance rule; it does not replace the deadness checks or the human gate.

The subtraction should also stay reviewable. A small removal tied to one rejected route has a clear reason and recovery path. A broad cleanup sweep mixes unrelated histories and makes both provenance and verification harder to inspect.

The pivot is the natural time to look

Subtraction often fails to happen because it is scheduled for an abstract future cleanup pass. Coldstart instead attaches the sweep to events that already have a reason to inspect the affected area: superseding a plan, resolving a checkpoint, closing a section, or demoting, renaming or removing a component.

The pivot is the clearest case. The session already knows which approach was rejected and which artifacts it created. Waiting several sessions discards that provenance and turns obvious current-session exhaust into mysterious old code. Looking now makes the ownership question cheaper without making the deadness test less strict.

This does not mean every pivot must delete something. The event opens the inspection. The three checks and provenance fork still decide the disposition.

A worked subtraction

Return to the export session. Before the read-model decision, the session created an adapter that turns display rows back into export values. After the human chooses a dedicated raw-data read model, the adapter belongs only to the rejected route.

The session checks it:

• no live references remain after the plan and implementation move
• it is not a route, command, hook target, public export, fixture or test
• it is not named by configuration, registration or string dispatch

The session also knows the adapter's provenance because it created it during this unit for this one approach. The candidate passes both decisions. It can be removed, named in the outcome and recovered from version control if the evidence later proves incomplete.

An older export module produces a different result. Search finds no direct reference, but its age and name suggest it may be an external batch entry point. The second check cannot be established, and the current session does not own its history. It stays. The session records the unresolved entry-point question for a human instead of treating visual similarity to the new module as proof.

The current cleanup boundary

The on-demand cleanup instruction in the pinned source runs the strict verification roster, reads the open queue and reports findings by class with one-line proposed fixes. It explicitly says that structural fixes are the user's call. Only formatting-level repairs inside files already in scope are treated as routine.

That boundary is important because the design language is more ambitious than a deletion command. The deadness and provenance model tells the project how a proposal should be judged. It is not an automatic garbage collector, a complete call graph or proof that every dynamic entry point is known.

What this page does not claim

A zero-reference search proves only what its search surface represents. The entry-point list can be incomplete, dynamic reach can be hidden, and an external consumer may be invisible. Provenance can also be misread if a session has modified material it did not originally create. Uncertainty keeps the candidate in place.

The page does not claim that subtraction improves outcomes, or that less code is always better. It describes a narrow rule for residue whose role has ended and whose removal can be justified.

Next

Keep the harness honest after the change: continue with Upkeep.

How current this page is

Checked on 10 August 2026 against the pinned product revision's cleanup design, cleanup instruction and divergence design. To ask whether a claim here still holds, or to report one that does not, write to [email protected].