specweave 0.22.2 → 0.22.3

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 spec.md for status=active/planning (SOURCE OF TRUTH!)
 # 2. Take first (oldest) as current increment
 # 3. Count all active/planning as openCount
-# 4. Parse current increment's tasks.md for progress
-# 5. Write to cache
+# 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)
 
@@ -116,19 +117,44 @@ if [[ -f "$TASKS_FILE" ]]; then
   fi
 fi
 
+# 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: {
@@ -136,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/user-prompt-submit.sh

@@ -342,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
 # ==============================================================================

package/plugins/specweave/hooks/validate-increment-completion.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+#
+# Pre-commit hook: Validate Increment Completion
+#
+# Prevents commits where increment status="completed" but:
+# - Acceptance criteria are still open (- [ ] **AC-...)
+# - Tasks are still pending (**Status**: [ ] pending)
+#
+# This prevents false completion and data integrity violations.
+#
+# Exit code 0: All completed increments are valid (allow commit)
+# Exit code 1: Invalid completion detected (block commit)
+
+# ANSI colors
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Check if in SpecWeave project
+if [ ! -d ".specweave/increments" ]; then
+  # Not a SpecWeave project, skip validation
+  exit 0
+fi
+
+# Track if any validation failures found
+has_failures=false
+
+# Check all increments
+for increment_dir in .specweave/increments/*/; do
+  # Skip if not a directory
+  [ ! -d "$increment_dir" ] && continue
+
+  increment_id=$(basename "$increment_dir")
+  spec_file="$increment_dir/spec.md"
+  tasks_file="$increment_dir/tasks.md"
+  metadata_file="$increment_dir/metadata.json"
+
+  # Skip if required files don't exist
+  [ ! -f "$spec_file" ] && continue
+  [ ! -f "$tasks_file" ] && continue
+
+  # Get status from spec.md frontmatter
+  spec_status=$(grep -m1 "^status:" "$spec_file" 2>/dev/null | cut -d: -f2 | tr -d ' ')
+
+  # Get status from metadata.json (if exists)
+  metadata_status=""
+  if [ -f "$metadata_file" ]; then
+    metadata_status=$(grep -m1 '"status"' "$metadata_file" 2>/dev/null | cut -d'"' -f4)
+  fi
+
+  # Only validate if status is "completed"
+  if [ "$spec_status" = "completed" ] || [ "$metadata_status" = "completed" ]; then
+    # Count open acceptance criteria (- [ ] **AC-)
+    open_acs=$(grep -c "^- \[ \] \*\*AC-" "$spec_file" 2>/dev/null || echo 0)
+
+    # Count pending tasks (**Status**: [ ] pending)
+    pending_tasks=$(grep -ic "\*\*Status\*\*:\s*\[\s*\]\s*pending" "$tasks_file" 2>/dev/null || echo 0)
+
+    # Validate
+    if [ "$open_acs" -gt 0 ] || [ "$pending_tasks" -gt 0 ]; then
+      has_failures=true
+
+      echo -e "${RED}❌ COMMIT BLOCKED: Invalid completion detected${NC}"
+      echo -e "${YELLOW}Increment: $increment_id${NC}"
+      echo -e "Status: $spec_status (spec.md) / $metadata_status (metadata.json)"
+      echo ""
+
+      if [ "$open_acs" -gt 0 ]; then
+        echo -e "${RED}  • $open_acs acceptance criteria still open${NC}"
+      fi
+
+      if [ "$pending_tasks" -gt 0 ]; then
+        echo -e "${RED}  • $pending_tasks tasks still pending${NC}"
+      fi
+
+      echo ""
+      echo -e "${YELLOW}Fix options:${NC}"
+      echo "  1. Complete the open work before committing"
+      echo "  2. Change status to 'active' or 'paused' in both spec.md and metadata.json"
+      echo ""
+      echo -e "${YELLOW}To see details:${NC}"
+      echo "  cat $spec_file | grep '- \[ \] \*\*AC-'"
+      echo "  cat $tasks_file | grep -i 'Status.*pending'"
+      echo ""
+    fi
+  fi
+done
+
+# Exit with failure if any validation failures
+if [ "$has_failures" = true ]; then
+  echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo -e "${RED}COMMIT BLOCKED: Cannot commit increments with invalid completion${NC}"
+  echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo ""
+  echo -e "${YELLOW}Why this matters:${NC}"
+  echo "  • Prevents false completion (status='completed' with open work)"
+  echo "  • Ensures data integrity (metadata matches reality)"
+  echo "  • Stops misleading status line and GitHub sync"
+  echo ""
+  echo -e "${YELLOW}To fix:${NC}"
+  echo "  1. Complete all open ACs and pending tasks, OR"
+  echo "  2. Change status to 'active'/'paused' in spec.md and metadata.json"
+  echo ""
+  echo -e "${YELLOW}To bypass (NOT RECOMMENDED):${NC}"
+  echo "  git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+# All validations passed
+echo -e "${GREEN}✅ Completion validation passed${NC}"
+exit 0

package/plugins/specweave-ado/lib/ado-multi-project-sync.js

@@ -373,7 +373,6 @@ ${userStory.technicalContext}
         return mapping.task || "Task";
       case "Subtask":
         return mapping.task || "Task";
-      // ADO doesn't have subtasks, use Task
       default:
         return "User Story";
     }

package/plugins/specweave-github/commands/specweave-github-cleanup-duplicates.md

@@ -1,6 +1,27 @@
 ---
 name: specweave-github:cleanup-duplicates
 description: Clean up duplicate GitHub issues for an Epic. Finds issues with duplicate titles and closes all except the first created issue.
+justification: |
+  CRITICAL INCIDENT RESPONSE TOOL - DO NOT DELETE!
+
+  Why This Command Exists:
+  - Prevention systems (deduplication, GitHub self-healing) work for single-process execution
+  - Multiple parallel Claude Code instances bypass all prevention (file-based cache, no distributed locking)
+  - GitHub API race conditions: Time gap between "check exists" and "create issue" allows duplicates
+  - Historical duplicates from pre-v0.14.1 users (before prevention was added)
+
+  Evidence of Need:
+  - 2025-11-13: 123 duplicate GitHub issues incident (cleaned to 29 unique)
+  - Parallel execution creates race conditions that prevention CANNOT solve
+  - Industry standard: Prevention + Detection + Cleanup (defense in depth)
+
+  When to Delete:
+  - ONLY if distributed locking implemented (Redis/file locks)
+  - AND parallel execution tested (100+ concurrent syncs with zero duplicates)
+  - AND zero duplicates for 6+ months in production
+  - AND all users migrated to prevention-enabled versions
+
+  See: .specweave/increments/0043-spec-md-desync-fix/reports/ULTRATHINK-CLEANUP-DUPLICATES-NECESSITY-2025-11-18.md
 ---
 
 # Clean Up Duplicate GitHub Issues

package/plugins/specweave-jira/lib/enhanced-jira-sync.js

@@ -1,6 +1,6 @@
-import { EnhancedContentBuilder } from "../../../dist/src/core/sync/enhanced-content-builder.js";
-import { SpecIncrementMapper } from "../../../dist/src/core/sync/spec-increment-mapper.js";
-import { parseSpecContent } from "../../../dist/src/core/spec-content-sync.js";
+import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
 import * as path from "path";
 import * as fs from "fs/promises";
 async function syncSpecToJiraWithEnhancedContent(options) {

package/plugins/specweave-ado/lib/enhanced-ado-sync.js

@@ -1,170 +0,0 @@
-import { AdoClientV2 } from "./ado-client-v2.js";
-import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
-import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
-import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
-import path from "path";
-import fs from "fs/promises";
-async function syncSpecToAdoWithEnhancedContent(options) {
-  const { specPath, organization, project, dryRun = false, verbose = false } = options;
-  try {
-    const baseSpec = await parseSpecContent(specPath);
-    if (!baseSpec) {
-      return {
-        success: false,
-        action: "error",
-        error: "Failed to parse spec content"
-      };
-    }
-    if (verbose) {
-      console.log(`\u{1F4C4} Parsed spec: ${baseSpec.identifier.compact}`);
-    }
-    const specId = baseSpec.identifier.full || baseSpec.identifier.compact;
-    const rootDir = await findSpecWeaveRoot(specPath);
-    const mapper = new SpecIncrementMapper(rootDir);
-    const mapping = await mapper.mapSpecToIncrements(specId);
-    if (verbose) {
-      console.log(`\u{1F517} Found ${mapping.increments.length} related increments`);
-    }
-    const taskMapping = buildTaskMapping(mapping.increments, organization, project);
-    const architectureDocs = await findArchitectureDocs(rootDir, specId);
-    const enhancedSpec = {
-      ...baseSpec,
-      summary: baseSpec.description,
-      taskMapping,
-      architectureDocs
-    };
-    const builder = new EnhancedContentBuilder();
-    const description = builder.buildExternalDescription(enhancedSpec);
-    if (verbose) {
-      console.log(`\u{1F4DD} Generated description: ${description.length} characters`);
-    }
-    if (dryRun) {
-      console.log("\u{1F50D} DRY RUN - Would create/update feature with:");
-      console.log(`   Title: ${baseSpec.title}`);
-      console.log(`   Description length: ${description.length}`);
-      return {
-        success: true,
-        action: "no-change",
-        tasksLinked: taskMapping?.tasks.length || 0
-      };
-    }
-    if (!organization || !project) {
-      return {
-        success: false,
-        action: "error",
-        error: "Azure DevOps organization/project not specified"
-      };
-    }
-    const profile = {
-      provider: "ado",
-      displayName: `${organization}/${project}`,
-      config: {
-        organization,
-        project
-      },
-      timeRange: { default: "1M", max: "6M" }
-    };
-    const pat = process.env.AZURE_DEVOPS_PAT || "";
-    const client = new AdoClientV2(profile, pat);
-    const existingFeature = await findExistingFeature(client, baseSpec.identifier.compact);
-    let result;
-    if (existingFeature) {
-      await client.updateWorkItem(existingFeature.id, {
-        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
-        description
-      });
-      result = {
-        success: true,
-        action: "updated",
-        featureId: existingFeature.id,
-        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${existingFeature.id}`,
-        tasksLinked: taskMapping?.tasks.length || 0
-      };
-    } else {
-      const feature = await client.createEpic({
-        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
-        description,
-        tags: ["spec", "external-tool-sync"]
-      });
-      result = {
-        success: true,
-        action: "created",
-        featureId: feature.id,
-        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${feature.id}`,
-        tasksLinked: taskMapping?.tasks.length || 0
-      };
-    }
-    if (verbose) {
-      console.log(`\u2705 ${result.action === "created" ? "Created" : "Updated"} feature #${result.featureId}`);
-    }
-    return result;
-  } catch (error) {
-    return {
-      success: false,
-      action: "error",
-      error: error.message
-    };
-  }
-}
-async function findSpecWeaveRoot(specPath) {
-  let currentDir = path.dirname(specPath);
-  while (true) {
-    const specweaveDir = path.join(currentDir, ".specweave");
-    try {
-      await fs.access(specweaveDir);
-      return currentDir;
-    } catch {
-      const parentDir = path.dirname(currentDir);
-      if (parentDir === currentDir) {
-        throw new Error(".specweave directory not found");
-      }
-      currentDir = parentDir;
-    }
-  }
-}
-function buildTaskMapping(increments, organization, project) {
-  if (increments.length === 0) return void 0;
-  const firstIncrement = increments[0];
-  const tasks = firstIncrement.tasks.map((task) => ({
-    id: task.id,
-    title: task.title,
-    userStories: task.userStories
-  }));
-  return {
-    incrementId: firstIncrement.id,
-    tasks,
-    tasksUrl: `https://dev.azure.com/${organization}/${project}/_git/repo?path=/.specweave/increments/${firstIncrement.id}/tasks.md`
-  };
-}
-async function findArchitectureDocs(rootDir, specId) {
-  const docs = [];
-  const archDir = path.join(rootDir, ".specweave/docs/internal/architecture");
-  try {
-    const adrDir = path.join(archDir, "adr");
-    try {
-      const adrs = await fs.readdir(adrDir);
-      const relatedAdrs = adrs.filter((file) => file.includes(specId.replace("spec-", "")));
-      for (const adr of relatedAdrs) {
-        docs.push({
-          type: "adr",
-          path: path.join(adrDir, adr),
-          title: adr.replace(".md", "").replace(/-/g, " ")
-        });
-      }
-    } catch {
-    }
-  } catch {
-  }
-  return docs;
-}
-async function findExistingFeature(client, specId) {
-  try {
-    const features = await client.queryWorkItems(`[System.Title] Contains '[${specId}]' AND [System.WorkItemType] = 'Feature'`);
-    return features[0] || null;
-  } catch {
-    return null;
-  }
-}
-export {
-  syncSpecToAdoWithEnhancedContent
-};