mindsystem-cc 4.0.3 → 4.1.0

package/mindsystem/workflows/complete-milestone.md

@@ -538,7 +538,7 @@ Archived to milestones/{slug}/:
 - phases/ (phase directories moved from .planning/phases/)
 - MILESTONE-AUDIT.md (if audit was run)
 - CONTEXT.md (if milestone context existed)
-- research/ (if research existed)
+- MILESTONE-RESEARCH.md (if existed)
 
 Cleaned:
 - Raw phase artifacts deleted (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
@@ -548,7 +548,7 @@ Cleaned:
 Deleted (fresh for next milestone):
 - ROADMAP.md
 - REQUIREMENTS.md
-- .planning/research/ (archived to milestone)
+- MILESTONE-RESEARCH.md (archived to milestone)
 
 Updated:
 - MILESTONES.md (new entry)
@@ -574,7 +574,7 @@ Shipped:
 Archived to milestones/{slug}/:
 - ROADMAP.md
 - REQUIREMENTS.md
-- research/ (if existed)
+- MILESTONE-RESEARCH.md (if existed)
 
 Summary: .planning/MILESTONES.md
 
@@ -590,7 +590,7 @@ Summary: .planning/MILESTONES.md
 
 **Next milestone flow:**
 1. `/ms:new-milestone` — discover what to build, update PROJECT.md with goals
-2. `/ms:research-project` — (optional) research ecosystem
+2. `/ms:research-milestone` — (optional) research ecosystem
 3. `/ms:create-roadmap` — define requirements and plan how to build it
 
 ---

package/mindsystem/workflows/define-requirements.md

@@ -2,7 +2,7 @@
 Define concrete, checkable requirements for v1.
 
 Two modes:
-1. **With research** — Transform FEATURES.md into scoped requirements
+1. **With research** — Transform MILESTONE-RESEARCH.md Product Landscape into scoped requirements
 2. **Without research** — Gather requirements through questioning
 </purpose>
 
@@ -11,8 +11,7 @@ Two modes:
 
 1. ~/.claude/mindsystem/templates/requirements.md
 2. .planning/PROJECT.md
-3. .planning/research/FEATURES.md (if exists)
-4. .planning/research/SUMMARY.md (if exists)
+3. .planning/MILESTONE-RESEARCH.md (if exists)
 </required_reading>
 
 <process>
@@ -20,7 +19,7 @@ Two modes:
 <step name="detect_mode">
 Check for research:
 ```bash
-[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
+[ -f .planning/MILESTONE-RESEARCH.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
 ```
 
 **If HAS_RESEARCH:** Follow steps load_context → present_features → scope_categories
@@ -33,17 +32,16 @@ Read PROJECT.md and extract:
 - Stated constraints (budget, timeline, tech limitations)
 - Any explicit scope boundaries from project definition
 
-Read research/FEATURES.md and extract:
+Read MILESTONE-RESEARCH.md and extract from Product Landscape:
 - Table stakes (users expect these)
 - Differentiators (competitive advantage)
 - Anti-features (commonly requested, often problematic)
-- Feature dependencies
-- MVP vs full product recommendations
 
-Read research/SUMMARY.md for:
-- Overall confidence level
-- Key architectural constraints
-- Suggested phase structure (informational only)
+Extract from other sections:
+- Technology constraints and decisions
+- Architecture dependencies
+- Feasibility constraints
+- Key risks and pitfalls
 </step>
 
 <step name="load_project" mode="without_research">
@@ -105,7 +103,7 @@ Here are the features for [domain]:
 - OAuth (Google, GitHub)
 - 2FA
 
-**Research notes:** [any relevant notes from FEATURES.md]
+**Research notes:** [any relevant notes from MILESTONE-RESEARCH.md]
 
 ---
 
@@ -114,8 +112,8 @@ Here are the features for [domain]:
 ```
 
 For each category, include:
-- Table stakes from FEATURES.md
-- Differentiators from FEATURES.md
+- Table stakes from MILESTONE-RESEARCH.md
+- Differentiators from MILESTONE-RESEARCH.md
 - Any anti-features flagged (with warnings)
 - Complexity notes where relevant
 </step>

package/mindsystem/workflows/verify-work.md

@@ -200,11 +200,7 @@ Read current batch from UAT.md (test descriptions needed for presenting to user)
 **1. Handle mock generation (if needed):**
 
 If `mock_type` is not null AND different from previous batch:
-- Revert old mocks if any (from `mocked_files` in UAT.md frontmatter):
-  ```bash
-  git checkout -- <mocked_files>
-  ```
-- Clear mocked_files: `ms-tools uat-update $PHASE_NUMBER --session mocked_files=`
+- Revert old mocks: `ms-tools uat-revert-mocks $PHASE_NUMBER`
 - Go to `generate_mocks`
 
 If `mock_type` is null or same as previous:
@@ -382,53 +378,28 @@ Progress auto-recalculates on every `uat-update` call. No manual progress recalc
 **Apply fix inline:**
 
 **1. Stash mocks (if active):**
-```bash
-git stash push -m "mocks-batch-{N}" -- <mocked_files>
-```
-Use `mocked_files` list from UAT.md frontmatter.
+`ms-tools uat-stash-mocks $PHASE_NUMBER`
 
 **2. Make the fix:**
 - Edit the file(s)
 - Test that fix compiles/runs
 
-**3. Commit (amend on retry when safe):**
+**3. Commit and record fix:**
 ```bash
-git add [specific files]
-
-# Check if this is a retry AND HEAD matches the test's previous fix_commit:
-PREV_FIX=$(ms-tools uat-status $PHASE_NUMBER | python3 -c "import sys,json; d=json.load(sys.stdin); t=[x for x in d['fixing_tests'] if x['num']==N]; print(t[0].get('fix_commit','') if t else '')" 2>/dev/null)
-HEAD_SHORT=$(git rev-parse --short HEAD)
-
-if [ "$PREV_FIX" = "$HEAD_SHORT" ] && [ -n "$PREV_FIX" ]; then
-  git commit --amend --no-edit
-else
-  git commit -m "fix({phase}-uat): {description}"
-fi
+ms-tools uat-fix-commit $PHASE_NUMBER --test N --message "fix({phase}-uat): {description}" <files>
 ```
+Handles amend-on-retry automatically (amends if HEAD matches previous fix_commit for this test).
 
-Safety: only amend if HEAD matches recorded fix_commit. If HEAD has moved (other fixes in between), create new commit.
-
-**4. Record in UAT.md via ms-tools:**
+**4. Record fix details in UAT.md:**
+Use the `hash` from fix-commit JSON output:
 ```bash
-FIX_HASH=$(git rev-parse --short HEAD)
-ms-tools uat-update $PHASE_NUMBER --test N fix_status=applied fix_commit=$FIX_HASH
-echo '{"commit":"'$FIX_HASH'","test":N,"description":"what was fixed","files":["changed.ts"]}' | ms-tools uat-update $PHASE_NUMBER --append-fix
+echo '{"commit":"HASH","test":N,"description":"what was fixed","files":["changed.ts"]}' | ms-tools uat-update $PHASE_NUMBER --append-fix
 ```
 
-`append-fix` updates in-place if a fix for the same test already exists (amend support).
-
 **5. Restore mocks:**
-```bash
-git stash pop
-```
+`ms-tools uat-pop-mocks $PHASE_NUMBER`
 
-**Handle stash conflict:**
-```bash
-# Conflict means fix touched a mocked file — take the fix version
-git checkout --theirs <conflicted-file>
-git add <conflicted-file>
-```
-Remove conflicted file from `mocked_files` list in UAT.md (mock no longer needed for that file).
+Conflicts are resolved automatically (fix version wins, conflicted files removed from mocked_files).
 
 **6. Request re-test:**
 ```
@@ -444,9 +415,7 @@ Go to `handle_retest`.
 **Spawn fixer subagent for complex issue:**
 
 **1. Stash mocks (if active):**
-```bash
-git stash push -m "mocks-batch-{N}" -- <mocked_files>
-```
+`ms-tools uat-stash-mocks $PHASE_NUMBER`
 
 **2. Spawn ms-verify-fixer:**
 ```
@@ -489,12 +458,11 @@ Mocks are stashed — working tree is clean.
 
 **If FIX COMPLETE:**
 - Record fix via ms-tools (same as `apply_fix` step 4: `uat-update --test N` + `--append-fix`)
-- Restore mocks: `git stash pop`
-- Handle conflicts as in `apply_fix`
+- Restore mocks: `ms-tools uat-pop-mocks $PHASE_NUMBER`
 - Request re-test
 
 **If INVESTIGATION INCONCLUSIVE:**
-- Restore mocks: `git stash pop`
+- Restore mocks: `ms-tools uat-pop-mocks $PHASE_NUMBER`
 - Present options:
   ```
   Investigation didn't find root cause.
@@ -607,10 +575,7 @@ The `--session current_batch=N` call auto-syncs the Current Batch section with t
 **Complete UAT session:**
 
 **1. Revert mocks:**
-```bash
-git checkout -- <mocked_files>
-```
-Use `mocked_files` list from UAT.md frontmatter. Clear the list after reverting.
+`ms-tools uat-revert-mocks $PHASE_NUMBER`
 
 **2. Generate UAT fixes patch (if fixes were made):**
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "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 ----
@@ -1306,15 +1354,15 @@ def cmd_archive_milestone_files(args: argparse.Namespace) -> None:
         print("Archived: MILESTONE-CONTEXT.md → CONTEXT.md")
         archived += 1
 
-    # Research directory
-    research = planning_dir / "research"
-    if research.is_dir():
-        shutil.move(str(research), str(milestone_dir / "research"))
-        print("Archived: research/ → research/")
+    # MILESTONE-RESEARCH.md
+    research_file = planning_dir / "MILESTONE-RESEARCH.md"
+    if research_file.is_file():
+        shutil.move(str(research_file), str(milestone_dir / "MILESTONE-RESEARCH.md"))
+        print("Archived: MILESTONE-RESEARCH.md")
         archived += 1
 
     if archived == 0:
-        print("No optional files to archive (audit, context, research all absent)")
+        print("No optional files to archive (audit, context, milestone research all absent)")
     else:
         print()
         print(f"Archived {archived} item(s) to milestones/{milestone}/")
@@ -2415,6 +2463,7 @@ class UATFile:
             "current_batch": 1,
             "mocked_files": [],
             "pre_work_stash": None,
+            "stash_ref": None,
         }
 
         # Build tests
@@ -2685,6 +2734,22 @@ class UATFile:
         return "\n".join(lines)
 
 
+def _load_uat(args_phase: str) -> tuple[Path, "UATFile"]:
+    """Load UAT file for a phase. Returns (uat_path, uat). Exits 1 if missing."""
+    phase = normalize_phase(args_phase)
+    planning = find_planning_dir()
+    phase_dir = find_phase_dir(planning, phase)
+    if phase_dir is None:
+        print(f"Error: Phase directory not found for {phase}", file=sys.stderr)
+        sys.exit(1)
+    uat_path = phase_dir / f"{phase_dir.name}-UAT.md"
+    if not uat_path.is_file():
+        print(f"Error: UAT file not found: {uat_path}", file=sys.stderr)
+        sys.exit(1)
+    uat = UATFile.parse(uat_path.read_text(encoding="utf-8"))
+    return uat_path, uat
+
+
 # ===================================================================
 # Subcommand: uat-init
 # ===================================================================
@@ -2857,6 +2922,7 @@ def cmd_uat_status(args: argparse.Namespace) -> None:
         "pending_tests": pending_tests,
         "blocked_tests": blocked_tests,
         "pre_work_stash": uat.frontmatter.get("pre_work_stash"),
+        "stash_ref": uat.frontmatter.get("stash_ref"),
         "path": str(uat_path),
     }
 
@@ -2864,6 +2930,193 @@ def cmd_uat_status(args: argparse.Namespace) -> None:
     sys.stdout.write("\n")
 
 
+# ===================================================================
+# Subcommand: uat-stash-mocks
+# ===================================================================
+
+
+def cmd_uat_stash_mocks(args: argparse.Namespace) -> None:
+    """Stash mocked files before applying a fix.
+
+    Contract:
+        Args: phase (str) — phase number
+        Output: JSON — stash_ref and files list
+        Exit codes: 0 = success (or no-op), 1 = git failure
+        Side effects: git stash push, updates UAT.md stash_ref
+    """
+    uat_path, uat = _load_uat(args.phase)
+
+    mocked_files = uat.frontmatter.get("mocked_files", [])
+    if not mocked_files:
+        print("No mocked files to stash", file=sys.stderr)
+        return
+
+    current_batch = uat.frontmatter.get("current_batch", 1)
+
+    try:
+        run_git("stash", "push", "-m", f"mocks-batch-{current_batch}", "--", *mocked_files)
+    except subprocess.CalledProcessError as e:
+        print(f"Error: git stash push failed: {e.stderr}", file=sys.stderr)
+        sys.exit(1)
+
+    uat.update_session({"stash_ref": "stash@{0}"})
+    uat_path.write_text(uat.serialize(), encoding="utf-8")
+
+    output = {"stash_ref": "stash@{0}", "files": mocked_files}
+    json.dump(output, sys.stdout, cls=_SafeEncoder)
+    sys.stdout.write("\n")
+
+
+# ===================================================================
+# Subcommand: uat-pop-mocks
+# ===================================================================
+
+
+def cmd_uat_pop_mocks(args: argparse.Namespace) -> None:
+    """Restore stashed mocks after fix is committed.
+
+    Contract:
+        Args: phase (str) — phase number
+        Output: JSON — status and conflicts list
+        Exit codes: 0 = success (or no-op), 1 = unexpected failure
+        Side effects: git stash pop, updates UAT.md stash_ref/mocked_files
+    """
+    uat_path, uat = _load_uat(args.phase)
+
+    stash_ref = uat.frontmatter.get("stash_ref")
+    if not stash_ref:
+        print("No stash to pop", file=sys.stderr)
+        return
+
+    try:
+        run_git("stash", "pop", stash_ref)
+        uat.update_session({"stash_ref": ""})
+        uat_path.write_text(uat.serialize(), encoding="utf-8")
+        output = {"status": "restored", "conflicts": []}
+        json.dump(output, sys.stdout, cls=_SafeEncoder)
+        sys.stdout.write("\n")
+    except subprocess.CalledProcessError:
+        # Check for merge conflicts
+        try:
+            conflict_output = run_git("diff", "--name-only", "--diff-filter=U")
+        except subprocess.CalledProcessError:
+            conflict_output = ""
+
+        conflicts = [f.strip() for f in conflict_output.splitlines() if f.strip()]
+        if not conflicts:
+            print("Error: stash pop failed with no merge conflicts — unexpected failure", file=sys.stderr)
+            sys.exit(1)
+
+        # Resolve conflicts by taking the fix version (theirs)
+        for f in conflicts:
+            run_git("checkout", "--theirs", f)
+            run_git("add", f)
+
+        # Drop the stash (failed pop doesn't auto-drop)
+        try:
+            run_git("stash", "drop", stash_ref)
+        except subprocess.CalledProcessError:
+            pass  # Best effort
+
+        # Remove conflicted files from mocked_files
+        mocked = uat.frontmatter.get("mocked_files", [])
+        removed = [f for f in conflicts if f in mocked]
+        uat.frontmatter["mocked_files"] = [f for f in mocked if f not in conflicts]
+        uat.update_session({"stash_ref": ""})
+        uat_path.write_text(uat.serialize(), encoding="utf-8")
+
+        output = {"status": "restored_with_conflicts", "conflicts": conflicts, "removed_from_mocks": removed}
+        json.dump(output, sys.stdout, cls=_SafeEncoder)
+        sys.stdout.write("\n")
+
+
+# ===================================================================
+# Subcommand: uat-fix-commit
+# ===================================================================
+
+
+def cmd_uat_fix_commit(args: argparse.Namespace) -> None:
+    """Stage files, commit (or amend), and record fix in UAT.md.
+
+    Contract:
+        Args: phase (str), --test (int), --message (str), files (list)
+        Output: JSON — hash and amend flag
+        Exit codes: 0 = success, 1 = no files or git failure
+        Side effects: git add/commit, updates UAT.md fix_status/fix_commit
+    """
+    uat_path, uat = _load_uat(args.phase)
+
+    if not args.files:
+        print("Error: No files to commit", file=sys.stderr)
+        sys.exit(1)
+
+    test_num = args.test
+
+    # Find previous fix_commit for this test
+    prev_fix_commit = ""
+    for t in uat.tests:
+        if t["num"] == str(test_num):
+            prev_fix_commit = t.get("fix_commit", "")
+            break
+
+    run_git("add", *args.files)
+
+    amend = False
+    if prev_fix_commit:
+        head_short = run_git("rev-parse", "--short", "HEAD")
+        if head_short == prev_fix_commit:
+            amend = True
+
+    if amend:
+        run_git("commit", "--amend", "--no-edit")
+    else:
+        run_git("commit", "-m", args.message)
+
+    new_hash = run_git("rev-parse", "--short", "HEAD")
+    uat.update_test(test_num, {"fix_status": "applied", "fix_commit": new_hash})
+    uat_path.write_text(uat.serialize(), encoding="utf-8")
+
+    output = {"hash": new_hash, "amend": amend}
+    json.dump(output, sys.stdout, cls=_SafeEncoder)
+    sys.stdout.write("\n")
+
+
+# ===================================================================
+# Subcommand: uat-revert-mocks
+# ===================================================================
+
+
+def cmd_uat_revert_mocks(args: argparse.Namespace) -> None:
+    """Revert mocked files and clear the mocked_files list.
+
+    Contract:
+        Args: phase (str) — phase number
+        Output: JSON — reverted files list
+        Exit codes: 0 = success (or no-op), 1 = git failure
+        Side effects: git checkout, clears mocked_files in UAT.md
+    """
+    uat_path, uat = _load_uat(args.phase)
+
+    mocked_files = uat.frontmatter.get("mocked_files", [])
+    if not mocked_files:
+        print("No mocked files to revert", file=sys.stderr)
+        return
+
+    try:
+        run_git("checkout", "--", *mocked_files)
+    except subprocess.CalledProcessError as e:
+        print(f"Error: git checkout failed: {e.stderr}", file=sys.stderr)
+        sys.exit(1)
+
+    reverted = list(mocked_files)
+    uat.frontmatter["mocked_files"] = []
+    uat_path.write_text(uat.serialize(), encoding="utf-8")
+
+    output = {"reverted": reverted}
+    json.dump(output, sys.stdout, cls=_SafeEncoder)
+    sys.stdout.write("\n")
+
+
 # ===================================================================
 # config-get / config-set / config-delete
 # ===================================================================
@@ -3072,6 +3325,29 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("phase", help="Phase number")
     p.set_defaults(func=cmd_uat_status)
 
+    # --- uat-stash-mocks ---
+    p = subparsers.add_parser("uat-stash-mocks", help="Stash mocked files before fix")
+    p.add_argument("phase", help="Phase number")
+    p.set_defaults(func=cmd_uat_stash_mocks)
+
+    # --- uat-pop-mocks ---
+    p = subparsers.add_parser("uat-pop-mocks", help="Restore stashed mocks after fix")
+    p.add_argument("phase", help="Phase number")
+    p.set_defaults(func=cmd_uat_pop_mocks)
+
+    # --- uat-fix-commit ---
+    p = subparsers.add_parser("uat-fix-commit", help="Commit fix and record in UAT.md")
+    p.add_argument("phase", help="Phase number")
+    p.add_argument("--test", type=int, required=True, help="Test number")
+    p.add_argument("--message", required=True, help="Commit message")
+    p.add_argument("files", nargs="*", help="Files to stage and commit")
+    p.set_defaults(func=cmd_uat_fix_commit)
+
+    # --- uat-revert-mocks ---
+    p = subparsers.add_parser("uat-revert-mocks", help="Revert mocked files to clean state")
+    p.add_argument("phase", help="Phase number")
+    p.set_defaults(func=cmd_uat_revert_mocks)
+
     # --- config-get ---
     p = subparsers.add_parser("config-get", help="Read a value from config.json by dot-path")
     p.add_argument("key", help="Dot-notation key (e.g. subsystems, code_review.phase, subsystems.0)")