@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,705 @@
+/**
+ * Execution — Multi-repo execution engine: preflight checks, per-repo commits,
+ *              planning commit body, change detection
+ *
+ * This module owns all multi-repo execution concerns. It coordinates
+ * git operations across multiple repos for plan execution.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execGit, safeReadFile, loadConfig, output, error } = require('./core.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { parseReposMd } = require('./repos.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { scanProjectReposTags } = require('./projects.cjs');
+
+// ─── Repo Path Resolution ───────────────────────────────────────────────────
+
+/**
+ * Resolve a repo name to its absolute path using REPOS.md.
+ *
+ * @param {string} cwd - Product root
+ * @param {string} repoName - Repo name to resolve
+ * @param {Array} repos - Parsed repos array (optional, loads from REPOS.md if not provided)
+ * @returns {{ absPath: string, repo: Object } | null}
+ */
+function resolveRepoPath(cwd, repoName, repos) {
+  if (!repos) {
+    const parsed = parseReposMd(cwd);
+    if (!parsed) return null;
+    repos = parsed.repos;
+  }
+  const repo = repos.find(r => r.name === repoName);
+  if (!repo) return null;
+  const absPath = path.resolve(cwd, repo.path);
+  return { absPath, repo };
+}
+
+/**
+ * Resolve a repo-relative file path to its absolute path.
+ *
+ * Given a repo name and a path relative to that repo's root (e.g., 'src/index.ts'),
+ * resolves to the absolute file path on disk using REPOS.md lookup.
+ *
+ * @param {string} cwd - Product root
+ * @param {string} repoName - Repo name to look up
+ * @param {string} relativePath - File path relative to repo root (e.g., 'src/index.ts')
+ * @param {Array} repos - Parsed repos array (optional, loads from REPOS.md if not provided)
+ * @returns {{ absFilePath: string, repoAbsPath: string, repo: Object } | null}
+ */
+function resolveRepoRelativePath(cwd, repoName, relativePath, repos) {
+  const resolved = resolveRepoPath(cwd, repoName, repos);
+  if (!resolved) return null;
+  const absFilePath = path.join(resolved.absPath, relativePath);
+  return { absFilePath, repoAbsPath: resolved.absPath, repo: resolved.repo };
+}
+
+// ─── Pre-flight Check ───────────────────────────────────────────────────────
+
+/**
+ * Pre-flight check: detect dirty repos, partial executions, and missing repos.
+ *
+ * @param {string} cwd - Product root
+ * @param {string[]} repoNames - Repo names to check
+ * @param {string} [phaseDir] - Optional phase directory to check for partial SUMMARY.md
+ * @returns {{ passed: boolean, dirty_repos: Array, partial_execution: Object|null, missing_repos: string[] }}
+ */
+function preflightCheck(cwd, repoNames, phaseDir) {
+  const parsed = parseReposMd(cwd);
+  const repos = parsed ? parsed.repos : [];
+  const dirty_repos = [];
+  const missing_repos = [];
+
+  for (const name of repoNames) {
+    const resolved = resolveRepoPath(cwd, name, repos);
+    if (!resolved) {
+      missing_repos.push(name);
+      continue;
+    }
+
+    if (!fs.existsSync(resolved.absPath)) {
+      missing_repos.push(name);
+      continue;
+    }
+
+    const status = execGit(resolved.absPath, ['status', '--porcelain']);
+    if (status.exitCode === 0 && status.stdout.trim()) {
+      // Filter out untracked-only lines (starting with ??)
+      const tracked = status.stdout.split('\n').filter(l => l && !l.startsWith('??'));
+      if (tracked.length > 0) {
+        dirty_repos.push({ name, files: tracked });
+      }
+    }
+  }
+
+  // Check for partial execution in SUMMARY.md files
+  let partial_execution = null;
+  if (phaseDir) {
+    const dir = path.isAbsolute(phaseDir) ? phaseDir : path.join(cwd, phaseDir);
+    try {
+      const files = fs.readdirSync(dir).filter(f => f.endsWith('-SUMMARY.md'));
+      for (const file of files) {
+        const content = safeReadFile(path.join(dir, file));
+        if (!content) continue;
+        const fm = extractFrontmatter(content);
+        if (fm.status === 'partial') {
+          partial_execution = { file, status: 'partial' };
+          break;
+        }
+      }
+    } catch {}
+  }
+
+  const passed = dirty_repos.length === 0 && missing_repos.length === 0 && partial_execution === null;
+  return { passed, dirty_repos, partial_execution, missing_repos };
+}
+
+// ─── Per-Repo Commit ────────────────────────────────────────────────────────
+
+/**
+ * Stage and commit specific files in a single repo.
+ * Internal helper used by both commitPerRepo and retryCommitPerRepo.
+ *
+ * @param {string} absPath - Absolute path to the repo
+ * @param {string[]} files - Files to stage (relative to repo root)
+ * @param {string} commitMsg - Commit message
+ * @returns {{ status: string, sha: string|null, error?: string }}
+ */
+function _commitSingleRepo(absPath, files, commitMsg) {
+  try {
+    // Stage each file specifically (never git add .)
+    for (const file of files) {
+      execGit(absPath, ['add', file]);
+    }
+
+    // Check if there's anything staged
+    const staged = execGit(absPath, ['diff', '--cached', '--name-only']);
+    if (staged.exitCode !== 0 || !staged.stdout.trim()) {
+      return { status: 'failed', sha: null, error: 'Nothing to commit after staging' };
+    }
+
+    // Commit
+    const commitResult = execGit(absPath, ['commit', '-m', commitMsg]);
+
+    if (commitResult.exitCode === 0) {
+      const shaResult = execGit(absPath, ['rev-parse', '--short', 'HEAD']);
+      return { status: 'complete', sha: shaResult.stdout.trim() };
+    } else {
+      return { status: 'failed', sha: null, error: commitResult.stderr };
+    }
+  } catch (err) {
+    return { status: 'failed', sha: null, error: err.message };
+  }
+}
+
+/**
+ * Commit changes in each repo separately with project-prefixed messages.
+ *
+ * @param {string} cwd - Product root
+ * @param {Array<{repoName: string, repoPath: string, files: string[]}>} repoChanges
+ * @param {{ type: string, project: string, phase: string, plan: string, description: string }} options
+ * @returns {Array<{repo: string, status: string, sha: string|null, error?: string}>}
+ */
+function commitPerRepo(cwd, repoChanges, options) {
+  const results = [];
+
+  // Sort by repoName alphabetically
+  const sorted = [...repoChanges].sort((a, b) => a.repoName.localeCompare(b.repoName));
+
+  for (const { repoName, repoPath, files } of sorted) {
+    const absPath = path.resolve(cwd, repoPath);
+    const msg = `${options.type}(${options.project}/${options.phase}-${options.plan}): ${options.description}`;
+    const result = _commitSingleRepo(absPath, files, msg);
+    results.push({ repo: repoName, ...result });
+  }
+
+  return results;
+}
+
+/**
+ * Retry commit for repos that failed in a prior run.
+ * Skips repos that already committed successfully (verified SHA),
+ * retries repos that failed or have stale SHAs.
+ *
+ * @param {string} cwd - Product root
+ * @param {Array<{repoName: string, repoPath: string, files: string[]}>} repoChanges
+ * @param {{ type: string, project: string, phase: string, plan: string, description: string }} options
+ * @param {Array<{repo: string, status: string, sha: string|null, error?: string}>} priorResults
+ * @returns {Array<{repo: string, status: string, sha: string|null, error?: string}>}
+ */
+function retryCommitPerRepo(cwd, repoChanges, options, priorResults) {
+  const results = [];
+  const priorMap = new Map();
+  if (priorResults && priorResults.length > 0) {
+    for (const pr of priorResults) {
+      priorMap.set(pr.repo, pr);
+    }
+  }
+
+  // Sort by repoName alphabetically
+  const sorted = [...repoChanges].sort((a, b) => a.repoName.localeCompare(b.repoName));
+
+  for (const { repoName, repoPath, files } of sorted) {
+    const absPath = path.resolve(cwd, repoPath);
+    const prior = priorMap.get(repoName);
+
+    // If prior result was complete with a SHA, verify it still exists
+    if (prior && prior.status === 'complete' && prior.sha) {
+      const verify = execGit(absPath, ['rev-parse', '--verify', prior.sha]);
+      if (verify.exitCode === 0) {
+        // SHA still exists — skip this repo, carry forward prior result
+        results.push({ repo: repoName, status: 'complete', sha: prior.sha });
+        continue;
+      }
+      // SHA no longer exists (rebased/force-pushed) — retry
+    }
+
+    // No prior, prior was failed, or prior SHA is stale — commit normally
+    const msg = `${options.type}(${options.project}/${options.phase}-${options.plan}): ${options.description}`;
+    const result = _commitSingleRepo(absPath, files, msg);
+    results.push({ repo: repoName, ...result });
+  }
+
+  return results;
+}
+
+// ─── Manual Resolution Detection ────────────────────────────────────────────
+
+/**
+ * Detect if a repo's expected changes have been manually resolved.
+ * Checks working tree cleanliness and file existence to determine
+ * if a user manually fixed and committed changes outside of DGS.
+ *
+ * @param {string} cwd - Product root
+ * @param {string} repoName - Repo name
+ * @param {string[]} expectedFiles - Files expected to be committed
+ * @param {string} [priorSha] - SHA from a prior DGS commit attempt
+ * @returns {{ resolved: boolean, reason: string }}
+ */
+function detectManualResolution(cwd, repoName, expectedFiles, priorSha) {
+  const resolved = resolveRepoPath(cwd, repoName);
+  if (!resolved) {
+    return { resolved: false, reason: 'unresolved' };
+  }
+
+  const absPath = resolved.absPath;
+
+  // Check if all expected files exist on disk
+  for (const file of expectedFiles) {
+    const filePath = path.join(absPath, file);
+    if (!fs.existsSync(filePath)) {
+      return { resolved: false, reason: 'unresolved' };
+    }
+  }
+
+  // Check if working tree is clean for expected files
+  const status = execGit(absPath, ['status', '--porcelain']);
+  if (status.exitCode === 0 && status.stdout.trim()) {
+    // Parse dirty files
+    const dirtyFiles = status.stdout
+      .split('\n')
+      .filter(l => l.trim())
+      .map(l => {
+        const match = l.match(/^[MADRCU?!]{1,2}\s+(.+)/);
+        return match ? match[1].trim() : null;
+      })
+      .filter(f => f);
+
+    // Check if any expected files are dirty
+    for (const file of expectedFiles) {
+      if (dirtyFiles.includes(file)) {
+        return { resolved: false, reason: 'unresolved' };
+      }
+    }
+  }
+
+  // Working tree is clean for expected files. Check SHA if provided.
+  if (priorSha) {
+    const verify = execGit(absPath, ['rev-parse', '--verify', priorSha]);
+    if (verify.exitCode === 0) {
+      return { resolved: true, reason: 'sha_verified' };
+    }
+    // SHA doesn't exist but tree is clean and files present — manually resolved
+  }
+
+  return { resolved: true, reason: 'manually_resolved' };
+}
+
+// ─── Planning Commit Body ───────────────────────────────────────────────────
+
+/**
+ * Build planning commit body with repo commit SHAs for traceability.
+ *
+ * @param {Array<{repo: string, status: string, sha: string|null}>} repoResults
+ * @returns {string}
+ */
+function buildPlanningCommitBody(repoResults) {
+  const completed = repoResults
+    .filter(r => r.status === 'complete')
+    .sort((a, b) => a.repo.localeCompare(b.repo));
+
+  if (completed.length === 0) return '';
+
+  return completed
+    .map(r => `Repo: ${r.repo} SHA: ${r.sha}`)
+    .join('\n');
+}
+
+// ─── Detect Repo Changes ───────────────────────────────────────────────────
+
+/**
+ * Detect changes in each repo by running git status.
+ * Groups changed files by repo, with paths relative to repo root.
+ *
+ * @param {string} cwd - Product root
+ * @param {string[]} repoNames - Repo names to check
+ * @returns {Array<{repoName: string, repoPath: string, files: string[]}>}
+ */
+function detectRepoChanges(cwd, repoNames) {
+  const parsed = parseReposMd(cwd);
+  const repos = parsed ? parsed.repos : [];
+  const changes = [];
+
+  for (const name of repoNames) {
+    const resolved = resolveRepoPath(cwd, name, repos);
+    if (!resolved) continue;
+    if (!fs.existsSync(resolved.absPath)) continue;
+
+    const status = execGit(resolved.absPath, ['status', '--porcelain']);
+    if (status.exitCode !== 0 || !status.stdout.trim()) continue;
+
+    const files = status.stdout
+      .split('\n')
+      .filter(l => l.trim())
+      .map(l => {
+        // git status --porcelain format: XY filename (but execGit trims leading spaces)
+        // Use regex to strip 1-2 char status code + space prefix
+        // Handles: 'M file.js', 'D file.js', '?? file.js', 'AM file.js', 'R old -> new'
+        const match = l.match(/^[MADRCU?!]{1,2}\s+(.+)/);
+        if (match) return match[1].trim();
+        // Fallback: strip first word (status) and return rest
+        const parts = l.trim().split(/\s+/);
+        return parts.length > 1 ? parts.slice(1).join(' ') : l.trim();
+      })
+      .filter(f => f);
+
+    if (files.length > 0) {
+      changes.push({
+        repoName: name,
+        repoPath: resolved.repo.path,
+        files,
+      });
+    }
+  }
+
+  return changes;
+}
+
+// ─── Branching ──────────────────────────────────────────────────────────────
+
+/**
+ * Create branches in each repo for multi-repo execution.
+ * Respects branching_strategy config — if 'none', skips branch creation.
+ * Reuses existing branch if it already exists.
+ * Detects branch prefix collisions and warns about potential ambiguity.
+ *
+ * When baseBranch is provided, uses two-pass validation:
+ *   Pass 1: Fetch and verify the base branch exists in ALL repos before any branch creation.
+ *   Pass 2: Checkout base branch, then create/checkout the new branch in each repo.
+ * This ensures no partial state — either all repos are validated or none are modified.
+ *
+ * The product folder (cwd itself) is NOT affected — this function only operates on
+ * sibling code repos registered in REPOS.md.
+ *
+ * @param {string} cwd - Product root
+ * @param {string[]} repoNames - Repo names
+ * @param {string} branchName - Branch name (e.g., dgs/project/phase-slug)
+ * @param {{ branching_strategy?: string }} config - Config object
+ * @param {string|null} [baseBranch=null] - Base branch to checkout before creating new branch.
+ *   When null/undefined, creates branch from wherever HEAD is (backwards-compatible behavior).
+ * @returns {{ created: boolean, reason?: string, error?: string, repo?: string, branches?: Array<{repo: string, branch: string, action: string}>, warnings?: Array }}
+ */
+function createRepoBranches(cwd, repoNames, branchName, config, baseBranch) {
+  if (config && config.branching_strategy === 'none') {
+    return { created: false, reason: 'branching_disabled' };
+  }
+
+  const parsed = parseReposMd(cwd);
+  const repos = parsed ? parsed.repos : [];
+  const branches = [];
+  const warnings = [];
+
+  // Extract project slug from branch name (format: dgs/<project-slug>/<phase-slug>)
+  const branchParts = branchName.split('/');
+  const projectSlug = branchParts.length >= 2 ? branchParts[1] : null;
+
+  // Resolve all repo paths upfront
+  const resolvedRepos = [];
+  for (const name of repoNames) {
+    const resolved = resolveRepoPath(cwd, name, repos);
+    if (!resolved) continue;
+    if (!fs.existsSync(resolved.absPath)) continue;
+    resolvedRepos.push({ name, resolved });
+  }
+
+  // ── Pass 1: Validate base branch in all repos (when baseBranch provided) ──
+  if (baseBranch) {
+    for (const { name, resolved } of resolvedRepos) {
+      // Fetch the base branch from remote (non-fatal — branch may be local-only)
+      execGit(resolved.absPath, ['fetch', 'origin', baseBranch]);
+
+      // Verify base branch exists locally
+      const baseCheck = execGit(resolved.absPath, ['rev-parse', '--verify', baseBranch]);
+      if (baseCheck.exitCode !== 0) {
+        // Also check remote tracking branch
+        const remoteCheck = execGit(resolved.absPath, ['rev-parse', '--verify', `origin/${baseBranch}`]);
+        if (remoteCheck.exitCode !== 0) {
+          return {
+            created: false,
+            reason: 'base_branch_missing',
+            error: `Base branch '${baseBranch}' does not exist in repo '${name}'. ` +
+                   `Checked both local and remote (origin/${baseBranch}). ` +
+                   `Configure git.base_branch in .planning/config.json or create the branch first.`,
+            repo: name,
+          };
+        }
+      }
+    }
+  }
+
+  // ── Pass 2: Create branches ───────────────────────────────────────────────
+  for (const { name, resolved } of resolvedRepos) {
+    // Check if branch already exists
+    const verify = execGit(resolved.absPath, ['rev-parse', '--verify', branchName]);
+    if (verify.exitCode === 0) {
+      // Branch exists — switch to it
+      execGit(resolved.absPath, ['checkout', branchName]);
+      branches.push({ repo: name, branch: branchName, action: 'reused' });
+    } else {
+      // Before creating, check for prefix collisions with existing branches
+      if (projectSlug) {
+        const listResult = execGit(resolved.absPath, ['branch', '--list', `dgs/${projectSlug}/*`]);
+        if (listResult.exitCode === 0 && listResult.stdout.trim()) {
+          const existingBranches = listResult.stdout
+            .split('\n')
+            .map(b => b.replace(/^\*?\s*/, '').trim())
+            .filter(b => b && b !== branchName);
+          if (existingBranches.length > 0) {
+            warnings.push({
+              type: 'prefix_collision',
+              repo: name,
+              existing_branches: existingBranches,
+              new_branch: branchName,
+            });
+          }
+        }
+      }
+
+      // Checkout base branch first (when baseBranch provided)
+      if (baseBranch) {
+        const baseCheckout = execGit(resolved.absPath, ['checkout', baseBranch]);
+        if (baseCheckout.exitCode !== 0) {
+          branches.push({ repo: name, branch: branchName, action: 'failed', error: `Failed to checkout base branch '${baseBranch}': ${baseCheckout.stderr}` });
+          continue;
+        }
+      }
+
+      // Create and switch to new branch
+      const create = execGit(resolved.absPath, ['checkout', '-b', branchName]);
+      if (create.exitCode === 0) {
+        branches.push({ repo: name, branch: branchName, action: 'created' });
+      } else {
+        branches.push({ repo: name, branch: branchName, action: 'failed', error: create.stderr });
+      }
+    }
+  }
+
+  return { created: true, branches, warnings };
+}
+
+/**
+ * Report branches to merge at phase completion.
+ * Informational only — does not perform any merge.
+ *
+ * @param {string} cwd - Product root
+ * @param {string[]} repoNames - Repo names
+ * @param {string} branchName - Branch name to check for
+ * @returns {{ branches: Array<{repo: string, branch: string, exists: boolean}> }}
+ */
+function reportBranchesToMerge(cwd, repoNames, branchName) {
+  const parsed = parseReposMd(cwd);
+  const repos = parsed ? parsed.repos : [];
+  const branches = [];
+
+  for (const name of repoNames) {
+    const resolved = resolveRepoPath(cwd, name, repos);
+    if (!resolved) continue;
+    if (!fs.existsSync(resolved.absPath)) continue;
+
+    const verify = execGit(resolved.absPath, ['rev-parse', '--verify', branchName]);
+    if (verify.exitCode === 0) {
+      branches.push({ repo: name, branch: branchName, exists: true });
+    }
+  }
+
+  return { branches };
+}
+
+// ─── Repo Status in STATE.md ────────────────────────────────────────────────
+
+/**
+ * Update Repo Status section in STATE.md.
+ * Writes table with Repo, Branch, Last Commit, Touched By columns.
+ *
+ * @param {string} cwd - Product root
+ * @param {string|null} projectSlug - Project slug for v2, null for v1
+ * @param {Array<{repo: string, status: string, sha: string|null}>} repoResults - Commit results
+ */
+function updateRepoStatus(cwd, projectSlug, repoResults) {
+  // Determine STATE.md path
+  let statePath;
+  const planRoot = getPlanningRoot(cwd);
+  if (projectSlug) {
+    statePath = path.join(planRoot, projectSlug, 'STATE.md');
+  }
+  if (!statePath || !fs.existsSync(statePath)) {
+    statePath = path.join(planRoot, 'STATE.md');
+  }
+
+  let stateContent = safeReadFile(statePath) || '';
+
+  // Build Repo Status table
+  const parsed = parseReposMd(cwd);
+  const repos = parsed ? parsed.repos : [];
+
+  let table = '## Repo Status\n\n';
+  table += '| Repo | Branch | Last Commit | Touched By |\n';
+  table += '|------|--------|-------------|------------|\n';
+
+  for (const result of repoResults.filter(r => r.status === 'complete')) {
+    const resolved = resolveRepoPath(cwd, result.repo, repos);
+    let branch = '-';
+    if (resolved && fs.existsSync(resolved.absPath)) {
+      const branchResult = execGit(resolved.absPath, ['branch', '--show-current']);
+      if (branchResult.exitCode === 0 && branchResult.stdout.trim()) {
+        branch = branchResult.stdout.trim();
+      }
+    }
+
+    // Derive "Touched By" from scanning active project plan tags
+    let touchedBy = '-';
+    try {
+      const projectFolders = getProjectSlugs(cwd);
+      const touchedByProjects = [];
+      for (const slug of projectFolders) {
+        const projectRepos = scanProjectReposTags(cwd, slug);
+        if (projectRepos.includes(result.repo)) {
+          touchedByProjects.push(slug);
+        }
+      }
+      if (touchedByProjects.length > 0) {
+        touchedBy = touchedByProjects.join(', ');
+      }
+    } catch {}
+
+    table += `| ${result.repo} | ${branch} | ${result.sha || '-'} | ${touchedBy} |\n`;
+  }
+
+  // Replace existing ## Repo Status section or append
+  const repoStatusRegex = /## Repo Status[\s\S]*?(?=\n## |\n---|\Z)/;
+  if (repoStatusRegex.test(stateContent)) {
+    stateContent = stateContent.replace(repoStatusRegex, table.trim());
+  } else {
+    stateContent = stateContent.trimEnd() + '\n\n' + table;
+  }
+
+  fs.writeFileSync(statePath, stateContent);
+}
+
+/**
+ * Get project slugs from .planning directory.
+ * Looks for subdirectories that contain STATE.md (project folders).
+ *
+ * @param {string} cwd - Product root
+ * @returns {string[]}
+ */
+function getProjectSlugs(cwd) {
+  const planningDir = getPlanningRoot(cwd);
+  const slugs = [];
+  try {
+    const entries = fs.readdirSync(planningDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'phases' || entry.name === 'debug' || entry.name === 'codebase') continue;
+      if (entry.name.startsWith('.')) continue;
+      // Check if it has STATE.md (project folder indicator)
+      if (fs.existsSync(path.join(planningDir, entry.name, 'STATE.md'))) {
+        slugs.push(entry.name);
+      }
+    }
+  } catch {}
+  return slugs;
+}
+
+// ─── CLI Command Functions ──────────────────────────────────────────────────
+
+/**
+ * CLI: Run multi-repo commit workflow.
+ * Preflight dirty_repos are advisory warnings (proceed anyway).
+ * Preflight missing_repos are hard errors (block execution).
+ * Supports --retry with prior results to skip already-committed repos.
+ *
+ * @param {string} cwd - Working directory
+ * @param {Object} options - { type, project, phase, plan, description, repos, retry, priorResults, phaseDir }
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdCommitMultiRepo(cwd, options, raw) {
+  const repoNames = options.repos;
+  if (!repoNames || repoNames.length === 0) {
+    error('No repos specified. Use --repos repo1,repo2');
+  }
+
+  const warnings = [];
+
+  // Run preflight
+  const preflight = preflightCheck(cwd, repoNames, options.phaseDir || null);
+
+  // Missing repos is a hard error — block execution
+  if (preflight.missing_repos && preflight.missing_repos.length > 0) {
+    output({
+      success: false,
+      preflight,
+      message: 'Pre-flight check failed: missing repos',
+      warnings,
+    }, raw);
+    return;
+  }
+
+  // Dirty repos are advisory — warn but proceed
+  if (preflight.dirty_repos && preflight.dirty_repos.length > 0) {
+    for (const dirty of preflight.dirty_repos) {
+      warnings.push({ type: 'dirty_repo', repo: dirty.name, files: dirty.files });
+    }
+  }
+
+  // Partial execution is informational — include but do not block
+  if (preflight.partial_execution) {
+    warnings.push({ type: 'partial_execution', info: preflight.partial_execution });
+  }
+
+  // Detect changes
+  const changes = detectRepoChanges(cwd, repoNames);
+  if (changes.length === 0) {
+    output({ success: true, message: 'No changes detected', commits: [], warnings }, raw);
+    return;
+  }
+
+  // Commit per repo (retry mode or normal)
+  let results;
+  if (options.retry && options.priorResults) {
+    results = retryCommitPerRepo(cwd, changes, options, options.priorResults);
+  } else {
+    results = commitPerRepo(cwd, changes, options);
+  }
+
+  // Build planning commit body
+  const body = buildPlanningCommitBody(results);
+
+  output({
+    success: results.every(r => r.status === 'complete'),
+    commits: results,
+    planning_body: body,
+    warnings,
+  }, raw);
+}
+
+/**
+ * CLI: Run pre-flight check.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string[]} repoNames - Repo names to check
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdCommitPreflight(cwd, repoNames, raw) {
+  const result = preflightCheck(cwd, repoNames);
+  output(result, raw);
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  resolveRepoPath,
+  resolveRepoRelativePath,
+  preflightCheck,
+  commitPerRepo,
+  retryCommitPerRepo,
+  detectManualResolution,
+  buildPlanningCommitBody,
+  detectRepoChanges,
+  createRepoBranches,
+  reportBranchesToMerge,
+  updateRepoStatus,
+  cmdCommitMultiRepo,
+  cmdCommitPreflight,
+};