@deftai/directive-core 0.107.0 → 0.109.0

package/dist/pr-closeout-attestable/evaluate.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Merge-time closeout attestability gate (#3781).
+ *
+ * A pull request may leave a brief unattested; it may not MERGE one whose issue
+ * it closes in the same act. The trigger is the PR's structured closing
+ * references, never the branch diff: CI runs before the merge and the issue
+ * closes on it, so at check time no orphan exists yet and a diff-keyed gate can
+ * never fail the PR that introduces the problem (PR #3786's own merge gate
+ * returned success while creating one). The brief also need not be in the diff —
+ * for #3598 it landed on master seventeen hours before its closing PR.
+ *
+ * The rule itself is not restated here. `evaluateAcceptanceEvidenceGate` is the
+ * single decision procedure `scope:complete` enforces, and this gate calls it so
+ * the two cannot drift.
+ */
+import { type GateRunner } from "../orphan-active/issue-state.js";
+import type { RunGhFn } from "../pr-protected-issues/types.js";
+import { type StrictAcceptanceAxis } from "../scope/acceptance-evidence.js";
+export type OutputStream = "stdout" | "stderr" | "none";
+/** One acceptance criterion the merge would strand without evidence or disposition. */
+export interface UnattestedCriterion {
+    /** Plan-item path, e.g. `items[3]` or `items[1].subItems[0]`. */
+    readonly path: string;
+    readonly title: string;
+    /** Verbatim detail from `evaluateAcceptanceEvidenceGate` — the reason it refused. */
+    readonly detail: string;
+    /**
+     * Strict axes inferred for this criterion (#3240). Non-empty means `merge` and
+     * `review` evidence cannot satisfy it, so the message must say which kind can.
+     */
+    readonly requiredAxes: readonly StrictAcceptanceAxis[];
+}
+/** An active/running brief the PR's closing reference would orphan on merge. */
+export interface CloseoutFinding {
+    /** Project-root-relative brief path. */
+    readonly briefPath: string;
+    /** The closing-referenced issue this brief tracks. */
+    readonly issue: number;
+    readonly unattested: readonly UnattestedCriterion[];
+}
+export interface PrCloseoutAttestableResult {
+    /** 0 attestable / 1 unattested closeout / 2 config or lookup error. */
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    readonly prNumber: number;
+    /** Structured closing-issue references read from the forge. */
+    readonly closingIssues: readonly number[];
+    readonly findings: readonly CloseoutFinding[];
+    /** True when the closing-reference read resolved through `ghx`, a cached GET proxy. */
+    readonly proxied: boolean;
+}
+/** Reads the PR's structured closing-issue references; `null` on lookup failure. */
+export type FetchClosingIssuesFn = (prNumber: number, repo: string | null, runGh: RunGhFn) => number[] | null;
+export interface EvaluateOptions {
+    readonly repo?: string | null;
+    /**
+     * SCM read seam plus its freshness basis. Defaults to `makeGateRunner()`, which
+     * pins plain `gh` when present so a cached `ghx` GET cannot fail this gate open.
+     */
+    readonly runner?: GateRunner;
+    readonly quiet?: boolean;
+    /** Closing-reference seam so tests do not need a forge. */
+    readonly fetchClosingIssues?: FetchClosingIssuesFn;
+}
+/**
+ * Fail closed when merging `prNumber` would close an issue whose brief is still
+ * `running` in `active/` with acceptance criteria carrying neither
+ * `x-directive/evidence` nor `x-directive/disposition`.
+ *
+ * Exit contract: 0 attestable (including "this PR closes nothing") / 1 unattested
+ * closeout / 2 config or closing-reference lookup error. A lookup that cannot be
+ * resolved is 2, not 0 — the gate never green-lights a merge it could not check.
+ *
+ * The brief is read from `projectRoot`'s working tree, which at merge time is the
+ * PR head checkout. That is the tree the merge lands, and it is the same
+ * working-tree basis `verify:orphan-active` uses.
+ */
+export declare function evaluate(projectRoot: string, prNumber: number, options?: EvaluateOptions): PrCloseoutAttestableResult;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/pr-closeout-attestable/evaluate.js

@@ -0,0 +1,306 @@
+/**
+ * Merge-time closeout attestability gate (#3781).
+ *
+ * A pull request may leave a brief unattested; it may not MERGE one whose issue
+ * it closes in the same act. The trigger is the PR's structured closing
+ * references, never the branch diff: CI runs before the merge and the issue
+ * closes on it, so at check time no orphan exists yet and a diff-keyed gate can
+ * never fail the PR that introduces the problem (PR #3786's own merge gate
+ * returned success while creating one). The brief also need not be in the diff —
+ * for #3598 it landed on master seventeen hours before its closing PR.
+ *
+ * The rule itself is not restated here. `evaluateAcceptanceEvidenceGate` is the
+ * single decision procedure `scope:complete` enforces, and this gate calls it so
+ * the two cannot drift.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { makeGateRunner } from "../orphan-active/issue-state.js";
+import { collectGithubRefs } from "../orphan-active/refs.js";
+import { fetchClosingIssuesReferences } from "../pr-protected-issues/gh.js";
+import { ACCEPTANCE_DISPOSITION_KEY, ACCEPTANCE_DISPOSITIONS, ACCEPTANCE_EVIDENCE_KEY, ACCEPTANCE_EVIDENCE_KINDS, evaluateAcceptanceEvidenceGate, inferRequiredStrictAxes, } from "../scope/acceptance-evidence.js";
+import { resolveRepo } from "../triage/queue/repo.js";
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function planOf(data) {
+    const plan = data?.plan;
+    return typeof plan === "object" && plan !== null && !Array.isArray(plan)
+        ? plan
+        : null;
+}
+function relBriefPath(path, projectRoot) {
+    try {
+        return relative(resolve(projectRoot), resolve(path)).replace(/\\/g, "/");
+    }
+    catch {
+        return path.replace(/\\/g, "/");
+    }
+}
+function listActiveRunningBriefs(lifecycleRoot) {
+    const activeDir = join(lifecycleRoot, "active");
+    if (!existsSync(activeDir)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of readdirSync(activeDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !hasArtifactSuffix(entry.name)) {
+            continue;
+        }
+        const path = join(activeDir, entry.name);
+        const plan = planOf(readJson(path));
+        if (plan === null || String(plan.status ?? "").toLowerCase() !== "running") {
+            continue;
+        }
+        out.push({ path, plan });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Index plan items by the same path the acceptance gate reports, so a blocker can
+ * be mapped back to its item for axis inference. Traversal order mirrors
+ * `walkItems` in `scope/acceptance-evidence.ts`; the attestation rule stays there.
+ */
+function indexPlanItems(items, pathPrefix, out) {
+    if (!Array.isArray(items)) {
+        return;
+    }
+    items.forEach((item, index) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            return;
+        }
+        const obj = item;
+        const path = `${pathPrefix}[${index}]`;
+        out.set(path, obj);
+        indexPlanItems(obj.subItems, `${path}.subItems`, out);
+        indexPlanItems(obj.items, `${path}.items`, out);
+    });
+}
+const DISPOSITION_SHAPE = `${ACCEPTANCE_DISPOSITION_KEY} {disposition: ${ACCEPTANCE_DISPOSITIONS.join("|")}, ` +
+    `reason, provenance {kind: operator-cli|operator-session|human-event, actor: <non-agent>}, recorded_at}`;
+function evidenceShape(kinds) {
+    return `${ACCEPTANCE_EVIDENCE_KEY} {kind: ${kinds}, pointer, recorded_at, recorded_by}`;
+}
+/**
+ * Name the exact shape this criterion needs. A single evidence.kind covers one
+ * axis, so two inferred axes cannot be satisfied by any kind — say that instead of
+ * printing a kind list that would still be refused (#3240 suitability rule).
+ */
+function renderCriterion(criterion) {
+    const axes = criterion.requiredAxes;
+    const lines = [
+        `      - ${criterion.path} "${criterion.title}"`,
+        `          why:   ${criterion.detail}`,
+    ];
+    if (axes.length > 1) {
+        lines.push(`          axis:  this criterion requires ${axes.join(" + ")}; no single evidence.kind covers`, "                 two axes, so evidence cannot satisfy it as written", `          needs: pin one axis with "requires": "${axes[0]}" then ` +
+            `${evidenceShape(axes[0])},`, "                 or split the criterion one axis per item,", `                 or ${DISPOSITION_SHAPE}`);
+        return lines;
+    }
+    const kinds = axes.length === 1 ? axes[0] : ACCEPTANCE_EVIDENCE_KINDS.join("|");
+    lines.push(`          needs: ${evidenceShape(kinds)}`, `                 or ${DISPOSITION_SHAPE}`);
+    if (axes.length === 1) {
+        lines.push(`          axis:  this criterion requires ${axes[0]} — ` +
+            "merge and review evidence cannot satisfy it (#3240)");
+    }
+    return lines;
+}
+/**
+ * `gh` was absent so the closing-reference read went through `ghx`, a cached GET
+ * proxy this gate cannot inspect. Say so rather than implying a fresh read
+ * (#3767 / #3737).
+ */
+const PROXIED_CAVEAT = "  Note: `gh` was not on PATH, so the closing-reference read resolved through `ghx`, a cached\n" +
+    "  GET proxy; freshness is bounded by that proxy, which this gate cannot inspect (#3737).";
+function formatRefusal(prNumber, findings, projectRoot, proxied) {
+    const criteria = findings.reduce((sum, f) => sum + f.unattested.length, 0);
+    const briefNoun = findings.length === 1 ? "brief" : "briefs";
+    const criterionNoun = criteria === 1 ? "criterion" : "criteria";
+    const issues = findings.map((f) => `#${f.issue}`).join(", ");
+    const lines = [
+        `verify:pr-closeout-attestable: PR #${prNumber} closes ${issues}, leaving ${findings.length} ` +
+            `active/running ${briefNoun} with ${criteria} unattested acceptance ${criterionNoun} ` +
+            `(project_root=${projectRoot}).`,
+        "  Merging now strands the brief on master: the issue closes, the brief stays running in",
+        "  active/, and scope:complete then refuses it. A PR may leave a brief unattested; it may",
+        "  not merge one whose issue is closing in the same act (#3781).",
+        "  Unattested criteria:",
+    ];
+    for (const finding of findings) {
+        lines.push(`    ${finding.briefPath} (closes #${finding.issue})`);
+        for (const criterion of finding.unattested) {
+            lines.push(...renderCriterion(criterion));
+        }
+    }
+    lines.push("  Evidence is not authenticated — recorded_by accepts any non-empty string. Record what you", "  actually did: a pointer must be the artifact its kind names (a test run for test, this PR's", "  merge for merge, a deployment for deploy). An agent may evidence a criterion; only", "  human-origin provenance may waive one (#3240 / #2944).", "  Remediation (performable by this PR's author): stamp the criteria above on the brief in this", "  branch, commit, push, then re-run:", `    task verify:pr-closeout-attestable -- --pr ${prNumber}`, "  Trigger is the PR's closing references, not the branch diff. A PR that leaves an unattested", "  brief without closing its issue is unaffected.");
+    if (proxied) {
+        lines.push(PROXIED_CAVEAT);
+    }
+    return lines.join("\n");
+}
+function configError(prNumber, message, proxied = false) {
+    return {
+        code: 2,
+        message: `verify:pr-closeout-attestable: ${message}`,
+        stream: "stderr",
+        prNumber,
+        closingIssues: [],
+        findings: [],
+        proxied,
+    };
+}
+/**
+ * Fail closed when merging `prNumber` would close an issue whose brief is still
+ * `running` in `active/` with acceptance criteria carrying neither
+ * `x-directive/evidence` nor `x-directive/disposition`.
+ *
+ * Exit contract: 0 attestable (including "this PR closes nothing") / 1 unattested
+ * closeout / 2 config or closing-reference lookup error. A lookup that cannot be
+ * resolved is 2, not 0 — the gate never green-lights a merge it could not check.
+ *
+ * The brief is read from `projectRoot`'s working tree, which at merge time is the
+ * PR head checkout. That is the tree the merge lands, and it is the same
+ * working-tree basis `verify:orphan-active` uses.
+ */
+export function evaluate(projectRoot, prNumber, options = {}) {
+    const root = resolve(projectRoot);
+    const quiet = options.quiet ?? false;
+    if (!existsSync(root)) {
+        return configError(prNumber, `project root does not exist: ${root}`);
+    }
+    let lifecycleRoot;
+    try {
+        lifecycleRoot = resolveLifecycleRoot(root);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Consumers may still be on a legacy vbrief/-only layout (#2112). Closeout
+        // attestability applies to xbrief/active/ only — skip cleanly, not config fail.
+        if (message.includes("No xbrief/ layout found")) {
+            return {
+                code: 0,
+                message: quiet
+                    ? ""
+                    : "verify:pr-closeout-attestable: no xbrief/ lifecycle root; nothing to check.",
+                stream: quiet ? "none" : "stdout",
+                prNumber,
+                closingIssues: [],
+                findings: [],
+                proxied: false,
+            };
+        }
+        return configError(prNumber, message);
+    }
+    if (!existsSync(lifecycleRoot)) {
+        return {
+            code: 0,
+            message: quiet
+                ? ""
+                : "verify:pr-closeout-attestable: no xbrief/ lifecycle root; nothing to check.",
+            stream: quiet ? "none" : "stdout",
+            prNumber,
+            closingIssues: [],
+            findings: [],
+            proxied: false,
+        };
+    }
+    // Pin plain `gh` when it exists: `ghx` is a cached GET proxy and a stale
+    // closing-reference read would fail this gate open (#3767 / #3737).
+    const runner = options.runner ?? makeGateRunner();
+    const fetchClosing = options.fetchClosingIssues ?? fetchClosingIssuesReferences;
+    const repo = resolveRepo(options.repo, root);
+    if (repo === null || repo.length === 0) {
+        // Closing references are repository-scoped. Without the slug this gate could
+        // only compare bare numbers, and a same-numbered issue in an unrelated
+        // repository would block a valid merge.
+        return configError(prNumber, "cannot resolve OWNER/REPO for the closing-reference read. Pass --repo OWNER/REPO, " +
+            "set $GH_REPO, or run inside a checkout with a GitHub origin remote.", runner.proxied);
+    }
+    const linked = fetchClosing(prNumber, repo, runner.runGh);
+    if (linked === null) {
+        return configError(prNumber, `could not read closing-issue references for PR #${prNumber}` +
+            ` (repo=${repo}). ` +
+            "Refusing to certify the merge on an unverified lookup — retry after fixing gh auth, " +
+            "rate limit, or network.", runner.proxied);
+    }
+    const closingIssues = [...new Set(linked)].sort((a, b) => a - b);
+    if (closingIssues.length === 0) {
+        return {
+            code: 0,
+            message: quiet
+                ? ""
+                : `verify:pr-closeout-attestable: PR #${prNumber} closes no issue; closeout attestability does not apply.`,
+            stream: quiet ? "none" : "stdout",
+            prNumber,
+            closingIssues,
+            findings: [],
+            proxied: runner.proxied,
+        };
+    }
+    const closingSet = new Set(closingIssues);
+    const findings = [];
+    for (const brief of listActiveRunningBriefs(lifecycleRoot)) {
+        const { issues } = collectGithubRefs(brief.plan, repo);
+        // Match on (repo, number). Closing references are scoped to the PR's repository,
+        // so a bare-number match would let an unrelated brief tracking the same number in
+        // another repository block this merge. Refs with no repo of their own inherit the
+        // PR's repo from collectGithubRefs, which is the correct reading of a bare number.
+        // GitHub slugs are case-insensitive; a case-sensitive compare would let
+        // DeftAI/Directive vs deftai/directive miss and fail the gate open.
+        const issue = issues.find((ref) => ref.repo.toLowerCase() === repo.toLowerCase() && closingSet.has(ref.number))?.number;
+        if (issue === undefined) {
+            continue;
+        }
+        const gate = evaluateAcceptanceEvidenceGate(brief.plan);
+        if (gate.ok) {
+            continue;
+        }
+        const itemsByPath = new Map();
+        indexPlanItems(brief.plan.items, "items", itemsByPath);
+        const unattested = gate.reports
+            .filter((report) => report.outcome === "missing" || report.outcome === "invalid")
+            .map((report) => {
+            const item = itemsByPath.get(report.path);
+            return {
+                path: report.path,
+                title: report.title,
+                detail: report.detail,
+                requiredAxes: item === undefined ? [] : inferRequiredStrictAxes(item),
+            };
+        });
+        findings.push({ briefPath: relBriefPath(brief.path, root), issue, unattested });
+    }
+    if (findings.length > 0) {
+        return {
+            code: 1,
+            message: formatRefusal(prNumber, findings, root, runner.proxied),
+            stream: "stderr",
+            prNumber,
+            closingIssues,
+            findings,
+            proxied: runner.proxied,
+        };
+    }
+    const issueList = closingIssues.map((n) => `#${n}`).join(", ");
+    const pass = `verify:pr-closeout-attestable: PR #${prNumber} closes ${issueList}; ` +
+        "no active/running brief for those issues has unattested acceptance criteria.";
+    return {
+        code: 0,
+        message: quiet ? "" : runner.proxied ? `${pass}\n${PROXIED_CAVEAT}` : pass,
+        stream: quiet ? "none" : "stdout",
+        prNumber,
+        closingIssues,
+        findings: [],
+        proxied: runner.proxied,
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/pr-closeout-attestable/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/pr-closeout-attestable/index.js

@@ -0,0 +1,2 @@
+export * from "./evaluate.js";
+//# sourceMappingURL=index.js.map

package/dist/pr-closing-keywords/gh.js

@@ -1,5 +1,7 @@
 import { execFileSync } from "node:child_process";
-import { resolveBinary } from "../scm/binary.js";
+import { defaultWhich } from "../scm/binary.js";
+import { classifyScmArgv, resolveBinaryForArgv } from "../scm/call-shape.js";
+import { ghxSpawnFallbackBinary } from "../scm/spawn-status.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { GH_TIMEOUT_S } from "./constants.js";
 /** UTF-8-safe gh capture via execFile (no shell) — mirrors _safe_subprocess.run_text (#1366). */
@@ -7,18 +9,39 @@ export function defaultRunGh(cmd) {
     if (cmd.length === 0 || cmd[0] !== "gh") {
         return { returncode: -1, stdout: "", stderr: "expected gh as first argv element" };
     }
-    const binary = resolveBinary();
     const args = cmd.slice(1);
+    const binary = resolveBinaryForArgv(args[0] ?? "", args.slice(1));
+    const execOpts = {
+        encoding: "utf8",
+        timeout: GH_TIMEOUT_S * 1000,
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: SUBPROCESS_MAX_BUFFER,
+    };
+    const runOnce = (bin) => execFileSync(bin, args, execOpts);
     try {
-        const stdout = execFileSync(binary, args, {
-            encoding: "utf8",
-            timeout: GH_TIMEOUT_S * 1000,
-            stdio: ["ignore", "pipe", "pipe"],
-            maxBuffer: SUBPROCESS_MAX_BUFFER,
-        });
+        const stdout = runOnce(binary);
         return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
     }
-    catch (err) {
+    catch (caught) {
+        let err = caught;
+        const first = err;
+        const retry = ghxSpawnFallbackBinary(classifyScmArgv(args[0] ?? "", args.slice(1)), binary, defaultWhich, {
+            status: typeof first.status === "number" ? first.status : null,
+            error: first.code === "ENOENT" || first.code === "ETIMEDOUT" || typeof first.status !== "number"
+                ? { code: first.code, message: first.message }
+                : undefined,
+            stdout: typeof first.stdout === "string" ? first.stdout : "",
+            stderr: typeof first.stderr === "string" ? first.stderr : "",
+        });
+        if (retry !== null) {
+            try {
+                const stdout = runOnce(retry);
+                return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
+            }
+            catch (retryErr) {
+                err = retryErr;
+            }
+        }
         const e = err;
         if (e.code === "ENOENT") {
             return { returncode: -1, stdout: "", stderr: "gh CLI not found. Install GitHub CLI." };

package/dist/pr-closing-keywords/main.d.ts

@@ -3,6 +3,7 @@ export declare function parseAllowList(values: readonly string[]): Set<number>;
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;
 export interface RunOptions {
     readonly runGh?: RunGhFn;
+    readonly runGit?: RunGhFn;
 }
 export declare function run(argv: readonly string[], options?: RunOptions): number;
 export declare function cmdPrCheckClosingKeywords(argv: readonly string[], options?: RunOptions): number;

package/dist/pr-closing-keywords/main.js

@@ -1,3 +1,5 @@
+import { execFileSync } from "node:child_process";
+import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { EXIT_CONFIG_ERROR, EXIT_HITS_FOUND, EXIT_OK } from "./constants.js";
 import { findAllClosingKeywordHits, findHits, renderHit } from "./detect.js";
 import { defaultRunGh, fetchPrBody, fetchPrCommitMessages } from "./gh.js";
@@ -23,6 +25,7 @@ function emptyParsed(error) {
         pr: null,
         bodyFile: null,
         commitsFile: null,
+        fromGitRange: null,
         repo: null,
         allowKnownFalsePositives: [],
         allowClose: [],
@@ -34,6 +37,7 @@ export function parseArgs(argv) {
     let pr = null;
     let bodyFile = null;
     let commitsFile = null;
+    let fromGitRange = null;
     let repo = null;
     let mode = "both";
     const allowKnownFalsePositives = [];
@@ -82,6 +86,17 @@ export function parseArgs(argv) {
         else if (arg?.startsWith("--commits-file=")) {
             commitsFile = arg.slice("--commits-file=".length);
         }
+        else if (arg === "--from-git-range") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return emptyParsed("argument --from-git-range: expected one argument");
+            }
+            fromGitRange = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--from-git-range=")) {
+            fromGitRange = arg.slice("--from-git-range=".length);
+        }
         else if (arg === "--repo") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -140,7 +155,50 @@ export function parseArgs(argv) {
             return emptyParsed(`unrecognized arguments: ${arg}`);
         }
     }
-    return { pr, bodyFile, commitsFile, repo, allowKnownFalsePositives, allowClose, mode };
+    return {
+        pr,
+        bodyFile,
+        commitsFile,
+        fromGitRange,
+        repo,
+        allowKnownFalsePositives,
+        allowClose,
+        mode,
+    };
+}
+function defaultRunGit(cmd) {
+    try {
+        const stdout = execFileSync("git", [...cmd], {
+            encoding: "utf8",
+            timeout: 30_000,
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: SUBPROCESS_MAX_BUFFER,
+        });
+        return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            returncode: typeof e.status === "number" ? e.status : 1,
+            stdout: typeof e.stdout === "string" ? e.stdout : "",
+            stderr: typeof e.stderr === "string" ? e.stderr : String(e.message ?? ""),
+        };
+    }
+}
+function readGitRange(range, runGit) {
+    const result = runGit(["log", range, "--format=%B%n--END--"]);
+    if (result.returncode !== 0) {
+        process.stderr.write("Error: git log " +
+            range +
+            " failed: " +
+            result.stderr.trim() +
+            ". Recovery: git fetch origin master.\n");
+        return null;
+    }
+    return result.stdout
+        .split("\n--END--\n")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
 }
 function filterHits(hits, allowList) {
     return hits.filter((h) => !allowList.has(h.issueNumber));
@@ -220,8 +278,8 @@ export function run(argv, options = {}) {
         commitMessages = msgs;
     }
     else {
-        if (args.bodyFile === null && args.commitsFile === null) {
-            process.stderr.write("Error: must specify --pr OR --body-file / --commits-file.\n");
+        if (args.bodyFile === null && args.commitsFile === null && args.fromGitRange === null) {
+            process.stderr.write("Error: must specify --pr OR --body-file / --commits-file / --from-git-range.\n");
             return EXIT_CONFIG_ERROR;
         }
         if (args.bodyFile !== null) {
@@ -238,6 +296,13 @@ export function run(argv, options = {}) {
             }
             commitMessages = msgs;
         }
+        if (args.fromGitRange !== null) {
+            const msgs = readGitRange(args.fromGitRange, options.runGit ?? defaultRunGit);
+            if (msgs === null) {
+                return EXIT_CONFIG_ERROR;
+            }
+            commitMessages = [...commitMessages, ...msgs];
+        }
     }
     const runFp = args.mode === "fp" || args.mode === "both";
     const runIntent = args.mode === "intent" || args.mode === "both";

package/dist/pr-closing-keywords/types.d.ts

@@ -18,6 +18,8 @@ export interface ParsedArgs {
     readonly pr: number | null;
     readonly bodyFile: string | null;
     readonly commitsFile: string | null;
+    /** Offline git range (e.g. origin/master..HEAD) for check-graph wiring (#3969). */
+    readonly fromGitRange: string | null;
     readonly repo: string | null;
     readonly allowKnownFalsePositives: readonly string[];
     /** Intent-mode allowlist of issue numbers permitted to use real closing keywords (#3015). */

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

@@ -1,5 +1,7 @@
 import { execFileSync } from "node:child_process";
-import { resolveBinary } from "../scm/binary.js";
+import { defaultWhich } from "../scm/binary.js";
+import { classifyScmArgv, resolveBinaryForArgv } from "../scm/call-shape.js";
+import { ghxSpawnFallbackBinary } from "../scm/spawn-status.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { GH_TIMEOUT_S, GREPTILE_LOGIN } from "./constants.js";
 /** Display / inventory key for a required context (includes app binding when set). */
@@ -47,18 +49,39 @@ export function defaultRunGh(cmd) {
     if (cmd.length === 0 || cmd[0] !== "gh") {
         return { returncode: -1, stdout: "", stderr: "expected gh as first argv element" };
     }
-    const binary = resolveBinary();
     const args = cmd.slice(1);
+    const binary = resolveBinaryForArgv(args[0] ?? "", args.slice(1));
+    const execOpts = {
+        encoding: "utf8",
+        timeout: GH_TIMEOUT_S * 1000,
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: SUBPROCESS_MAX_BUFFER,
+    };
+    const runOnce = (bin) => execFileSync(bin, args, execOpts);
     try {
-        const stdout = execFileSync(binary, args, {
-            encoding: "utf8",
-            timeout: GH_TIMEOUT_S * 1000,
-            stdio: ["ignore", "pipe", "pipe"],
-            maxBuffer: SUBPROCESS_MAX_BUFFER,
-        });
+        const stdout = runOnce(binary);
         return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
     }
-    catch (err) {
+    catch (caught) {
+        let err = caught;
+        const first = err;
+        const retry = ghxSpawnFallbackBinary(classifyScmArgv(args[0] ?? "", args.slice(1)), binary, defaultWhich, {
+            status: typeof first.status === "number" ? first.status : null,
+            error: first.code === "ENOENT" || first.code === "ETIMEDOUT" || typeof first.status !== "number"
+                ? { code: first.code, message: first.message }
+                : undefined,
+            stdout: typeof first.stdout === "string" ? first.stdout : "",
+            stderr: typeof first.stderr === "string" ? first.stderr : "",
+        });
+        if (retry !== null) {
+            try {
+                const stdout = runOnce(retry);
+                return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
+            }
+            catch (retryErr) {
+                err = retryErr;
+            }
+        }
         const e = err;
         if (e.code === "ENOENT") {
             return { returncode: -1, stdout: "", stderr: "gh CLI not found. Install GitHub CLI." };

package/dist/pr-protected-issues/gh.d.ts

@@ -1,6 +1,10 @@
 import type { RunGhFn, RunGhResult } from "./types.js";
-/** UTF-8-safe gh capture via execFile (no shell) — mirrors _safe_subprocess.run_text (#1366). */
-export declare function defaultRunGh(cmd: readonly string[]): RunGhResult;
+/**
+ * UTF-8-safe gh capture via execFile (no shell) — mirrors _safe_subprocess.run_text (#1366).
+ * `binaryOverride` lets a caller pin the SCM binary (e.g. plain `gh` instead of
+ * the `ghx` cached proxy) when its guarantee depends on an uncached read (#3767).
+ */
+export declare function defaultRunGh(cmd: readonly string[], binaryOverride?: string): RunGhResult;
 /**
  * Run ``gh pr view <N> --json closingIssuesReferences`` and return linked issue
  * numbers. Returns ``null`` on external error (caller maps to EXIT_EXTERNAL_ERROR).