@codeyam/codeyam-cli 0.1.0-staging.483fdc2 → 0.1.0-staging.62d4615

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

@@ -2,64 +2,199 @@
 """
 Rule reflection hook for Claude Code.
 
-Reads the session transcript to find new conversation since last check,
-then prompts Claude to consider rule updates if there was substantive content.
+Two responsibilities, now split into independent agents:
+1. Check for stale rules (files changed since rule was last reviewed) and prompt review
+2. Review conversation for confusion signals (mistakes, corrections, interruptions)
+
+Each 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 pathlib import Path
 
-MIN_USER_TURNS = 5  # Fire after N user turns
+MIN_USER_TURNS = 3  # Minimum user turns before checking for confusion
 
-def main():
-    # Read hook input from stdin
-    try:
-        hook_input = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        # No valid input, exit silently
-        return
+# 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",
+]
 
-    session_id = hook_input.get('session_id', '')
-    transcript_path = hook_input.get('transcript_path', '')
-    stop_hook_active = hook_input.get('stop_hook_active', False)
+# Prompt templates directory — installed alongside this hook in .codeyam/bin/prompts/
+PROMPTS_DIR = Path(__file__).parent / 'prompts'
 
-    # Prevent infinite loops - if we're already in a stop hook continuation, exit silently
-    if stop_hook_active:
-        return
 
-    if not session_id or not transcript_path:
-        return
+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
 
-    # Marker file tracks last checked line per session
-    marker_dir = Path('/tmp/claude-rule-markers')
-    marker_dir.mkdir(exist_ok=True)
-    marker_file = marker_dir / f'{session_id}.marker'
 
-    # Read last checked line
-    last_line = 0
-    if marker_file.exists():
+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:
-            last_line = int(marker_file.read_text().strip())
-        except (ValueError, IOError):
-            last_line = 0
+            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 []
 
-    # Read transcript and get new lines
+        # 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
+        return 0, [], set(), 0
 
     current_line_count = len(all_lines)
     new_lines = all_lines[last_line:]
 
     if not new_lines:
-        return
+        return 0, [], set(), current_line_count
 
-    # Count user turns and extract conversation content from new lines
     user_turn_count = 0
     conversation_snippets = []
+    modified_files = set()
 
     for line in new_lines:
         try:
@@ -75,87 +210,219 @@ def main():
 
             # Handle string content
             if isinstance(content, str):
-                # Skip meta messages and very short content
                 if obj.get('isMeta') or len(content) < 20:
                     continue
-                # Skip tool results (they show up as user messages)
                 if content.startswith('[{') or '<tool_result' in content:
                     continue
 
-                # Count substantive user turns
                 if is_external_user and not content.startswith('<'):
                     user_turn_count += 1
 
                 conversation_snippets.append({
                     'role': message.get('role', msg_type),
-                    'content': content[:500]  # Truncate long messages
+                    'content': content
                 })
 
-            # Handle array content (tool calls, etc.)
             elif isinstance(content, list):
                 for item in content:
-                    if isinstance(item, dict):
-                        if item.get('type') == 'text':
-                            text = item.get('text', '')
-                            if len(text) > 20:
-                                conversation_snippets.append({
-                                    'role': message.get('role', msg_type),
-                                    'content': text[:500]
-                                })
+                    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
 
-    # Only fire after enough user turns
-    if user_turn_count < MIN_USER_TURNS:
-        return
+    return user_turn_count, conversation_snippets, modified_files, current_line_count
 
-    # Update marker with current line count
-    marker_file.write_text(str(current_line_count))
 
-    # If not enough substantive conversation, exit silently
-    if len(conversation_snippets) < 3:
-        return
+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")
 
-    # Build a summary of the recent conversation for the rule check
+    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[-15:]:  # Last 15 messages
+    for snippet in conversation_snippets:
         role = snippet['role']
-        content = snippet['content'].replace('\n', ' ')[:300]
+        content = snippet['content'].replace('\n', ' ')
         summary_lines.append(f"[{role}]: {content}")
+    parts.append('\n'.join(summary_lines))
 
-    summary = '\n'.join(summary_lines)
-
-    # Write detailed context to a file (keeps displayed output short)
-    context_file = marker_dir / f'{session_id}.context'
-    context = f"""Recent conversation to review for rule-worthy learnings:
-
-{summary}
-
----
-Guidelines:
-- Did Claude get confused during this session in any way?
-- How exactly did it get confused and what information would have resolved that confusion. No additional detail is needed especially if it is something that Claude likely already knows.
-- Only update rules for patterns of confusion that will likely recur in future sessions.
-- Document knowledge not easily evident from code
-    - Locations of tests
-    - Commands that can be run that are relevant to the task at hand
-    - Architectural design, where to look for, fix, or add certain things
-- Pay particular attention to times when the user must interrupt or correct Claude.
-- Do not document bugs being fixed as they will likely be resolved.
-- Issues that are abandoned as known issues can be noted.
-- Keep rules concise (<50 lines), use bullets/tables where appropriate.
-- Clean up, summarize, and delete existing rules as needed.
-- If no changes are needed, just say "No rule updates needed."
-"""
-    context_file.write_text(context)
-
-    # Output blocking decision - just trigger background agent
-    # Keep reason minimal since main agent will spawn background worker
-    output = {
-        "decision": "block",
-        "reason": f"RULE_CHECK:{context_file}"
-    }
-    print(json.dumps(output))
+    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 main():
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+
+    session_id = hook_input.get('session_id', '')
+    transcript_path = hook_input.get('transcript_path', '')
+    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
+
+    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'
+
+    # Read last checked line
+    last_line = 0
+    if marker_file.exists():
+        try:
+            last_line = int(marker_file.read_text().strip())
+        except (ValueError, IOError):
+            last_line = 0
+
+    # Check for stale rules
+    stale_rules = get_stale_rules()
+
+    # Get conversation context
+    user_turn_count, conversation_snippets, modified_files, current_line_count = get_conversation_context(
+        transcript_path, last_line
+    )
+
+    # Determine what to include in review
+    has_stale_rules = len(stale_rules) > 0
+    has_conversation = len(conversation_snippets) > 0
+
+    # Only fire if there's something to review
+    if not has_stale_rules and not has_conversation:
+        return
+
+    # Update marker
+    marker_file.write_text(str(current_line_count))
+
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+
+    # Unique suffix per invocation so each Stop produces a distinct transcript
+    from datetime import datetime
+    invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
+    invocation_id = f'{session_id}-{invocation_ts}'
+
+    # Spawn independent agent for stale rules review
+    if has_stale_rules:
+        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)
+
+    # Spawn independent agent for conversation review
+    if has_conversation:
+        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)
 
 if __name__ == '__main__':
     main()

package/codeyam-cli/templates/rules-instructions.md

@@ -19,34 +19,33 @@ Create a new rule when:
 
 ## Before Creating: The Confusion Test
 
-Before writing a rule, verify it passes these tests:
+Only create rules that document genuinely confusing aspects—not things Claude can figure out by reading code and will likely come up again in future sessions.
 
-**1. Could Claude figure this out by reading the code?**
+**Ask yourself:**
 
-- If YES → don't create the rule (it documents the obvious)
-- If NO → the rule is valuable
+1. **Could Claude figure this out by reading the code?**
+   - If YES → don't create the rule
+   - If NO → proceed
 
-**2. Does this explain "why" not just "what"?**
+2. **Does this explain "why" not just "what"?**
+   - Good: Historical context, gotchas, non-obvious behavior, non-obvious architectural decisions
+   - Bad: Bug fixes, Limitations (unless the user requests the limitation be noted), What functions do (unless providing a high-level architectural overview)
 
-- Good: Explains historical context, gotchas, or non-obvious behavior
-- Bad: Describes what functions do or how files are structured
-
-**3. Would this have prevented a past mistake?**
-
-- If you can point to a commit, bug, or confusion this would have prevented → create it
-- If it's just "nice to know" information → skip it
+3. **Would this have prevented a past mistake?**
+   - If you can point to a bug or confusion this would have prevented → create it
+   - If it's just "nice to know" → skip it
 
 ### Examples
 
 **✅ Worth documenting:**
 
-- "Path prefix matching must check boundaries" (learned from a bug)
-- "These files must change together because of X invariant" (hidden dependency)
-- "This pattern exists because the obvious approach causes Y problem" (non-obvious design)
+- Where to add new functionality
+- An overview of all files, classes, functions, etc used in a particular part of the repo
+- Debugging strategies for a particular area of the repo
+- "Use `pnpm test` to run tests" (if there is more than one way to run tests and this way is preferred)
 
 **❌ Not worth documenting:**
 
-- "Use `pnpm jest` to run tests" (obvious from package.json)
 - "The auth module handles authentication" (obvious from reading code)
 - "This function takes X and returns Y" (Claude can read the signature)
 
@@ -80,16 +79,14 @@ Rules mirror the source code structure:
 paths:
   - 'specific/path/to/file.ts'
   - 'another/specific/path/*.ts'
-category: architecture | testing | faq
 timestamp: 2026-01-30T00:00:00Z
 ---
 ```
 
-| Field       | Purpose                                                                                            |
-| ----------- | -------------------------------------------------------------------------------------------------- |
-| `paths`     | Glob patterns - be specific to avoid loading rules unnecessarily                                   |
-| `category`  | `architecture` (design/data flow), `testing` (test commands/patterns), `faq` (gotchas/workarounds) |
-| `timestamp` | ISO 8601 - update when rule is reviewed                                                            |
+| Field       | Purpose                                                          |
+| ----------- | ---------------------------------------------------------------- |
+| `paths`     | Glob patterns - be specific to avoid loading rules unnecessarily |
+| `timestamp` | ISO 8601 - update when rule is reviewed                          |
 
 ## Content Guidelines
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.483fdc2",
+  "version": "0.1.0-staging.62d4615",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {
@@ -52,7 +52,7 @@
     "pluralize": "^8.0.0",
     "prompts": "^2.4.2",
     "react": "^19.2.3",
-    "react-diff-viewer-continued": "^4.0.6",
+    "react-diff-viewer-continued": "4.0.6",
     "react-dom": "^19.2.3",
     "react-markdown": "^10.1.0",
     "react-resizable": "^3.0.5",

package/packages/ai/src/lib/analyzeScope.js

@@ -94,9 +94,14 @@ function ensureWorkerPool() {
     }
     // Note: WORKER_PATH is null when __mocks__/analyzeScope.ts is active
     const { WORKER_PATH } = analyzeScopeWorkerPaths();
+    // Disable workers when tracing is enabled - we need access to ScopeDataStructure
+    // instance in the main thread to capture pre-serialization state
+    const tracingEnabled = process.env.CODEYAM_TRACE_TRANSFORMS === '1' ||
+        process.env.CODEYAM_TRACE_TRANSFORMS === 'true';
     if (process.env.USE_WORKER_THREADS &&
         WORKER_PATH &&
-        fs.existsSync(WORKER_PATH)) {
+        fs.existsSync(WORKER_PATH) &&
+        !tracingEnabled) {
         console.log('CodeYam: Using worker threads for analyzeScope', {
             WORKER_PATH,
         });
@@ -124,6 +129,7 @@ function ensureWorkerPool() {
             WORKER_PATH,
             workerExists: WORKER_PATH ? fs.existsSync(WORKER_PATH) : false,
             USE_WORKER_THREADS: process.env.USE_WORKER_THREADS,
+            tracingEnabled,
         });
         workerPool = null; // Explicitly set to indicate "no workers"
     }