This folder contains Architecture Decision Records (ADRs) for the Azure DevOps Migration Platform.
Each ADR records an important architectural decision: what was decided, why, what alternatives were considered, and what the consequences are.
- Accepted — the decision is in effect
- Superseded by XXXX — replaced by a later ADR
- Deprecated — no longer applies
| ADR | Title | Status |
|---|---|---|
| 0001 | Source → Files → Target architecture | Accepted |
| 0002 | Filesystem package as source of truth | Accepted |
| 0003 | Cursor-based checkpointing | Accepted — amended by ADR-0010 |
| 0004 | Control Plane does not execute migrations | Accepted |
| 0005 | Agent-only package write access | Accepted — amended by ADR-0008 |
| 0006 | Three-channel observability | Accepted — amended by iron-comms (Phases A–E, 2026-06-30); transport superseded by ADR-0020 |
| 0007 | Compiler-enforced project boundary topology | Accepted |
| 0008 | Configuration travels in the package | Accepted |
| 0009 | Single Job class with Kind discriminator | Accepted |
| 0010 | Plan-driven DAG execution | Accepted — amended by iron-comms (2026-07-01) |
| 0011 | Unified platform.* metric namespace |
Accepted |
| 0012 | IModule five-phase contract | Accepted |
| 0013 | Simulated connector as first-class CI infrastructure | Accepted |
| 0014 | ICapture: Unified capture contract | Accepted — amends ADR-0012 |
| 0015 | Mode-driven CLI and TUI UI contract | Accepted |
| 0016 | Unified package access | Accepted |
| 0017 | Capability seam ethos and TDD architecture governance | Accepted |
| 0018 | Compatibility-only guard clauses | Accepted |
| 0019 | WorkItems extension seam and staged cursor pipeline | Accepted |
| 0020 | Unified worker-event channel | Accepted — amends ADR-0006 and ADR-0010 |
| 0021 | Four-tier validation model | Accepted |
| 0022 | Host composition roots own storage selection; modules depend only on storage contracts | Accepted — executes MM-C1, MM-H1, CA-C2 |
| 0023 | Promote hidden cross-slice seams to canonical Abstractions ports | Accepted — executes CA-C1, CA-H1/HX-M1, VS-H1, VS-H2, VS-H3, VS-M3 |
| 0024 | Connector capability flags, team/comment extension seam contracts, and ADO pagination exemptions | Accepted — executes EC-H1, EC-M2, EC-M3, EC-M4, EC-L1 |
| 0025 | Storage-neutral error contract for package meta reset | Accepted — executes HX-H1 |
| 0026 | Tool-contract purification: embedded-image, identity-translation, and field-transform tools | Accepted — executes TC-H2, TC-M1, TC-M2, TC-L3; TC-H1 deferred |
| 0027 | Real Teams/Nodes Prepare validation and module-only dependency targets | Accepted — executes MC-L1, MC-L2 |
| 0028 | Module anatomy: Selection/Data/Processing configuration contract (ConfigVersion 2.0) | Accepted — executes MC-H1, MC-H2 |
| 0029 | Taxonomy suffix renames (Reader→Source, Mapper→Processor, Tracker→Lifecycle, Registry→Store, EventWriter→Sink, PlanExecutor→Orchestrator) | Accepted — pure rename, no behaviour change |
| 0030 | Team orchestrator unification (TeamMigrationOrchestrator) and phase-neutral WorkItem progress/metrics/context renames | Accepted — pure refactor, no behaviour change |