aiwcli 0.9.0 → 0.9.2

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

@@ -11,7 +11,6 @@ MODE_DISPLAY_MAP = {
     "planning": "[Planning]",
     "pending_implementation": "[Plan Ready]",
     "implementing": "[Implementing]",
-    "handoff_pending": "[Handoff Pending]",
     "none": "",
 }
 

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

@@ -0,0 +1,113 @@
+"""Persona-based question templates for plan clarification.
+
+Uses distinct reasoning lenses to surface hidden constraints and assumptions.
+"""
+
+from dataclasses import dataclass
+from typing import List, Dict
+
+
+@dataclass
+class PersonaQuestion:
+    """A clarifying question from a specific persona lens."""
+
+    persona: str
+    display_name: str
+    question: str
+    purpose: str
+
+
+CLARIFICATION_PERSONAS: Dict[str, List[PersonaQuestion]] = {
+    "problem_validator": [
+        PersonaQuestion(
+            persona="problem_validator",
+            display_name="Questioning the Problem",
+            question="Can you describe the problem you're trying to solve without mentioning the solution?",
+            purpose="Separates problem from solution to check alignment",
+        ),
+        PersonaQuestion(
+            persona="problem_validator",
+            display_name="Challenging the Approach",
+            question="What's the simplest possible way to achieve this outcome that we haven't considered?",
+            purpose="Identifies potential over-engineering",
+        ),
+    ],
+    "assumption_validator": [
+        PersonaQuestion(
+            persona="assumption_validator",
+            display_name="Surfacing Assumptions",
+            question="What must already be true about your users, systems, or constraints for this to succeed?",
+            purpose="Surfaces foundational assumptions that could invalidate the plan",
+        ),
+        PersonaQuestion(
+            persona="assumption_validator",
+            display_name="Hidden Dependencies",
+            question="What are you assuming 'everyone knows' about this problem that might not be documented?",
+            purpose="Uncovers implicit knowledge that needs to be made explicit",
+        ),
+    ],
+    "user_advocate": [
+        PersonaQuestion(
+            persona="user_advocate",
+            display_name="Understanding Users",
+            question="Who specifically will use this, and what problem does it solve for them today?",
+            purpose="Grounds the plan in actual user needs",
+        ),
+        PersonaQuestion(
+            persona="user_advocate",
+            display_name="Impact Assessment",
+            question="If we did nothing, what would happen? Who would be affected?",
+            purpose="Establishes urgency and stakes",
+        ),
+    ],
+    "tradeoff_illuminator": [
+        PersonaQuestion(
+            persona="tradeoff_illuminator",
+            display_name="Revealing Trade-offs",
+            question="What are you willing to sacrifice (scope, time, quality, features) to make this work?",
+            purpose="Forces explicit prioritization",
+        ),
+        PersonaQuestion(
+            persona="tradeoff_illuminator",
+            display_name="Foreclosed Options",
+            question="What becomes harder or impossible to do later if we proceed this way?",
+            purpose="Surfaces opportunity costs and lock-in risks",
+        ),
+    ],
+}
+
+
+def get_all_persona_questions() -> List[PersonaQuestion]:
+    """Get all persona questions as a flat list."""
+    questions = []
+    for persona_qs in CLARIFICATION_PERSONAS.values():
+        questions.extend(persona_qs)
+    return questions
+
+
+def format_questions_for_prompt() -> str:
+    """Format persona questions for injection into Claude prompt."""
+    lines = [
+        "### Persona-Based Clarifying Questions",
+        "",
+        "Ask 5-8 questions from these perspectives using AskUserQuestion:",
+        "",
+    ]
+
+    for persona_qs in CLARIFICATION_PERSONAS.values():
+        for q in persona_qs:
+            lines.append(f"**{q.display_name}**")
+            lines.append(f'- Q: "{q.question}"')
+            lines.append(f"- Purpose: {q.purpose}")
+            lines.append("")
+
+    lines.extend(
+        [
+            "**Guidance:**",
+            "- Select questions most relevant to THIS plan (skip if already answered)",
+            "- Ask one at a time with clear context",
+            "- Use answers to refine the plan before ExitPlanMode",
+        ]
+    )
+
+    return "\n".join(lines)

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

@@ -72,47 +72,33 @@ This context allows reviewers to assess whether your plan addresses the user's n
 def get_questions_offer_template() -> str:
     """Get the clarifying questions offer template.
 
+    Uses persona-based questioning to surface hidden constraints.
+
     Returns:
         Formatted markdown prompt for offering clarifying questions
     """
-    return """
+    from .persona_questions import format_questions_for_prompt
+
+    persona_questions = format_questions_for_prompt()
+
+    return f"""
 ## First Plan Write - Optional Clarifying Questions
 
 Your initial plan has been saved. Before finalizing, ask the user if they'd like to answer clarifying questions to refine it.
 
-**Use AskUserQuestion now with this question:**
+**Use AskUserQuestion now:**
 
 Header: "Questions?"
-Question: "I've drafted an initial plan. Would you like to answer a few clarifying questions so I can refine it?"
+Question: "I've drafted an initial plan. Would you like to answer a few clarifying questions from different perspectives so I can refine it?"
 Options:
-- "Yes, ask me questions" (description: "I'll interview you about technical details, constraints, and preferences, then update the plan")
+- "Yes, ask me questions" (description: "I'll ask targeted questions to surface hidden constraints, then update the plan")
 - "No, proceed as-is" (description: "Skip questions and proceed with the current plan")
 
-### If user chooses YES - Interview them about:
-
-1. **Technical Implementation**
-   - Preferred approaches or patterns?
-   - Technologies/libraries to use or avoid?
-   - Performance or scalability requirements?
-
-2. **Constraints & Requirements**
-   - Hard constraints that must be respected?
-   - Deadlines or scope limitations?
-   - Dependencies on other systems?
-
-3. **Edge Cases & Concerns**
-   - Known edge cases to handle?
-   - Security or privacy considerations?
-   - Error handling preferences?
-
-4. **Tradeoffs**
-   - Speed vs. quality preferences?
-   - Simplicity vs. flexibility?
-   - What's acceptable to defer to later?
+### If user chooses YES:
 
-Ask focused, **non-obvious** questions using AskUserQuestion (max 12). Questions should surface hidden constraints, unstated assumptions, or preferences that aren't evident from the original request - things that would meaningfully change the plan.
+{persona_questions}
 
-After gathering answers, **update the plan file** with the refined content before calling ExitPlanMode.
+After gathering answers, **update the plan file** with refined content before calling ExitPlanMode.
 
 ### If user chooses NO:
 Proceed directly to ExitPlanMode with the current plan.

package/dist/templates/_shared/scripts/save_handoff.py

@@ -1,40 +1,221 @@
 #!/usr/bin/env python3
-"""Save a handoff document and set context status to handoff_pending.
+"""Save a handoff document with folder-based sharding.
 
 Usage:
     python .aiwcli/_shared/scripts/save_handoff.py <context_id> <<'EOF'
-    # Your handoff markdown content here
+    # Your handoff markdown content here (with <!-- SECTION: name --> markers)
     EOF
 
 Or with a file:
     python .aiwcli/_shared/scripts/save_handoff.py <context_id> < handoff.md
 
 This script:
-1. Reads handoff markdown content from stdin
-2. Saves it to _output/contexts/{context_id}/handoffs/HANDOFF-{HHMM}.md
-3. Sets in_flight.mode = "handoff_pending"
-4. Records the event in events.jsonl
-
-The handoff will be automatically picked up by the next session.
+1. Parses sections from incoming markdown using <!-- SECTION: name --> markers
+2. Creates a timestamped folder at _output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/
+3. Writes sharded files:
+   - index.md (main entry point with navigation)
+   - completed-work.md, dead-ends.md, decisions.md, pending.md, context.md
+   - plan.md (copy of original plan if it exists)
+4. Records the event in events.jsonl (informational only)
 """
+import json
+import re
+import subprocess
 import sys
 from datetime import datetime
 from pathlib import Path
+from typing import Dict, Optional
 
 # Add parent directories to path for imports
 SCRIPT_DIR = Path(__file__).resolve().parent
 SHARED_ROOT = SCRIPT_DIR.parent
 sys.path.insert(0, str(SHARED_ROOT))
 
-from lib.context.context_manager import update_handoff_status, get_context
-from lib.base.utils import eprint, atomic_write
+from lib.context.context_manager import get_context
+from lib.base.utils import eprint
+from lib.base.atomic_write import atomic_write
+from lib.base.constants import get_handoff_folder_path
+
+
+def parse_frontmatter(content: str) -> tuple[Dict[str, str], str]:
+    """Parse YAML frontmatter from markdown content.
+
+    Returns:
+        Tuple of (frontmatter dict, remaining content)
+    """
+    frontmatter = {}
+    remaining = content
+
+    if content.startswith('---'):
+        parts = content.split('---', 2)
+        if len(parts) >= 3:
+            fm_lines = parts[1].strip().split('\n')
+            for line in fm_lines:
+                if ':' in line:
+                    key, value = line.split(':', 1)
+                    frontmatter[key.strip()] = value.strip()
+            remaining = parts[2].strip()
+
+    return frontmatter, remaining
+
+
+def parse_handoff_sections(content: str) -> Dict[str, str]:
+    """Parse markdown content by section markers.
+
+    Looks for <!-- SECTION: name --> markers and extracts content between them.
+
+    Returns:
+        Dict mapping section names to their content
+    """
+    sections = {}
+    current_section = None
+    current_content = []
+
+    for line in content.split('\n'):
+        if line.strip().startswith('<!-- SECTION:'):
+            # Save previous section
+            if current_section:
+                sections[current_section] = '\n'.join(current_content).strip()
+            # Extract new section name
+            match = re.search(r'<!-- SECTION:\s*(\S+)\s*-->', line)
+            if match:
+                current_section = match.group(1)
+                current_content = []
+        elif current_section:
+            current_content.append(line)
+
+    # Save final section
+    if current_section:
+        sections[current_section] = '\n'.join(current_content).strip()
+
+    return sections
+
+
+def get_git_status() -> str:
+    """Get current git status."""
+    try:
+        result = subprocess.run(
+            ['git', 'status', '--short'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        return result.stdout.strip() or "(no changes)"
+    except Exception:
+        return "(git status unavailable)"
+
+
+def get_plan_path_from_context(context_id: str, project_root: Path) -> Optional[Path]:
+    """Get the plan path from context.json if available."""
+    context = get_context(context_id, project_root)
+    if not context or not context.in_flight:
+        return None
+
+    artifact_path = context.in_flight.artifact_path
+    if artifact_path:
+        plan_path = Path(artifact_path)
+        if plan_path.exists():
+            return plan_path
+
+    return None
+
+
+def generate_index(
+    frontmatter: Dict[str, str],
+    sections: Dict[str, str],
+    git_status: str,
+    has_plan: bool,
+) -> str:
+    """Generate the index.md file with summary and navigation."""
+    now = datetime.now()
+
+    lines = [
+        "---",
+        "type: handoff",
+        f"context_id: {frontmatter.get('context_id', 'unknown')}",
+        f"created_at: {now.isoformat()}",
+        f"session_id: {frontmatter.get('session_id', 'unknown')}",
+        f"project: {frontmatter.get('project', 'unknown')}",
+        f"plan_path: {frontmatter.get('plan_document', 'none')}",
+        "---",
+        "",
+        f"# Session Handoff - {now.strftime('%Y-%m-%d %H:%M')}",
+        "",
+    ]
+
+    # Summary section
+    summary = sections.get('summary', '').strip()
+    if summary:
+        # Extract just the content (skip the ## Summary header if present)
+        summary_lines = summary.split('\n')
+        summary_text = '\n'.join(
+            line for line in summary_lines
+            if not line.strip().startswith('##')
+        ).strip()
+        lines.extend([
+            "## Summary",
+            summary_text,
+            "",
+        ])
+
+    # Navigation table
+    lines.extend([
+        "## Quick Navigation",
+        "",
+        "| Document | Purpose | Priority |",
+        "|----------|---------|----------|",
+        "| [Dead Ends](./dead-ends.md) | Failed approaches - DO NOT RETRY | Read First |",
+        "| [Pending](./pending.md) | Next steps and blockers | Action Items |",
+        "| [Completed Work](./completed-work.md) | Tasks finished this session | Reference |",
+        "| [Decisions](./decisions.md) | Technical choices and rationale | Reference |",
+    ])
+
+    if has_plan:
+        lines.append("| [Plan](./plan.md) | Original plan being implemented | Reference |")
+
+    lines.extend([
+        "| [Context](./context.md) | External requirements and notes | Reference |",
+        "",
+        "## Continuation Instructions",
+        "",
+        "To continue this work in a new session:",
+        "1. This index document provides the overview",
+        "2. **Read [Dead Ends](./dead-ends.md) first** to avoid repeating failed approaches",
+        "3. Check [Pending](./pending.md) for immediate next steps",
+        "4. Reference other documents as needed",
+        "",
+        "## Git Status at Handoff",
+        "```",
+        git_status,
+        "```",
+        "",
+    ])
+
+    return '\n'.join(lines)
+
+
+def write_section_file(folder: Path, filename: str, title: str, content: str) -> bool:
+    """Write a section file with header."""
+    lines = [
+        f"# {title}",
+        "",
+        content if content else "(No content for this section)",
+        "",
+    ]
+
+    file_path = folder / filename
+    success, error = atomic_write(file_path, '\n'.join(lines))
+    if not success:
+        eprint(f"[save_handoff] Warning: Failed to write {filename}: {error}")
+        return False
+    return True
 
 
 def main():
     if len(sys.argv) < 2:
         print("Usage: python save_handoff.py <context_id> < content.md", file=sys.stderr)
         print("       python save_handoff.py <context_id> <<'EOF'", file=sys.stderr)
-        print("       ... markdown content ...", file=sys.stderr)
+        print("       ... markdown content with <!-- SECTION: name --> markers ...", file=sys.stderr)
         print("       EOF", file=sys.stderr)
         sys.exit(1)
 
@@ -55,44 +236,109 @@ def main():
         print(f"Error: Context not found: {context_id}", file=sys.stderr)
         sys.exit(1)
 
-    # Create handoffs directory
-    handoffs_dir = project_root / "_output" / "contexts" / context_id / "handoffs"
-    handoffs_dir.mkdir(parents=True, exist_ok=True)
+    # Parse frontmatter and sections
+    frontmatter, body = parse_frontmatter(content)
+    sections = parse_handoff_sections(body)
 
-    # Generate filename with timestamp
-    timestamp = datetime.now().strftime("%H%M")
-    filename = f"HANDOFF-{timestamp}.md"
-    file_path = handoffs_dir / filename
+    eprint(f"[save_handoff] Parsed {len(sections)} sections: {list(sections.keys())}")
 
-    # Handle filename collision (add suffix if file exists)
-    counter = 1
-    while file_path.exists():
-        filename = f"HANDOFF-{timestamp}-{counter}.md"
-        file_path = handoffs_dir / filename
-        counter += 1
+    # Create handoff folder
+    handoff_folder = get_handoff_folder_path(context_id, project_root)
+    handoff_folder.mkdir(parents=True, exist_ok=True)
+    eprint(f"[save_handoff] Created folder: {handoff_folder}")
 
-    # Save the handoff document
-    try:
-        success, error = atomic_write(file_path, content)
-        if not success:
-            print(f"Error: Failed to write handoff: {error}", file=sys.stderr)
-            sys.exit(1)
-    except Exception as e:
-        print(f"Error: Failed to write handoff: {e}", file=sys.stderr)
+    # Get git status
+    git_status = get_git_status()
+
+    # Check for plan
+    plan_path = get_plan_path_from_context(context_id, project_root)
+    has_plan = plan_path is not None
+
+    # Copy plan if exists
+    if plan_path:
+        try:
+            plan_content = plan_path.read_text(encoding='utf-8')
+            plan_dest = handoff_folder / "plan.md"
+            success, error = atomic_write(plan_dest, plan_content)
+            if success:
+                eprint(f"[save_handoff] Copied plan from {plan_path}")
+            else:
+                eprint(f"[save_handoff] Warning: Failed to copy plan: {error}")
+        except Exception as e:
+            eprint(f"[save_handoff] Warning: Failed to read plan: {e}")
+
+    # Write index.md
+    index_content = generate_index(frontmatter, sections, git_status, has_plan)
+    index_path = handoff_folder / "index.md"
+    success, error = atomic_write(index_path, index_content)
+    if not success:
+        print(f"Error: Failed to write index.md: {error}", file=sys.stderr)
         sys.exit(1)
 
-    # Update context status
-    try:
-        update_handoff_status(context_id, str(file_path), project_root)
-    except Exception as e:
-        eprint(f"[save_handoff] Warning: Status update failed: {e}")
-        # Don't exit - file was saved successfully
-
-    # Output success message
-    print(f"✓ Saved handoff: {file_path}")
-    print(f"✓ Set status to handoff_pending for context: {context_id}")
+    # Write section files
+    section_mapping = {
+        'completed': ('completed-work.md', 'Work Completed'),
+        'dead-ends': ('dead-ends.md', 'Dead Ends - Do Not Retry'),
+        'decisions': ('decisions.md', 'Key Decisions'),
+        'pending': ('pending.md', 'Pending Issues'),
+        'next-steps': ('pending.md', None),  # Append to pending.md
+        'files': ('completed-work.md', None),  # Append to completed-work.md
+        'context': ('context.md', 'Context for Future Sessions'),
+    }
+
+    # Track which files we've written with their content
+    file_contents: Dict[str, list] = {}
+
+    for section_name, (filename, title) in section_mapping.items():
+        section_content = sections.get(section_name, '')
+        if not section_content:
+            continue
+
+        if title is None:
+            # Append mode - add to existing content
+            if filename not in file_contents:
+                file_contents[filename] = []
+            file_contents[filename].append(section_content)
+        else:
+            # Write mode - set as main content with title
+            if filename not in file_contents:
+                file_contents[filename] = [f"# {title}", "", section_content]
+            else:
+                # Insert title at beginning if not present
+                file_contents[filename] = [f"# {title}", ""] + file_contents[filename] + ["", section_content]
+
+    # Write all accumulated content
+    for filename, content_parts in file_contents.items():
+        file_path = handoff_folder / filename
+        full_content = '\n'.join(content_parts) + '\n'
+        success, error = atomic_write(file_path, full_content)
+        if not success:
+            eprint(f"[save_handoff] Warning: Failed to write {filename}: {error}")
+
+    # Ensure all expected files exist (even if empty)
+    expected_files = ['completed-work.md', 'dead-ends.md', 'decisions.md', 'pending.md', 'context.md']
+    titles = {
+        'completed-work.md': 'Work Completed',
+        'dead-ends.md': 'Dead Ends - Do Not Retry',
+        'decisions.md': 'Key Decisions',
+        'pending.md': 'Pending Issues & Next Steps',
+        'context.md': 'Context for Future Sessions',
+    }
+
+    for filename in expected_files:
+        file_path = handoff_folder / filename
+        if not file_path.exists():
+            write_section_file(handoff_folder, filename, titles[filename], "")
+
+    # Output success message (ASCII-safe for Windows)
+    print(f"[OK] Created handoff folder: {handoff_folder}")
+    print(f"  - index.md (entry point with navigation)")
+
+    files_created = [f.name for f in handoff_folder.iterdir() if f.is_file() and f.name != 'index.md']
+    print(f"  - {', '.join(sorted(files_created))}")
+
     print()
-    print("The next session will automatically offer to resume from this handoff.")
+    print("Handoff document saved. Use this folder for context in the next session.")
 
 
 if __name__ == "__main__":

package/dist/templates/_shared/workflows/handoff.md

@@ -52,7 +52,7 @@ If no active context is found, inform the user and stop - handoffs require an ac
 
 ### Step 3: Generate Document
 
-Use this template:
+Use this template. The `<!-- SECTION: name -->` markers are required for the save script to parse sections into sharded files.
 
 ```markdown
 ---
@@ -66,34 +66,40 @@ plan_document: {path to plan if provided, or "none"}
 
 # Session Handoff — {Date}
 
+<!-- SECTION: summary -->
 ## Summary
 {2-3 sentences: what's different now vs. session start}
 
+<!-- SECTION: completed -->
 ## Work Completed
 {Grouped by category if multiple areas. Specific file:function references.}
 
+<!-- SECTION: dead-ends -->
 ## Dead Ends — Do Not Retry
-{Approaches that were tried and failed. Critical for avoiding wasted effort in future sessions.}
 
-### {Problem/Goal attempted}
-| Approach Tried | Why It Failed | Time Spent |
-|----------------|---------------|------------|
-| {What was attempted} | {Specific reason: error, incompatibility, performance, etc.} | {Rough estimate} |
+These approaches were attempted and failed. Do not retry without addressing the root cause.
 
-**What to try instead**: {If known, suggest alternative direction}
+| Approach | Why It Failed | Time Spent | Alternative |
+|----------|---------------|------------|-------------|
+| {What was attempted} | {Specific reason} | {Rough estimate} | {What to try instead} |
 
+<!-- SECTION: decisions -->
 ## Key Decisions
 {Technical choices with rationale. Format: **Decision**: Rationale. Trade-off: X.}
 
+<!-- SECTION: pending -->
 ## Pending Issues
 - [ ] {Issue} — {severity: HIGH/MED/LOW} {optional workaround note}
 
+<!-- SECTION: next-steps -->
 ## Next Steps
 1. {Actionable item with file:line reference if applicable}
 
+<!-- SECTION: files -->
 ## Files Modified
 {Significant changes only. Skip formatting-only edits.}
 
+<!-- SECTION: context -->
 ## Context for Future Sessions
 {Non-obvious context: env quirks, stakeholder requirements}
 
@@ -150,11 +156,12 @@ EOF
 ```
 
 This script:
-1. Saves the handoff to `_output/contexts/{context_id}/handoffs/HANDOFF-{HHMM}.md`
-2. Sets `in_flight.mode = "handoff_pending"`
-3. Records the event in the context's event log
+1. Creates a folder at `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
+2. Parses sections and writes sharded files (index.md, completed-work.md, dead-ends.md, etc.)
+3. Copies the current plan (if any) to plan.md
+4. Records the event in the context's event log (informational only)
 
-The next session will automatically detect the handoff and offer to resume.
+Use the handoff folder for context in the next session.
 
 ## Dead Ends Section Guidelines
 
@@ -185,10 +192,14 @@ This section is critical for preventing context rot across sessions. Be specific
 After creating file, output:
 
 ```
-✓ Created _output/contexts/{context_id}/handoffs/HANDOFF-{HHMM}.md
+✓ Created handoff folder: _output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/
+  - index.md (entry point with navigation)
+  - completed-work.md, dead-ends.md, decisions.md, pending.md, context.md
+  - plan.md (copy of current plan, if any)
 
 To continue next session:
-  "Load _output/contexts/{context_id}/handoffs/HANDOFF-{HHMM}.md and continue from next steps"
+  The index.md will be automatically suggested when you start a new session.
+  Read dead-ends.md first to avoid repeating failed approaches.
 
 ⚠️  {N} dead ends documented — avoid re-attempting these approaches
 ```
@@ -203,10 +214,13 @@ If plan was updated:
 
 ## Success Criteria
 
-- [ ] Handoff document created in context's `handoffs/` subfolder
-- [ ] Dead ends section captures all failed approaches with specific details
+- [ ] Handoff folder created at `handoffs/{YYYY-MM-DD-HHMM}/`
+- [ ] index.md contains summary and navigation table
+- [ ] All section files created (completed-work.md, dead-ends.md, etc.)
+- [ ] Dead ends use structured table format for quick scanning
+- [ ] plan.md copied from context if plan exists
 - [ ] Next steps are actionable with file references
-- [ ] Git status reflects current state
+- [ ] Git status included in index.md
 - [ ] If plan provided: checkboxes updated to reflect completion status
 - [ ] If plan provided: Session Progress Log appended
 - [ ] Context state updated to indicate handoff pending