aiwcli 0.9.6 → 0.9.8

package/dist/templates/_shared/hooks/session_start.py

@@ -1,18 +1,14 @@
 #!/usr/bin/env python3
-"""SessionStart hook for mode transitions after /clear.
+"""SessionStart hook for mode transitions and post-compaction restore.
 
-This hook fires when a new session starts. It handles the critical transition
-from `pending_implementation` to `implementing` when a session starts after
-/clear with bypass permissions.
+This hook fires when a new session starts. It handles:
 
-The flow is:
-1. User approves plan (ExitPlanMode) -> mode = pending_implementation
-2. User clicks "yes and clear and bypass permissions"
-3. SessionStart fires with source="clear" and permission_mode="bypassPermissions"
-4. This hook transitions mode to "implementing"
+1. Mode transition from `pending_implementation` to `implementing` when
+   a session starts after /clear with bypass permissions.
 
-Without this hook, the mode stays stuck at pending_implementation because
-UserPromptSubmit may not receive the correct permission_mode after /clear.
+2. Post-compaction restore: when source="compact", the session is already
+   bound to a context. Load auto-state and inject rich restoration context
+   so Claude can continue seamlessly after compaction.
 
 Hook input:
 {
@@ -24,6 +20,7 @@ Hook input:
     ...
 }
 """
+import json
 import sys
 from pathlib import Path
 
@@ -36,22 +33,106 @@ from lib.base.hook_utils import load_hook_input
 from lib.base.utils import eprint, project_dir
 from lib.context.context_manager import (
     get_all_in_flight_contexts,
+    get_context_by_session_id,
     update_plan_status,
     update_context_session_id,
 )
+from lib.context.auto_state import load_auto_state
+from lib.context.discovery import (
+    _build_restore_sections,
+    find_plan_path,
+    format_relative_time,
+)
+from lib.context.task_sync import generate_task_summary
 
 
-def main():
+def _handle_clear_transition(hook_input, session_id, project_root):
+    """Handle /clear mode transitions (existing behavior)."""
+    permission_mode = hook_input.get("permission_mode", "default")
+
+    if permission_mode == "plan":
+        eprint("[session_start] Skipping: permission_mode is 'plan' (in planning mode)")
+        return
+
+    in_flight_contexts = get_all_in_flight_contexts(project_root)
+    if not in_flight_contexts:
+        eprint("[session_start] No in-flight contexts found")
+        return
+
+    pending_contexts = [
+        ctx for ctx in in_flight_contexts
+        if ctx.in_flight and ctx.in_flight.mode == "pending_implementation"
+    ]
+    for ctx in pending_contexts:
+        eprint(f"[session_start] Transitioning {ctx.id} from pending_implementation to implementing")
+        update_plan_status(ctx.id, "implementing", project_root=project_root)
+        update_context_session_id(ctx.id, session_id, project_root)
+        eprint(f"[session_start] Bound session {session_id[:8]}... to context {ctx.id}")
+
+    if pending_contexts:
+        eprint(f"[session_start] Transitioned {len(pending_contexts)} context(s) to implementing")
+
+
+def _handle_compact_restore(hook_input, session_id, project_root):
+    """
+    Handle post-compaction restore.
+
+    After compaction, the session is already bound to a context.
+    Load auto-state and inject rich restoration context via additionalContext.
     """
-    Handle mode transitions on session start.
+    context = get_context_by_session_id(session_id, project_root)
+    if not context:
+        eprint("[session_start] No context bound to session after compact")
+        return
+
+    context_id = context.id
+    eprint(f"[session_start] Post-compaction restore for context: {context_id}")
+
+    # Build restoration context
+    mode_display = "Active"
+    if context.in_flight and context.in_flight.mode != "none":
+        mode_display = context.in_flight.mode.replace("_", " ").title()
+
+    lines = [
+        f"## Resuming Context After Compaction: {context_id}",
+        "",
+        f"**Summary:** {context.summary}",
+        f"**Mode:** {mode_display}",
+    ]
+
+    # Add restore sections (auto-state, tasks, git)
+    restore = _build_restore_sections(context, project_root)
+    if restore:
+        lines.append(restore)
+
+    lines.extend([
+        "",
+        "---",
+        "",
+        "**Instructions:**",
+        "Context was compacted to free memory. Your previous conversation has been summarized.",
+        "1. Review the previous work above",
+        "2. Continue from where you left off",
+    ])
+
+    restore_context = "\n".join(lines)
+
+    # Output as additionalContext so Claude sees it
+    output = {
+        "hookSpecificOutput": {
+            "additionalContext": restore_context
+        }
+    }
+    print(json.dumps(output, ensure_ascii=False))
+    eprint(f"[session_start] Injected post-compaction restore context for {context_id}")
+
 
-    When source is "clear" and permission_mode is "bypassPermissions" or "acceptEdits",
-    transition any pending_implementation context to implementing.
+def main():
+    """
+    Handle mode transitions and post-compaction restore on session start.
     """
     try:
-        # Read hook input using shared utility
         hook_input = load_hook_input()
-
         if not hook_input:
             return
 
@@ -62,36 +143,12 @@ def main():
 
         eprint(f"[session_start] source={source}, permission_mode={permission_mode}, session={session_id[:8]}...")
 
-        # Only handle /clear with bypass/accept permissions
-        if source != "clear":
-            eprint(f"[session_start] Skipping: source is '{source}', not 'clear'")
-            return
-
-        if permission_mode == "plan":
-            eprint(f"[session_start] Skipping: permission_mode is 'plan' (in planning mode)")
-            return
-
-        # Find contexts in pending_implementation mode
-        in_flight_contexts = get_all_in_flight_contexts(project_root)
-        pending_contexts = [
-            ctx for ctx in in_flight_contexts
-            if ctx.in_flight and ctx.in_flight.mode == "pending_implementation"
-        ]
-
-        if not pending_contexts:
-            eprint("[session_start] No pending_implementation contexts found")
-            return
-
-        # Transition each pending context to implementing
-        for ctx in pending_contexts:
-            eprint(f"[session_start] Transitioning {ctx.id} from pending_implementation to implementing")
-            update_plan_status(ctx.id, "implementing", project_root=project_root)
-
-            # Also bind this session to the context
-            update_context_session_id(ctx.id, session_id, project_root)
-            eprint(f"[session_start] Bound session {session_id[:8]}... to context {ctx.id}")
-
-        eprint(f"[session_start] Transitioned {len(pending_contexts)} context(s) to implementing")
+        if source == "clear":
+            _handle_clear_transition(hook_input, session_id, project_root)
+        elif source == "compact":
+            _handle_compact_restore(hook_input, session_id, project_root)
+        else:
+            eprint(f"[session_start] No action for source='{source}'")
 
     except Exception as e:
         eprint(f"[session_start] ERROR: {e}")

package/dist/templates/_shared/hooks/task_create_atomicity.py

@@ -34,64 +34,47 @@ from lib.base.inference import inference
 # - Direct imperative instructions
 # - Explicit JSON output format
 
-ASSESSMENT_SYSTEM_PROMPT = """You assess task descriptions for atomicity and forkability.
+ASSESSMENT_SYSTEM_PROMPT = """Assess whether a task description is self-contained enough for a subagent with zero conversation history to execute it.
 
-## Definitions
+## What Makes a Good Task
 
-**Atomic Task:** Contains ALL context needed for independent execution without reading prior conversation.
-
-**Forkable Task:** Can be delegated to a subagent with ZERO conversation history and still be completed successfully.
-
-## Signs of Non-Atomic Tasks
-
-Look for these indicators:
-- Contextual references: "the file above", "as discussed", "the mentioned function", "this bug"
-- Vague descriptions assuming prior knowledge: "fix the bug", "update it", "finish the work"
-- Missing specifics: which file? what function? what expected behavior? what error?
-- Pronouns without antecedents: "it", "they", "the issue" without explicit definition
-
-## Signs of Atomic Tasks
-
-Well-specified tasks include:
+A well-specified task includes:
 - Explicit file paths: "Edit src/utils/parser.py"
-- Specific function names: "Modify the validate_input() function"
-- Clear expected behavior: "Should return 404 when user not found"
-- Complete error context: "TypeError on line 45 when input is None"
+- Specific function/component names: "Modify validate_input()"
+- Clear expected behavior: "Return 404 when user not found"
+- Concrete error context: "TypeError on line 45 when input is None"
 
-## Examples
+## What Makes a Poor Task
 
-**Example 1: Non-Atomic Task**
-Subject: "Fix the bug"
-Description: "The issue we discussed earlier needs to be resolved"
-Assessment: NOT atomic (no file, no function, no error details, references "discussed earlier")
+Watch for context-dependent references:
+- Dangling references: "the file above", "as discussed", "this bug"
+- Vague actions: "fix the bug", "update it", "finish the work"
+- Pronouns without antecedents: "it", "they", "the issue"
+- Missing specifics: which file? what function? what behavior?
 
-**Example 2: Atomic Task**
-Subject: "Fix null pointer in user lookup"
-Description: "In src/services/user.py, the get_user_by_id() function raises TypeError when user_id is None. Add null check at line 23 that returns None early instead of calling database.query()."
-Assessment: Atomic (file path, function name, specific error, exact fix location, expected behavior)
+## Examples
 
-**Example 3: Partially Atomic Task**
-Subject: "Add validation to form"
-Description: "Add email validation to the signup form. Return error message if invalid."
-Assessment: NOT fully atomic (missing: which file contains the form? what validation rules? where to display error?)
+**Atomic** — Subject: "Fix null pointer in user lookup"
+Description: "In src/services/user.py, get_user_by_id() raises TypeError when user_id is None. Add null check at line 23 to return None instead of calling database.query()."
+Why: file path, function, error, fix location, expected behavior.
 
-## Output Format
+**Not atomic** — Subject: "Fix the bug"
+Description: "The issue we discussed earlier needs to be resolved"
+Why: no file, no function, no error details, references conversation history.
 
-Respond with valid JSON only:
-{
-  "atomic": true/false,
-  "forkable": true/false,
-  "issues": ["specific issue 1", "specific issue 2"],
-  "recommendation": "brief actionable suggestion if issues exist, or 'Task is well-specified' if good"
-}"""
+**Partially atomic** — Subject: "Add validation to form"
+Description: "Add email validation to the signup form. Return error if invalid."
+Why: missing which file, what validation rules, where to display error.
 
-ASSESSMENT_USER_TEMPLATE = """Assess this task for atomicity and forkability:
+## Output
 
-**Subject:** {subject}
+Respond with JSON only:
+{"atomic": true/false, "forkable": true/false, "issues": ["issue 1", "issue 2"], "recommendation": "actionable suggestion or 'Well-specified'"}"""
 
+ASSESSMENT_USER_TEMPLATE = """**Subject:** {subject}
 **Description:** {description}
 
-Evaluate whether a subagent with zero prior context could execute this task successfully."""
+Could a subagent with zero conversation history execute this task?"""
 
 
 @safe_hook_main("task_create_atomicity")
@@ -167,33 +150,22 @@ def main() -> int:
 
     # Build context message based on assessment
     if atomic and forkable:
-        # Task is good - minimal positive feedback
-        context_msg = "Task Assessment: Well-specified and forkable."
+        context_msg = "Task assessment: well-specified and ready for delegation."
     else:
-        # Task has issues - inject detailed warning
-        status_parts = []
-        if not atomic:
-            status_parts.append("NOT ATOMIC")
-        if not forkable:
-            status_parts.append("NOT FORKABLE")
+        # Constructive guidance — what to add, not what's wrong
+        issues_text = "\n".join(f"- {issue}" for issue in issues) if issues else ""
 
-        issues_text = "\n".join(f"- {issue}" for issue in issues) if issues else "- See recommendation below"
+        context_msg = f"""**Enrich this task for subagent delegation**
 
-        context_msg = f"""**TASK ATOMICITY WARNING** ({', '.join(status_parts)})
+A subagent receiving this task will have no conversation history. To make it actionable:
 
-This task may lack sufficient context for independent execution by a subagent.
-
-**Issues detected:**
 {issues_text}
 
-**Recommendation:** {recommendation}
-
-Consider adding specific file paths, function names, expected behaviors, or error details before creating this task."""
+**Suggested enrichment:** {recommendation}"""
 
     # Output hook response with additionalContext
     out = {
         "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
             "additionalContext": context_msg
         }
     }

package/dist/templates/_shared/hooks/task_create_capture.py

@@ -115,6 +115,7 @@ def main() -> int:
         subject=subject,
         description=description,
         active_form=active_form,
+        session_id=session_id or "",
         project_root=project_root
     )
 

package/dist/templates/_shared/hooks/task_update_capture.py

@@ -53,6 +53,7 @@ from lib.context.task_sync import (
     record_task_started,
     record_task_completed,
     record_task_blocked,
+    record_task_deleted,
 )
 
 
@@ -147,6 +148,7 @@ def main() -> int:
         success = record_task_started(
             context_id=context_id,
             task_id=persistent_task_id,
+            session_id=session_id or "",
             project_root=project_root
         )
         if success:
@@ -173,11 +175,23 @@ def main() -> int:
             work_summary=work_summary,
             files_changed=files_changed if isinstance(files_changed, list) else [],
             commit_ref=commit_ref,
+            session_id=session_id or "",
             project_root=project_root
         )
         if success:
             events_recorded.append("task_completed")
 
+    # Status: deleted
+    elif status == "deleted":
+        success = record_task_deleted(
+            context_id=context_id,
+            task_id=persistent_task_id,
+            session_id=session_id or "",
+            project_root=project_root
+        )
+        if success:
+            events_recorded.append("task_deleted")
+
     # Blocked by tasks
     if add_blocked_by and isinstance(add_blocked_by, list) and len(add_blocked_by) > 0:
         blocked_reason = f"Blocked by tasks: {', '.join(add_blocked_by)}"
@@ -185,6 +199,7 @@ def main() -> int:
             context_id=context_id,
             task_id=persistent_task_id,
             reason=blocked_reason,
+            session_id=session_id or "",
             project_root=project_root
         )
         if success:

package/dist/templates/_shared/hooks/user_prompt_submit.py

@@ -46,36 +46,24 @@ def format_claudemd_reminder() -> str:
     return """
 ## CLAUDE.md Decision Capture
 
-When implementing changes, consider whether this work involves decisions with non-obvious rationale. If so, update or create a CLAUDE.md in the relevant directory.
+**Placement rule:** CLAUDE.md files cascade — subdirectories inherit from parents. Default to updating the nearest existing CLAUDE.md. Only create a new one at a semantic boundary where responsibility genuinely shifts (package roots with their own manifest, technology boundaries, domain boundaries, integration points).
 
-**When to update CLAUDE.md:**
-- Architectural choices (why this pattern over alternatives)
-- Non-obvious constraints (why something MUST be done a certain way)
-- Learned patterns (discovered issues that future work should avoid)
-- Integration decisions (why components connect this way)
-- Workarounds (temporary solutions with context on the underlying issue)
+**Before creating a new CLAUDE.md, ask:** "Do the rules here actually differ from the parent?" If not, update the parent instead.
 
-**What to capture (use this format):**
+**Keep files lean (progressive disclosure):** Each CLAUDE.md should contain only decisions relevant at that directory level. Verbose files become noise that degrades future task quality — every entry competes for attention in the context window. Capture only non-obvious rationale, not descriptions of what the code does.
 
-```markdown
-## [Topic]
-
-**Decision:** [What was decided]
-**Rationale:** [Why this approach was chosen]
-**Constraint:** [What breaks if this changes]
-```
+**What to capture** (only when decisions have non-obvious rationale):
+- Architectural choices and their alternatives
+- Non-obvious constraints (what breaks if this changes)
+- Workarounds with context on the underlying issue
+- Learned patterns that prevent future mistakes
 
-**Directory-specific:** Place CLAUDE.md in the directory closest to the affected code. If no CLAUDE.md exists, create one with a descriptive header.
-
-**Example new CLAUDE.md:**
+**Format:**
 
 ```markdown
-# Component Name
-
-Development decisions and patterns for this component.
-
-## [First Decision Topic]
-...
+## [Topic]
+**Decision:** [What was decided]
+**Rationale:** [Why — the non-obvious part]
 ```
 """
 
@@ -143,10 +131,8 @@ def main():
         elif user_prompt:
             # FIRST prompt - need context detection
             try:
-                context_id, method, context_output, remaining_prompt = determine_context(user_prompt, project_root, session_id)
+                context_id, method, context_output = determine_context(user_prompt, project_root, session_id)
                 eprint(f"[user_prompt_submit] Context: {method} -> {context_id}")
-                if remaining_prompt:
-                    eprint(f"[user_prompt_submit] Actual request: {remaining_prompt[:50]}...")
 
                 if context_id:
                     # Bind session to context

package/dist/templates/_shared/lib/base/constants.py

@@ -15,7 +15,7 @@ from pathlib import Path
 # Directory names (relative to project root)
 OUTPUT_DIR = "_output"
 CONTEXTS_DIR = "contexts"
-ARCHIVE_DIR = "archive"
+ARCHIVE_DIR = "_archive"
 INDEX_FILENAME = "index.json"
 
 # Context ID validation
@@ -255,6 +255,20 @@ def get_events_file_path(context_id: str, project_root: Path = None) -> Path:
     return get_context_dir(context_id, project_root) / "events.jsonl"
 
 
+def get_auto_state_path(context_id: str, project_root: Path = None) -> Path:
+    """
+    Get the auto-state.json file path for a specific context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to _output/contexts/{context_id}/auto-state.json
+    """
+    return get_context_dir(context_id, project_root) / "auto-state.json"
+
+
 def get_archive_dir(project_root: Path = None) -> Path:
     """
     Get the archive directory path.
@@ -263,7 +277,7 @@ def get_archive_dir(project_root: Path = None) -> Path:
         project_root: Project root directory (default: cwd)
 
     Returns:
-        Path to _output/contexts/archive/
+        Path to _output/contexts/_archive/
     """
     return get_contexts_dir(project_root) / ARCHIVE_DIR
 
@@ -277,7 +291,7 @@ def get_archive_context_dir(context_id: str, project_root: Path = None) -> Path:
         project_root: Project root directory (default: cwd)
 
     Returns:
-        Path to _output/contexts/archive/{context_id}/
+        Path to _output/contexts/_archive/{context_id}/
 
     Raises:
         ValueError: If context_id is invalid
@@ -294,7 +308,7 @@ def get_archive_index_path(project_root: Path = None) -> Path:
         project_root: Project root directory (default: cwd)
 
     Returns:
-        Path to _output/contexts/archive/index.json
+        Path to _output/contexts/_archive/index.json
     """
     return get_archive_dir(project_root) / INDEX_FILENAME
 

package/dist/templates/_shared/lib/base/hook_utils.py

@@ -19,30 +19,6 @@ from .utils import eprint
 F = TypeVar('F', bound=Callable[..., Any])
 
 
-def setup_hook_paths() -> Path:
-    """
-    Setup import paths for hooks.
-
-    Call this at module level in hook scripts to ensure
-    the shared lib directory is in sys.path.
-
-    Returns:
-        Path to the lib directory
-
-    Example:
-        SCRIPT_DIR = Path(__file__).resolve().parent
-        SHARED_LIB = SCRIPT_DIR.parent / "lib"
-        sys.path.insert(0, str(SHARED_LIB.parent))
-    """
-    # This function exists mainly for documentation
-    # Actual path setup must happen at module level before imports
-    hook_dir = Path(__file__).resolve().parent.parent.parent / "hooks"
-    lib_dir = hook_dir.parent / "lib"
-    if str(lib_dir.parent) not in sys.path:
-        sys.path.insert(0, str(lib_dir.parent))
-    return lib_dir
-
-
 def load_hook_input() -> Optional[Dict[str, Any]]:
     """
     Load and parse JSON from stdin.

package/dist/templates/_shared/lib/base/stop_words.py

@@ -187,4 +187,27 @@ STOP_WORDS = {
     # FRAGMENT WORDS (artifacts from contractions/tokenization)
     # ========================================================================
     're', 'pl', 'aiw', 've', 'll', 'doesn', 't', 's',
+
+    # ========================================================================
+    # CORPUS-DERIVED SHORT NOISE (2026-02 analysis of 131 docs)
+    # ========================================================================
+    # Contractions with punctuation stripped (I'm -> im, etc.)
+    'im', 'ive', 'id', 'ill', 'youre', 'youve', 'youll',
+    'hes', 'shes', 'weve', 'theyre', 'theyve', 'dont', 'doesnt',
+    'didnt', 'wont', 'wouldnt', 'cant', 'couldnt', 'shouldnt', 'isnt',
+    'arent', 'wasnt', 'werent', 'hasnt', 'havent', 'hadnt', 'lets',
+    'thats', 'whats', 'heres', 'theres', 'whos',
+
+    # Filler/noise from corpus (>10% frequency, non-action)
+    'etc', 'up', 'as', 'cc',
+
+    # Number words (common in plans but don't identify task)
+    'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten',
+
+    # Single letters (artifacts from lists, paths, variables)
+    'b', 'c', 'd', 'e', 'f', 'g', 'h', 'j', 'k', 'l', 'm', 'n', 'o', 'p',
+    'q', 'r', 'u', 'v', 'w', 'x', 'y', 'z',
+
+    # Short adverbs/fillers from review
+    'too', 'yes', 'ok', 'okay',
 }

package/dist/templates/_shared/lib/base/utils.py

@@ -138,22 +138,27 @@ def generate_context_id(summary: str, existing_ids: Optional[set] = None) -> str
     """
     Generate a context ID from a summary string.
 
-    Filters stop words from the summary and slugifies the result.
+    Prepends a YYMMDD-HHMM local-time timestamp for visual
+    distinguishability, then filters stop words and slugifies.
 
     Args:
         summary: Context summary text
         existing_ids: Optional set of existing context IDs to avoid
 
     Returns:
-        Unique context ID string
+        Unique context ID string (e.g. '260205-1700-add-user-auth')
     """
+    # Timestamp prefix using local time, to the minute
+    timestamp = datetime.now().strftime("%y%m%d-%H%M")
+
     if not summary or not summary.strip():
-        base_id = "context"
+        base_id = f"{timestamp}-context"
     else:
         # Use stop word filter, limit to 12 words
         from .stop_words import STOP_WORDS
         words = [w for w in summary.lower().split() if w not in STOP_WORDS and len(w) > 1][:12]
-        base_id = sanitize_title(' '.join(words), max_len=100)
+        slug = sanitize_title(' '.join(words), max_len=50)
+        base_id = f"{timestamp}-{slug}"
 
     if not existing_ids:
         return base_id

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

@@ -50,10 +50,6 @@ from .task_sync import (
 )
 from .plan_archive import (
     archive_plan_to_context,
-    get_active_context_for_plan,
-    create_context_from_plan,
-    mark_plan_implementation_started,
-    mark_plan_completed,
 )
 from .context_extractor import (
     extract_context_id,
@@ -108,10 +104,6 @@ __all__ = [
     "generate_next_task_id",
     # Plan Archive
     "archive_plan_to_context",
-    "get_active_context_for_plan",
-    "create_context_from_plan",
-    "mark_plan_implementation_started",
-    "mark_plan_completed",
     # Context Extractor
     "extract_context_id",
     "extract_context_id_for_session",