specweave 0.30.14 → 0.30.17

package/dist/src/core/living-docs/living-docs-sync.js

@@ -24,9 +24,11 @@ import { BoardMatcher } from './board-matcher.js';
 import { consoleLogger } from '../../utils/logger.js';
 import { autoDetectProjectIdSync } from '../../utils/project-detection.js';
 import { getGitHubAuthFromProject } from '../../utils/auth-helpers.js';
-// NOTE (2025-12-01): findNextAvailableInternalIdSync removed - internal features don't need collision check
-// Collision detection is only for EXTERNAL features (FS-XXXE) imported from GitHub/JIRA/ADO
-import { deriveFeatureId } from '../../utils/feature-id-derivation.js';
+// CRITICAL FIX (2025-12-04): Re-enabled collision detection for internal features
+// Bug: When external features (FS-001E) exist, internal features (FS-001) must NOT collide
+// IDs are scoped per project/board - each board has its own FS-XXX sequence
+import { findNextAvailableInternalIdSync } from '../../utils/feature-id-collision.js';
+import { extractIncrementNumber } from '../../utils/feature-id-derivation.js';
 // Import sync profile helpers for provider detection (v0.31.0+)
 import { getProfilesByProvider } from '../types/sync-profile.js';
 // Import extracted helpers
@@ -98,8 +100,13 @@ export class LivingDocsSync {
             }
             // Step 1: Build feature registry (auto-generates IDs for greenfield)
             await this.featureIdManager.buildRegistry();
-            // Step 2: Get feature ID (derived from increment number)
-            // SIMPLIFIED (v0.29.0): Feature ID is now always derived, not stored in metadata
+            // Step 2: Resolve project path FIRST (needed for collision detection)
+            // CRITICAL FIX (2025-12-04): Moved before feature ID derivation
+            // Collision detection is scoped per project/board
+            const basePath = path.join(this.projectRoot, '.specweave/docs/internal/specs');
+            const resolvedProjectPath = await this.resolveProjectPath(incrementId);
+            // Step 3: Get feature ID (derived from increment number WITH collision detection)
+            // CRITICAL FIX (2025-12-04): Now checks for FS-XXXE collisions
             let featureId;
             if (options.explicitFeatureId && /^FS-\d{3,}E?$/.test(options.explicitFeatureId)) {
                 // Allow explicit override for special cases (e.g., epic linking)
@@ -107,22 +114,16 @@ export class LivingDocsSync {
                 this.logger.log(`📎 Using explicit feature ID: ${featureId}`);
             }
             else {
-                // Derive from increment number (the normal case)
-                featureId = await this.getFeatureIdForIncrement(incrementId);
+                // Derive from increment number with collision detection
+                featureId = await this.getFeatureIdForIncrement(incrementId, resolvedProjectPath);
                 this.logger.log(`🔄 Derived feature ID: ${featureId}`);
             }
             result.featureId = featureId;
             // NOTE (v0.29.0): No longer write feature_id to metadata.json
             // Feature ID is derived from increment number - see ADR-0140
             this.logger.log(`📚 Syncing ${incrementId} → ${featureId}...`);
-            // Step 3: Parse increment spec
+            // Step 4: Parse increment spec
             const parsed = await this.parseIncrementSpec(incrementId);
-            // Step 4: Create living docs structure
-            // Structure: specs/{project}/FS-XXX/FEATURE.md (+ user stories)
-            // CRITICAL FIX (2025-12-02): Use smart project path resolution for brownfield setups
-            // This handles hierarchical paths like "acme/digital-operations-services"
-            const basePath = path.join(this.projectRoot, '.specweave/docs/internal/specs');
-            const resolvedProjectPath = await this.resolveProjectPath(incrementId);
             // Create {project}/FS-XXX/FEATURE.md
             const projectPath = path.join(basePath, resolvedProjectPath, featureId);
             this.logger.log(`   📁 Feature folder: ${resolvedProjectPath}/${featureId}/`);
@@ -201,163 +202,245 @@ export class LivingDocsSync {
         }
     }
     /**
-     * Get feature ID for increment
+     * Get feature ID for increment with collision detection
      *
      * SIMPLIFIED (v0.29.0): Feature ID is derived from increment number
      * No longer reads from metadata.json - derivation is the single source of truth
      *
-     * CRITICAL FIX (2025-12-01): Internal features are DETERMINISTIC - no collision check!
-     * - Increment 0060 → ALWAYS FS-060, never anything else
-     * - Increment 0072 → ALWAYS FS-072, never anything else
-     * - Sync is IDEMPOTENT: if FS-060 exists, UPDATE it (don't create FS-061)
+     * CRITICAL FIX (2025-12-04): Re-enabled collision detection!
+     * The previous assumption that "internal features are deterministic" was WRONG
+     * when external imports exist. If FS-001E exists, internal increment 0001
+     * must use FS-002 to avoid collision.
      *
-     * Collision detection is ONLY for EXTERNAL features (FS-XXXE) during imports,
-     * NOT for internal features derived from increment numbers.
+     * Collision detection is SCOPED per project/board:
+     * - Each project has its own FS-XXX sequence
+     * - Scans both FS-XXX and FS-XXXE folders
+     * - Also scans _orphans folder for US-XXX files
      *
+     * @param incrementId - Increment ID (e.g., "0081-ado-repo-cloning")
+     * @param resolvedProjectPath - Resolved project path (e.g., "acme/backend" or "my-project")
+     * @returns Feature ID with collision avoidance (e.g., "FS-081" or "FS-082" if 081 exists)
      * @see deriveFeatureId() in src/utils/feature-id-derivation.ts
-     * @see ADR-0140 for rationale
      */
-    async getFeatureIdForIncrement(incrementId) {
-        // Derive feature ID directly from increment number (e.g., "0081-name" → "FS-081")
-        // NO collision checking - internal feature IDs are deterministic and unique by design
-        return deriveFeatureId(incrementId);
+    async getFeatureIdForIncrement(incrementId, resolvedProjectPath) {
+        // Extract increment number (e.g., "0081-name" → 81)
+        const incrementNumber = extractIncrementNumber(incrementId);
+        // Build path to project's specs folder for collision detection
+        const specsPath = path.join(this.projectRoot, '.specweave/docs/internal/specs');
+        // CRITICAL: Use collision detection to avoid FS-XXX vs FS-XXXE conflicts
+        // This is scoped to the specific project/board folder
+        const safeNumber = findNextAvailableInternalIdSync(incrementNumber, specsPath, resolvedProjectPath, { logger: this.logger });
+        // Generate feature ID from safe number
+        const featureId = `FS-${String(safeNumber).padStart(3, '0')}`;
+        // Log if collision was avoided
+        if (safeNumber !== incrementNumber) {
+            this.logger.warn(`   ⚠️ Feature ID collision avoided: FS-${String(incrementNumber).padStart(3, '0')} exists, ` +
+                `using ${featureId} instead`);
+        }
+        return featureId;
     }
     /**
-     * Extract project name from increment spec.md
+     * Extract project and board from increment spec.md YAML frontmatter
+     *
+     * Priority:
+     * 1. YAML frontmatter `project:` field (v0.31.0+ - preferred)
+     * 2. Legacy **Project**: field in body (backward compatibility)
      *
-     * Looks for the **Project**: field in spec.md (e.g., "**Project**: digital-operation-services")
+     * For 2-level structures, also extracts `board:` field.
      *
-     * SECURITY: Validates both incrementId and extracted project name to prevent path traversal
+     * SECURITY: Validates both incrementId and extracted names to prevent path traversal
      *
      * @param incrementId - Increment ID (e.g., "0002-test-anton-monitor")
-     * @returns Project name or null if not specified or invalid
+     * @returns Object with project and board (null if not specified or invalid)
      */
-    async extractProjectFromSpec(incrementId) {
+    async extractProjectBoardFromSpec(incrementId) {
         // SECURITY FIX (2025-12-02): Validate incrementId format FIRST
-        // Prevents path traversal via malicious increment IDs like "../../../etc"
         if (!incrementId || !/^\d{4}-[a-z0-9-]+$/i.test(incrementId)) {
             this.logger.warn(`   ⚠️  Invalid increment ID format: ${incrementId}`);
-            return null;
+            return { project: null, board: null };
         }
         const specPath = path.join(this.projectRoot, '.specweave/increments', incrementId, 'spec.md');
         if (!existsSync(specPath)) {
-            return null;
+            return { project: null, board: null };
         }
         try {
             const content = await fs.readFile(specPath, 'utf-8');
-            // Match **Project**: value or **Project:** value (with or without space after colon)
-            const projectMatch = content.match(/\*\*Project\*\*:\s*(.+?)(?:\n|$)/i);
-            if (projectMatch && projectMatch[1]) {
-                // Strip markdown formatting before normalization
-                const rawProjectName = projectMatch[1]
-                    .trim()
-                    .replace(/\*\*/g, '') // Remove bold markers
-                    .replace(/__/g, '') // Remove italic markers
-                    .replace(/`/g, ''); // Remove code markers
-                const projectName = rawProjectName.toLowerCase().replace(/\s+/g, '-');
-                // SECURITY: Minimum length check to prevent empty names after stripping
-                if (!projectName || projectName.length < 2) {
-                    this.logger.warn(`   ⚠️  Project name too short: ${projectName}`);
-                    return null;
+            let project = null;
+            let board = null;
+            // 1. Try YAML frontmatter first (preferred - v0.31.0+)
+            const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+            if (frontmatterMatch) {
+                const frontmatter = frontmatterMatch[1];
+                // Extract project from YAML
+                const yamlProjectMatch = frontmatter.match(/^project:\s*["']?([^"'\n]+)["']?$/m);
+                if (yamlProjectMatch && yamlProjectMatch[1]) {
+                    project = this.validateAndNormalizeName(yamlProjectMatch[1].trim(), 'project');
                 }
-                // CRITICAL SECURITY: Block path traversal attempts
-                // Reject names containing: .., /, \, or null bytes
-                if (projectName.includes('..') ||
-                    projectName.includes('/') ||
-                    projectName.includes('\\') ||
-                    projectName.includes('\0')) {
-                    this.logger.warn(`   ⚠️  Invalid project name (potential path traversal): ${projectName}`);
-                    return null;
+                // Extract board from YAML
+                const yamlBoardMatch = frontmatter.match(/^board:\s*["']?([^"'\n]+)["']?$/m);
+                if (yamlBoardMatch && yamlBoardMatch[1]) {
+                    board = this.validateAndNormalizeName(yamlBoardMatch[1].trim(), 'board');
                 }
-                // Validate: only allow alphanumeric, hyphens, underscores
-                if (!/^[a-z0-9_-]+$/.test(projectName)) {
-                    this.logger.warn(`   ⚠️  Invalid project name (invalid characters): ${projectName}`);
-                    return null;
+            }
+            // 2. Fallback to legacy **Project**: field in body
+            if (!project) {
+                const bodyProjectMatch = content.match(/\*\*Project\*\*:\s*(.+?)(?:\n|$)/i);
+                if (bodyProjectMatch && bodyProjectMatch[1]) {
+                    const rawName = bodyProjectMatch[1]
+                        .trim()
+                        .replace(/\*\*/g, '')
+                        .replace(/__/g, '')
+                        .replace(/`/g, '');
+                    project = this.validateAndNormalizeName(rawName, 'project');
+                    if (project) {
+                        this.logger.log(`   ℹ️  Using legacy **Project**: field - consider migrating to YAML frontmatter`);
+                    }
                 }
-                return projectName;
             }
+            return { project, board };
         }
         catch {
-            // Ignore errors, return null
+            return { project: null, board: null };
+        }
+    }
+    /**
+     * Validate and normalize a project/board name
+     *
+     * SECURITY: Prevents path traversal and validates format
+     */
+    validateAndNormalizeName(rawName, fieldType) {
+        if (!rawName)
+            return null;
+        const normalized = rawName.toLowerCase().replace(/\s+/g, '-');
+        // Minimum length check
+        if (normalized.length < 2) {
+            this.logger.warn(`   ⚠️  ${fieldType} name too short: ${normalized}`);
+            return null;
+        }
+        // Block path traversal attempts
+        if (normalized.includes('..') ||
+            normalized.includes('/') ||
+            normalized.includes('\\') ||
+            normalized.includes('\0')) {
+            this.logger.warn(`   ⚠️  Invalid ${fieldType} name (potential path traversal): ${normalized}`);
+            return null;
         }
-        return null;
+        // Validate characters
+        if (!/^[a-z0-9_-]+$/.test(normalized)) {
+            this.logger.warn(`   ⚠️  Invalid ${fieldType} name (invalid characters): ${normalized}`);
+            return null;
+        }
+        return normalized;
     }
     /**
-     * Resolve the project path for an increment (SMART BOARD MATCHING - v0.31.0+)
+     * Extract project name from increment spec.md (legacy method - delegates to new method)
+     */
+    async extractProjectFromSpec(incrementId) {
+        const { project } = await this.extractProjectBoardFromSpec(incrementId);
+        return project;
+    }
+    /**
+     * Resolve the project path for an increment (v0.31.0+ - SPEC.MD FRONTMATTER REQUIRED)
      *
-     * For brownfield projects imported from ADO/JIRA, uses intelligent board matching
-     * based on increment title, description, and configured keywords.
+     * For new increments (v0.31.0+), spec.md MUST have `project:` field in YAML frontmatter.
+     * For 2-level structures, spec.md MUST have BOTH `project:` and `board:` fields.
      *
      * Priority:
-     * 1. Explicit **Project**: field in spec.md (always wins)
-     * 2. Intelligent board matching using BoardMatcher (ADR-0178)
-     *    - High confidence (>80%): auto-assign
-     *    - Medium/Low confidence: ask user
-     * 3. Existing folder match (hierarchical search)
-     * 4. Default project ID (single-project fallback)
+     * 1. YAML frontmatter `project:` and `board:` fields (REQUIRED for v0.31.0+)
+     * 2. Legacy **Project**: field in body (backward compatibility only)
+     * 3. Fallback: intelligent board matching (deprecated - will warn)
      *
      * @param incrementId - Increment ID (e.g., "0002-test-anton-monitor")
-     * @returns Project path (may be hierarchical like "org/project")
+     * @returns Project path (e.g., "my-project" or "acme-corp/digital-ops")
+     * @throws Error if required fields are missing in spec.md
      */
     async resolveProjectPath(incrementId) {
-        // 1. Extract project name from spec.md **Project**: field (explicit - always wins)
-        const specProject = await this.extractProjectFromSpec(incrementId);
-        if (specProject) {
-            // Explicit project specified - use it directly
-            const normalizedProject = specProject.toLowerCase().replace(/\s+/g, '-');
-            this.logger.log(`   📎 Using explicit project from spec.md: ${normalizedProject}`);
-            // Try to find existing hierarchical path
+        // Import structure level detector
+        const { detectStructureLevel } = await import('../../utils/structure-level-detector.js');
+        const structureConfig = detectStructureLevel(this.projectRoot);
+        // 1. Extract project and board from spec.md
+        const { project, board } = await this.extractProjectBoardFromSpec(incrementId);
+        // 2. For 2-level structures, REQUIRE both project AND board
+        if (structureConfig.level === 2) {
+            if (!project) {
+                this.logger.error(`❌ Missing 'project:' field in spec.md YAML frontmatter`);
+                this.logger.error(`   This is a 2-level structure - spec.md MUST have both 'project:' and 'board:' fields.`);
+                this.logger.error(`   Detection reason: ${structureConfig.detectionReason}`);
+                this.logger.error(`   Available projects: ${structureConfig.projects.map(p => p.id).join(', ')}`);
+                throw new Error(`spec.md missing required 'project:' field. ` +
+                    `This is a 2-level structure (${structureConfig.detectionReason}). ` +
+                    `Add 'project: <project_name>' to YAML frontmatter.`);
+            }
+            if (!board) {
+                const boardOptions = structureConfig.boardsByProject?.[project]
+                    ? structureConfig.boardsByProject[project].map(b => b.id).join(', ')
+                    : 'N/A';
+                this.logger.error(`❌ Missing 'board:' field in spec.md YAML frontmatter`);
+                this.logger.error(`   This is a 2-level structure - spec.md MUST have both 'project:' and 'board:' fields.`);
+                this.logger.error(`   Detection reason: ${structureConfig.detectionReason}`);
+                this.logger.error(`   Project: ${project}`);
+                this.logger.error(`   Available boards: ${boardOptions}`);
+                throw new Error(`spec.md missing required 'board:' field. ` +
+                    `This is a 2-level structure (${structureConfig.detectionReason}). ` +
+                    `Add 'board: <board_name>' to YAML frontmatter. ` +
+                    `Available boards for ${project}: ${boardOptions}`);
+            }
+            // Construct 2-level path: {project}/{board}
+            const fullPath = `${project}/${board}`;
+            this.logger.log(`   📁 2-level path from spec.md: ${fullPath}`);
+            return fullPath;
+        }
+        // 3. For 1-level structures, project is REQUIRED (but not board)
+        if (project) {
+            this.logger.log(`   📎 Using project from spec.md: ${project}`);
+            // Try to find existing hierarchical path (for backward compatibility)
             const specsBase = path.join(this.projectRoot, '.specweave/docs/internal/specs');
             if (existsSync(specsBase)) {
-                const foundPath = await this.findBestProjectMatch(specsBase, normalizedProject);
+                const foundPath = await this.findBestProjectMatch(specsBase, project);
                 if (foundPath) {
                     this.logger.log(`   🔍 Found existing project path: ${foundPath}`);
                     return foundPath;
                 }
             }
-            return normalizedProject;
+            return project;
         }
-        // 2. No explicit project - use intelligent board matching
+        // 4. No project in spec.md - WARN and fallback to auto-detection (deprecated behavior)
+        this.logger.warn(`   ⚠️  No 'project:' field in spec.md YAML frontmatter`);
+        this.logger.warn(`   💡 Add 'project: <project_name>' to spec.md frontmatter for explicit sync target`);
+        this.logger.warn(`   ⚠️  Using auto-detection (deprecated - will be required in future versions)`);
+        // Fallback: intelligent board matching (deprecated)
         const availableBoards = await this.boardMatcher.getAvailableBoards();
         if (availableBoards.length === 0) {
-            // No boards configured - use default project detection
             return this.projectId;
         }
         if (availableBoards.length === 1) {
-            // Single board - use it directly
-            // CRITICAL FIX (v0.30.13): For ADO with 2-level structure, construct {project}/{board}
-            const board = availableBoards[0];
-            if (board.adoProject) {
-                const fullPath = `${board.adoProject}/${board.id}`;
-                this.logger.log(`   📁 Single ADO board: ${board.name} → ${fullPath}`);
+            const singleBoard = availableBoards[0];
+            if (singleBoard.adoProject) {
+                const fullPath = `${singleBoard.adoProject}/${singleBoard.id}`;
+                this.logger.log(`   📁 Single ADO board (auto-detected): ${singleBoard.name} → ${fullPath}`);
                 return fullPath;
             }
-            this.logger.log(`   📁 Single board configured: ${board.name}`);
-            return board.id;
+            this.logger.log(`   📁 Single board (auto-detected): ${singleBoard.name}`);
+            return singleBoard.id;
         }
         // Multiple boards - run intelligent matching
         const specContent = await this.getIncrementSpecContent(incrementId);
         const matchDecision = await this.boardMatcher.matchIncrement(incrementId, specContent);
-        // Check if this is a utility/cross-cutting increment
         if (this.boardMatcher.isUtilityIncrement(specContent)) {
             this.logger.log(`   🔧 Utility increment detected - asking user for board selection`);
             return await this.askUserForBoardSelection(incrementId, matchDecision);
         }
-        // Handle match decision
         if (!matchDecision.needsUserInput && matchDecision.bestMatch) {
-            // High confidence match - auto-assign
             const match = matchDecision.bestMatch;
             this.logger.log(`   ✅ Auto-matched to board: ${match.boardName} (${match.confidence}% confidence)`);
             if (match.matchedTerms.length > 0) {
                 this.logger.log(`      Matched terms: ${match.matchedTerms.slice(0, 5).join(', ')}`);
             }
-            // CRITICAL FIX (v0.30.13): For ADO with 2-level structure, construct {project}/{board}
             if (match.adoProject) {
                 return `${match.adoProject}/${match.boardId}`;
             }
             return match.boardId;
         }
-        // Need user input - show match results and ask
         return await this.askUserForBoardSelection(incrementId, matchDecision);
     }
     /**
@@ -1100,18 +1183,192 @@ export class LivingDocsSync {
         }
     }
     /**
-     * Sync to JIRA (placeholder for future implementation)
+     * Sync to JIRA Epics
+     *
+     * Uses JiraSpecSync.syncSpecToJira() which is idempotent:
+     * - Uses existing epic if it exists
+     * - Updates existing stories
+     * - Only creates new stories if they don't exist
+     *
+     * Configuration priority:
+     * 1. config.sync.jira (most common)
+     * 2. config.sync.profiles[*] with provider='jira'
+     * 3. Environment variables (JIRA_DOMAIN, JIRA_EMAIL, JIRA_API_TOKEN)
      */
     async syncToJira(featureId, projectPath) {
-        this.logger.log(`   ⚠️  JIRA sync not yet implemented - skipping`);
-        // TODO: Implement JIRA sync when specweave-jira plugin is available
+        try {
+            this.logger.log(`   🔄 Syncing to JIRA...`);
+            // Dynamic import to avoid circular dependencies
+            const { JiraSpecSync } = await import('../../../plugins/specweave-jira/lib/jira-spec-sync.js');
+            // Load JIRA config from config.json FIRST, then environment
+            const configPath = path.join(this.projectRoot, '.specweave/config.json');
+            let domain = process.env.JIRA_DOMAIN || '';
+            let email = process.env.JIRA_EMAIL || '';
+            let apiToken = process.env.JIRA_API_TOKEN || '';
+            let projectKey = '';
+            if (existsSync(configPath)) {
+                try {
+                    const config = await readJson(configPath);
+                    // Method 1: Read from config.sync.jira (most common)
+                    if (config.sync?.jira?.domain) {
+                        domain = config.sync.jira.domain;
+                        projectKey = config.sync.jira.projectKey || '';
+                        this.logger.log(`   📝 Using JIRA config: ${domain}`);
+                    }
+                    // Method 2: Check profiles
+                    else {
+                        const jiraProfiles = getProfilesByProvider(config.sync, 'jira');
+                        if (jiraProfiles.length > 0) {
+                            const [profileName, profile] = jiraProfiles[0];
+                            const cfg = profile.config;
+                            domain = cfg?.domain || domain;
+                            projectKey = cfg?.projectKey || projectKey;
+                            this.logger.log(`   📝 Using JIRA profile: ${profileName}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger.warn(`   ⚠️  Failed to read config.json for JIRA, using environment variables`);
+                }
+            }
+            // Load secrets from .env if not already set
+            if (!apiToken) {
+                const envPath = path.join(this.projectRoot, '.env');
+                if (existsSync(envPath)) {
+                    try {
+                        const envContent = await fs.readFile(envPath, 'utf-8');
+                        for (const line of envContent.split('\n')) {
+                            if (line.startsWith('JIRA_API_TOKEN=')) {
+                                apiToken = line.split('=')[1]?.trim().replace(/^["']|["']$/g, '') || '';
+                            }
+                            if (!email && line.startsWith('JIRA_EMAIL=')) {
+                                email = line.split('=')[1]?.trim().replace(/^["']|["']$/g, '') || '';
+                            }
+                        }
+                    }
+                    catch {
+                        // Ignore .env read errors
+                    }
+                }
+            }
+            if (!domain || !email || !apiToken) {
+                this.logger.warn(`   ⚠️  JIRA credentials not configured`);
+                this.logger.warn(`   💡 Set JIRA_DOMAIN, JIRA_EMAIL, JIRA_API_TOKEN in .env`);
+                return;
+            }
+            // Initialize JIRA sync
+            const jiraSync = new JiraSpecSync({ domain, email, apiToken, projectKey }, this.projectRoot);
+            // Sync feature to JIRA
+            const result = await jiraSync.syncSpecToJira(featureId);
+            if (result.success) {
+                this.logger.log(`   ✅ Synced to JIRA: ${result.externalId || 'updated'}`);
+            }
+            else {
+                this.logger.warn(`   ⚠️  JIRA sync had issues: ${result.error || 'unknown'}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Cannot find module')) {
+                this.logger.warn(`   ⚠️  JIRA plugin not installed - skipping JIRA sync`);
+            }
+            else {
+                throw error;
+            }
+        }
     }
     /**
-     * Sync to Azure DevOps (placeholder for future implementation)
+     * Sync to Azure DevOps Features
+     *
+     * Uses AdoSpecSync.syncSpecToAdo() which is idempotent:
+     * - Uses existing feature if it exists
+     * - Updates existing user stories
+     * - Only creates new user stories if they don't exist
+     *
+     * Configuration priority:
+     * 1. config.sync.ado (most common)
+     * 2. config.sync.profiles[*] with provider='ado'
+     * 3. Environment variables (AZURE_DEVOPS_ORG, AZURE_DEVOPS_PROJECT, AZURE_DEVOPS_PAT)
      */
     async syncToADO(featureId, projectPath) {
-        this.logger.log(`   ⚠️  ADO sync not yet implemented - skipping`);
-        // TODO: Implement ADO sync when specweave-ado plugin is available
+        try {
+            this.logger.log(`   🔄 Syncing to Azure DevOps...`);
+            // Dynamic import to avoid circular dependencies
+            const { AdoSpecSync } = await import('../../../plugins/specweave-ado/lib/ado-spec-sync.js');
+            // Load ADO config from config.json FIRST, then environment
+            const configPath = path.join(this.projectRoot, '.specweave/config.json');
+            let organization = process.env.AZURE_DEVOPS_ORG || '';
+            let project = process.env.AZURE_DEVOPS_PROJECT || '';
+            let personalAccessToken = '';
+            if (existsSync(configPath)) {
+                try {
+                    const config = await readJson(configPath);
+                    // Method 1: Read from config.sync.ado (most common)
+                    if (config.sync?.ado?.organization) {
+                        organization = config.sync.ado.organization;
+                        project = config.sync.ado.project || project;
+                        this.logger.log(`   📝 Using ADO config: ${organization}/${project}`);
+                    }
+                    // Method 2: Check profiles
+                    else {
+                        const adoProfiles = getProfilesByProvider(config.sync, 'ado');
+                        if (adoProfiles.length > 0) {
+                            const [profileName, profile] = adoProfiles[0];
+                            const cfg = profile.config;
+                            organization = cfg?.organization || organization;
+                            project = cfg?.project || project;
+                            this.logger.log(`   📝 Using ADO profile: ${profileName}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger.warn(`   ⚠️  Failed to read config.json for ADO, using environment variables`);
+                }
+            }
+            // Load PAT from .env if not already set
+            const envPath = path.join(this.projectRoot, '.env');
+            if (existsSync(envPath)) {
+                try {
+                    const envContent = await fs.readFile(envPath, 'utf-8');
+                    for (const line of envContent.split('\n')) {
+                        if (line.startsWith('AZURE_DEVOPS_PAT=')) {
+                            personalAccessToken = line.split('=')[1]?.trim().replace(/^["']|["']$/g, '') || '';
+                        }
+                        if (!organization && line.startsWith('AZURE_DEVOPS_ORG=')) {
+                            organization = line.split('=')[1]?.trim().replace(/^["']|["']$/g, '') || '';
+                        }
+                        if (!project && line.startsWith('AZURE_DEVOPS_PROJECT=')) {
+                            project = line.split('=')[1]?.trim().replace(/^["']|["']$/g, '') || '';
+                        }
+                    }
+                }
+                catch {
+                    // Ignore .env read errors
+                }
+            }
+            if (!organization || !project || !personalAccessToken) {
+                this.logger.warn(`   ⚠️  ADO credentials not configured`);
+                this.logger.warn(`   💡 Set AZURE_DEVOPS_ORG, AZURE_DEVOPS_PROJECT, AZURE_DEVOPS_PAT in .env`);
+                return;
+            }
+            // Initialize ADO sync
+            const adoSync = new AdoSpecSync({ organization, project, personalAccessToken }, this.projectRoot);
+            // Sync feature to ADO
+            const result = await adoSync.syncSpecToAdo(featureId);
+            if (result.success) {
+                this.logger.log(`   ✅ Synced to ADO: ${result.externalId || 'updated'}`);
+            }
+            else {
+                this.logger.warn(`   ⚠️  ADO sync had issues: ${result.error || 'unknown'}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Cannot find module')) {
+                this.logger.warn(`   ⚠️  ADO plugin not installed - skipping ADO sync`);
+            }
+            else {
+                throw error;
+            }
+        }
     }
     /**
      * Validate feature folder consistency