prizmkit 1.1.1 → 1.1.3

package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py

@@ -1,18 +1,15 @@
 #!/usr/bin/env python3
 """
-detect-recovery-state.py — Scan filesystem for partial work from an interrupted
-feature pipeline session and output a structured recovery report.
+detect-recovery-state.py — Universal workflow recovery detector.
 
-Checks four state categories:
-  1. Pipeline state (dev-pipeline/state/)
-  2. PrizmKit artifacts (.prizmkit/specs/{slug}/)
-  3. Git state (branches, uncommitted changes, commits ahead)
-  4. Code changes (file counts, directories touched)
+Auto-detects which interactive workflow (feature-workflow, bug-fix-workflow,
+refactor-workflow) was interrupted and what phase it reached, by inspecting
+the workspace: git branch names, characteristic artifacts, and pipeline state.
 
 Does NOT run tests — that's left to the skill so the user sees output in real time.
 
 Usage:
-  python3 detect-recovery-state.py --feature-id F-007 --feature-list feature-list.json
+  python3 detect-recovery-state.py [--project-root .]
 """
 
 import argparse
@@ -23,6 +20,10 @@ import subprocess
 import sys
 
 
+# ---------------------------------------------------------------------------
+# Git helper
+# ---------------------------------------------------------------------------
+
 def run_git(args, cwd=None):
     """Run a git command and return stdout, or empty string on failure."""
     try:
@@ -38,175 +39,215 @@ def run_git(args, cwd=None):
         return ""
 
 
-def compute_slug(feature_id, title):
-    """Compute feature slug using the same algorithm as the pipeline."""
-    numeric = feature_id.replace("F-", "").replace("f-", "").zfill(3)
-    slug = title.lower()
-    slug = re.sub(r"[^a-z0-9\s-]", "", slug)
-    slug = re.sub(r"[\s]+", "-", slug.strip())
-    slug = re.sub(r"-+", "-", slug).strip("-") or "feature"
-    return f"{numeric}-{slug}"
+def detect_main_branch(project_root):
+    """Detect the default branch name (main or master)."""
+    for candidate in ["main", "master"]:
+        check = run_git(["rev-parse", "--verify", candidate], cwd=project_root)
+        if check:
+            return candidate
+    return "main"
 
 
-def find_feature(feature_list_path, feature_id):
-    """Find feature in feature-list.json."""
-    with open(feature_list_path) as f:
-        data = json.load(f)
-    for feat in data.get("features", []):
-        if feat.get("id") == feature_id:
-            return feat
-    return None
+# ---------------------------------------------------------------------------
+# Workflow signature detection (priority-ordered)
+# ---------------------------------------------------------------------------
 
+def extract_bug_id_from_branch(branch):
+    """Extract bug ID from branch name like fix/B-001-login-crash → B-001."""
+    match = re.match(r"fix/(B-\d+)", branch)
+    return match.group(1) if match else None
 
-def detect_pipeline_state(state_dir, feature_id):
-    """Check dev-pipeline/state/ for feature status."""
-    result = {
-        "status": "unknown",
-        "retry_count": 0,
-        "last_session_id": None,
-        "last_session_dir": None,
-        "has_state": False,
-    }
 
-    status_file = os.path.join(state_dir, "features", feature_id, "status.json")
-    if not os.path.isfile(status_file):
-        return result
+def detect_workflow_type(project_root):
+    """Priority-ordered signature matching.
 
-    try:
-        with open(status_file) as f:
-            status_data = json.load(f)
-        result["has_state"] = True
-        result["status"] = status_data.get("status", "unknown")
-        result["retry_count"] = status_data.get("retry_count", 0)
-
-        sessions = status_data.get("sessions", [])
-        if sessions:
-            last = sessions[-1]
-            sid = last.get("session_id", "")
-            result["last_session_id"] = sid
-            result["last_session_dir"] = os.path.join(
-                state_dir, "features", feature_id, "sessions", sid
-            )
-    except (json.JSONDecodeError, IOError):
-        pass
+    Returns (workflow_type, context_dict) or (None, None).
+    """
+    branch = run_git(["branch", "--show-current"], cwd=project_root)
+
+    # Priority 1: fix/* branch → bug-fix-workflow
+    if branch.startswith("fix/"):
+        bug_id = extract_bug_id_from_branch(branch)
+        return ("bug-fix-workflow", {"bug_id": bug_id, "branch": branch})
+
+    # Priority 2: .prizmkit/bugfix/ has content → bug-fix-workflow
+    bugfix_dir = os.path.join(project_root, ".prizmkit", "bugfix")
+    if os.path.isdir(bugfix_dir):
+        bug_ids = sorted(
+            d for d in os.listdir(bugfix_dir)
+            if os.path.isdir(os.path.join(bugfix_dir, d))
+        )
+        if bug_ids:
+            return ("bug-fix-workflow", {"bug_id": bug_ids[-1], "branch": branch})
 
-    return result
+    # Priority 3: refactor/* branch → refactor-workflow
+    if branch.startswith("refactor/"):
+        return ("refactor-workflow", {"branch": branch})
 
+    # Priority 4: refactor-list.json exists → refactor-workflow
+    if os.path.isfile(os.path.join(project_root, "refactor-list.json")):
+        return ("refactor-workflow", {"branch": branch})
 
-def detect_artifacts(project_root, feature_slug):
-    """Check .prizmkit/specs/{slug}/ for planning artifacts."""
-    specs_dir = os.path.join(project_root, ".prizmkit", "specs", feature_slug)
-    result = {
-        "spec_exists": False,
-        "plan_exists": False,
-        "spec_path": None,
-        "plan_path": None,
-        "plan_tasks_total": 0,
-        "plan_tasks_completed": 0,
-        "other_artifacts": [],
+    # Priority 5: feat/* branch → feature-workflow
+    if branch.startswith("feat/"):
+        return ("feature-workflow", {"branch": branch})
+
+    # Priority 6: feature-list.json exists → feature-workflow
+    if os.path.isfile(os.path.join(project_root, "feature-list.json")):
+        return ("feature-workflow", {"branch": branch})
+
+    # No match
+    return (None, None)
+
+
+# ---------------------------------------------------------------------------
+# Phase inference — one function per workflow
+# ---------------------------------------------------------------------------
+
+def infer_bugfix_phase(project_root, bug_id, code_changes, commits_ahead):
+    """Infer bug-fix-workflow phase from artifacts and git state.
+
+    Detection table (from bug-fix-workflow SKILL.md):
+      (nothing)                              → Phase 1: Deep Bug Diagnosis
+      fix-plan.md only                       → Phase 4: Fix
+      fix-plan.md + code changes             → Phase 5: Review
+      all docs + review passed               → Phase 6: User Verification
+      all docs + committed                   → Phase 7: Merge Decision
+    """
+    bugfix_dir = os.path.join(project_root, ".prizmkit", "bugfix", bug_id) if bug_id else ""
+    has_fix_plan = bugfix_dir and os.path.isfile(os.path.join(bugfix_dir, "fix-plan.md"))
+    has_fix_report = bugfix_dir and os.path.isfile(os.path.join(bugfix_dir, "fix-report.md"))
+
+    artifacts = {
+        "fix_plan_exists": has_fix_plan,
+        "fix_report_exists": has_fix_report,
     }
+    if has_fix_plan:
+        artifacts["fix_plan_path"] = os.path.relpath(
+            os.path.join(bugfix_dir, "fix-plan.md"), project_root
+        )
+    if has_fix_report:
+        artifacts["fix_report_path"] = os.path.relpath(
+            os.path.join(bugfix_dir, "fix-report.md"), project_root
+        )
 
-    if not os.path.isdir(specs_dir):
-        return result
-
-    spec_path = os.path.join(specs_dir, "spec.md")
-    plan_path = os.path.join(specs_dir, "plan.md")
-
-    if os.path.isfile(spec_path):
-        result["spec_exists"] = True
-        result["spec_path"] = os.path.relpath(spec_path, project_root)
-
-    if os.path.isfile(plan_path):
-        result["plan_exists"] = True
-        result["plan_path"] = os.path.relpath(plan_path, project_root)
-
-        # Count tasks in plan.md (look for checkbox pattern)
-        try:
-            with open(plan_path) as f:
-                content = f.read()
-            # Match both [x] and [ ] patterns (task checkboxes)
-            completed = len(re.findall(r"^\s*-\s*\[x\]", content, re.MULTILINE | re.IGNORECASE))
-            pending = len(re.findall(r"^\s*-\s*\[ \]", content, re.MULTILINE))
-            result["plan_tasks_total"] = completed + pending
-            result["plan_tasks_completed"] = completed
-        except IOError:
-            pass
-
-    # Check for other artifacts
-    try:
-        for name in os.listdir(specs_dir):
-            if name not in ("spec.md", "plan.md") and os.path.isfile(
-                os.path.join(specs_dir, name)
-            ):
-                result["other_artifacts"].append(name)
-    except IOError:
-        pass
+    if commits_ahead > 0:
+        return 7, "Merge Decision", artifacts, \
+            f"{commits_ahead} commit(s) ahead — fix likely committed", \
+            "merge decision only"
 
-    return result
+    if has_fix_report:
+        return 6, "User Verification", artifacts, \
+            "fix-report.md exists — review completed", \
+            "user verification → commit & merge"
 
+    if has_fix_plan and code_changes["has_changes"]:
+        return 5, "Review", artifacts, \
+            "fix-plan.md exists + code changes present", \
+            "code review → user verification → commit & merge"
 
-def detect_git_state(project_root, feature_slug):
-    """Check git for branch existence, uncommitted changes, commits ahead."""
-    result = {
-        "feature_branch": f"feat/{feature_slug}",
-        "branch_exists": False,
-        "on_feature_branch": False,
-        "uncommitted_files": 0,
-        "staged_files": 0,
-        "commits_ahead_of_main": 0,
-        "current_branch": "",
+    if has_fix_plan:
+        return 4, "Fix", artifacts, \
+            "fix-plan.md exists, no code changes yet", \
+            "implement fix → review → user verification → commit & merge"
+
+    # On fix branch but no artifacts
+    return 1, "Deep Bug Diagnosis", artifacts, \
+        "on fix branch but no artifacts found", \
+        "diagnosis → triage → reproduce → fix → review → commit & merge"
+
+
+def _infer_pipeline_workflow_phase(project_root, list_filename, state_subdir, workflow_label):
+    """Infer phase for pipeline-driven workflows (feature-workflow, refactor-workflow).
+
+    Both follow the same structure:
+      No list file                → Phase 1: Brainstorm
+      List file, no pipeline state → Phase 3: Launch
+      List file + pipeline state   → Phase 4: Monitor
+    """
+    has_list = os.path.isfile(os.path.join(project_root, list_filename))
+    state_dir = os.path.join(project_root, "dev-pipeline", "state", state_subdir)
+    has_pipeline_state = os.path.isdir(state_dir) and bool(os.listdir(state_dir))
+
+    artifacts = {
+        f"{workflow_label}_list_exists": has_list,
+        "pipeline_state_exists": has_pipeline_state,
     }
 
-    # Current branch
-    current = run_git(["branch", "--show-current"], cwd=project_root)
-    result["current_branch"] = current
+    if has_list and has_pipeline_state:
+        return 4, "Monitor", artifacts, \
+            f"{list_filename} + pipeline state exist", \
+            "check pipeline status and report results"
+
+    if has_list:
+        return 3, "Launch", artifacts, \
+            f"{list_filename} exists, no pipeline state", \
+            "launch pipeline → monitor progress"
+
+    return 1, "Brainstorm", artifacts, \
+        f"no {list_filename} found", \
+        f"{workflow_label} goal clarification → plan → launch → monitor"
+
+
+def infer_feature_phase(project_root):
+    """Infer feature-workflow phase from artifacts and pipeline state."""
+    return _infer_pipeline_workflow_phase(
+        project_root, "feature-list.json", "features", "feature"
+    )
+
+
+def infer_refactor_phase(project_root):
+    """Infer refactor-workflow phase from artifacts and pipeline state."""
+    return _infer_pipeline_workflow_phase(
+        project_root, "refactor-list.json", "refactors", "refactor"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Git state helpers
+# ---------------------------------------------------------------------------
 
-    # Check if feature branch exists
-    branch_name = f"feat/{feature_slug}"
-    branches_output = run_git(["branch", "--list", branch_name], cwd=project_root)
-    if branches_output.strip():
-        result["branch_exists"] = True
+def detect_commits_ahead(project_root, main_branch="main"):
+    """Count commits ahead of main branch."""
+    log_output = run_git(
+        ["log", f"{main_branch}..HEAD", "--oneline"], cwd=project_root
+    )
+    if log_output:
+        return len(log_output.strip().split("\n"))
+    return 0
 
-    # Also check without feat/ prefix (some pipelines use different naming)
-    if not result["branch_exists"]:
-        alt_branch = f"feature/{feature_slug}"
-        alt_output = run_git(["branch", "--list", alt_branch], cwd=project_root)
-        if alt_output.strip():
-            result["branch_exists"] = True
-            result["feature_branch"] = alt_branch
 
-    result["on_feature_branch"] = current == result["feature_branch"]
+def detect_git_state(project_root, main_branch="main", cached_branch=None):
+    """Detect git branch and change state."""
+    current = cached_branch or run_git(["branch", "--show-current"], cwd=project_root)
 
     # Uncommitted changes (working tree)
+    uncommitted = 0
     diff_stat = run_git(["diff", "--stat"], cwd=project_root)
     if diff_stat:
-        # Count "N files changed" from the summary line
         lines = diff_stat.strip().split("\n")
-        result["uncommitted_files"] = max(0, len(lines) - 1)  # exclude summary line
+        uncommitted = max(0, len(lines) - 1)
 
     # Staged changes
+    staged = 0
     staged_stat = run_git(["diff", "--cached", "--stat"], cwd=project_root)
     if staged_stat:
         lines = staged_stat.strip().split("\n")
-        result["staged_files"] = max(0, len(lines) - 1)
+        staged = max(0, len(lines) - 1)
 
-    # Commits ahead of main
-    main_branch = "main"
-    # Try to detect default branch
-    for candidate in ["main", "master"]:
-        check = run_git(["rev-parse", "--verify", candidate], cwd=project_root)
-        if check:
-            main_branch = candidate
-            break
+    commits_ahead = detect_commits_ahead(project_root, main_branch)
 
-    log_output = run_git(
-        ["log", f"{main_branch}..HEAD", "--oneline"], cwd=project_root
-    )
-    if log_output:
-        result["commits_ahead_of_main"] = len(log_output.strip().split("\n"))
+    return {
+        "current_branch": current,
+        "uncommitted_files": uncommitted,
+        "staged_files": staged,
+        "commits_ahead_of_main": commits_ahead,
+    }
 
-    return result
 
+# ---------------------------------------------------------------------------
+# Code change detection (reused from original, workflow-agnostic)
+# ---------------------------------------------------------------------------
 
 def detect_code_changes(project_root, main_branch="main"):
     """Analyze code changes relative to main branch.
@@ -214,10 +255,10 @@ def detect_code_changes(project_root, main_branch="main"):
     Filters out pipeline/config files that aren't source code — only counts
     files that represent actual implementation work.
     """
-    # Files/patterns that are pipeline artifacts, not implementation code
     IGNORED_FILES = {
         "feature-list.json",
         "bug-fix-list.json",
+        "refactor-list.json",
         "package-lock.json",
         "yarn.lock",
         "pnpm-lock.yaml",
@@ -249,7 +290,7 @@ def detect_code_changes(project_root, main_branch="main"):
         "has_changes": False,
     }
 
-    # Get diff stat relative to main
+    # Diff relative to main
     diff_output = run_git(
         ["diff", main_branch, "--name-status"], cwd=project_root
     )
@@ -308,7 +349,6 @@ def detect_code_changes(project_root, main_branch="main"):
             result["test_files_touched"] += 1
         parent = os.path.dirname(filepath)
         if parent:
-            # Keep first two levels for readability
             parts = parent.split(os.sep)
             dirs.add(os.sep.join(parts[:2]) + "/")
 
@@ -318,98 +358,13 @@ def detect_code_changes(project_root, main_branch="main"):
     return result
 
 
-def determine_recovery(artifacts, git_state, code_changes, pipeline):
-    """Recommend a recovery action based on detected state."""
-    has_spec = artifacts["spec_exists"]
-    has_plan = artifacts["plan_exists"]
-    has_code = code_changes["has_changes"]
-    has_commits = git_state["commits_ahead_of_main"] > 0
-    tasks_total = artifacts["plan_tasks_total"]
-    tasks_done = artifacts["plan_tasks_completed"]
-
-    # Scenario D: Already committed
-    if has_commits:
-        return {
-            "recommended_action": "complete_post_commit",
-            "recommended_phase": "review",
-            "scenario": "D",
-            "reason": f"{git_state['commits_ahead_of_main']} commit(s) ahead of main — implementation may be complete",
-            "remaining_work": "code review + retrospective + merge",
-        }
-
-    # Scenario A: Implementation in progress
-    if has_plan and has_code:
-        if tasks_total > 0 and tasks_done == tasks_total:
-            return {
-                "recommended_action": "review_and_commit",
-                "recommended_phase": "review",
-                "scenario": "A",
-                "reason": f"all {tasks_total} plan tasks completed, code changes present",
-                "remaining_work": "code review + commit",
-            }
-        else:
-            tasks_remaining = tasks_total - tasks_done if tasks_total > 0 else "unknown"
-            return {
-                "recommended_action": "continue_implementation",
-                "recommended_phase": "implement",
-                "scenario": "A",
-                "reason": f"spec and plan exist, {tasks_done}/{tasks_total} tasks completed, code changes present",
-                "remaining_work": f"{tasks_remaining} tasks + review + commit",
-            }
-
-    # Scenario B: Only planning artifacts
-    if has_spec or has_plan:
-        if has_plan:
-            return {
-                "recommended_action": "start_implementation",
-                "recommended_phase": "implement",
-                "scenario": "B",
-                "reason": "spec and plan exist, no code changes yet",
-                "remaining_work": f"{tasks_total} tasks + review + commit",
-            }
-        else:
-            return {
-                "recommended_action": "generate_plan",
-                "recommended_phase": "plan",
-                "scenario": "B",
-                "reason": "spec exists but no plan — session interrupted during planning",
-                "remaining_work": "plan + implement + review + commit",
-            }
-
-    # Scenario C: Code changes but no artifacts
-    if has_code:
-        return {
-            "recommended_action": "adopt_and_continue",
-            "recommended_phase": "review",
-            "scenario": "C",
-            "reason": "code changes found but no prizmkit artifacts — possible manual work or artifacts cleaned",
-            "remaining_work": "review + commit",
-        }
-
-    # Scenario E: Nothing found
-    return {
-        "recommended_action": "start_fresh",
-        "recommended_phase": "none",
-        "scenario": "E",
-        "reason": "no artifacts, no code changes, no commits — feature was never executed or fully cleaned",
-        "remaining_work": "full pipeline run",
-    }
-
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
 
 def main():
     parser = argparse.ArgumentParser(
-        description="Detect recovery state for an interrupted feature session"
-    )
-    parser.add_argument("--feature-id", required=True, help="Feature ID (e.g., F-007)")
-    parser.add_argument(
-        "--feature-list",
-        default="feature-list.json",
-        help="Path to feature-list.json (default: feature-list.json)",
-    )
-    parser.add_argument(
-        "--state-dir",
-        default=None,
-        help="Pipeline state directory (default: dev-pipeline/state)",
+        description="Auto-detect interrupted workflow state for recovery"
     )
     parser.add_argument(
         "--project-root",
@@ -426,54 +381,57 @@ def main():
         git_root = run_git(["rev-parse", "--show-toplevel"])
         project_root = git_root if git_root else os.getcwd()
 
-    # Resolve state dir
-    state_dir = args.state_dir or os.path.join(project_root, "dev-pipeline", "state")
+    main_branch = detect_main_branch(project_root)
 
-    # Resolve feature list path
-    feature_list_path = args.feature_list
-    if not os.path.isabs(feature_list_path):
-        feature_list_path = os.path.join(project_root, feature_list_path)
+    # Step 1: Detect workflow type (also caches branch name)
+    workflow_type, context = detect_workflow_type(project_root)
 
-    # Find feature
-    if not os.path.isfile(feature_list_path):
-        print(
-            json.dumps({"error": f"Feature list not found: {feature_list_path}"}),
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
-    feature = find_feature(feature_list_path, args.feature_id)
-    if not feature:
-        print(
-            json.dumps(
-                {
-                    "error": f"Feature {args.feature_id} not found in {feature_list_path}"
-                }
+    if workflow_type is None:
+        report = {
+            "detected": False,
+            "message": (
+                "No interrupted workflow detected. "
+                "Use /feature-workflow, /bug-fix-workflow, or /refactor-workflow to start."
             ),
-            file=sys.stderr,
-        )
+        }
+        print(json.dumps(report, indent=2))
         sys.exit(1)
 
-    title = feature.get("title", "untitled")
-    slug = compute_slug(args.feature_id, title)
-
-    # Run all detection phases
-    pipeline = detect_pipeline_state(state_dir, args.feature_id)
-    artifacts = detect_artifacts(project_root, slug)
-    git_state = detect_git_state(project_root, slug)
-    code_changes = detect_code_changes(project_root)
-    recovery = determine_recovery(artifacts, git_state, code_changes, pipeline)
+    # Step 2: Collect git state and code changes once (shared across phase inference + report)
+    cached_branch = context.get("branch")
+    git_state = detect_git_state(project_root, main_branch, cached_branch=cached_branch)
+    code_changes = detect_code_changes(project_root, main_branch)
+
+    # Step 3: Infer phase within the detected workflow
+    if workflow_type == "bug-fix-workflow":
+        phase, phase_name, artifacts, reason, remaining = \
+            infer_bugfix_phase(project_root, context.get("bug_id"),
+                               code_changes, git_state["commits_ahead_of_main"])
+    elif workflow_type == "feature-workflow":
+        phase, phase_name, artifacts, reason, remaining = \
+            infer_feature_phase(project_root)
+    elif workflow_type == "refactor-workflow":
+        phase, phase_name, artifacts, reason, remaining = \
+            infer_refactor_phase(project_root)
+    else:
+        # Should never reach here
+        print(json.dumps({"detected": False, "message": "Unknown workflow type"}), file=sys.stderr)
+        sys.exit(1)
 
-    # Build report
+    # Step 4: Build report
     report = {
-        "feature_id": args.feature_id,
-        "feature_title": title,
-        "feature_slug": slug,
-        "pipeline": pipeline,
+        "detected": True,
+        "workflow_type": workflow_type,
+        "phase": phase,
+        "phase_name": phase_name,
+        "context": context,
         "artifacts": artifacts,
         "git": git_state,
         "code": code_changes,
-        "recovery": recovery,
+        "recovery": {
+            "reason": reason,
+            "remaining_work": remaining,
+        },
     }
 
     print(json.dumps(report, indent=2))