📖Summary

The Migration service is built following the [agent-centric modular architecture](/dev/carolopedia/wiki/architecture) of Carolverse. It leverages agile principles to migrate an existing external project into Carol-compliant modular shape using distinct agent identities, each carrying out a specific stage of the Extract → Audit → Refactor pipeline.

📖Functional considerations

This is the on-ramp for outside code into Carolverse, so its architecture is shaped by what it must guarantee end-to-end:

- **Registration before work.** A migration is never started without an explicit git URL; [Noah](/dev/carolopedia/wiki/agent/agt-031)'s pipeline only touches a source that the user has named, slugged, and pointed at a real repo.
- **Reproducible workspace.** Each migration clones into its own isolated working directory on the VM, so the source under change is pinned and the pipeline reruns deterministically.
- **A staged, observable pipeline.** Extract → Audit → Refactor runs as ordered stages with a recorded `current_stage`, so status is a pure function of how far the project has progressed.
- **Hand-off, not lock-in.** When Refactor completes, the service stops at a roadmap rather than silently shipping changes — Leo synthesises the plan and files initiatives for another team to execute.
- **Subscription-scoped.** The service is external/revenue, so access is gated to subscribed users and surfaced through the subscribed-services listing.

📖Solution architecture

The service is a **staged pipeline** — register → clone → Extract → Audit → Refactor → roadmap — wired together by a small control plane. It is a direct instance of Carolverse's [agent-centric modular architecture](/dev/carolopedia/wiki/architecture): each stage is owned by an agent and carried out by that agent's droids (see the service's team above).

- **A single intake call.** Carol calls `register_migration`, which creates the migrations row and auto-clones the source — one entry point, so every migration starts the same way.
- **An owned pipeline.** [Noah](/dev/carolopedia/wiki/agent/agt-031) owns the Extract → Audit → Refactor stages; [Gimli](/dev/carolopedia/wiki/agent/agt-032) and [Thorin](/dev/carolopedia/wiki/agent/agt-033) support the pipeline and the roadmap surface.
- **Roadmap synthesis as the terminal stage.** When Refactor finishes, Leo (Head of Strategy) reads the refactor outputs and synthesises the migration roadmap.
- **A clean hand-off to the builder.** Leo files initiatives through his Initiative Filer into the [Build Initiatives](/dev/carolopedia/wiki/service/build-initiatives) service, where Elrond's team ships them — migration plans, Build Initiatives executes.

📖Design principles

- **Single source of truth.** "Carol-compliant modular shape" is defined by the live registry and design store, never hand-copied — the shared principle described on the [Carolverse Architecture](/dev/carolopedia/wiki/architecture) page.
- **Agent-centric modular architecture.** Every pipeline stage has an accountable agent and a doing droid.
- **Plan, then build elsewhere.** The service produces a roadmap and hands execution to [Build Initiatives](/dev/carolopedia/wiki/service/build-initiatives) rather than shipping changes itself.
- **Explicit consent before action.** No migration begins without a user-supplied git URL.
- **Observability first.** A migration's stage is always queryable, so progress is never a guess.

📖Success criteria

- A subscribed user can register a migration and have the source auto-cloned without operator help.
- Each migration moves through **Extract → Audit → Refactor** with a queryable `current_stage` at every point.
- On Refactor completion, **Leo produces a roadmap** and files initiatives into Build Initiatives for Elrond's team.
- **No migration starts without an explicit git URL.**
- Status (`get_migration_status`) always reflects the true stage, last-touched time, and counts.

📖Policies

- **Never register a migration without an explicit git URL** supplied by the user.
- **Subscription-gated.** Only subscribed users may invoke the service; access is surfaced through the subscribed-services listing.
- **The service plans, it does not ship.** Execution of the roadmap routes through Build Initiatives and Elrond's team — migration droids do not directly land changes.
- **Every stage is tagged to an agent and its droid** — Extract, Audit, and Refactor are owned, not anonymous.
- **Roadmap initiatives are filed through Leo's Initiative Filer**, not hand-inserted.

📖What it delivers today

- Register an existing project for migration and auto-clone its source repo — [Noah](/dev/carolopedia/wiki/agent/agt-031), via `register_migration`.
- Run the **Extract → Audit → Refactor** pipeline over the cloned source — [Noah](/dev/carolopedia/wiki/agent/agt-031) with [Gimli](/dev/carolopedia/wiki/agent/agt-032) and [Thorin](/dev/carolopedia/wiki/agent/agt-033) supporting.
- A **Migration Roadmap** surface at `/dev/migration/` to watch a migration's progress — [Thorin](/dev/carolopedia/wiki/agent/agt-033).
- Roadmap synthesis on Refactor completion plus initiative filing into Build Initiatives — Leo via his *Initiative Filer*.
- Query a migration's current stage, last-touched time, and counts — via `get_migration_status`.
- **The handover Migration owns (design 587, cookbook 1476)** — H2: hands Blueprint the graded as-is (extracted requirements with evidence, findings citing standards) and the proposal placing every capability, as the migration row at *handoff* — the flip that wakes Leo. A stage with no rows fails; a refusal is never a result.

📖What it will deliver

- Per-stage progress and diffs on the Migration Roadmap, not just the current stage.
- Multi-language Extract/Audit coverage beyond the primary source language captured at registration.
- Automatic re-scan when the source repo changes upstream.
- Tighter feedback from shipped Build Initiatives back into the roadmap, so a migration shows what has actually landed.