9thlevelsoftware/legion/milestone-tracker

## Milestones
 
### Milestone {N}: {name}
-**Phases**: {start}-{end}
-**Goal**: {one-line milestone goal}
-**Status**: Pending | In Progress | Complete | Archived
-**Completed**: {YYYY-MM-DD} (only present when Status is Complete or Archived)

## Phase Details        <-- existing section
...phases listed here...
 
## Milestones           <-- milestone section goes HERE
...milestones listed...
 
## Progress             <-- existing section
...progress table...

Step 1: Read ROADMAP.md phase list
  - Parse the ## Phase Details section
  - Extract all phase numbers, names, and descriptions
  - Count total phases
 
Step 2: Analyze phases for logical groupings
  Look for:
  - Shared theme (e.g., "core workflow", "advanced features", "integrations")
  - Dependency clusters (phases that build on each other)
  - Natural break points (major deliverables or user-facing milestones)
  - Group size: no fixed phase-count limit; group phases by coherent deliverable and dependency boundaries
 
Step 3: Propose the milestone set the roadmap needs
  For each proposed milestone, include:
  - Name: descriptive theme label
  - Phase range: {start}-{end} (inclusive, no gaps or overlaps)
  - Goal: one-line description of what this milestone delivers
 
Step 4: Present proposals to user
  Use AskUserQuestion to show the proposed milestones:
  "Here are the proposed milestones for your project:
 
  Milestone 1: {name} (Phases {start}-{end})
  Goal: {goal}
 
  Milestone 2: {name} (Phases {start}-{end})
  Goal: {goal}
 
  ...
 
  Accept these milestones, or describe changes?"
 
Step 5: Handle user response
  - Accept: proceed to write milestones
  - Modify: adjust boundaries, names, or goals as directed
  - Define from scratch: user provides their own groupings

Step 1: Read current ROADMAP.md
 
Step 2: Validate milestone ranges
  - Ranges must cover all phases exactly (no gaps, no overlaps)
  - Each phase appears in exactly one milestone
  - If validation fails: report the issue and ask user to fix
 
Step 3: Insert ## Milestones section
  - Place after ## Phase Details and before ## Progress
  - Add each milestone as ### Milestone {N}: {name} with fields
 
Step 4: Derive initial status for each milestone
  - Read the Progress table for each phase in the milestone's range
  - If all phases have Status = "Complete" → milestone Status = Complete
  - If any phase has Status != empty/Pending → milestone Status = In Progress
  - If no phases have started → milestone Status = Pending
  - If Status = Complete, add Completed field with today's date
 
Step 5: Write updated ROADMAP.md

Step 1: Read ROADMAP.md
  - Verify ## Milestones section exists
  - If missing: offer to define milestones (Section 2) instead of erroring
 
Step 2: Identify target milestone
  - If milestone number specified: find that milestone
  - If not specified: auto-detect the earliest milestone with Status = "In Progress"
  - If no In Progress milestones found: report "No milestones are currently in progress"
 
Step 3: Verify all phases are Complete
  - Read the Progress table
  - For each phase in the milestone's range (start through end inclusive):
    - Check that Status = "Complete"
  - If any phase is NOT Complete:
    - Report exactly which phases are incomplete
    - Show each incomplete phase's current status
    - Do NOT mark the milestone complete
    - Exit completion flow
 
Step 4: Verify reviews passed
  - Check for UAT.md files in each phase directory
  - Or check STATE.md for review status indicators
  - If reviews are missing: warn but do not block completion

Step 1: Create .planning/milestones/ directory if it doesn't exist
 
Step 2: Check if .planning/milestones/MILESTONE-{N}.md already exists
  - If it exists: ask user whether to overwrite or skip summary generation
  - If overwrite: proceed
  - If skip: go directly to "Mark milestone complete"
 
Step 3: Gather quantitative metrics
  From ROADMAP.md Progress table for phases in range:
  - Total plans: sum of Plans column
  - Plans completed: sum of Completed column
  - Phases: count of phases in the milestone (end - start + 1)
 
  From REQUIREMENTS.md traceability table:
  - Find all requirement IDs mapped to phases in the milestone's range
  - Count how many are checked [x] vs total
  - Format: {checked}/{total} requirements satisfied
 
  From SUMMARY.md files for each phase:
  - Extract key-files lists (created/modified)
  - Deduplicate and count
 
  From CONTEXT.md files for each phase:
  - Extract agent recommendations
  - Deduplicate agent IDs
 
Step 4: Gather qualitative data
  From SUMMARY.md files:
  - Extract key outcomes (done text or summary bullet points)
  - One line per phase summarizing the key deliverable
 
  From STATE.md:
  - Collect decisions from "Recent Decisions" that relate to phases in range
  - Extract relevant decision text
 
Step 5: Write .planning/milestones/MILESTONE-{N}.md

# Milestone {N}: {name} — Summary
 
## Completed
{YYYY-MM-DD}
 
## Goal
{milestone goal from ROADMAP.md}
 
## Metrics
| Metric | Value |
|--------|-------|
| Phases | {count} |
| Plans completed | {completed}/{total} |
| Requirements satisfied | {count} |
| Key files | {count} created/modified |
 
## Phase Outcomes
| Phase | Name | Plans | Key Deliverable |
|-------|------|-------|-----------------|
| {N} | {name} | {count} | {one-line from SUMMARY} |
...
 
## Key Decisions
-{decision 1}
-{decision 2}
...
 
## Files Created
-{list of key files created across all phases, grouped by type}
 
## Archive Location
.planning/archive/milestone-{N}/

Step 1: Read ROADMAP.md
 
Step 2: Find the milestone's ### heading
 
Step 3: Update Status from "In Progress" to "Complete"
 
Step 4: Add Completed field with today's date:
  - **Completed**: {YYYY-MM-DD}
 
Step 5: Write updated ROADMAP.md

Step 1: Read STATE.md
 
Step 2: Add or update a ## Milestones section
  - Place after Recent Decisions section
  - Add entry: - Milestone {N}: {name} — Complete ({YYYY-MM-DD})
  - If section already exists: append the new milestone entry
 
Step 3: Write updated STATE.md

Step 1: Verify milestone status
  - Read ROADMAP.md ## Milestones section
  - Find the target milestone
  - Status must be "Complete" (not Pending, In Progress, or Archived)
  - If Pending or In Progress: report "Milestone {N} is not complete. Complete it first."
  - If Archived: report "Milestone {N} is already archived at .planning/archive/milestone-{N}/"
 
Step 2: Verify milestone summary exists
  - Check .planning/milestones/MILESTONE-{N}.md exists
  - If missing: run completion first (Section 3) to generate the summary
 
Step 3: Verify phase directories exist
  - For each phase in the milestone's range:
    - Check .planning/phases/{NN-name}/ exists
  - If some are missing: report which are missing, ask whether to proceed with partial archive

Step 1: Create archive directory
  - Create .planning/archive/ if it doesn't exist
  - Create .planning/archive/milestone-{N}/ directory
  - If .planning/archive/milestone-{N}/ already exists:
    Ask user whether to continue (move remaining dirs) or abort
 
Step 2: Move phase directories
  For each phase in the milestone's range:
  - Source: .planning/phases/{NN-name}/
  - Destination: .planning/archive/milestone-{N}/{NN-name}/
  - Move the entire directory (preserving all files: CONTEXT.md, PLAN.md, SUMMARY.md, UAT.md)
 
Step 3: Verify moves
  For each moved phase:
  - Confirm destination directory exists
  - Confirm source directory is gone
  - If any move failed: report the failure, continue with remaining phases

ROADMAP.md updates:
  1. Read ROADMAP.md
  2. Update the milestone's Status from "Complete" to "Archived"
  3. In the Progress table, append " (Archived)" to the Status of each archived phase
     Example: "Complete" becomes "Complete (Archived)"
  4. Write updated ROADMAP.md
 
STATE.md updates:
  1. Read STATE.md
  2. Condense Phase Results sections for archived phases:
     Replace each ## Phase {N} Results block with:
       ## Phase {N} Results — Archived
       See .planning/milestones/MILESTONE-{M}.md and .planning/archive/milestone-{M}/{NN-name}/
  3. Update the Milestones section:
     Change: - Milestone {N}: {name} — Complete ({date})
     To:     - Milestone {N}: {name} — Archived ({date})
  4. Write updated STATE.md
 
Milestone summary updates:
  1. Read .planning/milestones/MILESTONE-{N}.md
  2. Add to the Archive Location section:
     Archived on {YYYY-MM-DD}
  3. Write updated milestone summary

phases_complete = count of phases in range with Status = "Complete" in ROADMAP.md Progress table
phases_total = end - start + 1 (inclusive range)
percentage = floor((phases_complete / phases_total) * 100)

plans_complete = sum of Completed column for phases in range from ROADMAP.md Progress table
plans_total = sum of Plans column for phases in range
plan_percentage = floor((plans_complete / plans_total) * 100)