> ## Documentation Index > Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt > Use this file to discover all available pages before exploring further. # Milestones > How milestones are reviewed, executed, automatically reviewed, shipped, and learned from Milestones are the heart of your migration. Each one delivers a working increment that you review before proceeding, so changes stay small, reviewable, and safe. Within each milestone, the agent breaks the work into **tasks** and handles them automatically. After tasks finish, the Morph Platform runs an **automated milestone review** and surfaces functional test and acceptance-criteria results before you merge. Once you merge, the Morph Platform **learns from your changes** and updates project knowledge so the next milestone doesn't repeat the same mistakes. For a high-level overview of the roadmap, see the [Roadmap](/migration/roadmap) page. *** ## The Milestone Lifecycle Each milestone moves through these phases: 1. **Review the Milestone Spec** in Project Knowledge. 2. **Approve & Start** — from Project Knowledge, approve the spec and start the agent. 3. **Automated Review & Tests** — milestone review, functional testing, and acceptance criteria run automatically and surface in dedicated tabs. 4. **Triage the Review and Merge the Milestone** — open Code Review to triage issues with chat, then jump to the pull request(s) and merge. 5. **Milestone Learning** — after merge, the Morph Platform learns from the PR review and your edits and updates project wikis and rules so future milestones avoid the same issues. The expanded milestone card on the Roadmap exposes up to four tabs — **Tasks**, **Review**, **Tests**, and **Acceptance Criteria** — that appear as each phase becomes relevant. *** ### Step 1: Review the Milestone Spec Before any code is generated, understand what the milestone will accomplish. Click a milestone on the Roadmap to expand it. * If the milestone is **ready to start**, the **Next Step** alert offers **Review & Approve** — this opens **Project Knowledge** with the milestone spec selected. * At any time, use the **Milestone Spec** button on the milestone action row to open the same view. * If prerequisites are not met yet, the alert shows **View** instead — you can read the plan, but approval waits until earlier milestones merge. ![Milestone expanded on the Roadmap](https://mintcdn.com/modelcodeai/FvveHrl7MJeyooqL/migration/images/milestone-expanded.png?fit=max\&auto=format\&n=FvveHrl7MJeyooqL\&q=85\&s=ab8227cfc31c87277eb09f747f99fc28) Both entry points open the **Project Knowledge** drawer with the milestone selected in the tree — alongside your project spec, rules, wikis, and lifecycle setup. In the drawer you can: * **Read the full Milestone Spec** — scope, relevant files, design decisions, and risks the agent will follow. * **Refine via Knowledge chat** — ask the Morph Platform to clarify, expand, or adjust the spec. The agent updates the Milestone Spec in place. * **Approve** — when you're satisfied, approve the milestone in the drawer to unlock **Approve & Start**. For deeper guidance on editing the Milestone Spec — including `Validate following milestones` to make sure your edits don't break later milestones — see [Editing Milestones](/customization/editing-milestones). For the drawer itself, see [Project Knowledge](/customization/project-knowledge). > [!TIP] > > You don't have to change anything. If the plan looks good, approve it. But if something looks off, this is the cheapest place to fix it — much cheaper than fixing generated code later. > **[Editing Milestones](/customization/editing-milestones)** > > How to adjust the Milestone Spec before approving > **[Project Knowledge](/customization/project-knowledge)** > > The drawer where milestone specs, rules, and wikis live *** ### Step 2: Approve and Start Approval and start happen in **Project Knowledge**, not on the Roadmap card itself. After you review the spec, click **Approve & Start** in the drawer toolbar. Before the milestone runs, a **Start this milestone?** dialog shows what the work will cost in dollars and credits, and whether it stays inside your monthly allotment. Nothing starts until you approve it. See [Billing and Credits](/support/billing-and-credits#approving-a-milestones-cost) for what the figures mean. Once approved, the Morph Platform prepares a sandbox and the agent begins working autonomously: it plans tasks, works through them one by one, and commits code after each task. > [!NOTE] > > To run a slow or flaky milestone faster, open the caret beside **Approve & Start** and choose **Start With Low Validation** — it implements and reviews this one milestone at the [Low validation level](/setup/validation-level#running-a-single-milestone-at-low) regardless of the project's setting. Run an ad-hoc validation after the PR merges to check the work at the project's level. > [!NOTE] > > To run a slow or flaky milestone faster, open the caret beside **Approve & Start** and choose **Start With Low Validation** — it implements and reviews this one milestone at the [Low validation level](/setup/validation-level#running-a-single-milestone-at-low) regardless of the project's setting. Run an ad-hoc validation after the PR merges to check the work at the project's level. ![Milestone initializing](https://mintcdn.com/modelcodeai/FvveHrl7MJeyooqL/migration/images/milestone-initializing.png?fit=max\&auto=format\&n=FvveHrl7MJeyooqL\&q=85\&s=93c07ae7f550854a04045c2390aa50cc) A **Tasks** tab appears on the expanded milestone where you can watch progress in real time. Each task shows its ID (for example `M1-T001`), title, and status badge. ![Tasks in progress](https://mintcdn.com/modelcodeai/FvveHrl7MJeyooqL/migration/images/tasks-in-progress.png?fit=max\&auto=format\&n=FvveHrl7MJeyooqL\&q=85\&s=bca1f1a66ce64c071bee4b728242ef42) You don't need to babysit execution — the agent runs autonomously and progress is persisted. Open the milestone whenever you want to check on it; the **Tasks** tab keeps updating in the background. *** ### Step 3: Automated Review & Tests After the agent finishes implementation, the Morph Platform runs automated validation before the milestone is ready to merge. What runs depends on your project's [validation level](/setup/validation-level) — a project-wide setting that controls **whether Morph actually runs your application on the source side, the target side, both, or neither**: | Validation level | Source (origin) app | Target app | | - | - | - | | **Low** | Not run | Not run — build and unit tests only | | **Medium** | Not run | Run — full lifecycle (install, build, run, healthcheck) | | **High** | Run — baseline captured upfront | Run — verified against the source baseline | At **Low**, there is no functional testing or acceptance criteria — the **Acceptance Criteria** tab stays empty, and the **Tests** tab appears only after lifecycle commands (build and unit tests) have run. At **Medium**, validation exercises only the migrated app. At **High**, the Morph Platform compares target behavior against what it observed on the source app, so regressions surface side by side. The **Review** tab runs at every level — it inspects the agent's code changes regardless of whether the app is exercised at runtime. Results surface as dedicated tabs on the expanded milestone card: | Tab | When it appears | What it shows | | - | - | - | | **Tasks** | As soon as planning produces tasks | The execution tasks the agent is working through | | **Review** | Once the milestone review starts | The review tasks (the automated review pipeline) and a count of issues raised | | **Tests** | When validation includes functional testing (**Medium**/**High**) or lifecycle commands have run | A summary of backend (API/CLI) and frontend (visual) functional test results for the milestone, with passed/total counts and origin-comparison counts where available | | **Acceptance Criteria** | Once acceptance-criteria results exist | Pass/fail status for built-in and custom criteria tied to lifecycle scripts | #### The Review tab The **Review** tab tracks the milestone's automated review tasks — the pipeline that inspects the agent's output and raises issues against the migrated code. Once review tasks finish, the milestone exposes a **Code Review** button on its action row that opens the dedicated Review drawer (see Step 4). Failed functional tests [also raise issues here automatically](/migration/validation-hub#failed-tests-create-review-issues), linked back to the failing test for easy back-and-forth. #### The Tests tab The **Tests** tab appears when your validation level includes [functional testing](/migration/validation-hub) — **Medium** (target-only) or **High** (source baseline + target comparison) — or when lifecycle commands have run during milestone validation (for example install, build, run, or test scripts). It shows passed/total counts for backend (API/CLI) and frontend (visual) functional test runs where available, with origin-comparison indicators on **High**. From here you can jump into the full breakdown: > **[Validation Hub](/migration/validation-hub)** > > Verify behavior with auto-generated tests; the Tests tab is your milestone-scoped entry point #### The Acceptance Criteria tab The **Acceptance Criteria** tab appears when your validation level includes acceptance-criteria checks — **Medium** (target-only thresholds you author) or **High** (source baselines captured and compared on the target). It shows pass/fail status for built-in checks (build succeeds, tests pass) plus any custom criteria defined in [Project Knowledge](/customization/project-knowledge). *** ### Step 4: Triage the Review and Merge the Milestone Once the automated review finishes and the pull request(s) are generated, the milestone moves to **Pending Code Review** (the UI label for all pending-review states, whether every task succeeded or some failed): ![Pending review](https://mintcdn.com/modelcodeai/FvveHrl7MJeyooqL/migration/images/milestone-pending-review.png?fit=max\&auto=format\&n=FvveHrl7MJeyooqL\&q=85\&s=241482cad1499bf0b9c1221264ba1925) Everything from here happens through the **Code Review** drawer. Click **Code Review** on the milestone action row to open it — this is the single entry point for both triaging review issues and reaching the underlying pull requests (there's no separate "open PR" button on the milestone). The button stays disabled until a PR exists. ![Milestone Review hub with issues list and chat panel](https://mintcdn.com/modelcodeai/VlpH1wOB6CUgSSGa/migration/images/review-hub.png?fit=max\&auto=format\&n=VlpH1wOB6CUgSSGa\&q=85\&s=b92275aa48982695a43cbf77a8ae1a5d) **Triage the review.** The Code Review drawer is an interactive hub for every issue raised on the milestone, with a chat panel for working through them. On this page you can: * **Browse review issues** across every repository in the milestone, filtered by status and assignee. * **Chat with the Morph Platform** to resolve issues, create new ones, add review criteria, or re-run the review against your latest changes. * **Inspect the Milestone Spec and Project Spec** in side tabs without leaving the page. > **[Code Review Chat](/migration/code-review-chat)** > > Full walkthrough: filters, chat actions, importing external issues, and re-running the review **Merge the milestone.** When the review looks good and tests pass, jump to the PRs from the same drawer: 1. Click **View Pull Requests** in the Code Review drawer header. A popover lists every PR in the milestone, each linking out to your SCM provider if you want to review or merge there. 2. Open each PR and review the code as you would any PR — leave comments, request changes, or push fixups. 3. When you're satisfied, click **Merge all PRs** in the Code Review drawer header to merge every open PR for the milestone in one step, without leaving the Morph Platform. (Final Code Delivery is the exception — that PR must be merged on your SCM provider.) After every PR in the milestone is merged, the milestone is complete and any dependent milestones are unlocked. > [!NOTE] > > When a milestone PR is merged while sibling milestones are still in progress, the Morph Platform automatically detects whether those sibling branches need to incorporate the newly merged code. If so, the affected milestones are flagged with a **Rebase required** alert — see [Rebase Required](#rebase-required) below. ![Milestone merged](https://mintcdn.com/modelcodeai/FvveHrl7MJeyooqL/migration/images/milestone-merged.png?fit=max\&auto=format\&n=FvveHrl7MJeyooqL\&q=85\&s=603dd932ea395ced5c02d64d47ea9e8e) > **[Reviewing Pull Requests](/migration/pull-requests)** > > Best practices for reviewing migration PRs *** ### Every milestone re-checks the ones before it From the second milestone onward, the Morph Platform also runs the functional tests accumulated from all previous milestones as a **regression suite**, after the current milestone's own tests. This is what keeps a long migration honest: work that lands in milestone 8 cannot quietly break behavior proven in milestone 2 without you hearing about it. Regression results appear alongside the milestone's own results in the [Validation Hub](/migration/validation-hub). A regression failure does not block the current milestone — it is surfaced for you to judge, since the right fix may belong in either milestone. *** ### Step 5: Milestone Learning Merging the PR is the signal that the final state of the milestone is what you wanted — including every change *you* applied on top of the agent's output (review comments accepted, fixups you pushed, criteria you added, manual edits). The Morph Platform treats that signal as a teaching moment. As soon as a milestone PR is merged, a background **Milestone Learning** task runs automatically. An agent opens a sandbox with full access to the merged PR (review comments, inline feedback, the final diff, your follow-up commits) and looks for patterns worth keeping — corrections, conventions, architectural constraints, or anti-patterns that future milestones should respect. Anything it finds gets written back to your project as updates to: * **Wikis** — when the PR reveals new context about the codebase or how a subsystem actually works. * **Rules** — when the PR enforces a convention, constraint, or fix-up pattern that should apply to future work (new rules start as **Draft** until you publish them). Both update [Project Knowledge](/customization/project-knowledge) directly, so the next milestone's agent loads them automatically — no copy-pasting feedback, no repeating the same correction across milestones. > [!TIP] > > Milestone Learning runs **asynchronously and non-blocking**. You can start the next milestone right away — learning will keep running in the background and the updated wikis/rules will be in place by the time the next agent needs them. You don't have to do anything to trigger this — merging the PR is enough. If you want to see what was learned, open [Project Knowledge](/customization/project-knowledge) after the next milestone starts and check **Rules** and **Wikis** for recent updates. > **[Project Knowledge](/customization/project-knowledge)** > > Where learned rules and wiki updates live > **[Rules](/customization/rules)** > > Conventions and constraints applied to every future milestone *** ## The Foundation Milestone **Milestone 1** (the foundation milestone) includes an extra automated step before migration code lands: **target lifecycle discovery**. The Morph Platform analyzes the target repo to determine how it should be installed, built, run, and tested. The discovered configuration is saved under **Target** in [Project Setup](/customization/project-knowledge) for you to review and edit. When and how **origin** lifecycle is set up depends on your [validation level](/setup/validation-level): | Validation level | Origin lifecycle | Target lifecycle | | - | - | - | | **High** | Discovered during **Project Setup** onboarding (before Milestone 1) | Discovered during the **foundation milestone** | | **Low / Medium** | Discovered automatically after your project environment is set up | Discovered during the **foundation milestone** | If discovery cannot get the target application healthy automatically, the configuration is saved as **Draft — Needs Review** and a warning appears so you can fix it before proceeding. *** ## Milestone Statuses As a milestone moves through its lifecycle, its status badge updates on the Roadmap. Here's what each one means in the UI: | Status | Meaning | | - | - | | **Blocked** | Either waiting for prerequisite milestones to merge (**Not Started** + **Blocked by** chips), or a hard failure state (agent crash, PR generation failure). Check the milestone alerts to tell which. | | **Not Started** | All prerequisites satisfied. Ready to review and approve. No agent work has begun. | | **In Progress** | The agent is actively working on tasks. | | **Pending Code Review** | Implementation finished (with or without task failures). Review and/or PR generation is underway or complete — triage in Code Review. | | **Merged** | You've merged the PR. Milestone complete. | | **Completed** | The milestone is finished without a merge. Either it needed **no code changes**, so no pull request was opened, or its pull request was closed without being merged. Dependent milestones unlock the same as for **Merged**. | Additional UI states you may see: | UI element | Meaning | | - | - | | **Locked** (milestone label) | Project setup is incomplete, or (on limited plans) the milestone is beyond your current access tier. Expand to see what's blocking it. | | **Rebase required** | A sibling milestone merged and this branch needs to incorporate those changes before you can merge. | | **Validating** | The Morph Platform is re-validating a Milestone Spec edit you made in Project Knowledge. Wait before approving. | > [!NOTE] > > A milestone reaches **Pending Code Review** whether or not every task succeeded. If some tasks failed, you'll see alerts on the milestone card and in the **Tasks** tab — so check there before assuming a clean run. *** ## Tasks You don't need to interact with individual tasks — they execute automatically as part of the milestone. This section is here for when you want to follow along in detail. ### Task Statuses | Status | Meaning | | - | - | | **Ready** | Waiting to be picked up. This is the default for new tasks. | | **In Progress** | The agent is working on it. | | **Completed** | Done. | | **Failed** | The task ran into an error. | | **Skipped** | A dependency failed, so this task was not run. | | **Needs human** | The agent paused and needs input before it can continue. | ### Task Dependencies Tasks can depend on other tasks. For example, "Implement authentication middleware" might need "Create project scaffolding" to finish first. The Morph Platform handles execution order automatically: * A task stays in **Ready** until all of its dependencies have completed. * Once a dependency finishes, tasks waiting on it become eligible to run. * If a dependency fails, all tasks waiting on it are **skipped**. This prevents the agent from building on top of work that didn't succeed. * Tasks with no dependencies can run in parallel (within the milestone's execution batch). * If dependencies form a loop (Task A needs Task B, which needs Task A), the Morph Platform catches this and stops with an error. *** ## Milestone Dependencies and Parallel Execution Milestones can declare **dependencies** on other milestones. A milestone that depends on another will not unlock until the prerequisite is merged. When milestones are independent — no shared file or logical dependencies — they can execute in parallel. ### How it works * The Morph Platform analyzes file dependencies and logical ordering when generating the roadmap, and sets up a dependency graph automatically. * **Independent milestones** (no shared dependencies) can be approved, started, and reviewed simultaneously — each runs in its own isolated branch. * **Dependent milestones** stay **Not Started** with a **Blocked** badge and **Blocked by** chips until all listed prerequisites are merged. * When a milestone is merged, any milestones that were waiting on it are automatically unlocked and become ready to start. * On self-hosted deployments, parallel execution is bounded by your pool's capacity — starting another milestone is refused while every machine in the pool is occupied, and you can start it once one frees up. ### Milestone states related to dependencies | What you see | Meaning | | - | - | | **Blocked** badge + **Blocked by** chips | Waiting for one or more prerequisite milestones to merge. Cannot be approved and started yet. | | **Not Started** (no Blocked badge) | All prerequisites satisfied. Review the spec and approve in Project Knowledge. | | **Rebase required** alert | A sibling milestone was merged and this milestone's branch needs to incorporate those changes before it can be merged. | ### Rebase Required When you have multiple milestones in progress and one of them merges, the remaining in-progress milestones may need to incorporate the newly merged code. The Morph Platform detects this automatically and shows a **Rebase required** alert on milestones that already have pull requests. To resolve it, click **Rebase** on the milestone card. The agent incorporates the upstream changes into the milestone branch so that the PR stays mergeable — you do not need to resolve conflicts manually. *** ## Tips * **Review before approving.** It's much cheaper to fix the plan in the Milestone Spec than to fix generated code. Use Knowledge chat to refine if anything looks off. * **Use the Review tab before the PR.** The automated review surfaces issues *before* you spend time in your SCM provider. Triage them in Code Review, then read the diff in the PR. * **Don't rush merges.** Review carefully. It's easier to catch issues now than after several milestones have built on top. * **Let Milestone Learning do the bookkeeping.** Corrections, fixups, and accepted review comments on a merged PR are automatically distilled into wiki and rule updates — you don't need to write rules by hand for every recurring issue. For conventions you want enforced *now* (before the next merge), you can still add a [Rule](/customization/rules) manually. * **Work independent milestones in parallel.** If two milestones have no dependency relationship, you can approve and start both. This shortens overall delivery time without sacrificing review quality (subject to pool capacity on self-hosted). * **Watch for "Rebase required."** When a sibling milestone merges and your in-progress milestone shares dependencies, the Morph Platform may flag it as needing a rebase. Trigger the rebase from the milestone card — the agent incorporates the upstream changes so your PR stays mergeable. After a rebase completes, open **Code Review** on that milestone and check the **Rebase Report** tab for a dedicated summary of what was incorporated. *** ## Related Docs > **[Roadmap](/migration/roadmap)** > > High-level view of your migration > **[Adhoc Milestones](/migration/adhoc-milestones)** > > Add new work as a full milestone > **[Code Review Chat](/migration/code-review-chat)** > > Triage milestone review issues with chat > **[Validation Hub](/migration/validation-hub)** > > Verify behavior with auto-generated tests > **[Reviewing Pull Requests](/migration/pull-requests)** > > Best practices for PR review > **[Editing Milestones](/customization/editing-milestones)** > > Adjust plans before approving > **[Validation Level](/setup/validation-level)** > > Choose whether Morph runs the source app, target app, both, or neither > **[Troubleshooting](/support/troubleshooting)** > > Common issues and how to fix them This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.