@deftai/directive-core 0.99.0 → 0.100.0

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

@@ -2,6 +2,46 @@ import { execFileSync } from "node:child_process";
 import { resolveBinary } from "../scm/binary.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). */
+export function requiredContextLabel(ctx) {
+    if (ctx.appId != null) {
+        return `${ctx.name} (app:${ctx.appId})`;
+    }
+    return ctx.name;
+}
+/** Normalize injected string names or full specs into RequiredStatusContext (#3234). */
+export function normalizeRequiredContexts(input) {
+    if (input === undefined) {
+        return [];
+    }
+    const out = [];
+    for (const item of input) {
+        if (typeof item === "string") {
+            if (item.length > 0) {
+                out.push({ name: item });
+            }
+            continue;
+        }
+        if (item !== null &&
+            typeof item === "object" &&
+            typeof item.name === "string" &&
+            item.name.length > 0) {
+            const appId = typeof item.appId === "number" && Number.isFinite(item.appId) ? item.appId : null;
+            out.push(appId === null ? { name: item.name } : { name: item.name, appId });
+        }
+    }
+    return out;
+}
+/** True when an observed check-run satisfies a required context (name + optional app id). */
+export function checkRunMatchesRequiredContext(run, ctx) {
+    if (run.name !== ctx.name) {
+        return false;
+    }
+    if (ctx.appId == null) {
+        return true;
+    }
+    return run.appId === ctx.appId;
+}
 /** UTF-8-safe gh capture via execFile (no shell) — mirrors _safe_subprocess.run_text (#1366). */
 export function defaultRunGh(cmd) {
     if (cmd.length === 0 || cmd[0] !== "gh") {
@@ -298,12 +338,21 @@ export function fetchCheckRunsRest(sha, repo, runGh) {
         const runSummary = extractCheckRunSummary(r);
         const createdAt = typeof r.created_at === "string" ? r.created_at : null;
         const startedAt = typeof r.started_at === "string" ? r.started_at : null;
+        let appId = null;
+        const appBlock = r.app;
+        if (appBlock !== null && typeof appBlock === "object" && !Array.isArray(appBlock)) {
+            const id = appBlock.id;
+            if (typeof id === "number" && Number.isFinite(id)) {
+                appId = id;
+            }
+        }
         const record = {
             name,
             status,
             conclusion,
             created_at: createdAt,
             started_at: startedAt,
+            appId,
             ...(runSummary === null ? {} : { summary: runSummary }),
         };
         checkRuns.push(record);
@@ -318,4 +367,223 @@ export function fetchCheckRunsRest(sha, repo, runGh) {
     }
     return { summary, checkRuns, error: "" };
 }
+/** PR base branch ref (rulesets / branch protection apply to the merge target) (#3234). */
+export function fetchPrBaseRef(prNumber, repo, runGh) {
+    const rc = runGh(["gh", "api", `repos/${repo}/pulls/${prNumber}`]);
+    if (rc.returncode !== 0) {
+        return { baseRef: null, error: `gh api /pulls/${prNumber} failed: ${rc.stderr.trim()}` };
+    }
+    if (!rc.stdout.trim()) {
+        return { baseRef: null, error: "empty body from gh api /pulls/<N>" };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(rc.stdout);
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        return { baseRef: null, error: `could not parse PR JSON: ${message}` };
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return { baseRef: null, error: "unexpected PR JSON shape (not a dict)" };
+    }
+    const base = payload.base;
+    if (base !== null && typeof base === "object" && !Array.isArray(base)) {
+        const ref = base.ref;
+        if (typeof ref === "string" && ref.length > 0) {
+            return { baseRef: ref, error: "" };
+        }
+    }
+    return { baseRef: null, error: "PR JSON missing base.ref" };
+}
+function parseOptionalAppId(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        return raw;
+    }
+    return null;
+}
+/** Extract required contexts from `GET .../rules/branches/{branch}` payload (#3234). */
+export function contextsFromBranchRules(payload) {
+    if (!Array.isArray(payload)) {
+        return [];
+    }
+    const out = [];
+    for (const rule of payload) {
+        if (rule === null || typeof rule !== "object" || Array.isArray(rule)) {
+            continue;
+        }
+        const r = rule;
+        if (r.type !== "required_status_checks") {
+            continue;
+        }
+        const params = r.parameters;
+        if (params === null || typeof params !== "object" || Array.isArray(params)) {
+            continue;
+        }
+        const checks = params.required_status_checks;
+        if (!Array.isArray(checks)) {
+            continue;
+        }
+        for (const check of checks) {
+            if (check === null || typeof check !== "object" || Array.isArray(check)) {
+                continue;
+            }
+            const c = check;
+            const context = c.context;
+            if (typeof context !== "string" || context.length === 0) {
+                continue;
+            }
+            // Rulesets use integration_id; treat as GitHub App id for check-run matching.
+            const appId = parseOptionalAppId(c.integration_id);
+            out.push(appId === null ? { name: context } : { name: context, appId });
+        }
+    }
+    return out;
+}
+/** Extract required contexts from classic branch-protection payload (#3234). */
+export function contextsFromBranchProtection(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return [];
+    }
+    const rsc = payload.required_status_checks;
+    if (rsc === null || typeof rsc !== "object" || Array.isArray(rsc)) {
+        return [];
+    }
+    const block = rsc;
+    const out = [];
+    const contexts = block.contexts;
+    if (Array.isArray(contexts)) {
+        for (const c of contexts) {
+            if (typeof c === "string" && c.length > 0) {
+                out.push({ name: c });
+            }
+        }
+    }
+    const checks = block.checks;
+    if (Array.isArray(checks)) {
+        for (const check of checks) {
+            if (check === null || typeof check !== "object" || Array.isArray(check)) {
+                continue;
+            }
+            const c = check;
+            const context = c.context;
+            if (typeof context !== "string" || context.length === 0) {
+                continue;
+            }
+            const appId = parseOptionalAppId(c.app_id);
+            out.push(appId === null ? { name: context } : { name: context, appId });
+        }
+    }
+    return out;
+}
+function contextDedupeKey(ctx) {
+    return ctx.appId == null ? ctx.name : `${ctx.name}\0${ctx.appId}`;
+}
+/**
+ * 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 function fetchRequiredStatusContexts(repo, branch, runGh) {
+    const found = new Map();
+    const sources = [];
+    const notes = [];
+    let hardFailure = false;
+    const encoded = encodeURIComponent(branch);
+    const rulesRc = runGh(["gh", "api", `repos/${repo}/rules/branches/${encoded}`]);
+    if (rulesRc.returncode === 0) {
+        if (!rulesRc.stdout.trim()) {
+            // Exit-zero empty body is not a trusted empty inventory (#3234 conf residual).
+            notes.push("rules/branches: empty body");
+            hardFailure = true;
+        }
+        else {
+            try {
+                const payload = JSON.parse(rulesRc.stdout);
+                const fromRules = contextsFromBranchRules(payload);
+                // Successful parse (including `[]`) is trusted; only non-empty contributes.
+                if (fromRules.length > 0) {
+                    for (const c of fromRules) {
+                        found.set(contextDedupeKey(c), c);
+                    }
+                    sources.push("rulesets");
+                }
+                else {
+                    sources.push("rulesets");
+                }
+            }
+            catch (exc) {
+                const message = exc instanceof Error ? exc.message : String(exc);
+                notes.push(`rules/branches parse: ${message}`);
+                hardFailure = true;
+            }
+        }
+    }
+    else {
+        // Soft-skip only when the error text clearly indicates no rulesets.
+        // Nonzero with empty stderr (or other errors) is fail-closed (#3234).
+        const err = rulesRc.stderr.trim();
+        if (/404|Not Found/i.test(err)) {
+            // no rulesets — soft empty contribution
+        }
+        else {
+            notes.push(`rules/branches: ${err || `exit ${rulesRc.returncode}`}`);
+            hardFailure = true;
+        }
+    }
+    const protRc = runGh(["gh", "api", `repos/${repo}/branches/${encoded}/protection`]);
+    if (protRc.returncode === 0) {
+        if (!protRc.stdout.trim()) {
+            notes.push("branches/protection: empty body");
+            hardFailure = true;
+        }
+        else {
+            try {
+                const payload = JSON.parse(protRc.stdout);
+                const fromProt = contextsFromBranchProtection(payload);
+                if (fromProt.length > 0) {
+                    for (const c of fromProt) {
+                        found.set(contextDedupeKey(c), c);
+                    }
+                    sources.push("branch_protection");
+                }
+                else {
+                    // Successful protection payload with no required checks still counts
+                    // as a trusted source (inventory empty intentionally).
+                    sources.push("branch_protection");
+                }
+            }
+            catch (exc) {
+                const message = exc instanceof Error ? exc.message : String(exc);
+                notes.push(`branches/protection parse: ${message}`);
+                hardFailure = true;
+            }
+        }
+    }
+    else {
+        const err = protRc.stderr.trim();
+        if (/404|Not Found|Branch not protected/i.test(err)) {
+            // no classic protection — soft empty contribution
+        }
+        else {
+            notes.push(`branches/protection: ${err || `exit ${protRc.returncode}`}`);
+            hardFailure = true;
+        }
+    }
+    const contexts = [...found.values()].sort((a, b) => requiredContextLabel(a).localeCompare(requiredContextLabel(b)));
+    // Fail closed on any hard error (parse / non-404), even when another source
+    // contributed contexts. Partial inventory can omit unique required checks
+    // from the failed source (#3234 Greptile conf residual).
+    const resolutionFailed = hardFailure;
+    return {
+        contexts,
+        sources,
+        error: notes.join("; "),
+        resolutionFailed,
+    };
+}
 //# sourceMappingURL=gh.js.map

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

@@ -1,8 +1,8 @@
 export { buildCiSummaryLine, type CiCheckConclusion, type CiGateOptions, type CiGateResult, type CiGateSummary, type CiReadyState, evaluateCiGate, isAuthoritativeSuiteAggregator, isBotReviewCheck, suiteFamilyOf, } from "./ci-gate.js";
-export { type ComputeGateOptions, computeGateResult, type FetchMergeabilityFn } from "./compute.js";
+export { type ComputeGateOptions, computeGateResult, type FetchMergeabilityFn, type FetchRequiredContextsFn, } from "./compute.js";
 export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
-export { defaultRunGh } from "./gh.js";
+export { checkRunMatchesRequiredContext, contextsFromBranchProtection, contextsFromBranchRules, defaultRunGh, fetchPrBaseRef, fetchRequiredStatusContexts, normalizeRequiredContexts, type RequiredStatusContext, type RequiredStatusContextsResult, requiredContextLabel, } from "./gh.js";
 export { evaluateInlineReviewThreads, fetchUnresolvedGreptileInlineFindings, headShaMatches, type InlineGreptileFindings, type InlineReviewComment, type InlineReviewThread, inlineFindingsToDict, } from "./greptile-inline.js";
 export { cmdPrMergeReadiness, parseArgs, run } from "./main.js";
 export { fetchMergeability, isGithubMergeableClean, MERGE_STATE_CLEAN, type MergeabilitySignal, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";

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

@@ -1,8 +1,8 @@
 export { buildCiSummaryLine, evaluateCiGate, isAuthoritativeSuiteAggregator, isBotReviewCheck, suiteFamilyOf, } from "./ci-gate.js";
-export { computeGateResult } from "./compute.js";
+export { computeGateResult, } from "./compute.js";
 export * from "./constants.js";
 export { evaluateGates, isMergeReady } from "./evaluate.js";
-export { defaultRunGh } from "./gh.js";
+export { checkRunMatchesRequiredContext, contextsFromBranchProtection, contextsFromBranchRules, defaultRunGh, fetchPrBaseRef, fetchRequiredStatusContexts, normalizeRequiredContexts, requiredContextLabel, } from "./gh.js";
 export { evaluateInlineReviewThreads, fetchUnresolvedGreptileInlineFindings, headShaMatches, inlineFindingsToDict, } from "./greptile-inline.js";
 export { cmdPrMergeReadiness, parseArgs, run } from "./main.js";
 export { fetchMergeability, isGithubMergeableClean, MERGE_STATE_CLEAN, mergeabilityToDict, verdictBlockIsSoftOnly, verdictShaIsStale, } from "./mergeability.js";

package/dist/pr-merge-readiness/test-gh-fixtures.helpers.js

@@ -57,6 +57,9 @@ export function fakeRunGhForMonitor(options = {}) {
                 stderr: "",
             };
         }
+        if (joined.includes("/rules/branches/") || joined.includes("/protection")) {
+            return { returncode: 1, stdout: "", stderr: "HTTP 404: Not Found" };
+        }
         if (joined.includes("/pulls/")) {
             return {
                 returncode: 0,
@@ -66,6 +69,7 @@ export function fakeRunGhForMonitor(options = {}) {
                     mergeable: true,
                     mergeable_state: "clean",
                     head: { sha: headSha },
+                    base: { ref: "master" },
                 }),
                 stderr: "",
             };

package/dist/pr-wait-mergeable/cascade.d.ts

@@ -1,3 +1,4 @@
+import { type EnforceMergeApprovalHeadInput, type MergeApprovalHeadResult } from "../policy/merge-approval-head.js";
 import { type AgentMergeEvaluateResult } from "../policy/require-human-merge.js";
 import { type SemanticGreenFn } from "./semantic-green.js";
 import type { MergeFn, MonitorFn, ProtectedCheckFn, WaitMergeableResult } from "./types.js";
@@ -23,6 +24,16 @@ export interface WaitMergeableOptions {
     readonly agentMergeFn?: (projectRoot: string) => AgentMergeEvaluateResult;
     /** When true, skip human-merge / intent preflight (tests only). */
     readonly skipHumanMergeGate?: boolean;
+    /**
+     * When true, skip head-bound plan:approved gate (#3235).
+     * Default: same as skipHumanMergeGate (test harnesses that skip human-merge
+     * also skip head-binding unless they opt in with skipMergeApprovalHeadGate=false).
+     */
+    readonly skipMergeApprovalHeadGate?: boolean;
+    /** Inject head-bound approval enforcer (unit tests). */
+    readonly mergeApprovalHeadFn?: (input: EnforceMergeApprovalHeadInput) => MergeApprovalHeadResult;
+    /** Inject PR HEAD fetch (unit tests; defaults to REST `pulls/<N>`). */
+    readonly fetchPrHeadShaFn?: (prNumber: number, repo: string | null) => string | null;
     /**
      * Post-merge umbrella reconcile (#1649). Defaults to live reconcileUmbrellas.
      * Pass `null` to skip (unit tests that inject mergeFn must pass null so they

package/dist/pr-wait-mergeable/cascade.js

@@ -1,4 +1,5 @@
 import { evaluateIntentCeilingFromEnv } from "../policy/intent-ceiling.js";
+import { disablePullRequestAutoMerge, enforceMergeApprovalHead, fetchPrHeadShaRest, } from "../policy/merge-approval-head.js";
 import { evaluateAgentMerge, } from "../policy/require-human-merge.js";
 import { reconcileUmbrellas, renderUmbrellasReport } from "../vbrief-reconcile/umbrellas.js";
 import { classifyMonitorOutcome, parseMonitorPayload } from "./classify.js";
@@ -40,6 +41,32 @@ export function waitMergeableAndMerge(prNumber, repo, options) {
                 error: intent.reason,
             });
         }
+        // #3235: revoke stale head-bound approval / auto-merge even when human-merge
+        // will refuse the bot merge — otherwise auto-merge can land a later HEAD.
+        if (options.skipMergeApprovalHeadGate !== true) {
+            const headGateFn = options.mergeApprovalHeadFn ?? enforceMergeApprovalHead;
+            const earlyHead = headGateFn({
+                prNumber,
+                repo,
+                projectRoot,
+                currentHeadSha: null,
+                fetchHeadShaFn: fetchPrHeadShaRest,
+                disableAutoMergeOnDeny: true,
+            });
+            if (!earlyHead.allowed) {
+                const parts = [earlyHead.message];
+                if (earlyHead.recovery !== null) {
+                    parts.push("", earlyHead.recovery);
+                }
+                return makeResult({
+                    prNumber,
+                    repo,
+                    outcome: "stale-merge-approval",
+                    exitCode: EXIT_CONFIG_ERROR,
+                    error: parts.join("\n"),
+                });
+            }
+        }
         const agentMergeFn = options.agentMergeFn ?? evaluateAgentMerge;
         const hm = agentMergeFn(projectRoot);
         if (!hm.allowed) {
@@ -121,7 +148,94 @@ export function waitMergeableAndMerge(prNumber, repo, options) {
             error: errorPayload,
         });
     }
-    const [mergeRc, mergeStdout, mergeStderr] = mergeFn(prNumber, repo);
+    // #3235: head-bound plan:approved — refuse merge when approval is stale vs
+    // current HEAD; best-effort disable auto-merge + recovery instructions.
+    // Re-read live HEAD immediately before merge (TOCTOU / Greptile P1) and pin
+    // `gh pr merge --match-head-commit` to that exact SHA.
+    // Default skip when human-merge gate is skipped (unit-test harness convention).
+    const skipHeadGate = options.skipMergeApprovalHeadGate === true ||
+        (options.skipMergeApprovalHeadGate === undefined && options.skipHumanMergeGate === true);
+    let matchHeadCommit = null;
+    if (!skipHeadGate) {
+        const readiness = typeof monitorPayload.readiness === "object" &&
+            monitorPayload.readiness !== null &&
+            !Array.isArray(monitorPayload.readiness)
+            ? monitorPayload.readiness
+            : {};
+        const headFromMonitor = typeof readiness.head_sha === "string"
+            ? readiness.head_sha
+            : typeof monitorPayload.head_sha === "string"
+                ? monitorPayload.head_sha
+                : null;
+        const headGateFn = options.mergeApprovalHeadFn ?? enforceMergeApprovalHead;
+        const fetchHead = options.fetchPrHeadShaFn ?? fetchPrHeadShaRest;
+        // Live HEAD only — never authorize against a stale monitor snapshot when
+        // the REST read fails (would pin A while GitHub head is B).
+        const liveHead = fetchHead(prNumber, repo);
+        if (liveHead === null || liveHead.trim() === "") {
+            disablePullRequestAutoMerge(prNumber, repo);
+            return makeResult({
+                prNumber,
+                repo,
+                outcome: "stale-merge-approval",
+                exitCode: EXIT_CONFIG_ERROR,
+                monitorResult: monitorPayload,
+                protectedCheck: protectedCheckPayload,
+                error: `❌ merge-approval-head (#3235): cannot read live PR HEAD for #${prNumber}` +
+                    (headFromMonitor !== null ? ` (monitor had ${headFromMonitor.slice(0, 12)})` : "") +
+                    "; refusing merge and disabling auto-merge (fail closed).",
+            });
+        }
+        const headGate = headGateFn({
+            prNumber,
+            repo,
+            projectRoot,
+            currentHeadSha: liveHead,
+            disableAutoMergeOnDeny: true,
+        });
+        if (!headGate.allowed) {
+            const parts = [headGate.message];
+            if (headGate.recovery !== null) {
+                parts.push("", headGate.recovery);
+            }
+            return makeResult({
+                prNumber,
+                repo,
+                outcome: "stale-merge-approval",
+                exitCode: EXIT_CONFIG_ERROR,
+                monitorResult: monitorPayload,
+                protectedCheck: protectedCheckPayload,
+                error: parts.join("\n"),
+            });
+        }
+        matchHeadCommit = liveHead;
+    }
+    else {
+        // Gate skipped: still prefer a live HEAD pin when available.
+        const fetchHead = options.fetchPrHeadShaFn ?? fetchPrHeadShaRest;
+        matchHeadCommit = fetchHead(prNumber, repo);
+        if (matchHeadCommit === null) {
+            const readiness = typeof monitorPayload.readiness === "object" &&
+                monitorPayload.readiness !== null &&
+                !Array.isArray(monitorPayload.readiness)
+                ? monitorPayload.readiness
+                : {};
+            if (typeof readiness.head_sha === "string") {
+                matchHeadCommit = readiness.head_sha;
+            }
+            else if (typeof monitorPayload.head_sha === "string") {
+                matchHeadCommit = monitorPayload.head_sha;
+            }
+        }
+    }
+    const [mergeRc, mergeStdout, mergeStderr] = mergeFn(prNumber, repo, {
+        matchHeadCommit,
+    });
+    // Pinned merge rejected (head advanced mid-call): revoke auto-merge so the
+    // unapproved head cannot land later under retained GitHub auto-merge.
+    if (mergeRc !== 0 && options.skipMergeApprovalHeadGate !== true) {
+        disablePullRequestAutoMerge(prNumber, repo);
+    }
     if (mergeRc === 0) {
         // Best-effort umbrella checklist + current-shape refresh after child merge (#1649).
         // Failures must not flip a successful merge into an error exit.

package/dist/pr-wait-mergeable/main.d.ts

@@ -18,6 +18,10 @@ export interface RunWaitMergeableOptions {
     readonly monitorFn?: Parameters<typeof waitMergeableAndMerge>[2]["monitorFn"];
     readonly mergeFn?: Parameters<typeof waitMergeableAndMerge>[2]["mergeFn"];
     readonly semanticGreenFn?: Parameters<typeof waitMergeableAndMerge>[2]["semanticGreenFn"];
+    readonly skipHumanMergeGate?: boolean;
+    readonly skipMergeApprovalHeadGate?: boolean;
+    readonly fetchPrHeadShaFn?: Parameters<typeof waitMergeableAndMerge>[2]["fetchPrHeadShaFn"];
+    readonly mergeApprovalHeadFn?: Parameters<typeof waitMergeableAndMerge>[2]["mergeApprovalHeadFn"];
 }
 export declare function runWaitMergeable(argv: readonly string[], options?: RunWaitMergeableOptions): number;
 export declare function cmdPrWaitMergeable(argv: readonly string[], options?: RunWaitMergeableOptions): number;

package/dist/pr-wait-mergeable/main.js

@@ -170,6 +170,10 @@ export function runWaitMergeable(argv, options = {}) {
         // Explicit CLI root (or cwd) so remote-target cascade does not resolve
         // minGreptileConfidence from an unrelated directory (#3102).
         projectRoot: args.projectRoot ?? process.cwd(),
+        skipHumanMergeGate: options.skipHumanMergeGate,
+        skipMergeApprovalHeadGate: options.skipMergeApprovalHeadGate,
+        fetchPrHeadShaFn: options.fetchPrHeadShaFn,
+        mergeApprovalHeadFn: options.mergeApprovalHeadFn,
     });
     const summaryLabel = summaryLabelForExit(result.exitCode);
     process.stderr.write(`[pr_wait_mergeable] PR #${result.prNumber} repo=${result.repo} ` +

package/dist/pr-wait-mergeable/types.d.ts

@@ -15,5 +15,7 @@ export type ProtectedCheckFn = (prNumber: number, repo: string | null, protected
 export type MonitorFn = (prNumber: number, repo: string, capMinutes: number, options?: {
     readonly projectRoot?: string;
 }) => SubprocessTriple;
-export type MergeFn = (prNumber: number, repo: string | null) => SubprocessTriple;
+export type MergeFn = (prNumber: number, repo: string | null, options?: {
+    readonly matchHeadCommit?: string | null;
+}) => SubprocessTriple;
 //# sourceMappingURL=types.d.ts.map

package/dist/pr-wait-mergeable/wrappers.d.ts

@@ -46,7 +46,12 @@ export interface RunMonitorOptions {
 export declare function runMonitor(prNumber: number, repo: string, capMinutes: number, options?: RunMonitorOptions): SubprocessTriple;
 export interface RunGhMergeOptions {
     readonly timeout?: number;
+    /**
+     * Pin merge to this exact head SHA via `gh pr merge --match-head-commit`
+     * (#3235 TOCTOU: refuse merge if PR head advanced after approval gate).
+     */
+    readonly matchHeadCommit?: string | null;
 }
-/** Invoke ``gh pr merge --squash --delete-branch --admin``. */
+/** Invoke ``gh pr merge --squash --delete-branch --admin`` [``--match-head-commit``]. */
 export declare function runGhMerge(prNumber: number, repo: string | null, options?: RunGhMergeOptions): SubprocessTriple;
 //# sourceMappingURL=wrappers.d.ts.map

package/dist/pr-wait-mergeable/wrappers.js

@@ -126,7 +126,7 @@ export function runMonitor(prNumber, repo, capMinutes, options = {}) {
     });
     return [result.returncode, result.stdout, result.stderr];
 }
-/** Invoke ``gh pr merge --squash --delete-branch --admin``. */
+/** Invoke ``gh pr merge --squash --delete-branch --admin`` [``--match-head-commit``]. */
 export function runGhMerge(prNumber, repo, options = {}) {
     const timeoutSec = options.timeout ?? 120;
     let binary;
@@ -140,6 +140,12 @@ export function runGhMerge(prNumber, repo, options = {}) {
     if (repo) {
         args.push("--repo", repo);
     }
+    const matchHead = typeof options.matchHeadCommit === "string" && options.matchHeadCommit.trim().length > 0
+        ? options.matchHeadCommit.trim()
+        : null;
+    if (matchHead !== null) {
+        args.push("--match-head-commit", matchHead);
+    }
     const result = captureExec(binary, args, timeoutSec * 1000);
     if (result.returncode === -1) {
         if (result.stderr.includes("timed out after")) {

package/dist/preflight/evaluate.d.ts

@@ -1,3 +1,4 @@
+import { type ParentLineageResult } from "../scope/parent-lineage.js";
 /** Canonical eligibility folder — only vbrief/active/ may spawn implementation. */
 export declare const ACTIVE_FOLDER = "active";
 /** Canonical eligibility status — only `running` signals an active handoff. */
@@ -11,6 +12,14 @@ export declare const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight --
 export interface EvaluateResult {
     readonly exitCode: 0 | 1;
     readonly message: string;
+    /** #3241 parent-lineage probe when structural checks passed far enough to load the payload. */
+    readonly parentLineage?: ParentLineageResult;
+}
+export interface EvaluateOptions {
+    /** Project root for resolving child planRef → parent (#3241). */
+    readonly projectRoot?: string;
+    /** Skip parent-lineage check (tests / opt-out). Default false. */
+    readonly skipParentLineage?: boolean;
 }
 /** Substitute `{path}` without `$`-pattern expansion in user paths (#1721). */
 export declare function formatActivateHint(path: string): string;
@@ -18,8 +27,13 @@ export declare function formatActivateHint(path: string): string;
  * Pure evaluator — returns `{ exitCode, message }`. Never throws; every error
  * path collapses to exit 1 with an actionable message. Faithful to
  * `scripts/preflight_implementation.py::evaluate`.
+ *
+ * #3241: after active+running + intent ceiling, re-check parent requirement
+ * lineage (coverage + approved behavioral deltas). Fail closed on missing
+ * coverage or undeclared deltas when the parent authors requirement IDs.
  */
-export declare function evaluate(vbriefPath: string): EvaluateResult;
+export declare function evaluate(vbriefPath: string, options?: EvaluateOptions): EvaluateResult;
+export { evaluateParentLineage, formatParentLineageLine, type ParentLineageResult, } from "../scope/parent-lineage.js";
 /** Structured `--json` payload (sorted keys), mirroring Python `_emit_json`. */
 export declare function emitJson(vbriefPath: string, exitCode: number, message: string): string;
 //# sourceMappingURL=evaluate.d.ts.map

package/dist/preflight/evaluate.js

@@ -1,6 +1,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { evaluateIntentCeilingFromEnv } from "../policy/intent-ceiling.js";
+import { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 /** Canonical eligibility folder — only vbrief/active/ may spawn implementation. */
 export const ACTIVE_FOLDER = "active";
 /** Canonical eligibility status — only `running` signals an active handoff. */
@@ -37,8 +38,12 @@ function nodeJsonErrorToPythonMsg(nodeMessage) {
  * Pure evaluator — returns `{ exitCode, message }`. Never throws; every error
  * path collapses to exit 1 with an actionable message. Faithful to
  * `scripts/preflight_implementation.py::evaluate`.
+ *
+ * #3241: after active+running + intent ceiling, re-check parent requirement
+ * lineage (coverage + approved behavioral deltas). Fail closed on missing
+ * coverage or undeclared deltas when the parent authors requirement IDs.
  */
-export function evaluate(vbriefPath) {
+export function evaluate(vbriefPath, options = {}) {
     const path = vbriefPath;
     let st;
     try {
@@ -134,11 +139,37 @@ export function evaluate(vbriefPath) {
             message: buildReject(path, intent.reason),
         };
     }
+    // #3241 pre-PR / implementation preflight: parent lineage fail-closed.
+    const lineage = evaluateParentLineage({
+        child: record,
+        childPath: path,
+        projectRoot: options.projectRoot,
+        skip: options.skipParentLineage === true,
+    });
+    if (!lineage.ok) {
+        const defect = lineage.defect_class !== null ? ` [defect_class=${lineage.defect_class}]` : "";
+        return {
+            exitCode: 1,
+            parentLineage: lineage,
+            message: buildReject(path, `${lineage.message}${defect}\n  ${formatParentLineageLine(lineage)}`),
+        };
+    }
+    // Keep the historical OK line when lineage is N/A (backward-compatible tests / agents).
+    const message = lineage.applicable
+        ? `OK ${path} -- ready for implementation. parent lineage OK ` +
+            `(${lineage.parent_requirement_ids.length} req IDs` +
+            (lineage.negative_invariant_ids.length > 0
+                ? `, ${lineage.negative_invariant_ids.length} negative invariants`
+                : "") +
+            `).`
+        : `OK ${path} -- ready for implementation.`;
     return {
         exitCode: 0,
-        message: `OK ${path} -- ready for implementation.`,
+        parentLineage: lineage,
+        message,
     };
 }
+export { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 /** Structured `--json` payload (sorted keys), mirroring Python `_emit_json`. */
 export function emitJson(vbriefPath, exitCode, message) {
     const payload = {