@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/worktrees.cjs

@@ -0,0 +1,790 @@
+/**
+ * Worktrees -- git worktree lifecycle management
+ *
+ * Create, remove, list, setup, and prune worktrees for code repos.
+ * State tracked in config.local.json under projects.{project}.worktrees.
+ *
+ * Worktree paths are siblings to main checkout:
+ *   {repoParent}/{repoName}--{projectSlug}-{slug}
+ *
+ * Branch naming:
+ *   milestone/{slug}  or  quick/{slug}
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+const { execGit, output, error, loadConfig } = require('./core.cjs');
+const { getLocalConfigPath } = require('./config.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { parseReposMd } = require('./repos.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Read config.local.json safely.
+ * @param {string} cwd
+ * @returns {object}
+ */
+function _readLocalConfig(cwd) {
+  const localPath = getLocalConfigPath(cwd);
+  try {
+    if (fs.existsSync(localPath)) {
+      return JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+    }
+  } catch { /* ignore */ }
+  return {};
+}
+
+/**
+ * Write config.local.json atomically.
+ * @param {string} cwd
+ * @param {object} data
+ */
+function _writeLocalConfig(cwd, data) {
+  const localPath = getLocalConfigPath(cwd);
+  const dir = path.dirname(localPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = localPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmpPath, localPath);
+}
+
+/**
+ * Get worktree state for a slug.
+ * @param {string} cwd
+ * @param {string} project
+ * @param {string} slug
+ * @returns {object|null}
+ */
+function _getWorktreeState(cwd, project, slug) {
+  const data = _readLocalConfig(cwd);
+  return (data.projects && data.projects[project]
+    && data.projects[project].worktrees
+    && data.projects[project].worktrees[slug]) || null;
+}
+
+/**
+ * Set worktree state for a slug.
+ * @param {string} cwd
+ * @param {string} project
+ * @param {string} slug
+ * @param {object} entry - { type, mode, setup_complete, repos: { repoName: absPath } }
+ */
+function _setWorktreeState(cwd, project, slug, entry) {
+  const data = _readLocalConfig(cwd);
+  if (!data.projects) data.projects = {};
+  if (!data.projects[project]) data.projects[project] = {};
+  if (!data.projects[project].worktrees) data.projects[project].worktrees = {};
+
+  // Merge repos into existing entry if present (multi-repo iterative creation)
+  const existing = data.projects[project].worktrees[slug];
+  if (existing && existing.repos && entry.repos) {
+    entry.repos = { ...existing.repos, ...entry.repos };
+  }
+
+  data.projects[project].worktrees[slug] = entry;
+  _writeLocalConfig(cwd, data);
+}
+
+/**
+ * Remove worktree state for a slug.
+ * @param {string} cwd
+ * @param {string} project
+ * @param {string} slug
+ */
+function _removeWorktreeState(cwd, project, slug) {
+  const data = _readLocalConfig(cwd);
+  if (data.projects && data.projects[project]
+    && data.projects[project].worktrees
+    && data.projects[project].worktrees[slug]) {
+    delete data.projects[project].worktrees[slug];
+    _writeLocalConfig(cwd, data);
+  }
+}
+
+/**
+ * Build worktree path as sibling to main checkout.
+ * Format: {repoParent}/{repoBaseName}--{projectSlug}-{slug}
+ * @param {string} repoAbsPath - Absolute path to the repo's main checkout
+ * @param {string} projectSlug
+ * @param {string} slug
+ * @returns {string}
+ */
+function _buildWorktreePath(repoAbsPath, projectSlug, slug) {
+  return path.join(
+    path.dirname(repoAbsPath),
+    path.basename(repoAbsPath) + '--' + projectSlug + '-' + slug
+  );
+}
+
+/**
+ * Build branch name from type and slug.
+ * @param {string} type - 'milestone' or 'quick'
+ * @param {string} slug
+ * @returns {string}
+ */
+function _buildBranchName(type, slug) {
+  if (type === 'milestone') return 'milestone/' + slug;
+  if (type === 'quick') return 'quick/' + slug;
+  return slug;
+}
+
+/**
+ * Sanitize a string into a valid slug.
+ * @param {string} input
+ * @returns {string}
+ */
+function _sanitizeSlug(input) {
+  if (!input) return '';
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50)
+    .replace(/-+$/, '');
+}
+
+/**
+ * Detect collision and disambiguate path if needed.
+ * @param {string} targetPath
+ * @param {string} slug
+ * @returns {string}
+ */
+function _detectCollision(targetPath, slug) {
+  if (!fs.existsSync(targetPath)) return targetPath;
+  // Append first 4 chars of a hash for disambiguation
+  const hash = crypto.createHash('sha256')
+    .update(slug + '-' + Date.now())
+    .digest('hex')
+    .slice(0, 4);
+  return targetPath + '-' + hash;
+}
+
+/**
+ * Resolve a relative repo path from REPOS.md to an absolute path.
+ * @param {string} cwd
+ * @param {string} repoRelPath
+ * @returns {string}
+ */
+function _resolveRepoAbsPath(cwd, repoRelPath) {
+  const root = getPlanningRoot(cwd);
+  return path.resolve(root, repoRelPath);
+}
+
+/**
+ * Execute setup command in worktree directory.
+ * Setup script receives: $1=slug, $2=worktree_path (absolute).
+ * cwd is set to the worktree directory.
+ * @param {string} worktreePath - Absolute path to the worktree directory
+ * @param {string} setupCmd - Setup command from REPOS.md
+ * @param {string} slug - Worktree slug
+ * @returns {{ success: boolean, skipped: boolean, error?: string, stderr?: string }}
+ */
+function _runSetupCommand(worktreePath, setupCmd, slug) {
+  if (!setupCmd) return { success: true, skipped: true };
+  try {
+    const cmd = setupCmd + ' ' + slug + ' "' + worktreePath + '"';
+    execSync(cmd, {
+      cwd: worktreePath,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+      timeout: 300000, // 5 minutes
+    });
+    return { success: true, skipped: false };
+  } catch (err) {
+    return {
+      success: false,
+      skipped: false,
+      error: err.message || String(err),
+      stderr: err.stderr || '',
+    };
+  }
+}
+
+/**
+ * Find the main checkout path for a repo given its worktree path and branch.
+ * Derives from the worktree naming convention.
+ * @param {string} cwd
+ * @param {string} repoName
+ * @returns {string|null}
+ */
+function _findMainCheckoutPath(cwd, repoName) {
+  const parsed = parseReposMd(cwd);
+  if (!parsed || !parsed.repos) return null;
+  const repo = parsed.repos.find(function(r) { return r.name === repoName; });
+  if (!repo || !repo.path) return null;
+  return _resolveRepoAbsPath(cwd, repo.path);
+}
+
+/**
+ * Read active milestone version from projects/{project}/STATE.md frontmatter.
+ * Returns null on any failure — callers must not throw.
+ * @param {string} cwd
+ * @param {string} project
+ * @returns {string|null}
+ */
+function _readMilestoneVersion(cwd, project) {
+  try {
+    const statePath = path.join(cwd, 'projects', project, 'STATE.md');
+    if (!fs.existsSync(statePath)) return null;
+    const content = fs.readFileSync(statePath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    const v = fm && fm.milestone;
+    if (typeof v === 'string' && /^v\d+(\.\d+)?$/.test(v)) return v;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Exported command functions ───────────────────────────────────────────────
+
+/**
+ * Create worktrees for a project's repos.
+ * @param {string} cwd
+ * @param {string[]} args - [slug, --type milestone|quick, --mode full|debug|null, --repo name]
+ */
+function cmdWorktreesCreate(cwd, args) {
+  // Parse args
+  const slug = _sanitizeSlug(args[0]);
+  if (!slug) error('Usage: worktrees create <slug> --type milestone|quick');
+
+  const typeIdx = args.indexOf('--type');
+  const type = typeIdx !== -1 ? args[typeIdx + 1] : null;
+  if (!type || (type !== 'milestone' && type !== 'quick')) {
+    error('--type must be "milestone" or "quick"');
+  }
+
+  const modeIdx = args.indexOf('--mode');
+  const mode = modeIdx !== -1 ? args[modeIdx + 1] : null;
+
+  const repoIdx = args.indexOf('--repo');
+  const repoFilter = repoIdx !== -1 ? args[repoIdx + 1] : null;
+
+  // Load config
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) error('No current project set. Use dgs-tools projects switch <name>');
+
+  const baseBranch = config.base_branch || 'main';
+
+  // Parse REPOS.md
+  const parsed = parseReposMd(cwd);
+  if (!parsed || !parsed.repos || parsed.repos.length === 0) {
+    error('No repos found in REPOS.md');
+  }
+
+  let repos = parsed.repos;
+  if (repoFilter) {
+    repos = repos.filter(function(r) { return r.name === repoFilter; });
+    if (repos.length === 0) error('Repo "' + repoFilter + '" not found in REPOS.md');
+  }
+
+  const createdRepos = {};
+
+  for (const repo of repos) {
+    const repoAbsPath = _resolveRepoAbsPath(cwd, repo.path);
+    let worktreePath = _buildWorktreePath(repoAbsPath, project, slug);
+    worktreePath = _detectCollision(worktreePath, slug);
+    const branchName = _buildBranchName(type, slug);
+
+    // Check existing state
+    const existingState = _getWorktreeState(cwd, project, slug);
+    if (existingState && existingState.repos && existingState.repos[repo.name]
+      && fs.existsSync(existingState.repos[repo.name])) {
+      process.stderr.write('Worktree for ' + repo.name + ' already exists at ' + existingState.repos[repo.name] + ', skipping.\n');
+      createdRepos[repo.name] = existingState.repos[repo.name];
+      continue;
+    }
+
+    // Verify main checkout is on base branch
+    const headResult = execGit(repoAbsPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    if (headResult.exitCode !== 0) {
+      error('Cannot determine branch for ' + repo.name + ': ' + headResult.stderr);
+    }
+    if (headResult.stdout !== baseBranch) {
+      error('Main checkout of ' + repo.name + ' is not on ' + baseBranch + ' (currently on ' + headResult.stdout + '). Cannot create worktree.');
+    }
+
+    // Check if branch already exists and is checked out elsewhere
+    const worktreeListResult = execGit(repoAbsPath, ['worktree', 'list', '--porcelain']);
+    if (worktreeListResult.exitCode === 0 && worktreeListResult.stdout.includes(branchName)) {
+      // Try pruning stale worktrees first
+      execGit(repoAbsPath, ['worktree', 'prune']);
+    }
+
+    // Create worktree
+    const createResult = execGit(repoAbsPath, ['worktree', 'add', '-b', branchName, worktreePath, baseBranch]);
+    if (createResult.exitCode !== 0) {
+      // Branch might already exist (e.g., from a previous partial creation)
+      // Try without -b (checkout existing branch)
+      const retryResult = execGit(repoAbsPath, ['worktree', 'add', worktreePath, branchName]);
+      if (retryResult.exitCode !== 0) {
+        error('Failed to create worktree for ' + repo.name + ': ' + createResult.stderr + ' | Retry: ' + retryResult.stderr);
+      }
+    }
+
+    // Run setup
+    const setupResult = _runSetupCommand(worktreePath, repo.setup, slug);
+    const setupComplete = setupResult.success;
+
+    if (!setupResult.success && !setupResult.skipped) {
+      process.stderr.write('Warning: Setup failed for ' + repo.name + ': ' + (setupResult.error || '') + '\n');
+      process.stderr.write('Re-run setup: dgs-tools worktrees setup ' + slug + '\n');
+    }
+
+    // Write state. milestone_version is captured from STATE.md frontmatter at
+    // creation time for milestone-type worktrees; quick worktrees and
+    // unresolvable STATE reads degrade cleanly to null.
+    const milestoneVersion = type === 'milestone' ? _readMilestoneVersion(cwd, project) : null;
+    _setWorktreeState(cwd, project, slug, {
+      type: type,
+      mode: mode,
+      setup_complete: setupComplete,
+      milestone_version: milestoneVersion,
+      repos: { [repo.name]: worktreePath },
+    });
+
+    createdRepos[repo.name] = worktreePath;
+  }
+
+  output({ created: true, slug: slug, type: type, repos: createdRepos });
+}
+
+/**
+ * Remove a worktree.
+ * @param {string} cwd
+ * @param {string[]} args - [slug]
+ */
+function cmdWorktreesRemove(cwd, args) {
+  const slug = args[0];
+  if (!slug) error('Usage: worktrees remove <slug>');
+
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) error('No current project set');
+
+  const state = _getWorktreeState(cwd, project, slug);
+  if (!state) error('No worktree tracked for slug \'' + slug + '\'');
+
+  const branchName = _buildBranchName(state.type || 'milestone', slug);
+
+  for (const repoName of Object.keys(state.repos)) {
+    const worktreePath = state.repos[repoName];
+    const mainCheckout = _findMainCheckoutPath(cwd, repoName);
+
+    if (!mainCheckout) {
+      process.stderr.write('Warning: Cannot find main checkout for ' + repoName + ', skipping git cleanup.\n');
+      // Still try to remove directory
+      if (fs.existsSync(worktreePath)) {
+        fs.rmSync(worktreePath, { recursive: true, force: true });
+      }
+      continue;
+    }
+
+    // Remove worktree via git
+    const removeResult = execGit(mainCheckout, ['worktree', 'remove', worktreePath]);
+    if (removeResult.exitCode !== 0) {
+      // Directory already gone or other issue — try prune
+      execGit(mainCheckout, ['worktree', 'prune']);
+      // Force remove directory if still exists
+      if (fs.existsSync(worktreePath)) {
+        fs.rmSync(worktreePath, { recursive: true, force: true });
+        execGit(mainCheckout, ['worktree', 'prune']);
+      }
+    }
+
+    // Delete branch (try -d first, then -D)
+    const delResult = execGit(mainCheckout, ['branch', '-d', branchName]);
+    if (delResult.exitCode !== 0) {
+      execGit(mainCheckout, ['branch', '-D', branchName]);
+    }
+  }
+
+  // Remove from config
+  _removeWorktreeState(cwd, project, slug);
+
+  // Clear active_context if it points to this slug
+  const localData = _readLocalConfig(cwd);
+  if (localData.execution && localData.execution.active_context === slug) {
+    localData.execution.active_context = null;
+    _writeLocalConfig(cwd, localData);
+  }
+
+  output({ removed: true, slug: slug });
+}
+
+/**
+ * List tracked worktrees.
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function cmdWorktreesList(cwd, args) {
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) error('No current project set');
+
+  const data = _readLocalConfig(cwd);
+  const worktrees = (data.projects && data.projects[project]
+    && data.projects[project].worktrees) || {};
+
+  const result = [];
+  for (const slug of Object.keys(worktrees)) {
+    const entry = worktrees[slug];
+    const repoStatus = {};
+    let stale = false;
+
+    if (entry.repos) {
+      for (const repoName of Object.keys(entry.repos)) {
+        const repoPath = entry.repos[repoName];
+        const exists = fs.existsSync(repoPath);
+        if (!exists) stale = true;
+        repoStatus[repoName] = { path: repoPath, exists: exists };
+      }
+    }
+
+    result.push({
+      slug: slug,
+      type: entry.type || 'milestone',
+      mode: entry.mode || null,
+      setup_complete: entry.setup_complete || false,
+      repos: repoStatus,
+      stale: stale,
+    });
+  }
+
+  output(result);
+}
+
+/**
+ * Re-run setup for a worktree.
+ * @param {string} cwd
+ * @param {string[]} args - [slug]
+ */
+function cmdWorktreesSetup(cwd, args) {
+  const slug = args[0];
+  if (!slug) error('Usage: worktrees setup <slug>');
+
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) error('No current project set');
+
+  const state = _getWorktreeState(cwd, project, slug);
+  if (!state) error('No worktree tracked for slug \'' + slug + '\'');
+
+  const parsed = parseReposMd(cwd);
+  if (!parsed || !parsed.repos) error('Cannot parse REPOS.md');
+
+  const results = {};
+  let allSuccess = true;
+
+  for (const repoName of Object.keys(state.repos)) {
+    const worktreePath = state.repos[repoName];
+    const repoEntry = parsed.repos.find(function(r) { return r.name === repoName; });
+
+    if (!repoEntry) {
+      results[repoName] = 'skipped';
+      continue;
+    }
+
+    if (!repoEntry.setup) {
+      results[repoName] = 'no_setup_command';
+      continue;
+    }
+
+    const setupResult = _runSetupCommand(worktreePath, repoEntry.setup, slug);
+    results[repoName] = setupResult.success ? 'success' : 'failed';
+    if (!setupResult.success) {
+      allSuccess = false;
+      process.stderr.write('Setup failed for ' + repoName + ': ' + (setupResult.error || '') + '\n');
+    }
+  }
+
+  // Update setup_complete flag
+  _setWorktreeState(cwd, project, slug, {
+    ...state,
+    setup_complete: allSuccess,
+  });
+
+  output({ setup_complete: allSuccess, slug: slug, results: results });
+}
+
+/**
+ * Prune orphaned worktree entries.
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function cmdWorktreesPrune(cwd, args) {
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) error('No current project set');
+
+  const data = _readLocalConfig(cwd);
+  const worktrees = (data.projects && data.projects[project]
+    && data.projects[project].worktrees) || {};
+
+  const pruned = [];
+
+  for (const slug of Object.keys(worktrees)) {
+    const entry = worktrees[slug];
+    if (!entry.repos) continue;
+
+    // Check if ALL repo directories are missing
+    const allMissing = Object.keys(entry.repos).every(function(repoName) {
+      return !fs.existsSync(entry.repos[repoName]);
+    });
+
+    if (!allMissing) continue;
+
+    const branchName = _buildBranchName(entry.type || 'milestone', slug);
+
+    // Clean up git metadata and branches
+    for (const repoName of Object.keys(entry.repos)) {
+      const mainCheckout = _findMainCheckoutPath(cwd, repoName);
+      if (mainCheckout) {
+        execGit(mainCheckout, ['worktree', 'prune']);
+        execGit(mainCheckout, ['branch', '-D', branchName]);
+      }
+    }
+
+    // Remove config entry
+    delete worktrees[slug];
+    pruned.push(slug);
+  }
+
+  if (pruned.length > 0) {
+    _writeLocalConfig(cwd, data);
+
+    // Clear active_context if it points to a pruned slug
+    const freshData = _readLocalConfig(cwd);
+    if (freshData.execution && pruned.includes(freshData.execution.active_context)) {
+      freshData.execution.active_context = null;
+      _writeLocalConfig(cwd, freshData);
+    }
+  }
+
+  output({ pruned: pruned, count: pruned.length });
+}
+
+// ─── Shared functions ─────────────────────────────────────────────────────────
+
+/**
+ * Rebase a worktree branch onto base_branch and fast-forward merge.
+ * Used by complete-milestone and complete-quick for clean rebase-before-merge completion.
+ *
+ * Steps:
+ * 1. Pull base_branch in main checkout (fetch + pull)
+ * 2. Check if rebase is needed (idempotent -- skip if already rebased)
+ * 3. Rebase worktree branch onto base_branch in worktree directory
+ * 4. On conflict: git rebase --abort, return error with manual instructions
+ * 5. Fast-forward merge to base_branch in main checkout
+ * 6. Push to remote (always -- not gated by sync config)
+ *
+ * @param {string} cwd - Planning root for config resolution
+ * @param {string} repoName - Repo name from REPOS.md
+ * @param {string} slug - Worktree slug (e.g., 'v19-0')
+ * @param {object} [options] - { push: true }
+ * @returns {{ success: boolean, merged: boolean, skipped: boolean, conflicted: boolean, pushed: boolean, error?: string, manualInstructions?: string }}
+ */
+function rebaseAndMerge(cwd, repoName, slug, options) {
+  options = options || {};
+  const shouldPush = options.push !== false; // default true
+
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  const baseBranch = config.base_branch || 'main';
+
+  if (!project) return { success: false, merged: false, skipped: false, conflicted: false, pushed: false, error: 'No current project set' };
+
+  const state = _getWorktreeState(cwd, project, slug);
+  if (!state) return { success: false, merged: false, skipped: false, conflicted: false, pushed: false, error: 'No worktree tracked for slug \'' + slug + '\'' };
+
+  const worktreePath = state.repos && state.repos[repoName];
+  if (!worktreePath) return { success: false, merged: false, skipped: false, conflicted: false, pushed: false, error: 'Repo \'' + repoName + '\' not in worktree \'' + slug + '\'' };
+
+  const mainCheckout = _findMainCheckoutPath(cwd, repoName);
+  if (!mainCheckout) return { success: false, merged: false, skipped: false, conflicted: false, pushed: false, error: 'Cannot find main checkout for \'' + repoName + '\'' };
+
+  const branchName = _buildBranchName(state.type || 'milestone', slug);
+
+  // Step 1: Pull base_branch in main checkout
+  const fetchResult = execGit(mainCheckout, ['fetch', 'origin']);
+  if (fetchResult.exitCode !== 0) {
+    process.stderr.write('Warning: fetch failed: ' + fetchResult.stderr + '\n');
+    // Continue anyway -- local base_branch may still be usable
+  }
+
+  // Ensure main checkout is on base_branch before pulling
+  const mainHead = execGit(mainCheckout, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (mainHead.exitCode === 0 && mainHead.stdout.trim() === baseBranch) {
+    const pullResult = execGit(mainCheckout, ['pull', 'origin', baseBranch]);
+    if (pullResult.exitCode !== 0) {
+      process.stderr.write('Warning: pull failed: ' + pullResult.stderr + '\n');
+      // Continue anyway
+    }
+  }
+
+  // Step 2: Check if rebase is already done (idempotent re-run)
+  // If the milestone branch's merge-base with base_branch equals base_branch tip,
+  // the branch is already rebased onto base_branch.
+  const baseTip = execGit(mainCheckout, ['rev-parse', baseBranch]);
+  const mergeBase = execGit(mainCheckout, ['merge-base', baseBranch, branchName]);
+  let rebaseSkipped = false;
+  if (baseTip.exitCode === 0 && mergeBase.exitCode === 0
+    && baseTip.stdout.trim() === mergeBase.stdout.trim()) {
+    // Already rebased -- skip to merge
+    process.stderr.write('Branch ' + branchName + ' already rebased onto ' + baseBranch + '. Skipping rebase.\n');
+    rebaseSkipped = true;
+  } else {
+    // Step 3: Rebase worktree branch onto base_branch
+    // First ensure worktree is on the correct branch
+    const headCheck = execGit(worktreePath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    if (headCheck.exitCode !== 0 || headCheck.stdout.trim() !== branchName) {
+      return {
+        success: false,
+        merged: false,
+        skipped: false,
+        conflicted: false,
+        pushed: false,
+        error: 'Worktree is not on expected branch ' + branchName + ' (on ' + (headCheck.stdout || 'unknown').trim() + ')',
+      };
+    }
+
+    const rebaseResult = execGit(worktreePath, ['rebase', baseBranch]);
+    if (rebaseResult.exitCode !== 0) {
+      // Rebase failed -- abort cleanly
+      execGit(worktreePath, ['rebase', '--abort']);
+
+      const instructions = [
+        'Rebase conflict in ' + repoName + '. Manual resolution required:',
+        '',
+        '  cd ' + worktreePath,
+        '  git rebase ' + baseBranch,
+        '  # Resolve conflicts in each file',
+        '  git add <resolved-files>',
+        '  git rebase --continue',
+        '  # Repeat for each conflicting commit',
+        '',
+        'Then re-run: /dgs:complete-milestone',
+      ].join('\n');
+
+      return {
+        success: false,
+        merged: false,
+        skipped: false,
+        conflicted: true,
+        pushed: false,
+        error: 'Rebase conflict in ' + repoName,
+        manualInstructions: instructions,
+      };
+    }
+  }
+
+  // Step 4: Fast-forward merge to base_branch in main checkout
+  // Ensure main checkout is on base_branch
+  const checkoutBase = execGit(mainCheckout, ['checkout', baseBranch]);
+  if (checkoutBase.exitCode !== 0) {
+    return {
+      success: false,
+      merged: false,
+      skipped: rebaseSkipped,
+      conflicted: false,
+      pushed: false,
+      error: 'Failed to checkout ' + baseBranch + ' in main checkout: ' + checkoutBase.stderr,
+    };
+  }
+
+  const mergeResult = execGit(mainCheckout, ['merge', '--ff-only', branchName]);
+  if (mergeResult.exitCode !== 0) {
+    return {
+      success: false,
+      merged: false,
+      skipped: rebaseSkipped,
+      conflicted: false,
+      pushed: false,
+      error: 'Fast-forward merge failed: ' + mergeResult.stderr,
+    };
+  }
+
+  // Step 5: Push to remote (always -- milestone completion is a definitive push point)
+  let pushed = false;
+  if (shouldPush) {
+    const pushResult = execGit(mainCheckout, ['push', 'origin', baseBranch]);
+    pushed = pushResult.exitCode === 0;
+    if (!pushed) {
+      process.stderr.write('Warning: push failed: ' + pushResult.stderr + '\n');
+    }
+  }
+
+  return {
+    success: true,
+    merged: true,
+    skipped: rebaseSkipped,
+    conflicted: false,
+    pushed: pushed,
+  };
+}
+
+/**
+ * Verify worktree health before execution.
+ * Checks: correct branch checked out, no uncommitted changes.
+ *
+ * @param {string} cwd - Planning root
+ * @param {string} slug - Worktree slug
+ * @returns {{ healthy: boolean, issues: string[] }}
+ */
+function checkWorktreeHealth(cwd, slug) {
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) return { healthy: false, issues: ['No current project set'] };
+
+  const state = _getWorktreeState(cwd, project, slug);
+  if (!state) return { healthy: false, issues: ['No worktree tracked for slug \'' + slug + '\''] };
+
+  const branchName = _buildBranchName(state.type || 'milestone', slug);
+  const issues = [];
+
+  for (const repoName of Object.keys(state.repos || {})) {
+    const worktreePath = state.repos[repoName];
+
+    // Check directory exists
+    if (!fs.existsSync(worktreePath)) {
+      issues.push(repoName + ': worktree directory missing at ' + worktreePath);
+      continue;
+    }
+
+    // Check correct branch
+    const headResult = execGit(worktreePath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    if (headResult.exitCode !== 0) {
+      issues.push(repoName + ': cannot determine branch');
+    } else if (headResult.stdout.trim() !== branchName) {
+      issues.push(repoName + ': expected branch ' + branchName + ' but on ' + headResult.stdout.trim());
+    }
+
+    // Check no uncommitted changes
+    const statusResult = execGit(worktreePath, ['status', '--porcelain']);
+    if (statusResult.exitCode === 0 && statusResult.stdout.trim()) {
+      issues.push(repoName + ': has uncommitted changes');
+    }
+  }
+
+  return { healthy: issues.length === 0, issues: issues };
+}
+
+module.exports = {
+  cmdWorktreesCreate,
+  cmdWorktreesRemove,
+  cmdWorktreesList,
+  cmdWorktreesSetup,
+  cmdWorktreesPrune,
+  rebaseAndMerge,
+  checkWorktreeHealth,
+};