@codeyam/codeyam-cli 0.1.0-staging.6e699e5 → 0.1.0-staging.79ef713

package/codeyam-cli/templates/rule-reflection-hook.py

@@ -0,0 +1,590 @@
+#!/usr/bin/env python3
+"""
+Rule reflection hook for Claude Code.
+
+Handles two hook events:
+1. Stop — Reviews completed turns for stale rules and conversation confusion signals
+2. UserPromptSubmit — Detects user interruptions (Escape/Ctrl+C) by checking if the
+   Stop hook's marker file is stale, then spawns a rule-reflection agent focused on
+   the interruption signal
+
+Each review fires as a separate `claude -p` invocation so the LLM can focus on one task at a time.
+Stays silent if there's nothing to review.
+
+Prompt text lives in templates/prompts/*.txt (single source of truth shared with TypeScript tests).
+"""
+
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+MIN_USER_TURNS = 3  # Minimum user turns before checking for confusion
+
+# Signals that indicate confusion, mistakes, or user corrections
+CONFUSION_SIGNALS = [
+    'no,', 'no ', "that's not", "thats not", "that is not",
+    'wrong', 'incorrect', 'actually,', 'actually ',
+    "i meant", "i mean", "not what i", "stop", "wait",
+    "don't do", "dont do", "shouldn't", "should not",
+    "try again", "let me clarify", "to clarify",
+    "that broke", "that failed", "error", "bug",
+]
+
+# Prompt templates directory — installed alongside this hook in .codeyam/bin/prompts/
+PROMPTS_DIR = Path(__file__).parent / 'prompts'
+
+
+def load_prompt_template(name, **kwargs):
+    """
+    Load a prompt template from the prompts/ directory and substitute placeholders.
+    Placeholders use {{KEY}} syntax (e.g., {{CONTEXT_FILE}}, {{PROJECT_DIR}}).
+    """
+    template_path = PROMPTS_DIR / name
+    text = template_path.read_text()
+    for key, value in kwargs.items():
+        text = text.replace(f'{{{{{key}}}}}', str(value))
+    return text
+
+
+def has_confusion_signals(conversation_snippets):
+    """
+    Check if the conversation contains signals of confusion or user corrections.
+    Returns True if confusion signals are detected.
+    """
+    for snippet in conversation_snippets:
+        if snippet['role'] != 'user':
+            continue
+        content_lower = snippet['content'].lower()
+        for signal in CONFUSION_SIGNALS:
+            if signal in content_lower:
+                return True
+    return False
+
+
+def get_file_diff(file_path, max_lines=50):
+    """
+    Get git diff for a file. Tries staged diff first, then unstaged.
+    Returns truncated diff string or empty string.
+    """
+    for diff_cmd in [
+        ['git', 'diff', 'HEAD', '--', file_path],
+        ['git', 'diff', '--', file_path],
+    ]:
+        try:
+            result = subprocess.run(
+                diff_cmd, capture_output=True, text=True, timeout=10
+            )
+            if result.stdout.strip():
+                lines = result.stdout.strip().split('\n')
+                # Skip the diff header (--- a/, +++ b/, @@ lines)
+                content_lines = [l for l in lines if not l.startswith('diff ') and
+                                 not l.startswith('index ') and not l.startswith('--- ') and
+                                 not l.startswith('+++ ')]
+                if len(content_lines) > max_lines:
+                    content_lines = content_lines[:max_lines] + [f'... ({len(lines) - max_lines} more lines)']
+                return '\n'.join(content_lines)
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            continue
+    return ''
+
+
+def read_rule_content(rule_name):
+    """
+    Read a rule file and return its content after YAML frontmatter.
+    Searches in .claude/rules/ directory.
+    """
+    # Search for the rule file
+    rules_dir = Path('.claude/rules')
+    if not rules_dir.exists():
+        return ''
+
+    # Find the file - could be at any depth
+    matches = list(rules_dir.rglob(rule_name))
+    if not matches:
+        return ''
+
+    try:
+        text = matches[0].read_text()
+    except IOError:
+        return ''
+
+    # Strip YAML frontmatter
+    if text.startswith('---'):
+        end = text.find('---', 3)
+        if end != -1:
+            text = text[end + 3:].strip()
+
+    return text
+
+
+def get_stale_rules():
+    """
+    Run `codeyam memory status` and parse the output to find stale rules.
+    Returns a list of dicts with rule info, or empty list if none stale.
+    """
+    try:
+        # Use the local codeyam CLI via node to avoid PATH issues
+        project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+        codeyam_js = os.path.join(project_dir, 'codeyam-cli', 'dist', 'codeyam-cli', 'src', 'codeyam-cli.js')
+        if os.path.exists(codeyam_js):
+            cmd = ['node', '--no-warnings', codeyam_js, 'memory', 'status']
+        else:
+            cmd = ['codeyam', 'memory', 'status']
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+        output = result.stdout
+
+        # Check if there are stale rules
+        if 'Found' not in output or 'stale rule' not in output:
+            return []
+
+        # Parse the output to extract stale rule information
+        stale_rules = []
+        lines = output.split('\n')
+        i = 0
+        while i < len(lines):
+            line = lines[i].strip()
+            # Look for rule filenames (lines that end with .md and aren't indented much)
+            if line.endswith('.md') and not line.startswith('Rule') and not line.startswith('Newest'):
+                rule_info = {'name': line}
+                # Look for the next few lines for details
+                for j in range(i + 1, min(i + 4, len(lines))):
+                    detail = lines[j].strip()
+                    if detail.startswith('Rule timestamp:'):
+                        rule_info['rule_timestamp'] = detail.replace('Rule timestamp:', '').strip()
+                    elif detail.startswith('Newest file:'):
+                        rule_info['newest_file'] = detail.replace('Newest file:', '').strip()
+                    elif detail.startswith('File modified:'):
+                        rule_info['file_modified'] = detail.replace('File modified:', '').strip()
+                # Get diff for the changed file
+                if rule_info.get('newest_file'):
+                    rule_info['diff'] = get_file_diff(rule_info['newest_file'])
+
+                # Get inline rule content
+                rule_info['rule_content'] = read_rule_content(rule_info['name'])
+
+                stale_rules.append(rule_info)
+            i += 1
+
+        return stale_rules
+    except (subprocess.TimeoutExpired, FileNotFoundError, Exception):
+        return []
+
+
+def get_conversation_context(transcript_path, last_line):
+    """
+    Extract conversation snippets and modified files from transcript for rule review.
+    Returns (user_turn_count, conversation_snippets, modified_files, current_line_count)
+    """
+    try:
+        with open(transcript_path, 'r') as f:
+            all_lines = f.readlines()
+    except IOError:
+        return 0, [], set(), 0
+
+    current_line_count = len(all_lines)
+    new_lines = all_lines[last_line:]
+
+    if not new_lines:
+        return 0, [], set(), current_line_count
+
+    user_turn_count = 0
+    conversation_snippets = []
+    modified_files = set()
+
+    for line in new_lines:
+        try:
+            obj = json.loads(line)
+            msg_type = obj.get('type')
+
+            if msg_type not in ('user', 'assistant'):
+                continue
+
+            message = obj.get('message', {})
+            content = message.get('content', '')
+            is_external_user = msg_type == 'user' and obj.get('userType') == 'external'
+
+            # Handle string content
+            if isinstance(content, str):
+                if obj.get('isMeta') or len(content) < 20:
+                    continue
+                if content.startswith('[{') or '<tool_result' in content:
+                    continue
+
+                if is_external_user and not content.startswith('<'):
+                    user_turn_count += 1
+
+                conversation_snippets.append({
+                    'role': message.get('role', msg_type),
+                    'content': content
+                })
+
+            elif isinstance(content, list):
+                for item in content:
+                    if not isinstance(item, dict):
+                        continue
+
+                    # Extract text snippets
+                    if item.get('type') == 'text':
+                        text = item.get('text', '')
+                        if len(text) > 20:
+                            conversation_snippets.append({
+                                'role': message.get('role', msg_type),
+                                'content': text
+                            })
+
+                    # Track file modifications from tool_use entries
+                    if item.get('type') == 'tool_use':
+                        tool_name = item.get('name', '')
+                        tool_input = item.get('input', {})
+                        if tool_name in ('Edit', 'Write') and tool_input.get('file_path'):
+                            modified_files.add((tool_input['file_path'], tool_name))
+
+        except (json.JSONDecodeError, KeyError):
+            continue
+
+    return user_turn_count, conversation_snippets, modified_files, current_line_count
+
+
+def has_assistant_messages(transcript_path, start_line):
+    """
+    Check if there are any assistant messages in the transcript after start_line.
+    Used to confirm Claude actually started responding before treating a gap as an interruption.
+    """
+    try:
+        with open(transcript_path, 'r') as f:
+            all_lines = f.readlines()
+    except IOError:
+        return False
+
+    for line in all_lines[start_line:]:
+        try:
+            obj = json.loads(line)
+            if obj.get('type') == 'assistant':
+                return True
+        except (json.JSONDecodeError, KeyError):
+            continue
+
+    return False
+
+
+def build_stale_rules_context(stale_rules):
+    """Build context content for stale rules review."""
+    parts = []
+    parts.append("# Reflection Step\n")
+    parts.append("Please review the stale rules below to determine if any need updating based on recent code changes.\n")
+    parts.append("Please show your thinking regarding the stale rules.\n")
+    parts.append("## Stale Rules to Review\n")
+    parts.append("The following rules have files that changed since the rule was last reviewed.")
+    parts.append("For each rule, review the rule content and the diff of changes, then:")
+    parts.append("1. Determine if the rule content needs updating based on the code changes")
+    parts.append("2. Update the rule if needed")
+    parts.append("3. ALWAYS update the timestamp (run `codeyam memory touch`)\n")
+
+    for rule in stale_rules:
+        parts.append(f"### {rule['name']}")
+        if rule.get('rule_content'):
+            parts.append(f"  Rule content:")
+            for line in rule['rule_content'].split('\n'):
+                parts.append(f"    {line}")
+        if rule.get('newest_file'):
+            parts.append(f"  Changed file: {rule['newest_file']}")
+        if rule.get('file_modified'):
+            parts.append(f"  File modified: {rule['file_modified']}")
+        if rule.get('rule_timestamp'):
+            parts.append(f"  Rule timestamp: {rule['rule_timestamp']}")
+        if rule.get('diff'):
+            parts.append(f"  Changes:")
+            for line in rule['diff'].split('\n'):
+                parts.append(f"    {line}")
+        parts.append("")
+
+    return '\n'.join(parts)
+
+
+def build_conversation_context(conversation_snippets, modified_files):
+    """Build context content for conversation review."""
+    parts = []
+    parts.append("## Conversation Review\n")
+    parts.append(
+        "Review this session for rule-worthy learnings: architectural decisions, tribal knowledge, "
+        "confusion, mistakes, or corrections that future sessions would benefit from knowing.\n"
+    )
+
+    # Load guidance from shared template file
+    guidance = (PROMPTS_DIR / 'conversation-guidance.txt').read_text()
+    parts.append(guidance)
+
+    if modified_files:
+        parts.append("Files modified this session:")
+        for file_path, tool_name in sorted(modified_files):
+            parts.append(f"- {file_path} ({tool_name})")
+        parts.append("")
+
+    parts.append("### Session transcript\n")
+    summary_lines = []
+    for snippet in conversation_snippets:
+        role = snippet['role']
+        content = snippet['content'].replace('\n', ' ')
+        summary_lines.append(f"[{role}]: {content}")
+    parts.append('\n'.join(summary_lines))
+
+    return '\n'.join(parts)
+
+
+def build_interruption_context(conversation_snippets, follow_up_prompt, modified_files):
+    """Build context content for an interrupted session review."""
+    parts = []
+    parts.append("## Interruption Review\n")
+    parts.append(
+        "The user interrupted Claude mid-response — a strong signal of confusion or misunderstanding. "
+        "Review the interrupted conversation and the user's follow-up to identify rule-worthy learnings.\n"
+    )
+
+    # Load guidance from shared template file
+    guidance = (PROMPTS_DIR / 'conversation-guidance.txt').read_text()
+    parts.append(guidance)
+
+    if modified_files:
+        parts.append("Files modified this session:")
+        for file_path, tool_name in sorted(modified_files):
+            parts.append(f"- {file_path} ({tool_name})")
+        parts.append("")
+
+    parts.append("### Session transcript\n")
+    summary_lines = []
+    for snippet in conversation_snippets:
+        role = snippet['role']
+        content = snippet['content'].replace('\n', ' ')
+        summary_lines.append(f"[{role}]: {content}")
+    parts.append('\n'.join(summary_lines))
+
+    parts.append("")
+    parts.append("### User's follow-up after interruption\n")
+    parts.append(follow_up_prompt)
+
+    return '\n'.join(parts)
+
+
+def spawn_claude_agent(prompt, log_file, project_dir):
+    """Spawn a detached claude -p agent as a background process."""
+    try:
+        log_fh = open(log_file, 'w')
+        env = os.environ.copy()
+        env['CODEYAM_RULE_AGENT'] = '1'
+        subprocess.Popen(
+            ['claude', '-p', prompt,
+             '--model', 'haiku',
+             '--output-format', 'stream-json', '--verbose',
+             '--allowedTools', 'Read,Edit,Write,Bash,Glob,Grep'],
+            cwd=project_dir,
+            stdout=log_fh,
+            stderr=log_fh,
+            env=env,
+            start_new_session=True,
+        )
+    except FileNotFoundError:
+        pass  # claude CLI not available, skip silently
+
+
+def read_marker(marker_file):
+    """
+    Read marker file. Returns (last_line, written_by_stop).
+    Format: "<line_count>" or "<line_count> stop" — the suffix distinguishes
+    whether the Stop hook wrote this marker (normal completion) vs the
+    UserPromptSubmit handler (interruption detection).
+    """
+    if marker_file.exists():
+        try:
+            text = marker_file.read_text().strip()
+            parts = text.split()
+            line_count = int(parts[0])
+            was_stop = len(parts) > 1 and parts[1] == 'stop'
+            return line_count, was_stop
+        except (ValueError, IOError):
+            pass
+    return 0, False
+
+
+def write_marker(marker_file, line_count, source='submit'):
+    """Write marker with source tag. source is 'stop' or 'submit'."""
+    marker_file.write_text(f'{line_count} {source}')
+
+
+def handle_stop(hook_input):
+    """
+    Handle the Stop hook event.
+    Reviews completed turns for stale rules and conversation confusion signals.
+
+    Important: the fast work (transcript parsing, marker update, conversation
+    agent spawn) runs first. The slow `get_stale_rules()` call (~10s) runs last
+    so the hook timeout doesn't kill us before the critical work is done.
+    """
+    session_id = hook_input.get('session_id', '')
+    transcript_path = hook_input.get('transcript_path', '')
+
+    if not session_id or not transcript_path:
+        return
+
+    marker_dir = Path('/tmp/claude-rule-markers')
+    marker_dir.mkdir(exist_ok=True)
+    marker_file = marker_dir / f'{session_id}.marker'
+
+    last_line, _ = read_marker(marker_file)
+
+    # Fast: parse transcript for conversation context
+    user_turn_count, conversation_snippets, modified_files, current_line_count = get_conversation_context(
+        transcript_path, last_line
+    )
+
+    # Update marker immediately so UserPromptSubmit knows Stop ran,
+    # even if we get killed during the slow stale rules check below
+    write_marker(marker_file, current_line_count, 'stop')
+
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+    invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
+    invocation_id = f'{session_id}-{invocation_ts}'
+
+    # Fast: spawn conversation review agent first
+    if len(conversation_snippets) > 0:
+        conv_context = build_conversation_context(conversation_snippets, modified_files)
+        conv_context_file = marker_dir / f'{invocation_id}-conversation.context'
+        conv_context_file.write_text(conv_context)
+
+        conv_log_file = marker_dir / f'{invocation_id}-conversation.log'
+        conv_notification_file = marker_dir / 'rule-notification-conversation.md'
+        conv_prompt = load_prompt_template(
+            'conversation-prompt.txt',
+            CONTEXT_FILE=str(conv_context_file),
+            NOTIFICATION_FILE=str(conv_notification_file),
+            PROJECT_DIR=project_dir,
+        )
+        spawn_claude_agent(conv_prompt, conv_log_file, project_dir)
+
+    # Slow (~10s): check for stale rules last — if the hook timeout kills us
+    # here, the conversation agent and marker are already handled
+    stale_rules = get_stale_rules()
+
+    if len(stale_rules) > 0:
+        stale_context = build_stale_rules_context(stale_rules)
+        stale_context_file = marker_dir / f'{invocation_id}-stale.context'
+        stale_context_file.write_text(stale_context)
+
+        stale_log_file = marker_dir / f'{invocation_id}-stale.log'
+        stale_notification_file = marker_dir / 'rule-notification-stale.md'
+        stale_prompt = load_prompt_template(
+            'stale-rules-prompt.txt',
+            CONTEXT_FILE=str(stale_context_file),
+            NOTIFICATION_FILE=str(stale_notification_file),
+            PROJECT_DIR=project_dir,
+        )
+        spawn_claude_agent(stale_prompt, stale_log_file, project_dir)
+
+
+def handle_user_prompt_submit(hook_input):
+    """
+    Handle the UserPromptSubmit hook event.
+    Detects whether the previous turn was interrupted by checking if the Stop hook's
+    marker file is stale (transcript has lines beyond the marker). If so, spawns a
+    rule-reflection agent focused on the interruption.
+    """
+    session_id = hook_input.get('session_id', '')
+    transcript_path = hook_input.get('transcript_path', '')
+    follow_up_prompt = hook_input.get('prompt', '')
+
+    if not session_id or not transcript_path:
+        return
+
+    marker_dir = Path('/tmp/claude-rule-markers')
+    marker_dir.mkdir(exist_ok=True)
+    marker_file = marker_dir / f'{session_id}.marker'
+
+    last_line, was_stop = read_marker(marker_file)
+
+    # If the Stop hook already ran for the previous turn, this is a normal
+    # completion — not an interruption. The Stop hook tags the marker with
+    # 'stop' when it writes it.
+    if was_stop:
+        return
+
+    # Count current transcript lines
+    try:
+        with open(transcript_path, 'r') as f:
+            current_line_count = sum(1 for _ in f)
+    except IOError:
+        return
+
+    # Quick exit: if nothing new since the marker, definitely no interruption
+    if current_line_count <= last_line:
+        return
+
+    # Verify Claude actually started responding in the unprocessed lines.
+    # Guards against false positives on first prompt (no assistant yet) or
+    # if the user hit Escape before Claude produced any output.
+    if not has_assistant_messages(transcript_path, last_line):
+        return
+
+    # Interruption detected! Build context and spawn agent.
+    _, conversation_snippets, modified_files, _ = get_conversation_context(
+        transcript_path, last_line
+    )
+
+    if not conversation_snippets:
+        return
+
+    # Update marker so we don't re-process these lines
+    write_marker(marker_file, current_line_count, 'submit')
+
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+
+    invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
+    invocation_id = f'{session_id}-{invocation_ts}'
+
+    interruption_context = build_interruption_context(
+        conversation_snippets, follow_up_prompt, modified_files
+    )
+    context_file = marker_dir / f'{invocation_id}-interruption.context'
+    context_file.write_text(interruption_context)
+
+    log_file = marker_dir / f'{invocation_id}-interruption.log'
+    notification_file = marker_dir / 'rule-notification-interruption.md'
+    prompt = load_prompt_template(
+        'interruption-prompt.txt',
+        CONTEXT_FILE=str(context_file),
+        NOTIFICATION_FILE=str(notification_file),
+        PROJECT_DIR=project_dir,
+    )
+    spawn_claude_agent(prompt, log_file, project_dir)
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+
+    stop_hook_active = hook_input.get('stop_hook_active', False)
+
+    # Prevent infinite loops — stop_hook_active covers same-process recursion,
+    # env var covers spawned subagent sessions triggering the hook on exit
+    if stop_hook_active or os.environ.get('CODEYAM_RULE_AGENT'):
+        return
+
+    # Detect event type: UserPromptSubmit has a 'prompt' field, Stop does not
+    is_user_prompt = 'prompt' in hook_input
+    if is_user_prompt:
+        handle_user_prompt_submit(hook_input)
+    else:
+        handle_stop(hook_input)
+
+
+if __name__ == '__main__':
+    main()