<purpose>

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.

</purpose>

<required_reading>

1. `.rcode/templates/milestone.md` (if present — otherwise inline templates below)
2. `.rcode/templates/milestone-archive.md` (if present — otherwise inline templates below)
3. `.planning/ROADMAP.md`
4. `.planning/REQUIREMENTS.md`
5. `.planning/PROJECT.md`

</required_reading>

<output_format>

Open with banner:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 rcode ► COMPLETE MILESTONE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Per-step banners: `rcode ► VERIFY READINESS`, `rcode ► ARCHIVE MILESTONE`, `rcode ► EVOLVE PROJECT.md`, `rcode ► TAG RELEASE`.

Closing banner: `rcode ► MILESTONE v[X.Y] COMPLETE 🎉`.

</output_format>

<archival_behavior>

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** — 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.

</archival_behavior>

<process>

<step name="verify_readiness">

## Step 1 — Verify readiness

Read `.planning/ROADMAP.md` directly and parse phase statuses. Use this to verify:
- Which phases belong to this milestone?
- All phases complete (all plans have summaries)? Check for `SUMMARY.md` in each phase directory.
- progress percent should be 100%.

```bash
ls -1 .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
ls -1 .planning/phases/*/*-SPRINT.md 2>/dev/null | wc -l
```

**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 via AskUserQuestion:
1. **Proceed anyway** — mark milestone complete with known gaps
2. **Run audit first** — `/rcode-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.

<config-check>

```bash
node .rcode/bin/rcode-tools.cjs config 2>/dev/null || true
```

</config-check>

<if mode="yolo">

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

Proceed to gather_stats.

</if>

<if mode="interactive" OR="custom with gates.confirm_milestone_scope true">

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

Use AskUserQuestion with options:
- "Ship it" — proceed
- "Wait" — stop, user returns when ready
- "Adjust scope" — ask which phases to include

</if>

</step>

<step name="gather_stats">

## Step 2 — Gather stats

Calculate milestone statistics:

```bash
git log --oneline --grep="feat(" | head -20
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
find . \
  -not -path '*/node_modules/*' \
  -not -path '*/dist/*' \
  -not -path '*/.next/*' \
  -not -path '*/.venv/*' \
  -not -path '*/__pycache__/*' \
  \( -name "*.swift" -o -name "*.ts" -o -name "*.py" -o -name "*.tsx" -o -name "*.js" \) \
  | head -500 | xargs wc -l 2>/dev/null | tail -1 || 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)
```

</step>

<step name="extract_accomplishments">

## Step 3 — Extract accomplishments

Extract one-liners from SUMMARY.md files:

```bash
for summary in .planning/phases/*/*-SUMMARY.md .planning/phases/*/SUMMARY.md; do
  [ -e "$summary" ] || continue
  # Read first H1 or one-liner line; fallback to first non-empty paragraph
  head -40 "$summary"
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]
```

</step>

<step name="create_milestone_entry">

## Step 4 — Create MILESTONES.md entry

Append (or create) `.planning/MILESTONES.md` with an entry for this milestone. Use this structure:

```markdown
## v[X.Y] — [Milestone Name]

**Shipped:** [date]
**Phases:** [count] ([numbers])
**Plans:** [count]
**Tasks:** [count]

### Delivered

[One paragraph summary of what shipped]

### Key Accomplishments
- [Item 1]
- [Item 2]
- [Item 3]
- [Item 4]
- [Item 5]

### Stats
- LOC: [count] ([language])
- Files modified: [count]
- Timeline: [days] days
- Git range: [first] → [last]

### Known Gaps
[Only if requirements incomplete — list REQ-IDs and descriptions]
```

Write with the Write tool (append-preserving — Read MILESTONES.md first if it exists).

</step>

<step name="evolve_project_full_review">

## Step 5 — Evolve PROJECT.md (full review)

Full PROJECT.md evolution review at milestone completion.

Read all phase summaries (capped to first 30 lines each, max 20 files):

```bash
find .planning/phases/ -maxdepth 3 \( -name '*-SUMMARY.md' -o -name 'SUMMARY.md' \) | head -20 | while IFS= read -r f; do
  echo "=== $f ===" && head -30 "$f"
done
```

**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 with the Edit tool. Update "Last updated" footer:

```markdown
---
*Last updated: [date] after v[X.Y] milestone*
```

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

Before:

```markdown
## 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:

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

</step>

<step name="archive_milestone">

## Step 6 — Archive milestone files

Create archive directory and copy files:

```bash
VERSION="v[X.Y]"
mkdir -p .planning/milestones
cp .planning/ROADMAP.md ".planning/milestones/${VERSION}-ROADMAP.md"
cp .planning/REQUIREMENTS.md ".planning/milestones/${VERSION}-REQUIREMENTS.md"
# Archive milestone audit if present
if [ -f ".planning/MILESTONE-AUDIT.md" ]; then
  mv .planning/MILESTONE-AUDIT.md ".planning/milestones/${VERSION}-MILESTONE-AUDIT.md"
fi
```

Prepend an archive header to each archived file (using Edit):

```markdown
---
archived: [ISO-DATE]
milestone: v[X.Y]
status: completed
---

# [Original Title] (Archived v[X.Y])

```

Verify: `✓ Milestone archived to .planning/milestones/`

**Phase archival (optional):** Ask the user via 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:

```bash
ARCHIVE_DIR=".planning/milestones/${VERSION}-phases"
mkdir -p "$ARCHIVE_DIR"
find .planning/phases -mindepth 1 -maxdepth 1 -type d -exec mv {} "$ARCHIVE_DIR/" \;
```

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

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

</step>

<step name="reorganize_roadmap_and_delete_originals">

## Step 7 — Reorganize ROADMAP.md and delete originals

After archival, reorganize ROADMAP.md with milestone groupings, then delete originals.

**Reorganize ROADMAP.md** — group completed milestone phases:

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

**Then delete originals** (ROADMAP.md has been reorganized in place above; REQUIREMENTS.md is deleted for a fresh milestone):

```bash
rm .planning/REQUIREMENTS.md
```

(ROADMAP.md is retained in its reorganized form. Do NOT delete it — deletion is reserved for between-milestone resets via `/rcode-new-milestone`.)

</step>

<step name="write_retrospective">

## Step 8 — Write retrospective

**Append to living retrospective:**

Check for existing retrospective:
```bash
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 inline template below.

**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:**

```markdown
## 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.

</step>

<step name="update_state">

## Step 9 — Update STATE.md

Update STATE.md to reflect milestone completion using Edit:

**Project Reference:**

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

Record the milestone completion via decision log:

```bash
node .rcode/bin/rcode-tools.cjs state add-decision "Completed milestone v[X.Y] — [Name]"
```

</step>

<step name="handle_branches">

## Step 10 — Handle branches

Check branching strategy and offer merge options.

```bash
CONFIG=$(node .rcode/bin/rcode-tools.cjs config 2>/dev/null || echo '{}')
# Extract branching_strategy, phase_branch_template, milestone_branch_template, commit_docs from config
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
BASE_BRANCH="${BASE_BRANCH:-main}"
```

**If branching_strategy is "none":** Skip to git_tag.

**For "phase" strategy:**

```bash
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:**

```bash
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}
```

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

**Squash merge:**

```bash
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"
    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"
  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:**

```bash
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"
    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"
  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:**

```bash
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".

</step>

<step name="git_tag">

## Step 11 — Git tag

Create git tag:

```bash
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]"

**DO NOT push the tag.** Report instead:

```
Tag created locally: v[X.Y]

To push the tag when ready:
  git push origin v[X.Y]

(Pushes require explicit user approval — see AGENTS.md.)
```

</step>

<step name="git_commit_milestone">

## Step 12 — Commit milestone

Commit milestone completion. Guard against `.planning/` being gitignored:

```bash
VERSION="v[X.Y]"
git add \
  .planning/milestones/${VERSION}-ROADMAP.md \
  .planning/milestones/${VERSION}-REQUIREMENTS.md \
  .planning/milestones/${VERSION}-MILESTONE-AUDIT.md \
  .planning/MILESTONES.md \
  .planning/PROJECT.md \
  .planning/STATE.md \
  .planning/RETROSPECTIVE.md \
  .planning/ROADMAP.md 2>/dev/null \
&& git commit -m "chore: complete ${VERSION} milestone" 2>/dev/null \
|| echo "ℹ .planning/ gitignored — milestone files written, not committed"
```

Confirm: "Committed: chore: complete v[X.Y] milestone" (or the gitignored notice).

</step>

<step name="offer_next">

## Step 13 — Offer next

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 rcode ► MILESTONE v[X.Y] 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] (local — push when ready)

---

## ▶ Next Up

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

`/clear` then:

`/rcode-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 locally (v[X.Y]) — NOT pushed (awaits explicit user approval per AGENTS.md)
- [ ] Milestone commit made (guarded for gitignored `.planning/`)
- [ ] 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 (/rcode-new-milestone)

</success_criteria>
</output>

## Next Up

- `/rcode-new-milestone` — start the next milestone cycle
- `/rcode-milestone-summary` — generate a narrative summary of the completed milestone
