mindsystem-cc 4.0.2 → 4.0.4

package/README.md

@@ -19,7 +19,7 @@ npx mindsystem-cc
 
 <br>
 
-[How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
+[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>
 
@@ -250,6 +250,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
@@ -282,6 +291,103 @@ Codebase mapping produces 7 documents covering your stack, conventions, and arch
 
 ---
 
+## The .planning directory
+
+Every artifact Mindsystem generates lives in `.planning/` — a markdown knowledge base that grows with your project. Commands read from it, execution enriches it, and it all survives `/clear` boundaries and context resets. Here's what a project looks like after a couple of milestones:
+
+```
+.planning/
+├── PROJECT.md                        # Living spec — vision, users, flows, decisions
+├── MILESTONES.md                     # Registry of completed milestones
+│
+├── STATE.md                          # Active phase, blockers, recent decisions
+├── MILESTONE-CONTEXT.md              # new-milestone → brainstorm that grounds the roadmap
+├── ROADMAP.md                        # Phase breakdown with goals and success criteria
+├── REQUIREMENTS.md                   # Checkable REQ-IDs mapped to phases
+│
+├── TECH-DEBT.md                      # Prioritized debt — TD-IDs, severity tiers
+├── config.json                       # Subsystems, code review tiers, preferences
+│
+├── knowledge/                        # Persists across milestones
+│   ├── auth.md                       # Patterns, decisions, pitfalls per subsystem
+│   ├── api.md                        # Enriched after every execute and verify cycle
+│   └── ui.md                         # Future phases load relevant files automatically
+│
+├── codebase/                         # /ms:map-codebase → existing repo analysis
+│   ├── STACK.md                      # Runtime, frameworks, key dependencies
+│   ├── ARCHITECTURE.md               # Modules, layers, data flow patterns
+│   ├── STRUCTURE.md                  # Directory layout and file organization
+│   ├── CONVENTIONS.md                # Naming, style, established patterns
+│   ├── TESTING.md                    # Test framework, coverage, how to add tests
+│   ├── INTEGRATIONS.md               # External services and API connections
+│   └── CONCERNS.md                   # Known issues, areas requiring care
+│
+├── phases/                           # Active milestone work
+│   │
+│   ├── 01-auth-foundation/           # ── Fully executed phase ──
+│   │   ├── CONTEXT.md                # discuss-phase → locked intent and decisions
+│   │   ├── DESIGN.md                 # design-phase → exact tokens, layout, interactions
+│   │   ├── RESEARCH.md               # research-phase → library picks, patterns, tradeoffs
+│   │   ├── 01-01-PLAN.md             # plan-phase → executable prompt, one per budget slice
+│   │   ├── 01-02-PLAN.md             #
+│   │   ├── EXECUTION-ORDER.md        # plan-phase → wave grouping and dependencies
+│   │   ├── 01-01-SUMMARY.md          # execute-phase → what changed, patterns, learnings
+│   │   ├── 01-02-SUMMARY.md          #
+│   │   ├── VERIFICATION.md           # execute-phase → goal-backward pass/fail
+│   │   ├── UAT.md                    # verify-work → manual acceptance test results
+│   │   ├── 01-changes.patch          # execute-phase → diff of all code changes
+│   │   ├── 01-uat-fixes.patch        # verify-work → diff of fixes applied during testing
+│   │   └── mockups/                  # design-phase → HTML/CSS design exploration
+│   │       ├── variant-a.html        #   self-contained mockup
+│   │       ├── variant-b.html        #   self-contained mockup
+│   │       └── comparison.html       #   side-by-side view, opens in browser
+│   │
+│   └── 02-payment-flow/              # ── Phase in progress ──
+│       ├── 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
+│       └── adhoc-01-changes.patch    # Code diff
+│
+├── debug/                            # /ms:debug → structured investigations
+│   ├── websocket-reconnect.md        # Active investigation — survives /clear
+│   └── resolved/
+│       └── race-condition-login.md   # Root cause found, fix documented
+│
+├── todos/                            # /ms:add-todo → captured work items
+│   ├── 2026-02-01-rate-limiting.md   # Pending — priority, estimate, subsystem
+│   └── done/
+│       └── 2026-01-20-header-fix.md  # Completed via /ms:adhoc
+│
+└── milestones/                       # /ms:complete-milestone → archived history
+    └── mvp/
+        ├── ROADMAP.md                # Historical phase breakdown
+        ├── REQUIREMENTS.md           # Final requirement status
+        ├── PHASE-SUMMARIES.md        # Consolidated execution summaries
+        ├── MILESTONE-AUDIT.md        # Requirements coverage, integration check
+        ├── CONTEXT.md                # Original milestone brainstorm
+        ├── research/                 # Archived domain research
+        │   └── ...
+        └── phases/                   # Archived phase artifacts
+            └── 01-foundation/
+                ├── 01-changes.patch  #   code diffs retained
+                └── mockups/          #   design mockups retained
+                    └── ...
+```
+
+Everything is plain markdown (plus `config.json` and `.patch` diffs). The entire directory is greppable, diffable, and readable by any team member or AI assistant. Phase 1 starts from scratch. Phase 10 starts with everything the project has learned.
+
+---
+
 ## Configuration
 
 Mindsystem stores project config in `.planning/config.json`. Run `/ms:config` to change these interactively.

package/agents/ms-codebase-researcher.md

@@ -37,19 +37,15 @@ Grep/Glob for imports, class names, and file patterns related to the research qu
 
 Read `.planning/codebase/*.md` if they exist (from `/ms:map-codebase`). Extract relevant conventions, stack info, architecture patterns.
 
-## 4. Learnings
-
-Grep `.planning/LEARNINGS.md` for entries matching phase keywords, subsystem, or tech terms. Extract matched entries verbatim.
-
-## 5. Prior Phase Summaries
+## 4. Prior Phase Summaries
 
 Scan `.planning/phases/*/SUMMARY.md` frontmatter only (first 25 lines) for `tech-stack`, `patterns-established`, `key-decisions` matching the phase domain. Read full summary only for direct matches.
 
-## 6. Debug Resolutions
+## 5. Debug Resolutions
 
 Scan `.planning/debug/resolved/*.md` for root causes related to the phase domain.
 
-## 7. Adhoc Summaries
+## 6. Adhoc Summaries
 
 Scan `.planning/adhoc/*-SUMMARY.md` learnings arrays for relevant entries.
 
@@ -71,7 +67,7 @@ Return as text (not file). Orchestrator reads this for synthesis.
 [Pattern name, files, description — how the project already handles similar work]
 
 ### Relevant Learnings
-[Verbatim entries from LEARNINGS.md, debug resolutions, summary deviations that match]
+[Debug resolutions, adhoc learnings, summary deviations that match]
 
 ### Reusable Components
 [Existing code that could be extended or reused for this phase]
@@ -99,7 +95,7 @@ Return as text (not file). Orchestrator reads this for synthesis.
 - [ ] All findings include file:line references
 - [ ] Empty sections explicitly noted
 - [ ] Structured output returned (not written to file)
-- [ ] Learnings scanned for relevant entries
+- [ ] Debug resolutions and adhoc summaries scanned for relevant entries
 - [ ] Prior summaries checked (frontmatter only)
 - [ ] Debug resolutions checked
 </success_criteria>

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/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">

package/package.json

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

package/scripts/ms-tools.py

@@ -761,19 +761,67 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
                 record("PASS", "PLAN Cleanup")
     print()
 
-    # ---- CHECK 7: CLI Wrappers ----
+    # ---- CHECK 7: CLI Wrappers & Environment ----
     print("=== CLI Wrappers ===")
     wrapper_names = ["ms-tools", "ms-lookup", "ms-compare-mockups"]
-    missing_wrappers = [w for w in wrapper_names if shutil.which(w) is None]
-    if missing_wrappers:
+
+    # 7a: Check bin directory exists
+    global_bin = Path.home() / ".claude" / "bin"
+    local_bin = Path(".claude") / "bin"
+    bin_dir = global_bin if global_bin.is_dir() else (local_bin if local_bin.is_dir() else None)
+
+    if bin_dir is None:
         print("Status: FAIL")
-        print(f"Not on PATH: {', '.join(missing_wrappers)}")
-        print("Fix: re-run `npx mindsystem-cc` to regenerate wrappers and PATH hook")
+        print("Bin directory not found (~/.claude/bin/ or .claude/bin/)")
+        print("Fix: re-run `npx mindsystem-cc` to generate wrappers")
         record("FAIL", "CLI Wrappers")
     else:
-        print("Status: PASS")
-        print(f"All {len(wrapper_names)} CLI wrappers found on PATH")
-        record("PASS", "CLI Wrappers")
+        # 7b: Check wrapper files present
+        missing_files = [w for w in wrapper_names if not (bin_dir / w).exists()]
+        if missing_files:
+            print("Status: FAIL")
+            print(f"Wrapper files missing from {bin_dir}: {', '.join(missing_files)}")
+            print("Fix: re-run `npx mindsystem-cc` to regenerate wrappers")
+            record("FAIL", "CLI Wrappers")
+        else:
+            # 7c: Check bin dir in PATH
+            path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+            bin_in_path = str(bin_dir.resolve()) in [os.path.realpath(p) for p in path_dirs]
+
+            # 7d: Check wrappers resolvable
+            missing_wrappers = [w for w in wrapper_names if shutil.which(w) is None]
+
+            if missing_wrappers:
+                print("Status: FAIL")
+                print(f"Not resolvable: {', '.join(missing_wrappers)}")
+                if not bin_in_path:
+                    print(f"Cause: {bin_dir} not in PATH")
+                    print("Fix: restart Claude Code session (PATH hook fires on SessionStart)")
+                else:
+                    print("Fix: re-run `npx mindsystem-cc` to regenerate wrappers and PATH hook")
+                record("FAIL", "CLI Wrappers")
+            else:
+                print(f"All {len(wrapper_names)} CLI wrappers found on PATH")
+
+                # 7e: Check uv available
+                uv_ok = shutil.which("uv") is not None
+                # 7f: Check Python available
+                py_ok = shutil.which("python3") is not None or shutil.which("python") is not None
+
+                issues = []
+                if not uv_ok:
+                    issues.append("uv not found — install: `curl -LsSf https://astral.sh/uv/install.sh | sh`")
+                if not py_ok:
+                    issues.append("Python not found — install Python 3.10+")
+
+                if issues:
+                    print("Status: WARN")
+                    for issue in issues:
+                        print(f"  {issue}")
+                    record("WARN", "CLI Wrappers")
+                else:
+                    print("Status: PASS")
+                    record("PASS", "CLI Wrappers")
     print()
 
     # ---- CHECK 8: Milestone Naming Convention ----