Ln 26 Architecture Migration Planner

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, tool failure, a zero exit status, or a self-reported success is not proof; only the observed outcome is. 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. When no one can answer during the run, state the exact question and apply the skill's verdict for the remaining gap instead of waiting or guessing. 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

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, state prerequisites, changed architecture state, owner, entry gate, observable success, abort condition, rollback or roll-forward action, and exit evidence.
• Define feature flags, routing controls, canary cohorts, rate limits, maintenance windows, and blast-radius controls where justified.
• Define metrics, logs, traces, reconciliation reports, dashboards, alerts, and SLO gates needed before traffic or data movement.
• Keep old and new versions interoperable through realistic deployment ordering and rollback windows.