specweave 0.23.10 → 0.23.14

package/plugins/specweave/hooks/post-user-story-complete.sh.backup

@@ -0,0 +1,179 @@
+#!/bin/bash
+
+###############################################################################
+# SpecWeave Post-User-Story-Complete Hook
+#
+# CRITICAL ARCHITECTURE:
+# - Fires when user story marked complete in spec.md (AC checkbox checked)
+# - Updates external PM tool (GitHub Issue/Jira Story/ADO User Story)
+# - Moves GitHub card to "Done" / Closes Jira story / Completes ADO story
+#
+# Trigger Points:
+# 1. After user manually checks AC checkbox in spec.md
+# 2. After bidirectional sync updates AC status
+# 3. After increment completion syncs to spec
+#
+# What It Does:
+# - Detects which user story was completed (all AC checkboxes checked)
+# - Finds corresponding external item (GitHub Issue/Jira Story/ADO User Story)
+# - Updates item status to "Done" / "Closed"
+# - Adds completion comment with timestamp
+#
+# Usage:
+#   post-user-story-complete.sh <spec-id> <user-story-id>
+#
+# Example:
+#   post-user-story-complete.sh spec-001 US-001
+#
+###############################################################################
+
+set -euo pipefail
+
+# Arguments
+SPEC_ID="${1:-}"
+USER_STORY_ID="${2:-}"
+
+# Validate arguments
+if [[ -z "$SPEC_ID" || -z "$USER_STORY_ID" ]]; then
+  echo "❌ Error: Spec ID and User Story ID required"
+  echo "Usage: post-user-story-complete.sh <spec-id> <user-story-id>"
+  exit 1
+fi
+
+echo ""
+echo "🎉 Post-User-Story-Complete Hook"
+echo "   Spec: $SPEC_ID"
+echo "   User Story: $USER_STORY_ID"
+
+# Find spec file
+SPEC_FILE=""
+if [[ -f ".specweave/docs/internal/specs/$SPEC_ID.md" ]]; then
+  SPEC_FILE=".specweave/docs/internal/specs/$SPEC_ID.md"
+elif [[ -f ".specweave/docs/internal/projects/default/specs/$SPEC_ID.md" ]]; then
+  SPEC_FILE=".specweave/docs/internal/projects/default/specs/$SPEC_ID.md"
+else
+  echo "❌ Error: Spec file not found for $SPEC_ID"
+  exit 1
+fi
+
+# Load config to check if auto-sync is enabled
+CONFIG_FILE=".specweave/config.json"
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "   ℹ️  No config file found, skipping auto-sync"
+  exit 0
+fi
+
+# Check if auto-sync is enabled
+AUTO_SYNC=$(jq -r '.hooks.post_user_story_complete.auto_sync // true' "$CONFIG_FILE")
+
+if [[ "$AUTO_SYNC" != "true" ]]; then
+  echo "   ℹ️  Auto-sync disabled in config, skipping"
+  exit 0
+fi
+
+# Parse spec frontmatter to detect external links
+# Check if GitHub link exists
+GITHUB_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "github:" | grep "projectId:" | sed 's/.*projectId: *//; s/ *$//' || echo "")
+
+# Check if Jira link exists
+JIRA_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "jira:" | grep "epicKey:" | sed 's/.*epicKey: *//; s/ *$//' || echo "")
+
+# Check if ADO link exists
+ADO_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "ado:" | grep "featureId:" | sed 's/.*featureId: *//; s/ *$//' || echo "")
+
+# Determine which provider to sync
+PROVIDER=""
+if [[ -n "$GITHUB_LINK" ]]; then
+  PROVIDER="github"
+  EXTERNAL_ID="$GITHUB_LINK"
+elif [[ -n "$JIRA_LINK" ]]; then
+  PROVIDER="jira"
+  EXTERNAL_ID="$JIRA_LINK"
+elif [[ -n "$ADO_LINK" ]]; then
+  PROVIDER="ado"
+  EXTERNAL_ID="$ADO_LINK"
+fi
+
+# No external link found - skip sync
+if [[ -z "$PROVIDER" ]]; then
+  echo "   ℹ️  Spec not linked to external tool, skipping sync"
+  exit 0
+fi
+
+echo "   🔗 Detected external link: $PROVIDER"
+
+# Update external tool based on provider
+case "$PROVIDER" in
+  github)
+    echo "   🔄 Updating GitHub Issue for $USER_STORY_ID..."
+
+    # Check if GitHub CLI is available
+    if ! command -v gh &> /dev/null; then
+      echo "   ⚠️  GitHub CLI (gh) not found, skipping sync"
+      exit 0
+    fi
+
+    # Find GitHub Issue for this user story
+    # Search for issue with title pattern "[USER_STORY_ID]"
+    REPO=$(git remote get-url origin | sed -E 's/.*github\.com[:/]([^/]+\/[^/]+)(\.git)?$/\1/')
+
+    # Search for issue
+    ISSUE_NUMBER=$(gh issue list --repo "$REPO" --search "\"[$USER_STORY_ID]\" in:title" --json number --jq '.[0].number' 2>/dev/null || echo "")
+
+    if [[ -z "$ISSUE_NUMBER" ]]; then
+      echo "   ⚠️  GitHub Issue not found for $USER_STORY_ID"
+      exit 0
+    fi
+
+    echo "   📝 Found GitHub Issue #$ISSUE_NUMBER"
+
+    # Close issue
+    gh issue close "$ISSUE_NUMBER" --repo "$REPO" --comment "✅ User story completed
+
+🤖 Auto-closed by SpecWeave hook
+Completed at: $(date -u +%Y-%m-%dT%H:%M:%SZ)" 2>/dev/null || {
+      echo "   ⚠️  Failed to close issue"
+      exit 0
+    }
+
+    echo "   ✅ GitHub Issue #$ISSUE_NUMBER closed"
+    ;;
+
+  jira)
+    echo "   🔄 Updating Jira Story for $USER_STORY_ID..."
+
+    # Check if Jira config exists
+    if [[ -z "${JIRA_DOMAIN:-}" ]]; then
+      echo "   ⚠️  Jira not configured (.env), skipping sync"
+      exit 0
+    fi
+
+    # TODO: Find Jira Story by title pattern
+    # TODO: Transition story to "Done" status
+    echo "   ✅ Jira story transition queued (implementation pending)"
+    ;;
+
+  ado)
+    echo "   🔄 Updating ADO User Story for $USER_STORY_ID..."
+
+    # Check if ADO config exists
+    if [[ -z "${ADO_ORGANIZATION:-}" ]]; then
+      echo "   ⚠️  ADO not configured (.env), skipping sync"
+      exit 0
+    fi
+
+    # TODO: Find ADO User Story by title pattern
+    # TODO: Update state to "Closed"
+    echo "   ✅ ADO user story update queued (implementation pending)"
+    ;;
+
+  *)
+    echo "   ⚠️  Unknown provider: $PROVIDER"
+    exit 0
+    ;;
+esac
+
+echo "   ✅ Post-user-story-complete hook complete"
+echo ""
+
+exit 0

package/plugins/specweave/hooks/post-write-spec.sh

@@ -5,12 +5,30 @@
 # Triggers: After Write tool creates/replaces spec.md or tasks.md
 # Action: Updates status line cache to reflect latest AC/task progress
 #
-# CRITICAL FIX (v0.24.1): Enhanced file detection to handle increment completion
+# EMERGENCY FIXES (v0.24.3):
+# - Kill switch: Set SPECWEAVE_DISABLE_HOOKS=1 to disable ALL hooks
+# - Circuit breaker: Auto-disable after 3 consecutive failures
+# - File locking: Prevent concurrent executions (max 1 at a time)
+# - Aggressive debouncing: Increased from 1s to 5s
+# - Complete error isolation: Never let errors reach Claude Code
+#
+# TIER 1 IMPROVEMENTS (v0.24.2):
+# - Debouncing: Skip if updated less than 1 second ago (90% overhead reduction)
+# - File mtime detection: Check recently modified spec.md/tasks.md as fallback
+# - Non-blocking: Run update-status-line.sh in background
+# - Smart detection: Only update if spec/tasks files actually changed
+#
+# Previous fix (v0.24.1): Enhanced file detection for increment completion
 # - Detects writes via TOOL_USE_CONTENT, TOOL_RESULT, and argument parsing
 # - Always updates status line for ANY spec.md/tasks.md write in increments folder
-# - Matches post-edit-spec.sh robustness improvements
 
-set -e
+# CRITICAL: Remove set -e to prevent hook errors from crashing Claude Code
+set +e
+
+# EMERGENCY KILL SWITCH: Disable all hooks if env variable set
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
 
 # Find project root
 find_project_root() {
@@ -29,31 +47,134 @@ PROJECT_ROOT=$(find_project_root)
 LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
 DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
 
-# Ensure logs directory exists
-mkdir -p "$LOGS_DIR" 2>/dev/null || true
+# Ensure state and logs directories exist
+mkdir -p "$PROJECT_ROOT/.specweave/state" "$LOGS_DIR" 2>/dev/null || true
 
-# Extract written file from multiple sources (Claude Code provides this in various ways)
-WRITTEN_FILE=""
+# EMERGENCY CIRCUIT BREAKER: Track consecutive failures
+CIRCUIT_BREAKER_FILE="$PROJECT_ROOT/.specweave/state/.hook-circuit-breaker"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+if [[ -f "$CIRCUIT_BREAKER_FILE" ]]; then
+  FAILURE_COUNT=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  if (( FAILURE_COUNT >= CIRCUIT_BREAKER_THRESHOLD )); then
+    echo "[$(date)] CIRCUIT BREAKER OPEN: Hooks disabled after $FAILURE_COUNT failures. Run: rm $CIRCUIT_BREAKER_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# EMERGENCY FILE LOCK: Prevent concurrent executions
+LOCK_FILE="$PROJECT_ROOT/.specweave/state/.hook-post-write.lock"
+LOCK_TIMEOUT=5  # seconds
+
+# Try to acquire lock with timeout
+LOCK_ACQUIRED=false
+for i in {1..5}; do
+  if mkdir "$LOCK_FILE" 2>/dev/null; then
+    LOCK_ACQUIRED=true
+    trap 'rmdir "$LOCK_FILE" 2>/dev/null || true' EXIT
+    break
+  fi
+
+  # Check if lock is stale (older than LOCK_TIMEOUT seconds)
+  if [[ -d "$LOCK_FILE" ]]; then
+    LOCK_AGE=$(($(date +%s) - $(stat -f "%m" "$LOCK_FILE" 2>/dev/null || echo 0)))
+    if (( LOCK_AGE > LOCK_TIMEOUT )); then
+      rmdir "$LOCK_FILE" 2>/dev/null || true
+      continue
+    fi
+  fi
+
+  sleep 0.2
+done
+
+if [[ "$LOCK_ACQUIRED" == "false" ]]; then
+  echo "[$(date)] post-write-spec: Could not acquire lock, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Log rotation: Keep debug log under 100KB
+if [[ -f "$DEBUG_LOG" ]] && [[ $(wc -c < "$DEBUG_LOG" 2>/dev/null || echo 0) -gt 102400 ]]; then
+  tail -100 "$DEBUG_LOG" > "$DEBUG_LOG.tmp" 2>/dev/null || true
+  mv "$DEBUG_LOG.tmp" "$DEBUG_LOG" 2>/dev/null || true
+  echo "[$(date)] Log rotated" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# TIER 1 FIX: Debouncing (Prevent Redundant Updates)
+# ============================================================================
+# Skip update if we updated less than 5 seconds ago (INCREASED FROM 1s)
+# This handles rapid consecutive writes (e.g., spec.md regeneration)
+LAST_UPDATE_FILE="$PROJECT_ROOT/.specweave/state/.last-status-update"
+DEBOUNCE_SECONDS=5
+
+if [[ -f "$LAST_UPDATE_FILE" ]]; then
+  LAST_UPDATE=$(cat "$LAST_UPDATE_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  TIME_SINCE_UPDATE=$((NOW - LAST_UPDATE))
 
-# Method 1: TOOL_USE_CONTENT environment variable (primary)
-if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
-  WRITTEN_FILE="$TOOL_USE_CONTENT"
+  if (( TIME_SINCE_UPDATE < DEBOUNCE_SECONDS )); then
+    echo "[$(date)] post-write-spec: Debounced (${TIME_SINCE_UPDATE}s since last update)" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0  # Skip this update
+  fi
 fi
 
-# Method 2: TOOL_RESULT environment variable (fallback)
-if [[ -z "$WRITTEN_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
-  # Extract file_path from tool result JSON
-  WRITTEN_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+# ============================================================================
+# TIER 2: Check for PreToolUse Signal (Primary Detection Method)
+# ============================================================================
+PENDING_FILE="$PROJECT_ROOT/.specweave/state/.pending-status-update"
+METRICS_FILE="$PROJECT_ROOT/.specweave/state/hook-metrics.jsonl"
+WRITTEN_FILE=""
+DETECTION_METHOD="none"
+
+# First, check if PreToolUse hook left a signal
+if [[ -f "$PENDING_FILE" ]]; then
+  WRITTEN_FILE=$(cat "$PENDING_FILE" 2>/dev/null || echo "")
+  # Delete pending file immediately (consume signal)
+  rm "$PENDING_FILE" 2>/dev/null || true
+
+  if [[ -n "$WRITTEN_FILE" ]]; then
+    DETECTION_METHOD="pretooluse"
+    echo "[$(date)] post-write-spec: File from PreToolUse signal: $WRITTEN_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Record Tier 2 success metric
+    TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"hook\":\"post-write-spec\",\"event\":\"tier2_success\",\"method\":\"pretooluse\"}" >> "$METRICS_FILE" 2>/dev/null || true
+  fi
 fi
 
-# Method 3: Parse tool use arguments (last resort)
-if [[ -z "$WRITTEN_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
-  # Extract file_path from tool arguments
-  WRITTEN_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+# ============================================================================
+# TIER 1 FALLBACK: Environment Variable Detection
+# ============================================================================
+# If PreToolUse didn't provide signal, fall back to Tier 1 methods
+if [[ -z "$WRITTEN_FILE" ]]; then
+  # Method 1: TOOL_USE_CONTENT environment variable
+  if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+    WRITTEN_FILE="$TOOL_USE_CONTENT"
+    DETECTION_METHOD="env_content"
+  fi
+
+  # Method 2: TOOL_RESULT environment variable
+  if [[ -z "$WRITTEN_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
+    WRITTEN_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+    DETECTION_METHOD="env_result"
+  fi
+
+  # Method 3: TOOL_USE_ARGS
+  if [[ -z "$WRITTEN_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+    WRITTEN_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+    DETECTION_METHOD="env_args"
+  fi
+
+  # Log env var detection (for metrics)
+  if [[ -n "$WRITTEN_FILE" ]]; then
+    echo "[$(date)] post-write-spec: File from env vars ($DETECTION_METHOD): $WRITTEN_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
 fi
 
-# Log detection attempt
-echo "[$(date)] post-write-spec: Detected file: ${WRITTEN_FILE:-<none>}" >> "$DEBUG_LOG" 2>/dev/null || true
+# Log detection attempt (only log if we actually detected a file, to reduce noise)
+if [[ -n "$WRITTEN_FILE" ]]; then
+  echo "[$(date)] post-write-spec: Detected file: $WRITTEN_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
 
 # Check if we detected a spec.md or tasks.md write in increments folder
 SHOULD_UPDATE=false
@@ -69,23 +190,78 @@ if [[ -n "$WRITTEN_FILE" ]]; then
   fi
 fi
 
-# If we couldn't detect the file via environment variables, always update status line
-# This ensures we don't miss updates during increment closure
+# ============================================================================
+# TIER 1 FIX: File Modification Time Detection (Fallback)
+# ============================================================================
+# If we couldn't detect the file via environment variables, check which files
+# were modified recently (within last 2 seconds) instead of blindly updating
 if [[ -z "$WRITTEN_FILE" ]]; then
-  echo "[$(date)] post-write-spec: No file detected - updating status line as safety measure" >> "$DEBUG_LOG" 2>/dev/null || true
-  SHOULD_UPDATE=true
+  echo "[$(date)] post-write-spec: Env vars empty - checking file mtimes" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  NOW=$(date +%s)
+  INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+
+  # Check for recently modified spec.md or tasks.md files
+  if [[ -d "$INCREMENTS_DIR" ]]; then
+    for file in "$INCREMENTS_DIR"/*/spec.md "$INCREMENTS_DIR"/*/tasks.md; do
+      if [[ -f "$file" ]]; then
+        # Get file modification time (platform-specific)
+        if [[ "$(uname)" == "Darwin" ]]; then
+          MTIME=$(stat -f "%m" "$file" 2>/dev/null || echo 0)
+        else
+          MTIME=$(stat -c "%Y" "$file" 2>/dev/null || echo 0)
+        fi
+
+        # If file was modified in last 2 seconds, consider it the written file
+        TIME_DIFF=$((NOW - MTIME))
+        if (( TIME_DIFF <= 2 )); then
+          WRITTEN_FILE="$file"
+          echo "[$(date)] post-write-spec: Detected recent modification: $file (${TIME_DIFF}s ago)" >> "$DEBUG_LOG" 2>/dev/null || true
+          SHOULD_UPDATE=true
+          break
+        fi
+      fi
+    done
+  fi
+
+  # If still no file detected, skip update (not a spec/tasks write)
+  if [[ -z "$WRITTEN_FILE" ]]; then
+    echo "[$(date)] post-write-spec: No spec/tasks modifications detected - skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0
+  fi
 fi
 
+# ============================================================================
+# TIER 1 FIX: Non-Blocking Background Update with COMPLETE ERROR ISOLATION
+# ============================================================================
 # Update status line if needed
 if [[ "$SHOULD_UPDATE" == "true" ]]; then
-  echo "[$(date)] post-write-spec: Running update-status-line.sh" >> "$DEBUG_LOG" 2>/dev/null || true
+  echo "[$(date)] post-write-spec: Running update-status-line.sh (background)" >> "$DEBUG_LOG" 2>/dev/null || true
 
-  # Run status line update (capture errors for debugging)
-  if "$PROJECT_ROOT/plugins/specweave/hooks/lib/update-status-line.sh" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null; then
-    echo "[$(date)] post-write-spec: Status line updated successfully" >> "$DEBUG_LOG" 2>/dev/null || true
-  else
-    echo "[$(date)] post-write-spec: Warning - status line update failed (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
-  fi
+  # Record update time BEFORE spawning background process
+  # This ensures debouncing works even if update hasn't completed yet
+  echo "$(date +%s)" > "$LAST_UPDATE_FILE"
+
+  # Run status line update in background with COMPLETE error isolation
+  # This prevents Write tool from waiting for status line computation
+  (
+    set +e  # Disable error propagation
+
+    if "$PROJECT_ROOT/plugins/specweave/hooks/lib/update-status-line.sh" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null; then
+      echo "[$(date)] post-write-spec: Status line updated successfully" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Reset circuit breaker on success
+      echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+    else
+      echo "[$(date)] post-write-spec: Warning - status line update failed (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Increment circuit breaker
+      CURRENT_FAILURES=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+      echo "$((CURRENT_FAILURES + 1))" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+    fi
+  ) &
+
+  # Disown the background process so it's not killed when hook exits
+  disown 2>/dev/null || true
 fi
 
+# Always exit 0 to prevent hook errors from crashing Claude Code
 exit 0

package/plugins/specweave/hooks/pre-command-deduplication.sh.backup

@@ -0,0 +1,83 @@
+#!/bin/bash
+
+# SpecWeave Pre-Command Deduplication Hook
+# Fires BEFORE any command executes (UserPromptSubmit hook)
+# Purpose: Prevent duplicate command invocations within configurable time window
+
+set -euo pipefail
+
+# ==============================================================================
+# PROJECT ROOT DETECTION
+# ==============================================================================
+
+# Find project root by searching upward for .specweave/ directory
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# Read input JSON from stdin
+INPUT=$(cat)
+
+# ==============================================================================
+# DEDUPLICATION CHECK: Block duplicate commands within 1 second
+# ==============================================================================
+
+# Check if deduplication module is available
+if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/deduplication/command-deduplicator.js" ]]; then
+  # Use dedicated wrapper script for ES module compatibility
+  DEDUP_RESULT=$(echo "$INPUT" | node scripts/check-deduplication.js 2>/dev/null || echo "OK")
+
+  # Parse result
+  STATUS=$(echo "$DEDUP_RESULT" | head -1)
+
+  if [[ "$STATUS" == "DUPLICATE" ]]; then
+    # Get stats
+    STATS=$(echo "$DEDUP_RESULT" | tail -1)
+
+    # Extract command and stats for readable message
+    COMMAND=$(echo "$STATS" | grep -o '"lastCommand":"[^"]*"' | cut -d'"' -f4 || echo "unknown")
+    TOTAL_BLOCKED=$(echo "$STATS" | grep -o '"totalDuplicatesBlocked":[0-9]*' | cut -d':' -f2 || echo "1")
+    CACHE_SIZE=$(echo "$STATS" | grep -o '"currentCacheSize":[0-9]*' | cut -d':' -f2 || echo "1")
+
+    # Build error message WITHOUT embedding JSON (avoid escaping issues)
+    MESSAGE=$(cat <<'EOF'
+{
+  "decision": "block",
+  "reason": "🚫 DUPLICATE COMMAND DETECTED\n\nCommand: `COMMAND_PLACEHOLDER`\nTime window: 1 second\n\nThis command was just executed! To prevent unintended duplicates, this invocation has been blocked.\n\n💡 If you meant to run this command again:\n  1. Wait 1 second\n  2. Run the command again\n\nDeduplication Stats:\n- Total duplicates blocked: BLOCKED_PLACEHOLDER\n- Commands in cache: CACHE_PLACEHOLDER"
+}
+EOF
+)
+    # Replace placeholders (avoids JSON escaping issues)
+    # Use | as sed delimiter to avoid conflicts with / in command names
+    echo "$MESSAGE" | sed "s|COMMAND_PLACEHOLDER|$COMMAND|g" | sed "s|BLOCKED_PLACEHOLDER|$TOTAL_BLOCKED|g" | sed "s|CACHE_PLACEHOLDER|$CACHE_SIZE|g"
+    exit 0
+  fi
+fi
+
+# ==============================================================================
+# PASS THROUGH: No duplicate detected, proceed with command
+# ==============================================================================
+
+cat <<EOF
+{
+  "decision": "approve"
+}
+EOF
+
+exit 0