specweave 1.0.255 → 1.0.256

package/plugins/specweave-github/lib/ThreeLayerSyncManager.ts

@@ -1,909 +0,0 @@
-/**
- * Three-Layer Full Sync Manager (All Permissions Enabled)
- *
- * Handles synchronization across three layers:
- * - Layer 1: GitHub Issue (stakeholder UI)
- * - Layer 2: Living Docs User Story files (intermediate representation)
- * - Layer 3: Increment spec.md + tasks.md (source of truth)
- *
- * Supports two sync flows:
- * 1. GitHub → Living Docs → Increment (stakeholder checks checkbox)
- * 2. Increment → Living Docs → GitHub (developer completes work)
- *
- * Features:
- * - Code validation (reopen tasks if code doesn't exist)
- * - Completion propagation (Tasks → ACs → User Stories)
- * - Conflict resolution (Increment always wins)
- *
- * @module ThreeLayerSyncManager
- */
-
-import * as fs from '../../../src/utils/fs-native.js';
-import path from 'path';
-import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
-import { CodeValidator, type TaskValidationResult } from './CodeValidator.js';
-import { getGitHubAuthFromProject } from '../../../src/utils/auth-helpers.js';
-
-/**
- * Acceptance Criterion with completion state
- */
-export interface AcceptanceCriterion {
-  id: string; // e.g., "AC-US1-01"
-  userStoryId: string; // e.g., "US1"
-  description: string;
-  completed: boolean;
-  projects: string[]; // ["backend", "frontend", "mobile"]
-  rawLine: string; // Original markdown line
-}
-
-/**
- * Task with completion state and AC references
- */
-export interface Task {
-  id: string; // e.g., "T-001"
-  title: string;
-  completed: boolean;
-  completedDate?: string;
-  acIds: string[]; // e.g., ["AC-US1-01", "AC-US1-02"]
-  filePaths?: string[]; // For code validation
-}
-
-/**
- * Change detected during sync
- */
-export interface SyncChange {
-  type: 'ac' | 'task';
-  id: string;
-  completed: boolean;
-  layer: 'github' | 'living-docs' | 'increment';
-  userStoryPath?: string;
-  incrementPath?: string;
-}
-
-/**
- * Sync result
- */
-export interface SyncResult {
-  acsUpdated: number;
-  tasksUpdated: number;
-  tasksReopened: number;
-  conflicts: string[];
-  errors: string[];
-}
-
-export class ThreeLayerSyncManager {
-  private codeValidator: CodeValidator;
-  private userStoryFileCache: Map<string, string | null> = new Map();
-  private projectRoot: string;
-  private token?: string;
-
-  constructor(projectRoot: string = process.cwd()) {
-    this.projectRoot = projectRoot;
-    this.codeValidator = new CodeValidator({ projectRoot });
-    this.token = getGitHubAuthFromProject(projectRoot).token;
-  }
-
-  /**
-   * Get environment object with GH_TOKEN for gh CLI commands.
-   */
-  private getGhEnv(): NodeJS.ProcessEnv {
-    return this.token
-      ? { ...process.env, GH_TOKEN: this.token }
-      : process.env;
-  }
-
-  /**
-   * Clear User Story file cache
-   * Call this when file structure changes or for testing
-   */
-  clearCache(): void {
-    this.userStoryFileCache.clear();
-  }
-
-  /**
-   * Sync from GitHub to Increment (Flow 1: GitHub → Living Docs → Increment)
-   *
-   * Triggered when stakeholder checks AC/Task checkbox in GitHub issue.
-   */
-  async syncGitHubToIncrement(
-    issueNumber: number,
-    incrementPath: string,
-    livingDocsPath: string
-  ): Promise<SyncResult> {
-    const result: SyncResult = {
-      acsUpdated: 0,
-      tasksUpdated: 0,
-      tasksReopened: 0,
-      conflicts: [],
-      errors: []
-    };
-
-    try {
-      console.log(`🔄 Syncing GitHub issue #${issueNumber} → Increment`);
-
-      // 1. Fetch GitHub issue state
-      const githubState = await this.fetchGitHubIssueState(issueNumber);
-
-      // 2. Extract AC and Task completion state from issue body
-      const githubAcs = this.extractAcsFromIssue(githubState.body);
-      const githubTasks = this.extractTasksFromIssue(githubState.body);
-
-      // 3. Update Living Docs User Stories (Layer 2) - PARALLEL I/O for performance
-      const acUpdatePromises = githubAcs.map(async (ac) => {
-        const userStoryPath = await this.findUserStoryFile(livingDocsPath, ac.userStoryId);
-        if (userStoryPath) {
-          await this.updateUserStoryAc(userStoryPath, ac.id, ac.completed);
-          result.acsUpdated++;
-        }
-      });
-
-      const taskUpdatePromises = githubTasks.map(async (task) => {
-        // Find User Story that contains this task
-        const userStoryPath = await this.findUserStoryFileForTask(livingDocsPath, task.id);
-        if (userStoryPath) {
-          await this.updateUserStoryTask(userStoryPath, task.id, task.completed);
-          result.tasksUpdated++;
-        }
-      });
-
-      // Wait for all updates to complete in parallel
-      await Promise.all([...acUpdatePromises, ...taskUpdatePromises]);
-
-      // 4. Update Increment (Layer 3 - source of truth) with conflict resolution
-      await this.updateIncrementAcsWithConflictResolution(incrementPath, githubAcs, result);
-      await this.updateIncrementTasksWithConflictResolution(incrementPath, githubTasks, result);
-
-      // 5. Code validation: If task marked complete, check if code exists - PARALLEL for performance
-      const completedTasks = githubTasks.filter(t => t.completed);
-      const validationPromises = completedTasks.map(async (task) => {
-        const codeExists = await this.validateCodeExists(task);
-        if (!codeExists) {
-          console.log(`⚠️  Task ${task.id} marked complete but code missing - reopening`);
-          await this.reopenTask(task.id, incrementPath, livingDocsPath, issueNumber);
-          result.tasksReopened++;
-        }
-      });
-
-      await Promise.all(validationPromises);
-
-      console.log(`✅ Sync complete: ${result.acsUpdated} ACs, ${result.tasksUpdated} tasks updated`);
-      if (result.tasksReopened > 0) {
-        console.log(`   ${result.tasksReopened} tasks reopened due to missing code`);
-      }
-
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      result.errors.push(errorMsg);
-      console.error(`❌ Error syncing GitHub → Increment:`, error);
-    }
-
-    return result;
-  }
-
-  /**
-   * Sync from Increment to GitHub (Flow 2: Increment → Living Docs → GitHub)
-   *
-   * Triggered when developer completes work and updates increment files.
-   */
-  async syncIncrementToGitHub(
-    incrementPath: string,
-    livingDocsPath: string,
-    issueNumber: number
-  ): Promise<SyncResult> {
-    const result: SyncResult = {
-      acsUpdated: 0,
-      tasksUpdated: 0,
-      tasksReopened: 0,
-      conflicts: [],
-      errors: []
-    };
-
-    try {
-      console.log(`🔄 Syncing Increment → GitHub issue #${issueNumber}`);
-
-      // 1. Read increment spec.md and tasks.md
-      const specPath = path.join(incrementPath, 'spec.md');
-      const tasksPath = path.join(incrementPath, 'tasks.md');
-
-      const specContent = await fs.readFile(specPath, 'utf-8');
-      const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-
-      // 2. Parse ACs and Tasks
-      const acs = this.parseAcceptanceCriteria(specContent);
-      const tasks = this.parseTasks(tasksContent);
-
-      // 3. Update Living Docs User Stories (Layer 2)
-      const acsByUserStory = this.groupAcsByUserStory(acs);
-
-      for (const [userStoryId, userStoryAcs] of Object.entries(acsByUserStory)) {
-        const userStoryPath = await this.findUserStoryFile(livingDocsPath, userStoryId);
-        if (userStoryPath) {
-          // Update ACs in User Story
-          await this.updateUserStoryAcs(userStoryPath, userStoryAcs);
-          result.acsUpdated += userStoryAcs.length;
-
-          // Update Tasks in User Story (filter by AC IDs)
-          const acIds = userStoryAcs.map(ac => ac.id);
-          const userStoryTasks = this.filterTasksByAcIds(tasks, acIds);
-          await this.updateUserStoryTasks(userStoryPath, userStoryTasks);
-          result.tasksUpdated += userStoryTasks.length;
-        }
-      }
-
-      // 4. Update GitHub issue (Layer 1)
-      await this.updateGitHubIssue(issueNumber, acs, tasks);
-
-      console.log(`✅ Sync complete: ${result.acsUpdated} ACs, ${result.tasksUpdated} tasks updated`);
-
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      result.errors.push(errorMsg);
-      console.error(`❌ Error syncing Increment → GitHub:`, error);
-    }
-
-    return result;
-  }
-
-  /**
-   * Validate that code exists for completed task
-   * Uses CodeValidator for comprehensive validation
-   */
-  private async validateCodeExists(task: Task): Promise<boolean> {
-    // Use CodeValidator for robust validation
-    const validationResult = await this.codeValidator.validateTask(task.title, task.id);
-    return validationResult.valid;
-  }
-
-  /**
-   * Reopen task if code validation fails
-   */
-  private async reopenTask(
-    taskId: string,
-    incrementPath: string,
-    livingDocsPath: string,
-    issueNumber: number
-  ): Promise<void> {
-    // 1. Reopen in increment tasks.md
-    const tasksPath = path.join(incrementPath, 'tasks.md');
-    let tasksContent = await fs.readFile(tasksPath, 'utf-8');
-
-    // Find task and mark as incomplete
-    const taskRegex = new RegExp(`(### ${taskId}:[^#]*?)\\*\\*Completed\\*\\*:[^\\n]*\\n`, 's');
-    tasksContent = tasksContent.replace(taskRegex, '$1');
-
-    await fs.writeFile(tasksPath, tasksContent, 'utf-8');
-
-    // 2. Propagate to Living Docs
-    const userStoryPath = await this.findUserStoryFileForTask(livingDocsPath, taskId);
-    if (userStoryPath) {
-      await this.updateUserStoryTask(userStoryPath, taskId, false);
-    }
-
-    // 3. Propagate to GitHub (add comment explaining why)
-    await this.addGitHubComment(
-      issueNumber,
-      `⚠️ Task ${taskId} reopened: Code validation failed (missing or empty file). Please implement the required code.`
-    );
-  }
-
-  /**
-   * Propagate completion from Tasks → ACs → User Stories (bottom-up)
-   */
-  async propagateCompletion(
-    incrementPath: string,
-    livingDocsPath: string
-  ): Promise<void> {
-    // 1. Read increment files
-    const specPath = path.join(incrementPath, 'spec.md');
-    const tasksPath = path.join(incrementPath, 'tasks.md');
-
-    const specContent = await fs.readFile(specPath, 'utf-8');
-    const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-
-    const acs = this.parseAcceptanceCriteria(specContent);
-    const tasks = this.parseTasks(tasksContent);
-
-    // 2. For each AC, check if all its tasks are complete
-    for (const ac of acs) {
-      const acTasks = tasks.filter(t => t.acIds.includes(ac.id));
-      const allTasksComplete = acTasks.length > 0 && acTasks.every(t => t.completed);
-
-      if (allTasksComplete && !ac.completed) {
-        // Mark AC as complete
-        console.log(`✅ All tasks for ${ac.id} complete - marking AC as complete`);
-        await this.updateIncrementAc(incrementPath, ac.id, true);
-
-        // Propagate to Living Docs
-        const userStoryPath = await this.findUserStoryFile(livingDocsPath, ac.userStoryId);
-        if (userStoryPath) {
-          await this.updateUserStoryAc(userStoryPath, ac.id, true);
-        }
-      }
-    }
-
-    // 3. For each User Story, check if all ACs are complete
-    const acsByUserStory = this.groupAcsByUserStory(acs);
-
-    for (const [userStoryId, userStoryAcs] of Object.entries(acsByUserStory)) {
-      const allAcsComplete = userStoryAcs.every(ac => ac.completed);
-
-      if (allAcsComplete) {
-        console.log(`✅ All ACs for ${userStoryId} complete - User Story complete`);
-        // Could trigger User Story completion workflow here
-      }
-    }
-  }
-
-  // ==================== Helper Methods ====================
-
-  /**
-   * Fetch GitHub issue state
-   */
-  private async fetchGitHubIssueState(issueNumber: number): Promise<{ body: string; state: string }> {
-    const result = await execFileNoThrow('gh', [
-      'issue',
-      'view',
-      String(issueNumber),
-      '--json',
-      'body,state'
-    ], { env: this.getGhEnv() });
-
-    if (result.stderr) {
-      throw new Error(`Failed to fetch GitHub issue: ${result.stderr}`);
-    }
-
-    return JSON.parse(result.stdout);
-  }
-
-  /**
-   * Extract ACs from GitHub issue body
-   *
-   * CRITICAL FIX (v1.0.59): Handle multiple checkbox formats:
-   * - Bold format: `- [ ] **AC-US5-01**: Description` (SpecWeave standard)
-   * - Plain format: `- [ ] AC-US5-01: Description` (legacy/external)
-   */
-  private extractAcsFromIssue(body: string): AcceptanceCriterion[] {
-    const acs: AcceptanceCriterion[] = [];
-    const lines = body.split('\n');
-
-    // Pattern 1: Bold format `- [x] **AC-US5-01**: Description` (SpecWeave standard)
-    const boldAcRegex = /^- \[([ x])\] \*\*(AC-[A-Z0-9]+-\d+)\*\*:\s*(.+)$/;
-
-    // Pattern 2: Plain format `- [x] AC-US5-01: Description` (legacy)
-    const plainAcRegex = /^- \[([ x])\] (AC-[A-Z0-9]+-\d+):\s*(.+)$/;
-
-    for (const line of lines) {
-      // Try bold format first (more common in SpecWeave)
-      let match = line.match(boldAcRegex);
-      if (!match) {
-        match = line.match(plainAcRegex);
-      }
-
-      if (match) {
-        const completed = match[1] === 'x';
-        const id = match[2];
-        const description = match[3];
-
-        const userStoryMatch = id.match(/AC-([A-Z0-9]+)-\d+/);
-        const userStoryId = userStoryMatch ? userStoryMatch[1] : '';
-
-        acs.push({
-          id,
-          userStoryId,
-          description,
-          completed,
-          projects: [],
-          rawLine: line
-        });
-      }
-    }
-
-    return acs;
-  }
-
-  /**
-   * Extract Tasks from GitHub issue body
-   *
-   * CRITICAL FIX (v1.0.59): Handle multiple checkbox formats:
-   * - Bold format: `- [ ] **T-001**: Description` (SpecWeave standard)
-   * - Plain format: `- [ ] T-001: Description` (legacy/external)
-   */
-  private extractTasksFromIssue(body: string): Task[] {
-    const tasks: Task[] = [];
-    const lines = body.split('\n');
-
-    // Pattern 1: Bold format `- [x] **T-001**: Description` (SpecWeave standard)
-    const boldTaskRegex = /^- \[([ x])\] \*\*(T-\d+)\*\*:\s*(.+)$/;
-
-    // Pattern 2: Plain format `- [x] T-001: Description` (legacy)
-    const plainTaskRegex = /^- \[([ x])\] (T-\d+):\s*(.+)$/;
-
-    for (const line of lines) {
-      // Try bold format first
-      let match = line.match(boldTaskRegex);
-      if (!match) {
-        match = line.match(plainTaskRegex);
-      }
-
-      if (match) {
-        const completed = match[1] === 'x';
-        const id = match[2];
-        const title = match[3];
-
-        tasks.push({
-          id,
-          title,
-          completed,
-          acIds: []
-        });
-      }
-    }
-
-    return tasks;
-  }
-
-  /**
-   * Parse ACs from spec.md
-   *
-   * CRITICAL FIX (v1.0.59): Handle multiple checkbox formats in spec.md:
-   * - Bold format: `- [x] **AC-US5-01**: Description` (SpecWeave standard)
-   * - Plain format: `- [x] AC-US5-01: Description` (legacy)
-   */
-  private parseAcceptanceCriteria(specContent: string): AcceptanceCriterion[] {
-    const acs: AcceptanceCriterion[] = [];
-    const lines = specContent.split('\n');
-
-    // Pattern 1: Bold format `- [x] **AC-US5-01**: Description` (SpecWeave standard)
-    const boldAcRegex = /^- \[([ x])\] \*\*(AC-[A-Z0-9]+-\d+)\*\*:\s*(.+)$/;
-
-    // Pattern 2: Plain format `- [x] AC-US5-01: Description` (legacy)
-    const plainAcRegex = /^- \[([ x])\] (AC-[A-Z0-9]+-\d+):\s*(.+)$/;
-
-    for (const line of lines) {
-      // Try bold format first (SpecWeave standard)
-      let match = line.match(boldAcRegex);
-      if (!match) {
-        match = line.match(plainAcRegex);
-      }
-
-      if (match) {
-        const completed = match[1] === 'x';
-        const id = match[2];
-        const description = match[3];
-
-        const userStoryMatch = id.match(/AC-([A-Z0-9]+)-\d+/);
-        const userStoryId = userStoryMatch ? userStoryMatch[1] : '';
-
-        acs.push({
-          id,
-          userStoryId,
-          description,
-          completed,
-          projects: [],
-          rawLine: line
-        });
-      }
-    }
-
-    return acs;
-  }
-
-  /**
-   * Parse Tasks from tasks.md
-   */
-  private parseTasks(tasksContent: string): Task[] {
-    const tasks: Task[] = [];
-    const lines = tasksContent.split('\n');
-
-    let currentTask: Partial<Task> | null = null;
-
-    for (const line of lines) {
-      // Match task header: ### T-001: Title (P1)
-      const headerMatch = line.match(/^### (T-\d+):\s*(.+?)\s*\(P\d+\)$/);
-      if (headerMatch) {
-        if (currentTask && currentTask.id) {
-          tasks.push(currentTask as Task);
-        }
-
-        currentTask = {
-          id: headerMatch[1],
-          title: headerMatch[2],
-          completed: false,
-          acIds: []
-        };
-        continue;
-      }
-
-      // Check for completion
-      const completedMatch = line.match(/^\*\*Completed\*\*:\s*(.+)$/);
-      if (completedMatch && currentTask) {
-        currentTask.completed = true;
-        currentTask.completedDate = completedMatch[1];
-      }
-
-      // Extract AC IDs
-      const acMatch = line.match(/\*\*AC\*\*:\s*(.+)$/);
-      if (acMatch && currentTask) {
-        const acIds = acMatch[1].split(',').map(id => id.trim());
-        currentTask.acIds = acIds;
-      }
-    }
-
-    if (currentTask && currentTask.id) {
-      tasks.push(currentTask as Task);
-    }
-
-    return tasks;
-  }
-
-  /**
-   * Group ACs by User Story ID
-   */
-  private groupAcsByUserStory(acs: AcceptanceCriterion[]): Record<string, AcceptanceCriterion[]> {
-    const grouped: Record<string, AcceptanceCriterion[]> = {};
-
-    for (const ac of acs) {
-      if (!grouped[ac.userStoryId]) {
-        grouped[ac.userStoryId] = [];
-      }
-      grouped[ac.userStoryId].push(ac);
-    }
-
-    return grouped;
-  }
-
-  /**
-   * Filter tasks by AC IDs
-   */
-  private filterTasksByAcIds(tasks: Task[], acIds: string[]): Task[] {
-    return tasks.filter(task =>
-      task.acIds.some(acId => acIds.includes(acId))
-    );
-  }
-
-  /**
-   * Find User Story file by ID (with caching for performance)
-   */
-  private async findUserStoryFile(livingDocsPath: string, userStoryId: string): Promise<string | null> {
-    // Check cache first
-    const cacheKey = `${livingDocsPath}:${userStoryId}`;
-    if (this.userStoryFileCache.has(cacheKey)) {
-      return this.userStoryFileCache.get(cacheKey)!;
-    }
-
-    // Search in specs directory
-    const specsPath = path.join(livingDocsPath, 'internal', 'specs');
-
-    // Use glob to find user story files
-    const pattern = `**/us-*${userStoryId.toLowerCase()}*.md`;
-    const { glob } = await import('glob');
-    const files = await glob(pattern, { cwd: specsPath, absolute: true });
-
-    const result = files.length > 0 ? files[0] : null;
-
-    // Cache the result
-    this.userStoryFileCache.set(cacheKey, result);
-
-    return result;
-  }
-
-  /**
-   * Find User Story file that contains specific task
-   */
-  private async findUserStoryFileForTask(livingDocsPath: string, taskId: string): Promise<string | null> {
-    // Search all user story files for the task
-    const specsPath = path.join(livingDocsPath, 'internal', 'specs');
-    const { glob } = await import('glob');
-    const files = await glob('**/us-*.md', { cwd: specsPath, absolute: true });
-
-    for (const file of files) {
-      const content = await fs.readFile(file, 'utf-8');
-      if (content.includes(taskId)) {
-        return file;
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Update AC in User Story file
-   */
-  private async updateUserStoryAc(userStoryPath: string, acId: string, completed: boolean): Promise<void> {
-    let content = await fs.readFile(userStoryPath, 'utf-8');
-
-    // Update checkbox state
-    const checkboxState = completed ? 'x' : ' ';
-    const regex = new RegExp(`(- \\[)[ x](\\] ${acId}:)`, 'g');
-    content = content.replace(regex, `$1${checkboxState}$2`);
-
-    await fs.writeFile(userStoryPath, content, 'utf-8');
-  }
-
-  /**
-   * Update Task in User Story file
-   */
-  private async updateUserStoryTask(userStoryPath: string, taskId: string, completed: boolean): Promise<void> {
-    let content = await fs.readFile(userStoryPath, 'utf-8');
-
-    // Update checkbox state
-    const checkboxState = completed ? 'x' : ' ';
-    const regex = new RegExp(`(- \\[)[ x](\\] ${taskId}:)`, 'g');
-    content = content.replace(regex, `$1${checkboxState}$2`);
-
-    await fs.writeFile(userStoryPath, content, 'utf-8');
-  }
-
-  /**
-   * Update multiple ACs in User Story file
-   */
-  private async updateUserStoryAcs(userStoryPath: string, acs: AcceptanceCriterion[]): Promise<void> {
-    let content = await fs.readFile(userStoryPath, 'utf-8');
-
-    for (const ac of acs) {
-      const checkboxState = ac.completed ? 'x' : ' ';
-      const regex = new RegExp(`(- \\[)[ x](\\] ${ac.id}:)`, 'g');
-      content = content.replace(regex, `$1${checkboxState}$2`);
-    }
-
-    await fs.writeFile(userStoryPath, content, 'utf-8');
-  }
-
-  /**
-   * Update multiple Tasks in User Story file
-   */
-  private async updateUserStoryTasks(userStoryPath: string, tasks: Task[]): Promise<void> {
-    let content = await fs.readFile(userStoryPath, 'utf-8');
-
-    for (const task of tasks) {
-      const checkboxState = task.completed ? 'x' : ' ';
-      const regex = new RegExp(`(- \\[)[ x](\\] ${task.id}:)`, 'g');
-      content = content.replace(regex, `$1${checkboxState}$2`);
-    }
-
-    await fs.writeFile(userStoryPath, content, 'utf-8');
-  }
-
-  /**
-   * Update AC in increment spec.md
-   */
-  private async updateIncrementAc(incrementPath: string, acId: string, completed: boolean): Promise<void> {
-    const specPath = path.join(incrementPath, 'spec.md');
-    let content = await fs.readFile(specPath, 'utf-8');
-
-    const checkboxState = completed ? 'x' : ' ';
-    const regex = new RegExp(`(- \\[)[ x](\\] ${acId}:)`, 'g');
-    content = content.replace(regex, `$1${checkboxState}$2`);
-
-    await fs.writeFile(specPath, content, 'utf-8');
-  }
-
-  /**
-   * Update multiple ACs in increment spec.md
-   */
-  private async updateIncrementAcs(incrementPath: string, acs: AcceptanceCriterion[]): Promise<void> {
-    const specPath = path.join(incrementPath, 'spec.md');
-    let content = await fs.readFile(specPath, 'utf-8');
-
-    for (const ac of acs) {
-      const checkboxState = ac.completed ? 'x' : ' ';
-      const regex = new RegExp(`(- \\[)[ x](\\] ${ac.id}:)`, 'g');
-      content = content.replace(regex, `$1${checkboxState}$2`);
-    }
-
-    await fs.writeFile(specPath, content, 'utf-8');
-  }
-
-  /**
-   * Update multiple Tasks in increment tasks.md
-   */
-  private async updateIncrementTasks(incrementPath: string, tasks: Task[]): Promise<void> {
-    const tasksPath = path.join(incrementPath, 'tasks.md');
-    let content = await fs.readFile(tasksPath, 'utf-8');
-
-    for (const task of tasks) {
-      if (task.completed) {
-        // Add **Completed** marker if not present
-        const taskHeader = `### ${task.id}:`;
-        const completedMarker = `**Completed**: ${new Date().toISOString().split('T')[0]}`;
-
-        if (!content.includes(`${taskHeader}`) || !content.includes(`**Completed**`)) {
-          // Find task section and add completed marker
-          const regex = new RegExp(`(### ${task.id}:[^#]*?)(###|$)`, 's');
-          content = content.replace(regex, `$1\n${completedMarker}\n\n$2`);
-        }
-      }
-    }
-
-    await fs.writeFile(tasksPath, content, 'utf-8');
-  }
-
-  /**
-   * Update ACs in increment with conflict resolution (Increment wins)
-   *
-   * If GitHub and Increment disagree, Increment state wins as it's the source of truth.
-   * Conflicts are logged for transparency.
-   */
-  private async updateIncrementAcsWithConflictResolution(
-    incrementPath: string,
-    githubAcs: AcceptanceCriterion[],
-    result: SyncResult
-  ): Promise<void> {
-    const specPath = path.join(incrementPath, 'spec.md');
-    const currentContent = await fs.readFile(specPath, 'utf-8');
-
-    // Parse current state from increment
-    const currentAcs = this.parseAcceptanceCriteria(currentContent);
-
-    let content = currentContent;
-
-    for (const githubAc of githubAcs) {
-      const currentAc = currentAcs.find(ac => ac.id === githubAc.id);
-
-      if (currentAc && currentAc.completed !== githubAc.completed) {
-        // CONFLICT: Increment state differs from GitHub state
-        const conflictMsg = `AC ${githubAc.id}: GitHub says ${githubAc.completed ? 'complete' : 'incomplete'}, Increment says ${currentAc.completed ? 'complete' : 'incomplete'} → Increment wins`;
-        result.conflicts.push(conflictMsg);
-        console.log(`⚠️  CONFLICT RESOLVED: ${conflictMsg}`);
-
-        // Keep increment state (do not update)
-        continue;
-      }
-
-      // No conflict - apply GitHub change
-      const checkboxState = githubAc.completed ? 'x' : ' ';
-      const regex = new RegExp(`(- \\[)[ x](\\] ${githubAc.id}:)`, 'g');
-      content = content.replace(regex, `$1${checkboxState}$2`);
-    }
-
-    await fs.writeFile(specPath, content, 'utf-8');
-  }
-
-  /**
-   * Update Tasks in increment with conflict resolution (Increment wins)
-   */
-  private async updateIncrementTasksWithConflictResolution(
-    incrementPath: string,
-    githubTasks: Task[],
-    result: SyncResult
-  ): Promise<void> {
-    const tasksPath = path.join(incrementPath, 'tasks.md');
-    const currentContent = await fs.readFile(tasksPath, 'utf-8');
-
-    // Parse current state from increment
-    const currentTasks = this.parseTasks(currentContent);
-
-    let content = currentContent;
-
-    for (const githubTask of githubTasks) {
-      const currentTask = currentTasks.find(t => t.id === githubTask.id);
-
-      if (currentTask && currentTask.completed !== githubTask.completed) {
-        // CONFLICT: Increment state differs from GitHub state
-        const conflictMsg = `Task ${githubTask.id}: GitHub says ${githubTask.completed ? 'complete' : 'incomplete'}, Increment says ${currentTask.completed ? 'complete' : 'incomplete'} → Increment wins`;
-        result.conflicts.push(conflictMsg);
-        console.log(`⚠️  CONFLICT RESOLVED: ${conflictMsg}`);
-
-        // Keep increment state (do not update)
-        continue;
-      }
-
-      // No conflict - apply GitHub change
-      if (githubTask.completed) {
-        const taskHeader = `### ${githubTask.id}:`;
-        const completedMarker = `**Completed**: ${new Date().toISOString().split('T')[0]}`;
-
-        if (!content.includes(`${taskHeader}`) || !content.includes(`**Completed**`)) {
-          const regex = new RegExp(`(### ${githubTask.id}:[^#]*?)(###|$)`, 's');
-          content = content.replace(regex, `$1\n${completedMarker}\n\n$2`);
-        }
-      }
-    }
-
-    await fs.writeFile(tasksPath, content, 'utf-8');
-  }
-
-  /**
-   * Update GitHub issue with ACs and Tasks
-   *
-   * CRITICAL FIX (v1.0.59): Handle multiple checkbox formats in GitHub issues:
-   * - Bold format: `- [ ] **AC-US5-01**: Description` (SpecWeave standard)
-   * - Plain format: `- [ ] AC-US5-01: Description` (legacy/external)
-   *
-   * The regex must match BOTH formats to correctly sync checkboxes.
-   */
-  private async updateGitHubIssue(issueNumber: number, acs: AcceptanceCriterion[], tasks: Task[]): Promise<void> {
-    // Fetch current issue
-    const result = await execFileNoThrow('gh', [
-      'issue',
-      'view',
-      String(issueNumber),
-      '--json',
-      'body'
-    ], { env: this.getGhEnv() });
-
-    if (result.stderr || !result.stdout) {
-      console.warn(`⚠️  Could not fetch GitHub issue #${issueNumber}: ${result.stderr}`);
-      return;
-    }
-
-    const { body } = JSON.parse(result.stdout);
-    if (!body) {
-      console.warn(`⚠️  GitHub issue #${issueNumber} has no body`);
-      return;
-    }
-
-    // Update AC checkboxes - handle BOTH bold and plain formats
-    let updatedBody = body;
-    let changesCount = 0;
-
-    for (const ac of acs) {
-      const checkboxState = ac.completed ? 'x' : ' ';
-      // Escape AC ID for use in regex (handle hyphens)
-      const escapedAcId = ac.id.replace(/-/g, '\\-');
-
-      // Pattern 1: Bold format `- [ ] **AC-US5-01**: Description` (SpecWeave standard)
-      const boldRegex = new RegExp(`(- \\[)[ x](\\] \\*\\*${escapedAcId}\\*\\*:)`, 'g');
-
-      // Pattern 2: Plain format `- [ ] AC-US5-01: Description` (legacy)
-      const plainRegex = new RegExp(`(- \\[)[ x](\\] ${escapedAcId}:)`, 'g');
-
-      const beforeLength = updatedBody.length;
-      updatedBody = updatedBody.replace(boldRegex, `$1${checkboxState}$2`);
-      updatedBody = updatedBody.replace(plainRegex, `$1${checkboxState}$2`);
-
-      if (updatedBody.length !== beforeLength || updatedBody !== body) {
-        changesCount++;
-      }
-    }
-
-    // Update Task checkboxes - handle BOTH bold and plain formats
-    for (const task of tasks) {
-      const checkboxState = task.completed ? 'x' : ' ';
-      const escapedTaskId = task.id.replace(/-/g, '\\-');
-
-      // Pattern 1: Bold format `- [ ] **T-001**: Description`
-      const boldRegex = new RegExp(`(- \\[)[ x](\\] \\*\\*${escapedTaskId}\\*\\*:)`, 'g');
-
-      // Pattern 2: Plain format `- [ ] T-001: Description`
-      const plainRegex = new RegExp(`(- \\[)[ x](\\] ${escapedTaskId}:)`, 'g');
-
-      updatedBody = updatedBody.replace(boldRegex, `$1${checkboxState}$2`);
-      updatedBody = updatedBody.replace(plainRegex, `$1${checkboxState}$2`);
-    }
-
-    // Only update if there are changes
-    if (updatedBody === body) {
-      console.log(`   ⏭️  No checkbox changes for issue #${issueNumber}`);
-      return;
-    }
-
-    // Update issue via gh CLI
-    const updateResult = await execFileNoThrow('gh', [
-      'issue',
-      'edit',
-      String(issueNumber),
-      '--body',
-      updatedBody
-    ], { env: this.getGhEnv() });
-
-    if (updateResult.stderr) {
-      console.warn(`⚠️  Failed to update GitHub issue #${issueNumber}: ${updateResult.stderr}`);
-    } else {
-      console.log(`   ✅ Updated checkboxes in GitHub issue #${issueNumber}`);
-    }
-  }
-
-  /**
-   * Add comment to GitHub issue
-   */
-  private async addGitHubComment(issueNumber: number, comment: string): Promise<void> {
-    await execFileNoThrow('gh', [
-      'issue',
-      'comment',
-      String(issueNumber),
-      '--body',
-      comment
-    ], { env: this.getGhEnv() });
-  }
-}