anvil-dev-framework 0.1.6

package/global/lib/handoff_generator.py

@@ -0,0 +1,775 @@
+#!/usr/bin/env python3
+"""
+handoff_generator.py - CCS Handoff Document Generator (ANV-195)
+
+Generates structured handoff documents for checkpoint continuity.
+Collects session state (git, Linear, files) and generates markdown
+documents with checkpoint metadata and resume instructions.
+
+Usage:
+    from global.lib.handoff_generator import HandoffGenerator
+
+    # Generate handoff document
+    generator = HandoffGenerator(project_path="/path/to/project")
+    handoff = generator.generate(
+        trigger_level="L2",
+        context_percent=85,
+        linear_issue="ANV-123",
+        summary="Implementing feature X"
+    )
+
+    # Save to file
+    filepath = generator.save(handoff)
+"""
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import List, Optional, TypedDict
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+DEFAULT_HANDOFF_DIR = ".claude/handoffs"
+CHECKPOINT_LEVELS = {"L1": "Warning", "L2": "Critical", "L3": "Emergency"}
+
+
+# =============================================================================
+# Type Definitions
+# =============================================================================
+
+
+class GitState(TypedDict, total=False):
+    """Git repository state."""
+
+    branch: str
+    commit_hash: str
+    commit_message: str
+    has_uncommitted: bool
+    staged_files: List[str]
+    modified_files: List[str]
+    untracked_files: List[str]
+
+
+class LinearState(TypedDict, total=False):
+    """Linear issue state."""
+
+    identifier: str
+    title: str
+    state: str
+    description: str
+    assignee: Optional[str]
+    url: str
+
+
+class FileProgress(TypedDict, total=False):
+    """File modification progress."""
+
+    path: str
+    lines_changed: int
+    status: str  # added, modified, deleted
+
+
+class HandoffDocument(TypedDict):
+    """Complete handoff document structure."""
+
+    # Metadata (YAML frontmatter)
+    session_date: str
+    session_time: str
+    branch: str
+    linear_issues: str
+    checkpoint_trigger: str
+    context_at_checkpoint: int
+
+    # Content sections
+    title: str
+    summary: str
+    completed_items: List[str]
+    in_progress_items: List[str]
+    next_steps: List[str]
+    git_state: GitState
+    linear_state: Optional[LinearState]
+    files_touched: List[FileProgress]
+    critical_context: List[str]
+
+
+# =============================================================================
+# HandoffGenerator Class
+# =============================================================================
+
+
+@dataclass
+class HandoffGenerator:
+    """Generate handoff documents for CCS checkpoints (ANV-195)."""
+
+    project_path: str = field(default_factory=os.getcwd)
+    handoff_dir: str = DEFAULT_HANDOFF_DIR
+
+    def __post_init__(self):
+        """Ensure project path is absolute."""
+        self.project_path = os.path.abspath(self.project_path)
+
+    # -------------------------------------------------------------------------
+    # Git State Collection
+    # -------------------------------------------------------------------------
+
+    def get_git_state(self) -> GitState:
+        """Collect current git repository state."""
+        state: GitState = {
+            "branch": "",
+            "commit_hash": "",
+            "commit_message": "",
+            "has_uncommitted": False,
+            "staged_files": [],
+            "modified_files": [],
+            "untracked_files": [],
+        }
+
+        try:
+            # Get current branch
+            result = subprocess.run(
+                ["git", "branch", "--show-current"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                state["branch"] = result.stdout.strip()
+
+            # Get commit hash and message
+            result = subprocess.run(
+                ["git", "log", "-1", "--format=%H|%s"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=5,
+            )
+            if result.returncode == 0 and "|" in result.stdout:
+                parts = result.stdout.strip().split("|", 1)
+                state["commit_hash"] = parts[0][:8]  # Short hash
+                state["commit_message"] = parts[1] if len(parts) > 1 else ""
+
+            # Get staged files
+            result = subprocess.run(
+                ["git", "diff", "--name-only", "--cached"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=5,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                state["staged_files"] = result.stdout.strip().split("\n")
+
+            # Get modified files (not staged)
+            result = subprocess.run(
+                ["git", "diff", "--name-only"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=5,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                state["modified_files"] = result.stdout.strip().split("\n")
+
+            # Get untracked files
+            result = subprocess.run(
+                ["git", "ls-files", "--others", "--exclude-standard"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=5,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                state["untracked_files"] = result.stdout.strip().split("\n")
+
+            # Determine if there are uncommitted changes
+            state["has_uncommitted"] = bool(
+                state["staged_files"]
+                or state["modified_files"]
+                or state["untracked_files"]
+            )
+
+        except (subprocess.TimeoutExpired, subprocess.SubprocessError):
+            pass  # Return partial state on error
+
+        return state
+
+    def get_file_progress(self) -> List[FileProgress]:
+        """Get detailed file modification info."""
+        files: List[FileProgress] = []
+
+        try:
+            # Get diff stats for staged and unstaged
+            result = subprocess.run(
+                ["git", "diff", "--stat", "--numstat", "HEAD"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=10,
+            )
+            if result.returncode == 0:
+                for line in result.stdout.strip().split("\n"):
+                    if not line or "\t" not in line:
+                        continue
+                    parts = line.split("\t")
+                    if len(parts) >= 3:
+                        added = int(parts[0]) if parts[0].isdigit() else 0
+                        deleted = int(parts[1]) if parts[1].isdigit() else 0
+                        filepath = parts[2]
+                        files.append(
+                            {
+                                "path": filepath,
+                                "lines_changed": added + deleted,
+                                "status": "modified",
+                            }
+                        )
+
+        except (subprocess.TimeoutExpired, subprocess.SubprocessError):
+            pass
+
+        return files
+
+    # -------------------------------------------------------------------------
+    # Linear State Collection
+    # -------------------------------------------------------------------------
+
+    def get_linear_state(self, issue_id: str) -> Optional[LinearState]:
+        """Fetch Linear issue state using the linear.py script."""
+        if not issue_id:
+            return None
+
+        try:
+            # Use the linear.py script from the linear-skill
+            script_path = os.path.expanduser(
+                "~/.claude/skills/linear-skill/scripts/linear.py"
+            )
+
+            if not os.path.exists(script_path):
+                return None
+
+            result = subprocess.run(
+                ["python3", script_path, "get-issue", "--id", issue_id],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+
+            if result.returncode == 0:
+                data = json.loads(result.stdout)
+                assignee_data = data.get("assignee")
+                assignee_name = assignee_data.get("name") if assignee_data else None
+                state_data = data.get("state")
+                state_name = state_data.get("name", "Unknown") if state_data else "Unknown"
+                description = data.get("description") or ""
+
+                return {
+                    "identifier": data.get("identifier", issue_id),
+                    "title": data.get("title", ""),
+                    "state": state_name,
+                    "description": description[:200],  # Truncate
+                    "assignee": assignee_name,
+                    "url": data.get("url", ""),
+                }
+
+        except (subprocess.TimeoutExpired, subprocess.SubprocessError, json.JSONDecodeError):
+            pass
+
+        return {"identifier": issue_id, "title": "", "state": "Unknown"}
+
+    # -------------------------------------------------------------------------
+    # Document Generation
+    # -------------------------------------------------------------------------
+
+    def generate(
+        self,
+        trigger_level: str = "L2",
+        context_percent: int = 0,
+        linear_issue: str = "",
+        summary: str = "",
+        completed_items: Optional[List[str]] = None,
+        in_progress_items: Optional[List[str]] = None,
+        next_steps: Optional[List[str]] = None,
+        critical_context: Optional[List[str]] = None,
+    ) -> HandoffDocument:
+        """Generate a complete handoff document.
+
+        Args:
+            trigger_level: CCS level that triggered checkpoint (L1, L2, L3)
+            context_percent: Context percentage at checkpoint
+            linear_issue: Linear issue ID (e.g., "ANV-195")
+            summary: Brief summary of work done
+            completed_items: List of completed tasks
+            in_progress_items: List of in-progress tasks
+            next_steps: Recommended next actions
+            critical_context: Important context for resumption
+
+        Returns:
+            HandoffDocument with all sections populated
+        """
+        now = datetime.now(timezone.utc)
+        git_state = self.get_git_state()
+        linear_state = self.get_linear_state(linear_issue) if linear_issue else None
+        files_touched = self.get_file_progress()
+
+        # Generate title
+        level_desc = CHECKPOINT_LEVELS.get(trigger_level, "Checkpoint")
+        if linear_state and linear_state.get("title"):
+            title = f"Session Handoff: {linear_state['identifier']} - {linear_state['title']}"
+        elif summary:
+            title = f"Session Handoff: {summary[:50]}"
+        else:
+            title = f"Session Handoff: {level_desc} Checkpoint"
+
+        # Generate default next steps if not provided
+        if not next_steps:
+            next_steps = self._generate_default_next_steps(
+                trigger_level, git_state, linear_issue
+            )
+
+        return {
+            # Metadata
+            "session_date": now.strftime("%Y-%m-%d"),
+            "session_time": now.strftime("%H:%M"),
+            "branch": git_state.get("branch", "unknown"),
+            "linear_issues": linear_issue,
+            "checkpoint_trigger": f"{trigger_level} (context at {context_percent}%)",
+            "context_at_checkpoint": context_percent,
+            # Content
+            "title": title,
+            "summary": summary,
+            "completed_items": completed_items or [],
+            "in_progress_items": in_progress_items or [],
+            "next_steps": next_steps,
+            "git_state": git_state,
+            "linear_state": linear_state,
+            "files_touched": files_touched,
+            "critical_context": critical_context or [],
+        }
+
+    def _generate_default_next_steps(
+        self, trigger_level: str, git_state: GitState, linear_issue: str
+    ) -> List[str]:
+        """Generate default next steps based on state."""
+        steps = []
+
+        # Context-level specific guidance
+        if trigger_level == "L3":
+            steps.append("URGENT: Review handoff immediately - context was near limit")
+        elif trigger_level == "L2":
+            steps.append("Review handoff and continue from in-progress items")
+        else:
+            steps.append("Continue from where the session left off")
+
+        # Git-based suggestions
+        if git_state.get("has_uncommitted"):
+            uncommitted_count = (
+                len(git_state.get("staged_files", []))
+                + len(git_state.get("modified_files", []))
+            )
+            steps.append(
+                f"Review {uncommitted_count} uncommitted file(s) before continuing"
+            )
+
+        # Linear-based suggestions
+        if linear_issue:
+            steps.append(f"Check Linear issue {linear_issue} for latest status")
+
+        return steps
+
+    # -------------------------------------------------------------------------
+    # Markdown Rendering
+    # -------------------------------------------------------------------------
+
+    def render_markdown(self, doc: HandoffDocument) -> str:
+        """Render handoff document as markdown."""
+        lines = []
+
+        # YAML frontmatter
+        lines.append("---")
+        lines.append(f"session_date: {doc['session_date']}")
+        lines.append(f"session_time: {doc['session_time']}")
+        lines.append(f"branch: {doc['branch']}")
+        if doc["linear_issues"]:
+            lines.append(f"linear_issues: {doc['linear_issues']}")
+        lines.append(f"checkpoint_trigger: {doc['checkpoint_trigger']}")
+        lines.append(f"context_at_checkpoint: {doc['context_at_checkpoint']}%")
+        lines.append("---")
+        lines.append("")
+
+        # Title
+        lines.append(f"# {doc['title']}")
+        lines.append("")
+
+        # Summary
+        if doc["summary"]:
+            lines.append("## Session Summary")
+            lines.append(doc["summary"])
+            lines.append("")
+
+        # Checkpoint Reason
+        lines.append("## Checkpoint Reason")
+        lines.append(f"Context checkpoint triggered at {doc['checkpoint_trigger']}")
+        lines.append("")
+
+        # Completed items
+        if doc["completed_items"]:
+            lines.append("## Completed This Session")
+            for item in doc["completed_items"]:
+                lines.append(f"- [x] {item}")
+            lines.append("")
+
+        # In progress items
+        if doc["in_progress_items"]:
+            lines.append("## In Progress (Not Complete)")
+            for item in doc["in_progress_items"]:
+                lines.append(f"- [ ] {item}")
+            lines.append("")
+
+        # Git State
+        git = doc["git_state"]
+        lines.append("## Git State")
+        lines.append(f"- **Branch**: {git.get('branch', 'unknown')}")
+        lines.append(f"- **Last commit**: {git.get('commit_hash', '')} {git.get('commit_message', '')}")
+        lines.append(f"- **Uncommitted changes**: {'Yes' if git.get('has_uncommitted') else 'No'}")
+
+        if git.get("staged_files"):
+            lines.append(f"- **Staged files**: {', '.join(git['staged_files'][:5])}")
+            if len(git["staged_files"]) > 5:
+                lines.append(f"  - ...and {len(git['staged_files']) - 5} more")
+
+        if git.get("modified_files"):
+            lines.append(f"- **Modified files**: {', '.join(git['modified_files'][:5])}")
+            if len(git["modified_files"]) > 5:
+                lines.append(f"  - ...and {len(git['modified_files']) - 5} more")
+        lines.append("")
+
+        # Linear State
+        if doc["linear_state"]:
+            linear = doc["linear_state"]
+            lines.append("## Linear Issue State")
+            lines.append(f"- **Issue**: {linear.get('identifier', 'Unknown')}")
+            lines.append(f"- **Title**: {linear.get('title', 'Unknown')}")
+            lines.append(f"- **Status**: {linear.get('state', 'Unknown')}")
+            if linear.get("url"):
+                lines.append(f"- **URL**: {linear['url']}")
+            lines.append("")
+
+        # Files touched with progress
+        if doc["files_touched"]:
+            lines.append("## Files Modified")
+            for f in doc["files_touched"][:10]:
+                lines.append(f"- `{f['path']}` ({f['lines_changed']} lines)")
+            if len(doc["files_touched"]) > 10:
+                lines.append(f"- ...and {len(doc['files_touched']) - 10} more files")
+            lines.append("")
+
+        # Critical context
+        if doc["critical_context"]:
+            lines.append("## Critical Context for Next Session")
+            for ctx in doc["critical_context"]:
+                lines.append(f"- {ctx}")
+            lines.append("")
+
+        # Next steps
+        if doc["next_steps"]:
+            lines.append("## Recommended Next Steps")
+            for i, step in enumerate(doc["next_steps"], 1):
+                lines.append(f"{i}. {step}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    # -------------------------------------------------------------------------
+    # File Operations
+    # -------------------------------------------------------------------------
+
+    def save(self, doc: HandoffDocument, filename: Optional[str] = None) -> str:
+        """Save handoff document to file.
+
+        Args:
+            doc: HandoffDocument to save
+            filename: Optional filename (auto-generated if not provided)
+
+        Returns:
+            Path to saved file
+        """
+        # Ensure handoff directory exists
+        handoff_path = os.path.join(self.project_path, self.handoff_dir)
+        os.makedirs(handoff_path, exist_ok=True)
+
+        # Generate filename if not provided
+        if not filename:
+            filename = f"{doc['session_date']}-{doc['session_time'].replace(':', '')}.md"
+
+        filepath = os.path.join(handoff_path, filename)
+
+        # Render and save
+        content = self.render_markdown(doc)
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        return filepath
+
+    def create_wip_commit(
+        self,
+        trigger_level: str = "L2",
+        context_percent: int = 0,
+        linear_issue: str = "",
+    ) -> tuple[bool, str]:
+        """Create a WIP commit at checkpoint if there are uncommitted changes.
+
+        Args:
+            trigger_level: CCS level that triggered checkpoint (L1, L2, L3)
+            context_percent: Context percentage at checkpoint
+            linear_issue: Linear issue ID (e.g., "ANV-195")
+
+        Returns:
+            Tuple of (success, message) where message is commit hash or error
+        """
+        try:
+            # Check if there are uncommitted changes
+            result = subprocess.run(
+                ["git", "status", "--porcelain"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=5,
+            )
+            if result.returncode != 0:
+                return False, "Failed to check git status"
+
+            if not result.stdout.strip():
+                return False, "No uncommitted changes to commit"
+
+            # Stage all changes
+            result = subprocess.run(
+                ["git", "add", "-A"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=10,
+            )
+            if result.returncode != 0:
+                return False, f"Failed to stage changes: {result.stderr}"
+
+            # Build commit message
+            issue_part = f"{linear_issue} - " if linear_issue else ""
+            commit_msg = f"[WIP] {issue_part}checkpoint ({trigger_level} at {context_percent}%)"
+
+            # Create the commit
+            result = subprocess.run(
+                ["git", "commit", "-m", commit_msg],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=30,
+            )
+            if result.returncode != 0:
+                return False, f"Failed to create commit: {result.stderr}"
+
+            # Get the commit hash
+            result = subprocess.run(
+                ["git", "rev-parse", "--short", "HEAD"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_path,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                commit_hash = result.stdout.strip()
+                return True, commit_hash
+
+            return True, "Commit created (hash unknown)"
+
+        except subprocess.TimeoutExpired:
+            return False, "Git command timed out"
+        except subprocess.SubprocessError as e:
+            return False, f"Git error: {e}"
+
+    def create_checkpoint_comment(
+        self,
+        linear_issue: str,
+        trigger_level: str = "L2",
+        context_percent: int = 0,
+        handoff_file: str = "",
+        completed_items: Optional[List[str]] = None,
+        in_progress_items: Optional[List[str]] = None,
+    ) -> tuple[bool, str]:
+        """Create a checkpoint comment on a Linear issue.
+
+        Args:
+            linear_issue: Linear issue ID (e.g., "ANV-197")
+            trigger_level: CCS level that triggered checkpoint (L1, L2, L3)
+            context_percent: Context percentage at checkpoint
+            handoff_file: Path to handoff document (relative to project)
+            completed_items: List of completed tasks
+            in_progress_items: List of in-progress tasks
+
+        Returns:
+            Tuple of (success, message) where message is comment ID or error
+        """
+        if not linear_issue:
+            return False, "No Linear issue specified"
+
+        # Build comment body
+        level_desc = CHECKPOINT_LEVELS.get(trigger_level, "Checkpoint")
+        lines = [
+            f"## 🔶 Context Checkpoint ({trigger_level})",
+            "",
+            f"**Trigger**: {level_desc} at {context_percent}% context usage",
+            f"**Timestamp**: {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}",
+        ]
+
+        # Add handoff file reference
+        if handoff_file:
+            lines.append(f"**Handoff**: `{handoff_file}`")
+
+        # Add git state summary
+        git_state = self.get_git_state()
+        if git_state.get("branch"):
+            lines.append(f"**Branch**: `{git_state['branch']}`")
+        if git_state.get("commit_hash"):
+            lines.append(
+                f"**Last Commit**: `{git_state['commit_hash']}` "
+                f"{git_state.get('commit_message', '')}"
+            )
+
+        # Add progress summary
+        if completed_items:
+            lines.append("")
+            lines.append("### Completed")
+            for item in completed_items[:5]:  # Limit to 5 items
+                lines.append(f"- [x] {item}")
+            if len(completed_items) > 5:
+                lines.append(f"- ...and {len(completed_items) - 5} more")
+
+        if in_progress_items:
+            lines.append("")
+            lines.append("### In Progress")
+            for item in in_progress_items[:5]:  # Limit to 5 items
+                lines.append(f"- [ ] {item}")
+            if len(in_progress_items) > 5:
+                lines.append(f"- ...and {len(in_progress_items) - 5} more")
+
+        # Add resume instructions
+        lines.extend(
+            [
+                "",
+                "---",
+                "*Session checkpointed due to context limits. "
+                "Resume with handoff document.*",
+            ]
+        )
+
+        comment_body = "\n".join(lines)
+
+        # Use linear.py script to create comment
+        try:
+            script_path = os.path.expanduser(
+                "~/.claude/skills/linear-skill/scripts/linear.py"
+            )
+
+            if not os.path.exists(script_path):
+                return False, "Linear skill script not found"
+
+            # Create comment via Linear API
+            result = subprocess.run(
+                [
+                    "python3",
+                    script_path,
+                    "create-comment",
+                    "--issue",
+                    linear_issue,
+                    "--body",
+                    comment_body,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+
+            if result.returncode == 0:
+                return True, f"Comment created on {linear_issue}"
+            else:
+                return False, f"Failed to create comment: {result.stderr}"
+
+        except subprocess.TimeoutExpired:
+            return False, "Linear API timed out"
+        except subprocess.SubprocessError as e:
+            return False, f"Linear API error: {e}"
+
+
+# =============================================================================
+# CLI Interface
+# =============================================================================
+
+
+def main():
+    """CLI entry point for testing."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Generate CCS handoff document")
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # Handoff command (default behavior)
+    handoff_parser = subparsers.add_parser("handoff", help="Generate handoff document")
+    handoff_parser.add_argument("--level", default="L2", help="Checkpoint level (L1, L2, L3)")
+    handoff_parser.add_argument("--percent", type=int, default=85, help="Context percentage")
+    handoff_parser.add_argument("--issue", default="", help="Linear issue ID")
+    handoff_parser.add_argument("--summary", default="", help="Session summary")
+    handoff_parser.add_argument("--save", action="store_true", help="Save to file")
+    handoff_parser.add_argument("--project", default=".", help="Project path")
+
+    # WIP commit command
+    wip_parser = subparsers.add_parser("wip", help="Create WIP checkpoint commit")
+    wip_parser.add_argument("--level", default="L2", help="Checkpoint level (L1, L2, L3)")
+    wip_parser.add_argument("--percent", type=int, default=85, help="Context percentage")
+    wip_parser.add_argument("--issue", default="", help="Linear issue ID")
+    wip_parser.add_argument("--project", default=".", help="Project path")
+
+    # Legacy support: if no command, treat as handoff
+    parser.add_argument("--level", default="L2", help="Checkpoint level (L1, L2, L3)")
+    parser.add_argument("--percent", type=int, default=85, help="Context percentage")
+    parser.add_argument("--issue", default="", help="Linear issue ID")
+    parser.add_argument("--summary", default="", help="Session summary")
+    parser.add_argument("--save", action="store_true", help="Save to file")
+    parser.add_argument("--project", default=".", help="Project path")
+
+    args = parser.parse_args()
+
+    generator = HandoffGenerator(project_path=args.project)
+
+    if args.command == "wip":
+        success, message = generator.create_wip_commit(
+            trigger_level=args.level,
+            context_percent=args.percent,
+            linear_issue=args.issue,
+        )
+        if success:
+            print(f"WIP commit created: {message}")
+        else:
+            print(f"No commit created: {message}")
+            exit(1)
+    else:
+        # Default: generate handoff document
+        doc = generator.generate(
+            trigger_level=args.level,
+            context_percent=args.percent,
+            linear_issue=args.issue,
+            summary=args.summary,
+        )
+
+        if args.save:
+            filepath = generator.save(doc)
+            print(f"Saved to: {filepath}")
+        else:
+            print(generator.render_markdown(doc))
+
+
+if __name__ == "__main__":
+    main()