specweave 0.18.1 → 0.20.0

package/dist/src/core/living-docs/hierarchy-mapper.js

@@ -1,238 +1,515 @@
 /**
- * SpecWeave Hierarchy Mapper
+ * SpecWeave Hierarchy Mapper (v4.0.0 - Universal Hierarchy with FS-XXX)
  *
- * Maps increments to Feature Spec (FS-*) folders following Universal Hierarchy architecture.
+ * Maps increments to universal hierarchy following work item type matrix:
+ * - Epic (EPIC-{id}) -> Cross-project strategic themes (_epics/)
+ * - Feature (FS-XXX) -> Cross-project features (_features/ + project folders)
+ * - User Story (us-{id}) -> Project-specific requirements (project/FS-XXX/us-{id}.md)
+ * - Task (T-{id}) -> Increment-specific implementation (increments/{id}/tasks.md)
  *
- * Supports three complexity levels:
- * 1. Simple: Increment → Issue/Epic/Feature (flat)
- * 2. Standard: FS-* (Epic) → US-* (User Stories) → T-* (Tasks)
- * 3. Enterprise: Domain → FS-* (Epic) → US-* → T-*
+ * Key Principles:
+ * - NO HARDCODED PROJECT NAMES (backend, frontend are examples)
+ * - Projects are DYNAMIC from config.json -> multiProject.projects
+ * - Single-project mode: ['default'] (always)
+ * - Multi-project mode: User-configured project names
+ * - Feature IDs assigned by creation date (FS-001, FS-002, etc.)
+ * - NO DUPLICATE FEATURE IDS (enforced by FeatureIDManager)
  *
  * @author SpecWeave Team
- * @version 3.0.0
+ * @version 4.0.0 (Universal Hierarchy with FS-XXX)
  */
 import fs from 'fs-extra';
 import path from 'path';
+import { ConfigManager } from '../config-manager.js';
+import { FeatureIDManager } from './feature-id-manager.js';
 /**
- * HierarchyMapper - Maps increments to feature folders (named by concept, not increment number)
+ * HierarchyMapper - Maps increments to universal hierarchy
  *
- * NEW ARCHITECTURE (v0.18.0+):
- * - Features are PERMANENT (named by concept: "release-management", "external-tool-sync")
- * - Increments are TEMPORARY (named by execution: "0023-release-management-enhancements")
- * - Multiple increments can contribute to same feature
- * - No FS-### prefix (features aren't numbered)
+ * Universal Hierarchy (v4.0.0):
+ * 1. Epic (EPIC-YYYY-QN-{name}) -> _epics/EPIC-{id}/EPIC.md
+ * 2. Feature (FS-XXX) -> _features/FS-XXX/FEATURE.md + {project}/FS-XXX/
+ * 3. User Story (us-NNN-{name}) -> {project}/FS-XXX/us-{id}.md
+ * 4. Task (T-NNN) -> increments/{id}/tasks.md
  */
 export class HierarchyMapper {
     constructor(projectRoot, config) {
+        this.specweaveConfig = null;
         this.projectRoot = projectRoot;
-        const projectId = config?.projectId || 'default';
+        this.configManager = new ConfigManager(projectRoot);
+        this.featureIdManager = new FeatureIDManager(projectRoot);
         this.config = {
-            level: 'standard', // SpecWeave uses Standard level by default
-            specsBaseDir: path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', projectId),
-            projectId,
-            featureFolderPattern: '{name}', // Feature-based naming (no FS- prefix)
-            userStoriesSubdir: '', // User stories go directly in feature folder, not subfolder
+            level: 'standard',
+            specsBaseDir: path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs'),
+            detectEpicFrom: ['frontmatter', 'config'],
             detectFeatureFrom: ['frontmatter', 'increment-name', 'config'],
-            fallbackFeature: undefined,
+            detectProjectFrom: ['frontmatter', 'increment-name', 'config'],
             ...config,
         };
     }
     /**
-     * Detect which feature folder this increment belongs to
+     * Load SpecWeave config (cached)
+     */
+    async getSpecweaveConfig() {
+        if (!this.specweaveConfig) {
+            this.specweaveConfig = await this.configManager.loadAsync();
+        }
+        return this.specweaveConfig;
+    }
+    /**
+     * Get list of configured projects
      *
-     * NEW: Features are named by CONCEPT (release-management), not INCREMENT NUMBER (FS-023)
+     * Returns:
+     * - Single-project mode: ['default']
+     * - Multi-project mode: User-configured project names (dynamic, no hardcodes)
+     */
+    async getConfiguredProjects() {
+        const config = await this.getSpecweaveConfig();
+        // Check if multi-project mode is enabled
+        if (config.multiProject?.enabled && config.multiProject.projects) {
+            const projects = Object.keys(config.multiProject.projects);
+            // If projects object is empty, fallback to default
+            if (projects.length > 0) {
+                return projects;
+            }
+        }
+        // Default: single-project mode
+        return ['default'];
+    }
+    /**
+     * Check if a feature is archived
+     */
+    async isFeatureArchived(featureId) {
+        const archivePaths = [
+            path.join(this.config.specsBaseDir, '_features', '_archive', featureId),
+            // Check project-specific archives
+            ...(await this.getConfiguredProjects()).map(project => path.join(this.config.specsBaseDir, project, '_archive', featureId))
+        ];
+        for (const archivePath of archivePaths) {
+            if (await fs.pathExists(archivePath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Check if an epic is archived
+     */
+    async isEpicArchived(epicId) {
+        const archivePath = path.join(this.config.specsBaseDir, '_epics', '_archive', epicId);
+        return await fs.pathExists(archivePath);
+    }
+    /**
+     * Filter out archived items from mappings
+     */
+    async filterArchivedItems(items, type) {
+        const filtered = [];
+        for (const item of items) {
+            const isArchived = type === 'feature'
+                ? await this.isFeatureArchived(item.id)
+                : await this.isEpicArchived(item.id);
+            if (!isArchived) {
+                filtered.push(item);
+            }
+        }
+        return filtered;
+    }
+    /**
+     * Get project context for a specific project ID
+     */
+    async getProjectContext(projectId) {
+        const config = await this.getSpecweaveConfig();
+        // Single-project mode
+        if (projectId === 'default') {
+            return {
+                projectId: 'default',
+                projectName: config.project?.name || 'Default Project',
+                projectPath: path.join(this.config.specsBaseDir, 'default'),
+                keywords: [],
+                techStack: config.project?.techStack || [],
+            };
+        }
+        // Multi-project mode
+        const projectConfig = config.multiProject?.projects?.[projectId];
+        if (!projectConfig) {
+            return null;
+        }
+        return {
+            projectId,
+            projectName: projectConfig.name,
+            projectPath: path.join(this.config.specsBaseDir, projectId),
+            keywords: projectConfig.keywords || [],
+            techStack: projectConfig.techStack || [],
+        };
+    }
+    /**
+     * Detect which epic this increment belongs to (OPTIONAL)
+     *
+     * Epic Format: EPIC-YYYY-QN-{name}
+     * Example: EPIC-2025-Q4-platform
+     *
+     * Detection Methods:
+     * 1. Frontmatter: epic: EPIC-2025-Q4-platform
+     * 2. Config: livingDocs.hierarchyMapping.incrementToEpic
+     * 3. Fallback: null (no epic required)
+     */
+    async detectEpicMapping(incrementId) {
+        const specPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId, 'spec.md');
+        if (!fs.existsSync(specPath)) {
+            return null;
+        }
+        const content = await fs.readFile(specPath, 'utf-8');
+        // Try each detection method
+        for (const method of this.config.detectEpicFrom) {
+            let mapping = null;
+            switch (method) {
+                case 'frontmatter':
+                    mapping = await this.detectEpicFromFrontmatter(content, incrementId);
+                    break;
+                case 'config':
+                    mapping = await this.detectEpicFromConfig(incrementId);
+                    break;
+            }
+            if (mapping && mapping.confidence >= 80) {
+                return mapping;
+            }
+        }
+        // No epic found (OK - epics are optional)
+        return null;
+    }
+    /**
+     * Detect which feature this increment belongs to (REQUIRED)
+     *
+     * Feature Format (Greenfield): FS-XXX (matches increment number)
+     * Feature Format (Brownfield): FS-YY-MM-DD-{feature-name} (date-based)
+     * Examples:
+     * - Greenfield: 0031-external-tool-sync → FS-031
+     * - Brownfield: Imported from JIRA → FS-25-11-14-external-tool-sync
+     *
+     * Detection Methods:
+     * 1. Frontmatter: feature: FS-031 (greenfield) or feature: FS-25-11-14-name (brownfield)
+     * 2. Increment Name: 0031-external-tool-status-sync → FS-031 (auto-extract number)
+     * 3. Config: livingDocs.hierarchyMapping.incrementToFeature
+     * 4. Fallback: Auto-create feature from increment number (FS-XXX format)
      */
     async detectFeatureMapping(incrementId) {
+        // Load feature registry first
+        await this.featureIdManager.loadRegistry();
         const specPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId, 'spec.md');
         if (!fs.existsSync(specPath)) {
             throw new Error(`Increment spec not found: ${specPath}`);
         }
         const content = await fs.readFile(specPath, 'utf-8');
-        // Try each detection method in order
+        // Try each detection method
         for (const method of this.config.detectFeatureFrom) {
             let mapping = null;
             switch (method) {
                 case 'frontmatter':
-                    mapping = await this.detectFromFrontmatter(content, incrementId);
+                    mapping = await this.detectFeatureFromFrontmatter(content, incrementId);
                     break;
                 case 'increment-name':
-                    mapping = await this.detectFromIncrementName(incrementId);
+                    mapping = await this.detectFeatureFromIncrementName(incrementId);
                     break;
                 case 'config':
-                    mapping = await this.detectFromConfig(incrementId);
+                    mapping = await this.detectFeatureFromConfig(incrementId);
                     break;
             }
             if (mapping && mapping.confidence >= 80) {
                 return mapping;
             }
         }
-        // Fallback: Extract feature name from increment ID
-        return await this.createFallbackMapping(incrementId);
+        // Fallback: Create feature from increment name + date
+        return await this.createFallbackFeatureMapping(incrementId);
     }
     /**
-     * Legacy alias for backward compatibility
+     * Detect which projects this increment/feature affects (REQUIRED)
+     *
+     * Returns array of project IDs (dynamic, from config)
+     *
+     * Detection Methods:
+     * 1. Frontmatter: project: backend OR projects: [backend, frontend]
+     * 2. Increment Name: Contains project keyword (0031-backend-api-sync)
+     * 3. Config: livingDocs.hierarchyMapping.incrementToProjects
+     * 4. Fallback: ['default'] (single-project mode)
      */
-    async detectEpicMapping(incrementId) {
-        return this.detectFeatureMapping(incrementId);
+    async detectProjects(incrementId) {
+        const specPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId, 'spec.md');
+        if (!fs.existsSync(specPath)) {
+            // Fallback to configured projects when spec missing
+            return await this.getConfiguredProjects();
+        }
+        const content = await fs.readFile(specPath, 'utf-8');
+        const config = await this.getSpecweaveConfig();
+        const configuredProjects = await this.getConfiguredProjects();
+        // Method 1: Frontmatter (explicit)
+        const frontmatterProjects = await this.detectProjectsFromFrontmatter(content);
+        if (frontmatterProjects.length > 0) {
+            // Validate projects exist in config
+            const validProjects = frontmatterProjects.filter(p => configuredProjects.includes(p));
+            if (validProjects.length > 0) {
+                return validProjects;
+            }
+        }
+        // Method 2: Increment name (contains project keyword)
+        const nameProjects = this.detectProjectsFromIncrementName(incrementId, configuredProjects, config);
+        if (nameProjects.length > 0) {
+            return nameProjects;
+        }
+        // Method 3: Config mapping
+        const configProjects = await this.detectProjectsFromConfig(incrementId);
+        if (configProjects.length > 0) {
+            return configProjects;
+        }
+        // Fallback: Use configured projects (single-project mode uses repo name, not 'default')
+        return configuredProjects;
     }
     /**
-     * Detect feature from frontmatter (epic: feature-name)
-     *
-     * FORMAT (v0.18.1+): Accepts simple feature names (external-tool-status-sync)
-     * LEGACY: Also accepts old FS-### format (FS-001) - extracts from increment name instead
+     * Detect epic from frontmatter
      */
-    async detectFromFrontmatter(content, incrementId) {
+    async detectEpicFromFrontmatter(content, incrementId) {
         const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
         if (!frontmatterMatch)
             return null;
         try {
             const yaml = await import('yaml');
             const frontmatter = yaml.parse(frontmatterMatch[1]);
-            // Check for explicit epic field
             if (frontmatter.epic && typeof frontmatter.epic === 'string') {
-                const epicValue = frontmatter.epic;
-                // Handle LEGACY numeric format (FS-001, FS-031) → extract from increment name
-                if (epicValue.match(/^FS-\d+$/)) {
-                    console.log(`   ⚠️  Legacy FS-### format detected (${epicValue}), extracting feature name from increment...`);
-                    return await this.detectFromIncrementName(incrementId);
-                }
-                // NEW FORMAT: FS-25-11-14-feature-name (date-based) OR plain feature-name
-                const featureFolder = await this.findFeatureFolder(epicValue);
-                if (featureFolder) {
-                    return {
-                        featureId: featureFolder, // ID = folder name
-                        featureFolder,
-                        featurePath: path.join(this.config.specsBaseDir, featureFolder),
-                        userStoriesPath: path.join(this.config.specsBaseDir, featureFolder, this.config.userStoriesSubdir),
-                        confidence: 100,
-                        detectionMethod: 'frontmatter',
-                    };
+                const epicId = frontmatter.epic; // EPIC-2025-Q4-platform
+                const epicFolder = epicId;
+                const epicPath = path.join(this.config.specsBaseDir, '_epics', epicFolder);
+                // Try to detect which features belong to this epic (from existing EPIC.md)
+                const epicFilePath = path.join(epicPath, 'EPIC.md');
+                let features = [];
+                if (fs.existsSync(epicFilePath)) {
+                    const epicContent = await fs.readFile(epicFilePath, 'utf-8');
+                    // Extract feature IDs from epic file (simple pattern matching)
+                    const featureMatches = epicContent.matchAll(/FS-\d{2}-\d{2}-\d{2}-[a-z0-9-]+/g);
+                    features = Array.from(featureMatches, m => m[0]);
                 }
+                return {
+                    epicId,
+                    epicFolder,
+                    epicPath,
+                    features,
+                    confidence: 100,
+                    detectionMethod: 'frontmatter',
+                };
             }
         }
         catch (error) {
-            console.warn(`   ⚠️  Failed to parse frontmatter: ${error}`);
+            console.warn(`   ⚠️  Failed to parse frontmatter for epic detection: ${error}`);
         }
         return null;
     }
     /**
-     * Detect feature from increment NAME
+     * Detect epic from config
+     */
+    async detectEpicFromConfig(incrementId) {
+        const config = await this.getSpecweaveConfig();
+        const epicMapping = config.livingDocs?.hierarchyMapping?.incrementToEpic?.[incrementId];
+        if (epicMapping && typeof epicMapping === 'string') {
+            const epicId = epicMapping;
+            const epicFolder = epicId;
+            const epicPath = path.join(this.config.specsBaseDir, '_epics', epicFolder);
+            return {
+                epicId,
+                epicFolder,
+                epicPath,
+                features: [],
+                confidence: 100,
+                detectionMethod: 'config',
+            };
+        }
+        return null;
+    }
+    /**
+     * Detect feature from frontmatter
      *
-     * FORMAT (v0.18.1+): Simple descriptive names (no date prefixes)
+     * CRITICAL: For greenfield projects, ALWAYS use increment number (FS-XXX)
+     * even if frontmatter says FS-YY-MM-DD-name (date-based format)
+     */
+    async detectFeatureFromFrontmatter(content, incrementId) {
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!frontmatterMatch)
+            return null;
+        try {
+            const yaml = await import('yaml');
+            const frontmatter = yaml.parse(frontmatterMatch[1]);
+            if (frontmatter.feature && typeof frontmatter.feature === 'string') {
+                let featureId = frontmatter.feature;
+                // Check if this is a brownfield project (imported from external tool)
+                const isBrownfield = frontmatter.source === 'external' || frontmatter.imported === true;
+                if (!isBrownfield) {
+                    // Greenfield: ALWAYS use increment number, ignore frontmatter's date-based ID
+                    const numMatch = incrementId.match(/^(\d{4})-/);
+                    if (numMatch) {
+                        const num = parseInt(numMatch[1], 10);
+                        featureId = `FS-${String(num).padStart(3, '0')}`;
+                    }
+                }
+                // For brownfield, keep the date-based ID from frontmatter
+                const projects = await this.detectProjects(incrementId);
+                const epic = frontmatter.epic || undefined;
+                return this.buildFeatureMapping(featureId, projects, epic, 100, 'frontmatter');
+            }
+        }
+        catch (error) {
+            console.warn(`   ⚠️  Failed to parse frontmatter for feature detection: ${error}`);
+        }
+        return null;
+    }
+    /**
+     * Detect feature from increment name
      *
-     * Extracts the descriptive part of increment ID and normalizes it to feature name
      * Examples:
-     *   0023-release-management-enhancements → release-management (new or existing)
-     *   0031-external-tool-status-sync → external-tool-status-sync
+     * - 0031-external-tool-status-sync → FS-031
+     * - 0032-user-authentication → FS-032
+     * - 0001-core-framework → FS-001
      */
-    async detectFromIncrementName(incrementId) {
-        // Extract name part (after number: 0023-release-management-enhancements → release-management-enhancements)
-        const nameMatch = incrementId.match(/^\d+-(.+)/);
-        if (!nameMatch)
+    async detectFeatureFromIncrementName(incrementId) {
+        // Extract increment number (first 4 digits)
+        const numMatch = incrementId.match(/^(\d{4})-/);
+        if (!numMatch)
             return null;
-        const fullName = nameMatch[1]; // release-management-enhancements
-        // Extract core feature name (remove suffixes like -enhancements, -improvements, -fixes)
-        const suffixesToRemove = ['-enhancements', '-improvements', '-fixes', '-updates', '-v2', '-v3'];
-        let featureName = fullName;
-        for (const suffix of suffixesToRemove) {
-            if (featureName.endsWith(suffix)) {
-                featureName = featureName.slice(0, -suffix.length);
-                break;
-            }
+        const num = parseInt(numMatch[1], 10);
+        // Build feature ID: FS-XXX (using last 3 digits, zero-padded)
+        const featureId = `FS-${String(num).padStart(3, '0')}`;
+        // Detect projects
+        const projects = await this.detectProjects(incrementId);
+        // Check if feature folder already exists
+        const existingFeature = await this.findExistingFeatureFolder(featureId);
+        if (existingFeature) {
+            return this.buildFeatureMapping(existingFeature, projects, undefined, 90, 'increment-name');
         }
-        // Try to find existing feature folder (legacy or new format)
-        let featureFolder = await this.findFeatureFolder(featureName);
-        // If not found, try with full name
-        if (!featureFolder) {
-            featureFolder = await this.findFeatureFolder(fullName);
+        return this.buildFeatureMapping(featureId, projects, undefined, 90, 'increment-name');
+    }
+    /**
+     * Detect feature from config
+     */
+    async detectFeatureFromConfig(incrementId) {
+        const config = await this.getSpecweaveConfig();
+        const featureMapping = config.livingDocs?.hierarchyMapping?.incrementToFeature?.[incrementId];
+        if (featureMapping && typeof featureMapping === 'string') {
+            const featureId = featureMapping;
+            const projects = await this.detectProjects(incrementId);
+            return this.buildFeatureMapping(featureId, projects, undefined, 100, 'config');
+        }
+        return null;
+    }
+    /**
+     * Create fallback feature mapping
+     */
+    async createFallbackFeatureMapping(incrementId) {
+        // Extract increment number (first 4 digits)
+        const numMatch = incrementId.match(/^(\d{4})-/);
+        if (!numMatch) {
+            throw new Error(`Invalid increment ID format: ${incrementId}`);
         }
-        // If not found, use simple feature name (no date prefix, no FS- prefix)
-        if (!featureFolder) {
-            featureFolder = featureName; // Simple: external-tool-status-sync
-            console.log(`   ✨ Creating new feature folder: ${featureFolder}`);
+        const num = parseInt(numMatch[1], 10);
+        // Build feature ID: FS-XXX (using last 3 digits, zero-padded)
+        const featureId = `FS-${String(num).padStart(3, '0')}`;
+        // Detect projects
+        const projects = await this.detectProjects(incrementId);
+        console.log(`   📁 Creating new feature: ${featureId}`);
+        return this.buildFeatureMapping(featureId, projects, undefined, 80, 'fallback');
+    }
+    /**
+     * Build FeatureMapping object
+     *
+     * CRITICAL: For greenfield (FS-XXX format), use the feature ID directly.
+     * The feature ID manager is only used for brownfield (date-based) IDs.
+     */
+    buildFeatureMapping(featureId, projects, epic, confidence, detectionMethod) {
+        // Check if this is greenfield (FS-XXX) or brownfield (FS-YY-MM-DD-name)
+        const isGreenfield = /^FS-\d{3}$/.test(featureId);
+        // For greenfield, use the feature ID directly (no registry lookup)
+        // For brownfield, get assigned ID from registry (for deduplication)
+        const finalFeatureId = isGreenfield
+            ? featureId
+            : this.featureIdManager.getAssignedId(featureId);
+        // Use final ID for folders
+        const featureFolder = finalFeatureId;
+        const featurePath = path.join(this.config.specsBaseDir, '_features', featureFolder);
+        // Build project paths map using final ID
+        const projectPaths = new Map();
+        for (const project of projects) {
+            projectPaths.set(project, path.join(this.config.specsBaseDir, project, finalFeatureId));
         }
         return {
-            featureId: featureFolder, // ID = folder name (for consistency)
+            featureId: finalFeatureId,
             featureFolder,
-            featurePath: path.join(this.config.specsBaseDir, featureFolder),
-            userStoriesPath: path.join(this.config.specsBaseDir, featureFolder, this.config.userStoriesSubdir),
-            confidence: 90,
-            detectionMethod: 'increment-name',
+            featurePath,
+            projects,
+            projectPaths,
+            epic,
+            confidence,
+            detectionMethod,
         };
     }
     /**
-     * Detect feature from config mapping (explicit increment → feature mapping)
+     * Detect projects from frontmatter
      */
-    async detectFromConfig(incrementId) {
-        // Load config to check for explicit mapping
-        const configPath = path.join(this.projectRoot, '.specweave', 'config.json');
-        if (!fs.existsSync(configPath))
-            return null;
+    async detectProjectsFromFrontmatter(content) {
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!frontmatterMatch)
+            return [];
         try {
-            const config = JSON.parse(await fs.readFile(configPath, 'utf-8'));
-            const featureMapping = config.livingDocs?.hierarchyMapping?.incrementToFeature?.[incrementId];
-            if (featureMapping && typeof featureMapping === 'string') {
-                const featureFolder = await this.findFeatureFolder(featureMapping);
-                if (featureFolder) {
-                    return {
-                        featureId: featureMapping,
-                        featureFolder,
-                        featurePath: path.join(this.config.specsBaseDir, featureFolder),
-                        userStoriesPath: path.join(this.config.specsBaseDir, featureFolder, this.config.userStoriesSubdir),
-                        confidence: 100,
-                        detectionMethod: 'config',
-                    };
-                }
+            const yaml = await import('yaml');
+            const frontmatter = yaml.parse(frontmatterMatch[1]);
+            // Single project: project: backend
+            if (frontmatter.project && typeof frontmatter.project === 'string') {
+                return [frontmatter.project];
+            }
+            // Multiple projects: projects: [backend, frontend]
+            if (frontmatter.projects && Array.isArray(frontmatter.projects)) {
+                return frontmatter.projects.filter((p) => typeof p === 'string');
             }
         }
         catch (error) {
-            console.warn(`   ⚠️  Failed to load config: ${error}`);
+            console.warn(`   ⚠️  Failed to parse frontmatter for project detection: ${error}`);
         }
-        return null;
+        return [];
     }
     /**
-     * Create fallback mapping (extract feature name from increment ID)
-     *
-     * FORMAT (v0.18.1+): Simple descriptive names (no prefixes)
-     * - Uses core feature name extracted from increment ID
-     * - No date prefixes (removed to prevent duplicates)
-     * - No FS- prefixes (features are not numbered)
-     *
-     * Example: 0023-release-management-enhancements → release-management
+     * Detect projects from increment name (keyword matching)
      */
-    async createFallbackMapping(incrementId) {
-        // Extract name from increment ID
-        const nameMatch = incrementId.match(/^\d+-(.+)/);
-        const fullName = nameMatch ? nameMatch[1] : 'unknown';
-        // Remove common suffixes to get core feature name
-        const suffixesToRemove = ['-enhancements', '-improvements', '-fixes', '-updates', '-v2', '-v3'];
-        let featureName = fullName;
-        for (const suffix of suffixesToRemove) {
-            if (featureName.endsWith(suffix)) {
-                featureName = featureName.slice(0, -suffix.length);
-                break;
+    detectProjectsFromIncrementName(incrementId, configuredProjects, config) {
+        const detectedProjects = [];
+        for (const projectId of configuredProjects) {
+            if (projectId === 'default')
+                continue;
+            const projectConfig = config.multiProject?.projects?.[projectId];
+            if (!projectConfig)
+                continue;
+            // Check if increment name contains project keywords
+            const keywords = projectConfig.keywords || [projectId];
+            for (const keyword of keywords) {
+                if (incrementId.toLowerCase().includes(keyword.toLowerCase())) {
+                    detectedProjects.push(projectId);
+                    break;
+                }
             }
         }
-        // Use simple feature name (no date prefix, no FS- prefix)
-        const featureFolder = featureName; // Simple: external-tool-status-sync
-        const featurePath = path.join(this.config.specsBaseDir, featureFolder);
-        const userStoriesPath = path.join(featurePath, this.config.userStoriesSubdir);
-        // Create folder if it doesn't exist
-        if (!fs.existsSync(featurePath)) {
-            console.log(`   📁 Creating new feature folder: ${featureFolder}`);
-            await fs.ensureDir(featurePath);
+        return detectedProjects;
+    }
+    /**
+     * Detect projects from config
+     */
+    async detectProjectsFromConfig(incrementId) {
+        const config = await this.getSpecweaveConfig();
+        const projectMapping = config.livingDocs?.hierarchyMapping?.incrementToProjects?.[incrementId];
+        if (projectMapping) {
+            if (typeof projectMapping === 'string') {
+                return [projectMapping];
+            }
+            if (Array.isArray(projectMapping)) {
+                return projectMapping.filter((p) => typeof p === 'string');
+            }
         }
-        return {
-            featureId: featureFolder, // ID = folder name (external-tool-status-sync)
-            featureFolder,
-            featurePath,
-            userStoriesPath,
-            confidence: 80,
-            detectionMethod: 'fallback',
-        };
+        return [];
     }
     /**
-     * Get increment creation date in yy-mm-dd format
+     * Get increment creation date in YY-MM-DD format
+     *
      * Tries: metadata.json → spec.md frontmatter → current date
      */
     async getIncrementCreationDate(incrementId) {
@@ -246,7 +523,7 @@ export class HierarchyMapper {
                 }
             }
             catch (error) {
-                // Fall through to next method
+                // Fall through
             }
         }
         // Try spec.md frontmatter
@@ -264,14 +541,14 @@ export class HierarchyMapper {
                 }
             }
             catch (error) {
-                // Fall through to current date
+                // Fall through
             }
         }
         // Fallback: current date
         return this.formatDateShort(new Date().toISOString());
     }
     /**
-     * Format date as yy-mm-dd
+     * Format date as YY-MM-DD
      * Input: "2025-11-14" or "2025-11-14T12:00:00Z"
      * Output: "25-11-14"
      */
@@ -283,58 +560,66 @@ export class HierarchyMapper {
         return `${yy}-${mm}-${dd}`;
     }
     /**
-     * NEW: Find feature folder by name (exact match or fuzzy match)
+     * Find existing feature folder (exact or fuzzy match)
      *
-     * Examples:
-     *   release-management → release-management/
-     *   external-tool-sync → external-tool-status-sync/ (fuzzy match)
+     * CRITICAL: For greenfield (FS-XXX), only exact match.
+     * For brownfield (FS-YY-MM-DD-name), fuzzy match allowed.
      */
-    async findFeatureFolder(featureName) {
+    async findExistingFeatureFolder(featureId) {
+        const featuresDir = path.join(this.config.specsBaseDir, '_features');
+        if (!fs.existsSync(featuresDir)) {
+            return null;
+        }
         try {
-            const folders = await fs.readdir(this.config.specsBaseDir);
-            // First: Try exact match
-            if (folders.includes(featureName)) {
-                const folderPath = path.join(this.config.specsBaseDir, featureName);
-                const stats = await fs.stat(folderPath);
-                if (stats.isDirectory()) {
-                    return featureName;
-                }
+            const folders = await fs.readdir(featuresDir);
+            // Exact match (always try this first)
+            if (folders.includes(featureId)) {
+                return featureId;
+            }
+            // Fuzzy match ONLY for brownfield (date-based) IDs
+            // Greenfield IDs (FS-XXX) should NEVER fuzzy match
+            const isGreenfield = /^FS-\d{3}$/.test(featureId);
+            if (isGreenfield) {
+                return null; // No fuzzy match for greenfield
+            }
+            // Fuzzy match for brownfield (feature name is substring)
+            // Example: FS-25-11-14-external-tool-sync matches FS-25-11-14-external-tool-status-sync
+            const featureNamePart = featureId.split('-').slice(3).join('-'); // external-tool-sync
+            if (!featureNamePart) {
+                return null; // No feature name part, skip fuzzy match
             }
-            // Second: Try fuzzy match (feature name is substring of folder name)
             for (const folder of folders) {
-                if (folder.startsWith(featureName) || folder.includes(featureName)) {
-                    const folderPath = path.join(this.config.specsBaseDir, folder);
+                if (folder.includes(featureNamePart)) {
+                    const folderPath = path.join(featuresDir, folder);
                     const stats = await fs.stat(folderPath);
-                    if (stats.isDirectory() && folder !== 'README.md') {
+                    if (stats.isDirectory()) {
                         return folder;
                     }
                 }
             }
         }
         catch (error) {
-            console.warn(`   ⚠️  Failed to find feature folder for ${featureName}: ${error}`);
+            console.warn(`   ⚠️  Failed to find feature folder: ${error}`);
         }
         return null;
     }
     /**
-     * LEGACY: Find FS-* epic folder (for backward compatibility)
-     */
-    async findEpicFolder(epicId) {
-        return this.findFeatureFolder(epicId);
-    }
-    /**
-     * Get all feature folders (NEW: no FS- prefix filtering)
+     * Get all feature folders
      */
     async getAllFeatureFolders() {
+        const featuresDir = path.join(this.config.specsBaseDir, '_features');
+        if (!fs.existsSync(featuresDir)) {
+            return [];
+        }
         try {
-            const folders = await fs.readdir(this.config.specsBaseDir);
+            const folders = await fs.readdir(featuresDir);
             const featureFolders = [];
             for (const folder of folders) {
                 // Skip special files/folders
-                if (folder === 'README.md' || folder.startsWith('.') || folder.startsWith('_')) {
+                if (folder.startsWith('.') || folder.startsWith('_')) {
                     continue;
                 }
-                const folderPath = path.join(this.config.specsBaseDir, folder);
+                const folderPath = path.join(featuresDir, folder);
                 const stats = await fs.stat(folderPath);
                 if (stats.isDirectory()) {
                     featureFolders.push(folder);
@@ -348,106 +633,39 @@ export class HierarchyMapper {
         }
     }
     /**
-     * LEGACY: Get all epic folders (for backward compatibility)
+     * Get all epic folders
      */
     async getAllEpicFolders() {
-        return this.getAllFeatureFolders();
-    }
-    /**
-     * Validate feature folder structure (NEW: checks for FEATURE.md)
-     */
-    async validateFeatureFolder(featureFolder) {
-        const featurePath = path.join(this.config.specsBaseDir, featureFolder);
-        const missing = [];
-        // Check FEATURE.md exists (feature overview)
-        if (!fs.existsSync(path.join(featurePath, 'FEATURE.md'))) {
-            missing.push('FEATURE.md');
-        }
-        // Note: User stories (us-*.md) go directly in feature folder, no validation needed here
-        return {
-            valid: missing.length === 0,
-            missing,
-        };
-    }
-    /**
-     * LEGACY: Validate epic folder structure (for backward compatibility)
-     */
-    async validateEpicFolder(epicFolder) {
-        return this.validateFeatureFolder(epicFolder);
-    }
-    /**
-     * Create feature folder structure if missing (NEW: creates FEATURE.md)
-     */
-    async createFeatureFolderStructure(featureFolder, title) {
-        const featurePath = path.join(this.config.specsBaseDir, featureFolder);
-        // Create feature directory (user stories go directly here, no subfolder)
-        await fs.ensureDir(featurePath);
-        // Create FEATURE.md if missing (feature overview - high-level summary)
-        const featureFilePath = path.join(featurePath, 'FEATURE.md');
-        if (!fs.existsSync(featureFilePath)) {
-            // ID = folder name (e.g., FS-25-11-14-release-management)
-            const featureContent = `---
-id: ${featureFolder}
-title: "${title}"
-type: feature
-status: in-progress
-priority: P1
-created: ${new Date().toISOString().split('T')[0]}
-last_updated: ${new Date().toISOString().split('T')[0]}
-# External Tool Mapping
-external_tools:
-  github:
-    type: project
-    id: null
-    url: null
-  jira:
-    type: epic
-    key: null
-    url: null
-  ado:
-    type: epic
-    id: null
-    url: null
----
-
-# ${featureFolder}: ${title}
-
-## Overview
-
-[High-level description of this feature - what it does and why it matters]
-
-## Business Value
-
-[Add business value and impact]
-
-## User Stories
-
-User stories are in this folder as \`us-*.md\` files:
-- us-001-*.md
-- us-002-*.md
-- ...
-
-## Implementation History
-
-| Increment | Stories Implemented | Status | Completion Date |
-|-----------|-------------------|--------|----------------|
-| [TBD]() | TBD | 🚧 In Progress | TBD |
-
-## External Tool Integration
-
-**GitHub Project**: Not yet synced
-**Jira Epic**: Not yet synced
-**Azure DevOps Epic**: Not yet synced
-`;
-            await fs.writeFile(featureFilePath, featureContent, 'utf-8');
-            console.log(`   ✅ Created FEATURE.md for ${featureFolder}`);
+        const epicsDir = path.join(this.config.specsBaseDir, '_epics');
+        if (!fs.existsSync(epicsDir)) {
+            return [];
+        }
+        try {
+            const folders = await fs.readdir(epicsDir);
+            const epicFolders = [];
+            for (const folder of folders) {
+                // Skip special files/folders
+                if (folder.startsWith('.') || folder.startsWith('_')) {
+                    continue;
+                }
+                const folderPath = path.join(epicsDir, folder);
+                const stats = await fs.stat(folderPath);
+                if (stats.isDirectory()) {
+                    epicFolders.push(folder);
+                }
+            }
+            return epicFolders.sort();
+        }
+        catch (error) {
+            console.warn(`   ⚠️  Failed to get epic folders: ${error}`);
+            return [];
         }
     }
     /**
-     * LEGACY: Create epic folder structure (for backward compatibility)
+     * LEGACY: Backward compatibility alias for detectFeatureMapping
      */
-    async createEpicFolderStructure(epicFolder, title) {
-        return this.createFeatureFolderStructure(epicFolder, title);
+    async detectEpicMapping_LEGACY(incrementId) {
+        return this.detectFeatureMapping(incrementId);
     }
 }
 //# sourceMappingURL=hierarchy-mapper.js.map