specweave 0.28.61 → 0.28.63

package/plugins/specweave/commands/specweave-next.md

@@ -9,6 +9,8 @@ description: Smart increment transition - auto-close current if ready, intellige
 
 You are helping the user complete their current increment and move to the next one with intelligent suggestions.
 
+**CRITICAL (v0.28.63+)**: This command now requires **EXPLICIT USER CONFIRMATION** before closing any increment! This prevents the auto-completion bug where increments were marked "completed" without user approval.
+
 ## Usage
 
 ```bash
@@ -24,9 +26,10 @@ You are helping the user complete their current increment and move to the next o
 The `/specweave:next` command is your **workflow continuation** command. It:
 
 1. **Validates current increment** - Checks if work is complete
-2. **Auto-closes if ready** - PM validates and closes automatically
-3. **Suggests next work** - Intelligent recommendations from backlog or prompt for new
-4. **Smooth transition** - No manual `/done` + `/inc` needed
+2. **Transitions to ready_for_review** - If all tasks done, auto-transitions to `ready_for_review`
+3. **ASKS USER FOR CONFIRMATION** - NEVER auto-closes! Always asks "Ready to close this increment?"
+4. **Closes on explicit approval** - Only marks `completed` if user confirms
+5. **Suggests next work** - Intelligent recommendations from backlog or prompt for new
 
 ---
 
@@ -131,7 +134,9 @@ Status: ✅ PASS
 
 **Based on PM validation results**:
 
-#### Scenario A: All Gates Pass ✅ (Auto-Close)
+#### Scenario A: All Gates Pass ✅ (ASK USER CONFIRMATION - v0.28.63+)
+
+**CRITICAL**: NEVER auto-close! Always ask for user confirmation to prevent the auto-completion bug.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -142,11 +147,43 @@ PM VALIDATION: ✅ READY TO CLOSE
 ✅ Gate 2: Tests (70/70 passing, 89% coverage)
 ✅ Gate 3: Docs (all current)
 
-Increment 0001-user-authentication is complete!
+Increment 0001-user-authentication is ready for closure!
+
+📋 Status: ready_for_review (awaiting your approval)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  CONFIRMATION REQUIRED (v0.28.63+)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This will permanently mark the increment as COMPLETED.
+
+Please confirm: Do you want to close this increment?
 
-🎯 Auto-closing increment...
-  ✓ Updated status: in-progress → completed
+A. Yes, close it - I've reviewed the work and it's complete
+B. No, keep it open - I need to review or make changes first
+```
+
+**🔥 CRITICAL**: Use the AskUserQuestion tool to get explicit confirmation:
+```
+AskUserQuestion({
+  questions: [{
+    header: "Close increment?",
+    question: "All PM gates passed. Ready to permanently close this increment?",
+    options: [
+      { label: "Yes, close it", description: "Mark as completed (irreversible)" },
+      { label: "No, keep open", description: "Stay at ready_for_review status" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**Only if user confirms "Yes"**:
+```
+🎯 Closing increment with your approval...
+  ✓ Updated status: ready_for_review → completed
   ✓ Set completion date: 2025-10-28
+  ✓ Set approvedAt timestamp
   ✓ Generated completion report
   ✓ Freed WIP slot (1/2 → 0/2)
 
@@ -412,8 +449,28 @@ Active: 0001-user-authentication
   ✅ Gate 2: All tests passing (70/70, 89% coverage)
   ✅ Gate 3: Documentation updated
 
-🎯 Auto-closing increment 0001...
-  ✓ Status: completed
+✅ All gates passed! Transitioning to ready_for_review...
+
+📋 Status: ready_for_review (awaiting your approval)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  CONFIRMATION REQUIRED (v0.28.63+)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This will permanently mark increment 0001 as COMPLETED.
+
+Please confirm: Do you want to close this increment?
+```
+
+**🔥 Claude uses AskUserQuestion tool here to get explicit confirmation**
+
+**User confirms: "Yes, close it"**
+
+**Output (after confirmation)**:
+```
+🎯 Closing increment with your approval...
+  ✓ Status: ready_for_review → completed
+  ✓ Set approvedAt: 2025-10-28
   ✓ Completion report generated
   ✓ WIP freed (1/2 → 0/2)
 
@@ -427,11 +484,6 @@ Running quality assessment...
 
 Overall Score: 87/100 (GOOD) ✓
 
-Dimension Scores:
-  Clarity:         92/100 ✓✓
-  Testability:     85/100 ✓
-  Risk Assessment: 75/100 ✓
-
 Quality Gate Decision: ✅ PASS
 
 📋 Report: .specweave/increments/0001-user-authentication/reports/qa-post-closure.md

package/plugins/specweave/hooks/hooks.json

@@ -10,6 +10,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "matcher_content": "metadata\\.json.*completed",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/completion-guard.sh"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write",

package/plugins/specweave/hooks/v2/detectors/lifecycle-detector.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# lifecycle-detector.sh - Detect increment lifecycle changes
+# Events: increment.created, increment.done, increment.archived, increment.reopened
+#
+# Called from post-tool-use.sh when metadata.json is edited
+# Compares current vs previous status to detect transitions
+#
+# IMPORTANT: This script must be fast (<10ms) and never crash
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+INC_ID="${1:-}"
+[[ -z "$INC_ID" ]] && exit 0
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+[[ ! -d "$PROJECT_ROOT/.specweave" ]] && exit 0
+
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+PREV_STATUS_FILE="$STATE_DIR/.prev-status-$INC_ID"
+META_FILE="$PROJECT_ROOT/.specweave/increments/$INC_ID/metadata.json"
+ARCHIVE_META="$PROJECT_ROOT/.specweave/increments/_archive/$INC_ID/metadata.json"
+
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+# Detect event
+EVENT=""
+EVENT_DATA="$INC_ID"
+
+# Check if archived (folder moved to _archive/)
+if [[ -f "$ARCHIVE_META" ]] && [[ ! -f "$META_FILE" ]]; then
+  # Check if we already detected this
+  PREV=$(cat "$PREV_STATUS_FILE" 2>/dev/null || echo "")
+  if [[ "$PREV" != "archived" ]]; then
+    EVENT="increment.archived"
+    echo "archived" > "$PREV_STATUS_FILE"
+  fi
+
+elif [[ -f "$META_FILE" ]]; then
+  # Get current status (fast grep, no jq)
+  CURRENT_STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$META_FILE" | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+  [[ -z "$CURRENT_STATUS" ]] && exit 0
+
+  # Get previous status
+  PREV_STATUS=$(cat "$PREV_STATUS_FILE" 2>/dev/null || echo "")
+
+  # Detect transitions
+  if [[ -z "$PREV_STATUS" ]]; then
+    # First time seeing this increment
+    if [[ "$CURRENT_STATUS" == "planning" ]] || [[ "$CURRENT_STATUS" == "active" ]]; then
+      EVENT="increment.created"
+    fi
+  elif [[ "$PREV_STATUS" != "$CURRENT_STATUS" ]]; then
+    # Status changed
+    case "$CURRENT_STATUS" in
+      completed)
+        EVENT="increment.done"
+        ;;
+      active)
+        # Was it completed before? That's a reopen
+        if [[ "$PREV_STATUS" == "completed" ]]; then
+          EVENT="increment.reopened"
+        fi
+        ;;
+      paused|abandoned)
+        # Status changes we don't emit events for
+        ;;
+    esac
+  fi
+
+  # Save current status
+  echo "$CURRENT_STATUS" > "$PREV_STATUS_FILE"
+fi
+
+# Fire event if detected
+if [[ -n "$EVENT" ]]; then
+  HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+  bash "$HOOK_DIR/queue/enqueue.sh" "$EVENT" "$EVENT_DATA" 2>/dev/null
+fi
+
+exit 0

package/plugins/specweave/hooks/v2/detectors/us-completion-detector.sh

@@ -0,0 +1,148 @@
+#!/bin/bash
+# us-completion-detector.sh - Detect user story completion
+# Events: user-story.completed, user-story.reopened
+#
+# A user story is complete when:
+# 1. ALL tasks for that US are completed ([x])
+# 2. ALL ACs for that US are checked ([x])
+#
+# Called from post-tool-use.sh when tasks.md or spec.md is edited
+#
+# IMPORTANT: This script must be fast (<50ms) and never crash
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+INC_ID="${1:-}"
+[[ -z "$INC_ID" ]] && exit 0
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+[[ ! -d "$PROJECT_ROOT/.specweave" ]] && exit 0
+
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+TASKS_FILE="$PROJECT_ROOT/.specweave/increments/$INC_ID/tasks.md"
+SPEC_FILE="$PROJECT_ROOT/.specweave/increments/$INC_ID/spec.md"
+US_STATE_FILE="$STATE_DIR/.us-completion-$INC_ID"
+
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+[[ ! -f "$TASKS_FILE" ]] && exit 0
+[[ ! -f "$SPEC_FILE" ]] && exit 0
+
+# Parse tasks.md to find US -> Tasks mapping and completion status
+# Format: ### T-001: Title
+#         **Satisfies ACs**: AC-US1-01, AC-US1-02
+#         **Status**: [x] completed
+
+declare -A US_TASKS_TOTAL
+declare -A US_TASKS_DONE
+
+# Parse task blocks
+CURRENT_TASK=""
+CURRENT_STATUS=""
+CURRENT_US=""
+
+while IFS= read -r line; do
+  # Detect task header
+  if [[ "$line" =~ ^###[[:space:]]+T-[0-9]+ ]]; then
+    # Process previous task
+    if [[ -n "$CURRENT_US" ]] && [[ -n "$CURRENT_TASK" ]]; then
+      US_TASKS_TOTAL["$CURRENT_US"]=$((${US_TASKS_TOTAL["$CURRENT_US"]:-0} + 1))
+      if [[ "$CURRENT_STATUS" == "done" ]]; then
+        US_TASKS_DONE["$CURRENT_US"]=$((${US_TASKS_DONE["$CURRENT_US"]:-0} + 1))
+      fi
+    fi
+    CURRENT_TASK=$(echo "$line" | grep -o 'T-[0-9][0-9][0-9]' | head -1)
+    CURRENT_STATUS=""
+    CURRENT_US=""
+  fi
+
+  # Detect User Story reference
+  if [[ "$line" =~ User[[:space:]]*Story.*:.*US-[0-9]+ ]]; then
+    CURRENT_US=$(echo "$line" | grep -o 'US-[0-9][0-9][0-9]' | head -1)
+  fi
+
+  # Detect completion status
+  if [[ "$line" =~ Status.*\[x\] ]]; then
+    CURRENT_STATUS="done"
+  fi
+done < "$TASKS_FILE"
+
+# Process last task
+if [[ -n "$CURRENT_US" ]] && [[ -n "$CURRENT_TASK" ]]; then
+  US_TASKS_TOTAL["$CURRENT_US"]=$((${US_TASKS_TOTAL["$CURRENT_US"]:-0} + 1))
+  if [[ "$CURRENT_STATUS" == "done" ]]; then
+    US_TASKS_DONE["$CURRENT_US"]=$((${US_TASKS_DONE["$CURRENT_US"]:-0} + 1))
+  fi
+fi
+
+# Parse spec.md for AC completion status
+# Format: - [x] **AC-US1-01**: Description
+declare -A US_ACS_TOTAL
+declare -A US_ACS_DONE
+
+while IFS= read -r line; do
+  # Find AC lines with US reference
+  if [[ "$line" =~ AC-US([0-9]+)-[0-9]+ ]]; then
+    US_NUM="${BASH_REMATCH[1]}"
+    US_ID="US-${US_NUM}"
+
+    US_ACS_TOTAL["$US_ID"]=$((${US_ACS_TOTAL["$US_ID"]:-0} + 1))
+
+    if [[ "$line" =~ \[x\] ]]; then
+      US_ACS_DONE["$US_ID"]=$((${US_ACS_DONE["$US_ID"]:-0} + 1))
+    fi
+  fi
+done < "$SPEC_FILE"
+
+# Load previous completion state
+declare -A PREV_COMPLETE
+if [[ -f "$US_STATE_FILE" ]]; then
+  while IFS='=' read -r us status; do
+    [[ -n "$us" ]] && PREV_COMPLETE["$us"]="$status"
+  done < "$US_STATE_FILE"
+fi
+
+# Check completion for each US
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+NEW_STATE=""
+
+for US_ID in "${!US_TASKS_TOTAL[@]}"; do
+  TASKS_TOTAL=${US_TASKS_TOTAL["$US_ID"]:-0}
+  TASKS_DONE=${US_TASKS_DONE["$US_ID"]:-0}
+  ACS_TOTAL=${US_ACS_TOTAL["$US_ID"]:-0}
+  ACS_DONE=${US_ACS_DONE["$US_ID"]:-0}
+
+  # US is complete if ALL tasks done AND ALL ACs checked
+  CURRENT_COMPLETE="no"
+  if [[ $TASKS_TOTAL -gt 0 ]] && [[ $TASKS_DONE -eq $TASKS_TOTAL ]]; then
+    if [[ $ACS_TOTAL -gt 0 ]] && [[ $ACS_DONE -eq $ACS_TOTAL ]]; then
+      CURRENT_COMPLETE="yes"
+    elif [[ $ACS_TOTAL -eq 0 ]]; then
+      # No ACs defined, just check tasks
+      CURRENT_COMPLETE="yes"
+    fi
+  fi
+
+  PREV="${PREV_COMPLETE["$US_ID"]:-no}"
+
+  # Detect transitions
+  if [[ "$CURRENT_COMPLETE" == "yes" ]] && [[ "$PREV" == "no" ]]; then
+    # User story just completed
+    bash "$HOOK_DIR/queue/enqueue.sh" "user-story.completed" "$INC_ID:$US_ID" 2>/dev/null
+  elif [[ "$CURRENT_COMPLETE" == "no" ]] && [[ "$PREV" == "yes" ]]; then
+    # User story reopened
+    bash "$HOOK_DIR/queue/enqueue.sh" "user-story.reopened" "$INC_ID:$US_ID" 2>/dev/null
+  fi
+
+  NEW_STATE="${NEW_STATE}${US_ID}=${CURRENT_COMPLETE}\n"
+done
+
+# Save new state
+echo -e "$NEW_STATE" > "$US_STATE_FILE"
+
+exit 0

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

@@ -1,7 +1,20 @@
 #!/bin/bash
 # post-tool-use.sh - Single dispatcher for ALL PostToolUse events
 # Replaces: post-task-edit, post-metadata-change, post-increment-planning, etc.
-# Goal: <10ms execution, queue heavy work for async processing
+#
+# Architecture (EDA v2):
+# - Detectors run synchronously (fast, detect state transitions)
+# - Detectors emit events to queue
+# - Handlers process events asynchronously from queue
+#
+# Event flow:
+# 1. metadata.json change -> lifecycle-detector -> increment.* events
+# 2. tasks.md/spec.md change -> us-completion-detector -> user-story.* events
+# 3. Events queued -> processor routes to handlers
+#
+# Goal: <10ms execution, all heavy work through event queue
+#
+# IMPORTANT: Never crash Claude, always exit 0
 set +e
 
 [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
@@ -20,25 +33,70 @@ INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
 [[ -z "$FILE_PATH" ]] && exit 0
 
-# Detect event type based on file
-EVENT_TYPE=""
+# Extract increment ID from path
+INC_ID=$(echo "$FILE_PATH" | grep -o '[0-9][0-9][0-9][0-9]-[^/]*' | head -1)
+[[ -z "$INC_ID" ]] && exit 0
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DETECTOR_DIR="$HOOK_DIR/detectors"
+
+# ============================================================================
+# EDA DISPATCHER: Route to detectors based on file type
+# Detectors detect state transitions and emit events to queue
+# All heavy work is done by handlers processing the queue
+# ============================================================================
+
 case "$FILE_PATH" in
-  */.specweave/increments/*/tasks.md)   EVENT_TYPE="task.updated" ;;
-  */.specweave/increments/*/spec.md)    EVENT_TYPE="spec.updated" ;;
-  */.specweave/increments/*/metadata.json) EVENT_TYPE="metadata.changed" ;;
-  */.specweave/increments/*/plan.md)    EVENT_TYPE="plan.updated" ;;
-  *) exit 0 ;;  # Not a specweave file, ignore
+  */.specweave/increments/*/metadata.json)
+    # Metadata changed -> check for lifecycle transitions
+    # Events: increment.created, increment.done, increment.archived, increment.reopened
+    bash "$DETECTOR_DIR/lifecycle-detector.sh" "$INC_ID" 2>/dev/null &
+    ;;
+
+  */.specweave/increments/*/tasks.md|*/.specweave/increments/*/spec.md)
+    # Tasks or spec changed -> check for US completion
+    # Events: user-story.completed, user-story.reopened
+    bash "$DETECTOR_DIR/us-completion-detector.sh" "$INC_ID" 2>/dev/null &
+
+    # Also queue legacy event for backward compatibility
+    if [[ "$FILE_PATH" == *tasks.md ]]; then
+      bash "$HOOK_DIR/queue/enqueue.sh" "task.updated" "$INC_ID" 2>/dev/null &
+    else
+      bash "$HOOK_DIR/queue/enqueue.sh" "spec.updated" "$INC_ID" 2>/dev/null &
+    fi
+    ;;
+
+  */.specweave/increments/*/plan.md)
+    # Plan updated (for future use, currently no special handling)
+    bash "$HOOK_DIR/queue/enqueue.sh" "plan.updated" "$INC_ID" 2>/dev/null &
+    ;;
+
+  *)
+    # Not a specweave increment file, ignore
+    exit 0
+    ;;
 esac
 
-# Extract increment ID
-INC_ID=$(echo "$FILE_PATH" | grep -o '[0-9][0-9][0-9][0-9]-[^/]*' | head -1)
+# NOTE: Removed synchronous status-update.sh call
+# Status line updates are now EVENT-DRIVEN:
+# - Updated on user-story.completed/reopened events
+# - Updated on increment lifecycle events
+# - NOT updated on every file edit (reduces flickering, race conditions)
 
-HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# Ensure processor is running to handle queued events
+# (Processor may have timed out from idle after 60s)
+PROCESSOR="$HOOK_DIR/queue/processor.sh"
+PID_FILE="$PROJECT_ROOT/.specweave/state/.processor.pid"
 
-# SYNCHRONOUS: Status update only (fast, always needed)
-bash "$HOOK_DIR/handlers/status-update.sh" "$INC_ID" 2>/dev/null &
+# Quick check: if PID file exists and process running, skip
+if [[ -f "$PID_FILE" ]]; then
+  PROC_PID=$(cat "$PID_FILE" 2>/dev/null)
+  if [[ -n "$PROC_PID" ]] && kill -0 "$PROC_PID" 2>/dev/null; then
+    exit 0  # Processor running, events will be processed
+  fi
+fi
 
-# ASYNC: Queue heavy operations for background processing
-bash "$HOOK_DIR/queue/enqueue.sh" "$EVENT_TYPE" "$INC_ID" 2>/dev/null
+# Start processor in background (non-daemon mode for quick processing)
+[[ -f "$PROCESSOR" ]] && nohup bash "$PROCESSOR" > /dev/null 2>&1 &
 
 exit 0

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

@@ -0,0 +1,81 @@
+#!/bin/bash
+# completion-guard.sh - Block direct editing of metadata.json to "completed" status
+#
+# v0.28.63+: Prevents the auto-completion bug by blocking direct status changes to completed.
+# Status MUST go through ready_for_review first, and only /specweave:done can mark completed.
+#
+# 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.
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+# Read stdin for tool input
+INPUT=$(cat)
+
+# Check if this is editing metadata.json with status: completed
+# Pattern: file_path contains metadata.json AND (new_string OR content) contains "status"..."completed"
+
+# Extract file_path
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+
+# Only care about metadata.json files
+if [[ "$FILE_PATH" != *metadata.json ]]; then
+  exit 0  # Allow
+fi
+
+# Extract the content being written (new_string for Edit, content for Write)
+NEW_CONTENT=$(echo "$INPUT" | grep -o '"new_string"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+if [[ -z "$NEW_CONTENT" ]]; then
+  NEW_CONTENT=$(echo "$INPUT" | grep -o '"content"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+fi
+
+# Check if trying to set status to "completed" directly
+# This is a simple pattern match - if the edit/write contains status...completed
+if echo "$NEW_CONTENT" | grep -q '"status"[[:space:]]*:[[:space:]]*"completed"'; then
+  # Read current status from file to check if coming from ready_for_review
+  if [[ -f "$FILE_PATH" ]]; then
+    CURRENT_STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$FILE_PATH" | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+
+    if [[ "$CURRENT_STATUS" == "ready_for_review" ]]; then
+      # This is a valid transition - allow
+      exit 0
+    fi
+  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
+
+  exit 2  # Block the tool call
+fi
+
+# Allow other edits to metadata.json
+exit 0

package/plugins/specweave/hooks/v2/handlers/ac-validation-handler.sh

@@ -2,8 +2,12 @@
 # ac-validation-handler.sh - Validate AC completion status
 # Checks that completed tasks have their ACs checked in spec.md
 # Non-blocking, logs warnings only
+#
+# IMPORTANT: Never crash Claude, always exit 0
 set +e
 
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
 INC_ID="${1:-}"
 [[ -z "$INC_ID" ]] && exit 0
 

package/plugins/specweave/hooks/v2/handlers/github-sync-handler.sh

@@ -1,8 +1,12 @@
 #!/bin/bash
 # github-sync-handler.sh - Sync increment status to GitHub issue
 # Called async by processor, non-blocking, error-tolerant
+#
+# IMPORTANT: Never crash Claude, always exit 0
 set +e
 
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
 INC_ID="${1:-}"
 [[ -z "$INC_ID" ]] && exit 0
 
@@ -23,11 +27,28 @@ GITHUB_ENABLED=$(grep -o '"enabled"[[:space:]]*:[[:space:]]*true' "$CONFIG_FILE"
 # Throttle: max once per 5 minutes per increment
 THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.github-sync-$INC_ID"
 if [[ -f "$THROTTLE_FILE" ]]; then
-  AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
+  if [[ "$(uname)" == "Darwin" ]]; then
+    AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
+  else
+    AGE=$(($(date +%s) - $(stat -c %Y "$THROTTLE_FILE" 2>/dev/null || echo 0)))
+  fi
   [[ $AGE -lt 300 ]] && exit 0
 fi
 touch "$THROTTLE_FILE"
 
+# Cross-platform timeout wrapper
+run_with_timeout() {
+  local timeout_secs="$1"
+  shift
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$timeout_secs" "$@" 2>/dev/null || true
+  elif command -v gtimeout >/dev/null 2>&1; then
+    gtimeout "$timeout_secs" "$@" 2>/dev/null || true
+  else
+    "$@" 2>/dev/null || true
+  fi
+}
+
 # Load GitHub token
 GITHUB_TOKEN=""
 [[ -f "$PROJECT_ROOT/.env" ]] && GITHUB_TOKEN=$(grep -E "^GITHUB_TOKEN=" "$PROJECT_ROOT/.env" | cut -d'=' -f2- | tr -d '"'"'")
@@ -50,5 +71,5 @@ FEATURE_ID=""
 
 # Run sync (timeout 60s)
 cd "$PROJECT_ROOT" || exit 0
-GITHUB_TOKEN="$GITHUB_TOKEN" timeout 60 node "$SYNC_SCRIPT" "$FEATURE_ID" >/dev/null 2>&1
+GITHUB_TOKEN="$GITHUB_TOKEN" run_with_timeout 60 node "$SYNC_SCRIPT" "$FEATURE_ID" >/dev/null 2>&1
 exit 0