Migrations

A migration is a change that is individually trivial and collectively enormous: renaming an interface used in six hundred places, moving every call from a deprecated client to its replacement, restructuring an error convention across a service. These are where agents deliver the most value and where partial completion is most dangerous.

Completeness as the primary objective#

A migration that is ninety-five per cent complete is frequently worse than one never started, because the remaining five per cent is now inconsistent with both the old and the new convention. Migrations are therefore planned against an enumerated site set derived from the symbol graph, and progress is measured against that enumeration rather than against effort spent.

1. 1

   Enumerate

   The full set of sites is derived from the symbol graph and frozen. The count is known before work begins — a migration with an unknown denominator cannot be verified complete.

2. 2

   Classify

   Sites are bucketed into mechanical, contextual and manual. Mechanical sites are transformable by rule; contextual sites need local judgement; manual sites are escalated rather than guessed at.

3. 3

   Pilot

   The transformation is applied to a small representative sample and verified. A pilot failure rate above threshold halts the migration before it has touched the bulk of the repository.

4. 4

   Execute in waves

   Remaining sites are processed in reviewable batches, grouped by module so each wave is an independently mergeable unit.

5. 5

   Reconcile

   The final site set is re-derived and compared against the frozen enumeration. Any site present in one and not the other is reported.

Handling the contextual bucket#

Mechanical sites are the easy majority. The contextual bucket is where migrations actually succeed or fail — call sites where the correct replacement depends on surrounding logic, error handling that does not map cleanly onto the new convention, tests asserting on the old behaviour. These are processed individually with the full symbol context loaded, and any site the agent cannot resolve with high confidence is escalated rather than approximated.

Reversibility#

Every wave produces a reversal patch. A migration can be unwound wave by wave in the reverse order it was applied, which is what makes it reasonable to attempt a six-hundred-site change on a Tuesday afternoon.