@goodtek/vibeops 2.5.1 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to VibeOps are documented here.
 
 ## Unreleased
 
+## 3.0.0 - 2026-10-03
+
+### Breaking changes
+
+- **`task merge` / `task release` refuse to merge a PR/MR with no checks at all** (default `merge.allowNoChecks: false`). Previously such PRs merged.
+  **Migration (repos without CI):** add to `.vibeops.json`:
+  ```json
+  { "merge": { "allowNoChecks": true } }
+  ```
+  A warning is printed on each such merge.
+- **Requires gh ≥ 2.13.0** (`gh pr merge --match-head-commit`). Check with `gh --version`; upgrade e.g. `brew upgrade gh`.
+- **Invalid `.vibeops.json` `merge` block** (non-object, unknown key, wrong type, out-of-range number) makes `task merge` / `task release` exit 1.
+
+### Fixed
+
+- **`task merge` / `task release` (GitHub):** GitHub Actions checks (`CheckRun`) were read from a `state` field they do not have, so a **failed Actions check counted as green** and the PR merged. Checks are now classified from `status` + `conclusion` (CheckRun) and `state` (StatusContext); missing or undocumented values fail closed.
+- **`task merge` / `task release` (GitLab):** `manual` and unknown head-pipeline statuses no longer count as mergeable; `scheduled` / `waiting_for_callback` / `canceling` count as running. A `405` on merge no longer falls back to scheduling auto-merge; it re-runs the gate and retries once with `--auto-merge=false`.
+
+### Added
+
+- **Merge gate:** refuse on any failed check (immediately), wait bounded on pending checks then refuse, refuse on merge conflicts. No override flag. Merges are pinned to the checked commit (`gh pr merge --match-head-commit`, `glab mr merge --sha`).
+- **`.vibeops.json` `merge` block:** `requiredChecks`, `releaseRequiredChecks` (exact or `*` glob; absent → `required check "X" never ran`), `waitTimeoutSeconds` (900), `pollIntervalSeconds` (5), `emptyRollupGraceSeconds` (30), `allowNoChecks` (false). Strictly validated; `task release --dry-run` shows the release required checks.
+
+### Behaviour changes
+
+- No checks at all: refused after a 30 s grace (`emptyRollupGraceSeconds`) for checks not registered yet — see Breaking changes.
+- **Host output is verified:** missing or empty `state` / `mergeable` / `headRefOid` / `statusCheckRollup` from `gh pr view` (GitLab: `state` / `sha` / `merge_status` / `detailed_merge_status` / `head_pipeline`) refuses the merge instead of being treated as green.
+- **GitLab `manual` head pipelines refuse** (previously merged when the MR was otherwise mergeable).
+- **Pending checks are always waited for** on `task merge` / `task release` (up to `waitTimeoutSeconds`); a PR whose checks are still running is no longer merged or auto-merge-scheduled.
+- `glab mr merge --sha` verified with glab 1.106.
+
+## 2.5.2 - 2026-07-20
+
+### Fixed
+
+- **`task add` / integration sync:** Governance-only dirt (`.vibeops.json`, `AGENTS.md`, `.vibeops/`, docs, `.cursor/rules/`) no longer blocks preflight. Right after `init`, `task add` works without stash. App-file dirt still fails and lists the blocking paths.
+
 ## 2.5.1 - 2026-07-20
 
 ### Fixed

package/README.md

@@ -111,7 +111,7 @@ vibeops task release
 
 Only one TASK **In Progress** at a time (`task add` blocks otherwise). **Shipped** slices do not block the next add; merge on the host or with `task merge`, then optional `task sync`.
 
-`task add` fast-forward-pulls the integration branch first. If that fails (diverged / dirty / local-ahead), it prints the cause and fix commands and **does not** create a TASK file. If a previous run left a TASK file without a branch, rerun `task add` to resume.
+`task add` fast-forward-pulls the integration branch first. If that fails (diverged / **app** dirty / local-ahead), it prints the cause and fix commands and **does not** create a TASK file. VibeOps/governance-only changes (e.g. `.vibeops.json` after `init`) do **not** block. If a previous run left a TASK file without a branch, rerun `task add` to resume.
 
 ## Status
 
@@ -155,13 +155,60 @@ vibeops llm use auto   # auto | codex-oauth | cursor-agent | openai
 - **Init** records branch policy in `.vibeops.json` (`integrationBranch`, `productionBranch`, `host`). Interactive remote setup: ask GitHub/GitLab, create or connect; soft-gate when `gh`/`glab` is missing.
 - **`task add`**: `task/<slug>` from **integration** (e.g. `develop`).
 - **`task ship`** (state-aware): **no PR** → commit + ship metadata (Status **Shipped**) → push → open MR/PR; **open PR** → commit + push the same branch, CI re-runs, no new PR; **merged PR** → new PR cycle (carries uncommitted work onto the task branch, integrates `develop`, opens a **new** PR). Use `--new-cycle` in non-interactive mode. Commit messages are TASK-id-scoped (`feat(task-001): …`). Refuses when HEAD is not the task branch.
-- **`task merge`**: merge MR/PR into integration (CLI or host UI; TASK md unchanged).
+- **`task merge`**: merge MR/PR into integration (TASK md unchanged) — **only when every check is green** (see [Merge gate](#merge-gate)).
 - **`task sync`**: integration ff-only pull → delete `task/*` branches (TASK md unchanged).
 - **`pull`**: fetch + switch to integration branch + `git pull --ff-only` (one command).
 - **`task release`**: integration → production PR + merge (skipped on trunk policy).
 - **`status`**: Now / Next card — focus stage, checklist, PR, and the next command to run.
 - No force-push to shared branches.
 
+## Merge gate
+
+> **3.0.0 breaking:** a PR/MR with **no checks at all** is refused by default. Repos without CI: set `"merge": {"allowNoChecks": true}` in `.vibeops.json`. Requires **gh ≥ 2.13.0**.
+
+`task merge` and `task release` are a client-side CI gate (useful when the host plan has no branch protection / required checks, e.g. private GitHub repos on the free plan). **Where server-side branch protection / required checks are available, enable them — the host remains the final authority;** this gate only stops VibeOps itself from merging red work (a human can still merge in the host UI).
+
+Before calling `gh pr merge` / `glab mr merge`:
+
+- **GitHub:** every item in the PR `statusCheckRollup` is classified from GitHub's documented enums — `CheckRun` (Actions) by `status` + `conclusion`, `StatusContext` by `state`:
+  - **passed:** `SUCCESS`, `NEUTRAL`, `SKIPPED`
+  - **failed:** `FAILURE`, `CANCELLED`, `TIMED_OUT`, `ACTION_REQUIRED`, `STARTUP_FAILURE`, `STALE`, `ERROR`
+  - **pending:** CheckRun `REQUESTED`, `QUEUED`, `IN_PROGRESS`, `WAITING`, `PENDING`; StatusContext `PENDING`, `EXPECTED`
+  - **anything missing or undocumented fails closed** (treated as failed). Several checks with the same name: any failure fails.
+- **GitLab:** the MR head pipeline must be `success` or `skipped`. `failed`, `canceled`, `manual` and unknown statuses refuse; `created` / `pending` / `running` / `scheduled` / … wait.
+- **Host output is verified:** if `gh pr view` lacks or has empty `state`, `mergeable`, `headRefOid`, or `statusCheckRollup` is not a list (GitLab: `state`, `sha`, `merge_status`, `detailed_merge_status`, `head_pipeline`), the merge is refused.
+- **Failed check → refuse immediately** (exit code 1, checks named). **Pending → wait** up to `waitTimeoutSeconds`, then refuse. There is no override flag: fix CI (re-run `task ship`) and rerun `task merge`.
+- **No checks at all → refuse** (after `emptyRollupGraceSeconds`, which covers checks not yet registered right after a push) unless `allowNoChecks: true`.
+- **The merge is pinned to the checked commit:** `gh pr merge --match-head-commit <sha>` (requires **gh ≥ 2.13.0**) / `glab mr merge --auto-merge=false --sha <sha>` (verified with glab 1.106). A push after the check makes the host refuse. A GitLab `405` re-runs the gate and retries once with the same flags.
+
+### Configuration (`.vibeops.json` → `merge`)
+
+```json
+{
+  "merge": {
+    "requiredChecks": ["build", "lint*"],
+    "releaseRequiredChecks": ["release smoke"],
+    "waitTimeoutSeconds": 900,
+    "pollIntervalSeconds": 5,
+    "emptyRollupGraceSeconds": 30,
+    "allowNoChecks": false
+  }
+}
+```
+
+| Key | Default | Allowed | Meaning |
+|-----|---------|---------|---------|
+| `requiredChecks` | `[]` | array of non-empty strings | Checks that must be present and green for `task merge`. A missing one refuses: `required check "X" never ran`. |
+| `releaseRequiredChecks` | `[]` | array of non-empty strings | Same for `task release` (integration → production). Shown by `task release --dry-run`. |
+| `waitTimeoutSeconds` | `900` | integer 1–7200 | Max wait for pending checks. |
+| `pollIntervalSeconds` | `5` | integer 1–300, ≤ timeout | Poll interval while waiting. |
+| `emptyRollupGraceSeconds` | `30` | integer 0–600 | How long an empty check list is re-polled before "no checks" applies. |
+| `allowNoChecks` | `false` | boolean | Merge a PR that has no checks at all (repo without CI). Prints one warning per such merge. |
+
+- Check names are exact (`CheckRun.name` / `StatusContext.context`) or a `*` glob (`"lint*"`, `"* · linux"`). Required checks are GitHub-only; GitLab gates on the head pipeline.
+- The block is validated strictly: it must be an object, unknown keys (typos) and wrong types are errors, and `task merge` / `task release` exit 1 naming the key.
+- **Recommended:** list your CI jobs in `requiredChecks`. Without it, the gate only sees the checks that happened to start — a workflow that never triggers is invisible.
+
 ## License
 
 MIT

package/dist/commands/task-merge.js

@@ -1,12 +1,13 @@
 import { resolve } from "node:path";
 import { GitConfigError, requireGitConfig } from "../lib/git-config.js";
+import { MergeConfigError, mergeGateTiming, readMergeConfig } from "../lib/merge-config.js";
 import { formatHostCliHint, formatHostCliMissingMessage } from "../lib/git-host-cli.js";
 import { detectGitHost, mergeRequestLabel } from "../lib/git-host.js";
 import { gitRemoteUrl } from "../lib/git.js";
 import { bold, cyan, dim, log } from "../lib/logger.js";
 import { projectPaths } from "../lib/paths.js";
 import { taskNotFoundMessage } from "../lib/resolve-task.js";
-import { getMergeRequestState, mergeMergeRequest, probeMergeRequestCli, } from "../lib/pr-create.js";
+import { getMergeRequestState, MergeGateError, mergeMergeRequest, probeMergeRequestCli, } from "../lib/pr-create.js";
 import { assertMergeRequestMerged } from "../lib/task-merge-verify.js";
 import { relPath } from "../lib/task-context.js";
 import { resolveLifecycleTarget } from "../lib/task-lifecycle-target.js";
@@ -19,6 +20,12 @@ function resolveMergeMethod(opts) {
         return "merge";
     return "squash";
 }
+function mergeFailureHint(error) {
+    if (error instanceof MergeGateError) {
+        return "Not merged. Fix the failing checks (re-run `vibeops task ship` to push a fix and re-run CI), then rerun `vibeops task merge`.";
+    }
+    return "Merge in the host UI if branch protection blocks CLI merge.";
+}
 export async function taskMergeCommand(taskRef, options = {}) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const dryRun = options.dryRun === true;
@@ -35,6 +42,20 @@ export async function taskMergeCommand(taskRef, options = {}) {
         }
         throw e;
     }
+    let mergeCfg;
+    try {
+        mergeCfg = await readMergeConfig(cwd);
+    }
+    catch (e) {
+        if (e instanceof MergeConfigError) {
+            log.error(e.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw e;
+    }
+    const requiredChecks = mergeCfg.requiredChecks;
+    const gate = { ...mergeGateTiming(mergeCfg), allowNoChecks: mergeCfg.allowNoChecks };
     const target = await resolveLifecycleTarget(paths, cwd, taskRef);
     if (target === null) {
         if (taskRef?.trim()) {
@@ -74,6 +95,7 @@ export async function taskMergeCommand(taskRef, options = {}) {
     log.info(`  ${dim("MR/PR")}      ${mergeRequestUrl}`);
     log.info(`  ${dim("target")}     ${ctx.baseBranch} (${gitCfg.integrationBranch})`);
     log.info(`  ${dim("method")}     ${method}`);
+    log.info(`  ${dim("checks")}     all green${requiredChecks.length > 0 ? ` + required: ${requiredChecks.join(", ")}` : ""}${mergeCfg.allowNoChecks ? dim(" (allowNoChecks: true)") : ""}`);
     log.blank();
     if (dryRun) {
         await mergeMergeRequest({
@@ -81,6 +103,8 @@ export async function taskMergeCommand(taskRef, options = {}) {
             host,
             url: mergeRequestUrl,
             method,
+            requiredChecks,
+            gate,
             dryRun: true,
         });
         log.blank();
@@ -112,7 +136,8 @@ export async function taskMergeCommand(taskRef, options = {}) {
                 url: mergeRequestUrl,
                 method,
                 waitForCi: true,
-                immediate: true,
+                requiredChecks,
+                gate,
             });
             const verified = await assertMergeRequestMerged({
                 cwd,
@@ -130,7 +155,7 @@ export async function taskMergeCommand(taskRef, options = {}) {
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
             log.error(`Merge failed: ${msg}`);
-            log.info(dim("Merge in the host UI if branch protection blocks CLI merge."));
+            log.info(dim(mergeFailureHint(e)));
             process.exitCode = 1;
             return;
         }
@@ -149,7 +174,8 @@ export async function taskMergeCommand(taskRef, options = {}) {
                 url: mergeRequestUrl,
                 method,
                 waitForCi: true,
-                immediate: true,
+                requiredChecks,
+                gate,
             });
             const verified = await assertMergeRequestMerged({
                 cwd,
@@ -167,6 +193,7 @@ export async function taskMergeCommand(taskRef, options = {}) {
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
             log.error(`Merge failed: ${msg}`);
+            log.info(dim(mergeFailureHint(e)));
             process.exitCode = 1;
             return;
         }

package/dist/commands/task-release.js

@@ -1,10 +1,11 @@
 import { resolve } from "node:path";
 import { GitConfigError, requireGitConfig } from "../lib/git-config.js";
+import { MergeConfigError, mergeGateTiming, readMergeConfig } from "../lib/merge-config.js";
 import { formatHostCliHint, formatHostCliMissingMessage } from "../lib/git-host-cli.js";
 import { detectGitHost, mergeRequestLabel } from "../lib/git-host.js";
 import { gitRemoteUrl } from "../lib/git.js";
 import { bold, dim, log } from "../lib/logger.js";
-import { createMergeRequest, getMergeRequestState, mergeMergeRequest, probeMergeRequestCli, } from "../lib/pr-create.js";
+import { createMergeRequest, getMergeRequestState, MergeGateError, mergeMergeRequest, probeMergeRequestCli, } from "../lib/pr-create.js";
 import { assertMergeRequestMerged } from "../lib/task-merge-verify.js";
 function resolveReleaseMergeMethod(opts) {
     if (opts.rebase === true)
@@ -29,6 +30,19 @@ export async function taskReleaseCommand(options = {}) {
         throw e;
     }
     const { integrationBranch, productionBranch, remote } = gitCfg;
+    let mergeCfg;
+    try {
+        mergeCfg = await readMergeConfig(cwd);
+    }
+    catch (e) {
+        if (e instanceof MergeConfigError) {
+            log.error(e.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw e;
+    }
+    const requiredChecks = mergeCfg.releaseRequiredChecks;
     if (integrationBranch === productionBranch) {
         log.info("Trunk policy: integration and production are the same branch — no release PR step.");
         return;
@@ -52,7 +66,11 @@ export async function taskReleaseCommand(options = {}) {
         log.info(bold("dry-run — would:"));
         log.info(`  · ${label}: ${integrationBranch} → ${productionBranch}`);
         if (options.noMerge !== true) {
-            log.info(`  · merge ${label} (${resolveReleaseMergeMethod(options)}, wait for CI)`);
+            log.info(`  · merge ${label} (${resolveReleaseMergeMethod(options)}) only when all checks are green`);
+            log.info(`  · required checks: ${requiredChecks.length > 0 ? requiredChecks.join(", ") : "(none configured)"}`);
+            if (mergeCfg.allowNoChecks) {
+                log.info("  · allowNoChecks: true (a release PR with no checks would merge)");
+            }
         }
         return;
     }
@@ -101,7 +119,8 @@ export async function taskReleaseCommand(options = {}) {
             url: releaseUrl,
             method,
             waitForCi: true,
-            immediate: true,
+            requiredChecks,
+            gate: { ...mergeGateTiming(mergeCfg), allowNoChecks: mergeCfg.allowNoChecks },
         });
         const verified = await assertMergeRequestMerged({
             cwd,
@@ -119,7 +138,12 @@ export async function taskReleaseCommand(options = {}) {
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         log.error(`Release merge failed: ${msg}`);
-        log.info(dim(`Complete merge in the host UI: ${releaseUrl}`));
+        if (e instanceof MergeGateError) {
+            log.info(dim(`Not merged. Fix the failing checks on ${releaseUrl}, then rerun task release.`));
+        }
+        else {
+            log.info(dim(`Complete merge in the host UI: ${releaseUrl}`));
+        }
         process.exitCode = 1;
     }
 }

package/dist/lib/check-rollup.js

@@ -0,0 +1,128 @@
+/**
+ * Classify GitHub `statusCheckRollup` items and evaluate the merge gate
+ * (`task merge` / `task release` refuse to merge on red or missing checks).
+ *
+ * GitHub returns two item shapes:
+ * - `CheckRun` (GitHub Actions, check apps): `status` + `conclusion`, no `state`.
+ * - `StatusContext` (commit status API): `state`, no `status`/`conclusion`.
+ */
+/** GitHub GraphQL `CheckStatusState` values other than COMPLETED. */
+const CHECK_RUN_IN_FLIGHT = new Set(["REQUESTED", "QUEUED", "IN_PROGRESS", "WAITING", "PENDING"]);
+/** GitHub GraphQL `CheckConclusionState`, split into pass / fail (exhaustive). */
+const CHECK_RUN_PASS = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
+const CHECK_RUN_FAIL = new Set([
+    "FAILURE",
+    "CANCELLED",
+    "TIMED_OUT",
+    "ACTION_REQUIRED",
+    "STARTUP_FAILURE",
+    "STALE",
+]);
+/** GitHub GraphQL `StatusState` (exhaustive): SUCCESS | PENDING | EXPECTED | FAILURE | ERROR. */
+const STATUS_CONTEXT_PENDING = new Set(["PENDING", "EXPECTED"]);
+const STATUS_CONTEXT_FAIL = new Set(["FAILURE", "ERROR"]);
+function upper(raw) {
+    return (raw ?? "").trim().toUpperCase();
+}
+function isCheckRun(item) {
+    if (item.__typename === "CheckRun")
+        return true;
+    if (item.__typename === "StatusContext")
+        return false;
+    // Unknown typename: infer from fields.
+    return (item.status ?? null) !== null || (item.conclusion ?? null) !== null;
+}
+export function classifyRollupItem(item) {
+    if (isCheckRun(item)) {
+        const name = (item.name ?? "").trim() || "(unnamed check run)";
+        const status = upper(item.status);
+        const conclusion = upper(item.conclusion);
+        if (CHECK_RUN_IN_FLIGHT.has(status)) {
+            return { name, kind: "CheckRun", verdict: "pending", detail: status };
+        }
+        if (status !== "COMPLETED") {
+            // Missing or undocumented status — fail closed.
+            return { name, kind: "CheckRun", verdict: "failed", detail: status || "MISSING_STATUS" };
+        }
+        if (CHECK_RUN_PASS.has(conclusion)) {
+            return { name, kind: "CheckRun", verdict: "passed", detail: conclusion };
+        }
+        if (CHECK_RUN_FAIL.has(conclusion)) {
+            return { name, kind: "CheckRun", verdict: "failed", detail: conclusion };
+        }
+        // Completed with a missing or undocumented conclusion — fail closed.
+        return {
+            name,
+            kind: "CheckRun",
+            verdict: "failed",
+            detail: conclusion || "MISSING_CONCLUSION",
+        };
+    }
+    const name = (item.context ?? item.name ?? "").trim() || "(unnamed status)";
+    const state = upper(item.state);
+    if (state === "SUCCESS") {
+        return { name, kind: "StatusContext", verdict: "passed", detail: state };
+    }
+    if (STATUS_CONTEXT_PENDING.has(state)) {
+        return { name, kind: "StatusContext", verdict: "pending", detail: state };
+    }
+    if (STATUS_CONTEXT_FAIL.has(state)) {
+        return { name, kind: "StatusContext", verdict: "failed", detail: state };
+    }
+    // Missing or undocumented state — fail closed.
+    return { name, kind: "StatusContext", verdict: "failed", detail: state || "MISSING_STATE" };
+}
+export function classifyRollup(items) {
+    return (items ?? []).map(classifyRollupItem);
+}
+/** Exact name, or a `*` glob (e.g. `lint*`, `* · linux`). */
+export function checkNameMatches(name, pattern) {
+    const p = pattern.trim();
+    if (p.length === 0)
+        return false;
+    if (!p.includes("*"))
+        return name === p;
+    const re = new RegExp(`^${p
+        .split("*")
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*")}$`);
+    return re.test(name);
+}
+/**
+ * Evaluate classified checks against optional required patterns.
+ * - any failed → red
+ * - any pending, or a required check not (yet) present → pending
+ * - otherwise green (including "no checks at all" when nothing is required)
+ */
+export function evaluateCheckGate(checks, requiredChecks = []) {
+    const failed = checks.filter((c) => c.verdict === "failed");
+    const pending = checks.filter((c) => c.verdict === "pending");
+    const passed = checks.filter((c) => c.verdict === "passed");
+    const missingRequired = requiredChecks
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+        .filter((p) => !checks.some((c) => checkNameMatches(c.name, p)));
+    let state = "green";
+    if (failed.length > 0)
+        state = "red";
+    else if (pending.length > 0 || missingRequired.length > 0)
+        state = "pending";
+    return { state, failed, pending, passed, missingRequired };
+}
+function describe(c) {
+    return `"${c.name}" (${c.detail})`;
+}
+/** Human-readable lines for a refused merge. */
+export function formatCheckGateProblems(gate) {
+    const lines = [];
+    if (gate.failed.length > 0) {
+        lines.push(`failed checks: ${gate.failed.map(describe).join(", ")}`);
+    }
+    if (gate.pending.length > 0) {
+        lines.push(`checks still pending: ${gate.pending.map(describe).join(", ")}`);
+    }
+    for (const p of gate.missingRequired) {
+        lines.push(`required check "${p}" never ran`);
+    }
+    return lines;
+}

package/dist/lib/config.js

@@ -64,6 +64,7 @@ export async function readConfig(root) {
             parsed.schemaVersion === VIBEOPS_CONFIG_SCHEMA_VERSION) {
             const llm = parseLlmBlock(parsed.llm);
             const git = parseGitBlock(parsed.git);
+            const merge = parsed.merge;
             const clients = parseClientsBlock(parsed.clients) ?? ["cursor"];
             return {
                 name: parsed.name,
@@ -73,6 +74,7 @@ export async function readConfig(root) {
                 clients,
                 ...(git ? { git } : {}),
                 ...(llm ? { llm } : {}),
+                ...(merge !== undefined ? { merge } : {}),
             };
         }
         return null;
@@ -90,6 +92,7 @@ export function buildConfig(name, clients, git, existing, nowIso) {
         clients,
         git,
         llm: existing?.llm ?? { provider: "auto" },
+        ...(existing?.merge !== undefined ? { merge: existing.merge } : {}),
     };
 }
 export function configToJson(config) {

package/dist/lib/git-integration-sync.js

@@ -1,4 +1,4 @@
-import { gitFetchRemote, gitLeftRightCount, gitPullFastForwardOnly, gitRemoteBranchExists, gitRemoteUrl, gitRevParse, gitSwitchToBranch, readGitInfo, } from "./git.js";
+import { gitFetchRemote, gitGovernanceOnlyDirty, gitLeftRightCount, gitPullFastForwardOnly, gitRemoteBranchExists, gitRemoteUrl, gitRevParse, gitSwitchToBranch, readGitInfo, restoreGovernanceStashAfterSwitch, stashGovernanceIfBlocking, } from "./git.js";
 import { cyan, dim, log } from "./logger.js";
 function remoteRef(remote, branch) {
     return `${remote}/${branch}`;
@@ -6,6 +6,9 @@ function remoteRef(remote, branch) {
 /**
  * Classify why `git pull --ff-only` would fail for the integration branch.
  * Call after fetch when possible so `origin/branch` is current.
+ *
+ * Governance-only dirt (`.vibeops.json`, docs/, `.vibeops/`, …) does **not**
+ * block — `task add` right after `init` must work.
  */
 export async function diagnoseIntegrationSync(cwd, remote, integrationBranch) {
     if ((await gitRemoteUrl(cwd, remote)) === null) {
@@ -26,19 +29,28 @@ export async function diagnoseIntegrationSync(cwd, remote, integrationBranch) {
     }
     const git = await readGitInfo(cwd);
     if (git.dirty === true) {
-        return {
-            ok: false,
-            kind: "dirty",
-            summary: `Working tree is dirty — cannot fast-forward ${integrationBranch}.`,
-            fixes: [
-                "git status",
-                "git stash push -u -m \"vibeops: before sync\"",
-                `git checkout ${integrationBranch}`,
-                `git pull --ff-only ${remote} ${integrationBranch}`,
-                "git stash pop   # if you stashed",
-                "vibeops task add",
-            ],
-        };
+        const gov = await gitGovernanceOnlyDirty(cwd);
+        if (!gov.onlyGovernance) {
+            const blocking = gov.nonGovernancePaths.slice(0, 8);
+            const more = gov.nonGovernancePaths.length > blocking.length
+                ? ` (+${gov.nonGovernancePaths.length - blocking.length} more)`
+                : "";
+            return {
+                ok: false,
+                kind: "dirty",
+                summary: `Working tree has app changes — cannot fast-forward ${integrationBranch}.`,
+                fixes: [
+                    "git status",
+                    `# Blocking (non-governance): ${blocking.join(", ")}${more}`,
+                    "git stash push -u -m \"vibeops: before sync\"",
+                    `git checkout ${integrationBranch}`,
+                    `git pull --ff-only ${remote} ${integrationBranch}`,
+                    "git stash pop   # if you stashed",
+                    "vibeops task add",
+                ],
+            };
+        }
+        // Governance-only dirty (.vibeops.json after init, docs, …) — proceed.
     }
     const localSha = await gitRevParse(cwd, integrationBranch);
     const remoteSha = await gitRevParse(cwd, remoteRef(remote, integrationBranch));
@@ -129,6 +141,7 @@ export function printIntegrationSyncDiagnosis(d) {
 /**
  * Fetch + ensure local integration can be used as the base for a new task branch.
  * Switches to the integration branch, then `--ff-only` pull when needed. Never force-resets.
+ * Governance-only dirt is stashed around switch/pull so post-`init` `.vibeops.json` edits do not block.
  */
 export async function ensureIntegrationSynced(opts) {
     const { cwd, remote, integrationBranch } = opts;
@@ -184,6 +197,8 @@ export async function ensureIntegrationSynced(opts) {
     if (localSha !== null && remoteSha !== null && localSha === remoteSha) {
         return { ok: true, diagnosis, pulled: false };
     }
+    // Stash governance dirt so ff-only pull cannot be blocked by `.vibeops.json` etc.
+    const stashed = await stashGovernanceIfBlocking(cwd);
     try {
         await gitPullFastForwardOnly(cwd, remote, integrationBranch);
         diagnosis = {
@@ -211,4 +226,7 @@ export async function ensureIntegrationSynced(opts) {
         }
         return { ok: false, diagnosis, pulled: false };
     }
+    finally {
+        await restoreGovernanceStashAfterSwitch(cwd, stashed);
+    }
 }

package/dist/lib/git.js

@@ -299,12 +299,17 @@ const GOVERNANCE_DOC_REL_PREFIXES = [
     "docs/project/",
     "docs/logs/",
     ".vibeops/",
+    ".cursor/rules/",
 ];
+/** Root files owned by vibeops init / config (not under `.vibeops/`). */
+const GOVERNANCE_DOC_EXACT = new Set([".vibeops.json", "AGENTS.md"]);
 function normalizeRepoRelPath(p) {
     return p.replace(/\\/g, "/").replace(/^\/+/, "");
 }
 export function isGovernanceDocumentationPath(repoRelativePath) {
     const n = normalizeRepoRelPath(repoRelativePath);
+    if (GOVERNANCE_DOC_EXACT.has(n))
+        return true;
     for (const prefix of GOVERNANCE_DOC_REL_PREFIXES) {
         if (n.startsWith(prefix))
             return true;

package/dist/lib/merge-config.js

@@ -0,0 +1,125 @@
+import { join } from "node:path";
+import { readTextOrNull } from "./filesystem.js";
+import { VIBEOPS_CONFIG_FILE } from "./paths.js";
+export const MERGE_GATE_DEFAULTS = {
+    requiredChecks: [],
+    releaseRequiredChecks: [],
+    waitTimeoutSeconds: 900,
+    pollIntervalSeconds: 5,
+    emptyRollupGraceSeconds: 30,
+    allowNoChecks: false,
+};
+/** Inclusive bounds for the numeric settings (seconds). */
+export const MERGE_GATE_LIMITS = {
+    waitTimeoutSeconds: { min: 1, max: 7_200 },
+    pollIntervalSeconds: { min: 1, max: 300 },
+    emptyRollupGraceSeconds: { min: 0, max: 600 },
+};
+const KNOWN_KEYS = new Set([
+    "requiredChecks",
+    "releaseRequiredChecks",
+    "waitTimeoutSeconds",
+    "pollIntervalSeconds",
+    "emptyRollupGraceSeconds",
+    "allowNoChecks",
+]);
+/** Invalid `merge` block in `.vibeops.json`. Merge commands refuse to run. */
+export class MergeConfigError extends Error {
+    constructor(message) {
+        super(`${VIBEOPS_CONFIG_FILE} merge: ${message}`);
+        this.name = "MergeConfigError";
+    }
+}
+function checkList(key, raw) {
+    if (!Array.isArray(raw)) {
+        throw new MergeConfigError(`\`${key}\` must be an array of check names.`);
+    }
+    return raw.map((item, i) => {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            throw new MergeConfigError(`\`${key}[${i}]\` must be a non-empty string.`);
+        }
+        return item.trim();
+    });
+}
+function seconds(key, raw) {
+    const { min, max } = MERGE_GATE_LIMITS[key];
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < min || raw > max) {
+        throw new MergeConfigError(`\`${key}\` must be an integer between ${min} and ${max}.`);
+    }
+    return raw;
+}
+/**
+ * Validate the raw `merge` block (fail closed): must be an object, only known
+ * keys, lists of non-empty strings, bounded integer seconds, boolean flags.
+ * `undefined` → defaults.
+ */
+export function parseMergeConfig(raw) {
+    if (raw === undefined)
+        return MERGE_GATE_DEFAULTS;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new MergeConfigError("must be an object.");
+    }
+    const o = raw;
+    const unknown = Object.keys(o).filter((k) => !KNOWN_KEYS.has(k));
+    if (unknown.length > 0) {
+        throw new MergeConfigError(`unknown key${unknown.length > 1 ? "s" : ""} ${unknown
+            .map((k) => `\`${k}\``)
+            .join(", ")} (allowed: ${[...KNOWN_KEYS].join(", ")}).`);
+    }
+    const cfg = {
+        requiredChecks: o.requiredChecks === undefined
+            ? MERGE_GATE_DEFAULTS.requiredChecks
+            : checkList("requiredChecks", o.requiredChecks),
+        releaseRequiredChecks: o.releaseRequiredChecks === undefined
+            ? MERGE_GATE_DEFAULTS.releaseRequiredChecks
+            : checkList("releaseRequiredChecks", o.releaseRequiredChecks),
+        waitTimeoutSeconds: o.waitTimeoutSeconds === undefined
+            ? MERGE_GATE_DEFAULTS.waitTimeoutSeconds
+            : seconds("waitTimeoutSeconds", o.waitTimeoutSeconds),
+        pollIntervalSeconds: o.pollIntervalSeconds === undefined
+            ? MERGE_GATE_DEFAULTS.pollIntervalSeconds
+            : seconds("pollIntervalSeconds", o.pollIntervalSeconds),
+        emptyRollupGraceSeconds: o.emptyRollupGraceSeconds === undefined
+            ? MERGE_GATE_DEFAULTS.emptyRollupGraceSeconds
+            : seconds("emptyRollupGraceSeconds", o.emptyRollupGraceSeconds),
+        allowNoChecks: MERGE_GATE_DEFAULTS.allowNoChecks,
+    };
+    if (o.allowNoChecks !== undefined) {
+        if (typeof o.allowNoChecks !== "boolean") {
+            throw new MergeConfigError("`allowNoChecks` must be true or false.");
+        }
+        cfg.allowNoChecks = o.allowNoChecks;
+    }
+    if (cfg.pollIntervalSeconds > cfg.waitTimeoutSeconds) {
+        throw new MergeConfigError("`pollIntervalSeconds` must not exceed `waitTimeoutSeconds`.");
+    }
+    return cfg;
+}
+/**
+ * Read and validate `.vibeops.json` `merge`. Throws `MergeConfigError` on an
+ * invalid block; a missing file or block yields the defaults.
+ */
+export async function readMergeConfig(root) {
+    const text = await readTextOrNull(join(root, VIBEOPS_CONFIG_FILE));
+    if (text === null)
+        return MERGE_GATE_DEFAULTS;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new MergeConfigError("file is not valid JSON.");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return MERGE_GATE_DEFAULTS;
+    }
+    return parseMergeConfig(parsed.merge);
+}
+/** Gate options (milliseconds) derived from resolved config. */
+export function mergeGateTiming(cfg) {
+    return {
+        timeoutMs: cfg.waitTimeoutSeconds * 1000,
+        intervalMs: cfg.pollIntervalSeconds * 1000,
+        emptyRollupGraceMs: cfg.emptyRollupGraceSeconds * 1000,
+    };
+}

package/dist/lib/merge-request-readiness.js

@@ -4,8 +4,13 @@ const ACTIVE_PIPELINE_STATUSES = new Set([
     "created",
     "waiting_for_resource",
     "preparing",
+    "scheduled",
+    "waiting_for_callback",
+    "canceling",
 ]);
 const TERMINAL_PIPELINE_FAILURES = new Set(["failed", "canceled"]);
+/** Pipeline statuses that count as green for the merge gate (`none` = no pipeline). */
+const GREEN_PIPELINE_STATUSES = new Set(["success", "skipped", "none"]);
 function normalizePipelineStatus(raw) {
     if (raw === null || raw === undefined || raw.trim().length === 0)
         return "none";
@@ -18,6 +23,8 @@ function normalizePipelineStatus(raw) {
         return "failed";
     if (status === "canceled" || status === "cancelled")
         return "canceled";
+    if (status === "manual")
+        return "manual";
     if (ACTIVE_PIPELINE_STATUSES.has(status))
         return "running";
     return "unknown";
@@ -25,6 +32,18 @@ function normalizePipelineStatus(raw) {
 export function pipelineStatusFromHost(raw) {
     return normalizePipelineStatus(raw);
 }
+/**
+ * Merge-gate verdict for a single pipeline status (GitLab head pipeline, or the
+ * aggregated GitHub rollup). Unknown / manual / failed / canceled are red —
+ * never merge on a status we cannot prove is green.
+ */
+export function pipelineGateState(status) {
+    if (GREEN_PIPELINE_STATUSES.has(status))
+        return "green";
+    if (isPipelineActive(status))
+        return "pending";
+    return "red";
+}
 export function isPipelineActive(status) {
     return status === "running" || status === "pending";
 }
@@ -50,7 +69,7 @@ export function isMergeRequestReadyToMerge(readiness) {
     }
     if (TERMINAL_PIPELINE_FAILURES.has(readiness.pipelineStatus))
         return false;
-    if (isPipelineActive(readiness.pipelineStatus))
+    if (pipelineGateState(readiness.pipelineStatus) !== "green")
         return false;
     const mergeStatus = readiness.mergeStatus?.trim().toLowerCase() ?? "";
     return mergeStatus === "can_be_merged" || detailed === "mergeable";

package/dist/lib/pr-create.js

@@ -1,8 +1,10 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mergeRequestLabel } from "./git-host.js";
-import { isMergeRequestReadyToMerge, isPipelineActive, pipelineStatusFromHost, } from "./merge-request-readiness.js";
+import { classifyRollup, evaluateCheckGate, formatCheckGateProblems, } from "./check-rollup.js";
+import { isMergeRequestReadyToMerge, isPipelineActive, pipelineGateState, pipelineStatusFromHost, } from "./merge-request-readiness.js";
 import { dim, log } from "./logger.js";
+import { MERGE_GATE_DEFAULTS, mergeGateTiming } from "./merge-config.js";
 const execFileAsync = promisify(execFile);
 async function ghPrCreate(opts) {
     const { stdout } = await execFileAsync("gh", [
@@ -192,52 +194,125 @@ export async function getMergeRequestState(cwd, host, url) {
     const details = await getMergeRequestDetails(cwd, host, url);
     return details?.state ?? "unknown";
 }
-export async function getMergeRequestDetails(cwd, host, url) {
-    const ref = prRefFromUrl(url);
-    try {
-        if (host === "gitlab") {
-            const { stdout } = await execFileAsync("glab", ["mr", "view", ref, "-F", "json"], { cwd, maxBuffer: 1024 * 1024 });
-            const parsed = JSON.parse(stdout.trim());
-            const state = normalizeGlabMergeRequestState(parsed.state ?? "");
-            return {
-                state,
-                mergedAt: parsed.merged_at ?? null,
-                mergeCommitSha: parsed.merge_commit_sha ?? null,
-                squashCommitSha: parsed.squash_commit_sha ?? null,
-                mergeStatus: parsed.merge_status ?? null,
-                detailedMergeStatus: parsed.detailed_merge_status ?? null,
-                pipelineStatus: pipelineStatusFromHost(parsed.head_pipeline?.status),
-                hasConflicts: parsed.has_conflicts ?? null,
-            };
+/** Host CLI returned JSON without a field the merge gate needs — fail closed. */
+export class MergeRequestShapeError extends Error {
+    constructor(tool, problems) {
+        super(`${tool} output cannot be trusted for the merge gate: ${problems.join("; ")}.`);
+        this.name = "MergeRequestShapeError";
+    }
+}
+/** Describe every field that violates its rule (`undefined`, `null`, `""`, wrong type). */
+function shapeProblems(obj, rules) {
+    const out = [];
+    for (const [field, rule] of Object.entries(rules)) {
+        const v = obj[field];
+        if (rule === "present") {
+            if (!(field in obj) || v === undefined)
+                out.push(`\`${field}\` is missing`);
         }
-        const { stdout } = await execFileAsync("gh", ["pr", "view", ref, "--json", "state,mergedAt,mergeCommit,mergeable,statusCheckRollup"], { cwd, maxBuffer: 1024 * 1024 });
-        const parsed = JSON.parse(stdout.trim());
-        const checks = parsed.statusCheckRollup ?? [];
-        let pipelineStatus = "none";
-        if (checks.some((c) => (c.state ?? "").toUpperCase() === "PENDING")) {
-            pipelineStatus = "running";
+        else if (rule === "array") {
+            if (!Array.isArray(v))
+                out.push(`\`${field}\` is missing or not a list`);
         }
-        else if (checks.some((c) => (c.state ?? "").toUpperCase() === "FAILURE")) {
-            pipelineStatus = "failed";
+        else if (typeof v !== "string" || v.trim().length === 0) {
+            out.push(`\`${field}\` is missing or empty`);
         }
-        else if (checks.length > 0) {
-            pipelineStatus = "success";
+    }
+    return out;
+}
+export async function getMergeRequestDetails(cwd, host, url) {
+    try {
+        return await readMergeRequestDetails(cwd, host, url, { strict: false });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read MR/PR details from the host CLI. Throws on CLI / JSON errors. With
+ * `strict`, also throws `MergeRequestShapeError` when a field the merge gate
+ * relies on is absent (never treat missing data as green).
+ */
+export async function readMergeRequestDetails(cwd, host, url, options) {
+    const ref = prRefFromUrl(url);
+    if (host === "gitlab") {
+        const { stdout } = await execFileAsync("glab", ["mr", "view", ref, "-F", "json"], { cwd, maxBuffer: 1024 * 1024 });
+        const parsed = JSON.parse(stdout.trim());
+        if (options.strict) {
+            const problems = shapeProblems(parsed, {
+                state: "nonEmptyString",
+                merge_status: "present",
+                detailed_merge_status: "present",
+                // `null` = no pipeline; the key itself must be there.
+                head_pipeline: "present",
+                sha: "nonEmptyString",
+            });
+            const pipeline = parsed.head_pipeline;
+            if (pipeline !== null &&
+                pipeline !== undefined &&
+                (typeof pipeline.status !== "string" || pipeline.status.trim().length === 0)) {
+                problems.push("`head_pipeline.status` is missing or empty");
+            }
+            if (problems.length > 0)
+                throw new MergeRequestShapeError("glab", problems);
         }
-        const mergeable = parsed.mergeable?.trim().toUpperCase() ?? "";
+        const state = normalizeGlabMergeRequestState(parsed.state ?? "");
         return {
-            state: normalizeGhMergeRequestState(parsed.state ?? ""),
-            mergedAt: parsed.mergedAt ?? null,
-            mergeCommitSha: parsed.mergeCommit?.oid ?? null,
-            squashCommitSha: null,
-            mergeStatus: mergeable === "MERGEABLE" ? "can_be_merged" : mergeable.toLowerCase(),
-            detailedMergeStatus: mergeable.toLowerCase(),
-            pipelineStatus,
-            hasConflicts: mergeable === "CONFLICTING" ? true : mergeable === "MERGEABLE" ? false : null,
+            state,
+            mergedAt: parsed.merged_at ?? null,
+            mergeCommitSha: parsed.merge_commit_sha ?? null,
+            squashCommitSha: parsed.squash_commit_sha ?? null,
+            mergeStatus: parsed.merge_status ?? null,
+            detailedMergeStatus: parsed.detailed_merge_status ?? null,
+            pipelineStatus: pipelineStatusFromHost(parsed.head_pipeline?.status),
+            hasConflicts: parsed.has_conflicts ?? null,
+            checks: null,
+            headSha: parsed.sha ?? null,
         };
     }
-    catch {
-        return null;
+    const { stdout } = await execFileAsync("gh", [
+        "pr",
+        "view",
+        ref,
+        "--json",
+        "state,mergedAt,mergeCommit,mergeable,headRefOid,statusCheckRollup",
+    ], { cwd, maxBuffer: 4 * 1024 * 1024 });
+    const parsed = JSON.parse(stdout.trim());
+    if (options.strict) {
+        const problems = shapeProblems(parsed, {
+            state: "nonEmptyString",
+            mergeable: "nonEmptyString",
+            headRefOid: "nonEmptyString",
+            statusCheckRollup: "array",
+        });
+        if (problems.length > 0)
+            throw new MergeRequestShapeError("gh", problems);
+    }
+    const checks = classifyRollup(parsed.statusCheckRollup);
+    const gate = evaluateCheckGate(checks);
+    let pipelineStatus = "none";
+    if (gate.state === "red") {
+        pipelineStatus = "failed";
+    }
+    else if (gate.state === "pending") {
+        pipelineStatus = "running";
     }
+    else if (checks.length > 0) {
+        pipelineStatus = "success";
+    }
+    const mergeable = parsed.mergeable?.trim().toUpperCase() ?? "";
+    return {
+        state: normalizeGhMergeRequestState(parsed.state ?? ""),
+        mergedAt: parsed.mergedAt ?? null,
+        mergeCommitSha: parsed.mergeCommit?.oid ?? null,
+        squashCommitSha: null,
+        mergeStatus: mergeable === "MERGEABLE" ? "can_be_merged" : mergeable.toLowerCase(),
+        detailedMergeStatus: mergeable.toLowerCase(),
+        pipelineStatus,
+        hasConflicts: mergeable === "CONFLICTING" ? true : mergeable === "MERGEABLE" ? false : null,
+        checks,
+        headSha: parsed.headRefOid ?? null,
+    };
 }
 /** Poll host until MR/PR state is merged (or timeout). */
 export async function waitForMergeRequestMerged(cwd, host, url, options = {}) {
@@ -264,26 +339,135 @@ function mergeRequestReadinessFromDetails(details) {
         hasConflicts: details.hasConflicts,
     };
 }
-/** Poll until MR/PR CI finished and host reports mergeable (or already merged). */
-export async function waitForMergeRequestReadyToMerge(cwd, host, url, options = {}) {
-    const timeoutMs = options.timeoutMs ?? 900_000;
-    const intervalMs = options.intervalMs ?? 5_000;
-    const deadline = Date.now() + timeoutMs;
+/** Thrown by `mergeMergeRequest` when the merge gate refuses (red / pending / missing checks). */
+export class MergeGateError extends Error {
+    problems;
+    constructor(label, problems) {
+        super(`Refusing to merge ${label}:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+        this.name = "MergeGateError";
+        this.problems = problems;
+    }
+}
+function evaluateDetailsGate(details, requiredChecks) {
+    if (details.checks !== null) {
+        const gate = evaluateCheckGate(details.checks, requiredChecks);
+        return {
+            state: gate.state,
+            problems: formatCheckGateProblems(gate),
+            noChecks: details.checks.length === 0,
+        };
+    }
+    const state = pipelineGateState(details.pipelineStatus);
+    return {
+        state,
+        problems: state === "green" ? [] : [`head pipeline is ${details.pipelineStatus}`],
+        noChecks: details.pipelineStatus === "none",
+    };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+/**
+ * Merge gate: poll the MR/PR until every check is green and the host reports it
+ * mergeable. Refuses immediately on any failed check, on host output it cannot
+ * trust, and on "no checks at all" (unless allowed); refuses after the timeout
+ * when checks stay pending or a required check never appears.
+ */
+export async function waitForMergeGate(cwd, host, url, options = {}) {
+    const defaults = mergeGateTiming(MERGE_GATE_DEFAULTS);
+    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
+    const intervalMs = options.intervalMs ?? defaults.intervalMs;
+    const graceMs = options.emptyRollupGraceMs ?? defaults.emptyRollupGraceMs;
+    const allowNoChecks = options.allowNoChecks ?? MERGE_GATE_DEFAULTS.allowNoChecks;
+    const waitForPending = options.waitForPending !== false;
+    const required = options.requiredChecks ?? [];
     const label = mergeRequestLabel(host);
+    const start = Date.now();
+    const deadline = start + timeoutMs;
     let loggedWait = false;
-    while (Date.now() < deadline) {
-        const details = await getMergeRequestDetails(cwd, host, url);
-        const readiness = mergeRequestReadinessFromDetails(details);
-        if (readiness !== null && isMergeRequestReadyToMerge(readiness)) {
-            return true;
+    let warnedGitLabRequired = false;
+    for (;;) {
+        let problems = [];
+        let details = null;
+        try {
+            details = await readMergeRequestDetails(cwd, host, url, { strict: true });
+        }
+        catch (error) {
+            if (error instanceof MergeRequestShapeError) {
+                return { ok: false, problems: [error.message] };
+            }
+            const msg = error instanceof Error ? error.message.split("\n")[0] : String(error);
+            problems = [`could not read ${label} details from the host: ${msg}`];
+        }
+        if (details === null) {
+            // problems set in catch; keep polling (transient CLI / network error).
+        }
+        else if (details.state === "merged") {
+            return { ok: true, alreadyMerged: true, details };
+        }
+        else if (details.state !== "open") {
+            return { ok: false, problems: [`${label} is ${details.state}, not open`] };
+        }
+        else {
+            const gitlab = details.checks === null;
+            if (gitlab && required.length > 0 && !warnedGitLabRequired) {
+                log.warn("merge.requiredChecks is GitHub-only; GitLab uses the head pipeline status.");
+                warnedGitLabRequired = true;
+            }
+            const ev = evaluateDetailsGate(details, required);
+            if (ev.state === "red") {
+                return { ok: false, problems: ev.problems };
+            }
+            if (details.hasConflicts === true) {
+                return { ok: false, problems: [`${label} has merge conflicts`] };
+            }
+            // "No checks at all" is judged here only when no required check could
+            // report it instead (GitHub with requiredChecks → "never ran" path).
+            const noChecksRule = ev.noChecks && (gitlab || required.length === 0);
+            const inGrace = waitForPending && noChecksRule && Date.now() - start < graceMs;
+            if (ev.state === "pending") {
+                problems = ev.problems;
+            }
+            else if (inGrace) {
+                problems = ["no status checks reported yet"];
+            }
+            else if (noChecksRule && !allowNoChecks) {
+                return {
+                    ok: false,
+                    problems: [
+                        `the host reports no checks for this ${label} — refusing (fail closed). ` +
+                            "Configure CI and `merge.requiredChecks`, or set `merge.allowNoChecks: true` in .vibeops.json for a repo without CI",
+                    ],
+                };
+            }
+            else {
+                const readiness = mergeRequestReadinessFromDetails(details);
+                if (readiness !== null && isMergeRequestReadyToMerge(readiness)) {
+                    if (noChecksRule) {
+                        // Once, after the gate has decided to merge — not on every poll.
+                        log.warn(`WARNING: merging ${label} with NO checks (merge.allowNoChecks is true). Nothing verified this change.`);
+                    }
+                    return { ok: true, alreadyMerged: false, details };
+                }
+                problems = [
+                    `host does not report the ${label} as mergeable yet (${details.detailedMergeStatus || details.mergeStatus || "unknown"})`,
+                ];
+            }
+        }
+        const now = Date.now();
+        if (!waitForPending || now >= deadline) {
+            const suffix = waitForPending
+                ? ` (gave up after ${Math.round(timeoutMs / 1000)}s)`
+                : "";
+            return {
+                ok: false,
+                problems: problems.map((p, i) => (i === problems.length - 1 ? `${p}${suffix}` : p)),
+            };
         }
         if (!loggedWait) {
-            log.info(dim(`Waiting for ${label} pipeline / merge checks…`));
+            log.info(dim(`Waiting for ${label} checks: ${problems.join("; ")}…`));
             loggedWait = true;
         }
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        await sleep(Math.min(intervalMs, deadline - now));
     }
-    return false;
 }
 function isMergeHttp405(error) {
     const msg = error instanceof Error ? error.message : String(error);
@@ -312,68 +496,74 @@ export async function mergeMergeRequest(opts) {
     const ref = prRefFromUrl(opts.url);
     const method = opts.method ?? "squash";
     const label = mergeRequestLabel(opts.host);
-    if (opts.waitForCi === true && opts.dryRun !== true) {
-        const ready = await waitForMergeRequestReadyToMerge(opts.cwd, opts.host, opts.url);
-        if (!ready) {
-            throw new Error(`${label} is not ready to merge yet (pipeline running, checks pending, or timeout).`);
-        }
-    }
-    const details = await getMergeRequestDetails(opts.cwd, opts.host, opts.url);
-    const readiness = mergeRequestReadinessFromDetails(details);
-    const pipelineActive = readiness !== null ? isPipelineActive(readiness.pipelineStatus) : false;
     if (opts.dryRun === true) {
+        const required = opts.requiredChecks && opts.requiredChecks.length > 0
+            ? ` + required: ${opts.requiredChecks.join(", ")}`
+            : "";
+        log.info(`would check ${label} status checks (all green${required}) before merging`);
         if (opts.host === "gitlab") {
-            const immediate = opts.immediate !== false && !pipelineActive;
-            const flags = immediate ? " --auto-merge=false" : " (auto-merge when pipeline succeeds)";
-            const methodFlag = method === "squash" ? " --squash" : method === "rebase" ? " --rebase" : "";
-            log.info(`would ${label} merge ${ref} (glab mr merge${flags}${methodFlag})`);
+            log.info(`would ${label} merge ${ref} (glab ${gitLabMergeArgs(ref, method, "<head sha>").join(" ")})`);
         }
         else {
-            log.info(`would gh pr merge ${ref} --${method}`);
+            log.info(`would gh ${gitHubMergeArgs(ref, method, "<head sha>").join(" ")}`);
         }
         return;
     }
-    if (opts.host === "gitlab") {
-        await mergeGitLabMergeRequest({
-            cwd: opts.cwd,
-            ref,
-            method,
-            immediate: opts.immediate !== false && !pipelineActive,
+    const runGate = async () => {
+        const gate = await waitForMergeGate(opts.cwd, opts.host, opts.url, {
+            ...opts.gate,
+            waitForPending: opts.waitForCi === true,
+            requiredChecks: opts.requiredChecks ?? [],
         });
-        return;
-    }
-    const args = ["pr", "merge", ref, `--${method}`];
-    await execFileAsync("gh", args, { cwd: opts.cwd, maxBuffer: 4 * 1024 * 1024 });
-}
-async function mergeGitLabMergeRequest(input) {
-    const attempt = async (immediate) => {
-        const args = ["mr", "merge", input.ref];
-        if (immediate) {
-            args.push("--auto-merge=false");
-        }
-        if (input.method === "squash") {
-            args.push("--squash");
-        }
-        else if (input.method === "rebase") {
-            args.push("--rebase");
+        if (!gate.ok)
+            throw new MergeGateError(label, gate.problems);
+        if (gate.alreadyMerged)
+            return null;
+        if (gate.details.headSha === null || gate.details.headSha.trim().length === 0) {
+            // Strict read already guarantees this; never merge unpinned.
+            throw new MergeGateError(label, ["host did not report the head commit SHA"]);
         }
-        await execFileAsync("glab", args, {
-            cwd: input.cwd,
-            maxBuffer: 4 * 1024 * 1024,
-        });
+        return gate.details;
     };
-    try {
-        await attempt(input.immediate);
-    }
-    catch (error) {
-        if (!input.immediate && isMergeHttp405(error)) {
-            await attempt(false);
-            return;
+    const details = await runGate();
+    if (details === null)
+        return;
+    if (opts.host === "gitlab") {
+        try {
+            await execGlabMerge(opts.cwd, gitLabMergeArgs(ref, method, details.headSha));
         }
-        if (input.immediate && isMergeHttp405(error)) {
-            await attempt(false);
-            return;
+        catch (error) {
+            if (!isMergeHttp405(error))
+                throw error;
+            // 405: GitLab not ready to accept the merge yet (e.g. mergeability still
+            // being computed). Re-run the gate, then retry once with the same flags
+            // (still `--auto-merge=false`, pinned to the re-checked SHA).
+            const again = await runGate();
+            if (again === null)
+                return;
+            await execGlabMerge(opts.cwd, gitLabMergeArgs(ref, method, again.headSha));
         }
-        throw error;
+        return;
     }
+    // Pinned to the commit the gate checked: a push after the gate makes GitHub refuse.
+    await execFileAsync("gh", gitHubMergeArgs(ref, method, details.headSha), {
+        cwd: opts.cwd,
+        maxBuffer: 4 * 1024 * 1024,
+    });
+}
+/** `gh pr merge` argv. `--match-head-commit` needs gh ≥ 2.13.0. */
+export function gitHubMergeArgs(ref, method, headSha) {
+    return ["pr", "merge", ref, `--${method}`, "--match-head-commit", headSha];
+}
+/** `glab mr merge` argv: immediate (never schedule auto-merge) and pinned with `--sha`. */
+export function gitLabMergeArgs(ref, method, headSha) {
+    const args = ["mr", "merge", ref, "--auto-merge=false", "--sha", headSha];
+    if (method === "squash")
+        args.push("--squash");
+    else if (method === "rebase")
+        args.push("--rebase");
+    return args;
+}
+async function execGlabMerge(cwd, args) {
+    await execFileAsync("glab", [...args], { cwd, maxBuffer: 4 * 1024 * 1024 });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodtek/vibeops",
-  "version": "2.5.1",
+  "version": "3.0.0",
   "description": "Minimal CLI rails for Cursor-based TASK-driven vibe coding.",
   "type": "module",
   "packageManager": "pnpm@9.15.9",