aiwcli 0.9.0 → 0.9.2

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

@@ -0,0 +1,158 @@
+"""Stop words for context ID generation.
+
+Generated from analysis of 1,424 prompts, context summaries, and plan files.
+Words that appear frequently but don't help identify the specific task.
+
+Categories organized for maintainability. Add new corpus-derived words to
+the appropriate category or to "Corpus-derived additions" at the end.
+
+ACTION VERBS ARE INTENTIONALLY EXCLUDED from this list:
+add, fix, update, create, implement, refactor, migrate, debug, remove, change,
+move, rename, delete, build, test, deploy, verify, analyze, modify, write, run,
+check, replace, save, sync, load, extract, install, refactor, clean, merge, etc.
+
+These action verbs should REMAIN in context IDs as they identify the task type.
+"""
+
+STOP_WORDS = {
+    # ========================================================================
+    # ARTICLES
+    # ========================================================================
+    'a', 'an', 'the',
+
+    # ========================================================================
+    # PREPOSITIONS
+    # ========================================================================
+    'to', 'for', 'in', 'on', 'at', 'by', 'with', 'from', 'of', 'about',
+    'into', 'over', 'under', 'between', 'through', 'during', 'before', 'after',
+    'above', 'below', 'against', 'among', 'around', 'behind', 'beside', 'besides',
+    'beyond', 'down', 'inside', 'outside', 'near', 'off', 'onto', 'out',
+    'since', 'toward', 'towards', 'until', 'upon', 'within', 'without',
+    'across', 'along', 'via', 'per',
+
+    # ========================================================================
+    # PRONOUNS
+    # ========================================================================
+    # Personal pronouns
+    'i', 'you', 'he', 'she', 'it', 'we', 'they',
+    'me', 'him', 'her', 'us', 'them',
+    'myself', 'yourself', 'himself', 'herself', 'itself', 'ourselves', 'themselves',
+
+    # Possessive pronouns
+    'my', 'your', 'his', 'her', 'its', 'our', 'their',
+    'mine', 'yours', 'hers', 'ours', 'theirs',
+
+    # Demonstrative pronouns
+    'this', 'that', 'these', 'those',
+
+    # Relative pronouns
+    'who', 'whom', 'whose', 'which', 'that',
+
+    # Indefinite pronouns
+    'someone', 'somebody', 'something', 'anyone', 'anybody', 'anything',
+    'everyone', 'everybody', 'everything', 'no one', 'nobody', 'nothing',
+    'one', 'ones',
+
+    # ========================================================================
+    # AUXILIARY/MODAL VERBS
+    # ========================================================================
+    'am', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'having',
+    'do', 'does', 'did', 'doing', 'done',
+    'can', 'could', 'will', 'would', 'shall', 'should', 'may', 'might', 'must',
+
+    # ========================================================================
+    # CONJUNCTIONS
+    # ========================================================================
+    'and', 'or', 'but', 'nor', 'so', 'yet', 'for',
+    'if', 'then', 'else', 'whether', 'unless', 'although', 'though',
+    'because', 'since', 'while', 'whereas', 'whenever', 'wherever',
+
+    # ========================================================================
+    # QUESTION WORDS
+    # ========================================================================
+    'what', 'when', 'where', 'why', 'how',
+
+    # ========================================================================
+    # ADVERBS OF PLACE/TIME
+    # ========================================================================
+    'here', 'there', 'now', 'then', 'always', 'never', 'often', 'sometimes',
+    'already', 'still', 'yet', 'soon', 'later', 'ago', 'today', 'tomorrow',
+    'yesterday', 'currently', 'previously', 'recently', 'immediately',
+    'finally', 'eventually', 'meanwhile', 'afterwards',
+
+    # ========================================================================
+    # NEGATION
+    # ========================================================================
+    'no', 'not', 'none', 'never', 'neither', 'nor',
+    'don', 'doesn', 'didn', 'won', 'wouldn', 'couldn', 'shouldn',
+    'isn', 'aren', 'wasn', 'weren', 'hasn', 'haven', 'hadn',
+
+    # ========================================================================
+    # QUANTIFIERS
+    # ========================================================================
+    'some', 'any', 'all', 'each', 'every', 'both', 'few', 'more', 'most',
+    'many', 'much', 'several', 'other', 'another', 'enough', 'less', 'least',
+    'either', 'neither', 'such',
+
+    # ========================================================================
+    # FILLER/HEDGE WORDS
+    # ========================================================================
+    'just', 'also', 'only', 'really', 'actually', 'basically', 'simply',
+    'very', 'quite', 'rather', 'pretty', 'somewhat', 'almost', 'nearly',
+    'exactly', 'completely', 'entirely', 'totally', 'absolutely',
+    'probably', 'possibly', 'maybe', 'perhaps', 'definitely', 'certainly',
+    'apparently', 'obviously', 'clearly', 'literally', 'essentially',
+
+    # ========================================================================
+    # COMMON REQUEST PHRASES (from corpus: high frequency in prompts)
+    # ========================================================================
+    'want', 'need', 'help', 'please', 'like', 'let', 'get',
+    'think', 'know', 'see', 'try', 'make', 'give', 'take',
+    'look', 'looking', 'trying', 'going', 'getting', 'making',
+
+    # ========================================================================
+    # COMMON NON-ACTION VERBS
+    # ========================================================================
+    'go', 'come', 'put', 'say', 'tell', 'ask', 'find', 'keep',
+    'seem', 'appear', 'become', 'remain', 'stay', 'feel', 'show', 'mean',
+    'include', 'provide', 'require', 'allow', 'expect', 'cause',
+    'follow', 'consider', 'continue', 'start', 'begin', 'end',
+    'contain', 'contain', 'contains',
+
+    # ========================================================================
+    # LINKING/TRANSITION WORDS
+    # ========================================================================
+    'however', 'therefore', 'thus', 'hence', 'otherwise', 'instead',
+    'moreover', 'furthermore', 'nevertheless', 'nonetheless', 'accordingly',
+    'consequently', 'similarly', 'likewise', 'conversely', 'alternatively',
+
+    # ========================================================================
+    # CORPUS-DERIVED HIGH-FREQUENCY NOISE (from 1,424 docs analysis)
+    # ========================================================================
+    # Words appearing in >10% of documents that don't identify the task
+
+    # File extensions/technical noise (appear in paths, not task descriptors)
+    'py', 'md', 'ts', 'json', 'js', 'yaml', 'toml', 'exe', 'bat',
+
+    # Common Claude/coding terms that don't identify specific tasks
+    'using', 'used', 'uses',
+    'based', 'following',
+    'same', 'different', 'specific', 'existing', 'new', 'current', 'first',
+    'full', 'complete', 'single', 'multiple', 'simple',
+    'needed', 'required', 'provided', 'expected', 'correctly',
+    'works', 'working', 'work',
+
+    # Common structural words from plan files
+    'step', 'steps', 'phase', 'below', 'above',
+
+    # Query/clarification language (high frequency in prompts)
+    'questions', 'question', 'clarification',
+
+    # Overly generic terms
+    'thing', 'things', 'way', 'ways', 'kind', 'type', 'types',
+    'example', 'examples', 'case', 'cases',
+    'part', 'parts', 'point', 'points',
+    'time', 'times', 'next', 'last', 'end',
+    'set', 'list', 'group', 'item', 'items',
+}

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

@@ -0,0 +1,46 @@
+"""Utilities for subprocess calls that invoke Claude Code CLI.
+
+Provides centralized management of environment flags for internal subprocess calls
+(orchestrator, agents, inference) to prevent recursion and unnecessary hook overhead.
+"""
+import os
+from typing import Dict
+
+# Environment variable names - single source of truth
+ENV_INTERNAL_CALL = "AIWCLI_INTERNAL_CALL"
+
+
+def get_internal_subprocess_env() -> Dict[str, str]:
+    """Get environment dict for internal Claude Code subprocess calls.
+
+    This prevents internal subprocess calls (orchestrator, agents, inference)
+    from triggering hooks that would cause recursion or unnecessary overhead.
+
+    All hooks should check is_internal_call() and return early if True.
+
+    Returns:
+        Environment dict with AIWCLI_INTERNAL_CALL flag set
+
+    Example:
+        >>> env = get_internal_subprocess_env()
+        >>> subprocess.run(['claude', '--agent', 'my-agent'], env=env)
+    """
+    env = os.environ.copy()
+    env[ENV_INTERNAL_CALL] = 'true'
+    return env
+
+
+def is_internal_call() -> bool:
+    """Check if current process is an internal subprocess call.
+
+    Hooks should check this at the beginning and return early to avoid
+    recursion and unnecessary processing for internal subprocess calls.
+
+    Returns:
+        True if this is an internal call that should skip hooks
+
+    Example:
+        >>> if is_internal_call():
+        ...     return  # Skip hook processing
+    """
+    return os.environ.get(ENV_INTERNAL_CALL) == 'true'

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

@@ -157,15 +157,18 @@ def generate_context_id(summary: str, existing_ids: Optional[set] = None) -> str
             from .inference import generate_semantic_summary
             semantic = generate_semantic_summary(summary)
             if semantic:
-                # Slugify the semantic summary
-                base_id = sanitize_title(semantic, max_len=60)
+                # Slugify the semantic summary (word limit already applied in inference)
+                base_id = sanitize_title(semantic, max_len=100)
                 eprint(f"[utils] Semantic context ID: {base_id}")
         except Exception as e:
             eprint(f"[utils] Inference failed, using fallback: {e}")
 
         # Fallback to old method if inference failed
         if not base_id:
-            base_id = sanitize_title(summary[:50])
+            # Fallback: 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)
 
     if not existing_ids:
         return base_id

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

@@ -12,9 +12,6 @@ from .context_manager import (
     update_plan_status,
     get_context_with_pending_plan,
     get_context_with_in_flight_work,
-    update_handoff_status,
-    clear_handoff_status,
-    get_context_with_handoff_pending,
 )
 from .event_log import (
     Task,
@@ -37,13 +34,11 @@ from .discovery import (
     get_in_flight_context,
     format_context_list,
     format_pending_plan_continuation,
-    format_handoff_continuation,
     format_implementation_continuation,
     format_context_picker_prompt,
     format_ready_for_new_work,
 )
 from .task_sync import (
-    generate_hydration_instructions,
     generate_task_summary,
     record_session_start,
     record_task_created,
@@ -77,9 +72,6 @@ __all__ = [
     "update_plan_status",
     "get_context_with_pending_plan",
     "get_context_with_in_flight_work",
-    "update_handoff_status",
-    "clear_handoff_status",
-    "get_context_with_handoff_pending",
     # Event Log
     "append_event",
     "read_events",
@@ -97,12 +89,10 @@ __all__ = [
     "get_in_flight_context",
     "format_context_list",
     "format_pending_plan_continuation",
-    "format_handoff_continuation",
     "format_implementation_continuation",
     "format_context_picker_prompt",
     "format_ready_for_new_work",
     # Task Sync
-    "generate_hydration_instructions",
     "generate_task_summary",
     "record_session_start",
     "record_task_created",

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

@@ -115,13 +115,11 @@ def rebuild_context_from_events(context_dir: Path, project_root: Path = None) ->
             context.in_flight.started_at = None
 
         elif event_type == "handoff_created":
-            context.in_flight.mode = "handoff_pending"
+            # Handoff events are informational only - no mode change
             context.in_flight.handoff_path = event.get("path")
 
         elif event_type == "handoff_cleared":
-            # Restore to "implementing" if artifact exists, otherwise "none"
-            restored_mode = event.get("restored_mode", "none")
-            context.in_flight.mode = restored_mode
+            # Legacy event - just clear handoff_path, no mode change
             context.in_flight.handoff_path = None
 
     return context

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

@@ -933,132 +933,15 @@ def get_context_with_in_flight_work(project_root: Path = None) -> Optional[Conte
     return None
 
 
-def update_handoff_status(
-    context_id: str,
-    handoff_path: str,
-    project_root: Path = None
-) -> Optional[Context]:
-    """
-    Update context to indicate a handoff is pending.
-
-    Called by handoff document generator after creating handoff document.
-    Sets in_flight.mode = "handoff_pending" and in_flight.handoff_path.
-
-    Args:
-        context_id: Context identifier
-        handoff_path: Path to the handoff document
-        project_root: Project root directory
-
-    Returns:
-        Updated Context or None if not found
-    """
-    context = get_context(context_id, project_root)
-    if not context:
-        return None
-
-    now = now_iso()
-
-    # Update in_flight state
-    context.in_flight.mode = "handoff_pending"
-    context.in_flight.handoff_path = handoff_path
-    context.in_flight.started_at = now
-    context.last_active = now
-
-    # Append event (source of truth) - MUST happen before cache updates
-    append_event(
-        context_id,
-        EVENT_HANDOFF_CREATED,
-        project_root,
-        path=handoff_path
-    )
-
-    # Update caches
-    _write_context_cache(context, project_root)
-    _update_index_cache(context, project_root)
-
-    eprint(f"[context_manager] Set handoff pending for: {context_id}")
-    return context
-
-
-def clear_handoff_status(context_id: str, project_root: Path = None) -> Optional[Context]:
-    """
-    Clear handoff pending status after resumption.
-
-    Called by SessionStart after successfully resuming from handoff.
-
-    Args:
-        context_id: Context identifier
-        project_root: Project root directory
-
-    Returns:
-        Updated Context or None if not found
-    """
-    context = get_context(context_id, project_root)
-    if not context:
-        return None
-
-    if context.in_flight.mode != "handoff_pending":
-        return context  # Nothing to clear
-
-    now = now_iso()
-
-    # Clear handoff state but preserve any artifact path (plan being implemented)
-    # If artifact_path exists, restore to "implementing" mode; otherwise "none"
-    if context.in_flight.artifact_path:
-        context.in_flight.mode = "implementing"
-    else:
-        context.in_flight.mode = "none"
-    context.in_flight.handoff_path = None
-    # Don't clear started_at if we're still implementing
-    if not context.in_flight.artifact_path:
-        context.in_flight.started_at = None
-    context.last_active = now
-
-    # Append event (source of truth) - MUST happen before cache updates
-    append_event(
-        context_id,
-        EVENT_HANDOFF_CLEARED,
-        project_root,
-        restored_mode=context.in_flight.mode
-    )
-
-    # Update caches
-    _write_context_cache(context, project_root)
-    _update_index_cache(context, project_root)
-
-    eprint(f"[context_manager] Cleared handoff status for: {context_id}")
-    return context
-
-
-def get_context_with_handoff_pending(project_root: Path = None) -> Optional[Context]:
-    """
-    Find context with handoff pending (highest priority for SessionStart).
-
-    Args:
-        project_root: Project root directory
-
-    Returns:
-        Context with handoff pending, or None if not found
-    """
-    contexts = get_all_contexts(status="active", project_root=project_root)
-
-    for context in contexts:
-        if context.in_flight and context.in_flight.mode == "handoff_pending":
-            return context
-
-    return None
-
-
 def get_all_in_flight_contexts(project_root: Path = None) -> List[Context]:
     """
     Return all contexts with truly in-flight work requiring attention.
 
     In-flight modes (require continuation/action):
-    - planning: Active planning session
     - pending_implementation: Plan created, awaiting implementation
-    - handoff_pending: Handoff document created, awaiting pickup
 
     NOT in-flight (normal working state):
+    - planning: Active planning session (doesn't auto-select context)
     - implementing: Active work, but doesn't block new context creation
     - none: No active work
 
@@ -1073,7 +956,7 @@ def get_all_in_flight_contexts(project_root: Path = None) -> List[Context]:
     Returns:
         List of contexts with in-flight work requiring attention
     """
-    IN_FLIGHT_MODES = {"planning", "pending_implementation", "handoff_pending"}
+    IN_FLIGHT_MODES = {"pending_implementation"}
     contexts = get_all_contexts(status="active", project_root=project_root)
     return [c for c in contexts if c.in_flight and c.in_flight.mode in IN_FLIGHT_MODES]
 

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

@@ -42,13 +42,12 @@ def discover_contexts_for_session(
 
 def get_in_flight_context(project_root: Path = None) -> Optional[Context]:
     """
-    Get context with any in-flight work (plan, handoff, etc.).
+    Get context with any in-flight work (plan, etc.).
 
     Priority order:
-    1. handoff_pending - highest priority (user was interrupted)
-    2. pending_implementation - plan ready for implementation
-    3. implementing - implementation in progress
-    4. planning - actively planning
+    1. pending_implementation - plan ready for implementation
+    2. implementing - implementation in progress
+    3. planning - actively planning
 
     Args:
         project_root: Project root directory
@@ -60,15 +59,14 @@ def get_in_flight_context(project_root: Path = None) -> Optional[Context]:
 
     # Sort by in-flight priority
     priority_order = {
-        "handoff_pending": 0,
-        "pending_implementation": 1,
-        "implementing": 2,
-        "planning": 3,
+        "pending_implementation": 0,
+        "implementing": 1,
+        "planning": 2,
         "none": 99,
     }
 
     # Only auto-continue for high-priority modes (not "implementing", "planning" or "none")
-    actionable_modes = {"handoff_pending", "pending_implementation"}
+    actionable_modes = {"pending_implementation"}
 
     in_flight_contexts = [
         c for c in contexts
@@ -177,46 +175,6 @@ def format_pending_plan_continuation(context: Context) -> str:
     return "\n".join(lines)
 
 
-def format_handoff_continuation(context: Context) -> str:
-    """
-    Format output for handoff continuation scenario.
-
-    This is shown when SessionStart detects a context with
-    in_flight.mode = "handoff_pending".
-
-    Args:
-        context: Context with handoff pending
-
-    Returns:
-        Formatted instructions for Claude
-    """
-    lines = [
-        format_continuation_header("resuming", context.id),
-        "",
-        f"**Summary:** {context.summary}",
-        "",
-    ]
-
-    # Add handoff document link
-    if context.in_flight and context.in_flight.handoff_path:
-        lines.append(f"**Handoff document:**")
-        lines.append(f"`{context.in_flight.handoff_path}`")
-        lines.append("")
-
-    lines.extend([
-        "---",
-        "",
-        "**Instructions:**",
-        "1. Read the handoff document above",
-        "2. Use TaskCreate to restore pending tasks",
-        "3. Continue where the previous session left off",
-        "",
-        "The context has been loaded. You may continue.",
-    ])
-
-    return "\n".join(lines)
-
-
 def format_implementation_continuation(context: Context) -> str:
     """
     Format output for ongoing implementation scenario.

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

@@ -1,22 +1,17 @@
 """Task synchronization utilities for Claude native task integration.
 
-Provides bi-directional sync between:
+Provides persistence for Claude Code native tasks:
 - Claude Code native TaskCreate/TaskUpdate/TaskList tools (ephemeral)
 - Persistent events.jsonl storage (source of truth)
 
-SESSION START (Hydrate):
-1. Read events.jsonl -> compute pending tasks
-2. Output instructions for Claude to recreate tasks via TaskCreate
-3. Claude's native TaskList now populated with persistent state
-
 DURING SESSION (Persist):
 1. Claude uses native TaskCreate/TaskUpdate
-2. CLAUDE.md instructs: after TaskUpdate, call append_event()
-3. Both systems stay in sync
+2. PostToolUse hooks capture events to events.jsonl
+3. Task state preserved for future reference
 
 SESSION END:
-- events.jsonl already has everything
-- Next session will hydrate from it
+- events.jsonl has complete task history
+- Can be queried for context summaries
 """
 from pathlib import Path
 from typing import List, Optional
@@ -35,78 +30,6 @@ from .event_log import (
 from ..base.utils import eprint
 
 
-def _escape_string(s: str) -> str:
-    """
-    Escape a string for safe embedding in quoted YAML-like format.
-
-    Handles backslashes, newlines, tabs, and quotes.
-
-    Args:
-        s: Input string
-
-    Returns:
-        Escaped string safe for embedding in double quotes
-    """
-    if not s:
-        return ""
-    # Order matters: escape backslashes first, then other special chars
-    s = s.replace('\\', '\\\\')
-    s = s.replace('\n', '\\n')
-    s = s.replace('\r', '\\r')
-    s = s.replace('\t', '\\t')
-    s = s.replace('"', '\\"')
-    return s
-
-
-def generate_hydration_instructions(
-    context_id: str,
-    project_root: Path = None
-) -> str:
-    """
-    Generate instructions for Claude to recreate tasks from persistent storage.
-
-    Called by SessionStart hook when resuming a context.
-
-    Args:
-        context_id: Context identifier
-        project_root: Project root directory
-
-    Returns:
-        Formatted instructions for Claude to restore tasks
-    """
-    pending_tasks = get_pending_tasks(context_id, project_root)
-
-    if not pending_tasks:
-        return "No pending tasks to restore."
-
-    lines = [
-        "## Restoring Tasks from Previous Session",
-        "",
-        "Please recreate these tasks using TaskCreate:",
-        "",
-    ]
-
-    for task in pending_tasks:
-        lines.append(f"### Task: {task.subject}")
-        lines.append("")
-        lines.append("```")
-        lines.append("TaskCreate:")
-        # Escape special characters for YAML-like format
-        subject_escaped = _escape_string(task.subject)
-        lines.append(f'  subject: "{subject_escaped}"')
-        if task.description:
-            desc_escaped = _escape_string(task.description)
-            lines.append(f'  description: "{desc_escaped}"')
-        if task.active_form:
-            active_form_escaped = _escape_string(task.active_form)
-            lines.append(f'  activeForm: "{active_form_escaped}"')
-        lines.append(f'  metadata: {{"persistent_id": "{task.id}", "context": "{context_id}", "skip_persistence": true}}')
-        lines.append("```")
-        lines.append("")
-
-    return "\n".join(lines)
-
-
 def generate_task_summary(context_id: str, project_root: Path = None) -> str:
     """
     Generate a summary of all tasks in a context.

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

@@ -83,7 +83,7 @@ def generate_handoff_document(
     Returns:
         HandoffDocument with file_path set, or None on failure
     """
-    from ..context.context_manager import get_context, update_handoff_status
+    from ..context.context_manager import get_context
 
     context = get_context(context_id, project_root)
     if not context:
@@ -141,7 +141,7 @@ def generate_handoff_document(
         eprint(f"[handoff] ERROR: Failed to write handoff document: {error}")
         return None
 
-    # Record event
+    # Record event (informational only - no mode change)
     append_event(
         context_id,
         EVENT_HANDOFF_CREATED,
@@ -151,9 +151,6 @@ def generate_handoff_document(
         session_id=session_id
     )
 
-    # Update context in_flight state
-    update_handoff_status(context_id, str(file_path), project_root)
-
     eprint(f"[handoff] Created handoff document: {file_path}")
     return doc
 

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

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