qualia-framework 2.1.0

package/framework/qualia-engine/workflows/complete-milestone.md

@@ -0,0 +1,858 @@
+<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. templates/milestone.md
+2. templates/milestone-archive.md
+3. `.planning/ROADMAP.md`
+4. `.planning/REQUIREMENTS.md`
+5. `.planning/PROJECT.md`
+
+</required_reading>
+
+<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
+
+**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.
+
+</archival_behavior>
+
+<process>
+
+<step name="verify_readiness">
+
+Check milestone completion:
+
+```bash
+cat .planning/ROADMAP.md
+ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
+```
+
+Verify:
+- Which phases belong to this milestone?
+- All phases complete (all plans have summaries)?
+- Work tested/validated?
+- Ready to ship/tag?
+
+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: 4 phases, 8 plans, all complete
+```
+
+<config-check>
+
+```bash
+cat .planning/config.json 2>/dev/null
+```
+
+</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)
+```
+
+Wait for confirmation.
+- "adjust scope": Ask which phases to include.
+- "wait": Stop, user returns when ready.
+
+</if>
+
+</step>
+
+<step name="gather_stats">
+
+Calculate milestone statistics:
+
+```bash
+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
+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">
+
+Extract one-liners from SUMMARY.md files using summary-extract:
+
+```bash
+# For each phase in milestone, extract one-liner
+for summary in .planning/phases/*-*/*-SUMMARY.md; do
+  node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js summary-extract "$summary" --fields one_liner | jq -r '.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]
+```
+
+</step>
+
+<step name="create_milestone_entry">
+
+Create or update `.planning/MILESTONES.md`.
+
+If file doesn't exist, create with project name header. If exists, prepend new entry (reverse chronological).
+
+Use template from `templates/milestone.md`:
+
+```markdown
+## 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] to ship
+
+**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
+
+**What's next:** [Ask user: what's the next goal?]
+
+---
+```
+
+</step>
+
+<step name="evolve_project_full_review">
+
+Full PROJECT.md evolution review at milestone completion.
+
+Read all phase summaries:
+
+```bash
+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:
+
+```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="reorganize_roadmap">
+
+Update `.planning/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 | -          |
+```
+
+</step>
+
+<step name="archive_milestone">
+
+Extract completed milestone details to archive.
+
+1. Create `.planning/milestones/v[X.Y]-ROADMAP.md`
+2. Read `/home/qualia/.claude/qualia-engine/templates/milestone-archive.md` template
+3. Extract from ROADMAP.md: all phases in milestone (by number range), full phase details, plan lists with checkmarks
+4. Extract from PROJECT.md: key decisions, validated requirements
+5. Fill template placeholders: {{VERSION}}, {{MILESTONE_NAME}}, {{DATE}}, {{PHASE_START}}, {{PHASE_END}}, {{TOTAL_PLANS}}, {{MILESTONE_DESCRIPTION}}, {{PHASES_SECTION}}, {{DECISIONS_FROM_PROJECT}}, {{ISSUES_RESOLVED_DURING_MILESTONE}}
+6. Write to `.planning/milestones/v[X.Y]-ROADMAP.md`
+7. Delete ROADMAP.md:
+   ```bash
+   rm .planning/ROADMAP.md
+   ```
+8. Verify:
+   ```bash
+   ls .planning/milestones/v[X.Y]-ROADMAP.md
+   ```
+9. Confirm:
+   ```
+   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
+   ✅ ROADMAP.md deleted (fresh one for next milestone)
+   ```
+
+**Note:** Phase directories (`.planning/phases/`) are NOT deleted — they accumulate across milestones as raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+
+</step>
+
+<step name="archive_requirements">
+
+Archive requirements for next milestone.
+
+1. Read REQUIREMENTS.md:
+   ```bash
+   cat .planning/REQUIREMENTS.md
+   ```
+
+2. Create `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+
+3. Transform: mark all requirements `[x]` complete, add outcome notes, update traceability table to "Complete", add milestone summary (total shipped, scope changes, drops)
+
+4. Write archive with header:
+   ```markdown
+   # Requirements Archive: v[X.Y] [Milestone Name]
+
+   **Archived:** [DATE]
+   **Status:** ✅ SHIPPED
+
+   For current requirements, see `.planning/REQUIREMENTS.md`.
+
+   ---
+
+   [Full REQUIREMENTS.md content with checkboxes marked complete]
+
+   ---
+
+   ## Milestone Summary
+
+   **Shipped:** [X] of [Y] requirements
+   **Adjusted:** [list any that changed]
+   **Dropped:** [list any removed and why]
+
+   ---
+   *Archived: [DATE] as part of v[X.Y] milestone completion*
+   ```
+
+5. Delete original:
+   ```bash
+   rm .planning/REQUIREMENTS.md
+   ```
+
+6. Confirm:
+   ```
+   ✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
+   ✅ REQUIREMENTS.md deleted (fresh one for next milestone)
+   ```
+
+**Note:** Next milestone starts with `/qualia:new-milestone` which includes requirements definition. PROJECT.md's Validated section carries cumulative record across milestones.
+
+</step>
+
+<step name="generate_changelog">
+
+Generate or update CHANGELOG.md at project root.
+
+```bash
+[ -f CHANGELOG.md ] && echo "EXISTS" || echo "NEW"
+```
+
+**New entry format:**
+```markdown
+## [v{VERSION}] — YYYY-MM-DD
+
+### What Shipped
+- {accomplishment 1 — from extract_accomplishments}
+- {accomplishment 2}
+- {accomplishment 3}
+- {accomplishment 4}
+
+### By Phase
+- Phase {X}: {one-liner from SUMMARY.md}
+- Phase {Y}: {one-liner}
+
+### Stats
+{phases} phases, {plans} plans, {files} files changed, {days} days
+```
+
+**Sources:** Reuse `accomplishments[]` from extract_accomplishments step and phase one-liners from gather_stats.
+
+**If CHANGELOG.md exists:** Prepend new entry (newest first). Keep all previous entries.
+**If new:** Create with `# Changelog\n\n` header then the entry.
+
+Include CHANGELOG.md in the final git commit file list.
+
+</step>
+
+<step name="archive_audit">
+
+Move audit file to archive (if exists). Use init context or check directly:
+
+```bash
+# Check if audit file exists
+[ -f ".planning/v[X.Y]-MILESTONE-AUDIT.md" ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
+```
+
+Confirm: `✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md`
+
+Skip silently if no audit file — audit is optional.
+
+</step>
+
+<step name="archive_and_reset_state">
+
+Archive current STATE.md decisions into the milestone archive, then reset for the next milestone.
+This prevents STATE.md from growing unbounded across milestones.
+
+**1. Archive STATE.md to milestone directory:**
+
+```bash
+cp .planning/STATE.md .planning/milestones/v[X.Y]-STATE.md
+```
+
+Confirm: `✅ STATE.md archived to milestones/v[X.Y]-STATE.md`
+
+**2. Reset STATE.md to a clean template:**
+
+Preserve the project header and position section but clear accumulated decisions, blockers, and quick tasks.
+
+Write a fresh STATE.md:
+
+```markdown
+# State: [Project Name]
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated [today])
+
+**Core value:** [Current core value from PROJECT.md]
+**Current focus:** Planning next milestone
+
+## Current Position
+
+Phase: [Next phase number] of [Total] (Not started)
+Plan: Not started
+Status: Ready to plan
+Last activity: [today] — v[X.Y] milestone complete, STATE.md reset
+
+Progress: [updated progress bar]
+
+## Accumulated Context
+
+### Key Decisions
+| # | Decision | Rationale | Date |
+|---|----------|-----------|------|
+| | | | |
+
+### Blockers/Concerns
+(None — fresh milestone)
+
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+```
+
+Note: The full decision history is preserved in:
+- `.planning/milestones/v[X.Y]-STATE.md` (raw archive)
+- `.planning/PROJECT.md` Key Decisions table (curated)
+
+</step>
+
+<step name="update_state">
+
+Update STATE.md for milestone completion.
+
+**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"]
+```
+
+**Current Position:**
+
+```markdown
+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
+
+</step>
+
+<step name="handle_branches">
+
+Check branching strategy and offer merge options.
+
+Use `init milestone-op` for context, or load config directly:
+
+```bash
+INIT=$(node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js init execute-phase "1")
+```
+
+Extract `branching_strategy`, `phase_branch_template`, `milestone_branch_template` from init JSON.
+
+**If "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}
+
+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:**
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+git checkout main
+
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    git merge --squash "$branch"
+    git commit -m "feat: $branch for v[X.Y]"
+  done
+fi
+
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  git merge --squash "$MILESTONE_BRANCH"
+  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 main
+
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    git merge --no-ff "$branch" -m "Merge branch '$branch' for v[X.Y]"
+  done
+fi
+
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  git merge --no-ff "$MILESTONE_BRANCH" -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="production_deploy">
+
+**Deploy the milestone to production before tagging.**
+
+This ensures the git tag marks code that's actually live — not just code that's done locally.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Qualia ► PRODUCTION DEPLOY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Detect project type from PROJECT.md/package.json:**
+
+| Project Type | Deploy Command |
+|-------------|----------------|
+| Next.js / Vercel | `/ship-website` |
+| AI Agent | `/ship-agent` |
+| Voice Agent | `/ship-voice` |
+| Mobile App (Expo) | `eas build` + `eas submit` |
+| Generic | `/ship` |
+
+Use AskUserQuestion:
+- header: "Deploy"
+- question: "Deploy v{version} to production now?"
+- options:
+  - "Deploy now (Recommended)" — Run the full ship pipeline (quality gates → preview → production → verify)
+  - "Already deployed" — I deployed manually, just tag and archive
+  - "Skip deploy" — Tag and archive without deploying (e.g., staging only)
+
+**If "Deploy now":**
+
+Run the appropriate `/ship-*` command. This handles:
+- Quality gates (tsc, eslint, build)
+- Preview deploy + verification
+- Production deploy
+- Post-deploy verification (HTTP 200, auth, latency, console errors)
+- Supabase migration safety (if applicable)
+
+**If deploy fails:** Stop milestone completion. Fix the issue, re-run `/ship-*`, then resume with `/qualia:complete-milestone`.
+
+**If "Already deployed" or "Skip deploy":** Continue to git_tag.
+
+</step>
+
+<step name="git_tag">
+
+Create git tag:
+
+```bash
+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 .planning/MILESTONES.md for full details.
+EOF
+)"
+```
+
+Confirm: "Tagged: v[X.Y]"
+
+Ask: "Push tag to remote? (y/n)"
+
+If yes:
+```bash
+git push origin v[X.Y]
+```
+
+</step>
+
+<step name="git_commit_milestone">
+
+Commit milestone completion.
+
+```bash
+node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js 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 `/qualia: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 archived to milestones/v[X.Y]-STATE.md
+- [ ] STATE.md reset to clean template for next milestone
+- [ ] Git tag created (v[X.Y])
+- [ ] Milestone commit made (includes archive files and deletion)
+- [ ] User knows next step (/qualia:new-milestone)
+
+</success_criteria>