specweave 0.17.17 → 0.17.19

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

@@ -0,0 +1,86 @@
+#!/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
+
+# Read input JSON from stdin
+INPUT=$(cat)
+
+# Extract prompt from JSON
+PROMPT=$(echo "$INPUT" | node -e "
+  const input = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+  console.log(input.prompt || '');
+")
+
+# ==============================================================================
+# DEDUPLICATION CHECK: Block duplicate commands within 1 second
+# ==============================================================================
+
+# Extract command name from prompt (if slash command)
+COMMAND=$(echo "$PROMPT" | grep -oE "^/[a-z0-9:-]+" | head -1 || echo "")
+
+if [[ -n "$COMMAND" ]]; then
+  # Check deduplication using TypeScript module
+  if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/deduplication/command-deduplicator.js" ]]; then
+    # Run deduplication check
+    DEDUP_RESULT=$(node -e "
+      (async () => {
+        try {
+          const { CommandDeduplicator } = require('./dist/src/core/deduplication/command-deduplicator.js');
+          const dedup = new CommandDeduplicator({ debug: false });
+
+          // Parse command and args
+          const fullCommand = '${COMMAND}';
+          const args = '${PROMPT}'.replace(fullCommand, '').trim().split(/\\s+/).filter(Boolean);
+
+          // Check for duplicate
+          const isDuplicate = await dedup.checkDuplicate(fullCommand, args);
+
+          if (isDuplicate) {
+            const stats = dedup.getStats();
+            console.log('DUPLICATE');
+            console.log(JSON.stringify(stats));
+          } else {
+            // Record invocation
+            await dedup.recordInvocation(fullCommand, args);
+            console.log('OK');
+          }
+        } catch (e) {
+          console.error('Error in deduplication:', e.message);
+          console.log('OK'); // Fail-open (don't block on errors)
+        }
+      })();
+    " 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)
+
+      cat <<EOF
+{
+  "decision": "block",
+  "reason": "🚫 DUPLICATE COMMAND DETECTED\\n\\nCommand: \`$COMMAND\`\\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\\n📊 Deduplication Stats:\\n$STATS\\n\\n🔧 To adjust the time window, edit \`.specweave/config.json\`:\\n\`\`\`json\\n{\\n  \\\"deduplication\\\": {\\n    \\\"windowMs\\\": 2000  // Increase to 2 seconds\\n  }\\n}\\n\`\`\`"
+}
+EOF
+      exit 0
+    fi
+  fi
+fi
+
+# ==============================================================================
+# PASS THROUGH: No duplicate detected, proceed with command
+# ==============================================================================
+
+cat <<EOF
+{
+  "decision": "approve"
+}
+EOF
+
+exit 0

package/plugins/specweave-ado/commands/specweave-ado-sync-spec.md

@@ -1,5 +1,5 @@
 ---
-name: specweave-ado-sync-spec
+name: specweave-ado:sync-spec
 description: Sync SpecWeave spec to Azure DevOps Feature (bidirectional). Use when syncing .specweave/docs/internal/specs/spec-*.md files with ADO Features for permanent feature tracking.
 ---
 

package/plugins/specweave-ado/lib/ado-spec-content-sync.js

@@ -4,8 +4,9 @@ import {
   hasExternalLink,
   updateSpecWithExternalLink
 } from "../../../src/core/spec-content-sync.js";
-import path from "path";
-import fs from "fs/promises";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import * as path from "path";
+import * as fs from "fs/promises";
 async function syncSpecContentToAdo(options) {
   const { specPath, client, dryRun = false, verbose = false } = options;
   try {
@@ -44,8 +45,9 @@ async function syncSpecContentToAdo(options) {
 async function createAdoFeature(client, spec, options) {
   const { specPath, dryRun, verbose } = options;
   try {
+    const tasks = await getTaskMappings(specPath, spec.id);
     const title = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const description = buildAdoDescription(spec);
+    const description = buildAdoDescription(spec, tasks);
     if (verbose) {
       console.log(`
 \u{1F4DD} Creating ADO feature:`);
@@ -125,8 +127,9 @@ async function updateAdoFeature(client, spec, workItemId, options) {
         console.log(`      - ${change}`);
       }
     }
+    const tasks = await getTaskMappings(specPath, spec.id);
     const newTitle = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const newDescription = buildAdoDescription(spec);
+    const newDescription = buildAdoDescription(spec, tasks);
     if (dryRun) {
       console.log("\n\u{1F50D} Dry run - would update feature:");
       console.log(`   Title: ${newTitle}`);
@@ -160,7 +163,7 @@ ${newDescription}`);
     };
   }
 }
-function buildAdoDescription(spec) {
+function buildAdoDescription(spec, tasks) {
   let html = "";
   if (spec.description) {
     html += `<p>${escapeHtml(spec.description)}</p>`;
@@ -179,11 +182,52 @@ function buildAdoDescription(spec) {
       }
     }
   }
+  if (tasks && tasks.length > 0) {
+    html += "<h2>Implementation Tasks</h2>";
+    html += "<ul>";
+    for (const task of tasks) {
+      html += `<li><strong>${task.id}</strong>: ${escapeHtml(task.title)}`;
+      if (task.userStories && task.userStories.length > 0) {
+        html += ` (${task.userStories.join(", ")})`;
+      }
+      html += "</li>";
+    }
+    html += "</ul>";
+  }
   if (spec.metadata.priority) {
     html += `<p><strong>Priority:</strong> ${spec.metadata.priority}</p>`;
   }
   return html;
 }
+async function getTaskMappings(specPath, specId) {
+  try {
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+    if (mapping.increments.length > 0) {
+      return mapping.increments[0].tasks;
+    }
+    return void 0;
+  } catch (error) {
+    return void 0;
+  }
+}
+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 escapeHtml(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
 }

package/plugins/specweave-ado/lib/ado-spec-content-sync.ts

@@ -20,8 +20,9 @@ import {
   ContentSyncResult,
 } from '../../../src/core/spec-content-sync.js';
 import { SyncProfile } from '../../../src/core/types/sync-profile.js';
-import path from 'path';
-import fs from 'fs/promises';
+import { SpecIncrementMapper, TaskInfo } from '../../../src/core/sync/spec-increment-mapper.js';
+import * as path from 'path';
+import * as fs from 'fs/promises';
 
 export interface AdoContentSyncOptions {
   specPath: string;
@@ -91,9 +92,12 @@ async function createAdoFeature(
   const { specPath, dryRun, verbose } = options;
 
   try {
+    // Get task mappings (if available)
+    const tasks = await getTaskMappings(specPath, spec.id);
+
     // Build feature title and description
     const title = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const description = buildAdoDescription(spec);
+    const description = buildAdoDescription(spec, tasks);
 
     if (verbose) {
       console.log(`\n📝 Creating ADO feature:`);
@@ -196,9 +200,12 @@ async function updateAdoFeature(
       }
     }
 
+    // Get task mappings (if available)
+    const tasks = await getTaskMappings(specPath, spec.id);
+
     // Build updated content
     const newTitle = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const newDescription = buildAdoDescription(spec);
+    const newDescription = buildAdoDescription(spec, tasks);
 
     if (dryRun) {
       console.log('\n🔍 Dry run - would update feature:');
@@ -242,10 +249,10 @@ async function updateAdoFeature(
 }
 
 /**
- * Build ADO description from spec content
+ * Build ADO description from spec content with optional task mappings
  * ADO supports HTML in description
  */
-function buildAdoDescription(spec: SpecContent): string {
+function buildAdoDescription(spec: SpecContent, tasks?: TaskInfo[]): string {
   let html = '';
 
   // Add spec description
@@ -271,6 +278,20 @@ function buildAdoDescription(spec: SpecContent): string {
     }
   }
 
+  // Add task mappings (if provided)
+  if (tasks && tasks.length > 0) {
+    html += '<h2>Implementation Tasks</h2>';
+    html += '<ul>';
+    for (const task of tasks) {
+      html += `<li><strong>${task.id}</strong>: ${escapeHtml(task.title)}`;
+      if (task.userStories && task.userStories.length > 0) {
+        html += ` (${task.userStories.join(', ')})`;
+      }
+      html += '</li>';
+    }
+    html += '</ul>';
+  }
+
   // Add metadata
   if (spec.metadata.priority) {
     html += `<p><strong>Priority:</strong> ${spec.metadata.priority}</p>`;
@@ -279,6 +300,51 @@ function buildAdoDescription(spec: SpecContent): string {
   return html;
 }
 
+/**
+ * Get task mappings for a spec (if available)
+ */
+async function getTaskMappings(specPath: string, specId: string): Promise<TaskInfo[] | undefined> {
+  try {
+    // Find SpecWeave root
+    const rootDir = await findSpecWeaveRoot(specPath);
+
+    // Use SpecIncrementMapper to get task mappings
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+
+    if (mapping.increments.length > 0) {
+      // Return tasks from the first (most recent) increment
+      return mapping.increments[0].tasks;
+    }
+
+    return undefined;
+  } catch (error) {
+    // If mapping fails, just return undefined (not critical)
+    return undefined;
+  }
+}
+
+/**
+ * Find SpecWeave root directory from spec path
+ */
+async function findSpecWeaveRoot(specPath: string): Promise<string> {
+  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;
+    }
+  }
+}
+
 /**
  * Escape HTML special characters
  */

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

@@ -1,5 +1,5 @@
 ---
-name: specweave-github-cleanup-duplicates
+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.
 ---
 

package/plugins/specweave-github/commands/specweave-github-sync-epic.md

@@ -1,5 +1,5 @@
 ---
-name: specweave-github-sync-epic
+name: specweave-github:sync-epic
 description: Sync SpecWeave Epic folder to GitHub (Milestone + Issues). Implements Universal Hierarchy architecture - Epic → Milestone, Increments → Issues.
 ---
 

package/plugins/specweave-github/commands/specweave-github-sync-spec.md

@@ -1,5 +1,5 @@
 ---
-name: specweave-github-sync-spec
+name: specweave-github:sync-spec
 description: Sync SpecWeave spec to GitHub Project (bidirectional). Use when syncing .specweave/docs/internal/specs/spec-*.md files with GitHub Projects for permanent feature tracking.
 ---
 

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

@@ -199,6 +199,38 @@ else
   fi
 fi
 
+# ============================================================================
+# EPIC GITHUB ISSUE SYNC (Update Epic issue with fresh task progress)
+# ============================================================================
+
+echo "[$(date)] [GitHub] 🔄 Checking for Epic GitHub issue update..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Find active increment ID
+ACTIVE_INCREMENT=$(ls -t .specweave/increments/ | grep -v '^\.' | while read inc; do
+  if [ -f ".specweave/increments/$inc/metadata.json" ]; then
+    STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' ".specweave/increments/$inc/metadata.json" 2>/dev/null | sed 's/.*"\([^"]*\)".*/\1/' || true)
+    if [ "$STATUS" = "active" ]; then
+      echo "$inc"
+      break
+    fi
+  fi
+done | head -1)
+
+if [ -n "$ACTIVE_INCREMENT" ]; then
+  echo "[$(date)] [GitHub] 🎯 Active increment: $ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Run Epic sync script (silently, errors logged to debug log)
+  if [ -f "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" ]; then
+    echo "[$(date)] [GitHub] 🚀 Updating Epic GitHub issue..." >> "$DEBUG_LOG" 2>/dev/null || true
+    "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" "$ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>&1 || true
+    echo "[$(date)] [GitHub] ✅ Epic sync complete (see logs for details)" >> "$DEBUG_LOG" 2>/dev/null || true
+  else
+    echo "[$(date)] [GitHub] ⚠️  Epic sync script not found, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+else
+  echo "[$(date)] [GitHub] ℹ️  No active increment found, skipping Epic sync" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
 # ============================================================================
 # OUTPUT TO CLAUDE
 # ============================================================================

package/plugins/specweave-github/lib/epic-content-builder.js

@@ -0,0 +1,227 @@
+import { readdir, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+class EpicContentBuilder {
+  constructor(epicFolder, projectRoot) {
+    this.epicFolder = epicFolder;
+    this.projectRoot = projectRoot;
+  }
+  /**
+   * Build hierarchical GitHub issue body
+   *
+   * Format:
+   * - Epic overview
+   * - User Stories section (checkable, with status + increment)
+   * - Tasks section (grouped by User Story)
+   */
+  async buildIssueBody() {
+    const epicData = await this.readEpicMetadata();
+    const userStories = await this.readUserStories();
+    const overview = this.buildOverviewSection(epicData);
+    const userStoriesSection = this.buildUserStoriesSection(userStories);
+    const tasksSection = this.buildTasksSection(userStories);
+    return `${overview}
+
+---
+
+${userStoriesSection}
+
+---
+
+${tasksSection}
+
+---
+
+\u{1F916} Auto-created by SpecWeave Epic Sync`;
+  }
+  /**
+   * Read Epic FEATURE.md frontmatter
+   */
+  async readEpicMetadata() {
+    const featurePath = path.join(this.epicFolder, "FEATURE.md");
+    const content = await readFile(featurePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("FEATURE.md missing YAML frontmatter");
+    }
+    return yaml.parse(match[1]);
+  }
+  /**
+   * Read all user stories from us-*.md files
+   */
+  async readUserStories() {
+    const files = await readdir(this.epicFolder);
+    const usFiles = files.filter((f) => f.startsWith("us-") && f.endsWith(".md"));
+    const userStories = [];
+    for (const file of usFiles.sort()) {
+      const filePath = path.join(this.epicFolder, file);
+      const content = await readFile(filePath, "utf-8");
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!match) {
+        console.warn(`   \u26A0\uFE0F  ${file} missing frontmatter, skipping`);
+        continue;
+      }
+      const frontmatter = yaml.parse(match[1]);
+      const bodyContent = content.slice(match[0].length).trim();
+      const incrementMatch = bodyContent.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      const increment = incrementMatch ? incrementMatch[1] : null;
+      const tasks = await this.extractTasksForUserStory(
+        frontmatter.id,
+        increment,
+        bodyContent
+      );
+      userStories.push({
+        id: frontmatter.id,
+        title: frontmatter.title,
+        status: this.normalizeStatus(frontmatter.status),
+        increment,
+        tasks
+      });
+    }
+    return userStories;
+  }
+  /**
+   * Extract tasks for a user story from its Implementation section
+   */
+  async extractTasksForUserStory(userStoryId, incrementId, content) {
+    if (!incrementId) {
+      return [];
+    }
+    const incrementFolder = path.join(
+      this.projectRoot,
+      ".specweave",
+      "increments",
+      incrementId
+    );
+    if (!existsSync(incrementFolder)) {
+      console.warn(`   \u26A0\uFE0F  Increment folder not found: ${incrementId}`);
+      return [];
+    }
+    const tasksPath = path.join(incrementFolder, "tasks.md");
+    if (!existsSync(tasksPath)) {
+      console.warn(`   \u26A0\uFE0F  tasks.md not found in ${incrementId}`);
+      return [];
+    }
+    const tasksContent = await readFile(tasksPath, "utf-8");
+    const taskLinkPattern = /- \[([T-\d]+):\s*([^\]]+)\]/g;
+    const taskLinks = [];
+    let match;
+    while ((match = taskLinkPattern.exec(content)) !== null) {
+      taskLinks.push({
+        id: match[1],
+        // e.g., "T-001"
+        title: match[2].trim()
+      });
+    }
+    const tasks = [];
+    for (const taskLink of taskLinks) {
+      const taskPattern = new RegExp(
+        `###\\s+${taskLink.id}:\\s*([^\\n]+)[\\s\\S]*?\\*\\*Status\\*\\*:\\s*\\[([x\\s])\\]`,
+        "i"
+      );
+      const taskMatch = tasksContent.match(taskPattern);
+      const isCompleted = taskMatch ? taskMatch[2] === "x" : false;
+      tasks.push({
+        id: taskLink.id,
+        title: taskLink.title,
+        status: isCompleted,
+        userStoryId
+      });
+    }
+    return tasks;
+  }
+  /**
+   * Build overview section
+   */
+  buildOverviewSection(epic) {
+    return `# [${epic.id}] ${epic.title}
+
+**Status**: ${epic.status}
+**Created**: ${epic.created}
+**Last Updated**: ${epic.last_updated}`;
+  }
+  /**
+   * Build User Stories section
+   */
+  buildUserStoriesSection(userStories) {
+    const total = userStories.length;
+    const completed = userStories.filter((us) => us.status === "complete").length;
+    const percentage = total > 0 ? Math.round(completed / total * 100) : 0;
+    let section = `## User Stories
+
+Progress: ${completed}/${total} user stories complete (${percentage}%)
+
+`;
+    for (const us of userStories) {
+      const checkbox = us.status === "complete" ? "[x]" : "[ ]";
+      const statusEmoji = this.getStatusEmoji(us.status);
+      const incrementLink = us.increment ? `[${us.increment}](../../increments/${us.increment}/)` : "TBD";
+      section += `- ${checkbox} **${us.id}: ${us.title}** (${statusEmoji} ${us.status} | Increment: ${incrementLink})
+`;
+    }
+    return section;
+  }
+  /**
+   * Build Tasks section (grouped by User Story)
+   */
+  buildTasksSection(userStories) {
+    const totalTasks = userStories.reduce((sum, us) => sum + us.tasks.length, 0);
+    const completedTasks = userStories.reduce(
+      (sum, us) => sum + us.tasks.filter((t) => t.status).length,
+      0
+    );
+    const percentage = totalTasks > 0 ? Math.round(completedTasks / totalTasks * 100) : 0;
+    let section = `## Tasks by User Story
+
+Progress: ${completedTasks}/${totalTasks} tasks complete (${percentage}%)
+
+`;
+    for (const us of userStories) {
+      if (us.tasks.length === 0) {
+        continue;
+      }
+      const incrementLink = us.increment ? `[${us.increment}](../../increments/${us.increment}/tasks.md)` : "TBD";
+      section += `### ${us.id}: ${us.title} (Increment: ${incrementLink})
+
+`;
+      for (const task of us.tasks) {
+        const checkbox = task.status ? "[x]" : "[ ]";
+        section += `- ${checkbox} ${task.id}: ${task.title}
+`;
+      }
+      section += "\n";
+    }
+    return section;
+  }
+  /**
+   * Normalize status values
+   */
+  normalizeStatus(status) {
+    const normalized = status.toLowerCase();
+    if (normalized === "complete" || normalized === "completed") return "complete";
+    if (normalized === "active" || normalized === "in-progress") return "active";
+    if (normalized === "planning") return "planning";
+    return "not-started";
+  }
+  /**
+   * Get status emoji
+   */
+  getStatusEmoji(status) {
+    switch (status) {
+      case "complete":
+        return "\u2705";
+      case "active":
+        return "\u{1F6A7}";
+      case "planning":
+        return "\u{1F4CB}";
+      case "not-started":
+        return "\u23F3";
+      default:
+        return "\u2753";
+    }
+  }
+}
+export {
+  EpicContentBuilder
+};