specweave 0.22.0 → 0.22.3

package/plugins/specweave/commands/specweave-sync-specs.md

@@ -1,11 +1,11 @@
 ---
 name: specweave:sync-specs
-description: Sync only specs folder to living docs - distributes increment specs into hierarchical user stories without updating architecture, operations, or other docs
+description: Sync increment specifications to living docs structure. Auto-generates feature IDs for greenfield increments (FS-XXX). Use after completing an increment to make it visible in living docs.
 ---
 
-# Sync Specs Only
+# Sync Increment Specifications to Living Docs
 
-You are executing the SpecWeave specs-only sync command. This distributes increment specs specifically into the living docs specs folder using the Universal Hierarchy (Epic → Feature → User Story → Task), without touching other documentation areas.
+Syncs increment specs to living docs structure for stakeholder visibility. Auto-generates feature IDs for greenfield increments.
 
 ---
 
@@ -85,58 +85,30 @@ fi
 
 ---
 
-## STEP 3: Execute Spec Distribution
+## STEP 3: Execute Spec Sync
 
-### 3.1 Run SpecDistributor
+### 3.1 Run Sync Command
 
-**Execute the distribution using Node.js**:
+**Execute the sync using the CLI command**:
 
-```javascript
-// Direct execution via Node.js
-node -e "
-import('./dist/src/core/living-docs/spec-distributor.js').then(async ({ SpecDistributor }) => {
-  const distributor = new SpecDistributor(process.cwd());
+```typescript
+import { syncSpecs } from './dist/src/cli/commands/sync-specs.js';
 
-  console.log('🚀 Starting spec distribution...');
-  console.log('   📄 Reading spec.md from increment ${INCREMENT_ID}');
+// Parse arguments
+const args = process.argv.slice(2); // e.g., ['0040', '--dry-run']
 
-  try {
-    const result = await distributor.distribute('${INCREMENT_ID}');
-
-    console.log('');
-    console.log('✅ Distribution successful!');
-    console.log('   📊 Total stories: ' + result.totalStories);
-    console.log('   📁 Total files created: ' + result.totalFiles);
-    console.log('   🎯 Feature ID: ' + result.specId);
-
-    if (result.epicPath) {
-      console.log('   📂 Feature path: ' + result.epicPath);
-    }
-
-    if (result.userStoryPaths && result.userStoryPaths.length > 0) {
-      console.log('   📝 User stories created:');
-      result.userStoryPaths.forEach(p => console.log('      • ' + p));
-    }
-
-    if (result.warnings && result.warnings.length > 0) {
-      console.log('');
-      console.log('⚠️  Warnings:');
-      result.warnings.forEach(w => console.log('   • ' + w));
-    }
-
-    // Update acceptance criteria status based on completed tasks
-    console.log('');
-    console.log('📊 Updating acceptance criteria status...');
-    await distributor.updateAcceptanceCriteriaStatus('${INCREMENT_ID}');
-
-  } catch (error) {
-    console.error('❌ Distribution failed:', error.message);
-    process.exit(1);
-  }
-});
-"
+// Execute sync
+await syncSpecs(args);
 ```
 
+**This will**:
+1. Auto-generate feature ID for greenfield increments (FS-040, FS-041, etc.)
+2. Parse spec.md for user stories and acceptance criteria
+3. Create living docs structure:
+   - `.specweave/docs/internal/specs/_features/FS-XXX/FEATURE.md`
+   - `.specweave/docs/internal/specs/specweave/FS-XXX/README.md`
+   - `.specweave/docs/internal/specs/specweave/FS-XXX/us-*.md`
+
 ---
 
 ## STEP 4: Report Distribution Results

package/plugins/specweave/commands/specweave-update-status.md

@@ -0,0 +1,151 @@
+---
+name: specweave:update-status
+description: Force-update status line cache with latest increment status
+---
+
+# Update Status Line
+
+**Purpose**: Force-refresh status line cache when it appears stale or after making changes.
+
+**Use When**:
+- Status line doesn't reflect recent changes
+- After completing tasks (want to see updated progress immediately)
+- After status transitions (active → completed)
+- Before checking progress with `/specweave:progress`
+- When status line shows outdated information
+
+---
+
+## How It Works
+
+1. **Scan All Increments**
+   - Reads all spec.md files in `.specweave/increments/`
+   - Identifies open increments (status = active/planning/in-progress)
+   - Extracts creation dates from YAML frontmatter
+
+2. **Select Current Increment**
+   - Sorts by creation date (oldest first)
+   - Takes first as current active increment
+   - Counts total open increments
+
+3. **Parse Task Progress**
+   - Reads tasks.md from current increment
+   - Uses TaskCounter for accurate counting (no overcounting)
+   - Calculates: completed, total, percentage
+
+4. **Update Cache**
+   - Writes `.specweave/state/status-line.json`
+   - Atomic write (temp file → rename)
+   - Runs SYNCHRONOUSLY (user waits ~50-100ms)
+
+---
+
+## Usage
+
+```bash
+# Force-update status line (no arguments)
+/specweave:update-status
+```
+
+**Output**:
+```
+✓ Status line cache updated
+```
+
+---
+
+## Example
+
+**Before Update** (stale cache):
+```
+Status Line: [0043] ████░░░░ 5/8 tasks (2 open)
+```
+
+**After Update** (fresh cache):
+```
+Status Line: [0043] ████████ 8/8 tasks (1 open) ✓
+```
+
+---
+
+## Integration with Other Commands
+
+This command is automatically called by:
+
+1. **`/specweave:progress`**
+   - Ensures status line is fresh before showing progress
+   - User always sees accurate completion percentages
+
+2. **`/specweave:done`**
+   - Refreshes status line before PM validation
+   - Ensures final progress is accurate
+
+3. **`/specweave:status`**
+   - Updates cache before showing increment list
+   - Shows current increment status
+
+---
+
+## Technical Details
+
+**Performance**: ~50-100ms (synchronous execution)
+
+**Cache Location**: `.specweave/state/status-line.json`
+
+**Cache Format**:
+```json
+{
+  "current": {
+    "id": "0043-spec-md-desync-fix",
+    "name": "0043-spec-md-desync-fix",
+    "completed": 8,
+    "total": 8,
+    "percentage": 100
+  },
+  "openCount": 1,
+  "lastUpdate": "2025-11-18T15:30:00Z"
+}
+```
+
+**Source of Truth**:
+- Increment status: `spec.md` YAML frontmatter (NOT metadata.json)
+- Task progress: `tasks.md` (TaskCounter for accuracy)
+
+**Atomicity**: Uses temp file → rename pattern to prevent cache corruption
+
+---
+
+## Troubleshooting
+
+**Status line still stale after update?**
+1. Check if `.specweave/state/status-line.json` was modified
+2. Verify spec.md has correct status in YAML frontmatter
+3. Check tasks.md has proper task format (## T-001, etc.)
+
+**Error: "Failed to update status line"**
+- Ensure `.specweave/increments/` exists
+- Check file permissions on `.specweave/state/`
+- Verify spec.md has valid YAML frontmatter
+
+**Cache shows wrong increment?**
+- Status line shows oldest active increment by default
+- Complete older increments first
+- Or check `created` date in spec.md frontmatter
+
+---
+
+## Implementation
+
+**CLI**: `src/cli/update-status-line.ts`
+**Core Logic**: `src/core/status-line/status-line-updater.ts`
+**Hook (async)**: `plugins/specweave/hooks/lib/update-status-line.sh`
+
+**Difference from Hook**:
+- **Command**: SYNCHRONOUS (user waits, sees immediate result)
+- **Hook**: ASYNCHRONOUS (background refresh, no blocking)
+
+Both use same logic, different execution model.
+
+---
+
+**This command ensures status line is ALWAYS fresh when you need it!** ✓

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

@@ -1,16 +1,17 @@
 #!/usr/bin/env bash
 #
-# update-status-line.sh (Simplified)
+# update-status-line.sh (Enhanced with AC Metrics)
 #
 # Updates status line cache with current increment progress.
-# Shows: [increment-name] ████░░░░ X/Y tasks (Z open)
+# Shows: [increment-name] ████░░░░ X/Y tasks | A/B ACs (Z open)
 #
 # Logic:
-# 1. Scan all metadata.json for status=active/in-progress/planning
+# 1. Scan all spec.md for status=active/planning (SOURCE OF TRUTH!)
 # 2. Take first (oldest) as current increment
-# 3. Count all active/in-progress/planning as openCount
-# 4. Parse current increment's tasks.md for progress
-# 5. Write to cache
+# 3. Count all active/planning as openCount
+# 4. Parse current increment's tasks.md for task progress
+# 5. Parse current increment's spec.md for AC progress
+# 6. Write to cache
 #
 # Performance: 50-100ms (runs async, user doesn't wait)
 
@@ -37,19 +38,24 @@ TMP_FILE="$PROJECT_ROOT/.specweave/state/.status-line-tmp.txt"
 # Ensure state directory exists
 mkdir -p "$PROJECT_ROOT/.specweave/state"
 
-# Step 1: Find all open increments (active/in-progress/planning)
+# Step 1: Find all open increments (active/planning)
+# Read from spec.md (source of truth), not metadata.json
+# ONLY accepts official IncrementStatus enum values
 # Write to temp file: "timestamp increment_id"
 > "$TMP_FILE"
 
 if [[ -d "$INCREMENTS_DIR" ]]; then
-  for metadata in "$INCREMENTS_DIR"/*/metadata.json; do
-    if [[ -f "$metadata" ]]; then
-      status=$(jq -r '.status // ""' "$metadata" 2>/dev/null || echo "")
-
-      # Check if increment is open (active, in-progress, or planning)
-      if [[ "$status" == "active" ]] || [[ "$status" == "in-progress" ]] || [[ "$status" == "planning" ]]; then
-        increment_id=$(basename "$(dirname "$metadata")")
-        created=$(jq -r '.created // ""' "$metadata" 2>/dev/null || echo "1970-01-01T00:00:00Z")
+  for spec_file in "$INCREMENTS_DIR"/*/spec.md; do
+    if [[ -f "$spec_file" ]]; then
+      # Parse YAML frontmatter for status (source of truth)
+      status=$(grep -m1 "^status:" "$spec_file" 2>/dev/null | cut -d: -f2 | tr -d ' ' || echo "")
+
+      # Check if increment is open (active, planning, or in-progress)
+      # ONLY accepts official IncrementStatus enum values
+      if [[ "$status" == "active" ]] || [[ "$status" == "planning" ]] || [[ "$status" == "in-progress" ]]; then
+        increment_id=$(basename "$(dirname "$spec_file")")
+        # Parse created date from spec.md YAML frontmatter
+        created=$(grep -m1 "^created:" "$spec_file" 2>/dev/null | cut -d: -f2- | tr -d ' ' || echo "1970-01-01")
 
         # Write to temp file
         echo "$created $increment_id" >> "$TMP_FILE"
@@ -85,41 +91,70 @@ COMPLETED_TASKS=0
 PERCENTAGE=0
 
 if [[ -f "$TASKS_FILE" ]]; then
-  # Count total tasks (## T- or ### T- headings)
-  TOTAL_TASKS=$(grep -cE '^##+ T-' "$TASKS_FILE" 2>/dev/null || echo 0)
-  TOTAL_TASKS=$(echo "$TOTAL_TASKS" | tr -d '\n\r ' || echo 0)
-
-  # Count completed tasks (multiple formats)
-  # Format 1: [x] at line start (legacy)
-  COMPLETED_STANDARD=$(grep -c '^\[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
-  COMPLETED_STANDARD=$(echo "$COMPLETED_STANDARD" | tr -d '\n\r ' || echo 0)
-
-  # Format 2: **Status**: [x] inline (legacy)
-  COMPLETED_INLINE=$(grep -c '\*\*Status\*\*: \[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
-  COMPLETED_INLINE=$(echo "$COMPLETED_INLINE" | tr -d '\n\r ' || echo 0)
-
-  # Format 3: **Completed**: <date> (current format)
-  COMPLETED_DATE=$(grep -c '\*\*Completed\*\*:' "$TASKS_FILE" 2>/dev/null || echo 0)
-  COMPLETED_DATE=$(echo "$COMPLETED_DATE" | tr -d '\n\r ' || echo 0)
-
-  COMPLETED_TASKS=$((COMPLETED_STANDARD + COMPLETED_INLINE + COMPLETED_DATE))
-
-  # Calculate percentage
-  if [[ $TOTAL_TASKS -gt 0 ]]; then
-    PERCENTAGE=$((COMPLETED_TASKS * 100 / TOTAL_TASKS))
+  # Use TaskCounter CLI for accurate counting (fixes overcounting bug)
+  COUNT_TASKS_CLI="$PROJECT_ROOT/dist/src/cli/count-tasks.js"
+
+  if [[ -f "$COUNT_TASKS_CLI" ]]; then
+    # Call CLI and parse JSON output
+    TASK_COUNTS=$(node "$COUNT_TASKS_CLI" "$TASKS_FILE" 2>/dev/null || echo '{"total":0,"completed":0,"percentage":0}')
+    TOTAL_TASKS=$(echo "$TASK_COUNTS" | jq -r '.total' 2>/dev/null || echo 0)
+    COMPLETED_TASKS=$(echo "$TASK_COUNTS" | jq -r '.completed' 2>/dev/null || echo 0)
+    PERCENTAGE=$(echo "$TASK_COUNTS" | jq -r '.percentage' 2>/dev/null || echo 0)
+  else
+    # Fallback to legacy counting if CLI not available (graceful degradation)
+    # Count total tasks (## T- or ### T- headings)
+    TOTAL_TASKS=$(grep -cE '^##+ T-' "$TASKS_FILE" 2>/dev/null || echo 0)
+    TOTAL_TASKS=$(echo "$TOTAL_TASKS" | tr -d '\n\r ' || echo 0)
+
+    # Count completed tasks - use most reliable single marker (**Completed**: format)
+    COMPLETED_TASKS=$(grep -c '\*\*Completed\*\*:' "$TASKS_FILE" 2>/dev/null || echo 0)
+    COMPLETED_TASKS=$(echo "$COMPLETED_TASKS" | tr -d '\n\r ' || echo 0)
+
+    # Calculate percentage
+    if [[ $TOTAL_TASKS -gt 0 ]]; then
+      PERCENTAGE=$((COMPLETED_TASKS * 100 / TOTAL_TASKS))
+    fi
   fi
 fi
 
-# Step 5: Extract increment name (remove 4-digit prefix)
-INCREMENT_NAME=$(echo "$CURRENT_INCREMENT" | sed 's/^[0-9]\{4\}-//')
+# Step 4b: Parse spec.md for AC (Acceptance Criteria) progress
+SPEC_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/spec.md"
+TOTAL_ACS=0
+COMPLETED_ACS=0
+OPEN_ACS=0
+
+if [[ -f "$SPEC_FILE" ]]; then
+  # Count total ACs: both checked and unchecked
+  # Pattern: - [ ] **AC- OR - [x] **AC-
+  TOTAL_ACS=$(grep -cE '^- \[(x| )\] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
+  TOTAL_ACS=$(echo "$TOTAL_ACS" | tr -d '\n\r ' || echo 0)
+
+  # Count completed ACs (checked)
+  # Pattern: - [x] **AC-
+  COMPLETED_ACS=$(grep -cE '^- \[x\] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
+  COMPLETED_ACS=$(echo "$COMPLETED_ACS" | tr -d '\n\r ' || echo 0)
+
+  # Count open ACs (unchecked)
+  # Pattern: - [ ] **AC-
+  OPEN_ACS=$(grep -cE '^- \[ \] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
+  OPEN_ACS=$(echo "$OPEN_ACS" | tr -d '\n\r ' || echo 0)
+fi
+
+# Step 5: Extract increment ID and name
+# Format: XXXX-name where XXXX is 4-digit prefix (brackets added by manager)
+INCREMENT_ID=$(echo "$CURRENT_INCREMENT" | grep -oE '^[0-9]{4}')
+INCREMENT_NAME_ONLY=$(echo "$CURRENT_INCREMENT" | sed 's/^[0-9]\{4\}-//')
+INCREMENT_NAME="$INCREMENT_ID-$INCREMENT_NAME_ONLY"
 
-# Step 6: Write cache
+# Step 6: Write cache (now includes AC metrics)
 jq -n \
   --arg id "$CURRENT_INCREMENT" \
   --arg name "$INCREMENT_NAME" \
   --argjson completed "$COMPLETED_TASKS" \
   --argjson total "$TOTAL_TASKS" \
   --argjson percentage "$PERCENTAGE" \
+  --argjson acsCompleted "$COMPLETED_ACS" \
+  --argjson acsTotal "$TOTAL_ACS" \
   --argjson openCount "$OPEN_COUNT" \
   '{
     current: {
@@ -127,7 +162,9 @@ jq -n \
       name: $name,
       completed: $completed,
       total: $total,
-      percentage: $percentage
+      percentage: $percentage,
+      acsCompleted: $acsCompleted,
+      acsTotal: $acsTotal
     },
     openCount: $openCount,
     lastUpdate: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))

package/plugins/specweave/hooks/lib/validate-spec-status.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+#
+# validate-spec-status.sh
+#
+# Validates that spec.md status values match IncrementStatus enum.
+# Prevents vocabulary drift and ensures status line hook compatibility.
+#
+# Usage:
+#   bash validate-spec-status.sh <increment-id>
+#   bash validate-spec-status.sh --all  # Validate all increments
+#
+# Exit codes:
+#   0 = Valid
+#   1 = Invalid status found
+#   2 = Error (file not found, etc.)
+#
+# Requires: bash 4.0+ (for associative arrays)
+
+set -euo pipefail
+
+# 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)
+INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+
+# Valid IncrementStatus enum values (from src/core/types/increment-metadata.ts)
+VALID_STATUSES=("planning" "active" "backlog" "paused" "completed" "abandoned")
+
+# Get suggested correction for invalid status
+get_correction() {
+  local status="$1"
+  case "$status" in
+    "planned") echo "planning" ;;
+    "in-progress"|"in_progress") echo "active" ;;
+    "done") echo "completed" ;;
+    "cancelled"|"canceled") echo "abandoned" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Validate a single spec file
+validate_spec() {
+  local spec_file="$1"
+  local increment_id=$(basename "$(dirname "$spec_file")")
+
+  if [[ ! -f "$spec_file" ]]; then
+    echo "❌ Error: spec.md not found for increment $increment_id"
+    return 2
+  fi
+
+  # Extract status from YAML frontmatter
+  local status=$(grep -m1 "^status:" "$spec_file" 2>/dev/null | cut -d: -f2 | tr -d ' "' || echo "")
+
+  if [[ -z "$status" ]]; then
+    echo "⚠️  Warning: No status field in $increment_id/spec.md"
+    return 0  # Not an error, just a warning
+  fi
+
+  # Check if status is valid
+  local is_valid=0
+  for valid_status in "${VALID_STATUSES[@]}"; do
+    if [[ "$status" == "$valid_status" ]]; then
+      is_valid=1
+      break
+    fi
+  done
+
+  if [[ $is_valid -eq 1 ]]; then
+    echo "✅ $increment_id: status '$status' is valid"
+    return 0
+  else
+    # Invalid status found - suggest correction
+    echo ""
+    echo "❌ Invalid status in $increment_id/spec.md"
+    echo "   Found: '$status'"
+    echo ""
+
+    # Check if we have a suggested correction
+    local correction=$(get_correction "$status")
+    if [[ -n "$correction" ]]; then
+      echo "   💡 Did you mean: '$correction'?"
+      echo ""
+      echo "   Fix:"
+      echo "   sed -i '' 's/^status: $status/status: $correction/' $spec_file"
+    else
+      echo "   Valid statuses: ${VALID_STATUSES[*]}"
+    fi
+    echo ""
+
+    return 1
+  fi
+}
+
+# Validate all increments
+validate_all() {
+  local exit_code=0
+  local total=0
+  local valid=0
+  local invalid=0
+
+  echo "Validating all increments in $INCREMENTS_DIR"
+  echo ""
+
+  for spec_file in "$INCREMENTS_DIR"/*/spec.md; do
+    if [[ -f "$spec_file" ]]; then
+      total=$((total + 1))
+      if validate_spec "$spec_file"; then
+        valid=$((valid + 1))
+      else
+        invalid=$((invalid + 1))
+        exit_code=1
+      fi
+    fi
+  done
+
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "Summary: $total increments checked"
+  echo "  ✅ Valid: $valid"
+  echo "  ❌ Invalid: $invalid"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  if [[ $invalid -gt 0 ]]; then
+    echo ""
+    echo "⚠️  Please fix invalid status values to use official IncrementStatus enum."
+    echo ""
+    echo "Valid statuses:"
+    for status in "${VALID_STATUSES[@]}"; do
+      echo "  - $status"
+    done
+  fi
+
+  return $exit_code
+}
+
+# Main logic
+if [[ $# -eq 0 ]]; then
+  echo "Usage: $0 <increment-id> | --all"
+  echo ""
+  echo "Examples:"
+  echo "  $0 0042-test-infrastructure-cleanup"
+  echo "  $0 --all"
+  exit 2
+fi
+
+if [[ "$1" == "--all" ]]; then
+  validate_all
+else
+  INCREMENT_ID="$1"
+  SPEC_FILE="$INCREMENTS_DIR/$INCREMENT_ID/spec.md"
+  validate_spec "$SPEC_FILE"
+fi

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

@@ -303,44 +303,26 @@ if [[ -d ".specweave/increments" ]]; then
   done)
 
   if [[ -n "$ACTIVE_INCREMENT" ]]; then
-    # Use status line cache for consistent display
-    STATUS_LINE_CACHE=".specweave/state/status-line.json"
-    if [[ -f "$STATUS_LINE_CACHE" ]]; then
-      # Get status line from cache (ultra-fast)
-      STATUS_LINE=$(node -e "
-        try {
-          const { StatusLineManager } = require('./dist/src/core/status-line/status-line-manager.js');
-          const manager = new StatusLineManager(process.cwd());
-          const result = manager.render();
-          console.log(result || '');
-        } catch (e) {
-          // Fallback: show increment name only
-          console.log('');
-        }
-      " 2>/dev/null || echo "")
-
-      if [[ -n "$STATUS_LINE" ]]; then
-        CONTEXT="✓ $STATUS_LINE"
+    # 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
-        # Fallback: parse tasks.md manually
-        TASKS_FILE=".specweave/increments/$ACTIVE_INCREMENT/tasks.md"
-        if [[ -f "$TASKS_FILE" ]]; then
-          TASK_STATS=$(grep -E "^\s*-\s*\[[ x]\]" "$TASKS_FILE" 2>/dev/null | wc -l | xargs || echo "0")
-          COMPLETED_TASKS=$(grep -E "^\s*-\s*\[x\]" "$TASKS_FILE" 2>/dev/null | wc -l | xargs || echo "0")
-
-          if [[ "$TASK_STATS" -gt 0 ]]; then
-            PERCENTAGE=$(( COMPLETED_TASKS * 100 / TASK_STATS ))
-            CONTEXT="✓ Active Increment: $ACTIVE_INCREMENT ($PERCENTAGE% complete, $COMPLETED_TASKS/$TASK_STATS tasks)"
-          else
-            CONTEXT="✓ Active Increment: $ACTIVE_INCREMENT"
-          fi
-        else
-          CONTEXT="✓ Active Increment: $ACTIVE_INCREMENT"
-        fi
+        CONTEXT="✓ Active: $ACTIVE_INCREMENT"
       fi
     else
-      # No cache, fall back to increment name only
-      CONTEXT="✓ Active Increment: $ACTIVE_INCREMENT"
+      CONTEXT="✓ Active: $ACTIVE_INCREMENT"
     fi
   fi
 fi
@@ -360,6 +342,27 @@ if echo "$PROMPT" | grep -qiE "(add|create|implement|build|develop)" && ! echo "
   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
 # ==============================================================================