specweave 0.18.1 → 0.20.1

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

@@ -0,0 +1,425 @@
+---
+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
+---
+
+# Sync Specs Only
+
+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.
+
+---
+
+## STEP 1: Parse Arguments
+
+```
+Arguments provided: [user's arguments]
+```
+
+**Parse the input**:
+- Check for increment ID: `0001`, `0002`, etc.
+- If no increment ID: find the most recent increment
+- Check for options: `--force`, `--dry-run`
+
+**Find increment**:
+```bash
+if [[ -z "$INCREMENT_ID" ]]; then
+  # Find most recent increment
+  INCREMENT_ID=$(ls -1 .specweave/increments/ | grep -E '^[0-9]{4}-' | sort -r | head -1)
+fi
+
+# Verify increment exists
+INCREMENT_PATH=".specweave/increments/$INCREMENT_ID"
+if [[ ! -d "$INCREMENT_PATH" ]]; then
+  echo "❌ Error: Increment $INCREMENT_ID not found"
+  exit 1
+fi
+```
+
+**Output**:
+```
+🎯 Target increment: {increment_id}
+📁 Increment path: .specweave/increments/{increment_id}
+🔄 Mode: Specs-only sync (Universal Hierarchy)
+
+Processing...
+```
+
+---
+
+## STEP 2: Check Prerequisites
+
+### 2.1 Verify Spec File Exists
+
+```bash
+SPEC_FILE="$INCREMENT_PATH/spec.md"
+if [[ ! -f "$SPEC_FILE" ]]; then
+  echo "❌ Error: No spec.md found in increment $INCREMENT_ID"
+  echo "   Cannot sync specs without a spec file"
+  exit 1
+fi
+```
+
+### 2.2 Check Tasks File (for bidirectional linking)
+
+```bash
+TASKS_FILE="$INCREMENT_PATH/tasks.md"
+HAS_TASKS=false
+if [[ -f "$TASKS_FILE" ]]; then
+  HAS_TASKS=true
+  echo "✅ Found tasks.md - will create bidirectional links"
+else
+  echo "⚠️  No tasks.md - spec will sync without task links"
+fi
+```
+
+### 2.3 Read Metadata for External Links
+
+```bash
+METADATA_FILE="$INCREMENT_PATH/metadata.json"
+if [[ -f "$METADATA_FILE" ]]; then
+  echo "✅ Found metadata.json - will include external links"
+else
+  echo "⚠️  No metadata.json - no external tool links available"
+fi
+```
+
+---
+
+## STEP 3: Execute Spec Distribution
+
+### 3.1 Run SpecDistributor
+
+**Execute the distribution using Node.js**:
+
+```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());
+
+  console.log('🚀 Starting spec distribution...');
+  console.log('   📄 Reading spec.md from increment ${INCREMENT_ID}');
+
+  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);
+  }
+});
+"
+```
+
+---
+
+## STEP 4: Report Distribution Results
+
+### 4.1 Show What Was Created
+
+```
+═══════════════════════════════════════════════════════
+✅ SPECS-ONLY SYNC COMPLETE
+═══════════════════════════════════════════════════════
+
+Increment: {increment_id}
+Title: {title from spec.md}
+
+───────────────────────────────────────────────────────
+📊 UNIVERSAL HIERARCHY CREATED
+───────────────────────────────────────────────────────
+
+📁 Epic (Optional):
+   {if created}
+   Path: .specweave/docs/internal/specs/_epics/{EPIC-ID}/EPIC.md
+   Status: Created/Updated
+
+📁 Feature (Required):
+   Path: .specweave/docs/internal/specs/_features/{FS-ID}/FEATURE.md
+   Status: Created/Updated
+   Projects: {list of projects}
+
+📁 Project Contexts:
+   {for each project}
+   • {project}: .specweave/docs/internal/specs/{project}/{FS-ID}/README.md
+
+📝 User Stories:
+   {for each project}
+   {project}:
+   {for each story}
+   • {story-id}: {story-title}
+     Path: .specweave/docs/internal/specs/{project}/{FS-ID}/{us-id}.md
+
+───────────────────────────────────────────────────────
+🔗 BIDIRECTIONAL LINKING
+───────────────────────────────────────────────────────
+
+{if tasks.md exists}
+✅ Task → User Story Links:
+   Updated tasks.md with user story references
+   Each task now links to its parent user story
+
+✅ User Story → Task Links:
+   Each user story shows implementing tasks
+   Tasks linked back to increment #{increment_id}
+{else}
+⚠️  No tasks.md found - stories created without task links
+{/if}
+
+───────────────────────────────────────────────────────
+📂 FILE STRUCTURE
+───────────────────────────────────────────────────────
+
+.specweave/docs/internal/specs/
+├── _epics/                     {if epic created}
+│   └── {EPIC-ID}/
+│       └── EPIC.md
+├── _features/
+│   └── {FS-ID}/
+│       └── FEATURE.md          ← Cross-project feature
+└── {project}/                  ← Per-project stories
+    └── {FS-ID}/
+        ├── README.md            ← Project context
+        ├── us-001-{title}.md    ← User story 1
+        ├── us-002-{title}.md    ← User story 2
+        └── ...
+
+───────────────────────────────────────────────────────
+🎯 WHAT THIS SYNC DID
+───────────────────────────────────────────────────────
+
+✅ Parsed increment spec.md
+✅ Detected Epic mapping (if applicable)
+✅ Detected Feature mapping (FS-YY-MM-DD pattern)
+✅ Classified content by project
+✅ Generated hierarchical structure
+✅ Created bidirectional links (if tasks.md exists)
+✅ Preserved external tool links (GitHub/Jira/ADO)
+
+❌ DID NOT UPDATE:
+   • Architecture decisions (ADRs)
+   • Operations docs (runbooks, deployment)
+   • Delivery docs (CI/CD, testing)
+   • Governance docs (security, compliance)
+   • Strategy docs (PRDs, roadmaps)
+
+This command ONLY syncs specs folder content!
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## STEP 5: Next Steps Guidance
+
+```
+🎯 NEXT STEPS
+───────────────────────────────────────────────────────
+
+1. Review generated specs:
+   cd .specweave/docs/internal/specs/
+   ls -la {project}/{FS-ID}/
+
+2. Verify bidirectional links (if applicable):
+   • Check tasks.md has "User Story:" links
+   • Check user stories have "Implementation:" sections
+
+3. Sync to external tools (if configured):
+   {if GitHub configured}
+   • GitHub: /specweave-github:sync-spec
+   {/if}
+   {if Jira configured}
+   • Jira: /specweave-jira:sync-spec
+   {/if}
+   {if ADO configured}
+   • Azure DevOps: /specweave-ado:sync-spec
+   {/if}
+
+4. Update other docs (if needed):
+   • Full sync: /specweave:sync-docs
+   • Architecture only: Update ADRs manually
+   • Operations only: Update runbooks manually
+
+5. Commit changes:
+   git add .specweave/docs/internal/specs/
+   git commit -m "docs: sync specs from increment {increment_id}"
+```
+
+---
+
+## ERROR HANDLING
+
+### Error: Increment Not Found
+```
+❌ Error: Increment '{increment_id}' not found
+
+Available increments:
+  {list .specweave/increments/*/}
+
+Usage: /specweave:sync-specs [increment_id] [--dry-run]
+```
+
+### Error: No Spec File
+```
+❌ Error: No spec.md in increment '{increment_id}'
+
+The increment must have a spec.md file to sync specs.
+Check: .specweave/increments/{increment_id}/spec.md
+
+Cannot proceed with specs sync.
+```
+
+### Error: Distribution Failed
+```
+❌ Error: Failed to distribute specs
+
+Reason: {error message}
+
+Common causes:
+  • Invalid spec.md format
+  • Missing user stories
+  • Corrupted YAML frontmatter
+
+Try: /specweave:validate {increment_id}
+```
+
+---
+
+## OPTIONS
+
+### --dry-run
+Show what would be synced without making changes:
+
+```bash
+/specweave:sync-specs 0031 --dry-run
+```
+
+Output:
+```
+🔍 DRY RUN MODE - No files will be modified
+
+Would create/update:
+  • Epic: _epics/EPIC-2025-Q1/EPIC.md
+  • Feature: _features/FS-25-11-14/FEATURE.md
+  • Project context: backend/FS-25-11-14/README.md
+  • User story: backend/FS-25-11-14/us-001-api-sync.md
+  • User story: backend/FS-25-11-14/us-002-status-mapping.md
+  • Tasks.md: Would add 5 user story links
+
+Total: 6 files would be affected
+```
+
+### --force
+Overwrite existing files without prompting:
+
+```bash
+/specweave:sync-specs 0031 --force
+```
+
+---
+
+## EXAMPLES
+
+### Example 1: Sync Current Increment
+```
+User: /specweave:sync-specs
+
+Output:
+🎯 Target increment: 0031-external-tool-status-sync
+📁 Increment path: .specweave/increments/0031-external-tool-status-sync
+🔄 Mode: Specs-only sync (Universal Hierarchy)
+
+Processing...
+✅ Distribution successful!
+   📊 Total stories: 7
+   📁 Total files created: 10
+   🎯 Feature ID: FS-25-11-14-external-tool-status-sync
+```
+
+### Example 2: Sync Specific Increment
+```
+User: /specweave:sync-specs 0025
+
+Output:
+🎯 Target increment: 0025-per-project-resource-config
+📁 Increment path: .specweave/increments/0025-per-project-resource-config
+🔄 Mode: Specs-only sync (Universal Hierarchy)
+
+Processing...
+✅ Distribution successful!
+   📊 Total stories: 3
+   📁 Total files created: 5
+```
+
+### Example 3: Dry Run
+```
+User: /specweave:sync-specs 0031 --dry-run
+
+Output:
+🔍 DRY RUN MODE - No files will be modified
+
+Would sync increment: 0031-external-tool-status-sync
+Would create feature: FS-25-11-14-external-tool-status-sync
+Would affect 2 projects: backend, frontend
+Would create 7 user stories
+Would update tasks.md with bidirectional links
+
+No changes made (dry run mode)
+```
+
+---
+
+## IMPORTANT NOTES
+
+1. **Specs-only**: This command ONLY updates `.specweave/docs/internal/specs/` folder
+2. **Universal Hierarchy**: Uses Epic → Feature → User Story → Task structure
+3. **Bidirectional Links**: Automatically creates if tasks.md exists
+4. **Project-aware**: Distributes stories to correct project folders
+5. **Non-destructive**: Creates backups before overwriting (unless --force)
+6. **External Links**: Preserves GitHub/Jira/ADO links from metadata.json
+
+---
+
+## WHEN TO USE THIS COMMAND
+
+✅ **Use `/specweave:sync-specs` when**:
+- You only want to update user stories and features
+- You've made changes to spec.md and want them in living docs
+- You want to preserve existing architecture/operations docs
+- You need quick spec sync without full documentation update
+
+❌ **Use `/specweave:sync-docs` instead when**:
+- You want to update ALL documentation areas
+- You have new architecture decisions (ADRs)
+- You updated operations/deployment docs
+- You need comprehensive documentation sync
+
+---
+
+**You are now ready to execute this specs-only sync command. Follow the steps above precisely.**

package/plugins/specweave/hooks/hooks.json

@@ -3,6 +3,10 @@
     "UserPromptSubmit": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-command-deduplication.sh"
+          },
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh"

package/plugins/specweave/hooks/lib/sync-spec-content.sh

@@ -109,7 +109,7 @@ if [[ ! "$PROVIDER" =~ ^(github|jira|ado)$ ]]; then
 fi
 
 # Check if sync CLI command exists
-SYNC_CLI="$PROJECT_ROOT/dist/cli/commands/sync-spec-content.js"
+SYNC_CLI="$PROJECT_ROOT/dist/src/cli/commands/sync-spec-content.js"
 if [ ! -f "$SYNC_CLI" ]; then
   echo "ℹ️  Sync CLI not built, skipping spec content sync" >&2
   echo "   Run: npm run build" >&2
@@ -141,7 +141,7 @@ else
   echo ""
   echo "⚠️  Spec content sync failed (exit code: $SYNC_EXIT_CODE)" >&2
   echo "   This is non-blocking. You can sync manually later:" >&2
-  echo "   node dist/cli/commands/sync-spec-content.js --spec \"$SPEC_PATH\" --provider $PROVIDER" >&2
+  echo "   node dist/src/cli/commands/sync-spec-content.js --spec \"$SPEC_PATH\" --provider $PROVIDER" >&2
   echo ""
   # Non-blocking: continue execution even if sync fails
 fi

package/plugins/specweave/hooks/post-task-completion.sh

@@ -229,6 +229,45 @@ if command -v node &> /dev/null; then
   fi
 fi
 
+# ============================================================================
+# UPDATE AC STATUS (NEW in v0.18.3 - Acceptance Criteria Checkbox Update)
+# ============================================================================
+# Updates acceptance criteria checkboxes in spec.md based on completed tasks
+# - Extracts AC-IDs from completed tasks (AC-US1-01, AC-US1-02, etc.)
+# - Checks off corresponding AC in spec.md
+# - Ensures external tool sync reflects current AC completion status
+
+if command -v node &> /dev/null; then
+  if [ -n "$CURRENT_INCREMENT" ]; then
+    echo "[$(date)] ✓ Updating AC status for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Determine which AC update script to use (project local or global)
+    UPDATE_AC_SCRIPT=""
+    if [ -f "$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/update-ac-status.js" ]; then
+      # Development: Use project's compiled files (has node_modules)
+      UPDATE_AC_SCRIPT="$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/update-ac-status.js"
+      echo "[$(date)]   Using local dist: $UPDATE_AC_SCRIPT" >> "$DEBUG_LOG" 2>/dev/null || true
+    elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/update-ac-status.js" ]; then
+      # Installed as dependency: Use node_modules version
+      UPDATE_AC_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/update-ac-status.js"
+      echo "[$(date)]   Using node_modules: $UPDATE_AC_SCRIPT" >> "$DEBUG_LOG" 2>/dev/null || true
+    elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/lib/hooks/update-ac-status.js" ]; then
+      # Fallback: Plugin marketplace (may fail if deps missing)
+      UPDATE_AC_SCRIPT="${CLAUDE_PLUGIN_ROOT}/lib/hooks/update-ac-status.js"
+      echo "[$(date)]   Using plugin marketplace: $UPDATE_AC_SCRIPT" >> "$DEBUG_LOG" 2>/dev/null || true
+    fi
+
+    if [ -n "$UPDATE_AC_SCRIPT" ]; then
+      # Run AC status update (non-blocking, best-effort)
+      (cd "$PROJECT_ROOT" && node "$UPDATE_AC_SCRIPT" "$CURRENT_INCREMENT") 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+        echo "[$(date)] ⚠️  Failed to update AC status (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+      }
+    else
+      echo "[$(date)] ⚠️  update-ac-status.js not found in any location" >> "$DEBUG_LOG" 2>/dev/null || true
+    fi
+  fi
+fi
+
 # ============================================================================
 # TRANSLATE LIVING DOCS (NEW in v0.6.0 - i18n)
 # ============================================================================

package/plugins/specweave/hooks/pre-command-deduplication.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+
+# SpecWeave Pre-Command Deduplication Hook
+# Fires BEFORE any command executes (UserPromptSubmit hook)
+# Purpose: Prevent duplicate command invocations within configurable time window
+
+set -euo pipefail
+
+# ==============================================================================
+# PROJECT ROOT DETECTION
+# ==============================================================================
+
+# Find project root by searching upward for .specweave/ directory
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# Read input JSON from stdin
+INPUT=$(cat)
+
+# ==============================================================================
+# DEDUPLICATION CHECK: Block duplicate commands within 1 second
+# ==============================================================================
+
+# Check if deduplication module is available
+if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/deduplication/command-deduplicator.js" ]]; then
+  # Use dedicated wrapper script for ES module compatibility
+  DEDUP_RESULT=$(echo "$INPUT" | node scripts/check-deduplication.js 2>/dev/null || echo "OK")
+
+  # Parse result
+  STATUS=$(echo "$DEDUP_RESULT" | head -1)
+
+  if [[ "$STATUS" == "DUPLICATE" ]]; then
+    # Get stats
+    STATS=$(echo "$DEDUP_RESULT" | tail -1)
+
+    # Extract command and stats for readable message
+    COMMAND=$(echo "$STATS" | grep -o '"lastCommand":"[^"]*"' | cut -d'"' -f4 || echo "unknown")
+    TOTAL_BLOCKED=$(echo "$STATS" | grep -o '"totalDuplicatesBlocked":[0-9]*' | cut -d':' -f2 || echo "1")
+    CACHE_SIZE=$(echo "$STATS" | grep -o '"currentCacheSize":[0-9]*' | cut -d':' -f2 || echo "1")
+
+    # Build error message WITHOUT embedding JSON (avoid escaping issues)
+    MESSAGE=$(cat <<'EOF'
+{
+  "decision": "block",
+  "reason": "🚫 DUPLICATE COMMAND DETECTED\n\nCommand: `COMMAND_PLACEHOLDER`\nTime window: 1 second\n\nThis command was just executed! To prevent unintended duplicates, this invocation has been blocked.\n\n💡 If you meant to run this command again:\n  1. Wait 1 second\n  2. Run the command again\n\nDeduplication Stats:\n- Total duplicates blocked: BLOCKED_PLACEHOLDER\n- Commands in cache: CACHE_PLACEHOLDER"
+}
+EOF
+)
+    # Replace placeholders (avoids JSON escaping issues)
+    # Use | as sed delimiter to avoid conflicts with / in command names
+    echo "$MESSAGE" | sed "s|COMMAND_PLACEHOLDER|$COMMAND|g" | sed "s|BLOCKED_PLACEHOLDER|$TOTAL_BLOCKED|g" | sed "s|CACHE_PLACEHOLDER|$CACHE_SIZE|g"
+    exit 0
+  fi
+fi
+
+# ==============================================================================
+# PASS THROUGH: No duplicate detected, proceed with command
+# ==============================================================================
+
+cat <<EOF
+{
+  "decision": "approve"
+}
+EOF
+
+exit 0

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

@@ -26,7 +26,7 @@ if echo "$PROMPT" | grep -q "/specweave:increment"; then
 
   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/cli/index.js" ]]; then
+    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 {

package/plugins/specweave/lib/hooks/sync-living-docs.js

@@ -77,6 +77,8 @@ async function hierarchicalDistribution(incrementId) {
         console.log(`      - ${warning}`);
       }
     }
+    console.log("   \u{1F4CA} Updating acceptance criteria status from completed tasks...");
+    await distributor.updateAcceptanceCriteriaStatus(incrementId);
     const changedFiles = [result.epicPath, ...result.userStoryPaths];
     return {
       success: true,

package/plugins/specweave/lib/hooks/sync-living-docs.ts

@@ -176,6 +176,10 @@ async function hierarchicalDistribution(
       }
     }
 
+    // Update acceptance criteria status based on completed tasks
+    console.log('   📊 Updating acceptance criteria status from completed tasks...');
+    await distributor.updateAcceptanceCriteriaStatus(incrementId);
+
     // Collect changed file paths
     const changedFiles = [result.epicPath, ...result.userStoryPaths];