prizmkit 1.0.144 → 1.0.148

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

@@ -0,0 +1,483 @@
+#!/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.
+
+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)
+
+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
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def run_git(args, cwd=None):
+    """Run a git command and return stdout, or empty string on failure."""
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=10,
+        )
+        return result.stdout.strip()
+    except (subprocess.SubprocessError, FileNotFoundError):
+        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 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
+
+
+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
+
+    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
+
+    return result
+
+
+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": [],
+    }
+
+    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
+
+    return result
+
+
+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": "",
+    }
+
+    # Current branch
+    current = run_git(["branch", "--show-current"], cwd=project_root)
+    result["current_branch"] = current
+
+    # 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
+
+    # 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"]
+
+    # Uncommitted changes (working tree)
+    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
+
+    # Staged changes
+    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)
+
+    # 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
+
+    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 result
+
+
+def detect_code_changes(project_root, main_branch="main"):
+    """Analyze code changes relative to main branch.
+
+    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",
+        "package-lock.json",
+        "yarn.lock",
+        "pnpm-lock.yaml",
+    }
+    IGNORED_PREFIXES = (
+        ".prizmkit/",
+        "dev-pipeline/state/",
+        ".prizm-docs/",
+        ".claude/",
+        ".codebuddy/",
+    )
+
+    def is_source_file(filepath):
+        """Return True if this file represents implementation code."""
+        basename = os.path.basename(filepath)
+        if basename in IGNORED_FILES:
+            return False
+        for prefix in IGNORED_PREFIXES:
+            if filepath.startswith(prefix):
+                return False
+        return True
+
+    result = {
+        "files_modified": 0,
+        "files_added": 0,
+        "files_deleted": 0,
+        "test_files_touched": 0,
+        "directories_touched": [],
+        "has_changes": False,
+    }
+
+    # Get diff stat relative to main
+    diff_output = run_git(
+        ["diff", main_branch, "--name-status"], cwd=project_root
+    )
+
+    # Also include uncommitted changes
+    uncommitted = run_git(["diff", "--name-status"], cwd=project_root)
+    untracked = run_git(
+        ["ls-files", "--others", "--exclude-standard"], cwd=project_root
+    )
+
+    all_files = set()
+    dirs = set()
+
+    if diff_output:
+        for line in diff_output.strip().split("\n"):
+            if not line.strip():
+                continue
+            parts = line.split("\t", 1)
+            if len(parts) < 2:
+                continue
+            status, filepath = parts[0], parts[1]
+            if not is_source_file(filepath):
+                continue
+            all_files.add(filepath)
+            if status.startswith("M"):
+                result["files_modified"] += 1
+            elif status.startswith("A"):
+                result["files_added"] += 1
+            elif status.startswith("D"):
+                result["files_deleted"] += 1
+
+    if uncommitted:
+        for line in uncommitted.strip().split("\n"):
+            if not line.strip():
+                continue
+            parts = line.split("\t", 1)
+            if len(parts) >= 2:
+                filepath = parts[1]
+                if not is_source_file(filepath):
+                    continue
+                all_files.add(filepath)
+                result["files_modified"] += 1
+
+    if untracked:
+        for filepath in untracked.strip().split("\n"):
+            if filepath.strip() and is_source_file(filepath.strip()):
+                all_files.add(filepath.strip())
+                result["files_added"] += 1
+
+    # Analyze file set
+    test_patterns = re.compile(
+        r"(test|spec|__tests__|\.test\.|\.spec\.)", re.IGNORECASE
+    )
+    for filepath in all_files:
+        if test_patterns.search(filepath):
+            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]) + "/")
+
+    result["directories_touched"] = sorted(dirs)
+    result["has_changes"] = len(all_files) > 0
+
+    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",
+    }
+
+
+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)",
+    )
+    parser.add_argument(
+        "--project-root",
+        default=None,
+        help="Project root directory (default: auto-detect from git)",
+    )
+
+    args = parser.parse_args()
+
+    # Resolve project root
+    if args.project_root:
+        project_root = os.path.abspath(args.project_root)
+    else:
+        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")
+
+    # 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)
+
+    # 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}"
+                }
+            ),
+            file=sys.stderr,
+        )
+        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)
+
+    # Build report
+    report = {
+        "feature_id": args.feature_id,
+        "feature_title": title,
+        "feature_slug": slug,
+        "pipeline": pipeline,
+        "artifacts": artifacts,
+        "git": git_state,
+        "code": code_changes,
+        "recovery": recovery,
+    }
+
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.144",
+  "version": "1.0.148",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {