@a-company/paradigm 3.1.5 → 3.5.0

package/dist/{chunk-DRUDZKIT.js → chunk-M2XMTJHQ.js}

@@ -4,6 +4,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { execSync } from "child_process";
 import chalk from "chalk";
 
 // src/commands/hooks/generated-hooks.ts
@@ -248,6 +249,8 @@ fi
 # --- Check 7: Lore entry expected for significant sessions ---
 if [ "$SOURCE_COUNT" -ge 3 ] && [ -d ".paradigm/lore" ]; then
   LORE_RECORDED=false
+
+  # Check git diff first (covers staged/committed lore)
   for file in $MODIFIED; do
     case "$file" in
       .paradigm/lore/entries/*.yaml|.paradigm/lore/entries/*/*.yaml)
@@ -257,6 +260,17 @@ if [ "$SOURCE_COUNT" -ge 3 ] && [ -d ".paradigm/lore" ]; then
     esac
   done
 
+  # Also check for recent lore on disk (covers MCP-written entries not yet staged)
+  if [ "$LORE_RECORDED" = false ]; then
+    TODAY=$(date -u +"%Y-%m-%d")
+    if [ -d ".paradigm/lore/entries/$TODAY" ]; then
+      ENTRY_COUNT=$(find ".paradigm/lore/entries/$TODAY" -name "*.yaml" 2>/dev/null | head -1)
+      if [ -n "$ENTRY_COUNT" ]; then
+        LORE_RECORDED=true
+      fi
+    fi
+  fi
+
   if [ "$LORE_RECORDED" = false ]; then
     VIOLATIONS="$VIOLATIONS
   - You modified $SOURCE_COUNT source files but recorded no lore entry.
@@ -460,6 +474,107 @@ for f in .paradigm/scan-index.json .paradigm/navigator.yaml .paradigm/flow-index
 done
 
 # Never block \u2014 exit 0
+exit 0
+`;
+var CURSOR_SESSION_START_HOOK = `#!/bin/sh
+# Paradigm Cursor Session Start Hook
+# Fires before the agent does anything \u2014 injects additional_context
+# that acts as a deterministic system prompt (not subject to context compaction).
+# Installed by: paradigm hooks install --cursor
+#
+# Hook type: sessionStart
+# Output: JSON with additional_context + continue: true
+# Exit 0 always (never blocks)
+
+# Read JSON from stdin (hook input)
+INPUT=$(cat)
+
+# Extract workspace root from Cursor's input
+if command -v jq >/dev/null 2>&1; then
+  CWD=$(echo "$INPUT" | jq -r '.workspace_roots[0] // empty' 2>/dev/null)
+else
+  CWD=$(echo "$INPUT" | grep -o '"workspace_roots"[[:space:]]*:[[:space:]]*\\["[^"]*"' | head -1 | sed 's/.*\\["//' | sed 's/"$//')
+fi
+
+if [ -z "$CWD" ]; then
+  CWD="$(pwd)"
+fi
+
+# Not a paradigm project \u2014 pass without injection
+if [ ! -d "$CWD/.paradigm" ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+# Build the additional_context payload
+# This is injected as a system-level context that survives context compaction.
+
+# Detect project characteristics for task-size guidance
+HAS_PORTAL="false"
+if [ -f "$CWD/portal.yaml" ]; then
+  HAS_PORTAL="true"
+fi
+
+HAS_LORE="false"
+if [ -d "$CWD/.paradigm/lore" ]; then
+  HAS_LORE="true"
+fi
+
+HAS_FLOWS="false"
+if [ -f "$CWD/.paradigm/flow-index.json" ]; then
+  HAS_FLOWS="true"
+fi
+
+# Build context string (escaped for JSON)
+CONTEXT="MANDATORY PARADIGM PROTOCOL \u2014 These rules are NON-NEGOTIABLE:\\\\n\\\\n"
+CONTEXT="\${CONTEXT}Rule 1: SESSION BOOKENDS\\\\n"
+CONTEXT="\${CONTEXT}  - FIRST action: Call paradigm_session_recover() to load previous session context\\\\n"
+CONTEXT="\${CONTEXT}  - LAST action before finishing: Call paradigm_pm_postflight() with filesModified and symbolsTouched\\\\n\\\\n"
+
+CONTEXT="\${CONTEXT}Rule 2: .PURPOSE UPDATES\\\\n"
+CONTEXT="\${CONTEXT}  - Every source file you modify MUST have a covering .purpose file\\\\n"
+CONTEXT="\${CONTEXT}  - Update the nearest .purpose file with: #components, ~aspects (with anchors), !signals\\\\n"
+CONTEXT="\${CONTEXT}  - The STOP HOOK WILL BLOCK you if .purpose files are not updated\\\\n\\\\n"
+
+CONTEXT="\${CONTEXT}Rule 3: RIPPLE BEFORE MODIFY\\\\n"
+CONTEXT="\${CONTEXT}  - Before modifying any existing symbol, call paradigm_ripple({ symbol: \\\\\\"#symbol-name\\\\\\" })\\\\n"
+CONTEXT="\${CONTEXT}  - This shows the blast radius \u2014 what else will break if you change it\\\\n\\\\n"
+
+CONTEXT="\${CONTEXT}ESSENTIAL MCP TOOLS:\\\\n"
+CONTEXT="\${CONTEXT}  paradigm_session_recover()          \u2014 Load previous session (call FIRST)\\\\n"
+CONTEXT="\${CONTEXT}  paradigm_ripple({ symbol })          \u2014 Check impact before modifying\\\\n"
+CONTEXT="\${CONTEXT}  paradigm_pm_postflight({ filesModified, symbolsTouched }) \u2014 Compliance check (call LAST)\\\\n"
+CONTEXT="\${CONTEXT}  paradigm_purpose_add_component({ path, name, description }) \u2014 Register code units\\\\n"
+CONTEXT="\${CONTEXT}  paradigm_reindex()                   \u2014 Rebuild indexes after .purpose changes\\\\n"
+CONTEXT="\${CONTEXT}  paradigm_lore_record({ type, title, summary, symbols_touched }) \u2014 Record session\\\\n"
+
+if [ "$HAS_PORTAL" = "true" ]; then
+  CONTEXT="\${CONTEXT}  paradigm_gates_for_route({ method, path }) \u2014 Get auth gate suggestions for endpoints\\\\n"
+  CONTEXT="\${CONTEXT}  paradigm_portal_add_route({ method, path, gates }) \u2014 Register route with gates\\\\n"
+fi
+
+CONTEXT="\${CONTEXT}\\\\nTASK-SIZE TIERS:\\\\n"
+CONTEXT="\${CONTEXT}  1 file:   Session bookends only (recover + postflight)\\\\n"
+CONTEXT="\${CONTEXT}  2-3 files: + ripple before modify + update .purpose files\\\\n"
+CONTEXT="\${CONTEXT}  3+ files:  + full workflow (ripple, .purpose, lore entry"
+
+if [ "$HAS_PORTAL" = "true" ]; then
+  CONTEXT="\${CONTEXT}, portal.yaml for routes"
+fi
+
+if [ "$HAS_FLOWS" = "true" ]; then
+  CONTEXT="\${CONTEXT}, flow validation"
+fi
+
+CONTEXT="\${CONTEXT})\\\\n"
+
+if [ "$HAS_LORE" = "true" ]; then
+  CONTEXT="\${CONTEXT}\\\\nLORE: This project tracks session history. Record a lore entry when modifying 3+ source files.\\\\n"
+fi
+
+# Output JSON to stdout
+printf '{"additional_context":"%s","continue":true}\\n' "$CONTEXT"
+
 exit 0
 `;
 var CURSOR_STOP_HOOK = `#!/bin/sh
@@ -501,6 +616,26 @@ fi
 
 cd "$CWD" || exit 0
 
+# --- Loop guard: prevent infinite retry loops ---
+# Cursor's stop hook with loop_limit fires repeatedly. Cap retries at 3.
+LOOP_GUARD_FILE=".paradigm/.stop-hook-active"
+if [ -f "$LOOP_GUARD_FILE" ]; then
+  RETRY_COUNT=$(cat "$LOOP_GUARD_FILE" 2>/dev/null | tr -d '[:space:]')
+  RETRY_COUNT=\${RETRY_COUNT:-0}
+  if [ "$RETRY_COUNT" -ge 3 ]; then
+    # Max retries reached \u2014 allow session to end to avoid infinite loop
+    echo "[paradigm] Stop hook: max retries (3) reached. Allowing session to end." >&2
+    rm -f "$LOOP_GUARD_FILE"
+    rm -f ".paradigm/.pending-review"
+    rm -f ".paradigm/.habits-blocking"
+    exit 0
+  fi
+  RETRY_COUNT=$((RETRY_COUNT + 1))
+  echo "$RETRY_COUNT" > "$LOOP_GUARD_FILE"
+else
+  echo "1" > "$LOOP_GUARD_FILE"
+fi
+
 # Get modified files (uncommitted changes)
 MODIFIED=$(git diff --name-only HEAD 2>/dev/null)
 if [ -z "$MODIFIED" ]; then
@@ -703,6 +838,8 @@ fi
 # --- Check 7: Lore entry expected for significant sessions ---
 if [ "$SOURCE_COUNT" -ge 3 ] && [ -d ".paradigm/lore" ]; then
   LORE_RECORDED=false
+
+  # Check git diff first (covers staged/committed lore)
   for file in $MODIFIED; do
     case "$file" in
       .paradigm/lore/entries/*.yaml|.paradigm/lore/entries/*/*.yaml)
@@ -712,6 +849,17 @@ if [ "$SOURCE_COUNT" -ge 3 ] && [ -d ".paradigm/lore" ]; then
     esac
   done
 
+  # Also check for recent lore on disk (covers MCP-written entries not yet staged)
+  if [ "$LORE_RECORDED" = false ]; then
+    TODAY=$(date -u +"%Y-%m-%d")
+    if [ -d ".paradigm/lore/entries/$TODAY" ]; then
+      ENTRY_COUNT=$(find ".paradigm/lore/entries/$TODAY" -name "*.yaml" 2>/dev/null | head -1)
+      if [ -n "$ENTRY_COUNT" ]; then
+        LORE_RECORDED=true
+      fi
+    fi
+  fi
+
   if [ "$LORE_RECORDED" = false ]; then
     VIOLATIONS="$VIOLATIONS
   - You modified $SOURCE_COUNT source files but recorded no lore entry.
@@ -756,6 +904,13 @@ if [ "$VIOLATION_COUNT" -gt 0 ]; then
   echo "  4. paradigm_reindex \u2014 rebuild indexes after updates" >&2
   echo "  5. paradigm_lore_record \u2014 record session lore entry" >&2
   echo "  6. paradigm_habits_check \u2014 evaluate habit compliance" >&2
+
+  # Output followup_message JSON to stdout for Cursor's compliance loop.
+  # Cursor auto-submits this as the next user message, creating a retry loop.
+  # Escape violations for JSON embedding (newlines \u2192 \\n, quotes \u2192 \\", backslash \u2192 \\\\)
+  ESCAPED_VIOLATIONS=$(printf '%s' "$VIOLATIONS" | sed 's/\\\\/\\\\\\\\/g' | sed 's/"/\\\\"/g' | sed ':a;N;$!ba;s/\\n/\\\\n/g')
+  printf '{"followup_message":"Paradigm compliance check found %d violation(s). Fix these:\\\\n%s\\\\nThen try finishing again."}\\n' "$VIOLATION_COUNT" "$ESCAPED_VIOLATIONS"
+
   exit 2
 fi
 
@@ -766,19 +921,25 @@ if [ -n "$ADVISORY" ]; then
   echo "$ADVISORY" >&2
 fi
 
-# Clean up pending-review on pass
+# Clean up pending-review and loop guard on pass
 rm -f ".paradigm/.pending-review"
 rm -f ".paradigm/.habits-blocking"
+rm -f ".paradigm/.stop-hook-active"
 
 exit 0
 `;
 var CURSOR_POSTWRITE_HOOK = `#!/bin/sh
-# Paradigm Cursor PostWrite Hook (v2)
-# Fires after file edits.
-# Tracks modified source files in .paradigm/.pending-review
-# and outputs compliance reminders.
+# Paradigm Cursor PostWrite Hook (v2) \u2014 LEGACY
+# Fires after file edits via Cursor's afterFileEdit hook type.
 # Installed by: paradigm hooks install --cursor
 #
+# IMPORTANT: Cursor ignores all output (stdout + stderr) from afterFileEdit hooks.
+# This hook's advisory messages are INVISIBLE to the agent. The postToolUse hook
+# (cursor-posttooluse.sh) is now the primary advisory mechanism.
+#
+# This hook is kept for backward compatibility and background file tracking only.
+# Both preToolUse and stop hooks depend on the .pending-review file this writes.
+#
 # Hook type: afterFileEdit
 # Exit 0 always (never blocks \u2014 advisory only)
 
@@ -856,18 +1017,8 @@ if [ -z "$found_purpose" ] && [ -f ".purpose" ]; then
   found_purpose=".purpose"
 fi
 
-if [ -z "$found_purpose" ]; then
-  file_dir=$(dirname "$REL_PATH")
-  echo "" >&2
-  echo "[paradigm] No .purpose file covers $file_dir/" >&2
-  echo "  Create one: paradigm_purpose_init + paradigm_purpose_add_component" >&2
-  echo "  $PENDING_COUNT file(s) pending review. The stop hook WILL BLOCK." >&2
-elif [ "$PENDING_COUNT" -gt 0 ] && [ "$((PENDING_COUNT % 3))" -eq 0 ]; then
-  echo "" >&2
-  echo "[paradigm] $PENDING_COUNT source file(s) modified. Update $found_purpose:" >&2
-  echo "  -> #components, ~aspects (with anchors), !signals, \\$flows, ^gates" >&2
-  echo "  The stop hook WILL BLOCK if .purpose files aren't updated." >&2
-fi
+# NOTE: No stderr output here \u2014 Cursor ignores afterFileEdit output.
+# Advisory messages are handled by cursor-posttooluse.sh (postToolUse hook).
 
 exit 0
 `;
@@ -915,6 +1066,263 @@ for f in .paradigm/scan-index.json .paradigm/navigator.yaml .paradigm/flow-index
 done
 
 # Never block \u2014 exit 0
+exit 0
+`;
+var CURSOR_PRETOOLUSE_HOOK = `#!/bin/sh
+# Paradigm Cursor PreToolUse Hook \u2014 Graduated Blocking
+# Fires BEFORE the agent calls Edit or Write.
+# Uses graduated enforcement based on uncovered source edits.
+# Installed by: paradigm hooks install --cursor
+#
+# Hook type: preToolUse
+# Matcher: Edit|Write
+# Exit 0 = allow, Exit 2 = block with stderr message
+#
+# Graduated enforcement:
+#   1-2 uncovered edits \u2192 silent pass (exit 0)
+#   3-4 uncovered edits \u2192 warn via stderr (exit 0)
+#   5+  uncovered edits \u2192 BLOCK (exit 2 + stderr)
+
+# Read JSON from stdin (hook input)
+INPUT=$(cat)
+
+# Extract tool_name and file_path from preToolUse input
+if command -v jq >/dev/null 2>&1; then
+  TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+  FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .input.file_path // empty' 2>/dev/null)
+else
+  TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"tool_name"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
+  FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
+fi
+
+# Must have a file path to check
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Extract workspace root
+if command -v jq >/dev/null 2>&1; then
+  CWD=$(echo "$INPUT" | jq -r '.workspace_roots[0] // empty' 2>/dev/null)
+else
+  CWD=$(echo "$INPUT" | grep -o '"workspace_roots"[[:space:]]*:[[:space:]]*\\["[^"]*"' | head -1 | sed 's/.*\\["//' | sed 's/"$//')
+fi
+
+if [ -z "$CWD" ]; then
+  CWD="$(pwd)"
+fi
+
+# Not a paradigm project \u2014 pass
+if [ ! -d "$CWD/.paradigm" ]; then
+  exit 0
+fi
+
+cd "$CWD" || exit 0
+
+# Convert to relative path
+REL_PATH="$FILE_PATH"
+case "$FILE_PATH" in
+  "$CWD"/*) REL_PATH=$(echo "$FILE_PATH" | sed "s|^$CWD/||") ;;
+esac
+
+# If still absolute, file is outside project \u2014 skip
+case "$REL_PATH" in
+  /*) exit 0 ;;
+esac
+
+# Skip non-source files (paradigm metadata, docs, config)
+case "$REL_PATH" in
+  *.purpose|portal.yaml|*.md|*.lock|*.log|*.json|*.yaml|*.yml|.gitignore|.env*) exit 0 ;;
+esac
+
+# Skip .paradigm, .claude, and .cursor directories
+case "$REL_PATH" in
+  .paradigm/*|.claude/*|.cursor/*) exit 0 ;;
+esac
+
+# Check if target file has a covering .purpose file
+dir=$(dirname "$REL_PATH")
+has_purpose=false
+
+while [ "$dir" != "." ] && [ "$dir" != "/" ] && [ "$dir" != "" ]; do
+  if [ -f "$dir/.purpose" ]; then
+    has_purpose=true
+    break
+  fi
+  dir=$(dirname "$dir")
+done
+
+# Check root .purpose
+if [ "$has_purpose" = false ] && [ -f ".purpose" ]; then
+  has_purpose=true
+fi
+
+# If this file already has .purpose coverage, always allow
+if [ "$has_purpose" = true ]; then
+  exit 0
+fi
+
+# Count uncovered source edits from .pending-review
+PENDING_FILE=".paradigm/.pending-review"
+UNCOVERED_COUNT=0
+
+if [ -f "$PENDING_FILE" ]; then
+  while IFS= read -r tracked_file; do
+    [ -z "$tracked_file" ] && continue
+    # Check if this tracked file has .purpose coverage
+    check_dir=$(dirname "$tracked_file")
+    found=false
+    while [ "$check_dir" != "." ] && [ "$check_dir" != "/" ] && [ "$check_dir" != "" ]; do
+      if [ -f "$check_dir/.purpose" ]; then
+        found=true
+        break
+      fi
+      check_dir=$(dirname "$check_dir")
+    done
+    if [ "$found" = false ] && [ -f ".purpose" ]; then
+      found=true
+    fi
+    if [ "$found" = false ]; then
+      UNCOVERED_COUNT=$((UNCOVERED_COUNT + 1))
+    fi
+  done < "$PENDING_FILE"
+fi
+
+# Include the current file (not yet tracked)
+UNCOVERED_COUNT=$((UNCOVERED_COUNT + 1))
+
+# Graduated enforcement
+if [ "$UNCOVERED_COUNT" -le 2 ]; then
+  # Silent pass \u2014 don't slow down small fixes
+  exit 0
+elif [ "$UNCOVERED_COUNT" -le 4 ]; then
+  # Warn but allow
+  echo "" >&2
+  echo "[paradigm] Warning: $UNCOVERED_COUNT source files modified without .purpose coverage." >&2
+  echo "  Update the nearest .purpose file before the stop hook blocks you." >&2
+  echo "  Use: paradigm_purpose_init + paradigm_purpose_add_component" >&2
+  exit 0
+else
+  # Block \u2014 too many uncovered edits
+  echo "" >&2
+  echo "[paradigm] BLOCKED: $UNCOVERED_COUNT source files modified without .purpose coverage." >&2
+  echo "  You must update .purpose files before continuing." >&2
+  echo "  Steps:" >&2
+  echo "    1. paradigm_purpose_init \u2014 create .purpose in uncovered directories" >&2
+  echo "    2. paradigm_purpose_add_component \u2014 register code units" >&2
+  echo "    3. paradigm_reindex \u2014 rebuild the index" >&2
+  echo "  Then retry your edit." >&2
+  exit 2
+fi
+`;
+var CURSOR_POSTTOOLUSE_HOOK = `#!/bin/sh
+# Paradigm Cursor PostToolUse Hook \u2014 Advisory Feedback
+# Fires AFTER the agent calls Edit or Write.
+# Tracks modified source files and outputs advisory the agent can see.
+# Installed by: paradigm hooks install --cursor
+#
+# Hook type: postToolUse
+# Matcher: Edit|Write
+# Exit 0 always (never blocks \u2014 advisory only)
+#
+# Unlike afterFileEdit, postToolUse output is visible to the Cursor agent.
+# This is the primary advisory mechanism for Cursor enforcement.
+
+# Read JSON from stdin (hook input)
+INPUT=$(cat)
+
+# Extract file_path from postToolUse input
+if command -v jq >/dev/null 2>&1; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .input.file_path // empty' 2>/dev/null)
+else
+  FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Extract workspace root
+if command -v jq >/dev/null 2>&1; then
+  CWD=$(echo "$INPUT" | jq -r '.workspace_roots[0] // empty' 2>/dev/null)
+else
+  CWD=$(echo "$INPUT" | grep -o '"workspace_roots"[[:space:]]*:[[:space:]]*\\["[^"]*"' | head -1 | sed 's/.*\\["//' | sed 's/"$//')
+fi
+
+if [ -z "$CWD" ]; then
+  CWD="$(pwd)"
+fi
+
+# Not a paradigm project \u2014 pass
+if [ ! -d "$CWD/.paradigm" ]; then
+  exit 0
+fi
+
+cd "$CWD" || exit 0
+
+# Convert to relative path
+REL_PATH="$FILE_PATH"
+case "$FILE_PATH" in
+  "$CWD"/*) REL_PATH=$(echo "$FILE_PATH" | sed "s|^$CWD/||") ;;
+esac
+
+# If still absolute, file is outside project \u2014 skip
+case "$REL_PATH" in
+  /*) exit 0 ;;
+esac
+
+# Skip non-source files
+case "$REL_PATH" in
+  *.purpose|portal.yaml|*.md|*.lock|*.log|*.json|*.yaml|*.yml|.gitignore|.env*) exit 0 ;;
+esac
+
+# Skip .paradigm, .claude, and .cursor directories
+case "$REL_PATH" in
+  .paradigm/*|.claude/*|.cursor/*) exit 0 ;;
+esac
+
+# Track: append to .paradigm/.pending-review (deduplicated)
+PENDING_FILE=".paradigm/.pending-review"
+if [ -f "$PENDING_FILE" ]; then
+  if ! grep -qxF "$REL_PATH" "$PENDING_FILE" 2>/dev/null; then
+    echo "$REL_PATH" >> "$PENDING_FILE"
+  fi
+else
+  echo "$REL_PATH" > "$PENDING_FILE"
+fi
+
+# Count pending files
+PENDING_COUNT=$(wc -l < "$PENDING_FILE" | tr -d ' ')
+
+# Walk up from the file's directory to find a .purpose file
+dir=$(dirname "$REL_PATH")
+found_purpose=""
+
+while [ "$dir" != "." ] && [ "$dir" != "/" ] && [ "$dir" != "" ]; do
+  if [ -f "$dir/.purpose" ]; then
+    found_purpose="$dir/.purpose"
+    break
+  fi
+  dir=$(dirname "$dir")
+done
+
+# Check root .purpose
+if [ -z "$found_purpose" ] && [ -f ".purpose" ]; then
+  found_purpose=".purpose"
+fi
+
+if [ -z "$found_purpose" ]; then
+  file_dir=$(dirname "$REL_PATH")
+  echo "" >&2
+  echo "[paradigm] No .purpose file covers $file_dir/" >&2
+  echo "  Create one: paradigm_purpose_init + paradigm_purpose_add_component" >&2
+  echo "  $PENDING_COUNT file(s) pending review. The stop hook WILL BLOCK." >&2
+elif [ "$PENDING_COUNT" -gt 0 ] && [ "$((PENDING_COUNT % 3))" -eq 0 ]; then
+  echo "" >&2
+  echo "[paradigm] $PENDING_COUNT source file(s) modified. Update $found_purpose:" >&2
+  echo "  -> #components, ~aspects (with anchors), !signals, \\$flows, ^gates" >&2
+  echo "  The stop hook WILL BLOCK if .purpose files aren't updated." >&2
+fi
+
 exit 0
 `;
 
@@ -938,6 +1346,68 @@ function isParadigmPluginActive() {
     return { active: false };
   }
 }
+function checkPluginVersionCompatibility() {
+  try {
+    const pluginInfo = isParadigmPluginActive();
+    if (!pluginInfo.active || !pluginInfo.cacheVersion) {
+      return { compatible: true };
+    }
+    const hooksJsonPath = path.join(
+      os.homedir(),
+      ".claude",
+      "plugins",
+      "cache",
+      "a-paradigm",
+      "paradigm",
+      pluginInfo.cacheVersion,
+      "hooks.json"
+    );
+    if (!fs.existsSync(hooksJsonPath)) {
+      return { compatible: true };
+    }
+    const hooksData = JSON.parse(fs.readFileSync(hooksJsonPath, "utf8"));
+    const compatibleVersions = hooksData.compatibleVersions;
+    if (!compatibleVersions) {
+      return { compatible: true };
+    }
+    const currentVersion = getCurrentParadigmVersion();
+    if (!currentVersion) {
+      return { compatible: true };
+    }
+    const parts = compatibleVersions.split(/\s+/);
+    for (const part of parts) {
+      const match = part.match(/^(>=?|<=?)\s*(\d+\.\d+\.\d+)/);
+      if (!match) continue;
+      const [, op, ver] = match;
+      const cmp = compareVersions(currentVersion, ver);
+      if (op === ">=" && cmp < 0) return { compatible: false, message: `Plugin requires paradigm ${compatibleVersions}, current: ${currentVersion}` };
+      if (op === ">" && cmp <= 0) return { compatible: false, message: `Plugin requires paradigm ${compatibleVersions}, current: ${currentVersion}` };
+      if (op === "<=" && cmp > 0) return { compatible: false, message: `Plugin requires paradigm ${compatibleVersions}, current: ${currentVersion}` };
+      if (op === "<" && cmp >= 0) return { compatible: false, message: `Plugin requires paradigm ${compatibleVersions}, current: ${currentVersion}` };
+    }
+    return { compatible: true };
+  } catch {
+    return { compatible: true };
+  }
+}
+function getCurrentParadigmVersion() {
+  try {
+    const pkgPath = path.join(path.dirname(new URL(import.meta.url).pathname), "..", "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return pkg.version || null;
+  } catch {
+    return null;
+  }
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+  }
+  return 0;
+}
 function cleanupProjectClaudeCodeHooks(rootDir) {
   const removed = [];
   const claudeHooksDir = path.join(rootDir, ".claude", "hooks");
@@ -993,6 +1463,25 @@ function cleanupProjectClaudeCodeHooks(rootDir) {
   }
   return { cleaned: removed.length > 0, removed };
 }
+function validateBashSyntax(scriptContent, scriptName) {
+  try {
+    const tmpPath = path.join(os.tmpdir(), `paradigm-hook-validate-${Date.now()}.sh`);
+    fs.writeFileSync(tmpPath, scriptContent, "utf8");
+    try {
+      execSync(`bash -n "${tmpPath}" 2>&1`, { encoding: "utf-8" });
+      return null;
+    } catch (err) {
+      return `${scriptName}: bash syntax error \u2014 ${err.message?.split("\n")[0] || "unknown error"}`;
+    } finally {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+      }
+    }
+  } catch {
+    return null;
+  }
+}
 var POST_COMMIT_HOOK = `#!/bin/sh
 # Paradigm post-commit hook - captures history from commits
 # Installed by: paradigm hooks install
@@ -1089,8 +1578,41 @@ fi
 `;
 async function hooksInstallCommand(options = {}) {
   const rootDir = process.cwd();
+  const dryRun = options.dryRun || false;
+  if (dryRun) {
+    console.log(chalk.cyan("\n  [dry-run] Showing what would be installed:\n"));
+  }
   const onlyClaudeCode = options.claudeCode && !options.postCommit && !options.prePush && !options.cursor;
   const onlyCursor = options.cursor && !options.postCommit && !options.prePush && !options.claudeCode;
+  if (!dryRun) {
+    const scriptsToValidate = [
+      { name: "post-commit", content: POST_COMMIT_HOOK },
+      { name: "pre-push", content: PRE_PUSH_HOOK },
+      { name: "claude-code-stop", content: CLAUDE_CODE_STOP_HOOK },
+      { name: "claude-code-precommit", content: CLAUDE_CODE_PRECOMMIT_HOOK },
+      { name: "claude-code-postwrite", content: CLAUDE_CODE_POSTWRITE_HOOK },
+      { name: "cursor-session-start", content: CURSOR_SESSION_START_HOOK },
+      { name: "cursor-stop", content: CURSOR_STOP_HOOK },
+      { name: "cursor-precommit", content: CURSOR_PRECOMMIT_HOOK },
+      { name: "cursor-postwrite", content: CURSOR_POSTWRITE_HOOK },
+      { name: "cursor-pretooluse", content: CURSOR_PRETOOLUSE_HOOK },
+      { name: "cursor-posttooluse", content: CURSOR_POSTTOOLUSE_HOOK }
+    ];
+    for (const script of scriptsToValidate) {
+      const err = validateBashSyntax(script.content, script.name);
+      if (err) {
+        console.log(chalk.red(`Hook syntax error: ${err}`));
+        console.log(chalk.gray("Aborting installation. Fix the hook script and try again."));
+        return;
+      }
+    }
+  }
+  const compat = checkPluginVersionCompatibility();
+  if (!compat.compatible) {
+    console.log(chalk.yellow(`
+\u26A0  ${compat.message}`));
+    console.log(chalk.gray("  Hook installation will continue, but behavior may differ from plugin expectations.\n"));
+  }
   if (!onlyClaudeCode && !onlyCursor) {
     const gitDir = path.join(rootDir, ".git");
     if (!fs.existsSync(gitDir)) {
@@ -1098,53 +1620,79 @@ async function hooksInstallCommand(options = {}) {
       return;
     }
     const hooksDir = path.join(gitDir, "hooks");
-    fs.mkdirSync(hooksDir, { recursive: true });
-    const installAll2 = !options.postCommit && !options.prePush && !options.claudeCode;
+    const installAllGit = !options.postCommit && !options.prePush && !options.claudeCode;
     const installed = [];
-    if (installAll2 || options.postCommit) {
+    if (installAllGit || options.postCommit) {
       const hookPath = path.join(hooksDir, "post-commit");
-      if (fs.existsSync(hookPath) && !options.force) {
-        const content = fs.readFileSync(hookPath, "utf8");
-        if (!content.includes("paradigm")) {
-          console.log(chalk.yellow("post-commit hook exists. Use --force to overwrite."));
+      if (dryRun) {
+        const action = fs.existsSync(hookPath) && !options.force ? "skip (exists)" : "install";
+        console.log(chalk.gray(`  post-commit: ${action} \u2192 ${hookPath}`));
+      } else {
+        if (fs.existsSync(hookPath) && !options.force) {
+          const content = fs.readFileSync(hookPath, "utf8");
+          if (!content.includes("paradigm")) {
+            console.log(chalk.yellow("post-commit hook exists. Use --force to overwrite."));
+          } else {
+            console.log(chalk.gray("post-commit hook already installed by paradigm"));
+          }
         } else {
-          console.log(chalk.gray("post-commit hook already installed by paradigm"));
+          fs.mkdirSync(hooksDir, { recursive: true });
+          fs.writeFileSync(hookPath, POST_COMMIT_HOOK);
+          fs.chmodSync(hookPath, "755");
+          installed.push("post-commit");
         }
-      } else {
-        fs.writeFileSync(hookPath, POST_COMMIT_HOOK);
-        fs.chmodSync(hookPath, "755");
-        installed.push("post-commit");
       }
     }
-    if (installAll2 || options.prePush) {
+    if (installAllGit || options.prePush) {
       const hookPath = path.join(hooksDir, "pre-push");
-      if (fs.existsSync(hookPath) && !options.force) {
-        const content = fs.readFileSync(hookPath, "utf8");
-        if (!content.includes("paradigm")) {
-          console.log(chalk.yellow("pre-push hook exists. Use --force to overwrite."));
+      if (dryRun) {
+        const action = fs.existsSync(hookPath) && !options.force ? "skip (exists)" : "install";
+        console.log(chalk.gray(`  pre-push: ${action} \u2192 ${hookPath}`));
+      } else {
+        if (fs.existsSync(hookPath) && !options.force) {
+          const content = fs.readFileSync(hookPath, "utf8");
+          if (!content.includes("paradigm")) {
+            console.log(chalk.yellow("pre-push hook exists. Use --force to overwrite."));
+          } else {
+            console.log(chalk.gray("pre-push hook already installed by paradigm"));
+          }
         } else {
-          console.log(chalk.gray("pre-push hook already installed by paradigm"));
+          fs.mkdirSync(hooksDir, { recursive: true });
+          fs.writeFileSync(hookPath, PRE_PUSH_HOOK);
+          fs.chmodSync(hookPath, "755");
+          installed.push("pre-push");
         }
-      } else {
-        fs.writeFileSync(hookPath, PRE_PUSH_HOOK);
-        fs.chmodSync(hookPath, "755");
-        installed.push("pre-push");
       }
     }
-    if (installed.length > 0) {
+    if (!dryRun && installed.length > 0) {
       console.log(chalk.green(`Git hooks installed: ${installed.join(", ")}`));
     }
     const historyDir = path.join(rootDir, ".paradigm/history");
-    if (!fs.existsSync(historyDir)) {
+    if (!fs.existsSync(historyDir) && !dryRun) {
       console.log(chalk.gray("Tip: Run `paradigm history init` to initialize history tracking"));
     }
   }
   const installAll = !options.postCommit && !options.prePush && !options.claudeCode && !options.cursor;
   if (installAll || options.claudeCode) {
-    await installClaudeCodeHooks(rootDir, options.force);
+    if (dryRun) {
+      console.log(chalk.gray("  Claude Code hooks: would install paradigm-stop.sh, paradigm-precommit.sh, paradigm-postwrite.sh"));
+      console.log(chalk.gray(`  \u2192 ${path.join(rootDir, ".claude", "hooks")}/`));
+      console.log(chalk.gray("  \u2192 Update .claude/settings.json with hook configuration"));
+    } else {
+      await installClaudeCodeHooks(rootDir, options.force);
+    }
   }
   if (installAll || options.cursor) {
-    await installCursorHooks(rootDir, options.force);
+    if (dryRun) {
+      console.log(chalk.gray("  Cursor hooks: would install paradigm-session-start.sh, paradigm-stop.sh, paradigm-precommit.sh, paradigm-postwrite.sh, paradigm-pretooluse.sh, paradigm-posttooluse.sh"));
+      console.log(chalk.gray(`  \u2192 ${path.join(rootDir, ".cursor", "hooks")}/`));
+      console.log(chalk.gray("  \u2192 Update .cursor/hooks.json"));
+    } else {
+      await installCursorHooks(rootDir, options.force);
+    }
+  }
+  if (dryRun) {
+    console.log(chalk.cyan("\n  [dry-run] No changes made.\n"));
   }
 }
 async function installClaudeCodeHooks(rootDir, force) {
@@ -1246,9 +1794,12 @@ async function installCursorHooks(rootDir, force) {
   fs.mkdirSync(cursorHooksDir, { recursive: true });
   const installed = [];
   const hookScripts = [
+    { name: "paradigm-session-start.sh", content: CURSOR_SESSION_START_HOOK },
     { name: "paradigm-stop.sh", content: CURSOR_STOP_HOOK },
     { name: "paradigm-precommit.sh", content: CURSOR_PRECOMMIT_HOOK },
-    { name: "paradigm-postwrite.sh", content: CURSOR_POSTWRITE_HOOK }
+    { name: "paradigm-postwrite.sh", content: CURSOR_POSTWRITE_HOOK },
+    { name: "paradigm-pretooluse.sh", content: CURSOR_PRETOOLUSE_HOOK },
+    { name: "paradigm-posttooluse.sh", content: CURSOR_POSTTOOLUSE_HOOK }
   ];
   for (const hook of hookScripts) {
     const destPath = path.join(cursorHooksDir, hook.name);
@@ -1270,9 +1821,14 @@ async function installCursorHooks(rootDir, force) {
   }
   hooksConfig.version = 1;
   const hooks = hooksConfig.hooks || {};
+  const paradigmSessionStartEntry = {
+    command: ".cursor/hooks/paradigm-session-start.sh",
+    timeout: 5
+  };
   const paradigmStopEntry = {
     command: ".cursor/hooks/paradigm-stop.sh",
-    timeout: 10
+    timeout: 10,
+    loop_limit: 3
   };
   const paradigmPostwriteEntry = {
     command: ".cursor/hooks/paradigm-postwrite.sh",
@@ -1283,6 +1839,14 @@ async function installCursorHooks(rootDir, force) {
     matcher: "git commit",
     timeout: 30
   };
+  const sessionStartHooks = hooks.sessionStart || [];
+  const hasParadigmSessionStart = sessionStartHooks.some(
+    (h) => JSON.stringify(h).includes("paradigm-session-start.sh")
+  );
+  if (!hasParadigmSessionStart) {
+    sessionStartHooks.push(paradigmSessionStartEntry);
+  }
+  hooks.sessionStart = sessionStartHooks;
   const stopHooks = hooks.stop || [];
   const hasParadigmStop = stopHooks.some(
     (h) => JSON.stringify(h).includes("paradigm-stop.sh")
@@ -1299,6 +1863,32 @@ async function installCursorHooks(rootDir, force) {
     afterFileEditHooks.push(paradigmPostwriteEntry);
   }
   hooks.afterFileEdit = afterFileEditHooks;
+  const paradigmPretoolUseEntry = {
+    command: ".cursor/hooks/paradigm-pretooluse.sh",
+    matcher: "Edit|Write",
+    timeout: 5
+  };
+  const preToolUseHooks = hooks.preToolUse || [];
+  const hasParadigmPretoolUse = preToolUseHooks.some(
+    (h) => JSON.stringify(h).includes("paradigm-pretooluse.sh")
+  );
+  if (!hasParadigmPretoolUse) {
+    preToolUseHooks.push(paradigmPretoolUseEntry);
+  }
+  hooks.preToolUse = preToolUseHooks;
+  const paradigmPosttoolUseEntry = {
+    command: ".cursor/hooks/paradigm-posttooluse.sh",
+    matcher: "Edit|Write",
+    timeout: 5
+  };
+  const postToolUseHooks = hooks.postToolUse || [];
+  const hasParadigmPosttoolUse = postToolUseHooks.some(
+    (h) => JSON.stringify(h).includes("paradigm-posttooluse.sh")
+  );
+  if (!hasParadigmPosttoolUse) {
+    postToolUseHooks.push(paradigmPosttoolUseEntry);
+  }
+  hooks.postToolUse = postToolUseHooks;
   const beforeShellHooks = hooks.beforeShellExecution || [];
   const hasParadigmPrecommit = beforeShellHooks.some(
     (h) => JSON.stringify(h).includes("paradigm-precommit.sh")
@@ -1316,6 +1906,10 @@ async function installCursorHooks(rootDir, force) {
 }
 async function hooksUninstallCommand(options = {}) {
   const rootDir = process.cwd();
+  const dryRun = options.dryRun || false;
+  if (dryRun) {
+    console.log(chalk.cyan("\n  [dry-run] Showing what would be removed:\n"));
+  }
   if (!options.cursor) {
     const gitDir = path.join(rootDir, ".git");
     if (!fs.existsSync(gitDir)) {
@@ -1329,53 +1923,76 @@ async function hooksUninstallCommand(options = {}) {
       if (fs.existsSync(hookPath)) {
         const content = fs.readFileSync(hookPath, "utf8");
         if (content.includes("paradigm")) {
-          fs.unlinkSync(hookPath);
+          if (dryRun) {
+            console.log(chalk.gray(`  Would remove: ${hookPath}`));
+          } else {
+            fs.unlinkSync(hookPath);
+          }
           removed.push(hookName);
         }
       }
     }
-    if (removed.length > 0) {
-      console.log(chalk.green(`Git hooks removed: ${removed.join(", ")}`));
-    } else {
-      console.log(chalk.gray("No paradigm git hooks found to remove"));
+    if (!dryRun) {
+      if (removed.length > 0) {
+        console.log(chalk.green(`Git hooks removed: ${removed.join(", ")}`));
+      } else {
+        console.log(chalk.gray("No paradigm git hooks found to remove"));
+      }
+    } else if (removed.length === 0) {
+      console.log(chalk.gray("  No paradigm git hooks to remove"));
     }
   }
   if (options.cursor) {
     const cursorHooksDir = path.join(rootDir, ".cursor", "hooks");
     const cursorRemoved = [];
-    for (const hookName of ["paradigm-stop.sh", "paradigm-precommit.sh", "paradigm-postwrite.sh"]) {
+    for (const hookName of ["paradigm-session-start.sh", "paradigm-stop.sh", "paradigm-precommit.sh", "paradigm-postwrite.sh", "paradigm-pretooluse.sh", "paradigm-posttooluse.sh"]) {
       const hookPath = path.join(cursorHooksDir, hookName);
       if (fs.existsSync(hookPath)) {
-        fs.unlinkSync(hookPath);
+        if (dryRun) {
+          console.log(chalk.gray(`  Would remove: ${hookPath}`));
+        } else {
+          fs.unlinkSync(hookPath);
+        }
         cursorRemoved.push(hookName);
       }
     }
     const hooksJsonPath = path.join(rootDir, ".cursor", "hooks.json");
     if (fs.existsSync(hooksJsonPath)) {
-      try {
-        const hooksConfig = JSON.parse(fs.readFileSync(hooksJsonPath, "utf8"));
-        const hooks = hooksConfig.hooks || {};
-        for (const key of ["stop", "afterFileEdit", "beforeShellExecution"]) {
-          if (Array.isArray(hooks[key])) {
-            hooks[key] = hooks[key].filter(
-              (h) => !JSON.stringify(h).includes("paradigm-")
-            );
-            if (hooks[key].length === 0) {
-              delete hooks[key];
+      if (dryRun) {
+        console.log(chalk.gray(`  Would clean paradigm entries from: ${hooksJsonPath}`));
+      } else {
+        try {
+          const hooksConfig = JSON.parse(fs.readFileSync(hooksJsonPath, "utf8"));
+          const hooks = hooksConfig.hooks || {};
+          for (const key of ["sessionStart", "stop", "afterFileEdit", "beforeShellExecution", "preToolUse", "postToolUse"]) {
+            if (Array.isArray(hooks[key])) {
+              hooks[key] = hooks[key].filter(
+                (h) => !JSON.stringify(h).includes("paradigm-")
+              );
+              if (hooks[key].length === 0) {
+                delete hooks[key];
+              }
             }
           }
+          hooksConfig.hooks = hooks;
+          fs.writeFileSync(hooksJsonPath, JSON.stringify(hooksConfig, null, 2) + "\n", "utf8");
+        } catch {
         }
-        hooksConfig.hooks = hooks;
-        fs.writeFileSync(hooksJsonPath, JSON.stringify(hooksConfig, null, 2) + "\n", "utf8");
-      } catch {
       }
     }
-    if (cursorRemoved.length > 0) {
-      console.log(chalk.green(`Cursor hooks removed: ${cursorRemoved.join(", ")}`));
-    } else {
-      console.log(chalk.gray("No paradigm Cursor hooks found to remove"));
+    if (!dryRun) {
+      if (cursorRemoved.length > 0) {
+        console.log(chalk.green(`Cursor hooks removed: ${cursorRemoved.join(", ")}`));
+      } else {
+        console.log(chalk.gray("No paradigm Cursor hooks found to remove"));
+      }
+    } else if (cursorRemoved.length === 0) {
+      console.log(chalk.gray("  No paradigm Cursor hooks to remove"));
     }
   }
+  if (dryRun) {
+    console.log(chalk.cyan("\n  [dry-run] No changes made.\n"));
+  }
 }
 async function hooksStatusCommand() {
   const rootDir = process.cwd();
@@ -1471,7 +2088,7 @@ async function hooksStatusCommand() {
   }
   console.log(chalk.magenta("\n  Cursor Hooks Status\n"));
   const cursorHooksDir = path.join(rootDir, ".cursor", "hooks");
-  const cursorHooks = ["paradigm-stop.sh", "paradigm-precommit.sh", "paradigm-postwrite.sh"];
+  const cursorHooks = ["paradigm-session-start.sh", "paradigm-stop.sh", "paradigm-precommit.sh", "paradigm-postwrite.sh", "paradigm-pretooluse.sh", "paradigm-posttooluse.sh"];
   for (const hookName of cursorHooks) {
     const hookPath = path.join(cursorHooksDir, hookName);
     if (fs.existsSync(hookPath)) {
@@ -1485,11 +2102,17 @@ async function hooksStatusCommand() {
     try {
       const hooksJson = JSON.parse(fs.readFileSync(cursorHooksJsonPath, "utf8"));
       const hooks = hooksJson.hooks || {};
+      const hasSessionStart = JSON.stringify(hooks.sessionStart || []).includes("paradigm-session-start.sh");
       const hasStop = JSON.stringify(hooks.stop || []).includes("paradigm-stop.sh");
       const hasPostwrite = JSON.stringify(hooks.afterFileEdit || []).includes("paradigm-postwrite.sh");
       const hasPrecommit = JSON.stringify(hooks.beforeShellExecution || []).includes("paradigm-precommit.sh");
+      const hasPretoolUse = JSON.stringify(hooks.preToolUse || []).includes("paradigm-pretooluse.sh");
+      const hasPosttoolUse = JSON.stringify(hooks.postToolUse || []).includes("paradigm-posttooluse.sh");
+      console.log(chalk.gray(`  hooks.json sessionStart: ${hasSessionStart ? "configured" : "missing"}`));
       console.log(chalk.gray(`  hooks.json stop: ${hasStop ? "configured" : "missing"}`));
       console.log(chalk.gray(`  hooks.json afterFileEdit: ${hasPostwrite ? "configured" : "missing"}`));
+      console.log(chalk.gray(`  hooks.json preToolUse: ${hasPretoolUse ? "configured" : "missing"}`));
+      console.log(chalk.gray(`  hooks.json postToolUse: ${hasPosttoolUse ? "configured" : "missing"}`));
       console.log(chalk.gray(`  hooks.json beforeShellExecution: ${hasPrecommit ? "configured" : "missing"}`));
     } catch {
       console.log(chalk.yellow("  hooks.json: parse error"));