@deftai/directive-core 0.100.0 → 0.101.0

package/dist/check/cached-orchestrator.js

@@ -1,30 +1,60 @@
 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 { readCorePackageVersion } from "../engine-version.js";
+import { applyProductFirstGateMode, isHygieneGate, isProductAcGate, 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 { 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, {
         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 +63,41 @@ 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,
+            });
+        }
+        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 +105,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 +114,86 @@ 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 preflight = options.preflight === undefined
+        ? runToolchainPreflight({
+            projectRoot: resolvedProject,
+            frameworkRoot: resolvedFramework,
+        })
+        : options.preflight;
+    // 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);
+        let lastSpawn = { exitCode: 0, stdout: "", stderr: "" };
         const result = runWithCache({
             projectRoot: cwd,
             contract,
@@ -78,6 +206,12 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
                         env: options.env,
                     })
                     : captureSpawn(taskBin, taskArgs, { cwd, env: options.env });
+                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 +222,105 @@ 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) {
+            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/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,7 @@
-export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { type CachedCheckOptions, dispatchCachedTaskCheck } from "./cached-orchestrator.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,7 @@
 export { dispatchCachedTaskCheck } from "./cached-orchestrator.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

package/dist/check/named-cause.js

@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+/** Per-gate remedy hints (static; no env interpolation). */
+const GATE_REMEDIES = {
+    "verify:branch": "Create a feature branch (`git switch -c feat/<name>`) or set plan.policy.allowDirectCommitsToMaster with confirmation",
+    "verify:encoding": "Fix non-ASCII / encoding issues flagged by the gate; re-run task verify:encoding",
+    "verify:cache-fresh": "Run task cache:fetch-all or task triage:bootstrap to refresh the cache",
+    "verify:orphan-active": "Complete or cancel active xBRIEFs whose issues are closed / PRs merged (task scope:complete / scope:cancel)",
+    "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)",
+    "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",
+    "verify:test-boundary": "Move tests to the allowed placement or update plan.policy test-boundary allowlist",
+    "verify:scope-provenance": "Record approved scope provenance for the failing paths",
+    "verify:consumer-check-contract": "Align consumer Taskfile includes with the required gate graph",
+    "verify:forward-coverage": "Add tests covering new source files (task verify:forward-coverage)",
+    "verify:scm-boundary": "Move SCM mutations off GraphQL-heavy paths or wait for rate-limit reset",
+    "verify:license-sync": "Sync LICENSE / package license fields",
+    "verify:agents-md-budget": "Trim AGENTS.md managed section or raise plan.policy.agentsMdBudget deliberately",
+};
+const SPAWN_ERROR_REMEDY = "Install go-task (https://taskfile.dev/installation/) and ensure `task` is on PATH; then re-run task check";
+/**
+ * Extract a short cause from gate stdout/stderr without leaking env values.
+ * Strips lines that look like KEY=value assignments.
+ */
+export function extractGateCause(stdout, stderr, exitCode, spawnError) {
+    if (spawnError !== undefined && spawnError.length > 0) {
+        // Normalize common missing-binary messages without path dumps.
+        if (/ENOENT|not found|not recognized/i.test(spawnError)) {
+            return "task binary not found on PATH (cannot spawn go-task)";
+        }
+        return sanitizeCauseLine(spawnError);
+    }
+    const combined = `${stderr}\n${stdout}`
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    for (const line of combined) {
+        if (looksLikeEnvLeak(line))
+            continue;
+        if (line.startsWith("check:"))
+            continue;
+        return sanitizeCauseLine(line);
+    }
+    return `gate exited ${exitCode} without a diagnostic message`;
+}
+function looksLikeEnvLeak(line) {
+    // Avoid echoing DEFT_*= or generic env dumps.
+    if (/^[A-Z][A-Z0-9_]*=/.test(line))
+        return true;
+    if (/\bDEFT_[A-Z0-9_]+\b/.test(line) && line.includes("="))
+        return true;
+    return false;
+}
+function sanitizeCauseLine(line) {
+    // Cap length; collapse absolute home paths lightly.
+    let out = line.replace(/\r/g, "").trim();
+    if (out.length > 240) {
+        out = `${out.slice(0, 237)}...`;
+    }
+    return out;
+}
+export function remedyForGate(gateId, cause) {
+    if (/task binary not found|cannot spawn go-task/i.test(cause)) {
+        return SPAWN_ERROR_REMEDY;
+    }
+    if (/pnpm binary not found|pnpm: NOT FOUND/i.test(cause)) {
+        return "Enable pnpm: corepack enable && corepack prepare pnpm@latest --activate";
+    }
+    return (GATE_REMEDIES[gateId] ??
+        `Re-run the gate for details: task ${gateId}  (or task check); fix the reported product/process defect`);
+}
+/**
+ * Format named-cause failure lines for a single gate.
+ */
+export function formatNamedCauseFailure(input) {
+    const cause = extractGateCause(input.stdout ?? "", input.stderr ?? "", input.exitCode, input.spawnError);
+    const remedy = remedyForGate(input.gateId, cause);
+    const lines = [
+        `check: gate ${input.gateId} failed (exit ${input.exitCode})`,
+        `  cause: ${cause}`,
+        `  remedy: ${remedy}`,
+    ];
+    return {
+        gateId: input.gateId,
+        exitCode: input.exitCode,
+        cause,
+        remedy,
+        lines,
+    };
+}
+/**
+ * Format degraded-mode skip report (which gates skipped and why).
+ */
+export function formatDegradedSkipReport(input) {
+    const exitCode = input.exitCode ?? 2;
+    const lines = [
+        `check: degraded mode — ${input.reason}`,
+        `check: skipped ${input.skipped.length} gate(s) due to missing framework toolchain (#3282):`,
+    ];
+    for (const gate of input.skipped) {
+        lines.push(`  - ${gate.id}: cause: ${gate.cause}; remedy: ${gate.remedy}`);
+    }
+    if (input.ran !== undefined && input.ran.length > 0) {
+        lines.push(`check: ran: ${input.ran.join(", ")}`);
+    }
+    if (input.failed !== undefined && input.failed.length > 0) {
+        lines.push(`check: failed: ${input.failed.join(", ")}`);
+    }
+    lines.push(`check: exit ${exitCode} (degraded/config) — skipped required gates are not a green pass; ` +
+        "install missing tooling (see remedies above) and re-run task check");
+    return lines;
+}
+//# sourceMappingURL=named-cause.js.map

package/dist/check/orchestrator.js

@@ -57,7 +57,12 @@ export function dispatchTaskCheck(frameworkRoot, projectRoot, seams = {}) {
         timeoutMs: seams.timeoutMs,
     });
     if (result.error !== undefined) {
-        process.stderr.write(`check: failed to invoke task: ${result.error.message}\n`);
+        // #3282: named cause + remedy instead of bare spawn failure.
+        const detail = result.error.message;
+        const missingTask = /ENOENT|not found|not recognized/i.test(detail);
+        process.stderr.write(`check: gate ${target} failed (exit 2)\n` +
+            `  cause: ${missingTask ? "task binary not found on PATH (cannot spawn go-task)" : detail}\n` +
+            "  remedy: Install go-task (https://taskfile.dev/installation/) and ensure `task` is on PATH; then re-run task check\n");
         return 2;
     }
     if (result.signal === "SIGTERM" && result.status === null && seams.timeoutMs !== undefined) {

package/dist/doctor/help.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Doctor --help / -h text (#2712 session coda env docs + flag surface).
+ */
+export declare function formatDoctorHelp(): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/doctor/help.js

@@ -0,0 +1,31 @@
+/**
+ * Doctor --help / -h text (#2712 session coda env docs + flag surface).
+ */
+import { DOCTOR_ALLOWED_FLAGS } from "./constants.js";
+import { sessionCodaHelpText } from "./session-coda.js";
+export function formatDoctorHelp() {
+    const flags = DOCTOR_ALLOWED_FLAGS.join(", ");
+    return [
+        "Usage: deft doctor [options]",
+        "",
+        "Diagnose the Directive install and print the one next step.",
+        "",
+        "Options:",
+        "  --session              Session-oriented probe",
+        "  --fix, --repair       Attempt safe repairs (Taskfile / OpenClaw pins)",
+        "  --json                 Machine-readable JSON (no human footer / no coda)",
+        "  --quiet                Suppress mid-run chatter; final summary still prints",
+        "  --full                 Bypass throttle; re-probe fully",
+        "  --network              Allow offline-tier network checks (payload staleness)",
+        "  --project-root <path>  Project root (default: cwd)",
+        "  --force                Replace divergent OpenClaw pins during --fix",
+        "  --openclaw-all-agents  Wire always-pins into every OpenClaw workspace seat",
+        "  -h, --help             Show this help",
+        "",
+        `Allowed flags: ${flags}`,
+        "",
+        sessionCodaHelpText(),
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=help.js.map

package/dist/doctor/index.d.ts

@@ -3,6 +3,7 @@ export * from "./checks.js";
 export * from "./constants.js";
 export * from "./doctor-state.js";
 export * from "./flags.js";
+export * from "./help.js";
 export * from "./json.js";
 export * from "./main.js";
 export * from "./manifest.js";
@@ -13,6 +14,7 @@ export * from "./openclaw-soft-rebind.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";
+export * from "./session-coda.js";
 export * from "./taskfile.js";
 export * from "./types.js";
 export * from "./which.js";