@deftai/directive-core 0.99.0 → 0.100.0

package/dist/pr-merge-readiness/ci-gate.js

@@ -1,3 +1,4 @@
+import { checkRunMatchesRequiredContext, normalizeRequiredContexts, requiredContextLabel, } from "./gh.js";
 import { classifyCapacityStalledRequired, DEFAULT_CAPACITY_STALL_MS, } from "./runner-capacity-stall.js";
 /** Real product/test failures (distinct from cancelled primaries, #3167). */
 const FAILURE_CONCLUSIONS = new Set(["failure", "timed_out"]);
@@ -68,7 +69,7 @@ function isPending(status, conclusion) {
     }
     return status !== "completed" || conclusion === "none";
 }
-function emptySummary(readyState, ignored = []) {
+function emptySummary(readyState, ignored = [], requiredContexts = []) {
     return {
         ready_state: readyState,
         checked_count: 0,
@@ -77,6 +78,8 @@ function emptySummary(readyState, ignored = []) {
         pending_required: [],
         capacity_stalled_required: [],
         cancelled_required: [],
+        absent_required: [],
+        required_contexts: requiredContexts,
         conclusions: [],
     };
 }
@@ -88,34 +91,43 @@ export function buildCiSummaryLine(summary) {
     const cancelSuffix = summary.cancelled_required.length > 0
         ? ` / ${summary.cancelled_required.length} cancelled`
         : "";
+    const absentSuffix = summary.absent_required.length > 0
+        ? ` / ${summary.absent_required.length} absent-required`
+        : "";
     const weather = summary.ready_state === "ci_never_scheduled"
         ? " (ci_never_scheduled)"
         : summary.ready_state === "ci_cancelled_no_failover"
             ? " (ci_cancelled_no_failover)"
             : summary.ready_state === "ci_failures"
                 ? " (ci_failures)"
-                : "";
+                : summary.ready_state === "ci_absent_required"
+                    ? " (ci_absent_required)"
+                    : "";
     return (`CI check-runs: ${passed} passed / ` +
         `${summary.failed_required.length} failed / ${summary.pending_required.length} pending` +
         stallSuffix +
         cancelSuffix +
+        absentSuffix +
         weather);
 }
 /**
- * Classify required CI weather for a HEAD check-run list (#2169 / #2672 / #3167).
+ * Classify required CI weather for a HEAD check-run list (#2169 / #2672 / #3167 / #3234).
  *
  * Distinct ready_state codes:
  * - `ci_never_scheduled` — no CI workflow check-runs (bots alone / empty)
  * - `runner_capacity_stall` — queued past budget, no runner claimed
  * - `ci_failures` — completed failure / timed_out with product evidence
  * - `ci_cancelled_no_failover` — only cancelled failures; no green failover
+ * - `ci_absent_required` — ruleset/BP required context missing on HEAD (#3234)
  * - `not_ready_yet` / `ready` / `blocked` / `skipped` — legacy + residual
  */
 export function evaluateCiGate(checkRuns, options = {}) {
+    const requiredSpecs = normalizeRequiredContexts(options.requiredContexts);
+    const requiredContextLabels = requiredSpecs.map(requiredContextLabel);
     if (options.skipCi === true) {
         return {
             failures: [],
-            summary: emptySummary("skipped"),
+            summary: emptySummary("skipped", [], requiredContextLabels),
         };
     }
     const ignoredSet = new Set(options.ignoreCheckNames ?? []);
@@ -162,13 +174,25 @@ export function evaluateCiGate(checkRuns, options = {}) {
             pendingProbes.push(run);
         }
     }
+    // #3234: ruleset/BP required contexts with no matching HEAD check-run
+    // (path-filtered). Match name + optional app id; operator-ignored contexts skip.
+    const absentRequired = [];
+    for (const ctx of requiredSpecs) {
+        if (ignoredSet.has(ctx.name) || ignoredSet.has(requiredContextLabel(ctx))) {
+            continue;
+        }
+        if (!checkRuns.some((run) => checkRunMatchesRequiredContext(run, ctx))) {
+            absentRequired.push(requiredContextLabel(ctx));
+        }
+    }
     // Operator --ci-ignore-check on every non-bot run is intentional, not weather.
     operatorIgnoredOnly =
         workflowCheckCount === 0 &&
             checkRuns.some((r) => ignoredSet.has(r.name) && !isBotReviewCheck(r.name));
     // #3167: no workflow CI check-runs at all (empty list or bots-only) → never scheduled.
+    // When ruleset/BP names the absents, prefer ci_absent_required (#3234) over weather.
     // Distinct from "all remaining checks operator-ignored" (legacy ready).
-    if (workflowCheckCount === 0 && !operatorIgnoredOnly) {
+    if (workflowCheckCount === 0 && !operatorIgnoredOnly && absentRequired.length === 0) {
         return {
             failures: [
                 "Required CI workflow check-runs never scheduled (ci_never_scheduled): " +
@@ -183,6 +207,8 @@ export function evaluateCiGate(checkRuns, options = {}) {
                 pending_required: [],
                 capacity_stalled_required: [],
                 cancelled_required: [],
+                absent_required: [],
+                required_contexts: requiredContextLabels,
                 conclusions,
             },
         };
@@ -201,6 +227,12 @@ export function evaluateCiGate(checkRuns, options = {}) {
         failedRequired = [...failedProduct, ...cancelledRequired];
         failures.push(`Required CI check-runs failed (ci_failures): ${failedProduct.join(", ")}. ` +
             "Required checks fail closed by default (#2169 / #3167).");
+        if (absentRequired.length > 0) {
+            failures.push(`Required status-check contexts absent on HEAD (ci_absent_required): ` +
+                `${absentRequired.join(", ")}. ` +
+                "Ruleset/branch-protection contexts with no check-run (path-filtered workflows) " +
+                "fail closed (#3234).");
+        }
     }
     else if (pendingRequired.length > 0) {
         // Pending wins over cancelled siblings (failover may still be arming).
@@ -217,6 +249,12 @@ export function evaluateCiGate(checkRuns, options = {}) {
             failures.push(`Required CI check-runs still running (not-ready-yet): ${pendingRequired.join(", ")}. ` +
                 "Wait for required checks to finish before merge.");
         }
+        if (absentRequired.length > 0) {
+            failures.push(`Required status-check contexts absent on HEAD (ci_absent_required): ` +
+                `${absentRequired.join(", ")}. ` +
+                "Ruleset/branch-protection contexts with no check-run (path-filtered workflows) " +
+                "fail closed (#3234).");
+        }
     }
     else if (cancelledRequired.length > 0) {
         // Cancelled suite jobs clear only when a NON-IGNORED AUTHORITATIVE aggregator
@@ -253,12 +291,32 @@ export function evaluateCiGate(checkRuns, options = {}) {
                 `${cancelledRequired.join(", ")}. ` +
                 "Cancelled required check with no green non-ignored authoritative suite aggregator (#3167 / #3168). " +
                 "Do not multi-hour re-push thrash; BLOCKED after thrash caps.");
+            if (absentRequired.length > 0) {
+                failures.push(`Required status-check contexts absent on HEAD (ci_absent_required): ` +
+                    `${absentRequired.join(", ")}. ` +
+                    "Ruleset/branch-protection contexts with no check-run (path-filtered workflows) " +
+                    "fail closed (#3234).");
+            }
+        }
+        else if (absentRequired.length > 0) {
+            readyState = "ci_absent_required";
+            failures.push(`Required status-check contexts absent on HEAD (ci_absent_required): ` +
+                `${absentRequired.join(", ")}. ` +
+                "Ruleset/branch-protection contexts with no check-run (path-filtered workflows) " +
+                "fail closed (#3234).");
         }
         else {
             // Every cancelled suite family has a green non-ignored aggregator; no non-suite cancels.
             readyState = "ready";
         }
     }
+    else if (absentRequired.length > 0) {
+        readyState = "ci_absent_required";
+        failures.push(`Required status-check contexts absent on HEAD (ci_absent_required): ` +
+            `${absentRequired.join(", ")}. ` +
+            "Ruleset/branch-protection contexts with no check-run (path-filtered workflows) " +
+            "fail closed (#3234).");
+    }
     else {
         readyState = "ready";
     }
@@ -272,6 +330,8 @@ export function evaluateCiGate(checkRuns, options = {}) {
             pending_required: pendingRequired,
             capacity_stalled_required: capacityStalledRequired,
             cancelled_required: cancelledRequired,
+            absent_required: absentRequired,
+            required_contexts: requiredContextLabels,
             conclusions,
         },
     };

package/dist/pr-merge-readiness/compute.d.ts

@@ -1,5 +1,6 @@
 import type { CiGateOptions } from "./ci-gate.js";
 import { isMergeReady } from "./evaluate.js";
+import { type RequiredStatusContext } from "./gh.js";
 import { type InlineGreptileFindings } from "./greptile-inline.js";
 import { type MergeabilitySignal } from "./mergeability.js";
 import type { SlizardGateOptions } from "./slizard-gate.js";
@@ -7,6 +8,13 @@ import type { GateResult, RunGhFn } from "./types.js";
 declare function buildGateResult(prNumber: number, repo: string | null, headSha: string | null, body: string, via: string, partialData?: Record<string, unknown>, error?: string | null, inline?: InlineGreptileFindings | null, minConfidence?: number): GateResult;
 /** Injectable GitHub-mergeability read seam (#2260) — keeps unit tests hermetic. */
 export type FetchMergeabilityFn = (prNumber: number, repo: string, runGh: RunGhFn) => MergeabilitySignal;
+/** Injectable required-context resolve seam (#3234) — keeps unit tests hermetic. */
+export type FetchRequiredContextsFn = (repo: string, branch: string, runGh: RunGhFn) => {
+    contexts: readonly RequiredStatusContext[];
+    sources: readonly string[];
+    error: string;
+    resolutionFailed?: boolean;
+};
 export interface ComputeGateOptions extends CiGateOptions, SlizardGateOptions {
     /** Override the GitHub-mergeability read (defaults to the REST reader). */
     readonly fetchMergeabilityFn?: FetchMergeabilityFn;
@@ -25,6 +33,11 @@ export interface ComputeGateOptions extends CiGateOptions, SlizardGateOptions {
      * Tests and injectors use this; production callers leave it unset.
      */
     readonly minConfidence?: number;
+    /**
+     * Override ruleset/BP required-context resolution (#3234). When set, skips
+     * REST fetch. Production callers leave unset; tests inject hermetic lists.
+     */
+    readonly fetchRequiredContextsFn?: FetchRequiredContextsFn;
 }
 /** Run the primary->fallback1->fallback2 cascade and return a result. */
 export declare function computeGateResult(prNumber: number, repo: string | null, runGh: RunGhFn, options?: ComputeGateOptions): GateResult;

package/dist/pr-merge-readiness/compute.js

@@ -2,7 +2,7 @@ import { resolveMinGreptileConfidence } from "../policy/min-greptile-confidence.
 import { buildCiSummaryLine, evaluateCiGate } from "./ci-gate.js";
 import { FALLBACK2_NOT_CLEAN_MSG, VIA_ERROR, VIA_FALLBACK1, VIA_FALLBACK2, VIA_PRIMARY, } from "./constants.js";
 import { evaluateGates, isMergeReady } from "./evaluate.js";
-import { fetchCheckRunsRest, fetchGreptileBodyRest, fetchGreptileCommentBody, fetchPrHeadSha, fetchPrHeadShaRest, resolveRepo, } from "./gh.js";
+import { fetchCheckRunsRest, fetchGreptileBodyRest, fetchGreptileCommentBody, fetchPrBaseRef, fetchPrHeadSha, fetchPrHeadShaRest, fetchRequiredStatusContexts, normalizeRequiredContexts, requiredContextLabel, resolveRepo, } from "./gh.js";
 import { fetchUnresolvedGreptileInlineFindings, inlineFindingsToDict, } from "./greptile-inline.js";
 import { fetchMergeability, isGithubMergeableClean, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";
 import { emptyVerdict, parseGreptileBody } from "./parse.js";
@@ -30,8 +30,8 @@ function resolvedMinConfidence(options) {
     }
     return resolveMinGreptileConfidence(options.projectRoot ?? process.cwd()).min;
 }
-/** Run the CI + SLizard gates off a single check-runs fetch (#2169 / #2189). */
-function evaluateCiAndSlizard(checkRuns, options) {
+/** Run the CI + SLizard gates off a single check-runs fetch (#2169 / #2189 / #3234). */
+function evaluateCiAndSlizard(checkRuns, options, requiredContexts = [], requiredMeta = {}) {
     const slizardResult = evaluateSlizardGate(checkRuns, options);
     // The SLizard check is scored by the structured gate, so exclude it from the
     // generic CI required set to avoid double-counting the same run.
@@ -39,11 +39,16 @@ function evaluateCiAndSlizard(checkRuns, options) {
     const ciOptions = {
         skipCi: options.skipCi,
         ignoreCheckNames: [...(options.ignoreCheckNames ?? []), ...slizardNames],
+        capacityStallBudgetMs: options.capacityStallBudgetMs,
+        nowMs: options.nowMs,
+        // Prefer explicit inject (tests) over resolved ruleset/BP list (#3234).
+        requiredContexts: options.requiredContexts ?? requiredContexts,
     };
     const ciResult = evaluateCiGate(checkRuns, ciOptions);
     const ci = {
         ...ciResult.summary,
         summary_line: buildCiSummaryLine(ciResult.summary),
+        ...requiredMeta,
     };
     // #3180: static status URLs when weather-class (no network fetch).
     attachPlatformStatusUrls(ci, ciResult.summary.ready_state);
@@ -53,7 +58,52 @@ function evaluateCiAndSlizard(checkRuns, options) {
         slizard: { ...slizardResult.summary },
     };
 }
-function applyCiGateForHead(repo, headSha, runGh, options) {
+/**
+ * Resolve ruleset/BP required contexts for the PR base branch (#3234).
+ * Soft-degrades to empty only when sources are cleanly absent (404 / none).
+ * Base-ref failures and untrusted inventory (parse/API hard errors) fail closed.
+ */
+function resolveRequiredContextsForPr(prNumber, repo, runGh, options) {
+    if (options.requiredContexts !== undefined) {
+        return {
+            contexts: normalizeRequiredContexts(options.requiredContexts),
+            meta: {
+                required_contexts_source: "injected",
+            },
+            hardError: null,
+        };
+    }
+    const base = fetchPrBaseRef(prNumber, repo, runGh);
+    if (base.baseRef === null) {
+        return {
+            contexts: [],
+            meta: {
+                required_contexts_source: "unresolved",
+                required_contexts_error: base.error || "base.ref unresolved",
+            },
+            hardError: "Could not resolve PR base.ref for required status-check contexts; " +
+                `fail closed (#3234). Root cause: ${base.error || "base.ref unresolved"}`,
+        };
+    }
+    const fetchFn = options.fetchRequiredContextsFn ?? fetchRequiredStatusContexts;
+    const resolved = fetchFn(repo, base.baseRef, runGh);
+    const contexts = normalizeRequiredContexts(resolved.contexts);
+    const resolutionFailed = resolved.resolutionFailed === true;
+    return {
+        contexts,
+        meta: {
+            required_contexts_source: resolved.sources.length > 0 ? resolved.sources.join("+") : "none",
+            required_contexts_base_ref: base.baseRef,
+            ...(resolved.error ? { required_contexts_error: resolved.error } : {}),
+            ...(resolutionFailed ? { required_contexts_resolution_failed: true } : {}),
+        },
+        hardError: resolutionFailed
+            ? "Required status-check context inventory could not be resolved; " +
+                `fail closed (#3234). Root cause: ${resolved.error || "unknown inventory error"}`
+            : null,
+    };
+}
+function applyCiGateForHead(prNumber, repo, headSha, runGh, options) {
     if (repo === null) {
         return {
             failures: [
@@ -63,6 +113,8 @@ function applyCiGateForHead(repo, headSha, runGh, options) {
             ci: {
                 ready_state: "blocked",
                 error: "repo unresolved for check-runs lookup",
+                absent_required: [],
+                required_contexts: [],
             },
             slizard: {
                 ready_state: "skipped",
@@ -71,10 +123,35 @@ function applyCiGateForHead(repo, headSha, runGh, options) {
             },
         };
     }
+    const { contexts: requiredContexts, meta: requiredMeta, hardError, } = resolveRequiredContextsForPr(prNumber, repo, runGh, options);
+    if (hardError !== null) {
+        return {
+            failures: [hardError],
+            ci: {
+                ready_state: "blocked",
+                error: hardError,
+                checked_count: 0,
+                ignored_checks: [...(options.ignoreCheckNames ?? [])],
+                failed_required: [],
+                pending_required: [],
+                capacity_stalled_required: [],
+                cancelled_required: [],
+                absent_required: [],
+                required_contexts: requiredContexts.map(requiredContextLabel),
+                conclusions: [],
+                ...requiredMeta,
+            },
+            slizard: {
+                ready_state: "skipped",
+                present: false,
+                summary_line: "SLizard review: skipped (required-context inventory unresolved)",
+            },
+        };
+    }
     // When CI is skipped we do not fetch check-runs, so the SLizard gate cannot
     // evaluate either; run both gates against an empty set to honor the overrides.
     if (options.skipCi === true) {
-        const outcome = evaluateCiAndSlizard([], options);
+        const outcome = evaluateCiAndSlizard([], options, requiredContexts, requiredMeta);
         outcome.ci.summary_line = "CI check-runs: skipped (--skip-ci)";
         return { failures: outcome.failures, ci: outcome.ci, slizard: outcome.slizard };
     }
@@ -94,7 +171,10 @@ function applyCiGateForHead(repo, headSha, runGh, options) {
                 pending_required: [],
                 capacity_stalled_required: [],
                 cancelled_required: [],
+                absent_required: [],
+                required_contexts: requiredContexts.map(requiredContextLabel),
                 conclusions: [],
+                ...requiredMeta,
             },
             slizard: {
                 ready_state: "skipped",
@@ -103,7 +183,7 @@ function applyCiGateForHead(repo, headSha, runGh, options) {
             },
         };
     }
-    const outcome = evaluateCiAndSlizard(check.checkRuns, options);
+    const outcome = evaluateCiAndSlizard(check.checkRuns, options, requiredContexts, requiredMeta);
     return { failures: outcome.failures, ci: outcome.ci, slizard: outcome.slizard };
 }
 /**
@@ -134,7 +214,7 @@ function finalizeVerdictGate(prNumber, repo, headSha, verdict, runGh, options) {
         minConfidence,
     });
     if (failures.length === 0) {
-        const ci = applyCiGateForHead(resolved.repo, headSha, runGh, options);
+        const ci = applyCiGateForHead(prNumber, resolved.repo, headSha, runGh, options);
         failures.push(...ci.failures);
         partialData.ci = ci.ci;
         partialData.slizard = ci.slizard;
@@ -148,17 +228,23 @@ function finalizeVerdictGate(prNumber, repo, headSha, verdict, runGh, options) {
         !verdictBlockIsSoftOnly(verdict, headSha, inline, minConfidence)) {
         return { failures, partialData };
     }
-    const ci = applyCiGateForHead(resolved.repo, headSha, runGh, options);
+    const ci = applyCiGateForHead(prNumber, resolved.repo, headSha, runGh, options);
     partialData.ci = ci.ci;
     partialData.slizard = ci.slizard;
     const fetchMergeabilityFn = options.fetchMergeabilityFn ?? fetchMergeability;
     const signal = fetchMergeabilityFn(prNumber, resolved.repo, runGh);
     partialData.mergeability = mergeabilityToDict(signal);
+    // #3234: never discard CI gate failures during soft-verdict reconciliation.
+    // GitHub CLEAN must not erase ci_absent_required / inventory hard-fails.
+    if (ci.failures.length > 0) {
+        failures.push(...ci.failures);
+        return { failures, partialData };
+    }
     if (isGithubMergeableClean(signal)) {
-        // GitHub itself reports CLEAN + MERGEABLE: required checks are green and the
-        // branch is mergeable. Proceed even though the OPTIONAL review verdict is
-        // absent/stale for the head SHA -- exactly the manual `gh pr merge --admin`
-        // case this fix reproduces automatically (#2260).
+        // GitHub itself reports CLEAN + MERGEABLE and our CI inventory is green:
+        // proceed even though the OPTIONAL review verdict is absent/stale for the
+        // head SHA -- exactly the manual `gh pr merge --admin` case this fix
+        // reproduces automatically (#2260).
         partialData.verdict_override = {
             reason: verdictShaIsStale(verdict, headSha) ? "verdict-stale-head-sha" : "verdict-absent",
             basis: "github mergeable_state=clean + mergeable=true (mergeStateStatus:CLEAN + " +
@@ -168,8 +254,7 @@ function finalizeVerdictGate(prNumber, repo, headSha, verdict, runGh, options) {
         return { failures: [], partialData };
     }
     // Not overridable (GitHub not CLEAN/MERGEABLE). Preserve the soft verdict
-    // failures and surface any CI failures so the heartbeat's blocked-on is clear.
-    failures.push(...ci.failures);
+    // failures so the heartbeat's blocked-on is clear.
     return { failures, partialData };
 }
 function computePrimary(prNumber, repo, runGh, options) {

package/dist/pr-merge-readiness/gh.d.ts

@@ -9,7 +9,26 @@ export interface CheckRunRecord {
     readonly created_at?: string | null;
     /** ISO started_at — null while still queued with no runner (#2672). */
     readonly started_at?: string | null;
+    /**
+     * GitHub App id that produced the check run (`app.id`), when present.
+     * Used to match app-bound required contexts from rulesets / branch protection (#3234).
+     */
+    readonly appId?: number | null;
 }
+/**
+ * A required status-check context name, optionally bound to a GitHub App id
+ * (branch-protection `app_id` / ruleset `integration_id`) (#3234).
+ */
+export interface RequiredStatusContext {
+    readonly name: string;
+    readonly appId?: number | null;
+}
+/** Display / inventory key for a required context (includes app binding when set). */
+export declare function requiredContextLabel(ctx: RequiredStatusContext): string;
+/** Normalize injected string names or full specs into RequiredStatusContext (#3234). */
+export declare function normalizeRequiredContexts(input: readonly (string | RequiredStatusContext)[] | undefined): RequiredStatusContext[];
+/** True when an observed check-run satisfies a required context (name + optional app id). */
+export declare function checkRunMatchesRequiredContext(run: CheckRunRecord, ctx: RequiredStatusContext): boolean;
 /** UTF-8-safe gh capture via execFile (no shell) — mirrors _safe_subprocess.run_text (#1366). */
 export declare function defaultRunGh(cmd: readonly string[]): RunGhResult;
 export declare function fetchPrHeadSha(prNumber: number, repo: string | null, runGh: RunGhFn): string | null;
@@ -31,4 +50,34 @@ export declare function fetchCheckRunsRest(sha: string, repo: string, runGh: Run
     checkRuns: CheckRunRecord[];
     error: string;
 };
+/** PR base branch ref (rulesets / branch protection apply to the merge target) (#3234). */
+export declare function fetchPrBaseRef(prNumber: number, repo: string, runGh: RunGhFn): {
+    baseRef: string | null;
+    error: string;
+};
+/** Extract required contexts from `GET .../rules/branches/{branch}` payload (#3234). */
+export declare function contextsFromBranchRules(payload: unknown): RequiredStatusContext[];
+/** Extract required contexts from classic branch-protection payload (#3234). */
+export declare function contextsFromBranchProtection(payload: unknown): RequiredStatusContext[];
+export interface RequiredStatusContextsResult {
+    readonly contexts: readonly RequiredStatusContext[];
+    /** Which REST surfaces contributed contexts (`rulesets` / `branch_protection`). */
+    readonly sources: readonly string[];
+    readonly error: string;
+    /**
+     * True when inventory could not be trusted (parse failure / non-404 REST error
+     * with no successful source). Callers MUST fail closed (#3234 Greptile P1).
+     */
+    readonly resolutionFailed: boolean;
+}
+/**
+ * Resolve required status-check contexts for a branch from rulesets and/or
+ * classic branch protection (REST only) (#3234).
+ *
+ * Absent or 404 sources are soft-skipped (empty contribution). Parse failures
+ * and non-404 REST errors with no successful source set `resolutionFailed`.
+ * Callers compare returned contexts against exact-HEAD check runs (name +
+ * optional app id) and fail closed on absent required contexts.
+ */
+export declare function fetchRequiredStatusContexts(repo: string, branch: string, runGh: RunGhFn): RequiredStatusContextsResult;
 //# sourceMappingURL=gh.d.ts.map