name	complete-milestone
description	将已发布版本（v1.0、v1.1、v2.0）标记为完成。在 MILESTONES.md 中创建历史记录，执行 PROJECT.md 演进审查，重组 ROADMAP.md，并在 git 中打标签。

将已发布版本（v1.0、v1.1、v2.0）标记为完成。在 MILESTONES.md 中创建历史记录，执行完整的 PROJECT.md 演进审查，重组 ROADMAP.md，并在 git 中打标签。

<required_reading>

Read these files NOW:

templates/milestone.md
templates/milestone-archive.md
.gsd/ROADMAP.md
.gsd/REQUIREMENTS.md
.gsd/PROJECT.md

</required_reading>

<archival_behavior>

When a milestone completes, this workflow:

Extracts full milestone details to .gsd/milestones/v[X.Y]-ROADMAP.md
Archives requirements to .gsd/milestones/v[X.Y]-REQUIREMENTS.md
Updates ROADMAP.md to replace milestone details with one-line summary
Deletes REQUIREMENTS.md (fresh one created for next milestone)
Performs full PROJECT.md evolution review
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:

"What This Is" accuracy:
- Read current description
- Compare to what was actually built
- Update if the product has meaningfully changed
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
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
Context update:
- Current codebase state (LOC, tech stack)
- User feedback themes (if any)
- Known issues or technical debt to address
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
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:

Create archive file path: .gsd/milestones/v[X.Y]-ROADMAP.md
Read ~/.gsd/templates/milestone-archive.md template
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
Extract data from PROJECT.md:
- Key decisions made during this milestone
- Requirements that were validated
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
Write filled template to .gsd/milestones/v[X.Y]-ROADMAP.md
Delete ROADMAP.md (fresh one created for next milestone):
```
rm .gsd/ROADMAP.md
```
Verify archive exists:
```
ls .gsd/milestones/v[X.Y]-ROADMAP.md
```

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:

Read current REQUIREMENTS.md:
```
cat .gsd/REQUIREMENTS.md
```
Create archive file: .gsd/milestones/v[X.Y]-REQUIREMENTS.md
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

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_

Delete original REQUIREMENTS.md:
```
rm .gsd/REQUIREMENTS.md
```

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 HumanAgent MCP (HumanAgent_Chat):

HumanAgent MCP (HumanAgent_Chat)([
  {
    question: "How should branches be handled?",
    header: "Branches",
    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:

</success_criteria>