@deftai/directive-core 0.100.0 → 0.102.0

package/dist/session/session-start.js

@@ -7,6 +7,8 @@ import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposi
 import { hostContentSurfaceToDict, maybeFormatHostContentSurfaceLines, } from "../platform/host-content-surface.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { ceremonyDialToDict, formatCeremonyDialStatusLine, mergeCeremonyDialDeferrals, resolveCeremonyDial, resolveSessionCeremonyDialInputs, } from "../policy/ceremony-dial.js";
+import { emitCeremonyDialEscalationEvaluation, evaluateSessionStartCeremonyDialEscalation, formatCeremonyDialPinBypassLine, isCeremonyStartTierPinned, resolveCeremonyStartTierProvenance, } from "../policy/ceremony-dial-escalation.js";
+import { maybeFormatCoverageCheckResumeDisclosure } from "../policy/coverage-debt.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
@@ -14,19 +16,21 @@ import { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/re
 import { resolvePolicy } from "../policy/resolve.js";
 import { maybeFormatProductSignalConsentPrompt } from "../product-signal/consent-prompt.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
+import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { formatScmReadinessLines, probeScmReadiness, scmReadinessToDict, } from "../scm/readiness.js";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { emitSessionValueReadback } from "../value/readback.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
-import { maybeFormatCoverageCheckResumeNudge } from "./coverage-check-resume-nudge.js";
 import { effortBudgetToDict, maybeFormatEffortBudgetLines, resolveProductionHostEffortDescriptor, } from "./effort-budget.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
+import { runOrientationCompression, } from "./orientation-compression.js";
 import { emitSessionStartProcessCost } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
 import { newRitualStatePayload, readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { timestampIso } from "./time.js";
+import { runToolchainPreflight, toolchainPreflightToDict, } from "./toolchain-preflight.js";
 export const SESSION_POSTURES = ["read-only", "mutation"];
 export const READ_ONLY_POSTURE = "read-only";
 export const MUTATION_POSTURE = "mutation";
@@ -45,6 +49,18 @@ export const QUICK_STEPS = [
     "verify_tools",
 ];
 export const GATED_STEPS = ["agent_hooks", "doctor", "cache_fresh"];
+/** Standing one-liner when coverageDebt/checkResume is non-default (#3314). */
+function pushCoverageCheckResumeDisclosure(lines, projectRoot) {
+    try {
+        const line = maybeFormatCoverageCheckResumeDisclosure(projectRoot);
+        if (line !== null) {
+            lines.push(line);
+        }
+    }
+    catch {
+        // best-effort — ritual must not abort
+    }
+}
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
 export const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
 /** Human-readable skip notice when optional network is off the hot path (#2991). */
@@ -524,16 +540,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     if (humanMergeLine !== null) {
         lines.push(humanMergeLine);
     }
-    // #3189: re-arm still surfaces undecided coverage/check-resume once per ritual.
-    try {
-        const coverageNudge = maybeFormatCoverageCheckResumeNudge({ projectRoot });
-        if (coverageNudge.length > 0) {
-            lines.push(coverageNudge.trimEnd());
-        }
-    }
-    catch {
-        // best-effort — re-arm must not abort
-    }
+    pushCoverageCheckResumeDisclosure(lines, projectRoot);
     const priorQuick = eligibility.state.quickSteps;
     const priorTriage = priorQuick.triage_welcome ?? ritualStep({ ok: true, ts: instant });
     // Greptile P1: legacy ritual-state without verify_tools must re-run tools —
@@ -799,6 +806,11 @@ export function runSessionStart(projectRoot, options = {}) {
         env: options.env,
     });
     const ceremonyDialSelection = options.ceremonyDial ?? resolveCeremonyDial(projectRoot, { inputs: resolvedDialInputs });
+    const startTierProvenance = resolveCeremonyStartTierProvenance({
+        selection: ceremonyDialSelection,
+        injectedSelection: options.ceremonyDial !== undefined,
+        hint: options.ceremonyDialStartTierProvenance,
+    });
     const effectiveDeferrals = mergeCeremonyDialDeferrals(deferrals, ceremonyDialSelection);
     const skipFatPath = ceremonyDialSelection.profile.skipFatPath;
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
@@ -828,7 +840,13 @@ export function runSessionStart(projectRoot, options = {}) {
     const quickSteps = recordDeferredSteps(QUICK_STEPS, effectiveDeferrals, instant);
     const gatedSteps = recordDeferredSteps(GATED_STEPS, effectiveDeferrals, instant);
     const lines = [];
-    lines.push(formatCeremonyDialStatusLine(ceremonyDialSelection));
+    lines.push(formatCeremonyDialStatusLine(ceremonyDialSelection, {
+        startTierProvenance,
+    }));
+    const pinBypassLine = formatCeremonyDialPinBypassLine(startTierProvenance);
+    if (pinBypassLine !== null) {
+        lines.push(pinBypassLine);
+    }
     if (provisionalDial.reasons.length > 0 && options.ceremonyDial === undefined) {
         lines.push(`[deft ceremony-dial] provisional: ${provisionalDial.reasons.join("; ")}`);
     }
@@ -916,6 +934,8 @@ export function runSessionStart(projectRoot, options = {}) {
     else {
         stepTimings.push({ name: "branch_policy", duration_ms: 0, skipped: true });
     }
+    // Standing disclosure is independent of branch_policy deferral (#3314 / Greptile).
+    pushCoverageCheckResumeDisclosure(lines, projectRoot);
     // #3214 / #3156: verify_tools is mutation readiness — always run, even under
     // rapid/minimal. Dial skipFatPath only lightens *ceremony* (triage welcome,
     // optional network, staleness tickler), never readiness gates.
@@ -952,6 +972,120 @@ export function runSessionStart(projectRoot, options = {}) {
         });
         stepTimings.push({ name: "verify_tools", duration_ms: durationMs });
     }
+    // #3282 / #3286: orientation compression — compose doctor + toolchain preflight
+    // (+ agents:refresh / cache-fresh deposit-sha fast-paths) as inline sections with
+    // per-section status lines. Composition of existing steps, not a new monolith.
+    // Read-only posture never reaches here (#2176). Dual-path Later (`deft orient`)
+    // remains open — see orientation bundle.later.
+    let toolchainPreflightResult = null;
+    let orientationBundle = null;
+    {
+        const stepStarted = performance.now();
+        if (options.orientation === null) {
+            // Explicit skip (tests): still honour legacy preflight-only path when set.
+            if (options.toolchainPreflight === null) {
+                stepTimings.push({ name: "orientation", duration_ms: 0, skipped: true });
+                stepTimings.push({ name: "toolchain_preflight", duration_ms: 0, skipped: true });
+            }
+            else if (options.toolchainPreflight !== undefined) {
+                toolchainPreflightResult = options.toolchainPreflight;
+                lines.push(...toolchainPreflightResult.lines);
+                stepTimings.push({
+                    name: "toolchain_preflight",
+                    duration_ms: elapsedMs(stepStarted),
+                });
+            }
+            else {
+                stepTimings.push({ name: "orientation", duration_ms: 0, skipped: true });
+            }
+        }
+        else if (options.orientation !== undefined) {
+            orientationBundle = options.orientation;
+            toolchainPreflightResult = orientationBundle.preflight;
+            lines.push(...orientationBundle.lines);
+            for (const section of orientationBundle.sections) {
+                stepTimings.push({
+                    name: section.name,
+                    duration_ms: section.durationMs,
+                    ...(section.status === "skipped" ? { skipped: true } : {}),
+                });
+                // Record gated ritual steps so verify:session-ritual can skip re-runs.
+                // Do not overwrite explicit --defer (deferred_reason) records.
+                if ((section.name === "doctor" || section.name === "cache_fresh") &&
+                    !gatedSteps[section.name]?.deferred_reason) {
+                    gatedSteps[section.name] = ritualStep({
+                        ok: section.ok,
+                        ts: instant,
+                        message: section.lines[0] ?? section.status,
+                        exitCode: section.exitCode,
+                        durationMs: section.durationMs,
+                        command: section.name === "doctor" ? ["doctor"] : ["verify:cache-fresh"],
+                    });
+                }
+            }
+            stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+        }
+        else {
+            try {
+                // Skip composed doctor/cache_fresh work when those gated steps are deferred.
+                const doctorDeferred = Boolean(gatedSteps.doctor?.deferred_reason);
+                const cacheDeferred = Boolean(gatedSteps.cache_fresh?.deferred_reason);
+                orientationBundle = runOrientationCompression({
+                    projectRoot,
+                    frameworkRoot: options.frameworkRoot ?? projectRoot,
+                    compact: options.compact,
+                    env: options.env,
+                    now: instant,
+                    toolchainPreflight: options.toolchainPreflight,
+                    toolchainPreflightOptions: options.toolchainPreflightOptions,
+                    includeDoctor: !doctorDeferred,
+                    includeCacheFresh: !cacheDeferred,
+                    ...options.orientationOptions,
+                });
+                toolchainPreflightResult = orientationBundle.preflight;
+                lines.push(...orientationBundle.lines);
+                for (const section of orientationBundle.sections) {
+                    stepTimings.push({
+                        name: section.name,
+                        duration_ms: section.durationMs,
+                        ...(section.status === "skipped" ? { skipped: true } : {}),
+                    });
+                    if ((section.name === "doctor" || section.name === "cache_fresh") &&
+                        !gatedSteps[section.name]?.deferred_reason) {
+                        gatedSteps[section.name] = ritualStep({
+                            ok: section.ok,
+                            ts: instant,
+                            message: section.lines[0] ?? section.status,
+                            exitCode: section.exitCode,
+                            durationMs: section.durationMs,
+                            command: section.name === "doctor" ? ["doctor"] : ["verify:cache-fresh"],
+                        });
+                    }
+                }
+                stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+            }
+            catch {
+                // fail-open: orientation composition must not abort session:start —
+                // fall back to preflight-only (#3282).
+                try {
+                    if (options.toolchainPreflight !== null) {
+                        toolchainPreflightResult =
+                            options.toolchainPreflight ??
+                                runToolchainPreflight({
+                                    projectRoot,
+                                    frameworkRoot: options.frameworkRoot ?? projectRoot,
+                                    ...options.toolchainPreflightOptions,
+                                });
+                        lines.push(...toolchainPreflightResult.lines);
+                    }
+                }
+                catch {
+                    // ignore
+                }
+                stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+            }
+        }
+    }
     // #3214: rapid/minimal skip informational cold-path ceremony only.
     if (!quickSteps.triage_welcome && !skipFatPath) {
         const stepStarted = performance.now();
@@ -1065,20 +1199,12 @@ export function runSessionStart(projectRoot, options = {}) {
     if (consentPrompt.length > 0) {
         lines.push(consentPrompt.trimEnd());
     }
-    // #3189: skippable coverageDebt/checkResume project-decision nudge (fail-open; never blocks).
-    try {
-        const coverageNudge = maybeFormatCoverageCheckResumeNudge({ projectRoot });
-        if (coverageNudge.length > 0) {
-            lines.push(coverageNudge.trimEnd());
-        }
-    }
-    catch {
-        // best-effort operator advisory — session start must not abort
-    }
     const writeStarted = performance.now();
     const coldSessionId = (options.newSessionId ?? randomUUID)();
     const dialDict = {
         ...ceremonyDialToDict(ceremonyDialSelection),
+        start_tier: ceremonyDialSelection.depth,
+        start_tier_provenance: startTierProvenance,
         provisional: {
             taskSize: provisionalDial.taskSize,
             modelTier: provisionalDial.modelTier,
@@ -1086,6 +1212,7 @@ export function runSessionStart(projectRoot, options = {}) {
             reasons: [...provisionalDial.reasons],
         },
     };
+    const preflightDict = toolchainPreflightResult !== null ? toolchainPreflightToDict(toolchainPreflightResult) : null;
     const payload = {
         ...newRitualStatePayload({
             sessionId: coldSessionId,
@@ -1097,6 +1224,8 @@ export function runSessionStart(projectRoot, options = {}) {
         }),
         // #3214: record dial choice on ritual-state for audit / later re-arm context.
         ceremony_dial: dialDict,
+        // #3282: durable preflight snapshot for harness / later check degraded mode.
+        ...(preflightDict !== null ? { toolchain_preflight: preflightDict } : {}),
     };
     let statePath;
     try {
@@ -1120,8 +1249,58 @@ export function runSessionStart(projectRoot, options = {}) {
         .filter(([, step]) => !step.ok && !step.deferred_reason)
         .map(([name]) => name);
     // verify_tools is recorded on quick_steps; failure makes ready=false.
+    // #3282: toolchain preflight degraded mode does NOT flip ready=false by itself —
+    // agents still proceed with a named skip report at check time.
     const code = failed.length > 0 ? 1 : 0;
     const totalMs = elapsedMs(overallStarted);
+    // #3282 / #3286: event-driven run-summary (dial + preflight + orientation call
+    // count for dual-path Later graduation trigger) — fail-open, silent when unset.
+    if (options.emitRunSummary !== false) {
+        try {
+            const emitter = new RunSummaryEmitter({
+                projectRoot,
+                sessionId: coldSessionId,
+                env: options.env,
+            });
+            emitter.emitSessionStart({
+                ceremony_dial: dialDict,
+                preflight: preflightDict ?? undefined,
+                ceremony_tier: COLD_CEREMONY_TIER,
+                ready: code === 0,
+                exit_code: code,
+                ...(orientationBundle !== null
+                    ? {
+                        orientation_call_count: orientationBundle.orientationCallCount,
+                        orientation_compact: orientationBundle.compact,
+                        deposit_sha: orientationBundle.depositSha,
+                        orientation_later_status: orientationBundle.later.status,
+                        orientation_sections: orientationBundle.sections.map((s) => ({
+                            name: s.name,
+                            status: s.status,
+                            ok: s.ok,
+                            sha_match: s.shaMatch,
+                        })),
+                    }
+                    : {}),
+            });
+            emitter.emitKnownToolTurnDenominator();
+            // #3319: evaluate escalate-on-evidence only when #3274 is live. A pin
+            // emits nothing so never-evaluated stays distinguishable from declined.
+            if (!isCeremonyStartTierPinned(startTierProvenance)) {
+                emitCeremonyDialEscalationEvaluation({
+                    projectRoot,
+                    sessionId: coldSessionId,
+                    env: options.env,
+                    evaluation: evaluateSessionStartCeremonyDialEscalation({
+                        selection: ceremonyDialSelection,
+                    }),
+                });
+            }
+        }
+        catch {
+            // fail-open
+        }
+    }
     // #3117: bind live deposit generation when payload surfaces load (cold path).
     let freshnessBind = null;
     try {
@@ -1153,6 +1332,24 @@ export function runSessionStart(projectRoot, options = {}) {
         exit_code: code,
         ceremony_tier: COLD_CEREMONY_TIER,
         ceremony_dial: dialDict,
+        ...(preflightDict !== null ? { toolchain_preflight: preflightDict } : {}),
+        ...(orientationBundle !== null
+            ? {
+                orientation: {
+                    deposit_sha: orientationBundle.depositSha,
+                    compact: orientationBundle.compact,
+                    call_count: orientationBundle.orientationCallCount,
+                    later: orientationBundle.later,
+                    sections: orientationBundle.sections.map((s) => ({
+                        name: s.name,
+                        status: s.status,
+                        ok: s.ok,
+                        sha_match: s.shaMatch,
+                        exit_code: s.exitCode,
+                    })),
+                },
+            }
+            : {}),
         state_path: statePath,
         ...(freshnessBind ? { freshness: freshnessBind } : {}),
         quick_steps: quickSteps,

package/dist/session/toolchain-preflight.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Done-gate toolchain preflight at session start (#3282).
+ *
+ * Verifies the framework done-gate's own toolchain (task binary, package
+ * manager, node, optional CLI dist) up front so agents get a named cause +
+ * remedy in one turn instead of reverse-engineering `directive check` failures.
+ *
+ * Never bootstraps tooling the PRODUCT does not need. Failures name cause and
+ * remedy without embedding env values.
+ */
+import { type CheckGateSpec } from "../check/gate-lists.js";
+export declare const TOOLCHAIN_PREFLIGHT_TOOLS: readonly ["task", "pnpm", "node", "git"];
+export type ToolchainPreflightTool = (typeof TOOLCHAIN_PREFLIGHT_TOOLS)[number];
+export type ToolchainPreflightStatus = "ok" | "missing" | "degraded";
+/** How a missing tool affects check dispatch (#3335). */
+export type ToolchainPreflightImpact = "none" | "degraded";
+export interface ToolchainPreflightFinding {
+    readonly tool: ToolchainPreflightTool | "cli_dist";
+    readonly present: boolean;
+    /** Machine-stable cause code (never embeds env values). */
+    readonly cause: string | null;
+    /** Operator/agent remedy command or instruction. */
+    readonly remedy: string | null;
+    /**
+     * Missing-tool impact. `none` = present false but no install remedy and
+     * check does not skip CLI-native gates (#3335).
+     */
+    readonly impact?: ToolchainPreflightImpact | null;
+}
+export interface ToolchainPreflightResult {
+    readonly status: ToolchainPreflightStatus;
+    readonly ok: boolean;
+    /** True when missing tools would force check into degraded/skip mode. */
+    readonly degraded: boolean;
+    readonly findings: readonly ToolchainPreflightFinding[];
+    /** Human lines for session:start stdout (named cause + remedy). */
+    readonly lines: readonly string[];
+    /**
+     * Gate ids that check should skip when this preflight is degraded.
+     * Product-ordering of remaining gates is owned by #3284.
+     */
+    readonly skipGateIds: readonly string[];
+}
+export interface ToolchainPreflightOptions {
+    readonly projectRoot?: string;
+    readonly frameworkRoot?: string;
+    /** which(name) seam for tests. */
+    readonly which?: (name: string) => string | null;
+    /** existsSync seam for tests. */
+    readonly exists?: (path: string) => boolean;
+    /**
+     * When true (default), also probe for a built CLI dist under frameworkRoot
+     * (framework-source dogfood). Consumers without a local dist are fine when
+     * a global `deft`/`directive` is on PATH.
+     */
+    readonly probeCliDist?: boolean;
+    /** Active check composition. Defaults from consumer vs framework context. */
+    readonly composedGates?: readonly CheckGateSpec[];
+    /**
+     * Consumer deposit (not framework source). When omitted, inferred from
+     * frameworkRoot vs projectRoot (#3335 / #3324).
+     */
+    readonly consumerDeposit?: boolean;
+}
+/**
+ * Gates that specifically need a package manager / built dist.
+ * When task/node is missing, the orchestrator skips *all* scheduled gates
+ * (dynamic from gate-lists), not this static list — avoids hardcode drift.
+ */
+export declare const PNPM_DEPENDENT_GATE_IDS: readonly string[];
+/** Sentinel skip id meaning "every gate in the active check composition". */
+export declare const SKIP_ALL_GATES = "*";
+/**
+ * Run done-gate toolchain preflight. Pure probe — never installs or builds.
+ */
+export declare function runToolchainPreflight(options?: ToolchainPreflightOptions): ToolchainPreflightResult;
+/** Serialize preflight for run-summary / ritual-state (no env values). */
+export declare function toolchainPreflightToDict(result: ToolchainPreflightResult): Record<string, unknown>;
+//# sourceMappingURL=toolchain-preflight.d.ts.map

package/dist/session/toolchain-preflight.js

@@ -0,0 +1,211 @@
+/**
+ * Done-gate toolchain preflight at session start (#3282).
+ *
+ * Verifies the framework done-gate's own toolchain (task binary, package
+ * manager, node, optional CLI dist) up front so agents get a named cause +
+ * remedy in one turn instead of reverse-engineering `directive check` failures.
+ *
+ * Never bootstraps tooling the PRODUCT does not need. Failures name cause and
+ * remedy without embedding env values.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { allGatesCliDispatchable, GLOBAL_CLI_REMEDY, isCliNativeGate, } from "../check/cli-native-gates.js";
+import { isFrameworkRepoRoot, isFrameworkSourceContext } from "../check/context.js";
+import { CONSUMER_CHECK_GATES, checkGateId, FRAMEWORK_CHECK_GATES, } from "../check/gate-lists.js";
+import { defaultWhich } from "../doctor/which.js";
+export const TOOLCHAIN_PREFLIGHT_TOOLS = ["task", "pnpm", "node", "git"];
+const REMEDY = {
+    task: "Install go-task: https://taskfile.dev/installation/ (e.g. winget install Task.Task / brew install go-task)",
+    pnpm: "Enable pnpm via corepack: corepack enable && corepack prepare pnpm@latest --activate",
+    node: "Install Node 20+ (see .nvmrc); then corepack enable",
+    git: "Install Git: https://git-scm.com/downloads",
+};
+const CAUSE = {
+    task: "go-task binary not found on PATH",
+    pnpm: "pnpm binary not found on PATH",
+    node: "node binary not found on PATH",
+    git: "git binary not found on PATH",
+};
+/**
+ * Gates that specifically need a package manager / built dist.
+ * When task/node is missing, the orchestrator skips *all* scheduled gates
+ * (dynamic from gate-lists), not this static list — avoids hardcode drift.
+ */
+export const PNPM_DEPENDENT_GATE_IDS = [
+    "toolchain:check",
+    "toolchain:check-consumer",
+    "ts:check-lane",
+];
+/** Sentinel skip id meaning "every gate in the active check composition". */
+export const SKIP_ALL_GATES = "*";
+function probeTool(tool, which) {
+    const present = which(tool) !== null;
+    return {
+        tool,
+        present,
+        cause: present ? null : CAUSE[tool],
+        remedy: present ? null : REMEDY[tool],
+    };
+}
+function probeCliDist(frameworkRoot, which, exists) {
+    const globalCli = which("deft") !== null || which("directive") !== null;
+    if (globalCli) {
+        return { tool: "cli_dist", present: true, cause: null, remedy: null };
+    }
+    if (frameworkRoot) {
+        const distBin = join(frameworkRoot, "packages", "cli", "dist", "bin.js");
+        if (exists(distBin)) {
+            return { tool: "cli_dist", present: true, cause: null, remedy: null };
+        }
+        return {
+            tool: "cli_dist",
+            present: false,
+            cause: "CLI dist missing and no global deft/directive on PATH",
+            remedy: "Run `task build` (framework source) or `npm i -g @deftai/directive@latest`",
+        };
+    }
+    return {
+        tool: "cli_dist",
+        present: false,
+        cause: "no global deft/directive on PATH",
+        remedy: "Install: npm i -g @deftai/directive@latest",
+    };
+}
+function formatFindingLine(finding) {
+    if (finding.present) {
+        return `[deft preflight] ${finding.tool}: ok`;
+    }
+    if (finding.impact === "none") {
+        const cause = finding.cause ?? "absent";
+        return `[deft preflight] ${finding.tool}: absent (impact: none) — ${cause}`;
+    }
+    const cause = finding.cause ?? "missing";
+    const remedy = finding.remedy ?? "install the tool";
+    return `[deft preflight] ${finding.tool}: MISSING — cause: ${cause}; remedy: ${remedy}`;
+}
+function inferConsumerDeposit(options) {
+    if (options.consumerDeposit !== undefined)
+        return options.consumerDeposit;
+    const project = options.projectRoot;
+    if (project === undefined)
+        return false;
+    // Same-path roots are framework-source only when the tree is the source repo.
+    if (isFrameworkRepoRoot(project))
+        return false;
+    const framework = options.frameworkRoot ?? project;
+    return !isFrameworkSourceContext(framework, project);
+}
+/**
+ * Run done-gate toolchain preflight. Pure probe — never installs or builds.
+ */
+export function runToolchainPreflight(options = {}) {
+    const which = options.which ?? defaultWhich;
+    const exists = options.exists ?? existsSync;
+    const consumerDeposit = inferConsumerDeposit(options);
+    const composed = options.composedGates ?? (consumerDeposit ? CONSUMER_CHECK_GATES : FRAMEWORK_CHECK_GATES);
+    const allCli = allGatesCliDispatchable(composed);
+    const findings = [];
+    for (const tool of TOOLCHAIN_PREFLIGHT_TOOLS) {
+        findings.push(probeTool(tool, which));
+    }
+    if (options.probeCliDist !== false) {
+        findings.push(probeCliDist(options.frameworkRoot ?? options.projectRoot, which, exists));
+    }
+    const cliPresent = findings.some((f) => f.tool === "cli_dist" && f.present);
+    const taskMissing = findings.some((f) => f.tool === "task" && !f.present);
+    const pnpmMissing = findings.some((f) => f.tool === "pnpm" && !f.present);
+    const nodeMissing = findings.some((f) => f.tool === "node" && !f.present);
+    // #3335: in a deposit whose composed gates are all CLI-dispatchable, a
+    // missing task binary is impact none — no install-go-task remedy.
+    if (taskMissing && allCli) {
+        const idx = findings.findIndex((f) => f.tool === "task");
+        const prior = findings[idx];
+        if (idx >= 0 && prior !== undefined) {
+            findings[idx] = {
+                ...prior,
+                impact: "none",
+                remedy: cliPresent || nodeMissing ? null : GLOBAL_CLI_REMEDY,
+                cause: cliPresent
+                    ? "go-task absent; CLI-native gates dispatch via global deft/directive (#3335)"
+                    : "go-task absent and no global deft/directive CLI",
+            };
+        }
+    }
+    const missingCritical = findings.filter((f) => {
+        if (f.present || f.impact === "none")
+            return false;
+        return f.tool === "task" || f.tool === "pnpm" || f.tool === "node";
+    });
+    const skip = new Set();
+    if (nodeMissing) {
+        skip.add(SKIP_ALL_GATES);
+    }
+    else if (taskMissing && !allCli) {
+        if (!cliPresent) {
+            skip.add(SKIP_ALL_GATES);
+        }
+        else {
+            for (const spec of composed) {
+                const id = checkGateId(spec);
+                if (!isCliNativeGate(id))
+                    skip.add(id);
+            }
+        }
+    }
+    else if (taskMissing && allCli && !cliPresent) {
+        skip.add(SKIP_ALL_GATES);
+    }
+    else if (pnpmMissing) {
+        for (const id of PNPM_DEPENDENT_GATE_IDS) {
+            skip.add(id);
+        }
+    }
+    const degraded = missingCritical.length > 0 || (taskMissing && allCli && !cliPresent);
+    const ok = !degraded;
+    const status = ok ? "ok" : "degraded";
+    const lines = [];
+    lines.push(`[deft preflight] toolchain status: ${status}`);
+    for (const finding of findings) {
+        if (!finding.present) {
+            lines.push(formatFindingLine(finding));
+        }
+    }
+    if (ok) {
+        lines.push(taskMissing && allCli
+            ? "[deft preflight] done-gate toolchain ready (CLI dispatch; go-task not required) (#3335)"
+            : "[deft preflight] done-gate toolchain ready (task, pnpm, node)");
+    }
+    else {
+        lines.push("[deft preflight] degraded mode: directive check will skip toolchain-dependent gates " +
+            "with a named skip report rather than bootstrapping product-unneeded tooling (#3282)");
+        if (skip.size > 0) {
+            lines.push(`[deft preflight] gates subject to skip when degraded: ${[...skip].sort().join(", ")}`);
+        }
+    }
+    return {
+        status,
+        ok,
+        degraded,
+        findings,
+        lines,
+        skipGateIds: [...skip].sort(),
+    };
+}
+/** Serialize preflight for run-summary / ritual-state (no env values). */
+export function toolchainPreflightToDict(result) {
+    return {
+        status: result.status,
+        ok: result.ok,
+        degraded: result.degraded,
+        findings: result.findings.map((f) => ({
+            tool: f.tool,
+            present: f.present,
+            cause: f.cause,
+            remedy: f.remedy,
+            ...(f.impact !== undefined ? { impact: f.impact } : {}),
+        })),
+        skip_gate_ids: [...result.skipGateIds],
+    };
+}
+//# sourceMappingURL=toolchain-preflight.js.map

package/dist/triage/bootstrap/gitignore.d.ts

@@ -8,7 +8,7 @@ export declare function gitignoreTriageCacheEntries(projectRoot: string): readon
 export declare function gitattributesTriageCacheGlob(projectRoot: string): string;
 export declare const GITATTRIBUTES_EVAL_RULE = "vbrief/.triage-cache/*.jsonl  merge=union";
 export declare const FORBIDDEN_BLANKET_EVAL_LINES: readonly string[];
-export declare const EVAL_README_BODY = "# `vbrief/.triage-cache/` \u2014 triage working-set files\n\nThis directory holds JSON-lines logs and scratch files that Deft triage and\nslicing workflows emit. Deft configures your repo's `.gitignore` and\n`.gitattributes` so some files stay local while team-shared records can be\ncommitted.\n\n## What lives here\n\n| File | Committed? | Notes |\n| --- | --- | --- |\n| `slices.jsonl` | Yes | Team-shared cohort records from slicing skills. New teammates use prior cohort outputs to spot orphans and avoid re-slicing the same scope. |\n| `candidates.jsonl` | No | Your local triage accept / defer / reject stream. Re-create on a fresh clone with `deft triage:bootstrap`. |\n| `summary-history.jsonl` | No | Local history of `deft triage:summary` output; not required for day-to-day work. |\n| `scope-lifecycle.jsonl` | No | Local audit trail for scope demotions (`deft scope:demote`). Each operator's stream stays on their machine. |\n| `decompositions/` | No | Draft story-decomposition scratch. Produced child story xBRIEFs live in lifecycle folders via `deft scope:decompose`. |\n| `doctor-state.json` | No | Per-clone throttle state for `deft doctor` re-probe timing. |\n| `staleness-tickler-state.json` | No | Per-clone upgrade-tickler throttle state. |\n| `release-availability-state.json` | No | Per-clone release-availability probe throttle state. |\n\nPaths listed as \"No\" above are added to `.gitignore` during bootstrap; anything\nnot listed remains committable by default. The selective ignore entries live in\nthe repo-root `.gitignore` (`vbrief/.triage-cache/candidates.jsonl`,\n`vbrief/.triage-cache/summary-history.jsonl`, `vbrief/.triage-cache/scope-lifecycle.jsonl`,\n`vbrief/.triage-cache/decompositions/`, `vbrief/.triage-cache/doctor-state.json`,\n`vbrief/.triage-cache/staleness-tickler-state.json`, and\n`vbrief/.triage-cache/release-availability-state.json`).\n\n## Fresh clone\n\nIf `candidates.jsonl` is missing, run:\n\n```\ndeft triage:bootstrap\n```\n\nBootstrap rebuilds the local candidates log without altering committed\n`slices.jsonl`.\n\n## Merge behavior for `*.jsonl`\n\nThe repo-root `.gitattributes` may declare:\n\n```\nvbrief/.triage-cache/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on auto-merge,\nso parallel append-only edits to the same JSON-lines file rebase without manual\nconflict surgery. It does not dedupe semantically similar records \u2014 downstream\nreaders should tolerate duplicate-looking entries.\n\n## See also\n\n- `.gitignore` \u2014 selective ignore rules for operator-private files\n- `.gitattributes` \u2014 merge driver for committed JSON-lines logs\n";
+export declare const EVAL_README_BODY = "# `vbrief/.triage-cache/` \u2014 triage working-set files\n\nThis directory holds JSON-lines logs and scratch files that Deft triage and\nslicing workflows emit. Deft configures your repo's `.gitignore` and\n`.gitattributes` so some files stay local while team-shared records can be\ncommitted.\n\n## What lives here\n\n| File | Committed? | Notes |\n| --- | --- | --- |\n| `slices.jsonl` | Yes | Team-shared cohort records from slicing skills. New teammates use prior cohort outputs to spot orphans and avoid re-slicing the same scope. |\n| `candidates.jsonl` | No | Your local triage accept / defer / reject stream. Re-create on a fresh clone with `deft triage:bootstrap`. |\n| `summary-history.jsonl` | No | Local history of `deft triage:summary` output; not required for day-to-day work. |\n| `scope-lifecycle.jsonl` | No | Local audit trail for scope demotions (`deft scope:demote`). Each operator's stream stays on their machine. |\n| `decompositions/` | No | Draft story-decomposition scratch. Produced child story xBRIEFs live in lifecycle folders via `deft scope:decompose`. |\n| `doctor-state.json` | No | Per-clone throttle state for `deft doctor` re-probe timing. |\n| `staleness-tickler-state.json` | No | Per-clone upgrade-tickler throttle state. |\n| `release-availability-state.json` | No | Per-clone release-availability probe throttle state. |\n| `scm-label-mirror-discovery-state.json` | No | Per-clone SCM label-mirror discovery tip throttle (#3124). |\n\nPaths listed as \"No\" above are added to `.gitignore` during bootstrap; anything\nnot listed remains committable by default. The selective ignore entries live in\nthe repo-root `.gitignore` (`vbrief/.triage-cache/candidates.jsonl`,\n`vbrief/.triage-cache/summary-history.jsonl`, `vbrief/.triage-cache/scope-lifecycle.jsonl`,\n`vbrief/.triage-cache/decompositions/`, `vbrief/.triage-cache/doctor-state.json`,\n`vbrief/.triage-cache/staleness-tickler-state.json`,\n`vbrief/.triage-cache/release-availability-state.json`, and\n`vbrief/.triage-cache/scm-label-mirror-discovery-state.json`).\n\n## Fresh clone\n\nIf `candidates.jsonl` is missing, run:\n\n```\ndeft triage:bootstrap\n```\n\nBootstrap rebuilds the local candidates log without altering committed\n`slices.jsonl`.\n\n## Merge behavior for `*.jsonl`\n\nThe repo-root `.gitattributes` may declare:\n\n```\nvbrief/.triage-cache/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on auto-merge,\nso parallel append-only edits to the same JSON-lines file rebase without manual\nconflict surgery. It does not dedupe semantically similar records \u2014 downstream\nreaders should tolerate duplicate-looking entries.\n\n## See also\n\n- `.gitignore` \u2014 selective ignore rules for operator-private files\n- `.gitattributes` \u2014 merge driver for committed JSON-lines logs\n";
 /** Layout-aware triage-cache README body for the active lifecycle tree (#2344 / #2349). */
 export declare function generateTriageCacheReadmeBody(projectRoot: string): string;
 /** Strip an inline `# ...` comment from a gitignore line. */