claude-autopm 2.7.0 → 2.8.2

package/lib/services/EpicService.js

@@ -1,10 +1,10 @@
 /**
  * EpicService - Epic Management Service
  *
- * Pure service layer for epic operations without any I/O operations.
- * Follows 3-layer architecture: Service (logic) -> No direct I/O
+ * Pure service layer for epic operations following ClaudeAutoPM patterns.
+ * Follows 3-layer architecture: Service (logic) -> Provider (I/O) -> CLI (presentation)
  *
- * Provides 12 pure business logic methods:
+ * Provides comprehensive epic lifecycle management:
  *
  * 1. Status & Categorization (5 methods):
  *    - categorizeStatus: Categorize epic status
@@ -26,11 +26,21 @@
  *    - generateEpicContent: Build complete epic markdown
  *    - buildTaskSection: Format tasks as markdown list
  *
+ * 5. GitHub Epic Sync Methods (6 methods):
+ *    - syncEpicToGitHub: Push epic to GitHub with conflict detection
+ *    - syncEpicFromGitHub: Pull GitHub epic to local
+ *    - syncEpicBidirectional: Full bidirectional sync
+ *    - createGitHubEpic: Create GitHub issue with "epic" label
+ *    - updateGitHubEpic: Update GitHub epic
+ *    - getEpicSyncStatus: Get sync status for epic
+ *
  * Documentation Queries:
  * - mcp://context7/agile/epic-management - Epic management best practices
  * - mcp://context7/agile/task-breakdown - Task breakdown patterns
  * - mcp://context7/project-management/dependencies - Dependency management
  * - mcp://context7/markdown/frontmatter - YAML frontmatter patterns
+ * - mcp://context7/github/issues-api - GitHub Issues API v3 best practices
+ * - mcp://context7/conflict-resolution/sync - Conflict resolution strategies
  */
 
 const PRDService = require('./PRDService');
@@ -878,6 +888,1085 @@ ${prdContent}`;
     const path = require('path');
     return path.join(this.getEpicPath(epicName), 'epic.md');
   }
+
+  // ==========================================
+  // 7. GITHUB EPIC SYNC METHODS (6 METHODS)
+  // ==========================================
+
+  /**
+   * Sync local epic to GitHub (enhanced push with conflict detection)
+   *
+   * @param {string} epicName - Local epic name
+   * @param {Object} [options={}] - Sync options
+   * @param {boolean} [options.detectConflicts=false] - Enable conflict detection
+   * @returns {Promise<Object>} Result: { success, epicName, githubNumber, action, conflict? }
+   * @throws {Error} If no provider configured or epic not found
+   */
+  async syncEpicToGitHub(epicName, options = {}) {
+    if (!this.provider) {
+      throw new Error('No provider configured for GitHub sync');
+    }
+
+    const fs = require('fs-extra');
+    const epicFilePath = this.getEpicFilePath(epicName);
+
+    // Check if epic exists
+    const exists = await fs.pathExists(epicFilePath);
+    if (!exists) {
+      throw new Error(`Epic not found: ${epicName}`);
+    }
+
+    // Read epic content
+    const content = await fs.readFile(epicFilePath, 'utf8');
+    const metadata = this.parseFrontmatter(content);
+
+    // Extract overview and tasks from content
+    const overviewMatch = content.match(/## Overview\s+([\s\S]*?)(?=\n## |$)/);
+    const overview = overviewMatch ? overviewMatch[1].trim() : '';
+
+    const tasksMatch = content.match(/## Tasks?\s+([\s\S]*?)(?=\n## |$)/);
+    const tasksContent = tasksMatch ? tasksMatch[1].trim() : '';
+
+    // Parse tasks from markdown checkboxes
+    const tasks = this._parseTasksFromContent(tasksContent);
+
+    const epicData = {
+      name: epicName,
+      title: metadata?.name || epicName,
+      overview,
+      tasks,
+      priority: metadata?.priority || 'P2',
+      status: metadata?.status || 'planning',
+      updated: metadata?.updated
+    };
+
+    const syncMap = await this._loadEpicSyncMap();
+    const githubNumber = syncMap['epic-to-github'][epicName];
+
+    let result;
+    let action;
+
+    if (githubNumber) {
+      // Check for conflicts if enabled
+      if (options.detectConflicts) {
+        const githubIssue = await this.provider.getIssue(githubNumber);
+        const conflict = this._detectEpicConflict(epicData, githubIssue);
+
+        if (conflict.hasConflict && conflict.remoteNewer) {
+          return {
+            success: false,
+            epicName,
+            githubNumber: String(githubNumber),
+            conflict
+          };
+        }
+      }
+
+      // Update existing GitHub epic
+      result = await this.updateGitHubEpic(githubNumber, epicData);
+      action = 'updated';
+    } else {
+      // Create new GitHub epic
+      result = await this.createGitHubEpic(epicData);
+      action = 'created';
+    }
+
+    // Update sync-map
+    await this._updateEpicSyncMap(epicName, String(result.number));
+
+    return {
+      success: true,
+      epicName,
+      githubNumber: String(result.number),
+      action
+    };
+  }
+
+  /**
+   * Sync GitHub epic to local (enhanced pull with merge)
+   *
+   * @param {number|string} githubNumber - GitHub issue number
+   * @param {Object} [options={}] - Sync options
+   * @param {boolean} [options.detectConflicts=false] - Enable conflict detection
+   * @returns {Promise<Object>} Result: { success, epicName, githubNumber, action, conflict? }
+   * @throws {Error} If issue is not an epic
+   */
+  async syncEpicFromGitHub(githubNumber, options = {}) {
+    const fs = require('fs-extra');
+    const path = require('path');
+
+    const githubIssue = await this.provider.getIssue(githubNumber);
+
+    // Verify it's an epic
+    const labels = githubIssue.labels || [];
+    const isEpic = labels.some(label => {
+      const name = typeof label === 'string' ? label : label.name;
+      return name === 'epic';
+    });
+
+    if (!isEpic) {
+      throw new Error(`GitHub issue #${githubNumber} is not an epic`);
+    }
+
+    const syncMap = await this._loadEpicSyncMap();
+    let epicName = syncMap['github-to-epic'][String(githubNumber)];
+
+    let action;
+
+    if (epicName) {
+      // Check for conflicts if enabled
+      if (options.detectConflicts) {
+        const epicFilePath = this.getEpicFilePath(epicName);
+        const localContent = await fs.readFile(epicFilePath, 'utf8');
+        const localMetadata = this.parseFrontmatter(localContent);
+
+        const conflict = this._detectEpicConflict(
+          { updated: localMetadata?.updated },
+          githubIssue
+        );
+
+        if (conflict.hasConflict && conflict.localNewer) {
+          return {
+            success: false,
+            epicName,
+            githubNumber: String(githubNumber),
+            conflict
+          };
+        }
+      }
+
+      action = 'updated';
+    } else {
+      // Generate epic name from title
+      epicName = this._generateEpicNameFromTitle(githubIssue.title);
+      action = 'created';
+    }
+
+    // Parse GitHub epic
+    const epicData = this._parseGitHubEpic(githubIssue);
+
+    // Build epic content
+    const epicContent = this._buildEpicContent(epicData, githubNumber);
+
+    // Ensure epic directory exists
+    const epicPath = this.getEpicPath(epicName);
+    await fs.ensureDir(epicPath);
+
+    // Write epic.md
+    const epicFilePath = this.getEpicFilePath(epicName);
+    await fs.writeFile(epicFilePath, epicContent);
+
+    // Update sync-map
+    await this._updateEpicSyncMap(epicName, String(githubNumber));
+
+    return {
+      success: true,
+      epicName,
+      githubNumber: String(githubNumber),
+      action
+    };
+  }
+
+  /**
+   * Bidirectional sync - sync in the direction of newer changes
+   *
+   * @param {string} epicName - Local epic name
+   * @param {Object} [options={}] - Sync options
+   * @param {string} [options.conflictStrategy='detect'] - How to handle conflicts
+   * @returns {Promise<Object>} Result: { success, direction, conflict? }
+   */
+  async syncEpicBidirectional(epicName, options = {}) {
+    const syncMap = await this._loadEpicSyncMap();
+    const githubNumber = syncMap['epic-to-github'][epicName];
+
+    if (!githubNumber) {
+      // No GitHub mapping, push to GitHub
+      const result = await this.syncEpicToGitHub(epicName);
+      return { ...result, direction: 'to-github' };
+    }
+
+    // Get both versions
+    const fs = require('fs-extra');
+    const epicFilePath = this.getEpicFilePath(epicName);
+    const localContent = await fs.readFile(epicFilePath, 'utf8');
+    const localMetadata = this.parseFrontmatter(localContent);
+
+    const githubIssue = await this.provider.getIssue(githubNumber);
+
+    const conflict = this._detectEpicConflict(
+      { updated: localMetadata?.updated },
+      githubIssue
+    );
+
+    if (conflict.hasConflict) {
+      if (options.conflictStrategy === 'detect') {
+        return {
+          success: false,
+          direction: 'conflict',
+          conflict
+        };
+      }
+
+      // Auto-resolve based on timestamps
+      if (conflict.localNewer) {
+        const result = await this.syncEpicToGitHub(epicName);
+        return { ...result, direction: 'to-github' };
+      } else if (conflict.remoteNewer) {
+        const result = await this.syncEpicFromGitHub(githubNumber);
+        return { ...result, direction: 'from-github' };
+      }
+    }
+
+    // No conflict - sync local to GitHub
+    const result = await this.syncEpicToGitHub(epicName);
+    return { ...result, direction: 'to-github' };
+  }
+
+  /**
+   * Create new GitHub epic from local data
+   *
+   * @param {Object} epicData - Epic data
+   * @returns {Promise<Object>} Created GitHub issue
+   */
+  async createGitHubEpic(epicData) {
+    const labels = ['epic'];
+
+    if (epicData.priority) {
+      labels.push(`priority:${epicData.priority}`);
+    }
+
+    const body = this._formatEpicForGitHub(epicData);
+
+    const githubData = {
+      title: `Epic: ${epicData.title}`,
+      body,
+      labels,
+      state: 'open'
+    };
+
+    const result = await this.provider.createIssue(githubData);
+
+    // Update sync-map
+    if (epicData.name) {
+      await this._updateEpicSyncMap(epicData.name, String(result.number));
+    }
+
+    return result;
+  }
+
+  /**
+   * Update existing GitHub epic with local data
+   *
+   * @param {number|string} githubNumber - GitHub issue number
+   * @param {Object} epicData - Epic data
+   * @returns {Promise<Object>} Updated GitHub issue
+   */
+  async updateGitHubEpic(githubNumber, epicData) {
+    const updateData = {};
+
+    if (epicData.title) {
+      updateData.title = `Epic: ${epicData.title}`;
+    }
+
+    if (epicData.overview || epicData.tasks) {
+      updateData.body = this._formatEpicForGitHub(epicData);
+    }
+
+    if (epicData.priority) {
+      updateData.labels = ['epic', `priority:${epicData.priority}`];
+    }
+
+    return await this.provider.updateIssue(githubNumber, updateData);
+  }
+
+  /**
+   * Get sync status for an epic
+   *
+   * @param {string} epicName - Local epic name
+   * @returns {Promise<Object>} Status: { synced, epicName, githubNumber, lastSync, status }
+   */
+  async getEpicSyncStatus(epicName) {
+    const syncMap = await this._loadEpicSyncMap();
+    const githubNumber = syncMap['epic-to-github'][epicName];
+
+    if (!githubNumber) {
+      return {
+        synced: false,
+        epicName,
+        githubNumber: null,
+        status: 'not-synced'
+      };
+    }
+
+    const metadata = syncMap.metadata[epicName] || {};
+
+    // Check if out of sync
+    try {
+      const fs = require('fs-extra');
+      const epicFilePath = this.getEpicFilePath(epicName);
+      const localContent = await fs.readFile(epicFilePath, 'utf8');
+      const localMetadata = this.parseFrontmatter(localContent);
+
+      const githubIssue = await this.provider.getIssue(githubNumber);
+
+      const localTime = new Date(localMetadata?.updated || localMetadata?.created || 0);
+      const githubTime = new Date(githubIssue.updated_at || githubIssue.created_at || 0);
+      const lastSyncTime = new Date(metadata.lastSync || 0);
+
+      const isOutOfSync = localTime > lastSyncTime || githubTime > lastSyncTime;
+
+      return {
+        synced: !isOutOfSync,
+        epicName,
+        githubNumber: String(githubNumber),
+        lastSync: metadata.lastSync,
+        status: isOutOfSync ? 'out-of-sync' : 'synced'
+      };
+    } catch (error) {
+      // If error checking, assume synced
+      return {
+        synced: true,
+        epicName,
+        githubNumber: String(githubNumber),
+        lastSync: metadata.lastSync,
+        status: 'synced'
+      };
+    }
+  }
+
+  // ==========================================
+  // PRIVATE HELPER METHODS FOR EPIC SYNC
+  // ==========================================
+
+  /**
+   * Load epic-sync-map from file
+   * @private
+   */
+  async _loadEpicSyncMap() {
+    const fs = require('fs-extra');
+    const path = require('path');
+    const syncMapPath = path.join(process.cwd(), '.claude/epic-sync-map.json');
+
+    if (await fs.pathExists(syncMapPath)) {
+      return await fs.readJSON(syncMapPath);
+    }
+
+    return {
+      'epic-to-github': {},
+      'github-to-epic': {},
+      'metadata': {}
+    };
+  }
+
+  /**
+   * Save epic-sync-map to file
+   * @private
+   */
+  async _saveEpicSyncMap(syncMap) {
+    const fs = require('fs-extra');
+    const path = require('path');
+    const syncMapPath = path.join(process.cwd(), '.claude/epic-sync-map.json');
+    await fs.writeJSON(syncMapPath, syncMap, { spaces: 2 });
+  }
+
+  /**
+   * Update epic-sync-map with new mapping
+   * @private
+   */
+  async _updateEpicSyncMap(epicName, githubNumber) {
+    const syncMap = await this._loadEpicSyncMap();
+
+    syncMap['epic-to-github'][epicName] = String(githubNumber);
+    syncMap['github-to-epic'][String(githubNumber)] = epicName;
+    syncMap['metadata'][epicName] = {
+      lastSync: new Date().toISOString(),
+      githubNumber: String(githubNumber)
+    };
+
+    await this._saveEpicSyncMap(syncMap);
+  }
+
+  /**
+   * Format epic data as GitHub issue body
+   * @private
+   */
+  _formatEpicForGitHub(epicData) {
+    let body = '';
+
+    if (epicData.overview) {
+      body += `## Overview\n${epicData.overview}\n\n`;
+    }
+
+    body += '## Task Breakdown\n';
+
+    if (epicData.tasks && epicData.tasks.length > 0) {
+      epicData.tasks.forEach(task => {
+        const checkbox = task.status === 'closed' ? '[x]' : '[ ]';
+        body += `- ${checkbox} ${task.title}\n`;
+      });
+    } else {
+      body += 'No tasks defined yet.\n';
+    }
+
+    return body;
+  }
+
+  /**
+   * Parse GitHub issue to epic format
+   * @private
+   */
+  _parseGitHubEpic(githubIssue) {
+    // Extract epic name from title
+    const titleMatch = githubIssue.title.match(/Epic:\s*(.+)/i);
+    const title = titleMatch ? titleMatch[1].trim() : githubIssue.title;
+    const name = this._generateEpicNameFromTitle(title);
+
+    // Extract overview
+    const overviewMatch = githubIssue.body?.match(/## Overview\s+([\s\S]*?)(?=\n## |$)/);
+    const overview = overviewMatch ? overviewMatch[1].trim() : '';
+
+    // Extract priority from labels
+    const labels = githubIssue.labels || [];
+    let priority = 'P2';
+    labels.forEach(label => {
+      const labelName = typeof label === 'string' ? label : label.name;
+      const priorityMatch = labelName.match(/priority:(P\d)/i);
+      if (priorityMatch) {
+        priority = priorityMatch[1];
+      }
+    });
+
+    // Extract tasks from checkboxes
+    const tasksMatch = githubIssue.body?.match(/## Task Breakdown\s+([\s\S]*?)(?=\n## |$)/);
+    const tasksContent = tasksMatch ? tasksMatch[1].trim() : '';
+    const tasks = this._parseTasksFromContent(tasksContent);
+
+    return {
+      name,
+      title,
+      overview,
+      priority,
+      tasks,
+      created: githubIssue.created_at,
+      updated: githubIssue.updated_at
+    };
+  }
+
+  /**
+   * Parse tasks from markdown checkbox content
+   * @private
+   */
+  _parseTasksFromContent(content) {
+    const tasks = [];
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const checkboxMatch = line.match(/^-\s+\[([ x])\]\s+(.+)$/i);
+      if (checkboxMatch) {
+        const status = checkboxMatch[1].toLowerCase() === 'x' ? 'closed' : 'open';
+        const title = checkboxMatch[2].trim();
+        tasks.push({ title, status });
+      }
+    }
+
+    return tasks;
+  }
+
+  /**
+   * Generate epic name from title
+   * @private
+   */
+  _generateEpicNameFromTitle(title) {
+    return title
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+  }
+
+  /**
+   * Build epic content from parsed data
+   * @private
+   */
+  _buildEpicContent(epicData, githubNumber) {
+    const frontmatter = `---
+name: ${epicData.name}
+status: planning
+priority: ${epicData.priority}
+created: ${epicData.created}
+updated: ${epicData.updated}
+progress: 0%
+github: https://github.com/owner/repo/issues/${githubNumber}
+---
+
+# Epic: ${epicData.title}
+
+## Overview
+${epicData.overview || 'No overview provided.'}
+
+## Tasks
+${epicData.tasks.map(task => {
+  const checkbox = task.status === 'closed' ? '[x]' : '[ ]';
+  return `- ${checkbox} ${task.title}`;
+}).join('\n')}
+`;
+
+    return frontmatter;
+  }
+
+  /**
+   * Detect conflict between local epic and GitHub issue
+   * @private
+   */
+  _detectEpicConflict(localEpic, githubIssue) {
+    const localTime = new Date(localEpic.updated || localEpic.created || 0);
+    const githubTime = new Date(githubIssue.updated_at || githubIssue.created_at || 0);
+
+    const hasConflict = localTime.getTime() !== githubTime.getTime();
+    const localNewer = localTime > githubTime;
+    const remoteNewer = githubTime > localTime;
+
+    return {
+      hasConflict,
+      localNewer,
+      remoteNewer,
+      conflictFields: []
+    };
+  }
+
+  // ==========================================
+  // 8. AZURE DEVOPS EPIC SYNC METHODS (6 METHODS)
+  // ==========================================
+
+  /**
+   * Sync local epic to Azure DevOps (enhanced push with conflict detection)
+   *
+   * @param {string} epicName - Local epic name
+   * @param {Object} [options={}] - Sync options
+   * @param {boolean} [options.detectConflicts=false] - Enable conflict detection
+   * @returns {Promise<Object>} Result: { success, epicName, workItemId, action, conflict? }
+   * @throws {Error} If no provider configured or epic not found
+   */
+  async syncEpicToAzure(epicName, options = {}) {
+    if (!this.provider) {
+      throw new Error('No provider configured for Azure sync');
+    }
+
+    const fs = require('fs-extra');
+    const epicFilePath = this.getEpicFilePath(epicName);
+
+    // Check if epic exists
+    const exists = await fs.pathExists(epicFilePath);
+    if (!exists) {
+      throw new Error(`Epic not found: ${epicName}`);
+    }
+
+    // Read epic content
+    const content = await fs.readFile(epicFilePath, 'utf8');
+    const metadata = this.parseFrontmatter(content);
+
+    // Extract overview and tasks from content
+    const overviewMatch = content.match(/## Overview\s+([\s\S]*?)(?=\n## |$)/);
+    const overview = overviewMatch ? overviewMatch[1].trim() : '';
+
+    const tasksMatch = content.match(/## Tasks?\s+([\s\S]*?)(?=\n## |$)/);
+    const tasksContent = tasksMatch ? tasksMatch[1].trim() : '';
+
+    // Parse tasks from markdown checkboxes
+    const tasks = this._parseTasksFromContent(tasksContent);
+
+    const epicData = {
+      name: epicName,
+      title: metadata?.name || epicName,
+      overview,
+      tasks,
+      priority: metadata?.priority || 'P2',
+      status: metadata?.status || 'planning',
+      updated: metadata?.updated
+    };
+
+    const syncMap = await this._loadAzureEpicSyncMap();
+    const workItemId = syncMap['epic-to-azure'][epicName];
+
+    let result;
+    let action;
+
+    if (workItemId) {
+      // Check for conflicts if enabled
+      if (options.detectConflicts) {
+        const azureWorkItem = await this.provider.getWorkItem(workItemId);
+        const conflict = this._detectAzureEpicConflict(epicData, azureWorkItem);
+
+        if (conflict.hasConflict && conflict.remoteNewer) {
+          return {
+            success: false,
+            epicName,
+            workItemId: String(workItemId),
+            conflict
+          };
+        }
+      }
+
+      // Update existing Azure epic
+      result = await this.updateAzureEpic(workItemId, epicData);
+      action = 'updated';
+    } else {
+      // Create new Azure epic
+      result = await this.createAzureEpic(epicData);
+      action = 'created';
+    }
+
+    // Update sync-map
+    await this._updateAzureEpicSyncMap(epicName, String(result.id));
+
+    return {
+      success: true,
+      epicName,
+      workItemId: String(result.id),
+      action
+    };
+  }
+
+  /**
+   * Sync Azure DevOps epic to local (enhanced pull with merge)
+   *
+   * @param {number|string} workItemId - Azure work item ID
+   * @param {Object} [options={}] - Sync options
+   * @param {boolean} [options.detectConflicts=false] - Enable conflict detection
+   * @returns {Promise<Object>} Result: { success, epicName, workItemId, action, conflict? }
+   * @throws {Error} If work item is not an Epic
+   */
+  async syncEpicFromAzure(workItemId, options = {}) {
+    const fs = require('fs-extra');
+    const path = require('path');
+
+    const azureWorkItem = await this.provider.getWorkItem(workItemId);
+
+    // Verify it's an Epic
+    const workItemType = azureWorkItem.fields['System.WorkItemType'];
+    if (workItemType !== 'Epic') {
+      throw new Error(`Azure work item #${workItemId} is not an Epic (type: ${workItemType})`);
+    }
+
+    const syncMap = await this._loadAzureEpicSyncMap();
+    let epicName = syncMap['azure-to-epic'][String(workItemId)];
+
+    let action;
+
+    if (epicName) {
+      // Check for conflicts if enabled
+      if (options.detectConflicts) {
+        const epicFilePath = this.getEpicFilePath(epicName);
+        const localContent = await fs.readFile(epicFilePath, 'utf8');
+        const localMetadata = this.parseFrontmatter(localContent);
+
+        const conflict = this._detectAzureEpicConflict(
+          { updated: localMetadata?.updated },
+          azureWorkItem
+        );
+
+        if (conflict.hasConflict && conflict.localNewer) {
+          return {
+            success: false,
+            epicName,
+            workItemId: String(workItemId),
+            conflict
+          };
+        }
+      }
+
+      action = 'updated';
+    } else {
+      // Generate epic name from title
+      const title = azureWorkItem.fields['System.Title'] || 'Untitled';
+      epicName = this._generateEpicNameFromTitle(title);
+      action = 'created';
+    }
+
+    // Parse Azure epic
+    const epicData = this._parseAzureEpic(azureWorkItem);
+
+    // Build epic content
+    const epicContent = this._buildAzureEpicContent(epicData, workItemId);
+
+    // Ensure epic directory exists
+    const epicPath = this.getEpicPath(epicName);
+    await fs.ensureDir(epicPath);
+
+    // Write epic.md
+    const epicFilePath = this.getEpicFilePath(epicName);
+    await fs.writeFile(epicFilePath, epicContent);
+
+    // Update sync-map
+    await this._updateAzureEpicSyncMap(epicName, String(workItemId));
+
+    return {
+      success: true,
+      epicName,
+      workItemId: String(workItemId),
+      action
+    };
+  }
+
+  /**
+   * Bidirectional sync - sync in the direction of newer changes (Azure)
+   *
+   * @param {string} epicName - Local epic name
+   * @param {Object} [options={}] - Sync options
+   * @param {string} [options.conflictStrategy='detect'] - How to handle conflicts
+   * @returns {Promise<Object>} Result: { success, direction, conflict? }
+   */
+  async syncEpicBidirectionalAzure(epicName, options = {}) {
+    const syncMap = await this._loadAzureEpicSyncMap();
+    const workItemId = syncMap['epic-to-azure'][epicName];
+
+    if (!workItemId) {
+      // No Azure mapping, push to Azure
+      const result = await this.syncEpicToAzure(epicName);
+      return { ...result, direction: 'to-azure' };
+    }
+
+    // Get both versions
+    const fs = require('fs-extra');
+    const epicFilePath = this.getEpicFilePath(epicName);
+    const localContent = await fs.readFile(epicFilePath, 'utf8');
+    const localMetadata = this.parseFrontmatter(localContent);
+
+    const azureWorkItem = await this.provider.getWorkItem(workItemId);
+
+    const conflict = this._detectAzureEpicConflict(
+      { updated: localMetadata?.updated },
+      azureWorkItem
+    );
+
+    if (conflict.hasConflict) {
+      if (options.conflictStrategy === 'detect') {
+        return {
+          success: false,
+          direction: 'conflict',
+          conflict
+        };
+      }
+
+      // Auto-resolve based on timestamps
+      if (conflict.localNewer) {
+        const result = await this.syncEpicToAzure(epicName);
+        return { ...result, direction: 'to-azure' };
+      } else if (conflict.remoteNewer) {
+        const result = await this.syncEpicFromAzure(workItemId);
+        return { ...result, direction: 'from-azure' };
+      }
+    }
+
+    // No conflict - sync local to Azure
+    const result = await this.syncEpicToAzure(epicName);
+    return { ...result, direction: 'to-azure' };
+  }
+
+  /**
+   * Create new Azure epic work item from local data
+   *
+   * @param {Object} epicData - Epic data
+   * @returns {Promise<Object>} Created Azure work item
+   */
+  async createAzureEpic(epicData) {
+    const tags = epicData.priority ? `priority:${epicData.priority}` : '';
+    const description = this._formatEpicForAzure(epicData);
+
+    const azureData = {
+      title: epicData.title,
+      description,
+      tags,
+      state: 'New'
+    };
+
+    const result = await this.provider.createWorkItem('Epic', azureData);
+
+    // Update sync-map if epic name exists
+    if (epicData.name) {
+      await this._updateAzureEpicSyncMap(epicData.name, String(result.id));
+    }
+
+    return result;
+  }
+
+  /**
+   * Update existing Azure epic with local data
+   *
+   * @param {number|string} workItemId - Azure work item ID
+   * @param {Object} epicData - Epic data
+   * @returns {Promise<Object>} Updated Azure work item
+   */
+  async updateAzureEpic(workItemId, epicData) {
+    const updateData = {};
+
+    if (epicData.title) {
+      updateData.title = epicData.title;
+    }
+
+    if (epicData.status) {
+      updateData.state = this._mapEpicStatusToAzure(epicData.status);
+    }
+
+    if (epicData.overview || epicData.tasks) {
+      updateData.description = this._formatEpicForAzure(epicData);
+    }
+
+    if (epicData.priority) {
+      updateData.tags = `priority:${epicData.priority}`;
+    }
+
+    return await this.provider.updateWorkItem(workItemId, updateData);
+  }
+
+  /**
+   * Get sync status for an epic (Azure)
+   *
+   * @param {string} epicName - Local epic name
+   * @returns {Promise<Object>} Status: { synced, epicName, workItemId, lastSync, status }
+   */
+  async getEpicAzureSyncStatus(epicName) {
+    const syncMap = await this._loadAzureEpicSyncMap();
+    const workItemId = syncMap['epic-to-azure'][epicName];
+
+    if (!workItemId) {
+      return {
+        synced: false,
+        epicName,
+        workItemId: null,
+        status: 'not-synced'
+      };
+    }
+
+    const metadata = syncMap.metadata[epicName] || {};
+
+    // Check if out of sync
+    try {
+      const fs = require('fs-extra');
+      const epicFilePath = this.getEpicFilePath(epicName);
+      const localContent = await fs.readFile(epicFilePath, 'utf8');
+      const localMetadata = this.parseFrontmatter(localContent);
+
+      const azureWorkItem = await this.provider.getWorkItem(workItemId);
+
+      const localTime = new Date(localMetadata?.updated || localMetadata?.created || 0);
+      const azureTime = new Date(
+        azureWorkItem.fields['System.ChangedDate'] ||
+        azureWorkItem.fields['System.CreatedDate'] ||
+        0
+      );
+      const lastSyncTime = new Date(metadata.lastSync || 0);
+
+      const isOutOfSync = localTime > lastSyncTime || azureTime > lastSyncTime;
+
+      return {
+        synced: !isOutOfSync,
+        epicName,
+        workItemId: String(workItemId),
+        lastSync: metadata.lastSync,
+        status: isOutOfSync ? 'out-of-sync' : 'synced'
+      };
+    } catch (error) {
+      // If error checking, assume synced
+      return {
+        synced: true,
+        epicName,
+        workItemId: String(workItemId),
+        lastSync: metadata.lastSync,
+        status: 'synced'
+      };
+    }
+  }
+
+  // ==========================================
+  // PRIVATE HELPER METHODS FOR AZURE EPIC SYNC
+  // ==========================================
+
+  /**
+   * Load epic-azure-sync-map from file
+   * @private
+   */
+  async _loadAzureEpicSyncMap() {
+    const fs = require('fs-extra');
+    const path = require('path');
+    const syncMapPath = path.join(process.cwd(), '.claude/epic-azure-sync-map.json');
+
+    if (await fs.pathExists(syncMapPath)) {
+      return await fs.readJSON(syncMapPath);
+    }
+
+    return {
+      'epic-to-azure': {},
+      'azure-to-epic': {},
+      'metadata': {}
+    };
+  }
+
+  /**
+   * Save epic-azure-sync-map to file
+   * @private
+   */
+  async _saveAzureEpicSyncMap(syncMap) {
+    const fs = require('fs-extra');
+    const path = require('path');
+    const syncMapPath = path.join(process.cwd(), '.claude/epic-azure-sync-map.json');
+    await fs.writeJSON(syncMapPath, syncMap, { spaces: 2 });
+  }
+
+  /**
+   * Update epic-azure-sync-map with new mapping
+   * @private
+   */
+  async _updateAzureEpicSyncMap(epicName, workItemId) {
+    const syncMap = await this._loadAzureEpicSyncMap();
+
+    syncMap['epic-to-azure'][epicName] = String(workItemId);
+    syncMap['azure-to-epic'][String(workItemId)] = epicName;
+    syncMap['metadata'][epicName] = {
+      lastSync: new Date().toISOString(),
+      workItemId: String(workItemId),
+      workItemType: 'Epic'
+    };
+
+    await this._saveAzureEpicSyncMap(syncMap);
+  }
+
+  /**
+   * Format epic data as Azure work item description
+   * @private
+   */
+  _formatEpicForAzure(epicData) {
+    let description = '';
+
+    if (epicData.overview) {
+      description += `${epicData.overview}\n\n`;
+    }
+
+    description += '## Tasks\n';
+
+    if (epicData.tasks && epicData.tasks.length > 0) {
+      epicData.tasks.forEach(task => {
+        const checkbox = task.status === 'closed' ? '[x]' : '[ ]';
+        description += `- ${checkbox} ${task.title}\n`;
+      });
+    } else {
+      description += 'No tasks defined yet.\n';
+    }
+
+    return description.trim();
+  }
+
+  /**
+   * Parse Azure work item to epic format
+   * @private
+   */
+  _parseAzureEpic(azureWorkItem) {
+    const title = azureWorkItem.fields['System.Title'] || '';
+    const name = this._generateEpicNameFromTitle(title);
+    const description = azureWorkItem.fields['System.Description'] || '';
+
+    // Extract overview (text before ## Tasks)
+    const overviewMatch = description.match(/^([\s\S]*?)(?=## Tasks|$)/);
+    const overview = overviewMatch ? overviewMatch[1].trim() : '';
+
+    // Extract priority from tags
+    const tags = azureWorkItem.fields['System.Tags'] || '';
+    const priorityMatch = tags.match(/priority:(P\d)/i);
+    const priority = priorityMatch ? priorityMatch[1] : 'P2';
+
+    // Extract tasks from checkboxes
+    const tasksMatch = description.match(/## Tasks\s+([\s\S]*?)$/);
+    const tasksContent = tasksMatch ? tasksMatch[1].trim() : '';
+    const tasks = this._parseTasksFromContent(tasksContent);
+
+    return {
+      name,
+      title,
+      overview,
+      priority,
+      tasks,
+      created: azureWorkItem.fields['System.CreatedDate'],
+      updated: azureWorkItem.fields['System.ChangedDate']
+    };
+  }
+
+  /**
+   * Detect conflict between local epic and Azure work item
+   * @private
+   */
+  _detectAzureEpicConflict(localEpic, azureWorkItem) {
+    const localTime = new Date(localEpic.updated || localEpic.created || 0);
+    const azureTime = new Date(
+      azureWorkItem.fields['System.ChangedDate'] ||
+      azureWorkItem.fields['System.CreatedDate'] ||
+      0
+    );
+
+    const hasConflict = localTime.getTime() !== azureTime.getTime();
+    const localNewer = localTime > azureTime;
+    const remoteNewer = azureTime > localTime;
+
+    return {
+      hasConflict,
+      localNewer,
+      remoteNewer,
+      conflictFields: []
+    };
+  }
+
+  /**
+   * Map epic status to Azure DevOps state
+   * @private
+   */
+  _mapEpicStatusToAzure(status) {
+    if (!status) return 'New';
+
+    const lowerStatus = status.toLowerCase();
+    const statusMap = {
+      'backlog': 'New',
+      'planning': 'New',
+      'in-progress': 'Active',
+      'in_progress': 'Active',
+      'active': 'Active',
+      'done': 'Resolved',
+      'completed': 'Resolved',
+      'closed': 'Closed'
+    };
+
+    return statusMap[lowerStatus] || 'New';
+  }
+
+  /**
+   * Build Azure epic content from parsed data
+   * @private
+   */
+  _buildAzureEpicContent(epicData, workItemId) {
+    const frontmatter = `---
+name: ${epicData.name}
+status: planning
+priority: ${epicData.priority}
+created: ${epicData.created}
+updated: ${epicData.updated}
+progress: 0%
+azure_work_item_id: ${workItemId}
+work_item_type: Epic
+---
+
+# Epic: ${epicData.title}
+
+## Overview
+${epicData.overview || 'No overview provided.'}
+
+## Tasks
+${epicData.tasks.map(task => {
+  const checkbox = task.status === 'closed' ? '[x]' : '[ ]';
+  return `- ${checkbox} ${task.title}`;
+}).join('\n')}
+`;
+
+    return frontmatter;
+  }
 }
 
 module.exports = EpicService;