specweave 1.0.32 → 1.0.33

package/plugins/specweave/hooks/universal/fail-fast-wrapper.sh

@@ -1,317 +1,64 @@
 #!/bin/bash
-# fail-fast-wrapper.sh - HARD TIMEOUT wrapper for all hooks with proper concurrency control
-# If ANY hook takes longer than HOOK_TIMEOUT, it gets KILLED.
+# fail-fast-wrapper.sh - Simple timeout wrapper for hooks
 #
 # Usage: bash fail-fast-wrapper.sh <hook-script> [args...]
 #
 # Environment:
-#   HOOK_TIMEOUT        - max seconds (default: 5)
-#   HOOK_DEBUG          - set to 1 for verbose logging
-#   HOOK_MAX_CONCURRENT - max concurrent hooks (default: 15)
-#   HOOK_ACQUIRE_TIMEOUT_MS - semaphore acquire timeout (default: 3000)
+#   HOOK_TIMEOUT - max seconds (default: 5)
 #
-# Exit behavior:
-#   - Returns hook output on success
-#   - Returns safe JSON on timeout ({"continue":true} or {"decision":"approve"})
-#   - NEVER hangs - timeout is enforced with SIGKILL
-#
-# CONCURRENCY CONTROL (v1.0.30):
-#   - Semaphore-based concurrency limiting (NOT process storm detection)
-#   - Proper circuit breaker with CLOSED/OPEN/HALF_OPEN states
-#   - Structured logging with request tracing
-#   - Metrics collection for observability
-#
-# v0.33.0 - Enhanced with crash prevention integration
-# v1.0.30 - Complete rewrite with proper concurrency primitives
-
-set -o pipefail
-
-# === Configuration ===
-HOOK_TIMEOUT="${HOOK_TIMEOUT:-5}"  # 5 seconds - more than enough for any hook
-HOOK_DEBUG="${HOOK_DEBUG:-0}"
-HOOK_MAX_CONCURRENT="${HOOK_MAX_CONCURRENT:-15}"  # Max concurrent hooks
-HOOK_ACQUIRE_TIMEOUT_MS="${HOOK_ACQUIRE_TIMEOUT_MS:-3000}"  # 3 seconds to acquire semaphore
-LOG_FILE="${HOME}/.claude/hook-failures.log"
-
-# === Library paths ===
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-LIB_DIR="${SCRIPT_DIR}/../lib"
-
-# === Source libraries (fail gracefully if missing) ===
-SEMAPHORE_LOADED=false
-CIRCUIT_BREAKER_LOADED=false
-LOGGING_LOADED=false
-METRICS_LOADED=false
+# Returns safe JSON on timeout or error. Never hangs.
 
-# Set state dir for all libraries
-export SPECWEAVE_STATE_DIR="${SPECWEAVE_STATE_DIR:-.specweave/state}"
-export SPECWEAVE_LOG_DIR="${SPECWEAVE_LOG_DIR:-.specweave/logs/hooks}"
+set +e
 
-if [[ -f "$LIB_DIR/semaphore.sh" ]]; then
-  source "$LIB_DIR/semaphore.sh" 2>/dev/null && SEMAPHORE_LOADED=true
-fi
-
-if [[ -f "$LIB_DIR/circuit-breaker.sh" ]]; then
-  source "$LIB_DIR/circuit-breaker.sh" 2>/dev/null && CIRCUIT_BREAKER_LOADED=true
-fi
-
-if [[ -f "$LIB_DIR/logging.sh" ]]; then
-  source "$LIB_DIR/logging.sh" 2>/dev/null && LOGGING_LOADED=true
-fi
+HOOK_TIMEOUT="${HOOK_TIMEOUT:-5}"
 
-if [[ -f "$LIB_DIR/metrics.sh" ]]; then
-  source "$LIB_DIR/metrics.sh" 2>/dev/null && METRICS_LOADED=true
-fi
-
-# Legacy crash prevention (fallback)
-CRASH_PREVENTION="${LIB_DIR}/crash-prevention.sh"
-if [[ -f "$CRASH_PREVENTION" ]]; then
-  source "$CRASH_PREVENTION" 2>/dev/null || true
-fi
-
-# === Helper functions ===
-log_debug() {
-  [[ "$HOOK_DEBUG" == "1" ]] && echo "[DEBUG $(date +%H:%M:%S)] $*" >&2
-}
-
-log_failure() {
-  local msg="$1"
-  mkdir -p "$(dirname "$LOG_FILE")"
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] HOOK FAILURE: $msg" >> "$LOG_FILE"
-}
-
-# === Safe JSON output based on hook type ===
+# Safe output based on hook type
 get_safe_output() {
   local script="$1"
-  # PreToolUse hooks need "decision" format
-  if [[ "$script" == *"guard"* ]] || [[ "$script" == *"validator"* ]] || [[ "$script" == *"PreToolUse"* ]]; then
+  if [[ "$script" == *"guard"* ]] || [[ "$script" == *"validator"* ]]; then
     echo '{"decision":"allow"}'
   else
     echo '{"continue":true}'
   fi
 }
 
-# === Get hook name from script path ===
-get_hook_name() {
-  local script="$1"
-  basename "$script" .sh | tr '/' '-'
-}
-
-# === Read stdin with timeout ===
-# Critical: stdin can block forever if not handled properly
-read_stdin_with_timeout() {
-  local stdin_content=""
-
-  # Use read with timeout (integer seconds for bash compatibility)
-  if read -t 1 -r line; then
-    stdin_content="$line"
-    # Continue reading remaining lines (no timeout - stdin should be closed)
-    while IFS= read -r line; do
-      stdin_content="${stdin_content}"$'\n'"${line}"
-    done
-  fi
-
-  echo "$stdin_content"
-}
-
-# === Main execution ===
-main() {
-  local script="$1"
-  shift
-  local args=("$@")
-
-  if [[ -z "$script" ]]; then
-    echo '{"continue":true}'
-    exit 0
-  fi
-
-  if [[ ! -f "$script" ]]; then
-    log_debug "Script not found: $script"
-    echo '{"continue":true}'
-    exit 0
-  fi
-
-  local hook_name
-  hook_name=$(get_hook_name "$script")
-
-  # === Initialize libraries ===
-  if [[ "$LOGGING_LOADED" == "true" ]]; then
-    log_init "$hook_name"
-    log_debug "Starting hook execution" "script=$script"
-  fi
-
-  if [[ "$METRICS_LOADED" == "true" ]]; then
-    metrics_init "$hook_name"
-    metrics_start_request
-  fi
-
-  # === CIRCUIT BREAKER CHECK ===
-  # If circuit is open for this hook, fail fast
-  if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
-    if ! cb_allow_request "$hook_name"; then
-      local cb_status
-      cb_status=$(cb_get_status "$hook_name")
-      log_debug "Circuit breaker OPEN for $hook_name: $cb_status"
-
-      if [[ "$LOGGING_LOADED" == "true" ]]; then
-        log_warn "Circuit breaker open - failing fast" "hook=$hook_name"
-      fi
-
-      if [[ "$METRICS_LOADED" == "true" ]]; then
-        metrics_end_request "skipped"
-      fi
-
-      get_safe_output "$script"
-      exit 0
-    fi
-  fi
-
-  # === SEMAPHORE: Acquire concurrency slot ===
-  local semaphore_acquired=false
-  if [[ "$SEMAPHORE_LOADED" == "true" ]]; then
-    if acquire_semaphore "hooks" "$HOOK_MAX_CONCURRENT" "$HOOK_ACQUIRE_TIMEOUT_MS"; then
-      semaphore_acquired=true
-      log_debug "Acquired semaphore slot for $hook_name"
-    else
-      # Could not acquire semaphore in time - graceful degradation
-      log_debug "Semaphore timeout for $hook_name - graceful skip"
-
-      if [[ "$LOGGING_LOADED" == "true" ]]; then
-        log_warn "Semaphore acquisition timeout - graceful degradation" "hook=$hook_name" "max_concurrent=$HOOK_MAX_CONCURRENT"
-      fi
-
-      if [[ "$METRICS_LOADED" == "true" ]]; then
-        metrics_end_request "skipped"
-      fi
-
-      # DON'T record as failure - this is graceful degradation, not an error
-      get_safe_output "$script"
-      exit 0
-    fi
-  fi
-
-  # Ensure semaphore is released on exit
-  trap 'release_semaphore 2>/dev/null || true' EXIT INT TERM
-
-  log_debug "Executing: $script (timeout: ${HOOK_TIMEOUT}s)"
-
-  # Read stdin first (with its own timeout)
-  local stdin_content
-  stdin_content=$(read_stdin_with_timeout)
-
-  # Execute the hook with hard timeout
-  local output
-  local exit_code
-  local tmp_out
-  tmp_out=$(mktemp)
-
-  # Run with timeout - kill entire process group on timeout
-  if command -v gtimeout >/dev/null 2>&1; then
-    # macOS with coreutils
-    echo "$stdin_content" | gtimeout --kill-after=2 "$HOOK_TIMEOUT" bash "$script" "${args[@]}" > "$tmp_out" 2>/dev/null
-    exit_code=$?
-  elif command -v timeout >/dev/null 2>&1; then
-    # Linux
-    echo "$stdin_content" | timeout --kill-after=2 "$HOOK_TIMEOUT" bash "$script" "${args[@]}" > "$tmp_out" 2>/dev/null
-    exit_code=$?
-  else
-    # Fallback: manual timeout using background process
-    (
-      echo "$stdin_content" | bash "$script" "${args[@]}" > "$tmp_out" 2>/dev/null
-    ) &
-    local pid=$!
-
-    # Wait with timeout
-    local count=0
-    while kill -0 "$pid" 2>/dev/null && [[ $count -lt $((HOOK_TIMEOUT * 10)) ]]; do
-      sleep 0.1
-      count=$((count + 1))
-    done
-
-    if kill -0 "$pid" 2>/dev/null; then
-      # Still running - kill it!
-      kill -9 "$pid" 2>/dev/null
-      wait "$pid" 2>/dev/null
-      exit_code=124  # timeout exit code
-    else
-      wait "$pid"
-      exit_code=$?
-    fi
-  fi
-
-  output=$(cat "$tmp_out" 2>/dev/null)
-  rm -f "$tmp_out"
-
-  # Release semaphore immediately after execution
-  if [[ "$semaphore_acquired" == "true" ]]; then
-    release_semaphore
-  fi
-
-  # Handle timeout (exit code 124 or 137)
-  if [[ $exit_code -eq 124 ]] || [[ $exit_code -eq 137 ]]; then
-    log_failure "$script - killed after ${HOOK_TIMEOUT}s"
-    log_debug "TIMEOUT: $script killed after ${HOOK_TIMEOUT}s"
-
-    if [[ "$LOGGING_LOADED" == "true" ]]; then
-      log_error "Hook timeout - killed after ${HOOK_TIMEOUT}s" "hook=$hook_name"
-    fi
-
-    if [[ "$METRICS_LOADED" == "true" ]]; then
-      metrics_end_request "timeout"
-    fi
-
-    # Record failure for circuit breaker
-    if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
-      cb_record_failure "$hook_name"
-    fi
-
-    # Clean up potential zombie processes (legacy)
-    if type kill_zombie_heredocs &>/dev/null; then
-      kill_zombie_heredocs 2>/dev/null || true
-    fi
-
-    get_safe_output "$script"
-    exit 0
-  fi
-
-  # Handle hook errors (non-zero exit, excluding block exit code 2)
-  if [[ $exit_code -ne 0 ]] && [[ $exit_code -ne 2 ]]; then
-    log_debug "Hook error: $script exited with $exit_code"
-
-    if [[ "$LOGGING_LOADED" == "true" ]]; then
-      log_warn "Hook exited with error" "hook=$hook_name" "exit_code=$exit_code"
-    fi
-
-    if [[ "$METRICS_LOADED" == "true" ]]; then
-      metrics_end_request "failure"
-    fi
-
-    if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
-      cb_record_failure "$hook_name"
-    fi
-  else
-    # Success!
-    if [[ "$METRICS_LOADED" == "true" ]]; then
-      metrics_end_request "success"
-    fi
-
-    if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
-      cb_record_success "$hook_name"
-    fi
-
-    if [[ "$LOGGING_LOADED" == "true" ]]; then
-      log_debug "Hook completed successfully" "hook=$hook_name"
-    fi
-  fi
+script="$1"
+shift
+
+# No script or doesn't exist = safe default
+[[ -z "$script" || ! -f "$script" ]] && echo '{"continue":true}' && exit 0
+
+# Read stdin
+stdin_content=$(cat 2>/dev/null || echo '{}')
+
+# Run with timeout
+tmp_out=$(mktemp)
+if command -v gtimeout >/dev/null 2>&1; then
+  echo "$stdin_content" | gtimeout --kill-after=2 "$HOOK_TIMEOUT" bash "$script" "$@" > "$tmp_out" 2>/dev/null
+  exit_code=$?
+elif command -v timeout >/dev/null 2>&1; then
+  echo "$stdin_content" | timeout --kill-after=2 "$HOOK_TIMEOUT" bash "$script" "$@" > "$tmp_out" 2>/dev/null
+  exit_code=$?
+else
+  # Fallback: run without timeout (rare - most systems have timeout)
+  echo "$stdin_content" | bash "$script" "$@" > "$tmp_out" 2>/dev/null
+  exit_code=$?
+fi
 
-  # Return output or safe default
-  if [[ -n "$output" ]]; then
-    echo "$output"
-  else
-    get_safe_output "$script"
-  fi
+output=$(cat "$tmp_out" 2>/dev/null)
+rm -f "$tmp_out"
 
+# Timeout = safe default
+if [[ $exit_code -eq 124 ]] || [[ $exit_code -eq 137 ]]; then
+  get_safe_output "$script"
   exit 0
-}
+fi
+
+# Return output or safe default
+if [[ -n "$output" ]]; then
+  echo "$output"
+else
+  get_safe_output "$script"
+fi
 
-main "$@"
+exit 0

package/plugins/specweave/hooks/universal/hook-wrapper.sh

@@ -8,8 +8,10 @@
 #
 # Usage: bash hook-wrapper.sh <hook-type>
 # Where hook-type is: session-start, post-tool-use, completion-guard
+#
+# v0.35.3 - Fixed: use set +e for hook safety
 
-set -e
+set +e  # CRITICAL: Never use set -e in hooks (causes cascading failures)
 
 HOOK_TYPE="${1:-unknown}"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

package/plugins/specweave/hooks/user-prompt-submit.sh

@@ -18,7 +18,7 @@ set +e
 # ==============================================================================
 # ULTRA-FAST EARLY EXIT (before ANY processing)
 # ==============================================================================
-INPUT=$(cat)
+INPUT=$(cat 2>/dev/null || echo '{}')
 
 # Use jq if available (10x faster than node), fallback to simple grep
 if command -v jq >/dev/null 2>&1; then

package/plugins/specweave/hooks/v2/dispatchers/post-tool-use.sh

@@ -26,8 +26,8 @@ while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
 done
 [[ ! -d "$PROJECT_ROOT/.specweave" ]] && exit 0
 
-# Read stdin (tool result JSON)
-INPUT=$(cat)
+# Read stdin (tool result JSON) - with safe fallback to prevent hanging
+INPUT=$(cat 2>/dev/null || echo '{}')
 
 # Extract file path (fast grep, no jq)
 FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/')

package/plugins/specweave/hooks/v2/dispatchers/session-start.sh

@@ -15,17 +15,8 @@ done
 # Consume stdin
 cat > /dev/null
 
-# === CRITICAL: Guard Verification ===
-# Check that essential guards are available to prevent session hangs
+# Hook directory for finding other scripts
 HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-GUARDS_DIR="$HOOK_DIR/../guards"
-BASH_FILE_GUARD="$GUARDS_DIR/bash-file-guard.sh"
-
-if [[ ! -f "$BASH_FILE_GUARD" ]] || [[ ! -x "$BASH_FILE_GUARD" ]]; then
-  # Output warning as system message
-  echo '{"continue":true,"systemMessage":"⚠️ CRITICAL: bash-file-guard.sh not found or not executable! Session hang protection DISABLED. Run: bash scripts/refresh-marketplace.sh"}'
-  # Continue session but warn about missing protection
-fi
 
 # === MCP Connection Health Check ===
 # Check for recent MCP drops that could cause session hangs

package/plugins/specweave/hooks/v2/guards/completion-guard.sh

@@ -7,12 +7,13 @@
 # PreToolUse hook - can BLOCK the tool call by returning non-zero exit code
 #
 # IMPORTANT: This is a safety guard. Exit 0 allows, exit 2 blocks.
+# All exit paths MUST output JSON for proper Claude Code handling.
 set +e
 
-[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && echo '{"decision":"allow"}' && exit 0
 
 # Read stdin for tool input
-INPUT=$(cat)
+INPUT=$(cat 2>/dev/null || echo '{}')
 
 # Check if this is editing metadata.json with status: completed
 # Pattern: file_path contains metadata.json AND (new_string OR content) contains "status"..."completed"
@@ -27,6 +28,7 @@ fi
 
 # Only care about metadata.json files
 if [[ "$FILE_PATH" != *metadata.json ]]; then
+  echo '{"decision":"allow"}'
   exit 0  # Allow
 fi
 
@@ -50,40 +52,21 @@ if echo "$NEW_CONTENT" | grep -q '"status"[[:space:]]*:[[:space:]]*"completed"';
 
     if [[ "$CURRENT_STATUS" == "ready_for_review" ]]; then
       # This is a valid transition - allow
+      echo '{"decision":"allow"}'
       exit 0
     fi
   fi
 
   # BLOCK - trying to set completed without going through ready_for_review
-  echo ""
-  echo "=============================================================================="
-  echo "  BLOCKED: Direct status change to \"completed\" is not allowed (v0.28.63+)"
-  echo "=============================================================================="
-  echo ""
-  echo "You cannot directly set status to \"completed\" in metadata.json."
-  echo ""
-  echo "This prevents the auto-completion bug where increments get marked as"
-  echo "completed without proper validation."
-  echo ""
-  echo "CORRECT WORKFLOW:"
-  echo "1. All tasks completed -> status auto-transitions to \"ready_for_review\""
-  echo "2. Run /sw:done <increment-id> with explicit user confirmation"
-  echo "3. Only then does status become \"completed\""
-  echo ""
-  echo "WHY THIS MATTERS:"
-  echo "- Ensures all ACs are checked in spec.md before closure"
-  echo "- Requires explicit user approval"
-  echo "- Maintains audit trail (approvedAt timestamp)"
-  echo ""
-  echo "If you're implementing closure logic, use:"
-  echo "  MetadataManager.updateStatus(incrementId, IncrementStatus.COMPLETED)"
-  echo ""
-  echo "This will only succeed if current status is \"ready_for_review\"."
-  echo ""
-  echo "=============================================================================="
-
+  cat << 'BLOCK_EOF'
+{
+  "decision": "block",
+  "reason": "🚫 BLOCKED: Direct status change to \"completed\" is not allowed (v0.28.63+)\n\nYou cannot directly set status to \"completed\" in metadata.json.\n\nCORRECT WORKFLOW:\n1. All tasks completed → status auto-transitions to \"ready_for_review\"\n2. Run /sw:done <increment-id> with explicit user confirmation\n3. Only then does status become \"completed\"\n\nWHY THIS MATTERS:\n• Ensures all ACs are checked in spec.md before closure\n• Requires explicit user approval\n• Maintains audit trail (approvedAt timestamp)\n\n🔧 If implementing closure logic, use:\n  MetadataManager.updateStatus(incrementId, IncrementStatus.COMPLETED)"
+}
+BLOCK_EOF
   exit 2  # Block the tool call
 fi
 
 # Allow other edits to metadata.json
+echo '{"decision":"allow"}'
 exit 0

package/plugins/specweave/hooks/v2/guards/increment-duplicate-guard.sh

@@ -10,13 +10,13 @@
 # - 0121-ado-jira-feature-parity-p2-p3
 # - 0121-intelligent-living-docs-content
 #
-# Exit 0 = allow, Exit 2 = block
+# Exit 0 = allow (with JSON), Exit 2 = block (with JSON)
 set +e
 
-[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && echo '{"decision":"allow"}' && exit 0
 
 # Read stdin for tool input
-INPUT=$(cat)
+INPUT=$(cat 2>/dev/null || echo '{}')
 
 # Extract file_path from the tool call
 # Claude Code passes tool input in .tool_input.file_path format
@@ -28,6 +28,7 @@ fi
 
 # Only care about .specweave/increments/ paths
 if [[ "$FILE_PATH" != *.specweave/increments/* ]]; then
+  echo '{"decision":"allow"}'
   exit 0  # Not an increment file - allow
 fi
 
@@ -43,6 +44,7 @@ INCREMENT_FOLDER=$(echo "$AFTER_INCREMENTS" | cut -d'/' -f1)
 
 # Skip special folders
 if [[ "$INCREMENT_FOLDER" == "_archive" ]] || [[ "$INCREMENT_FOLDER" == "_abandoned" ]] || [[ "$INCREMENT_FOLDER" == "_paused" ]] || [[ "$INCREMENT_FOLDER" == "README.md" ]]; then
+  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -50,6 +52,7 @@ fi
 INCREMENT_NUM=$(echo "$INCREMENT_FOLDER" | grep -oE '^[0-9]{3,4}' | head -1)
 
 if [[ -z "$INCREMENT_NUM" ]]; then
+  echo '{"decision":"allow"}'
   exit 0  # Not a standard increment folder pattern - allow
 fi
 
@@ -60,7 +63,9 @@ INCREMENT_NUM=$(printf "%04d" "$((10#$INCREMENT_NUM))")
 INCREMENTS_DIR=$(echo "$FILE_PATH" | grep -o '.*/\.specweave/increments' | head -1)
 
 if [[ ! -d "$INCREMENTS_DIR" ]]; then
-  exit 0  # Increments directory doesn't exist yet - allow (first increment)
+  # Increments directory doesn't exist yet - first increment, allow creation
+  echo '{"decision":"allow"}'
+  exit 0
 fi
 
 # Scan ALL directories for existing increment with the same number
@@ -104,37 +109,30 @@ for DIR in "${DIRS_TO_CHECK[@]}"; do
   done < <(find "$DIR" -maxdepth 1 -type d -name "${INCREMENT_NUM}*" -print0 2>/dev/null)
 done
 
-# If duplicates found, BLOCK the operation
+# If duplicates found, BLOCK the operation and provide the correct number to use
 if [[ ${#FOUND_DUPLICATES[@]} -gt 0 ]]; then
-  echo ""
-  echo "=============================================================================="
-  echo "  BLOCKED: Duplicate increment ID detected (v0.33.0+)"
-  echo "=============================================================================="
-  echo ""
-  echo "You are trying to create increment: $INCREMENT_FOLDER"
-  echo "But increment number $INCREMENT_NUM already exists:"
-  echo ""
+  # Format duplicates for JSON
+  DUP_LIST=""
   for DUP in "${FOUND_DUPLICATES[@]}"; do
-    echo "  - $DUP"
+    DUP_LIST="${DUP_LIST}\\n  - ${DUP}"
+  done
+
+  # Calculate the next available number using gap-filling strategy
+  EXISTING_NUMS=$(find "$INCREMENTS_DIR" "$INCREMENTS_DIR/_archive" "$INCREMENTS_DIR/_abandoned" "$INCREMENTS_DIR/_paused" -maxdepth 1 -type d -name "[0-9]*-*" 2>/dev/null | xargs -I {} basename {} | grep -oE '^[0-9]{3,4}' | sort -n | uniq)
+  NEXT_NUM=1
+  while echo "$EXISTING_NUMS" | grep -q "^$(printf "%04d" $NEXT_NUM)$\|^$(printf "%03d" $NEXT_NUM)$"; do
+    NEXT_NUM=$((NEXT_NUM + 1))
   done
-  echo ""
-  echo "IMPORTANT: Increment IDs MUST be unique across all directories:"
-  echo "  - Active increments"
-  echo "  - Archived increments (_archive/)"
-  echo "  - Abandoned increments (_abandoned/)"
-  echo "  - Paused increments (_paused/)"
-  echo ""
-  echo "NOTE: 0001 and 0001E share the SAME base number and cannot coexist!"
-  echo ""
-  echo "TO FIX:"
-  echo "1. Use a different increment number"
-  echo "2. Get the next available number:"
-  echo "   node -e \"import('./dist/core/increment/increment-utils.js').then(m => console.log(m.IncrementNumberManager.getNextIncrementNumber()))\""
-  echo ""
-  echo "=============================================================================="
+  NEXT_NUM_PADDED=$(printf "%04d" $NEXT_NUM)
+
+  # Extract the name part from the attempted folder
+  FOLDER_NAME_PART=$(echo "$INCREMENT_FOLDER" | sed 's/^[0-9]\{3,4\}E\?-//')
+  SUGGESTED_FOLDER="${NEXT_NUM_PADDED}-${FOLDER_NAME_PART}"
 
+  printf '{"decision":"block","reason":"🚫 DUPLICATE INCREMENT ID - Use this instead:\\n\\n✅ CORRECT: %s\\n❌ ATTEMPTED: %s\\n\\nNumber %s already exists:%s\\n\\n🔧 IMMEDIATE FIX: Replace your file path with:\\n   .specweave/increments/%s/...\\n\\nThe guard calculated the next available number for you."}\n' "$SUGGESTED_FOLDER" "$INCREMENT_FOLDER" "$INCREMENT_NUM" "$DUP_LIST" "$SUGGESTED_FOLDER"
   exit 2  # Block the tool call
 fi
 
 # No duplicates - allow
+echo '{"decision":"allow"}'
 exit 0

package/plugins/specweave/hooks/v2/guards/metadata-json-guard.sh

@@ -25,7 +25,7 @@
 #
 # v0.34.0 - Initial implementation based on user project bug analysis
 
-set -e
+set +e  # CRITICAL: Never use set -e in hooks (causes cascading failures)
 
 # Check for force bypass
 if [ "$SPECWEAVE_FORCE_METADATA" = "1" ]; then
@@ -39,10 +39,16 @@ if [ "$SPECWEAVE_DISABLE_HOOKS" = "1" ]; then
   exit 0
 fi
 
-# Read tool input from stdin
-INPUT=$(cat)
+# Read tool input from stdin (safe handling)
+INPUT=$(cat 2>/dev/null || echo '{}')
 
-# Extract tool name
+# Check jq availability - allow if not present
+if ! command -v jq >/dev/null 2>&1; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Extract tool name - with jq fallback
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // .tool_input.tool_name // ""' 2>/dev/null || echo "")
 
 # Only validate Write tool calls