claude-capsule-kit 3.0.0

package/docs/TOOL_ENFORCEMENT_REFERENCE.md

@@ -0,0 +1,418 @@
+# Tool Enforcement Reference
+
+Complete guide for tool selection and enforcement rules in Claude Capsule Kit.
+
+---
+
+## Overview
+
+Claude Capsule Kit provides specialized tools that are **FASTER and MORE ACCURATE** than generic exploration. These rules are **MANDATORY** and enforced by the PreToolUse hook.
+
+**Principle**: Use the right tool for the job—specialized tools beat Task/Explore agents for simple queries.
+
+---
+
+## Dependency Analysis Tools
+
+### Always Use Specialized Tools (NEVER Task/Explore)
+
+#### 1. query-deps - "What imports this file?"
+
+**Command**:
+```bash
+bash $HOME/.claude/cck/tools/query-deps/query-deps.sh <file-path>
+```
+
+**Use cases**:
+- Finding files that import/depend on a specific file
+- Checking if a function/export is used before deleting
+- Understanding dependency relationships
+
+**Example**:
+```bash
+bash $HOME/.claude/cck/tools/query-deps/query-deps.sh src/auth/auth.service.ts
+
+# Output:
+Imported by 12 files:
+- src/controllers/auth.controller.ts
+- src/middleware/auth.middleware.ts
+- src/guards/jwt.guard.ts
+...
+```
+
+---
+
+#### 2. impact-analysis - "What would break if I change this?"
+
+**Command**:
+```bash
+bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh <file-path>
+```
+
+**Use cases**:
+- Impact analysis before refactoring
+- Understanding blast radius of changes
+- Risk assessment for modifications
+
+**Returns**:
+- Direct dependents
+- Transitive dependents
+- Risk assessment (LOW/MEDIUM/HIGH/CRITICAL)
+
+**Example**:
+```bash
+bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh src/auth/auth.service.ts
+
+# Output:
+DIRECT DEPENDENTS (5 files):
+- src/controllers/auth.controller.ts
+- src/middleware/auth.middleware.ts
+...
+
+TRANSITIVE DEPENDENTS (18 files):
+[Files that depend on the direct dependents]
+
+RISK: MEDIUM
+Recommendation: Update tests after changes
+```
+
+---
+
+#### 3. find-circular - "Any circular dependencies?"
+
+**Command**:
+```bash
+bash $HOME/.claude/cck/tools/find-circular/find-circular.sh
+```
+
+**Use cases**:
+- Finding import cycles
+- Debugging module resolution errors
+- Code cleanup and refactoring prep
+
+**Returns**:
+- All circular dependency chains with fix suggestions
+
+**Example**:
+```bash
+bash $HOME/.claude/cck/tools/find-circular/find-circular.sh
+
+# Output:
+CIRCULAR DEPENDENCY FOUND:
+A.ts → B.ts → C.ts → A.ts
+
+Suggestion: Break cycle by extracting shared code to D.ts
+```
+
+---
+
+#### 4. find-dead-code - "What files are unused?"
+
+**Command**:
+```bash
+bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh
+```
+
+**Use cases**:
+- Finding unused/unreferenced files
+- Code cleanup
+- Identifying candidates for deletion
+
+**Returns**:
+- List of potentially unused files
+
+**Example**:
+```bash
+bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh
+
+# Output:
+Potentially unused files (5):
+- src/utils/legacy-helper.ts (not imported anywhere)
+- src/models/old-user.model.ts (not imported)
+...
+```
+
+---
+
+### Why NOT Task/Explore for Dependencies?
+
+| Issue | Reason |
+|-------|--------|
+| **Slower** | Must read and parse files sequentially |
+| **Incomplete** | May miss indirect dependencies |
+| **Expensive** | High token usage for simple queries |
+| **Cannot detect cycles** | Needs graph analysis (pre-computed) |
+
+**Use dependency tools instead** - they read the pre-built dependency graph (instant, complete, accurate).
+
+---
+
+## File Search: Glob Tool
+
+### Always Use Glob (NOT Task/Explore)
+
+**Tool**: Glob
+**Reason**: Direct file pattern matching
+
+**Examples**:
+
+**Find file by name**:
+```
+Glob(pattern="**/*auth*")
+# Finds: auth.service.ts, auth.controller.ts, auth.middleware.ts
+```
+
+**Find files by extension**:
+```
+Glob(pattern="**/*.ts")
+# Finds: All TypeScript files
+```
+
+**Find files in specific directory**:
+```
+Glob(pattern="src/controllers/**/*.ts")
+# Finds: All controllers
+```
+
+**Why NOT Task/Explore?**
+- Slower (agent must search iteratively)
+- Glob is instant (built-in file system query)
+
+---
+
+## Code Search: Grep Tool
+
+### Always Use Grep (NOT Task/Explore)
+
+**Tool**: Grep
+**Reason**: Fast pattern matching
+
+**Examples**:
+
+**Find by keyword**:
+```
+Grep(pattern="TODO", output_mode="files_with_matches")
+# Finds: All files with TODO comments
+```
+
+**Find definition**:
+```
+Grep(pattern="function authenticateUser", output_mode="content")
+# Finds: Function definition with line numbers
+```
+
+**Find with context**:
+```
+Grep(pattern="error", output_mode="content", -A=3, -B=3)
+# Shows 3 lines before/after each match
+```
+
+**Why NOT Task/Explore?**
+- Grep is instant (ripgrep is extremely fast)
+- Task/Explore must read files sequentially
+
+---
+
+## Progressive Reader (Large Files >50KB)
+
+### Navigation Tool for Large Files
+
+**Tool**: `progressive-reader`
+**Reason**: File navigation and structure discovery
+
+**Purpose**:
+Progressive-reader is a NAVIGATION TOOL for large files. Use it to understand file structure BEFORE reading, then read only what you need.
+
+### Primary Value: `--list` Command
+
+The `--list` command shows file structure WITHOUT reading content:
+
+**Benefits**:
+- Shows all functions/classes with their chunk numbers
+- Each chunk has a summary of what it contains
+- ~500 tokens to see entire file structure (vs ~48,000 for full read)
+- BETTER THAN GREP for understanding "what's in this file?"
+
+### Workflow
+
+**Step 1**: Discover structure
+```bash
+$HOME/.claude/bin/progressive-reader --path <file> --list
+```
+
+**Output**:
+```
+File: src/services/large-service.ts
+Total Chunks: 8
+
+Chunk 0 (lines 1-200): Imports, type definitions, class declaration
+Chunk 1 (lines 201-400): Constructor and initialization methods
+Chunk 2 (lines 401-600): Core business logic (create, update, delete)
+Chunk 3 (lines 601-800): Validation and helper methods
+...
+```
+
+**Step 2**: Find relevant chunks from function/class names in the list
+
+**Step 3**: Read specific chunk
+```bash
+$HOME/.claude/bin/progressive-reader --path <file> --chunk N
+```
+
+**Step 4**: Continue if needed
+```bash
+$HOME/.claude/bin/progressive-reader --continue-file /tmp/continue.toon
+```
+
+### When to Use Progressive Reader
+
+- **Understanding file structure**: "What functions are in this file?"
+- **Finding specific functionality**: "Which part handles authentication?"
+- **Adding new code**: "Show me similar functions so I can follow the pattern"
+- **Targeted reading**: "I need to understand just the login function"
+- **Context-limited sessions**: Nearing token limits, need efficient reading
+
+### When Grep is Fine
+
+- Finding specific keyword occurrences
+- Searching for error messages or strings
+- Quick lookups where you know what you're searching for
+
+### Language Support
+
+**Full AST parsing** (intelligent chunking):
+- TypeScript
+- JavaScript
+- Python
+- Go
+
+**Fallback** (line-based chunking):
+- Other languages (still useful, less intelligent)
+
+**Token Savings**: 75-97% vs full file read
+
+---
+
+## File Size Check (MANDATORY)
+
+### BEFORE using Read tool, ALWAYS check file size first
+
+**Check command**:
+```bash
+wc -c <file> | awk '{print int($1/1024)"KB"}'
+```
+
+**Decision**:
+- **If under 50KB**: Use Read tool normally
+- **If over 50KB**: STOP. Use progressive-reader instead
+
+**Why this matters**:
+- Files over 50KB (~12,500+ tokens) cause `MaxFileReadTokenExceededError`
+- Each failed Read attempt wastes tokens
+- Check size FIRST to avoid errors
+
+**Progressive reader command** (for large files):
+```bash
+$HOME/.claude/bin/progressive-reader --path <file> --list
+$HOME/.claude/bin/progressive-reader --path <file> --chunk N
+```
+
+---
+
+## Error Recovery
+
+### MaxFileReadTokenExceededError
+
+**Trigger**: Attempted to read file >50KB with Read tool
+
+**Action**: IMMEDIATELY stop using Read tool on this file
+
+**Solution**: Switch to progressive-reader
+```bash
+$HOME/.claude/bin/progressive-reader --path <file> --list
+```
+
+**Do NOT**: Retry Read with offset/limit—use progressive-reader instead
+
+**Note**: PreToolUse hook will warn/block large file reads automatically
+
+---
+
+## Task Tool - Allowed Uses
+
+### When Task Tool IS Allowed
+
+**Allowed Use Cases**:
+
+1. **Complex architectural questions** requiring analysis
+   - Example: "How does the authentication system work?"
+
+2. **Implementation understanding**
+   - Example: "How does X work internally?"
+
+3. **Multi-file refactoring planning**
+   - Example: "Plan refactoring of auth module across files"
+
+4. **Design pattern identification**
+   - Example: "What patterns are used in this codebase?"
+
+### When Task Tool is NOT Allowed
+
+**Forbidden**:
+- Dependency lookups → Use `query-deps` instead
+- File searches → Use `Glob` instead
+- Code searches → Use `Grep` instead
+
+**Why**: Specialized tools are instant and accurate. Task/Explore agents are slow and may miss results.
+
+---
+
+## Enforcement Mechanism
+
+**PreToolUse Hook**: Intercepts tool calls and displays enforcement warnings
+
+**How it works**:
+1. Hook detects dependency query keywords in Task/Explore prompts
+2. Outputs enforcement warning to stderr
+3. Suggests correct tool with example command
+4. Task still executes (warning only, not blocking)
+
+**You must**: HEED THESE WARNINGS—they indicate you are using the wrong tool.
+
+**Example warning**:
+```json
+{
+  "type": "tool-enforcement",
+  "category": "dependency-analysis",
+  "warning": "Query appears to be about code dependencies",
+  "dontUse": {
+    "tool": "Task",
+    "reason": "inefficient"
+  },
+  "useInstead": [
+    {
+      "name": "query-deps",
+      "command": "bash $HOME/.claude/cck/tools/query-deps/query-deps.sh <file-path>"
+    }
+  ]
+}
+```
+
+---
+
+## Quick Reference Card
+
+| Need | Use | NOT |
+|------|-----|-----|
+| What imports X? | `query-deps` | Task/Explore |
+| What breaks if I change X? | `impact-analysis` | Task/Explore |
+| Circular deps? | `find-circular` | Task/Explore |
+| Dead code? | `find-dead-code` | Task/Explore |
+| Find files by name | Glob | Task/Explore |
+| Find code patterns | Grep | Task/Explore |
+| Read large files (>50KB) | `progressive-reader` | Read |
+| Understand architecture | Task/architecture-explorer | Read files |
+
+---
+
+**These tools exist to make you FASTER. Use them.**

package/hooks/check-refresh-needed.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Smart Refresh Heuristics
+# Determines if capsule needs updating based on state changes
+# Returns: 0 if refresh needed, 1 if can skip
+
+set -euo pipefail
+
+REFRESH_STATE_FILE=".claude/last_refresh_state.txt"
+TIMESTAMP=$(date +%s)
+
+# Helper: Calculate hash of current state
+calculate_state_hash() {
+  local state_string=""
+
+  # Git state (if available)
+  if git rev-parse --git-dir > /dev/null 2>&1; then
+    state_string+=$(git status --porcelain 2>/dev/null | md5 -q 2>/dev/null || echo "")
+  else
+    # Fallback: use timestamp of last modified file
+    state_string+=$(find . -type f -not -path "./.claude/*" -not -path "./.git/*" -not -path "./node_modules/*" -printf "%T@\n" 2>/dev/null | sort -n | tail -1 || echo "0")
+  fi
+
+  # File log size (number of lines)
+  if [ -f ".claude/session_files.log" ]; then
+    state_string+=$(wc -l < .claude/session_files.log 2>/dev/null || echo "0")
+  fi
+
+  # Task log size
+  if [ -f ".claude/current_tasks.log" ]; then
+    state_string+=$(wc -l < .claude/current_tasks.log 2>/dev/null || echo "0")
+  fi
+
+  # Sub-agent log size
+  if [ -f ".claude/subagent_results.log" ]; then
+    state_string+=$(wc -l < .claude/subagent_results.log 2>/dev/null || echo "0")
+  fi
+
+  # Discovery log size
+  if [ -f ".claude/session_discoveries.log" ]; then
+    state_string+=$(wc -l < .claude/session_discoveries.log 2>/dev/null || echo "0")
+  fi
+
+  # Return hash of combined state
+  echo "$state_string" | md5 -q 2>/dev/null || echo "$state_string" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "$state_string"
+}
+
+# Get current state hash
+CURRENT_HASH=$(calculate_state_hash)
+
+# Check if we have previous state
+if [ -f "$REFRESH_STATE_FILE" ]; then
+  # Read previous state
+  LAST_HASH=$(cut -d',' -f1 "$REFRESH_STATE_FILE" 2>/dev/null || echo "")
+  LAST_REFRESH=$(cut -d',' -f2 "$REFRESH_STATE_FILE" 2>/dev/null || echo "0")
+  TIME_SINCE_REFRESH=$((TIMESTAMP - LAST_REFRESH))
+
+  # Compare hashes
+  if [ "$CURRENT_HASH" = "$LAST_HASH" ]; then
+    # State unchanged - check if too much time passed
+    if [ $TIME_SINCE_REFRESH -lt 300 ]; then
+      # Less than 5 minutes - safe to skip
+      exit 1  # Skip refresh
+    else
+      # Over 5 minutes - force refresh for freshness
+      echo "$CURRENT_HASH,$TIMESTAMP" > "$REFRESH_STATE_FILE"
+      exit 0  # Need refresh
+    fi
+  else
+    # State changed - need refresh
+    echo "$CURRENT_HASH,$TIMESTAMP" > "$REFRESH_STATE_FILE"
+    exit 0  # Need refresh
+  fi
+else
+  # First run - need refresh
+  echo "$CURRENT_HASH,$TIMESTAMP" > "$REFRESH_STATE_FILE"
+  exit 0  # Need refresh
+fi

package/hooks/detect-changes.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# Automatic Change Detection Script
+# Detects file changes, tool usage, and discoveries since last prompt
+# Called by pre-task-analysis hook
+
+set -euo pipefail
+
+SNAPSHOT_FILE=".claude/last_snapshot.txt"
+FILE_LOG=".claude/session_files.log"
+TIMESTAMP=$(date +%s)
+
+# Create snapshot file if doesn't exist
+mkdir -p .claude
+touch "$SNAPSHOT_FILE"
+
+# ============================================
+# GIT-BASED FILE DETECTION (if available)
+# ============================================
+# Detect files that changed since last snapshot
+if git rev-parse --git-dir > /dev/null 2>&1 && [ -f "$SNAPSHOT_FILE" ]; then
+  # Get current git status
+  CURRENT_STATUS=$(git status --porcelain 2>/dev/null || echo "")
+  LAST_STATUS=$(cat "$SNAPSHOT_FILE" 2>/dev/null || echo "")
+
+  # Compare and find new/modified files
+  while IFS= read -r line; do
+    if [ -z "$line" ]; then continue; fi
+
+    # Parse git status line (e.g., " M file.txt", "A  file.txt")
+    STATUS_CODE="${line:0:2}"
+    FILE_PATH="${line:3}"
+
+    # Skip if this file was already in last snapshot
+    if echo "$LAST_STATUS" | grep -qF "$FILE_PATH"; then
+      # File was already modified, check if it changed further
+      continue
+    fi
+
+    # New change detected, log it
+    case "$STATUS_CODE" in
+      *M*|" M")
+        echo "$FILE_PATH,edit,$TIMESTAMP" >> "$FILE_LOG"
+        ;;
+      A*|"A ")
+        echo "$FILE_PATH,write,$TIMESTAMP" >> "$FILE_LOG"
+        ;;
+      D*|"D ")
+        echo "$FILE_PATH,delete,$TIMESTAMP" >> "$FILE_LOG"
+        ;;
+    esac
+  done <<< "$CURRENT_STATUS"
+
+  # Save current status as snapshot
+  echo "$CURRENT_STATUS" > "$SNAPSHOT_FILE"
+elif git rev-parse --git-dir > /dev/null 2>&1; then
+  # First run with git, save snapshot
+  git status --porcelain 2>/dev/null > "$SNAPSHOT_FILE" || touch "$SNAPSHOT_FILE"
+else
+  # No git available, mark as initialized
+  touch "$SNAPSHOT_FILE"
+fi
+
+# ============================================
+# FILE MODIFICATION TIME TRACKING
+# ============================================
+# Track recently modified files in project (last 60 seconds)
+if command -v find >/dev/null 2>&1; then
+  # Find files modified in last 60 seconds
+  find . -type f \
+    -not -path "./.git/*" \
+    -not -path "./node_modules/*" \
+    -not -path "./.claude/*" \
+    -not -path "./build/*" \
+    -not -path "./dist/*" \
+    -mtime -60s 2>/dev/null | while read -r file; do
+
+    # Check if already logged recently
+    if grep -qF "$file" "$FILE_LOG" 2>/dev/null; then
+      LAST_LOG=$(grep -F "$file" "$FILE_LOG" | tail -1 | cut -d',' -f3)
+      # Only log if more than 30 seconds since last log
+      if [ $((TIMESTAMP - LAST_LOG)) -gt 30 ]; then
+        echo "$file,edit,$TIMESTAMP" >> "$FILE_LOG"
+      fi
+    else
+      echo "$file,read,$TIMESTAMP" >> "$FILE_LOG"
+    fi
+  done
+fi
+
+exit 0

package/hooks/keyword-triggers.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Keyword triggers - auto-suggests tools based on user prompt keywords
+# Can be called standalone or integrated into other hooks
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TOOL_RUNNER_PATH="$HOME/.claude/cck/lib/tool-runner.sh"
+
+if [ ! -f "$TOOL_RUNNER_PATH" ]; then
+    exit 0
+fi
+
+source "$TOOL_RUNNER_PATH"
+
+USER_PROMPT="${1:-}"
+
+if [ -z "$USER_PROMPT" ]; then
+    exit 0
+fi
+
+PROMPT_LOWER=$(echo "$USER_PROMPT" | tr '[:upper:]' '[:lower:]')
+
+SUGGESTIONS_MADE=false
+
+suggest_tool() {
+    local tool_name="$1"
+    local reason="$2"
+
+    if ! $SUGGESTIONS_MADE; then
+        echo ""
+        echo "Claude Capsule Kit - Available Tools:"
+        SUGGESTIONS_MADE=true
+    fi
+
+    echo "   $tool_name - $reason"
+}
+
+if echo "$PROMPT_LOWER" | grep -qE '(depend|import|require|reference)'; then
+    suggest_tool "query-deps" "Query dependency relationships"
+fi
+
+if echo "$PROMPT_LOWER" | grep -qE '(circular|cycle|loop)'; then
+    suggest_tool "find-circular" "Find circular dependency cycles"
+fi
+
+if echo "$PROMPT_LOWER" | grep -qE '(unused|dead code|orphan|unreferenced)'; then
+    suggest_tool "find-dead-code" "Find potentially unused files"
+fi
+
+if echo "$PROMPT_LOWER" | grep -qE '(impact|affect|break|change.*will)'; then
+    suggest_tool "impact-analysis" "Analyze impact of file changes"
+fi
+
+if echo "$PROMPT_LOWER" | grep -qE '(refactor|restructure|reorganize)'; then
+    suggest_tool "query-deps" "Check dependencies before refactoring"
+    suggest_tool "impact-analysis" "Analyze refactoring impact"
+fi
+
+if $SUGGESTIONS_MADE; then
+    echo ""
+    echo "   Usage: run_tool <tool-name> [args...]"
+    echo ""
+fi
+
+exit 0