aiwcli 0.10.3 → 0.11.1

package/dist/templates/_shared/lib/handoff/document_generator.py

@@ -1,278 +0,0 @@
-"""Handoff document generator for context-aware session management.
-
-Creates structured handoff documents when a session needs to transfer
-work to a new session (typically due to context window limits).
-
-Handoff documents capture:
-- Links to active plan and context folder
-- Current task state from events.jsonl
-- Work in progress summary
-- Next steps for continuation
-"""
-import json
-import uuid
-from dataclasses import dataclass, field
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-from ..base.atomic_write import atomic_write
-from ..base.constants import get_context_handoffs_dir, get_context_dir
-from ..base.logger import log_info, log_error
-from ..base.utils import now_iso
-from ..context.context_store import get_context as _get_context_state, save_state as _save_state
-from ..context.task_tracker import get_tasks
-from ..templates.formatters import render_task_list, format_continuation_header, format_reason
-
-
-@dataclass
-class HandoffDocument:
-    """Structured handoff document content."""
-    context_id: str
-    context_summary: str
-    session_id: str
-    reason: str  # e.g., "low_context", "user_requested", "error_recovery"
-    created_at: str
-
-    # Links
-    plan_path: Optional[str] = None
-    context_folder: str = ""
-    events_log_path: str = ""
-
-    # Task state
-    active_tasks: List[Dict[str, Any]] = field(default_factory=list)
-    completed_tasks_this_session: List[Dict[str, Any]] = field(default_factory=list)
-
-    # Context summary
-    work_summary: str = ""
-    next_steps: List[str] = field(default_factory=list)
-    important_notes: List[str] = field(default_factory=list)
-
-    # File path (set after saving)
-    file_path: Optional[str] = None
-
-
-def generate_handoff_document(
-    context_id: str,
-    reason: str = "low_context",
-    work_summary: str = "",
-    next_steps: Optional[List[str]] = None,
-    important_notes: Optional[List[str]] = None,
-    completed_this_session: Optional[List[str]] = None,
-    project_root: Path = None
-) -> Optional[HandoffDocument]:
-    """
-    Generate and save a handoff document for a context.
-
-    This creates a markdown document capturing current work state,
-    saves it to the context's handoffs folder, and records the event.
-
-    Args:
-        context_id: Context identifier
-        reason: Why handoff is happening (low_context, user_requested, etc.)
-        work_summary: Summary of current work in progress
-        next_steps: List of next steps for continuation
-        important_notes: Important decisions or context to preserve
-        completed_this_session: List of task subjects completed this session
-        project_root: Project root directory
-
-    Returns:
-        HandoffDocument with file_path set, or None on failure
-    """
-    context = _get_context_state(context_id, project_root)
-    if not context:
-        log_error("handoff", f"Context '{context_id}' not found")
-        return None
-
-    # Generate session ID
-    session_id = str(uuid.uuid4())[:8]
-
-    # Get pending tasks from state.json
-    all_tasks = get_tasks(context_id, project_root)
-    pending_tasks = [t for t in all_tasks if t.get("status") in ("pending", "in_progress", "blocked")]
-
-    # Build document
-    now = now_iso()
-    context_dir = get_context_dir(context_id, project_root)
-
-    doc = HandoffDocument(
-        context_id=context_id,
-        context_summary=context.summary,
-        session_id=session_id,
-        reason=reason,
-        created_at=now,
-        plan_path=context.plan_path,
-        context_folder=str(context_dir),
-        events_log_path=str(context_dir / "state.json"),
-        active_tasks=pending_tasks,
-        completed_tasks_this_session=[
-            {"subject": s} for s in (completed_this_session or [])
-        ],
-        work_summary=work_summary,
-        next_steps=next_steps or [],
-        important_notes=important_notes or [],
-    )
-
-    # Compute file path BEFORE rendering markdown
-    handoffs_dir = get_context_handoffs_dir(context_id, project_root)
-    handoffs_dir.mkdir(parents=True, exist_ok=True)
-
-    # Filename: YYYY-MM-DD-session-{session_id}.md
-    date_str = datetime.now().strftime("%Y-%m-%d")
-    filename = f"{date_str}-session-{session_id}.md"
-    file_path = handoffs_dir / filename
-
-    # Set file_path on doc BEFORE rendering markdown
-    doc.file_path = str(file_path)
-
-    # Generate markdown content
-    markdown = _render_handoff_markdown(doc)
-
-    # Save to handoffs folder
-
-    success, error = atomic_write(file_path, markdown)
-    if not success:
-        log_error("handoff", f"Failed to write handoff document: {error}")
-        return None
-
-    log_info("handoff", f"Created handoff document: {file_path}")
-    return doc
-
-
-def _render_handoff_markdown(doc: HandoffDocument) -> str:
-    """Render handoff document as markdown."""
-    lines = [
-        format_continuation_header("handoff", doc.context_id),
-        "",
-        f"**Created**: {doc.created_at}",
-        f"**Context ID**: {doc.context_id}",
-        f"**Session ID**: {doc.session_id}",
-        f"**Reason**: {format_reason(doc.reason)}",
-        "",
-        "## Links",
-        "",
-    ]
-
-    # Plan link
-    if doc.plan_path:
-        lines.append(f"- **Plan**: [{Path(doc.plan_path).name}]({doc.plan_path})")
-
-    lines.extend([
-        f"- **Context Folder**: `{doc.context_folder}`",
-        f"- **Events Log**: `{doc.events_log_path}`",
-        "",
-        "## Current State",
-        "",
-    ])
-
-    # Active tasks
-    lines.append(render_task_list(doc.active_tasks, header="Active Tasks", show_description=True).rstrip())
-    lines.append("")
-
-    # Completed this session
-    if doc.completed_tasks_this_session:
-        lines.append(render_task_list(
-            doc.completed_tasks_this_session,
-            header="Completed This Session",
-            show_description=False
-        ).rstrip())
-        lines.append("")
-
-    # Work summary
-    if doc.work_summary:
-        lines.extend([
-            "## Context Summary",
-            "",
-            doc.work_summary,
-            "",
-        ])
-
-    # Next steps
-    if doc.next_steps:
-        lines.extend([
-            "## Next Steps",
-            "",
-        ])
-        for i, step in enumerate(doc.next_steps, 1):
-            lines.append(f"{i}. {step}")
-        lines.append("")
-
-    # Important notes
-    if doc.important_notes:
-        lines.extend([
-            "## Important Notes",
-            "",
-        ])
-        for note in doc.important_notes:
-            lines.append(f"- {note}")
-        lines.append("")
-
-    # Continuation prompt
-    lines.extend([
-        "---",
-        "",
-        "**Continuation Prompt**:",
-        "```",
-        f'Continue working on context "{doc.context_id}".',
-        "",
-        f"Handoff document: {doc.file_path or 'See above'}",
-        "",
-        "Read the handoff document, restore tasks with TaskCreate, and continue implementation.",
-        "```",
-    ])
-
-    return "\n".join(lines)
-
-
-def get_handoff_continuation_prompt(doc: HandoffDocument) -> str:
-    """
-    Generate the prompt to paste into new session for continuation.
-
-    Args:
-        doc: HandoffDocument with file_path set
-
-    Returns:
-        Prompt string for continuing work
-    """
-    return f"""Continue working on context "{doc.context_id}".
-
-Handoff document: {doc.file_path}
-
-Read the handoff document, restore tasks with TaskCreate, and continue implementation."""
-
-
-def get_low_context_warning(context_remaining_percent: int, context_id: str) -> str:
-    """
-    Generate system reminder for low context warning.
-
-    This is injected by the UserPromptSubmit hook when context is low.
-
-    Args:
-        context_remaining_percent: Percentage of context remaining
-        context_id: Current context identifier
-
-    Returns:
-        System reminder markdown
-    """
-    return f"""<system-reminder>
-## LOW CONTEXT WARNING ({context_remaining_percent}% remaining)
-
-Your context window is running low. Please:
-
-1. **Finish current task** if 1-2 steps away, OR save current progress
-2. **Create handoff document** by calling:
-   ```python
-   from _shared.lib.handoff import generate_handoff_document
-   doc = generate_handoff_document(
-       context_id="{context_id}",
-       reason="low_context",
-       work_summary="<describe current work>",
-       next_steps=["<step 1>", "<step 2>"],
-       important_notes=["<key decision 1>"]
-   )
-   ```
-3. **Ask permission** to clear and paste continuation prompt
-
-After creating handoff, ask the user:
-"Context is low. I've created a handoff document. May I clear and continue in a new session?"
-</system-reminder>"""

package/dist/templates/_shared/lib/templates/README.md

@@ -1,206 +0,0 @@
-# Shared Templates Module
-
-Centralized templates and formatters for consistent context management output across context formatting, handoff, and hooks.
-
-## Purpose
-
-This module eliminates duplication by providing a single source of truth for:
-- Mode displays (planning, implementing, etc.)
-- Status icons (pending, in_progress, completed)
-- Task rendering formatters
-- Context continuation headers
-- Plan context templates
-- Handoff reason formatting
-
-## Modules
-
-### `formatters.py`
-
-Core formatters and constants for context management output.
-
-#### Constants
-
-```python
-MODE_DISPLAY_MAP = {
-    "planning": "[Planning]",
-    "pending_implementation": "[Plan Ready]",
-    "implementing": "[Implementing]",
-    "none": "",
-}
-
-STATUS_ICON_MAP = {
-    "pending": "⬜",
-    "in_progress": "🔄",
-    "blocked": "🚫",
-    "completed": "✅",
-}
-
-REASON_MAP = {
-    "low_context": "Context window running low",
-    "user_requested": "User requested handoff",
-    "error_recovery": "Error recovery",
-    "session_end": "Session ending",
-}
-```
-
-#### Functions
-
-**`get_mode_display(mode: str) -> str`**
-
-Get display string for in-flight mode.
-
-```python
->>> get_mode_display("planning")
-"[Planning]"
->>> get_mode_display("none")
-""
-```
-
-**`get_status_icon(status: str) -> str`**
-
-Get emoji icon for task status.
-
-```python
->>> get_status_icon("pending")
-"⬜"
->>> get_status_icon("completed")
-"✅"
-```
-
-**`render_task_item(task, show_description=True, max_description_length=100) -> str`**
-
-Render single task with status icon and subject.
-
-```python
-task = {"status": "pending", "subject": "Fix bug", "description": "Details"}
->>> render_task_item(task)
-"- ⬜ [PENDING] Fix bug\n  - Details"
-```
-
-**`render_task_list(tasks, header="Active Tasks", show_description=True) -> str`**
-
-Render list of tasks with header.
-
-```python
-tasks = [{"status": "pending", "subject": "Task 1", "description": "Details"}]
->>> render_task_list(tasks, header="My Tasks")
-"### My Tasks\n\n- ⬜ [PENDING] Task 1\n  - Details\n"
-```
-
-**`format_continuation_header(header_type: str, context_id: str) -> str`**
-
-Format continuation header for various scenarios.
-
-```python
->>> format_continuation_header("resuming", "my-context")
-"## RESUMING FROM HANDOFF: my-context"
-```
-
-Types: `context`, `resuming`, `implementing`, `handoff`
-
-**`format_reason(reason: str) -> str`**
-
-Format handoff reason code as human-readable string.
-
-```python
->>> format_reason("low_context")
-"Context window running low"
-```
-
-### `plan_context.py`
-
-Plan context templates for the add_plan_context hook.
-
-**`get_evaluation_context_reminder() -> str`**
-
-Returns the evaluation context reminder template that prompts Claude to add evaluation context to plans.
-
-## Usage
-
-### In Discovery Functions
-
-```python
-from ..templates.formatters import (
-    get_mode_display,
-    get_status_icon,
-    format_continuation_header,
-)
-
-# Display mode status
-mode_display = get_mode_display(context.in_flight.mode)
-status = f"Context: {context.id} {mode_display}"
-
-# Render task with icon
-icon = get_status_icon(task.status)
-output = f"{icon} {task.subject}"
-
-# Create continuation header
-header = format_continuation_header("implementing", context.id)
-```
-
-### In Document Generator
-
-```python
-from ..templates.formatters import render_task_list, format_reason
-
-# Render task list section
-tasks_md = render_task_list(doc.active_tasks, header="Active Tasks")
-lines.append(tasks_md)
-
-# Format handoff reason
-reason_text = format_reason(doc.reason)
-```
-
-### In Hooks
-
-```python
-from templates.plan_context import get_evaluation_context_reminder
-
-# Get plan context template
-CONTEXT_REMINDER = get_evaluation_context_reminder()
-```
-
-## Dependent Files
-
-Files that import from this module:
-
-- `.aiwcli/_shared/lib/context/context_formatter.py`
-  - Uses: `get_mode_display`, `get_status_icon`, `format_continuation_header`
-
-- `.aiwcli/_shared/lib/handoff/document_generator.py`
-  - Uses: `render_task_list`, `format_continuation_header`, `format_reason`
-
-- `.aiwcli/_cc-native/hooks/add_plan_context.py`
-  - Uses: `get_evaluation_context_reminder`
-
-## Design Principles
-
-1. **Single Source of Truth**: Each constant/function exists in one location only
-2. **Backward Compatible**: All functions preserve existing output formats
-3. **Type Flexible**: Functions handle both Task objects and dicts
-4. **Fail-Safe**: Use `.get()` with defaults for missing keys
-
-## Testing
-
-```bash
-# Test imports
-cd .aiwcli
-python -c "from _shared.lib.templates.formatters import get_mode_display; \
-           assert get_mode_display('planning') == '[Planning]'"
-
-# Test task rendering
-python -c "from _shared.lib.templates.formatters import get_status_icon; \
-           assert get_status_icon('pending') != ''"
-```
-
-## Synchronization
-
-Changes to this module must be synchronized to the template directory:
-
-```bash
-# After editing
-cp .aiwcli/_shared/lib/templates/*.py \
-   packages/cli/src/templates/_shared/lib/templates/
-```
-
-See `CLAUDE.md` for template synchronization requirements.

package/dist/templates/_shared/lib/templates/__init__.py

@@ -1,36 +0,0 @@
-"""Shared templates and formatters for context management output.
-
-This module provides centralized templates for:
-- Mode displays (planning, implementing, etc.)
-- Status icons (pending, in_progress, completed)
-- Task rendering
-- Context continuation headers
-
-Used by context_formatter.py, document_generator.py, and hooks.
-"""
-
-from .formatters import (
-    MODE_DISPLAY_MAP,
-    STATUS_ICON_MAP,
-    REASON_MAP,
-    get_mode_display,
-    get_status_icon,
-    render_task_item,
-    render_task_list,
-    format_continuation_header,
-    format_reason,
-)
-from .plan_context import get_evaluation_context_reminder
-
-__all__ = [
-    "MODE_DISPLAY_MAP",
-    "STATUS_ICON_MAP",
-    "REASON_MAP",
-    "get_mode_display",
-    "get_status_icon",
-    "render_task_item",
-    "render_task_list",
-    "format_continuation_header",
-    "format_reason",
-    "get_evaluation_context_reminder",
-]

package/dist/templates/_shared/lib/templates/formatters.py

@@ -1,146 +0,0 @@
-"""Formatters for context management templates.
-
-Provides constants and helper functions for consistent formatting
-across discovery, handoff, and hook output.
-"""
-
-from typing import Any, Dict, List, Optional, Union
-
-# Mode display mapping for in-flight work states
-MODE_DISPLAY_MAP = {
-    "planning": "[Planning]",
-    "pending_implementation": "[Plan Ready]",
-    "implementing": "[Implementing]",
-    "none": "",
-}
-
-# Status icon mapping for task states
-STATUS_ICON_MAP = {
-    "pending": "⬜",
-    "in_progress": "🔄",
-    "blocked": "🚫",
-    "completed": "✅",
-}
-
-
-def get_mode_display(mode: str) -> str:
-    """Get display string for in-flight mode.
-
-    Args:
-        mode: In-flight mode string (planning, implementing, etc.)
-
-    Returns:
-        Display string like "[Planning]" or empty string for "none"
-    """
-    return MODE_DISPLAY_MAP.get(mode, "")
-
-
-def get_status_icon(status: str) -> str:
-    """Get emoji icon for task status.
-
-    Args:
-        status: Task status (pending, in_progress, blocked, completed)
-
-    Returns:
-        Emoji icon like "⬜" or "✅"
-    """
-    return STATUS_ICON_MAP.get(status, "⬜")
-
-
-def render_task_item(
-    task: Union["Task", Dict[str, Any]],
-    show_description: bool = True,
-    max_description_length: int = 100
-) -> str:
-    """Render single task with status icon and subject.
-
-    Args:
-        task: Task object or dict with status, subject, description
-        show_description: Whether to include description
-        max_description_length: Maximum length for description before truncating
-
-    Returns:
-        Formatted string: "- {icon} [{STATUS}] {subject}"
-    """
-    # Handle both Task objects and dicts
-    status = task.get("status") if isinstance(task, dict) else task.status
-    subject = task.get("subject") if isinstance(task, dict) else task.subject
-    description = task.get("description") if isinstance(task, dict) else task.description
-
-    icon = get_status_icon(status)
-    status_text = f"[{status.upper()}]"
-    line = f"- {icon} {status_text} {subject}"
-
-    if show_description and description:
-        truncated = description[:max_description_length]
-        if len(description) > max_description_length:
-            truncated += "..."
-        return f"{line}\n  - {truncated}"
-    return line
-
-
-def render_task_list(
-    tasks: List[Union["Task", Dict[str, Any]]],
-    header: Optional[str] = "Active Tasks",
-    show_description: bool = True
-) -> str:
-    """Render list of tasks with header.
-
-    Args:
-        tasks: List of Task objects or dicts
-        header: Section header text
-        show_description: Whether to show task descriptions
-
-    Returns:
-        Formatted markdown section with task list
-    """
-    lines = [f"### {header}", ""]
-
-    if not tasks:
-        lines.append("No active tasks.")
-    else:
-        for task in tasks:
-            lines.append(render_task_item(task, show_description))
-
-    lines.append("")
-    return "\n".join(lines)
-
-
-def format_continuation_header(header_type: str, context_id: str) -> str:
-    """Format continuation header for various scenarios.
-
-    Args:
-        header_type: Type of continuation (context, resuming, implementing, handoff)
-        context_id: Context identifier
-
-    Returns:
-        Formatted markdown header
-    """
-    headers = {
-        "context": f"## CONTINUING CONTEXT: {context_id}",
-        "resuming": f"## RESUMING FROM HANDOFF: {context_id}",
-        "implementing": f"## CONTINUING IMPLEMENTATION: {context_id}",
-        "handoff": f"# Session Handoff: {context_id}",
-    }
-    return headers.get(header_type, f"## {context_id}")
-
-
-# Handoff reason display mapping
-REASON_MAP = {
-    "low_context": "Context window running low",
-    "user_requested": "User requested handoff",
-    "error_recovery": "Error recovery",
-    "session_end": "Session ending",
-}
-
-
-def format_reason(reason: str) -> str:
-    """Format handoff reason code as human-readable string.
-
-    Args:
-        reason: Reason code (low_context, user_requested, etc.)
-
-    Returns:
-        Human-readable reason string
-    """
-    return REASON_MAP.get(reason, reason)