@deftai/directive-core 0.100.0 → 0.102.0

package/dist/check/cached-orchestrator.js

@@ -1,30 +1,63 @@
 import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { join, resolve } from "node:path";
 import { lintShippedRegistry, resolveTaskContract, runWithCache, } from "../cache/task-cache/index.js";
+import { defaultWhich } from "../doctor/which.js";
 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 { checkGateCliArgv, cliSpawnPlan, resolveGateDispatch, resolveGlobalCliBin, } from "./cli-native-gates.js";
 import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "./consumer-gate-integrity.js";
 import { resolveCheckTarget } from "./context.js";
 import { checkGateId, checkGateSpawnArgs, gatesForCheckTarget, isSuiteCheckGate, } from "./gate-lists.js";
+import { formatDegradedSkipReport, formatNamedCauseFailure, remedyForGate } from "./named-cause.js";
 function captureSpawn(taskBin, args, opts) {
-    const result = spawnSync(taskBin, args, {
+    const plan = opts.cli === true ? cliSpawnPlan(taskBin, args) : { command: taskBin, args };
+    const result = spawnSync(plan.command, plan.args, {
         cwd: opts.cwd,
         encoding: "utf8",
         env: opts.env ?? process.env,
     });
+    if (result.error !== undefined) {
+        return {
+            exitCode: result.status ?? 1,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            spawnError: result.error.message,
+        };
+    }
     return {
         exitCode: result.status ?? 1,
         stdout: result.stdout ?? "",
         stderr: result.stderr ?? "",
     };
 }
+function writeLines(lines, stream = "stderr") {
+    const write = stream === "stdout"
+        ? process.stdout.write.bind(process.stdout)
+        : process.stderr.write.bind(process.stderr);
+    for (const line of lines) {
+        write(`${line}\n`);
+    }
+}
 /**
  * Run check gates sequentially with content-hash caching (#1713).
  * Falls back to fail-open execution for undeclared / non-cacheable gates.
  *
- * Gate order is fast-before-slow (#3188): non-suite gates complete (or fail)
- * before any suite gate (`ts:check-lane` / vitest+coverage) is started. A
- * non-zero exit aborts the loop immediately — the suite never starts after a
- * fast-gate failure (observable via `onGateStart` / suite start log).
+ * Gate order (#3284 / #3188):
+ *  1. Product AC (`verify:ac`) first — fail-fast; never skippable when commands exist
+ *  2. Hygiene preflight (may be advisory under pressure / degraded)
+ *  3. Suite last (`ts:check-lane`)
+ *
+ * Modes (env / ceremony dial / hard budget — see resolveProductFirstCheckMode):
+ *  - full: AC hard → hygiene hard → suite
+ *  - pressure: AC hard → hygiene advisory → suite
+ *  - rapid: AC only (ceremony dial rapid/minimal positive content)
+ *
+ * #3282: toolchain preflight enables degraded skip report when go-task/pnpm
+ * are missing; gate failures print named cause + remedy; run-summary JSONL
+ * is appended when DEFT_RUN_SUMMARY_PATH is set (fail-open).
  */
 export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}) {
     const resolvedFramework = resolve(frameworkRoot);
@@ -33,8 +66,42 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
     const taskBin = options.taskBin ?? "task";
     const target = resolveCheckTarget(resolvedFramework, resolvedProject);
     const cwd = target === "check:framework-source" ? resolvedFramework : resolvedProject;
-    const gates = gatesForCheckTarget(target);
+    const modeResolution = resolveProductFirstCheckMode({
+        environ: options.env ?? process.env,
+        projectRoot: resolvedProject,
+    });
+    const baseGates = gatesForCheckTarget(target);
+    const gates = applyProductFirstGateMode(baseGates, modeResolution.mode, checkGateId);
     const codeVersion = readCorePackageVersion();
+    const sessionId = options.sessionId ?? randomUUID();
+    const gateOutcomes = [];
+    const emitSummary = (exitCode, degraded) => {
+        if (options.emitRunSummary === false)
+            return;
+        try {
+            const emitter = new RunSummaryEmitter({
+                projectRoot: resolvedProject,
+                sessionId,
+                frameworkVersion: codeVersion,
+                env: options.env,
+            });
+            emitter.emitCheckInvocation({
+                target,
+                exit_code: exitCode,
+                degraded,
+                gates: gateOutcomes,
+            });
+            emitter.emitKnownToolTurnDenominator();
+        }
+        catch {
+            // fail-open
+        }
+    };
+    if (modeResolution.mode !== "full") {
+        process.stderr.write(`check: product-first mode=${modeResolution.mode} ` +
+            `(sources=${modeResolution.sources.join(",")}; ` +
+            `hygieneAdvisory=${modeResolution.hygieneAdvisory}; acOnly=${modeResolution.acOnly}) (#3284)\n`);
+    }
     // #3070: fail loud with deposit-repair guidance when consumer check-graph
     // includes (e.g. tasks/verify.yml for verify:orphan-active) are missing,
     // instead of opaque go-task "Task does not exist" exit 200/201.
@@ -42,6 +109,7 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
         const integrity = evaluateConsumerGateIntegrity(resolvedFramework);
         if (!integrity.ok) {
             process.stderr.write(formatConsumerGateIntegrityFailure(integrity));
+            emitSummary(2, false);
             return 2;
         }
     }
@@ -50,22 +118,111 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
         for (const finding of registryLint.findings.filter((f) => f.kind === "under-declared-input")) {
             process.stderr.write(`check: task registry lint failed for ${finding.taskId}: ${finding.detail}\n`);
         }
+        emitSummary(2, false);
         return 2;
     }
     if (gates.length === 0) {
         process.stderr.write(`check: no gate list for target ${target}\n`);
+        emitSummary(2, false);
         return 2;
     }
+    // #3282: toolchain preflight — degraded skip when framework tools missing.
+    const which = options.which ?? defaultWhich;
+    const preflight = options.preflight === undefined
+        ? runToolchainPreflight({
+            projectRoot: resolvedProject,
+            frameworkRoot: resolvedFramework,
+            composedGates: gates,
+            consumerDeposit: target === "check:consumer",
+            which,
+        })
+        : options.preflight;
+    const taskPresent = preflight === null || !preflight.findings.some((f) => f.tool === "task" && !f.present);
+    const cliBin = options.cliBin !== undefined ? options.cliBin : resolveGlobalCliBin(which);
+    // Expand SKIP_ALL_GATES sentinel to the live composition (avoids hardcode drift).
+    const skipSet = new Set();
+    for (const id of preflight?.skipGateIds ?? []) {
+        if (id === SKIP_ALL_GATES) {
+            for (const g of gates) {
+                skipSet.add(checkGateId(g));
+            }
+        }
+        else {
+            skipSet.add(id);
+        }
+    }
+    const degraded = preflight?.degraded === true;
+    if (preflight?.degraded) {
+        for (const line of preflight.lines) {
+            process.stderr.write(`${line}\n`);
+        }
+    }
+    // When task/node are missing, every gate is skipped — report named skips and
+    // exit 2 (config/environment), never exit 0 green (#3282 Greptile P1).
+    // Missing framework tooling must not look like a clean product pass.
+    if (degraded && skipSet.size > 0) {
+        const allSkipped = gates.every((g) => skipSet.has(checkGateId(g)));
+        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);
+                gateOutcomes.push({ id, status: "skipped", cause, remedy });
+                return { id, cause, remedy };
+            });
+            writeLines(formatDegradedSkipReport({
+                reason: "done-gate toolchain incomplete at check start",
+                skipped,
+                exitCode: 2,
+            }));
+            emitSummary(2, true);
+            return 2;
+        }
+    }
     for (const gateSpec of gates) {
         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 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`);
+            gateOutcomes.push({ id: gateId, status: "skipped", cause, remedy });
+            options.onGateStart?.(gateId);
+            options.onGateComplete?.(gateId, 0, false);
+            continue;
+        }
         // #3188: log suite entry so operators/tests can prove fast failures never
         // reach vitest+coverage (suite gates are ordered last in gate-lists).
         if (isSuiteCheckGate(gateSpec)) {
             process.stderr.write(`check: starting suite gate ${gateId} after fast preflight (#3188)\n`);
         }
+        if (isProductAcGate(gateId)) {
+            process.stderr.write(`check: product AC gate ${gateId} first (#3284)\n`);
+        }
         options.onGateStart?.(gateId);
         const contract = resolveTaskContract(gateId);
-        const taskArgs = checkGateSpawnArgs(gateSpec, taskfilePath);
+        const dispatch = resolveGateDispatch({
+            gateId,
+            taskPresent,
+            cliBin,
+        });
+        if ("skip" in dispatch) {
+            process.stderr.write(`check: skipping gate ${gateId} (no runner) — cause: ${dispatch.cause}; remedy: ${dispatch.remedy}\n`);
+            gateOutcomes.push({
+                id: gateId,
+                status: "skipped",
+                cause: dispatch.cause,
+                remedy: dispatch.remedy,
+            });
+            options.onGateComplete?.(gateId, 0, false);
+            continue;
+        }
+        const spawnBin = dispatch.mode === "cli" ? dispatch.bin : taskBin;
+        const spawnArgs = dispatch.mode === "cli"
+            ? checkGateCliArgv(gateSpec)
+            : checkGateSpawnArgs(gateSpec, taskfilePath);
+        let lastSpawn = { exitCode: 0, stdout: "", stderr: "" };
         const result = runWithCache({
             projectRoot: cwd,
             contract,
@@ -73,11 +230,21 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
             noCache: options.noCache,
             runner: () => {
                 const spawned = options.gateSpawnFn
-                    ? options.gateSpawnFn(gateId, taskBin, taskArgs, {
+                    ? options.gateSpawnFn(gateId, spawnBin, spawnArgs, {
                         cwd,
                         env: options.env,
                     })
-                    : captureSpawn(taskBin, taskArgs, { cwd, env: options.env });
+                    : captureSpawn(spawnBin, spawnArgs, {
+                        cwd,
+                        env: options.env,
+                        cli: dispatch.mode === "cli",
+                    });
+                lastSpawn = {
+                    exitCode: spawned.exitCode,
+                    stdout: spawned.stdout,
+                    stderr: spawned.stderr,
+                    spawnError: "spawnError" in spawned ? spawned.spawnError : undefined,
+                };
                 if (spawned.stdout.length > 0) {
                     process.stdout.write(spawned.stdout);
                 }
@@ -88,17 +255,137 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
             },
         });
         options.onGateComplete?.(gateId, result.exitCode, result.fromCache);
-        // Fail-fast: do not start later gates (including suite) after a failure.
+        // Fail-fast: do not start later gates (including suite) after a failure —
+        // unless this is a hygiene gate under pressure mode (advisory only, #3284).
         if (result.exitCode !== 0) {
+            const combinedOut = `${lastSpawn.stdout}\n${lastSpawn.stderr}`;
+            if (isProductAcGate(gateId) && isSoftEmptyAcText(combinedOut)) {
+                process.stderr.write(`check: verify:ac empty-resolution is not a green run (soft_empty); ` +
+                    `degraded (#3334) — cause: ${EMPTY_AC_CAUSE}; remedy: ${EMPTY_AC_REMEDY}\n`);
+                gateOutcomes.push({
+                    id: gateId,
+                    status: "skipped",
+                    exit_code: result.exitCode,
+                    cause: EMPTY_AC_CAUSE,
+                    remedy: EMPTY_AC_REMEDY,
+                    from_cache: result.fromCache,
+                });
+                let sawCurrent = false;
+                for (const later of gates) {
+                    const id = checkGateId(later);
+                    if (!sawCurrent) {
+                        if (id === gateId)
+                            sawCurrent = true;
+                        continue;
+                    }
+                    if (!gateOutcomes.some((o) => o.id === id)) {
+                        gateOutcomes.push({
+                            id,
+                            status: "skipped",
+                            cause: `skipped after ${gateId} soft_empty`,
+                            remedy: EMPTY_AC_REMEDY,
+                        });
+                    }
+                }
+                emitSummary(1, true);
+                return 1;
+            }
+            if (modeResolution.hygieneAdvisory && isHygieneGate(gateId) && !isProductAcGate(gateId)) {
+                process.stderr.write(`check: hygiene gate ${gateId} failed (exit ${result.exitCode}) but is ADVISORY ` +
+                    `under ${modeResolution.mode} mode — continuing (#3284)\n`);
+                const named = formatNamedCauseFailure({
+                    gateId,
+                    exitCode: result.exitCode,
+                    stdout: lastSpawn.stdout,
+                    stderr: lastSpawn.stderr,
+                    spawnError: lastSpawn.spawnError,
+                });
+                writeLines(named.lines);
+                gateOutcomes.push({
+                    id: gateId,
+                    status: "run",
+                    exit_code: result.exitCode,
+                    cause: `advisory hygiene failure: ${named.cause}`,
+                    remedy: named.remedy,
+                    from_cache: result.fromCache,
+                });
+                continue;
+            }
+            const named = formatNamedCauseFailure({
+                gateId,
+                exitCode: result.exitCode,
+                stdout: lastSpawn.stdout,
+                stderr: lastSpawn.stderr,
+                spawnError: lastSpawn.spawnError,
+            });
+            writeLines(named.lines);
+            gateOutcomes.push({
+                id: gateId,
+                status: "failed",
+                exit_code: result.exitCode,
+                cause: named.cause,
+                remedy: named.remedy,
+                from_cache: result.fromCache,
+            });
+            // Mark remaining as skipped for the summary (not run).
+            let sawCurrent = false;
+            for (const later of gates) {
+                const id = checkGateId(later);
+                if (!sawCurrent) {
+                    if (id === gateId)
+                        sawCurrent = true;
+                    continue;
+                }
+                if (!gateOutcomes.some((o) => o.id === id)) {
+                    gateOutcomes.push({
+                        id,
+                        status: "skipped",
+                        cause: `skipped after ${gateId} failed`,
+                        remedy: "Fix the failed gate above, then re-run task check",
+                    });
+                }
+            }
+            if (isProductAcGate(gateId)) {
+                process.stderr.write(`check: product AC gate ${gateId} failed (exit ${result.exitCode}); ` +
+                    `failing closed before hygiene (#3284)\n`);
+                emitSummary(result.exitCode, degraded);
+                return result.exitCode;
+            }
             if (!isSuiteCheckGate(gateSpec)) {
                 const remaining = gates.some(isSuiteCheckGate)
                     ? "skipping remaining gates including suite"
                     : "skipping remaining gates";
                 process.stderr.write(`check: fast gate ${gateId} failed (exit ${result.exitCode}); ${remaining} (#3188)\n`);
             }
+            emitSummary(result.exitCode, degraded);
             return result.exitCode;
         }
+        gateOutcomes.push({
+            id: gateId,
+            status: "run",
+            exit_code: 0,
+            from_cache: result.fromCache,
+        });
+    }
+    // Partial degraded (some gates skipped for pnpm, others ran): never report a
+    // green pass when required suite/toolchain gates were skipped (#3282 Greptile P1).
+    const skippedOutcomes = gateOutcomes.filter((o) => o.status === "skipped");
+    if (degraded && skippedOutcomes.length > 0) {
+        const skipped = skippedOutcomes.map((o) => ({
+            id: o.id,
+            cause: o.cause ?? "degraded",
+            remedy: o.remedy ?? remedyForGate(o.id, o.cause ?? "degraded"),
+        }));
+        writeLines(formatDegradedSkipReport({
+            reason: "partial toolchain; skipped gates did not run",
+            skipped,
+            ran: gateOutcomes.filter((o) => o.status === "run").map((o) => o.id),
+            exitCode: 2,
+        }));
+        emitSummary(2, true);
+        return 2;
     }
+    emitSummary(0, degraded);
     return 0;
 }
 //# sourceMappingURL=cached-orchestrator.js.map

package/dist/check/cli-native-gates.d.ts

@@ -0,0 +1,43 @@
+/**
+ * CLI-native check-gate dispatch (#3335).
+ *
+ * Consumer `verify:*` (and sibling CLI verbs) must run via global
+ * `deft`/`directive` when go-task is absent. Coordinate with the #3324
+ * engine-invoke deposit marker: same global-CLI surface, no install-go-task
+ * remedy when every composed gate is CLI-dispatchable.
+ */
+import type { CheckGateSpec } from "./gate-lists.js";
+/** Install the published CLI — not go-task — when a deposit has no global deft. */
+export declare const GLOBAL_CLI_REMEDY = "Install: npm i -g @deftai/directive@latest";
+export type GateDispatchMode = "task" | "cli";
+/** True when the gate is a native CLI verb and does not require go-task. */
+export declare function isCliNativeGate(gateId: string): boolean;
+export declare function allGatesCliDispatchable(gates: readonly CheckGateSpec[]): boolean;
+/**
+ * Argv for `deft <verb> …` (no go-task `--` separator, no `--taskfile`).
+ */
+export declare function checkGateCliArgv(spec: CheckGateSpec): string[];
+export declare function resolveGlobalCliBin(which: (name: string) => string | null): string | null;
+/** Quote one argv token for `cmd.exe /d /s /c` (mirrors tasks/engine-invoke.cjs). */
+export declare function quoteWin32Arg(arg: string): string;
+/**
+ * Spawn plan for the global CLI. Win32 uses cmd.exe so `.cmd` shims run
+ * without `shell: true` (#3324 / #2547).
+ */
+export declare function cliSpawnPlan(cliBin: string, argv: readonly string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+export declare function resolveGateDispatch(input: {
+    readonly gateId: string;
+    readonly taskPresent: boolean;
+    readonly cliBin: string | null;
+}): {
+    readonly mode: GateDispatchMode;
+    readonly bin: string;
+} | {
+    readonly skip: true;
+    readonly cause: string;
+    readonly remedy: string;
+};
+//# sourceMappingURL=cli-native-gates.d.ts.map

package/dist/check/cli-native-gates.js

@@ -0,0 +1,84 @@
+/**
+ * CLI-native check-gate dispatch (#3335).
+ *
+ * Consumer `verify:*` (and sibling CLI verbs) must run via global
+ * `deft`/`directive` when go-task is absent. Coordinate with the #3324
+ * engine-invoke deposit marker: same global-CLI surface, no install-go-task
+ * remedy when every composed gate is CLI-dispatchable.
+ */
+import { checkGateId } from "./gate-lists.js";
+/** Install the published CLI — not go-task — when a deposit has no global deft. */
+export const GLOBAL_CLI_REMEDY = "Install: npm i -g @deftai/directive@latest";
+const WIN32_CMD_METACHAR_RE = /[\s"&|<>^()%!]/;
+/** True when the gate is a native CLI verb and does not require go-task. */
+export function isCliNativeGate(gateId) {
+    if (gateId.startsWith("verify:") || gateId.startsWith("verify-"))
+        return true;
+    return (gateId === "doctor" ||
+        gateId === "vbrief:validate" ||
+        gateId === "toolchain:check" ||
+        gateId === "toolchain:check-consumer" ||
+        gateId === "ts:check-lane");
+}
+export function allGatesCliDispatchable(gates) {
+    return gates.every((spec) => isCliNativeGate(checkGateId(spec)));
+}
+/**
+ * Argv for `deft <verb> …` (no go-task `--` separator, no `--taskfile`).
+ */
+export function checkGateCliArgv(spec) {
+    const id = checkGateId(spec);
+    const extra = typeof spec === "string" ? [] : (spec.args ?? []);
+    if (id === "toolchain:check-consumer") {
+        return ["toolchain-check", "--consumer", ...extra];
+    }
+    if (id === "toolchain:check") {
+        return ["toolchain-check", ...extra];
+    }
+    if (id === "ts:check-lane") {
+        return ["ts-check-lane", ...extra];
+    }
+    return [id, ...extra];
+}
+export function resolveGlobalCliBin(which) {
+    return which("deft") ?? which("directive");
+}
+/** Quote one argv token for `cmd.exe /d /s /c` (mirrors tasks/engine-invoke.cjs). */
+export function quoteWin32Arg(arg) {
+    if (arg.length > 0 && !WIN32_CMD_METACHAR_RE.test(arg)) {
+        return arg;
+    }
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+/**
+ * Spawn plan for the global CLI. Win32 uses cmd.exe so `.cmd` shims run
+ * without `shell: true` (#3324 / #2547).
+ */
+export function cliSpawnPlan(cliBin, argv, platform = process.platform) {
+    if (platform === "win32") {
+        const commandLine = [cliBin, ...argv].map(quoteWin32Arg).join(" ");
+        return { command: "cmd.exe", args: ["/d", "/s", "/c", commandLine] };
+    }
+    return { command: cliBin, args: [...argv] };
+}
+export function resolveGateDispatch(input) {
+    if (input.taskPresent) {
+        return { mode: "task", bin: "task" };
+    }
+    if (isCliNativeGate(input.gateId) && input.cliBin !== null) {
+        return { mode: "cli", bin: input.cliBin };
+    }
+    if (isCliNativeGate(input.gateId)) {
+        return {
+            skip: true,
+            cause: "no go-task and no global deft/directive CLI",
+            remedy: GLOBAL_CLI_REMEDY,
+        };
+    }
+    return {
+        skip: true,
+        cause: "go-task binary not found on PATH",
+        remedy: "Install go-task: https://taskfile.dev/installation/",
+    };
+}
+//# sourceMappingURL=cli-native-gates.js.map

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

@@ -9,6 +9,11 @@ export type CheckGateSpec = string | {
     readonly task: string;
     readonly args?: readonly string[];
 };
+/**
+ * Product-first AC gate (#3284): always first; soft-missing when no active
+ * xBRIEF so framework self-check is not deadlocked without a story.
+ */
+export declare const PRODUCT_FIRST_AC_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[];
@@ -26,11 +31,12 @@ export declare function isSuiteCheckGate(spec: CheckGateSpec | string): boolean;
  */
 export declare function isFastBeforeSlowOrder(gates: readonly CheckGateSpec[]): boolean;
 /**
- * Framework-source check composition (#1713 / #3188).
+ * Framework-source check composition (#1713 / #3188 / #3284).
  *
- * Order contract: cheap preflight gates first; `ts:check-lane` (lint+build+
- * vitest coverage suite) last so a stale cache / orphan-active / branch miss
- * fails in seconds without starting the suite.
+ * Order contract:
+ *  1. Product AC first (fail-fast; never skippable when commands exist) — #3284
+ *  2. Cheap hygiene preflight — #3188
+ *  3. `ts:check-lane` suite last
  */
 export declare const FRAMEWORK_CHECK_GATES: readonly CheckGateSpec[];
 export declare const CONSUMER_CHECK_GATES: readonly CheckGateSpec[];

package/dist/check/gate-lists.js

@@ -1,4 +1,13 @@
 /** Gate execution order mirrors Taskfile.yml check targets (#1713 dogfood). */
+import { PRODUCT_AC_GATE_ID } from "../product-first-done-gate/types.js";
+/**
+ * Product-first AC gate (#3284): always first; soft-missing when no active
+ * xBRIEF so framework self-check is not deadlocked without a story.
+ */
+export const PRODUCT_FIRST_AC_GATE = {
+    task: PRODUCT_AC_GATE_ID,
+    args: ["--soft-missing-xbrief"],
+};
 export function checkGateId(spec) {
     return typeof spec === "string" ? spec : spec.task;
 }
@@ -39,13 +48,16 @@ export function isFastBeforeSlowOrder(gates) {
     return true;
 }
 /**
- * Framework-source check composition (#1713 / #3188).
+ * Framework-source check composition (#1713 / #3188 / #3284).
  *
- * Order contract: cheap preflight gates first; `ts:check-lane` (lint+build+
- * vitest coverage suite) last so a stale cache / orphan-active / branch miss
- * fails in seconds without starting the suite.
+ * Order contract:
+ *  1. Product AC first (fail-fast; never skippable when commands exist) — #3284
+ *  2. Cheap hygiene preflight — #3188
+ *  3. `ts:check-lane` suite last
  */
 export const FRAMEWORK_CHECK_GATES = [
+    // --- Product-first done-gate (#3284) — AC before any hygiene ---
+    PRODUCT_FIRST_AC_GATE,
     // --- Fast preflight (seconds–few min) — #3188 ---
     "verify:branch",
     "verify:encoding",
@@ -89,7 +101,9 @@ export const FRAMEWORK_CHECK_GATES = [
     "ts:check-lane",
 ];
 export const CONSUMER_CHECK_GATES = [
-    // Cheap lifecycle / policy first (no suite co-list today; keep fail-fast order)
+    // Product-first: stated AC before hygiene (#3284)
+    PRODUCT_FIRST_AC_GATE,
+    // Cheap lifecycle / policy second (no suite co-list today; keep fail-fast order)
     "verify:branch",
     "verify:cache-fresh",
     "verify:wip-cap",

package/dist/check/index.d.ts

@@ -1,6 +1,8 @@
-export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { type CachedCheckOptions, dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { allGatesCliDispatchable, checkGateCliArgv, cliSpawnPlan, GLOBAL_CLI_REMEDY, isCliNativeGate, resolveGateDispatch, resolveGlobalCliBin, } from "./cli-native-gates.js";
 export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, type ConsumerGateIntegrityFinding, type ConsumerGateIntegrityResult, type ConsumerGateIntegritySeams, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
-export { type CheckGateSpec, CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { type CheckGateSpec, CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, PRODUCT_FIRST_AC_GATE, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { extractGateCause, formatDegradedSkipReport, formatNamedCauseFailure, type NamedCauseMessage, remedyForGate, } from "./named-cause.js";
 export type { CheckOrchestratorOptions, CheckOrchestratorSeams } from "./orchestrator.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, type RunnerDetectResult, runnerDetectionTable, type TestRunnerKind, } from "./runner-detect.js";

package/dist/check/index.js

@@ -1,6 +1,8 @@
 export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { allGatesCliDispatchable, checkGateCliArgv, cliSpawnPlan, GLOBAL_CLI_REMEDY, isCliNativeGate, resolveGateDispatch, resolveGlobalCliBin, } from "./cli-native-gates.js";
 export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
-export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, isFastBeforeSlowOrder, isSuiteCheckGate, PRODUCT_FIRST_AC_GATE, SUITE_CHECK_GATE_IDS, } from "./gate-lists.js";
+export { extractGateCause, formatDegradedSkipReport, formatNamedCauseFailure, remedyForGate, } from "./named-cause.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, runnerDetectionTable, } from "./runner-detect.js";
 //# sourceMappingURL=index.js.map

package/dist/check/named-cause.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Named-cause + remedy formatting for check gate failures (#3282).
+ *
+ * Gate failures must never be bare exit 1: report gate name, cause, and remedy
+ * without embedding env values.
+ */
+export interface NamedCauseMessage {
+    readonly gateId: string;
+    readonly exitCode: number;
+    readonly cause: string;
+    readonly remedy: string;
+    readonly lines: readonly string[];
+}
+/**
+ * Extract a short cause from gate stdout/stderr without leaking env values.
+ * Strips lines that look like KEY=value assignments.
+ */
+export declare function extractGateCause(stdout: string, stderr: string, exitCode: number, spawnError?: string): string;
+export declare function remedyForGate(gateId: string, cause: string): string;
+/**
+ * Format named-cause failure lines for a single gate.
+ */
+export declare function formatNamedCauseFailure(input: {
+    readonly gateId: string;
+    readonly exitCode: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+    readonly spawnError?: string;
+}): NamedCauseMessage;
+/**
+ * Format degraded-mode skip report (which gates skipped and why).
+ */
+export declare function formatDegradedSkipReport(input: {
+    readonly reason: string;
+    readonly skipped: readonly {
+        id: string;
+        cause: string;
+        remedy: string;
+    }[];
+    readonly ran?: readonly string[];
+    readonly failed?: readonly string[];
+    /** Default 2 = config/environment (never green-pass skipped required gates). */
+    readonly exitCode?: number;
+}): readonly string[];
+//# sourceMappingURL=named-cause.d.ts.map