qualia-framework 2.6.0 → 3.2.0

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

@@ -1,858 +0,0 @@
-<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-framework/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-framework/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-framework/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-framework/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>