ADR 009 Migration Evidence Control Loop

Context

Migration inventory, implementation, runtime wiring, and browser proof are different states. Large prose execution logs made those states hard to audit and let historical smoke results look like current architecture truth.

Decision

Each migration slice follows one evidence chain:

1. Record exact legacy source evidence and stable feature id.
2. Name bounded context, backend feature, and domain/application authority.
3. Implement smallest backend or contract slice that replaces legacy authority.
4. Add persistence, SpiceDB authorization, Restate workflow, or Kill Bill integration only when feature requires that platform boundary.
5. Keep changed tests colocated with *_test naming.
6. Run focused tests plus relevant Ruff, Tach, contract, frontend, or docs gates.
7. Advance checklist status only when linked evidence supports new state.

Backend uses DDD plus bounded-context feature slices. CQRS remains optional; separate command and query models only when write invariants and read projection needs differ.

Frontend remains static Astro Atomic Design shell. It may collect intent, format backend projections, and hold ephemeral interaction state in NanoStores. It may not own DDD feature slices, business rules, authorization, lifecycle transitions, or financial calculations.

Evidence States

• pending: source gap identified.
• mapped: target bounded context and feature named.
• foundation: domain/application/contract behavior tested.
• runtime_wired: required adapter, API, worker, or policy boundary connected.
• e2e_proven: same runtime path exercised end to end.
• migrated: legacy or UI authority removed from active path.
• blocked: owner and concrete unblock condition recorded.

Passing unit tests does not prove runtime wiring. Passing browser smoke does not prove business authority moved out of frontend. Dated runtime evidence remains historical unless rerun and recorded against current revisions.

Verification Gate

Use only gates relevant to changed slice:

• Python: focused uv run pytest, uv run ruff check, and Tach checks.
• JavaScript/Astro: pnpm repository scripts.
• Docs: pnpm docs:check.
• Architecture: implementation links pinned to repository revisions.

No ADR claims deployment or production readiness from repository structure alone.

Implementation Evidence

• Machine-countable source feature checklist
• Backend bounded-context feature tree
• Backend Tach boundaries
• Frontend Atomic Design boundary rules

Checklist still contains pending, partial, and intermediate rows. Control loop is active, but migration is not complete.

Consequences

ADR stays short and durable. Per-feature execution detail belongs in checklist or source-map evidence, not appended implementation diary.

Revision History

• 2026-07-06: accepted source-to-implementation control loop.
• 2026-07-10: moved execution snapshots back to checklist authority and added explicit evidence-state semantics.