mindsystem-cc 4.0.4 → 4.1.1

package/README.md

@@ -2,9 +2,9 @@
 
 # MINDSYSTEM
 
-**A meta-prompting and context engineering system for Claude Code.**
+**The engineer's meta-prompting system for Claude Code.**
 
-Every piece of work makes the next one better. Mindsystem structures your Claude Code sessions into plannable, executable, verifiable phases, and compounds what it learns into persistent knowledge files that survive `/clear`. Context rot stops being the bottleneck. Every prompt in the system is tested against research on how LLMs actually follow instructions, so quality stays consistent from phase 1 to phase 20.
+Amplifies every step of the development workflow you already follow — discovery, research, design, planning, execution, verification. Each one refined, parallelized, and compounded into persistent knowledge. Built for engineers who want to multiply their output without giving up control.
 
 ```bash
 npx mindsystem-cc
@@ -19,18 +19,41 @@ npx mindsystem-cc
 
 <br>
 
-[How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [.planning](#the-planning-directory) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
+[Why Mindsystem](#why-mindsystem) · [How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [.planning](#the-planning-directory) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
 
 </div>
 
 ---
 
+## Why Mindsystem
+
+Fully autonomous coding tools take a spec and run for hours until a product emerges. That works for prototypes and one-shot projects.
+
+Mindsystem takes the opposite approach. It follows the same workflow a thorough engineer already uses — and amplifies each step:
+
+| What you'd do manually | What Mindsystem does |
+|---|---|
+| Talk through requirements, catch misalignment early | **Discuss phase** surfaces assumptions with confidence levels, forces tradeoff decisions before any code gets written |
+| Google libraries, read a few docs | **Research phase** runs 3 parallel agents across documentation, your codebase, and community practices — 10x more sources, synthesized in minutes |
+| Try design directions, pick the best one | **Design phase** generates parallel HTML/CSS mockups with side-by-side comparison and exact design tokens |
+| Plan from what you remember about the codebase | **Plan phase** loads knowledge files capturing every decision, pattern, and pitfall from prior phases |
+| Figure out what states to test, mock them manually | **Verify work** determines mock states automatically — you validate visually or programmatically |
+
+The workflow stays yours. Each step finishes in minutes instead of hours. Everything learned compounds into knowledge that survives context resets — phase 10 starts with everything the project learned from phases 1–9.
+
+This is not an autopilot. It's a force multiplier.
+
+---
+
 ## How it works
 
 ```
 [ new-milestone ]       Define what to build next
         │
         ▼
+[ research-milestone ]  (optional) Research domain before roadmapping
+        │
+        ▼
 [ create-roadmap ]      Derive requirements, map to phases
         │
         ▼
@@ -72,6 +95,12 @@ Execution happens in fresh subagent contexts, so each plan gets up to 200k token
 
 ## End-to-end walkthrough
 
+### Project setup
+
+Before building features, initialize the project once with `/ms:new-project`. For existing codebases, also run `/ms:map-codebase` (analyzes your stack, conventions, and architecture into 7 structured documents) and `/ms:doctor` (validates config and generates per-subsystem knowledge files from source code). See [Quick start](#quick-start) for the exact sequences.
+
+Everything below is the feature-building loop, identical for new and existing projects.
+
 ### 1. New milestone
 
 ```
@@ -82,7 +111,17 @@ Claude reads your project history (tech debt, deferred requirements, validated d
 
 Think of it as guided brainstorming: Claude asks the right questions rather than prescribing answers, helping you figure out what to build next.
 
-### 2. Create roadmap
+### 2. Research milestone (optional)
+
+```
+/ms:research-milestone
+```
+
+Spawns 2-5 research agents adapted to your milestone scope — ecosystem/stack, product landscape, codebase feasibility, architecture, pitfalls. You approve which dimensions to research, then agents run in parallel.
+
+Produces `MILESTONE-RESEARCH.md` that the roadmapper consumes for better phase breakdowns. Valuable when entering unfamiliar domains, evaluating new tech stacks, or starting a project's first milestone.
+
+### 3. Create roadmap
 
 ```
 /ms:create-roadmap
@@ -94,7 +133,7 @@ Requirements define what must be TRUE when you ship, not what to build. This goa
 
 **Creates:** `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, phase directories.
 
-### 3. Discuss phase (optional, recommended)
+### 4. Discuss phase (optional, recommended)
 
 ```
 /ms:discuss-phase 1
@@ -106,7 +145,7 @@ Worth taking seriously. Decisions here propagate through everything that follows
 
 **Creates:** `CONTEXT.md` with vision, essentials, and reasoning-backed decisions.
 
-### 4. Design phase (optional)
+### 5. Design phase (optional)
 
 ```
 /ms:design-phase 1
@@ -116,7 +155,7 @@ Claude generates parallel HTML/CSS mockup variants and a side-by-side comparison
 
 The output is a `DESIGN.md` with exact design tokens (hex colors, px spacing, font weights), not descriptions of what things should look like.
 
-### 5. Research phase (optional)
+### 6. Research phase (optional)
 
 ```
 /ms:research-phase 1
@@ -126,7 +165,7 @@ Three parallel agents investigate at once: one queries external documentation th
 
 You resolve library conflicts if any come up. Otherwise, this runs with minimal input.
 
-### 6. Plan phase
+### 7. Plan phase
 
 ```
 /ms:plan-phase 1
@@ -140,7 +179,7 @@ You approve the plan structure and can adjust granularity.
 
 **Creates:** `PLAN.md` files, `EXECUTION-ORDER.md`.
 
-### 7. Execute phase
+### 8. Execute phase
 
 ```
 /ms:execute-phase 1
@@ -154,7 +193,7 @@ After execution, knowledge consolidation updates subsystem-scoped knowledge file
 
 **Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, knowledge file updates.
 
-### 8. Verify work
+### 9. Verify work
 
 ```
 /ms:verify-work 1
@@ -168,21 +207,21 @@ Fixes compound into knowledge files through automatic consolidation. This is whe
 
 **Creates:** `UAT.md`, `uat-fixes.patch`, knowledge file updates.
 
-### 9. Repeat
+### 10. Repeat
 
-Run steps 3-8 for each phase. Pick the preparation depth each phase needs.
+Run steps 4-9 for each phase. Pick the preparation depth each phase needs.
 
-### 10. Audit milestone
+### 11. Audit milestone
 
 ```
 /ms:audit-milestone
 ```
 
-Claude checks requirements coverage against `REQ-IDs`, spawns an integration checker for cross-phase wiring, aggregates untested UAT assumptions, and consolidates tech debt into `TECH-DEBT.md` with severity tiers and `TD-IDs`.
+Claude checks requirements coverage against `REQ-IDs`, verifies cross-phase wiring from verification artifacts, aggregates untested UAT assumptions, and consolidates tech debt into `TECH-DEBT.md` with severity tiers and `TD-IDs`.
 
 Optional code review with quality-phase decisions for high-impact findings. You decide what gets fixed vs. accepted as debt.
 
-### 11. Complete milestone
+### 12. Complete milestone
 
 ```
 /ms:complete-milestone
@@ -261,31 +300,37 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 
 ## Quick start
 
-### New project
+### Project setup (one-time)
+
+**New project:**
 
 ```
 /ms:new-project
-/ms:new-milestone
-/ms:create-roadmap
-/ms:plan-phase 1
-/ms:execute-phase 1
-/ms:verify-work 1
 ```
 
-You'll get `.planning/` with your project vision, milestone context, requirements, roadmap, and the first phase implemented with commits, patch files, and knowledge files.
+**Existing codebase:**
+
+```
+/ms:new-project                 # Business context and vision
+/ms:map-codebase                # Analyze code → 7 structured documents
+/ms:doctor                      # Validate config, generate knowledge files
+```
+
+Optional: `/ms:config` — configure code reviewers, gitignore, and other preferences.
+
+### Building features
 
-### Existing project
+Once the project is set up, the workflow is the same for new and existing codebases:
 
 ```
-/ms:new-project
-/ms:map-codebase
-/ms:new-milestone
-/ms:create-roadmap
-/ms:plan-phase 1
-/ms:execute-phase 1
+/ms:new-milestone               # Discover what to build next
+/ms:create-roadmap              # Define requirements, map to phases
+/ms:plan-phase 1                # Create detailed plan
+/ms:execute-phase 1             # Run in fresh subagents
+/ms:verify-work 1               # Manual acceptance testing
 ```
 
-Codebase mapping produces 7 documents covering your stack, conventions, and architecture. Then you define what to build, and all downstream planning respects what's already there.
+Repeat for each milestone. All downstream planning automatically loads codebase docs and knowledge files.
 
 **Returning after a break?** Run `/ms:progress` to see where you left off and what to do next.
 
@@ -302,6 +347,7 @@ Every artifact Mindsystem generates lives in `.planning/` — a markdown knowled
 │
 ├── STATE.md                          # Active phase, blockers, recent decisions
 ├── MILESTONE-CONTEXT.md              # new-milestone → brainstorm that grounds the roadmap
+├── MILESTONE-RESEARCH.md             # research-milestone → domain research before roadmapping
 ├── ROADMAP.md                        # Phase breakdown with goals and success criteria
 ├── REQUIREMENTS.md                   # Checkable REQ-IDs mapped to phases
 │
@@ -346,13 +392,6 @@ Every artifact Mindsystem generates lives in `.planning/` — a markdown knowled
 │       ├── CONTEXT.md                #   discussed, not yet planned
 │       └── 02-01-PLAN.md             #   planned, not yet executed
 │
-├── research/                         # /ms:research-project → domain ecosystem
-│   ├── STACK.md                      # Technology recommendations for this domain
-│   ├── ARCHITECTURE.md               # Common system structure patterns
-│   ├── FEATURES.md                   # Feature landscape in this domain
-│   ├── PITFALLS.md                   # Mistakes to avoid
-│   └── SUMMARY.md                    # Synthesized findings with roadmap implications
-│
 ├── adhoc/                            # /ms:adhoc → out-of-pipeline work
 │   └── 2026-01-15-fix-token/
 │       ├── adhoc-01-SUMMARY.md       # Execution results and learnings
@@ -373,10 +412,9 @@ Every artifact Mindsystem generates lives in `.planning/` — a markdown knowled
         ├── ROADMAP.md                # Historical phase breakdown
         ├── REQUIREMENTS.md           # Final requirement status
         ├── PHASE-SUMMARIES.md        # Consolidated execution summaries
-        ├── MILESTONE-AUDIT.md        # Requirements coverage, integration check
+        ├── MILESTONE-AUDIT.md        # Requirements coverage, cross-phase wiring check
         ├── CONTEXT.md                # Original milestone brainstorm
-        ├── research/                 # Archived domain research
-        │   └── ...
+        ├── MILESTONE-RESEARCH.md     # Archived domain research (if existed)
         └── phases/                   # Archived phase artifacts
             └── 01-foundation/
                 ├── 01-changes.patch  #   code diffs retained
@@ -438,7 +476,7 @@ Full docs live in `/ms:help`.
 | `/ms:new-project` | Initialize `.planning/` and capture project intent |
 | `/ms:config` | Configure code reviewers, mockups, gitignore, git remote |
 | `/ms:map-codebase` | Document existing repo's stack, structure, and conventions |
-| `/ms:research-project` | Domain research saved to `.planning/research/` |
+| `/ms:research-milestone` | Milestone-scoped research saved to `.planning/MILESTONE-RESEARCH.md` |
 | `/ms:create-roadmap` | Define requirements and create phases mapped to them |
 | `/ms:new-milestone [name]` | Discover what to build next, start new milestone |
 | `/ms:discuss-phase <number>` | Product-informed collaborative thinking before planning |
@@ -515,4 +553,4 @@ MIT License. See [LICENSE](LICENSE) for details.
 
 ---
 
-Inspired by [GSD](https://github.com/gsd-build/get-shit-done) and [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin).
+Originally rooted in [GSD](https://github.com/gsd-build/get-shit-done), now an independent system with its own philosophy. Knowledge compounding inspired by [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin).

package/agents/ms-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: ms-researcher
-description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /ms:research-phase and /ms:research-project orchestrators.
+description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /ms:research-phase and /ms:research-milestone orchestrators.
 model: opus
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 color: cyan
@@ -12,7 +12,7 @@ You are a Mindsystem researcher. You conduct comprehensive research using system
 You are spawned by:
 
 - `/ms:research-phase` orchestrator (phase-specific research before planning)
-- `/ms:research-project` orchestrator (project-wide research before roadmap)
+- `/ms:research-milestone` orchestrator (milestone-scoped research before roadmap)
 
 Your job: Answer research questions with verified, actionable findings. Produce structured output files that inform quality planning.
 </role>
@@ -461,7 +461,7 @@ Output format templates are in `~/.claude/mindsystem/templates/`. Read the match
 | Research Type | Template |
 |---------------|----------|
 | Phase research | `~/.claude/mindsystem/templates/research.md` |
-| Project research | `~/.claude/mindsystem/templates/research-project-output.md` |
+| Milestone research | `~/.claude/mindsystem/templates/milestone-research.md` |
 | Comparison | `~/.claude/mindsystem/templates/research-comparison-output.md` |
 | Feasibility | `~/.claude/mindsystem/templates/research-feasibility-output.md` |
 

package/agents/ms-roadmapper.md

@@ -52,7 +52,7 @@ Parse the milestone context for:
 
 If PROJECT.md has a `## Deferred` section, treat those items as v1 candidates for this milestone. Cross-reference deferred items with milestone context — if the milestone naturally covers a deferred item, promote to v1; if not relevant to this milestone, keep deferred.
 
-If research/FEATURES.md exists, cross-reference:
+If MILESTONE-RESEARCH.md exists, cross-reference Product Landscape:
 - Table stakes → strong v1 candidates
 - Differentiators → contextual (include if aligned with milestone priorities)
 - Anti-features → out of scope
@@ -413,9 +413,12 @@ Use template from `~/.claude/mindsystem/templates/roadmap.md`.
 
 Key sections:
 - Overview (2-3 sentences)
+- Research Conclusions (when MILESTONE-RESEARCH.md was provided)
 - Phases with Goal, Dependencies, Requirements, Success Criteria
 - Progress table
 
+**Research Conclusions:** When MILESTONE-RESEARCH.md is provided, add a `## Research Conclusions` section between Overview and Phases. Subsections: Technology Stack, Key Constraints, Architecture Decisions, Risk Mitigations. Extract from MILESTONE-RESEARCH.md sections. This is the mechanism for downstream passthrough — plan-phase, discuss-phase, and research-phase consume this implicitly by reading ROADMAP.md.
+
 ## STATE.md Structure
 
 Use template from `~/.claude/mindsystem/templates/state.md`.
@@ -492,8 +495,7 @@ Approve roadmap or provide feedback for revision.
 Orchestrator provides:
 - MILESTONE-CONTEXT.md content (or gathered context from user questioning)
 - PROJECT.md content (core value, constraints)
-- research/FEATURES.md content (if exists - feature categorization)
-- research/SUMMARY.md content (if exists - phase suggestions)
+- MILESTONE-RESEARCH.md content (if exists - technology decisions, product landscape, architecture, risks)
 - config.json (starting phase number)
 
 Parse and confirm understanding before proceeding.
@@ -506,9 +508,12 @@ Apply `<requirements_derivation>` process. Write REQUIREMENTS.md immediately usi
 
 ## Step 3: Load Research Context (if exists)
 
-If research/SUMMARY.md provided:
-- Extract suggested phase structure from "Implications for Roadmap"
-- Note research flags (which phases need deeper research)
+If MILESTONE-RESEARCH.md provided:
+- Extract technology decisions and constraints
+- Use Architecture & Dependencies for phase ordering
+- Use Pitfalls for pre-work Research indicator enrichment
+- Use Feasibility constraints for phase boundary decisions
+- Use Open Questions to populate per-phase Research topics
 - Use as input, not mandate
 
 Research informs phase identification but requirements drive coverage.

package/bin/install.js

@@ -471,8 +471,8 @@ function ensurePathHook(claudeDir, isGlobal, configDir) {
   });
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-  if (removed > 0) {
-    console.log(`  ${green}✓${reset} Configured PATH hook (cleaned ${removed} duplicate(s))`);
+  if (removed > 1) {
+    console.log(`  ${green}✓${reset} Configured PATH hook (cleaned ${removed - 1} duplicate(s))`);
   } else {
     console.log(`  ${green}✓${reset} Configured PATH hook`);
   }

package/commands/ms/audit-milestone.md

@@ -9,12 +9,13 @@ allowed-tools:
   - Bash
   - Task
   - Write
+  - AskUserQuestion
 ---
 
 <objective>
 Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
 
-**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), generates/updates `.planning/TECH-DEBT.md` as single source of truth for tech debt, then spawns integration checker for cross-phase wiring.
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), generates/updates `.planning/TECH-DEBT.md` as single source of truth for tech debt, then checks cross-phase wiring inline from verification and summary artifacts.
 </objective>
 
 <execution_context>
@@ -37,7 +38,7 @@ Glob: .planning/phases/*/*-SUMMARY.md
 Glob: .planning/phases/*/*-VERIFICATION.md
 
 **Tech Debt:**
-Read `.planning/TECH-DEBT.md` at Step 8.5 (lazy — only needed for de-duplication)
+Read `.planning/TECH-DEBT.md` at Step 7.5 (lazy — only needed for de-duplication)
 </context>
 
 <process>
@@ -100,37 +101,33 @@ assumptions:
           reason: "Can't manipulate time in tests"
 ```
 
-## 3. Spawn Integration Checker
+## 3. Cross-Phase Wiring Check
 
-With phase context collected:
+Check aggregate cross-phase connections that per-phase verifiers miss.
 
-```
-Task(
-  prompt="Check cross-phase integration and E2E flows.
+From the SUMMARY.md and VERIFICATION.md files already loaded in Step 2:
 
-Phases: {phase_dirs}
-Phase exports: {from SUMMARYs}
-API routes: {routes created}
+1. **Build provides/consumes map** — For each phase SUMMARY, extract key exports, files created, APIs defined. Identify what each phase provides and what it consumes from other phases.
 
-Verify cross-phase wiring and E2E user flows.",
-  subagent_type="ms-integration-checker"
-)
-```
+2. **Cross-reference verification results** — For each cross-phase dependency (Phase N consumes something Phase M provides), check Phase M's VERIFICATION.md:
+   - Provider artifact is VERIFIED → connection satisfied
+   - Provider artifact is STUB, MISSING, or ORPHANED → wiring gap
 
-## 4. Collect Results
+3. **Flag aggregate patterns** — Multiple orphaned artifacts across phases (systemic wiring issue). APIs/exports created but consumed by no other phase's SUMMARY. A phase depending on another phase with status: gaps_found.
 
-Combine:
-- Phase-level gaps and tech debt (from step 2)
-- Integration checker's report (wiring gaps, broken flows)
+Produce a wiring summary:
+- **Connected:** N cross-phase dependencies satisfied
+- **Gaps:** N unsatisfied (list each: from-phase → to-phase, what's missing)
+- **Score:** wiring = connected / (connected + gaps)
 
-## 5. Check Requirements Coverage
+## 4. Check Requirements Coverage
 
 For each requirement in REQUIREMENTS.md mapped to this milestone:
 - Find owning phase
 - Check phase verification status
 - Determine: satisfied | partial | unsatisfied
 
-## 6. Aggregate into MILESTONE-AUDIT.md
+## 5. Aggregate into MILESTONE-AUDIT.md
 
 Create `.planning/MILESTONE-AUDIT.md` with:
 
@@ -142,12 +139,10 @@ status: passed | gaps_found | tech_debt
 scores:
   requirements: N/M
   phases: N/M
-  integration: N/M
-  flows: N/M
+  wiring: N/M
 gaps:  # Critical blockers
   requirements: [...]
-  integration: [...]
-  flows: [...]
+  wiring: [...]
 tech_debt: see .planning/TECH-DEBT.md
 assumptions:  # Tests skipped during UAT
   count: [N]
@@ -182,11 +177,11 @@ Plus full markdown report with tables for requirements, phases, integration, and
 - `gaps_found` — critical blockers exist
 - `tech_debt` — no blockers but accumulated deferred items need review
 
-## 7. Present Results
+## 6. Present Audit Summary
 
-Route by status (see `<offer_next>`).
+Present the audit summary (status, scores, gaps) to the user. Continue to Step 7.
 
-## 8. Code Review (Milestone)
+## 7. Code Review (Milestone)
 
 Read code review agent from config:
 
@@ -202,7 +197,7 @@ Proceed to next steps.
 Report: "No milestone reviewer configured. Run `/ms:config` to set one."
 Skip code review step (proceed to next steps).
 
-### Step 8.1: Get Changed Files
+### Step 7.1: Get Changed Files
 
 ```bash
 # Find first commit in milestone (first phase commit)
@@ -213,7 +208,7 @@ FIRST_COMMIT=$(git log --oneline --grep="(${FIRST_PHASE}-" --format="%H" | tail
 CHANGED_FILES=$(git diff --name-only ${FIRST_COMMIT}^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')
 ```
 
-### Step 8.2: Spawn Code Review Agent
+### Step 7.2: Spawn Code Review Agent
 
 ```
 Task(
@@ -246,7 +241,7 @@ Task(
 )
 ```
 
-### Step 8.3: Handle Results
+### Step 7.3: Handle Results
 
 The agent controls its own behavior — it may modify files, report findings, or both. React to what actually happened.
 
@@ -295,7 +290,7 @@ Add markdown section to report body:
 {Include full findings report from reviewer}
 ```
 
-Code review findings flow into `.planning/TECH-DEBT.md` via Step 8.5 — do NOT add them to `tech_debt` YAML.
+Code review findings flow into `.planning/TECH-DEBT.md` via Step 7.5 — do NOT add them to `tech_debt` YAML.
 
 **If any findings were reported**, present a decision gate. Recommend based on findings profile:
 
@@ -360,16 +355,16 @@ Continue to offer_next section.
 
 **If user chooses "Accept as tech debt":**
 
-Findings are already tracked in `.planning/TECH-DEBT.md` via Step 8.5. Continue to offer_next section.
+Findings are already tracked in `.planning/TECH-DEBT.md` via Step 7.5. Continue to offer_next section.
 
-## 8.5. Generate/Update TECH-DEBT.md
+## 7.5. Generate/Update TECH-DEBT.md
 
 After code review (all sources now available), generate or update `.planning/TECH-DEBT.md`:
 
 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 with severity mapping:
-   - Integration checker bugs → **Critical**
+   - Cross-phase wiring gaps → **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)
@@ -378,7 +373,7 @@ After code review (all sources now available), generate or update `.planning/TEC
 5. **Assign `TD-{N}` IDs** continuing from highest existing ID
 6. **Write/update** `.planning/TECH-DEBT.md` — group items under `## Critical`, `## High`, `## Medium`, `## Low` sections per template. Omit empty sections.
 
-## 9. Commit Audit Report
+## 8. Commit Audit Report
 
 ```bash
 git add .planning/MILESTONE-AUDIT.md .planning/TECH-DEBT.md
@@ -386,7 +381,7 @@ git commit -m "$(cat <<'EOF'
 docs(milestone): complete {name} audit
 
 Status: {status}
-Scores: Requirements {N}/{M} | Phases {N}/{M} | Integration {N}/{M} | Flows {N}/{M}
+Scores: Requirements {N}/{M} | Phases {N}/{M} | Wiring {N}/{M}
 EOF
 )"
 ```
@@ -402,12 +397,10 @@ Read `~/.claude/mindsystem/references/routing/audit-result-routing.md` and follo
 - [ ] If quality phase chosen: Phase directory created, ROADMAP updated with TECH-DEBT.md scope
 - [ ] If files modified by reviewer: changes committed
 - [ ] If findings reported: parsed and added to MILESTONE-AUDIT.md
-- [ ] MILESTONE-AUDIT.md and TECH-DEBT.md committed to git
-- [ ] Tech debt collected into .planning/TECH-DEBT.md (de-duplicated, TD-{N} IDs assigned)
-- [ ] UAT assumptions collected and aggregated by phase
-- [ ] Integration checker spawned for cross-phase wiring
 - [ ] Code review completed (or skipped if config says "skip")
-- [ ] All phase VERIFICATION.md files read
-- [ ] MILESTONE-AUDIT.md created with assumptions section
+- [ ] Tech debt collected into .planning/TECH-DEBT.md (de-duplicated, TD-{N} IDs assigned)
+- [ ] UAT assumptions collected, aggregated by phase, and included in MILESTONE-AUDIT.md
+- [ ] MILESTONE-AUDIT.md and TECH-DEBT.md committed to git
+- [ ] Cross-phase wiring checked from all phase verification and summary artifacts
 - [ ] Results presented with actionable next steps
 </success_criteria>

package/commands/ms/create-roadmap.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 Define project requirements and create roadmap with phase breakdown.
 
-Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-project`.
+Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-milestone`.
 </objective>
 
 <execution_context>
@@ -23,8 +23,7 @@ Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-proj
 <context>
 @.planning/PROJECT.md
 @.planning/MILESTONE-CONTEXT.md (if exists)
-@.planning/research/FEATURES.md (if exists)
-@.planning/research/SUMMARY.md (if exists)
+@.planning/MILESTONE-RESEARCH.md (if exists)
 </context>
 
 <process>
@@ -36,7 +35,7 @@ Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-proj
 
 # Detect available context
 [ -f .planning/MILESTONE-CONTEXT.md ] && echo "HAS_MILESTONE_CONTEXT" || echo "NO_MILESTONE_CONTEXT"
-[ -d .planning/research ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
+[ -f .planning/MILESTONE-RESEARCH.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
 [ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
 [ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
 ```
@@ -64,7 +63,7 @@ If "Replace": Continue
 
 **If MILESTONE-CONTEXT.md exists:** Skip (context ready for agent).
 
-**If no MILESTONE-CONTEXT.md but HAS_RESEARCH:** Skip (research provides feature context).
+**If no MILESTONE-CONTEXT.md but HAS_RESEARCH:** Skip (MILESTONE-RESEARCH.md provides feature context).
 
 **If neither exists (first milestone, no research):**
 
@@ -122,8 +121,7 @@ Task(
 **Starting phase number:** $START_PHASE
 
 **Research (if exists):**
-@.planning/research/FEATURES.md
-@.planning/research/SUMMARY.md
+@.planning/MILESTONE-RESEARCH.md
 
 **Config:**
 @.planning/config.json
@@ -302,25 +300,9 @@ Requirements and roadmap created:
 - Roadmap: .planning/ROADMAP.md
 - State: .planning/STATE.md
 - [X] v1 requirements, [M] phases defined
-
----
-
-## ▶ Next Up
-
-**Phase 1: [Name]** — [Goal from ROADMAP.md]
-
-`/ms:plan-phase 1`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/ms:discuss-phase 1` — gather context first
-- `/ms:research-phase 1` — investigate unknowns
-
----
 ```
+
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions to present "Next Up" with pre-work context for Phase $START_PHASE.
 </step>
 
 <step name="update_last_command">