specweave 0.28.59 → 0.28.62

package/plugins/specweave/hooks/v2/handlers/living-specs-handler.sh

@@ -0,0 +1,179 @@
+#!/bin/bash
+# living-specs-handler.sh - Update living SPECS on lifecycle events
+# Events: increment.created, increment.done, increment.archived, increment.reopened
+#
+# This handler updates the specs/ folder structure when increment lifecycle changes.
+# It is called by the event processor, NOT directly by post-tool-use.
+#
+# IMPORTANT: This script must be fast (<100ms) and never crash Claude
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+EVENT="${1:-}"
+INC_ID="${2:-}"
+
+[[ -z "$EVENT" ]] && exit 0
+[[ -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
+
+# Throttle: max once per 60 seconds per increment
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+THROTTLE_FILE="$STATE_DIR/.living-specs-$INC_ID"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+if [[ -f "$THROTTLE_FILE" ]]; then
+  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 60 ]] && exit 0
+fi
+touch "$THROTTLE_FILE"
+
+# Find the sync script
+SYNC_SCRIPT=""
+for path in \
+  "$PROJECT_ROOT/plugins/specweave/lib/hooks/sync-living-docs.js" \
+  "$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/sync-living-docs.js" \
+  "${CLAUDE_PLUGIN_ROOT:-}/lib/hooks/sync-living-docs.js"; do
+  [[ -f "$path" ]] && { SYNC_SCRIPT="$path"; break; }
+done
+
+# Log event (silent, async)
+LOG_FILE="$PROJECT_ROOT/.specweave/logs/hooks.log"
+mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] living-specs-handler: $EVENT $INC_ID" >> "$LOG_FILE" 2>/dev/null
+
+# Get increment paths
+INC_DIR="$PROJECT_ROOT/.specweave/increments/$INC_ID"
+ARCHIVE_DIR="$PROJECT_ROOT/.specweave/increments/_archive/$INC_ID"
+SPEC_FILE="$INC_DIR/spec.md"
+ARCHIVE_SPEC="$ARCHIVE_DIR/spec.md"
+
+# Extract feature ID from spec.md (fast grep)
+get_feature_id() {
+  local spec="$1"
+  [[ -f "$spec" ]] && grep -E "^(epic|feature_id):" "$spec" 2>/dev/null | head -1 | sed 's/.*:[[:space:]]*//' | tr -d '"'"'"
+}
+
+case "$EVENT" in
+  increment.created)
+    # Create spec entry in living docs via Node.js script
+    if [[ -n "$SYNC_SCRIPT" ]] && [[ -f "$SPEC_FILE" ]]; then
+      FEATURE_ID=$(get_feature_id "$SPEC_FILE")
+      cd "$PROJECT_ROOT" || exit 0
+      if [[ -n "$FEATURE_ID" ]]; then
+        FEATURE_ID="$FEATURE_ID" timeout 30 node "$SYNC_SCRIPT" "$INC_ID" >/dev/null 2>&1 &
+      else
+        timeout 30 node "$SYNC_SCRIPT" "$INC_ID" >/dev/null 2>&1 &
+      fi
+    fi
+    ;;
+
+  increment.done)
+    # Update status to complete in living docs
+    if [[ -n "$SYNC_SCRIPT" ]] && [[ -f "$SPEC_FILE" ]]; then
+      FEATURE_ID=$(get_feature_id "$SPEC_FILE")
+      cd "$PROJECT_ROOT" || exit 0
+
+      # Mark as complete in FEATURE.md if it exists
+      if [[ -n "$FEATURE_ID" ]]; then
+        SPECS_DIR="$PROJECT_ROOT/.specweave/docs/internal/specs"
+        # Find FEATURE.md for this feature
+        FEATURE_FILE=$(find "$SPECS_DIR" -path "*/$FEATURE_ID/FEATURE.md" 2>/dev/null | head -1)
+
+        if [[ -f "$FEATURE_FILE" ]]; then
+          # Update status in FEATURE.md (in-progress -> complete)
+          sed -i.bak 's/status: in-progress/status: complete/g' "$FEATURE_FILE" 2>/dev/null
+          rm -f "${FEATURE_FILE}.bak" 2>/dev/null
+
+          # Update increment row status
+          sed -i.bak "s/\[$INC_ID\].*in-progress/[$INC_ID](..\/..\/..\/..\/increments\/$INC_ID\/spec.md) | complete/g" "$FEATURE_FILE" 2>/dev/null
+          rm -f "${FEATURE_FILE}.bak" 2>/dev/null
+        fi
+
+        # Also run full sync for completeness
+        FEATURE_ID="$FEATURE_ID" timeout 30 node "$SYNC_SCRIPT" "$INC_ID" >/dev/null 2>&1 &
+      else
+        timeout 30 node "$SYNC_SCRIPT" "$INC_ID" >/dev/null 2>&1 &
+      fi
+    fi
+    ;;
+
+  increment.archived)
+    # Move spec entry to _archive section in living docs
+    if [[ -f "$ARCHIVE_SPEC" ]]; then
+      FEATURE_ID=$(get_feature_id "$ARCHIVE_SPEC")
+
+      if [[ -n "$FEATURE_ID" ]]; then
+        SPECS_DIR="$PROJECT_ROOT/.specweave/docs/internal/specs"
+        ACTIVE_FEATURE=$(find "$SPECS_DIR" -path "*/$FEATURE_ID/FEATURE.md" -not -path "*/_archive/*" 2>/dev/null | head -1)
+        ARCHIVE_SPECS="$SPECS_DIR/specweave/_archive"
+
+        if [[ -f "$ACTIVE_FEATURE" ]]; then
+          # Check if all increments for this feature are archived
+          FEATURE_DIR=$(dirname "$ACTIVE_FEATURE")
+          ACTIVE_INC_COUNT=$(ls -1 "$FEATURE_DIR"/*.md 2>/dev/null | grep -v FEATURE.md | grep -v README.md | wc -l | tr -d ' ')
+
+          if [[ "$ACTIVE_INC_COUNT" -eq 0 ]]; then
+            # Move entire feature folder to archive
+            mkdir -p "$ARCHIVE_SPECS" 2>/dev/null
+            mv "$FEATURE_DIR" "$ARCHIVE_SPECS/" 2>/dev/null
+          else
+            # Just update status in FEATURE.md
+            sed -i.bak "s/\[$INC_ID\].*|.*$/[$INC_ID](..\/..\/..\/..\/increments\/_archive\/$INC_ID\/spec.md) | archived/g" "$ACTIVE_FEATURE" 2>/dev/null
+            rm -f "${ACTIVE_FEATURE}.bak" 2>/dev/null
+          fi
+        fi
+      fi
+    fi
+    ;;
+
+  increment.reopened)
+    # Restore from archive section in living docs
+    if [[ -f "$SPEC_FILE" ]]; then
+      FEATURE_ID=$(get_feature_id "$SPEC_FILE")
+
+      if [[ -n "$FEATURE_ID" ]]; then
+        SPECS_DIR="$PROJECT_ROOT/.specweave/docs/internal/specs"
+        ARCHIVE_FEATURE="$SPECS_DIR/specweave/_archive/$FEATURE_ID"
+        ACTIVE_SPECS="$SPECS_DIR/specweave"
+
+        # Check if feature was archived, restore it
+        if [[ -d "$ARCHIVE_FEATURE" ]]; then
+          mv "$ARCHIVE_FEATURE" "$ACTIVE_SPECS/" 2>/dev/null
+
+          # Update status back to in-progress
+          FEATURE_FILE="$ACTIVE_SPECS/$FEATURE_ID/FEATURE.md"
+          if [[ -f "$FEATURE_FILE" ]]; then
+            sed -i.bak 's/status: archived/status: in-progress/g' "$FEATURE_FILE" 2>/dev/null
+            sed -i.bak 's/status: complete/status: in-progress/g' "$FEATURE_FILE" 2>/dev/null
+            rm -f "${FEATURE_FILE}.bak" 2>/dev/null
+          fi
+        else
+          # Feature still exists, just update increment status
+          FEATURE_FILE=$(find "$SPECS_DIR" -path "*/$FEATURE_ID/FEATURE.md" -not -path "*/_archive/*" 2>/dev/null | head -1)
+          if [[ -f "$FEATURE_FILE" ]]; then
+            sed -i.bak "s/\[$INC_ID\].*archived/[$INC_ID](..\/..\/..\/..\/increments\/$INC_ID\/spec.md) | in-progress/g" "$FEATURE_FILE" 2>/dev/null
+            sed -i.bak "s/\[$INC_ID\].*complete/[$INC_ID](..\/..\/..\/..\/increments\/$INC_ID\/spec.md) | in-progress/g" "$FEATURE_FILE" 2>/dev/null
+            rm -f "${FEATURE_FILE}.bak" 2>/dev/null
+          fi
+        fi
+
+        # Run full sync to restore any missing content
+        cd "$PROJECT_ROOT" || exit 0
+        FEATURE_ID="$FEATURE_ID" timeout 30 node "$SYNC_SCRIPT" "$INC_ID" >/dev/null 2>&1 &
+      fi
+    fi
+    ;;
+esac
+
+exit 0

package/plugins/specweave/hooks/v2/handlers/status-line-handler.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# status-line-handler.sh - Event-driven status line updates
+# Events: user-story.completed, user-story.reopened, increment.done, increment.archived, increment.reopened
+#
+# This handler updates the status line ONLY when meaningful events occur:
+# - User story completed (all ACs + tasks done for that US)
+# - User story reopened (US tasks/ACs unchecked)
+# - Increment lifecycle changes (done, archived, reopened)
+#
+# It does NOT update on every task.md edit - that would cause:
+# - Race conditions (multiple rapid updates)
+# - Performance issues (too frequent writes)
+# - Status line flickering
+#
+# IMPORTANT: This script must be fast (<20ms) and never crash Claude
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+EVENT="${1:-}"
+EVENT_DATA="${2:-}"
+
+[[ -z "$EVENT" ]] && exit 0
+[[ -z "$EVENT_DATA" ]] && 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"
+CACHE_FILE="$STATE_DIR/status-line.json"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+# Log event (silent, async)
+LOG_FILE="$PROJECT_ROOT/.specweave/logs/hooks.log"
+mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] status-line-handler: $EVENT $EVENT_DATA" >> "$LOG_FILE" 2>/dev/null
+
+# Parse event data
+# Format: INC_ID:US_ID (for user-story events) or just INC_ID (for lifecycle events)
+if [[ "$EVENT_DATA" == *":"* ]]; then
+  INC_ID="${EVENT_DATA%%:*}"
+  US_ID="${EVENT_DATA##*:}"
+else
+  INC_ID="$EVENT_DATA"
+  US_ID=""
+fi
+
+# Handle events
+case "$EVENT" in
+  user-story.completed)
+    # User story completed - update status line with US progress
+    # This is the RIGHT time to update (not on every checkbox click)
+    ;;
+
+  user-story.reopened)
+    # User story reopened - update status line
+    ;;
+
+  increment.done)
+    # Increment completed - update status line to show completion
+    ;;
+
+  increment.archived)
+    # Increment archived - clear from status line, find next active
+    INC_ID=""  # Force finding a new active increment
+    ;;
+
+  increment.reopened)
+    # Increment reopened - show it as active again
+    ;;
+
+  *)
+    # Unknown event - ignore
+    exit 0
+    ;;
+esac
+
+# Find active increment if not determined or was archived
+if [[ -z "$INC_ID" ]] || [[ "$EVENT" == "increment.archived" ]]; then
+  INC_ID=""
+  for meta in "$PROJECT_ROOT/.specweave/increments"/[0-9]*/metadata.json; do
+    [[ -f "$meta" ]] || continue
+    STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$meta" | grep -o '"[^"]*"$' | tr -d '"')
+    [[ "$STATUS" == "active" || "$STATUS" == "planning" ]] && {
+      INC_ID=$(basename "$(dirname "$meta")")
+      break
+    }
+  done
+fi
+
+# If no active increment, write null status
+if [[ -z "$INC_ID" ]]; then
+  cat > "$CACHE_FILE" << 'EOF'
+{"current":null,"event":"increment.archived","ts":"__TS__"}
+EOF
+  sed -i.bak "s/__TS__/$(date +%s)/" "$CACHE_FILE" 2>/dev/null
+  rm -f "${CACHE_FILE}.bak" 2>/dev/null
+  exit 0
+fi
+
+# Get increment paths
+TASKS_FILE="$PROJECT_ROOT/.specweave/increments/$INC_ID/tasks.md"
+SPEC_FILE="$PROJECT_ROOT/.specweave/increments/$INC_ID/spec.md"
+META_FILE="$PROJECT_ROOT/.specweave/increments/$INC_ID/metadata.json"
+
+# Check files exist
+[[ ! -f "$TASKS_FILE" ]] && exit 0
+
+# Count tasks (pure bash, fast)
+TOTAL=$(grep -c "^###\? T-" "$TASKS_FILE" 2>/dev/null || echo 0)
+DONE=$(grep -c "\[x\]" "$TASKS_FILE" 2>/dev/null || echo 0)
+PCT=0; [[ $TOTAL -gt 0 ]] && PCT=$((DONE * 100 / TOTAL))
+
+# Count user stories completed
+US_TOTAL=0
+US_DONE=0
+if [[ -f "$SPEC_FILE" ]]; then
+  # Count user story headers (## US-XXX or similar)
+  US_TOTAL=$(grep -c "^##.*US-" "$SPEC_FILE" 2>/dev/null || echo 0)
+
+  # Count by checking if all ACs for each US are checked
+  # This is a simplified count - the actual detection is done by us-completion-detector.sh
+  US_STATE_FILE="$STATE_DIR/.us-completion-$INC_ID"
+  if [[ -f "$US_STATE_FILE" ]]; then
+    US_DONE=$(grep -c "=yes$" "$US_STATE_FILE" 2>/dev/null || echo 0)
+  fi
+fi
+
+# Get increment status
+INC_STATUS="active"
+if [[ -f "$META_FILE" ]]; then
+  INC_STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$META_FILE" | grep -o '"[^"]*"$' | tr -d '"')
+fi
+
+# Build detailed status JSON with event info
+TMP_FILE="$CACHE_FILE.tmp.$$"
+cat > "$TMP_FILE" << EOF
+{
+  "current": {
+    "id": "$INC_ID",
+    "completed": $DONE,
+    "total": $TOTAL,
+    "percentage": $PCT,
+    "status": "$INC_STATUS",
+    "userStories": {
+      "completed": $US_DONE,
+      "total": $US_TOTAL
+    }
+  },
+  "lastEvent": {
+    "type": "$EVENT",
+    "data": "$EVENT_DATA"
+  },
+  "ts": "$(date +%s)"
+}
+EOF
+
+# Atomic write (mv is atomic on same filesystem)
+mv "$TMP_FILE" "$CACHE_FILE" 2>/dev/null
+
+exit 0

package/plugins/specweave/hooks/v2/handlers/status-update.sh

@@ -1,8 +1,15 @@
 #!/bin/bash
 # status-update.sh - Fast status line update (synchronous)
 # Goal: <20ms execution, pure bash, no external processes
+#
+# NOTE: This is the LEGACY handler. New EDA architecture uses
+# status-line-handler.sh which is EVENT-DRIVEN.
+#
+# IMPORTANT: Never crash Claude, always exit 0
 set +e
 
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
 INC_ID="${1:-}"
 
 # Find project root

package/plugins/specweave/hooks/v2/queue/dequeue.sh

@@ -2,8 +2,12 @@
 # dequeue.sh - Get and remove next event from queue
 # Usage: dequeue.sh [--peek]
 # Returns JSON event or empty if queue is empty
+#
+# IMPORTANT: Never crash Claude, always exit 0
 set +e
 
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
 PEEK=false
 [[ "$1" == "--peek" ]] && PEEK=true
 

package/plugins/specweave/hooks/v2/queue/enqueue.sh

@@ -1,9 +1,15 @@
 #!/bin/bash
-# enqueue.sh - Add event to queue with deduplication
+# enqueue.sh - Add event to queue with deduplication and coalescing
 # Usage: enqueue.sh <event_type> <event_data>
-# Events are deduplicated by type+data hash within 5 second window
+#
+# Events are coalesced (deduplicated) by type+data hash within 10 second window.
+# Events have priorities: lifecycle=1 (highest), user-story=2, other=3 (lowest)
+#
+# IMPORTANT: This script must be fast (<5ms) and never crash
 set +e
 
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
 EVENT_TYPE="${1:-unknown}"
 EVENT_DATA="${2:-}"
 
@@ -17,25 +23,57 @@ done
 QUEUE_DIR="$PROJECT_ROOT/.specweave/state/event-queue"
 mkdir -p "$QUEUE_DIR" 2>/dev/null || exit 0
 
-# Deduplication: hash event type + data
-HASH=$(echo "${EVENT_TYPE}:${EVENT_DATA}" | md5 | cut -c1-8)
+# Assign event priority
+# Priority 1: Lifecycle events (most important)
+# Priority 2: User story events
+# Priority 3: Other events
+PRIORITY=3
+case "$EVENT_TYPE" in
+  increment.created|increment.done|increment.archived|increment.reopened)
+    PRIORITY=1
+    ;;
+  user-story.completed|user-story.reopened)
+    PRIORITY=2
+    ;;
+esac
+
+# Coalescing: hash event type + data for deduplication
+# Cross-platform md5 (works on macOS and Linux)
+if command -v md5 >/dev/null 2>&1; then
+  HASH=$(echo "${EVENT_TYPE}:${EVENT_DATA}" | md5 | cut -c1-8)
+elif command -v md5sum >/dev/null 2>&1; then
+  HASH=$(echo "${EVENT_TYPE}:${EVENT_DATA}" | md5sum | cut -c1-8)
+else
+  # Fallback: simple hash from type and data
+  HASH=$(printf "%s" "${EVENT_TYPE}:${EVENT_DATA}" | cksum | cut -d' ' -f1)
+fi
+
 DEDUP_FILE="$QUEUE_DIR/.dedup-$HASH"
-DEDUP_TTL=5
+DEDUP_TTL=10  # Increased from 5s to 10s for better coalescing
 
-# Check if duplicate (within TTL)
+# Coalescing check: skip if same event within TTL
 if [[ -f "$DEDUP_FILE" ]]; then
-  AGE=$(($(date +%s) - $(stat -f %m "$DEDUP_FILE" 2>/dev/null || echo 0)))
+  if [[ "$(uname)" == "Darwin" ]]; then
+    AGE=$(($(date +%s) - $(stat -f %m "$DEDUP_FILE" 2>/dev/null || echo 0)))
+  else
+    AGE=$(($(date +%s) - $(stat -c %Y "$DEDUP_FILE" 2>/dev/null || echo 0)))
+  fi
   [[ $AGE -lt $DEDUP_TTL ]] && exit 0
 fi
 touch "$DEDUP_FILE"
 
 # Enqueue event (atomic write)
-TIMESTAMP=$(date +%s%N)
-EVENT_FILE="$QUEUE_DIR/${TIMESTAMP}-${EVENT_TYPE}.event"
-cat > "$EVENT_FILE" << EOF
-{"type":"$EVENT_TYPE","data":"$EVENT_DATA","ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
+# Filename includes priority for priority-ordered processing
+TIMESTAMP=$(date +%s%N 2>/dev/null || date +%s)
+EVENT_FILE="$QUEUE_DIR/${PRIORITY}-${TIMESTAMP}-${EVENT_TYPE}.event"
+
+# Create event file atomically
+TMP_FILE="$EVENT_FILE.tmp.$$"
+cat > "$TMP_FILE" << EOF
+{"type":"$EVENT_TYPE","data":"$EVENT_DATA","priority":$PRIORITY,"ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date +%Y-%m-%dT%H:%M:%SZ)"}
 EOF
+mv "$TMP_FILE" "$EVENT_FILE" 2>/dev/null
 
-# Cleanup old dedup files (>30s)
+# Cleanup old dedup files (>30s) - non-blocking
 find "$QUEUE_DIR" -name ".dedup-*" -mmin +1 -delete 2>/dev/null &
 exit 0

package/plugins/specweave/hooks/v2/queue/processor.sh

@@ -1,10 +1,21 @@
 #!/bin/bash
-# processor.sh - Background event processor
-# Processes queued events asynchronously, routes to handlers
+# processor.sh - Background event processor with EDA routing
+# Processes queued events asynchronously, routes to specialized handlers
+#
 # Usage: processor.sh [--daemon]
-# Self-terminates after 30s of idle
+#
+# Event routing:
+# - increment.created/done/archived/reopened -> living-specs-handler
+# - user-story.completed/reopened -> status-line-handler
+# - task.updated/spec.updated -> living-docs-handler (legacy)
+#
+# Self-terminates after 60s of idle
+#
+# IMPORTANT: This script uses flock for safe concurrent access
 set +e
 
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
 DAEMON_MODE=false
 [[ "$1" == "--daemon" ]] && DAEMON_MODE=true
 
@@ -19,23 +30,44 @@ QUEUE_DIR="$PROJECT_ROOT/.specweave/state/event-queue"
 HANDLER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../handlers" && pwd)"
 LOG_FILE="$PROJECT_ROOT/.specweave/logs/processor.log"
 PID_FILE="$PROJECT_ROOT/.specweave/state/.processor.pid"
-IDLE_TIMEOUT=30
+LOCK_FILE="$PROJECT_ROOT/.specweave/state/.processor.lock"
+IDLE_TIMEOUT=60  # Increased from 30s to 60s
 IDLE_COUNT=0
+HANDLER_TIMEOUT=30  # Max time per handler call
 
 mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null
+mkdir -p "$QUEUE_DIR" 2>/dev/null
+
+# Acquire exclusive lock using flock
+exec 200>"$LOCK_FILE"
+if ! flock -n 200 2>/dev/null; then
+  # Another processor is running - exit silently
+  exit 0
+fi
 
-# Check if already running
+# Double-check PID file for extra safety
 if [[ -f "$PID_FILE" ]]; then
   OLD_PID=$(cat "$PID_FILE" 2>/dev/null)
-  if kill -0 "$OLD_PID" 2>/dev/null; then
+  if [[ -n "$OLD_PID" ]] && kill -0 "$OLD_PID" 2>/dev/null; then
     exit 0  # Already running
   fi
 fi
 echo $$ > "$PID_FILE"
-trap 'rm -f "$PID_FILE"' EXIT
+trap 'rm -f "$PID_FILE"; flock -u 200 2>/dev/null' EXIT
 
 log() { echo "[$(date +%H:%M:%S)] $1" >> "$LOG_FILE" 2>/dev/null; }
-log "Processor started (PID: $$)"
+log "Processor started (PID: $$, IDLE_TIMEOUT: ${IDLE_TIMEOUT}s)"
+
+# Run handler with timeout (prevents stuck handlers from blocking queue)
+run_handler() {
+  local handler="$1"
+  local event_type="$2"
+  local event_data="$3"
+
+  if [[ -x "$handler" ]]; then
+    timeout "$HANDLER_TIMEOUT" bash "$handler" "$event_type" "$event_data" 2>/dev/null || true
+  fi
+}
 
 process_event() {
   local EVENT_JSON="$1"
@@ -45,12 +77,38 @@ process_event() {
   log "Processing: $EVENT_TYPE ($EVENT_DATA)"
 
   case "$EVENT_TYPE" in
+    # ========================================
+    # EDA Event Routing (new architecture)
+    # ========================================
+
+    # Lifecycle events -> living-specs-handler
+    increment.created|increment.done|increment.archived|increment.reopened)
+      run_handler "$HANDLER_DIR/living-specs-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
+      # Also update status line on lifecycle changes
+      run_handler "$HANDLER_DIR/status-line-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
+      ;;
+
+    # User story events -> status-line-handler
+    user-story.completed|user-story.reopened)
+      run_handler "$HANDLER_DIR/status-line-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
+      ;;
+
+    # ========================================
+    # Legacy event routing (backward compat)
+    # ========================================
     task.updated|spec.updated)
-      bash "$HANDLER_DIR/living-docs-handler.sh" "$EVENT_DATA" 2>/dev/null
-      bash "$HANDLER_DIR/ac-validation-handler.sh" "$EVENT_DATA" 2>/dev/null
+      # Legacy: don't update status line on every task edit
+      # That causes race conditions and flickering
+      run_handler "$HANDLER_DIR/living-docs-handler.sh" "" "$EVENT_DATA"
+      run_handler "$HANDLER_DIR/ac-validation-handler.sh" "" "$EVENT_DATA"
       ;;
+
     metadata.changed)
-      bash "$HANDLER_DIR/github-sync-handler.sh" "$EVENT_DATA" 2>/dev/null
+      run_handler "$HANDLER_DIR/github-sync-handler.sh" "" "$EVENT_DATA"
+      ;;
+
+    *)
+      log "Unknown event type: $EVENT_TYPE"
       ;;
   esac
 }
@@ -64,9 +122,13 @@ while true; do
     process_event "$EVENT"
   else
     IDLE_COUNT=$((IDLE_COUNT + 1))
-    [[ $IDLE_COUNT -ge $IDLE_TIMEOUT ]] && { log "Idle timeout, exiting"; exit 0; }
+    if [[ $IDLE_COUNT -ge $IDLE_TIMEOUT ]]; then
+      log "Idle timeout (${IDLE_TIMEOUT}s), exiting"
+      exit 0
+    fi
     sleep 1
   fi
 
+  # In non-daemon mode, exit after 3s of idle (quick processing)
   [[ "$DAEMON_MODE" == "false" ]] && [[ $IDLE_COUNT -ge 3 ]] && exit 0
 done