/milestone-runner

name: milestone-runner
description: 'Use when asked to "run milestones", "execute EXECUTION_PROMPTS.md", "continue the milestone sequence", "run independent milestones in parallel", "merge the stack", or "reconcile M5" after prior work changes the current design. Not for generating plan files; use plan-prompts. Not for repairing one stack; use stacked-prs.'
metadata:
  version: 1.3.0
  category: development
  tags: [milestones, orchestration, adaptive-planning, stacked-prs, ci, release-management, execution-prompts]
  difficulty: advanced
  phase: ship
  complements:
    - plan-prompts
    - stacked-prs
    - ship-workflow

Milestone Runner

Run milestone prompts produced by `plan-prompts`. The runner coordinates mandatory design reconciliation, dependency-safe execution, verification, CI, review, merge/cleanup, and release preparation.

The runner executes existing prompts; it does not author a new product plan. It may require a docs-only reconciliation PR when the current plan no longer matches repository evidence. It invokes `stacked-prs` for stack topology and `ship-workflow` only after a complete release train requires preparation.

Core model

A milestone has two independent gates:

1. **Design gate.** Before implementation, inspect the authoritative plan/prompt, current codebase, merged predecessor diffs, predecessor verification, CI, and local history. Require `DESIGN GO` or stop on `DESIGN NO-GO`. 2. **Merge gate.** After implementation, require release-aware `GO` plus external PR, CI, verification, and review evidence.

An ignored history ledger is reconstructible local evidence, not authoritative state. `.docs/DEVELOPMENT_PLAN.md` and `.docs/EXECUTION_PROMPTS.md`, merged PRs, CI, and current code remain authoritative.

Every terminal milestone result must print the literal heading `NEXT STEPS:` followed by concrete, ordered actions: the current milestone action, release-preparation state, and the next runnable milestone. A `NO-GO` must name remediation and either an independent milestone that can proceed or the reason no milestone can. A prose follow-up or JSON `next_steps` key is insufficient.

| Evidence | Use | | --- | --- | | Authoritative plan and prompts | Build the DAG, release trains, milestone contract, and design-gate scope. | | Local history ledger | Carry prior gate decisions and verified outcomes; rebuild it when absent. | | Current code plus merged predecessor diffs and PR evidence | Validate the plan’s assumptions, interfaces, dependencies, and acceptance. | | CI/check state and verification commands | Confirm predecessor outcomes, reconciliation PRs, and implementation stacks. | | Provider PR metadata | Confirm bases, reviewed reconciliation, stack topology, and merge state. |

Modes

| Mode | Trigger | Behavior | | --- | --- | --- | | Sequential build | "run milestones", "one after another" | Reconcile the next ready milestone, run it only after `DESIGN GO`, merge after external gates, then continue. | | Parallel build | "run independent milestones in parallel" | Reconcile every candidate serially on the latest base; launch only the stable `DESIGN GO` wave in isolated worktrees. | | Resume | "continue the milestone sequence" | Reconstruct state from authoritative artifacts and external evidence, then reconcile the next ready milestone or release train. | | Merge and clean | "merge the stack", "ensure CI is green" | Verify design and merge gates, use stacked-PR discipline, clean verified merged branches, and evaluate release preparation. |

Default to sequential. Never launch code after `DESIGN NO-GO`, a failed or pending gate, an unresolved release target, or a required human gate.

Workflow

1. Inspect inputs and local evidence

1. Read `.docs/DEVELOPMENT_PLAN.md`, `.docs/EXECUTION_PROMPTS.md`, and every `/goal` block. Extract dependencies, release-train fields, design-reevaluation rows, and exact verification commands. 2. Read `.docs/DEVELOPMENT_PLAN_HISTORY.md` when it exists. Verify it is ignored. Maintain this single ledger only in the canonical runner workspace. 3. When the ledger is absent, reconstruct the gate context from committed plan/prompt history, merged predecessor PRs and diffs, CI/check results, verification output, and current code. Create a local ledger header and append the reconstruction evidence; do not claim unavailable history. 4. Reconcile each prompt release-train field with the plan. Stop on contradictions or unresolved `> GAP:`. 5. Confirm a clean canonical workspace before reconciliation, launches, merges, rebases, cleanup, or release preparation. Stop on unrelated dirty state.

2. Build the provisional DAG

Before any launch, report:

| Milestone | Depends on | Target release | Design status | Implementation status | Runnable now | Lane | | --- | --- | --- | --- | --- | --- | --- | | M1 | none | v2.4.0 | awaiting design | pending | no | design-1 | | M2 | M1 | v2.4.0 | blocked | blocked | no | design-2 |

Rules:

• An unmerged dependency blocks both design and implementation.
• Release preparation begins only after every train member is externally merged.
• A `DESIGN GO` applies only to the exact authoritative plan/prompt revision that was inspected.
• A material reconciliation invalidates every provisional design result for affected milestones. Re-read the artifacts and rebuild the DAG before any implementation launch.

3. Reconcile milestone design

Run design gates serially in fresh top-level sessions from the canonical clean base. A design session must do only the prompt’s `PRE-IMPLEMENTATION DESIGN GATE`; it must not create product-code branches, write product code, or launch implementation PRs.

For each dependency-ready milestone:

1. Supply the current authoritative plan/prompt and local history context. 2. Inspect the milestone’s source-map rows, current code, merged predecessor diffs, predecessor PR outcomes, CI/check evidence, verification output, release fields, and every declared dependen