@ktpartners/dgs-platform 2.6.3 → 2.7.0

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

@@ -0,0 +1,878 @@
+/**
+ * Sync — Pull/push operations across all registered repos
+ *
+ * Provides pullAll and pushAll that iterate planning repo + REPOS.md code repos,
+ * with pre-flight checks, error handling, and structured result reporting.
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { execGit, safeReadFile, loadConfig } = require('./core.cjs');
+const { parseReposMd } = require('./repos.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { getLocalConfigPath } = require('./config.cjs');
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Execute a git command with a timeout.
+ *
+ * Wrapper around execSync (NOT execGit) that adds a timeout option.
+ * The existing execGit in core.cjs does not support timeouts and we
+ * should not modify it (other callers don't need timeouts).
+ *
+ * @param {string} cwd - Working directory
+ * @param {string[]} args - Git command arguments
+ * @param {number} timeoutMs - Timeout in milliseconds (default 30000)
+ * @returns {{ exitCode: number, stdout: string, stderr: string, isTimeout?: boolean, isAuth?: boolean }}
+ */
+function execGitWithTimeout(cwd, args, timeoutMs = 30000) {
+  try {
+    const escaped = args.map(a => {
+      if (/^[a-zA-Z0-9._\-/=:@]+$/.test(a)) return a;
+      return "'" + a.replace(/'/g, "'\\''") + "'";
+    });
+    const stdout = execSync('git ' + escaped.join(' '), {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      timeout: timeoutMs,
+    });
+    return { exitCode: 0, stdout: stdout.trim(), stderr: '' };
+  } catch (err) {
+    // Classify error
+    const stderr = (err.stderr ?? '').toString().trim();
+    const isTimeout = err.killed || (err.signal === 'SIGTERM');
+    const isAuth = /authentication|permission denied|could not read.*credentials|fatal: unable to access/i.test(stderr);
+    return {
+      exitCode: err.status ?? 1,
+      stdout: (err.stdout ?? '').toString().trim(),
+      stderr,
+      isTimeout,
+      isAuth,
+    };
+  }
+}
+
+/**
+ * Check if a repo has a remote configured.
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @returns {boolean}
+ */
+function hasRemote(repoPath) {
+  const result = execGitWithTimeout(repoPath, ['remote'], 5000);
+  return result.exitCode === 0 && result.stdout.trim().length > 0;
+}
+
+/**
+ * Get the current branch name for a repo.
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @returns {string|null} Branch name, or null on error
+ */
+function getCurrentBranch(repoPath) {
+  const result = execGitWithTimeout(repoPath, ['rev-parse', '--abbrev-ref', 'HEAD'], 5000);
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim();
+}
+
+/**
+ * Check if a branch has an upstream tracking branch configured.
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {string} branch - Branch name
+ * @returns {boolean}
+ */
+function hasUpstreamTracking(repoPath, branch) {
+  const result = execGitWithTimeout(repoPath, ['config', '--get', `branch.${branch}.remote`], 5000);
+  return result.exitCode === 0 && result.stdout.trim().length > 0;
+}
+
+/**
+ * Translate raw git errors into user-friendly messages.
+ *
+ * @param {Object} result - execGitWithTimeout result
+ * @param {string} operation - 'fetch', 'pull', or 'push'
+ * @param {string} repoName - Repo display name
+ * @param {string} repoPath - Absolute path to the repo
+ * @returns {string} User-friendly error message
+ */
+function classifyError(result, operation, repoName, repoPath) {
+  if (result.isTimeout) {
+    return 'Network timeout after 30s -- check connection or try again';
+  }
+  if (result.isAuth) {
+    return 'Authentication failed -- check credentials for remote';
+  }
+
+  const stderr = result.stderr || '';
+
+  // Non-fast-forward on pull/fetch+merge
+  if ((operation === 'pull' || operation === 'fetch') && /not possible to fast-forward|non-fast-forward/i.test(stderr)) {
+    const branch = getCurrentBranch(repoPath) || 'main';
+    return `Cannot fast-forward -- history has diverged. Fix: cd ${repoPath} && git pull --rebase origin ${branch}`;
+  }
+
+  // Rejected push
+  if (operation === 'push' && /rejected|failed to push/i.test(stderr)) {
+    const branch = getCurrentBranch(repoPath) || 'main';
+    return `Push rejected -- remote has new commits. Fix: cd ${repoPath} && git pull --rebase origin ${branch} && git push`;
+  }
+
+  // Default: first line of stderr
+  const firstLine = stderr.split('\n')[0];
+  return firstLine || `Git ${operation} failed (exit code ${result.exitCode})`;
+}
+
+// ─── Repo Collection ─────────────────────────────────────────────────────────
+
+/**
+ * Build the list of repos to sync.
+ *
+ * Returns an array of { name, path, isPlanning } objects.
+ * First entry is the planning repo, remaining entries from REPOS.md.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @returns {Array<{ name: string, path: string, isPlanning: boolean }>}
+ */
+function collectSyncRepos(cwd) {
+  const repos = [];
+
+  // First entry: the planning repo itself (cwd is the product root containing .planning/)
+  const resolvedCwd = path.resolve(cwd);
+  const basename = path.basename(resolvedCwd);
+
+  // Check if cwd is a git repo
+  const isGitRepo = fs.existsSync(path.join(resolvedCwd, '.git'));
+  if (isGitRepo) {
+    repos.push({
+      name: basename,
+      path: resolvedCwd,
+      isPlanning: true,
+    });
+  }
+
+  // Remaining entries: parse REPOS.md
+  const parsed = parseReposMd(cwd);
+  if (parsed && parsed.repos) {
+    for (const repo of parsed.repos) {
+      if (!repo.name || !repo.path) continue;
+      const absPath = path.isAbsolute(repo.path)
+        ? repo.path
+        : path.resolve(cwd, repo.path);
+      repos.push({
+        name: repo.name,
+        path: absPath,
+        isPlanning: false,
+      });
+    }
+  }
+
+  return repos;
+}
+
+// ─── Pre-flight Checks ──────────────────────────────────────────────────────
+
+/**
+ * Check ALL repos before blocking -- reports all problems at once.
+ *
+ * @param {Array<{ name: string, path: string, isPlanning: boolean }>} repos
+ * @returns {{ ok: boolean, problems: Array<{ repo: string, path: string, issue: string, fix: string }> }}
+ */
+function preFlightCheck(repos) {
+  const problems = [];
+
+  for (const repo of repos) {
+    const label = repo.isPlanning ? `${repo.name} (planning)` : repo.name;
+
+    // Find the actual .git directory (handles worktrees and submodules)
+    const gitDirResult = execGitWithTimeout(repo.path, ['rev-parse', '--git-dir'], 5000);
+    if (gitDirResult.exitCode !== 0) {
+      problems.push({
+        repo: label,
+        path: repo.path,
+        issue: 'not a git repository',
+        fix: `cd ${repo.path} && git init`,
+      });
+      continue;
+    }
+
+    const gitDir = path.isAbsolute(gitDirResult.stdout)
+      ? gitDirResult.stdout
+      : path.resolve(repo.path, gitDirResult.stdout);
+
+    // Dirty state: git status --porcelain
+    const statusResult = execGitWithTimeout(repo.path, ['status', '--porcelain'], 5000);
+    if (statusResult.exitCode === 0 && statusResult.stdout.trim().length > 0) {
+      problems.push({
+        repo: label,
+        path: repo.path,
+        issue: 'uncommitted changes',
+        fix: `cd ${repo.path} && git add -A && git commit -m "WIP" or git stash`,
+      });
+    }
+
+    // Mid-merge: check for MERGE_HEAD
+    if (fs.existsSync(path.join(gitDir, 'MERGE_HEAD'))) {
+      problems.push({
+        repo: label,
+        path: repo.path,
+        issue: 'merge in progress',
+        fix: `cd ${repo.path} && git merge --abort or git merge --continue`,
+      });
+    }
+
+    // Mid-rebase: check for rebase-merge/ or rebase-apply/
+    if (fs.existsSync(path.join(gitDir, 'rebase-merge')) || fs.existsSync(path.join(gitDir, 'rebase-apply'))) {
+      problems.push({
+        repo: label,
+        path: repo.path,
+        issue: 'rebase in progress',
+        fix: `cd ${repo.path} && git rebase --abort or git rebase --continue`,
+      });
+    }
+
+    // Mid-cherry-pick: check for CHERRY_PICK_HEAD
+    if (fs.existsSync(path.join(gitDir, 'CHERRY_PICK_HEAD'))) {
+      problems.push({
+        repo: label,
+        path: repo.path,
+        issue: 'cherry-pick in progress',
+        fix: `cd ${repo.path} && git cherry-pick --abort`,
+      });
+    }
+
+    // Detached HEAD: git symbolic-ref HEAD
+    const headResult = execGitWithTimeout(repo.path, ['symbolic-ref', 'HEAD'], 5000);
+    if (headResult.exitCode !== 0) {
+      problems.push({
+        repo: label,
+        path: repo.path,
+        issue: 'detached HEAD',
+        fix: `cd ${repo.path} && git checkout <branch>`,
+      });
+    }
+  }
+
+  return {
+    ok: problems.length === 0,
+    problems,
+  };
+}
+
+// ─── Pull ────────────────────────────────────────────────────────────────────
+
+/**
+ * Pull from all registered repos (planning + REPOS.md code repos).
+ *
+ * Uses fetch + merge --ff-only (not git pull) to get accurate commit counts
+ * before merging and to handle missing origin/<branch> gracefully.
+ *
+ * Continues processing all repos on failure rather than aborting on first failure.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun=false] - Report what would happen without modifying repos
+ * @param {boolean} [options.force=false] - Bypass pre-flight checks
+ * @returns {{ ok: boolean, results: Array<{ repo: string, path: string, status: string, commits: number|null, message: string }>, problems?: Array, summary: string }}
+ */
+function pullAll(cwd, options = {}) {
+  const { dryRun = false, force = false } = options;
+  const repos = collectSyncRepos(cwd);
+  const results = [];
+
+  // Pre-flight (unless forced or dry-run)
+  if (!force && !dryRun) {
+    const preflight = preFlightCheck(repos);
+    if (!preflight.ok) {
+      return {
+        ok: false,
+        results: [],
+        problems: preflight.problems,
+        summary: `Pre-flight failed: ${preflight.problems.length} repo(s) have issues`,
+      };
+    }
+  }
+
+  for (const repo of repos) {
+    const label = repo.isPlanning ? `${repo.name} (planning)` : repo.name;
+
+    // Skip repos with no remote
+    if (!hasRemote(repo.path)) {
+      results.push({ repo: label, path: repo.path, status: 'skipped', commits: null, message: 'No remote configured' });
+      continue;
+    }
+
+    if (dryRun) {
+      results.push({ repo: label, path: repo.path, status: 'current', commits: null, message: 'Would pull' });
+      continue;
+    }
+
+    const branch = getCurrentBranch(repo.path);
+    if (!branch || branch === 'HEAD') {
+      results.push({ repo: label, path: repo.path, status: 'skipped', commits: null, message: 'Detached HEAD' });
+      continue;
+    }
+
+    // Fetch first to check what would change
+    const fetchResult = execGitWithTimeout(repo.path, ['fetch', 'origin', branch], 30000);
+    if (fetchResult.exitCode !== 0) {
+      const msg = classifyError(fetchResult, 'fetch', repo.name, repo.path);
+      results.push({ repo: label, path: repo.path, status: 'failed', commits: null, message: msg });
+      continue;
+    }
+
+    // Check if there are new commits to pull
+    const logResult = execGitWithTimeout(repo.path, ['rev-list', '--count', `HEAD..origin/${branch}`], 5000);
+    const commitCount = logResult.exitCode === 0 ? parseInt(logResult.stdout, 10) : 0;
+
+    if (commitCount === 0) {
+      results.push({ repo: label, path: repo.path, status: 'current', commits: 0, message: 'Already up to date' });
+      continue;
+    }
+
+    // Pull with --ff-only (via merge)
+    const pullResult = execGitWithTimeout(repo.path, ['merge', '--ff-only', `origin/${branch}`], 30000);
+    if (pullResult.exitCode !== 0) {
+      const msg = classifyError(pullResult, 'pull', repo.name, repo.path);
+      results.push({ repo: label, path: repo.path, status: 'failed', commits: null, message: msg });
+      continue;
+    }
+
+    results.push({ repo: label, path: repo.path, status: 'updated', commits: commitCount, message: `Pulled ${commitCount} commit${commitCount !== 1 ? 's' : ''}` });
+  }
+
+  // Build summary
+  const updated = results.filter(r => r.status === 'updated').length;
+  const current = results.filter(r => r.status === 'current').length;
+  const skipped = results.filter(r => r.status === 'skipped').length;
+  const failed = results.filter(r => r.status === 'failed').length;
+  const parts = [];
+  if (updated) parts.push(`${updated} updated`);
+  if (current) parts.push(`${current} current`);
+  if (skipped) parts.push(`${skipped} skipped`);
+  if (failed) parts.push(`${failed} failed`);
+  const summary = dryRun ? `Dry run: ${repos.length} repo(s) checked` : parts.join(', ');
+
+  return {
+    ok: failed === 0,
+    results,
+    summary,
+  };
+}
+
+// ─── Push ────────────────────────────────────────────────────────────────────
+
+/**
+ * Push to all registered repos (planning + REPOS.md code repos).
+ *
+ * Uses -u origin <branch> on first push when no upstream tracking exists.
+ * Continues past failures and reports all results at end.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun=false] - Report what would happen without modifying repos
+ * @param {boolean} [options.force=false] - Bypass pre-flight checks
+ * @param {string[]|null} [options.repos=null] - Filter to push only specific repos by name
+ * @returns {{ ok: boolean, results: Array<{ repo: string, path: string, status: string, commits: number|null, message: string }>, problems?: Array, summary: string }}
+ */
+function pushAll(cwd, options = {}) {
+  const { dryRun = false, force = false, repos: repoFilter = null } = options;
+  let allRepos = collectSyncRepos(cwd);
+
+  // Apply --repos filter if specified
+  if (repoFilter && repoFilter.length > 0) {
+    const filterSet = new Set(repoFilter.map(r => r.toLowerCase()));
+    allRepos = allRepos.filter(r => filterSet.has(r.name.toLowerCase()));
+    if (allRepos.length === 0) {
+      return { ok: false, results: [], summary: 'No matching repos found for filter' };
+    }
+  }
+
+  const results = [];
+
+  // Pre-flight (unless forced or dry-run)
+  if (!force && !dryRun) {
+    const preflight = preFlightCheck(allRepos);
+    if (!preflight.ok) {
+      return {
+        ok: false,
+        results: [],
+        problems: preflight.problems,
+        summary: `Pre-flight failed: ${preflight.problems.length} repo(s) have issues`,
+      };
+    }
+  }
+
+  for (const repo of allRepos) {
+    const label = repo.isPlanning ? `${repo.name} (planning)` : repo.name;
+
+    // Skip repos with no remote
+    if (!hasRemote(repo.path)) {
+      results.push({ repo: label, path: repo.path, status: 'skipped', commits: null, message: 'No remote configured' });
+      continue;
+    }
+
+    const branch = getCurrentBranch(repo.path);
+    if (!branch || branch === 'HEAD') {
+      results.push({ repo: label, path: repo.path, status: 'skipped', commits: null, message: 'Detached HEAD' });
+      continue;
+    }
+
+    if (dryRun) {
+      // Check if there are unpushed commits
+      const upstream = hasUpstreamTracking(repo.path, branch);
+      if (upstream) {
+        const logResult = execGitWithTimeout(repo.path, ['rev-list', '--count', `origin/${branch}..HEAD`], 5000);
+        const count = logResult.exitCode === 0 ? parseInt(logResult.stdout, 10) : 0;
+        if (count > 0) {
+          results.push({ repo: label, path: repo.path, status: 'pushed', commits: count, message: `Would push ${count} commit${count !== 1 ? 's' : ''}` });
+        } else {
+          results.push({ repo: label, path: repo.path, status: 'current', commits: 0, message: 'Nothing to push' });
+        }
+      } else {
+        results.push({ repo: label, path: repo.path, status: 'pushed', commits: null, message: 'Would push (first push, sets upstream)' });
+      }
+      continue;
+    }
+
+    // Check if there are commits to push
+    const upstream = hasUpstreamTracking(repo.path, branch);
+    let commitCount = null;
+
+    if (upstream) {
+      const logResult = execGitWithTimeout(repo.path, ['rev-list', '--count', `origin/${branch}..HEAD`], 5000);
+      commitCount = logResult.exitCode === 0 ? parseInt(logResult.stdout, 10) : null;
+
+      if (commitCount === 0) {
+        results.push({ repo: label, path: repo.path, status: 'current', commits: 0, message: 'Nothing to push' });
+        continue;
+      }
+    }
+
+    // Push -- use -u origin <branch> if no upstream tracking
+    const pushArgs = upstream
+      ? ['push', 'origin', branch]
+      : ['push', '-u', 'origin', branch];
+
+    const pushResult = execGitWithTimeout(repo.path, pushArgs, 30000);
+    if (pushResult.exitCode !== 0) {
+      const msg = classifyError(pushResult, 'push', repo.name, repo.path);
+      results.push({ repo: label, path: repo.path, status: 'failed', commits: null, message: msg });
+      continue;
+    }
+
+    const commitLabel = commitCount != null ? `${commitCount} commit${commitCount !== 1 ? 's' : ''}` : 'branch';
+    results.push({ repo: label, path: repo.path, status: 'pushed', commits: commitCount, message: `Pushed ${commitLabel}` });
+  }
+
+  // Build summary
+  const pushed = results.filter(r => r.status === 'pushed').length;
+  const current = results.filter(r => r.status === 'current').length;
+  const skipped = results.filter(r => r.status === 'skipped').length;
+  const failed = results.filter(r => r.status === 'failed').length;
+  const totalCommits = results.reduce((sum, r) => sum + (r.commits || 0), 0);
+  const parts = [];
+  if (pushed) parts.push(`${pushed} pushed`);
+  if (current) parts.push(`${current} current`);
+  if (skipped) parts.push(`${skipped} skipped`);
+  if (failed) parts.push(`${failed} failed`);
+  let summary = dryRun ? `Dry run: ${allRepos.length} repo(s) checked` : parts.join(', ');
+  if (!dryRun && totalCommits > 0) {
+    summary += ` (${totalCommits} commit${totalCommits !== 1 ? 's' : ''} total)`;
+  }
+
+  return {
+    ok: failed === 0,
+    results,
+    summary,
+  };
+}
+
+// ─── Suppression Tracking ─────────────────────────────────────────────────────
+
+// Suppression window: 5 minutes. Persists across CLI invocations via temp files.
+const SUPPRESSION_WINDOW_MS = 5 * 60 * 1000;
+const SUPPRESSION_DIR = path.join(require('os').tmpdir(), 'dgs-sync');
+
+function getSuppressionFile(direction) {
+  return path.join(SUPPRESSION_DIR, `${direction}.ts`);
+}
+
+function isWithinSuppressionWindow(direction) {
+  try {
+    const ts = parseInt(fs.readFileSync(getSuppressionFile(direction), 'utf-8'), 10);
+    return (Date.now() - ts) < SUPPRESSION_WINDOW_MS;
+  } catch { return false; }
+}
+
+function recordPromptYes(direction) {
+  fs.mkdirSync(SUPPRESSION_DIR, { recursive: true });
+  fs.writeFileSync(getSuppressionFile(direction), String(Date.now()));
+}
+
+// ─── First-Run Hint Tracking ─────────────────────────────────────────────────
+
+function shouldShowFirstRunHint(cwd) {
+  // Show hint when: remote exists, sync mode is 'off' or 'manual', hint not already shown
+  const config = loadConfig(cwd);
+  const syncPush = config.sync_push || 'off';
+  const syncPull = config.sync_pull || 'off';
+  if (syncPush !== 'off' || syncPull !== 'off') return false; // sync is configured, no hint needed
+  if (config.sync_hint_shown) return false; // already shown
+  // Check if any repo has a remote
+  const repos = collectSyncRepos(cwd);
+  return repos.some(r => hasRemote(r.path));
+}
+
+function markFirstRunHintShown(cwd) {
+  // Write sync_hint_shown: true to config.local.json (top-level key, not nested under git.)
+  const configPath = getLocalConfigPath(cwd);
+  let raw = {};
+  try {
+    if (fs.existsSync(configPath)) {
+      raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+  } catch { /* start fresh */ }
+  raw.sync_hint_shown = true;
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n');
+}
+
+// ─── Stale-State Detection ───────────────────────────────────────────────────
+
+function checkStaleState(cwd) {
+  // Check if planning repo's remote is ahead. Returns { stale, commitsBehind, branch }.
+  const repos = collectSyncRepos(cwd);
+  const planningRepo = repos.find(r => r.isPlanning);
+  if (!planningRepo || !hasRemote(planningRepo.path)) return { stale: false, commitsBehind: 0, branch: null };
+
+  const branch = getCurrentBranch(planningRepo.path);
+  if (!branch) return { stale: false, commitsBehind: 0, branch: null };
+
+  // Fetch without merging (silent)
+  const fetchResult = execGitWithTimeout(planningRepo.path, ['fetch', 'origin', branch], 10000);
+  if (fetchResult.exitCode !== 0) return { stale: false, commitsBehind: 0, branch }; // can't tell, don't warn
+
+  // Count commits behind
+  const logResult = execGitWithTimeout(planningRepo.path, ['rev-list', '--count', `HEAD..origin/${branch}`], 5000);
+  const commitsBehind = logResult.exitCode === 0 ? parseInt(logResult.stdout, 10) : 0;
+
+  return { stale: commitsBehind > 0, commitsBehind, branch };
+}
+
+// ─── Workflow Pull ───────────────────────────────────────────────────────────
+
+/**
+ * Pull before workflow starts, respecting sync mode.
+ *
+ * @param {string} cwd - Working directory
+ * @param {Object} options
+ * @param {string} options.syncMode - 'off'|'prompt'|'auto' (from init sync_pull)
+ * @param {boolean} options.cadencePull - Whether this workflow should pull (from init cadence_pull)
+ * @param {Object} [options.io] - I/O callbacks for prompt mode { prompt(msg) => Promise<string>, stderr(msg) => void }
+ * @returns {Promise<{ action: 'pulled'|'skipped'|'aborted', result?: Object, message: string }>}
+ */
+async function workflowPull(cwd, options) {
+  const { syncMode, cadencePull, io } = options;
+
+  // No pull: cadence says no, or mode is off
+  if (!cadencePull || syncMode === 'off') {
+    // In manual/off mode with cadence_pull, show stale-state warning (WFL-08)
+    if (cadencePull && syncMode === 'off') {
+      const stale = checkStaleState(cwd);
+      if (stale.stale && io?.stderr) {
+        io.stderr(`Warning: origin/${stale.branch} is ${stale.commitsBehind} commit${stale.commitsBehind !== 1 ? 's' : ''} ahead. Consider pulling.`);
+      }
+      // First-run hint (WFL-12)
+      if (shouldShowFirstRunHint(cwd) && io?.stderr) {
+        io.stderr('Tip: Remote detected. Enable sync with /dgs:settings');
+        markFirstRunHintShown(cwd);
+      }
+    }
+    return { action: 'skipped', message: 'Sync pull not configured' };
+  }
+
+  // Prompt mode
+  if (syncMode === 'prompt') {
+    // Check suppression window (WFL-11)
+    if (isWithinSuppressionWindow('pull')) {
+      // Auto-pull silently (recent Yes answer)
+      const result = pullAll(cwd, { force: false });
+      if (!result.ok) {
+        // Even suppressed, report failures
+        if (io?.stderr) io.stderr(`Pull failed: ${result.summary}`);
+        return { action: 'aborted', result, message: result.summary };
+      }
+      return { action: 'pulled', result, message: result.summary };
+    }
+
+    // Prompt user
+    if (io?.prompt) {
+      const answer = await io.prompt('Pull from remote before starting? [Y/n]');
+      const no = /^n/i.test((answer || '').trim());
+      if (no) {
+        return { action: 'skipped', message: 'Pull declined by user' };
+      }
+      recordPromptYes('pull');
+    }
+  }
+
+  // Auto mode or prompt-accepted: execute pull
+  const result = pullAll(cwd, { force: false });
+
+  if (!result.ok) {
+    // Pull failure: detailed diagnosis (WFL-04)
+    const failedRepos = result.results?.filter(r => r.status === 'failed') || [];
+    const diagnosis = failedRepos.map(r => `  ${r.repo}: ${r.message}`).join('\n');
+    const preflightProblems = result.problems?.map(p => `  ${p.repo}: ${p.issue} -- ${p.fix}`).join('\n');
+    const detail = preflightProblems || diagnosis || result.summary;
+
+    if (io?.stderr) {
+      io.stderr(`Pull failed:\n${detail}`);
+    }
+
+    // Offer override in prompt mode (WFL-04)
+    if (syncMode === 'prompt' && io?.prompt) {
+      const override = await io.prompt('Continue without pulling? [y/N]');
+      const yes = /^y/i.test((override || '').trim());
+      if (yes) {
+        return { action: 'skipped', message: 'Pull failed, user chose to continue' };
+      }
+    }
+
+    return { action: 'aborted', result, message: detail };
+  }
+
+  return { action: 'pulled', result, message: result.summary };
+}
+
+// ─── Workflow Push ───────────────────────────────────────────────────────────
+
+/**
+ * Push after workflow completes, respecting sync mode.
+ *
+ * @param {string} cwd - Working directory
+ * @param {Object} options
+ * @param {string} options.syncMode - 'off'|'prompt'|'auto' (from init sync_push)
+ * @param {boolean} options.cadencePush - Whether this workflow should push (from init cadence_push)
+ * @param {boolean} [options.midWorkflow=false] - True for mid-workflow pushes (no prompt, silent)
+ * @param {number} [options.maxRetries=1] - Max retries on failure (1 for prompt, 3 for auto)
+ * @param {Object} [options.io] - I/O callbacks { stderr(msg) => void, prompt(msg) => Promise<string> }
+ * @returns {Promise<{ action: 'pushed'|'skipped'|'warning', result?: Object, message: string }>}
+ */
+async function workflowPush(cwd, options) {
+  const { syncMode, cadencePush, midWorkflow = false, maxRetries = 1, io } = options;
+
+  // No push: cadence says no, or mode is off
+  if (!cadencePush || syncMode === 'off') {
+    return { action: 'skipped', message: 'Sync push not configured' };
+  }
+
+  // Prompt mode (non-mid-workflow): ask user
+  if (syncMode === 'prompt' && !midWorkflow) {
+    // Check suppression window (WFL-11)
+    if (!isWithinSuppressionWindow('push')) {
+      if (io?.prompt) {
+        const answer = await io.prompt('Push to remote? [Y/n]');
+        const no = /^n/i.test((answer || '').trim());
+        if (no) {
+          return { action: 'skipped', message: 'Push declined by user' };
+        }
+        recordPromptYes('push');
+      }
+    }
+  }
+
+  // Execute push with retries
+  let lastResult;
+  const retries = midWorkflow ? maxRetries : 0; // Only retry mid-workflow pushes
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    lastResult = pushAll(cwd, { force: true }); // force: bypass preflight for push (already committed)
+    if (lastResult.ok) break;
+    // Don't retry if not mid-workflow
+    if (!midWorkflow) break;
+  }
+
+  if (!lastResult.ok) {
+    // Push failure: warning only, do not abort (WFL-05)
+    const failedRepos = lastResult.results?.filter(r => r.status === 'failed') || [];
+    const failSummary = failedRepos.map(r => `${r.repo}: ${r.message}`).join(', ');
+    const msg = `Warning: push failed (${failSummary}). Work saved locally.`;
+    if (io?.stderr) io.stderr(msg);
+    return { action: 'warning', result: lastResult, message: msg };
+  }
+
+  // Build push summary (WFL-09)
+  const totalCommits = lastResult.results.reduce((sum, r) => sum + (r.commits || 0), 0);
+  const repoCount = lastResult.results.filter(r => r.status === 'pushed').length;
+  let summaryMsg;
+
+  const failedCount = lastResult.results.filter(r => r.status === 'failed').length;
+  if (failedCount > 0) {
+    const unpushed = lastResult.results.filter(r => r.status === 'failed').reduce((s, r) => s + (r.commits || 0), 0);
+    summaryMsg = `Pushed ${totalCommits} commit${totalCommits !== 1 ? 's' : ''} across ${repoCount} repo${repoCount !== 1 ? 's' : ''} (${unpushed} commits unpushed -- see warnings above)`;
+  } else if (repoCount > 1) {
+    summaryMsg = `Pushed ${totalCommits} commit${totalCommits !== 1 ? 's' : ''} across ${repoCount} repos`;
+  } else if (totalCommits > 0) {
+    const branch = getCurrentBranch(collectSyncRepos(cwd)[0]?.path || cwd) || 'main';
+    summaryMsg = `Pushed ${totalCommits} commit${totalCommits !== 1 ? 's' : ''} to origin/${branch}`;
+  } else {
+    summaryMsg = 'Nothing to push';
+  }
+
+  if (!midWorkflow && io?.stderr) {
+    io.stderr(summaryMsg);
+  }
+
+  // Log remote branch creation for mid-workflow (WFL-10)
+  if (midWorkflow) {
+    const newBranches = lastResult.results.filter(r => r.message?.includes('first push') || r.message?.includes('branch'));
+    for (const nb of newBranches) {
+      if (io?.stderr) {
+        const branch = getCurrentBranch(nb.path) || 'unknown';
+        io.stderr(`Created remote branch: ${branch}`);
+      }
+    }
+  }
+
+  return { action: 'pushed', result: lastResult, message: summaryMsg };
+}
+
+// ─── Cadence Table ───────────────────────────────────────────────────────────
+
+/**
+ * Cadence lookup table mapping every DGS workflow to its sync classification.
+ *
+ * Each entry is keyed by the workflow name (slash command name without the
+ * `dgs:` prefix). Values are `{ pull: boolean, push: boolean }`.
+ *
+ * This is the source of truth for cadence classification. The documentation
+ * in sync-cadence.md (Plan 02) mirrors this table but is not parsed.
+ *
+ * Groups:
+ *   Pull + Push (35): Workflows that read shared state AND produce artifacts
+ *   Push only (17):   Workflows that produce artifacts but don't need fresh state
+ *   Pull only (4):    Workflows that read shared state but don't produce artifacts
+ *   No sync (14):     Informational or diagnostic workflows
+ */
+const CADENCE_TABLE = {
+  // ── Pull + Push (35) ──────────────────────────────────────────────────────
+  'execute-phase':        { pull: true,  push: true },
+  'plan-phase':           { pull: true,  push: true },
+  'discuss-phase':        { pull: true,  push: true },
+  'research-phase':       { pull: true,  push: true },
+  'run-job':              { pull: true,  push: true },
+  'create-milestone-job': { pull: true,  push: true },
+  'cancel-job':           { pull: true,  push: true },
+  'rollback-job':         { pull: true,  push: true },
+  'new-milestone':        { pull: true,  push: true },
+  'complete-milestone':   { pull: true,  push: true },
+  'audit-milestone':      { pull: true,  push: true },
+  'plan-milestone-gaps':  { pull: true,  push: true },
+  'cleanup':              { pull: true,  push: true },
+  'discuss-idea':         { pull: true,  push: true },
+  'develop-idea':         { pull: true,  push: true },
+  'research-idea':        { pull: true,  push: true },
+  'consolidate-ideas':    { pull: true,  push: true },
+  'undo-consolidation':   { pull: true,  push: true },
+  'write-spec':           { pull: true,  push: true },
+  'refine-spec':          { pull: true,  push: true },
+  'approve-spec':         { pull: true,  push: true },
+  'quick':                { pull: true,  push: true },
+  'fast':                 { pull: true,  push: true },
+  'add-todo':             { pull: true,  push: true },
+  'check-todos':          { pull: true,  push: true },
+  'new-project':          { pull: true,  push: true },
+  'init-product':         { pull: true,  push: true },
+  'add-phase':            { pull: true,  push: true },
+  'insert-phase':         { pull: true,  push: true },
+  'remove-phase':         { pull: true,  push: true },
+  'audit-phase':          { pull: true,  push: true },
+  'validate-phase':       { pull: true,  push: true },
+  'verify-work':          { pull: true,  push: true },
+  'add-tests':            { pull: true,  push: true },
+  'settings':             { pull: true,  push: true },
+
+  // ── Push only (17) ────────────────────────────────────────────────────────
+  'pause-work':           { pull: false, push: true },
+  'add-idea':             { pull: false, push: true },
+  'import-spec':          { pull: false, push: true },
+  'reject-idea':          { pull: false, push: true },
+  'restore-idea':         { pull: false, push: true },
+  'update-idea':          { pull: false, push: true },
+  'add-doc':              { pull: false, push: true },
+  'remove-doc':           { pull: false, push: true },
+  'add-repo':             { pull: false, push: true },
+  'remove-repo':          { pull: false, push: true },
+  'capture-principle':    { pull: false, push: true },
+  'complete-project':     { pull: false, push: true },
+  'reactivate-project':   { pull: false, push: true },
+  'switch-project':       { pull: false, push: true },
+  'set-profile':          { pull: false, push: true },
+  'map-codebase':         { pull: false, push: true },
+  'reapply-patches':      { pull: false, push: true },
+
+  // ── Pull only (4) ─────────────────────────────────────────────────────────
+  'resume-work':          { pull: true,  push: false },
+  'progress':             { pull: true,  push: false },
+  'find-related-ideas':   { pull: true,  push: false },
+  'list-phase-assumptions': { pull: true,  push: false },
+
+  // ── No sync (14) ──────────────────────────────────────────────────────────
+  'help':                 { pull: false, push: false },
+  'join-discord':         { pull: false, push: false },
+  'list-ideas':           { pull: false, push: false },
+  'list-specs':           { pull: false, push: false },
+  'list-docs':            { pull: false, push: false },
+  'list-jobs':            { pull: false, push: false },
+  'list-projects':        { pull: false, push: false },
+  'search':               { pull: false, push: false },
+  'overlap-check':        { pull: false, push: false },
+  'health':               { pull: false, push: false },
+  'update':               { pull: false, push: false },
+  'debug':                { pull: false, push: false },
+  'node-repair':          { pull: false, push: false },
+  'sync-upstream':        { pull: false, push: false },
+};
+
+/**
+ * Get the cadence classification for a workflow.
+ *
+ * @param {string} workflowName - Workflow name (e.g., 'execute-phase', 'pause-work')
+ * @returns {{ pull: boolean, push: boolean }} Cadence flags. Unknown workflows default to no-sync.
+ */
+function getCadence(workflowName) {
+  return CADENCE_TABLE[workflowName] || { pull: false, push: false };
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  collectSyncRepos,
+  preFlightCheck,
+  pullAll,
+  pushAll,
+  // Workflow orchestration
+  workflowPull,
+  workflowPush,
+  checkStaleState,
+  shouldShowFirstRunHint,
+  markFirstRunHintShown,
+  // Cadence
+  CADENCE_TABLE,
+  getCadence,
+  // Exported for testing
+  execGitWithTimeout,
+  hasRemote,
+  getCurrentBranch,
+  hasUpstreamTracking,
+  classifyError,
+  isWithinSuppressionWindow,
+  recordPromptYes,
+  getSuppressionFile,
+  SUPPRESSION_WINDOW_MS,
+};