refactor-governance

Preventing incomplete migrations requires enforcing staged entry and exit gates with baseline evidence capture. Breaking refactoring into baseline, switching, and cleanup phases ensures old truth sources and compatibility layers cannot unintentionally survive into later stages.

Stage-based refactor governance is a process that breaks implementation replacement and abstraction convergence into explicit baseline, switching, and cleanup phases. You need it when managing migration boundaries and compatibility layers to prevent cross-stage leakage and conflicting truth sources.

Cleaning up obsolete evidence requires a clear must-clear list and strict cleanup rules enforced during the final stage. Mandatory documentation in docs/refactor ensures compatibility layers and old truths are tracked and removed before stage exit.

Yes, evidence-based validation requires stage exit to be backed by tests, checks, and a review gate. This ensures that implementation replacement and abstraction convergence are verified before moving forward to the next refactoring phase.

To start a governed refactor, ask your AI to run the refactor-governance workflow for your planned migration and produce the first stage document under docs/refactor. This captures the baseline evidence needed to begin the staged entry and exit process.

AI refactoring leaves conflicting truth sources when cross-stage leftovers occur without explicit stage gating. Without a must-clear list and evidence-backed exit criteria, compatibility layers and old implementations unintentionally survive into later stages.