awesome-copilot/skills/doc-and-modernize/references/migration-hazards.md

Migration Hazard Catalog

A generic, stack-agnostic catalog of migration hazards that are predictable per ecosystem but are routinely missed in a first-draft modernization plan. Every phase plan should be red-teamed against this list before it is implemented (see Modernization mode's pre-implementation red-team step).

Each hazard is written as: Trigger (when it applies) → Risk (what breaks) → Detection probe (a concrete check you can run now) → Plan action (what to add to the phase) → Examples (per-ecosystem, illustrative only).

These are hazard classes, not a fixed checklist for one stack. The examples (Java/Spring/Mongo/Docker etc.) are illustrations drawn from real runs — map each class onto whatever ecosystem you're actually migrating. If a hazard doesn't apply, say so explicitly rather than silently skipping it.

---

How to use this catalog

Before implementing any phase:

1. Walk every hazard below and ask "does this phase trigger it?"
2. For each triggered hazard, run the detection probe against the real repo.
3. Fold the plan action into the phase's tasks and exit criteria before writing code — a hazard caught in planning is a task; caught in review it's rework; caught in prod it's an incident.
4. Record hazards you checked and cleared, not just the ones that fired — a silent skip is indistinguishable from a miss.

Empirically (the PiggyMetrics run, phases 0–6) an independent critic caught a blocking plan gap in every single phase, and each gap was an instance of one of the classes below. Running this catalog is that critic, institutionalized.

---

H1 — Incomplete quarantine / removal set

Trigger: You are removing, quarantining, or cutting over an entire dependency family (a dead framework, a removed runtime API, an EOL library set) and only some modules are being touched.

Risk: A module you didn't list still transitively depends on the removed artifact, so the default build/test target fails after the cutover — often in a module the plan never mentioned.

Detection probe: Grep the dead artifact/coordinate across all manifests, not just the ones you're editing (pom.xml/build.gradle, package.json, *.csproj, requirements*.txt/pyproject.toml, go.mod, etc.). Every hit is a module that must move or be quarantined in the same phase.

Plan action: Enumerate the full transitive set of dead-artifact dependents up front and list every one in the phase's reactor/quarantine decision. State the post-cutover build target explicitly (which modules are in, which are quarantined).

Examples:

• JVM: Spring Cloud 2023 removes Netflix Hystrix/Turbine; monitoring and turbine-stream-service still pulled netflix-hystrix-dashboard / netflix-turbine-stream and broke mvn verify even though the plan only quarantined gateway + auth-service.
• JS: dropping request — grep for every require('request') / from 'request', not just the one service you remembered.
• Python: removing a C-extension lib — check every import site + extras.

---

H2 — Framework-major mechanical codemods (namespace / API / test-engine)

Trigger: A major version bump of a framework, language, or platform (not a patch/minor). Major bumps carry mechanical breaking changes independent of your own logic.

Risk: The plan treats "bump the version" as one task and misses the whole-tree mechanical migrations the bump forces — namespace renames, removed deprecated APIs, changed test runner/engine, changed config keys — so the build won't even compile.

Detection probe: Read the target version's migration/upgrade guide and identify the known breaking-change recipes. Grep the tree for the old namespace / API surface to size the change. Check whether an ecosystem codemod/recipe tool exists.

Plan action: Enumerate each mechanical migration as its own explicit task, and prefer the ecosystem's automated recipe tool over hand-editing where it's reliable. Decide tool-vs-manual deliberately (small trees may be safer by hand; large trees need the tool). Include test-framework migration in the list — it is routinely forgotten.

Examples:

• Spring Boot 2→3: javax.* → jakarta.* namespace migration and JUnit 4→5 (add junit-vintage-engine to keep JUnit 4 tests running, migrate OutputCapture-style Jupiter-only cases). Tool: OpenRewrite.
• JS: CommonJS→ESM, or React class→hooks. Tools: jscodeshift, react-codemod.
• Python: 2to3/pyupgrade; async API renames.
• .NET: Newtonsoft→System.Text.Json, HttpClient patterns.

---

H3 — Runtime bump not in lockstep with deployment artifacts

Trigger: You bump the language/runtime major (JDK, Node, Python, Ruby, Go) used to build the app.

Risk: The build now emits artifacts for the new runtime, but the deployment/runtime surface still pins the old one — base images, CI runner version, buildpacks, engines fields, lambda runtimes — so the app builds green and then fails to run (bytecode/ABI/syntax mismatch), often only in a smoke/e2e step, or silently in prod.

Detection probe: Inventory every place the runtime version is pinned: Dockerfile/Containerfile base images, docker-compose* build contexts, CI workflow setup-*/runner images, .tool-versions/.nvmrc/runtime.txt, engines in package.json, serverless runtime keys. Cross-check each against the new target.

Plan action: Add an explicit task to move every deployment/runtime pin in the same phase as the build bump. Never let build-runtime and run-runtime drift across a phase boundary. Verify the smoke path actually builds/runs the new artifacts (and doesn't build quarantined modules).

Examples:

• JVM: source-built services emit JDK 21 bytecode but every Dockerfile still FROM java:8-jre → containers won't start; dev-compose still built the quarantined auth-service.
• Node: CI bumped to Node 22 but Docker image still node:14-alpine.
• Python: venv on 3.12 but the container base is python:3.7.

---

H4 — Traffic-flow / route-class enumeration gap (edge & auth rewrites)

Trigger: Rewriting an edge/gateway, an auth/identity layer, or any request-routing/security boundary.

Risk: The plan pins the obvious authenticated happy path and silently drops one or more other traffic classes — anonymous flows (signup, password reset, public assets, health/metrics scrape), service-to-service calls, webhooks — so those break at cutover.

Detection probe: Enumerate every route class the boundary must serve: (1) anonymous/public, (2) end-user authenticated, (3) service-to-service (machine tokens/scopes), (4) infra/observability (health, readiness, metrics scrape), (5) webhooks/callbacks. For each, confirm the new config has an explicit rule.

Plan action: Make the route-class enumeration an explicit artifact of the phase (a table of route class → new rule → scope). Call out that scanners/security expect infra endpoints (e.g. metrics scrape) to remain reachable. Decide token/scope granularity for s2s calls (narrow scope, not a generic "server" grant).

Examples:

• BFF/OAuth2: SCG BFF + TokenRelay covered login but missed the anonymous registration POST + signup assets, and /uaa/users was permitAll instead of requiring a narrow user.write service scope.
• Metrics: resource-server security must keep /actuator/prometheus open or scraping silently breaks.

---

H5 — Stateful data-store major upgrade treated as an image/version bump

Trigger: Bumping the major version of a stateful backing service (database, cache, broker, search index) that has persisted data/volumes.

Risk: Engine majors frequently can't start on prior-major on-disk data without a sequential/FCV upgrade path. A naive image bump either fails to start, appears flaky depending on local volume state, or corrupts data.

Detection probe: Check whether the store has persisted volumes/data directories, and read the engine's supported upgrade path (sequential majors? feature-compatibility-version steps? dump/restore only?). Determine whether the data is production/durable or ephemeral/demo.

Plan action: Choose and document one path: (a) sequential/FCV migration with steps + rollback, or (b) an explicit destructive reset (drop volumes, re-seed) when the data is ephemeral/demo — stated as a decision, not an accident. Put this in the migration safety net with a rollback plan.

Examples:

• MongoDB 3→7: direct image bump over an existing anonymous /data/db volume is unsafe; for a demo, the blessed path was docker compose down -v + re-seed via native initdb.d, with the old mongo:3 image retained for rollback.
• Postgres major: needs pg_upgrade or dump/restore, not just a tag change.

---

H6 — Transitional-insecure state trips scanners & reviewers repeatedly

Trigger: A phase intentionally introduces a temporary, deliberately-weak state to keep the system runnable mid-migration — permit-all security shims, CSRF disabled, an open endpoint, a hard-coded secret placeholder, a disabled check.

Risk: Every code scanner (CodeQL, Dependabot, SAST) and every automated reviewer flags it each review, generating recurring noise and re-litigation, and — worse — a shim that was meant to be temporary silently ships because nobody tracked its closing phase.

Detection probe: For each transitional weakening, ask: which scanner will flag this, and which later phase closes it? Is the weakening minimally scoped (e.g. permit-all chains should still explicitly disable form-login/HTTP-Basic so the surface is exactly what's intended)?

Plan action: Maintain a transitional-insecure-state register: each shim with (a) why it's needed, (b) the phase that closes it, (c) the residual risk, (d) a note to reviewers that it's by-design-until-phase-N. Scope each weakening as tightly as possible. Pre-declaring it converts review churn into a resolved, tracked decision.

Examples:

• Phase-5 permit-all SecurityConfig shims flagged CodeQL "CSRF disabled" on every service, every review; the fix was to explicitly disable form-login/basic and annotate "stateless permit-all shim, closed in Phase N."

---

H7 — Stacked-PR trap & trunk split-brain (phased governance)

Trigger: A multi-phase migration where each phase depends on the previous, developed branch-per-phase.

Risk: If phase N+1 is branched off phase N's branch (instead of trunk) and phase N is never merged to trunk, PRs get merged into each other, the trunk silently stalls several phases behind, and later phases are forced to stack — producing the exact bind where the "no stacked PRs" rule has to be overridden. A parallel failure: a repo with two default-ish branches (master + main) where phase work targets the wrong one.

Detection probe: Before starting a phase, verify the previous phase's PR is merged to trunk and the new branch is cut from trunk (git log origin/<trunk>..HEAD should be empty at branch creation). Confirm the repo's real trunk name and that no legacy default branch is being targeted.

Plan action: Mandate merge each phase PR to trunk before starting the next phase. Never base a phase branch/PR on a sibling phase branch. If genuinely blocked and controlled stacking is unavoidable, require a reconciliation PR that lands the stack onto trunk and an explicit residual-risk note. Pin the trunk name and mark any legacy default branch "history only — do not target."

Examples:

• PiggyMetrics phases 3 & 4 were merged into each other; main stuck at Phase 2; master/main split-brain — reconciled only by a dedicated PR #6, after Phase 5 had to break the no-stacking rule.

---

H8 — Living-doc drift (topology changes outrun the docs)

Trigger: A phase changes system topology — module/reactor membership, removed services, renamed branches, changed commands, new/removed endpoints.

Risk: Only the plan's status markers get updated; the executable/onboarding docs (.github/copilot-instructions.md, README, module lists, command tables) go stale and start actively misleading the next agent/human — e.g. a "quarantined module" list that no longer matches the reactor.

Detection probe: After any topology change, diff the change against every doc that describes topology: agent-instructions file, README, architecture doc's module/command tables, compose/service inventories.

Plan action: Extend the living-plan discipline beyond the plan file: any phase that changes topology must update copilot-instructions.md, the README, and any module/topology list in the same PR. Treat these docs as part of the phase's Definition of Done, not a follow-up.

Examples:

• copilot-instructions.md quarantine text stayed stale after gateway moved into the reactor and monitoring/turbine were removed; README hard-coded a master branch link that 404'd after the trunk became main; actuator exposure omitted refresh, breaking the @RefreshScope workflow.

---

Quick pre-flight checklist (per phase)

• H1 Grepped the dead artifact across all manifests; full quarantine set listed?
• H2 Enumerated the major-bump codemods (namespace, removed APIs, test engine); recipe tool chosen?
• H3 Every runtime pin (base images, CI runners, engines) moved in lockstep with the build bump?
• H4 Every route class enumerated (anon, authed, s2s, scrape, webhook) with an explicit rule?
• H5 Stateful-store major has a migration path or an explicit destructive-reset decision + rollback?
• H6 Every transitional-insecure state registered with its closing phase + scoped tightly?
• H7 Previous phase merged to trunk; new branch cut from trunk; trunk name confirmed?
• H8 Topology change reflected in copilot-instructions.md + README + module lists in the same PR?