claude-self-reflect 7.0.0 → 7.1.8

package/src/runtime/hooks/ralph_state.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python3
+"""
+Ralph State File Manager - Schema and parsing for .ralph_state.md
+
+This module provides:
+1. State file schema definition
+2. Parsing utilities to read/write state
+3. Validation for state integrity
+
+Enhanced Features (v7.1+):
+- Output decline detection (circuit breaker pattern)
+- Error signature deduplication
+- Confidence-based exit signals
+- Work type tracking (IMPLEMENTATION/TESTING/DEBUGGING)
+
+Attribution:
+    Several patterns in this module were inspired by the excellent work in
+    https://github.com/frankbria/ralph-claude-code - a community implementation
+    of autonomous AI development loops. We gratefully acknowledge their
+    contributions to the Ralph loop ecosystem.
+"""
+
+import re
+import json
+from pathlib import Path
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Optional
+from datetime import datetime
+
+
+@dataclass
+class RalphState:
+    """Schema for .ralph_state.md file content."""
+
+    # Session metadata
+    session_id: str = ""
+    task: str = ""
+    iteration: int = 0
+    started_at: str = ""
+    updated_at: str = ""
+
+    # Current approach
+    current_approach: str = ""
+
+    # History tracking
+    failed_approaches: List[str] = field(default_factory=list)
+    successful_strategies: List[str] = field(default_factory=list)
+    blocking_errors: List[str] = field(default_factory=list)
+
+    # Progress tracking
+    files_modified: List[str] = field(default_factory=list)
+    learnings: List[str] = field(default_factory=list)
+
+    # Next action
+    next_action: str = ""
+
+    # Completion tracking
+    completion_promise: str = ""
+    completion_promise_met: bool = False
+
+    # Output tracking for decline detection (circuit breaker pattern)
+    output_lengths: List[int] = field(default_factory=list)
+
+    # Confidence-based exit scoring (0-100)
+    exit_confidence: int = 0
+
+    # Work type tracking for filtering
+    work_type: str = ""  # IMPLEMENTATION, TESTING, DEBUGGING, DOCUMENTATION
+
+    # Deduplicated error signatures for anti-pattern detection
+    error_signatures: Dict[str, int] = field(default_factory=dict)  # sig -> count
+
+    def _error_signature(self, error: str) -> str:
+        """Extract error signature for deduplication (removes line numbers, paths)."""
+        sig = re.sub(r'line \d+', 'line N', error)
+        sig = re.sub(r'/[\w/.-]+/', '/.../', sig)
+        sig = re.sub(r'\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}', 'TIMESTAMP', sig)
+        return sig[:100]
+
+    def add_error(self, error: str) -> None:
+        """Add error with deduplication by signature."""
+        sig = self._error_signature(error)
+        prev_count = self.error_signatures.get(sig, 0)
+        self.error_signatures[sig] = prev_count + 1
+        # Only add to blocking_errors if this is a new signature (O(1) vs O(n²))
+        if prev_count == 0:
+            self.blocking_errors.append(error)
+
+    def track_output(self, length: int) -> None:
+        """Track output length for decline detection."""
+        self.output_lengths.append(length)
+        if len(self.output_lengths) > 10:
+            self.output_lengths = self.output_lengths[-10:]
+
+    def output_declining(self, threshold: float = 0.7) -> bool:
+        """Check if output is declining (circuit breaker signal)."""
+        if len(self.output_lengths) < 3:
+            return False
+        recent = self.output_lengths[-3:]
+        avg_recent = sum(recent) / len(recent)
+        earlier = self.output_lengths[:-3]
+        if not earlier:
+            return False
+        avg_earlier = sum(earlier) / len(earlier)
+        return avg_recent < (avg_earlier * threshold)
+
+    def update_confidence(self, signals: dict) -> None:
+        """Update exit confidence based on multiple signals."""
+        score = 0
+        if signals.get('all_tasks_complete'):
+            score += 40
+        if signals.get('tests_passing'):
+            score += 20
+        if signals.get('no_errors'):
+            score += 20
+        if signals.get('done_keyword'):
+            score += 10
+        if signals.get('consecutive_test_only', 0) >= 3:
+            score += 10
+        self.exit_confidence = min(100, score)
+
+    def to_markdown(self) -> str:
+        """Convert state to markdown format for .ralph_state.md"""
+        # Format error signatures for display
+        error_sig_display = ""
+        if self.error_signatures:
+            error_sig_display = "\n".join(
+                f"- `{sig}` (x{count})" for sig, count in self.error_signatures.items()
+            )
+        else:
+            error_sig_display = "- (none yet)"
+
+        return f"""# Ralph Session State
+
+## Metadata
+- **Session ID:** {self.session_id}
+- **Task:** {self.task}
+- **Iteration:** {self.iteration}
+- **Started:** {self.started_at}
+- **Updated:** {self.updated_at}
+- **Work Type:** {self.work_type or 'UNKNOWN'}
+- **Exit Confidence:** {self.exit_confidence}%
+
+## Current Approach
+{self.current_approach}
+
+## Completion Promise
+`{self.completion_promise}`
+Met: {self.completion_promise_met}
+
+## Failed Approaches (DO NOT RETRY)
+{self._list_to_md(self.failed_approaches)}
+
+## Blocking Errors
+{self._list_to_md(self.blocking_errors)}
+
+## Error Signatures (Deduplicated)
+{error_sig_display}
+
+## Successful Strategies
+{self._list_to_md(self.successful_strategies)}
+
+## Files Modified
+{self._list_to_md(self.files_modified)}
+
+## Learnings
+{self._list_to_md(self.learnings)}
+
+## Output Tracking
+- Recent lengths: {self.output_lengths[-5:] if self.output_lengths else []}
+- Declining: {self.output_declining()}
+
+## Next Action
+{self.next_action}
+"""
+
+    def _list_to_md(self, items: List[str]) -> str:
+        """Convert list to markdown bullet points."""
+        if not items:
+            return "- (none yet)"
+        return "\n".join(f"- {item}" for item in items)
+
+    @classmethod
+    def create_new(cls, task: str, completion_promise: str, session_id: str = None) -> 'RalphState':
+        """Create a new state for a fresh Ralph session."""
+        import uuid
+        return cls(
+            session_id=session_id or f"ralph_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{uuid.uuid4().hex[:8]}",
+            task=task,
+            iteration=1,
+            started_at=datetime.now().isoformat(),
+            updated_at=datetime.now().isoformat(),
+            completion_promise=completion_promise
+        )
+
+    @classmethod
+    def from_markdown(cls, content: str) -> 'RalphState':
+        """Parse markdown content into RalphState object."""
+        state = cls()
+
+        # Parse metadata
+        if match := re.search(r'\*\*Session ID:\*\*\s*(.+)', content):
+            state.session_id = match.group(1).strip()
+        if match := re.search(r'\*\*Task:\*\*\s*(.+)', content):
+            state.task = match.group(1).strip()
+        if match := re.search(r'\*\*Iteration:\*\*\s*(\d+)', content):
+            state.iteration = int(match.group(1))
+        if match := re.search(r'\*\*Started:\*\*\s*(.+)', content):
+            state.started_at = match.group(1).strip()
+        if match := re.search(r'\*\*Updated:\*\*\s*(.+)', content):
+            state.updated_at = match.group(1).strip()
+
+        # NEW: Parse work type and exit confidence
+        if match := re.search(r'\*\*Work Type:\*\*\s*(.+)', content):
+            state.work_type = match.group(1).strip()
+        if match := re.search(r'\*\*Exit Confidence:\*\*\s*(\d+)', content):
+            state.exit_confidence = int(match.group(1))
+
+        # Parse completion promise
+        if match := re.search(r'## Completion Promise\n`(.+)`', content):
+            state.completion_promise = match.group(1)
+        if 'Met: True' in content:
+            state.completion_promise_met = True
+
+        # Parse current approach
+        if match := re.search(r'## Current Approach\n(.+?)(?=\n##|\Z)', content, re.DOTALL):
+            state.current_approach = match.group(1).strip()
+
+        # Parse next action
+        if match := re.search(r'## Next Action\n(.+?)(?=\n##|\Z)', content, re.DOTALL):
+            state.next_action = match.group(1).strip()
+
+        # Parse lists
+        state.failed_approaches = cls._parse_list_section(content, "Failed Approaches")
+        state.blocking_errors = cls._parse_list_section(content, "Blocking Errors")
+        state.successful_strategies = cls._parse_list_section(content, "Successful Strategies")
+        state.files_modified = cls._parse_list_section(content, "Files Modified")
+        state.learnings = cls._parse_list_section(content, "Learnings")
+
+        # NEW: Parse error signatures
+        state.error_signatures = cls._parse_error_signatures(content)
+
+        # NEW: Parse output lengths
+        if match := re.search(r'Recent lengths:\s*\[([^\]]*)\]', content):
+            try:
+                lengths_str = match.group(1).strip()
+                if lengths_str:
+                    state.output_lengths = [int(x.strip()) for x in lengths_str.split(',') if x.strip()]
+            except ValueError:
+                pass
+
+        return state
+
+    @staticmethod
+    def _parse_error_signatures(content: str) -> Dict[str, int]:
+        """Parse error signatures section."""
+        signatures = {}
+        pattern = r'## Error Signatures[^\n]*\n((?:- .+\n?)+)'
+        if match := re.search(pattern, content):
+            for line in match.group(1).strip().split('\n'):
+                # Format: - `signature` (xN)
+                sig_match = re.search(r'- `(.+?)` \(x(\d+)\)', line)
+                if sig_match:
+                    signatures[sig_match.group(1)] = int(sig_match.group(2))
+        return signatures
+
+    @staticmethod
+    def _parse_list_section(content: str, section_name: str) -> List[str]:
+        """Parse a markdown list section."""
+        pattern = rf'## {section_name}[^\n]*\n((?:- .+\n?)+)'
+        if match := re.search(pattern, content):
+            items = []
+            for line in match.group(1).strip().split('\n'):
+                if line.startswith('- ') and line != '- (none yet)':
+                    items.append(line[2:].strip())
+            return items
+        return []
+
+
+def load_state(path: Path = None) -> Optional[RalphState]:
+    """Load state from .ralph_state.md file."""
+    path = path or Path('.ralph_state.md')
+    if not path.exists():
+        return None
+    return RalphState.from_markdown(path.read_text())
+
+
+def save_state(state: RalphState, path: Path = None) -> None:
+    """Save state to .ralph_state.md file."""
+    path = path or Path('.ralph_state.md')
+    state.updated_at = datetime.now().isoformat()
+    path.write_text(state.to_markdown())
+
+
+def is_ralph_session() -> bool:
+    """Check if current directory has an ACTIVE Ralph session.
+
+    Checks for both:
+    - .claude/ralph-loop.local.md (ralph-wiggum plugin)
+    - .ralph_state.md (our custom state file)
+
+    Returns False if file exists but active: false.
+    """
+    for path in [Path('.claude/ralph-loop.local.md'), Path('.ralph_state.md')]:
+        if path.exists():
+            try:
+                content = path.read_text()
+                # Check for active: false explicitly
+                if 'active: false' in content:
+                    return False
+                # Check for active: true or assume active if file exists without active flag
+                if 'active: true' in content or 'active:' not in content:
+                    return True
+            except Exception:
+                pass
+    return False
+
+
+def get_ralph_state_path() -> Optional[Path]:
+    """Get the path to the active Ralph state file.
+
+    Priority:
+    1. .claude/ralph-loop.local.md (ralph-wiggum plugin)
+    2. .ralph_state.md (custom state)
+    """
+    ralph_wiggum_path = Path('.claude/ralph-loop.local.md')
+    custom_path = Path('.ralph_state.md')
+
+    if ralph_wiggum_path.exists():
+        return ralph_wiggum_path
+    if custom_path.exists():
+        return custom_path
+    return None
+
+
+def parse_ralph_wiggum_state(path: Path) -> Optional[RalphState]:
+    """Parse ralph-wiggum's .claude/ralph-loop.local.md format.
+
+    The format is:
+    ---
+    active: true
+    iteration: 1
+    max_iterations: 50
+    completion_promise: "COMPLETE"
+    started_at: "2026-01-04T04:25:46Z"
+    ---
+
+    Task description follows...
+    """
+    content = path.read_text()
+
+    state = RalphState()
+
+    # Parse YAML frontmatter
+    import re
+    frontmatter_match = re.search(r'^---\n(.+?)\n---\n(.+)', content, re.DOTALL)
+    if not frontmatter_match:
+        return None
+
+    frontmatter = frontmatter_match.group(1)
+    task_content = frontmatter_match.group(2).strip()
+
+    # Parse frontmatter fields
+    if match := re.search(r'iteration:\s*(\d+)', frontmatter):
+        state.iteration = int(match.group(1))
+    if match := re.search(r'max_iterations:\s*(\d+)', frontmatter):
+        # Store for reference but not in RalphState dataclass
+        pass
+    if match := re.search(r'completion_promise:\s*["\']?(.+?)["\']?\s*$', frontmatter, re.MULTILINE):
+        state.completion_promise = match.group(1).strip('"\'')
+    if match := re.search(r'started_at:\s*["\']?(.+?)["\']?\s*$', frontmatter, re.MULTILINE):
+        state.started_at = match.group(1).strip('"\'')
+
+    # Task is the content after frontmatter
+    state.task = task_content[:500]  # First 500 chars as task summary
+
+    # Generate session ID from file
+    state.session_id = f"ralph_wiggum_{state.started_at.replace(':', '').replace('-', '')[:15]}"
+
+    return state
+
+
+def load_ralph_session_state() -> Optional[RalphState]:
+    """Load Ralph state from whichever format is available.
+
+    Automatically detects and parses:
+    - .claude/ralph-loop.local.md (ralph-wiggum format)
+    - .ralph_state.md (our custom format)
+    """
+    path = get_ralph_state_path()
+    if not path:
+        return None
+
+    if path.name == 'ralph-loop.local.md':
+        return parse_ralph_wiggum_state(path)
+    else:
+        return load_state(path)

package/src/runtime/hooks/session_end_hook.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""
+Ralph SessionEnd Hook - Stores session narrative to CSR.
+
+Triggered at session end. Parses .ralph_state.md, determines outcome,
+and stores narrative with metadata for future sessions.
+
+Enhanced Features (v7.1+):
+- Structured status block extraction
+- Rich metadata storage (work type, confidence, error signatures)
+- Output trend tracking for circuit breaker patterns
+
+Input (stdin): JSON with session_id, transcript_path, reason
+Output: None (cannot block session end)
+
+Attribution:
+    Status block format inspired by https://github.com/frankbria/ralph-claude-code
+"""
+
+import sys
+import json
+import logging
+from pathlib import Path
+from datetime import datetime
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+from src.runtime.hooks.ralph_state import load_state, is_ralph_session, load_ralph_session_state
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def extract_status_block(content: str) -> dict:
+    """Extract ---RALPH_STATUS--- block if present.
+
+    Format:
+    ---RALPH_STATUS---
+    STATUS: IN_PROGRESS | COMPLETE | BLOCKED
+    WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION
+    EXIT_SIGNAL: true | false
+    ---END_RALPH_STATUS---
+    """
+    import re
+    match = re.search(
+        r'---RALPH_STATUS---\n(.+?)\n---END_RALPH_STATUS---',
+        content, re.DOTALL
+    )
+    if not match:
+        return {}
+
+    status = {}
+    for line in match.group(1).strip().split('\n'):
+        if ':' in line:
+            key, val = line.split(':', 1)
+            key = key.strip().lower().replace(' ', '_')
+            val = val.strip()
+            # Convert boolean strings
+            if val.lower() in ('true', 'false'):
+                val = val.lower() == 'true'
+            # Convert numeric strings
+            elif val.isdigit():
+                val = int(val)
+            status[key] = val
+    return status
+
+
+def get_project_root() -> Path:
+    """Dynamically determine project root (works for any installation)."""
+    # This file is at: <project_root>/src/runtime/hooks/session_end_hook.py
+    return Path(__file__).parent.parent.parent.parent
+
+
+def store_session_narrative(state, session_id: str, reason: str) -> bool:
+    """Store session narrative to CSR with rich metadata."""
+    try:
+        # Import CSR standalone client (dynamic path for any installation)
+        project_root = get_project_root()
+        mcp_server_path = project_root / "mcp-server" / "src"
+        if str(mcp_server_path) not in sys.path:
+            sys.path.insert(0, str(mcp_server_path))
+        from standalone_client import CSRStandaloneClient
+        client = CSRStandaloneClient()
+
+        # Determine outcome
+        if state.completion_promise_met:
+            outcome = "COMPLETED"
+        elif reason in ('clear', 'logout'):
+            outcome = "ABANDONED"
+        else:
+            outcome = "INCOMPLETE"
+
+        # Get enhanced fields if available (new RalphState fields)
+        work_type = getattr(state, 'work_type', '') or 'UNKNOWN'
+        exit_confidence = getattr(state, 'exit_confidence', 0)
+        error_signatures = getattr(state, 'error_signatures', {})
+        # Handle output_declining as either method or boolean safely
+        output_declining_attr = getattr(state, 'output_declining', None)
+        output_declining = output_declining_attr() if callable(output_declining_attr) else False
+
+        # Generate narrative with enhanced metadata
+        narrative = f"""# Ralph Session Complete
+
+## Metadata
+- Session ID: {state.session_id}
+- End Reason: {reason}
+- Timestamp: {datetime.now().isoformat()}
+- Total Iterations: {state.iteration}
+- Work Type: {work_type}
+- Exit Confidence: {exit_confidence}%
+- Output Trend: {"DECLINING" if output_declining else "STABLE"}
+
+## Task
+{state.task}
+
+## Outcome: {outcome}
+Completion Promise: `{state.completion_promise}`
+Promise Met: {state.completion_promise_met}
+
+## Final Approach
+{state.current_approach}
+
+## What Worked
+{chr(10).join(f'- {s}' for s in state.successful_strategies) or '- (none recorded)'}
+
+## What Failed (Don't Retry These)
+{chr(10).join(f'- {f}' for f in state.failed_approaches) or '- (none recorded)'}
+
+## Blocking Errors Encountered
+{chr(10).join(f'- {e}' for e in state.blocking_errors) or '- (none recorded)'}
+
+## Error Signatures (Deduplicated)
+{chr(10).join(f'- `{sig}` (x{count})' for sig, count in error_signatures.items()) or '- (none)'}
+
+## Key Learnings
+{chr(10).join(f'- {l}' for l in state.learnings) or '- (none recorded)'}
+
+## Files Modified
+{chr(10).join(f'- {f}' for f in state.files_modified) or '- (none recorded)'}
+"""
+
+        # Store with outcome-aware tags
+        tags = [
+            "ralph_session",
+            f"session_{state.session_id}",
+            f"outcome_{outcome.lower()}",
+            f"iterations_{state.iteration}",
+            f"work_type_{work_type.lower()}"
+        ]
+
+        # Rich metadata for better search filtering
+        metadata = {
+            "outcome": outcome,
+            "iterations": state.iteration,
+            "work_type": work_type,
+            "exit_confidence": exit_confidence,
+            "output_declining": output_declining,
+            "error_signatures": list(error_signatures.keys()),
+            "failed_approaches": state.failed_approaches,
+            "successful_strategies": state.successful_strategies,
+            "learnings": state.learnings,
+            "files_modified": state.files_modified,
+        }
+
+        # Note: CSR store_reflection may not support metadata yet,
+        # but we include the rich info in the narrative for searchability
+        client.store_reflection(content=narrative, tags=tags)
+
+        logger.info(f"Stored session narrative: {outcome}, {state.iteration} iterations, confidence={exit_confidence}%")
+
+        # If successful, also store the winning strategy separately
+        if outcome == "COMPLETED" and state.successful_strategies:
+            success_summary = f"""Successful Ralph approach for '{state.task[:100]}':
+Approach: {state.current_approach}
+Key strategies: {', '.join(state.successful_strategies[:5])}
+Exit confidence: {exit_confidence}%
+Iterations: {state.iteration}
+"""
+            client.store_reflection(
+                content=success_summary,
+                tags=["ralph_success", "winning_strategy", f"work_type_{work_type.lower()}"]
+            )
+
+        return True
+
+    except ImportError:
+        logger.warning("CSR standalone client not available")
+        return False
+    except Exception as e:
+        logger.error(f"Error storing narrative: {e}")
+        return False
+
+
+def cleanup_session_files():
+    """Clean up temporary session files."""
+    files_to_remove = [
+        Path('.ralph_past_sessions.md'),
+        Path('.ralph_memories.md')
+    ]
+
+    for f in files_to_remove:
+        if f.exists():
+            try:
+                f.unlink()
+                logger.info(f"Cleaned up: {f}")
+            except Exception as e:
+                logger.warning(f"Could not remove {f}: {e}")
+
+
+def main():
+    """Main hook entry point."""
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        input_data = {}
+
+    session_id = input_data.get('session_id', 'unknown')
+    reason = input_data.get('reason', 'other')
+
+    logger.info(f"SessionEnd hook triggered: reason={reason}")
+
+    # Check if this is a Ralph session
+    if not is_ralph_session():
+        sys.exit(0)
+
+    # Load state (supports both ralph-wiggum and custom formats)
+    state = load_ralph_session_state()
+    if not state:
+        logger.warning("Could not load Ralph state for narrative storage")
+        sys.exit(0)
+
+    # Store narrative to CSR
+    store_session_narrative(state, session_id, reason)
+
+    # Note: Don't clean up .ralph_state.md - it may be needed for resume
+    # Only clean up helper files
+    cleanup_session_files()
+
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()