@hustle-together/api-dev-tools 3.12.3 → 4.5.1

package/hooks/completion-promise-detector.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+Completion Promise Detector Hook (Ralph Wiggum Pattern)
+
+Detects when the agent outputs a completion promise signal like:
+  <promise>DONE</promise>
+  <promise>FIXED</promise>
+  <promise>REFACTORED</promise>
+  <promise>COMPLETE</promise>
+
+This enables autonomous loops to self-terminate gracefully when work is done,
+rather than relying solely on max-iterations safety nets.
+
+Hook Type: PostToolUse (monitors Bash, Write, Edit outputs)
+           Stop (allows graceful termination)
+
+References:
+- Geoffrey Huntley's Ralph Wiggum Technique: https://ghuntley.com/ralph/
+- docs/CLAUDE_CODE_BEST_PRACTICES.md - Section on autonomous loops
+
+Updated in v4.5.0:
+  - Add workflow logging for promise_emitted events
+  - Add iteration counting and max-iterations enforcement
+  - Log phase_transition events
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# Import shared utilities for logging and iteration tracking (v4.5.0)
+try:
+    from hook_utils import (
+        log_workflow_event,
+        increment_phase_iteration,
+        get_phase_iterations
+    )
+    UTILS_AVAILABLE = True
+except ImportError:
+    UTILS_AVAILABLE = False
+
+# Completion promise patterns
+PROMISE_PATTERNS = [
+    r'<promise>(DONE|COMPLETE|FINISHED|SUCCESS)</promise>',
+    r'<promise>(FIXED|RESOLVED|SOLVED)</promise>',
+    r'<promise>(REFACTORED|CLEANED|IMPROVED)</promise>',
+    r'<promise>(TESTED|VERIFIED|VALIDATED)</promise>',
+    r'<promise>(DEPLOYED|SHIPPED|RELEASED)</promise>',
+    # Custom promises defined in state
+]
+
+# State file for tracking promises
+STATE_FILE = '.claude/completion-promises.json'
+
+
+def load_state():
+    """Load completion promise state."""
+    state_path = Path(STATE_FILE)
+    if state_path.exists():
+        try:
+            return json.loads(state_path.read_text())
+        except json.JSONDecodeError:
+            pass
+    return {
+        'active_promise': None,
+        'custom_patterns': [],
+        'history': []
+    }
+
+
+def save_state(state):
+    """Save completion promise state."""
+    state_path = Path(STATE_FILE)
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    state_path.write_text(json.dumps(state, indent=2))
+
+
+def get_all_patterns(state):
+    """Get all promise patterns including custom ones."""
+    patterns = PROMISE_PATTERNS.copy()
+    for custom in state.get('custom_patterns', []):
+        patterns.append(rf'<promise>({custom})</promise>')
+    return patterns
+
+
+def detect_promise(text, state):
+    """Detect if text contains a completion promise."""
+    if not text:
+        return None
+
+    patterns = get_all_patterns(state)
+    for pattern in patterns:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if match:
+            return match.group(1).upper()
+    return None
+
+
+def handle_post_tool_use():
+    """Handle PostToolUse event - detect promises in tool output."""
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        return
+
+    tool_name = hook_input.get('tool_name', '')
+    tool_result = hook_input.get('tool_result', '')
+
+    # Only check tools that produce output
+    if tool_name not in ['Bash', 'Write', 'Edit', 'Read']:
+        return
+
+    state = load_state()
+
+    # v4.5.0: Check iteration limits for tools that indicate phase progress
+    if tool_name in ['Write', 'Edit'] and UTILS_AVAILABLE:
+        try:
+            # Detect current phase from context or state
+            current_phase = state.get('current_phase', 'unknown')
+            current_iter, max_iter, exceeded = increment_phase_iteration(current_phase)
+
+            if exceeded:
+                # Log the limit exceeded event
+                log_workflow_event("iteration_limit_exceeded", {
+                    "phase": current_phase,
+                    "current": current_iter,
+                    "limit": max_iter
+                })
+
+                print(json.dumps({
+                    'result': 'block',
+                    'message': f"""
+{'='*60}
+ MAX ITERATIONS EXCEEDED: {current_phase}
+{'='*60}
+
+Current iteration: {current_iter}
+Limit: {max_iter}
+
+The autonomous loop has exceeded the maximum iterations for this phase.
+This is a safety mechanism to prevent infinite loops.
+
+To continue:
+- Run /ralph-continue to reset and proceed
+- Or increase max_iterations in hustle-build-defaults.json
+"""
+                }))
+                return
+        except Exception:
+            pass
+
+    # Check for promise in output
+    promise = detect_promise(str(tool_result), state)
+
+    if promise:
+        # Record the promise detection
+        state['active_promise'] = promise
+        state['history'].append({
+            'promise': promise,
+            'tool': tool_name,
+            'detected_at': datetime.now().isoformat(),
+        })
+
+        # Keep only last 50 history entries
+        state['history'] = state['history'][-50:]
+        save_state(state)
+
+        # v4.5.0: Log the promise detection
+        if UTILS_AVAILABLE:
+            try:
+                log_workflow_event("promise_emitted", {
+                    "promise": promise,
+                    "tool": tool_name,
+                    "phase": state.get('current_phase', 'unknown')
+                })
+            except Exception:
+                pass
+
+        # Output notification
+        print(json.dumps({
+            'result': 'continue',
+            'message': f"\n{'='*60}\n COMPLETION PROMISE DETECTED: {promise}\n{'='*60}\n\nThe autonomous loop can now terminate gracefully.\nTo continue anyway, use: /ralph-continue\n"
+        }))
+        return
+
+    # No promise detected, continue normally
+    print(json.dumps({'result': 'continue'}))
+
+
+def handle_stop():
+    """Handle Stop event - check if we should allow graceful termination."""
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        print(json.dumps({'result': 'continue'}))
+        return
+
+    state = load_state()
+    active_promise = state.get('active_promise')
+
+    if active_promise:
+        # Clear the active promise
+        state['active_promise'] = None
+        save_state(state)
+
+        # Allow graceful termination with summary
+        print(json.dumps({
+            'result': 'continue',
+            'message': f"\n AUTONOMOUS LOOP COMPLETE \n\nCompletion promise '{active_promise}' was fulfilled.\nThe agent has signaled that the task is done.\n"
+        }))
+    else:
+        # No active promise, continue with normal stop behavior
+        print(json.dumps({'result': 'continue'}))
+
+
+def handle_user_prompt():
+    """Handle UserPromptSubmit - detect promise configuration."""
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        print(json.dumps({'result': 'continue'}))
+        return
+
+    prompt = hook_input.get('prompt', '').lower()
+    state = load_state()
+
+    # Check for Ralph Wiggum loop start
+    if '/ralph-loop' in prompt or '--completion-promise' in prompt:
+        # Extract custom promise if specified
+        match = re.search(r'--completion-promise\s+["\']?(\w+)["\']?', prompt, re.IGNORECASE)
+        if match:
+            custom_promise = match.group(1).upper()
+            if custom_promise not in state.get('custom_patterns', []):
+                state.setdefault('custom_patterns', []).append(custom_promise)
+                save_state(state)
+
+        print(json.dumps({
+            'result': 'continue',
+            'message': f"\n RALPH WIGGUM LOOP INITIALIZED \n\nListening for completion promises:\n- DONE, COMPLETE, FINISHED, SUCCESS\n- FIXED, RESOLVED, SOLVED\n- REFACTORED, CLEANED, IMPROVED\n- TESTED, VERIFIED, VALIDATED\n- DEPLOYED, SHIPPED, RELEASED\n{f'- {custom_promise} (custom)' if match else ''}\n\nOutput <promise>DONE</promise> when the task is complete.\n"
+        }))
+        return
+
+    # Check for continue command
+    if '/ralph-continue' in prompt:
+        state['active_promise'] = None
+        save_state(state)
+        print(json.dumps({
+            'result': 'continue',
+            'message': "Cleared active promise. Autonomous loop will continue."
+        }))
+        return
+
+    # Check for status command
+    if '/ralph-status' in prompt:
+        active = state.get('active_promise', 'None')
+        history = state.get('history', [])[-5:]
+
+        status_msg = f"\n RALPH WIGGUM STATUS \n\nActive Promise: {active}\n\nRecent History:\n"
+        for h in history:
+            status_msg += f"  - {h.get('promise')} via {h.get('tool')} at {h.get('detected_at', 'unknown')[:19]}\n"
+
+        if not history:
+            status_msg += "  (no promises detected yet)\n"
+
+        print(json.dumps({
+            'result': 'continue',
+            'message': status_msg
+        }))
+        return
+
+    print(json.dumps({'result': 'continue'}))
+
+
+def main():
+    """Main entry point - determine hook type from environment."""
+    hook_type = os.environ.get('CLAUDE_HOOK_TYPE', 'PostToolUse')
+
+    if hook_type == 'PostToolUse':
+        handle_post_tool_use()
+    elif hook_type == 'Stop':
+        handle_stop()
+    elif hook_type == 'UserPromptSubmit':
+        handle_user_prompt()
+    else:
+        # Unknown hook type, pass through
+        print(json.dumps({'result': 'continue'}))
+
+
+if __name__ == '__main__':
+    main()

package/hooks/context-capacity-warning.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse
+Purpose: Warn when context capacity reaches thresholds
+
+Monitors estimated context usage and warns at:
+- 50% capacity: Suggest summarizing or compacting
+- 75% capacity: Urgent warning, recommend /summarize
+- 90% capacity: Critical, workflow may be interrupted
+
+Uses token tracking from api-dev-state.json to estimate context size.
+
+Version: 4.0.0
+"""
+import json
+import sys
+from pathlib import Path
+from datetime import datetime
+
+# Context window sizes for Claude models (approximate)
+MODEL_CONTEXT_LIMITS = {
+    "claude-3-opus": 200000,
+    "claude-opus-4": 200000,
+    "claude-opus-4-5": 200000,
+    "claude-3-sonnet": 200000,
+    "claude-sonnet-4": 200000,
+    "claude-3-haiku": 200000,
+    "claude-3-5-sonnet": 200000,
+    "claude-3-5-haiku": 200000,
+    "default": 200000,
+}
+
+# Warning thresholds
+THRESHOLDS = {
+    "info": 0.50,      # 50% - informational
+    "warning": 0.75,   # 75% - warning
+    "critical": 0.90,  # 90% - critical
+}
+
+
+def estimate_context_usage(state: dict) -> int:
+    """
+    Estimate current context usage from state file.
+
+    Uses token tracking data to estimate how much of the
+    context window has been consumed.
+    """
+    token_usage = state.get("token_usage", {})
+    by_phase = token_usage.get("by_phase", {})
+
+    if not by_phase:
+        return 0
+
+    # Get latest phase token count
+    phase_keys = list(by_phase.keys())
+    if phase_keys:
+        latest = by_phase[phase_keys[-1]]
+        return latest.get("total_tokens", 0)
+
+    return 0
+
+
+def get_context_limit() -> int:
+    """Get the context limit for the current model."""
+    # Default to 200k for Opus/Sonnet
+    return MODEL_CONTEXT_LIMITS.get("default", 200000)
+
+
+def format_warning(level: str, usage_pct: float, tokens: int, limit: int) -> str:
+    """Format the warning message based on level."""
+    remaining = limit - tokens
+
+    if level == "info":
+        return f"""
+📊 Context Usage: {usage_pct:.0%}
+   Tokens used: ~{tokens:,} / {limit:,}
+   Remaining: ~{remaining:,}
+
+   💡 Consider running /summarize to reduce context usage.
+"""
+    elif level == "warning":
+        return f"""
+⚠️  CONTEXT WARNING: {usage_pct:.0%} CAPACITY
+   Tokens used: ~{tokens:,} / {limit:,}
+   Remaining: ~{remaining:,}
+
+   🔧 Recommended actions:
+   1. Run /summarize to compact conversation
+   2. Complete current phase before starting new work
+   3. Consider splitting remaining work into new session
+"""
+    else:  # critical
+        return f"""
+🚨 CRITICAL: CONTEXT AT {usage_pct:.0%} CAPACITY
+   Tokens used: ~{tokens:,} / {limit:,}
+   Remaining: ~{remaining:,}
+
+   ⚡ IMMEDIATE ACTION REQUIRED:
+   1. Run /summarize NOW
+   2. Complete or save current work
+   3. Context may auto-compact soon
+   4. Risk of work interruption if limit reached
+"""
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    # Read state file
+    cwd = Path.cwd()
+    state_file = cwd / ".claude" / "api-dev-state.json"
+
+    if not state_file.exists():
+        sys.exit(0)
+
+    try:
+        state = json.loads(state_file.read_text())
+    except (json.JSONDecodeError, IOError):
+        sys.exit(0)
+
+    # Estimate context usage
+    tokens_used = estimate_context_usage(state)
+    context_limit = get_context_limit()
+    usage_pct = tokens_used / context_limit if context_limit > 0 else 0
+
+    # Check if we've already warned at this level
+    capacity_state = state.get("capacity_warnings", {})
+    last_warning_level = capacity_state.get("last_level", "")
+
+    # Determine warning level
+    warning_level = None
+    if usage_pct >= THRESHOLDS["critical"]:
+        warning_level = "critical"
+    elif usage_pct >= THRESHOLDS["warning"]:
+        warning_level = "warning"
+    elif usage_pct >= THRESHOLDS["info"]:
+        warning_level = "info"
+
+    # Only warn if level has increased
+    level_order = {"": 0, "info": 1, "warning": 2, "critical": 3}
+    should_warn = (
+        warning_level and
+        level_order.get(warning_level, 0) > level_order.get(last_warning_level, 0)
+    )
+
+    if should_warn:
+        # Output warning
+        warning_msg = format_warning(warning_level, usage_pct, tokens_used, context_limit)
+        print(warning_msg, file=sys.stderr)
+
+        # Update state to track warning
+        state["capacity_warnings"] = {
+            "last_level": warning_level,
+            "last_warning_at": datetime.now().isoformat(),
+            "tokens_at_warning": tokens_used,
+        }
+
+        try:
+            state_file.write_text(json.dumps(state, indent=2))
+        except IOError:
+            pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/docs-update-check.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Documentation Update Check Hook
+
+Triggers after significant file changes to remind about documentation updates.
+Runs on PostToolUse for Write/Edit operations.
+
+Hook Type: PostToolUse
+Tools: Write, Edit
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# Import hook utilities
+try:
+    from hook_utils import is_source_repository
+except ImportError:
+    def is_source_repository():
+        return Path(".git").exists() and Path("package.json").exists() and \
+               "api-dev-tools" in Path("package.json").read_text()
+
+def get_tool_input():
+    """Parse tool input from environment."""
+    tool_input = os.environ.get("TOOL_INPUT", "{}")
+    try:
+        return json.loads(tool_input)
+    except json.JSONDecodeError:
+        return {}
+
+def get_file_category(file_path: str) -> str | None:
+    """Categorize file by type for doc update needs."""
+    path = Path(file_path)
+
+    if ".skills/" in file_path and file_path.endswith("SKILL.md"):
+        return "skill"
+    if "hooks/" in file_path and file_path.endswith(".py"):
+        return "hook"
+    if ".claude/agents/" in file_path and file_path.endswith(".md"):
+        return "agent"
+    if "docs/" in file_path and file_path.endswith(".md"):
+        return "doc"
+    if "templates/" in file_path and file_path.endswith(".tsx"):
+        return "template"
+    if file_path.endswith("registry.json"):
+        return "registry"
+
+    return None
+
+def check_needs_doc_update(file_path: str) -> dict:
+    """Check if file change needs documentation update."""
+    category = get_file_category(file_path)
+
+    if not category:
+        return {"needs_update": False}
+
+    updates_needed = []
+
+    if category == "skill":
+        skill_name = Path(file_path).parent.name
+        updates_needed.append(f"docs/SKILLS.md - Add {skill_name} skill")
+        updates_needed.append(f"README.md - Update skills count if new")
+        updates_needed.append(f"CHANGELOG.md - Add entry for new skill")
+
+    elif category == "hook":
+        hook_name = Path(file_path).stem
+        updates_needed.append(f"docs/HOOKS.md - Add {hook_name} hook")
+        updates_needed.append(f"README.md - Update hooks count if new")
+
+    elif category == "agent":
+        agent_name = Path(file_path).stem
+        updates_needed.append(f"docs/AGENTS.md - Add {agent_name} agent")
+        updates_needed.append(f"README.md - Update agents count if new")
+
+    elif category == "doc":
+        doc_name = Path(file_path).name
+        updates_needed.append(f"README.md - Link to {doc_name} in Documentation section")
+
+    elif category == "template":
+        template_name = Path(file_path).stem
+        updates_needed.append(f"Consider dashboard integration for {template_name}")
+
+    elif category == "registry":
+        updates_needed.append("Check if new registry sections need documentation")
+
+    return {
+        "needs_update": len(updates_needed) > 0,
+        "category": category,
+        "file": file_path,
+        "updates_needed": updates_needed
+    }
+
+def main():
+    # Skip if in source repository (we're building the tool itself)
+    if is_source_repository():
+        # Even in source, we want reminders - just softer ones
+        pass
+
+    tool_input = get_tool_input()
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path:
+        return
+
+    result = check_needs_doc_update(file_path)
+
+    if result["needs_update"]:
+        # Output reminder (shown to user)
+        print(f"\n📝 Documentation Update Reminder")
+        print(f"   File: {result['file']}")
+        print(f"   Category: {result['category']}")
+        print(f"\n   Consider updating:")
+        for update in result["updates_needed"]:
+            print(f"   • {update}")
+        print(f"\n   Run /docs-update to auto-check all documentation.\n")
+
+if __name__ == "__main__":
+    main()