mindsystem-cc 4.0.3 → 4.0.4

package/README.md

@@ -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

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.3",
+  "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 ----