@deftai/directive-core 0.107.0 → 0.109.0

package/dist/architecture/sor-preflight.js

@@ -16,6 +16,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 import { hasArtifactSuffix, LIFECYCLE_DIR_NAMES } from "../layout/resolve.js";
+import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 // ---------------------------------------------------------------------------
 // Classification constants
 // ---------------------------------------------------------------------------
@@ -776,6 +777,7 @@ function gitDiff(projectRoot, baseRef) {
         cwd: resolve(projectRoot),
         encoding: "utf8",
         timeout: 30_000,
+        maxBuffer: SUBPROCESS_MAX_BUFFER,
     });
     if (result.error) {
         return [

package/dist/cache/operations.js

@@ -107,7 +107,7 @@ export function cachePut(source, key, raw, options = {}) {
     const rawSize = Buffer.byteLength(rawText, "utf8");
     // #1870 Greptile P2: account for current-shape sidecar bytes in cap + meta
     // so usage does not underreport by the cumulative sidecar size.
-    const plannedSidecar = buildCurrentShapeSidecar(raw);
+    const plannedSidecar = buildCurrentShapeSidecar(raw).sidecar;
     const plannedSidecarText = plannedSidecar !== null
         ? `${pythonJsonDump({
             ...plannedSidecar,

package/dist/check/cached-orchestrator.js

@@ -6,6 +6,7 @@ import { readCorePackageVersion } from "../engine-version.js";
 import { applyProductFirstGateMode, EMPTY_AC_CAUSE, EMPTY_AC_REMEDY, isHygieneGate, isProductAcGate, isSoftEmptyAcText, resolveProductFirstCheckMode, } from "../product-first-done-gate/index.js";
 import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { runToolchainPreflight, SKIP_ALL_GATES, } from "../session/toolchain-preflight.js";
+import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { checkGateCliArgv, cliSpawnPlan, resolveGateDispatch, resolveGlobalCliBin, } from "./cli-native-gates.js";
 import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "./consumer-gate-integrity.js";
 import { resolveCheckTarget } from "./context.js";
@@ -17,6 +18,7 @@ function captureSpawn(taskBin, args, opts) {
         cwd: opts.cwd,
         encoding: "utf8",
         env: opts.env ?? process.env,
+        maxBuffer: SUBPROCESS_MAX_BUFFER,
     });
     if (result.error !== undefined) {
         return {
@@ -40,6 +42,27 @@ function writeLines(lines, stream = "stderr") {
         write(`${line}\n`);
     }
 }
+function firstImpactingMissingFinding(preflight) {
+    const missing = preflight?.findings.filter((finding) => !finding.present) ?? [];
+    const impacting = missing.filter((finding) => finding.impact !== "none");
+    const priority = [
+        "node",
+        "task",
+        "cli_dist",
+        "package_manager",
+        preflight?.packageManager,
+        "npm",
+        "pnpm",
+    ];
+    for (const tool of priority) {
+        if (tool === null || tool === undefined)
+            continue;
+        const finding = impacting.find((candidate) => candidate.tool === tool);
+        if (finding !== undefined)
+            return finding;
+    }
+    return impacting[0] ?? missing[0];
+}
 /**
  * Run check gates sequentially with content-hash caching (#1713).
  * Falls back to fail-open execution for undeclared / non-cacheable gates.
@@ -135,6 +158,7 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
             composedGates: gates,
             consumerDeposit: target === "check:consumer",
             which,
+            env: options.env,
         })
         : options.preflight;
     const taskPresent = preflight === null || !preflight.findings.some((f) => f.tool === "task" && !f.present);
@@ -165,8 +189,9 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
         if (allSkipped) {
             const skipped = gates.map((g) => {
                 const id = checkGateId(g);
-                const cause = preflight?.findings.find((f) => !f.present)?.cause ?? "toolchain preflight degraded";
-                const remedy = preflight?.findings.find((f) => !f.present)?.remedy ?? remedyForGate(id, cause);
+                const missing = firstImpactingMissingFinding(preflight);
+                const cause = missing?.cause ?? "toolchain preflight degraded";
+                const remedy = missing?.remedy ?? remedyForGate(id, cause);
                 gateOutcomes.push({ id, status: "skipped", cause, remedy });
                 return { id, cause, remedy };
             });
@@ -183,7 +208,7 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
         const gateId = checkGateId(gateSpec);
         // #3282: skip gates that require missing tools (e.g. pnpm-only suite).
         if (skipSet.has(gateId)) {
-            const missing = preflight?.findings.find((f) => !f.present);
+            const missing = firstImpactingMissingFinding(preflight);
             const cause = missing?.cause ?? "toolchain preflight marked gate skippable";
             const remedy = missing?.remedy ?? remedyForGate(gateId, cause);
             process.stderr.write(`check: skipping gate ${gateId} (degraded) — cause: ${cause}; remedy: ${remedy}\n`);

package/dist/check/gate-lists.d.ts

@@ -15,6 +15,20 @@ export type CheckGateSpec = string | {
  * xbrief/completed instead of skipping (#3357).
  */
 export declare const PRODUCT_FIRST_AC_GATE: CheckGateSpec;
+/**
+ * Candidate-scoped orphan-active for check aggregates (#3893).
+ *
+ * The unscoped sweep on the merge chokepoint gave a brief stranded by one
+ * merge authority over every other open PR, and N stranded briefs made N
+ * single-brief lifecycle PRs mutually unmergeable. It was never preventive for
+ * the candidate either: that candidate's linked PR still reads
+ * `merged_at: null` while its own gate runs.
+ *
+ * Bare `verify:orphan-active` stays repo-wide for `deft doctor`, manual runs,
+ * swarm finalize, and the after-merge `--issue N` DONE gate (#3429); the
+ * scoped form still falls back to the full sweep at the delivery tip.
+ */
+export declare const ORPHAN_ACTIVE_MERGE_GATE: CheckGateSpec;
 export declare function checkGateId(spec: CheckGateSpec): string;
 /** Args for `task … --taskfile <path>` (optional `--` + public CLI flags). */
 export declare function checkGateSpawnArgs(spec: CheckGateSpec, taskfilePath: string): string[];

package/dist/check/gate-lists.js

@@ -9,6 +9,23 @@ export const PRODUCT_FIRST_AC_GATE = {
     task: PRODUCT_AC_GATE_ID,
     args: ["--soft-missing-xbrief"],
 };
+/**
+ * Candidate-scoped orphan-active for check aggregates (#3893).
+ *
+ * The unscoped sweep on the merge chokepoint gave a brief stranded by one
+ * merge authority over every other open PR, and N stranded briefs made N
+ * single-brief lifecycle PRs mutually unmergeable. It was never preventive for
+ * the candidate either: that candidate's linked PR still reads
+ * `merged_at: null` while its own gate runs.
+ *
+ * Bare `verify:orphan-active` stays repo-wide for `deft doctor`, manual runs,
+ * swarm finalize, and the after-merge `--issue N` DONE gate (#3429); the
+ * scoped form still falls back to the full sweep at the delivery tip.
+ */
+export const ORPHAN_ACTIVE_MERGE_GATE = {
+    task: "verify:orphan-active",
+    args: ["--changed-only"],
+};
 export function checkGateId(spec) {
     return typeof spec === "string" ? spec : spec.task;
 }
@@ -62,8 +79,9 @@ export const FRAMEWORK_CHECK_GATES = [
     // --- Fast preflight (seconds–few min) — #3188 ---
     "verify:branch",
     "verify:encoding",
+    "verify:closing-keywords",
     "verify:cache-fresh",
-    "verify:orphan-active",
+    ORPHAN_ACTIVE_MERGE_GATE,
     "verify:completed-write-guard",
     "verify:license-sync",
     "verify:contract-drift",
@@ -73,7 +91,10 @@ export const FRAMEWORK_CHECK_GATES = [
     "verify:rule-ownership",
     "verify:biome-config",
     "verify:content-manifest",
+    // #3900 check 1: C1 declaration vs staged pack. Checks 2/3 compose C3/C2.
+    "verify:deposit-closure",
     "verify:skill-external-fetch-gate",
+    "verify:semantic-single-source",
     "verify:cursor-tier1",
     "verify:openclaw-tier1",
     "verify:go-freeze",
@@ -82,7 +103,9 @@ export const FRAMEWORK_CHECK_GATES = [
     // #3145: test/source boundary + approved-scope provenance + consumer gate composition
     "verify:test-boundary",
     "verify:scope-provenance",
-    "verify:consumer-check-contract",
+    // #3893: fail-closed on merge-chokepoint gate scoping for the composition
+    // this repo owns; consumer deposits stay warn-only until `deft update`.
+    { task: "verify:consumer-check-contract", args: ["--framework-source"] },
     // #3362: dead-surface detector (warn-only this release; no --enforce)
     "verify:telemetry-coverage",
     "verify:vbrief-conformance",
@@ -111,7 +134,7 @@ export const CONSUMER_CHECK_GATES = [
     "verify:branch",
     "verify:cache-fresh",
     "verify:wip-cap",
-    "verify:orphan-active",
+    ORPHAN_ACTIVE_MERGE_GATE,
     "verify:completed-write-guard",
     "doctor",
     "toolchain:check-consumer",

package/dist/check/named-cause.js

@@ -13,7 +13,7 @@ const GATE_REMEDIES = {
     "verify:wip-cap": "Demote stale pending scopes (task scope:demote) or raise plan.policy.wipCap deliberately",
     doctor: "Run task doctor and follow the named recovery steps",
     "toolchain:check": "Install missing maintainer tools reported by the gate (go, uv, git, gh, node, pnpm)",
-    "toolchain:check-consumer": "Install missing consumer tools: go-task, git, gh, node, pnpm (corepack enable && corepack prepare pnpm@latest --activate)",
+    "toolchain:check-consumer": "Install the missing consumer tool reported by the gate; use npm from Node or enable pnpm with Corepack as declared by package.json",
     "ts:check-lane": "Fix lint/type/test failures; re-run task ts:check-lane",
     "vbrief:validate": "Fix xBRIEF/vBRIEF schema errors reported by the gate",
     "verify-strategy-output": "Re-run strategy output or fix non-conformant scope filenames / PROJECT-DEFINITION",
@@ -57,6 +57,12 @@ export function extractGateCause(stdout, stderr, exitCode, spawnError, gateId) {
         useful.push(line);
     }
     const gateHint = gateId?.trim() ?? "";
+    if (gateHint === "toolchain:check" || gateHint === "toolchain:check-consumer") {
+        const toolFailure = useful.find((line) => /^(?:package manager|go|uv|git|gh|node|npm|pnpm|task): (?:NOT FOUND|FAILED|ERROR)\b/i.test(line));
+        if (toolFailure !== undefined) {
+            return sanitizeCauseLine(toolFailure);
+        }
+    }
     if (gateHint.length > 0) {
         const named = useful.find((line) => line.includes(gateHint));
         if (named !== undefined) {
@@ -106,14 +112,23 @@ export function remedyForGate(gateId, cause) {
         return CLI_SPAWN_ERROR_REMEDY;
     }
     if (/task binary not found|cannot spawn go-task/i.test(cause)) {
-        if (gateId.startsWith("verify:") || gateId.startsWith("verify-") || gateId === "doctor") {
+        if (gateId.startsWith("verify:") ||
+            gateId.startsWith("verify-") ||
+            gateId === "doctor" ||
+            gateId === "toolchain:check-consumer") {
             return CLI_SPAWN_ERROR_REMEDY;
         }
         return SPAWN_ERROR_REMEDY;
     }
-    if (/pnpm binary not found|pnpm: NOT FOUND/i.test(cause)) {
+    if (/Unsupported DEFT_PACKAGE_MANAGER value/i.test(cause)) {
+        return "Set DEFT_PACKAGE_MANAGER to npm or pnpm, or unset it to use package.json; then re-run the consumer check";
+    }
+    if (/\bpnpm(?: binary not found|: (?:NOT FOUND|FAILED|ERROR))/i.test(cause)) {
         return "Enable pnpm: corepack enable && corepack prepare pnpm@latest --activate";
     }
+    if (/\bnpm(?: binary not found|: (?:NOT FOUND|FAILED|ERROR))/i.test(cause)) {
+        return "Install or repair Node 20+ (npm is bundled), then re-run the consumer check";
+    }
     return (GATE_REMEDIES[gateId] ??
         `Re-run the gate for details: task ${gateId}  (or task check); fix the reported product/process defect`);
 }

package/dist/check/session-completed-ac.d.ts

@@ -8,7 +8,7 @@
 /** One remediation when check cannot target the just-completed brief (#3357). */
 export declare const SESSION_COMPLETED_AC_REMEDIATION = "Run task verify:ac -- xbrief/completed/<just-completed>.xbrief.json (a story completed this session; check must not soft-skip) (#3357)";
 /** Project-relative marker written by scope:complete for this session (#3357). */
-export declare const SESSION_COMPLETED_MARKER_REL: readonly [".deft", "last-completed.json"];
+export declare const SESSION_COMPLETED_MARKER_REL: readonly [".deft", "cache", "last-completed.json"];
 export interface SessionCompletedMarker {
     readonly path: string;
     readonly sessionId: string;

package/dist/check/session-completed-ac.js

@@ -13,7 +13,7 @@ import { parseTimestamp } from "../session/time.js";
 /** One remediation when check cannot target the just-completed brief (#3357). */
 export const SESSION_COMPLETED_AC_REMEDIATION = "Run task verify:ac -- xbrief/completed/<just-completed>.xbrief.json (a story completed this session; check must not soft-skip) (#3357)";
 /** Project-relative marker written by scope:complete for this session (#3357). */
-export const SESSION_COMPLETED_MARKER_REL = [".deft", "last-completed.json"];
+export const SESSION_COMPLETED_MARKER_REL = [".deft", "cache", "last-completed.json"];
 function asRecord(value) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         return value;

package/dist/codebase/provider.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { readPlanPolicy } from "../policy/plan-extensions.js";
+import { resolveCaptureFailureStderr, SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { loadJsonFile } from "../verify-source/code-structure-validate.js";
 import { CODEBASE_MAP_SCHEMA_PATH } from "./constants.js";
 import { buildCodebaseMap, CodeStructureConfigError, configErrorToDict, defaultCodeStructurePath, fileSha256, } from "./default-extractor.js";
@@ -547,6 +548,7 @@ function runProviderCommand(command, cwd) {
             cwd,
             encoding: "utf8",
             timeout: 60_000,
+            maxBuffer: SUBPROCESS_MAX_BUFFER,
             stdio: ["ignore", "pipe", "pipe"],
         });
         return { returncode: 0, stdout, stderr: "" };
@@ -556,7 +558,11 @@ function runProviderCommand(command, cwd) {
         return {
             returncode: typeof e.status === "number" ? e.status : 1,
             stdout: typeof e.stdout === "string" ? e.stdout : "",
-            stderr: typeof e.stderr === "string" ? e.stderr : String(e.message ?? err),
+            stderr: resolveCaptureFailureStderr({
+                captured: typeof e.stderr === "string" ? e.stderr : "",
+                status: e.status,
+                message: e.message ?? String(err),
+            }),
         };
     }
 }

package/dist/consumer-check-contract/evaluate.d.ts

@@ -10,6 +10,20 @@
 import { type CheckGateSpec } from "../check/gate-lists.js";
 /** Gates that #3145 requires on consumer check composition (beyond baseline). */
 export declare const REQUIRED_CONSUMER_ENFORCEMENT_GATES: readonly string[];
+/**
+ * Gates whose composition on a check aggregate must carry a scoping argument
+ * (#3893).
+ *
+ * `verify:orphan-active` is repo-wide by default. Composed unscoped on a merge
+ * chokepoint it fails a candidate for residue another merge stranded, and N
+ * stranded briefs make N single-brief lifecycle PRs mutually unmergeable. It is
+ * not preventive for the candidate either: that candidate's linked PR still
+ * reads `merged_at: null` while its own gate runs.
+ *
+ * Fail-closed under `--framework-source`, where this repo owns the composition;
+ * a warning elsewhere while `deft update` re-deposits the Taskfile.
+ */
+export declare const MERGE_CHOKEPOINT_SCOPED_GATE_ARGS: ReadonlyMap<string, string>;
 export interface ConsumerCheckContractFinding {
     readonly gateId: string;
     readonly surface: "check-task" | "ci-workflow" | "verify-taskfile";
@@ -150,11 +164,44 @@ export declare function stripTaskBodyComments(body: string): string;
 export declare function taskBodyInvokesCheckOrchestrator(body: string): boolean;
 /** True when the check / check:consumer / check:framework-source task invokes orchestrator. */
 export declare function taskfileInvokesCheckOrchestrator(text: string): boolean;
+/** One `deps:` entry plus the YAML nested under it (`vars:` and friends). */
+export interface CheckDepEntry {
+    readonly name: string;
+    readonly body: string;
+}
+/**
+ * Extract `deps:` entries from a go-task task definition, keeping each entry's
+ * nested body so an argument-carrying dep (#3893) is distinguishable from a
+ * bare one. Best-effort line parser.
+ */
+export declare function extractCheckDepEntries(taskfileText: string, taskName: string): CheckDepEntry[];
 /**
  * Extract dependency task names from a go-task task definition body snippet.
  * Best-effort line parser for `deps:` list entries.
  */
 export declare function extractCheckDeps(taskfileText: string, taskName: string): string[];
+/**
+ * Drop a YAML trailing comment and surrounding quotes from a scalar value.
+ * Honours double-quoted `\\"` escapes and single-quoted `''` doubling, so a
+ * value carrying a quote is not truncated before the argument that follows.
+ */
+export declare function parseYamlScalar(raw: string): string;
+/**
+ * Effective `CLI_ARGS` value for a `deps:` entry, or null when it sets none.
+ *
+ * Reads the key itself rather than the entry text, so the required argument
+ * appearing in a comment, a sibling variable, or a descriptive value cannot
+ * stand in for the argument the gate actually receives (#3893).
+ */
+export declare function depEntryCliArgs(body: string): string | null;
+/**
+ * True when the effective `CLI_ARGS` token list carries `requiredArg`.
+ *
+ * Exact token only: the guarded verbs accept the bare flag, so an equals form
+ * like `--changed-only=0` would exit 2 on an unrecognized argument while the
+ * contract reported the composition healthy.
+ */
+export declare function cliArgsCarry(cliArgs: string | null, requiredArg: string): boolean;
 /**
  * Evaluate whether required enforcement gates are composed into consumer check/CI.
  */

package/dist/consumer-check-contract/evaluate.js

@@ -17,6 +17,22 @@ export const REQUIRED_CONSUMER_ENFORCEMENT_GATES = [
     "verify:scope-provenance",
     "verify:consumer-check-contract",
 ];
+/**
+ * Gates whose composition on a check aggregate must carry a scoping argument
+ * (#3893).
+ *
+ * `verify:orphan-active` is repo-wide by default. Composed unscoped on a merge
+ * chokepoint it fails a candidate for residue another merge stranded, and N
+ * stranded briefs make N single-brief lifecycle PRs mutually unmergeable. It is
+ * not preventive for the candidate either: that candidate's linked PR still
+ * reads `merged_at: null` while its own gate runs.
+ *
+ * Fail-closed under `--framework-source`, where this repo owns the composition;
+ * a warning elsewhere while `deft update` re-deposits the Taskfile.
+ */
+export const MERGE_CHOKEPOINT_SCOPED_GATE_ARGS = new Map([
+    ["verify:orphan-active", "--changed-only"],
+]);
 /**
  * Relative path forms accepted for the deft-install canonical Taskfile include
  * (init-deposit `MINIMAL_TASKFILE` / `CANONICAL_TASKFILE_INCLUDE`).
@@ -575,16 +591,18 @@ export function taskfileInvokesCheckOrchestrator(text) {
     return false;
 }
 /**
- * Extract dependency task names from a go-task task definition body snippet.
- * Best-effort line parser for `deps:` list entries.
+ * Extract `deps:` entries from a go-task task definition, keeping each entry's
+ * nested body so an argument-carrying dep (#3893) is distinguishable from a
+ * bare one. Best-effort line parser.
  */
-export function extractCheckDeps(taskfileText, taskName) {
+export function extractCheckDepEntries(taskfileText, taskName) {
     const lines = taskfileText.replace(/\r\n/g, "\n").split("\n");
-    const deps = [];
+    const entries = [];
     let inTask = false;
     let taskIndent = 0;
     let inDeps = false;
     let depsIndent = 0;
+    let current = null;
     const taskRe = new RegExp(`^${escapeRegExp(taskName)}\\s*:`);
     for (const raw of lines) {
         const stripped = raw.trim();
@@ -604,23 +622,142 @@ export function extractCheckDeps(taskfileText, taskName) {
         if (/^deps\s*:/.test(stripped)) {
             inDeps = true;
             depsIndent = indent;
+            current = null;
             continue;
         }
-        if (inDeps) {
-            if (indent <= depsIndent && !stripped.startsWith("-")) {
-                inDeps = false;
+        if (!inDeps)
+            continue;
+        if (indent <= depsIndent && !stripped.startsWith("-")) {
+            inDeps = false;
+            current = null;
+        }
+        else if (stripped.startsWith("-")) {
+            // - verify:branch  OR  - task: verify:branch
+            const m = stripped.match(/^-\s+task:\s*["']?([^"'#]+?)["']?\s*(?:#.*)?$/) ??
+                stripped.match(/^-\s+["']?([^"'#]+?)["']?\s*(?:#.*)?$/);
+            current = m?.[1] === undefined ? null : { name: m[1].trim(), lines: [] };
+            if (current !== null) {
+                entries.push(current);
             }
-            else if (stripped.startsWith("-")) {
-                // - verify:branch  OR  - task: verify:branch
-                const m = stripped.match(/^-\s+task:\s*["']?([^"'#]+?)["']?\s*(?:#.*)?$/) ??
-                    stripped.match(/^-\s+["']?([^"'#]+?)["']?\s*(?:#.*)?$/);
-                if (m?.[1]) {
-                    deps.push(m[1].trim());
+        }
+        else if (current !== null) {
+            // Keep indentation: the scoping check below needs to tell an immediate
+            // `vars:` property from deeper YAML (#3893).
+            current.lines.push(raw);
+        }
+    }
+    return entries.map((entry) => ({ name: entry.name, body: entry.lines.join("\n") }));
+}
+/**
+ * Extract dependency task names from a go-task task definition body snippet.
+ * Best-effort line parser for `deps:` list entries.
+ */
+export function extractCheckDeps(taskfileText, taskName) {
+    return extractCheckDepEntries(taskfileText, taskName).map((entry) => entry.name);
+}
+/**
+ * Drop a YAML trailing comment and surrounding quotes from a scalar value.
+ * Honours double-quoted `\\"` escapes and single-quoted `''` doubling, so a
+ * value carrying a quote is not truncated before the argument that follows.
+ */
+export function parseYamlScalar(raw) {
+    const text = raw.trim();
+    if (text.startsWith('"')) {
+        let out = "";
+        for (let i = 1; i < text.length; i += 1) {
+            const ch = text[i];
+            if (ch === "\\" && i + 1 < text.length) {
+                out += text[i + 1];
+                i += 1;
+                continue;
+            }
+            if (ch === '"')
+                return out;
+            out += ch;
+        }
+        return out;
+    }
+    if (text.startsWith("'")) {
+        let out = "";
+        for (let i = 1; i < text.length; i += 1) {
+            const ch = text[i];
+            if (ch === "'") {
+                if (text[i + 1] === "'") {
+                    out += "'";
+                    i += 1;
+                    continue;
                 }
+                return out;
             }
+            out += ch;
         }
+        return out;
     }
-    return deps;
+    const comment = text.indexOf(" #");
+    return (comment === -1 ? text : text.slice(0, comment)).trim();
+}
+/**
+ * Inline-flow `vars: { CLI_ARGS: ... }` scalar. Quote escapes are honoured so a
+ * value carrying a quote is not truncated before the argument that follows.
+ */
+const INLINE_CLI_ARGS_RE = /CLI_ARGS\s*:\s*("(?:\\.|[^"\\])*"|'(?:''|[^'])*'|[^,}]*)/;
+/**
+ * Effective `CLI_ARGS` value for a `deps:` entry, or null when it sets none.
+ *
+ * Reads the key itself rather than the entry text, so the required argument
+ * appearing in a comment, a sibling variable, or a descriptive value cannot
+ * stand in for the argument the gate actually receives (#3893).
+ */
+export function depEntryCliArgs(body) {
+    let varsIndent = null;
+    let propIndent = null;
+    let value = null;
+    for (const rawLine of body.split("\n")) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const indent = rawLine.length - rawLine.trimStart().length;
+        if (varsIndent !== null && indent <= varsIndent) {
+            varsIndent = null;
+            propIndent = null;
+        }
+        const varsBlock = /^vars\s*:\s*(.*)$/.exec(line);
+        if (varsBlock !== null) {
+            varsIndent = indent;
+            propIndent = null;
+            // Inline flow form: vars: { CLI_ARGS: "--changed-only" }
+            const inline = INLINE_CLI_ARGS_RE.exec(varsBlock[1] ?? "");
+            if (inline !== null) {
+                value = parseYamlScalar(inline[1] ?? "");
+            }
+            continue;
+        }
+        if (varsIndent === null)
+            continue;
+        propIndent ??= indent;
+        if (indent !== propIndent)
+            continue;
+        const cliArgs = /^CLI_ARGS\s*:\s*(.*)$/.exec(line);
+        if (cliArgs !== null) {
+            value = parseYamlScalar(cliArgs[1] ?? "");
+        }
+    }
+    return value;
+}
+/**
+ * True when the effective `CLI_ARGS` token list carries `requiredArg`.
+ *
+ * Exact token only: the guarded verbs accept the bare flag, so an equals form
+ * like `--changed-only=0` would exit 2 on an unrecognized argument while the
+ * contract reported the composition healthy.
+ */
+export function cliArgsCarry(cliArgs, requiredArg) {
+    if (cliArgs === null)
+        return false;
+    return cliArgs
+        .split(/\s+/)
+        .filter((token) => token.length > 0)
+        .some((token) => token === requiredArg);
 }
 function remediationForMissing(gateId, surface) {
     return (`Add \`${gateId}\` to the consumer ${surface} composition (Taskfile check deps ` +
@@ -712,12 +849,41 @@ export function evaluateConsumerCheckContract(projectRoot, options = {}) {
     }
     let anyAggregateDefined = false;
     for (const target of checkTargets) {
-        const deps = extractCheckDeps(rootTaskfile, target);
+        const entries = extractCheckDepEntries(rootTaskfile, target);
+        const deps = entries.map((entry) => entry.name);
         const body = extractTaskBody(rootTaskfile, target);
         const defined = deps.length > 0 || body.trim().length > 0;
         if (!defined)
             continue;
         anyAggregateDefined = true;
+        // Checked even on a trusted orchestrator body: a listed dep still runs, and
+        // unscoped on a merge chokepoint is the #3893 defect.
+        for (const [gateId, requiredArg] of MERGE_CHOKEPOINT_SCOPED_GATE_ARGS) {
+            // Every occurrence must carry the argument: a scoped entry followed by a
+            // bare duplicate still runs the repo-wide scan (#3893).
+            const listed = entries.filter((row) => row.name === gateId);
+            if (listed.length === 0)
+                continue;
+            if (listed.every((row) => cliArgsCarry(depEntryCliArgs(row.body), requiredArg)))
+                continue;
+            const finding = {
+                gateId,
+                surface: "check-task",
+                detail: `aggregate '${target}' composes ${gateId} without ${requiredArg}: an unscoped ` +
+                    "repo-wide lifecycle scan on a merge chokepoint fails a candidate for residue " +
+                    "another merge stranded (#3893)",
+                remediation: `Pass ${requiredArg} to ${gateId} in the '${target}' deps (go-task object form, ` +
+                    `vars: CLI_ARGS: "${requiredArg}"). Bare ${gateId} stays repo-wide for doctor, ` +
+                    "manual runs, and the after-merge --issue N run. " +
+                    "See content/docs/consumer-check-contract.md (#3893).",
+            };
+            if (options.frameworkSource === true) {
+                findings.push(finding);
+            }
+            else {
+                soft.push(finding);
+            }
+        }
         const trustThis = taskInvokesOrchestrator(target) && verifyDefinesRequired;
         if (trustThis)
             continue;

package/dist/delivery-attempt/evaluate.d.ts

@@ -4,7 +4,7 @@
  * Loads durable unit state and returns a single deterministic decision
  * before every delivery dispatch or retry.
  */
-import type { DeliveryUnitLedger, PreDispatchInput, PreDispatchResult } from "./types.js";
+import type { DeliveryBudgetPolicy, DeliveryUnitLedger, PreDispatchInput, PreDispatchResult } from "./types.js";
 /**
  * Evaluate whether a delivery dispatch may proceed.
  *
@@ -15,6 +15,14 @@ import type { DeliveryUnitLedger, PreDispatchInput, PreDispatchResult } from "./
  * That keeps bounded override quota for dispatches that truly need it.
  */
 export declare function evaluatePreDispatch(ledger: DeliveryUnitLedger, input: PreDispatchInput): PreDispatchResult;
+/**
+ * Elapsed budget for a run already queued or running (#3983).
+ * Pre-dispatch cannot see this case: an active attempt is DENY_DUPLICATE_ACTIVE.
+ */
+export declare function evaluateInFlight(ledger: DeliveryUnitLedger, input?: {
+    readonly now?: string;
+    readonly policy?: Partial<DeliveryBudgetPolicy>;
+}): PreDispatchResult;
 /**
  * Convenience: evaluate against ledger, and if blocked, return handoff suitable
  * for persistence via markBlocked + saveUnitLedger.