mindsystem-cc 4.1.2 → 4.2.1

package/scripts/ms-tools.py

@@ -109,13 +109,63 @@ def normalize_phase(phase_str: str) -> str:
 
 
 def find_phase_dir(planning: Path, phase: str) -> Path | None:
-    """Find the phase directory matching a normalized phase number."""
+    """Find the phase directory matching a normalized phase number.
+
+    Tries three patterns in priority order:
+    1. Canonical padded: {phase}-* (e.g., 05-*)
+    2. Unpadded variant: {raw}-* (e.g., 5-*) — only when raw != phase
+    3. Bare directory: {phase}/ or {raw}/ — only directories
+    """
     phases_dir = planning / "phases"
     if not phases_dir.is_dir():
         return None
+
+    # Derive raw (unpadded) form: "05" -> "5", "02.1" -> "2.1"
+    raw_match = re.match(r"^0*(\d.*)", phase)
+    raw = raw_match.group(1) if raw_match else phase
+
+    # Tier 1: canonical padded glob
     matches = sorted(phases_dir.glob(f"{phase}-*"))
     dirs = [m for m in matches if m.is_dir()]
-    return dirs[0] if dirs else None
+    if dirs:
+        return dirs[0]
+
+    # Tier 2: unpadded variant glob (skip when raw == phase)
+    if raw != phase:
+        matches = sorted(phases_dir.glob(f"{raw}-*"))
+        dirs = [m for m in matches if m.is_dir()]
+        if dirs:
+            return dirs[0]
+
+    # Tier 3: bare directory
+    bare_padded = phases_dir / phase
+    if bare_padded.is_dir():
+        return bare_padded
+    if raw != phase:
+        bare_raw = phases_dir / raw
+        if bare_raw.is_dir():
+            return bare_raw
+
+    return None
+
+
+def parse_roadmap_phases(roadmap_path: Path) -> list[tuple[str, str]]:
+    """Parse phase headers from ROADMAP.md.
+
+    Returns list of (phase_number, phase_name) tuples.
+    Strips markers like (INSERTED), (Generated) from names.
+    """
+    if not roadmap_path.is_file():
+        return []
+    text = roadmap_path.read_text(encoding="utf-8")
+    results: list[tuple[str, str]] = []
+    for line in text.splitlines():
+        m = re.match(r"^###\s+Phase\s+(\d+(?:\.\d+)?)\s*:\s*(.+)$", line)
+        if m:
+            num = m.group(1)
+            name = re.sub(r"\s*\([A-Z][A-Za-z]*\)\s*$", "", m.group(2)).strip()
+            results.append((num, name))
+    return results
 
 
 def run_git(*args: str) -> str:
@@ -297,6 +347,80 @@ def build_exclude_pathspecs() -> list[str]:
     return [f":!{p}" for p in PATCH_EXCLUSIONS]
 
 
+# -------------------------------------------------------------------
+# Helper: find_phase_commit_hashes
+# -------------------------------------------------------------------
+
+
+def find_phase_commit_hashes(phase_input: str, suffix: str = "") -> list[str]:
+    """Find commit hashes matching a phase's commit convention.
+
+    Contract:
+        Args: phase_input (str), suffix (str, optional)
+        Output: list of commit hash strings (newest first)
+        Side effects: none (reads git log only)
+    """
+    padded_phase = normalize_phase(phase_input)
+    # Strip leading zeros from integer part, preserve decimal: "02.1" -> "2.1"
+    m = re.match(r"^(\d+)(.*)", padded_phase)
+    raw_phase = str(int(m.group(1))) + m.group(2) if m else padded_phase
+
+    # Build alternation pattern matching both padded and raw forms
+    if padded_phase == raw_phase:
+        phase_alt = re.escape(raw_phase)
+    else:
+        phase_alt = f"(?:0*{re.escape(raw_phase)})"
+
+    # Build commit pattern based on suffix
+    if suffix:
+        if suffix == "uat-fixes":
+            commit_pattern = f"\\({phase_alt}-uat\\):"
+        else:
+            commit_pattern = f"\\({phase_alt}-{re.escape(suffix)}\\):"
+    else:
+        commit_pattern = f"\\({phase_alt}-"
+
+    # Find matching commits
+    try:
+        log_output = run_git("log", "--oneline")
+    except subprocess.CalledProcessError:
+        raise
+
+    hashes = []
+    for line in log_output.splitlines():
+        if re.search(commit_pattern, line):
+            hashes.append(line.split()[0])
+    return hashes
+
+
+# -------------------------------------------------------------------
+# Subcommand: find-phase-commits
+# -------------------------------------------------------------------
+
+
+def cmd_find_phase_commits(args: argparse.Namespace) -> None:
+    """Print commit hashes matching a phase's commit convention.
+
+    Contract:
+        Args: phase (str), --suffix (str, optional)
+        Output: text — one commit hash per line (newest first), empty if no matches
+        Exit codes: 0 = success (including zero matches), 1 = git error
+        Side effects: none
+    """
+    git_root = find_git_root()
+    import os
+    os.chdir(git_root)
+
+    try:
+        hashes = find_phase_commit_hashes(args.phase, args.suffix)
+    except subprocess.CalledProcessError:
+        print("Error: Failed to read git log", file=sys.stderr)
+        sys.exit(1)
+
+    for h in hashes:
+        print(h)
+
+
 # ===================================================================
 # Subcommand: update-state
 # ===================================================================
@@ -475,6 +599,166 @@ def cmd_validate_execution_order(args: argparse.Namespace) -> None:
     print(f"PASS: {len(disk_plans)} plans across {wave_count} waves")
 
 
+# ===================================================================
+# Subcommand: browser-check
+# ===================================================================
+
+
+def _get_claude_config_dir() -> Path:
+    """Cross-platform Claude Code config directory."""
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            return Path(appdata) / "Claude"
+        return Path.home() / "AppData" / "Roaming" / "Claude"
+    return Path.home() / ".claude"
+
+
+WEB_FRAMEWORK_DEPS = {
+    "react", "react-dom", "vue", "next", "nuxt", "@angular/core",
+    "svelte", "@sveltejs/kit", "solid-js", "astro", "@remix-run/react",
+    "gatsby", "preact",
+}
+
+WEB_CONFIG_FILES = [
+    "next.config.*", "nuxt.config.*", "vite.config.*", "angular.json",
+    "svelte.config.*", "astro.config.*", "remix.config.*",
+]
+
+
+def _detect_web_project(git_root: Path) -> tuple[bool, str]:
+    """Detect if project is a web project. Returns (is_web, signal_description)."""
+    # Signal 1: package.json deps
+    pkg = git_root / "package.json"
+    if pkg.is_file():
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+            all_deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+            found = WEB_FRAMEWORK_DEPS & set(all_deps.keys())
+            if found:
+                return True, f"{', '.join(sorted(found))} in package.json"
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Signal 2: Framework config files (glob at root)
+    for pattern in WEB_CONFIG_FILES:
+        if list(git_root.glob(pattern)):
+            return True, f"{pattern} found"
+
+    # Signal 3: One level deep package.json (monorepo)
+    for child_pkg in git_root.glob("*/package.json"):
+        if "node_modules" in str(child_pkg):
+            continue
+        try:
+            data = json.loads(child_pkg.read_text(encoding="utf-8"))
+            all_deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+            found = WEB_FRAMEWORK_DEPS & set(all_deps.keys())
+            if found:
+                return True, f"{', '.join(sorted(found))} in {child_pkg.relative_to(git_root)}"
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Signal 4: PROJECT.md tech stack mentions
+    project_md = git_root / ".planning" / "PROJECT.md"
+    if project_md.is_file():
+        try:
+            content = project_md.read_text(encoding="utf-8").lower()
+            web_keywords = ["react", "vue", "next.js", "nextjs", "nuxt", "angular", "svelte", "sveltekit", "astro", "remix"]
+            for kw in web_keywords:
+                if kw in content:
+                    return True, f"'{kw}' mentioned in PROJECT.md"
+        except OSError:
+            pass
+
+    return False, "no web framework in package.json, no framework config files, no web stack in PROJECT.md"
+
+
+def _check_skill_installed(skill_name: str) -> tuple[bool, str]:
+    """Check if a Claude Code skill is installed. Cross-platform."""
+    config_dir = _get_claude_config_dir()
+    locations = [
+        ("user", config_dir / "skills" / skill_name / "SKILL.md"),
+        ("project", Path.cwd() / ".claude" / "skills" / skill_name / "SKILL.md"),
+    ]
+    for label, path in locations:
+        if path.is_file():
+            return True, f"{label}: {path}"
+    return False, "not found in ~/.claude/skills/ or .claude/skills/"
+
+
+def cmd_browser_check(args: argparse.Namespace) -> None:
+    """Check browser verification prerequisites.
+
+    Contract:
+        Output: text — section-based status report
+        Exit codes: 0 = READY, 1 = MISSING_DEPS, 2 = SKIP
+        Side effects: read-only
+    """
+    git_root = find_git_root()
+    planning = git_root / ".planning"
+
+    # 1. Config check
+    print("=== Browser Verification Config ===")
+    enabled = True  # default
+    config_path = planning / "config.json" if planning.is_dir() else None
+    if config_path and config_path.is_file():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+            bv = config.get("browser_verification", {})
+            if isinstance(bv, dict):
+                enabled = bv.get("enabled", True)
+            # else: malformed, default to enabled
+        except (json.JSONDecodeError, OSError):
+            pass  # malformed config, default to enabled
+    print(f"Status: {'enabled' if enabled else 'disabled'}")
+
+    if not enabled:
+        print("\nResult: SKIP (disabled in config)")
+        sys.exit(2)
+
+    # 2. Web project check
+    print("\n=== Web Project Detection ===")
+    is_web, signal = _detect_web_project(git_root)
+    print(f"Web project: {is_web}")
+    print(f"Signal: {signal}")
+
+    if not is_web:
+        print("\nResult: SKIP (not a web project)")
+        sys.exit(2)
+
+    # 3. CLI check
+    print("\n=== Browser CLI ===")
+    cli_path = shutil.which("agent-browser")
+    if cli_path:
+        print(f"agent-browser: {cli_path}")
+    else:
+        print("agent-browser: not found")
+        print("Install: npm install -g agent-browser")
+
+    # 4. Skill check
+    print("\n=== Browser Skill ===")
+    skill_ok, skill_detail = _check_skill_installed("agent-browser")
+    if skill_ok:
+        print(f"agent-browser skill: {skill_detail}")
+    else:
+        print(f"agent-browser skill: {skill_detail}")
+        print("Install: add agent-browser skill to ~/.claude/skills/")
+
+    # Result
+    missing: list[str] = []
+    if not cli_path:
+        missing.append("agent-browser CLI")
+    if not skill_ok:
+        missing.append("agent-browser skill")
+
+    if missing:
+        print(f"\nResult: MISSING_DEPS ({', '.join(missing)})")
+        sys.exit(1)
+
+    print("\nResult: READY")
+    sys.exit(0)
+
+
 # ===================================================================
 # Subcommand: doctor-scan
 # ===================================================================
@@ -530,12 +814,6 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
         else:
             skip_count += 1
 
-    def format_phase_prefix(phase: str) -> str:
-        if "." in phase:
-            int_part, dec_part = phase.split(".", 1)
-            return f"{int(int_part):02d}.{dec_part}"
-        return f"{int(phase):02d}"
-
     def parse_phase_numbers(line: str) -> list[str]:
         """Parse phase numbers from a 'Phases completed' line."""
         range_match = re.search(r"(\d+)-(\d+)", line)
@@ -629,7 +907,7 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
             orphans: list[str] = []
             for line in phase_lines:
                 for phase_num in parse_phase_numbers(line):
-                    prefix = format_phase_prefix(phase_num)
+                    prefix = normalize_phase(phase_num)
                     if phases_dir.is_dir():
                         for d in phases_dir.glob(f"{prefix}-*/"):
                             if d.is_dir():
@@ -728,7 +1006,7 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
             leftovers: list[str] = []
             for line in phase_lines:
                 for phase_num in parse_phase_numbers(line):
-                    prefix = format_phase_prefix(phase_num)
+                    prefix = normalize_phase(phase_num)
                     if phases_dir.is_dir():
                         for d in phases_dir.glob(f"{prefix}-*/"):
                             if d.is_dir():
@@ -877,6 +1155,84 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
         record("WARN", "Research API Keys")
     print()
 
+    # ---- CHECK 10: Phase Directory Naming ----
+    print("=== Phase Directory Naming ===")
+    roadmap_path = planning / "ROADMAP.md"
+    roadmap_phases = parse_roadmap_phases(roadmap_path)
+    if not roadmap_phases:
+        print("Status: SKIP")
+        print("No ROADMAP.md or no phases found")
+        record("SKIP", "Phase Directory Naming")
+    else:
+        non_canonical: list[str] = []
+        missing_dirs: list[str] = []
+        for num, name in roadmap_phases:
+            padded = normalize_phase(num)
+            slug = slugify(name)
+            canonical = f"{padded}-{slug}"
+            canonical_path = phases_dir / canonical if phases_dir.is_dir() else None
+            if canonical_path and canonical_path.is_dir():
+                continue
+            found = find_phase_dir(planning, padded)
+            if found is not None:
+                non_canonical.append(f"  {found.name} → git mv .planning/phases/{found.name} .planning/phases/{canonical}")
+            else:
+                missing_dirs.append(f"  {canonical} (missing, run: ms-tools create-phase-dirs)")
+        if non_canonical:
+            print("Status: FAIL")
+            print(f"Found {len(non_canonical)} non-canonical phase directory name(s):")
+            for line in non_canonical:
+                print(line)
+            record("FAIL", "Phase Directory Naming")
+        elif missing_dirs:
+            print("Status: WARN")
+            print(f"Found {len(missing_dirs)} missing phase directory(ies):")
+            for line in missing_dirs:
+                print(line)
+            record("WARN", "Phase Directory Naming")
+        else:
+            print("Status: PASS")
+            print("All phase directories use canonical naming")
+            record("PASS", "Phase Directory Naming")
+    print()
+
+    # ---- CHECK 11: Browser Verification ----
+    print("=== Browser Verification ===")
+    bv_enabled = True
+    bv_config = config.get("browser_verification", {})
+    if isinstance(bv_config, dict):
+        bv_enabled = bv_config.get("enabled", True)
+
+    if not bv_enabled:
+        print("Status: SKIP")
+        print("Disabled in config.json")
+        record("SKIP", "Browser Verification")
+    else:
+        is_web, web_signal = _detect_web_project(git_root)
+        if not is_web:
+            print("Status: SKIP")
+            print(f"Not a web project ({web_signal})")
+            record("SKIP", "Browser Verification")
+        else:
+            bv_missing: list[str] = []
+            cli_path = shutil.which("agent-browser")
+            if not cli_path:
+                bv_missing.append("agent-browser CLI (npm install -g agent-browser)")
+            skill_ok, _ = _check_skill_installed("agent-browser")
+            if not skill_ok:
+                bv_missing.append("agent-browser skill")
+            if bv_missing:
+                print("Status: WARN")
+                print(f"Web project detected ({web_signal}) but missing:")
+                for m in bv_missing:
+                    print(f"  {m}")
+                record("WARN", "Browser Verification")
+            else:
+                print("Status: PASS")
+                print(f"Web project ({web_signal}), CLI and skill installed")
+                record("PASS", "Browser Verification")
+    print()
+
     # ---- SUMMARY ----
     total = pass_count + warn_count + fail_count + skip_count
     print("=== Summary ===")
@@ -890,6 +1246,44 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
         print("All checks passed")
 
 
+# ===================================================================
+# Subcommand: create-phase-dirs
+# ===================================================================
+
+
+def cmd_create_phase_dirs(args: argparse.Namespace) -> None:
+    """Create phase directories from ROADMAP.md headers.
+
+    Reads ### Phase N: Name headers, creates .planning/phases/{padded}-{slug}/
+    for each. Skips phases that already have a directory (found via resilient
+    find_phase_dir).
+    """
+    planning = find_planning_dir()
+    roadmap_path = planning / "ROADMAP.md"
+    phases = parse_roadmap_phases(roadmap_path)
+    if not phases:
+        print("Error: No phases found in ROADMAP.md (or file missing)", file=sys.stderr)
+        sys.exit(1)
+
+    phases_dir = planning / "phases"
+    phases_dir.mkdir(parents=True, exist_ok=True)
+
+    created = 0
+    skipped = 0
+    for num, name in phases:
+        padded = normalize_phase(num)
+        if find_phase_dir(planning, padded) is not None:
+            skipped += 1
+            continue
+        slug = slugify(name)
+        dir_name = f"{padded}-{slug}"
+        (phases_dir / dir_name).mkdir(parents=True, exist_ok=True)
+        print(f"Created: {dir_name}")
+        created += 1
+
+    print(f"\n{created} created, {skipped} skipped (already exist)")
+
+
 # ===================================================================
 # Subcommand: gather-milestone-stats
 # ===================================================================
@@ -982,28 +1376,32 @@ def cmd_gather_milestone_stats(args: argparse.Namespace) -> None:
 
     all_commits: list[str] = []
 
-    # Integer phases
+    # Integer phases — try both padded and raw formats
     for i in range(start, end + 1):
-        phase = f"{i:02d}"
-        try:
-            out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({phase}-")
-            if out:
-                all_commits.extend(out.splitlines())
-        except subprocess.CalledProcessError:
-            pass
+        padded = normalize_phase(str(i))
+        raw = str(i)
+        for p in ([padded, raw] if padded != raw else [padded]):
+            try:
+                out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({p}-")
+                if out:
+                    all_commits.extend(out.splitlines())
+            except subprocess.CalledProcessError:
+                pass
 
-    # Decimal phases
+    # Decimal phases — try both directory-derived and padded forms
     for d in sorted(phases_dir.iterdir()):
         if not d.is_dir():
             continue
         phase_num = d.name.split("-", 1)[0]
         if "." in phase_num and in_range(phase_num, start, end):
-            try:
-                out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({phase_num}-")
-                if out:
-                    all_commits.extend(out.splitlines())
-            except subprocess.CalledProcessError:
-                pass
+            padded = normalize_phase(phase_num)
+            for p in ([padded, phase_num] if padded != phase_num else [padded]):
+                try:
+                    out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({p}-")
+                    if out:
+                        all_commits.extend(out.splitlines())
+                except subprocess.CalledProcessError:
+                    pass
 
     # Deduplicate and sort by date
     seen: set[str] = set()
@@ -1071,38 +1469,24 @@ def cmd_generate_phase_patch(args: argparse.Namespace) -> None:
     import os
     os.chdir(git_root)
 
-    # Normalize phase number
-    if re.match(r"^\d$", phase_input):
-        phase_number = f"{int(phase_input):02d}"
-    else:
-        phase_number = phase_input
+    padded_phase = normalize_phase(phase_input)
 
-    # Determine commit pattern
     if suffix:
         if suffix == "uat-fixes":
-            commit_pattern = f"\\({phase_number}-uat\\):"
-            print(f"Generating UAT fixes patch for phase {phase_number}...")
+            print(f"Generating UAT fixes patch for phase {padded_phase}...")
         else:
-            commit_pattern = f"\\({phase_number}-{suffix}\\):"
-            print(f"Generating {suffix} patch for phase {phase_number}...")
+            print(f"Generating {suffix} patch for phase {padded_phase}...")
     else:
-        commit_pattern = f"\\({phase_number}-"
-        print(f"Generating patch for phase {phase_number}...")
+        print(f"Generating patch for phase {padded_phase}...")
 
-    # Find matching commits
     try:
-        log_output = run_git("log", "--oneline")
+        phase_commits = find_phase_commit_hashes(phase_input, suffix)
     except subprocess.CalledProcessError:
         print("Error: Failed to read git log", file=sys.stderr)
         sys.exit(1)
 
-    phase_commits = []
-    for line in log_output.splitlines():
-        if re.search(commit_pattern, line):
-            phase_commits.append(line.split()[0])
-
     if not phase_commits:
-        print(f"No commits found matching pattern: {commit_pattern}")
+        print("No commits found matching phase convention")
         print("Patch skipped")
         return
 
@@ -1120,7 +1504,7 @@ def cmd_generate_phase_patch(args: argparse.Namespace) -> None:
 
     # Find output directory
     phases_dir = Path(".planning/phases")
-    phase_dir_matches = sorted(phases_dir.glob(f"{phase_number}-*")) if phases_dir.is_dir() else []
+    phase_dir_matches = sorted(phases_dir.glob(f"{padded_phase}-*")) if phases_dir.is_dir() else []
     phase_dir = str(phase_dir_matches[0]) if phase_dir_matches else str(phases_dir)
 
     Path(phase_dir).mkdir(parents=True, exist_ok=True)
@@ -1128,9 +1512,9 @@ def cmd_generate_phase_patch(args: argparse.Namespace) -> None:
 
     # Determine output filename
     if suffix:
-        patch_file = f"{phase_dir}/{phase_number}-{suffix}.patch"
+        patch_file = f"{phase_dir}/{padded_phase}-{suffix}.patch"
     else:
-        patch_file = f"{phase_dir}/{phase_number}-changes.patch"
+        patch_file = f"{phase_dir}/{padded_phase}-changes.patch"
 
     # Generate diff
     exclude_args = build_exclude_pathspecs()
@@ -2776,10 +3160,8 @@ def cmd_uat_init(args: argparse.Namespace) -> None:
 
     phase_dir = find_phase_dir(planning, phase)
     if phase_dir is None:
-        phases_dir = planning / "phases"
-        phases_dir.mkdir(parents=True, exist_ok=True)
-        phase_dir = phases_dir / phase
-        phase_dir.mkdir(parents=True, exist_ok=True)
+        print(f"Error: Phase directory not found for {phase}. Run: ms-tools create-phase-dirs", file=sys.stderr)
+        sys.exit(1)
 
     phase_name = phase_dir.name
     uat = UATFile.from_init_json(data, phase_name)
@@ -3234,10 +3616,18 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("phase_dir", help="Phase directory path")
     p.set_defaults(func=cmd_validate_execution_order)
 
+    # --- browser-check ---
+    p = subparsers.add_parser("browser-check", help="Check browser verification prerequisites")
+    p.set_defaults(func=cmd_browser_check)
+
     # --- doctor-scan ---
     p = subparsers.add_parser("doctor-scan", help="Diagnostic scan of .planning/ tree")
     p.set_defaults(func=cmd_doctor_scan)
 
+    # --- create-phase-dirs ---
+    p = subparsers.add_parser("create-phase-dirs", help="Create phase directories from ROADMAP.md")
+    p.set_defaults(func=cmd_create_phase_dirs)
+
     # --- 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")
@@ -3250,6 +3640,12 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--suffix", default="", help="Filter commits and customize output filename")
     p.set_defaults(func=cmd_generate_phase_patch)
 
+    # --- find-phase-commits ---
+    p = subparsers.add_parser("find-phase-commits", help="Find commit hashes matching phase convention")
+    p.add_argument("phase", help="Phase number (e.g., 04 or 4)")
+    p.add_argument("--suffix", default="", help="Filter by suffix (e.g., uat)")
+    p.set_defaults(func=cmd_find_phase_commits)
+
     # --- generate-adhoc-patch ---
     p = subparsers.add_parser("generate-adhoc-patch", help="Generate patch from an adhoc commit or range")
     p.add_argument("commit", help="Start commit hash")