specweave 0.22.11 → 0.22.12

package/dist/src/generators/spec/task-parser.js

@@ -0,0 +1,301 @@
+/**
+ * Task Parser with US-Task Linkage Support
+ *
+ * Parses tasks.md files to extract task metadata including new US linkage fields:
+ * - userStory: US-ID this task implements (e.g., "US-001")
+ * - satisfiesACs: List of AC-IDs this task satisfies (e.g., ["AC-US1-01", "AC-US1-02"])
+ *
+ * Supports hierarchical task structure grouped by User Story.
+ */
+import { readFileSync } from 'fs';
+/**
+ * Parse tasks.md and extract all tasks with US linkage
+ *
+ * @param tasksPath - Path to tasks.md file
+ * @returns Map of User Story ID → Tasks
+ * @throws Error if tasks.md cannot be read or is malformed
+ */
+export function parseTasksWithUSLinks(tasksPath) {
+    try {
+        const content = readFileSync(tasksPath, 'utf-8');
+        const tasks = {};
+        // Split content into lines for line number tracking
+        const lines = content.split('\n');
+        // Regex patterns for task parsing
+        const taskHeaderRegex = /^###\s+(T-\d{3}):\s*(.+)$/;
+        const userStoryRegex = /^\*\*User Story\*\*:\s*(US-\d{3})/;
+        const satisfiesACsRegex = /^\*\*Satisfies ACs\*\*:\s*(AC-US\d+-\d{2}(?:,\s*AC-US\d+-\d{2})*)/;
+        const statusRegex = /^\*\*Status\*\*:\s*\[([x ])\]\s*(\w+)/;
+        const priorityRegex = /^\*\*Priority\*\*:\s*(.+)/;
+        const estimatedEffortRegex = /^\*\*Estimated Effort\*\*:\s*(.+)/;
+        const dependenciesRegex = /^\*\*Dependencies\*\*:\s*(.+)/;
+        let currentTask = null;
+        let currentDescription = [];
+        let currentSection = 'none';
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const lineNumber = i + 1;
+            // Check for task header (### T-XXX: Title)
+            const taskHeaderMatch = line.match(taskHeaderRegex);
+            if (taskHeaderMatch) {
+                // Save previous task if exists
+                if (currentTask) {
+                    saveTask(tasks, currentTask, currentDescription);
+                }
+                // Start new task
+                currentTask = {
+                    id: taskHeaderMatch[1],
+                    title: taskHeaderMatch[2],
+                    status: 'pending',
+                    lineNumber
+                };
+                currentDescription = [];
+                currentSection = 'none';
+                continue;
+            }
+            // Skip if no current task
+            if (!currentTask)
+                continue;
+            // Parse task fields
+            const userStoryMatch = line.match(userStoryRegex);
+            if (userStoryMatch) {
+                currentTask.userStory = userStoryMatch[1];
+                continue;
+            }
+            const satisfiesACsMatch = line.match(satisfiesACsRegex);
+            if (satisfiesACsMatch) {
+                // Split comma-separated AC-IDs and trim whitespace
+                currentTask.satisfiesACs = satisfiesACsMatch[1]
+                    .split(',')
+                    .map(ac => ac.trim());
+                continue;
+            }
+            const statusMatch = line.match(statusRegex);
+            if (statusMatch) {
+                const checkbox = statusMatch[1];
+                const statusText = statusMatch[2].toLowerCase();
+                // Map checkbox and status text to TaskStatus
+                if (checkbox === 'x') {
+                    currentTask.status = 'completed';
+                }
+                else if (statusText.includes('progress')) {
+                    currentTask.status = 'in_progress';
+                }
+                else if (statusText.includes('transfer')) {
+                    currentTask.status = 'transferred';
+                }
+                else if (statusText.includes('cancel')) {
+                    currentTask.status = 'canceled';
+                }
+                else {
+                    currentTask.status = 'pending';
+                }
+                continue;
+            }
+            const priorityMatch = line.match(priorityRegex);
+            if (priorityMatch) {
+                currentTask.priority = priorityMatch[1];
+                continue;
+            }
+            const estimatedEffortMatch = line.match(estimatedEffortRegex);
+            if (estimatedEffortMatch) {
+                currentTask.estimatedEffort = estimatedEffortMatch[1];
+                continue;
+            }
+            const dependenciesMatch = line.match(dependenciesRegex);
+            if (dependenciesMatch) {
+                // Parse dependencies (T-001, T-002, etc.)
+                currentTask.dependencies = dependenciesMatch[1]
+                    .split(',')
+                    .map(dep => dep.trim())
+                    .filter(dep => dep.match(/^T-\d{3}$/));
+                continue;
+            }
+            // Track sections for description parsing
+            if (line.startsWith('**Description**:')) {
+                currentSection = 'description';
+                continue;
+            }
+            if (line.startsWith('**Implementation Steps**:')) {
+                currentSection = 'implementation';
+                continue;
+            }
+            if (line.startsWith('**Test Plan**:')) {
+                currentSection = 'test';
+                continue;
+            }
+            if (line.startsWith('**Files Affected**:')) {
+                currentSection = 'files';
+                currentTask.filesAffected = [];
+                continue;
+            }
+            // Collect description lines
+            if (currentSection === 'description' && line.trim() && !line.startsWith('**')) {
+                currentDescription.push(line.trim());
+            }
+            // Collect files affected
+            if (currentSection === 'files' && line.trim().startsWith('- `')) {
+                const filePath = line.trim().replace(/^- `(.+)`/, '$1');
+                if (currentTask.filesAffected) {
+                    currentTask.filesAffected.push(filePath);
+                }
+            }
+        }
+        // Save last task
+        if (currentTask) {
+            saveTask(tasks, currentTask, currentDescription);
+        }
+        return tasks;
+    }
+    catch (error) {
+        throw new Error(`Failed to parse tasks.md at ${tasksPath}: ${error}`);
+    }
+}
+/**
+ * Helper: Save task to tasks map, grouped by User Story
+ */
+function saveTask(tasks, task, description) {
+    // Set description
+    if (description.length > 0) {
+        task.description = description.join(' ');
+    }
+    // Group by User Story (or "unassigned" if no userStory field)
+    const usId = task.userStory || 'unassigned';
+    if (!tasks[usId]) {
+        tasks[usId] = [];
+    }
+    tasks[usId].push(task);
+}
+/**
+ * Validate task US and AC linkage
+ *
+ * @param task - Task to validate
+ * @param validUSIds - List of valid US-IDs from spec.md
+ * @param validACIds - List of valid AC-IDs from spec.md
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateTaskLinkage(task, validUSIds, validACIds) {
+    const errors = [];
+    // Validate userStory field
+    if (task.userStory) {
+        // Check format (US-XXX)
+        if (!task.userStory.match(/^US-\d{3}$/)) {
+            errors.push({
+                taskId: task.id,
+                field: 'userStory',
+                value: task.userStory,
+                message: `Invalid US-ID format: "${task.userStory}" (expected format: US-001)`,
+                suggestedFix: 'Use format: US-XXX where XXX is a 3-digit number'
+            });
+        }
+        // Check if US exists in spec.md
+        else if (!validUSIds.includes(task.userStory)) {
+            errors.push({
+                taskId: task.id,
+                field: 'userStory',
+                value: task.userStory,
+                message: `User Story ${task.userStory} not found in spec.md`,
+                suggestedFix: `Valid User Stories: ${validUSIds.join(', ')}`
+            });
+        }
+    }
+    // Validate satisfiesACs field
+    if (task.satisfiesACs && task.satisfiesACs.length > 0) {
+        for (const acId of task.satisfiesACs) {
+            // Check format (AC-USXX-YY)
+            if (!acId.match(/^AC-US\d+-\d{2}$/)) {
+                errors.push({
+                    taskId: task.id,
+                    field: 'satisfiesACs',
+                    value: acId,
+                    message: `Invalid AC-ID format: "${acId}" (expected format: AC-US1-01)`,
+                    suggestedFix: 'Use format: AC-USXX-YY where XX is US number, YY is AC number'
+                });
+                continue;
+            }
+            // Check if AC exists in spec.md
+            if (!validACIds.includes(acId)) {
+                errors.push({
+                    taskId: task.id,
+                    field: 'satisfiesACs',
+                    value: acId,
+                    message: `Acceptance Criteria ${acId} not found in spec.md`,
+                    suggestedFix: `Check spec.md for valid AC-IDs in this User Story`
+                });
+                continue;
+            }
+            // Check if AC belongs to correct User Story
+            if (task.userStory) {
+                const acUSNumber = extractUSNumberFromACId(acId);
+                const taskUSNumber = extractUSNumber(task.userStory);
+                if (acUSNumber !== taskUSNumber) {
+                    errors.push({
+                        taskId: task.id,
+                        field: 'satisfiesACs',
+                        value: acId,
+                        message: `AC ${acId} belongs to US-${String(acUSNumber).padStart(3, '0')}, but task is linked to ${task.userStory}`,
+                        suggestedFix: `Either link task to US-${String(acUSNumber).padStart(3, '0')} or use different AC-ID`
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Extract US number from AC-ID (AC-US1-01 → 1)
+ */
+function extractUSNumberFromACId(acId) {
+    const match = acId.match(/^AC-US(\d+)-\d{2}$/);
+    return match ? parseInt(match[1], 10) : -1;
+}
+/**
+ * Extract US number from US-ID (US-001 → 1)
+ */
+function extractUSNumber(usId) {
+    const match = usId.match(/^US-(\d{3})$/);
+    return match ? parseInt(match[1], 10) : -1;
+}
+/**
+ * Get all tasks (flattened, not grouped by US)
+ *
+ * @param tasksByUS - Tasks grouped by User Story
+ * @returns Array of all tasks
+ */
+export function getAllTasks(tasksByUS) {
+    return Object.values(tasksByUS).flat();
+}
+/**
+ * Count tasks by status
+ *
+ * @param tasksByUS - Tasks grouped by User Story
+ * @returns Map of status → count
+ */
+export function countTasksByStatus(tasksByUS) {
+    const counts = {
+        pending: 0,
+        in_progress: 0,
+        completed: 0,
+        transferred: 0,
+        canceled: 0
+    };
+    const allTasks = getAllTasks(tasksByUS);
+    allTasks.forEach(task => {
+        counts[task.status]++;
+    });
+    return counts;
+}
+/**
+ * Calculate completion percentage
+ *
+ * @param tasksByUS - Tasks grouped by User Story
+ * @returns Completion percentage (0-100)
+ */
+export function calculateCompletionPercentage(tasksByUS) {
+    const allTasks = getAllTasks(tasksByUS);
+    if (allTasks.length === 0)
+        return 0;
+    const completedTasks = allTasks.filter(t => t.status === 'completed').length;
+    return Math.round((completedTasks / allTasks.length) * 100);
+}
+//# sourceMappingURL=task-parser.js.map

package/dist/src/generators/spec/task-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-parser.js","sourceRoot":"","sources":["../../../../src/generators/spec/task-parser.ts"],"names":[],"mappings":"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"}

package/dist/src/validators/ac-coverage-validator.d.ts

@@ -0,0 +1,106 @@
+/**
+ * AC Coverage Validator
+ *
+ * Validates Acceptance Criteria coverage by tasks:
+ * - Detects uncovered ACs (ACs with no implementing tasks)
+ * - Detects orphan tasks (tasks with no AC linkage)
+ * - Builds traceability matrix (AC ↔ Task mapping)
+ * - Calculates coverage metrics
+ *
+ * Used by `/specweave:validate` and `/specweave:done` commands to ensure
+ * all acceptance criteria are covered before increment closure.
+ */
+/**
+ * AC Coverage Report
+ */
+export interface ACCoverageReport {
+    /** Total number of Acceptance Criteria in spec.md */
+    totalACs: number;
+    /** Number of ACs covered by at least one task */
+    coveredACs: number;
+    /** AC-IDs with no implementing tasks */
+    uncoveredACs: string[];
+    /** Task IDs with no satisfiesACs field or invalid AC-IDs */
+    orphanTasks: string[];
+    /** Coverage percentage (0-100) */
+    coveragePercentage: number;
+    /** Traceability matrix: AC-ID → Task IDs */
+    acToTasksMap: Map<string, string[]>;
+    /** Reverse mapping: Task ID → AC-IDs */
+    taskToACsMap: Map<string, string[]>;
+    /** Per-User Story coverage breakdown */
+    coverageByUS: Map<string, USCoverageStats>;
+    /** Validation timestamp */
+    timestamp: string;
+}
+/**
+ * Coverage statistics per User Story
+ */
+export interface USCoverageStats {
+    /** User Story ID */
+    usId: string;
+    /** User Story title */
+    title: string;
+    /** Total ACs for this US */
+    totalACs: number;
+    /** Covered ACs for this US */
+    coveredACs: number;
+    /** Coverage percentage for this US */
+    coveragePercentage: number;
+    /** Uncovered AC-IDs for this US */
+    uncoveredACs: string[];
+}
+/**
+ * Validation options
+ */
+export interface ValidationOptions {
+    /** Allow orphan tasks (default: false) */
+    allowOrphans?: boolean;
+    /** Minimum coverage percentage required (default: 100) */
+    minCoveragePercentage?: number;
+    /** Logger for output messages */
+    logger?: {
+        log: (msg: string) => void;
+        error: (msg: string, err?: Error) => void;
+        warn: (msg: string) => void;
+    };
+}
+/**
+ * Validate AC coverage for an increment
+ *
+ * @param incrementPath - Path to increment directory (e.g., .specweave/increments/0047-us-task-linkage)
+ * @param options - Validation options
+ * @returns AC Coverage Report
+ * @throws Error if spec.md or tasks.md cannot be read
+ */
+export declare function validateACCoverage(incrementPath: string, options?: ValidationOptions): ACCoverageReport;
+/**
+ * Check if coverage report passes validation
+ *
+ * @param report - Coverage report
+ * @param options - Validation options
+ * @returns True if validation passes, false otherwise
+ */
+export declare function isCoveragePassing(report: ACCoverageReport, options?: ValidationOptions): boolean;
+/**
+ * Print detailed coverage report to console
+ *
+ * @param report - Coverage report
+ * @param options - Validation options
+ */
+export declare function printCoverageReport(report: ACCoverageReport, options?: ValidationOptions): void;
+/**
+ * Export coverage report to JSON file
+ *
+ * @param report - Coverage report
+ * @param outputPath - Path to output JSON file
+ */
+export declare function exportCoverageReportJSON(report: ACCoverageReport, outputPath: string): Promise<void>;
+/**
+ * Get recommended actions based on coverage report
+ *
+ * @param report - Coverage report
+ * @returns Array of recommended actions
+ */
+export declare function getRecommendedActions(report: ACCoverageReport): string[];
+//# sourceMappingURL=ac-coverage-validator.d.ts.map

package/dist/src/validators/ac-coverage-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ac-coverage-validator.d.ts","sourceRoot":"","sources":["../../../src/validators/ac-coverage-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IAEjB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IAEnB,wCAAwC;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,kCAAkC;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAE3B,4CAA4C;IAC5C,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEpC,wCAAwC;IACxC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEpC,wCAAwC;IACxC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAE3C,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IAEjB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IAEnB,sCAAsC;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAE3B,mCAAmC;IACnC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,0DAA0D;IAC1D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,iCAAiC;IACjC,MAAM,CAAC,EAAE;QACP,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC3B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;QAC1C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;KAC7B,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAwGlB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAeT;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,iBAAsB,GAC9B,IAAI,CAqEN;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,EAAE,CA4BxE"}

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

@@ -0,0 +1,250 @@
+/**
+ * AC Coverage Validator
+ *
+ * Validates Acceptance Criteria coverage by tasks:
+ * - Detects uncovered ACs (ACs with no implementing tasks)
+ * - Detects orphan tasks (tasks with no AC linkage)
+ * - Builds traceability matrix (AC ↔ Task mapping)
+ * - Calculates coverage metrics
+ *
+ * Used by `/specweave:validate` and `/specweave:done` commands to ensure
+ * all acceptance criteria are covered before increment closure.
+ */
+import path from 'path';
+import { existsSync } from 'fs';
+import { parseSpecMd } from '../generators/spec/spec-parser.js';
+import { parseTasksWithUSLinks, getAllTasks } from '../generators/spec/task-parser.js';
+/**
+ * Validate AC coverage for an increment
+ *
+ * @param incrementPath - Path to increment directory (e.g., .specweave/increments/0047-us-task-linkage)
+ * @param options - Validation options
+ * @returns AC Coverage Report
+ * @throws Error if spec.md or tasks.md cannot be read
+ */
+export function validateACCoverage(incrementPath, options = {}) {
+    const logger = options.logger ?? console;
+    // Validate paths
+    const specPath = path.join(incrementPath, 'spec.md');
+    const tasksPath = path.join(incrementPath, 'tasks.md');
+    if (!existsSync(specPath)) {
+        throw new Error(`spec.md not found at ${specPath}`);
+    }
+    if (!existsSync(tasksPath)) {
+        throw new Error(`tasks.md not found at ${tasksPath}`);
+    }
+    // Parse spec.md to get all ACs
+    logger.log('📋 Parsing spec.md to extract Acceptance Criteria...');
+    const specMetadata = parseSpecMd(specPath);
+    logger.log(`   Found ${specMetadata.allACIds.length} Acceptance Criteria across ${specMetadata.userStories.length} User Stories`);
+    // Parse tasks.md to get all tasks
+    logger.log('📝 Parsing tasks.md to extract tasks...');
+    const tasksByUS = parseTasksWithUSLinks(tasksPath);
+    const allTasks = getAllTasks(tasksByUS);
+    logger.log(`   Found ${allTasks.length} tasks`);
+    // Build traceability matrices
+    logger.log('🔗 Building traceability matrix...');
+    const acToTasksMap = new Map();
+    const taskToACsMap = new Map();
+    const orphanTasks = [];
+    // Initialize AC map with empty arrays
+    specMetadata.allACIds.forEach(acId => {
+        acToTasksMap.set(acId, []);
+    });
+    // Populate mappings from tasks
+    allTasks.forEach(task => {
+        if (!task.satisfiesACs || task.satisfiesACs.length === 0) {
+            // Task has no AC linkage - mark as orphan
+            orphanTasks.push(task.id);
+            return;
+        }
+        // Store task → ACs mapping
+        taskToACsMap.set(task.id, task.satisfiesACs);
+        // Store AC → tasks mapping
+        task.satisfiesACs.forEach(acId => {
+            // Only count if AC exists in spec.md (valid AC-ID)
+            if (acToTasksMap.has(acId)) {
+                const tasks = acToTasksMap.get(acId);
+                tasks.push(task.id);
+            }
+        });
+    });
+    // Calculate coverage
+    const uncoveredACs = [];
+    acToTasksMap.forEach((tasks, acId) => {
+        if (tasks.length === 0) {
+            uncoveredACs.push(acId);
+        }
+    });
+    const coveredACs = specMetadata.allACIds.length - uncoveredACs.length;
+    const coveragePercentage = specMetadata.allACIds.length > 0
+        ? Math.round((coveredACs / specMetadata.allACIds.length) * 100)
+        : 100;
+    // Calculate per-US coverage
+    const coverageByUS = new Map();
+    specMetadata.userStories.forEach(us => {
+        const usACs = us.acceptanceCriteria;
+        const usUncoveredACs = usACs.filter(acId => uncoveredACs.includes(acId));
+        const usCoveredACs = usACs.length - usUncoveredACs.length;
+        const usCoveragePercentage = usACs.length > 0
+            ? Math.round((usCoveredACs / usACs.length) * 100)
+            : 100;
+        coverageByUS.set(us.id, {
+            usId: us.id,
+            title: us.title,
+            totalACs: usACs.length,
+            coveredACs: usCoveredACs,
+            coveragePercentage: usCoveragePercentage,
+            uncoveredACs: usUncoveredACs
+        });
+    });
+    logger.log(`   Coverage: ${coveredACs}/${specMetadata.allACIds.length} ACs (${coveragePercentage}%)`);
+    logger.log(`   Orphan tasks: ${orphanTasks.length}`);
+    return {
+        totalACs: specMetadata.allACIds.length,
+        coveredACs,
+        uncoveredACs,
+        orphanTasks,
+        coveragePercentage,
+        acToTasksMap,
+        taskToACsMap,
+        coverageByUS,
+        timestamp: new Date().toISOString()
+    };
+}
+/**
+ * Check if coverage report passes validation
+ *
+ * @param report - Coverage report
+ * @param options - Validation options
+ * @returns True if validation passes, false otherwise
+ */
+export function isCoveragePassing(report, options = {}) {
+    const minCoverage = options.minCoveragePercentage ?? 100;
+    const allowOrphans = options.allowOrphans ?? false;
+    // Check coverage percentage
+    if (report.coveragePercentage < minCoverage) {
+        return false;
+    }
+    // Check orphan tasks
+    if (!allowOrphans && report.orphanTasks.length > 0) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Print detailed coverage report to console
+ *
+ * @param report - Coverage report
+ * @param options - Validation options
+ */
+export function printCoverageReport(report, options = {}) {
+    const logger = options.logger ?? console;
+    logger.log('\n' + '='.repeat(80));
+    logger.log('📊 Acceptance Criteria Coverage Report');
+    logger.log('='.repeat(80));
+    // Summary
+    logger.log('\n📈 Summary:');
+    logger.log(`   Total ACs: ${report.totalACs}`);
+    logger.log(`   Covered ACs: ${report.coveredACs}`);
+    logger.log(`   Uncovered ACs: ${report.uncoveredACs.length}`);
+    logger.log(`   Coverage: ${report.coveragePercentage}%`);
+    logger.log(`   Orphan Tasks: ${report.orphanTasks.length}`);
+    // Overall status
+    const passing = isCoveragePassing(report, options);
+    if (passing) {
+        logger.log('\n✅ VALIDATION PASSED');
+    }
+    else {
+        logger.log('\n❌ VALIDATION FAILED');
+    }
+    // Per-User Story breakdown
+    if (report.coverageByUS.size > 0) {
+        logger.log('\n📋 Coverage by User Story:');
+        report.coverageByUS.forEach(stats => {
+            const icon = stats.coveragePercentage === 100 ? '✅' : '⚠️';
+            logger.log(`   ${icon} ${stats.usId}: ${stats.coveredACs}/${stats.totalACs} ACs (${stats.coveragePercentage}%)`);
+        });
+    }
+    // Uncovered ACs
+    if (report.uncoveredACs.length > 0) {
+        logger.log('\n⚠️  Uncovered Acceptance Criteria:');
+        report.coverageByUS.forEach(stats => {
+            if (stats.uncoveredACs.length > 0) {
+                logger.log(`   ${stats.usId} - ${stats.title}:`);
+                stats.uncoveredACs.forEach(acId => {
+                    logger.log(`      - ${acId}`);
+                });
+            }
+        });
+        logger.log('\n💡 Suggestion: Create tasks that satisfy these ACs or mark them as not applicable');
+    }
+    // Orphan tasks
+    if (report.orphanTasks.length > 0) {
+        logger.log('\n⚠️  Orphan Tasks (no AC linkage):');
+        report.orphanTasks.forEach(taskId => {
+            logger.log(`   - ${taskId}`);
+        });
+        logger.log('\n💡 Suggestion: Add **Satisfies ACs** field to these tasks');
+    }
+    // Traceability matrix (only show if requested via debug mode)
+    if (process.env.DEBUG) {
+        logger.log('\n🔗 Traceability Matrix:');
+        report.acToTasksMap.forEach((tasks, acId) => {
+            if (tasks.length > 0) {
+                logger.log(`   ${acId} ← ${tasks.join(', ')}`);
+            }
+        });
+    }
+    logger.log('\n' + '='.repeat(80));
+    logger.log(`Generated: ${report.timestamp}\n`);
+}
+/**
+ * Export coverage report to JSON file
+ *
+ * @param report - Coverage report
+ * @param outputPath - Path to output JSON file
+ */
+export async function exportCoverageReportJSON(report, outputPath) {
+    const fs = await import('fs-extra');
+    // Convert Maps to plain objects for JSON serialization
+    const serializable = {
+        totalACs: report.totalACs,
+        coveredACs: report.coveredACs,
+        uncoveredACs: report.uncoveredACs,
+        orphanTasks: report.orphanTasks,
+        coveragePercentage: report.coveragePercentage,
+        acToTasksMap: Object.fromEntries(report.acToTasksMap),
+        taskToACsMap: Object.fromEntries(report.taskToACsMap),
+        coverageByUS: Object.fromEntries(report.coverageByUS),
+        timestamp: report.timestamp
+    };
+    await fs.writeJSON(outputPath, serializable, { spaces: 2 });
+}
+/**
+ * Get recommended actions based on coverage report
+ *
+ * @param report - Coverage report
+ * @returns Array of recommended actions
+ */
+export function getRecommendedActions(report) {
+    const actions = [];
+    if (report.uncoveredACs.length > 0) {
+        actions.push(`Create tasks to satisfy ${report.uncoveredACs.length} uncovered AC(s): ${report.uncoveredACs.slice(0, 3).join(', ')}${report.uncoveredACs.length > 3 ? '...' : ''}`);
+    }
+    if (report.orphanTasks.length > 0) {
+        actions.push(`Add **Satisfies ACs** field to ${report.orphanTasks.length} orphan task(s): ${report.orphanTasks.slice(0, 3).join(', ')}${report.orphanTasks.length > 3 ? '...' : ''}`);
+    }
+    if (report.coveragePercentage < 100) {
+        const gap = 100 - report.coveragePercentage;
+        actions.push(`Increase coverage by ${gap}% to reach 100% target`);
+    }
+    // Check for User Stories with low coverage
+    report.coverageByUS.forEach(stats => {
+        if (stats.coveragePercentage < 80) {
+            actions.push(`User Story ${stats.usId} has low coverage (${stats.coveragePercentage}%) - prioritize tasks for this US`);
+        }
+    });
+    return actions;
+}
+//# sourceMappingURL=ac-coverage-validator.js.map