safe-migrations

# Safe Migrations Treat compatibility, state, and reversibility as first-class requirements. ## Decide whether to migrate Identify the forcing function, affected producers and consumers, stored state, support window, blast radius, and cost of leaving the old path in place. Reject a migration whose benefit does not justify its operational risk. ## Establish the baseline Before changing implementation, capture current contracts and representative behavior: tests, state snapshots, traffic shape, performance, error semantics, and rollback prerequisites. Existing consumers are part of the contract even when their behavior is undocumented. ## Design coexistence and cutover Choose a pattern from [migration-patterns.md](references/migration-patterns.md): expand/contract, adapter, dual-read/write, shadow, strangler, or versioned contract. Define phases, ownership, observability, data reconciliation, entry and exit criteria, and the exact point of no return. Prefer additive steps: 1. Introduce the new shape or implementation without removing the old one. 2. Backfill or translate state with idempotent, resumable operations. 3. Validate old and new behavior side by side. 4. Shift traffic or consumers in measured stages. 5. Hold through a defined observation window. 6. Remove compatibility code only after usage reaches the agreed threshold. For each phase, define rollback when reversible and a forward-fix when rollback would corrupt or discard newer state. Never label an unteste...