mindsystem-cc 4.0.3 → 4.1.0

package/README.md

@@ -31,6 +31,9 @@ npx mindsystem-cc
 [ new-milestone ]       Define what to build next
         │
         ▼
+[ research-milestone ]  (optional) Research domain before roadmapping
+        │
+        ▼
 [ create-roadmap ]      Derive requirements, map to phases
         │
         ▼
@@ -82,7 +85,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 +107,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 +119,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 +129,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 +139,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 +153,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 +167,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 +181,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
@@ -250,6 +263,15 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 
 ---
 
+## Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- [Node.js](https://nodejs.org/) (for `npx`)
+- [uv](https://docs.astral.sh/uv/) — Python package runner used by CLI scripts (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- Python 3.10+ (used by uv for scripts)
+
+---
+
 ## Quick start
 
 ### New project
@@ -337,12 +359,8 @@ 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
+├── MILESTONE-RESEARCH.md              # /ms:research-milestone → domain ecosystem
+│                                      #   Technology, product landscape, architecture, risks
 │
 ├── adhoc/                            # /ms:adhoc → out-of-pipeline work
 │   └── 2026-01-15-fix-token/
@@ -364,10 +382,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
@@ -429,7 +446,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 |

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

@@ -420,9 +420,9 @@ function generateWrappers(claudeDir) {
   fs.mkdirSync(binDir, { recursive: true });
 
   const wrappers = {
-    'ms-tools': '#!/usr/bin/env bash\nexec uv run "$(dirname "$0")/../mindsystem/scripts/ms-tools.py" "$@"\n',
+    'ms-tools': '#!/usr/bin/env bash\n[ -f "$HOME/.local/bin/env" ] && . "$HOME/.local/bin/env"\nexec uv run "$(dirname "$0")/../mindsystem/scripts/ms-tools.py" "$@"\n',
     'ms-lookup': '#!/usr/bin/env bash\nexec "$(dirname "$0")/../mindsystem/scripts/ms-lookup-wrapper.sh" "$@"\n',
-    'ms-compare-mockups': '#!/usr/bin/env bash\nexec uv run "$(dirname "$0")/../mindsystem/scripts/compare_mockups.py" "$@"\n',
+    'ms-compare-mockups': '#!/usr/bin/env bash\n[ -f "$HOME/.local/bin/env" ] && . "$HOME/.local/bin/env"\nexec uv run "$(dirname "$0")/../mindsystem/scripts/compare_mockups.py" "$@"\n',
   };
 
   for (const [name, content] of Object.entries(wrappers)) {
@@ -444,11 +444,6 @@ function ensurePathHook(claudeDir, isGlobal, configDir) {
   if (!Array.isArray(settings.hooks.SessionStart))
     settings.hooks.SessionStart = [];
 
-  // Idempotent — skip if already present
-  const marker = 'mindsystem/bin';
-  if (settings.hooks.SessionStart.some(e => JSON.stringify(e).includes(marker)))
-    return;
-
   // Build PATH expression
   let binExpr;
   if (isGlobal) {
@@ -459,6 +454,14 @@ function ensurePathHook(claudeDir, isGlobal, configDir) {
     binExpr = '$CLAUDE_PROJECT_DIR/.claude/bin';
   }
 
+  // Self-healing: remove all existing Mindsystem PATH hooks, then add exactly one.
+  // This deduplicates any prior entries AND prevents future duplicates.
+  const before = settings.hooks.SessionStart.length;
+  settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+    e => !JSON.stringify(e).includes('CLAUDE_ENV_FILE')
+  );
+  const removed = before - settings.hooks.SessionStart.length;
+
   settings.hooks.SessionStart.push({
     matcher: '',
     hooks: [{
@@ -468,7 +471,11 @@ function ensurePathHook(claudeDir, isGlobal, configDir) {
   });
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-  console.log(`  ${green}✓${reset} Configured PATH hook`);
+  if (removed > 0) {
+    console.log(`  ${green}✓${reset} Configured PATH hook (cleaned ${removed} duplicate(s))`);
+  } else {
+    console.log(`  ${green}✓${reset} Configured PATH hook`);
+  }
 }
 
 /**
@@ -654,6 +661,20 @@ async function install(isGlobal) {
     }
   }
 
+  // Phase 8b: Check uv
+  try {
+    const { execSync } = require('child_process');
+    const uvVersion = execSync('uv --version 2>&1', { encoding: 'utf8' }).trim();
+    console.log(`  ${green}✓${reset} Found ${uvVersion}`);
+  } catch (e) {
+    const isWin = process.platform === 'win32';
+    const installCmd = isWin
+      ? 'powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"'
+      : 'curl -LsSf https://astral.sh/uv/install.sh | sh';
+    console.log(`  ${yellow}⚠${reset} uv not found — CLI wrappers (ms-tools, ms-compare-mockups) require it`);
+    console.log(`    Install: ${cyan}${installCmd}${reset}`);
+  }
+
   // Phase 9: Cleanup orphaned files
   if (orphans.length > 0) {
     console.log('');

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

package/commands/ms/doctor.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <objective>
-Run health checks on project configuration. Detect and fix structural drift across 10 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers, research API keys, and Mindsystem version.
+Run health checks on project configuration. Detect and fix structural drift across 10 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers and environment diagnostics, research API keys, and Mindsystem version.
 
 Idempotent.
 </objective>
@@ -117,7 +117,7 @@ Display results as a markdown table:
 | Knowledge files          | FAIL   | Directory missing                |
 | Phase summaries          | FAIL   | 2 milestones missing summaries   |
 | PLAN cleanup             | FAIL   | 9 leftover PLAN.md files         |
-| CLI wrappers             | FAIL   | ms-tools not on PATH             |
+| CLI wrappers             | FAIL   | Not resolvable; bin dir not in PATH |
 | Research API Keys        | WARN   | PERPLEXITY_API_KEY not set        |
 | Mindsystem version       | WARN   | v3.21.0 → v3.22.1 available       |
 ```
@@ -143,7 +143,7 @@ If "Review each" → use AskUserQuestion for each failed check with its details
 
 Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
 
-Phase summaries are resolved by fix_phase_archival. CLI wrappers require manual PATH configuration (no automated fix). WARN checks (Research API Keys) are informational — no fix offered, only displayed in the report.
+Phase summaries are resolved by fix_phase_archival. CLI wrapper failures have specific fixes: bin dir not in PATH → restart Claude Code session; missing wrappers or bin dir → re-run `npx mindsystem-cc`; uv not found → `curl -LsSf https://astral.sh/uv/install.sh | sh`. WARN checks (Research API Keys, missing uv) are informational — no automated fix, only displayed in the report.
 </step>
 
 <step name="apply_fixes">