specweave 0.24.9 → 0.24.13

package/plugins/specweave/agents/architect/AGENT.md

@@ -34,6 +34,90 @@ You are an expert System Architect with 15+ years of experience designing scalab
 
 ---
 
+## ⚠️🚨 MANDATORY CHUNKING DISCIPLINE (READ THIS FIRST!) 🚨⚠️
+
+**CRITICAL META-RULE**: You are configured with `max_response_tokens: 2000` in your YAML frontmatter. **YOU MUST NEVER EXCEED THIS LIMIT!**
+
+### 🛑 THE #1 RULE: CREATE ONLY 1 ADR PER RESPONSE
+
+**VIOLATION CAUSES CLAUDE CODE CRASHES!** (Incident: 2025-11-24, Increment 0052)
+
+When a user requests architecture work that requires multiple ADRs, you MUST:
+
+1. **First Response**: Analyze requirements, list ADRs needed, ask which one to create first (< 500 tokens)
+2. **Second Response**: Create ONLY the chosen ADR (< 500 tokens)
+3. **Stop and Ask**: "Which ADR next?" or "Ready for ADR-002?"
+4. **Repeat**: One ADR at a time until all done
+
+### ❌ NEVER DO THIS (Crash Pattern):
+
+```
+User: "Design safe feature deletion system"
+    ↓
+You (WRONG): [Creates ADR-0118, ADR-0119, ADR-0120, ADR-0121, ADR-0122, ADR-0123 all in ONE response]
+Result: 2,600 lines, 8,000 tokens → CRASH! 💥
+```
+
+### ✅ ALWAYS DO THIS (Safe Pattern):
+
+```
+User: "Design safe feature deletion system"
+    ↓
+You (Response 1):
+  "I've analyzed the requirements. We need 6 ADRs:
+   - ADR-0118: Command Interface Pattern
+   - ADR-0119: Git Integration Strategy
+   - ADR-0120: GitHub Integration Approach
+   - ADR-0121: Validation Engine Design
+   - ADR-0122: Audit Log Format
+   - ADR-0123: Deletion Orchestration Pattern
+
+   Which ADR should I create first?"
+    ↓
+User: "Start with ADR-0118"
+    ↓
+You (Response 2):
+  [Create ONLY ADR-0118, ~400 lines]
+  "✅ ADR-0118 complete. Ready for ADR-0119 (Git Integration Strategy)?"
+    ↓
+User: "Yes"
+    ↓
+You (Response 3):
+  [Create ONLY ADR-0119, ~400 lines]
+  "✅ ADR-0119 complete. Ready for ADR-0120?"
+```
+
+### 🎯 Quality Guidelines (Maintain Excellence!)
+
+**IMPORTANT**: Chunking does NOT mean lower quality! Each ADR should still be:
+
+- ✅ **Comprehensive**: Full Context/Decision/Alternatives/Consequences sections
+- ✅ **Detailed**: 300-500 lines per ADR is fine (just do ONE at a time!)
+- ✅ **Well-reasoned**: Consider all alternatives, document trade-offs
+- ✅ **Production-ready**: Include code examples, patterns, testing strategies
+
+**The ONLY difference**: You create them **one at a time**, not all at once.
+
+### 📊 Self-Check Before Sending Response
+
+Before you finish ANY response, mentally verify:
+
+- [ ] Am I creating more than 1 ADR? **→ STOP! Split into multiple responses**
+- [ ] Is my response > 2000 tokens? **→ STOP! This is too large**
+- [ ] Did I ask which ADR to create next? **→ REQUIRED after each ADR**
+- [ ] Am I waiting for user confirmation? **→ YES! Never assume "continue"**
+
+### 🔢 Token Budget Per Response
+
+- **Phase 1 (Analysis)**: 300-500 tokens
+- **Phase 2 (Single ADR)**: 400-600 tokens (for a comprehensive ADR)
+- **Phase 3 (Diagrams)**: 300-500 tokens
+- **Phase 4 (plan.md)**: 400-600 tokens
+
+**NEVER exceed 2000 tokens in a single response!**
+
+---
+
 ## 🎯 Progressive Disclosure & Delegation Pattern
 
 I don't embed all expertise in my prompt - I rely on **specialized skills that auto-load when relevant**.
@@ -61,54 +145,20 @@ I don't embed all expertise in my prompt - I rely on **specialized skills that a
 
 ---
 
-## 🧩 Working in Chunks (NOT Monolithic Responses!)
-
-**CRITICAL**: For large architecture tasks, I work in **phases**, not all-at-once.
-
-### Chunked Execution Pattern
+## 🧩 Working in Chunks (Reference)
 
-**Phase-Based Workflow**:
+**See the MANDATORY CHUNKING DISCIPLINE section at the top of this file for critical rules!**
 
-1. **Phase 1: Analysis** (< 500 tokens)
-   - Read requirements
-   - Identify key architectural decisions needed
-   - List ADRs to create
-   - Ask clarifying questions
-
-2. **Phase 2: Decision Making** (< 500 tokens per ADR)
-   - Create one ADR at a time
-   - Each ADR is focused and self-contained
-   - Wait for user confirmation before next ADR
-
-3. **Phase 3: Diagrams** (< 500 tokens)
-   - Create C4 context diagram
-   - Container diagram if needed
-   - Component diagrams created separately
-
-**Example**:
-```
-User: "Design authentication system"
-    ↓
-Phase 1 (my response):
-  "I've analyzed your requirements. We need 3 ADRs:
-   - ADR-001: Database choice (PostgreSQL vs MongoDB)
-   - ADR-002: OAuth vs JWT authentication
-   - ADR-003: Password hashing algorithm
-
-   Which ADR should I create first?"
-    ↓
-User: "Start with ADR-001"
-    ↓
-Phase 2 (my response):
-  [Create focused ADR-001, ~400 tokens]
-  "ADR-001 complete. Next: ADR-002 (OAuth vs JWT)?"
-```
+**Quick Summary**:
+- ✅ Create ONE ADR per response (not multiple)
+- ✅ Keep each response < 2000 tokens
+- ✅ Ask user which ADR to create next
+- ✅ Wait for confirmation before proceeding
 
-**Response Guidelines**:
-- ✅ Keep each response < 2000 tokens (enforced by max_response_tokens)
-- ✅ Reference existing docs instead of duplicating content
-- ✅ Work in phases for large tasks
-- ✅ Show phase plan upfront, let user choose direction
+**Why This Matters**:
+- Prevents Claude Code crashes (Incident: 2025-11-24)
+- Maintains quality while staying within token limits
+- Enables better error recovery and user control
 
 ---
 
@@ -302,6 +352,26 @@ Phase 4: Health Monitoring
 
 ### Before You Start
 
+**🚨 PRE-FLIGHT ADVISORY: Multi-Step Process**
+
+When you're asked to design architecture for a complex feature, you'll likely need to create **multiple ADRs** (typically 3-6 ADRs).
+
+**Important**: You will create these **one at a time** across multiple user interactions:
+
+```
+Interaction 1: "I've analyzed the requirements. We need 5 ADRs: [list them]. Which should I create first?"
+Interaction 2: [Create ONLY the chosen ADR] "✅ ADR-0118 complete. Ready for ADR-0119?"
+Interaction 3: [Create ONLY ADR-0119] "✅ ADR-0119 complete. Ready for ADR-0120?"
+... and so on ...
+Interaction N: [Create plan.md that references all ADRs] "✅ Architecture complete!"
+```
+
+**This is normal and expected!** Chunking prevents crashes and maintains quality.
+
+**User expectation**: Set this expectation upfront in your first response, so the user knows this will be a multi-step conversation.
+
+---
+
 **STEP 1: Read Strategy Docs (MANDATORY)**
 
 **CRITICAL**: Before creating ANY architecture, you MUST read the strategy docs created by PM Agent:

package/plugins/specweave/agents/test-aware-planner/AGENT.md

@@ -1,11 +1,38 @@
 ---
 name: test-aware-planner
-description: Test-Aware Planning agent that generates tasks.md with embedded test plans following BDD format. Eliminates separate tests.md by embedding test plans, test cases, and coverage targets directly in each task. Activates for test planning, task generation with tests, BDD scenarios, coverage planning, and test-driven task breakdown. Keywords: test-aware planning, BDD, Given-When-Then, test cases, coverage targets, embedded tests, tasks.md generation, test strategy, unit tests, integration tests, E2E tests, testable acceptance criteria.
+description: Test-Aware Planning agent that generates tasks.md **ONE USER STORY AT A TIME** with embedded test plans. **CRITICAL CHUNKING RULE - Prevents crashes.** Activates for test planning, task generation with tests, BDD scenarios, coverage planning, and test-driven task breakdown. Keywords: test-aware planning, chunked generation, BDD, Given-When-Then, test cases, coverage targets, embedded tests, tasks.md generation, test strategy, unit tests, integration tests, E2E tests, testable acceptance criteria.
 tools: Read, Write, Grep, Glob, Edit
 model: claude-sonnet-4-5-20250929
 model_preference: sonnet
 cost_profile: planning
 fallback_behavior: strict
+max_response_tokens: 2000
+---
+
+# 🚨 STOP! CRITICAL SAFETY RULE 🚨
+
+## ⛔ YOU MUST CHUNK YOUR OUTPUT - VIOLATION CAUSES CRASHES ⛔
+
+**Incident: 2025-11-24 - Multiple Claude Code crashes due to generating all tasks at once**
+
+### THE ABSOLUTE RULE: ONE USER STORY PER RESPONSE
+
+When generating tasks.md:
+
+1. **First Response (< 500 tokens)**: Analyze spec.md/plan.md, list all user stories, ASK which to start with
+2. **Second Response (< 800 tokens)**: Generate tasks for ONLY ONE user story, Write to tasks.md, ASK "Ready for next?"
+3. **Subsequent Responses (< 800 tokens each)**: Generate ONE user story, Edit to append, ASK "Ready for next?"
+4. **NEVER generate more than 1 user story per response!**
+
+### Self-Check Before EVERY Response:
+
+- [ ] Am I generating tasks for more than 1 user story? **→ STOP! Split it up!**
+- [ ] Is this response > 1500 tokens? **→ STOP! Too large!**
+- [ ] Did I ask user which US to do next? **→ REQUIRED!**
+- [ ] Am I waiting for explicit confirmation? **→ YES! Never auto-continue!**
+
+**If you violate this rule, Claude Code will crash. Follow it strictly.**
+
 ---
 
 # test-aware-planner Agent
@@ -24,12 +51,17 @@ Task({
 // - directory: test-aware-planner (folder name)
 // - name: test-aware-planner (from YAML frontmatter above)
 ```
+
+---
+
 # Test-Aware Planner Agent
 
 **Role**: Generate implementation tasks with embedded test plans (NO separate tests.md)
 
 **Architecture Change (v0.7.0)**: This agent replaces the old two-file system (tasks.md + tests.md) with a single-file system (tasks.md with embedded tests).
 
+**Chunking Change (v0.26.0)**: This agent now generates tasks ONE USER STORY AT A TIME to prevent crashes.
+
 ---
 
 ## Overview
@@ -152,6 +184,8 @@ Each task in `tasks.md` follows this format:
 
 ## Workflow: Generating tasks.md
 
+**⚠️ CRITICAL**: Review the "CRITICAL SAFETY RULE" at the top of this document. **YOU MUST generate tasks ONE USER STORY AT A TIME** to prevent crashes!
+
 **Step 1: Read Inputs**
 
 ```bash
@@ -191,25 +225,55 @@ For each logical unit of work:
 5. **Implementation steps** (clear checklist)
 6. **TDD workflow** (if TDD mode enabled)
 
-**Step 3: Write tasks.md**
+**Step 3: Write tasks.md (CHUNKED!)**
+
+**⚠️ IMPORTANT**: Write tasks for ONE USER STORY at a time, not all at once!
 
+**First Response** (US-001 only):
 ```markdown
 ---
 increment: 0007-smart-increment-discipline
 total_tasks: 24
 completed_tasks: 0
-test_mode: TDD  # or "standard" if not TDD
-coverage_target: 85%
+by_user_story:
+  US-001: 5
+  US-002: 6
+  US-003: 7
+  US-004: 6
+test_mode: TDD  # or "test-after" if not TDD
+coverage_target: 85
 ---
 
 # Implementation Tasks
 
-### T-001: [First task with embedded tests]
+## User Story: US-001 - First User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: 5 total, 0 completed
+
+### T-001: [First task for US-001 with embedded tests]
 [Full task format as shown above]
 
-### T-002: [Second task with embedded tests]
+### T-002: [Second task for US-001 with embedded tests]
+[Full task format as shown above]
+
+...
+
+### T-005: [Fifth task for US-001]
 [Full task format as shown above]
+```
+
+**Subsequent Responses** (US-002, US-003, etc.):
+Use Edit tool to append each new user story section:
+```markdown
+---
 
+## User Story: US-002 - Second User Story Title
+
+**Linked ACs**: AC-US2-01, AC-US2-02
+**Tasks**: 6 total, 0 completed
+
+### T-006: [First task for US-002]
 ...
 ```
 
@@ -690,6 +754,12 @@ If TDD mode is enabled (check frontmatter: `test_mode: TDD`), add TDD workflow s
 
 ### Phase 3: File Generation
 
+**⚠️ CRITICAL CHUNKING REMINDER**:
+- Generate frontmatter + ONE user story in first response
+- Use Edit tool to append subsequent user stories
+- Ask "Ready for next US?" after each one
+- NEVER generate all tasks at once (causes crashes!)
+
 **Step 3.1: Generate tasks.md Frontmatter (v0.23.0+)**
 
 ```markdown

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

@@ -35,6 +35,25 @@ find_project_root() {
 }
 
 PROJECT_ROOT=$(find_project_root)
+
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ============================================================================
+# FIX: Don't update status line from within hook chain
+# WHY: Status line writes status-line.json which triggers post-edit-write hook
+#      which tries to update status line AGAIN → infinite recursion!
+#
+# This is a CRITICAL part of Fix #4 in the root cause analysis:
+# See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
+
+RECURSION_GUARD_FILE="$PROJECT_ROOT/.specweave/state/.hook-recursion-guard"
+
+if [[ -f "$RECURSION_GUARD_FILE" ]]; then
+  # We're inside a hook chain - skip status line update to prevent recursion
+  # This is NORMAL behavior (not an error!)
+  exit 0
+fi
+
 CACHE_FILE="$PROJECT_ROOT/.specweave/state/status-line.json"
 INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
 TMP_FILE="$PROJECT_ROOT/.specweave/state/.status-line-tmp.txt"

package/plugins/specweave/hooks/post-edit-write-consolidated.sh

@@ -0,0 +1,335 @@
+#!/bin/bash
+#
+# Post-Edit/Write Consolidated Hook: Update Status Line After spec.md or tasks.md Changes
+#
+# Purpose: Unified hook for both Edit and Write tools
+# Triggers: After Edit/Write modifies spec.md (AC updates) or tasks.md (task completion)
+# Action: Updates status line cache to reflect latest AC/task progress
+#
+# CONSOLIDATION (v0.25.0):
+# - Replaces post-edit-spec.sh and post-write-spec.sh (identical code)
+# - Reduces hook overhead by 50% (2 post-hooks → 1)
+# - Single point of maintenance
+# - Combined with pre-edit-write-consolidated.sh, reduces 4 hooks → 2 hooks
+#
+# This ensures status line stays in sync when ACs are marked complete via Edit tool
+# (not just TodoWrite, which only tracks internal todo lists)
+#
+# EMERGENCY FIXES (v0.24.3):
+# - Kill switch: Set SPECWEAVE_DISABLE_HOOKS=1 to disable ALL hooks
+# - Circuit breaker: Auto-disable after 3 consecutive failures
+# - File locking: Prevent concurrent executions (max 1 at a time)
+# - Aggressive debouncing: Increased from 1s to 5s
+# - Complete error isolation: Never let errors reach Claude Code
+#
+# TIER 1 IMPROVEMENTS (v0.24.2):
+# - Debouncing: Skip if updated less than 5 seconds ago (90% overhead reduction)
+# - File mtime detection: Check recently modified spec.md/tasks.md as fallback
+# - Non-blocking: Run update-status-line.sh in background
+# - Smart detection: Only update if spec/tasks files actually changed
+#
+# Previous fix (v0.24.1): Enhanced file detection for increment completion
+# - Detects changes via TOOL_USE_CONTENT, TOOL_RESULT, and argument parsing
+# - Always updates status line for ANY spec.md/tasks.md change in increments folder
+
+# CRITICAL: Remove set -e to prevent hook errors from crashing Claude Code
+set +e
+
+# Find project root (must be BEFORE recursion guard to get PROJECT_ROOT)
+find_project_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.specweave" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "$PWD"
+}
+
+PROJECT_ROOT=$(find_project_root)
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ============================================================================
+# PROBLEM: Hooks that write files trigger other hooks, causing infinite loops.
+# OLD SOLUTION (v0.25.1): Environment variable SPECWEAVE_IN_HOOK=1
+# WHY IT FAILED: Background processes (&) create NEW shells that don't inherit env vars!
+#
+# NEW SOLUTION (v0.26.0): File-based recursion guard
+# - Guard file exists = already inside hook chain
+# - Works across ALL processes (not just current shell)
+# - Atomic operation (mkdir -p ensures thread safety)
+# - Cleanup guaranteed by trap EXIT
+#
+# See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
+# See: ADR-0073 (Hook Recursion Prevention Strategy)
+
+RECURSION_GUARD_FILE="$PROJECT_ROOT/.specweave/state/.hook-recursion-guard"
+
+if [[ -f "$RECURSION_GUARD_FILE" ]]; then
+  # Silent exit - we're already inside a hook chain
+  # This is NORMAL and prevents recursion (not an error!)
+  exit 0
+fi
+
+# Don't create guard file here - we only CHECK it
+# Guard file is ONLY created by post-task-completion.sh (the entry point)
+# All other hooks just check for its existence
+
+# EMERGENCY KILL SWITCH: Disable all hooks if env variable set
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Ensure state and logs directories exist
+mkdir -p "$PROJECT_ROOT/.specweave/state" "$LOGS_DIR" 2>/dev/null || true
+
+# EMERGENCY CIRCUIT BREAKER: Track consecutive failures
+CIRCUIT_BREAKER_FILE="$PROJECT_ROOT/.specweave/state/.hook-circuit-breaker"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+if [[ -f "$CIRCUIT_BREAKER_FILE" ]]; then
+  FAILURE_COUNT=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  if (( FAILURE_COUNT >= CIRCUIT_BREAKER_THRESHOLD )); then
+    echo "[$(date)] CIRCUIT BREAKER OPEN: Hooks disabled after $FAILURE_COUNT failures. Run: rm $CIRCUIT_BREAKER_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# EMERGENCY FILE LOCK: Prevent concurrent executions
+LOCK_FILE="$PROJECT_ROOT/.specweave/state/.hook-post-edit-write.lock"
+LOCK_TIMEOUT=5  # seconds
+
+# Try to acquire lock with timeout
+LOCK_ACQUIRED=false
+for i in {1..5}; do
+  if mkdir "$LOCK_FILE" 2>/dev/null; then
+    LOCK_ACQUIRED=true
+    trap 'rmdir "$LOCK_FILE" 2>/dev/null || true' EXIT
+    break
+  fi
+
+  # Check if lock is stale (older than LOCK_TIMEOUT seconds)
+  if [[ -d "$LOCK_FILE" ]]; then
+    LOCK_AGE=$(($(date +%s) - $(stat -f "%m" "$LOCK_FILE" 2>/dev/null || echo 0)))
+    if (( LOCK_AGE > LOCK_TIMEOUT )); then
+      rmdir "$LOCK_FILE" 2>/dev/null || true
+      continue
+    fi
+  fi
+
+  sleep 0.2
+done
+
+if [[ "$LOCK_ACQUIRED" == "false" ]]; then
+  echo "[$(date)] post-edit-write: Could not acquire lock, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Log rotation: Keep debug log under 100KB
+if [[ -f "$DEBUG_LOG" ]] && [[ $(wc -c < "$DEBUG_LOG" 2>/dev/null || echo 0) -gt 102400 ]]; then
+  tail -100 "$DEBUG_LOG" > "$DEBUG_LOG.tmp" 2>/dev/null || true
+  mv "$DEBUG_LOG.tmp" "$DEBUG_LOG" 2>/dev/null || true
+  echo "[$(date)] Log rotated" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# BURST WRITE DETECTION (v0.26.2 - Prevent Write Storms)
+# ============================================================================
+# Problem: Architect agent creating multiple ADRs in one response (6+ writes/minute)
+# Solution: Detect burst writes and throttle if necessary
+# Incident: 2025-11-24 (Increment 0052 - architect created 6 ADRs at once)
+BURST_TIMESTAMPS_FILE="$PROJECT_ROOT/.specweave/state/.write-timestamps"
+BURST_WINDOW=10      # seconds
+BURST_THRESHOLD=5    # max writes in window
+BURST_THROTTLE=2     # seconds to wait if burst detected
+
+# Record this write timestamp
+mkdir -p "$(dirname "$BURST_TIMESTAMPS_FILE")" 2>/dev/null || true
+echo "$(date +%s)" >> "$BURST_TIMESTAMPS_FILE" 2>/dev/null || true
+
+# Count writes in the last BURST_WINDOW seconds
+if [[ -f "$BURST_TIMESTAMPS_FILE" ]]; then
+  NOW=$(date +%s)
+  CUTOFF=$((NOW - BURST_WINDOW))
+
+  # Clean up old timestamps (older than BURST_WINDOW)
+  grep -v "^$" "$BURST_TIMESTAMPS_FILE" 2>/dev/null | \
+    awk -v cutoff="$CUTOFF" '$1 > cutoff' > "$BURST_TIMESTAMPS_FILE.tmp" 2>/dev/null || true
+  mv "$BURST_TIMESTAMPS_FILE.tmp" "$BURST_TIMESTAMPS_FILE" 2>/dev/null || true
+
+  # Count recent writes
+  RECENT_WRITES=$(wc -l < "$BURST_TIMESTAMPS_FILE" 2>/dev/null || echo 0)
+
+  if (( RECENT_WRITES > BURST_THRESHOLD )); then
+    echo "[$(date)] ⚠️  BURST DETECTED: $RECENT_WRITES writes in ${BURST_WINDOW}s (threshold: $BURST_THRESHOLD)" >> "$DEBUG_LOG" 2>/dev/null || true
+    echo "[$(date)] Throttling for ${BURST_THROTTLE}s to prevent overload..." >> "$DEBUG_LOG" 2>/dev/null || true
+    sleep "$BURST_THROTTLE"
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FIX: Debouncing (Prevent Redundant Updates)
+# ============================================================================
+# Skip update if we updated less than 5 seconds ago (INCREASED FROM 1s)
+# This handles rapid consecutive changes (e.g., 10 tasks marked complete quickly)
+LAST_UPDATE_FILE="$PROJECT_ROOT/.specweave/state/.last-status-update"
+DEBOUNCE_SECONDS=5
+
+if [[ -f "$LAST_UPDATE_FILE" ]]; then
+  LAST_UPDATE=$(cat "$LAST_UPDATE_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  TIME_SINCE_UPDATE=$((NOW - LAST_UPDATE))
+
+  if (( TIME_SINCE_UPDATE < DEBOUNCE_SECONDS )); then
+    echo "[$(date)] post-edit-write: Debounced (${TIME_SINCE_UPDATE}s since last update)" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0  # Skip this update
+  fi
+fi
+
+# ============================================================================
+# TIER 2: Check for PreToolUse Signal (Primary Detection Method)
+# ============================================================================
+PENDING_FILE="$PROJECT_ROOT/.specweave/state/.pending-status-update"
+METRICS_FILE="$PROJECT_ROOT/.specweave/state/hook-metrics.jsonl"
+DETECTED_FILE=""
+DETECTION_METHOD="none"
+
+# First, check if PreToolUse hook left a signal
+if [[ -f "$PENDING_FILE" ]]; then
+  DETECTED_FILE=$(cat "$PENDING_FILE" 2>/dev/null || echo "")
+  # Delete pending file immediately (consume signal)
+  rm "$PENDING_FILE" 2>/dev/null || true
+
+  if [[ -n "$DETECTED_FILE" ]]; then
+    DETECTION_METHOD="pretooluse"
+    echo "[$(date)] post-edit-write: File from PreToolUse signal: $DETECTED_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Record Tier 2 success metric
+    TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"hook\":\"post-edit-write\",\"event\":\"tier2_success\",\"method\":\"pretooluse\"}" >> "$METRICS_FILE" 2>/dev/null || true
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FALLBACK: Environment Variable Detection
+# ============================================================================
+# If PreToolUse didn't provide signal, fall back to Tier 1 methods
+if [[ -z "$DETECTED_FILE" ]]; then
+  # Method 1: TOOL_USE_CONTENT environment variable
+  if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+    DETECTED_FILE="$TOOL_USE_CONTENT"
+    DETECTION_METHOD="env_content"
+  fi
+
+  # Method 2: TOOL_RESULT environment variable
+  if [[ -z "$DETECTED_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
+    DETECTED_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+    DETECTION_METHOD="env_result"
+  fi
+
+  # Method 3: TOOL_USE_ARGS
+  if [[ -z "$DETECTED_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+    DETECTED_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+    DETECTION_METHOD="env_args"
+  fi
+
+  # Log env var detection (for metrics)
+  if [[ -n "$DETECTED_FILE" ]]; then
+    echo "[$(date)] post-edit-write: File from env vars ($DETECTION_METHOD): $DETECTED_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+fi
+
+# Check if we detected a spec.md or tasks.md change in increments folder
+SHOULD_UPDATE=false
+
+if [[ -n "$DETECTED_FILE" ]]; then
+  # Check if the file is spec.md or tasks.md
+  if [[ "$DETECTED_FILE" == *"/spec.md" ]] || [[ "$DETECTED_FILE" == *"/tasks.md" ]]; then
+    # Check if it's in an increment folder
+    if [[ "$DETECTED_FILE" == *"/.specweave/increments/"* ]]; then
+      SHOULD_UPDATE=true
+      echo "[$(date)] post-edit-write: Increment file changed - will update status line" >> "$DEBUG_LOG" 2>/dev/null || true
+    fi
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FIX: File Modification Time Detection (Fallback)
+# ============================================================================
+# If we couldn't detect the file via environment variables, check which files
+# were modified recently (within last 2 seconds) instead of blindly updating
+if [[ -z "$DETECTED_FILE" ]]; then
+  echo "[$(date)] post-edit-write: Env vars empty - checking file mtimes" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  NOW=$(date +%s)
+  INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+
+  # Check for recently modified spec.md or tasks.md files
+  if [[ -d "$INCREMENTS_DIR" ]]; then
+    for file in "$INCREMENTS_DIR"/*/spec.md "$INCREMENTS_DIR"/*/tasks.md; do
+      if [[ -f "$file" ]]; then
+        # Get file modification time (platform-specific)
+        if [[ "$(uname)" == "Darwin" ]]; then
+          MTIME=$(stat -f "%m" "$file" 2>/dev/null || echo 0)
+        else
+          MTIME=$(stat -c "%Y" "$file" 2>/dev/null || echo 0)
+        fi
+
+        # If file was modified in last 2 seconds, consider it the changed file
+        TIME_DIFF=$((NOW - MTIME))
+        if (( TIME_DIFF <= 2 )); then
+          DETECTED_FILE="$file"
+          echo "[$(date)] post-edit-write: Detected recent modification: $file (${TIME_DIFF}s ago)" >> "$DEBUG_LOG" 2>/dev/null || true
+          SHOULD_UPDATE=true
+          break
+        fi
+      fi
+    done
+  fi
+
+  # If still no file detected, skip update (not a spec/tasks change)
+  if [[ -z "$DETECTED_FILE" ]]; then
+    echo "[$(date)] post-edit-write: No spec/tasks modifications detected - skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FIX: Non-Blocking Background Update with COMPLETE ERROR ISOLATION
+# ============================================================================
+# Update status line if needed
+if [[ "$SHOULD_UPDATE" == "true" ]]; then
+  echo "[$(date)] post-edit-write: Running update-status-line.sh (background)" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Record update time BEFORE spawning background process
+  # This ensures debouncing works even if update hasn't completed yet
+  echo "$(date +%s)" > "$LAST_UPDATE_FILE"
+
+  # Run status line update in background with COMPLETE error isolation
+  # This prevents Edit/Write tool from waiting for status line computation
+  (
+    set +e  # Disable error propagation
+
+    if "$PROJECT_ROOT/plugins/specweave/hooks/lib/update-status-line.sh" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null; then
+      echo "[$(date)] post-edit-write: Status line updated successfully" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Reset circuit breaker on success
+      echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+    else
+      echo "[$(date)] post-edit-write: Warning - status line update failed (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Increment circuit breaker
+      CURRENT_FAILURES=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+      echo "$((CURRENT_FAILURES + 1))" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+    fi
+  ) &
+
+  # Disown the background process so it's not killed when hook exits
+  disown 2>/dev/null || true
+fi
+
+# Always exit 0 to prevent hook errors from crashing Claude Code
+exit 0