fix(review): hold the gate when an enforced pre-merge check's files can't be resolved (#1371)

review.pre_merge_checks built changedPaths from getReviewFiles(), which returns [] when the PR's files
are unresolved (review fired before detail-sync AND the inline fetch failed). evaluatePreMergeChecks then
treated every whenPaths-gated check as N/A (`[].some()` is false) and SKIPPED it — including enforce:true
checks — so a guarded PR with green CI auto-MERGED, silently bypassing the maintainer's hard requirement.

A PR always touches >=1 file, so an empty resolved set means UNRESOLVED. Thread filesResolved into
evaluatePreMergeChecks: when false, an enforced whenPaths check emits a new `pre_merge_check_unresolved`
finding that isEvaluationBlocker treats as a NEUTRAL gate (HELD, re-evaluates on the next sync) — never
silently skipping the requirement (auto-merge bypass) and never hard-closing the contributor on a transient
resolution miss. Advisory checks are dropped (no noise); path-less checks are unaffected.

Author: JSONbored

src/queue/processors.ts

@@ -2560,12 +2560,16 @@ async function maybePublishPrPublicSurface(
     const preMergeChecks = resolveReviewPreMergeChecks(await loadRepoFocusManifest(env, repoFullName).catch(() => null));
     if (preMergeChecks.length > 0) {
       const checkFiles = await getReviewFiles(); // memoized — reuses the gate/slop diff when already resolved
+      // An empty resolved file set means the changed paths could not be resolved (a PR always touches >=1 file),
+      // so a path-gated check cannot be evaluated — pass filesResolved=false so an ENFORCED whenPaths check HOLDS
+      // the gate (re-evaluates later) instead of silently skipping a hard requirement into an auto-merge (#review-audit).
       advisory.findings.push(
         ...evaluatePreMergeChecks(preMergeChecks, {
           title: pr.title,
           body: pr.body,
           labels: pr.labels,
           changedPaths: checkFiles.map((file) => file.path),
+          filesResolved: checkFiles.length > 0,
         }),
       );
     }

src/review/pre-merge-checks.ts

@@ -6,6 +6,11 @@ export const PRE_MERGE_CHECK_ADVISORY_CODE = "pre_merge_check_failed";
 /** Finding code for a FAILED pre-merge check the maintainer marked `enforce: true` — a hard gate blocker
  *  (isConfiguredGateBlocker treats this code as blocking, like secret_leak). */
 export const PRE_MERGE_CHECK_BLOCKING_CODE = "pre_merge_check_required";
+/** Finding code emitted when an ENFORCED `whenPaths`-gated check cannot be evaluated because the PR's changed-file
+ *  set could not be resolved. isEvaluationBlocker (advisory.ts) treats this as a NEUTRAL gate (HELD, re-evaluates
+ *  automatically) — never silently skipping a hard requirement (auto-merge bypass) and never hard-closing the
+ *  contributor on a transient resolution miss. (#review-audit) */
+export const PRE_MERGE_CHECK_UNRESOLVED_CODE = "pre_merge_check_unresolved";
 
 /**
  * Evaluate the maintainer's `.gittensory.yml review.pre_merge_checks` against a PR — DETERMINISTICALLY, with no AI
@@ -18,16 +23,33 @@ export const PRE_MERGE_CHECK_BLOCKING_CODE = "pre_merge_check_required";
  */
 export function evaluatePreMergeChecks(
   checks: PreMergeCheck[],
-  ctx: { title?: string | null | undefined; body?: string | null | undefined; labels?: string[] | null | undefined; changedPaths: string[] },
+  ctx: { title?: string | null | undefined; body?: string | null | undefined; labels?: string[] | null | undefined; changedPaths: string[]; filesResolved?: boolean | undefined },
 ): AdvisoryFinding[] {
   const title = (ctx.title ?? "").toLowerCase();
   const body = (ctx.body ?? "").toLowerCase();
   const labels = (ctx.labels ?? []).map((label) => label.toLowerCase());
+  const filesResolved = ctx.filesResolved ?? true; // absent ⇒ caller asserts a trustworthy changedPaths set
   const findings: AdvisoryFinding[] = [];
   for (const check of checks) {
     // when_paths gate: a check with whenPaths applies ONLY to PRs that touch a matching path; an unmatched check
-    // is N/A (no finding). Empty whenPaths ⇒ the check always applies.
-    if (check.whenPaths.length > 0 && !ctx.changedPaths.some((path) => check.whenPaths.some((glob) => matchesManifestPath(path, glob)))) continue;
+    // is N/A (no finding). Empty whenPaths ⇒ the check always applies (title/description/label only).
+    if (check.whenPaths.length > 0) {
+      if (!filesResolved) {
+        // The changed-file set could not be resolved, so we cannot evaluate this path gate. HOLD the gate for an
+        // ENFORCED check (re-evaluates when files resolve) instead of silently skipping a hard requirement (which
+        // would let a guarded PR auto-merge). An advisory check is just dropped (no noise on a transient miss).
+        if (check.enforce)
+          findings.push({
+            code: PRE_MERGE_CHECK_UNRESOLVED_CODE,
+            severity: "warning",
+            title: `Pre-merge check held — changed files not resolved: ${check.name}`,
+            detail: `Gittensory could not resolve this PR's changed files to evaluate the path-gated check "${check.name}"; the gate is held and re-evaluates automatically.`,
+            action: "No action needed — the gate re-evaluates once the PR's files are available.",
+          });
+        continue;
+      }
+      if (!ctx.changedPaths.some((path) => check.whenPaths.some((glob) => matchesManifestPath(path, glob)))) continue;
+    }
     const unmet: string[] = [];
     if (check.titleContains !== null && !title.includes(check.titleContains.toLowerCase())) unmet.push(`the title must contain "${check.titleContains}"`);
     if (check.descriptionContains !== null && !body.includes(check.descriptionContains.toLowerCase())) unmet.push(`the description must contain "${check.descriptionContains}"`);

src/rules/advisory.ts

@@ -705,7 +705,10 @@ function conclusionForSeverity(severity: AdvisorySeverity, findings: AdvisoryFin
 }
 
 function isEvaluationBlocker(code: string): boolean {
-  return code === "repo_not_registered" || code === "repo_not_seen" || code === "pr_not_cached";
+  // pre_merge_check_unresolved: an enforced path-gated pre-merge check whose changed-file set could not be
+  // resolved — gittensory cannot evaluate it yet, so the gate is NEUTRAL (held) and re-evaluates on the next
+  // sync, rather than auto-merging past the unverified requirement or hard-closing on a transient miss. (#review-audit)
+  return code === "repo_not_registered" || code === "repo_not_seen" || code === "pr_not_cached" || code === "pre_merge_check_unresolved";
 }
 
 function isConfiguredGateBlocker(code: string, policy: GateCheckPolicy): boolean {

test/unit/gate-check-policy.test.ts

@@ -145,6 +145,16 @@ describe("AI fail-closed hold (#ai-fail-closed)", () => {
     expect(advisoryResult.blockers).toEqual([]);
     expect(advisoryResult.warnings.map((warning) => warning.code)).toContain("pre_merge_check_failed");
   });
+
+  it("an unresolved-files enforced pre-merge check HOLDS the gate (neutral), never close or pass (#review-audit)", () => {
+    const held: Advisory = {
+      ...missingIssueAdvisory(),
+      findings: [{ code: "pre_merge_check_unresolved", title: "Pre-merge check held — changed files not resolved: Migrations documented", severity: "warning", detail: "could not resolve files", action: "re-evaluates automatically" }],
+    };
+    const result = evaluateGateCheck(held, gateCheckPolicy(settings(), null, true));
+    expect(result.conclusion).toBe("neutral"); // held: not a pass (would auto-merge past the unverified check) nor a failure (would auto-close on a transient miss)
+    expect(result.blockers).toEqual([]);
+  });
 });
 
 describe("policy pack (#692)", () => {

test/unit/pre-merge-checks.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { evaluatePreMergeChecks, PRE_MERGE_CHECK_ADVISORY_CODE, PRE_MERGE_CHECK_BLOCKING_CODE } from "../../src/review/pre-merge-checks";
+import { evaluatePreMergeChecks, PRE_MERGE_CHECK_ADVISORY_CODE, PRE_MERGE_CHECK_BLOCKING_CODE, PRE_MERGE_CHECK_UNRESOLVED_CODE } from "../../src/review/pre-merge-checks";
 import type { PreMergeCheck } from "../../src/signals/focus-manifest";
 
 const check = (over: Partial<PreMergeCheck> = {}): PreMergeCheck => ({
@@ -52,6 +52,21 @@ describe("evaluatePreMergeChecks (#review-pre-merge-checks)", () => {
     expect(out[0]?.code).toBe(PRE_MERGE_CHECK_BLOCKING_CODE);
   });
 
+  it("filesResolved=false HOLDS an enforced whenPaths check (unresolved code) but skips an advisory one and still evaluates non-path checks (#review-audit)", () => {
+    const enforced = check({ name: "Migrations documented", whenPaths: ["migrations/**"], descriptionContains: "migration", enforce: true });
+    const advisory = check({ name: "advisory path check", whenPaths: ["migrations/**"], descriptionContains: "migration", enforce: false });
+    const noPath = check({ name: "JIRA in title", titleContains: "JIRA-", enforce: true }); // no whenPaths → unaffected
+    // Files could not be resolved (changedPaths empty + filesResolved false): the enforced path check HOLDS, the
+    // advisory path check is dropped, and the path-less check still evaluates normally.
+    const out = evaluatePreMergeChecks([enforced, advisory, noPath], { title: "no ref", body: "", labels: [], changedPaths: [], filesResolved: false });
+    expect(out).toHaveLength(2);
+    expect(out.find((f) => f.title.includes("Migrations documented"))?.code).toBe(PRE_MERGE_CHECK_UNRESOLVED_CODE);
+    expect(out.find((f) => f.title.includes("JIRA in title"))?.code).toBe(PRE_MERGE_CHECK_BLOCKING_CODE);
+    expect(out.some((f) => f.title.includes("advisory path check"))).toBe(false);
+    // With files resolved (default), the same enforced check is N/A when no path matches — no hold.
+    expect(evaluatePreMergeChecks([enforced], { title: "t", body: "", labels: [], changedPaths: ["src/a.ts"] })).toEqual([]);
+  });
+
   it("defaults null/absent title, body, and labels to empty (no crash; the assertion simply fails)", () => {
     const out = evaluatePreMergeChecks([check({ name: "T", titleContains: "feat" })], { changedPaths: [] });
     expect(out).toHaveLength(1);