@agile-vibe-coding/avc 0.2.3 → 0.3.2

package/cli/worktree-runner.js

@@ -0,0 +1,654 @@
+/**
+ * worktree-runner.js — Git worktree lifecycle for AI-assisted task implementation.
+ *
+ * Flow: createWorktree → readDocChain → generate→validate loop → runTests → commitAndMerge → cleanup
+ *
+ * Uses split agents (code-implementer + code-validator) with ceremony-grade configuration:
+ * - Per-stage provider/model from avc.json "run" ceremony
+ * - Check definitions from src/cli/checks/code/*.json (with project overrides)
+ * - Validation loop controlled by maxValidationIterations and acceptanceThreshold
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync, execFileSync } from 'child_process';
+import { LLMProvider } from './llm-provider.js';
+import { loadAgent } from './agent-loader.js';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Execute a git command in a given directory, returning stdout.
+ * Throws on non-zero exit.
+ */
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: 60_000 }).trim();
+}
+
+/**
+ * Compute hierarchy prefix from a task ID.
+ * context-0001-0002-0003 → e0001_s0002_t0003
+ * context-0001-0002 → e0001_s0002
+ * context-0001 → e0001
+ */
+export function computeHierarchyPrefix(taskId) {
+  const parts = taskId.replace('context-', '').split('-');
+  const labels = ['e', 's', 't', 'st'];
+  return parts.slice(0, 4).map((p, i) => `${labels[i] || 'x'}${p}`).join('_');
+}
+
+export class WorktreeRunner {
+  /**
+   * @param {string} taskId — context-XXXX-XXXX-XXXX
+   * @param {string} projectRoot — absolute path to the project (parent of .avc)
+   */
+  constructor(taskId, projectRoot) {
+    this.taskId = taskId;
+    this.projectRoot = projectRoot;
+    this.avcPath = path.join(projectRoot, '.avc');
+    this.worktreePath = path.join(this.avcPath, 'worktrees', taskId);
+    this.branchName = `avc/${taskId}`;
+    this.prefix = computeHierarchyPrefix(taskId);
+
+    // Read ceremony config for the 'run' ceremony
+    const configPath = path.join(this.avcPath, 'avc.json');
+    let ceremony = null;
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      ceremony = cfg.settings?.ceremonies?.find(c => c.name === 'run');
+    } catch {}
+
+    this._ceremony = ceremony || {};
+    this._defaultProvider = ceremony?.provider || 'local';
+    this._defaultModel = ceremony?.defaultModel || 'qwen/qwen3-coder-next';
+    this._maxIterations = ceremony?.maxValidationIterations ?? 3;
+    this._acceptanceThreshold = ceremony?.acceptanceThreshold ?? 80;
+    this._stageProviders = {};
+  }
+
+  /**
+   * Pre-flight check: verify the project has minimum infrastructure before running tasks.
+   * Warns (does not block) if package.json or test config is missing — the scaffolding
+   * epic should have created these, but if it hasn't run yet, we still proceed with warnings.
+   */
+  _preflightCheck(progressCallback) {
+    const warnings = [];
+
+    // Check package.json
+    const pkgPath = path.join(this.projectRoot, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      warnings.push('No package.json found — tests will be skipped. Run the Project Scaffolding epic first.');
+    }
+
+    // Check git repo
+    try {
+      git(['rev-parse', '--git-dir'], this.projectRoot);
+    } catch {
+      warnings.push('No git repository found — worktree creation may fail. Run "git init" first.');
+    }
+
+    for (const w of warnings) {
+      this.debug(`[PRE-FLIGHT WARNING] ${w}`);
+      progressCallback?.(`Warning: ${w}`);
+    }
+  }
+
+  debug(msg, data = null) {
+    const ts = new Date().toISOString();
+    if (data) {
+      console.log(`[DEBUG][${ts}] ${msg}`, JSON.stringify(data, null, 2));
+    } else {
+      console.log(`[DEBUG][${ts}] ${msg}`);
+    }
+  }
+
+  /**
+   * Main execution — full worktree lifecycle.
+   * @param {Function} progressCallback — (message) => void
+   * @param {Function} cancelledCheck — () => boolean
+   * @returns {Promise<{ success: boolean, error?: string }>}
+   */
+  async execute(progressCallback, cancelledCheck = null) {
+    try {
+      // 0. Pre-flight: verify project structure exists
+      this._preflightCheck(progressCallback);
+
+      // 1. Create worktree
+      progressCallback?.('Creating git worktree...');
+      if (cancelledCheck?.()) throw new Error('CANCELLED');
+      this.createWorktree();
+
+      // 2. Read full doc chain
+      progressCallback?.('Reading documentation chain...');
+      if (cancelledCheck?.()) throw new Error('CANCELLED');
+      const context = this.readDocChain();
+
+      // 3. Implement code via LLM
+      progressCallback?.('Implementing code with AI agent...');
+      if (cancelledCheck?.()) throw new Error('CANCELLED');
+      await this.implementCode(context, progressCallback);
+
+      // 4. Run tests
+      progressCallback?.('Running tests...');
+      if (cancelledCheck?.()) throw new Error('CANCELLED');
+      const testResult = this.runTests();
+
+      if (!testResult.passed) {
+        progressCallback?.(`Tests failed: ${testResult.summary}`);
+        this.cleanup();
+        return { success: false, error: `Tests failed: ${testResult.summary}` };
+      }
+
+      // 5. Commit and merge
+      progressCallback?.('Committing and merging to main...');
+      if (cancelledCheck?.()) throw new Error('CANCELLED');
+      this.commitAndMerge();
+
+      // 6. Cleanup
+      progressCallback?.('Cleaning up worktree...');
+      this.cleanup();
+
+      return { success: true };
+    } catch (err) {
+      // Always cleanup on failure
+      try { this.cleanup(); } catch {}
+
+      if (err.message === 'CANCELLED') {
+        return { success: false, error: 'Cancelled' };
+      }
+      return { success: false, error: err.message };
+    }
+  }
+
+  /**
+   * Create a new git worktree for the task.
+   */
+  createWorktree() {
+    const worktreesDir = path.dirname(this.worktreePath);
+    if (!fs.existsSync(worktreesDir)) {
+      fs.mkdirSync(worktreesDir, { recursive: true });
+    }
+
+    // Ensure we're in a git repo
+    try {
+      git(['rev-parse', '--git-dir'], this.projectRoot);
+    } catch {
+      throw new Error('Not a git repository. Initialize with "git init" first.');
+    }
+
+    // Ensure there's at least one commit
+    try {
+      git(['rev-parse', 'HEAD'], this.projectRoot);
+    } catch {
+      // Create initial commit if repo is empty
+      git(['commit', '--allow-empty', '-m', 'Initial commit'], this.projectRoot);
+    }
+
+    // Remove stale worktree if it exists
+    if (fs.existsSync(this.worktreePath)) {
+      try { git(['worktree', 'remove', '--force', this.worktreePath], this.projectRoot); } catch {}
+    }
+
+    // Delete branch if it exists from a previous failed run
+    try { git(['branch', '-D', this.branchName], this.projectRoot); } catch {}
+
+    // Create new worktree with branch
+    git(['worktree', 'add', this.worktreePath, '-b', this.branchName], this.projectRoot);
+    this.debug('Worktree created', { path: this.worktreePath, branch: this.branchName });
+  }
+
+  /**
+   * Read the full documentation chain: project → epic → story → task (+ subtasks).
+   * Returns concatenated context string.
+   */
+  readDocChain() {
+    const projectPath = path.join(this.avcPath, 'project');
+    const parts = [];
+
+    // Walk from task ID up through ancestors
+    // context-0001-0001-0001 → [context-0001, context-0001-0001, context-0001-0001-0001]
+    const segments = this.taskId.match(/context-\d{4}(-\d{4})*/g) || [];
+    const ancestorIds = [];
+    const idParts = this.taskId.replace('context-', '').split('-');
+    let current = 'context';
+    for (const part of idParts) {
+      current += `-${part}`;
+      ancestorIds.push(current);
+    }
+
+    // Read project-level docs
+    const projectDoc = this._readIfExists(path.join(projectPath, 'doc.md'));
+    const projectContext = this._readIfExists(path.join(projectPath, 'context.md'));
+    if (projectDoc) parts.push(`# Project Documentation\n\n${projectDoc}`);
+    if (projectContext) parts.push(`# Project Context\n\n${projectContext}`);
+
+    // Read each ancestor level
+    let dirPath = projectPath;
+    for (const id of ancestorIds) {
+      dirPath = path.join(projectPath, ...ancestorIds.slice(0, ancestorIds.indexOf(id) + 1).map((_, i) => ancestorIds[i]));
+      // Actually build the nested path correctly
+      break; // Will use a different approach
+    }
+
+    // Build nested path: project/epic-id/story-id/task-id
+    const epicId = ancestorIds[0]; // context-0001
+    const dirs = [projectPath];
+    let nested = projectPath;
+    for (const id of ancestorIds) {
+      nested = path.join(nested, id);
+      dirs.push(nested);
+    }
+
+    // Read context.md and doc.md at each level (skip project, already read)
+    for (let i = 1; i < dirs.length; i++) {
+      const dir = dirs[i];
+      const id = ancestorIds[i - 1];
+      const doc = this._readIfExists(path.join(dir, 'doc.md'));
+      const ctx = this._readIfExists(path.join(dir, 'context.md'));
+      const work = this._readIfExists(path.join(dir, 'work.json'));
+
+      if (ctx) parts.push(`# Context: ${id}\n\n${ctx}`);
+      if (doc) parts.push(`# Documentation: ${id}\n\n${doc}`);
+
+      // Include work.json acceptance criteria for the task itself
+      if (i === dirs.length - 1 && work) {
+        try {
+          const w = JSON.parse(work);
+          if (w.acceptance?.length) {
+            parts.push(`# Acceptance Criteria (${id})\n\n${w.acceptance.map((a, j) => `${j + 1}. ${a}`).join('\n')}`);
+          }
+        } catch {}
+      }
+    }
+
+    // Also read subtask docs if they exist
+    const taskDir = dirs[dirs.length - 1];
+    if (fs.existsSync(taskDir)) {
+      try {
+        const entries = fs.readdirSync(taskDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory() && entry.name.startsWith('context-')) {
+            const subtaskDoc = this._readIfExists(path.join(taskDir, entry.name, 'doc.md'));
+            const subtaskCtx = this._readIfExists(path.join(taskDir, entry.name, 'context.md'));
+            if (subtaskCtx) parts.push(`# Subtask Context: ${entry.name}\n\n${subtaskCtx}`);
+            if (subtaskDoc) parts.push(`# Subtask Documentation: ${entry.name}\n\n${subtaskDoc}`);
+          }
+        }
+      } catch {}
+    }
+
+    this.debug('Doc chain read', { levels: dirs.length, totalChars: parts.join('').length });
+    return parts.join('\n\n---\n\n');
+  }
+
+  /**
+   * Get or create an LLM provider for a specific stage.
+   */
+  async _getStageProvider(stageName) {
+    const key = stageName;
+    if (this._stageProviders[key]) return this._stageProviders[key];
+
+    const stageConfig = this._ceremony?.stages?.[stageName] || {};
+    const provider = stageConfig.provider || this._defaultProvider;
+    const model = stageConfig.model || this._defaultModel;
+
+    const instance = await LLMProvider.create(provider, model);
+    this._stageProviders[key] = instance;
+    return instance;
+  }
+
+  /**
+   * Load code check definitions from src/cli/checks/code/*.json,
+   * with project-level overrides from .avc/customized-agents/checks/code/*.json.
+   */
+  _loadCodeChecks() {
+    const builtinDir = path.join(__dirname, 'checks', 'code');
+    const overrideDir = path.join(this.avcPath, 'customized-agents', 'checks', 'code');
+    const checks = [];
+
+    if (!fs.existsSync(builtinDir)) return checks;
+
+    for (const file of fs.readdirSync(builtinDir)) {
+      if (!file.endsWith('.json')) continue;
+      const overridePath = path.join(overrideDir, file);
+      const builtinPath = path.join(builtinDir, file);
+      const source = fs.existsSync(overridePath) ? overridePath : builtinPath;
+      try {
+        const defs = JSON.parse(fs.readFileSync(source, 'utf8'));
+        checks.push(...defs);
+      } catch {}
+    }
+
+    this.debug('Code checks loaded', { count: checks.length });
+    return checks;
+  }
+
+  /**
+   * Read acceptance criteria from the task's work.json.
+   */
+  _readAcceptanceCriteria() {
+    const idParts = this.taskId.replace('context-', '').split('-');
+    let dir = path.join(this.avcPath, 'project');
+    let current = 'context';
+    for (const part of idParts) {
+      current += `-${part}`;
+      dir = path.join(dir, current);
+    }
+    const workJsonPath = path.join(dir, 'work.json');
+    try {
+      const w = JSON.parse(fs.readFileSync(workJsonPath, 'utf8'));
+      return w.acceptance || [];
+    } catch { return []; }
+  }
+
+  /**
+   * Generate code using the code-implementer agent.
+   */
+  async _generateCode(context, prefix, acceptance, violations = null) {
+    const provider = await this._getStageProvider('code-generation');
+    const agentInstructions = loadAgent('code-implementer.md');
+
+    const violationSection = violations
+      ? `\n\n## Previous Validation Violations (FIX THESE)\n\n${violations.map(v => `- [${v.id}] ${v.detail}: ${v.fix}`).join('\n')}`
+      : '';
+
+    const prompt = `## Hierarchy Prefix\n${prefix}\n\n## Task ID\n${this.taskId}\n\n## Acceptance Criteria\n${acceptance.map((ac, i) => `${i + 1}. ${ac}`).join('\n')}\n\n## Documentation Chain\n\n${context}${violationSection}`;
+
+    const result = await provider.generateJSON(prompt, agentInstructions);
+
+    if (!result?.files || !Array.isArray(result.files)) {
+      throw new Error('Code implementer did not return valid file structure');
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate generated code using the code-validator agent.
+   */
+  async _validateCode(codeOutput, checks, prefix, acceptance) {
+    const provider = await this._getStageProvider('code-validation');
+    const agentInstructions = loadAgent('code-validator.md');
+
+    const codeSection = [
+      ...(codeOutput.files || []).map(f => `### ${f.path}\n\`\`\`javascript\n${f.content}\n\`\`\``),
+      ...(codeOutput.tests || []).map(f => `### ${f.path}\n\`\`\`javascript\n${f.content}\n\`\`\``),
+    ].join('\n\n');
+
+    const prompt = `## Generated Code\n\n${codeSection}\n\n## Check Definitions\n\n${JSON.stringify(checks, null, 2)}\n\n## Task ID\n${this.taskId}\n\n## Hierarchy Prefix\n${prefix}\n\n## Acceptance Criteria\n${acceptance.map((ac, i) => `${i + 1}. ${ac}`).join('\n')}\n\n## Acceptance Threshold\n${this._acceptanceThreshold}`;
+
+    const result = await provider.generateJSON(prompt, agentInstructions);
+    return result;
+  }
+
+  /**
+   * Implement code with generate→validate loop.
+   * Replaces the old single-shot implementCode().
+   */
+  async implementCode(context, progressCallback) {
+    const checks = this._loadCodeChecks();
+    const acceptance = this._readAcceptanceCriteria();
+
+    let codeOutput = null;
+    let validationResult = null;
+    let violations = null;
+    let finalScore = null;
+    let bestOutput = null;
+    let bestScore = 0;
+
+    for (let iter = 1; iter <= this._maxIterations; iter++) {
+      progressCallback?.(`Code generation (iteration ${iter}/${this._maxIterations})...`);
+      codeOutput = await this._generateCode(context, this.prefix, acceptance, violations);
+
+      if (checks.length > 0) {
+        progressCallback?.(`Code validation (iteration ${iter}/${this._maxIterations})...`);
+        validationResult = await this._validateCode(codeOutput, checks, this.prefix, acceptance);
+
+        const score = validationResult?.score ?? 0;
+        finalScore = score;
+
+        // Track best output
+        if (score > bestScore) {
+          bestScore = score;
+          bestOutput = JSON.parse(JSON.stringify(codeOutput));
+        }
+
+        if (validationResult?.passed || score >= this._acceptanceThreshold) {
+          progressCallback?.(`Validation passed (score: ${score}, threshold: ${this._acceptanceThreshold})`);
+          break;
+        }
+
+        violations = validationResult?.violations || [];
+        const criticalCount = violations.filter(v => v.severity === 'critical').length;
+        progressCallback?.(`Validation: ${violations.length} violation(s) (${criticalCount} critical), score ${score} (threshold: ${this._acceptanceThreshold})`);
+
+        if (iter === this._maxIterations) {
+          // Use best output if final iteration didn't improve
+          if (bestOutput && bestScore > score) {
+            codeOutput = bestOutput;
+            finalScore = bestScore;
+          }
+
+          // Fail if critical violations remain after all iterations
+          if (criticalCount > 0 && finalScore < this._acceptanceThreshold) {
+            progressCallback?.(`FAILED: ${criticalCount} critical violation(s) remain after ${this._maxIterations} iterations (score: ${finalScore})`);
+            throw new Error(`Code validation failed with ${criticalCount} critical violation(s) after ${this._maxIterations} iterations. Score: ${finalScore}/${this._acceptanceThreshold}`);
+          }
+
+          progressCallback?.(`Max iterations — accepting best score ${finalScore} (threshold: ${this._acceptanceThreshold})`);
+        }
+      } else {
+        break; // No checks defined, skip validation
+      }
+    }
+
+    // Write all files to worktree
+    const allFiles = [...(codeOutput.files || []), ...(codeOutput.tests || [])];
+    for (const file of allFiles) {
+      if (!file.path || typeof file.content !== 'string') continue;
+      const filePath = path.join(this.worktreePath, file.path);
+      const fileDir = path.dirname(filePath);
+      if (!fs.existsSync(fileDir)) fs.mkdirSync(fileDir, { recursive: true });
+      fs.writeFileSync(filePath, file.content, 'utf8');
+      this.debug('File written', { path: file.path, size: file.content.length });
+    }
+
+    // Write function registry to task work.json
+    if (codeOutput.functionRegistry?.length > 0) {
+      this._updateFunctionRegistry(codeOutput.functionRegistry);
+    }
+
+    // Write validation metadata to task work.json
+    if (finalScore !== null) {
+      this._writeValidationMetadata(finalScore, validationResult?.violations || []);
+    }
+
+    progressCallback?.(`Generated ${allFiles.length} file(s) (validation score: ${finalScore ?? 'n/a'}): ${codeOutput.summary || ''}`);
+  }
+
+  /**
+   * Write function registry to the task's work.json and propagate up to story and epic.
+   */
+  _updateFunctionRegistry(functions) {
+    const idParts = this.taskId.replace('context-', '').split('-');
+
+    // Build path to task's work.json
+    let dir = path.join(this.avcPath, 'project');
+    let current = 'context';
+    for (const part of idParts) {
+      current += `-${part}`;
+      dir = path.join(dir, current);
+    }
+
+    // Write to task
+    this._mergeFunctionsIntoWorkJson(path.join(dir, 'work.json'), functions);
+
+    // Propagate to story (parent of task)
+    const storyDir = path.dirname(dir);
+    const storyFunctions = functions.map(f => ({ ...f, task: this.taskId }));
+    this._mergeFunctionsIntoWorkJson(path.join(storyDir, 'work.json'), storyFunctions);
+
+    // Propagate to epic (parent of story)
+    const epicDir = path.dirname(storyDir);
+    this._mergeFunctionsIntoWorkJson(path.join(epicDir, 'work.json'), storyFunctions);
+
+    this.debug('Function registry updated', { count: functions.length, taskId: this.taskId });
+  }
+
+  /**
+   * Merge functions into a work.json file's functions array (deduplicating by name).
+   */
+  _mergeFunctionsIntoWorkJson(workJsonPath, newFunctions) {
+    if (!fs.existsSync(workJsonPath)) return;
+    try {
+      const workJson = JSON.parse(fs.readFileSync(workJsonPath, 'utf8'));
+      const existing = workJson.functions || [];
+      const existingNames = new Set(existing.map(f => f.name));
+      for (const fn of newFunctions) {
+        if (!existingNames.has(fn.name)) {
+          existing.push(fn);
+          existingNames.add(fn.name);
+        }
+      }
+      workJson.functions = existing;
+      fs.writeFileSync(workJsonPath, JSON.stringify(workJson, null, 2), 'utf8');
+    } catch {}
+  }
+
+  /**
+   * Write validation score and remaining violations to the task's work.json metadata.
+   */
+  _writeValidationMetadata(score, violations) {
+    const idParts = this.taskId.replace('context-', '').split('-');
+    let dir = path.join(this.avcPath, 'project');
+    let current = 'context';
+    for (const part of idParts) {
+      current += `-${part}`;
+      dir = path.join(dir, current);
+    }
+    const workJsonPath = path.join(dir, 'work.json');
+    if (!fs.existsSync(workJsonPath)) return;
+    try {
+      const workJson = JSON.parse(fs.readFileSync(workJsonPath, 'utf8'));
+      workJson.metadata = workJson.metadata || {};
+      workJson.metadata.codeValidation = {
+        score,
+        threshold: this._acceptanceThreshold,
+        violations: violations.length,
+        criticalViolations: violations.filter(v => v.severity === 'critical').length,
+        lastChecked: new Date().toISOString(),
+      };
+      fs.writeFileSync(workJsonPath, JSON.stringify(workJson, null, 2), 'utf8');
+    } catch {}
+  }
+
+  /**
+   * Run the project's test command.
+   */
+  runTests() {
+    // Try to find test command from package.json or avc.json
+    let testCmd = 'npm test';
+    try {
+      const avcConfig = JSON.parse(fs.readFileSync(path.join(this.avcPath, 'avc.json'), 'utf8'));
+      if (avcConfig.settings?.testCommand) {
+        testCmd = avcConfig.settings.testCommand;
+      }
+    } catch {}
+
+    // Check if package.json exists in worktree
+    const pkgPath = path.join(this.worktreePath, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      this.debug('No package.json in worktree — skipping tests');
+      return { passed: true, summary: 'No test configuration found — skipped' };
+    }
+
+    try {
+      const output = execSync(testCmd, {
+        cwd: this.worktreePath,
+        encoding: 'utf8',
+        timeout: 5 * 60_000, // 5 min timeout
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      this.debug('Tests passed', { output: output.slice(-500) });
+      return { passed: true, summary: 'All tests passed' };
+    } catch (err) {
+      const output = (err.stdout || '') + (err.stderr || '');
+      this.debug('Tests failed', { output: output.slice(-1000) });
+      return { passed: false, summary: output.slice(-500) };
+    }
+  }
+
+  /**
+   * Commit changes in the worktree and merge to the main branch.
+   */
+  commitAndMerge() {
+    // Stage all changes
+    git(['add', '-A'], this.worktreePath);
+
+    // Check if there's anything to commit
+    const status = git(['status', '--porcelain'], this.worktreePath);
+    if (!status) {
+      this.debug('No changes to commit');
+      return;
+    }
+
+    // Commit
+    const commitMsg = `feat(${this.taskId}): implement task\n\nGenerated by AVC WorktreeRunner`;
+    git(['commit', '-m', commitMsg], this.worktreePath);
+    this.debug('Committed in worktree');
+
+    // Determine the main branch name
+    let mainBranch = 'main';
+    try {
+      mainBranch = git(['symbolic-ref', '--short', 'HEAD'], this.projectRoot);
+    } catch {
+      // If HEAD is detached, try common branch names
+      try { git(['rev-parse', '--verify', 'main'], this.projectRoot); mainBranch = 'main'; } catch {
+        try { git(['rev-parse', '--verify', 'master'], this.projectRoot); mainBranch = 'master'; } catch {}
+      }
+    }
+
+    // Merge into main
+    try {
+      git(['merge', '--no-ff', this.branchName, '-m', `Merge ${this.branchName}: implement ${this.taskId}`], this.projectRoot);
+      this.debug('Merged to main', { mainBranch });
+    } catch (err) {
+      // Merge conflict — abort and report
+      try { git(['merge', '--abort'], this.projectRoot); } catch {}
+      throw new Error(`Merge conflict: ${err.message}`);
+    }
+  }
+
+  /**
+   * Clean up the worktree and branch.
+   */
+  cleanup() {
+    try {
+      if (fs.existsSync(this.worktreePath)) {
+        git(['worktree', 'remove', '--force', this.worktreePath], this.projectRoot);
+      }
+    } catch (err) {
+      this.debug('Worktree removal warning', { error: err.message });
+      // Force remove the directory if git worktree remove fails
+      try { fs.rmSync(this.worktreePath, { recursive: true, force: true }); } catch {}
+    }
+
+    try {
+      git(['branch', '-D', this.branchName], this.projectRoot);
+    } catch {
+      // Branch may not exist
+    }
+
+    this.debug('Cleanup complete');
+  }
+
+  _readIfExists(filePath) {
+    try {
+      return fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return null;
+    }
+  }
+}