@imdeadpool/guardex 7.0.41 → 7.1.0

package/src/finish/index.js

@@ -1,4 +1,6 @@
+// @ts-check
 const { TOOL_NAME, LOCK_FILE_RELATIVE, path, fs } = require('../context');
+const { isTerseMode } = require('../output');
 const { run, runPackageAsset } = require('../core/runtime');
 const {
   resolveRepoRoot,
@@ -26,7 +28,52 @@ const {
   parseFinishArgs,
   parseSyncArgs,
 } = require('../cli/args');
-
+const submoduleModule = require('../submodule');
+const { runPreflight, summarizePreflight } = require('./preflight');
+const { runReviewGate } = require('./review-gate');
+
+/**
+ * Options recognized by {@link autoCommitWorktreeForFinish} and the public
+ * {@link finish} entry. Mirrors the relevant subset of `parseFinishArgs`'s
+ * output.
+ *
+ * @typedef {Object} FinishOptions
+ * @property {boolean} [noAutoCommit] When true, refuse to auto-commit dirty worktrees.
+ * @property {boolean} [dryRun] When true, surface intended actions without performing them.
+ * @property {string} [commitMessage] Override for the auto-commit message.
+ * @property {boolean} [advanceSubmodules] Run `submoduleModule.advance` against the worktree before finish.
+ * @property {boolean} [waitForMerge] Forward `--wait-for-merge` to `agent-branch-finish`.
+ * @property {boolean} [cleanup] Forward `--cleanup` (vs `--no-cleanup`) to `agent-branch-finish`.
+ * @property {'pr'|'direct'|'auto'} [mergeMode] Merge selection forwarded to `agent-branch-finish`.
+ * @property {boolean} [keepRemote] Forward `--keep-remote-branch` to `agent-branch-finish`.
+ * @property {boolean} [parentGitlinkCommit] Toggle for `--parent-gitlink-commit`.
+ * @property {boolean} [failFast] Stop the loop after the first failing branch.
+ * @property {boolean} [all] Include already-merged branches in the candidate list.
+ * @property {string} [branch] Single branch to finish (skips discovery).
+ * @property {string} [base] Explicit base branch override.
+ * @property {string} [target] Path inside the target repo (defaults to cwd).
+ */
+
+/**
+ * Outcome of an auto-commit attempt for a single branch.
+ *
+ * @typedef {Object} AutoCommitResult
+ * @property {boolean} changed True when the worktree had local changes.
+ * @property {boolean} committed True only when a commit was created.
+ * @property {boolean} [dryRun] True when `--dry-run` short-circuited the commit.
+ * @property {string} [message] Commit message used (when `committed` is true).
+ */
+
+/**
+ * Claim agent file locks for every file the worktree is about to commit,
+ * including pending deletions. No-op when there is nothing to claim.
+ *
+ * @param {string} repoRoot Repo root for the lock tool to operate on.
+ * @param {string} worktreePath Worktree whose changes are being committed.
+ * @param {string} branch Agent branch that should own the new claims.
+ * @returns {void}
+ * @throws {Error} When the lock-claim or allow-delete subprocess exits non-zero.
+ */
 function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
   const changedFiles = uniquePreserveOrder([
     ...gitOutputLines(worktreePath, ['diff', '--name-only', '--', '.', ':(exclude).omx/state/agent-file-locks.json']),
@@ -83,6 +130,17 @@ function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
   }
 }
 
+/**
+ * Stage and commit pending work in `worktreePath` (if any) before the
+ * finish flow takes over. Honors `--no-auto-commit` and `--dry-run`.
+ *
+ * @param {string} repoRoot Repo root for lock-tool dispatch.
+ * @param {string} worktreePath Worktree to commit in.
+ * @param {string} branch Agent branch the worktree is checked out on.
+ * @param {FinishOptions} options Finish options (only auto-commit fields are read).
+ * @returns {AutoCommitResult} What happened (or would happen, in dry-run).
+ * @throws {Error} When `--no-auto-commit` is set with dirty state, or when git add/commit fails.
+ */
 function autoCommitWorktreeForFinish(repoRoot, worktreePath, branch, options) {
   const hasChanges = worktreeHasLocalChanges(worktreePath);
   if (!hasChanges) {
@@ -133,7 +191,17 @@ function autoCommitWorktreeForFinish(repoRoot, worktreePath, branch, options) {
   return { changed: true, committed: true, message: commitMessage };
 }
 
+/**
+ * Run the worktree-prune sweep with options parsed from `rawArgs`. In watch
+ * mode loops forever (or until `--once`), printing the cycle header and
+ * delegating each cycle to the `worktreePrune` package asset.
+ *
+ * @param {ReadonlyArray<string>} rawArgs CLI argv slice for the cleanup command.
+ * @returns {void}
+ * @throws {Error} When the underlying prune subprocess exits non-zero or the watch sleep fails.
+ */
 function cleanup(rawArgs) {
+  const activeCwd = process.cwd();
   const options = parseCleanupArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
 
@@ -168,7 +236,11 @@ function cleanup(rawArgs) {
   }
 
   const runCleanupCycle = () => {
-    const runResult = runPackageAsset('worktreePrune', args, { cwd: repoRoot, stdio: 'inherit' });
+    const runResult = runPackageAsset('worktreePrune', args, {
+      cwd: repoRoot,
+      stdio: 'inherit',
+      env: { GUARDEX_PRUNE_ACTIVE_CWD: activeCwd },
+    });
     if (runResult.status !== 0) {
       throw new Error('Cleanup command failed');
     }
@@ -198,6 +270,14 @@ function cleanup(rawArgs) {
   process.exitCode = 0;
 }
 
+/**
+ * Dispatch to the `branchMerge` package asset with options parsed from
+ * `rawArgs`. Pipes stdout/stderr through to the parent process.
+ *
+ * @param {ReadonlyArray<string>} rawArgs CLI argv slice for the merge command.
+ * @returns {void}
+ * @throws {Error} When the merge subprocess exits non-zero.
+ */
 function merge(rawArgs) {
   const options = parseMergeArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -233,7 +313,19 @@ function merge(rawArgs) {
   process.exitCode = 0;
 }
 
+/**
+ * Drive the finish flow across one or many agent branches: discover
+ * candidates, auto-commit dirty worktrees, optionally advance submodules,
+ * and invoke `agent-branch-finish` for each branch. Aggregates per-branch
+ * outcomes and prints a single summary line at the end.
+ *
+ * @param {ReadonlyArray<string>} rawArgs CLI argv slice for the finish command.
+ * @param {Partial<FinishOptions>} [defaults] Defaults merged before CLI overrides.
+ * @returns {void}
+ * @throws {Error} When `--branch` references an unknown ref, or when any branch fails to finish (after the loop completes).
+ */
 function finish(rawArgs, defaults = {}) {
+  const activeCwd = process.cwd();
   const options = parseFinishArgs(rawArgs, defaults);
   const repoRoot = resolveRepoRoot(options.target);
 
@@ -279,12 +371,19 @@ function finish(rawArgs, defaults = {}) {
   let succeeded = 0;
   let failed = 0;
   let autoCommitted = 0;
+  const terse = isTerseMode();
 
   for (const candidate of candidates) {
     const { branch, baseBranch, worktreePath } = candidate;
-    console.log(
-      `[${TOOL_NAME}] Finishing '${branch}' -> '${baseBranch}'${worktreePath ? ` (${worktreePath})` : ''}...`,
-    );
+    // In terse mode, defer the "Finishing X -> Y" line until we know whether
+    // we also need to announce an auto-commit, then emit a single combined
+    // line per branch. Keep branch + base + worktree path so agents still see
+    // the load-bearing literals.
+    if (!terse) {
+      console.log(
+        `[${TOOL_NAME}] Finishing '${branch}' -> '${baseBranch}'${worktreePath ? ` (${worktreePath})` : ''}...`,
+      );
+    }
 
     try {
       let commitState = { changed: false, committed: false };
@@ -292,13 +391,49 @@ function finish(rawArgs, defaults = {}) {
         commitState = autoCommitWorktreeForFinish(repoRoot, worktreePath, branch, options);
       }
 
-      if (commitState.committed) {
+      if (terse) {
+        const suffix = commitState.committed
+          ? ' [auto-committed]'
+          : (commitState.changed && commitState.dryRun ? ' [dry-run: would auto-commit]' : '');
+        console.log(
+          `[${TOOL_NAME}] Finishing '${branch}' -> '${baseBranch}'${worktreePath ? ` (${worktreePath})` : ''}${suffix}`,
+        );
+        if (commitState.committed) {
+          autoCommitted += 1;
+        }
+      } else if (commitState.committed) {
         autoCommitted += 1;
         console.log(`[${TOOL_NAME}] Auto-committed '${branch}' before finish.`);
       } else if (commitState.changed && commitState.dryRun) {
         console.log(`[${TOOL_NAME}] [dry-run] Would auto-commit pending changes on '${branch}'.`);
       }
 
+      if (options.advanceSubmodules && worktreePath) {
+        const gitmodulesPath = path.join(worktreePath, '.gitmodules');
+        if (fs.existsSync(gitmodulesPath)) {
+          if (options.dryRun) {
+            const preview = submoduleModule.advance({
+              target: worktreePath,
+              push: false,
+              commit: false,
+              dryRun: true,
+            });
+            console.log(`[${TOOL_NAME}] [dry-run] Would advance submodules for '${branch}':`);
+            submoduleModule.printAdvanceResult(preview);
+          } else {
+            const advanceResult = submoduleModule.advance({
+              target: worktreePath,
+              push: false,
+              commit: true,
+              dryRun: false,
+            });
+            submoduleModule.printAdvanceResult(advanceResult);
+          }
+        } else {
+          console.log(`[${TOOL_NAME}] --advance-submodules ignored: '${branch}' has no .gitmodules.`);
+        }
+      }
+
       const finishArgs = [
         '--branch',
         branch,
@@ -325,7 +460,40 @@ function finish(rawArgs, defaults = {}) {
         continue;
       }
 
-      const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot, stdio: 'pipe' });
+      // Preflight: typecheck + lint touched workspace packages before opening
+      // a PR. Only enforced for PR-mode finishes; bypass with --skip-preflight.
+      if (options.mergeMode === 'pr' && !options.skipPreflight) {
+        const preflight = runPreflight(repoRoot, worktreePath, branch, baseBranch, {
+          verbose: !terse,
+        });
+        console.log(`[${TOOL_NAME}] ${summarizePreflight(preflight)}`);
+        if (preflight.status === 'failed') {
+          for (const f of preflight.failures) {
+            console.error(`[${TOOL_NAME}] preflight failure: ${f.label} (exit ${f.status})`);
+            if (f.stderr && f.stderr.trim()) {
+              console.error(f.stderr.trim());
+            } else if (f.stdout && f.stdout.trim()) {
+              console.error(f.stdout.trim());
+            }
+          }
+          throw new Error(
+            `preflight failed for ${preflight.failures.length} script(s). Fix the failures or rerun with --skip-preflight to bypass.`,
+          );
+        }
+      }
+
+      // Opt-in merge gate (--gate-review / gx ship): enforce a clean AI review +
+      // green CI + GitHub-mergeable verdict BEFORE the shell merge runs. Throws on
+      // failure, which the catch below turns into a finish failure (no merge).
+      if (options.mergeMode === 'pr' && options.gateReview) {
+        runReviewGate({ repoRoot, branch, baseBranch, options });
+      }
+
+      const finishResult = runPackageAsset('branchFinish', finishArgs, {
+        cwd: repoRoot,
+        stdio: 'pipe',
+        env: { GUARDEX_FINISH_ACTIVE_CWD: activeCwd },
+      });
       if (finishResult.stdout) {
         process.stdout.write(finishResult.stdout);
       }
@@ -357,6 +525,17 @@ function finish(rawArgs, defaults = {}) {
   process.exitCode = 0;
 }
 
+/**
+ * Sync the current (or all) agent branches against the configured base
+ * branch using either rebase or merge. Supports `--check`, `--dry-run`,
+ * `--json`, and `--all-agent-branches` modes. Temporarily resets the lock
+ * registry around the sync operation when it is dirty so it does not block
+ * the rebase/merge, then restores the saved contents.
+ *
+ * @param {ReadonlyArray<string>} rawArgs CLI argv slice for the sync command.
+ * @returns {void}
+ * @throws {Error} When the working tree is dirty (without `--allow-dirty`), the lock reset fails, or the underlying rebase/merge fails.
+ */
 function sync(rawArgs) {
   const options = parseSyncArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);

package/src/finish/preflight.js

@@ -0,0 +1,177 @@
+'use strict';
+
+// Pre-ship preflight: before `gx finish --via-pr` opens a PR, walk the diff
+// against the base branch, find which `apps/<pkg>/` workspace packages were
+// touched, and run their `typecheck` + `lint` scripts. If any fail, abort the
+// PR creation — keeps main green so the user's root-worktree dev server (the
+// one they're "visualizing" against) never breaks.
+//
+// Bypass with `--skip-preflight`. Non-monorepo repos (no `apps/<pkg>/package.json`)
+// are silently no-ops.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PREFLIGHT_SCRIPTS = ['typecheck', 'lint'];
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function detectAppPackages(repoRoot) {
+  const appsRoot = path.join(repoRoot, 'apps');
+  let stat;
+  try {
+    stat = fs.statSync(appsRoot);
+  } catch {
+    return [];
+  }
+  if (!stat.isDirectory()) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(appsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const packages = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const pkgPath = path.join(appsRoot, e.name, 'package.json');
+    const pkg = readJson(pkgPath);
+    if (!pkg) continue;
+    packages.push({
+      dir: `apps/${e.name}`,
+      name: pkg.name || e.name,
+      scripts: pkg.scripts || {},
+    });
+  }
+  return packages;
+}
+
+function detectTouchedDirs(workingDir, baseBranch, branch) {
+  const ref = baseBranch
+    ? `${baseBranch}...${branch || 'HEAD'}`
+    : (branch || 'HEAD');
+  const diff = spawnSync('git', ['-C', workingDir, 'diff', '--name-only', ref], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 15_000,
+  });
+  if (diff.status !== 0) {
+    // Try a fallback range with the local base.
+    const fallback = spawnSync(
+      'git',
+      ['-C', workingDir, 'diff', '--name-only', 'HEAD'],
+      { stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000 },
+    );
+    if (fallback.status !== 0) return null;
+    return (fallback.stdout || '').toString().split('\n').filter(Boolean);
+  }
+  return (diff.stdout || '').toString().split('\n').filter(Boolean);
+}
+
+function pickPackageManager(repoRoot) {
+  // Prefer pnpm if a lockfile exists; fall back to npm.
+  if (fs.existsSync(path.join(repoRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(repoRoot, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function buildScriptInvocation(pm, pkgName, script) {
+  if (pm === 'pnpm') return { cmd: 'pnpm', args: ['--filter', pkgName, script] };
+  if (pm === 'yarn') return { cmd: 'yarn', args: ['workspace', pkgName, 'run', script] };
+  return { cmd: 'npm', args: ['--workspace', pkgName, 'run', script] };
+}
+
+function runPreflight(repoRoot, worktreePath, branch, baseBranch, options = {}) {
+  const workingDir = worktreePath || repoRoot;
+  const packages = detectAppPackages(repoRoot);
+  if (packages.length === 0) {
+    return { status: 'skipped', reason: 'no-monorepo', failures: [], ran: [] };
+  }
+
+  const touchedFiles = detectTouchedDirs(workingDir, baseBranch, branch);
+  if (touchedFiles === null) {
+    return {
+      status: 'skipped',
+      reason: 'diff-unavailable',
+      failures: [],
+      ran: [],
+    };
+  }
+
+  const touchedPkgs = packages.filter((pkg) =>
+    touchedFiles.some((file) => file.startsWith(pkg.dir + '/')),
+  );
+  if (touchedPkgs.length === 0) {
+    return {
+      status: 'skipped',
+      reason: 'no-app-changes',
+      failures: [],
+      ran: [],
+    };
+  }
+
+  const pm = pickPackageManager(repoRoot);
+  const ran = [];
+  const failures = [];
+  for (const pkg of touchedPkgs) {
+    for (const script of PREFLIGHT_SCRIPTS) {
+      if (!pkg.scripts[script]) continue;
+      const { cmd, args } = buildScriptInvocation(pm, pkg.name, script);
+      const label = `${pkg.name}:${script}`;
+      if (options.verbose) {
+        process.stdout.write(`[preflight] running ${label}…\n`);
+      }
+      const result = spawnSync(cmd, args, {
+        cwd: repoRoot,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 5 * 60_000,
+      });
+      const stdout = (result.stdout || '').toString();
+      const stderr = (result.stderr || '').toString();
+      const ok = !result.error && result.status === 0;
+      ran.push({ label, ok, status: result.status, cmd, args });
+      if (!ok) {
+        failures.push({
+          label,
+          status: result.status,
+          stdout: stdout.slice(-2000),
+          stderr: stderr.slice(-2000),
+          error: result.error ? result.error.message : null,
+        });
+      }
+    }
+  }
+
+  return {
+    status: failures.length === 0 ? 'ok' : 'failed',
+    reason: failures.length === 0 ? 'all-passed' : 'script-failures',
+    packageManager: pm,
+    touched: touchedPkgs.map((p) => p.name),
+    ran,
+    failures,
+  };
+}
+
+function summarizePreflight(result) {
+  if (result.status === 'skipped') {
+    return `[preflight] skipped (${result.reason})`;
+  }
+  const tail = result.ran
+    .map((r) => `${r.ok ? '✓' : '✗'} ${r.label}`)
+    .join(', ');
+  return `[preflight] ${result.status} — ${tail}`;
+}
+
+module.exports = {
+  detectAppPackages,
+  detectTouchedDirs,
+  pickPackageManager,
+  runPreflight,
+  summarizePreflight,
+};

package/src/finish/review-gate.js

@@ -0,0 +1,182 @@
+// Opt-in merge gate for `gx branch finish --gate-review` / `gx ship`.
+//
+// `gx branch finish` trusts server-side branch protection for the actual merge,
+// which can fail open (it merged PR #610 to main with red preflight tests). When
+// `--gate-review` is set, this module enforces a REAL local gate BEFORE the merge
+// runs: a clean AI review (fail-closed) AND green CI AND GitHub reporting the PR
+// mergeable under branch protection. It throws to block; the finish() catch then
+// skips the merge for that branch. Synchronous, to match finish().
+
+const { run } = require('../core/runtime');
+const { TOOL_NAME } = require('../context');
+const pr = require('../pr');
+const prReview = require('../pr-review');
+
+const DEFAULT_GATE_TIMEOUT_SECONDS = 1800; // 30 min — CI can be slow.
+const DEFAULT_GATE_POLL_SECONDS = 15;
+const DEFAULT_NO_CHECKS_GRACE_SECONDS = 60; // let CI register check runs after promote.
+// GitHub mergeStateStatus values that mean "mergeable under current protection".
+const MERGEABLE_STATES = new Set(['CLEAN', 'HAS_HOOKS']);
+// mergeStateStatus values that mean "GitHub will not allow this merge as-is".
+// UNSTABLE = a non-required check is failing/pending; BLOCKED = required review/
+// check unmet; DIRTY = conflicts; BEHIND = base moved. All fail closed.
+const BLOCKED_STATES = new Set(['DIRTY', 'BLOCKED', 'BEHIND', 'UNSTABLE']);
+
+function gateLog(message) {
+  console.log(`[${TOOL_NAME}] [gate] ${message}`);
+}
+
+/**
+ * Poll the PR's CI until it settles. Fail-closed: red checks, timeout, or a
+ * check-less PR (after a grace window) all return a non-green status the caller
+ * turns into a block. A just-promoted PR whose checks have not registered yet
+ * keeps polling rather than being misread as check-less.
+ *
+ * Fail-closed semantics:
+ *  - any failed OR cancelled check blocks (a cancelled required check is NOT a pass);
+ *  - GitHub's mergeStateStatus is authoritative — BLOCKED/DIRTY/BEHIND/UNSTABLE block;
+ *  - when GitHub gives no verdict (mss absent/UNKNOWN) we require EVERY check to be an
+ *    explicit success (no `other` states like ACTION_REQUIRED slipping through);
+ *  - a check-less PR is only declared `no-checks` after a grace window, so a freshly
+ *    promoted PR whose checks have not registered yet is not misread.
+ *
+ * @returns {{status: 'green'|'checks-failed'|'merge-blocked'|'no-checks'|'timeout'|'no-pr', pr?: object}}
+ */
+function waitForGreenCi(repoRoot, branch, options = {}) {
+  const timeoutSeconds = options.timeoutSeconds || DEFAULT_GATE_TIMEOUT_SECONDS;
+  const pollSeconds = options.pollSeconds || DEFAULT_GATE_POLL_SECONDS;
+  const requireChecks = options.requireChecks !== false;
+  const graceSeconds = options.noChecksGraceSeconds || DEFAULT_NO_CHECKS_GRACE_SECONDS;
+  const sleep = options.sleep || ((seconds) => run('sleep', [String(seconds)], { cwd: repoRoot }));
+  const now = options.now || (() => Date.now());
+  const getStatus = options.getStatus || ((r, b) => pr.getPullRequestStatus(r, b));
+
+  const start = now();
+  const deadline = start + timeoutSeconds * 1000;
+  const graceDeadline = start + graceSeconds * 1000;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const snap = getStatus(repoRoot, branch);
+    if (!snap) return { status: 'no-pr' };
+    const c = snap.checks;
+    // A failed or cancelled check is terminal and never a pass.
+    if (c.failed > 0 || c.cancelled > 0) return { status: 'checks-failed', pr: snap };
+
+    const mss = snap.mergeStateStatus;
+    // GitHub says this can't merge as-is and won't self-resolve within a finish run.
+    if (mss && BLOCKED_STATES.has(mss)) return { status: 'merge-blocked', pr: snap };
+
+    const settled = c.pending === 0;
+    const mergeable = !snap.isDraft && snap.mergeable === 'MERGEABLE';
+    const hasChecks = c.total > 0;
+    // Trust GitHub's CLEAN/HAS_HOOKS verdict; with no verdict, demand all-success
+    // (every check SUCCESS, zero `other`/ambiguous states).
+    const trusted = mss
+      ? MERGEABLE_STATES.has(mss)
+      : (c.other === 0 && c.success === c.total);
+
+    if (settled && mergeable && hasChecks && trusted) return { status: 'green', pr: snap };
+    if (settled && mergeable && !hasChecks && (mss ? MERGEABLE_STATES.has(mss) : true)) {
+      if (!requireChecks) return { status: 'green', pr: snap };
+      // No checks yet — give CI a grace window to create check runs before
+      // concluding the PR is genuinely check-less (avoids the promote->merge race).
+      if (now() >= graceDeadline) return { status: 'no-checks', pr: snap };
+    }
+    if (now() >= deadline) return { status: 'timeout', pr: snap };
+    sleep(pollSeconds);
+  }
+}
+
+/**
+ * Enforce the merge gate for `branch`. Throws (blocking the merge) unless the PR
+ * passes a clean AI review AND green CI AND GitHub reports it mergeable. Returns
+ * `{ prNumber }` on pass; the caller then proceeds to the real merge.
+ */
+function runReviewGate({ repoRoot, branch, baseBranch, options = {} }, deps = {}) {
+  const openPullRequest = deps.openPullRequest || pr.openPullRequest;
+  const runPrReview = deps.runPrReview || prReview.runPrReview;
+  const markReady = deps.markPullRequestReady || pr.markPullRequestReady;
+  const evaluate = deps.evaluateReviewGate || prReview.evaluateReviewGate;
+  const waitGreen = deps.waitForGreenCi || waitForGreenCi;
+
+  const provider = options.reviewProvider || 'codex';
+  const requireChecks = !options.allowNoChecks;
+
+  // 1. Ensure a PR exists (push + open as draft so CI is deferred until the
+  //    review passes and we explicitly promote).
+  const opened = openPullRequest({ repoRoot, branch, base: baseBranch, push: true });
+  const prNumber = opened.pr.number;
+  gateLog(`PR #${prNumber}: enforcing review + CI gate before merge`);
+
+  // 2. AI review — FAIL CLOSED. A provider error / timeout / unparseable output
+  //    throws here; convert it to a block, never a silent pass.
+  let review;
+  try {
+    review = runPrReview({ target: repoRoot, pr: prNumber, provider, post: true });
+  } catch (err) {
+    throw new Error(
+      `review gate: AI review did not complete (${err.message}). Refusing to merge. `
+      + 'Fix the provider/auth issue or rerun with --skip-review-gate.',
+    );
+  }
+  const verdict = evaluate(review.findings);
+  if (!verdict.clean) {
+    const detail = verdict.blocking
+      .map((f) => `  - ${String(f.severity).toUpperCase()} ${f.path}:${f.line} ${f.message}`)
+      .join('\n');
+    throw new Error(
+      `review gate: ${verdict.blocking.length} blocking finding(s). Refusing to merge.\n${detail}\n`
+      + 'Fix the findings or rerun with --skip-review-gate.',
+    );
+  }
+  gateLog(
+    `PR #${prNumber}: review clean (${review.findings.length} non-blocking finding(s))`
+    + (review.reason === 'github-auth-unavailable' ? ' [not posted: github-auth-unavailable]' : ''),
+  );
+
+  // 3. Promote draft -> ready so required CI checks fire.
+  markReady(repoRoot, prNumber);
+
+  // 4. Wait for CI to settle green + GitHub to report mergeable. waitForGreenCi
+  //    is fully fail-closed (failed/cancelled checks, blocked mergeStateStatus,
+  //    timeout, and check-less PRs all return non-green statuses).
+  const ci = waitGreen(repoRoot, branch, {
+    timeoutSeconds: options.gateTimeoutSeconds,
+    pollSeconds: options.gatePollSeconds,
+    requireChecks,
+  });
+  if (ci.status === 'checks-failed') {
+    throw new Error(`review gate: CI checks failed/cancelled on PR #${prNumber}. Refusing to merge.`);
+  }
+  if (ci.status === 'merge-blocked') {
+    const mss = (ci.pr && ci.pr.mergeStateStatus) || 'BLOCKED';
+    throw new Error(
+      `review gate: GitHub reports mergeStateStatus=${mss} for PR #${prNumber} `
+      + '(not mergeable under branch protection). Refusing to merge.',
+    );
+  }
+  if (ci.status === 'no-checks') {
+    throw new Error(
+      `review gate: PR #${prNumber} has no CI checks configured. Refusing to merge an `
+      + 'unverified PR. Pass --allow-no-checks to override.',
+    );
+  }
+  if (ci.status === 'timeout') {
+    throw new Error(`review gate: timed out waiting for CI to go green on PR #${prNumber}.`);
+  }
+  if (ci.status !== 'green') {
+    throw new Error(`review gate: PR #${prNumber} not in a mergeable state (${ci.status}).`);
+  }
+
+  const mss = ci.pr && ci.pr.mergeStateStatus;
+  gateLog(`PR #${prNumber}: review clean + CI green${mss ? ` + mergeStateStatus=${mss}` : ''} — proceeding to merge`);
+  return { prNumber };
+}
+
+module.exports = {
+  runReviewGate,
+  waitForGreenCi,
+  DEFAULT_GATE_TIMEOUT_SECONDS,
+  MERGEABLE_STATES,
+};