Fix 11 automation gaps: dead-end phases, autopilot runtime, guard plugin, status.py bugs, Category 3 audit

- Fix decomposition:approved and human_intervention dead-end phases
- Add scripts/autopilot.py: real drive_all() implementation
- Fix guard plugin: throw Error instead of injecting user messages
- Fix status.py: double continue, _require_state, --list-states
- Add Category 3 (git-based modification) audit
- Add Category 5 (stuck-task detection) audit
- All 206 tests pass

scripts/autopilot.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Autopilot runtime for Automaton framework.
+
+Replaces the pseudocode drive_all() loop in prompt/orchestrate.md
+with a functioning CLI tool that agents can invoke to determine
+the next action in an autopilot workflow.
+
+Usage:
+    python autopilot.py --project /path/to/project       Drive one step forward
+    python autopilot.py --project . --loop               Run continuous loop
+    python autopilot.py --project . --detect-stuck        Detect stuck tasks
+    python autopilot.py --project . --summary              Show autopilot summary
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+AUTOMATON_DIR = Path.home() / ".automaton"
+
+PHASE_PRIORITY = {
+    "referee": 12,
+    "doc_review": 10,
+    "adversarial_bug_find": 8,
+    "bug_find": 6,
+    "implement": 5,
+    "test_design": 4,
+    "design": 3,
+    "decomposition": 2,
+    "research": 1,
+    "new": 0,
+}
+
+
+def _find_project_dir(project_arg: Optional[str]) -> Path:
+    if project_arg:
+        p = Path(project_arg).expanduser().resolve()
+        if p.is_dir():
+            return p
+    cwd = Path.cwd()
+    if (cwd / ".automaton").is_dir():
+        return cwd
+    return AUTOMATON_DIR
+
+
+def _base_phase(phase: str) -> str:
+    return phase.split(":")[0]
+
+
+def _read_state(task_path: Path) -> Optional[str]:
+    state_file = task_path / ".state"
+    if not state_file.exists():
+        return None
+    content = state_file.read_text().strip()
+    return content if content else None
+
+
+def _all_tasks(project_dir: Path) -> list[tuple[str, Path]]:
+    tasks_dir = project_dir / "tasks"
+    if not tasks_dir.is_dir():
+        return []
+    result = []
+    for subdir in sorted(tasks_dir.iterdir()):
+        if subdir.is_dir():
+            result.append((subdir.name, subdir))
+    return result
+
+
+def scan_all_tasks(project_dir: Path) -> list[dict]:
+    """Scan all tasks and return their state info."""
+    tasks = []
+    for name, path in _all_tasks(project_dir):
+        phase = _read_state(path)
+        tasks.append({
+            "name": name,
+            "path": str(path),
+            "phase": phase,
+            "base_phase": _base_phase(phase) if phase else None,
+        })
+    return tasks
+
+
+def is_terminal(task: dict) -> bool:
+    """Check if a task is in a terminal state."""
+    phase = task.get("phase")
+    if phase is None:
+        return False
+    return phase in ("complete", "human_intervention")
+
+
+def needs_user_input(task: dict) -> bool:
+    """Check if a task is blocked waiting for user input."""
+    phase = task.get("phase")
+    if phase is None:
+        return False
+    if phase.endswith(":awaiting_approval"):
+        return True
+    task_path = Path(task["path"])
+    verdict_file = task_path / "VERDICT.md"
+    if verdict_file.exists():
+        content = verdict_file.read_text()
+        first_line = content.split("\n")[0] if content else ""
+        if any(kw in first_line.upper() for kw in ("FAIL", "NEEDS_REVIEW", "TIE-BREAK")):
+            return True
+    return False
+
+
+def sort_by_advancement(tasks: list[dict]) -> list[dict]:
+    """Sort tasks by how close they are to completion (most advanced first)."""
+    return sorted(tasks, key=lambda t: PHASE_PRIORITY.get(t.get("base_phase", ""), 0), reverse=True)
+
+
+def detect_stuck_tasks(project_dir: Path, threshold_minutes: int = 60) -> list[dict]:
+    """Detect tasks that appear stuck (in same non-terminal phase too long)."""
+    stuck = []
+    now = time.time()
+    for name, path in _all_tasks(project_dir):
+        state_file = path / ".state"
+        if not state_file.exists():
+            continue
+        phase = _read_state(path)
+        if phase is None or is_terminal({"phase": phase}):
+            continue
+        mtime = state_file.stat().st_mtime
+        age_minutes = (now - mtime) / 60
+        if age_minutes > threshold_minutes:
+            stuck.append({
+                "name": name,
+                "phase": phase,
+                "age_minutes": round(age_minutes),
+                "path": str(path),
+            })
+    return sorted(stuck, key=lambda t: t["age_minutes"], reverse=True)
+
+
+def cmd_summary(args):
+    """Show autopilot summary of all tasks."""
+    project_dir = _find_project_dir(args.project)
+    all_tasks = scan_all_tasks(project_dir)
+
+    if not all_tasks:
+        print("No tasks found. Create one with:")
+        print("  python ~/.automaton/scripts/status.py --create-task <name> --project", project_dir)
+        return 0
+
+    terminal = [t for t in all_tasks if is_terminal(t)]
+    non_terminal = [t for t in all_tasks if not is_terminal(t)]
+    blocked = [t for t in non_terminal if needs_user_input(t)]
+    unblocked = [t for t in non_terminal if not needs_user_input(t)]
+    stuck = detect_stuck_tasks(project_dir)
+
+    print(f"Project: {project_dir}")
+    print(f"Tasks: {len(all_tasks)} total | {len(terminal)} done | {len(non_terminal)} in progress")
+    print(f"  Blocked (awaiting user): {len(blocked)}")
+    print(f"  Unblocked (ready to drive): {len(unblocked)}")
+    print(f"  Stuck (>60 min): {len(stuck)}")
+    print()
+
+    if stuck:
+        print("=== STUCK TASKS ===")
+        for t in stuck:
+            print(f"  {t['name']}: stuck at '{t['phase']}' for {t['age_minutes']} min")
+        print()
+
+    if unblocked:
+        print("=== READY TO DRIVE ===")
+        for t in sort_by_advancement(unblocked):
+            print(f"  {t['name']}: {t['phase']} (priority: {PHASE_PRIORITY.get(t.get('base_phase', ''), 0)})")
+        print()
+
+    if blocked:
+        print("=== AWAITING USER ===")
+        for t in blocked:
+            approval = t["phase"].endswith(":awaiting_approval")
+            print(f"  {t['name']}: {t['phase']}{' (needs --approve)' if approval else ' (needs VERDICT review)'}")
+        print()
+
+    if not unblocked and not non_terminal:
+        print("ALL TASKS TERMINAL — nothing to drive.")
+        print("Create a new task to continue:")
+        print("  python ~/.automaton/scripts/status.py --create-task <name> --project", project_dir)
+
+    return 0
+
+
+def cmd_drive(args):
+    """Drive one step: find the best task to advance and output instructions."""
+    project_dir = _find_project_dir(args.project)
+    all_tasks = scan_all_tasks(project_dir)
+
+    if not all_tasks:
+        print("NO_TASKS: No tasks found. Create one with:")
+        print("  python ~/.automaton/scripts/status.py --create-task <name> --project", project_dir)
+        return 1
+
+    non_terminal = [t for t in all_tasks if not is_terminal(t)]
+
+    if not non_terminal:
+        print("ORCHESTRATION_COMPLETE: all tasks done.")
+        print("Nothing to drive. Create a new task:")
+        print("  python ~/.automaton/scripts/status.py --create-task <name> --project", project_dir)
+        return 0
+
+    unblocked = [t for t in non_terminal if not needs_user_input(t)]
+
+    if not unblocked:
+        print("ORCHESTRATION_BLOCKED: all non-terminal tasks are awaiting user review.")
+        for t in non_terminal:
+            print(f"  {t['name']}: {t['phase']}")
+        print()
+        print("To proceed:")
+        for t in non_terminal:
+            if t["phase"].endswith(":awaiting_approval"):
+                print(f"  python ~/.automaton/scripts/status.py --approve --task {t['name']} --project {project_dir}")
+            else:
+                print(f"  Review {t['name']}/VERDICT.md and take action")
+        return 0
+
+    sorted_tasks = sort_by_advancement(unblocked)
+    task = sorted_tasks[0]
+
+    print(f"NEXT_TASK: {task['name']}")
+    print(f"PHASE: {task['phase']}")
+    print(f"PRIORITY: {PHASE_PRIORITY.get(task.get('base_phase', ''), 0)}")
+    print()
+
+    phase = task["phase"]
+    base = _base_phase(phase) if phase else "unknown"
+
+    if base == "new":
+        print("→ Transition to research:")
+        print(f"  python ~/.automaton/scripts/status.py --transition research --task {task['name']} --project {project_dir}")
+    elif base == "research":
+        if phase == "research":
+            print("→ Generate SPEC.md, then transition to awaiting_approval:")
+            print(f"  python ~/.automaton/scripts/status.py --transition research:awaiting_approval --task {task['name']} --project {project_dir}")
+        elif phase == "research:approved":
+            print("→ Transition to next phase (decomposition/design/implement):")
+            print(f"  python ~/.automaton/scripts/status.py --transition decomposition --task {task['name']} --project {project_dir}")
+    elif base == "decomposition":
+        if phase == "decomposition":
+            print("→ Generate DECOMPOSITION.md, then transition to awaiting_approval:")
+            print(f"  python ~/.automaton/scripts/status.py --transition decomposition:awaiting_approval --task {task['name']} --project {project_dir}")
+        elif phase == "decomposition:approved":
+            print("→ Create sub-tasks from DECOMPOSITION.md, then complete parent:")
+            print(f"  python ~/.automaton/scripts/status.py --transition complete --task {task['name']} --project {project_dir}")
+    elif base == "design":
+        if phase == "design":
+            print("→ Generate DESIGN.md, then transition to awaiting_approval:")
+            print(f"  python ~/.automaton/scripts/status.py --transition design:awaiting_approval --task {task['name']} --project {project_dir}")
+        elif phase == "design:approved":
+            print("→ Transition to test_design or implement:")
+            print(f"  python ~/.automaton/scripts/status.py --transition test_design --task {task['name']} --project {project_dir}")
+    elif base == "test_design":
+        if phase == "test_design":
+            print("→ Generate TEST_PLAN.md, then transition to awaiting_approval:")
+            print(f"  python ~/.automaton/scripts/status.py --transition test_design:awaiting_approval --task {task['name']} --project {project_dir}")
+        elif phase == "test_design:approved":
+            print("→ Transition to implement:")
+            print(f"  python ~/.automaton/scripts/status.py --transition implement --task {task['name']} --project {project_dir}")
+    elif base == "implement":
+        print("→ Write implementation, generate IMPLEMENTATION.md, then transition:")
+        print(f"  python ~/.automaton/scripts/status.py --transition bug_find --task {task['name']} --project {project_dir}")
+    elif base == "bug_find":
+        print("→ Generate BUG_REPORT.md, then transition:")
+        print(f"  python ~/.automaton/scripts/status.py --transition adversarial_bug_find --task {task['name']} --project {project_dir}")
+    elif base == "adversarial_bug_find":
+        print("→ Generate ADVERSARIAL_BUG_REPORT.md, then transition:")
+        print(f"  python ~/.automaton/scripts/status.py --transition doc_review --task {task['name']} --project {project_dir}")
+    elif base == "doc_review":
+        print("→ Generate DOC_REVIEW.md, then transition:")
+        print(f"  python ~/.automaton/scripts/status.py --transition referee --task {task['name']} --project {project_dir}")
+    elif base == "referee":
+        print("→ Generate VERDICT.md, then transition to complete:")
+        print(f"  python ~/.automaton/scripts/status.py --transition complete --task {task['name']} --project {project_dir}")
+    elif base == "human_intervention":
+        print("→ Task needs human intervention. Review and transition to referee or complete:")
+        print(f"  python ~/.automaton/scripts/status.py --transition referee --task {task['name']} --project {project_dir}")
+
+    return 0
+
+
+def cmd_loop(args):
+    """Run the drive loop continuously until blocked or complete."""
+    max_iterations = args.max_iterations or 100
+    for iteration in range(1, max_iterations + 1):
+        print(f"--- Iteration {iteration}/{max_iterations} ---")
+        result = cmd_drive(args)
+        if result != 0:
+            return result
+        if args.delay:
+            import time as tm
+            tm.sleep(args.delay)
+    print(f"Reached max iterations ({max_iterations}).")
+    return 0
+
+
+def cmd_stuck(args):
+    """Detect and report stuck tasks."""
+    project_dir = _find_project_dir(args.project)
+    threshold = args.threshold or 60
+    stuck = detect_stuck_tasks(project_dir, threshold)
+
+    if not stuck:
+        print(f"No stuck tasks detected (threshold: {threshold} min).")
+        return 0
+
+    print(f"=== STUCK TASKS (>{threshold} min in same phase) ===")
+    for t in stuck:
+        print(f"  {t['name']}: stuck at '{t['phase']}' for {t['age_minutes']} min")
+        print(f"    Path: {t['path']}")
+        print(f"    Action: Review and transition manually or mark complete")
+        print()
+    print(f"Total stuck: {len(stuck)}")
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Automaton autopilot runtime")
+    parser.add_argument("--project", help="Project root directory")
+    parser.add_argument("--drive", action="store_true", help="Drive one step forward (default)")
+    parser.add_argument("--summary", action="store_true", help="Show autopilot summary")
+    parser.add_argument("--stuck", action="store_true", dest="detect_stuck", help="Detect stuck tasks")
+    parser.add_argument("--loop", action="store_true", help="Run continuous drive loop")
+    parser.add_argument("--max-iterations", type=int, help="Max iterations for --loop (default: 100)")
+    parser.add_argument("--delay", type=int, help="Delay seconds between iterations for --loop")
+    parser.add_argument("--threshold", type=int, help="Stuck detection threshold in minutes (default: 60)")
+
+    args = parser.parse_args()
+
+    if args.summary:
+        return cmd_summary(args)
+    if args.detect_stuck:
+        return cmd_stuck(args)
+    if args.loop:
+        return cmd_loop(args)
+    return cmd_drive(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/status.py

@@ -88,7 +88,7 @@ LEGAL_TRANSITIONS = {
     "research:approved": ["decomposition", "design", "implement"],
     "decomposition": ["decomposition:awaiting_approval"],
     "decomposition:awaiting_approval": ["decomposition:approved"],
-    "decomposition:approved": [],
+    "decomposition:approved": ["complete"],
     "design": ["design:awaiting_approval", "test_design", "implement"],
     "design:awaiting_approval": ["design:approved"],
     "design:approved": ["test_design", "implement"],
@@ -100,6 +100,7 @@ LEGAL_TRANSITIONS = {
     "adversarial_bug_find": ["doc_review"],
     "doc_review": ["referee"],
     "referee": ["complete", "human_intervention"],
+    "human_intervention": ["referee", "complete"],
 }
 
 PHASE_REQUIRED_ARTIFACTS = {
@@ -518,10 +519,9 @@ def cmd_approve(args):
     if not task_path.exists():
         print(f"ERROR: Task '{args.task}' not found in {task_path.parent}")
         return 2
-    current = _read_state(task_path)
+    current = _require_state(task_path, args.task)
     if current is None:
-        print(f"ERROR: Cannot determine current phase for task '{args.task}'")
-        return 2
+        return 1
     base = _base_phase(current)
     if base not in APPROVAL_PHASES:
         print(f"This phase ({base}) does not require approval.")
@@ -602,6 +602,73 @@ def _check_forbidden_artifacts(task_path: Path, phase: str) -> list[tuple[str, s
     return found
 
 
+def _audit_category3(project_dir, tasks):
+    """Audit Category 3: Git-based unauthorized modification detection."""
+    import subprocess
+
+    # Collect active edit-allowed tasks
+    active_edit_tasks = set()
+    for name, path in tasks:
+        phase = _read_state(path)
+        if phase and _base_phase(phase) in ("implement", "doc_review"):
+            active_edit_tasks.add(name)
+
+    # Get uncommitted changes (working tree + staged)
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD"],
+            capture_output=True, text=True, cwd=str(project_dir), timeout=10
+        )
+        uncommitted = [f.strip() for f in result.stdout.splitlines() if f.strip()]
+    except Exception as e:
+        print(f"[WARN] Failed to check git diff: {e}")
+        return 0
+
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--name-only", "HEAD"],
+            capture_output=True, text=True, cwd=str(project_dir), timeout=10
+        )
+        staged = [f.strip() for f in result.stdout.splitlines() if f.strip()]
+    except Exception:
+        staged = []
+
+    all_changed = set(uncommitted + staged)
+    violations = 0
+
+    if not all_changed:
+        print("[PASS] No uncommitted modifications detected")
+        return violations
+
+    # Exclude files inside task folders
+    task_names = {name for name, _ in tasks}
+    unauthorized = set()
+
+    for changed_file in all_changed:
+        parts = Path(changed_file).parts
+        is_in_task_folder = len(parts) >= 2 and parts[0] == "tasks" and parts[1] in task_names
+        if not is_in_task_folder:
+            unauthorized.add(changed_file)
+
+    if not unauthorized:
+        print("[PASS] All uncommitted changes are within task folders — no unauthorized modifications")
+        return violations
+
+    if not active_edit_tasks:
+        print("[FAIL] No task in implement or doc_review phase, but uncommitted changes exist outside task folders:")
+        for f in sorted(unauthorized):
+            print(f"  - {f}")
+            violations += 1
+        print(f"  To allow edits: create a task and transition to implement phase")
+    else:
+        print(f"[INFO] Active edit tasks: {', '.join(sorted(active_edit_tasks))}")
+        print("[INFO] Uncommitted changes outside task folders exist (may be authorized if within active task scope):")
+        for f in sorted(unauthorized):
+            print(f"  - {f}")
+
+    return violations
+
+
 def cmd_audit(args):
     project_dir = _find_project_dir(args.project)
     tasks = _all_task_dirs(args.project)
@@ -699,7 +766,27 @@ def cmd_audit(args):
     if not git_dir.exists():
         print("Skipped: not a git repository")
     else:
-        print("Git-based modification checking is available but requires implementation (future work)")
+        violations += _audit_category3(project_dir, tasks)
+
+    print("\n=== Category 5: Stuck Tasks ===")
+    import time as _time
+    stuck_threshold = 60
+    stuck_found = 0
+    for name, path in tasks:
+        state_file = path / ".state"
+        if not state_file.exists():
+            continue
+        phase = _read_state(path)
+        if phase is None or phase in ("complete", "human_intervention"):
+            continue
+        mtime = state_file.stat().st_mtime
+        age_minutes = (_time.time() - mtime) / 60
+        if age_minutes > stuck_threshold:
+            print(f"[WARN] {name}: stuck at '{phase}' for {age_minutes:.0f} minutes (threshold: {stuck_threshold} min)")
+            stuck_found += 1
+            violations += 1
+    if stuck_found == 0:
+        print(f"[PASS] No stuck tasks (threshold: {stuck_threshold} min)")
 
     print(f"\n=== Summary ===")
     total = len(tasks)
@@ -1001,7 +1088,6 @@ def cmd_next_available(args):
         phase = _read_state(path)
         if phase is None:
             continue
-            continue
         base = _base_phase(phase)
         if phase in ("complete", "human_intervention"):
             continue
@@ -1055,7 +1141,6 @@ def cmd_available(args):
         phase = _read_state(path)
         if phase is None:
             continue
-            continue
         base = _base_phase(phase)
         if phase in ("complete", "human_intervention"):
             continue
@@ -1083,6 +1168,16 @@ def cmd_available(args):
     return 0
 
 
+def cmd_list_states(args):
+    """Print all valid phase names."""
+    print("Valid phases:")
+    for phase in VALID_PHASES:
+        base = _base_phase(phase)
+        approvals = " * requires approval" if base in APPROVAL_PHASES and phase == base else ""
+        print(f"  {phase}{approvals}")
+    return 0
+
+
 def main():
     parser = argparse.ArgumentParser(description="Automaton status and enforcement script")
     parser.add_argument("--project", help="Project root directory (defaults to CWD)")
@@ -1103,6 +1198,7 @@ def main():
     parser.add_argument("--scope-check", action="store_true", help="Check if a file is in project scope")
     parser.add_argument("--file", help="File path for scope check or can-edit file scope check")
     parser.add_argument("--same-session", action="store_true", help="Check if task was created in current session")
+    parser.add_argument("--list-states", action="store_true", help="List all valid phase names")
     parser.add_argument("--json", action="store_true", dest="json_output", help="Output machine-readable JSON on last line (for harness integration)")
 
     args = parser.parse_args()
@@ -1156,6 +1252,8 @@ def main():
             print("ERROR: --task is required for --same-session")
             return 2
         return cmd_same_session(args)
+    if args.list_states:
+        return cmd_list_states(args)
     if args.task:
         return cmd_show_task(args)
     print("ERROR: No command specified. Use --help for usage information.")