mindsystem-cc 3.16.2 → 3.17.1

package/README.md

@@ -269,8 +269,8 @@ Replace `<N>` with the phase number you're working on.
 
 **What you'll get:**
 
-- `.planning/milestones/v1.0-DECISIONS.md` — consolidated decisions for future reference
-- `.planning/milestones/v1.0-ROADMAP.md` / `v1.0-REQUIREMENTS.md` — archived detail to keep active docs lean
+- `.planning/milestones/v1.0/` — archived milestone (ROADMAP, REQUIREMENTS, DECISIONS, research)
+- Active docs stay lean; full detail lives in the version folder
 
 **Tip:** Milestone review can be **report-only** (e.g., Flutter structural review) so you stay in control. Create a quality phase, or accept tech debt explicitly — your call.
 

package/agents/ms-roadmapper.md

@@ -214,25 +214,12 @@ For each phase, analyze whether pre-work would reduce risk before planning. Thre
 
 | Pre-Work | Question It Answers | Command |
 |----------|---------------------|---------|
-| **Research** | "Do I know HOW to build this?" | `/ms:research-phase` |
 | **Discussion** | "Do I understand WHAT the user wants?" | `/ms:discuss-phase` |
 | **Design** | "Do I know what this should LOOK like?" | `/ms:design-phase` |
+| **Research** | "Do I know HOW to build this?" | `/ms:research-phase` |
 
 All use binary Likely/Unlikely with parenthetical reason. These are hints to users, not mandates.
 
-### Research Indicators
-
-**Likely when ANY of:**
-- External APIs or services involved
-- New libraries/frameworks to learn
-- Architectural decisions not yet made
-- Technical approach unclear
-
-**Unlikely when ALL of:**
-- Using established internal patterns
-- CRUD operations with known stack
-- Well-documented conventions exist
-
 ### Discussion Indicators
 
 **Problem it solves:** User's mental model isn't documented. Planning happens without understanding what's essential vs nice-to-have.
@@ -266,6 +253,19 @@ All use binary Likely/Unlikely with parenthetical reason. These are hints to use
 - Infrastructure, testing, deployment phases
 - Uses established UI patterns exclusively
 
+### Research Indicators
+
+**Likely when ANY of:**
+- External APIs or services involved
+- New libraries/frameworks to learn
+- Architectural decisions not yet made
+- Technical approach unclear
+
+**Unlikely when ALL of:**
+- Using established internal patterns
+- CRUD operations with known stack
+- Well-documented conventions exist
+
 **Note:** Discussion and Design often overlap for UI-facing phases. This is intentional — they serve different purposes (vision vs specification) and a phase may benefit from both.
 
 ### Output Format
@@ -273,12 +273,12 @@ All use binary Likely/Unlikely with parenthetical reason. These are hints to use
 For each phase in ROADMAP.md:
 
 ```markdown
-**Research**: Likely (external API) | Unlikely (established patterns)
-**Research topics**: [What needs investigating] (only if Likely)
 **Discuss**: Likely (ambiguous user flow) | Unlikely (clear requirements)
 **Discuss topics**: [What to clarify] (only if Likely)
 **Design**: Likely (significant new UI) | Unlikely (backend only)
 **Design focus**: [What to design] (only if Likely)
+**Research**: Likely (external API) | Unlikely (established patterns)
+**Research topics**: [What needs investigating] (only if Likely)
 ```
 
 </pre_work_analysis>
@@ -461,11 +461,11 @@ When presenting to user for approval:
 
 ### Pre-Work Recommendations
 
-| Phase | Research | Discuss | Design |
-|-------|----------|---------|--------|
+| Phase | Discuss | Design | Research |
+|-------|---------|--------|----------|
 | 1 - Setup | Unlikely | Unlikely | Unlikely |
-| 2 - Auth | Likely | Likely | Unlikely |
-| 3 - Content | Unlikely | Likely | Likely |
+| 2 - Auth | Likely | Unlikely | Likely |
+| 3 - Content | Likely | Likely | Unlikely |
 
 **Phase 2 topics:**
 - Research: [external auth providers]
@@ -601,8 +601,8 @@ When files are written and returning to orchestrator:
 
 ### Pre-Work Recommendations
 
-| Phase | Research | Discuss | Design |
-|-------|----------|---------|--------|
+| Phase | Discuss | Design | Research |
+|-------|---------|--------|----------|
 | 1 - {name} | {Likely/Unlikely} | {Likely/Unlikely} | {Likely/Unlikely} |
 | 2 - {name} | {Likely/Unlikely} | {Likely/Unlikely} | {Likely/Unlikely} |
 

package/commands/ms/audit-milestone.md

@@ -306,34 +306,29 @@ Use AskUserQuestion with options A and B.
 
 1. Determine next phase number (append at end of current phases)
 2. Create phase directory: `.planning/phases/{NN}-code-quality/`
-3. Create `PHASE-FINDINGS.md` with full review findings
-4. Update ROADMAP.md with new phase:
+3. Update ROADMAP.md with new phase:
 
 ```markdown
 ### Phase {N}: Code Quality (Generated)
 **Goal:** Address structural improvements from milestone code review
-
-**Findings to address:**
-[High impact items from review]
+**Scope:** High and Medium items from .planning/TECH-DEBT.md
 
 Plans:
 - [ ] {N}-01: High impact structural fixes
 ```
 
-5. Report:
+4. Report:
 ```markdown
 ## Quality Phase Created
 
 **Phase {N}:** `.planning/phases/{NN}-code-quality/`
-**Findings documented:** `PHASE-FINDINGS.md`
+**Scope source:** `.planning/TECH-DEBT.md`
 
 ---
 
 ## ▶ Next Up
 
-**Plan the quality phase**
-
-`/ms:plan-phase {N}`
+`/ms:plan-phase {N}` — plan the quality phase
 
 <sub>`/clear` first → fresh context window</sub>
 ```
@@ -394,13 +389,15 @@ After code review (all sources now available), generate or update `.planning/TEC
 
 1. **Read existing** `.planning/TECH-DEBT.md` (if exists) — parse active items and dismissed list, note highest `TD-{N}` ID
 2. **Read template** from `@~/.claude/mindsystem/templates/tech-debt.md`
-3. **Collect tech debt** from all sources:
-   - Phase VERIFICATION.md anti-patterns (severity: warning or info — blockers go to `gaps`)
-   - Non-critical gaps from phase verifications
-   - Code review findings (if analyze-only reviewer was used in Step 8)
+3. **Collect tech debt** from all sources with severity mapping:
+   - Integration checker bugs → **Critical**
+   - Unfixed UAT issues (result: `issue`, fix_status ≠ `verified`) → **Critical** (blocker) / **High** (major) / **Medium** (minor) / **Low** (cosmetic)
+   - Code review findings → pass through reviewer severity (**High** / **Medium** / **Low**)
+   - Phase VERIFICATION.md anti-patterns → **Medium** or **Low** (blockers go to `gaps`, not tech debt)
+   - Non-critical gaps from phase verifications → **Medium**
 4. **De-duplicate** against existing active items AND dismissed items (match by location + description similarity)
 5. **Assign `TD-{N}` IDs** continuing from highest existing ID
-6. **Write/update** `.planning/TECH-DEBT.md` following the template format
+6. **Write/update** `.planning/TECH-DEBT.md` — group items under `## Critical`, `## High`, `## Medium`, `## Low` sections per template. Omit empty sections.
 
 ## 9. Commit Audit Report
 
@@ -432,7 +429,7 @@ Read `~/.claude/mindsystem/references/routing/audit-result-routing.md` and follo
 - [ ] Code review completed (or skipped if config says "skip")
 - [ ] If analyze-only reviewer: YAML findings parsed and added to report
 - [ ] If analyze-only reviewer: Binary decision presented (quality phase vs tech debt)
-- [ ] If quality phase chosen: Phase directory created with PHASE-FINDINGS.md
+- [ ] If quality phase chosen: Phase directory created, ROADMAP updated with TECH-DEBT.md scope
 - [ ] MILESTONE-AUDIT.md committed to git
 - [ ] Results presented with actionable next steps
 </success_criteria>

package/commands/ms/complete-milestone.md

@@ -91,18 +91,24 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 4. **Archive milestone:**
 
-   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Create `.planning/milestones/v{{version}}/` directory
+   - Create `.planning/milestones/v{{version}}/ROADMAP.md`
    - Extract full phase details from ROADMAP.md
    - Fill milestone-archive.md template
    - Update ROADMAP.md to one-line summary with link
 
 5. **Archive requirements:**
 
-   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Create `.planning/milestones/v{{version}}/REQUIREMENTS.md`
    - Mark all v1 requirements as complete (checkboxes checked)
    - Note requirement outcomes (validated, adjusted, dropped)
    - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
 
+5.5. **Archive research:**
+
+   - If `.planning/research/` exists, move to `.planning/milestones/v{{version}}/research/`
+   - Skip silently if no research directory exists
+
 6. **Update PROJECT.md:**
 
    - Add "Current State" section with shipped version
@@ -128,8 +134,9 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 <success_criteria>
 
 - Raw artifacts cleaned from phase directories (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
-- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
-- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- Milestone archived to `.planning/milestones/v{{version}}/ROADMAP.md`
+- Requirements archived to `.planning/milestones/v{{version}}/REQUIREMENTS.md`
+- Research archived to `.planning/milestones/v{{version}}/research/` (if existed)
 - `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
 - ROADMAP.md collapsed to one-line entry
 - PROJECT.md updated with current state

package/commands/ms/new-milestone.md

@@ -64,7 +64,7 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 3. **Strategic assessment (silent — do not output this step):**
    - Check for previous milestone artifacts using calculated version:
      - `.planning/knowledge/*.md` (subsystem knowledge files — persist across milestones)
-     - `.planning/milestones/v{VERSION}-MILESTONE-AUDIT.md` (if exists)
+     - `.planning/milestones/v{VERSION}/MILESTONE-AUDIT.md` (if exists)
      - `.planning/TECH-DEBT.md` (if exists)
    - Identify: outstanding tech debt, untested assumptions, high-impact gaps, unaddressed requirements
    - This is background analysis — synthesize silently, surface through suggestions in step 4
@@ -266,15 +266,13 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
     ## ▶ Next Up
 
-    **[Recommended command]** — [one-line reason from conversation]
-
-    `/ms:[recommended-command]`
+    `/ms:[recommended-command]` — [one-line reason from conversation]
 
     <sub>`/clear` first → fresh context window</sub>
 
     ---
 
-    **Also available:** `/ms:[alternative-command]`
+    **Also available:** `/ms:[alternative-command]` — [brief reason]
 
     ---
     ```

package/commands/ms/plan-milestone-gaps.md

@@ -176,9 +176,7 @@ git commit -m "docs(roadmap): add gap closure phases {N}-{M}"
 
 ## ▶ Next Up
 
-**Plan first gap closure phase**
-
-`/ms:plan-phase {N}`
+`/ms:plan-phase {N}` — plan first gap closure phase
 
 <sub>`/clear` first → fresh context window</sub>
 

package/commands/ms/plan-phase.md

@@ -67,6 +67,10 @@ Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains rese
 **Load design specs if exists (created by /ms:design-phase):**
 Check for and read `.planning/phases/XX-name/{phase}-DESIGN.md` - contains visual/UX specifications including layouts, components, flows, and verification criteria.
 
+**Load tech debt if quality/cleanup phase:**
+If phase name or roadmap goal contains "quality", "cleanup", "refactor", or "tech debt":
+Check for and read `.planning/TECH-DEBT.md` — prioritized issues for scope selection during task breakdown.
+
 **Load codebase context if exists:**
 Check for `.planning/codebase/` and load relevant documents based on phase type.
 

package/commands/ms/research-project.md

@@ -335,9 +335,9 @@ Key findings:
 - Critical pitfall: [one-liner]
 
 ---
-## > Next Up
-**Define requirements and create roadmap** - `/ms:create-roadmap`
-<sub>`/clear` first</sub>
+## ▶ Next Up
+`/ms:create-roadmap` — define requirements and create roadmap
+<sub>`/clear` first → fresh context window</sub>
 ---
 ```
 

package/mindsystem/references/continuation-format.md

@@ -9,9 +9,7 @@ Standard format for presenting next steps after completing a command or workflow
 
 ## ▶ Next Up
 
-**{identifier}: {name}** — {one-line description}
-
-`{command to copy-paste}`
+`{command to copy-paste}` — {one-line description}
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -24,14 +22,23 @@ Standard format for presenting next steps after completing a command or workflow
 ---
 ```
 
+When there's meaningful additional context (like a phase identifier), add it as a header line:
+
+```
+**Phase {N}: {Name}** — {Goal}
+
+`/ms:plan-phase {N}`
+```
+
 ## Format Rules
 
-1. **Always show what it is** — name + description, never just a command path
-2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
-3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
-4. **`/clear` explanation** — always include, keeps it concise but explains why
-5. **"Also available" not "Other options"** — sounds more app-like
-6. **Visual separators** — `---` above and below to make it stand out
+1. **Command is the anchor** — backtick command + description on one line, no separate bold label restating the command name
+2. **Phase identifiers are additive context** — `**Phase 2: Auth**` carries info the command doesn't; bold labels like `**Plan gap closure**` just restate `/ms:plan-phase --gaps` and should be omitted
+3. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+4. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+5. **`/clear` explanation** — always include, keeps it concise but explains why
+6. **"Also available" not "Other options"** — sounds more app-like
+7. **Visual separators** — `---` above and below to make it stand out
 
 ## Variants
 
@@ -167,9 +174,7 @@ All 4 phases shipped
 
 ## ▶ Next Up
 
-**Start v1.1** — discover what to build next
-
-`/ms:new-milestone`
+`/ms:new-milestone` — discover what to build next
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/references/routing/audit-result-routing.md

@@ -38,9 +38,7 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 
 ## ▶ Next Up
 
-**Complete milestone** — archive and tag
-
-`/ms:complete-milestone {version}`
+`/ms:complete-milestone {version}` — archive and tag
 
 <sub>`/clear` first → fresh context window</sub>
 ```
@@ -73,9 +71,7 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 
 ## ▶ Next Up
 
-**Plan gap closure** — create phases to complete milestone
-
-`/ms:plan-milestone-gaps`
+`/ms:plan-milestone-gaps` — create phases to complete milestone
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -112,13 +108,8 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 
 ## ▶ Options
 
-**A. Complete milestone** — accept debt, track in backlog
-
-`/ms:complete-milestone {version}`
-
-**B. Plan cleanup phase** — address debt before completing
-
-`/ms:plan-milestone-gaps`
+- `/ms:complete-milestone {version}` — accept debt, track in backlog
+- `/ms:plan-milestone-gaps` — address debt before completing
 
 <sub>`/clear` first → fresh context window</sub>
 ```

package/mindsystem/references/routing/between-milestones-routing.md

@@ -28,9 +28,7 @@ Ready to plan the next milestone.
 
 ## ▶ Next Up
 
-**Start Next Milestone** — discover what to build, update PROJECT.md
-
-`/ms:new-milestone`
+`/ms:new-milestone` — discover what to build, update PROJECT.md
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/references/routing/gap-closure-routing.md

@@ -46,9 +46,7 @@ Extract:
 
 ## ▶ Next Up
 
-**Plan gap closure** — create additional plans to complete the phase
-
-`/ms:plan-phase {Z} --gaps`
+`/ms:plan-phase {Z} --gaps` — create additional plans to complete the phase
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/references/routing/milestone-complete-routing.md

@@ -23,9 +23,7 @@ All {N} phases finished!
 
 ## ▶ Next Up
 
-**Audit milestone** — verify requirements, cross-phase integration, E2E flows
-
-`/ms:audit-milestone`
+`/ms:audit-milestone` — verify requirements, cross-phase integration, E2E flows
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/templates/milestone-archive.md

@@ -112,8 +112,8 @@ _For current project status, see .planning/ROADMAP.md_
 
 **Archive location:**
 
-- Save to `.planning/milestones/v{VERSION}-{NAME}.md`
-- Example: `.planning/milestones/v1.0-mvp.md`
+- Save to `.planning/milestones/v{VERSION}/ROADMAP.md`
+- Example: `.planning/milestones/v1.0/ROADMAP.md`
 
 **After archiving:**
 

package/mindsystem/templates/roadmap.md

@@ -34,9 +34,9 @@ Decimal phases appear between their surrounding integers in numeric order.
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
   3. [Observable behavior from user perspective]
-**Research**: Unlikely (established patterns)
 **Discuss**: Unlikely (clear requirements)
 **Design**: Unlikely (backend only)
+**Research**: Unlikely (established patterns)
 **Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
 
 Plans:
@@ -51,12 +51,12 @@ Plans:
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
-**Research**: Likely (new integration)
-**Research topics**: [What needs investigating]
 **Discuss**: Likely (ambiguous user flow)
 **Discuss topics**: [What to clarify]
 **Design**: Likely (significant new UI)
 **Design focus**: [What to design]
+**Research**: Likely (new integration)
+**Research topics**: [What needs investigating]
 **Plans**: [Number of plans]
 
 Plans:
@@ -81,10 +81,10 @@ Plans:
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
   3. [Observable behavior from user perspective]
-**Research**: Likely (external API)
-**Research topics**: [What needs investigating]
 **Discuss**: Unlikely (established patterns)
 **Design**: Unlikely (API only)
+**Research**: Likely (external API)
+**Research topics**: [What needs investigating]
 **Plans**: [Number of plans]
 
 Plans:
@@ -98,9 +98,9 @@ Plans:
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
-**Research**: Unlikely (internal patterns)
 **Discuss**: Unlikely (clear requirements)
 **Design**: Unlikely (backend only)
+**Research**: Unlikely (internal patterns)
 **Plans**: [Number of plans]
 
 Plans:
@@ -137,9 +137,9 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Format: "User can [action]" or "[Thing] works/exists"
 
 **Pre-work indicators** (all use Likely/Unlikely with parenthetical reason):
-- `Research` - Technical unknowns: external APIs, new libraries, architectural decisions
 - `Discuss` - Vision unknowns: ambiguous requirements, UX decisions, novel features
 - `Design` - Visual unknowns: significant new UI, novel interactions, multi-screen flows
+- `Research` - Technical unknowns: external APIs, new libraries, architectural decisions
 - Include topic/focus fields only when Likely
 - Indicators are hints, not mandates - validate at planning time
 - UI-facing phases often need both Discuss and Design (this is intentional)

package/mindsystem/templates/tech-debt.md

@@ -6,11 +6,11 @@ Template for `.planning/TECH-DEBT.md` — single source of truth for all tech de
 
 ## Usage
 
-Created and updated by `/ms:audit-milestone`. Items persist across milestones. Users reference items manually via `/ms:adhoc` (small fixes) or `/ms:insert-phase` (larger remediation).
+Created and updated by `/ms:audit-milestone`. Items persist across milestones. Users reference items manually via `/ms:adhoc` (small fixes) or `/ms:insert-phase` (larger remediation). Loaded automatically by `/ms:plan-phase` for quality/cleanup phases.
 
 **Item IDs** use `TD-{N}` format — monotonically increasing, never reused. New items continue from highest existing ID.
 
-**Sources:** Phase verifications (anti-patterns, non-critical gaps), code review findings.
+**Sources:** Phase verifications (anti-patterns, non-critical gaps), code review findings, integration checker bugs, unfixed UAT issues.
 
 ---
 
@@ -23,17 +23,14 @@ Created and updated by `/ms:audit-milestone`. Items persist across milestones. U
 > Single source of truth for tech debt. Updated by `/ms:audit-milestone`.
 > Address items via `/ms:adhoc` (1-2 tasks) or `/ms:insert-phase` (larger work).
 
-## Active Items
+## {Severity}
+<!-- Sections in order: Critical, High, Medium, Low. Omit empty sections. -->
 
 ### TD-{N}: {Title}
-- **Phase:** {source phase, e.g. 03-chat}
-- **Source:** {verification | code-review | anti-pattern}
-- **Severity:** {blocker | warning | info}
 - **Location:** {file:line or component}
-- **Impact:** {what this causes}
-- **Suggested fix:** {how to address}
-- **Related files:** {other affected files}
-- **Identified:** v{milestone} | {YYYY-MM-DD}
+- **Impact:** {what this causes and why it matters}
+- **Fix:** {how to address}
+- <sub>Phase {source phase} | {verification | integration-check | code-review} | v{milestone}</sub>
 
 ---
 
@@ -50,9 +47,19 @@ Created and updated by `/ms:audit-milestone`. Items persist across milestones. U
 ## Guidelines
 
 **Severity levels:**
-- `blocker` — Prevents future work or degrades reliability. Rare in tech debt (blockers usually go to `gaps`).
-- `warning` — Indicates incomplete or fragile code. Common for TODOs, missing validation, stubs.
-- `info` — Notable but low impact. Style issues, minor inconsistencies, improvement opportunities.
+- `Critical` — Breaks behavior or risks data loss. Integration checker bugs (broken cross-phase wiring, failed E2E flows) always map here.
+- `High` — Causes cascading changes if left unaddressed. Fragile patterns that spread to new code, missing abstractions forcing workarounds.
+- `Medium` — Contained friction. TODOs, missing validation, incomplete error handling. Impact stays local.
+- `Low` — Won't compound. Style inconsistencies, minor naming issues, improvement opportunities.
+
+**Severity mapping from sources:**
+- Integration checker bugs → Critical
+- Unfixed UAT issues → Critical (blocker) / High (major) / Medium (minor) / Low (cosmetic)
+- Code review findings → pass through reviewer severity (High/Medium/Low)
+- Phase verification anti-patterns → Medium or Low (blockers go to `gaps`, not tech debt)
+- Non-critical verification gaps → Medium
+
+**Empty sections:** Omit severity sections with no items. Keep only sections that contain entries.
 
 **De-duplication:** Match by location + description similarity. An item in Dismissed is never re-added as Active — if the same issue recurs, note it as a new item referencing the original.
 

package/mindsystem/workflows/complete-milestone.md

@@ -23,13 +23,15 @@ This is the ritual that separates "development" from "shipped."
 When a milestone completes, this workflow:
 
 1. Cleans up raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER deleted)
-2. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
-3. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
-4. Archives milestone context to `.planning/milestones/v[X.Y]-CONTEXT.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
+2. Creates `.planning/milestones/v[X.Y]/` directory for all archive files
+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. Archives milestone context to `.planning/milestones/v[X.Y]/CONTEXT.md`
+6. Archives research files to `.planning/milestones/v[X.Y]/research/` (if exists)
+7. Updates ROADMAP.md to replace milestone details with one-line summary
+8. Deletes REQUIREMENTS.md (fresh one created for next milestone)
+9. Performs full PROJECT.md evolution review
+10. Routes to `/ms:new-milestone` for next milestone
 
 Knowledge files in `.planning/knowledge/` persist across milestones (maintained by phase-level consolidation in execute-phase).
 
@@ -428,7 +430,11 @@ Extract completed milestone details and create archive file.
 
 **Process:**
 
-1. Create archive file path: `.planning/milestones/v[X.Y]-ROADMAP.md`
+1. Create milestone directory and archive file:
+   ```bash
+   mkdir -p .planning/milestones/v[X.Y]
+   ```
+   Archive file path: `.planning/milestones/v[X.Y]/ROADMAP.md`
 
 2. Read `~/.claude/mindsystem/templates/milestone-archive.md` template
 
@@ -453,7 +459,7 @@ Extract completed milestone details and create archive file.
    - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
    - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
 
-6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
+6. Write filled template to `.planning/milestones/v[X.Y]/ROADMAP.md`
 
 7. Delete ROADMAP.md (fresh one created for next milestone):
    ```bash
@@ -462,13 +468,13 @@ Extract completed milestone details and create archive file.
 
 8. Verify archive exists:
    ```bash
-   ls .planning/milestones/v[X.Y]-ROADMAP.md
+   ls .planning/milestones/v[X.Y]/ROADMAP.md
    ```
 
 9. Confirm roadmap archive complete:
 
    ```
-   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
+   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]/ROADMAP.md
    ✅ ROADMAP.md deleted (fresh one for next milestone)
    ```
 
@@ -487,7 +493,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
    cat .planning/REQUIREMENTS.md
    ```
 
-2. Create archive file: `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+2. Create archive file: `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
 
 3. Transform requirements for archive:
    - Mark all v1 requirements as `[x]` complete
@@ -531,7 +537,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 6. Confirm:
    ```
-   ✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
+   ✅ Requirements archived to milestones/v[X.Y]/REQUIREMENTS.md
    ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
    ```
 
@@ -544,13 +550,13 @@ Archive requirements and prepare for fresh requirements in next milestone.
 Move the milestone audit file to the archive (if it exists):
 
 ```bash
-# Move audit to milestones folder (if exists)
-[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
+# Move audit to milestone folder (if exists)
+[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/v[X.Y]/MILESTONE-AUDIT.md
 ```
 
 Confirm:
 ```
-✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md
+✅ Audit archived to milestones/v[X.Y]/MILESTONE-AUDIT.md
 ```
 
 (Skip silently if no audit file exists — audit is optional)
@@ -562,18 +568,35 @@ Confirm:
 Archive the milestone context file (if it exists):
 
 ```bash
-[ -f .planning/MILESTONE-CONTEXT.md ] && mv .planning/MILESTONE-CONTEXT.md .planning/milestones/v[X.Y]-CONTEXT.md
+[ -f .planning/MILESTONE-CONTEXT.md ] && mv .planning/MILESTONE-CONTEXT.md .planning/milestones/v[X.Y]/CONTEXT.md
 ```
 
 If archived:
 ```
-✅ Context archived to milestones/v[X.Y]-CONTEXT.md
+✅ Context archived to milestones/v[X.Y]/CONTEXT.md
 ```
 
 (Skip silently if no context file exists)
 
 </step>
 
+<step name="archive_research">
+
+Archive research files to milestone (if research directory exists):
+
+```bash
+[ -d .planning/research ] && mv .planning/research .planning/milestones/v[X.Y]/research
+```
+
+If archived:
+```
+✅ Research archived to milestones/v[X.Y]/research/
+```
+
+(Skip silently if no research directory exists)
+
+</step>
+
 <step name="update_state">
 
 Update STATE.md to reflect milestone completion.
@@ -645,28 +668,27 @@ git push origin v[X.Y]
 Commit milestone completion including archive files and deletions.
 
 ```bash
-# Stage archive files (new)
-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
-git add .planning/milestones/v[X.Y]-CONTEXT.md 2>/dev/null || true
+# Stage archive directory (covers ROADMAP, REQUIREMENTS, AUDIT, CONTEXT, research)
+git add .planning/milestones/v[X.Y]/
 
 # Stage updated files
 git add .planning/MILESTONES.md
 git add .planning/PROJECT.md
 git add .planning/STATE.md
 
-# Stage deletions (raw artifacts cleaned from phase directories)
+# Stage deletions (raw artifacts cleaned from phase directories, research dir removed)
 git add -u .planning/
 
 # 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)
+Archived to milestones/v[X.Y]/:
+- ROADMAP.md
+- REQUIREMENTS.md
+- MILESTONE-AUDIT.md (if audit was run)
+- CONTEXT.md (if milestone context existed)
+- research/ (if research existed)
 
 Cleaned:
 - Raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
@@ -675,6 +697,7 @@ Cleaned:
 Deleted (fresh for next milestone):
 - ROADMAP.md
 - REQUIREMENTS.md
+- .planning/research/ (archived to milestone)
 
 Updated:
 - MILESTONES.md (new entry)
@@ -699,9 +722,10 @@ 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
+Archived to milestones/v[X.Y]/:
+- ROADMAP.md
+- REQUIREMENTS.md
+- research/ (if existed)
 
 Summary: .planning/MILESTONES.md
 Tag: v[X.Y]
@@ -710,9 +734,7 @@ Tag: v[X.Y]
 
 ## ▶ Next Up
 
-**Start Next Milestone** — define goals and requirements
-
-`/ms:new-milestone`
+`/ms:new-milestone` — define goals and requirements
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -777,8 +799,10 @@ Milestone completion is successful when:
 - [ ] 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)
+- [ ] Milestone directory created (milestones/v[X.Y]/)
+- [ ] Roadmap archive created (milestones/v[X.Y]/ROADMAP.md)
+- [ ] Requirements archive created (milestones/v[X.Y]/REQUIREMENTS.md)
+- [ ] Research archived to milestone (milestones/v[X.Y]/research/) if .planning/research/ existed
 - [ ] REQUIREMENTS.md deleted (fresh for next milestone)
 - [ ] STATE.md updated with fresh project reference
 - [ ] Git tag created (v[X.Y])

package/mindsystem/workflows/define-requirements.md

@@ -289,9 +289,7 @@ Requirements defined:
 
 ## ▶ Next Up
 
-**Create roadmap** — phases mapped to requirements
-
-`/ms:create-roadmap`
+`/ms:create-roadmap` — phases mapped to requirements
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/workflows/diagnose-issues.md

@@ -181,9 +181,7 @@ Debug sessions: ${DEBUG_DIR}/
 
 ## Next Up
 
-**Plan fixes** — create fix plans from diagnosed gaps
-
-`/ms:plan-phase {phase} --gaps`
+`/ms:plan-phase {phase} --gaps` — create fix plans from diagnosed gaps
 
 `/clear` first for fresh context window
 

package/mindsystem/workflows/execute-phase.md

@@ -386,9 +386,7 @@ Present gaps and offer next command:
 
 ## ▶ Next Up
 
-**Plan gap closure** — create additional plans to complete the phase
-
-`/ms:plan-phase {X} --gaps`
+`/ms:plan-phase {X} --gaps` — create additional plans to complete the phase
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/workflows/map-codebase.md

@@ -271,9 +271,7 @@ Created .planning/codebase/:
 
 ## ▶ Next Up
 
-**Initialize project** — use codebase context for planning
-
-`/ms:new-project`
+`/ms:new-project` — use codebase context for planning
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/workflows/plan-phase.md

@@ -74,7 +74,7 @@ ls .planning/codebase/*.md 2>/dev/null
 | database, schema, models | ARCHITECTURE.md, STACK.md |
 | testing, tests | TESTING.md, CONVENTIONS.md |
 | integration, external API | INTEGRATIONS.md, STACK.md |
-| refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
+| refactor, cleanup, quality, tech debt | CONCERNS.md, ARCHITECTURE.md |
 | setup, config | STACK.md, STRUCTURE.md |
 | (default) | STACK.md, ARCHITECTURE.md |
 
@@ -213,9 +213,7 @@ Also create or update EXECUTION-ORDER.md to include gap closure plans (typically
 
 ## ▶ Next Up
 
-**Execute gap closure plans**
-
-`/ms:execute-phase {X}`
+`/ms:execute-phase {X}` — execute gap closure plans
 
 <sub>`/clear` first → fresh context window</sub>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.16.2",
+  "version": "3.17.1",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"