anvil-dev-framework 0.1.6

package/global/lib/ralph_state.py

@@ -0,0 +1,1202 @@
+#!/usr/bin/env python3
+"""
+ralph_state.py - Ralph Wiggum State Management (ANV-164)
+
+Python module for managing Ralph Wiggum autonomous execution state.
+Provides a clean API for the /ralph skill to interact with state files.
+
+Usage:
+    from global.lib.ralph_state import RalphState, ContextCheckpoint
+
+    # Initialize a new Ralph session
+    state = RalphState.initialize(
+        task_name="Migrate Jest to Vitest",
+        objective="Convert all test files from Jest to Vitest",
+        todo_items=["Update config", "Migrate tests", "Run tests"]
+    )
+
+    # Load existing state
+    state = RalphState.load()
+
+    # Update state
+    state.increment_iteration()
+    state.update_status("completed")
+    state.save()
+
+    # Get status report
+    print(state.status_report())
+"""
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+import importlib.util
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+DEFAULT_STATE_FILE = ".claude/ralph-state.json"
+DEFAULT_MAX_ITERATIONS = 50
+DEFAULT_COMPLETION_PROMISE = "COMPLETE"
+DEFAULT_PROGRESS_FILE = "progress.txt"
+DEFAULT_FIX_PLAN_FILE = "fix_plan.md"
+DEFAULT_PROMPT_FILE = "PROMPT.md"
+
+
+
+
+# =============================================================================
+# Linear Provider Dynamic Import
+# =============================================================================
+
+
+def _get_linear_provider():
+    """Dynamically import LinearProvider to avoid 'global' keyword issues."""
+    lib_dir = Path(__file__).parent
+    spec = importlib.util.spec_from_file_location("linear_provider", lib_dir / "linear_provider.py")
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not find linear_provider.py in {lib_dir}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.LinearProvider
+
+
+def _get_linear_config() -> Dict[str, str]:
+    """Load Linear team configuration from .claude/linear.yaml.
+
+    Returns:
+        Dict with team_key and team_id, or empty dict if not configured.
+
+    Fixes ANV-120: Ensures LinearProvider always gets proper team context
+    to prevent state UUID cache discrepancies between teams.
+    """
+    try:
+        import yaml
+    except ImportError:
+        return {}
+
+    config_path = Path(".claude/linear.yaml")
+    if not config_path.exists():
+        return {}
+
+    try:
+        config = yaml.safe_load(config_path.read_text())
+        return {
+            "team_key": config.get("team_key", ""),
+            "team_id": config.get("team_id", ""),
+        }
+    except Exception:
+        return {}
+
+
+def _create_linear_provider():
+    """Create a LinearProvider instance with proper team configuration.
+
+    This is the preferred way to instantiate LinearProvider in ralph_state.py.
+    It loads team config from .claude/linear.yaml to ensure the state cache
+    is populated with the correct team's workflow state UUIDs.
+
+    Fixes ANV-120: Linear state UUID caching causes team/state discrepancy errors.
+    """
+    LinearProvider = _get_linear_provider()
+    config = _get_linear_config()
+    return LinearProvider(
+        team_key=config.get("team_key", ""),
+        team_id=config.get("team_id", ""),
+    )
+
+
+# =============================================================================
+# Linear Integration Data Classes
+# =============================================================================
+
+
+@dataclass
+class LinearSubtask:
+    """A Linear subtask tracked by Ralph."""
+    id: str
+    identifier: str
+    title: str
+    status: str = "todo"
+    completed_at: Optional[str] = None
+    skip_reason: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary."""
+        return {"id": self.id, "identifier": self.identifier, "title": self.title,
+                "status": self.status, "completed_at": self.completed_at, "skip_reason": self.skip_reason}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LinearSubtask":
+        """Deserialize from dictionary."""
+        return cls(id=data["id"], identifier=data["identifier"], title=data["title"],
+                   status=data.get("status", "todo"), completed_at=data.get("completed_at"),
+                   skip_reason=data.get("skip_reason"))
+
+
+@dataclass
+class LinearIntegration:
+    """Linear integration state for Ralph."""
+    enabled: bool = False
+    mode: str = "issue"
+    parent_issue: Optional[str] = None
+    parent_id: Optional[str] = None
+    project_name: Optional[str] = None
+    subtasks: List[LinearSubtask] = None
+    last_sync: str = ""
+    no_sync: bool = False
+
+    def __post_init__(self):
+        if self.subtasks is None:
+            self.subtasks = []
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary."""
+        return {"enabled": self.enabled, "mode": self.mode, "parent_issue": self.parent_issue,
+                "parent_id": self.parent_id, "project_name": self.project_name,
+                "subtasks": [s.to_dict() for s in self.subtasks], "last_sync": self.last_sync,
+                "no_sync": self.no_sync}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LinearIntegration":
+        """Deserialize from dictionary."""
+        subtasks = [LinearSubtask.from_dict(s) for s in data.get("subtasks", [])]
+        return cls(enabled=data.get("enabled", False), mode=data.get("mode", "issue"),
+                   parent_issue=data.get("parent_issue"), parent_id=data.get("parent_id"),
+                   project_name=data.get("project_name"), subtasks=subtasks,
+                   last_sync=data.get("last_sync", ""), no_sync=data.get("no_sync", False))
+
+
+# =============================================================================
+# Data Classes
+# =============================================================================
+
+
+@dataclass
+class ContextCheckpoint:
+    """Context checkpoint state for CCS integration (ANV-198).
+
+    Tracks checkpoint information when context limits are approached,
+    enabling seamless session handoffs during Ralph autonomous execution.
+    """
+
+    active: bool = False
+    level: str = ""  # L1, L2, L3
+    percent_at_checkpoint: int = 0
+    timestamp: str = ""
+    handoff_file: str = ""
+    resume_summary: str = ""
+    files_in_progress: List[Dict[str, Any]] = field(default_factory=list)
+    current_todo_item: str = ""
+    progress_on_item: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "active": self.active,
+            "level": self.level,
+            "percent_at_checkpoint": self.percent_at_checkpoint,
+            "timestamp": self.timestamp,
+            "handoff_file": self.handoff_file,
+            "resume_summary": self.resume_summary,
+            "files_in_progress": self.files_in_progress,
+            "current_todo_item": self.current_todo_item,
+            "progress_on_item": self.progress_on_item,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ContextCheckpoint":
+        """Create from dictionary."""
+        return cls(
+            active=data.get("active", False),
+            level=data.get("level", ""),
+            percent_at_checkpoint=data.get("percent_at_checkpoint", 0),
+            timestamp=data.get("timestamp", ""),
+            handoff_file=data.get("handoff_file", ""),
+            resume_summary=data.get("resume_summary", ""),
+            files_in_progress=data.get("files_in_progress", []),
+            current_todo_item=data.get("current_todo_item", ""),
+            progress_on_item=data.get("progress_on_item", ""),
+        )
+
+
+@dataclass
+class RalphState:
+    """Ralph Wiggum execution state."""
+
+    task_name: str
+    objective: str
+    iteration: int = 0
+    started_at: str = ""
+    status: str = "running"
+    no_change_count: int = 0
+    last_diff_hash: str = ""
+    error_hashes: List[str] = field(default_factory=list)
+    max_iterations: int = DEFAULT_MAX_ITERATIONS
+    completion_promise: str = DEFAULT_COMPLETION_PROMISE
+    todo_items: List[str] = field(default_factory=list)
+    completed_items: List[str] = field(default_factory=list)
+
+    # CCS checkpoint state (ANV-198)
+    context_checkpoint: Optional[ContextCheckpoint] = None
+    context_history: List[Dict[str, Any]] = field(default_factory=list)
+
+    # Linear integration (ANV-211)
+    linear_integration: Optional[LinearIntegration] = None
+
+    # File paths
+    state_file: str = DEFAULT_STATE_FILE
+    progress_file: str = DEFAULT_PROGRESS_FILE
+    fix_plan_file: str = DEFAULT_FIX_PLAN_FILE
+    prompt_file: str = DEFAULT_PROMPT_FILE
+
+    @classmethod
+    def initialize(
+        cls,
+        task_name: str,
+        objective: str,
+        todo_items: Optional[List[str]] = None,
+        max_iterations: int = DEFAULT_MAX_ITERATIONS,
+        completion_promise: str = DEFAULT_COMPLETION_PROMISE,
+        state_file: str = DEFAULT_STATE_FILE,
+        linear_integration: Optional[LinearIntegration] = None,
+    ) -> "RalphState":
+        """Initialize a new Ralph session."""
+        now = datetime.now(timezone.utc).isoformat()
+
+        state = cls(
+            task_name=task_name,
+            objective=objective,
+            iteration=0,
+            started_at=now,
+            status="running",
+            no_change_count=0,
+            last_diff_hash="",
+            error_hashes=[],
+            max_iterations=max_iterations,
+            completion_promise=completion_promise,
+            todo_items=todo_items or [],
+            completed_items=[],
+            context_checkpoint=None,
+            context_history=[],
+            linear_integration=linear_integration,
+            state_file=state_file,
+        )
+
+        # Ensure directory exists
+        Path(state_file).parent.mkdir(parents=True, exist_ok=True)
+
+        state.save()
+        return state
+
+    @classmethod
+    def load(cls, state_file: str = DEFAULT_STATE_FILE) -> Optional["RalphState"]:
+        """Load existing Ralph state from file."""
+        if not Path(state_file).exists():
+            return None
+
+        try:
+            with open(state_file, "r") as f:
+                data = json.load(f)
+
+            # Handle legacy state files without all fields
+            # Parse context_checkpoint if present (ANV-198)
+            checkpoint_data = data.get("context_checkpoint")
+            context_checkpoint = (
+                ContextCheckpoint.from_dict(checkpoint_data)
+                if checkpoint_data
+                else None
+            )
+
+            # Parse linear_integration if present (ANV-211)
+            linear_data = data.get("linear_integration")
+            linear_integration = (
+                LinearIntegration.from_dict(linear_data)
+                if linear_data
+                else None
+            )
+
+            return cls(
+                task_name=data.get("task_name", "unknown"),
+                objective=data.get("objective", ""),
+                iteration=data.get("iteration", 0),
+                started_at=data.get("started_at", ""),
+                status=data.get("status", "unknown"),
+                no_change_count=data.get("no_change_count", 0),
+                last_diff_hash=data.get("last_diff_hash", ""),
+                error_hashes=data.get("error_hashes", []),
+                max_iterations=data.get("max_iterations", DEFAULT_MAX_ITERATIONS),
+                completion_promise=data.get(
+                    "completion_promise", DEFAULT_COMPLETION_PROMISE
+                ),
+                todo_items=data.get("todo_items", []),
+                completed_items=data.get("completed_items", []),
+                context_checkpoint=context_checkpoint,
+                context_history=data.get("context_history", []),
+                linear_integration=linear_integration,
+                state_file=state_file,
+                progress_file=data.get("progress_file", DEFAULT_PROGRESS_FILE),
+                fix_plan_file=data.get("fix_plan_file", DEFAULT_FIX_PLAN_FILE),
+                prompt_file=data.get("prompt_file", DEFAULT_PROMPT_FILE),
+            )
+        except (json.JSONDecodeError, KeyError) as e:
+            print(f"Error loading state: {e}")
+            return None
+
+    @classmethod
+    def exists(cls, state_file: str = DEFAULT_STATE_FILE) -> bool:
+        """Check if a Ralph session is active."""
+        return Path(state_file).exists()
+
+    def save(self) -> None:
+        """Save state to file."""
+        Path(self.state_file).parent.mkdir(parents=True, exist_ok=True)
+
+        data = {
+            "task_name": self.task_name,
+            "objective": self.objective,
+            "iteration": self.iteration,
+            "started_at": self.started_at,
+            "status": self.status,
+            "no_change_count": self.no_change_count,
+            "last_diff_hash": self.last_diff_hash,
+            "error_hashes": self.error_hashes,
+            "max_iterations": self.max_iterations,
+            "completion_promise": self.completion_promise,
+            "todo_items": self.todo_items,
+            "completed_items": self.completed_items,
+            "progress_file": self.progress_file,
+            "fix_plan_file": self.fix_plan_file,
+            "prompt_file": self.prompt_file,
+            # CCS checkpoint state (ANV-198)
+            "context_checkpoint": (
+                self.context_checkpoint.to_dict()
+                if self.context_checkpoint
+                else None
+            ),
+            "context_history": self.context_history,
+            # Linear integration (ANV-211)
+            "linear_integration": (
+                self.linear_integration.to_dict()
+                if self.linear_integration
+                else None
+            ),
+        }
+
+        with open(self.state_file, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def delete(self) -> None:
+        """Delete state file (cleanup)."""
+        if Path(self.state_file).exists():
+            Path(self.state_file).unlink()
+
+    # =========================================================================
+    # State Updates
+    # =========================================================================
+
+    def increment_iteration(self) -> int:
+        """Increment iteration counter and save."""
+        self.iteration += 1
+        self.save()
+        return self.iteration
+
+    def update_status(self, status: str) -> None:
+        """Update status and save."""
+        valid_statuses = [
+            "running",
+            "completed",
+            "fatal_error",
+            "circuit_breaker",
+            "max_iterations",
+            "stopped",
+            "interrupted",
+        ]
+        if status not in valid_statuses:
+            raise ValueError(
+                f"Invalid status: {status}. Must be one of {valid_statuses}"
+            )
+
+        self.status = status
+        self.save()
+
+    def mark_item_complete(self, item: str) -> None:
+        """Mark a todo item as complete."""
+        if item in self.todo_items:
+            self.todo_items.remove(item)
+        if item not in self.completed_items:
+            self.completed_items.append(item)
+        self.save()
+
+    def add_todo_item(self, item: str) -> None:
+        """Add a new todo item."""
+        if item not in self.todo_items:
+            self.todo_items.append(item)
+            self.save()
+
+    def record_no_change(self, diff_hash: str) -> int:
+        """Record a no-change iteration, return count."""
+        if diff_hash == self.last_diff_hash and self.last_diff_hash:
+            self.no_change_count += 1
+        else:
+            self.no_change_count = 0
+            self.last_diff_hash = diff_hash
+        self.save()
+        return self.no_change_count
+
+    def record_error(self, error_hash: str) -> int:
+        """Record an error hash, return count of this specific error."""
+        self.error_hashes.append(error_hash)
+        count = self.error_hashes.count(error_hash)
+        self.save()
+        return count
+
+    # =========================================================================
+    # Queries
+    # =========================================================================
+
+    @property
+    def remaining_items(self) -> int:
+        """Number of remaining todo items."""
+        return len(self.todo_items)
+
+    @property
+    def total_items(self) -> int:
+        """Total number of items (complete + remaining)."""
+        return len(self.todo_items) + len(self.completed_items)
+
+    @property
+    def progress_percent(self) -> float:
+        """Completion percentage."""
+        total = self.total_items
+        if total == 0:
+            return 0.0
+        return (len(self.completed_items) / total) * 100
+
+    @property
+    def is_complete(self) -> bool:
+        """Check if all items are complete."""
+        return len(self.todo_items) == 0 and len(self.completed_items) > 0
+
+    @property
+    def duration_minutes(self) -> float:
+        """Duration since start in minutes."""
+        if not self.started_at:
+            return 0.0
+        try:
+            start = datetime.fromisoformat(self.started_at.replace("Z", "+00:00"))
+            now = datetime.now(timezone.utc)
+            return (now - start).total_seconds() / 60
+        except ValueError:
+            return 0.0
+
+    # =========================================================================
+    # Reporting
+    # =========================================================================
+
+    def status_report(self) -> str:
+        """Generate a status report for display."""
+        duration = self.duration_minutes
+
+        if duration < 60:
+            duration_str = f"{int(duration)} minutes"
+        else:
+            hours = int(duration // 60)
+            mins = int(duration % 60)
+            duration_str = f"{hours}h {mins}m"
+
+        report = f"""## Ralph Wiggum Status
+
+| Metric | Value |
+|--------|-------|
+| Status | {self.status.replace('_', ' ').title()} |
+| Iteration | {self.iteration} of {self.max_iterations} |
+| Started | {self.started_at} |
+| Duration | {duration_str} |
+| Items Complete | {len(self.completed_items)} of {self.total_items} |
+| Progress | {self.progress_percent:.0f}% |
+"""
+
+        if self.completed_items:
+            report += "\n### Recently Completed\n"
+            for item in self.completed_items[-3:]:
+                report += f"- {item}\n"
+
+        if self.todo_items:
+            report += "\n### Remaining Items\n"
+            for item in self.todo_items[:5]:
+                report += f"- [ ] {item}\n"
+            if len(self.todo_items) > 5:
+                report += f"- ... and {len(self.todo_items) - 5} more\n"
+
+        if self.no_change_count > 0:
+            report += (
+                f"\n**Warning**: {self.no_change_count} iterations "
+                "with no file changes\n"
+            )
+
+        # Add Linear integration status (ANV-212)
+        if self.linear_integration and self.linear_integration.enabled:
+            completed, skipped, remaining = self.get_linear_progress()
+            sync_status = "Disabled" if self.linear_integration.no_sync else "Enabled"
+            parent = self.linear_integration.parent_issue or "Unknown"
+
+            report += f"""
+### Linear Integration
+| Field | Value |
+|-------|-------|
+| Parent Issue | {parent} |
+| Subtasks | {completed} done, {skipped} skipped, {remaining} remaining |
+| Last Sync | {self.linear_integration.last_sync or "Never"} |
+| Sync Status | {sync_status} |
+"""
+            # Show current subtask
+            next_subtask = self.get_next_subtask()
+            if next_subtask:
+                report += f"\n### Current Subtask\n[{next_subtask.identifier}] {next_subtask.title}\n"
+
+        return report
+
+    def stop_summary(self) -> str:
+        """Generate a summary for manual stop."""
+        return f"""## Ralph Wiggum Stopped
+
+Task: {self.task_name}
+Iterations completed: {self.iteration}
+Items completed: {len(self.completed_items)} of {self.total_items}
+Status: Manually stopped
+
+### Remaining items:
+{chr(10).join(f'- [ ] {item}' for item in self.todo_items)}
+
+To resume later, run: /ralph start "{self.objective}"
+"""
+
+
+
+    # =========================================================================
+    # Linear Integration (ANV-211)
+    # =========================================================================
+
+    @classmethod
+    def initialize_from_linear(
+        cls,
+        issue_id: str,
+        subtask_filter: Optional[str] = None,
+        no_sync: bool = False,
+        state_file: str = DEFAULT_STATE_FILE,
+    ) -> "RalphState":
+        """Initialize Ralph session from a Linear issue.
+
+        Args:
+            issue_id: Linear issue identifier (e.g., "ANV-209")
+            subtask_filter: Optional filter for subtasks (e.g., "ANV-1..ANV-5" or "ANV-1,ANV-3")
+            no_sync: If True, don't sync status updates back to Linear
+            state_file: Path to state file
+
+        Returns:
+            Initialized RalphState with Linear integration enabled
+        """
+        # ANV-120: Use _create_linear_provider() to ensure proper team config
+        provider = _create_linear_provider()
+
+        # Fetch issue details
+        issue = provider.get_issue(issue_id)
+        if not issue:
+            raise ValueError(f"Issue {issue_id} not found in Linear")
+
+        # Fetch subtasks (children) - Issue objects use attribute access
+        children = provider.get_children(issue.id)
+        if not children:
+            raise ValueError(f"Issue {issue_id} has no subtasks to process")
+
+        # Filter subtasks if specified
+        if subtask_filter:
+            children = cls._filter_subtasks(children, subtask_filter)
+            if not children:
+                raise ValueError(f"No subtasks match filter: {subtask_filter}")
+
+        # Build LinearSubtask objects from Issue dataclass instances
+        subtasks = []
+        todo_items = []
+        for child in children:
+            # Issue.status is an IssueStatus enum - check if done
+            child_status = child.status.value.lower() if child.status else ""
+            status = "completed" if child_status in ("done", "completed", "closed") else "todo"
+            subtask = LinearSubtask(
+                id=child.id,
+                identifier=child.identifier,
+                title=child.title,
+                status=status,
+            )
+            subtasks.append(subtask)
+            if status == "todo":
+                todo_items.append(f"[{child.identifier}] {child.title}")
+
+        # Create LinearIntegration
+        linear_integration = LinearIntegration(
+            enabled=True,
+            mode="issue",
+            parent_issue=issue.identifier,
+            parent_id=issue.id,
+            project_name=None,  # Issue dataclass doesn't expose project directly
+            subtasks=subtasks,
+            last_sync=datetime.now(timezone.utc).isoformat(),
+            no_sync=no_sync,
+        )
+
+        # Initialize state
+        state = cls(
+            task_name=f"Linear: {issue.identifier}",
+            objective=issue.title or "Complete Linear subtasks",
+            iteration=0,
+            started_at=datetime.now(timezone.utc).isoformat(),
+            status="running",
+            no_change_count=0,
+            last_diff_hash="",
+            error_hashes=[],
+            max_iterations=DEFAULT_MAX_ITERATIONS,
+            completion_promise=DEFAULT_COMPLETION_PROMISE,
+            todo_items=todo_items,
+            completed_items=[],
+            context_checkpoint=None,
+            context_history=[],
+            linear_integration=linear_integration,
+            state_file=state_file,
+        )
+
+        Path(state_file).parent.mkdir(parents=True, exist_ok=True)
+        state.save()
+        return state
+
+    @staticmethod
+    def _filter_subtasks(
+        subtasks: List[Any], filter_spec: str
+    ) -> List[Any]:
+        """Filter subtasks by range or list specification.
+
+        Args:
+            subtasks: List of Issue objects from LinearProvider
+            filter_spec: Filter specification:
+                - Range: "ANV-1..ANV-5" (inclusive)
+                - List: "ANV-1,ANV-3,ANV-7"
+
+        Returns:
+            Filtered list of Issue objects
+        """
+        # Range syntax: PREFIX-START..PREFIX-END
+        range_match = re.match(r"([A-Z]+-)(\d+)\.\.\1(\d+)", filter_spec)
+        if range_match:
+            prefix = range_match.group(1)
+            start_num = int(range_match.group(2))
+            end_num = int(range_match.group(3))
+            valid_ids = {f"{prefix}{n}" for n in range(start_num, end_num + 1)}
+            return [s for s in subtasks if s.identifier in valid_ids]
+
+        # List syntax: ID1,ID2,ID3
+        if "," in filter_spec:
+            valid_ids = {id.strip() for id in filter_spec.split(",")}
+            return [s for s in subtasks if s.identifier in valid_ids]
+
+        # Single ID
+        return [s for s in subtasks if s.identifier == filter_spec]
+
+    def get_next_subtask(self) -> Optional[LinearSubtask]:
+        """Get the next uncompleted Linear subtask.
+
+        Returns:
+            Next LinearSubtask with status 'todo', or None if all complete
+        """
+        if not self.linear_integration or not self.linear_integration.enabled:
+            return None
+
+        for subtask in self.linear_integration.subtasks:
+            if subtask.status == "todo":
+                return subtask
+        return None
+
+    def mark_subtask_complete(
+        self,
+        identifier: str,
+        skip_reason: Optional[str] = None,
+    ) -> bool:
+        """Mark a Linear subtask as complete and sync to Linear.
+
+        Args:
+            identifier: Linear issue identifier (e.g., "ANV-212")
+            skip_reason: If provided, mark as skipped instead of completed
+
+        Returns:
+            True if subtask was found and updated
+        """
+        if not self.linear_integration or not self.linear_integration.enabled:
+            return False
+
+        for subtask in self.linear_integration.subtasks:
+            if subtask.identifier == identifier:
+                now = datetime.now(timezone.utc).isoformat()
+                if skip_reason:
+                    subtask.status = "skipped"
+                    subtask.skip_reason = skip_reason
+                else:
+                    subtask.status = "completed"
+                subtask.completed_at = now
+
+                # Update todo_items
+                item_prefix = f"[{identifier}]"
+                self.todo_items = [t for t in self.todo_items if not t.startswith(item_prefix)]
+                if not skip_reason:
+                    self.completed_items.append(f"[{identifier}] {subtask.title}")
+
+                # Sync to Linear if not disabled
+                if not self.linear_integration.no_sync and not skip_reason:
+                    self.sync_to_linear(identifier, "done")
+
+                self.save()
+                return True
+        return False
+
+    def sync_to_linear(self, identifier: str, state_name: str) -> bool:
+        """Sync subtask status to Linear.
+
+        Args:
+            identifier: Linear issue identifier
+            state_name: Target state name ("done", "in_progress", etc.)
+
+        Returns:
+            True if sync succeeded
+        """
+        if not self.linear_integration or self.linear_integration.no_sync:
+            return False
+
+        try:
+            # ANV-120: Use _create_linear_provider() to ensure proper team config
+            provider = _create_linear_provider()
+
+            # Import IssueStatus for state conversion
+            try:
+                from .issue_models import IssueStatus
+            except ImportError:
+                from issue_models import IssueStatus
+
+            # Convert state name to IssueStatus enum
+            target_status = IssueStatus.from_linear_state(state_name)
+
+            # Update issue with the converted status
+            provider.update_issue(identifier, status=target_status)
+            self.linear_integration.last_sync = datetime.now(timezone.utc).isoformat()
+            self.save()
+            return True
+        except (ImportError, AttributeError, ValueError, OSError) as e:
+            # Log the error for debugging but don't crash
+            # Catch: ImportError (module issues), AttributeError (API mismatch),
+            # ValueError (bad data), OSError (network/auth failures)
+            print(f"Warning: Failed to sync {identifier} to Linear: {e}")
+            return False
+
+    def get_linear_progress(self) -> Tuple[int, int, int]:
+        """Get Linear subtask progress counts.
+
+        Returns:
+            Tuple of (completed, skipped, remaining)
+        """
+        if not self.linear_integration or not self.linear_integration.enabled:
+            return (0, 0, 0)
+
+        completed = sum(1 for s in self.linear_integration.subtasks if s.status == "completed")
+        skipped = sum(1 for s in self.linear_integration.subtasks if s.status == "skipped")
+        remaining = sum(1 for s in self.linear_integration.subtasks if s.status == "todo")
+        return (completed, skipped, remaining)
+
+
+# =============================================================================
+# File Generation
+# =============================================================================
+
+
+def create_fix_plan(
+    task_name: str,
+    objective: str,
+    todo_items: List[str],
+    completion_promise: str = DEFAULT_COMPLETION_PROMISE,
+    output_file: str = DEFAULT_FIX_PLAN_FILE,
+) -> None:
+    """Create fix_plan.md from template."""
+    timestamp = datetime.now(timezone.utc).isoformat()
+
+    items_md = "\n".join(f"- [ ] {item}" for item in todo_items)
+
+    content = f"""# Fix Plan: {task_name}
+
+> Generated: {timestamp}
+> Task: {objective}
+
+---
+
+## TODO Items
+
+Complete these items **one at a time**, in order:
+
+{items_md}
+
+---
+
+## Completion Criteria
+
+All items must be checked AND:
+- [ ] All tests passing
+- [ ] All lint checks passing
+- [ ] Code reviewed for quality
+
+When complete, output: `<promise>{completion_promise}</promise>`
+
+---
+
+## Notes
+
+- Mark items complete with `- [x]` when done
+- Do NOT skip items - complete in order
+- If stuck on an item for 3+ iterations, output `<fatal>reason</fatal>`
+"""
+
+    with open(output_file, "w") as f:
+        f.write(content)
+
+
+def create_progress_file(
+    task_name: str,
+    objective: str,
+    total_items: int,
+    output_file: str = DEFAULT_PROGRESS_FILE,
+) -> None:
+    """Create progress.txt from template."""
+    timestamp = datetime.now(timezone.utc).isoformat()
+
+    content = f"""# Ralph Wiggum Progress Log
+
+> Task: {task_name}
+> Started: {timestamp}
+> Objective: {objective}
+
+---
+
+## Iteration 0 - Initialization
+
+### Completed
+- Created fix_plan.md with {total_items} items
+- Initialized progress tracking
+
+### Next
+- Begin with first TODO item
+
+### Blockers
+- None
+
+---
+
+<!-- Each iteration should append a new section below -->
+
+"""
+
+    with open(output_file, "w") as f:
+        f.write(content)
+
+
+def create_prompt_file(
+    task_name: str,
+    objective: str,
+    iteration: int = 0,
+    last_action: str = "None (starting)",
+    remaining_count: int = 0,
+    total_items: int = 0,
+    started_at: str = "",
+    completion_promise: str = DEFAULT_COMPLETION_PROMISE,
+    additional_context: str = "",
+    output_file: str = DEFAULT_PROMPT_FILE,
+) -> None:
+    """Create PROMPT.md from template."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+    content = f"""# Task: {task_name}
+
+## Objective
+{objective}
+
+## Current State
+- **Iteration**: {iteration}
+- **Last action**: {last_action}
+- **Remaining items**: {remaining_count} of {total_items}
+- **Started**: {started_at}
+
+---
+
+## Instructions
+
+### Step 1: Review Progress
+1. **Read `progress.txt`** first - learn from what previous iterations attempted
+2. Read `fix_plan.md` for the current TODO list
+
+### Step 2: Execute ONE Item
+3. Find the **first unchecked item** in fix_plan.md
+4. Complete **ONLY that one item** - do not attempt multiple items
+5. Run tests after completion
+
+### Step 3: Update State
+6. If tests pass, mark the item complete in fix_plan.md: `- [x]`
+7. **Update `progress.txt`** with what you did this iteration
+
+### Step 4: Check Completion
+8. If ALL items are complete and tests pass, output:
+   ```
+   <promise>{completion_promise}</promise>
+   ```
+
+---
+
+## Progress Tracking (REQUIRED)
+
+After each iteration, **append** to `progress.txt`:
+
+```markdown
+## Iteration {iteration} - {timestamp}
+
+### Completed
+- [What you finished this iteration]
+
+### Attempted (if any failed)
+- [What you tried but couldn't complete]
+
+### Next
+- [What the next iteration should focus on]
+
+### Blockers
+- [Anything blocking progress, or "None"]
+```
+
+---
+
+## Constraints
+
+| Rule | Reason |
+|------|--------|
+| **ONE item per iteration** | Prevents context overflow |
+| **Always update progress.txt** | Prevents repeated mistakes |
+| **Run tests before marking complete** | Ensures quality |
+| **Commit on successful item** | Preserves progress |
+| **Use subagents for research** | Keeps main context clean |
+
+---
+
+## Completion Signal
+
+When ALL items are done and tests pass:
+```
+<promise>{completion_promise}</promise>
+```
+
+## Fatal Error Signal
+
+If stuck or unrecoverable after multiple attempts:
+```
+<fatal>Description of the blocking issue</fatal>
+```
+
+---
+
+## Context
+
+{additional_context if additional_context else "No additional context provided."}
+"""
+
+    with open(output_file, "w") as f:
+        f.write(content)
+
+
+# =============================================================================
+# CLI Interface
+# =============================================================================
+
+
+def main():
+    """CLI for ralph_state.py."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Ralph Wiggum State Management")
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # Init command
+    init_parser = subparsers.add_parser("init", help="Initialize Ralph session")
+    init_parser.add_argument("--task", required=True, help="Task name")
+    init_parser.add_argument("--objective", required=True, help="Task objective")
+    init_parser.add_argument("--items", nargs="+", help="Todo items")
+    init_parser.add_argument("--max-iterations", type=int, default=50)
+
+    # Status command
+    subparsers.add_parser("status", help="Show current status")
+
+    # Stop command
+    subparsers.add_parser("stop", help="Stop Ralph session")
+
+    # Init-linear command (ANV-211)
+    init_linear_parser = subparsers.add_parser(
+        "init-linear", help="Initialize Ralph from Linear issue"
+    )
+    init_linear_parser.add_argument(
+        "--issue", required=True, help="Linear issue ID (e.g., ANV-209)"
+    )
+    init_linear_parser.add_argument(
+        "--filter", help="Subtask filter (e.g., ANV-1..ANV-5 or ANV-1,ANV-3)"
+    )
+    init_linear_parser.add_argument(
+        "--no-sync", action="store_true", help="Don't sync status back to Linear"
+    )
+
+    # Sync command (ANV-211)
+    sync_parser = subparsers.add_parser("sync", help="Sync status with Linear")
+    # --complete and --skip are mutually exclusive
+    sync_action_group = sync_parser.add_mutually_exclusive_group()
+    sync_action_group.add_argument(
+        "--complete", help="Mark subtask complete (issue ID)"
+    )
+    sync_action_group.add_argument(
+        "--skip", help="Mark subtask skipped (issue ID)"
+    )
+    sync_parser.add_argument(
+        "--reason", help="Skip reason (used with --skip)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        state = RalphState.initialize(
+            task_name=args.task,
+            objective=args.objective,
+            todo_items=args.items or [],
+            max_iterations=args.max_iterations,
+        )
+
+        # Create supporting files
+        create_fix_plan(
+            args.task,
+            args.objective,
+            args.items or [],
+        )
+        create_progress_file(
+            args.task,
+            args.objective,
+            len(args.items or []),
+        )
+        create_prompt_file(
+            args.task,
+            args.objective,
+            remaining_count=len(args.items or []),
+            total_items=len(args.items or []),
+            started_at=state.started_at,
+        )
+
+        print(f"Ralph session initialized: {args.task}")
+        print(f"   State file: {state.state_file}")
+        print(f"   Items: {len(args.items or [])} todo items")
+
+    elif args.command == "status":
+        state = RalphState.load()
+        if state:
+            print(state.status_report())
+        else:
+            print("No active Ralph session")
+
+    elif args.command == "stop":
+        state = RalphState.load()
+        if state:
+            print(state.stop_summary())
+            state.update_status("stopped")
+            state.delete()
+            print("\nRalph session stopped and cleaned up")
+        else:
+            print("No active Ralph session to stop")
+
+    elif args.command == "init-linear":
+        try:
+            state = RalphState.initialize_from_linear(
+                issue_id=args.issue,
+                subtask_filter=args.filter,
+                no_sync=args.no_sync,
+            )
+
+            # Create supporting files
+            create_fix_plan(
+                state.task_name,
+                state.objective,
+                state.todo_items,
+            )
+            create_progress_file(
+                state.task_name,
+                state.objective,
+                len(state.todo_items),
+            )
+            create_prompt_file(
+                state.task_name,
+                state.objective,
+                remaining_count=len(state.todo_items),
+                total_items=len(state.todo_items),
+                started_at=state.started_at,
+            )
+
+            completed, skipped, remaining = state.get_linear_progress()
+            print(f"Ralph session initialized from Linear: {args.issue}")
+            print(f"   State file: {state.state_file}")
+            print(f"   Subtasks: {remaining} todo, {completed} already done")
+            if args.filter:
+                print(f"   Filter: {args.filter}")
+            if args.no_sync:
+                print("   Sync: DISABLED (changes won't update Linear)")
+
+        except ValueError as e:
+            print(f"Error: {e}")
+        except ImportError as e:
+            print(f"Error: Could not load Linear provider - {e}")
+
+    elif args.command == "sync":
+        state = RalphState.load()
+        if not state:
+            print("No active Ralph session")
+        elif not state.linear_integration or not state.linear_integration.enabled:
+            print("Linear integration not enabled for this session")
+        else:
+            if args.complete:
+                if state.mark_subtask_complete(args.complete):
+                    print(f"Marked {args.complete} as complete")
+                    if not state.linear_integration.no_sync:
+                        print("  -> Synced to Linear")
+                else:
+                    print(f"Subtask {args.complete} not found")
+            elif args.skip:
+                reason = args.reason or "Skipped via CLI"
+                if state.mark_subtask_complete(args.skip, skip_reason=reason):
+                    print(f"Marked {args.skip} as skipped: {reason}")
+                else:
+                    print(f"Subtask {args.skip} not found")
+            else:
+                # Show Linear progress
+                completed, skipped, remaining = state.get_linear_progress()
+                print(f"Linear Integration: {state.linear_integration.parent_issue}")
+                print(f"   Completed: {completed}")
+                print(f"   Skipped: {skipped}")
+                print(f"   Remaining: {remaining}")
+                print(f"   Last sync: {state.linear_integration.last_sync}")
+
+                next_task = state.get_next_subtask()
+                if next_task:
+                    print(f"\n   Next: [{next_task.identifier}] {next_task.title}")
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()