mindsystem-cc 3.2.3 → 3.3.1

package/commands/ms/execute-phase.md

@@ -61,38 +61,45 @@ Phase: $ARGUMENTS
    - Collect summaries from all plans
    - Report phase completion status
 
-6. **Verify phase goal**
+6. **Simplify code (optional)**
+   - Read `simplifier` from config.json (default: `ms-code-simplifier`)
+   - If `"skip"`: proceed to step 7
+   - Spawn simplifier agent with phase file scope
+   - If changes made: commit as `refactor({phase}): simplify phase code`
+
+7. **Verify phase goal**
    - Spawn `ms-verifier` subagent with phase directory and goal
    - Verifier checks must_haves against actual codebase (not SUMMARY claims)
    - Creates VERIFICATION.md with detailed report
    - Route by status:
-     - `passed` → continue to step 7
+     - `passed` → continue to step 8
      - `human_needed` → present items, get approval or feedback
      - `gaps_found` → present gaps, offer `/ms:plan-phase {X} --gaps`
 
-7. **Generate phase patch**
+8. **Generate phase patch**
    - Run: `~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}`
    - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`
    - Verify: patch file exists OR skip message logged
+   - Note: Patch captures all changes including simplifications
 
-8. **Update roadmap and state**
+9. **Update roadmap and state**
    - Update ROADMAP.md, STATE.md
 
-9. **Update requirements**
-   Mark phase requirements as Complete:
-   - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
-   - Read REQUIREMENTS.md traceability table
-   - For each REQ-ID in this phase: change Status from "Pending" to "Complete"
-   - Write updated REQUIREMENTS.md
-   - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
+10. **Update requirements**
+    Mark phase requirements as Complete:
+    - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
+    - Read REQUIREMENTS.md traceability table
+    - For each REQ-ID in this phase: change Status from "Pending" to "Complete"
+    - Write updated REQUIREMENTS.md
+    - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
-10. **Commit phase completion**
+11. **Commit phase completion**
     Bundle all phase metadata updates in one commit:
     - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
     - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
     - Commit: `docs({phase}): complete {phase-name} phase`
 
-11. **Offer next steps**
+12. **Offer next steps**
     - Route to next action (see `<offer_next>`)
 </process>
 
@@ -261,9 +268,16 @@ After all tasks in a plan complete:
 2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
 3. NO code files (already committed per-task)
 
+**Simplification Commit (if changes made):**
+
+After code simplification step:
+1. Stage only simplified files
+2. Commit with format: `refactor({phase}): simplify phase code`
+3. Include simplifier agent name and file count in commit body
+
 **Phase Completion Commit:**
 
-After all plans in phase complete (step 7):
+After all plans in phase complete:
 1. Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
 2. Commit with format: `docs({phase}): complete {phase-name} phase`
 3. Bundles all phase-level state updates in one commit
@@ -279,6 +293,7 @@ After all plans in phase complete (step 7):
 <success_criteria>
 - [ ] All incomplete plans in phase executed
 - [ ] Each plan has SUMMARY.md
+- [ ] Code simplified (or skipped if config says "skip")
 - [ ] Phase goal verified (must_haves checked against codebase)
 - [ ] VERIFICATION.md created in phase directory
 - [ ] Patch file generated OR explicitly skipped with message

package/commands/ms/help.md

@@ -158,7 +158,7 @@ Audit and improve design of already-implemented features.
 - Creates retroactive DESIGN.md if none exists
 - Presents improvements with benefits and trade-offs
 - Applies user-approved changes, runs verification
-- Use for features implemented before GSD, or periodic design audits
+- Use for features implemented before Mindsystem, or periodic design audits
 
 Usage: `/ms:review-design 4` (review phase 4)
 Usage: `/ms:review-design lib/features/home/home_screen.dart`

package/commands/ms/new-milestone.md

@@ -30,9 +30,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 @.planning/STATE.md
 @.planning/MILESTONES.md
 @.planning/config.json
-
-**Load milestone context (if exists, from /ms:discuss-milestone):**
-@.planning/MILESTONE-CONTEXT.md
 </context>
 
 <process>
@@ -41,14 +38,15 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    - Read PROJECT.md (existing project, Validated requirements, decisions)
    - Read MILESTONES.md (what shipped previously)
    - Read STATE.md (pending todos, blockers)
-   - Check for MILESTONE-CONTEXT.md (from /ms:discuss-milestone)
+   - Calculate previous milestone version from MILESTONES.md (e.g., if last shipped was v1.0, previous=1.0)
+   - Note: Previous milestone files will be loaded on-demand based on user's choice in step 3
+
+   **Why only the last milestone?** We load DECISIONS.md and AUDIT.md from only the immediately preceding milestone. Older decisions that remain important should already be in PROJECT.md or visible in the codebase. Older untested assumptions that weren't addressed in subsequent milestones are intentionally skipped or no longer relevant. Loading all previous milestones would bloat context for diminishing returns.
 
 2. **Present what shipped (if MILESTONES.md exists):**
 
    ```bash
    cat .planning/MILESTONES.md 2>/dev/null
-   # Also check for assumptions from last audit
-   cat .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | grep -A 100 "assumptions:" | head -50
    ```
 
    Format the presentation:
@@ -63,7 +61,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    **Key accomplishments:**
    - [From MILESTONES.md accomplishments]
    - [From MILESTONES.md accomplishments]
-   - [From MILESTONES.md accomplishments]
 
    **Validated requirements:**
    - [From PROJECT.md Validated section]
@@ -71,37 +68,56 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    **Pending todos (if any):**
    - [From STATE.md accumulated context]
 
-   **Untested assumptions (if any):**
-   - [From MILESTONE-AUDIT.md assumptions section]
-   - Error state displays (04-comments, 05-auth)
-   - Empty state handling (04-comments)
-   - Session timeout behavior (05-auth)
-
-   *These were skipped during UAT because required states couldn't be mocked.*
-
    ---
    ```
 
-   This gives users context before asking what they want to build next.
+3. **Decision gate:**
 
-3. **Gather milestone goals:**
+   Use AskUserQuestion:
+   - header: "New Milestone"
+   - question: "How do you want to start?"
+   - options:
+     - "I know what to build" — proceed to goal gathering
+     - "Help me figure it out" — enter discovery mode with previous context
+     - "Show previous decisions first" — view DECISIONS.md and AUDIT.md, then decide
 
-   **If MILESTONE-CONTEXT.md exists:**
-   - Use features and scope from discuss-milestone
-   - Present summary for confirmation
+4. **Gather milestone goals:**
 
-   **If no context file:**
-   - Present what shipped in last milestone
-   - Ask: "What do you want to build next?"
+   **If "I know what to build":**
+   - Ask directly: "What do you want to build next?"
    - Use AskUserQuestion to explore features
    - Probe for priorities, constraints, scope
 
-4. **Determine milestone version:**
+   **If "Show previous decisions first":**
+   - Using the previous version calculated in step 1 (e.g., "1.0"):
+     - Check for and read `.planning/milestones/v1.0-DECISIONS.md` if exists
+     - Check for and read `.planning/milestones/v1.0-MILESTONE-AUDIT.md` if exists
+   - Present relevant context from these files
+   - Return to decision gate (without this option)
+
+   **If "Help me figure it out" (Discovery Mode):**
+   - Using the previous version calculated in step 1:
+     - Check for and read `.planning/milestones/v{VERSION}-DECISIONS.md` if exists
+     - Check for and read `.planning/milestones/v{VERSION}-MILESTONE-AUDIT.md` if exists
+   - Surface untested assumptions from AUDIT.md (if found):
+     ```
+     📋 Untested from v[previous]:
+     - Error state displays
+     - Empty state handling
+     - [etc. from assumptions section]
+     ```
+   - Follow questioning.md patterns for AskUserQuestion-based discovery:
+     - "What do you want to add, improve, or fix?"
+     - Options: Address untested assumptions, New features, Improvements, Bug fixes, Let me describe
+   - Follow up with probing questions
+   - Continue until clear goals emerge
+
+5. **Determine milestone version:**
    - Parse last version from MILESTONES.md
    - Suggest next version (v1.0 → v1.1, or v2.0 for major)
    - Confirm with user
 
-5. **Update PROJECT.md:**
+6. **Update PROJECT.md:**
 
    Add/update these sections:
 
@@ -120,7 +136,7 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
    Update "Last updated" footer.
 
-6. **Update STATE.md:**
+7. **Update STATE.md:**
 
    ```markdown
    ## Current Position
@@ -131,9 +147,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    Last activity: [today] — Milestone v[X.Y] started
    ```
 
-7. **Cleanup:**
-   - Delete MILESTONE-CONTEXT.md if exists (consumed)
-
 8. **Git commit:**
    ```bash
    git add .planning/PROJECT.md .planning/STATE.md
@@ -187,7 +200,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 - PROJECT.md updated with Current Milestone section
 - Active requirements reflect new milestone goals
 - STATE.md reset for new milestone
-- MILESTONE-CONTEXT.md consumed and deleted (if existed)
 - Git commit made
 - User routed to define-requirements (or research-project)
 </success_criteria>

package/commands/ms/progress.md

@@ -380,5 +380,5 @@ Ready to plan the next milestone.
 - [ ] What's next clearly explained
 - [ ] Smart routing: /ms:execute-phase if plan exists, /ms:plan-phase if not
 - [ ] User confirms before any action
-- [ ] Seamless handoff to appropriate gsd command
+- [ ] Seamless handoff to appropriate mindsystem command
       </success_criteria>

package/commands/ms/research-project.md

@@ -299,8 +299,16 @@ Create SUMMARY.md with:
 - Confidence assessment
 - Gaps to address
 
+After creating SUMMARY.md, update config.json simplifier with agent name:
+1. Read recommended stack from STACK.md
+2. Map to simplifier agent name:
+   - Flutter/Dart → \"ms-flutter-simplifier\"
+   - All others → \"ms-code-simplifier\"
+3. Update .planning/config.json (create from template if needed)
+
 Then commit ALL research files together:
 git add .planning/research/
+git add .planning/config.json
 git commit -m 'docs: complete [domain] project research'
 ",
   subagent_type="ms-research-synthesizer",

package/commands/ms/review-design.md

@@ -60,7 +60,7 @@ Options:
 - "Uncommitted changes" - Review files with uncommitted modifications
 - "Specific file" - I'll provide a file path
 - "Recent feature work" - Review files from recent commits
-- "GSD phase" - Review all code from a specific phase
+- "Mindsystem phase" - Review all code from a specific phase
 ```
 
 ### Step 1.2: Resolve Phase Directory (if phase-based)

package/mindsystem/references/git-integration.md

@@ -1,5 +1,5 @@
 <overview>
-Git integration for GSD framework.
+Git integration for Mindsystem framework.
 </overview>
 
 <core_principle>
@@ -29,7 +29,7 @@ The git log should read like a changelog of what shipped, not a diary of plannin
 [ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
 ```
 
-If NO_GIT: Run `git init` silently. GSD projects always get their own repo.
+If NO_GIT: Run `git init` silently. Mindsystem projects always get their own repo.
 </git_check>
 
 <commit_formats>

package/mindsystem/references/goal-backward.md

@@ -255,7 +255,7 @@ Key links are verification priorities. Without them, you check everything equall
 
 </common_failures>
 
-<integration_with_gsd>
+<integration_with_mindsystem>
 
 ## In plan-phase.md
 
@@ -283,4 +283,4 @@ derive_must_haves → tasks → execute → verify → [gaps?] → fix plans →
 
 Must-haves are derived once, verified as many times as needed until all pass.
 
-</integration_with_gsd>
+</integration_with_mindsystem>

package/mindsystem/references/principles.md

@@ -1,6 +1,6 @@
 <principles>
 
-Core principles for the GSD planning system.
+Core principles for the Mindsystem planning system.
 
 <solo_developer_claude>
 

package/mindsystem/templates/adhoc-summary.md

@@ -17,6 +17,7 @@ files_modified:
   - [path/to/file1.ts]
   - [path/to/file2.ts]
 commit: [git hash]
+patch_file: [path to .patch file, or empty if skipped]
 ---
 
 # Adhoc: [Description]
@@ -66,6 +67,7 @@ Adhoc summaries document small work items executed outside the normal phase work
 | related_phase | Yes | Current phase from STATE.md, or "none" if between phases |
 | files_modified | Yes | List of file paths changed |
 | commit | Yes | Git commit hash |
+| patch_file | No | Path to generated patch file (empty if no code changes) |
 
 </frontmatter_fields>
 
@@ -100,6 +102,7 @@ files_modified:
   - src/lib/api-client.ts
   - src/hooks/useAuth.ts
 commit: abc123f
+patch_file: .planning/adhoc/2026-01-20-fix-auth-token-not-refreshing-on-401.patch
 ---
 
 # Adhoc: Fix auth token not refreshing on 401

package/mindsystem/templates/codebase/architecture.md

@@ -146,7 +146,7 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 **CLI Command Execution:**
 
-1. User runs: `gsd new-project`
+1. User runs: `ms new-project`
 2. Commander parses args and flags
 3. Command handler invoked (`src/commands/new-project.ts`)
 4. Handler calls service methods (`src/services/project.ts` → `create()`)
@@ -180,7 +180,7 @@ Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code org
 
 **CLI Entry:**
 - Location: `src/index.ts`
-- Triggers: User runs `gsd <command>`
+- Triggers: User runs `ms <command>`
 - Responsibilities: Register commands, parse args, display help
 
 **Commands:**

package/mindsystem/templates/codebase/structure.md

@@ -145,7 +145,7 @@ mindsystem/
 - Key files: install.js - handles npx installation
 - Subdirectories: None
 
-**commands/gsd/**
+**commands/ms/**
 - Purpose: Slash command definitions for Claude Code
 - Contains: *.md files (one per command)
 - Key files: new-project.md, plan-phase.md, execute-plan.md

package/mindsystem/templates/config.json

@@ -11,5 +11,6 @@
   "safety": {
     "always_confirm_destructive": true,
     "always_confirm_external_services": true
-  }
+  },
+  "simplifier": null
 }

package/mindsystem/templates/decisions.md

@@ -0,0 +1,145 @@
+# Decisions Template
+
+Template for `.planning/milestones/v{X.Y}-DECISIONS.md` — consolidated decisions from a milestone.
+
+**Purpose:** Preserve decision rationale for future reference. When starting a new milestone, previous DECISIONS.md provides context for "why did we do it this way?"
+
+**Created by:** `ms-consolidator` agent during `/ms:complete-milestone`
+
+**Referenced by:** `/ms:new-milestone` during discovery mode
+
+---
+
+<template>
+
+```markdown
+# Milestone v{{VERSION}} Decisions
+
+**Milestone:** {{NAME}}
+**Phases:** {{PHASE_START}}-{{PHASE_END}}
+**Consolidated:** {{DATE}}
+
+---
+
+## Technical Stack
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Architecture
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Data Model
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## API Design
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## UI/UX
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Security
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+## Performance
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| {{DECISION}} | {{RATIONALE}} | {{PHASE}} |
+
+---
+
+## Sources
+
+Files consolidated from each phase:
+
+| Phase | Files Found |
+|-------|-------------|
+| {{PHASE_NUM}} | {{FILES_LIST}} |
+
+---
+
+*Consolidated: {{DATE}} during v{{VERSION}} milestone completion*
+```
+
+</template>
+
+<guidelines>
+
+## What This File Captures
+
+**Decisions = Choices + Rationale**
+
+This template captures WHY decisions were made, not just WHAT was built. SUMMARY.md captures what was built. DECISIONS.md captures why it was built that way.
+
+Decisions help future milestones by:
+- Explaining why certain approaches were chosen
+- Documenting rejected alternatives
+- Preserving constraints that influenced choices
+- Providing context for "why is it this way?" questions
+
+## Categories Explained
+
+| Category | Content |
+|----------|---------|
+| **Technical Stack** | Libraries, frameworks, versions, tools |
+| **Architecture** | System structure, module boundaries, patterns |
+| **Data Model** | Schema, relationships, storage approach |
+| **API Design** | Endpoints, auth, errors, response format |
+| **UI/UX** | Components, layouts, interactions |
+| **Security** | Auth, authorization, data protection |
+| **Performance** | Caching, optimization, loading patterns |
+
+## Usage Rules
+
+**Remove empty categories.** If no Security decisions were made, don't include the Security section.
+
+**Keep entries concise.** Decision in 5-10 words. Rationale in 10-20 words.
+
+**Include phase number.** Helps trace when decisions were made.
+
+## Good vs Bad Entries
+
+**Good decision entries:**
+- "Use jose over jsonwebtoken | Better TypeScript support, actively maintained | 2"
+- "Flat folder structure | Avoids premature abstraction, easier navigation | 1"
+- "Server actions over API routes | Simpler data mutations for forms | 3"
+- "Tailwind over styled-components | Team familiarity, smaller bundle | 1"
+
+**Bad decision entries:**
+- "Use React | — | 1" (no rationale)
+- "Implemented authentication | Users can log in | 2" (not a decision, just work done)
+- "Added tests | Testing is important | 3" (obvious, no real decision)
+
+## Sources Appendix
+
+The Sources section documents which files were consolidated from each phase:
+
+```markdown
+| Phase | Files Found |
+|-------|-------------|
+| 1 | PLAN.md, RESEARCH.md |
+| 2 | PLAN.md, CONTEXT.md, DESIGN.md |
+| 3 | PLAN.md |
+| 4 | PLAN.md, RESEARCH.md, DESIGN.md |
+```
+
+This helps understand which phases had dedicated research, design, or context discussion.
+
+</guidelines>

package/mindsystem/workflows/complete-milestone.md

@@ -22,12 +22,14 @@ This is the ritual that separates "development" from "shipped."
 
 When a milestone completes, this workflow:
 
-1. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
-2. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
-3. Updates ROADMAP.md to replace milestone details with one-line summary
-4. Deletes REQUIREMENTS.md (fresh one created for next milestone)
-5. Performs full PROJECT.md evolution review
-6. Offers to create next milestone inline
+1. Consolidates phase decisions into `.planning/milestones/v[X.Y]-DECISIONS.md`
+2. Cleans up phase artifacts (PLAN, CONTEXT, RESEARCH, DESIGN files deleted)
+3. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
+4. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+5. Updates ROADMAP.md to replace milestone details with one-line summary
+6. Deletes REQUIREMENTS.md (fresh one created for next milestone)
+7. Performs full PROJECT.md evolution review
+8. Routes to `/ms:new-milestone` for next milestone
 
 **Context Efficiency:**
 
@@ -98,7 +100,50 @@ cat .planning/config.json 2>/dev/null
 Proceeding to stats gathering...
 ```
 
-Proceed directly to gather_stats step.
+Proceed directly to consolidate_decisions step.
+
+</step>
+
+<step name="consolidate_decisions">
+
+Consolidate phase decisions before archiving.
+
+**Spawn ms-consolidator agent:**
+
+```
+Task(
+  prompt="Consolidate decisions from milestone v[X.Y] [Name].
+
+Phase range: [PHASE_START]-[PHASE_END]
+Phase directories:
+- .planning/phases/01-foundation
+- .planning/phases/02-auth
+- [etc. for all phases in milestone]
+
+Extract decisions from PLAN, CONTEXT, RESEARCH, DESIGN files.
+Create v[X.Y]-DECISIONS.md in .planning/milestones/.
+Delete source files (preserve SUMMARY, VERIFICATION, UAT).",
+  subagent_type="ms-consolidator"
+)
+```
+
+**Wait for completion and verify:**
+
+```bash
+ls .planning/milestones/v[X.Y]-DECISIONS.md
+```
+
+**Present consolidation summary:**
+
+```
+✓ Decisions consolidated: [N] decisions in [M] categories
+✓ Source files cleaned: PLAN, CONTEXT, RESEARCH, DESIGN deleted
+✓ Preserved: SUMMARY, VERIFICATION, UAT files
+
+Report: .planning/milestones/v[X.Y]-DECISIONS.md
+```
+
+Continue to gather_stats step.
 
 </step>
 
@@ -604,6 +649,7 @@ Commit milestone completion including archive files and deletions.
 
 ```bash
 # Stage archive files (new)
+git add .planning/milestones/v[X.Y]-DECISIONS.md
 git add .planning/milestones/v[X.Y]-ROADMAP.md
 git add .planning/milestones/v[X.Y]-REQUIREMENTS.md
 git add .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
@@ -621,10 +667,14 @@ git commit -m "$(cat <<'EOF'
 chore: complete v[X.Y] milestone
 
 Archived:
+- milestones/v[X.Y]-DECISIONS.md (consolidated decisions)
 - milestones/v[X.Y]-ROADMAP.md
 - milestones/v[X.Y]-REQUIREMENTS.md
 - milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
 
+Cleaned:
+- Phase PLAN, CONTEXT, RESEARCH, DESIGN files (consolidated into DECISIONS.md)
+
 Deleted (fresh for next milestone):
 - ROADMAP.md
 - REQUIREMENTS.md
@@ -663,20 +713,19 @@ Tag: v[X.Y]
 
 ## ▶ Next Up
 
-**Discuss Next Milestone** — figure out what to build next
+**Start Next Milestone** — define goals and requirements
 
-`/ms:discuss-milestone`
+`/ms:new-milestone`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Next milestone flow:**
-1. `/ms:discuss-milestone` — thinking partner, creates context file
-2. `/ms:new-milestone` — update PROJECT.md with new goals
-3. `/ms:research-project` — (optional) research ecosystem
-4. `/ms:define-requirements` — scope what to build
-5. `/ms:create-roadmap` — plan how to build it
+1. `/ms:new-milestone` — discover what to build, update PROJECT.md with goals
+2. `/ms:research-project` — (optional) research ecosystem
+3. `/ms:define-requirements` — scope what to build
+4. `/ms:create-roadmap` — plan how to build it
 
 ---
 ```
@@ -725,6 +774,8 @@ If yes → milestone. If no → keep working.
 
 Milestone completion is successful when:
 
+- [ ] Decisions consolidated (milestones/v[X.Y]-DECISIONS.md created)
+- [ ] Phase artifacts cleaned (PLAN, CONTEXT, RESEARCH, DESIGN deleted)
 - [ ] MILESTONES.md entry created with stats and accomplishments
 - [ ] PROJECT.md full evolution review completed
 - [ ] All shipped requirements moved to Validated in PROJECT.md
@@ -736,6 +787,6 @@ Milestone completion is successful when:
 - [ ] STATE.md updated with fresh project reference
 - [ ] Git tag created (v[X.Y])
 - [ ] Milestone commit made (includes archive files and deletion)
-- [ ] User knows next steps (starting with /ms:define-requirements)
+- [ ] User knows next steps (starting with /ms:new-milestone)
 
 </success_criteria>