specweave 0.21.3 → 0.22.2

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/hooks/lib/update-status-line.sh

@@ -6,9 +6,9 @@
 # Shows: [increment-name] ████░░░░ X/Y tasks (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
+# 3. Count all active/planning as openCount
 # 4. Parse current increment's tasks.md for progress
 # 5. Write to cache
 #
@@ -37,19 +37,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,33 +90,37 @@ 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 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
 jq -n \

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

package/plugins/specweave/lib/hooks/update-tasks-md.js

@@ -20,13 +20,22 @@ async function updateTasksMd(incrementId) {
     console.log(`\u{1F4D6} Read tasks.md (${lines.length} lines)`);
     const tasks = parseTaskStatus(lines);
     console.log(`\u{1F4CB} Found ${tasks.length} tasks`);
-    const completedTasks = detectCompletedTasks(lines);
-    if (completedTasks.length === 0) {
-      console.log("\u2705 No new task completions detected");
+    const { completedTasks, fixes } = detectCompletedTasks(lines);
+    let updatedContent = originalContent;
+    let autoFixedCount = 0;
+    if (fixes.length > 0) {
+      console.log(`\u{1F527} Auto-fixing ${fixes.length} task consistency issue(s)...`);
+      updatedContent = applyConsistencyFixes(originalContent, fixes);
+      autoFixedCount = fixes.length;
+      console.log("\u2705 Task consistency auto-fixed");
+    }
+    if (completedTasks.length === 0 && fixes.length === 0) {
+      console.log("\u2705 No new task completions or consistency fixes needed");
       return;
     }
-    console.log(`\u{1F3AF} Detected ${completedTasks.length} completed task(s):`, completedTasks);
-    let updatedContent = originalContent;
+    if (completedTasks.length > 0) {
+      console.log(`\u{1F3AF} Detected ${completedTasks.length} completed task(s):`, completedTasks);
+    }
     for (const taskId of completedTasks) {
       updatedContent = markTaskComplete(updatedContent, taskId);
     }
@@ -38,6 +47,9 @@ async function updateTasksMd(incrementId) {
     updatedContent = updateProgressHeader(updatedContent, completedCount, totalTasks, progress);
     await fs.writeFile(tasksPath, updatedContent, "utf-8");
     console.log(`\u2705 Updated ${tasksPath}`);
+    if (autoFixedCount > 0) {
+      console.log(`\u{1F527} Auto-fixed ${autoFixedCount} consistency issue(s)`);
+    }
     console.log(`   Completed: ${completedCount}/${totalTasks}`);
     console.log(`   Progress: ${progress}%
 `);
@@ -78,6 +90,7 @@ function parseTaskStatus(lines) {
 }
 function detectCompletedTasks(lines) {
   const completedTasks = [];
+  const fixes = [];
   const warnings = [];
   const taskPattern = /^###\s+(T-\d+[-A-Z]*):?\s+(.+)/;
   for (let i = 0; i < lines.length; i++) {
@@ -99,17 +112,33 @@ function detectCompletedTasks(lines) {
           completedTasks.push(taskId);
         }
       } else {
+        fixes.push({
+          taskId,
+          lineNumber: i,
+          action: "remove-complete-marker",
+          currentLine: line
+        });
         warnings.push(`${taskId}: Header has \u2705 COMPLETE but not all checkboxes checked`);
       }
       continue;
     }
     if (hasCompleteMarker && !implementationSection) {
-      if (!completedTasks.includes(taskId)) {
-        completedTasks.push(taskId);
-      }
+      fixes.push({
+        taskId,
+        lineNumber: i,
+        action: "remove-complete-marker",
+        currentLine: line
+      });
+      warnings.push(`${taskId}: Header has \u2705 COMPLETE but no implementation section to verify`);
       continue;
     }
     if (!hasCompleteMarker && implementationSection && allCheckboxesComplete) {
+      fixes.push({
+        taskId,
+        lineNumber: i,
+        action: "add-complete-marker",
+        currentLine: line
+      });
       warnings.push(`${taskId}: All checkboxes checked but header missing \u2705 COMPLETE`);
       if (!completedTasks.includes(taskId)) {
         completedTasks.push(taskId);
@@ -131,7 +160,21 @@ function detectCompletedTasks(lines) {
     warnings.forEach((w) => console.warn(`   ${w}`));
     console.warn("");
   }
-  return completedTasks;
+  return { completedTasks, fixes };
+}
+function applyConsistencyFixes(content, fixes) {
+  const lines = content.split("\n");
+  for (const fix of fixes.reverse()) {
+    const line = lines[fix.lineNumber];
+    if (fix.action === "remove-complete-marker") {
+      const fixed = line.replace(/\s*✅\s*COMPLETE\s*/g, "");
+      lines[fix.lineNumber] = fixed;
+    } else if (fix.action === "add-complete-marker") {
+      const fixed = line.trim() + " \u2705 COMPLETE";
+      lines[fix.lineNumber] = fixed;
+    }
+  }
+  return lines.join("\n");
 }
 function findNextTaskStart(lines, startIndex) {
   const taskPattern = /^###\s+T-\d+/;