mindsystem-cc 4.4.1 → 4.5.0

package/mindsystem/workflows/verify-work.md

@@ -376,14 +376,13 @@ Format:
 Fix: {what the fix changes, 1-2 sentences}
 ```
 
-**If fix is simple (single file, straightforward change):**
-- Go to `apply_fix` immediately
-
-**If fix is complex (multiple files, architectural):**
-- Spawn ms-verify-fixer subagent (go to `escalate_to_fixer`)
+Go to `apply_fix`.
 
 **If cause NOT found after 2-3 checks:**
-- Escalate to fixer subagent (go to `escalate_to_fixer`)
+- Present options via AskUserQuestion:
+  1. Try different approach — Investigate from another angle
+  2. Skip as assumption — Log and move on
+  3. Manual investigation — You'll look into this yourself
 </step>
 
 <step name="apply_fix">
@@ -423,74 +422,6 @@ Fix applied. Please re-test: {specific instruction}
 Go to `handle_retest`.
 </step>
 
-<step name="escalate_to_fixer">
-**Spawn fixer subagent for complex issue:**
-
-**1. Stash mocks (if active):**
-`ms-tools uat-stash-mocks $PHASE_NUMBER`
-
-**2. Spawn ms-verify-fixer:**
-```
-Task(
-  prompt="""
-You are a Mindsystem verify-fixer. Investigate this issue, find the root cause, implement a fix, and commit it.
-
-## Issue
-
-**Test:** {test_name}
-**Expected:** {expected_behavior}
-**Actual:** {user_reported_behavior}
-**Severity:** {inferred_severity}
-
-## Context
-
-**Phase:** {phase_name}
-**Mock state active:** {mock_type or "none"}
-**Relevant files (suspected):** {file_list}
-
-## What was already checked
-
-{lightweight_investigation_results}
-
-## Knowledge Context
-
-{loaded_knowledge_content or "No knowledge files loaded for this session."}
-
-## Your task
-
-1. Investigate to find root cause
-2. Implement minimal fix
-3. Commit with message: fix({phase}-uat): {description}
-4. Return FIX COMPLETE or INVESTIGATION INCONCLUSIVE
-
-Mocks are stashed — working tree is clean.
-""",
-  subagent_type="ms-verify-fixer",
-  description="Fix: {test_name}"
-)
-```
-
-**3. Handle fixer return:**
-
-**If FIX COMPLETE:**
-- Record fix via ms-tools (same as `apply_fix` step 4: `uat-update --test N` + `--append-fix`)
-- Restore mocks: `ms-tools uat-pop-mocks $PHASE_NUMBER`
-- Request re-test
-
-**If INVESTIGATION INCONCLUSIVE:**
-- Restore mocks: `ms-tools uat-pop-mocks $PHASE_NUMBER`
-- Present options:
-  ```
-  Investigation didn't find root cause.
-
-  Options:
-  1. Try different approach — I'll investigate from another angle
-  2. Skip as assumption — Log and move on
-  3. Manual investigation — You'll look into this yourself
-  ```
-- Handle response accordingly
-</step>
-
 <step name="handle_retest">
 **Handle re-test result:**
 
@@ -515,12 +446,12 @@ ms-tools uat-update $PHASE_NUMBER --test N retry_count=1
 
   Options:
   1. Try different approach — Investigate from scratch
-  2. Escalate to subagent — Fresh context might help
-  3. Skip as assumption — Log and move on
+  2. Skip as assumption — Log and move on
+  3. Manual investigation — You'll look into this yourself
   ```
 - "Try different" → Reset investigation, try again
-- "Escalate" → Go to `escalate_to_fixer`
 - "Skip" → Mark as skipped assumption
+- "Manual" → Mark as skipped, user will investigate
 
 **If New issue:**
 - Mark original as pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "The engineer's meta-prompting system for Claude Code.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/scripts/ms-tools.py

@@ -168,6 +168,14 @@ def parse_roadmap_phases(roadmap_path: Path) -> list[tuple[str, str]]:
     return results
 
 
+def _phase_sort_key(phase_str: str) -> float:
+    """Convert phase string to sortable float: '17' -> 17.0, '17.1' -> 17.1."""
+    try:
+        return float(phase_str)
+    except ValueError:
+        return float("inf")
+
+
 def run_git(*args: str) -> str:
     """Run a git command and return stdout. Raise on failure."""
     result = subprocess.run(
@@ -1413,6 +1421,121 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
             record("WARN", "Screenshot Optimization")
     print()
 
+    # ---- CHECK 13: Roadmap Format ----
+    print("=== Roadmap Format ===")
+    roadmap_path = planning / "ROADMAP.md"
+    if not roadmap_path.is_file():
+        print("Status: SKIP")
+        print("No ROADMAP.md found")
+        record("SKIP", "Roadmap Format")
+    else:
+        roadmap_text = roadmap_path.read_text(encoding="utf-8")
+        all_phases = parse_roadmap_phases(roadmap_path)
+
+        if not all_phases:
+            print("Status: SKIP")
+            print("No phases found in ROADMAP.md")
+            record("SKIP", "Roadmap Format")
+        else:
+            # Find incomplete phases — check overview checklist
+            completed_phases: set[str] = set()
+            for line in roadmap_text.splitlines():
+                done_match = re.match(
+                    r"^-\s*\[x\]\s*\*\*Phase\s+(\d+(?:\.\d+)?)", line
+                )
+                if done_match:
+                    completed_phases.add(done_match.group(1))
+
+            phases_to_check = [
+                (num, name)
+                for num, name in all_phases
+                if num not in completed_phases
+            ]
+
+            if not phases_to_check:
+                print("Status: PASS")
+                print("All phases completed — no pre-work flags to validate")
+                record("PASS", "Roadmap Format")
+            else:
+                issues: list[str] = []
+                for num, name in phases_to_check:
+                    padded = normalize_phase(num)
+                    info = _parse_phase_section(roadmap_text, padded)
+                    if info is None:
+                        issues.append(f"Phase {num}: no detail section found")
+                        continue
+                    for flag in ("discuss", "design", "research"):
+                        pw = info["prework"][flag]
+                        if pw.get("status") == "parse_error":
+                            issues.append(
+                                f"Phase {num} ({name}): {flag.capitalize()} flag missing or malformed"
+                            )
+
+                if issues:
+                    print("Status: FAIL")
+                    print(f"{len(issues)} pre-work flag issue(s):")
+                    for issue in issues:
+                        print(f"  - {issue}")
+                    record("FAIL", "Roadmap Format")
+                else:
+                    print("Status: PASS")
+                    print(
+                        f"All {len(phases_to_check)} incomplete phase(s) have valid pre-work flags"
+                    )
+                    record("PASS", "Roadmap Format")
+    print()
+
+    # ---- CHECK 14: Phase Skills ----
+    print("=== Phase Skills ===")
+    skills_config = config.get("skills", {})
+    plan_skills = skills_config.get("plan", []) if isinstance(skills_config, dict) else []
+    design_skills = skills_config.get("design", []) if isinstance(skills_config, dict) else []
+    skill_warnings: list[str] = []
+
+    if not plan_skills:
+        skill_warnings.append("plan")
+        print("skills.plan: not configured")
+        print("  Impact: Plan-phase code quality — the highest-leverage skill slot")
+        print("  What to add: A code quality skill encoding your project's framework")
+        print("  best practices. Include rules for common pitfalls, idiomatic patterns,")
+        print("  performance gotchas, and structural conventions specific to your stack.")
+        print("  The executor runs a multi-pass review after implementation, catching")
+        print("  framework misuse and structural problems before they reach verification.")
+        print("  Ideal structure: A SKILL.md with categorized rules (reactivity, typing,")
+        print("  performance, composition) plus reference files with bad/good code examples")
+        print("  for each category. The agent selectively reads only rules relevant to the")
+        print("  changed code, keeping context usage efficient.")
+        print("  Set up: Create a skill with framework-specific rules and reference files,")
+        print("  then run /ms:config to add it to skills.plan")
+    else:
+        print(f"skills.plan: {', '.join(plan_skills)}")
+
+    if not design_skills:
+        skill_warnings.append("design")
+        print("skills.design: not configured")
+        print("  Impact: Design-phase quality — ensures generated designs match your")
+        print("  existing design system instead of generic AI output")
+        print("  What to add: A skill describing your project's design system — color")
+        print("  palette, typography, spacing scale, reusable components, and layout")
+        print("  conventions. The designer agent uses this to produce designs that feel")
+        print("  native to your product rather than starting from scratch.")
+        print("  Ideal structure: Document your design tokens (colors, fonts, sizes),")
+        print("  component inventory (buttons, cards, inputs with their variants), and")
+        print("  brand guidelines (visual tone, density preference, platform conventions).")
+        print("  Set up: Create a skill with your design tokens and component inventory,")
+        print("  then run /ms:config to add it to skills.design")
+    else:
+        print(f"skills.design: {', '.join(design_skills)}")
+
+    if skill_warnings:
+        print(f"Status: WARN")
+        record("WARN", "Phase Skills")
+    else:
+        print("Status: PASS")
+        print("Plan and design phase skills configured")
+        record("PASS", "Phase Skills")
+    print()
+
     # ---- SUMMARY ----
     total = pass_count + warn_count + fail_count + skip_count
     print("=== Summary ===")
@@ -1464,6 +1587,140 @@ def cmd_create_phase_dirs(args: argparse.Namespace) -> None:
     print(f"\n{created} created, {skipped} skipped (already exist)")
 
 
+# ===================================================================
+# Subcommand: phase-renumber
+# ===================================================================
+
+
+def cmd_phase_renumber(args: argparse.Namespace) -> None:
+    """Renumber phase directories and files after phase removal.
+
+    Contract:
+        Args: phase (str, the removed phase number), --dry-run (bool)
+        Output: JSON report of all renames
+        Exit codes: 0 = success, 1 = error
+        Side effects: renames directories and files (unless --dry-run)
+    """
+    removed = normalize_phase(args.phase)
+    is_decimal = "." in removed
+    dry_run = args.dry_run
+
+    git_root = find_git_root()
+    planning = git_root / ".planning"
+    phases_dir = planning / "phases"
+
+    if not phases_dir.is_dir():
+        print("Error: .planning/phases/ directory not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Precondition: removed phase dir must not exist
+    if find_phase_dir(planning, removed) is not None:
+        print(
+            f"Error: Directory for phase {removed} still exists. "
+            "Delete it before renumbering.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Parse removed phase components
+    removed_float = _phase_sort_key(removed)
+    if is_decimal:
+        removed_parent = int(removed_float)  # e.g., 17.1 -> 17
+    else:
+        removed_int = int(removed_float)  # e.g., 17
+
+    # Scan all phase dirs and compute renames
+    renames: list[tuple[str, str, Path]] = []  # (old_phase, new_phase, dir_path)
+    for d in sorted(phases_dir.iterdir()):
+        if not d.is_dir():
+            continue
+        parts = d.name.split("-", 1)
+        phase_prefix = parts[0]
+        phase_float = _phase_sort_key(phase_prefix)
+        if phase_float == float("inf"):
+            continue  # not a phase dir
+
+        is_phase_decimal = "." in phase_prefix
+
+        if is_decimal:
+            # Decimal removal: only subsequent decimals in same series
+            if not is_phase_decimal:
+                continue
+            phase_parent = int(phase_float)
+            if phase_parent != removed_parent:
+                continue
+            if phase_float <= removed_float:
+                continue
+            # Decrement decimal: 17.2 -> 17.1, 17.3 -> 17.2
+            old_decimal = int(phase_prefix.split(".")[1])
+            new_decimal = old_decimal - 1
+            new_phase = normalize_phase(f"{phase_parent}.{new_decimal}")
+            renames.append((phase_prefix, new_phase, d))
+        else:
+            # Integer removal: all dirs with phase > removed decrement by 1
+            if phase_float <= removed_float:
+                continue
+            if is_phase_decimal:
+                # Decimal under higher integer: 18.1 -> 17.1
+                parent = int(phase_float)
+                dec = phase_prefix.split(".")[1]
+                new_parent = parent - 1
+                new_phase = normalize_phase(f"{new_parent}.{dec}")
+            else:
+                # Integer: 18 -> 17
+                new_phase = normalize_phase(str(int(phase_float) - 1))
+            renames.append((phase_prefix, new_phase, d))
+
+    # Sort ascending by phase key — ascending is correct because the removed
+    # phase slot is free, so each rename fills the slot vacated by the previous
+    renames.sort(key=lambda r: _phase_sort_key(r[0]))
+
+    # Collision detection: check every target path before renaming
+    source_paths = {r[2] for r in renames}
+    for old_phase, new_phase, dir_path in renames:
+        suffix = dir_path.name.split("-", 1)[1] if "-" in dir_path.name else ""
+        target_name = f"{new_phase}-{suffix}" if suffix else new_phase
+        target_path = phases_dir / target_name
+        if target_path.exists() and target_path not in source_paths:
+            print(
+                f"Error: Collision — renaming {dir_path.name} to {target_name} "
+                f"would overwrite existing directory",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    # Execute renames
+    dir_renames = []
+    file_renames = []
+
+    for old_phase, new_phase, dir_path in renames:
+        suffix = dir_path.name.split("-", 1)[1] if "-" in dir_path.name else ""
+        new_dir_name = f"{new_phase}-{suffix}" if suffix else new_phase
+        new_dir_path = phases_dir / new_dir_name
+
+        dir_renames.append({"old": dir_path.name, "new": new_dir_name})
+
+        if not dry_run:
+            dir_path.rename(new_dir_path)
+
+        # Rename files matching {old_phase}-* inside the directory
+        scan_dir = new_dir_path if not dry_run else dir_path
+        for f in sorted(scan_dir.iterdir()):
+            if f.is_file() and f.name.startswith(f"{old_phase}-"):
+                new_file_name = f"{new_phase}-{f.name[len(old_phase) + 1:]}"
+                file_renames.append({"directory": new_dir_name, "old": f.name, "new": new_file_name})
+                if not dry_run:
+                    f.rename(scan_dir / new_file_name)
+
+    report = {
+        "removed_phase": removed,
+        "dry_run": dry_run,
+        "directory_renames": dir_renames,
+        "file_renames": file_renames,
+    }
+    print(json.dumps(report, indent=2))
+
+
 # ===================================================================
 # Subcommand: gather-milestone-stats
 # ===================================================================
@@ -2217,6 +2474,219 @@ def cmd_list_artifacts(args: argparse.Namespace) -> None:
     sys.stdout.write("\n")
 
 
+# ===================================================================
+# Subcommand: prework-status
+# ===================================================================
+
+
+def _parse_phase_section(roadmap_text: str, phase: str) -> dict[str, Any] | None:
+    """Parse a phase section from ROADMAP.md for pre-work flags.
+
+    Returns dict with name, goal, and prework flags, or None if phase not found.
+    """
+    # Try both padded ("08") and unpadded ("8") forms
+    raw_match = re.match(r"^0*(\d.*)", phase)
+    raw = raw_match.group(1) if raw_match else phase
+    candidates = [phase] if raw == phase else [phase, raw]
+
+    match = None
+    for candidate in candidates:
+        pattern = rf"### Phase\s+{re.escape(candidate)}:\s*(.+)"
+        match = re.search(pattern, roadmap_text)
+        if match:
+            break
+
+    if not match:
+        return None
+
+    phase_name = match.group(1).strip()
+
+    # Extract section text until next "### " or end
+    start = match.start()
+    next_section = re.search(r"\n### ", roadmap_text[start + 1:])
+    if next_section:
+        section = roadmap_text[start : start + 1 + next_section.start()]
+    else:
+        section = roadmap_text[start:]
+
+    # Extract goal
+    goal_match = re.search(r"\*\*Goal\*\*:\s*(.+)", section)
+    goal = goal_match.group(1).strip() if goal_match else ""
+
+    # Extract pre-work flags with two-tier detection:
+    # 1. Keyword check: does **Flag** appear at all?
+    # 2. Full regex: does it match "Likely/Unlikely (reason)"?
+    detail_keys = {"Discuss": "topics", "Design": "focus", "Research": "topics"}
+    prework: dict[str, dict[str, str]] = {}
+
+    for flag_type, detail_key in detail_keys.items():
+        # Tier 1: keyword presence check (case-insensitive)
+        keyword_present = bool(
+            re.search(rf"\*\*{flag_type}\*\*", section, re.IGNORECASE)
+        )
+
+        # Tier 2: full regex match (case-insensitive, greedy reason capture)
+        flag_match = re.search(
+            rf"\*\*{flag_type}\*\*:\s*(Likely|Unlikely)(?:\s*\((.+)\))?",
+            section,
+            re.IGNORECASE,
+        )
+
+        if flag_match:
+            recommended = flag_match.group(1).capitalize()
+            reason = (flag_match.group(2) or "").strip()
+            status = "ok"
+        elif keyword_present:
+            # Keyword found but format doesn't match — non-standard
+            recommended = ""
+            reason = ""
+            status = "parse_error"
+        else:
+            # Keyword absent — older roadmap format
+            recommended = ""
+            reason = ""
+            status = "parse_error"
+
+        # Extract detail line (topics/focus)
+        detail = ""
+        if recommended == "Likely":
+            detail_match = re.search(
+                rf"\*\*{flag_type} {detail_key}\*\*:\s*(.+)", section, re.IGNORECASE
+            )
+            if detail_match:
+                detail = detail_match.group(1).strip()
+
+        prework[flag_type.lower()] = {
+            "recommended": recommended,
+            "reason": reason,
+            "detail": detail,
+            "status": status,
+        }
+
+    return {"name": phase_name, "goal": goal, "prework": prework}
+
+
+def _determine_prework_suggestion(
+    prework: dict[str, dict[str, str]],
+    has_context: bool,
+    has_design: bool,
+    has_research: bool,
+) -> tuple[str, str]:
+    """Apply routing logic to determine next suggested command.
+
+    Returns (command_name, reason) tuple. Flags with parse errors are skipped
+    in the routing waterfall (never treated as Likely or Unlikely).
+    """
+    if prework["discuss"].get("status") != "parse_error":
+        if prework["discuss"]["recommended"] == "Likely" and not has_context:
+            return "discuss-phase", prework["discuss"]["reason"] or "clarify vision"
+    if prework["design"].get("status") != "parse_error":
+        if prework["design"]["recommended"] == "Likely" and not has_design:
+            return "design-phase", prework["design"]["reason"] or "create UI/UX specs"
+    if prework["research"].get("status") != "parse_error":
+        if prework["research"]["recommended"] == "Likely" and not has_research:
+            return "research-phase", prework["research"]["reason"] or "investigate approach"
+
+    # Check if any flags had parse errors with no other Likely flag triggering
+    has_parse_error = any(
+        prework[f].get("status") == "parse_error" for f in ("discuss", "design", "research")
+    )
+    if has_parse_error:
+        return "plan-phase", "ready to plan (some flags unreadable — verify ROADMAP.md)"
+    return "plan-phase", "ready to plan"
+
+
+def cmd_prework_status(args: argparse.Namespace) -> None:
+    """Show pre-work status and routing suggestion for a phase.
+
+    Contract:
+        Args: phase (str) — phase number (e.g., 5, 05, 2.1)
+        Output: human-readable text — phase info, pre-work status, suggestion
+        Exit codes: 0 = success, 1 = ROADMAP.md missing or phase not found
+        Side effects: read-only
+    """
+    phase = normalize_phase(args.phase)
+    planning = find_planning_dir()
+
+    # Parse ROADMAP.md
+    roadmap = planning / "ROADMAP.md"
+    if not roadmap.is_file():
+        print("Error: No ROADMAP.md found", file=sys.stderr)
+        sys.exit(1)
+
+    roadmap_text = roadmap.read_text(encoding="utf-8")
+    phase_info = _parse_phase_section(roadmap_text, phase)
+    if not phase_info:
+        print(f"Error: Phase {phase} not found in ROADMAP.md", file=sys.stderr)
+        sys.exit(1)
+
+    # Check artifacts
+    phase_dir = find_phase_dir(planning, phase)
+    has_context = False
+    has_design = False
+    has_research = False
+    if phase_dir and phase_dir.is_dir():
+        has_context = any(phase_dir.glob("*-CONTEXT.md"))
+        has_design = any(phase_dir.glob("*-DESIGN.md"))
+        has_research = any(phase_dir.glob("*-RESEARCH.md"))
+
+    # Routing
+    suggested_cmd, reason = _determine_prework_suggestion(
+        phase_info["prework"], has_context, has_design, has_research
+    )
+
+    # Format output
+    print(f"Phase {phase}: {phase_info['name']}")
+    print(f"Goal: {phase_info['goal']}")
+    print()
+    print("Pre-work:")
+
+    artifact_done = {
+        "discuss": has_context,
+        "design": has_design,
+        "research": has_research,
+    }
+    detail_labels = {"discuss": "Topics", "design": "Focus", "research": "Topics"}
+
+    has_any_parse_error = False
+    for flag in ("discuss", "design", "research"):
+        pw = phase_info["prework"][flag]
+        if pw.get("status") == "parse_error":
+            has_any_parse_error = True
+            print(f"  {flag.capitalize()}: [parse error] — read ROADMAP.md phase section for this flag")
+        elif pw["recommended"] == "Likely":
+            done = artifact_done[flag]
+            status = "done" if done else "not started"
+            line = f"  {flag.capitalize()}: Likely ({status})"
+            if pw["reason"]:
+                line += f" — {pw['reason']}"
+            print(line)
+            if pw["detail"]:
+                print(f"    {detail_labels[flag]}: {pw['detail']}")
+        else:
+            print(f"  {flag.capitalize()}: Unlikely")
+
+    # Existing artifacts
+    existing = []
+    if has_context:
+        existing.append("CONTEXT.md")
+    if has_design:
+        existing.append("DESIGN.md")
+    if has_research:
+        existing.append("RESEARCH.md")
+
+    print()
+    if existing:
+        print(f"Existing: {', '.join(existing)}")
+    else:
+        print("Existing: (none)")
+
+    print(f"Suggested: /ms:{suggested_cmd} {phase} — {reason}")
+
+    if has_any_parse_error:
+        print(f"\nNote: Some pre-work flags could not be parsed. Read ROADMAP.md phase section for Phase {phase} to determine accurate routing.")
+
+
 # ===================================================================
 # Subcommand: check-artifact
 # ===================================================================
@@ -3812,6 +4282,12 @@ def build_parser() -> argparse.ArgumentParser:
     p = subparsers.add_parser("create-phase-dirs", help="Create phase directories from ROADMAP.md")
     p.set_defaults(func=cmd_create_phase_dirs)
 
+    # --- phase-renumber ---
+    p = subparsers.add_parser("phase-renumber", help="Renumber phase dirs and files after phase removal")
+    p.add_argument("phase", help="The removed phase number (e.g., 17 or 17.1)")
+    p.add_argument("--dry-run", action="store_true", help="Preview renames without executing")
+    p.set_defaults(func=cmd_phase_renumber)
+
     # --- gather-milestone-stats ---
     p = subparsers.add_parser("gather-milestone-stats", help="Gather milestone readiness and git statistics")
     p.add_argument("start_phase", type=int, help="Start phase number")
@@ -3877,6 +4353,11 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("phase", help="Phase number")
     p.set_defaults(func=cmd_list_artifacts)
 
+    # --- prework-status ---
+    p = subparsers.add_parser("prework-status", help="Show pre-work status and routing suggestion")
+    p.add_argument("phase", help="Phase number (e.g., 5, 05, 2.1)")
+    p.set_defaults(func=cmd_prework_status)
+
     # --- check-artifact ---
     p = subparsers.add_parser("check-artifact", help="Check if specific artifact exists")
     p.add_argument("phase", help="Phase number")