Gsd Complete Milestone

Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone. Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.

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

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

When a milestone completes:

1. Extract full milestone details to .planning/milestones/v[X.Y]-ROADMAP.md
2. Archive requirements to .planning/milestones/v[X.Y]-REQUIREMENTS.md
3. Update ROADMAP.md — replace milestone details with one-line summary
4. Delete REQUIREMENTS.md (fresh one for next milestone)
5. Perform full PROJECT.md evolution review
6. Offer to create next milestone inline
7. Archive UI artifacts (*-UI-SPEC.md, *-UI-REVIEW.md) alongside other phase documents
8. Clean up .planning/ui-reviews/ screenshot files (binary assets, never archived)

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

ROADMAP archive uses templates/milestone-archive.md — includes milestone header (status, phases, date), full phase details, milestone summary (decisions, issues, tech debt).

REQUIREMENTS archive contains all requirements marked complete with outcomes, traceability table with final status, notes on changed requirements.

Use roadmap analyze for comprehensive readiness check:

ROADMAP=$(node "$GSD_TOOLS" roadmap analyze)

This returns all phases with plan/summary counts and disk status. Use this to verify:

• Which phases belong to this milestone?
• All phases complete (all plans have summaries)? Check disk_status === 'complete' for each.
• progress_percent should be 100%.

Requirements completion check (REQUIRED before presenting):

Parse REQUIREMENTS.md traceability table:

• Count total v1 requirements vs checked-off ([x]) requirements
• Identify any non-Complete rows in the traceability table

Present:

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

Includes:
- 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: {phase_count} phases, {total_plans} plans, all complete
Requirements: {N}/{M} v1 requirements checked off

If requirements incomplete (N < M):

⚠ Unchecked Requirements:

- [ ] {REQ-ID}: {description} (Phase {X})
- [ ] {REQ-ID}: {description} (Phase {Y})

MUST present 3 options:

1. Proceed anyway — mark milestone complete with known gaps
2. Run audit first — /gsd-audit-milestone to assess gap severity
3. Abort — return to development

If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md under ### Known Gaps with REQ-IDs and descriptions.

cat .planning/config.json 2>/dev/null || true

⚡ Auto-approved: Milestone scope verification
[Show breakdown summary without prompting]
Proceeding to stats gathering...

Proceed to gather_stats.

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

Wait for confirmation.

• "adjust scope": Ask which phases to include.
• "wait": Stop, user returns when ready.

Calculate milestone statistics:

git log --oneline --grep="feat(" | head -20
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null || true
git log --format="%ai" FIRST_COMMIT | tail -1
git log --format="%ai" LAST_COMMIT | head -1

Present:

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

Extract one-liners from SUMMARY.md files using summary-extract:

# For each phase in milestone, extract one-liner
for summary in .planning/phases/*-*/*-SUMMARY.md; do
  [ -e "$summary" ] || continue
  node "$GSD_TOOLS" summary-extract "$summary" --fields one_liner --pick one_liner
done

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]

Note: MILESTONES.md entry is now created automatically by gsd-tools milestone complete in the archive_milestone step. The entry includes version, date, phase/plan/task counts, and accomplishments extracted from SUMMARY.md files.

If additional details are needed (e.g., user-provided "Delivered" summary, git range, LOC stats), add them manually after the CLI creates the base entry.

Full PROJECT.md evolution review at milestone completion.

Read all phase summaries:

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

Full review checklist:

1. "What This Is" accuracy:

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

2. Core Value check:

   • 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 this milestone → Move to Validated
   • Format: - ✓ [Requirement] — v[X.Y]

   Active section:

   • Remove requirements moved to Validated
   • Add new requirements for next milestone
   • Keep unaddressed requirements

   Out of Scope audit:

   • Review each item — reasoning still valid?
   • Remove irrelevant items
   • Add requirements invalidated during milestone

4. Context update:

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

5. Key Decisions audit:

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

6. Constraints check:

   • Any constraints changed during development? Update as needed

Update PROJECT.md 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 .planning/ROADMAP.md — group completed milestone phases:

# 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 | -          |

Delegate archival to gsd-tools:

ARCHIVE=$(node "$GSD_TOOLS" milestone complete "v[X.Y]" --name "[Milestone Name]")

The CLI handles:

• Creating .planning/milestones/ directory
• Archiving ROADMAP.md to milestones/v[X.Y]-ROADMAP.md
• Archiving REQUIREMENTS.md to milestones/v[X.Y]-REQUIREMENTS.md with archive header
• Moving audit file to milestones if it exists
• Creating/appending MILESTONES.md entry with accomplishments from SUMMARY.md files
• Updating STATE.md (status, last activity)

Extract from result: version, date, phases, plans, tasks, accomplishments, archived.

Verify: ✅ Milestone archived to .planning/milestones/

Phase archival (optional): After archival completes, ask the user:

AskUserQuestion(header="Archive Phases", question="Archive phase directories to milestones/?", options: "Yes — move to milestones/v[X.Y]-phases/" | "Skip — keep phases in place")

If "Yes": move phase directories to the milestone archive:

mkdir -p .planning/milestones/v[X.Y]-phases
# For each phase directory in .planning/phases/:
mv .planning/phases/{phase-dir} .planning/milestones/v[X.Y]-phases/

Verify: ✅ Phase directories archived to .planning/milestones/v[X.Y]-phases/

If "Skip": Phase directories remain in .planning/phases/ as raw execution history. Use /gsd-cleanup later to archive retroactively.

After archival, the AI still handles:

• Reorganizing ROADMAP.md with milestone grouping (requires judgment)
• Full PROJECT.md evolution review (requires understanding)
• Deleting original ROADMAP.md and REQUIREMENTS.md
• These are NOT fully delegated because they require AI interpretation of content

Finalize phase memories for all milestone phases:

Before archiving phase directories, ensure every completed phase has its memory written to Claude Code's auto-memory system. This is a safety net -- the primary write happens at verify-work time. This step catches any phase that was verified but whose memory write was skipped or failed.

# For each phase in this milestone, write memory if not already present
for phase_dir in .planning/phases/*/; do
  PHASE_NUM=$(basename "$phase_dir" | grep -oE '^[0-9]+')
  if [ -n "$PHASE_NUM" ]; then
    node "$GSD_TOOLS" write-phase-memory "$PHASE_NUM" 2>/dev/null || true
  fi
done

This writes project-type memory files into Claude Code's memdir auto-memory directory. Each file uses a stable filename (phase-NN-slug.md) so repeated runs update the same file instead of creating duplicates. The MEMORY.md index is also updated so Claude Code auto-recalls phase outcomes in future sessions.

After milestone complete has archived, reorganize ROADMAP.md with milestone groupings, then delete originals:

Reorganize ROADMAP.md — group completed milestone phases:

# Roadmap: [Project Name]

## Milestones

- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
- 🚧 **v1.1 Security** — Phases 5-6 (in progress)

## 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

</details>

Then delete originals:

rm .planning/ROADMAP.md
rm .planning/REQUIREMENTS.md

Append to living retrospective:

Check for existing retrospective:

ls .planning/RETROSPECTIVE.md 2>/dev/null || true

If exists: Read the file, append new milestone section before the "## Cross-Milestone Trends" section.

If doesn't exist: Create from template at ${CLAUDE_PLUGIN_ROOT}/templates/retrospective.md.

Gather retrospective data:

1. From SUMMARY.md files: Extract key deliverables, one-liners, tech decisions
2. From VERIFICATION.md files: Extract verification scores, gaps found
3. From UAT.md files: Extract test results, issues found
4. From git log: Count commits, calculate timeline
5. From the milestone work: Reflect on what worked and what didn't

Write the milestone section:

## Milestone: v{version} — {name}

**Shipped:** {date}
**Phases:** {phase_count} | **Plans:** {plan_count}

### What Was Built
{Extract from SUMMARY.md one-liners}

### What Worked
{Patterns that led to smooth execution}

### What Was Inefficient
{Missed opportunities, rework, bottlenecks}

### Patterns Established
{New conventions discovered during this milestone}

### Key Lessons
{Specific, actionable takeaways}

### Cost Observations
- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
- Sessions: {count}
- Notable: {efficiency observation}

Update cross-milestone trends:

If the "## Cross-Milestone Trends" section exists, update the tables with new data from this milestone.

Commit:

node "$GSD_TOOLS" commit "docs: update retrospective for v${VERSION}" --files .planning/RETROSPECTIVE.md

Most STATE.md updates were handled by milestone complete, but verify and update remaining fields:

Project Reference:

## Project Reference

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

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

Accumulated Context:

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

Check branching strategy and offer merge options.

Use init milestone-op for context, or load config directly:

INIT=$(node "$GSD_TOOLS" init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

Extract branching_strategy, phase_branch_template, milestone_branch_template, and commit_docs from init JSON.

Detect base branch:

BASE_BRANCH=$(node "$GSD_TOOLS" config-get git.base_branch 2>/dev/null || echo "")
if [ -z "$BASE_BRANCH" ] || [ "$BASE_BRANCH" = "null" ]; then
  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
  BASE_BRANCH="${BASE_BRANCH:-main}"
fi

If "none": Skip to git_tag.

For "phase" strategy:

BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')

For "milestone" strategy:

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

If no branches found: Skip to git_tag.

If branches exist:

## Git Branches Detected

Branching strategy: {phase/milestone}
Branches: {list}

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

AskUserQuestion with options: Squash merge (Recommended), Merge with history, Delete without merging, Keep branches.

Squash merge:

CURRENT_BRANCH=$(git branch --show-current)
git checkout ${BASE_BRANCH}

if [ "$BRANCHING_STRATEGY" = "phase" ]; then
  for branch in $PHASE_BRANCHES; do
    git merge --squash "$branch"
    # Strip .planning/ from staging if commit_docs is false
    if [ "$COMMIT_DOCS" = "false" ]; then
      git reset HEAD .planning/ 2>/dev/null || true
    fi
    git commit -m "feat: $branch for v[X.Y]"
  done
fi

if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
  git merge --squash "$MILESTONE_BRANCH"
  # Strip .planning/ from staging if commit_docs is false
  if [ "$COMMIT_DOCS" = "false" ]; then
    git reset HEAD .planning/ 2>/dev/null || true
  fi
  git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
fi

git checkout "$CURRENT_BRANCH"

Merge with history:

CURRENT_BRANCH=$(git branch --show-current)
git checkout ${BASE_BRANCH}

if [ "$BRANCHING_STRATEGY" = "phase" ]; then
  for branch in $PHASE_BRANCHES; do
    git merge --no-ff --no-commit "$branch"
    # Strip .planning/ from staging if commit_docs is false
    if [ "$COMMIT_DOCS" = "false" ]; then
      git reset HEAD .planning/ 2>/dev/null || true
    fi
    git commit -m "Merge branch '$branch' for v[X.Y]"
  done
fi

if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
  git merge --no-ff --no-commit "$MILESTONE_BRANCH"
  # Strip .planning/ from staging if commit_docs is false
  if [ "$COMMIT_DOCS" = "false" ]; then
    git reset HEAD .planning/ 2>/dev/null || true
  fi
  git commit -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
fi

git checkout "$CURRENT_BRANCH"

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

Keep branches: Report "Branches preserved for manual handling"

Create git tag:

git tag -a v[X.Y] -m "v[X.Y] [Name]

Delivered: [One sentence]

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

See .planning/MILESTONES.md for full details."

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

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

If yes:

git push origin v[X.Y]

Commit milestone completion.

node "$GSD_TOOLS" commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md

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

</step>

<step name="offer_next">

✅ 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: .planning/MILESTONES.md Tag: v[X.Y]

▶ Next Up

Start Next Milestone — questioning → research → requirements → roadmap

/clear then:

/gsd-new-milestone

</step>

</process>

<milestone_naming>

**Version conventions:**
- **v1.0** — Initial MVP
- **v1.1, v1.2** — Minor updates, new features, fixes
- **v2.0, v3.0** — Major rewrites, breaking changes, new direction

**Names:** Short 1-2 words (v1.0 MVP, v1.1 Security, v1.2 Performance, v2.0 Redesign).

</milestone_naming>

<what_qualifies>

**Create milestones for:** Initial release, public releases, major feature sets shipped, before archiving planning.

**Don't create milestones for:** Every phase completion (too granular), work in progress, internal dev iterations (unless truly shipped).

Heuristic: "Is this deployed/usable/shipped?" 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)
- [ ] Requirements completion checked against REQUIREMENTS.md traceability table
- [ ] Incomplete requirements surfaced with proceed/audit/abort options
- [ ] Known gaps recorded in MILESTONES.md if user proceeded with incomplete requirements
- [ ] RETROSPECTIVE.md updated with milestone section
- [ ] Cross-milestone trends updated
- [ ] User knows next step (/gsd-new-milestone)

</success_criteria>