specweave 0.18.0 → 0.20.0

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];
 

package/plugins/specweave/lib/hooks/update-ac-status.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import * as fs from "fs/promises";
+import * as path from "path";
+async function updateACStatus(incrementId) {
+  try {
+    const projectRoot = process.cwd();
+    const incrementPath = path.join(projectRoot, ".specweave/increments", incrementId);
+    try {
+      await fs.access(incrementPath);
+    } catch {
+      console.error(`\u274C Increment ${incrementId} not found at ${incrementPath}`);
+      return;
+    }
+    console.log(`\u{1F504} Updating AC status for increment ${incrementId}...`);
+    const completedACs = await extractCompletedACsFromTasks(incrementPath);
+    if (completedACs.size === 0) {
+      console.log(`\u2139\uFE0F  No completed tasks with AC-IDs found in tasks.md`);
+      return;
+    }
+    console.log(`\u2713 Found ${completedACs.size} completed AC-IDs from tasks.md`);
+    const updatedCount = await updateSpecACCheckboxes(incrementPath, completedACs);
+    if (updatedCount > 0) {
+      console.log(`\u2705 Updated ${updatedCount} AC checkbox(es) in spec.md`);
+    } else {
+      console.log(`\u2139\uFE0F  No AC checkboxes needed updating in spec.md`);
+    }
+  } catch (error) {
+    console.error("\u274C Error updating AC status:", error);
+  }
+}
+async function extractCompletedACsFromTasks(incrementPath) {
+  const tasksPath = path.join(incrementPath, "tasks.md");
+  const completedACs = /* @__PURE__ */ new Set();
+  try {
+    const tasksContent = await fs.readFile(tasksPath, "utf-8");
+    const taskSections = tasksContent.split(/^(###+)\s+T-\d+:/gm);
+    for (let i = 1; i < taskSections.length; i += 2) {
+      const taskContent = taskSections[i + 1];
+      const statusMatch = taskContent.match(/\*\*Status\*\*:\s*\[x\]/i);
+      if (!statusMatch) continue;
+      const acMatch = taskContent.match(/\*\*AC\*\*:\s*([^\n]+)/);
+      if (!acMatch) continue;
+      const acField = acMatch[1];
+      const acIds = acField.split(",").map((id) => id.trim()).filter((id) => /^AC-[A-Z0-9]+-\d+$/.test(id));
+      acIds.forEach((acId) => completedACs.add(acId));
+    }
+    return completedACs;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      console.log(`\u2139\uFE0F  tasks.md not found, skipping AC update`);
+    } else {
+      console.error("Error reading tasks.md:", error);
+    }
+    return completedACs;
+  }
+}
+async function updateSpecACCheckboxes(incrementPath, completedACs) {
+  const specPath = path.join(incrementPath, "spec.md");
+  try {
+    let specContent = await fs.readFile(specPath, "utf-8");
+    let updatedCount = 0;
+    const acPattern = /^(\s*)-\s+\[([ x])\]\s+\*\*([A-Z]+-[A-Z0-9]+-\d+)\*\*:(.*)$/gm;
+    specContent = specContent.replace(acPattern, (match, indent, currentState, acId, description) => {
+      const shouldBeChecked = completedACs.has(acId);
+      const isCurrentlyChecked = currentState === "x";
+      if (shouldBeChecked && !isCurrentlyChecked) {
+        updatedCount++;
+        return `${indent}- [x] **${acId}**:${description}`;
+      } else if (!shouldBeChecked && isCurrentlyChecked) {
+        updatedCount++;
+        return `${indent}- [ ] **${acId}**:${description}`;
+      }
+      return match;
+    });
+    if (updatedCount > 0) {
+      await fs.writeFile(specPath, specContent, "utf-8");
+    }
+    return updatedCount;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      console.log(`\u2139\uFE0F  spec.md not found, skipping AC update`);
+    } else {
+      console.error("Error updating spec.md:", error);
+    }
+    return 0;
+  }
+}
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const incrementId = process.argv[2];
+  if (!incrementId) {
+    console.error("Usage: node update-ac-status.js <increment-id>");
+    console.error("Example: node update-ac-status.js 0031-external-tool-status-sync");
+    process.exit(1);
+  }
+  updateACStatus(incrementId).then(() => {
+    process.exit(0);
+  }).catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  });
+}

package/plugins/specweave/lib/hooks/update-ac-status.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+
+/**
+ * AC Status Update Hook
+ *
+ * Updates acceptance criteria checkboxes in spec.md based on completed tasks.
+ *
+ * Flow:
+ * 1. Read tasks.md → Extract completed tasks
+ * 2. Extract AC-IDs from **AC**: field (e.g., AC-US1-01, AC-US1-02)
+ * 3. Read spec.md → Find all AC checkboxes
+ * 4. Check off AC if task implementing it is complete
+ * 5. Write updated spec.md
+ *
+ * Called by: plugins/specweave/hooks/post-task-completion.sh
+ *
+ * Example:
+ * - Task T-001: [x] Completed, **AC**: AC-US1-01, AC-US1-02
+ * - spec.md: - [ ] **AC-US1-01**: ... → - [x] **AC-US1-01**: ... ✅
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+interface ACStatus {
+  acId: string;
+  isComplete: boolean;
+  completedByTasks: string[];
+}
+
+/**
+ * Main entry point
+ */
+async function updateACStatus(incrementId: string): Promise<void> {
+  try {
+    const projectRoot = process.cwd();
+    const incrementPath = path.join(projectRoot, '.specweave/increments', incrementId);
+
+    // Verify increment exists
+    try {
+      await fs.access(incrementPath);
+    } catch {
+      console.error(`❌ Increment ${incrementId} not found at ${incrementPath}`);
+      return;
+    }
+
+    console.log(`🔄 Updating AC status for increment ${incrementId}...`);
+
+    // Step 1: Extract completed ACs from tasks.md
+    const completedACs = await extractCompletedACsFromTasks(incrementPath);
+
+    if (completedACs.size === 0) {
+      console.log(`ℹ️  No completed tasks with AC-IDs found in tasks.md`);
+      return;
+    }
+
+    console.log(`✓ Found ${completedACs.size} completed AC-IDs from tasks.md`);
+
+    // Step 2: Update spec.md checkboxes
+    const updatedCount = await updateSpecACCheckboxes(incrementPath, completedACs);
+
+    if (updatedCount > 0) {
+      console.log(`✅ Updated ${updatedCount} AC checkbox(es) in spec.md`);
+    } else {
+      console.log(`ℹ️  No AC checkboxes needed updating in spec.md`);
+    }
+  } catch (error) {
+    console.error('❌ Error updating AC status:', error);
+    // Non-blocking: Don't throw, just log
+  }
+}
+
+/**
+ * Extract AC-IDs from completed tasks in tasks.md
+ */
+async function extractCompletedACsFromTasks(incrementPath: string): Promise<Set<string>> {
+  const tasksPath = path.join(incrementPath, 'tasks.md');
+  const completedACs = new Set<string>();
+
+  try {
+    const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+
+    // Pattern: Match tasks with completed status and AC field
+    // Example:
+    // ### T-001: Task Title
+    // **Status**: [x] (100% - Completed)
+    // **AC**: AC-US1-01, AC-US1-02, AC-US1-03
+
+    // Split by task headings (## or ###)
+    const taskSections = tasksContent.split(/^(###+)\s+T-\d+:/gm);
+
+    for (let i = 1; i < taskSections.length; i += 2) {
+      const taskContent = taskSections[i + 1];
+
+      // Check if task is completed
+      const statusMatch = taskContent.match(/\*\*Status\*\*:\s*\[x\]/i);
+      if (!statusMatch) continue;
+
+      // Extract AC-IDs from **AC**: field
+      const acMatch = taskContent.match(/\*\*AC\*\*:\s*([^\n]+)/);
+      if (!acMatch) continue;
+
+      const acField = acMatch[1]; // "AC-US1-01, AC-US1-02, AC-US1-03"
+      const acIds = acField
+        .split(',')
+        .map(id => id.trim())
+        .filter(id => /^AC-[A-Z0-9]+-\d+$/.test(id)); // Validate format
+
+      acIds.forEach(acId => completedACs.add(acId));
+    }
+
+    return completedACs;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      console.log(`ℹ️  tasks.md not found, skipping AC update`);
+    } else {
+      console.error('Error reading tasks.md:', error);
+    }
+    return completedACs;
+  }
+}
+
+/**
+ * Update AC checkboxes in spec.md
+ */
+async function updateSpecACCheckboxes(
+  incrementPath: string,
+  completedACs: Set<string>
+): Promise<number> {
+  const specPath = path.join(incrementPath, 'spec.md');
+
+  try {
+    let specContent = await fs.readFile(specPath, 'utf-8');
+    let updatedCount = 0;
+
+    // Pattern: - [ ] **AC-US1-01**: Description
+    // Captures: indent, checkbox state, AC-ID, rest of line
+    const acPattern = /^(\s*)-\s+\[([ x])\]\s+\*\*([A-Z]+-[A-Z0-9]+-\d+)\*\*:(.*)$/gm;
+
+    specContent = specContent.replace(acPattern, (match, indent, currentState, acId, description) => {
+      const shouldBeChecked = completedACs.has(acId);
+      const isCurrentlyChecked = currentState === 'x';
+
+      if (shouldBeChecked && !isCurrentlyChecked) {
+        // Check off this AC
+        updatedCount++;
+        return `${indent}- [x] **${acId}**:${description}`;
+      } else if (!shouldBeChecked && isCurrentlyChecked) {
+        // Uncheck this AC (task was un-completed?)
+        updatedCount++;
+        return `${indent}- [ ] **${acId}**:${description}`;
+      }
+
+      return match; // No change needed
+    });
+
+    if (updatedCount > 0) {
+      await fs.writeFile(specPath, specContent, 'utf-8');
+    }
+
+    return updatedCount;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      console.log(`ℹ️  spec.md not found, skipping AC update`);
+    } else {
+      console.error('Error updating spec.md:', error);
+    }
+    return 0;
+  }
+}
+
+// CLI Entry Point (ES Module)
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+
+if (isMainModule) {
+  const incrementId = process.argv[2];
+
+  if (!incrementId) {
+    console.error('Usage: node update-ac-status.js <increment-id>');
+    console.error('Example: node update-ac-status.js 0031-external-tool-status-sync');
+    process.exit(1);
+  }
+
+  updateACStatus(incrementId)
+    .then(() => {
+      process.exit(0);
+    })
+    .catch((error) => {
+      console.error('Fatal error:', error);
+      process.exit(1);
+    });
+}

package/plugins/specweave/skills/archive-increments/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: archive-increments
+description: Intelligent increment archiving expert. Analyzes increment age, status, and activity to recommend archiving strategy. Keeps workspace clean while preserving history. Activates for archive increments, clean workspace, too many increments, archive old, archive completed, preserve history, _archive folder.
+---
+
+# Increment Archive Manager
+
+Expert at keeping the `.specweave/increments/` folder clean and organized through intelligent archiving.
+
+## Core Knowledge
+
+### Archiving Philosophy
+
+**The 10-10-10 Rule**:
+- **10 Active**: Keep last 10 increments readily accessible
+- **10 Days**: Archive increments inactive for >10 days
+- **10 Seconds**: Archive operation should take <10 seconds
+
+### Archive Structure
+
+```
+.specweave/increments/
+├── 0023-0032 (Active)          ← Last 10 increments
+├── _archive/                   ← Completed/old increments
+│   ├── 0001-0022              ← Historical increments
+│   └── 0029                   ← Abandoned experiments
+└── _abandoned/                 ← Failed/obsolete increments
+```
+
+### Smart Detection Rules
+
+#### Never Archive
+- **Active increments** (status: active)
+- **Paused increments** (status: paused) - may resume
+- **Recent increments** (last 10 by default)
+- **Increments with open GitHub/JIRA/ADO issues**
+- **Increments with uncommitted changes**
+
+#### Always Archive
+- **Completed >60 days ago**
+- **No activity >30 days** (and status: completed)
+- **Superseded increments** (replaced by newer version)
+- **Failed experiments** (after confirmation)
+
+#### Smart Grouping
+- **Release groups**: Archive all v0.7.x after v0.8.0 ships
+- **Feature groups**: Archive related increments together
+- **Time-based**: Quarter/month-based archiving
+
+## Usage Patterns
+
+### Keep Workspace Clean
+```bash
+# Interactive archiving - prompts for confirmation
+/specweave:archive-increments
+
+# Keep only last 5 increments
+/specweave:archive-increments --keep-last 5
+
+# Archive all completed increments
+/specweave:archive-increments --archive-completed
+```
+
+### Prepare for Release
+```bash
+# Archive all pre-release increments
+/specweave:archive-increments --pattern "v0.7"
+
+# Archive by date range
+/specweave:archive-increments --older-than 30d
+```
+
+### Restore from Archive
+```bash
+# List archived increments
+/specweave:archive-increments --list-archived
+
+# Restore specific increment
+/specweave:archive-increments --restore 0015
+```
+
+## Configuration
+
+### Default Settings
+```json
+{
+  "archiving": {
+    "keepLast": 10,              // Keep last 10 increments
+    "autoArchive": false,        // Manual by default
+    "archiveAfterDays": 60,      // Archive after 60 days
+    "preserveActive": true,      // Never archive active
+    "archiveCompleted": false    // Manual control
+  }
+}
+```
+
+### Aggressive Cleanup
+```json
+{
+  "archiving": {
+    "keepLast": 5,               // Minimal workspace
+    "autoArchive": true,         // Auto-archive on completion
+    "archiveAfterDays": 14,      // Archive after 2 weeks
+    "archiveCompleted": true     // Auto-archive completed
+  }
+}
+```
+
+## Archive Statistics
+
+### Current State Analysis
+When asked about archiving, I analyze:
+- Number of active increments
+- Age of oldest active increment
+- Total size of increments folder
+- Number of completed increments
+- External sync status
+
+### Recommendations
+Based on analysis, I suggest:
+- **Overcrowded** (>20 active): Archive all but last 10
+- **Stale** (many >30 days old): Archive by age
+- **Post-release**: Archive previous version increments
+- **Large size** (>100MB): Archive largest completed increments
+
+## Safety Features
+
+### Pre-Archive Checks
+1. **Metadata validation**: Check increment status
+2. **External sync**: Verify no open issues
+3. **Git status**: Check for uncommitted changes
+4. **Dependencies**: Check if referenced by active increments
+5. **User confirmation**: Show what will be archived
+
+### Archive Operations
+- **Atomic moves**: Use fs.move with overwrite protection
+- **Preserve structure**: Maintain full increment structure
+- **Update references**: Fix links in living docs
+- **Reversible**: Easy restore from archive
+- **Audit trail**: Log all archive operations
+
+## Smart Suggestions
+
+### When to Archive
+- **After major release**: Archive all pre-release increments
+- **Quarterly cleanup**: Archive increments >3 months old
+- **Before new project phase**: Archive previous phase work
+- **Low disk space**: Archive largest completed increments
+
+### Archive Patterns
+- **By version**: `--pattern "v0.7"` (all v0.7.x increments)
+- **By feature**: `--pattern "auth|login"` (auth-related)
+- **By date**: `--older-than 30d` (time-based)
+- **By status**: `--archive-completed` (all completed)
+
+## Integration Points
+
+### Status Line
+- Shows "23-32 (10 active, 22 archived)" format
+- Warns when >15 active increments
+- Suggests archiving when appropriate
+
+### Increment Commands
+- `/specweave:done` can trigger auto-archive
+- `/specweave:status` shows archive statistics
+- `/specweave:next` considers archived increments
+
+### Living Docs
+- Archive preserves living docs references
+- Restore updates living docs links
+- Archive included in docs statistics
+
+## Best Practices
+
+1. **Regular Cleanup**: Archive monthly or after releases
+2. **Keep Recent**: Always keep last 5-10 increments
+3. **Preserve Active**: Never force-archive active work
+4. **Group Related**: Archive feature groups together
+5. **Document Reasons**: Add archive notes for context
+
+## Quick Reference
+
+```bash
+# Archive old increments
+/specweave:archive-increments --older-than 30d
+
+# Keep workspace minimal
+/specweave:archive-increments --keep-last 5
+
+# Archive after release
+/specweave:archive-increments --pattern "pre-release"
+
+# Restore for reference
+/specweave:archive-increments --restore 0015
+
+# Check archive stats
+/specweave:archive-increments --stats
+```

package/plugins/specweave/skills/increment-planner/scripts/feature-utils.js

@@ -59,8 +59,15 @@ function generateShortName(description) {
  * Get the next available feature number
  * @param {string} featuresDir - Path to features directory (default: '.specweave/increments')
  * @returns {string} Next feature number (zero-padded to 4 digits: 0001-9999)
+ *
+ * NOTE: This function is DEPRECATED. Use IncrementNumberManager from src/core/increment-utils.ts instead.
+ * Kept for backward compatibility with existing scripts.
  */
 function getNextFeatureNumber(featuresDir = '.specweave/increments') {
+  // DEPRECATED: For backward compatibility only
+  // The NEW implementation scans ALL directories (_archive, _abandoned, _paused)
+  // To use the new implementation, import IncrementNumberManager from src/core/increment-utils.ts
+
   let highest = 0;
 
   if (fs.existsSync(featuresDir)) {
@@ -104,8 +111,15 @@ function featureExists(shortName, featuresDir = '.specweave/increments') {
  * @param {string} incrementNumber - Increment number to check (e.g., '0001')
  * @param {string} featuresDir - Path to features directory
  * @returns {boolean} True if number already exists
+ *
+ * NOTE: This function is DEPRECATED. Use IncrementNumberManager.incrementNumberExists() instead.
+ * Kept for backward compatibility with existing scripts.
  */
 function incrementNumberExists(incrementNumber, featuresDir = '.specweave/increments') {
+  // DEPRECATED: For backward compatibility only
+  // The NEW implementation scans ALL directories (_archive, _abandoned, _paused)
+  // To use the new implementation, import IncrementNumberManager from src/core/increment-utils.ts
+
   if (!fs.existsSync(featuresDir)) {
     return false;
   }