specweave 0.23.10 → 0.23.14

package/plugins/specweave/hooks/pre-write-spec.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+#
+# Pre-Write Hook: Capture File Path BEFORE Write Executes (Tier 2)
+#
+# Purpose: Detect which file will be written BEFORE the Write tool runs
+# Strategy: PreToolUse has better access to tool arguments than PostToolUse
+#
+# TIER 2 COORDINATION:
+# 1. Extract file_path from TOOL_USE_ARGS (more reliable in PreToolUse)
+# 2. If it's spec.md/tasks.md in increments folder, signal PostToolUse hook
+# 3. Write file path to .pending-status-update for PostToolUse to consume
+#
+# This eliminates the need for mtime-based fallback detection (Tier 1)
+# and reduces false positives to near zero.
+#
+# Architecture:
+#   PreToolUse:Write → pre-write-spec.sh (this file)
+#     ↓ writes to
+#   .specweave/state/.pending-status-update
+#     ↓ read by
+#   PostToolUse:Write → post-write-spec.sh
+#
+# Version: v0.24.3 (EMERGENCY FIXES)
+# Date: 2025-11-22
+
+# EMERGENCY FIX: Remove set -e - it causes Claude Code crashes!
+set +e
+
+# EMERGENCY KILL SWITCH: Disable all hooks if env variable set
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Find 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)
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+PENDING_FILE="$STATE_DIR/.pending-status-update"
+METRICS_FILE="$STATE_DIR/hook-metrics.jsonl"
+
+# Ensure directories exist
+mkdir -p "$STATE_DIR" "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# TIER 2: Extract File Path from Tool Arguments
+# ============================================================================
+# PreToolUse should have access to tool arguments BEFORE execution
+# Try multiple methods to extract file_path
+
+FILE_PATH=""
+
+# Method 1: TOOL_USE_ARGS environment variable (primary for PreToolUse)
+if [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+  # Try to parse JSON with jq if available
+  if command -v jq &> /dev/null; then
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | jq -r '.file_path // empty' 2>/dev/null || echo "")
+  fi
+
+  # Fallback: Regex extraction if jq not available or failed
+  if [[ -z "$FILE_PATH" ]]; then
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+  fi
+fi
+
+# Method 2: TOOL_USE_CONTENT (fallback)
+if [[ -z "$FILE_PATH" ]] && [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+  FILE_PATH="$TOOL_USE_CONTENT"
+fi
+
+# Method 3: Parse from stdin (last resort - experimental)
+if [[ -z "$FILE_PATH" ]] && [[ ! -t 0 ]]; then
+  # Read stdin and try to extract file_path
+  STDIN_DATA=$(cat 2>/dev/null || echo "")
+  if [[ -n "$STDIN_DATA" ]] && command -v jq &> /dev/null; then
+    FILE_PATH=$(echo "$STDIN_DATA" | jq -r '.file_path // empty' 2>/dev/null || echo "")
+  fi
+fi
+
+# ============================================================================
+# TIER 2: Signal Detection and Validation
+# ============================================================================
+
+# Log what we detected (for debugging PreToolUse effectiveness)
+if [[ -n "$FILE_PATH" ]]; then
+  echo "[$(date)] pre-write-spec: Detected file_path: $FILE_PATH" >> "$DEBUG_LOG" 2>/dev/null || true
+else
+  echo "[$(date)] pre-write-spec: No file_path detected (will fall back to Tier 1)" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0  # Let PostToolUse handle it with mtime fallback
+fi
+
+# Check if this is a spec.md or tasks.md file in increments folder
+IS_SPEC_FILE=false
+if [[ "$FILE_PATH" == *"/spec.md" ]] || [[ "$FILE_PATH" == *"/tasks.md" ]]; then
+  if [[ "$FILE_PATH" == *"/.specweave/increments/"* ]]; then
+    # Exclude archived increments
+    if [[ "$FILE_PATH" != *"/_archive/"* ]]; then
+      IS_SPEC_FILE=true
+    fi
+  fi
+fi
+
+# If not a spec/tasks file, exit silently (no signal to PostToolUse)
+if [[ "$IS_SPEC_FILE" != "true" ]]; then
+  echo "[$(date)] pre-write-spec: Not a spec/tasks file - no signal" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# ============================================================================
+# TIER 2: Write Signal for PostToolUse Hook
+# ============================================================================
+
+# Write file path to pending file for PostToolUse to consume
+echo "$FILE_PATH" > "$PENDING_FILE" 2>/dev/null || true
+
+echo "[$(date)] pre-write-spec: Signaled PostToolUse for: $FILE_PATH" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# TIER 2: Metrics Collection
+# ============================================================================
+
+# Record metrics (JSONL format - one JSON object per line)
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+METRIC_ENTRY="{\"timestamp\":\"$TIMESTAMP\",\"hook\":\"pre-write-spec\",\"event\":\"file_detected\",\"file_path\":\"$FILE_PATH\",\"method\":\"TOOL_USE_ARGS\"}"
+
+# Append to metrics file (JSONL)
+echo "$METRIC_ENTRY" >> "$METRICS_FILE" 2>/dev/null || true
+
+# Log rotation for metrics (keep last 1000 entries)
+if [[ -f "$METRICS_FILE" ]]; then
+  LINE_COUNT=$(wc -l < "$METRICS_FILE" 2>/dev/null || echo 0)
+  if (( LINE_COUNT > 1000 )); then
+    tail -1000 "$METRICS_FILE" > "$METRICS_FILE.tmp" 2>/dev/null || true
+    mv "$METRICS_FILE.tmp" "$METRICS_FILE" 2>/dev/null || true
+  fi
+fi
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

package/plugins/specweave/hooks/test-pretooluse-env.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+#
+# PreToolUse Environment Variable Validation Test
+#
+# Purpose: Validate that PreToolUse hooks receive tool arguments via env vars
+# This tests the core assumption of Tier 2 implementation
+#
+# Usage:
+#   1. Register this hook in plugin.json under PreToolUse:Edit
+#   2. Make 10 test edits to any file
+#   3. Review /tmp/pretooluse-test.log
+#   4. Check if TOOL_USE_ARGS is populated
+#
+# Success Criteria:
+#   - TOOL_USE_ARGS contains file_path
+#   - At least 80% of invocations have non-empty TOOL_USE_ARGS
+#
+# If this test fails, Tier 2 PreToolUse coordination cannot work
+# and we must rely on Tier 1 (mtime fallback) or proceed to Tier 3
+#
+# Version: v0.24.2 (Tier 2 Validation)
+# Date: 2025-11-22
+
+set +e  # Don't fail on errors (this is a diagnostic tool)
+
+TEST_LOG="/tmp/pretooluse-test.log"
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Initialize log on first run
+if [[ ! -f "$TEST_LOG" ]]; then
+  echo "==================================" > "$TEST_LOG"
+  echo "PreToolUse Environment Variable Test" >> "$TEST_LOG"
+  echo "Started: $TIMESTAMP" >> "$TEST_LOG"
+  echo "==================================" >> "$TEST_LOG"
+  echo "" >> "$TEST_LOG"
+fi
+
+# Record this invocation
+echo "[$TIMESTAMP] PreToolUse:Edit invocation #$(wc -l < "$TEST_LOG")" >> "$TEST_LOG"
+
+# Check ALL tool-related environment variables
+echo "  TOOL_USE_ARGS:    ${TOOL_USE_ARGS:-<EMPTY>}" >> "$TEST_LOG"
+echo "  TOOL_USE_CONTENT: ${TOOL_USE_CONTENT:-<EMPTY>}" >> "$TEST_LOG"
+echo "  TOOL_RESULT:      ${TOOL_RESULT:-<EMPTY>}" >> "$TEST_LOG"
+echo "  PWD:              $PWD" >> "$TEST_LOG"
+
+# Try to extract file_path if TOOL_USE_ARGS exists
+if [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+  if command -v jq &> /dev/null; then
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | jq -r '.file_path // "<NOT_FOUND>"' 2>/dev/null)
+    echo "  Extracted file_path: $FILE_PATH" >> "$TEST_LOG"
+  else
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "<PARSE_FAILED>")
+    echo "  Extracted file_path (no jq): $FILE_PATH" >> "$TEST_LOG"
+  fi
+fi
+
+# Dump all TOOL* env vars
+echo "  All TOOL* environment variables:" >> "$TEST_LOG"
+env | grep -E "^TOOL" | while read line; do
+  echo "    $line" >> "$TEST_LOG"
+done
+
+echo "" >> "$TEST_LOG"
+
+# Log rotation: Keep last 100 invocations
+if [[ $(wc -l < "$TEST_LOG") -gt 500 ]]; then
+  tail -400 "$TEST_LOG" > "$TEST_LOG.tmp"
+  mv "$TEST_LOG.tmp" "$TEST_LOG"
+fi
+
+exit 0  # Always succeed (diagnostic tool)

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

@@ -0,0 +1,386 @@
+#!/bin/bash
+
+# SpecWeave UserPromptSubmit Hook
+# Fires BEFORE user's command executes (prompt-based hook)
+# Purpose: Discipline validation, context injection, command suggestions
+
+set -euo pipefail
+
+# Read input JSON from stdin
+INPUT=$(cat)
+
+# Extract prompt from JSON
+PROMPT=$(echo "$INPUT" | node -e "
+  const input = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+  console.log(input.prompt || '');
+")
+
+# ==============================================================================
+# DISCIPLINE VALIDATION: Block /specweave:increment if incomplete increments exist
+# ==============================================================================
+
+if echo "$PROMPT" | grep -q "/specweave:increment"; then
+  # Check increment discipline using check-discipline CLI command
+  # This enforces WIP limits (max 1 active, hard cap 2)
+  SPECWEAVE_DIR=".specweave"
+
+  if [[ -d "$SPECWEAVE_DIR/increments" ]]; then
+    # Run discipline check (exit code: 0=pass, 1=violations, 2=error)
+    if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/increment/metadata-manager.js" ]]; then
+      # Check active increments using MetadataManager
+      ACTIVE_COUNT=$(node -e "
+        try {
+          const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
+          const active = MetadataManager.getActive();
+          console.log(active.length);
+        } catch (e) {
+          console.error('Error checking active increments:', e.message);
+          process.exit(2);
+        }
+      " 2>/dev/null || echo "0")
+
+      # Hard cap: never >2 active
+      if [[ "$ACTIVE_COUNT" -ge 2 ]]; then
+        # Get list of active increments for error message
+        ACTIVE_LIST=$(node -e "
+          try {
+            const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
+            const active = MetadataManager.getActive();
+            active.forEach(inc => console.log('  - ' + inc.id + ' [' + inc.type + ']'));
+          } catch (e) {}
+        " 2>/dev/null || echo "")
+
+        cat <<EOF
+{
+  "decision": "block",
+  "reason": "❌ HARD CAP REACHED\n\nYou have $ACTIVE_COUNT active increments (absolute maximum: 2)\n\nActive increments:\n$ACTIVE_LIST\n\n💡 You MUST complete or pause existing work first:\n\n1️⃣  Complete an increment:\n   /specweave:done <id>\n\n2️⃣  Pause an increment:\n   /specweave:pause <id> --reason=\"...\"\n\n3️⃣  Check status:\n   /specweave:status\n\n📝 Multiple hotfixes? Combine them into ONE increment!\n   Example: 0009-security-fixes (SQL + XSS + CSRF)\n\n⛔ This limit is enforced for your productivity.\nResearch: 3+ concurrent tasks = 40% slower + more bugs"
+}
+EOF
+        exit 0
+      fi
+
+      # Soft warning: 1 active (recommended limit)
+      if [[ "$ACTIVE_COUNT" -ge 1 ]]; then
+        # Get list of active increments for warning
+        ACTIVE_LIST=$(node -e "
+          try {
+            const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
+            const active = MetadataManager.getActive();
+            active.forEach(inc => console.log('  - ' + inc.id + ' [' + inc.type + ']'));
+          } catch (e) {}
+        " 2>/dev/null || echo "")
+
+        # Just warn, don't block (user can choose to continue)
+        cat <<EOF
+{
+  "decision": "approve",
+  "systemMessage": "⚠️  WIP LIMIT REACHED\n\nYou have $ACTIVE_COUNT active increment (recommended limit: 1)\n\nActive increments:\n$ACTIVE_LIST\n\n🧠 Focus Principle: ONE active increment = maximum productivity\nStarting a 2nd increment reduces focus and velocity.\n\n💡 Consider:\n  1️⃣  Complete current work (recommended)\n  2️⃣  Pause current work (/specweave:pause)\n  3️⃣  Continue anyway (accept 20% productivity cost)\n\n⚠️  Emergency hotfix/bug? Use --type=hotfix or --type=bug to bypass this warning."
+}
+EOF
+        exit 0
+      fi
+    else
+      # Fallback: check for active/planning status manually
+      INCOMPLETE_INCREMENTS=$(find "$SPECWEAVE_DIR/increments" -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+        metadata="$increment_dir/metadata.json"
+        if [[ -f "$metadata" ]]; then
+          status=$(node -e "
+            try {
+              const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+              console.log(data.status || 'unknown');
+            } catch (e) {
+              console.log('unknown');
+            }
+          ")
+
+          if [[ "$status" == "active" || "$status" == "planning" ]]; then
+            echo "$(basename "$increment_dir")"
+          fi
+        fi
+      done)
+
+      if [[ -n "$INCOMPLETE_INCREMENTS" ]]; then
+        COUNT=$(echo "$INCOMPLETE_INCREMENTS" | wc -l | xargs)
+
+        # Get incomplete task count for migration guidance
+        MIGRATION_SCRIPT="$(dirname "${BASH_SOURCE[0]}")/lib/migrate-increment-work.sh"
+        INCOMPLETE_TASKS=""
+
+        for increment in $INCOMPLETE_INCREMENTS; do
+          if [[ -x "$MIGRATION_SCRIPT" ]]; then
+            TASK_COUNT=$("$MIGRATION_SCRIPT" count-incomplete "$increment" 2>/dev/null || echo "?")
+            INCOMPLETE_TASKS="${INCOMPLETE_TASKS}\n  - $increment ($TASK_COUNT incomplete tasks)"
+          else
+            INCOMPLETE_TASKS="${INCOMPLETE_TASKS}\n  - $increment"
+          fi
+        done
+
+        cat <<EOF
+{
+  "decision": "block",
+  "reason": "❌ Cannot create new increment! You have $COUNT incomplete increment(s):$INCOMPLETE_TASKS\n\n💡 **SMART MIGRATION OPTIONS:**\n\n1️⃣  **Transfer Work** (Recommended)\n   Move incomplete tasks to new increment:\n   \`\`\`bash\n   # After creating new increment, run:\n   bash plugins/specweave/hooks/lib/migrate-increment-work.sh transfer <old-id> <new-id>\n   \`\`\`\n   ✅ Clean closure + work continues\n\n2️⃣  **Adjust WIP Limit** (Emergency Only)\n   Temporarily allow 3 active increments:\n   \`\`\`bash\n   bash plugins/specweave/hooks/lib/migrate-increment-work.sh adjust-wip 3\n   \`\`\`\n   ⚠️  20% productivity cost, revert ASAP\n\n3️⃣  **Force-Close** (Quick Fix)\n   Mark increment as complete (work lost):\n   \`\`\`bash\n   bash plugins/specweave/hooks/lib/migrate-increment-work.sh force-close <increment-id>\n   \`\`\`\n   ⚠️  Incomplete work NOT transferred!\n\n📝 **Traditional Options:**\n  - /specweave:done <id>     # Complete properly\n  - /specweave:pause <id>    # Pause for later\n  - /specweave:abandon <id>  # Abandon if obsolete\n\nℹ️ The discipline exists for a reason:\n  ✓ Prevents scope creep\n  ✓ Ensures completions are tracked\n  ✓ Maintains living docs accuracy\n  ✓ Keeps work focused"
+}
+EOF
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# ==============================================================================
+# PRE-FLIGHT SYNC CHECK: Ensure living docs are fresh before operations
+# ==============================================================================
+
+# Detect increment operations that need fresh data
+if echo "$PROMPT" | grep -qE "/(specweave:)?(done|validate|progress|do)"; then
+  # Extract increment ID from prompt (if provided)
+  INCREMENT_ID=$(echo "$PROMPT" | grep -oE "[0-9]{4}[a-z0-9-]*" | head -1)
+
+  # If no ID in prompt, try to find active increment
+  if [[ -z "$INCREMENT_ID" ]] && [[ -d ".specweave/increments" ]]; then
+    INCREMENT_ID=$(find .specweave/increments -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+      metadata="$increment_dir/metadata.json"
+      if [[ -f "$metadata" ]]; then
+        status=$(node -e "
+          try {
+            const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+            if (data.status === 'active') {
+              console.log('$(basename "$increment_dir")');
+            }
+          } catch (e) {}
+        " 2>/dev/null)
+
+        if [[ -n "$status" ]]; then
+          echo "$status"
+          break
+        fi
+      fi
+    done)
+  fi
+
+  # If we have an increment ID, check freshness
+  if [[ -n "$INCREMENT_ID" ]]; then
+    INCREMENT_SPEC=".specweave/increments/$INCREMENT_ID/spec.md"
+    LIVING_DOCS_SPEC=".specweave/docs/internal/specs/spec-$INCREMENT_ID.md"
+
+    # Check if increment spec exists
+    if [[ -f "$INCREMENT_SPEC" ]]; then
+      # Get modification times
+      if [[ "$(uname)" == "Darwin" ]]; then
+        # macOS
+        INCREMENT_MTIME=$(stat -f %m "$INCREMENT_SPEC" 2>/dev/null || echo 0)
+        LIVING_DOCS_MTIME=$(stat -f %m "$LIVING_DOCS_SPEC" 2>/dev/null || echo 0)
+      else
+        # Linux
+        INCREMENT_MTIME=$(stat -c %Y "$INCREMENT_SPEC" 2>/dev/null || echo 0)
+        LIVING_DOCS_MTIME=$(stat -c %Y "$LIVING_DOCS_SPEC" 2>/dev/null || echo 0)
+      fi
+
+      # Check if increment is newer than living docs (or living docs doesn't exist)
+      if [[ "$INCREMENT_MTIME" -gt "$LIVING_DOCS_MTIME" ]]; then
+        # Sync needed - run sync-living-docs
+        PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+        SYNC_SCRIPT="$PLUGIN_ROOT/lib/hooks/sync-living-docs.js"
+
+        if [[ -f "$SYNC_SCRIPT" ]]; then
+          # Run sync (capture output but don't block on errors)
+          if node "$SYNC_SCRIPT" "$INCREMENT_ID" >/dev/null 2>&1; then
+            # Success - sync completed
+            :
+          else
+            # Sync failed - log but continue
+            echo "[WARNING] Pre-flight sync failed for $INCREMENT_ID" >&2
+          fi
+        fi
+      fi
+    fi
+  fi
+fi
+
+# ==============================================================================
+# SPEC SYNC CHECK: Detect spec.md changes and warn about sync needed
+# ==============================================================================
+
+# Check if spec.md was modified after plan.md (requires sync)
+if [[ -d ".specweave/increments" ]]; then
+  # Find active increment
+  ACTIVE_INCREMENT_FOR_SYNC=$(find .specweave/increments -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+    metadata="$increment_dir/metadata.json"
+    if [[ -f "$metadata" ]]; then
+      status=$(node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+          if (data.status === 'active') {
+            console.log('$(basename "$increment_dir")');
+          }
+        } catch (e) {}
+      " 2>/dev/null)
+
+      if [[ -n "$status" ]]; then
+        echo "$status"
+        break
+      fi
+    fi
+  done)
+
+  if [[ -n "$ACTIVE_INCREMENT_FOR_SYNC" ]]; then
+    # Check if SpecSyncManager detects changes
+    if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/increment/spec-sync-manager.js" ]]; then
+      SYNC_CHECK=$(node -e "
+        try {
+          const { SpecSyncManager } = require('./dist/src/core/increment/spec-sync-manager.js');
+          const manager = new SpecSyncManager(process.cwd());
+          const detection = manager.detectSpecChange('$ACTIVE_INCREMENT_FOR_SYNC');
+
+          if (detection.specChanged) {
+            const message = manager.formatSyncMessage(detection);
+            console.log(JSON.stringify({ needsSync: true, message }));
+          } else {
+            console.log(JSON.stringify({ needsSync: false }));
+          }
+        } catch (e) {
+          console.log(JSON.stringify({ needsSync: false, error: e.message }));
+        }
+      " 2>/dev/null || echo '{"needsSync":false}')
+
+      NEEDS_SYNC=$(echo "$SYNC_CHECK" | node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+          console.log(data.needsSync || false);
+        } catch (e) {
+          console.log(false);
+        }
+      ")
+
+      if [[ "$NEEDS_SYNC" == "true" ]]; then
+        SYNC_MESSAGE=$(echo "$SYNC_CHECK" | node -e "
+          try {
+            const data = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+            console.log(data.message || '');
+          } catch (e) {
+            console.log('');
+          }
+        ")
+
+        # Show sync warning (don't block, just warn)
+        cat <<EOF
+{
+  "decision": "approve",
+  "systemMessage": "$SYNC_MESSAGE"
+}
+EOF
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# ==============================================================================
+# CONTEXT INJECTION: Add current increment status
+# ==============================================================================
+
+CONTEXT=""
+
+# Find active increment
+if [[ -d ".specweave/increments" ]]; then
+  ACTIVE_INCREMENT=$(find .specweave/increments -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+    metadata="$increment_dir/metadata.json"
+    if [[ -f "$metadata" ]]; then
+      status=$(node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+          if (data.status === 'active') {
+            console.log('$(basename "$increment_dir")');
+          }
+        } catch (e) {}
+      ")
+
+      if [[ -n "$status" ]]; then
+        echo "$status"
+        break
+      fi
+    fi
+  done)
+
+  if [[ -n "$ACTIVE_INCREMENT" ]]; then
+    # Simple status: parse tasks.md for completion
+    TASKS_FILE=".specweave/increments/$ACTIVE_INCREMENT/tasks.md"
+    if [[ -f "$TASKS_FILE" ]]; then
+      # Count tasks (headers with T-NNN format - both ### and ####)
+      TOTAL_TASKS=$(grep -cE '^#{3,4}\s*T-[0-9]' "$TASKS_FILE" 2>/dev/null | tr -d '\n' || echo "0")
+      # Count completed (various formats)
+      COMPLETED_TASKS=$(grep -cE '(✅ COMPLETE|\[COMPLETED\]|\[x\] Completed)' "$TASKS_FILE" 2>/dev/null | tr -d '\n' || echo "0")
+
+      # Ensure valid numbers
+      TOTAL_TASKS=${TOTAL_TASKS:-0}
+      COMPLETED_TASKS=${COMPLETED_TASKS:-0}
+
+      if [[ "$TOTAL_TASKS" -gt 0 ]] 2>/dev/null; then
+        PERCENTAGE=$(( COMPLETED_TASKS * 100 / TOTAL_TASKS ))
+        CONTEXT="✓ Active: $ACTIVE_INCREMENT ($COMPLETED_TASKS/$TOTAL_TASKS tasks, $PERCENTAGE%)"
+      else
+        CONTEXT="✓ Active: $ACTIVE_INCREMENT"
+      fi
+    else
+      CONTEXT="✓ Active: $ACTIVE_INCREMENT"
+    fi
+  fi
+fi
+
+# ==============================================================================
+# COMMAND SUGGESTIONS: Guide users to structured workflow
+# ==============================================================================
+
+if echo "$PROMPT" | grep -qiE "(add|create|implement|build|develop)" && ! echo "$PROMPT" | grep -q "/specweave:"; then
+  if [[ -n "$CONTEXT" ]]; then
+    CONTEXT="$CONTEXT
+
+💡 TIP: Consider using SpecWeave commands for structured development:
+  - /specweave:increment \"feature name\"  # Plan new increment
+  - /specweave:do                         # Execute current tasks
+  - /specweave:progress                   # Check progress"
+  fi
+fi
+
+# ==============================================================================
+# STATUS LINE REFRESH: Ensure cache is fresh before showing context
+# ==============================================================================
+# Performance: ~50-100ms (acceptable for UX)
+# Frequency: Every user prompt (high coverage)
+# Benefit: Catches ALL edge cases (manual edits, resume, direct changes)
+#
+# Why here? This hook runs on EVERY user prompt, ensuring status line
+# is ALWAYS up-to-date before showing context to the user.
+#
+# Prevents desync scenarios:
+# - Manual spec.md edits (status: planning → active)
+# - /specweave:resume (status: paused → active)
+# - Direct metadata changes (without hook triggers)
+# - File system operations bypassing hooks
+#
+# Background execution: Runs async, doesn't block user prompt
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
+# ==============================================================================
+# OUTPUT: Approve with context or no context
+# ==============================================================================
+
+if [[ -n "$CONTEXT" ]]; then
+  cat <<EOF
+{
+  "decision": "approve",
+  "systemMessage": "$CONTEXT"
+}
+EOF
+else
+  # Just approve, no extra context
+  cat <<EOF
+{
+  "decision": "approve"
+}
+EOF
+fi
+
+exit 0