A Refactor Is a Transaction, Not a Diff

A diff shows what changed between two file states. It does not tell you whether the change stayed in scope, began from the expected repository, preserved the intended contracts, or was transferred safely.

For a risky refactor—especially one performed by an AI coding agent—the useful unit of control is a transaction.

Declare intent before mutation

A change contract can name:

• the architecture outcome;
• files and symbols allowed to change;
• public entrypoints and opaque files to protect;
• literals and host contracts that must remain exact;
• required tests and project gates;
• behavior scenarios to compare;
• unsupported surfaces that require review;
• transfer policy.

This makes scope enforceable. “Refactor the module” becomes a set of observable constraints instead of a broad invitation to improve nearby code.

Capture the real before-state

The baseline should represent the actual working tree, not merely HEAD.

Tracked modifications, staged changes, and relevant untracked files may all be part of the engineer’s current state. Requiring a commit or stash before every experiment creates friction and can hide which state the agent actually saw.

An immutable fingerprint lets the transaction detect if the original workspace changes while the candidate is being evaluated.

Isolate candidate mutation

The agent should work in a disposable candidate derived from the captured before-state. It can make broad edits there without risking the original workspace.

Deterministic operations can be prepared as exact, preview-bound plans. Manual semantic edits remain allowed inside the candidate, but they do not bypass the evidence stack.

Isolation also makes refusal cheap. A blocked candidate can be retained for diagnosis or discarded without undoing user work.

Verify the declared transition

Static and runtime checks should evaluate the change against its contract:

• unified file accounting;
• import, export, and binding roles;
• protected literals and opaque bytes;
• direct-consumer migration;
• module cycles and initialization order;
• affected tests and full project gates;
• runtime characterization and parity scenarios;
• environment availability and harness health.

Missing evidence is not the same as a regression, but neither should it produce a silent green verdict.

Explain causality

A transaction can fail for different reasons:

• the candidate introduced a regression;
• the baseline was already red;
• the environment changed;
• the agent violated scope;
• the requested transformation is unsupported;
• the harness failed;
• the workflow stopped before transfer.

A useful verdict preserves these categories. “Tests failed” does not tell the engineer whether to repair the candidate, fix the environment, or change the contract.

Transfer is a separate gate

Even a green candidate should not overwrite an original workspace that has changed since the transaction began.

Before transfer, the system rechecks the original fingerprint and the declared file set. Only authorized candidate paths move. If the workspace drifted or the postimage does not match the accepted candidate, transfer refuses.

The final record should distinguish “candidate passed” from “candidate transferred.” Otherwise an interrupted workflow can be mistaken for a completed change.

Why this matters for agents

AI agents are valuable because they can reason across large changes and execute quickly. Those same properties make retrospective review difficult.

A transaction gives the agent a bounded place to use judgment while an independent system retains authority over scope, evidence, and transfer.

KodeProof is built around that separation. The objective is not to slow every edit. It is to make high-risk changes inspectable as one causal event: what we intended, what state we started from, what changed, what evidence ran, why the verdict followed, and exactly what reached the repository.