specweave 0.18.0 → 0.20.0

package/dist/src/core/living-docs/spec-distributor.js

@@ -13,6 +13,8 @@ import fs from 'fs-extra';
 import path from 'path';
 import { HierarchyMapper } from './hierarchy-mapper.js';
 import { detectPrimaryGitHubRemote } from '../../utils/git-detector.js';
+import { ACProjectSpecificGenerator } from './ac-project-specific-generator.js';
+import { TaskProjectSpecificGenerator } from './task-project-specific-generator.js';
 /**
  * SpecDistributor - Distributes increment specs into hierarchical living docs
  */
@@ -36,15 +38,15 @@ export class SpecDistributor {
             createBackups: true,
             ...config,
         };
-        // Initialize HierarchyMapper with same project config
-        this.hierarchyMapper = new HierarchyMapper(projectRoot, {
-            projectId: config?.specsDir?.includes('/specs/')
-                ? config.specsDir.split('/specs/')[1]?.split('/')[0] || 'default'
-                : 'default'
-        });
+        // Initialize HierarchyMapper
+        this.hierarchyMapper = new HierarchyMapper(projectRoot);
+        // Initialize AC Generator
+        this.acGenerator = new ACProjectSpecificGenerator();
+        // ✅ NEW: Initialize Task Generator
+        this.taskGenerator = new TaskProjectSpecificGenerator(projectRoot);
     }
     /**
-     * Distribute increment spec into epic + user story files
+     * Distribute increment spec into universal hierarchy (epic + feature + user stories)
      */
     async distribute(incrementId) {
         const errors = [];
@@ -54,46 +56,80 @@ export class SpecDistributor {
             if (!this.githubRemote) {
                 this.githubRemote = await detectPrimaryGitHubRemote(this.projectRoot);
             }
-            // Step 0a: Parse increment spec to detect project ID
+            // Step 1: Parse increment spec (with epic and project detection)
             const parsed = await this.parseIncrementSpec(incrementId);
-            // Step 0b: Update config if project ID is specified in frontmatter
-            let projectId = this.config.specsDir.split('/specs/')[1]?.split('/')[0] || 'default';
-            if (parsed.project) {
-                projectId = parsed.project;
-                // Update config paths for correct project
-                this.config.specsDir = path.join(this.projectRoot, '.specweave', 'docs', 'internal', 'specs', projectId);
-                // Recreate hierarchy mapper with correct project ID
-                this.hierarchyMapper = new HierarchyMapper(this.projectRoot, {
-                    projectId,
-                    specsBaseDir: this.config.specsDir,
-                });
+            // Step 1.5: Filter abandoned/archived increments (CRITICAL: prevent pollution)
+            if (parsed.status === 'abandoned' || parsed.status === 'archived') {
+                console.log(`   ⚠️  Skipping distribution for ${parsed.status} increment: ${incrementId}`);
+                console.log(`   💡 Living docs are NOT updated for ${parsed.status} increments`);
+                return {
+                    epic: {},
+                    userStories: [],
+                    incrementId,
+                    specId: `${parsed.status.toUpperCase()}-${incrementId}`,
+                    totalStories: 0,
+                    totalFiles: 0,
+                    epicPath: '',
+                    userStoryPaths: [],
+                    success: false,
+                    errors: [`Increment ${incrementId} is ${parsed.status} - skipping living docs distribution`],
+                    warnings: [`To preserve history, archived content remains in the increment folder`],
+                };
+            }
+            // Step 2: Check if we should create epics (skip for GitHub)
+            const config = await this.hierarchyMapper.getSpecweaveConfig();
+            const syncProvider = config.sync?.provider || config.sync?.activeProfile ?
+                config.sync.profiles?.[config.sync.activeProfile]?.provider : undefined;
+            const shouldCreateEpic = syncProvider !== 'github'; // GitHub doesn't have epics concept
+            // Step 3: Detect epic mapping (OPTIONAL - skip for GitHub)
+            let epicMapping = null;
+            if (shouldCreateEpic) {
+                epicMapping = await this.hierarchyMapper.detectEpicMapping(incrementId);
+                if (epicMapping) {
+                    console.log(`   🎯 Mapped to epic ${epicMapping.epicId} (confidence: ${epicMapping.confidence}%)`);
+                }
+            }
+            else {
+                console.log(`   ⚡ Skipping epic creation (GitHub integration)`);
             }
-            // Step 0c: Detect feature folder using HierarchyMapper (NEW: feature-based naming)
+            // Step 4: Detect feature mapping (REQUIRED)
             console.log(`   🔍 Detecting feature folder for ${incrementId}...`);
-            const epicMapping = await this.hierarchyMapper.detectFeatureMapping(incrementId);
-            console.log(`   📁 Mapped to ${epicMapping.featureFolder} (confidence: ${epicMapping.confidence}%, method: ${epicMapping.detectionMethod})`);
-            // Ensure specs base directory exists (for multi-project support)
-            await fs.ensureDir(this.config.specsDir);
-            // Step 2: Classify content (pass epicMapping to use feature folder as ID)
-            const classified = await this.classifyContent(parsed, epicMapping);
-            // Step 3: Generate epic file
-            const epic = await this.generateEpicFile(classified, incrementId);
-            // Step 4: Generate user story files
-            const userStories = await this.generateUserStoryFiles(classified, incrementId);
-            // Step 5: Write files (using epicMapping paths)
-            const epicPath = await this.writeEpicFile(epic, epicMapping);
-            const userStoryPaths = await this.writeUserStoryFiles(userStories, epicMapping);
-            // Step 6: Update tasks.md with bidirectional links to user stories (CRITICAL!)
-            await this.updateTasksWithUserStoryLinks(incrementId, userStories, epicMapping);
+            const featureMapping = await this.hierarchyMapper.detectFeatureMapping(incrementId);
+            console.log(`   📁 Mapped to feature ${featureMapping.featureId} (confidence: ${featureMapping.confidence}%, method: ${featureMapping.detectionMethod})`);
+            console.log(`   📦 Projects: ${featureMapping.projects.join(', ')}`);
+            // Step 5: Classify content by project (NEW)
+            const storiesByProject = await this.classifyContentByProject(parsed, featureMapping);
+            console.log(`   📊 Classified ${parsed.userStories.length} user stories across ${storiesByProject.size} project(s)`);
+            // Step 6: Generate epic file (OPTIONAL - only if not GitHub)
+            const epicFile = epicMapping && shouldCreateEpic ? await this.generateEpicFile(parsed, epicMapping, featureMapping) : null;
+            // Step 7: Generate feature file (REQUIRED)
+            const featureFile = await this.generateFeatureFile(parsed, featureMapping, storiesByProject, incrementId);
+            // Step 8: Generate project context files (REQUIRED)
+            const projectContextFiles = await this.generateProjectContextFiles(featureMapping, parsed);
+            // Step 9: Generate user story files by project (REQUIRED)
+            const userStoryFilesByProject = await this.generateUserStoryFilesByProject(storiesByProject, featureMapping, incrementId);
+            // Step 10: Write epic file (if exists and not GitHub)
+            const epicPath = epicFile && epicMapping && shouldCreateEpic ? await this.writeEpicFile(epicFile, epicMapping) : null;
+            // Step 11: Write feature file
+            const featurePath = await this.writeFeatureFile(featureFile, featureMapping);
+            // Step 12: Write project context files
+            const contextPaths = await this.writeProjectContextFiles(projectContextFiles, featureMapping);
+            // Step 13: Write user story files by project
+            const storyPathsByProject = await this.writeUserStoryFilesByProject(userStoryFilesByProject, featureMapping, incrementId);
+            // Step 14: Update tasks.md with bidirectional links (project-aware)
+            await this.updateTasksWithUserStoryLinks(incrementId, userStoryFilesByProject, featureMapping);
+            // Prepare legacy result (for backward compatibility)
+            const allUserStories = Array.from(userStoryFilesByProject.values()).flat();
+            const allStoryPaths = Array.from(storyPathsByProject.values()).flat();
             return {
-                epic,
-                userStories,
+                epic: featureFile, // Type compatibility hack
+                userStories: allUserStories,
                 incrementId,
-                specId: epic.id,
-                totalStories: userStories.length,
-                totalFiles: 1 + userStories.length,
-                epicPath,
-                userStoryPaths,
+                specId: featureFile.id,
+                totalStories: allUserStories.length,
+                totalFiles: 1 + (epicFile ? 1 : 0) + contextPaths.length + allStoryPaths.length,
+                epicPath: featurePath, // Feature is the new "epic"
+                userStoryPaths: allStoryPaths,
                 success: true,
                 errors,
                 warnings,
@@ -164,18 +200,34 @@ export class SpecDistributor {
         // Extract overview (try multiple sections)
         let overview = '';
         // Try "Quick Overview" or "Executive Summary"
-        let overviewMatch = bodyContent.match(/##\s+(?:Quick\s+)?(?:Overview|Executive\s+Summary)\s*\n+([\s\S]*?)(?=\n##|\n---|\Z)/i);
-        if (overviewMatch)
+        let overviewMatch = bodyContent.match(/##\s+(?:Quick\s+)?(?:Overview|Executive\s+Summary)\s*\n+([\s\S]*?)(?=\n\*\*Business Value\*\*:|\n##|\n---|$)/im);
+        if (overviewMatch) {
             overview = overviewMatch[1].trim();
+            // Remove any trailing fragments or incomplete sentences
+            if (overview && !overview.endsWith('.') && !overview.endsWith('!') && !overview.endsWith('?')) {
+                // Try to complete the sentence by looking ahead
+                const extendedMatch = bodyContent.match(/##\s+(?:Quick\s+)?(?:Overview|Executive\s+Summary)\s*\n+([\s\S]{0,1000}?)(?:\n\n|\n\*\*|\n##|\n---|$)/im);
+                if (extendedMatch) {
+                    const extended = extendedMatch[1].trim();
+                    // Find the last complete sentence
+                    const sentences = extended.match(/[^.!?]+[.!?]/g);
+                    if (sentences) {
+                        overview = sentences.join('').trim();
+                    }
+                }
+            }
+        }
         if (!overview) {
             // Try "Overview" section
-            overviewMatch = bodyContent.match(/##\s+Overview\s*\n+([\s\S]*?)(?=\n##|\n---|\Z)/i);
-            if (overviewMatch)
-                overview = overviewMatch[1].trim();
+            overviewMatch = bodyContent.match(/##\s+Overview\s*\n+([\s\S]*?)(?=\n##|\n---|$)/im);
+            if (overviewMatch) {
+                const parts = overviewMatch[1].trim().split(/\n\n|\n---/);
+                overview = parts[0].trim();
+            }
         }
         if (!overview) {
             // Try "Problem Statement" section
-            const problemMatch = bodyContent.match(/##\s+Problem\s+Statement\s*\n+([\s\S]*?)(?=\n##|\n---|\Z)/i);
+            const problemMatch = bodyContent.match(/##\s+Problem\s+Statement\s*\n+([\s\S]*?)(?=\n##|\n---|$)/im);
             if (problemMatch) {
                 // Take first paragraph only
                 const firstPara = problemMatch[1].trim().split('\n\n')[0];
@@ -202,14 +254,23 @@ export class SpecDistributor {
         }
         // Extract user stories
         const userStories = await this.extractUserStories(content, incrementId);
+        // Extract priority, status, and created date from frontmatter
+        const priority = frontmatter.priority || 'P1';
+        const status = frontmatter.status || 'planning';
+        const created = frontmatter.created || new Date().toISOString();
         return {
             incrementId,
             title,
             overview,
             businessValue,
+            epic: frontmatter.epic, // Epic ID from frontmatter (optional)
             project: frontmatter.project, // Project ID from frontmatter (if present)
+            projects: frontmatter.projects || [], // Multiple projects (for cross-project features)
+            priority,
+            status,
+            created,
             userStories,
-            externalLinks, // NEW: External links from metadata.json
+            externalLinks, // External links from metadata.json
         };
     }
     /**
@@ -241,30 +302,98 @@ export class SpecDistributor {
         }
         return links;
     }
+    /**
+     * Detect external tool mapping from metadata.json
+     *
+     * Maps SpecWeave hierarchy to external tool hierarchy with clear indicators.
+     * Examples:
+     * - SpecWeave Feature (FS-031) → JIRA Epic (AUTH-100)
+     * - SpecWeave Feature (FS-031) → GitHub Issue (#45)
+     * - SpecWeave Feature (FS-031) → ADO Feature (12345)
+     */
+    async detectExternalToolMapping(incrementId) {
+        const metadataPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId, 'metadata.json');
+        if (!fs.existsSync(metadataPath)) {
+            return undefined;
+        }
+        try {
+            const metadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
+            // Priority order: JIRA > ADO > GitHub
+            // (JIRA has most divergence, GitHub has least)
+            // JIRA mapping (Epic → Feature divergence)
+            if (metadata.jira?.epicKey) {
+                return {
+                    provider: 'jira',
+                    externalType: 'epic',
+                    externalId: metadata.jira.epicKey,
+                    externalUrl: metadata.jira.url || `https://jira.atlassian.com/browse/${metadata.jira.epicKey}`,
+                    hierarchyLevel: 'feature',
+                    mappingNote: 'JIRA Epic maps to SpecWeave Feature',
+                };
+            }
+            // Azure DevOps mapping (Feature → Feature same level)
+            if (metadata.ado?.workItemId) {
+                return {
+                    provider: 'ado',
+                    externalType: 'feature',
+                    externalId: String(metadata.ado.workItemId),
+                    externalUrl: metadata.ado.workItemUrl,
+                    hierarchyLevel: 'feature',
+                    mappingNote: 'ADO Feature maps to SpecWeave Feature',
+                };
+            }
+            // GitHub mapping - Features should NOT map to issues
+            // According to Universal Hierarchy:
+            // - SpecWeave Feature (FS-*) → GitHub Milestone
+            // - SpecWeave User Story (US-*) → GitHub Issue
+            // We should NOT show GitHub issue mapping at feature level
+            // This will be handled at user story level instead
+        }
+        catch (error) {
+            console.warn(`   ⚠️  Failed to parse metadata.json for external mapping: ${error}`);
+        }
+        return undefined;
+    }
     /**
      * Extract user stories from increment spec
      */
     async extractUserStories(content, incrementId) {
         const userStories = [];
-        // Find all user story sections (supports both ### and #### patterns, with or without blank line)
-        const userStoryPattern = /^###+\s+(US-\d+):\s+(.+?)\s*\n([\s\S]*?)(?=^###+\s+US-|\n---\n|$)/gm;
-        let match;
-        while ((match = userStoryPattern.exec(content)) !== null) {
-            const id = match[1]; // US-001
-            const title = match[2];
-            const storyContent = match[3];
+        // Split content into individual user stories
+        // Each story runs from "### US-XXX:" or "#### US-XXX:" until the next user story or end of content
+        const storyParts = content.split(/(?=^#{3,4}\s+US-\d+:)/m);
+        for (const part of storyParts) {
+            // Skip empty parts or parts that don't start with US-
+            if (!part.trim() || !part.match(/^#{3,4}\s+US-\d+:/))
+                continue;
+            // Extract the user story ID and title from the first line (supports both ### and ####)
+            const headerMatch = part.match(/^#{3,4}\s+(US-\d+):\s+(.+?)$/m);
+            if (!headerMatch)
+                continue;
+            const id = headerMatch[1];
+            const title = headerMatch[2];
+            // Get everything after the header line, removing trailing ---
+            const storyContent = part
+                .substring(part.indexOf('\n') + 1)
+                .replace(/\n---\s*$/, '')
+                .trim();
             // Extract description (As a... I want... So that...) - supports both inline and separate line formats
-            const descMatch = storyContent.match(/\*\*As a\*\*\s+(.*?)\s*\n\*\*I want\*\*\s+(.*?)\s*\n\*\*So that\*\*\s+(.*?)(?=\n\n|\*\*Acceptance)/is);
+            const descMatch = storyContent.match(/\*\*As a\*\*\s+(.*?)\n\*\*I want\*\*\s+(.*?)\n\*\*So that\*\*\s+(.*?)(?:\n|$)/is);
             const description = descMatch
                 ? `**As a** ${descMatch[1].trim()}\n**I want** ${descMatch[2].trim()}\n**So that** ${descMatch[3].trim()}`
                 : '';
-            // Extract acceptance criteria
-            const acceptanceCriteria = this.extractAcceptanceCriteria(storyContent);
+            // Extract acceptance criteria from the Acceptance Criteria section
+            // Try full content first (works for #### headings), then story content (works for ### headings)
+            let acceptanceCriteria = this.extractAcceptanceCriteriaFromSection(content, id);
+            if (!acceptanceCriteria || acceptanceCriteria.length === 0) {
+                acceptanceCriteria = this.extractAcceptanceCriteria(storyContent);
+            }
             // Extract business rationale
             const rationaleMatch = storyContent.match(/\*\*Business Rationale\*\*:\s+(.*?)(?=\n\n---|\n\n##|$)/is);
             const businessRationale = rationaleMatch ? rationaleMatch[1].trim() : undefined;
-            // Extract phase
-            const phaseMatch = content.substring(0, match.index).match(/###\s+(Phase\s+\d+:.*?)$/im);
+            // Extract phase (look for phase header before this story in the original content)
+            const storyIndex = content.indexOf(part);
+            const phaseMatch = content.substring(0, storyIndex).match(/###\s+(Phase\s+\d+:.*?)$/im);
             const phase = phaseMatch ? phaseMatch[1] : undefined;
             // Determine status (assume complete if in completed increment)
             const status = 'complete'; // Can be enhanced later
@@ -286,87 +415,145 @@ export class SpecDistributor {
      */
     extractAcceptanceCriteria(content) {
         const criteria = [];
-        // Pattern: - [x] **AC-US1-01**: Description (P1, testable)
-        const acPattern = /^[-*]\s+\[([ x])\]\s+\*\*(.+?)\*\*:\s+(.+?)(?:\s+\(([^)]+)\))?$/gm;
-        let match;
-        while ((match = acPattern.exec(content)) !== null) {
-            const completed = match[1] === 'x';
-            const id = match[2]; // AC-US1-01
-            const description = match[3];
-            const metaString = match[4] || ''; // "P1, testable"
-            const priority = metaString.match(/P\d/)?.[0];
-            const testable = metaString.includes('testable');
-            criteria.push({
-                id,
-                description,
-                priority,
-                testable,
-                completed,
-            });
+        // Pattern 1: - [x] **AC-US1-01**: Description (P1, testable)
+        // Pattern 2: - [ ] **AC-001**: Description (P0, testable)
+        // Pattern 3: - AC-001: Description (P0, testable) [without checkbox]
+        // Also handles both ** bold ** and plain text formats
+        const acPatterns = [
+            // With checkbox and bold
+            /^[-*]\s+\[([ x])\]\s+\*\*(AC-[^:]+)\*\*:\s+(.+?)(?:\s+\(([^)]+)\))?$/gm,
+            // Without checkbox but with bold
+            /^[-*]\s+\*\*(AC-[^:]+)\*\*:\s+(.+?)(?:\s+\(([^)]+)\))?$/gm,
+            // Without checkbox and without bold (common in specs)
+            /^[-*]\s+(AC-\d+):\s+(.+?)(?:\s+\(([^)]+)\))?$/gm,
+        ];
+        // Try each pattern
+        for (const pattern of acPatterns) {
+            const contentCopy = content; // Work with a copy for each pattern
+            pattern.lastIndex = 0; // Reset regex state
+            let match;
+            while ((match = pattern.exec(contentCopy)) !== null) {
+                let completed = false;
+                let id = '';
+                let description = '';
+                let metaString = '';
+                // Handle different match groups based on pattern
+                if (match.length === 5) {
+                    // Pattern with checkbox: [1]=checkbox, [2]=id, [3]=desc, [4]=meta
+                    completed = match[1] === 'x';
+                    id = match[2];
+                    description = match[3];
+                    metaString = match[4] || '';
+                }
+                else if (match.length === 4) {
+                    // Pattern without checkbox: [1]=id, [2]=desc, [3]=meta
+                    completed = false; // Default to not completed
+                    id = match[1];
+                    description = match[2];
+                    metaString = match[3] || '';
+                }
+                // Skip if already added (avoid duplicates from multiple patterns)
+                if (criteria.some(c => c.id === id)) {
+                    continue;
+                }
+                const priority = metaString.match(/P\d/)?.[0];
+                const testable = metaString.includes('testable');
+                criteria.push({
+                    id,
+                    description,
+                    priority,
+                    testable,
+                    completed,
+                });
+            }
         }
         return criteria;
     }
     /**
-     * Classify content into epic vs user-story level
-     *
-     * NEW (v0.18.0): Uses feature folder name as ID (e.g., FS-25-11-14-release-management)
-     */
-    async classifyContent(parsed, epicMapping) {
-        // Use feature folder name as ID (e.g., FS-25-11-14-release-management)
-        // This ensures ID matches folder name
-        const specId = epicMapping.featureFolder;
-        return {
-            epic: {
-                id: specId,
-                title: parsed.title,
-                overview: parsed.overview,
-                businessValue: parsed.businessValue,
-                status: 'complete',
-            },
-            userStories: parsed.userStories,
-            implementationHistory: [
-                {
-                    increment: parsed.incrementId,
-                    stories: parsed.userStories.map((us) => us.id),
-                    status: 'complete',
-                    date: new Date().toISOString().split('T')[0],
-                },
-            ],
-            externalLinks: parsed.externalLinks || {},
-            relatedDocs: [],
-        };
-    }
-    /**
-     * Generate epic file
+     * Extract acceptance criteria from the full spec content for a specific user story
+     * This handles cases where AC is in a separate section after the user story
      */
-    async generateEpicFile(classified, incrementId) {
-        // Generate user story summaries
-        const userStorySummaries = classified.userStories.map((us) => ({
-            id: us.id,
-            title: us.title,
-            status: us.status,
-            phase: us.phase,
-            filePath: this.generateUserStoryFilename(us.id, us.title), // User stories are directly in FS folder
-        }));
-        const completedStories = classified.userStories.filter((us) => us.status === 'complete').length;
-        return {
-            id: classified.epic.id,
-            title: classified.epic.title,
-            type: 'epic',
-            status: 'complete',
-            priority: classified.epic.priority,
-            created: new Date().toISOString().split('T')[0],
-            lastUpdated: new Date().toISOString().split('T')[0],
-            overview: classified.epic.overview,
-            businessValue: classified.epic.businessValue,
-            implementationHistory: classified.implementationHistory,
-            userStories: userStorySummaries,
-            externalLinks: classified.externalLinks,
-            relatedDocs: classified.relatedDocs,
-            totalStories: classified.userStories.length,
-            completedStories,
-            overallProgress: Math.round((completedStories / classified.userStories.length) * 100),
-        };
+    extractAcceptanceCriteriaFromSection(content, userStoryId) {
+        const criteria = [];
+        // Find the user story section and its acceptance criteria
+        const usNumber = userStoryId.replace('US-', '');
+        // Try multiple patterns to find AC section (supports both ### and #### headings)
+        const patterns = [
+            // Pattern 1: AC in "**Acceptance Criteria**:" section (most common - matches spec format)
+            // This matches: **Acceptance Criteria**:\n- AC-XXX: description
+            new RegExp(`####+?\\s+${userStoryId}:.*?\\n[\\s\\S]*?\\*\\*Acceptance Criteria\\*\\*:\\s*\\n+((?:[-*]\\s+AC-\\d+:[^\\n]+\\n?)+)`, 'im'),
+            // Pattern 2: AC with checkboxes format
+            new RegExp(`####+?\\s+${userStoryId}:.*?\\n[\\s\\S]*?\\*\\*Acceptance Criteria\\*\\*:\\s*\\n+((?:[-*]\\s+\\[[ x]\\]\\s+\\*\\*AC-[^\\n]+\\n?)+)`, 'im'),
+            // Pattern 3: AC directly after user story (no separate section)
+            new RegExp(`####+?\\s+${userStoryId}:.*?\\n[\\s\\S]*?(?:\\n\\n|\\n)+([-*]\\s+\\[[ x]\\]\\s+\\*\\*AC-US${usNumber}-\\d+[\\s\\S]*?)(?=\\n\\s*\\*\\*Business|\\n###|\\n---|$)`, 'im'),
+            // Pattern 4: AC in a dedicated "### Acceptance Criteria" subsection
+            new RegExp(`####+?\\s+${userStoryId}:.*?\\n[\\s\\S]*?####+?\\s+Acceptance Criteria\\s*\\n+([\\s\\S]*?)(?=\\n\\s*\\*\\*Business|\\n###|\\n---|$)`, 'im'),
+        ];
+        let acContent = '';
+        for (const pattern of patterns) {
+            const match = content.match(pattern);
+            if (match && match[1]) {
+                acContent = match[1];
+                break;
+            }
+        }
+        if (!acContent) {
+            return criteria;
+        }
+        // Multiple patterns to handle different AC formats
+        // Pattern 1: - [ ] **AC-USX-XX**: Description (P1, testable)
+        // Pattern 2: - [x] **AC-001**: Description (P0, testable)
+        // Pattern 3: - AC-001: Description (P0, testable) [without checkbox]
+        const acPatterns = [
+            // With checkbox and bold (specific user story format)
+            /^[-*]\s+\[([ x])\]\s+\*\*(AC-US\d+-\d+)\*\*:\s+(.+?)(?:\s+\(([^)]+)\))?$/gm,
+            // With checkbox and bold (general format)
+            /^[-*]\s+\[([ x])\]\s+\*\*(AC-\d+)\*\*:\s+(.+?)(?:\s+\(([^)]+)\))?$/gm,
+            // Without checkbox but with bold
+            /^[-*]\s+\*\*(AC-\d+)\*\*:\s+(.+?)(?:\s+\(([^)]+)\))?$/gm,
+            // Without checkbox and without bold (common in specs)
+            /^[-*]\s+(AC-\d+):\s+(.+?)(?:\s+\(([^)]+)\))?$/gm,
+        ];
+        // Try each pattern
+        for (const pattern of acPatterns) {
+            pattern.lastIndex = 0; // Reset regex state
+            let match;
+            while ((match = pattern.exec(acContent)) !== null) {
+                let completed = false;
+                let id = '';
+                let description = '';
+                let metaString = '';
+                // Handle different match groups based on pattern
+                if (match.length === 5) {
+                    // Pattern with checkbox: [1]=checkbox, [2]=id, [3]=desc, [4]=meta
+                    completed = match[1] === 'x';
+                    id = match[2];
+                    description = match[3];
+                    metaString = match[4] || '';
+                }
+                else if (match.length === 4) {
+                    // Pattern without checkbox: [1]=id, [2]=desc, [3]=meta
+                    completed = false; // Default to not completed
+                    id = match[1];
+                    description = match[2];
+                    metaString = match[3] || '';
+                }
+                // Skip if already added (avoid duplicates from multiple patterns)
+                if (criteria.some(c => c.id === id)) {
+                    continue;
+                }
+                const priority = metaString.match(/P\d/)?.[0];
+                const testable = metaString.includes('testable');
+                criteria.push({
+                    id,
+                    description,
+                    priority,
+                    testable,
+                    completed,
+                });
+            }
+        }
+        return criteria;
     }
     /**
      * Generate user story files
@@ -489,36 +676,6 @@ export class SpecDistributor {
             .replace(/^-|-$/g, '');
         return `${id.toLowerCase()}-${slug}.md`;
     }
-    /**
-     * Write feature file to disk (NEW: writes to FEATURE.md instead of README.md)
-     */
-    async writeEpicFile(epic, epicMapping) {
-        // Write to feature-folder/FEATURE.md (feature overview - high-level summary)
-        const featurePath = path.join(epicMapping.featurePath, 'FEATURE.md');
-        const content = this.formatEpicFile(epic);
-        await fs.ensureDir(path.dirname(featurePath));
-        await fs.writeFile(featurePath, content, 'utf-8');
-        console.log(`   ✅ Written feature overview to ${epicMapping.featureFolder}/FEATURE.md`);
-        return featurePath;
-    }
-    /**
-     * Write user story files to disk (NEW: writes directly to feature folder)
-     */
-    async writeUserStoryFiles(userStories, epicMapping) {
-        // Write user stories directly to feature folder (not in subfolder)
-        const featureDir = epicMapping.featurePath;
-        await fs.ensureDir(featureDir);
-        const paths = [];
-        for (const userStory of userStories) {
-            const filename = this.generateUserStoryFilename(userStory.id, userStory.title);
-            const filePath = path.join(featureDir, filename);
-            const content = this.formatUserStoryFile(userStory);
-            await fs.writeFile(filePath, content, 'utf-8');
-            paths.push(filePath);
-        }
-        console.log(`   ✅ Written ${userStories.length} user stories directly to ${epicMapping.featureFolder}/`);
-        return paths;
-    }
     /**
      * Format epic file as markdown
      */
@@ -651,7 +808,7 @@ export class SpecDistributor {
         // Frontmatter
         lines.push('---');
         lines.push(`id: ${userStory.id}`);
-        lines.push(`epic: ${userStory.epic}`);
+        lines.push(`feature: ${userStory.epic}`); // ✅ FIX: Use 'feature:' not 'epic:' (Universal Hierarchy)
         lines.push(`title: "${userStory.title}"`);
         lines.push(`status: ${userStory.status}`);
         if (userStory.priority)
@@ -659,40 +816,81 @@ export class SpecDistributor {
         lines.push(`created: ${userStory.created}`);
         if (userStory.completed)
             lines.push(`completed: ${userStory.completed}`);
+        // Add external tool mapping to frontmatter
+        if (userStory.externalToolMapping) {
+            lines.push('externalTool:');
+            lines.push(`  provider: ${userStory.externalToolMapping.provider}`);
+            lines.push(`  type: ${userStory.externalToolMapping.externalType}`);
+            lines.push(`  id: "${userStory.externalToolMapping.externalId}"`);
+            lines.push(`  url: "${userStory.externalToolMapping.externalUrl}"`);
+        }
         lines.push('---');
         lines.push('');
-        // Title
-        lines.push(`# ${userStory.id}: ${userStory.title}`);
+        // Title with external tool indicator
+        let titleLine = `# ${userStory.id}: ${userStory.title}`;
+        if (userStory.externalToolMapping) {
+            const provider = userStory.externalToolMapping.provider.toUpperCase();
+            const type = userStory.externalToolMapping.externalType.charAt(0).toUpperCase() +
+                userStory.externalToolMapping.externalType.slice(1);
+            titleLine += ` (${provider} ${type}: ${userStory.externalToolMapping.externalId})`;
+        }
+        lines.push(titleLine);
         lines.push('');
-        // Feature link (FEATURE.md in same folder)
-        lines.push(`**Feature**: [${userStory.epic}](./FEATURE.md)`);
+        // Feature link (to _features folder)
+        // User story is at: .specweave/docs/internal/specs/{project}/{FS-XXX}/us-*.md
+        // Feature is at: .specweave/docs/internal/specs/_features/{FS-XXX}/FEATURE.md
+        // From {project}/{FS-XXX}/ we need to go up 2 levels to specs/, then into _features/
+        // Relative path: ../../_features/{FS-XXX}/FEATURE.md
+        const featureRelativePath = `../../_features/${userStory.epic}/FEATURE.md`;
+        lines.push(`**Feature**: [${userStory.epic}](${featureRelativePath})`);
         lines.push('');
         // Description
-        lines.push(userStory.description);
-        lines.push('');
+        if (userStory.description) {
+            lines.push(userStory.description);
+            lines.push('');
+        }
         lines.push('---');
         lines.push('');
         // Acceptance Criteria
         lines.push('## Acceptance Criteria');
         lines.push('');
-        for (const ac of userStory.acceptanceCriteria) {
-            const checkbox = ac.completed ? '[x]' : '[ ]';
-            const priorityText = ac.priority ? ` (${ac.priority}, testable)` : '';
-            lines.push(`- ${checkbox} **${ac.id}**: ${ac.description}${priorityText}`);
+        if (userStory.acceptanceCriteria && userStory.acceptanceCriteria.length > 0) {
+            for (const ac of userStory.acceptanceCriteria) {
+                const checkbox = ac.completed ? '[x]' : '[ ]';
+                const priorityText = ac.priority ? ` (${ac.priority}, testable)` : '';
+                lines.push(`- ${checkbox} **${ac.id}**: ${ac.description}${priorityText}`);
+            }
+        }
+        else {
+            lines.push('*Acceptance criteria to be extracted from increment specification*');
         }
         lines.push('');
         lines.push('---');
         lines.push('');
-        // Implementation
+        // ✅ NEW: Tasks section with checkboxes (project-specific)
+        if (userStory.tasks && userStory.tasks.length > 0) {
+            lines.push('## Tasks');
+            lines.push('');
+            for (const task of userStory.tasks) {
+                const checkbox = task.completed ? '[x]' : '[ ]';
+                lines.push(`- ${checkbox} **${task.id}**: ${task.title}`);
+            }
+            lines.push('');
+            lines.push('> **Note**: Tasks are project-specific. For the full increment task list, see [increment tasks.md](../../../../../increments/${userStory.implementation.increment}/tasks.md)');
+            lines.push('');
+            lines.push('---');
+            lines.push('');
+        }
+        // Implementation (source reference)
         lines.push('## Implementation');
         lines.push('');
-        lines.push(`**Increment**: [${userStory.implementation.increment}](${userStory.implementation.tasks[0]?.path.replace(/#.*$/, '')})`);
+        const incrementLink = userStory.implementation.tasks[0]?.path.replace(/#.*$/, '') || `../../../../../increments/${userStory.implementation.increment}/tasks.md`;
+        lines.push(`**Increment**: [${userStory.implementation.increment}](${incrementLink})`);
         lines.push('');
-        lines.push('**Tasks**:');
-        for (const task of userStory.implementation.tasks) {
-            lines.push(`- [${task.id}: ${task.title}](${task.path})`);
+        if (userStory.implementation.tasks.length > 0) {
+            lines.push('**Source Tasks**: See increment tasks.md for complete task breakdown');
+            lines.push('');
         }
-        lines.push('');
         // Business Rationale
         if (userStory.businessRationale) {
             lines.push('---');
@@ -726,98 +924,917 @@ export class SpecDistributor {
      * Update tasks.md with bidirectional links to user stories (CRITICAL!)
      *
      * This creates bidirectional traceability:
-     * - User Story → Tasks (already done in us-*.md files)
-     * - Tasks → User Story (NEW - added here)
-     *
-     * When a task implements a user story, this adds a link in tasks.md:
-     * **User Story**: [US-001: Title](../../docs/internal/specs/{project}/{feature}/us-001-*.md)
+  
+    /**
+     * Classify content by project (NEW for universal hierarchy)
+     * Split user stories across projects based on keywords and frontmatter
+     */
+    async classifyContentByProject(parsed, featureMapping) {
+        const storiesByProject = new Map();
+        for (const story of parsed.userStories) {
+            // Detect which project(s) this story belongs to
+            const storyProjects = await this.detectUserStoryProjects(story, featureMapping.projects);
+            for (const project of storyProjects) {
+                if (!storiesByProject.has(project)) {
+                    storiesByProject.set(project, []);
+                }
+                storiesByProject.get(project).push(story);
+            }
+        }
+        // If no stories were classified to any project, add all to default/first project
+        if (storiesByProject.size === 0 && parsed.userStories.length > 0) {
+            const defaultProject = featureMapping.projects[0] || 'default';
+            storiesByProject.set(defaultProject, parsed.userStories);
+        }
+        return storiesByProject;
+    }
+    /**
+     * Detect which projects a user story belongs to
      */
-    async updateTasksWithUserStoryLinks(incrementId, userStories, epicMapping) {
+    async detectUserStoryProjects(story, availableProjects) {
+        // If only one project available, return it
+        if (availableProjects.length === 1) {
+            return availableProjects;
+        }
+        const projects = [];
+        const config = await this.hierarchyMapper.getSpecweaveConfig();
+        // Method 1: Check if story has explicit project field
+        if (story.project) {
+            if (availableProjects.includes(story.project)) {
+                return [story.project];
+            }
+        }
+        // Method 2: Keyword detection in title and description
+        const text = `${story.title} ${story.description}`.toLowerCase();
+        for (const projectId of availableProjects) {
+            if (projectId === 'default') {
+                continue; // Skip default for keyword matching
+            }
+            // Get project config for keywords
+            const projectConfig = config.multiProject?.projects?.[projectId];
+            if (projectConfig?.keywords) {
+                const hasKeyword = projectConfig.keywords.some(keyword => text.includes(keyword.toLowerCase()));
+                if (hasKeyword) {
+                    projects.push(projectId);
+                }
+            }
+            // Also check if project name is mentioned
+            if (text.includes(projectId.toLowerCase())) {
+                if (!projects.includes(projectId)) {
+                    projects.push(projectId);
+                }
+            }
+        }
+        // Method 3: Fallback - if no projects detected, assign to all
+        if (projects.length === 0) {
+            return availableProjects;
+        }
+        return projects;
+    }
+    /**
+     * Generate epic file (OPTIONAL - for strategic themes)
+     */
+    async generateEpicFile(parsed, epicMapping, featureMapping) {
+        if (!epicMapping)
+            return null;
+        return {
+            id: epicMapping.epicId,
+            title: parsed.title,
+            type: 'epic',
+            status: parsed.status || 'in-progress',
+            created: parsed.created || new Date().toISOString(),
+            lastUpdated: new Date().toISOString(),
+            strategicOverview: parsed.overview,
+            features: [featureMapping.featureId],
+            successMetrics: [],
+            timeline: {
+                start: parsed.created || new Date().toISOString(),
+                targetCompletion: 'TBD',
+                currentPhase: 'Phase 1',
+            },
+            stakeholders: {},
+            externalLinks: parsed.externalLinks || {},
+        };
+    }
+    /**
+     * Generate feature file (REQUIRED - cross-project overview)
+     */
+    async generateFeatureFile(parsed, featureMapping, storiesByProject, incrementId) {
+        // Convert stories to summaries grouped by project
+        const userStoriesByProject = new Map();
+        for (const [project, stories] of storiesByProject.entries()) {
+            const summaries = stories.map(s => ({
+                id: s.id,
+                title: s.title,
+                status: s.status,
+                phase: s.phase,
+                filePath: `../../${project}/${featureMapping.featureFolder}/${this.generateUserStoryFilename(s.id, s.title)}`,
+            }));
+            userStoriesByProject.set(project, summaries);
+        }
+        // Count completed stories
+        let completedStories = 0;
+        for (const stories of storiesByProject.values()) {
+            completedStories += stories.filter(s => s.status === 'complete').length;
+        }
+        // Detect external tool mapping
+        const externalToolMapping = incrementId ? await this.detectExternalToolMapping(incrementId) : undefined;
+        return {
+            id: featureMapping.featureId,
+            title: parsed.title,
+            type: 'feature',
+            status: parsed.status || 'in-progress',
+            priority: parsed.priority || 'P1',
+            created: parsed.created || new Date().toISOString(),
+            lastUpdated: new Date().toISOString(),
+            epic: featureMapping.epic,
+            projects: featureMapping.projects,
+            overview: parsed.overview,
+            businessValue: parsed.businessValue || [],
+            implementationHistory: [],
+            userStoriesByProject,
+            externalLinks: parsed.externalLinks || {},
+            totalStories: parsed.userStories.length,
+            completedStories,
+            overallProgress: parsed.userStories.length > 0
+                ? Math.round((completedStories / parsed.userStories.length) * 100)
+                : 0,
+            sourceIncrement: incrementId, // Track the source increment
+            externalToolMapping, // Include external tool mapping
+        };
+    }
+    /**
+     * Generate project context files (README.md for each project)
+     */
+    async generateProjectContextFiles(featureMapping, parsed) {
+        const contextFiles = new Map();
+        for (const project of featureMapping.projects) {
+            const projectContext = await this.hierarchyMapper.getProjectContext(project);
+            if (!projectContext)
+                continue;
+            const content = this.formatProjectContextFile(featureMapping, projectContext, parsed);
+            contextFiles.set(project, content);
+        }
+        return contextFiles;
+    }
+    /**
+     * Format project context file (README.md)
+     * IMPORTANT: This README is created for ALL increments, even without user stories!
+     */
+    formatProjectContextFile(featureMapping, projectContext, parsed) {
+        const featurePathUp = featureMapping.projects.length > 1 ? '../../../' : '../../';
+        // Determine if this increment has user stories
+        const hasUserStories = parsed.userStories && parsed.userStories.length > 0;
+        const statusNote = parsed.status === 'abandoned' ? 'abandoned' :
+            parsed.status === 'complete' ? 'complete' : 'in-progress';
+        return `---
+id: ${featureMapping.featureId}-${projectContext.projectId}
+title: "${parsed.title} - ${projectContext.projectName} Implementation"
+feature: ${featureMapping.featureId}
+project: ${projectContext.projectId}
+type: feature-context
+status: ${statusNote}
+sourceIncrement: ${parsed.incrementId}
+---
+
+# ${projectContext.projectName} Implementation: ${parsed.title}
+
+**Feature**: [${featureMapping.featureId}](${featurePathUp}_features/${featureMapping.featureFolder}/FEATURE.md)
+
+## Overview
+
+${parsed.overview}
+
+## ${projectContext.projectName}-Specific Context
+
+This document contains the ${projectContext.projectName} implementation details for the ${parsed.title} feature.
+
+## Tech Stack
+
+${projectContext.techStack.map(t => `- ${t}`).join('\n')}
+
+## User Stories (${projectContext.projectName})
+
+${hasUserStories ? 'User stories for this project are listed below.' : `_This increment has no user stories. See [FEATURE.md](${featurePathUp}_features/${featureMapping.featureFolder}/FEATURE.md) for overview and implementation details._`}
+
+## Dependencies
+
+[Project-specific dependencies will be documented here]
+
+## Architecture Considerations
+
+[${projectContext.projectName}-specific architecture notes]
+
+---
+
+**Source**: [Increment ${parsed.incrementId}](../../../../../increments/${parsed.incrementId})
+`;
+    }
+    /**
+     * Generate user story files by project
+     */
+    async generateUserStoryFilesByProject(storiesByProject, featureMapping, incrementId) {
+        const filesByProject = new Map();
+        // Load tasks for linking (LEGACY - for backward compatibility)
+        const taskMap = await this.loadTaskReferences(incrementId);
+        for (const [project, stories] of storiesByProject.entries()) {
+            const userStoryFiles = [];
+            // Get project context for AC and task transformation
+            const rawProjectContext = await this.hierarchyMapper.getProjectContext(project);
+            for (const userStory of stories) {
+                // LEGACY: Find tasks that implement this user story (for backward compatibility)
+                const taskReferences = this.findTasksForUserStory(userStory.id, taskMap);
+                // ✅ NEW: Generate project-specific tasks with completion status
+                const projectSpecificTasks = await this.taskGenerator.generateProjectSpecificTasks(incrementId, userStory.id, rawProjectContext ? {
+                    id: rawProjectContext.projectId,
+                    name: rawProjectContext.projectName,
+                    type: this.detectProjectType(rawProjectContext),
+                    techStack: rawProjectContext.techStack,
+                    keywords: rawProjectContext.keywords,
+                } : undefined);
+                // Find related user stories (same project, same phase)
+                const relatedStories = stories
+                    .filter((us) => us.id !== userStory.id && us.phase === userStory.phase)
+                    .map((us) => ({
+                    id: us.id,
+                    title: us.title,
+                    status: us.status,
+                    phase: us.phase,
+                    filePath: this.generateUserStoryFilename(us.id, us.title),
+                }));
+                // ✨ Apply project-specific AC transformation
+                let projectSpecificACs = userStory.acceptanceCriteria;
+                if (rawProjectContext) {
+                    // Map ProjectContext to AC generator's expected format
+                    const acGeneratorContext = {
+                        id: rawProjectContext.projectId,
+                        name: rawProjectContext.projectName,
+                        type: this.detectProjectType(rawProjectContext),
+                        techStack: rawProjectContext.techStack,
+                        keywords: rawProjectContext.keywords,
+                    };
+                    projectSpecificACs = this.acGenerator.makeProjectSpecific(userStory.acceptanceCriteria, userStory.id, acGeneratorContext);
+                }
+                userStoryFiles.push({
+                    id: userStory.id,
+                    epic: featureMapping.featureId, // Feature is the parent
+                    title: userStory.title,
+                    status: userStory.status,
+                    priority: userStory.priority,
+                    created: new Date().toISOString().split('T')[0],
+                    completed: userStory.status === 'complete' ? new Date().toISOString().split('T')[0] : undefined,
+                    description: userStory.description,
+                    acceptanceCriteria: projectSpecificACs, // ✅ Use project-specific AC
+                    tasks: projectSpecificTasks, // ✅ NEW: Project-specific tasks with completion status
+                    implementation: {
+                        increment: incrementId,
+                        tasks: taskReferences, // LEGACY: Keep for backward compatibility
+                    },
+                    businessRationale: userStory.businessRationale,
+                    relatedStories,
+                    phase: userStory.phase,
+                    project, // Add project field
+                });
+            }
+            filesByProject.set(project, userStoryFiles);
+        }
+        return filesByProject;
+    }
+    /**
+     * Write epic file to _epics/ folder
+     */
+    async writeEpicFile(epic, epicMapping) {
+        if (!epic || !epicMapping)
+            return null;
+        const epicPath = path.join(epicMapping.epicPath, 'EPIC.md');
+        const content = this.formatEpicThemeFile(epic);
+        await fs.ensureDir(path.dirname(epicPath));
+        await fs.writeFile(epicPath, content, 'utf-8');
+        console.log(`   ✅ Written epic overview to _epics/${epicMapping.epicFolder}/EPIC.md`);
+        return epicPath;
+    }
+    /**
+     * Format epic theme file content
+     */
+    formatEpicThemeFile(epic) {
+        const yaml = `---
+id: ${epic.id}
+title: "${epic.title}"
+type: ${epic.type}
+status: ${epic.status}
+---`;
+        return `${yaml}
+
+# ${epic.title}
+
+## Strategic Overview
+
+${epic.strategicOverview}
+
+## Features
+
+${epic.features.map(f => `- ${f}`).join('\n')}
+
+## Timeline
+
+- **Start**: ${epic.timeline.start}
+- **Target Completion**: ${epic.timeline.targetCompletion}
+- **Current Phase**: ${epic.timeline.currentPhase}
+`;
+    }
+    /**
+     * Write feature file to _features/ folder
+     */
+    async writeFeatureFile(feature, featureMapping) {
+        const featurePath = path.join(featureMapping.featurePath, 'FEATURE.md');
+        const content = this.formatFeatureFile(feature);
+        await fs.ensureDir(path.dirname(featurePath));
+        await fs.writeFile(featurePath, content, 'utf-8');
+        console.log(`   ✅ Written feature overview to _features/${featureMapping.featureFolder}/FEATURE.md`);
+        return featurePath;
+    }
+    /**
+     * Format feature file content
+     */
+    formatFeatureFile(feature) {
+        // Build YAML frontmatter with external tool mapping
+        let yaml = `---
+id: ${feature.id}
+title: "${feature.title}"
+type: ${feature.type}
+status: ${feature.status}
+priority: ${feature.priority}
+created: ${feature.created}
+lastUpdated: ${feature.lastUpdated}
+projects: [${feature.projects.map(p => `"${p}"`).join(', ')}]
+${feature.epic ? `epic: ${feature.epic}` : ''}
+${feature.sourceIncrement ? `sourceIncrement: ${feature.sourceIncrement}` : ''}`;
+        // Add external tool mapping to frontmatter
+        if (feature.externalToolMapping) {
+            yaml += `
+externalTool:
+  provider: ${feature.externalToolMapping.provider}
+  type: ${feature.externalToolMapping.externalType}
+  id: "${feature.externalToolMapping.externalId}"
+  url: "${feature.externalToolMapping.externalUrl}"`;
+        }
+        yaml += '\n---';
+        const storiesByProjectSection = Array.from(feature.userStoriesByProject.entries())
+            .map(([project, stories]) => `
+### ${project}
+
+${stories.map(s => `- [${s.id}: ${s.title}](${s.filePath}) - ${s.status}`).join('\n')}`)
+            .join('\n');
+        // Build title with external tool indicator
+        let titleLine = `# ${feature.title}`;
+        if (feature.externalToolMapping) {
+            const provider = feature.externalToolMapping.provider.toUpperCase();
+            const type = feature.externalToolMapping.externalType.charAt(0).toUpperCase() +
+                feature.externalToolMapping.externalType.slice(1);
+            titleLine += ` (${provider} ${type}: ${feature.externalToolMapping.externalId})`;
+        }
+        // Add external tool mapping section
+        let externalMappingSection = '';
+        if (feature.externalToolMapping) {
+            externalMappingSection = `
+## External Tool Mapping
+
+**Mapped from**: ${feature.externalToolMapping.provider.toUpperCase()} ${feature.externalToolMapping.externalType.charAt(0).toUpperCase() + feature.externalToolMapping.externalType.slice(1)} [${feature.externalToolMapping.externalId}](${feature.externalToolMapping.externalUrl})
+
+> **Note**: ${feature.externalToolMapping.mappingNote}
+
+This SpecWeave Feature corresponds to a ${feature.externalToolMapping.externalType} in ${feature.externalToolMapping.provider.toUpperCase()}. The hierarchy mapping is:
+- **SpecWeave**: Feature (${feature.id})
+- **${feature.externalToolMapping.provider.toUpperCase()}**: ${feature.externalToolMapping.externalType.charAt(0).toUpperCase() + feature.externalToolMapping.externalType.slice(1)} (${feature.externalToolMapping.externalId})
+
+`;
+        }
+        // Add source section based on where the feature came from
+        let sourceSection = '';
+        if (feature.sourceIncrement) {
+            sourceSection = `
+## Source
+
+This feature was created from increment: [\`${feature.sourceIncrement}\`](../../../../../increments/${feature.sourceIncrement})
+`;
+        }
+        else if (feature.externalLinks?.github || feature.externalLinks?.jira || feature.externalLinks?.ado) {
+            sourceSection = `
+## Source
+
+This feature was imported from external tool:
+${feature.externalLinks?.github ? `- GitHub: ${feature.externalLinks.github}` : ''}
+${feature.externalLinks?.jira ? `- JIRA: ${feature.externalLinks.jira}` : ''}
+${feature.externalLinks?.ado ? `- Azure DevOps: ${feature.externalLinks.ado}` : ''}
+
+Note: No explicit feature was specified during import.
+`;
+        }
+        return `${yaml}
+
+${titleLine}
+${externalMappingSection}
+## Overview
+
+${feature.overview}
+${sourceSection}
+## Business Value
+
+${feature.businessValue.map(v => `- ${v}`).join('\n') || 'See overview above'}
+
+## Projects
+
+This feature spans the following projects:
+${feature.projects.map(p => `- ${p}`).join('\n')}
+
+## User Stories by Project
+${storiesByProjectSection}
+
+## Progress
+
+- **Total Stories**: ${feature.totalStories}
+- **Completed**: ${feature.completedStories}
+- **Progress**: ${feature.overallProgress}%
+`;
+    }
+    /**
+     * Write project context files (README.md for each project)
+     * IMPORTANT: Always create README.md even if increment has no user stories!
+     * This ensures every increment is represented in living docs, preventing gaps.
+     */
+    async writeProjectContextFiles(contextFiles, featureMapping) {
+        const writtenPaths = [];
+        // Write README.md for EVERY project, even if no user stories exist
+        for (const [project, content] of contextFiles.entries()) {
+            const projectPath = featureMapping.projectPaths.get(project);
+            if (!projectPath) {
+                console.warn(`   ⚠️  No project path found for ${project}, skipping README`);
+                continue;
+            }
+            // Ensure directory exists
+            await fs.ensureDir(projectPath);
+            // Write README.md
+            const readmePath = path.join(projectPath, 'README.md');
+            await fs.writeFile(readmePath, content, 'utf-8');
+            writtenPaths.push(readmePath);
+        }
+        if (writtenPaths.length > 0) {
+            console.log(`   ✅ Written README.md to ${writtenPaths.length} project folder(s)`);
+        }
+        return writtenPaths;
+    }
+    /**
+     * Write user story files by project
+     * IMPORTANT: Ensures project folders exist even if no user stories!
+     */
+    async writeUserStoryFilesByProject(userStoryFilesByProject, featureMapping, incrementId) {
+        const pathsByProject = new Map();
+        // CRITICAL FIX: Ensure ALL project folders exist, even without user stories
+        for (const project of featureMapping.projects) {
+            const projectPath = featureMapping.projectPaths.get(project);
+            if (!projectPath) {
+                console.warn(`   ⚠️  No project path found for ${project}, skipping`);
+                continue;
+            }
+            // Ensure directory exists (even if no stories to write)
+            await fs.ensureDir(projectPath);
+            const stories = userStoryFilesByProject.get(project) || [];
+            const paths = [];
+            // Write user story files (if any exist)
+            for (const story of stories) {
+                const filename = this.generateUserStoryFilename(story.id, story.title);
+                const filePath = path.join(projectPath, filename);
+                const content = this.formatUserStoryFile(story);
+                await fs.writeFile(filePath, content, 'utf-8');
+                paths.push(filePath);
+            }
+            pathsByProject.set(project, paths);
+        }
+        const totalStories = Array.from(userStoryFilesByProject.values())
+            .reduce((sum, stories) => sum + stories.length, 0);
+        if (totalStories > 0) {
+            console.log(`   ✅ Written ${totalStories} user stories to ${featureMapping.projects.length} project(s)`);
+        }
+        else {
+            console.log(`   ℹ️  No user stories to write, but created ${featureMapping.projects.length} project folder(s)`);
+        }
+        return pathsByProject;
+    }
+    /**
+     * Update tasks.md with bidirectional links (project-aware)
+     */
+    async updateTasksWithUserStoryLinks(incrementId, userStoryFilesByProject, featureMapping) {
         const tasksPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId, 'tasks.md');
-        // Check if tasks.md exists
         if (!fs.existsSync(tasksPath)) {
-            console.log(`   ⚠️  tasks.md not found for ${incrementId}, skipping bidirectional link update`);
+            console.warn(`   ⚠️  tasks.md not found for ${incrementId}, skipping bidirectional linking`);
             return;
         }
-        try {
-            const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-            // Parse tasks to create task → user story mapping
-            const taskToUSMapping = this.mapTasksToUserStories(tasksContent, userStories);
-            if (Object.keys(taskToUSMapping).length === 0) {
-                console.log(`   ℹ️  No AC-based task-to-US mapping found, skipping bidirectional links`);
-                return;
-            }
-            // Update tasks.md content with user story links
-            let updatedContent = tasksContent;
-            let linksAdded = 0;
-            for (const [taskId, userStory] of Object.entries(taskToUSMapping)) {
-                // Generate relative path from tasks.md to user story file
-                const projectId = epicMapping.featurePath.split('/specs/')[1]?.split('/')[0] || 'default';
-                const featureFolder = epicMapping.featureFolder;
-                const userStoryFile = this.generateUserStoryFilename(userStory.id, userStory.title);
-                const relativePath = `../../docs/internal/specs/${projectId}/${featureFolder}/${userStoryFile}`;
-                // Find task section and add link if not already present (supports both ## and ### headings)
-                // CRITICAL: Remove 'g' flag to prevent multiple matches of the same task
-                const taskPattern = new RegExp(`(^##+ ${taskId}:.*?$\\n)([\\s\\S]*?)(?=^##+ T-|^---$|$)`, 'm');
-                // Only replace once per task
-                let replaced = false;
-                updatedContent = updatedContent.replace(taskPattern, (match, heading, body) => {
-                    // Prevent multiple replacements
-                    if (replaced) {
-                        return match;
+        let content = await fs.readFile(tasksPath, 'utf-8');
+        // Build a map of all user stories across all projects
+        const allUserStories = new Map();
+        for (const [project, stories] of userStoryFilesByProject.entries()) {
+            for (const story of stories) {
+                allUserStories.set(story.id, { story, project });
+            }
+        }
+        // Pattern to find task headings and their AC fields
+        const taskSections = content.split(/(?=^##+ T-\d+:)/m);
+        const updatedSections = [];
+        for (const section of taskSections) {
+            if (!section.trim()) {
+                updatedSections.push(section);
+                continue;
+            }
+            // Extract task ID and AC list
+            const taskMatch = section.match(/^(##+ T-\d+:.+?)$/m);
+            const acMatch = section.match(/\*\*AC\*\*:\s*([^\n]+)/);
+            if (!taskMatch || !acMatch) {
+                updatedSections.push(section);
+                continue;
+            }
+            const taskHeading = taskMatch[1];
+            const acList = acMatch[1];
+            // Find which user story this task belongs to based on AC-IDs
+            let linkedStory = null;
+            const acPattern = /AC-US(\d+)-\d+/g;
+            let acIdMatch;
+            while ((acIdMatch = acPattern.exec(acList)) !== null) {
+                const usNumber = acIdMatch[1];
+                const usId = `US-${usNumber.padStart(3, '0')}`;
+                if (allUserStories.has(usId)) {
+                    linkedStory = allUserStories.get(usId);
+                    break;
+                }
+            }
+            if (linkedStory) {
+                const { story, project } = linkedStory;
+                // Use the FS-XXX feature ID from featureMapping, not featureFolder
+                const newRelativePath = `../../docs/internal/specs/${project}/${featureMapping.featureId}/${this.generateUserStoryFilename(story.id, story.title)}`;
+                const newLinkLine = `**User Story**: [${story.id}: ${story.title}](${newRelativePath})`;
+                // Check for existing user story links (old or new format)
+                const userStoryLinkPattern = /\*\*User Story\*\*:.*/g;
+                const existingLinks = section.match(userStoryLinkPattern);
+                if (!existingLinks || existingLinks.length === 0) {
+                    // No link exists - add new one
+                    const lines = section.split('\n');
+                    const headingIndex = lines.findIndex(line => line.match(/^##+ T-\d+:/));
+                    if (headingIndex >= 0) {
+                        lines.splice(headingIndex + 1, 0, '', newLinkLine);
+                        updatedSections.push(lines.join('\n'));
                     }
-                    // Check if link already exists
-                    if (body.includes('**User Story**:')) {
-                        return match; // Link already exists
+                    else {
+                        updatedSections.push(section);
                     }
-                    // Insert link right after the heading (before any content)
-                    const linkLine = `**User Story**: [${userStory.id}: ${userStory.title}](${relativePath})\n\n`;
-                    replaced = true;
-                    linksAdded++;
-                    return heading + linkLine + body;
-                });
-            }
-            // Write updated tasks.md
-            if (linksAdded > 0) {
-                await fs.writeFile(tasksPath, updatedContent, 'utf-8');
-                console.log(`   🔗 Added ${linksAdded} bidirectional links to tasks.md`);
+                }
+                else {
+                    // Link(s) exist - update them and remove duplicates/blank lines
+                    const lines = section.split('\n');
+                    let foundFirst = false;
+                    const cleanedLines = [];
+                    let consecutiveBlankLines = 0;
+                    for (let i = 0; i < lines.length; i++) {
+                        const line = lines[i];
+                        // Handle user story links
+                        if (line.includes('**User Story**:')) {
+                            if (!foundFirst) {
+                                foundFirst = true;
+                                cleanedLines.push(newLinkLine); // Replace with updated link
+                                consecutiveBlankLines = 0;
+                            }
+                            // Skip duplicate links
+                            continue;
+                        }
+                        // Handle blank lines (keep max 1 consecutive)
+                        if (line.trim() === '') {
+                            consecutiveBlankLines++;
+                            if (consecutiveBlankLines <= 1) {
+                                cleanedLines.push(line);
+                            }
+                        }
+                        else {
+                            consecutiveBlankLines = 0;
+                            cleanedLines.push(line);
+                        }
+                    }
+                    updatedSections.push(cleanedLines.join('\n'));
+                }
             }
             else {
-                console.log(`   ℹ️  All tasks already have user story links`);
+                updatedSections.push(section);
             }
         }
-        catch (error) {
-            console.warn(`   ⚠️  Failed to update tasks.md with bidirectional links: ${error}`);
+        const updatedContent = updatedSections.join('');
+        if (content !== updatedContent) {
+            await fs.writeFile(tasksPath, updatedContent, 'utf-8');
+            console.log(`   ✅ Updated tasks.md with bidirectional user story links`);
         }
     }
     /**
-     * Map tasks to user stories using AC-IDs
-     *
-     * Extracts AC-IDs from tasks (e.g., AC-US1-01) and maps them to user stories (e.g., US-001)
+     * Update acceptance criteria status in user stories based on completed tasks
+     * This method synchronizes AC checkboxes with task completion status
      */
-    mapTasksToUserStories(tasksContent, userStories) {
-        const mapping = {};
-        // Extract all tasks with their AC-IDs (supports both ## and ### headings)
-        const taskPattern = /^##+ (T-\d+):.*?$\n[\s\S]*?\*\*AC\*\*:\s*([^\n]+)/gm;
-        let match;
-        while ((match = taskPattern.exec(tasksContent)) !== null) {
-            const taskId = match[1]; // T-001
-            const acList = match[2]; // AC-US1-01, AC-US1-02
-            // Extract user story IDs from AC-IDs (AC-US1-01 → US-001)
-            const acPattern = /AC-US(\d+)-\d+/g;
-            let acMatch;
-            while ((acMatch = acPattern.exec(acList)) !== null) {
-                const usNumber = acMatch[1]; // "1"
-                const usId = `US-${usNumber.padStart(3, '0')}`; // "US-001"
-                // Find matching user story
-                const userStory = userStories.find(us => us.id === usId);
-                if (userStory) {
-                    mapping[taskId] = userStory;
-                    break; // One task can only map to one primary user story
+    async updateAcceptanceCriteriaStatus(incrementId) {
+        console.log(`\n📊 Updating acceptance criteria status for increment: ${incrementId}`);
+        const incrementPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId);
+        const tasksPath = path.join(incrementPath, 'tasks.md');
+        const specPath = path.join(incrementPath, 'spec.md');
+        if (!await fs.pathExists(tasksPath)) {
+            console.log(`   ⚠️  No tasks.md found, skipping AC status update`);
+            return;
+        }
+        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+        // Parse completed tasks and their AC references
+        const completedACs = this.extractCompletedAcceptanceCriteria(tasksContent);
+        if (completedACs.size === 0) {
+            console.log(`   ℹ️  No completed acceptance criteria found`);
+            return;
+        }
+        console.log(`   📝 Found ${completedACs.size} user stories with completed acceptance criteria`);
+        // Try to detect the feature folder this increment maps to
+        let featureId = null;
+        if (await fs.pathExists(specPath)) {
+            const specContent = await fs.readFile(specPath, 'utf-8');
+            // Look for feature mapping in frontmatter or content
+            const featureMatch = specContent.match(/feature:\s*(FS-[^\s\n]+)/i);
+            if (featureMatch) {
+                const declaredFeature = featureMatch[1];
+                // Try to find the actual feature folder that exists
+                featureId = await this.findActualFeatureFolder(incrementId, declaredFeature);
+                console.log(`   📁 Feature mapping: ${declaredFeature} → ${featureId || 'not found'}`);
+            }
+        }
+        // Update user story files with completed ACs
+        await this.updateUserStoryACStatus(completedACs, incrementId, featureId);
+    }
+    /**
+     * Extract completed acceptance criteria from tasks
+     */
+    extractCompletedAcceptanceCriteria(tasksContent) {
+        const completedACs = new Map(); // US-ID -> Set of AC-IDs
+        // Split into task sections
+        const taskSections = tasksContent.split(/^#{2,3}\s+T-\d+:/m);
+        for (const section of taskSections) {
+            if (!section.trim())
+                continue;
+            // Check if task is completed
+            const statusMatch = section.match(/\*\*Status\*\*:\s*\[x\]/i);
+            if (!statusMatch)
+                continue; // Skip incomplete tasks
+            // Extract AC field
+            const acMatch = section.match(/\*\*AC\*\*:\s*([^\n]+)/);
+            if (!acMatch)
+                continue;
+            // Parse AC-IDs
+            const acIds = acMatch[1].split(/[,\s]+/).filter(id => id.match(/^AC-/));
+            for (const acId of acIds) {
+                // Determine user story from AC-ID
+                // Patterns: AC-US1-01 -> US-001, AC-001 -> US-001 (assume single story)
+                let userStoryId = '';
+                const usMatch = acId.match(/AC-US(\d+)-/);
+                if (usMatch) {
+                    userStoryId = `US-${usMatch[1].padStart(3, '0')}`;
+                }
+                else {
+                    // For generic AC-XXX format, try to infer from task's user story link
+                    const usLinkMatch = section.match(/\[US-(\d+):/);
+                    if (usLinkMatch) {
+                        userStoryId = `US-${usLinkMatch[1].padStart(3, '0')}`;
+                    }
+                }
+                if (userStoryId) {
+                    if (!completedACs.has(userStoryId)) {
+                        completedACs.set(userStoryId, new Set());
+                    }
+                    completedACs.get(userStoryId).add(acId);
+                }
+            }
+        }
+        return completedACs;
+    }
+    /**
+     * Update user story files with completed AC status
+     */
+    async updateUserStoryACStatus(completedACs, incrementId, featureId = null) {
+        const specsPath = path.join(this.projectRoot, '.specweave', 'docs', 'internal', 'specs');
+        // Find all user story files
+        const projects = await this.getProjectFolders();
+        let updatedCount = 0;
+        for (const project of projects) {
+            const projectSpecsPath = path.join(specsPath, project);
+            if (!await fs.pathExists(projectSpecsPath))
+                continue;
+            // Find all feature folders
+            const entries = await fs.readdir(projectSpecsPath, { withFileTypes: true });
+            let featureFolders = entries.filter(e => e.isDirectory() && e.name.startsWith('FS-'));
+            // If we have a specific feature ID, only look in that folder
+            if (featureId) {
+                featureFolders = featureFolders.filter(e => e.name === featureId || e.name.includes(featureId));
+                if (featureFolders.length === 0) {
+                    console.log(`   ⚠️  Feature folder ${featureId} not found in ${project}`);
+                }
+            }
+            for (const folder of featureFolders) {
+                const featurePath = path.join(projectSpecsPath, folder.name);
+                // Find all user story files
+                const files = await fs.readdir(featurePath);
+                const userStoryFiles = files.filter(f => f.match(/^us-\d+-.+\.md$/));
+                for (const file of userStoryFiles) {
+                    const filePath = path.join(featurePath, file);
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    // Extract user story ID from content or filename
+                    const idMatch = content.match(/^id:\s*(US-\d+)/m) || file.match(/us-(\d+)/);
+                    if (!idMatch)
+                        continue;
+                    const userStoryId = idMatch[1].startsWith('US') ? idMatch[1] : `US-${idMatch[1].padStart(3, '0')}`;
+                    const acsToComplete = completedACs.get(userStoryId);
+                    if (!acsToComplete || acsToComplete.size === 0)
+                        continue;
+                    // Update AC checkboxes
+                    let updatedContent = content;
+                    let hasUpdates = false;
+                    for (const acId of acsToComplete) {
+                        // Find and update the AC checkbox
+                        // Pattern: - [ ] **AC-XXX**: Description
+                        const acPattern = new RegExp(`^(\\s*-\\s*)\\[\\s\\](\\s*\\*\\*${acId}\\*\\*:.*)$`, 'gm');
+                        // Check if pattern exists before replacing
+                        const originalContent = updatedContent;
+                        updatedContent = updatedContent.replace(acPattern, '$1[x]$2');
+                        // Check if replacement actually happened
+                        if (originalContent !== updatedContent) {
+                            hasUpdates = true;
+                            console.log(`   ✅ Updated ${acId} in ${userStoryId} (${project}/${folder.name})`);
+                        }
+                        else {
+                            // Debug: pattern didn't match
+                            console.log(`   ⚠️  Could not find ${acId} in ${userStoryId} (${project}/${folder.name})`);
+                            // Try to find what format the AC actually has
+                            const lineWithAc = updatedContent.split('\n').find(line => line.includes(acId));
+                            if (lineWithAc) {
+                                console.log(`      Found line: "${lineWithAc}"`);
+                            }
+                        }
+                    }
+                    if (hasUpdates) {
+                        await fs.writeFile(filePath, updatedContent, 'utf-8');
+                        updatedCount++;
+                    }
                 }
             }
         }
-        return mapping;
+        if (updatedCount > 0) {
+            console.log(`   ✅ Updated ${updatedCount} user story file(s) with completed acceptance criteria`);
+        }
+    }
+    /**
+     * Get all project folders from specs
+     */
+    async getProjectFolders() {
+        const specsPath = path.join(this.projectRoot, '.specweave', 'docs', 'internal', 'specs');
+        if (!await fs.pathExists(specsPath)) {
+            return ['default'];
+        }
+        const entries = await fs.readdir(specsPath, { withFileTypes: true });
+        const projectFolders = entries
+            .filter(e => e.isDirectory() && !e.name.startsWith('_'))
+            .map(e => e.name);
+        return projectFolders.length > 0 ? projectFolders : ['default'];
+    }
+    /**
+     * Detect project type for AC generation (backend, frontend, mobile, infrastructure, generic)
+     */
+    detectProjectType(context) {
+        const projectId = context.projectId.toLowerCase();
+        const keywords = context.keywords.map(k => k.toLowerCase());
+        const techStack = context.techStack.map(t => t.toLowerCase());
+        // Direct match on project ID
+        if (projectId.includes('backend') || projectId.includes('api') || projectId.includes('service')) {
+            return 'backend';
+        }
+        if (projectId.includes('frontend') || projectId.includes('web') || projectId.includes('ui')) {
+            return 'frontend';
+        }
+        if (projectId.includes('mobile') || projectId.includes('ios') || projectId.includes('android')) {
+            return 'mobile';
+        }
+        if (projectId.includes('infra') || projectId.includes('devops') || projectId.includes('deployment')) {
+            return 'infrastructure';
+        }
+        // Keyword-based detection
+        const backendKeywords = ['api', 'backend', 'service', 'server', 'database'];
+        const frontendKeywords = ['frontend', 'ui', 'component', 'react', 'web'];
+        const mobileKeywords = ['mobile', 'ios', 'android', 'react-native'];
+        const infraKeywords = ['infrastructure', 'devops', 'deployment', 'ci/cd', 'kubernetes'];
+        if (keywords.some(k => backendKeywords.includes(k)))
+            return 'backend';
+        if (keywords.some(k => frontendKeywords.includes(k)))
+            return 'frontend';
+        if (keywords.some(k => mobileKeywords.includes(k)))
+            return 'mobile';
+        if (keywords.some(k => infraKeywords.includes(k)))
+            return 'infrastructure';
+        // Tech stack-based detection
+        const backendTech = ['node.js', 'express', 'postgresql', 'mongodb', 'redis'];
+        const frontendTech = ['react', 'next.js', 'vue', 'angular', 'typescript'];
+        const mobileTech = ['react native', 'swift', 'kotlin', 'flutter'];
+        const infraTech = ['docker', 'kubernetes', 'terraform', 'ansible'];
+        if (techStack.some(t => backendTech.some(bt => t.includes(bt))))
+            return 'backend';
+        if (techStack.some(t => frontendTech.some(ft => t.includes(ft))))
+            return 'frontend';
+        if (techStack.some(t => mobileTech.some(mt => t.includes(mt))))
+            return 'mobile';
+        if (techStack.some(t => infraTech.some(it => t.includes(it))))
+            return 'infrastructure';
+        // Default to generic if no match
+        return 'generic';
+    }
+    /**
+     * Find the actual feature folder that matches an increment
+     * Handles mapping between different naming conventions
+     */
+    async findActualFeatureFolder(incrementId, declaredFeature) {
+        const specsPath = path.join(this.projectRoot, '.specweave', 'docs', 'internal', 'specs');
+        const projects = await this.getProjectFolders();
+        // Extract increment number
+        const incrementNum = incrementId.match(/^(\d+)/)?.[1];
+        for (const project of projects) {
+            const projectPath = path.join(specsPath, project);
+            if (!await fs.pathExists(projectPath))
+                continue;
+            const entries = await fs.readdir(projectPath);
+            const featureFolders = entries.filter(e => e.startsWith('FS-'));
+            // Strategy 1: Direct match
+            if (featureFolders.includes(declaredFeature)) {
+                return declaredFeature;
+            }
+            // Strategy 2: Match by increment number (FS-031 for increment 0031)
+            if (incrementNum) {
+                const paddedNum = incrementNum.padStart(3, '0');
+                const numericFeature = `FS-${paddedNum}`;
+                if (featureFolders.includes(numericFeature)) {
+                    return numericFeature;
+                }
+            }
+            // Strategy 3: Match by suffix (e.g., FS-XXX-external-tool-sync matches external-tool-sync)
+            const incrementSuffix = incrementId.replace(/^\d+-/, '');
+            for (const folder of featureFolders) {
+                if (folder.includes(incrementSuffix)) {
+                    return folder;
+                }
+            }
+            // Strategy 4: Match by date pattern
+            if (declaredFeature.match(/^FS-\d{2}-\d{2}-\d{2}-/)) {
+                // Find folder with same date prefix
+                const datePrefix = declaredFeature.match(/^FS-\d{2}-\d{2}-\d{2}/)?.[0];
+                for (const folder of featureFolders) {
+                    if (folder.startsWith(datePrefix)) {
+                        return folder;
+                    }
+                }
+            }
+            // Strategy 5: Smart content-based matching
+            // Look for feature folders containing user stories that reference this increment
+            for (const folder of featureFolders) {
+                const featurePath = path.join(projectPath, folder);
+                const files = await fs.readdir(featurePath);
+                const userStoryFiles = files.filter(f => f.match(/^us-\d+-.+\.md$/));
+                for (const file of userStoryFiles) {
+                    const filePath = path.join(featurePath, file);
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    // Check if this user story references our increment
+                    if (content.includes(`increments/${incrementId}/`) ||
+                        content.includes(`Increment**: [${incrementId}]`)) {
+                        console.log(`   🎯 Found feature folder ${folder} by content match in ${file}`);
+                        return folder;
+                    }
+                }
+            }
+            // Strategy 6: Fuzzy match on increment name parts
+            // Split increment name into words and look for feature folders with matching words
+            const incrementWords = incrementId.toLowerCase().split(/[-_]/);
+            let bestMatch = null;
+            for (const folder of featureFolders) {
+                const folderWords = folder.toLowerCase().split(/[-_]/);
+                let matchScore = 0;
+                // Count matching words (ignoring numbers and 'FS' prefix)
+                for (const word of incrementWords) {
+                    if (word.match(/^\d+$/) || word === 'fs')
+                        continue;
+                    if (folderWords.includes(word)) {
+                        matchScore++;
+                    }
+                }
+                // Update best match if this score is better
+                if (matchScore > 0 && (!bestMatch || matchScore > bestMatch.score)) {
+                    bestMatch = { folder, score: matchScore };
+                }
+            }
+            if (bestMatch && bestMatch.score >= 2) { // Require at least 2 word matches
+                console.log(`   🎯 Found feature folder ${bestMatch.folder} by fuzzy match (score: ${bestMatch.score})`);
+                return bestMatch.folder;
+            }
+        }
+        return null;
     }
 }
 //# sourceMappingURL=spec-distributor.js.map