@deftai/directive-core 0.106.0 → 0.108.0

package/dist/policy/value-feedback.js

@@ -1,5 +1,4 @@
-import { readFileSync } from "node:fs";
-import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { valueFeedbackInstallForceOnSource } from "./org-force-on-migration.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 import { policyColonInvocation } from "./policy-invocation.js";
@@ -219,14 +218,10 @@ export function enableValueFeedback(projectRoot, options) {
             changed: false,
         };
     }
-    const path = projectDefinitionPath(projectRoot);
+    const _path = projectDefinitionPath(projectRoot);
     try {
-        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
-            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-            }
-            const data = parsed;
+        const { changed } = withProjectDefinitionMutation(projectRoot, (mutation) => {
+            const data = mutation.load();
             if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
                 if (data.plan === undefined) {
                     data.plan = {};
@@ -277,7 +272,7 @@ export function enableValueFeedback(projectRoot, options) {
                 legacyKeyMigrated;
             policyBlock.valueFeedback = nextBlock;
             if (changedFlag) {
-                atomicWriteProjectDefinition(path, data);
+                mutation.persist(data);
             }
             const actor = options.actor ?? policyColonInvocation("enable-value-feedback");
             const note = options.note ?? "";
@@ -317,14 +312,10 @@ export function enableValueFeedback(projectRoot, options) {
  * updates will not re-force against intentional opt-out.
  */
 export function clearValueFeedback(projectRoot, options = {}) {
-    const path = projectDefinitionPath(projectRoot);
+    const _path = projectDefinitionPath(projectRoot);
     try {
-        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
-            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-            }
-            const data = parsed;
+        const { changed } = withProjectDefinitionMutation(projectRoot, (mutation) => {
+            const data = mutation.load();
             if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
                 throw new Error("PROJECT-DEFINITION 'plan' is not an object");
             }
@@ -342,7 +333,7 @@ export function clearValueFeedback(projectRoot, options = {}) {
             }
             const previous = policyBlock.valueFeedback;
             delete policyBlock.valueFeedback;
-            atomicWriteProjectDefinition(path, data);
+            mutation.persist(data);
             const actor = options.actor ?? policyColonInvocation("clear-value-feedback");
             const note = options.note ?? "";
             const parts = [

package/dist/policy/write-fence.js

@@ -140,6 +140,9 @@ export function resolveWriteFence(projectPolicy, storyFileScope, options) {
         allowPaths,
         denyPaths,
         scopes,
+        // Carry the project setting through: resolving a write fence must not
+        // silently enable Shell dest-form enforcement for a story (#3438 / #3594).
+        shellDestForms: projectPolicy.shellDestForms,
         storyAllowPaths: storyAllow,
         fenceSources: sources,
     };

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