data-tier-cutover

data-tier-cutover — the stateful-tier decision model, inventory, gate, runbooks, and review hook

Migrating the stateful tier is the hardest step of a platform migration and is categorically different from the stateless id-* flow. This skill encodes the decision model and the four evidence-backed traps so they are driven, not re-derived. Read-only / never-apply: this skill authors the plan artifact + runbook; every mutating step in the emitted runbook is operator-run (the id-apply posture discipline). The merge floor — the adopter's branch protection + CI checks (see docs/merge-floor.md) — stays the merge authority.

Stage A — the cutover-mechanism decision tree (fail-closed)

• Inputs (all three required): downtime_tolerance (window_ok | near_zero), source_shared_with_prod (bool), source_is_replicable (bool). A missing input is a STOP — never assume tolerance.
• window_ok AND not shared ⇒ snapshot-restore (the simple path): a snapshot restore PRESERVES the source DB users and passwords — the app keeps its credentials and only the host string changes.
• near_zero OR shared-with-prod ⇒ CDC-replicate + fast-promote, and the plan artifact MUST carry the three required CDC caveat items: sequences are NOT replicated by logical CDC — resync them at promote; the cache cannot be slaved cross-environment — provision it FRESH and warm it; define a replication-lag SLA before promote (stale reads until promote).
• Record the chosen mechanism + rationale into the per-app cutover plan artifact so the operator and the PR reviewers see WHY, not just WHAT.

Stage B — connection-pool inventory (from application source, never the deploy layer)

• Read the APPLICATION SOURCE for the data-access topology and record a matrix row per app: {pool_shape: single | dual, ro_endpoint_key, rw_endpoint_key, sticky_read_your_writes: bool, orm/driver}. The deploy/gitops layer is an UNRELIABLE source for this — a dual read/write pool or a sticky read-your-writes default is only visible in code, and guessing from the deploy layer produced a wrong matrix on the evidence engagement.
• The matrix drives feasibility: dual-pool apps can take a phased read-first cutover; a single-pool app cannot. Missing/ambiguous topology ⇒ default-deny — STOP and ask; never guess (a wrong guess silently reads stale data or connects to the wrong endpoint).