anvil-dev-framework 0.1.6

package/global/lib/ralph_prompt_generator.py

@@ -0,0 +1,563 @@
+#!/usr/bin/env python3
+"""
+ralph_prompt_generator.py - PROMPT.md Resume Template Generator (ANV-201)
+
+Generates resume PROMPT.md templates for checkpoint continuation, supporting
+both Ralph autonomous mode and manual session resumption.
+
+Usage:
+    from global.lib.ralph_prompt_generator import generate_resume_prompt
+
+    # Generate resume prompt after checkpoint
+    content = generate_resume_prompt(
+        checkpoint=context_checkpoint,
+        state=ralph_state,
+        mode="ralph"  # or "manual"
+    )
+
+    # CLI usage
+    python ralph_prompt_generator.py --mode ralph --output PROMPT.md
+    python ralph_prompt_generator.py --mode manual --handoff .claude/handoffs/2026-01-11-1145.md
+"""
+
+import json
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+DEFAULT_STATE_FILE = ".claude/ralph-state.json"
+DEFAULT_PROMPT_FILE = "PROMPT.md"
+DEFAULT_HANDOFFS_DIR = ".claude/handoffs"
+
+
+# =============================================================================
+# Template Sections
+# =============================================================================
+
+
+def get_checkpoint_header(
+    level: str,
+    percent: int,
+    timestamp: str,
+    mode: str = "ralph",
+) -> str:
+    """Generate checkpoint resume header section."""
+    mode_label = "Ralph Autonomous" if mode == "ralph" else "Manual"
+    return f"""# {mode_label} Session Resume
+
+> **Context Checkpoint Recovery**
+> Generated at {timestamp}
+> Previous session hit {level} threshold ({percent}% context)
+
+---
+"""
+
+
+def get_session_summary(
+    task_name: str,
+    objective: str,
+    iteration: int,
+    completed_items: List[str],
+    total_items: int,
+) -> str:
+    """Generate previous session summary section."""
+    completed_count = len(completed_items)
+    progress_pct = int((completed_count / total_items) * 100) if total_items > 0 else 0
+
+    completed_list = ""
+    if completed_items:
+        completed_list = "\n".join(f"  - [x] {item}" for item in completed_items[-5:])
+        if len(completed_items) > 5:
+            completed_list = f"  (...{len(completed_items) - 5} earlier items)\n" + completed_list
+    else:
+        completed_list = "  (None completed yet)"
+
+    return f"""## Previous Session Summary
+
+**Task**: {task_name}
+**Objective**: {objective}
+**Iteration**: {iteration}
+**Progress**: {completed_count}/{total_items} items ({progress_pct}%)
+
+### Completed Work
+{completed_list}
+
+---
+"""
+
+
+def get_handoff_reference(handoff_file: str) -> str:
+    """Generate handoff document reference section."""
+    if not handoff_file:
+        return ""
+
+    return f"""## Handoff Document
+
+The previous session created a detailed handoff document with full context:
+
+```
+{handoff_file}
+```
+
+**IMPORTANT**: Read this file first to understand the full context of where work left off.
+
+---
+"""
+
+
+def get_memory_query_instructions(include_anvil_memory: bool = True) -> str:
+    """Generate Anvil Memory query instructions section."""
+    if not include_anvil_memory:
+        return ""
+
+    return """## Memory Query (Optional)
+
+If Anvil Memory is configured, query for additional context:
+
+```bash
+# Get recent checkpoint context
+anvil-memory context --include-checkpoints --limit 5
+
+# Get session history for this task
+anvil-memory search --type checkpoint --project $(basename $(pwd))
+```
+
+This provides cross-session context that may help with continuation.
+
+---
+"""
+
+
+def get_current_task_context(
+    current_todo_item: str,
+    progress_on_item: str,
+    files_in_progress: List[Dict[str, Any]],
+    remaining_items: List[str],
+) -> str:
+    """Generate current task context section."""
+
+    # Current item being worked on
+    current_section = ""
+    if current_todo_item:
+        current_section = f"""### Current Item (In Progress)
+
+**Task**: {current_todo_item}
+**Progress**: {progress_on_item or "Started but not completed"}
+"""
+
+    # Files that were being modified
+    files_section = ""
+    if files_in_progress:
+        files_list = "\n".join(
+            f"  - `{f.get('path', 'unknown')}` (lines {f.get('start_line', '?')}-{f.get('end_line', '?')})"
+            for f in files_in_progress[:5]
+        )
+        files_section = f"""
+### Files In Progress
+
+{files_list}
+"""
+
+    # Remaining todo items
+    remaining_section = ""
+    if remaining_items:
+        remaining_list = "\n".join(f"  - [ ] {item}" for item in remaining_items[:10])
+        if len(remaining_items) > 10:
+            remaining_list += f"\n  - ... and {len(remaining_items) - 10} more items"
+        remaining_section = f"""
+### Remaining Work
+
+{remaining_list}
+"""
+
+    return f"""## Current Task Context
+
+{current_section}{files_section}{remaining_section}
+---
+"""
+
+
+def get_resume_instructions(mode: str = "ralph") -> str:
+    """Generate resume instructions section."""
+
+    if mode == "ralph":
+        return """## Resume Instructions
+
+**CRITICAL**: This is a continuation session. Follow these rules:
+
+1. **DO NOT restart from the beginning** - Work has already been done
+2. **Read the handoff document first** - Contains full context
+3. **Continue from the current item** - Pick up exactly where left off
+4. **Complete current task before moving on** - Don't skip items
+5. **Signal completion with `<promise>COMPLETE</promise>`** when done
+
+### Ralph Mode Guidelines
+
+- The loop will continue until completion or safety limits
+- Create git checkpoints at each iteration
+- If stuck, write to `fix_plan.md` for next iteration
+- Report progress to `progress.txt`
+
+---
+"""
+    else:
+        return """## Resume Instructions
+
+**CRITICAL**: This is a continuation of a previous session. Follow these steps:
+
+1. **Read the handoff document** - Contains full context from previous session
+2. **Check git status** - See what files were modified
+3. **Review the remaining todo items** - Understand what's left
+4. **Continue from where left off** - Don't restart completed work
+
+### Manual Resume Checklist
+
+- [ ] Read handoff document
+- [ ] Run `git status` and `git diff` to see current state
+- [ ] Review any uncommitted changes
+- [ ] Understand the current task context
+- [ ] Continue implementation from the stopping point
+
+### If Unsure
+
+If the context is unclear, ask clarifying questions before proceeding.
+It's better to confirm understanding than to redo completed work.
+
+---
+"""
+
+
+def get_next_steps(
+    current_todo_item: str,
+    remaining_items: List[str],
+) -> str:
+    """Generate next steps section."""
+    steps = []
+
+    if current_todo_item:
+        steps.append(f"1. Complete current item: **{current_todo_item}**")
+
+    if remaining_items:
+        next_item = remaining_items[0] if not current_todo_item else (
+            remaining_items[1] if len(remaining_items) > 1 else None
+        )
+        if next_item:
+            steps.append(f"2. Move to next item: {next_item}")
+
+    if not steps:
+        steps.append("1. Review handoff document for context")
+        steps.append("2. Determine what work remains")
+
+    steps.append(f"{len(steps) + 1}. Continue until task is complete")
+
+    return f"""## Next Steps
+
+{chr(10).join(steps)}
+"""
+
+
+def get_footer(mode: str = "ralph") -> str:
+    """Generate footer section."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    if mode == "ralph":
+        return f"""
+---
+
+*This prompt was auto-generated by ralph_prompt_generator.py (ANV-201)*
+*Generated at: {timestamp}*
+*Mode: Ralph Autonomous Execution*
+"""
+    else:
+        return f"""
+---
+
+*This prompt was auto-generated for manual session resumption (ANV-201)*
+*Generated at: {timestamp}*
+*Mode: Manual Resume*
+"""
+
+
+# =============================================================================
+# Main Generator Functions
+# =============================================================================
+
+
+def generate_resume_prompt(
+    level: str = "L2",
+    percent: int = 85,
+    timestamp: Optional[str] = None,
+    task_name: str = "",
+    objective: str = "",
+    iteration: int = 0,
+    handoff_file: str = "",
+    current_todo_item: str = "",
+    progress_on_item: str = "",
+    files_in_progress: Optional[List[Dict[str, Any]]] = None,
+    completed_items: Optional[List[str]] = None,
+    remaining_items: Optional[List[str]] = None,
+    mode: str = "ralph",
+    include_anvil_memory: bool = True,
+) -> str:
+    """Generate a complete resume PROMPT.md.
+
+    Args:
+        level: CCS level that triggered checkpoint (L1, L2, L3)
+        percent: Context percentage at checkpoint
+        timestamp: Checkpoint timestamp (auto-generated if not provided)
+        task_name: Name of the task being worked on
+        objective: Task objective description
+        iteration: Ralph iteration number
+        handoff_file: Path to handoff document
+        current_todo_item: Item currently being worked on
+        progress_on_item: Progress description for current item
+        files_in_progress: List of files being modified
+        completed_items: List of completed todo items
+        remaining_items: List of remaining todo items
+        mode: "ralph" or "manual" - affects instructions
+        include_anvil_memory: Whether to include memory query instructions
+
+    Returns:
+        Complete PROMPT.md content as string
+    """
+    if timestamp is None:
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    files_in_progress = files_in_progress or []
+    completed_items = completed_items or []
+    remaining_items = remaining_items or []
+    total_items = len(completed_items) + len(remaining_items)
+    if current_todo_item and current_todo_item not in remaining_items:
+        total_items += 1
+
+    sections = [
+        get_checkpoint_header(level, percent, timestamp, mode),
+        get_session_summary(task_name, objective, iteration, completed_items, total_items),
+        get_handoff_reference(handoff_file),
+        get_memory_query_instructions(include_anvil_memory),
+        get_current_task_context(
+            current_todo_item, progress_on_item, files_in_progress, remaining_items
+        ),
+        get_resume_instructions(mode),
+        get_next_steps(current_todo_item, remaining_items),
+        get_footer(mode),
+    ]
+
+    return "".join(sections)
+
+
+def generate_from_state(
+    state_file: str = DEFAULT_STATE_FILE,
+    mode: str = "ralph",
+    include_anvil_memory: bool = True,
+) -> str:
+    """Generate resume prompt from Ralph state file.
+
+    Args:
+        state_file: Path to ralph-state.json
+        mode: "ralph" or "manual"
+        include_anvil_memory: Whether to include memory query instructions
+
+    Returns:
+        Complete PROMPT.md content as string
+    """
+    state_path = Path(state_file)
+    if not state_path.exists():
+        raise FileNotFoundError(f"State file not found: {state_file}")
+
+    with open(state_path) as f:
+        state = json.load(f)
+
+    # Extract checkpoint info
+    checkpoint = state.get("context_checkpoint", {})
+
+    return generate_resume_prompt(
+        level=checkpoint.get("level", "L2"),
+        percent=checkpoint.get("percent_at_checkpoint", 85),
+        timestamp=checkpoint.get("timestamp"),
+        task_name=state.get("task_name", "Unknown Task"),
+        objective=state.get("objective", ""),
+        iteration=state.get("iteration", 0),
+        handoff_file=checkpoint.get("handoff_file", ""),
+        current_todo_item=checkpoint.get("current_todo_item", ""),
+        progress_on_item=checkpoint.get("progress_on_item", ""),
+        files_in_progress=checkpoint.get("files_in_progress", []),
+        completed_items=state.get("completed_items", []),
+        remaining_items=state.get("todo_items", []),
+        mode=mode,
+        include_anvil_memory=include_anvil_memory,
+    )
+
+
+def generate_from_handoff(
+    handoff_file: str,
+    mode: str = "manual",
+    include_anvil_memory: bool = True,
+) -> str:
+    """Generate resume prompt from a handoff document.
+
+    Args:
+        handoff_file: Path to handoff markdown file
+        mode: "ralph" or "manual"
+        include_anvil_memory: Whether to include memory query instructions
+
+    Returns:
+        Complete PROMPT.md content as string
+    """
+    handoff_path = Path(handoff_file)
+    if not handoff_path.exists():
+        raise FileNotFoundError(f"Handoff file not found: {handoff_file}")
+
+    content = handoff_path.read_text()
+
+    # Parse YAML frontmatter if present
+    task_name = ""
+    level = "L2"
+    percent = 85
+
+    if content.startswith("---"):
+        parts = content.split("---", 2)
+        if len(parts) >= 3:
+            import yaml
+            try:
+                meta = yaml.safe_load(parts[1])
+                task_name = meta.get("linear_issues", "")
+                # Try to extract checkpoint info from frontmatter
+                if "checkpoint_trigger" in meta:
+                    trigger = meta["checkpoint_trigger"]
+                    if "L3" in trigger:
+                        level = "L3"
+                    elif "L2" in trigger:
+                        level = "L2"
+                    elif "L1" in trigger:
+                        level = "L1"
+                if "context_at_checkpoint" in meta:
+                    percent = meta["context_at_checkpoint"]
+            except Exception:
+                pass
+
+    # Extract task name from first heading if not in frontmatter
+    if not task_name:
+        for line in content.split("\n"):
+            if line.startswith("# "):
+                task_name = line[2:].strip()
+                break
+
+    return generate_resume_prompt(
+        level=level,
+        percent=percent,
+        task_name=task_name,
+        objective="Resume from handoff document",
+        handoff_file=handoff_file,
+        mode=mode,
+        include_anvil_memory=include_anvil_memory,
+    )
+
+
+def write_resume_prompt(
+    content: str,
+    output_file: str = DEFAULT_PROMPT_FILE,
+) -> str:
+    """Write resume prompt to file.
+
+    Args:
+        content: PROMPT.md content
+        output_file: Output file path
+
+    Returns:
+        Path to written file
+    """
+    output_path = Path(output_file)
+    output_path.write_text(content)
+    return str(output_path)
+
+
+# =============================================================================
+# CLI Entry Point
+# =============================================================================
+
+
+def main():
+    """CLI entry point for ralph_prompt_generator."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Generate PROMPT.md resume templates for checkpoint continuation"
+    )
+
+    parser.add_argument(
+        "--mode",
+        choices=["ralph", "manual"],
+        default="ralph",
+        help="Resume mode: ralph (autonomous) or manual",
+    )
+
+    parser.add_argument(
+        "--state",
+        default=DEFAULT_STATE_FILE,
+        help=f"Path to ralph-state.json (default: {DEFAULT_STATE_FILE})",
+    )
+
+    parser.add_argument(
+        "--handoff",
+        help="Path to handoff document (for manual mode)",
+    )
+
+    parser.add_argument(
+        "--output",
+        default=DEFAULT_PROMPT_FILE,
+        help=f"Output file path (default: {DEFAULT_PROMPT_FILE})",
+    )
+
+    parser.add_argument(
+        "--no-memory",
+        action="store_true",
+        help="Exclude Anvil Memory query instructions",
+    )
+
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print to stdout instead of writing file",
+    )
+
+    args = parser.parse_args()
+
+    include_memory = not args.no_memory
+
+    try:
+        if args.handoff:
+            content = generate_from_handoff(
+                args.handoff,
+                mode=args.mode,
+                include_anvil_memory=include_memory,
+            )
+        else:
+            content = generate_from_state(
+                args.state,
+                mode=args.mode,
+                include_anvil_memory=include_memory,
+            )
+
+        if args.dry_run:
+            print(content)
+        else:
+            output_path = write_resume_prompt(content, args.output)
+            print(f"Generated resume prompt: {output_path}")
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        exit(1)
+    except Exception as e:
+        print(f"Error generating resume prompt: {e}")
+        exit(1)
+
+
+if __name__ == "__main__":
+    main()