complete-milestone

name	complete-milestone
description	Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record in MILESTONES.md, performs PROJECT.md evolution review, reorganizes ROADMAP.md, and tags the release in git.

Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.

This is the ritual that separates "development" from "shipped."

<required_reading>

Read these files NOW:

1. templates/milestone.md
2. templates/milestone-archive.md
3. .gsd/ROADMAP.md
4. .gsd/REQUIREMENTS.md
5. .gsd/PROJECT.md

</required_reading>

<archival_behavior>

When a milestone completes, this workflow:

1. Extracts full milestone details to .gsd/milestones/v[X.Y]-ROADMAP.md
2. Archives requirements to .gsd/milestones/v[X.Y]-REQUIREMENTS.md
3. Updates ROADMAP.md to replace milestone details with one-line summary
4. Deletes REQUIREMENTS.md (fresh one created for next milestone)
5. Performs full PROJECT.md evolution review
6. Offers to create next milestone inline

Context Efficiency: Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.

Archive Format:

ROADMAP archive uses templates/milestone-archive.md template with:

• Milestone header (status, phases, date)
• Full phase details from roadmap
• Milestone summary (decisions, issues, technical debt)

REQUIREMENTS archive contains:

• All v1 requirements marked complete with outcomes
• Traceability table with final status
• Notes on any requirements that changed during milestone

</archival_behavior>

Check if milestone is truly complete:

cat .gsd/ROADMAP.md
ls .gsd/phases/*/SUMMARY.md 2>/dev/null | wc -l

Questions to ask:

• Which phases belong to this milestone?
• Are all those phases complete (all plans have summaries)?
• Has the work been tested/validated?
• Is this ready to ship/tag?

Present:

Milestone: [Name from user, e.g., "v1.0 MVP"]

Appears to include:
- Phase 1: Foundation (2/2 plans complete)
- Phase 2: Authentication (2/2 plans complete)
- Phase 3: Core Features (3/3 plans complete)
- Phase 4: Polish (1/1 plan complete)

Total: 4 phases, 8 plans, all complete

cat .gsd/config.json 2>/dev/null

⚡ Auto-approved: Milestone scope verification

[Show breakdown summary without prompting]

Proceeding to stats gathering...

Proceed directly to gather_stats step.

Ready to mark this milestone as shipped?
(yes / wait / adjust scope)

Wait for confirmation.

If "adjust scope": Ask which phases should be included. If "wait": Stop, user will return when ready.

Calculate milestone statistics:

# Count phases and plans in milestone
# (user specified or detected from roadmap)

# Find git range
git log --oneline --grep="feat(" | head -20

# Count files modified in range
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1

# Count LOC (adapt to language)
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null

# Calculate timeline
git log --format="%ai" FIRST_COMMIT | tail -1  # Start date
git log --format="%ai" LAST_COMMIT | head -1   # End date

Present summary:

Milestone Stats:
- Phases: [X-Y]
- Plans: [Z] total
- Tasks: [N] total (estimated from phase summaries)
- Files modified: [M]
- Lines of code: [LOC] [language]
- Timeline: [Days] days ([Start] → [End])
- Git range: feat(XX-XX) → feat(YY-YY)

Read all phase SUMMARY.md files in milestone range:

cat .gsd/phases/01-*/01-*-SUMMARY.md
cat .gsd/phases/02-*/02-*-SUMMARY.md
# ... for each phase in milestone

From summaries, extract 4-6 key accomplishments.

Present:

Key accomplishments for this milestone:
1. [Achievement from phase 1]
2. [Achievement from phase 2]
3. [Achievement from phase 3]
4. [Achievement from phase 4]
5. [Achievement from phase 5]

Create or update .gsd/MILESTONES.md.

If file doesn't exist:

# Project Milestones: [Project Name from PROJECT.md]

[New entry]

If exists, prepend new entry (reverse chronological order).

Use template from templates/milestone.md:

## v[Version] [Name] (Shipped: YYYY-MM-DD)

**Delivered:** [One sentence from user]

**Phases completed:** [X-Y] ([Z] plans total)

**Key accomplishments:**

- [List from previous step]

**Stats:**

- [Files] files created/modified
- [LOC] lines of [language]
- [Phases] phases, [Plans] plans, [Tasks] tasks
- [Days] days from [start milestone or start project] to ship

**Git range:** `feat(XX-XX)` → `feat(YY-YY)`

**What's next:** [Ask user: what's the next goal?]

---

Perform full PROJECT.md evolution review at milestone completion.

Read all phase summaries in this milestone:

cat .gsd/phases/*-*/*-SUMMARY.md

Full review checklist:

1. "What This Is" accuracy:

   • Read current description
   • Compare to what was actually built
   • Update if the product has meaningfully changed

2. Core Value check:

   • Is the stated core value still the right priority?
   • Did shipping reveal a different core value?
   • Update if the ONE thing has shifted

3. Requirements audit:

   Validated section:

   • All Active requirements shipped in this milestone → Move to Validated
   • Format: - ✓ [Requirement] — v[X.Y]

   Active section:

   • Remove requirements that moved to Validated
   • Add any new requirements for next milestone
   • Keep requirements that weren't addressed yet

   Out of Scope audit:

   • Review each item — is the reasoning still valid?
   • Remove items that are no longer relevant
   • Add any requirements invalidated during this milestone

4. Context update:

   • Current codebase state (LOC, tech stack)
   • User feedback themes (if any)
   • Known issues or technical debt to address

5. Key Decisions audit:

   • Extract all decisions from milestone phase summaries
   • Add to Key Decisions table with outcomes where known
   • Mark ✓ Good, ⚠️ Revisit, or — Pending for each

6. Constraints check:

   • Any constraints that changed during development?
   • Update as needed

Update PROJECT.md:

Make all edits inline. Update "Last updated" footer:

---

_Last updated: [date] after v[X.Y] milestone_

Example full evolution (v1.0 → v1.1 prep):

Before:

## What This Is

A real-time collaborative whiteboard for remote teams.

## Core Value

Real-time sync that feels instant.

## Requirements

### Validated

(None yet — ship to validate)

### Active

- [ ] Canvas drawing tools
- [ ] Real-time sync < 500ms
- [ ] User authentication
- [ ] Export to PNG

### Out of Scope

- Mobile app — web-first approach
- Video chat — use external tools

After v1.0:

## What This Is

A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.

## Core Value

Real-time sync that feels instant.

## Requirements

### Validated

- ✓ Canvas drawing tools — v1.0
- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
- ✓ User authentication — v1.0

### Active

- [ ] Export to PNG
- [ ] Undo/redo history
- [ ] Shape tools (rectangles, circles)

### Out of Scope

- Mobile app — web-first approach, PWA works well
- Video chat — use external tools
- Offline mode — real-time is core value

## Context

Shipped v1.0 with 2,400 LOC TypeScript.
Tech stack: Next.js, Supabase, Canvas API.
Initial user testing showed demand for shape tools.

Step complete when:

• "What This Is" reviewed and updated if needed
• Core Value verified as still correct
• All shipped requirements moved to Validated
• New requirements added to Active for next milestone
• Out of Scope reasoning audited
• Context updated with current state
• All milestone decisions added to Key Decisions
• "Last updated" footer reflects milestone completion

Update .gsd/ROADMAP.md to group completed milestone phases.

Add milestone headers and collapse completed work:

# Roadmap: [Project Name]

## Milestones

- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
- 📋 **v2.0 Redesign** — Phases 7-10 (planned)

## Phases

<details>
<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>

- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD

</details>

### 🚧 v[Next] [Name] (In Progress / Planned)

- [ ] Phase 5: [Name] ([N] plans)
- [ ] Phase 6: [Name] ([N] plans)

## Progress

| Phase             | Milestone | Plans Complete | Status      | Completed  |
| ----------------- | --------- | -------------- | ----------- | ---------- |
| 1. Foundation     | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
| 2. Authentication | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
| 3. Core Features  | v1.0      | 3/3            | Complete    | YYYY-MM-DD |
| 4. Polish         | v1.0      | 1/1            | Complete    | YYYY-MM-DD |
| 5. Security Audit | v1.1      | 0/1            | Not started | -          |
| 6. Hardening      | v1.1      | 0/2            | Not started | -          |

Extract completed milestone details and create archive file.

Process:

1. Create archive file path: .gsd/milestones/v[X.Y]-ROADMAP.md

2. Read ~/.gsd/templates/milestone-archive.md template

3. Extract data from current ROADMAP.md:

   • All phases belonging to this milestone (by phase number range)
   • Full phase details (goals, plans, dependencies, status)
   • Phase plan lists with completion checkmarks

4. Extract data from PROJECT.md:

   • Key decisions made during this milestone
   • Requirements that were validated

5. Fill template {{PLACEHOLDERS}}:

   • {{VERSION}} — Milestone version (e.g., "1.0")
   • {{MILESTONE_NAME}} — From ROADMAP.md milestone header
   • {{DATE}} — Today's date
   • {{PHASE_START}} — First phase number in milestone
   • {{PHASE_END}} — Last phase number in milestone
   • {{TOTAL_PLANS}} — Count of all plans in milestone
   • {{MILESTONE_DESCRIPTION}} — From ROADMAP.md overview
   • {{PHASES_SECTION}} — Full phase details extracted
   • {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
   • {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries

6. Write filled template to .gsd/milestones/v[X.Y]-ROADMAP.md

7. Delete ROADMAP.md (fresh one created for next milestone):

   rm .gsd/ROADMAP.md
   

8. Verify archive exists:

   ls .gsd/milestones/v[X.Y]-ROADMAP.md
   

9. Confirm roadmap archive complete:

   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
   ✅ ROADMAP.md deleted (fresh one for next milestone)
   

Note: Phase directories (.gsd/phases/) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).

Archive requirements and prepare for fresh requirements in next milestone.

Process:

1. Read current REQUIREMENTS.md:

   cat .gsd/REQUIREMENTS.md
   

2. Create archive file: .gsd/milestones/v[X.Y]-REQUIREMENTS.md

3. Transform requirements for archive:

   • Mark all v1 requirements as [x] complete
   • Add outcome notes where relevant (validated, adjusted, dropped)
   • Update traceability table status to "Complete" for all shipped requirements
   • Add "Milestone Summary" section with:
     • Total requirements shipped
     • Any requirements that changed scope during milestone
     • Any requirements dropped and why

4. Write archive file with header:

   # Requirements Archive: v[X.Y] [Milestone Name]
   
   **Archived:** [DATE]
   **Status:** ✅ SHIPPED
   
   This is the archived requirements specification for v[X.Y].
   For current requirements, see `.gsd/REQUIREMENTS.md` (created for next milestone).
   
   ---
   
   [Full REQUIREMENTS.md content with checkboxes marked complete]
   
   ---
   
   ## Milestone Summary
   
   **Shipped:** [X] of [Y] v1 requirements
   **Adjusted:** [list any requirements that changed during implementation]
   **Dropped:** [list any requirements removed and why]
   
   ---
   
   _Archived: [DATE] as part of v[X.Y] milestone completion_
   

5. Delete original REQUIREMENTS.md:

   rm .gsd/REQUIREMENTS.md
   

6. Confirm:

   ✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
   ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
   

Important: The next milestone workflow starts with /new-milestone.md which includes requirements definition. PROJECT.md's Validated section carries the cumulative record across milestones.

Move the milestone audit file to the archive (if it exists):

# Move audit to milestones folder (if exists)
[ -f .gsd/v[X.Y]-MILESTONE-AUDIT.md ] && mv .gsd/v[X.Y]-MILESTONE-AUDIT.md .gsd/milestones/

Confirm:

✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md

(Skip silently if no audit file exists — audit is optional)

Update STATE.md to reflect milestone completion.

Project Reference:

## Project Reference

See: .gsd/PROJECT.md (updated [today])

**Core value:** [Current core value from PROJECT.md]
**Current focus:** [Next milestone or "Planning next milestone"]

Current Position:

Phase: [Next phase] of [Total] ([Phase name])
Plan: Not started
Status: Ready to plan
Last activity: [today] — v[X.Y] milestone complete

Progress: [updated progress bar]

Accumulated Context:

• Clear decisions summary (full log in PROJECT.md)
• Clear resolved blockers
• Keep open blockers for next milestone

Check if branching was used and offer merge options.

Check branching strategy:

# Get branching strategy from config
BRANCHING_STRATEGY=$(cat .gsd/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "none")

If strategy is "none": Skip to git_tag step.

For "phase" strategy — find phase branches:

PHASE_BRANCH_TEMPLATE=$(cat .gsd/config.json 2>/dev/null | grep -o '"phase_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/phase-{phase}-{slug}")

# Extract prefix from template (before first variable)
BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')

# Find all phase branches for this milestone
PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')

For "milestone" strategy — find milestone branch:

MILESTONE_BRANCH_TEMPLATE=$(cat .gsd/config.json 2>/dev/null | grep -o '"milestone_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/{milestone}-{slug}")

# Extract prefix from template
BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')

# Find milestone branch
MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)

If no branches found: Skip to git_tag step.

If branches exist — present merge options:

## Git Branches Detected

Branching strategy: {phase/milestone}

Branches found:
{list of branches}

Options:
1. **Merge to main** — Merge branch(es) to main
2. **Delete without merging** — Branches already merged or not needed
3. **Keep branches** — Leave for manual handling

Use ask_questions tool (functions.ask_questions):

ask_questions (functions.ask_questions)([
  {
   questions: [
    header: "Branches",
    question: "How should branches be handled?",
    multiSelect: false,
    options: [
      { label: "Squash merge (Recommended)", description: "Squash all commits into one clean commit on main" },
      { label: "Merge with history", description: "Preserve all individual commits (--no-ff)" },
      { label: "Delete without merging", description: "Branches already merged or not needed" },
      { label: "Keep branches", description: "Leave branches for manual handling later" }
    ]
   ]
  }
])

If "Squash merge":

CURRENT_BRANCH=$(git branch --show-current)
git checkout main

# For phase strategy - squash merge each phase branch
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
  for branch in $PHASE_BRANCHES; do
    echo "Squash merging $branch..."
    git merge --squash "$branch"
    git commit -m "feat: $branch for v[X.Y]"
  done
fi

# For milestone strategy - squash merge milestone branch
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
  echo "Squash merging $MILESTONE_BRANCH..."
  git merge --squash "$MILESTONE_BRANCH"
  git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
fi

git checkout "$CURRENT_BRANCH"

Report: "Squash merged branches to main"

If "Merge with history":

CURRENT_BRANCH=$(git branch --show-current)
git checkout main

# For phase strategy - merge each phase branch
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
  for branch in $PHASE_BRANCHES; do
    echo "Merging $branch..."
    git merge --no-ff "$branch" -m "Merge branch '$branch' for v[X.Y]"
  done
fi

# For milestone strategy - merge milestone branch
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
  echo "Merging $MILESTONE_BRANCH..."
  git merge --no-ff "$MILESTONE_BRANCH" -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
fi

git checkout "$CURRENT_BRANCH"

Report: "Merged branches to main with full history"

If "Delete without merging":

if [ "$BRANCHING_STRATEGY" = "phase" ]; then
  for branch in $PHASE_BRANCHES; do
    git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
  done
fi

if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
  git branch -d "$MILESTONE_BRANCH" 2>/dev/null || git branch -D "$MILESTONE_BRANCH"
fi

Report: "Deleted branches"

If "Keep branches":

Report: "Branches preserved for manual handling"

Create git tag for milestone:

git tag -a v[X.Y] -m "$(cat <<'EOF'
v[X.Y] [Name]

Delivered: [One sentence]

Key accomplishments:
- [Item 1]
- [Item 2]
- [Item 3]

See .gsd/MILESTONES.md for full details.
EOF
)"

Confirm: "Tagged: v[X.Y]"

Ask: "Push tag to remote? (y/n)"

If yes:

git push origin v[X.Y]

Commit milestone completion including archive files and deletions.

Check planning config:

COMMIT_PLANNING_DOCS=$(cat .gsd/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .gsd 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=false: Skip git operations

If COMMIT_PLANNING_DOCS=true (default):

# Stage archive files (new)
git add .gsd/milestones/v[X.Y]-ROADMAP.md
git add .gsd/milestones/v[X.Y]-REQUIREMENTS.md
git add .gsd/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true

# Stage updated files
git add .gsd/MILESTONES.md
git add .gsd/PROJECT.md
git add .gsd/STATE.md

# Stage deletions
git add -u .gsd/

# Commit with descriptive message
git commit -m "$(cat <<'EOF'
chore: complete v[X.Y] milestone

Archived:
- milestones/v[X.Y]-ROADMAP.md
- milestones/v[X.Y]-REQUIREMENTS.md
- milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)

Deleted (fresh for next milestone):
- ROADMAP.md
- REQUIREMENTS.md

Updated:
- MILESTONES.md (new entry)
- PROJECT.md (requirements → Validated)
- STATE.md (reset for next milestone)

Tagged: v[X.Y]
EOF
)"

Confirm: "Committed: chore: complete v[X.Y] milestone"

✅ Milestone v[X.Y] [Name] complete

Shipped:
- [N] phases ([M] plans, [P] tasks)
- [One sentence of what shipped]

Archived:
- milestones/v[X.Y]-ROADMAP.md
- milestones/v[X.Y]-REQUIREMENTS.md

Summary: .gsd/MILESTONES.md
Tag: v[X.Y]

---

## ▶ Next Up

**Start Next Milestone** — questioning → research → requirements → roadmap

`/new-milestone.md`

<sub>`/clear` first → fresh context window</sub>

---

<milestone_naming>

Version conventions:

• v1.0 — Initial MVP
• v1.1, v1.2, v1.3 — Minor updates, new features, fixes
• v2.0, v3.0 — Major rewrites, breaking changes, significant new direction

Name conventions:

• v1.0 MVP
• v1.1 Security
• v1.2 Performance
• v2.0 Redesign
• v2.0 iOS Launch

Keep names short (1-2 words describing the focus).

</milestone_naming>

<what_qualifies>

Create milestones for:

• Initial release (v1.0)
• Public releases
• Major feature sets shipped
• Before archiving planning

Don't create milestones for:

• Every phase completion (too granular)
• Work in progress (wait until shipped)
• Internal dev iterations (unless truly shipped internally)

If uncertain, ask: "Is this deployed/usable/shipped in some form?" If yes → milestone. If no → keep working.

</what_qualifies>

<success_criteria>

Milestone completion is successful when:

• MILESTONES.md entry created with stats and accomplishments
• PROJECT.md full evolution review completed
• All shipped requirements moved to Validated in PROJECT.md
• Key Decisions updated with outcomes
• ROADMAP.md reorganized with milestone grouping
• Roadmap archive created (milestones/v[X.Y]-ROADMAP.md)
• Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
• REQUIREMENTS.md deleted (fresh for next milestone)
• STATE.md updated with fresh project reference
• Git tag created (v[X.Y])
• Milestone commit made (includes archive files and deletion)
• User knows next step (/new-milestone.md)

</success_criteria>