/ln-26-architecture-migration-planner

name: ln-26-architecture-migration-planner
description: "Plans architecture migrations with compatibility, data safety, rollout and recovery; does not execute them."

Architecture Migration Planner

**Goal:** Plan a safe transition from evidenced current architecture to an explicit target, with reversibility limits and recovery actions. Change only the approved migration document; do not execute migrations, edit product code, build a generic task plan, approve delivery, or hide irreversible steps.

**Execution contract:** The checklist defines completion. Track each item internally as `PENDING`, `PROVEN` with evidence, `CLEARED` with evidence its condition is absent, or `UNPROVEN` with a gap; reading, delegation, or tool failure is not proof. Reconcile after each section. Before returning, resolve all `PENDING`, count only `PROVEN` and `CLEARED`, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

| Need | Preferred capability | Fallback | |---|---|---| | Current and target states | Repository evidence plus approved architecture artifacts | Explicit user-provided states with limitations | | Consumers and compatibility | Language intelligence, schema tools, config search, telemetry, and direct inspection | Conservative inventory marked `UNVERIFIED` | | Data scale and runtime risk | Production metrics, checked-in reports, migrations, and workload evidence | Ranges with validation gates before execution | | External migration constraints | Official vendor migration and compatibility guidance | Mark dependent phases `BLOCKED` or `UNVERIFIED` | | Document mutation | Minimal patch to the approved migration-plan artifact | Return `BLOCKED` when authority or path is unclear |

A migration phase must leave the system in a supported state. Additive and reversible steps precede cutover; destructive cleanup follows verified zero use.

Artifact Rules

• Reuse a clear architecture migration document; otherwise use `docs/architecture/migration-plan.md`.
• Treat current-state, target-design, baseline, decisions, diagrams, interfaces, and telemetry as optional shared evidence.
• Keep the plan architectural: phases, compatibility, data, topology, gates, rollback, ownership, and removal.
• Leave file-level implementation tasks to downstream planning.
• Never describe rollback as "revert" when data or external effects are not reversible.
• Give every destructive step explicit approval, backup, restoration, and zero-consumer evidence requirements.

Checklist

1. Establish the Transition Contract

• [ ] Resolve migration scope, business outcome, current state, target state, non-goals, deadline or horizon, owners, and approved destination.
• [ ] Read repository instructions, Git state, relevant architecture artifacts, migrations, deployment configuration, and compatibility policies.
• [ ] Verify that current and target states are specific enough to compute a gap; return `BLOCKED` rather than invent either state.
• [ ] Identify protected user journeys, invariants, SLOs, recovery objectives, compliance duties, and change windows.
• [ ] Keep the run read-only except for the approved migration document.

2. Build the Gap and Dependency Map

• [ ] Inventory affected modules, deployables, data stores, schemas, APIs, events, configuration, infrastructure, and operational procedures.
• [ ] Inventory internal and external consumers, owners, versions, traffic, data volume, and evidence quality.
• [ ] Map current-to-target changes in boundaries, ownership, contracts, data, runtime topology, observability, and failure behavior.
• [ ] Identify shared mutable resources, sequencing dependencies, long-running work, mixed-version windows, and irreversible effects.
• [ ] Record unknown consumers or usage as migration risks; absence of search results is not zero usage.

3. Design Compatibility and Data Safety

• [ ] Define old/new contract compatibility, version negotiation, adapters, dual-read or dual-write behavior, and deprecation policy where relevant.
• [ ] Use expand/migrate/contract when mixed versions or online migration require coexistence; separate additive and destructive releases in that case. For an approved offline atomic transition, document the equivalent compatibility, recovery, and downtime controls.
• [ ] Define backfill selection, batching, throttling, idempotency, checkpoints, retries, reconciliation, and correctness oracle.
• [ ] Define source of truth during coexistence, concurrent-write conflict handling, and detection, retry, and reconciliation of partial dual-write failure; do not assume two writes are atomic.
• [ ] Define backup, restore, RPO/RTO impact, privacy, retention, and audit evidence for data movement.

4. Build Reversible Phases

• [ ] Define preparation, shadow or coexistence, progressive migration, cutover, stabilization, and old-path removal as independently verifiable phases.
• [ ] For every phase, s