specweave 0.22.11 → 0.22.12

package/dist/src/validators/ac-coverage-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ac-coverage-validator.js","sourceRoot":"","sources":["../../../src/validators/ac-coverage-validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.22.11",
+  "version": "0.22.12",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/commands/specweave-done.md

@@ -80,6 +80,8 @@ if (!validation.isValid) {
 
   • 17 acceptance criteria still open
   • 13 tasks still pending
+  • 4 ACs uncovered by tasks (NEW - v0.23.0)
+  • 2 orphan tasks detected (NEW - v0.23.0)
 
 Fix these issues before running /specweave:done again
 ```
@@ -89,6 +91,8 @@ Fix these issues before running /specweave:done again
 ✅ Automated validation passed
   • All acceptance criteria completed
   • All tasks completed
+  • 100% AC coverage (29/29 ACs) (NEW - v0.23.0)
+  • 0 orphan tasks (NEW - v0.23.0)
 
 Proceeding to PM validation...
 ```
@@ -98,6 +102,10 @@ Proceeding to PM validation...
 - [ ] All tasks are completed in **tasks.md** (`**Status**: [x] completed`)
 - [ ] Required files exist (`spec.md`, `tasks.md`)
 - [ ] **NEW**: Tasks count in frontmatter matches checked tasks (source of truth validation)
+- [ ] **NEW (v0.23.0)**: AC coverage validation (US-Task Linkage Architecture)
+  - [ ] All ACs covered by at least one task (0% uncovered)
+  - [ ] No orphan tasks (all tasks have **Satisfies ACs** field)
+  - [ ] All US linkage valid (**User Story** field references exist in spec.md)
 
 **⚠️  SOURCE OF TRUTH ENFORCEMENT (CRITICAL)**:
 
@@ -128,6 +136,56 @@ if (tasksInFile < total_tasks) {
 - ❌ Marking work "done" without updating acceptance criteria
 - ❌ The critical violation from increment 0044 (2025-11-19)
 
+**⚠️  AC COVERAGE VALIDATION (NEW - v0.23.0)**:
+
+Gate 0 now validates AC coverage to ensure all Acceptance Criteria have implementing tasks:
+
+```typescript
+import { validateACCoverage } from '../../../src/validators/ac-coverage-validator.js';
+
+// Validate AC coverage
+const coverageReport = validateACCoverage(incrementPath, {
+  minCoveragePercentage: 100,  // Require 100% coverage
+  allowOrphans: false,          // Block if orphan tasks exist
+  logger: consoleLogger
+});
+
+// BLOCK if coverage fails
+if (coverageReport.uncoveredACs.length > 0) {
+  throw new ValidationError(
+    `CRITICAL: AC Coverage validation failed!\n` +
+    `\n` +
+    `Uncovered Acceptance Criteria (${coverageReport.uncoveredACs.length}):\n` +
+    coverageReport.uncoveredACs.map(acId => `  • ${acId}`).join('\n') +
+    `\n\n` +
+    `All ACs MUST have at least one implementing task.\n` +
+    `Create tasks with **Satisfies ACs** field linking to these ACs.\n` +
+    `\n` +
+    `Run: /specweave:validate ${incrementId} to see detailed coverage report.`
+  );
+}
+
+if (coverageReport.orphanTasks.length > 0) {
+  throw new ValidationError(
+    `CRITICAL: Orphan tasks detected!\n` +
+    `\n` +
+    `Tasks without AC linkage (${coverageReport.orphanTasks.length}):\n` +
+    coverageReport.orphanTasks.map(taskId => `  • ${taskId}`).join('\n') +
+    `\n\n` +
+    `All tasks MUST have **Satisfies ACs** field linking to acceptance criteria.\n` +
+    `Add AC references to these tasks.\n` +
+    `\n` +
+    `Run: /specweave:validate ${incrementId} to see detailed validation report.`
+  );
+}
+```
+
+**This ensures**:
+- ✅ All ACs covered by at least one task (100% coverage required)
+- ✅ No orphan tasks (all tasks link to valid ACs)
+- ✅ Traceability maintained (AC → Task mapping complete)
+- ✅ Living docs accuracy (sync depends on task-AC linkage)
+
 **Why Gate 0 matters**:
 - **Prevents false completion**: Can't mark increment "completed" with open work
 - **Fast feedback**: Fails immediately (< 1s) vs waiting for PM agent (30s+)

package/plugins/specweave/commands/specweave-validate.md

@@ -57,7 +57,7 @@ Usage: /specweave:validate-increment <id> [--quality] [--export] [--fix] [--alwa
 
 ### Step 2: Run Rule-Based Validation (Always)
 
-Run 130+ validation rules across 6 categories:
+Run 130+ validation rules across 7 categories:
 
 **CRITICAL: Always run structure validation FIRST to prevent duplicate task files**
 
@@ -104,19 +104,31 @@ Run 130+ validation rules across 6 categories:
    - ADR references exist
    - Diagram references valid
 
+7. **AC Coverage & Traceability (NEW - v0.23.0)**:
+   - All Acceptance Criteria have implementing tasks (0% uncovered)
+   - All tasks link to valid User Stories (**User Story**: US-XXX)
+   - All tasks link to valid Acceptance Criteria (**Satisfies ACs**: AC-USXX-YY)
+   - No orphan tasks (tasks without AC linkage)
+   - AC-Task traceability matrix builds successfully
+   - Per-User Story coverage calculated
+
 **Display results**:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 VALIDATION RESULTS: Increment 0001-authentication
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-✅ Rule-Based Validation: PASSED (135/135 checks)
+✅ Rule-Based Validation: PASSED (141/141 checks)
    ✓ Structure (5/5)
    ✓ Three-File Canonical (10/10) [ADR-0047]
    ✓ Consistency (47/47)
    ✓ Completeness (23/23)
    ✓ Quality (31/31)
    ✓ Traceability (19/19)
+   ✓ AC Coverage & Traceability (6/6) [NEW - v0.23.0]
+      • 100% AC coverage (15/15 ACs covered)
+      • 0 orphan tasks
+      • All tasks linked to valid User Stories
 
 Files validated:
   • spec.md (250 lines, 6 user stories)
@@ -129,13 +141,17 @@ Files validated:
 
 **If errors found**:
 ```
-❌ Rule-Based Validation: FAILED (122/135 checks)
+❌ Rule-Based Validation: FAILED (128/141 checks)
    ❌ Structure (3/5) - 2 CRITICAL ERRORS
    ❌ Three-File Canonical (7/10) - 3 CRITICAL ERRORS [ADR-0047]
    ✓ Consistency (45/47) - 2 errors
    ✓ Completeness (23/23)
    ⚠️  Quality (28/31) - 3 warnings
    ✓ Traceability (19/19)
+   ❌ AC Coverage & Traceability (3/6) - 3 ERRORS [NEW - v0.23.0]
+      • 73% AC coverage (11/15 ACs covered) - 4 uncovered
+      • 2 orphan tasks detected
+      • All US linkage valid
 
 CRITICAL STRUCTURE ERRORS (MUST FIX FIRST):
   ❌ Duplicate task files detected: tasks.md, tasks-detailed.md
@@ -153,6 +169,16 @@ CRITICAL THREE-FILE VIOLATIONS (ADR-0047):
   🚨 spec.md:102 - Contains task ID reference "T-001"
      → Tasks belong in tasks.md, use AC-IDs to link instead
 
+AC COVERAGE ERRORS (3) [NEW - v0.23.0]:
+  🔴 4 Acceptance Criteria uncovered by tasks:
+     → AC-US2-03: Real-time notification delivery (no implementing tasks)
+     → AC-US3-01: API rate limiting (no implementing tasks)
+     → AC-US3-05: Error handling for network failures (no implementing tasks)
+     → AC-US4-02: Audit logging for security events (no implementing tasks)
+  🔴 2 Orphan tasks (no AC linkage):
+     → T-008: Refactor authentication module (no **Satisfies ACs** field)
+     → T-015: Update documentation (no **Satisfies ACs** field)
+
 ERRORS (2):
   🔴 spec.md:45 - Missing acceptance criteria for US-003
   🔴 Inconsistency: spec.md mentions "real-time updates" but plan.md doesn't address it
@@ -168,9 +194,13 @@ Action required:
    - Run refactoring script: .specweave/increments/XXXX/scripts/refactor-tasks-ac-to-implementation.sh
    - Or manually replace "**Acceptance Criteria**:" with "**Implementation**:"
    - Add "**AC-IDs**: AC-US-XX-YY" references to link tasks to spec.md
-3. Fix missing acceptance criteria for US-003
-4. Address "real-time updates" in plan.md or remove from spec.md
-5. Consider breaking down T012 into smaller tasks
+3. 🔴 FIX AC COVERAGE ERRORS (v0.23.0 - US-Task Linkage):
+   - Create tasks for 4 uncovered ACs (AC-US2-03, AC-US3-01, AC-US3-05, AC-US4-02)
+   - Add **Satisfies ACs** field to 2 orphan tasks (T-008, T-015)
+   - Run: /specweave:validate 0001 to verify 100% coverage
+4. Fix missing acceptance criteria for US-003
+5. Address "real-time updates" in plan.md or remove from spec.md
+6. Consider breaking down T012 into smaller tasks
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```

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

@@ -103,6 +103,27 @@ async function hierarchicalDistribution(incrementId) {
     console.log(`      Files created/updated: ${result.filesCreated.length + result.filesUpdated.length}`);
 
     const changedFiles = [...result.filesCreated, ...result.filesUpdated];
+
+    // NEW (v0.23.0): Sync tasks from tasks.md to living docs US files
+    // Part of increment 0047-us-task-linkage implementation
+    try {
+      const { syncUSTasksToLivingDocs } = await import("./sync-us-tasks.js");
+      const taskSyncResult = await syncUSTasksToLivingDocs(
+        incrementId,
+        projectRoot,
+        result.featureId,
+        {}
+      );
+
+      if (taskSyncResult.success && taskSyncResult.updatedFiles.length > 0) {
+        changedFiles.push(...taskSyncResult.updatedFiles);
+      }
+    } catch (error) {
+      // Don't fail entire sync if US-Task sync fails (graceful degradation)
+      console.log(`   \u26A0\uFE0F  US-Task sync failed (non-fatal):`, error.message);
+      console.log(`   \u{1F4A1} Tip: This is a new feature (v0.23.0) - may need task parser build`);
+    }
+
     return {
       success: true,
       changedFiles

package/plugins/specweave/lib/hooks/sync-us-tasks.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+/**
+ * US-Task Synchronization Module
+ *
+ * Syncs task completion status from tasks.md to living docs User Story files.
+ * Updates:
+ * - Task lists in US files (replaces "No tasks defined")
+ * - AC checkboxes based on task completion
+ *
+ * Part of increment 0047-us-task-linkage implementation.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { parseTasksWithUSLinks, getAllTasks } from '../../../../dist/src/generators/spec/task-parser.js';
+import { glob } from 'glob';
+
+/**
+ * Sync tasks from tasks.md to living docs User Story files
+ *
+ * @param {string} incrementId - Increment ID (e.g., "0047-us-task-linkage")
+ * @param {string} projectRoot - Project root directory
+ * @param {string} featureId - Feature ID (e.g., "FS-047")
+ * @param {object} options - Sync options
+ * @returns {Promise<SyncResult>} Sync result
+ */
+export async function syncUSTasksToLivingDocs(incrementId, projectRoot, featureId, options = {}) {
+  try {
+    console.log(`   📋 Syncing tasks to living docs User Stories...`);
+
+    const tasksPath = path.join(projectRoot, '.specweave', 'increments', incrementId, 'tasks.md');
+
+    // Check if tasks.md exists
+    if (!fs.existsSync(tasksPath)) {
+      console.log(`   ⚠️  tasks.md not found, skipping task sync`);
+      return { success: true, updatedFiles: [], errors: [] };
+    }
+
+    // Parse tasks with US linkage
+    let tasksByUS;
+    try {
+      tasksByUS = parseTasksWithUSLinks(tasksPath);
+    } catch (error) {
+      console.error(`   ❌ Failed to parse tasks.md:`, error.message);
+      return { success: false, updatedFiles: [], errors: [error.message] };
+    }
+
+    const allTasks = getAllTasks(tasksByUS);
+    console.log(`   ✓ Parsed ${allTasks.length} tasks from tasks.md`);
+
+    // Check for tasks without US linkage (backward compatibility)
+    const unassignedTasks = tasksByUS['unassigned'] || [];
+    if (unassignedTasks.length > 0) {
+      console.log(`   ⚠️  ${unassignedTasks.length} tasks without User Story linkage (old format)`);
+    }
+
+    // Get project ID (default to "specweave" for now, can be enhanced later)
+    const projectId = getProjectId(projectRoot, incrementId) || 'specweave';
+
+    const updatedFiles = [];
+    const errors = [];
+
+    // For each User Story with tasks, update its living docs file
+    for (const [usId, tasks] of Object.entries(tasksByUS)) {
+      if (usId === 'unassigned') continue; // Skip unassigned tasks
+
+      try {
+        // Find US file in living docs
+        const usFilePath = await findUSFile(projectRoot, projectId, featureId, usId);
+
+        if (!usFilePath) {
+          console.log(`   ⚠️  Living docs file not found for ${usId}, skipping`);
+          continue;
+        }
+
+        // Update US file with task list
+        const updated = await updateUSFile(usFilePath, tasks, incrementId);
+
+        if (updated) {
+          updatedFiles.push(usFilePath);
+          console.log(`   ✓ Updated ${usId} with ${tasks.length} tasks`);
+        }
+      } catch (error) {
+        console.error(`   ❌ Error updating ${usId}:`, error.message);
+        errors.push(`${usId}: ${error.message}`);
+      }
+    }
+
+    if (updatedFiles.length > 0) {
+      console.log(`   ✅ Updated ${updatedFiles.length} User Story file(s)`);
+    } else {
+      console.log(`   ℹ️  No User Story files updated`);
+    }
+
+    return {
+      success: errors.length === 0,
+      updatedFiles,
+      errors
+    };
+  } catch (error) {
+    console.error(`   ❌ US-Task sync failed:`, error);
+    return { success: false, updatedFiles: [], errors: [error.message] };
+  }
+}
+
+/**
+ * Find User Story file in living docs
+ *
+ * @param {string} projectRoot - Project root
+ * @param {string} projectId - Project ID (e.g., "specweave")
+ * @param {string} featureId - Feature ID (e.g., "FS-047")
+ * @param {string} usId - User Story ID (e.g., "US-001")
+ * @returns {Promise<string|null>} Path to US file or null if not found
+ */
+async function findUSFile(projectRoot, projectId, featureId, usId) {
+  // Pattern: .specweave/docs/internal/specs/{project}/{feature}/us-{id}-*.md
+  const pattern = path.join(
+    projectRoot,
+    '.specweave',
+    'docs',
+    'internal',
+    'specs',
+    projectId,
+    featureId,
+    `${usId.toLowerCase()}-*.md`
+  );
+
+  const files = await glob(pattern);
+
+  if (files.length === 0) {
+    return null;
+  }
+
+  if (files.length > 1) {
+    console.log(`   ⚠️  Multiple files found for ${usId}, using first: ${path.basename(files[0])}`);
+  }
+
+  return files[0];
+}
+
+/**
+ * Update User Story file with task list and AC checkboxes
+ *
+ * @param {string} usFilePath - Path to US markdown file
+ * @param {Array} tasks - Tasks linked to this US
+ * @param {string} incrementId - Increment ID
+ * @returns {Promise<boolean>} True if file was updated
+ */
+async function updateUSFile(usFilePath, tasks, incrementId) {
+  let content = await fs.readFile(usFilePath, 'utf-8');
+  let updated = false;
+
+  // 1. Update task list section
+  const taskList = generateTaskList(tasks, incrementId);
+  const newTasksSection = `## Tasks\n\n${taskList}`;
+
+  // Replace existing tasks section
+  if (content.includes('## Tasks')) {
+    // Replace everything from "## Tasks" to next "##" or end of file
+    const tasksRegex = /(## Tasks\n\n)(?:.*?)(?=\n## |\n---\n|$)/s;
+    const newContent = content.replace(tasksRegex, newTasksSection);
+
+    if (newContent !== content) {
+      content = newContent;
+      updated = true;
+    }
+  }
+
+  // 2. Update AC checkboxes based on task completion
+  const updatedACs = updateACCheckboxes(content, tasks);
+  if (updatedACs !== content) {
+    content = updatedACs;
+    updated = true;
+  }
+
+  // Write updated content
+  if (updated) {
+    await fs.writeFile(usFilePath, content, 'utf-8');
+  }
+
+  return updated;
+}
+
+/**
+ * Generate task list markdown
+ *
+ * @param {Array} tasks - Tasks to list
+ * @param {string} incrementId - Increment ID
+ * @returns {string} Markdown task list
+ */
+function generateTaskList(tasks, incrementId) {
+  if (tasks.length === 0) {
+    return '_No tasks defined for this user story_';
+  }
+
+  return tasks.map(task => {
+    const checkbox = task.status === 'completed' ? 'x' : ' ';
+    const link = `../../../../increments/${incrementId}/tasks.md#${task.id}`;
+    return `- [${checkbox}] [${task.id}](${link}): ${task.title}`;
+  }).join('\n');
+}
+
+/**
+ * Update AC checkboxes based on task completion
+ *
+ * @param {string} content - US file content
+ * @param {Array} tasks - Tasks linked to this US
+ * @returns {string} Updated content
+ */
+function updateACCheckboxes(content, tasks) {
+  // Collect all AC-IDs satisfied by completed tasks
+  const satisfiedACs = new Set();
+
+  tasks.forEach(task => {
+    if (task.status === 'completed' && task.satisfiesACs) {
+      task.satisfiesACs.forEach(acId => satisfiedACs.add(acId));
+    }
+  });
+
+  // Update AC checkboxes
+  let updatedContent = content;
+
+  satisfiedACs.forEach(acId => {
+    // Replace: - [ ] **AC-US1-01** with - [x] **AC-US1-01**
+    const uncheckedRegex = new RegExp(`- \\[ \\] \\*\\*${escapeRegex(acId)}\\*\\*`, 'g');
+    updatedContent = updatedContent.replace(uncheckedRegex, `- [x] **${acId}**`);
+  });
+
+  // Also uncheck ACs that are no longer satisfied (tasks incomplete/pending)
+  // Extract all AC-IDs from content
+  const acPattern = /- \[[x ]\] \*\*(AC-US\d+-\d{2})\*\*/g;
+  let match;
+  const allACs = [];
+
+  while ((match = acPattern.exec(content)) !== null) {
+    allACs.push(match[1]);
+  }
+
+  // Uncheck ACs not in satisfiedACs set
+  allACs.forEach(acId => {
+    if (!satisfiedACs.has(acId)) {
+      const checkedRegex = new RegExp(`- \\[x\\] \\*\\*${escapeRegex(acId)}\\*\\*`, 'g');
+      updatedContent = updatedContent.replace(checkedRegex, `- [ ] **${acId}**`);
+    }
+  });
+
+  return updatedContent;
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Get project ID from metadata or config
+ *
+ * @param {string} projectRoot - Project root
+ * @param {string} incrementId - Increment ID
+ * @returns {string|null} Project ID or null
+ */
+function getProjectId(projectRoot, incrementId) {
+  try {
+    // Try to get from metadata.json
+    const metadataPath = path.join(projectRoot, '.specweave', 'increments', incrementId, 'metadata.json');
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+      if (metadata.project) {
+        return metadata.project;
+      }
+    }
+
+    // Try to get from config.json
+    const configPath = path.join(projectRoot, '.specweave', 'config.json');
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (config.defaultProject) {
+        return config.defaultProject;
+      }
+    }
+
+    // Default to "specweave" (single-project mode)
+    return 'specweave';
+  } catch (error) {
+    console.log(`   ⚠️  Could not determine project ID, using default: "specweave"`);
+    return 'specweave';
+  }
+}

package/src/templates/AGENTS.md.template

@@ -5,6 +5,22 @@
 
 ---
 
+## 🎯 Getting Started
+
+**Initial Increment Created**: `0001-project-setup` (`.specweave/increments/0001-project-setup/`)
+
+This increment was auto-generated by `specweave init` to give you a starting point.
+
+**Your Options**:
+1. **Start Fresh** (Recommended): Delete it and create your first real feature
+   - Delete the increment folder manually
+   - Ask user to run `/specweave:increment "your-feature-name"` (if in Claude Code) or create new increment via this file's commands
+2. **Customize It**: Edit the spec.md in the increment folder and use it for initial setup tasks
+
+**Note**: SpecWeave works best when each increment represents a single, focused feature or bugfix.
+
+---
+
 ## 🚨 CRITICAL: How to Use This File (Non-Claude Code Tools)
 
 **You're using Cursor, GitHub Copilot, or another AI tool - NOT Claude Code.**

package/src/templates/CLAUDE.md.template

@@ -4,6 +4,24 @@ This project uses **SpecWeave** - a specification-first AI development framework
 
 ---
 
+## 🎯 Getting Started
+
+**Initial Increment Created**: `0001-project-setup` (`.specweave/increments/0001-project-setup/`)
+
+This increment was auto-generated by `specweave init` to give you a starting point.
+
+**Your Options**:
+1. **Start Fresh** (Recommended): Delete it and create your first real feature
+   ```bash
+   rm -rf .specweave/increments/0001-project-setup
+   /specweave:increment "your-feature-name"
+   ```
+2. **Customize It**: Edit the spec.md and use this increment for initial setup tasks
+
+**Note**: SpecWeave works best when each increment represents a single, focused feature or bugfix.
+
+---
+
 ## 🚨 CRITICAL: NEVER POLLUTE PROJECT ROOT!
 
 **⛔ THIS IS THE #1 RULE - ALL AI-GENERATED FILES GO IN INCREMENT FOLDERS ⛔**