specweave 0.32.10 → 0.33.3

package/plugins/specweave/commands/specweave-living-docs.md

@@ -31,6 +31,7 @@ Launch the Living Docs Builder independently of `specweave init`. This is essent
 | `--sources <folders>` | Additional doc folders (comma-separated): `docs/,wiki/` |
 | `--depends-on <jobIds>` | Wait for jobs before starting (comma-separated) |
 | `--foreground` | Run in current session instead of background |
+| `--full` | Force full rebuild by clearing cache and checkpoints (bypasses incremental mode) |
 
 ---
 
@@ -73,6 +74,9 @@ Launch the Living Docs Builder independently of `specweave init`. This is essent
 
 # AI-powered deep analysis (FREE with MAX subscription)
 /specweave:living-docs --depth deep-native --priority core,api
+
+# Force full rebuild (clears cache and checkpoints)
+/specweave:living-docs --full --depth standard
 ```
 
 ---
@@ -220,6 +224,44 @@ The job will:
 
 ---
 
+## Update Summary (v0.33.0+)
+
+After completion, you'll see a detailed summary showing:
+
+```
+✅ LIVING DOCS UPDATE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 SUMMARY:
+
+  Discovery: Discovered 3 repos (2,845 files)
+    Duration: 5s
+
+  Analysis: Analyzed 3 repos
+    Duration: 127s
+
+  Synthesis: Generated 12 ADRs, 4 teams
+    Duration: 43s
+
+  Files Created: 47
+    • .specweave/docs/internal/repos/main/overview.md
+    • .specweave/docs/internal/repos/main/api-surface.md
+    • .specweave/docs/internal/architecture/system-architecture.md
+    • .specweave/docs/internal/architecture/adr/0001-typescript-migration.md
+    • .specweave/docs/internal/architecture/adr/0002-plugin-system.md
+    ... and 42 more
+
+  Files Updated: 8
+    • .specweave/docs/internal/modules/auth.md
+    • .specweave/docs/internal/modules/payments.md
+    ... and 6 more
+
+  Total Duration: 175s
+  Mode: INCREMENTAL (cache used)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
 ## Output Files
 
 After completion:

package/plugins/specweave/hooks/hooks.json

@@ -50,6 +50,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write",
+        "matcher_content": "\\.specweave/increments/\\d{3,4}E?-[^/]+/spec\\.md",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/per-us-project-validator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "matcher_content": "\\.specweave/docs/internal/specs/_features/",
@@ -69,6 +79,16 @@
             "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/increment-duplicate-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
           }
         ]
+      },
+      {
+        "matcher": "Write",
+        "matcher_content": "\\.specweave/increments/\\d{3,4}E?-[^/]+/[^/]+$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/increment-root-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/plugins/specweave/hooks/lib/update-active-increment.sh

@@ -37,7 +37,7 @@ mkdir -p "$STATE_DIR" 2>/dev/null || true
 # ============================================================================
 # SCAN ALL INCREMENTS FOR ACTIVE STATUS
 # ============================================================================
-# Strategy: Scan metadata.json files for status=active|planning|in-progress
+# Strategy: Scan metadata.json files for status=active|planning|backlog|ready_for_review
 # This matches what ActiveIncrementManager.smartUpdate() does in TypeScript
 
 ACTIVE_IDS=()
@@ -54,7 +54,7 @@ while IFS= read -r metadata_file; do
   fi
 
   # Check if status is active-like
-  if [[ "$status" == "active" ]] || [[ "$status" == "planning" ]] || [[ "$status" == "in-progress" ]]; then
+  if [[ "$status" == "active" ]] || [[ "$status" == "planning" ]] || [[ "$status" == "backlog" ]] || [[ "$status" == "ready_for_review" ]]; then
     increment_id=$(basename "$(dirname "$metadata_file")")
     ACTIVE_IDS+=("$increment_id")
     echo "[$(date)] update-active-increment: Found active: $increment_id (status: $status)" >> "$DEBUG_LOG" 2>/dev/null || true

package/plugins/specweave/hooks/lib/update-status-line.sh

@@ -129,7 +129,7 @@ while IFS= read -r metadata_file; do
   fi
 
   # Check if active
-  if [[ "$status" == "active" || "$status" == "planning" || "$status" == "in-progress" ]]; then
+  if [[ "$status" == "active" || "$status" == "planning" || "$status" == "backlog" || "$status" == "ready_for_review" ]]; then
     OPEN_COUNT=$((OPEN_COUNT + 1))
     increment_id=$(basename "$(dirname "$metadata_file")")
 

package/plugins/specweave/hooks/post-increment-status-change.sh

@@ -62,7 +62,7 @@ echo "[$(date)] 📊 Status changed: $NEW_STATUS" >> "$DEBUG_LOG" 2>/dev/null ||
 
 # Validate status
 case "$NEW_STATUS" in
-  paused|resumed|abandoned|active|in-progress)
+  paused|abandoned|active|planning|backlog|ready_for_review|completed)
     ;;
   *)
     echo "[$(date)] ⚠️  Unknown status: $NEW_STATUS (skipping sync)" >> "$DEBUG_LOG" 2>/dev/null || true
@@ -107,11 +107,11 @@ fi
 # ============================================================================
 
 case "$NEW_STATUS" in
-  resumed|active|in-progress)
+  active|planning|backlog|ready_for_review)
     # ========================================================================
     # REOPEN GitHub Issues (NEW)
     # ========================================================================
-    # When increment is resumed, reopen all closed GitHub issues
+    # When increment becomes active (including resumed from pause), reopen all closed GitHub issues
     echo "[$(date)] ▶️  Status is $NEW_STATUS - checking if issues need reopening" >> "$DEBUG_LOG" 2>/dev/null || true
 
     if command -v node &> /dev/null; then

package/plugins/specweave/hooks/post-metadata-change.sh

@@ -224,7 +224,7 @@ case "$CURRENT_STATUS" in
     bash "$HOOK_DIR/lib/update-status-line.sh" --force 2>/dev/null || true
     ;;
 
-  active|planning|in-progress)
+  active|planning|backlog|ready_for_review)
     # Increment became active - MUST register in active-increment.json!
     # CRITICAL FIX (v0.26.15): post-task-completion.sh depends on this file
     # Without registration, ALL sync operations are skipped!

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

@@ -1,26 +1,26 @@
-@echo off
-REM hook-wrapper.cmd - Windows resilient hook launcher
-REM Prevents crashes when dispatcher.mjs is temporarily unavailable
-
-setlocal enabledelayedexpansion
-
-set "HOOK_TYPE=%~1"
-if "%HOOK_TYPE%"=="" set "HOOK_TYPE=unknown"
-
-set "SCRIPT_DIR=%~dp0"
-set "DISPATCHER=%SCRIPT_DIR%dispatcher.mjs"
-
-REM Check if dispatcher exists
-if not exist "%DISPATCHER%" (
-    echo {"continue":true,"systemMessage":"Hook skipped: dispatcher.mjs not found"}
-    exit /b 0
-)
-
-REM Run dispatcher with error suppression
-node "%DISPATCHER%" "%HOOK_TYPE%" 2>nul
-if errorlevel 1 (
-    echo {"continue":true,"systemMessage":"Hook error, continuing"}
-    exit /b 0
-)
-
-exit /b 0
+@echo off
+REM hook-wrapper.cmd - Windows resilient hook launcher
+REM Prevents crashes when dispatcher.mjs is temporarily unavailable
+
+setlocal enabledelayedexpansion
+
+set "HOOK_TYPE=%~1"
+if "%HOOK_TYPE%"=="" set "HOOK_TYPE=unknown"
+
+set "SCRIPT_DIR=%~dp0"
+set "DISPATCHER=%SCRIPT_DIR%dispatcher.mjs"
+
+REM Check if dispatcher exists
+if not exist "%DISPATCHER%" (
+    echo {"continue":true,"systemMessage":"Hook skipped: dispatcher.mjs not found"}
+    exit /b 0
+)
+
+REM Run dispatcher with error suppression
+node "%DISPATCHER%" "%HOOK_TYPE%" 2>nul
+if errorlevel 1 (
+    echo {"continue":true,"systemMessage":"Hook error, continuing"}
+    exit /b 0
+)
+
+exit /b 0

package/plugins/specweave/hooks/universal/session-start.cmd

@@ -1,16 +1,16 @@
-@echo off
-:: Universal Session Start Hook for Windows
-:: Calls the Node.js dispatcher
-
-:: Find node.exe
-where node >nul 2>&1
-if %ERRORLEVEL% neq 0 (
-    echo {"continue": true, "error": "Node.js not found"}
-    exit /b 0
-)
-
-:: Get the directory of this script
-set "SCRIPT_DIR=%~dp0"
-
-:: Run the dispatcher
-node "%SCRIPT_DIR%dispatcher.mjs" session-start
+@echo off
+:: Universal Session Start Hook for Windows
+:: Calls the Node.js dispatcher
+
+:: Find node.exe
+where node >nul 2>&1
+if %ERRORLEVEL% neq 0 (
+    echo {"continue": true, "error": "Node.js not found"}
+    exit /b 0
+)
+
+:: Get the directory of this script
+set "SCRIPT_DIR=%~dp0"
+
+:: Run the dispatcher
+node "%SCRIPT_DIR%dispatcher.mjs" session-start

package/plugins/specweave/hooks/universal/session-start.ps1

@@ -1,16 +1,16 @@
-# Universal Session Start Hook for Windows PowerShell
-# Calls the Node.js dispatcher for cross-platform compatibility
-
-# Find node.exe
-$nodePath = Get-Command node -ErrorAction SilentlyContinue
-
-if (-not $nodePath) {
-    Write-Host '{"continue": true, "error": "Node.js not found"}'
-    exit 0
-}
-
-# Get script directory
-$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
-
-# Run the dispatcher
-& node "$scriptDir\dispatcher.mjs" session-start
+# Universal Session Start Hook for Windows PowerShell
+# Calls the Node.js dispatcher for cross-platform compatibility
+
+# Find node.exe
+$nodePath = Get-Command node -ErrorAction SilentlyContinue
+
+if (-not $nodePath) {
+    Write-Host '{"continue": true, "error": "Node.js not found"}'
+    exit 0
+}
+
+# Get script directory
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Run the dispatcher
+& node "$scriptDir\dispatcher.mjs" session-start

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

@@ -151,7 +151,7 @@ if echo "$PROMPT" | grep -qE "^/specweave:do($| )"; then
       else
         status=$(grep -oP '"status"\s*:\s*"\K[^"]*' "$meta" 2>/dev/null || echo "unknown")
       fi
-      if [[ "$status" == "active" || "$status" == "in-progress" ]]; then
+      if [[ "$status" == "active" || "$status" == "planning" || "$status" == "backlog" || "$status" == "ready_for_review" ]]; then
         DO_INCREMENT_ID=$(basename "$(dirname "$meta")")
         break
       fi
@@ -191,7 +191,7 @@ if [[ -d "$SPECWEAVE_DIR/increments" ]]; then
       inc_type=$(grep -oP '"type"\s*:\s*"\K[^"]*' "$metadata_file" 2>/dev/null || echo "feature")
     fi
 
-    if [[ "$status" == "active" || "$status" == "planning" || "$status" == "in-progress" ]]; then
+    if [[ "$status" == "active" || "$status" == "planning" || "$status" == "backlog" || "$status" == "ready_for_review" ]]; then
       inc_id=$(basename "$(dirname "$metadata_file")")
       ACTIVE_COUNT=$((ACTIVE_COUNT + 1))
       ACTIVE_LIST="${ACTIVE_LIST}  - $inc_id [$inc_type]\n"
@@ -204,7 +204,91 @@ fi
 # DISCIPLINE VALIDATION: Warn about WIP limits (configurable, not hard block!)
 # ==============================================================================
 
-if echo "$PROMPT" | grep -q "/specweave:increment"; then
+# ==============================================================================
+# PROJECT CONTEXT + WIP LIMITS FOR /specweave:increment (v0.34.0)
+# ==============================================================================
+# CRITICAL: Inject project/board context BEFORE Claude generates spec.md
+# This ensures Claude knows available projects and uses correct IDs
+# ALSO: Check WIP limits in same block to avoid duplicate command detection
+
+if echo "$PROMPT" | grep -qE "^/specweave:increment"; then
+  # Get project context (uses specweave CLI if available)
+  PROJECT_CONTEXT=""
+
+  if command -v specweave >/dev/null 2>&1; then
+    # Use CLI for accurate project/board detection
+    CONTEXT_JSON=$(specweave context projects 2>/dev/null || echo '{}')
+
+    # Validate JSON before parsing (defensive coding)
+    if [[ -n "$CONTEXT_JSON" ]] && [[ "$CONTEXT_JSON" != "{}" ]]; then
+      if command -v jq >/dev/null 2>&1; then
+        # Verify JSON is parseable before extracting fields
+        if ! echo "$CONTEXT_JSON" | jq empty 2>/dev/null; then
+          CONTEXT_JSON='{}'  # Invalid JSON - reset to empty
+        fi
+      fi
+    fi
+
+    if [[ -n "$CONTEXT_JSON" ]] && [[ "$CONTEXT_JSON" != "{}" ]]; then
+      # Parse JSON with jq
+      if command -v jq >/dev/null 2>&1; then
+        LEVEL=$(echo "$CONTEXT_JSON" | jq -r '.level // 1')
+        PROJECTS=$(echo "$CONTEXT_JSON" | jq -r '.projects | map(.id) | join(", ")' 2>/dev/null || echo "")
+
+        if [[ "$LEVEL" == "2" ]]; then
+          # 2-level structure: include boards
+          BOARDS_JSON=$(echo "$CONTEXT_JSON" | jq -r '.boardsByProject // {}' 2>/dev/null)
+          if [[ -n "$BOARDS_JSON" ]] && [[ "$BOARDS_JSON" != "{}" ]]; then
+            PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT (2-LEVEL STRUCTURE)\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}⚠️ MANDATORY: Each User Story MUST have both:\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}  - **Project**: <project_id>\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}  - **Board**: <board_id>\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Available projects: ${PROJECTS}\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Boards by project:\\n"
+
+            # Format boards
+            for proj in $(echo "$CONTEXT_JSON" | jq -r '.projects[].id' 2>/dev/null); do
+              PROJ_BOARDS=$(echo "$CONTEXT_JSON" | jq -r ".boardsByProject[\"$proj\"] | map(.id) | join(\", \")" 2>/dev/null || echo "")
+              [[ -n "$PROJ_BOARDS" ]] && PROJECT_CONTEXT="${PROJECT_CONTEXT}  - ${proj}: ${PROJ_BOARDS}\\n"
+            done
+
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}\\n❌ FORBIDDEN: Comma-separated values (e.g., **Project**: fe, be)\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}✅ REQUIRED: One project + one board per User Story"
+          fi
+        elif [[ -n "$PROJECTS" ]]; then
+          # 1-level structure: projects only
+          PROJECT_COUNT=$(echo "$CONTEXT_JSON" | jq '.projects | length' 2>/dev/null || echo "0")
+
+          if [[ "$PROJECT_COUNT" -gt 1 ]]; then
+            PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT (MULTI-PROJECT)\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}⚠️ MANDATORY: Each User Story MUST have:\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}  - **Project**: <project_id>\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Available projects: ${PROJECTS}\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}\\n❌ FORBIDDEN: Comma-separated values\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}✅ REQUIRED: One project per User Story"
+          elif [[ "$PROJECT_COUNT" -eq 1 ]]; then
+            # Single project: auto-select
+            SINGLE_PROJECT=$(echo "$CONTEXT_JSON" | jq -r '.projects[0].id' 2>/dev/null)
+            PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Single project detected: ${SINGLE_PROJECT} (auto-selected)"
+          fi
+        fi
+      fi
+    fi
+  else
+    # Fallback: Check for multi-project folders
+    if [[ -d "$SPECWEAVE_DIR/docs/internal/specs" ]]; then
+      PROJ_COUNT=$(find "$SPECWEAVE_DIR/docs/internal/specs" -maxdepth 1 -type d | wc -l)
+      if [[ "$PROJ_COUNT" -gt 2 ]]; then
+        PROJ_LIST=$(ls -1 "$SPECWEAVE_DIR/docs/internal/specs" 2>/dev/null | grep -v "_" | tr '\n' ', ' | sed 's/,$//')
+        PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT (MULTI-PROJECT)\\n"
+        PROJECT_CONTEXT="${PROJECT_CONTEXT}⚠️ MANDATORY: Each User Story MUST have **Project**: field\\n"
+        PROJECT_CONTEXT="${PROJECT_CONTEXT}Available folders: ${PROJ_LIST}"
+      fi
+    fi
+  fi
+
+  # WIP LIMITS CHECK (inside same block - no duplicate command detection)
   # Read limits from config.json (respect user's settings!)
   CONFIG_FILE="$SPECWEAVE_DIR/config.json"
   SOFT_LIMIT=1
@@ -226,13 +310,31 @@ if echo "$PROMPT" | grep -q "/specweave:increment"; then
 
   # Above hard cap: strong warning but NOT a block (user decides!)
   if [[ "$ACTIVE_COUNT" -ge "$HARD_CAP" ]]; then
-    printf '{"decision":"approve","systemMessage":"⚠️  WIP LIMIT EXCEEDED (%s/%s)\\n\\nYou have %s active increments (configured maximum: %s)\\n\\nActive increments:\\n%s\\n\\n🧠 Research shows 3+ concurrent tasks = 40%% slower + more bugs\\n\\n💡 Options:\\n  1️⃣  Complete an increment: /specweave:done <id>\\n  2️⃣  Pause an increment: /specweave:pause <id>\\n  3️⃣  Increase limit: Edit .specweave/config.json limits.hardCap\\n  4️⃣  Continue anyway (not recommended)\\n\\n📝 To proceed anyway, just confirm your intent."}\n' "$ACTIVE_COUNT" "$HARD_CAP" "$ACTIVE_COUNT" "$HARD_CAP" "$ACTIVE_LIST"
+    WIP_MSG="⚠️  WIP LIMIT EXCEEDED (${ACTIVE_COUNT}/${HARD_CAP})\\n\\nYou have ${ACTIVE_COUNT} active increments (configured maximum: ${HARD_CAP})\\n\\nActive increments:\\n${ACTIVE_LIST}\\n\\n🧠 Research shows 3+ concurrent tasks = 40%% slower + more bugs\\n\\n💡 Options:\\n  1️⃣  Complete an increment: /specweave:done <id>\\n  2️⃣  Pause an increment: /specweave:pause <id>\\n  3️⃣  Increase limit: Edit .specweave/config.json limits.hardCap\\n  4️⃣  Continue anyway (not recommended)\\n\\n📝 To proceed anyway, just confirm your intent."
+    # Prepend project context if available
+    if [[ -n "$PROJECT_CONTEXT" ]]; then
+      printf '{"decision":"approve","systemMessage":"%s%s"}\n' "$PROJECT_CONTEXT" "$WIP_MSG"
+    else
+      printf '{"decision":"approve","systemMessage":"%s"}\n' "$WIP_MSG"
+    fi
     exit 0
   fi
 
   # At soft limit: mild warning, approve
   if [[ "$ACTIVE_COUNT" -ge "$SOFT_LIMIT" ]]; then
-    printf '{"decision":"approve","systemMessage":"⚠️  WIP LIMIT REACHED (%s/%s)\\n\\nYou have %s active increment(s) (recommended limit: %s)\\n\\nActive increments:\\n%s\\n\\n🧠 Focus Principle: Fewer active increments = maximum productivity\\n\\n💡 Consider:\\n  1️⃣  Complete current work (recommended)\\n  2️⃣  Pause current work (/specweave:pause)\\n  3️⃣  Continue anyway\\n\\n⚠️  Emergency hotfix/bug? Use --type=hotfix or --type=bug"}\n' "$ACTIVE_COUNT" "$SOFT_LIMIT" "$ACTIVE_COUNT" "$SOFT_LIMIT" "$ACTIVE_LIST"
+    WIP_MSG="⚠️  WIP LIMIT REACHED (${ACTIVE_COUNT}/${SOFT_LIMIT})\\n\\nYou have ${ACTIVE_COUNT} active increment(s) (recommended limit: ${SOFT_LIMIT})\\n\\nActive increments:\\n${ACTIVE_LIST}\\n\\n🧠 Focus Principle: Fewer active increments = maximum productivity\\n\\n💡 Consider:\\n  1️⃣  Complete current work (recommended)\\n  2️⃣  Pause current work (/specweave:pause)\\n  3️⃣  Continue anyway\\n\\n⚠️  Emergency hotfix/bug? Use --type=hotfix or --type=bug"
+    # Prepend project context if available
+    if [[ -n "$PROJECT_CONTEXT" ]]; then
+      printf '{"decision":"approve","systemMessage":"%s%s"}\n' "$PROJECT_CONTEXT" "$WIP_MSG"
+    else
+      printf '{"decision":"approve","systemMessage":"%s"}\n' "$WIP_MSG"
+    fi
+    exit 0
+  fi
+
+  # No WIP limit warning, but we may have project context to inject
+  if [[ -n "$PROJECT_CONTEXT" ]]; then
+    printf '{"decision":"approve","systemMessage":"%s"}\n' "$PROJECT_CONTEXT"
     exit 0
   fi
 fi

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

@@ -0,0 +1,61 @@
+#!/bin/bash
+# increment-root-guard.sh - Block files at increment root (except allowed)
+#
+# ROOT CAUSE: Agents sometimes create files like COMPLETION_REPORT.md,
+# COMPLETION_SUMMARY.md, or other .md files at increment root instead of
+# placing them in appropriate subfolders (reports/, scripts/, logs/, etc.)
+#
+# SOLUTION: Block Write operations to increment root for non-standard files.
+# Only allow: metadata.json, spec.md, plan.md, tasks.md
+# Everything else MUST go in subfolders: reports/, scripts/, logs/, backups/, docs/
+#
+# PreToolUse hook for Write command - exit 0 allows, exit 2 blocks
+#
+# v0.33.0 - Initial implementation based on bug analysis from 2025-12-09
+
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+# Read stdin for tool input
+INPUT=$(cat)
+
+# Extract the file_path being written
+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 files at increment root that should be in subfolders
+
+# Pattern: .specweave/increments/####-name/FILE.md (at root, not in subfolder)
+# Allowed at root: metadata.json, spec.md, plan.md, tasks.md
+if [[ "$FILE_PATH" =~ \.specweave/increments/[0-9]{3,4}E?-[^/]+/([^/]+)$ ]]; then
+  FILENAME="${BASH_REMATCH[1]}"
+
+  # Allow standard increment files at root
+  if [[ "$FILENAME" =~ ^(metadata\.json|spec\.md|plan\.md|tasks\.md)$ ]]; then
+    printf '{"decision":"allow"}'
+    exit 0
+  fi
+
+  # Block everything else at increment root
+  cat << EOF
+{
+  "decision": "block",
+  "reason": "🚫 BLOCKED: File '$FILENAME' should be in a subfolder, not at increment root\n\n⚠️ CLAUDE.md Folder Structure Rule:\n  Inside increment folders - ONLY at root: spec.md, plan.md, tasks.md, metadata.json\n  Everything else → subfolders: reports/, scripts/, logs/, backups/, docs/\n\n📋 CORRECT structure:\n  .specweave/increments/####-name/reports/COMPLETION_REPORT.md ✅\n  .specweave/increments/####-name/reports/COMPLETION_SUMMARY.md ✅\n  .specweave/increments/####-name/scripts/analyze.sh ✅\n\n❌ WRONG structure:\n  .specweave/increments/####-name/COMPLETION_REPORT.md ❌\n  .specweave/increments/####-name/COMPLETION_SUMMARY.md ❌\n\n🔧 To fix: Create file in reports/ subfolder instead.\nUse: Write({ file_path: \".specweave/increments/####-name/reports/$FILENAME\", ... })\n\nSee: CLAUDE.md section 'Folder Structure'"
+}
+EOF
+  exit 2
+fi
+
+# Allow all other writes (files in subfolders, or outside increments)
+printf '{"decision":"allow"}'
+exit 0