specweave 0.32.0 → 0.32.3

package/plugins/specweave/hooks/v2/guards/bash-file-guard.sh

@@ -0,0 +1,211 @@
+#!/bin/bash
+# bash-file-guard.sh - CRITICAL: Block Bash file creation patterns that cause infinite hangs
+#
+# ROOT CAUSE: When Claude uses heredoc (cat << EOF ... EOF) to create files and the
+# content gets truncated due to token limits, the shell waits FOREVER for the EOF
+# terminator that will never come. This causes Claude Code to hang indefinitely
+# (2+ hours observed in production crashes).
+#
+# SOLUTION: Block ALL bash file creation patterns and force use of Write/Edit tools.
+# Write/Edit tools are:
+# - Atomic (no intermediate states)
+# - Token-safe (handled by Claude Code, not shell)
+# - Recoverable (no zombie processes)
+#
+# PreToolUse hook for Bash commands - exit 0 allows, exit 2 blocks
+#
+# v0.32.1 - Initial implementation based on crash analysis from 2025-12-06
+
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+# Read stdin for tool input
+INPUT=$(cat)
+
+# Extract the command being executed
+# The Bash tool has a "command" parameter
+# Use jq for proper JSON parsing (handles escaped quotes correctly)
+if command -v jq &> /dev/null; then
+  COMMAND=$(echo "$INPUT" | jq -r '.command // empty' 2>/dev/null)
+else
+  # Fallback: simple regex (may fail on complex JSON with escaped quotes)
+  COMMAND=$(echo "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+fi
+
+# If no command found or empty, allow (safety)
+if [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# === PATTERN DETECTION ===
+# These patterns WILL cause infinite hangs or truncation issues
+
+BLOCKED=0
+PATTERN_NAME=""
+
+# === HEREDOC PATTERNS (MOST DANGEROUS - infinite hang!) ===
+
+# Pattern 1a: Standard heredoc with any delimiter
+# Matches: cat << EOF, cat << 'EOF', cat << "EOF", cat <<EOF (no space)
+if echo "$COMMAND" | grep -qE "(cat|tee).*<<-?[[:space:]]*['\"]?[A-Za-z]+" 2>/dev/null; then
+  BLOCKED=1
+  PATTERN_NAME="heredoc (cat << DELIMITER)"
+fi
+
+# Pattern 1b: Heredoc with escaped quotes in JSON (\"EOF\")
+# JSON escapes double quotes, so << "EOF" becomes << \"EOF\"
+if echo "$COMMAND" | grep -qE "(cat|tee).*<<-?[[:space:]]*\\\\\"[A-Za-z]+" 2>/dev/null; then
+  BLOCKED=1
+  PATTERN_NAME="heredoc with quoted delimiter"
+fi
+
+# Pattern 1c: SUPER AGGRESSIVE - block ANY heredoc-like pattern
+# Catches edge cases where content has << followed by word boundary
+# This is the NUCLEAR option - heredocs are NEVER safe in Claude context
+if echo "$COMMAND" | grep -qE "<<[[:space:]]*['\"]?[A-Za-z_]+" 2>/dev/null; then
+  BLOCKED=1
+  PATTERN_NAME="heredoc pattern (any form)"
+fi
+
+# Pattern 1d: Multiline content in the command itself
+# If the command contains literal newlines, it might be a heredoc in disguise
+if echo "$COMMAND" | grep -qE $'\n' 2>/dev/null; then
+  # Commands with newlines are suspicious - check for file redirects
+  if echo "$COMMAND" | grep -qE '>' 2>/dev/null; then
+    BLOCKED=1
+    PATTERN_NAME="multiline command with redirect (heredoc variant)"
+  fi
+fi
+
+# === CAT STDIN REDIRECT (VERY DANGEROUS!) ===
+# Pattern 2: Plain cat with output redirect but no input
+# Matches: cat > file.txt (waits forever for stdin!)
+# This is just as dangerous as heredoc - shell waits for input
+if echo "$COMMAND" | grep -qE "^[[:space:]]*cat[[:space:]]+>[[:space:]]*[^>]" 2>/dev/null; then
+  BLOCKED=1
+  PATTERN_NAME="cat > file (stdin redirect - waits forever!)"
+fi
+
+# === DD COMMAND (EQUALLY DANGEROUS!) ===
+# Pattern 2b: dd with stdin or output file
+# Matches: dd if=/dev/stdin of=file, dd of=file bs=1024
+# dd waits for input EXACTLY like cat > file
+if echo "$COMMAND" | grep -qE "^[[:space:]]*dd[[:space:]]" 2>/dev/null; then
+  if echo "$COMMAND" | grep -qE "of=" 2>/dev/null; then
+    BLOCKED=1
+    PATTERN_NAME="dd command (waits for stdin like cat)"
+  fi
+fi
+
+# === READ COMMAND (WAITS FOR INPUT) ===
+# Pattern 2c: read with redirect
+# Matches: read VAR > file (waits for input from user/stdin)
+if echo "$COMMAND" | grep -qE "^[[:space:]]*read[[:space:]].*>" 2>/dev/null; then
+  BLOCKED=1
+  PATTERN_NAME="read command with redirect (waits for input)"
+fi
+
+# === STREAM REDIRECT EXCEPTION ===
+# Allow redirects to /dev/stdout, /dev/stderr, /dev/null (safe stream operations)
+if echo "$COMMAND" | grep -qE ">[[:space:]]*/dev/(stdout|stderr|null)" 2>/dev/null; then
+  exit 0  # Safe stream redirect, not file creation
+fi
+
+# === ECHO/PRINTF PATTERNS ===
+# These can cause truncation issues and are bad practice
+# NOTE: Match any echo/printf that writes to file (single > not >>)
+
+# Pattern 3: Echo with redirect to file
+# Matches: echo anything > file (but not >>)
+# Use negative lookahead simulation: check for > but then verify not >>
+if echo "$COMMAND" | grep -qE '^[[:space:]]*(echo)[[:space:]]' 2>/dev/null; then
+  if echo "$COMMAND" | grep -qE '>[[:space:]]*[^>]' 2>/dev/null; then
+    # Check it's not append (>>)
+    if ! echo "$COMMAND" | grep -qE '>>' 2>/dev/null; then
+      BLOCKED=1
+      PATTERN_NAME="echo > file"
+    fi
+  fi
+fi
+
+# Pattern 4: Printf with redirect to file
+if echo "$COMMAND" | grep -qE '^[[:space:]]*(printf)[[:space:]]' 2>/dev/null; then
+  if echo "$COMMAND" | grep -qE '>[[:space:]]*[^>]' 2>/dev/null; then
+    # Check it's not append (>>)
+    if ! echo "$COMMAND" | grep -qE '>>' 2>/dev/null; then
+      BLOCKED=1
+      PATTERN_NAME="printf > file"
+    fi
+  fi
+fi
+
+# Pattern 5: Multi-line string with cat
+# Matches: cat > file -e "multi\nline", etc.
+if echo "$COMMAND" | grep -qE "cat[[:space:]]+-[a-z]*[[:space:]]+['\"].*\\\\n" 2>/dev/null; then
+  BLOCKED=1
+  PATTERN_NAME="cat with multi-line string"
+fi
+
+# === SAFE EXCEPTIONS ===
+# Append operations (>>) are safe - echo/printf complete immediately
+if echo "$COMMAND" | grep -qE "(echo|printf)[[:space:]].*>>[[:space:]]*" 2>/dev/null; then
+  BLOCKED=0
+  PATTERN_NAME=""
+fi
+
+# === EXCEPTION: Allow safe bash operations ===
+# These are safe because they don't involve file content creation
+
+# Exception 1: Simple redirects from commands (not content creation)
+# Safe: curl ... > file, wget ... > file (command output, not content creation)
+# These won't hang because the content comes from the command, not heredoc
+if echo "$COMMAND" | grep -qE "^(curl|wget|git|npm|node|python|pip)[[:space:]].*>" 2>/dev/null; then
+  # These are downloading/generating content from commands, not creating from heredoc
+  # Only block if also contains heredoc/echo patterns
+  if [[ "$PATTERN_NAME" != "heredoc"* ]] && [[ "$PATTERN_NAME" != "echo"* ]] && [[ "$PATTERN_NAME" != "printf"* ]]; then
+    exit 0  # Allow
+  fi
+fi
+
+# === BLOCK DANGEROUS PATTERNS ===
+if [[ $BLOCKED -eq 1 ]]; then
+  echo ""
+  echo "=============================================================================="
+  echo "  🛑 BLOCKED: Bash file creation detected (Infinite Hang Prevention)"
+  echo "=============================================================================="
+  echo ""
+  echo "Pattern detected: $PATTERN_NAME"
+  echo ""
+  echo "WHY THIS IS BLOCKED:"
+  echo "  When using heredoc (cat << EOF) or echo/printf redirects, if the content"
+  echo "  is truncated due to token limits, the shell waits FOREVER for input that"
+  echo "  will never come. This causes Claude Code to hang for hours with no recovery."
+  echo ""
+  echo "  Observed crash: 2+ hour session hang from truncated heredoc (2025-12-06)"
+  echo ""
+  echo "SAFE ALTERNATIVES:"
+  echo "  ┌─────────────────────────────────────────────────────────────────────┐"
+  echo "  │ Instead of:          Use:                                           │"
+  echo "  ├─────────────────────────────────────────────────────────────────────┤"
+  echo "  │ cat > file << EOF    Write tool: Write(file_path, content)          │"
+  echo "  │ echo \"...\" > file    Write tool: Write(file_path, content)          │"
+  echo "  │ printf ... > file    Write tool: Write(file_path, content)          │"
+  echo "  │ Modify existing      Edit tool: Edit(file_path, old, new)           │"
+  echo "  │ Append to file       Read + Write tools                             │"
+  echo "  └─────────────────────────────────────────────────────────────────────┘"
+  echo ""
+  echo "WHAT IS ALLOWED:"
+  echo "  - mkdir -p /path/to/dir    (directory creation)"
+  echo "  - git commit, git push     (version control)"
+  echo "  - npm install, npm run     (package management)"
+  echo "  - curl URL > file          (downloading, not content creation)"
+  echo "  - rm, mv, cp               (file operations)"
+  echo ""
+  echo "=============================================================================="
+
+  exit 2  # Block the tool call
+fi
+
+# All other bash commands are allowed
+exit 0

package/plugins/specweave/hooks/v2/guards/bash-file-guard.test.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# Comprehensive test suite for bash-file-guard.sh
+# Tests ALL dangerous patterns that could cause infinite hangs
+#
+# Usage: bash bash-file-guard.test.sh
+
+set -e
+
+GUARD="$(dirname "$0")/bash-file-guard.sh"
+PASS=0
+FAIL=0
+TOTAL=0
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+test_should_block() {
+  local name="$1"
+  local command="$2"
+  TOTAL=$((TOTAL + 1))
+
+  # Properly escape the command for JSON: " becomes \"
+  local escaped_command=$(echo "$command" | sed 's/"/\\"/g')
+  result=$(echo "{\"command\": \"$escaped_command\"}" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+  exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+
+  if [[ "$exit_code" == "2" ]]; then
+    echo -e "${GREEN}✓ BLOCKED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ NOT BLOCKED${NC}: $name"
+    echo "  Command: $command"
+    echo "  Exit code: $exit_code (expected 2)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+test_should_allow() {
+  local name="$1"
+  local command="$2"
+  TOTAL=$((TOTAL + 1))
+
+  # Properly escape the command for JSON: " becomes \"
+  local escaped_command=$(echo "$command" | sed 's/"/\\"/g')
+  result=$(echo "{\"command\": \"$escaped_command\"}" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+  exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+
+  if [[ "$exit_code" == "0" ]]; then
+    echo -e "${GREEN}✓ ALLOWED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ WRONGLY BLOCKED${NC}: $name"
+    echo "  Command: $command"
+    echo "  Exit code: $exit_code (expected 0)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "========================================"
+echo "  BASH FILE GUARD - COMPREHENSIVE TESTS"
+echo "========================================"
+echo ""
+
+echo -e "${YELLOW}=== HEREDOC PATTERNS (MOST DANGEROUS) ===${NC}"
+test_should_block "Basic heredoc" "cat > file.txt << EOF"
+test_should_block "Heredoc with quotes" "cat > file.txt << 'EOF'"
+test_should_block "Heredoc double quotes" 'cat > file.txt << "EOF"'
+test_should_block "Heredoc reversed order" "cat << EOF > file.txt"
+test_should_block "Heredoc with END delimiter" "cat > file.txt << END"
+test_should_block "Heredoc with CONTENT delimiter" "cat << CONTENT > out.md"
+test_should_block "Heredoc with MARKER" "cat << MARKER"
+test_should_block "Heredoc tab strip" "cat <<- EOF > file.txt"
+test_should_block "Tee with heredoc" "tee file.txt << EOF"
+test_should_block "Tee reversed" "tee << EOF > file.txt"
+test_should_block "Heredoc with path" "cat > /tmp/test.md << EOF"
+test_should_block "Heredoc with variable path" 'cat > $HOME/test.txt << EOF'
+
+echo ""
+echo -e "${YELLOW}=== ECHO PATTERNS ===${NC}"
+test_should_block "Echo to file" "echo hello > file.txt"
+test_should_block "Echo quoted string" 'echo "hello world" > file.txt'
+test_should_block "Echo single quoted" "echo 'hello' > file.txt"
+test_should_block "Echo with -e flag" "echo -e 'hello\\nworld' > file.txt"
+test_should_block "Echo with -n flag" "echo -n 'hello' > file.txt"
+test_should_block "Echo variable" 'echo $VAR > file.txt'
+test_should_block "Echo to path" "echo content > /tmp/test.txt"
+
+echo ""
+echo -e "${YELLOW}=== PRINTF PATTERNS ===${NC}"
+test_should_block "Printf to file" "printf hello > file.txt"
+test_should_block "Printf format string" "printf '%s' hello > file.txt"
+test_should_block "Printf with newline" "printf '%s\\n' hello > file.txt"
+test_should_block "Printf quoted" 'printf "hello world" > file.txt'
+
+echo ""
+echo -e "${YELLOW}=== EDGE CASES - SHOULD BLOCK ===${NC}"
+test_should_block "Cat stdin to file (dangerous!)" "cat > file.txt"
+test_should_block "Bash -c with heredoc" "bash -c 'cat > f << EOF'"
+test_should_block "Double redirect" "echo a > file.txt > backup.txt"
+test_should_block "dd stdin to file" "dd if=/dev/stdin of=output.dat"
+test_should_block "dd output file" "dd of=file.bin bs=1024"
+test_should_block "dd with count" "dd of=output.img bs=512 count=100"
+test_should_block "read to file" "read VAR > input.txt"
+test_should_block "read prompt to file" 'read -p "Enter:" > log.txt'
+
+echo ""
+echo -e "${YELLOW}=== SAFE COMMANDS - SHOULD ALLOW ===${NC}"
+test_should_allow "Git status" "git status"
+test_should_allow "Git add" "git add ."
+test_should_allow "Git commit" "git commit -m 'message'"
+test_should_allow "Git push" "git push origin main"
+test_should_allow "Git diff" "git diff HEAD"
+test_should_allow "Npm install" "npm install"
+test_should_allow "Npm run build" "npm run build"
+test_should_allow "Npm test" "npm test"
+test_should_allow "Mkdir" "mkdir -p /tmp/test"
+test_should_allow "Ls" "ls -la"
+test_should_allow "Pwd" "pwd"
+test_should_allow "Cd" "cd /tmp"
+test_should_allow "Rm file" "rm -f /tmp/test.txt"
+test_should_allow "Mv file" "mv old.txt new.txt"
+test_should_allow "Cp file" "cp source.txt dest.txt"
+test_should_allow "Curl download" "curl -o file.txt https://example.com"
+test_should_allow "Wget download" "wget -O file.txt https://example.com"
+test_should_allow "Ps" "ps aux"
+test_should_allow "Kill" "kill -9 1234"
+test_should_allow "Grep" "grep pattern file.txt"
+test_should_allow "Find" "find . -name '*.ts'"
+test_should_allow "Chmod" "chmod +x script.sh"
+test_should_allow "Node run" "node script.js"
+test_should_allow "Python run" "python script.py"
+test_should_allow "Read from file" "cat file.txt"
+test_should_allow "Head" "head -n 10 file.txt"
+test_should_allow "Tail" "tail -f log.txt"
+
+echo ""
+echo -e "${YELLOW}=== APPEND OPERATIONS (should allow) ===${NC}"
+test_should_allow "Echo append" "echo hello >> file.txt"
+test_should_allow "Printf append" "printf '%s' data >> file.txt"
+
+echo ""
+echo -e "${YELLOW}=== STREAM REDIRECTS (should allow) ===${NC}"
+test_should_allow "Echo to stderr" "echo 'error' > /dev/stderr"
+test_should_allow "Printf to stdout" "printf '%s' output > /dev/stdout"
+test_should_allow "Echo to null" "echo 'discard' > /dev/null"
+
+echo ""
+echo "========================================"
+echo "  RESULTS"
+echo "========================================"
+echo -e "Total: $TOTAL"
+echo -e "${GREEN}Passed: $PASS${NC}"
+if [[ $FAIL -gt 0 ]]; then
+  echo -e "${RED}Failed: $FAIL${NC}"
+  exit 1
+else
+  echo -e "Failed: 0"
+  echo ""
+  echo -e "${GREEN}ALL TESTS PASSED!${NC}"
+fi

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

@@ -45,34 +45,32 @@ if echo "$NEW_CONTENT" | grep -q '"status"[[:space:]]*:[[:space:]]*"completed"';
   fi
 
   # BLOCK - trying to set completed without going through ready_for_review
-  cat << 'EOF'
-
-==============================================================================
-  BLOCKED: Direct status change to "completed" is not allowed (v0.28.63+)
-==============================================================================
-
-You cannot directly set status to "completed" in metadata.json.
-
-This prevents the auto-completion bug where increments get marked as
-completed without proper validation.
-
-CORRECT WORKFLOW:
-1. All tasks completed -> status auto-transitions to "ready_for_review"
-2. Run /specweave:done <increment-id> with explicit user confirmation
-3. Only then does status become "completed"
-
-WHY THIS MATTERS:
-- Ensures all ACs are checked in spec.md before closure
-- Requires explicit user approval
-- Maintains audit trail (approvedAt timestamp)
-
-If you're implementing closure logic, use:
-  MetadataManager.updateStatus(incrementId, IncrementStatus.COMPLETED)
-
-This will only succeed if current status is "ready_for_review".
-
-==============================================================================
-EOF
+  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 /specweave: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 "=============================================================================="
 
   exit 2  # Block the tool call
 fi

package/plugins/specweave/hooks/v2/guards/features-folder-guard.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# features-folder-guard.sh - Block writes to obsolete _features/ folder
+#
+# ROOT CAUSE: The _features/ folder is OBSOLETE since v5.0.0. Features should
+# live in {project}/FS-XXX/ folders. LLM agents sometimes create files in
+# _features/ due to outdated documentation references.
+#
+# SOLUTION: Block all Write/Edit operations targeting _features/ folder.
+# This forces proper project-based feature folder structure.
+#
+# PreToolUse hook for Write/Edit commands - exit 0 allows, exit 2 blocks
+#
+# v0.33.0 - Initial implementation based on bug analysis from 2025-12-06
+
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+# Read stdin for tool input
+INPUT=$(cat)
+
+# Extract the file_path being written/edited
+if command -v jq &> /dev/null; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.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:]]*"\(.*\)"/\1/')
+fi
+
+# If no file_path found, allow (safety)
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# === PATTERN DETECTION ===
+# Block any write to _features/ folder (obsolete since v5.0.0)
+
+# Pattern: .specweave/docs/internal/specs/_features/
+if [[ "$FILE_PATH" =~ \.specweave/docs/internal/specs/_features/ ]]; then
+  cat << 'EOF'
+{
+  "decision": "block",
+  "reason": "🚫 BLOCKED: Writing to _features/ folder (OBSOLETE since v5.0.0)\n\n⚠️ The _features/ folder has been deprecated.\nFeatures must now live in project folders: .specweave/docs/internal/specs/{project}/FS-XXX/\n\n📋 CORRECT structure:\n  .specweave/docs/internal/specs/specweave/FS-116/FEATURE.md ✅\n  .specweave/docs/internal/specs/backend/FS-117/us-001.md ✅\n\n❌ OBSOLETE structure:\n  .specweave/docs/internal/specs/_features/FS-116/FEATURE.md ❌\n\n🔧 To fix: Use spec.md `project:` field to determine target folder.\nSee: CLAUDE.md section '2c. spec.md MUST Have project:'"
+}
+EOF
+  exit 2
+fi
+
+# Allow all other writes
+printf '{"decision":"allow"}'
+exit 0

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

@@ -0,0 +1,135 @@
+#!/bin/bash
+# increment-duplicate-guard.sh - Block creation of duplicate increment IDs
+#
+# v0.33.0+: Prevents duplicate increment numbers (0121 and 0121 both existing)
+# Also prevents 0001 and 0001E collisions (they share the same base number)
+#
+# PreToolUse hook for Write tool - BLOCKS the tool call if duplicate detected
+#
+# CRITICAL: This guards against the BUG where two increments get the same ID:
+# - 0121-ado-jira-feature-parity-p2-p3
+# - 0121-intelligent-living-docs-content
+#
+# Exit 0 = allow, Exit 2 = block
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+# Read stdin for tool input
+INPUT=$(cat)
+
+# Extract file_path from the tool call
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+
+# Only care about .specweave/increments/ paths
+if [[ "$FILE_PATH" != *.specweave/increments/* ]]; then
+  exit 0  # Not an increment file - allow
+fi
+
+# Extract the increment folder name from the path
+# Pattern: .specweave/increments/XXXX-name/file.md or .specweave/increments/XXXX-name/subfolder/file
+# We need to extract "XXXX-name" part
+
+# Remove the .specweave/increments/ prefix
+AFTER_INCREMENTS=${FILE_PATH#*.specweave/increments/}
+
+# Get the first path component (the increment folder)
+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
+  exit 0
+fi
+
+# Extract the increment number from folder name (handles both 0121-name and 0121E-name)
+INCREMENT_NUM=$(echo "$INCREMENT_FOLDER" | grep -oE '^[0-9]{3,4}' | head -1)
+
+if [[ -z "$INCREMENT_NUM" ]]; then
+  exit 0  # Not a standard increment folder pattern - allow
+fi
+
+# Normalize to 4 digits (strip leading zeros to avoid octal interpretation)
+INCREMENT_NUM=$(printf "%04d" "$((10#$INCREMENT_NUM))")
+
+# Find the increments root directory
+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)
+fi
+
+# Scan ALL directories for existing increment with the same number
+DIRS_TO_CHECK=(
+  "$INCREMENTS_DIR"
+  "$INCREMENTS_DIR/_archive"
+  "$INCREMENTS_DIR/_abandoned"
+  "$INCREMENTS_DIR/_paused"
+)
+
+FOUND_DUPLICATES=()
+
+for DIR in "${DIRS_TO_CHECK[@]}"; do
+  if [[ ! -d "$DIR" ]]; then
+    continue
+  fi
+
+  # Find all folders matching this increment number (including E suffix variants)
+  while IFS= read -r -d '' EXISTING_FOLDER; do
+    EXISTING_NAME=$(basename "$EXISTING_FOLDER")
+
+    # Extract number from existing folder
+    EXISTING_NUM=$(echo "$EXISTING_NAME" | grep -oE '^[0-9]{3,4}' | head -1)
+
+    if [[ -z "$EXISTING_NUM" ]]; then
+      continue
+    fi
+
+    EXISTING_NUM=$(printf "%04d" "$((10#$EXISTING_NUM))")
+
+    # Check if same base number (0121 matches 0121, 0121E, etc.)
+    if [[ "$EXISTING_NUM" == "$INCREMENT_NUM" ]]; then
+      # Skip if it's the exact same folder we're creating
+      if [[ "$EXISTING_NAME" == "$INCREMENT_FOLDER" ]]; then
+        continue
+      fi
+
+      # Found a duplicate!
+      FOUND_DUPLICATES+=("$EXISTING_NAME (in $(basename "$DIR"))")
+    fi
+  done < <(find "$DIR" -maxdepth 1 -type d -name "${INCREMENT_NUM}*" -print0 2>/dev/null)
+done
+
+# If duplicates found, BLOCK the operation
+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 ""
+  for DUP in "${FOUND_DUPLICATES[@]}"; do
+    echo "  - $DUP"
+  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 "=============================================================================="
+
+  exit 2  # Block the tool call
+fi
+
+# No duplicates - allow
+exit 0

package/plugins/specweave/lib/vendor/core/increment/duplicate-detector.js

@@ -184,8 +184,8 @@ async function scanDirectory(dir, throwOnError = false) {
  * Extract increment number from increment name (e.g., "0001-feature" → "0001")
  */
 function extractIncrementNumber(name) {
-    const match = name.match(/^(\d{4})-/);
-    return match ? match[1] : null;
+    const match = name.match(/^(\d{3,4})E?-/);
+    return match ? match[1].padStart(4, '0') : null;
 }
 /**
  * Select winning version based on priority rules