@deftai/directive-core 0.107.0 → 0.108.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-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).

package/dist/pr-protected-issues/gh.js

@@ -2,12 +2,16 @@ 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 } from "./constants.js";
-/** UTF-8-safe gh capture via execFile (no shell) — mirrors _safe_subprocess.run_text (#1366). */
-export function defaultRunGh(cmd) {
+/**
+ * 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 function defaultRunGh(cmd, binaryOverride) {
     if (cmd.length === 0 || cmd[0] !== "gh") {
         return { returncode: -1, stdout: "", stderr: "expected gh as first argv element" };
     }
-    const binary = resolveBinary();
+    const binary = binaryOverride ?? resolveBinary();
     const args = cmd.slice(1);
     try {
         const stdout = execFileSync(binary, args, {

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

@@ -1,7 +1,7 @@
 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";
+import type { CloseoutAttestableFn, MergeFn, MonitorFn, ProtectedCheckFn, WaitMergeableResult } from "./types.js";
 /** Post-merge umbrella checklist + current-shape refresh (#1649). */
 export type UmbrellaReconcileFn = (projectRoot: string, repo: string) => void;
 export interface WaitMergeableOptions {
@@ -32,6 +32,14 @@ export interface WaitMergeableOptions {
     readonly skipMergeApprovalHeadGate?: boolean;
     /** Inject head-bound approval enforcer (unit tests). */
     readonly mergeApprovalHeadFn?: (input: EnforceMergeApprovalHeadInput) => MergeApprovalHeadResult;
+    /**
+     * When true, skip the merge-time closeout attestability gate (#3781).
+     * Default: same as skipHumanMergeGate, matching the head-gate convention —
+     * test harnesses that skip human-merge also skip this unless they opt in.
+     */
+    readonly skipCloseoutAttestableGate?: boolean;
+    /** Inject the closeout attestability gate (unit tests). */
+    readonly closeoutAttestableFn?: CloseoutAttestableFn;
     /** Inject PR HEAD fetch (unit tests; defaults to REST `pulls/<N>`). */
     readonly fetchPrHeadShaFn?: (prNumber: number, repo: string | null) => string | null;
     /**

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

@@ -6,7 +6,7 @@ import { classifyMonitorOutcome, parseMonitorPayload } from "./classify.js";
 import { EXIT_CONFIG_ERROR, EXIT_MERGED, EXIT_TIMEOUT_OR_ESCALATION } from "./constants.js";
 import { makeResult } from "./result.js";
 import { evaluateSemanticGreen } from "./semantic-green.js";
-import { runGhMerge, runMonitor, runProtectedCheck } from "./wrappers.js";
+import { runCloseoutAttestableCheck, runGhMerge, runMonitor, runProtectedCheck, } from "./wrappers.js";
 /** Node module-not-found / missing script — not a protected-issue overlap (#2667). */
 function isProtectedCheckConfigFailure(stderr) {
     const tail = stderr.trim();
@@ -228,6 +228,26 @@ export function waitMergeableAndMerge(prNumber, repo, options) {
             }
         }
     }
+    // #3781: last gate before the merge call. A PR may leave a brief unattested; it
+    // may not merge one whose issue it closes in the same act. Keyed on the PR's
+    // closing references, so it fires even when the brief is not in the branch diff.
+    const skipCloseoutGate = options.skipCloseoutAttestableGate === true ||
+        (options.skipCloseoutAttestableGate === undefined && options.skipHumanMergeGate === true);
+    if (!skipCloseoutGate) {
+        const closeoutFn = options.closeoutAttestableFn ?? runCloseoutAttestableCheck;
+        const [coRc, , coStderr] = closeoutFn(prNumber, repo, projectRoot);
+        if (coRc !== 0) {
+            return makeResult({
+                prNumber,
+                repo,
+                outcome: coRc === 1 ? "closeout-unattested" : "config-error",
+                exitCode: coRc === 1 ? EXIT_TIMEOUT_OR_ESCALATION : EXIT_CONFIG_ERROR,
+                monitorResult: monitorPayload,
+                protectedCheck: protectedCheckPayload,
+                error: coStderr.trim(),
+            });
+        }
+    }
     const [mergeRc, mergeStdout, mergeStderr] = mergeFn(prNumber, repo, {
         matchHeadCommit,
     });

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

@@ -18,4 +18,6 @@ export type MonitorFn = (prNumber: number, repo: string, capMinutes: number, opt
 export type MergeFn = (prNumber: number, repo: string | null, options?: {
     readonly matchHeadCommit?: string | null;
 }) => SubprocessTriple;
+/** Merge-time closeout attestability gate (#3781): 0 attestable / 1 unattested / 2 lookup. */
+export type CloseoutAttestableFn = (prNumber: number, repo: string | null, projectRoot: string) => SubprocessTriple;
 //# sourceMappingURL=types.d.ts.map

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

@@ -32,6 +32,12 @@ export interface RunProtectedCheckOptions {
 }
 /** Invoke pr-protected-issues CLI and return (returncode, stdout, stderr). */
 export declare function runProtectedCheck(prNumber: number, repo: string | null, protectedIssues: readonly number[], options?: RunProtectedCheckOptions): SubprocessTriple;
+/**
+ * Merge-time closeout attestability gate (#3781). In-process: the evaluator lives
+ * in this package, and a subprocess hop would only add a script-path failure mode
+ * to a gate that must fail closed.
+ */
+export declare function runCloseoutAttestableCheck(prNumber: number, repo: string | null, projectRoot: string): SubprocessTriple;
 export interface RunMonitorOptions {
     readonly nodeExecutable?: string;
     readonly timeout?: number;

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

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { evaluate as evaluateCloseoutAttestable } from "../pr-closeout-attestable/evaluate.js";
 import { resolveBinary } from "../scm/binary.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 /** UTF-8-safe subprocess capture via spawnSync (no shell) — mirrors #1366. */
@@ -97,6 +98,16 @@ export function runProtectedCheck(prNumber, repo, protectedIssues, options = {})
     });
     return [result.returncode, result.stdout, result.stderr];
 }
+/**
+ * Merge-time closeout attestability gate (#3781). In-process: the evaluator lives
+ * in this package, and a subprocess hop would only add a script-path failure mode
+ * to a gate that must fail closed.
+ */
+export function runCloseoutAttestableCheck(prNumber, repo, projectRoot) {
+    const result = evaluateCloseoutAttestable(projectRoot, prNumber, { repo });
+    const text = result.message.length > 0 ? `${result.message}\n` : "";
+    return result.code === 0 ? [0, text, ""] : [result.code, "", text];
+}
 /** Invoke pr-monitor CLI with --json and return (returncode, stdout, stderr). */
 export function runMonitor(prNumber, repo, capMinutes, options = {}) {
     const scriptPath = cliScriptPath("pr-monitor");

package/dist/preflight/evaluate.d.ts

@@ -6,6 +6,19 @@ export declare const ACTIVE_FOLDER = "active";
 export declare const ELIGIBLE_STATUS = "running";
 /** Actionable redirect appended to every reject path (#810 / #2449). */
 export declare const ACTIVATE_HINT = "Run `task scope:activate -- {path}` (or legacy `task vbrief:activate -- {path}`) before spawning an implementation agent.";
+/**
+ * Recovery for the origin-freshness reject (#3828).
+ *
+ * Freshness is only reached after the active/ + running checks pass, so
+ * `ACTIVATE_HINT` names a transition that cannot apply here: `activate` accepts
+ * `pending/` alone and fails with `Invalid transition: 'activate' requires file
+ * in pending/`. `block` -> `unblock` is in place (`targetFolder: null`), requires
+ * and restores `running`, and stamps `plan.updated` plus `xBRIEFInfo.updated`,
+ * the field this reject compares. It is interim: the pair also records a
+ * `blocked` -> `running` transition for a brief that was never blocked, a
+ * tradeoff accepted knowingly. #3857 owns the dedicated acknowledge verb.
+ */
+export declare const ORIGIN_FRESHNESS_HINT: string;
 /** Lifecycle folder names eligible for implementation (#810). */
 export declare const ELIGIBLE_LIFECYCLE_DIRS: readonly ["xbrief/active", "vbrief/active"];
 export declare const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight -- xbrief/active/<story>.xbrief.json` (legacy: `task vbrief:preflight -- <path>`).";
@@ -32,6 +45,8 @@ export interface EvaluateOptions {
 }
 /** Substitute `{path}` without `$`-pattern expansion in user paths (#1721). */
 export declare function formatActivateHint(path: string): string;
+/** Substitute every `{path}` without `$`-pattern expansion in user paths (#1721). */
+export declare function formatOriginFreshnessHint(path: string): string;
 /**
  * Pure evaluator — returns `{ exitCode, message }`. Never throws; every error
  * path collapses to exit 1 with an actionable message. Faithful to

package/dist/preflight/evaluate.js

@@ -11,6 +11,26 @@ export const ACTIVE_FOLDER = "active";
 export const ELIGIBLE_STATUS = "running";
 /** Actionable redirect appended to every reject path (#810 / #2449). */
 export const ACTIVATE_HINT = "Run `task scope:activate -- {path}` (or legacy `task vbrief:activate -- {path}`) before spawning an implementation agent.";
+/**
+ * Recovery for the origin-freshness reject (#3828).
+ *
+ * Freshness is only reached after the active/ + running checks pass, so
+ * `ACTIVATE_HINT` names a transition that cannot apply here: `activate` accepts
+ * `pending/` alone and fails with `Invalid transition: 'activate' requires file
+ * in pending/`. `block` -> `unblock` is in place (`targetFolder: null`), requires
+ * and restores `running`, and stamps `plan.updated` plus `xBRIEFInfo.updated`,
+ * the field this reject compares. It is interim: the pair also records a
+ * `blocked` -> `running` transition for a brief that was never blocked, a
+ * tradeoff accepted knowingly. #3857 owns the dedicated acknowledge verb.
+ */
+export const ORIGIN_FRESHNESS_HINT = "Recovery: this xBRIEF is already in active/ at status running. " +
+    "Once you have re-read the origin delta, stamp xBRIEFInfo.updated in place with " +
+    "`task scope:block -- {path}` then `task scope:unblock -- {path}`. " +
+    "That pair is interim: it records a blocked -> running transition for a brief " +
+    "that was never blocked, and #3857 owns the verb that records the " +
+    "acknowledgement honestly. If the origin could not be fetched or compared, " +
+    "restore `gh` REST access to the origin repository first -- a stamp does not " +
+    "clear that.";
 /** Lifecycle folder names eligible for implementation (#810). */
 export const ELIGIBLE_LIFECYCLE_DIRS = ["xbrief/active", "vbrief/active"];
 export const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight -- xbrief/active/<story>.xbrief.json` (legacy: `task vbrief:preflight -- <path>`).";
@@ -18,8 +38,12 @@ export const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight -- xbrief/
 export function formatActivateHint(path) {
     return ACTIVATE_HINT.replace("{path}", () => path);
 }
-function buildReject(path, reason) {
-    return `${reason}\n  ${PREFLIGHT_USAGE_HINT}\n  ${formatActivateHint(path)}`;
+/** Substitute every `{path}` without `$`-pattern expansion in user paths (#1721). */
+export function formatOriginFreshnessHint(path) {
+    return ORIGIN_FRESHNESS_HINT.split("{path}").join(path);
+}
+function buildReject(path, reason, hint) {
+    return `${reason}\n  ${PREFLIGHT_USAGE_HINT}\n  ${hint ?? formatActivateHint(path)}`;
 }
 /** Map Node `JSON.parse` errors to CPython `json.JSONDecodeError.msg` for parity (#1721). */
 function nodeJsonErrorToPythonMsg(nodeMessage) {
@@ -167,7 +191,9 @@ export function evaluate(vbriefPath, options = {}) {
         return {
             exitCode: 1,
             parentLineage: lineage,
-            message: buildReject(path, originFreshness.message),
+            // #3828: the brief is active + running by this point, so the activate
+            // hint would name a transition that hard-errors from the printed state.
+            message: buildReject(path, originFreshness.message, formatOriginFreshnessHint(path)),
         };
     }
     // #3425: fail closed when an applicable project invariant has no disposition.

package/dist/product-first-done-gate/acceptance-resolver.d.ts

@@ -93,18 +93,30 @@ export declare function resolveAcceptanceVerdict(reading: AcceptanceReading): Ac
 /** One line naming the predicate and the value it read (#3497). */
 export declare function formatAcceptanceVerdict(verdictResult: AcceptanceVerdict): string;
 /**
- * Clause-walk composition (#3323 / #3497).
+ * Clause-walk composition (#3323 / #3497 / #3826).
  *
  * A clause the shipped artifact contradicts (`failed`) always blocks. A clause the
  * static walk cannot decide (`unverifiable`) is evidence of nothing — it blocks only
  * when nothing else verified the product. A green executable acceptance run IS that
  * something: the product-first oracle already ran. Before #3497 an all-unverifiable
  * clause set refused an artifact whose stated command had just exited 0.
+ *
+ * #3826 excused a set the walk has no oracle for at all: a clause with no bound
+ * artifact path can only ever come back `unverifiable`, so demanding a positive
+ * `verified` from a set of them cannot be satisfied by doing the work correctly.
+ * Where the walk has no oracle, `failed === 0` is the strongest verdict available
+ * and `evaluateAcceptanceEvidenceGate` adjudicates those criteria at `scope:complete`.
+ *
+ * #3835 makes that excusal per clause. As a *set* predicate, `verified > 0` was
+ * re-armed for every clause by any single bound one, so one verified binding
+ * covered siblings that had their own oracle and did not meet it.
+ * `adjudicableUnverified` counts exactly those siblings.
  */
 export declare function clauseWalkBlocks(input: {
     readonly failed: number;
-    readonly verified: number;
     readonly walked: number;
+    /** Clauses the walk had an oracle for and that did not come back `verified`. */
+    readonly adjudicableUnverified: number;
     readonly hasGreenExecutableRun: boolean;
 }): boolean;
 /** Which consumer is reading acceptance. Selects one shared option profile (#3497). */