@deftai/directive-core 0.100.0 → 0.102.0

package/dist/session/orientation-compression.js

@@ -0,0 +1,435 @@
+/**
+ * Orientation compression Now path (#3286 / dual-path #2899).
+ *
+ * Composes doctor + toolchain preflight into session:start as inline sections
+ * with per-section status lines; offers deposit-sha fast-paths for
+ * agents:refresh and verify:cache-fresh; formats compact (opt-in) vs verbose
+ * (default). Does NOT implement unified `deft orient` (Later remains open).
+ */
+import { isFrameworkRepoRoot } from "../check/context.js";
+import { decideThrottle, readState as readDoctorState, renderDoctorStatusLine, } from "../doctor/doctor-state.js";
+import { cmdDoctor } from "../doctor/main.js";
+import { applyAgentsRefresh } from "../platform/agents-md.js";
+import { evaluate as evaluateCacheFresh, } from "../preflight-cache/evaluate.js";
+import { computeDepositSha, DEPOSIT_SHA_MATCH_NOOP, formatDepositShaMatchLine, } from "./deposit-sha.js";
+import { readOrientationState, surfaceRecord, writeOrientationState, } from "./orientation-state.js";
+import { runToolchainPreflight, toolchainPreflightToDict, } from "./toolchain-preflight.js";
+/** Env opt-in for compact orientation output (#3286). Verbose remains default. */
+export const ENV_SESSION_COMPACT = "DEFT_SESSION_COMPACT";
+/** Dual-path Later graduation status — Now ships without closing Later (#2899). */
+export const ORIENTATION_LATER_STATUS = "open";
+export const ORIENTATION_LATER_COMMAND = "deft orient";
+export const ORIENTATION_GRADUATION_TRIGGER = "post-#3282 run-summary telemetry shows ritual+gate share >= 25% of tool calls " +
+    "on a benchmark-suite run AFTER Now ships (starting threshold, tunable)";
+function elapsedMs(started) {
+    return Math.max(0, Math.round(performance.now() - started));
+}
+function truthyEnv(raw) {
+    return new Set(["1", "true", "yes", "on"]).has((raw ?? "").trim().toLowerCase());
+}
+/** Resolve compact flag: explicit option wins, else DEFT_SESSION_COMPACT. */
+export function resolveSessionCompact(options = {}) {
+    if (options.compact === true)
+        return true;
+    if (options.compact === false)
+        return false;
+    const env = options.env ?? process.env;
+    return truthyEnv(env[ENV_SESSION_COMPACT]);
+}
+function statusLine(name, status) {
+    return `[deft orientation] ${name}: ${status}`;
+}
+/** Compact machine lines (one per section). Verbose default keeps prose. */
+export function formatOrientationCompactLines(sections) {
+    return sections.map((s) => {
+        const tag = s.shaMatch ? "sha_match" : s.status;
+        return `${s.name}=${tag}`;
+    });
+}
+export function formatOrientationVerboseLines(sections) {
+    const out = [];
+    for (const section of sections) {
+        out.push(statusLine(section.name, section.status));
+        for (const line of section.lines) {
+            // Avoid duplicating the status header when the section already emitted it.
+            if (line === statusLine(section.name, section.status))
+                continue;
+            out.push(line);
+        }
+    }
+    return out;
+}
+/**
+ * Doctor orientation section — throttle status when clean/recent; otherwise
+ * run doctor and surface a per-section status line (#3286 compose).
+ */
+export function runDoctorOrientationSection(projectRoot, options = {}) {
+    const started = performance.now();
+    const now = options.now ?? new Date();
+    try {
+        const state = readDoctorState(projectRoot);
+        const decision = decideThrottle(state, now);
+        if (decision.skip) {
+            const dirty = decision.dirty;
+            const status = dirty ? "dirty" : "ok";
+            const line = renderDoctorStatusLine(decision, now);
+            return {
+                name: "doctor",
+                status,
+                ok: !dirty,
+                exitCode: dirty ? 1 : 0,
+                lines: [line],
+                shaMatch: false,
+                durationMs: elapsedMs(started),
+                detail: { throttle_skipped: true, dirty },
+            };
+        }
+        const runner = options.doctorRunner ?? cmdDoctor;
+        // Capture stdout/stderr from doctor JSON mode for a terse status.
+        const captured = [];
+        const prevOut = process.stdout.write.bind(process.stdout);
+        const prevErr = process.stderr.write.bind(process.stderr);
+        const capture = (chunk) => {
+            captured.push(String(chunk));
+            return true;
+        };
+        process.stdout.write = capture;
+        process.stderr.write = capture;
+        let code = 0;
+        try {
+            code = runner(["--project-root", projectRoot, "--json"], options.seams);
+        }
+        finally {
+            process.stdout.write = prevOut;
+            process.stderr.write = prevErr;
+        }
+        const status = code === 0 ? "ok" : code === 1 ? "dirty" : "error";
+        const summary = code === 0 ? "[deft doctor] status: ok" : `[deft doctor] status: ${status} (exit ${code})`;
+        return {
+            name: "doctor",
+            status,
+            ok: code === 0,
+            exitCode: code,
+            lines: [summary],
+            shaMatch: false,
+            durationMs: elapsedMs(started),
+            detail: { throttle_skipped: false, captured_len: captured.join("").length },
+        };
+    }
+    catch (exc) {
+        // Session:start continues, but do not persist as a successful gated doctor
+        // step (Greptile #3286) — next verify:session-ritual must re-run doctor.
+        return {
+            name: "doctor",
+            status: "error",
+            ok: false,
+            exitCode: 2,
+            lines: [`[deft doctor] status: error (session continues): ${String(exc)}`],
+            shaMatch: false,
+            durationMs: elapsedMs(started),
+        };
+    }
+}
+export function runPreflightOrientationSection(projectRoot, options = {}) {
+    const started = performance.now();
+    if (options.result === null) {
+        return {
+            section: {
+                name: "preflight",
+                status: "skipped",
+                ok: true,
+                exitCode: 0,
+                lines: ["[deft preflight] toolchain status: skipped"],
+                shaMatch: false,
+                durationMs: 0,
+            },
+            preflight: null,
+        };
+    }
+    try {
+        const preflight = options.result ??
+            runToolchainPreflight({
+                projectRoot,
+                frameworkRoot: options.frameworkRoot ?? projectRoot,
+                ...options.preflightOptions,
+            });
+        const status = preflight.ok
+            ? "ok"
+            : preflight.degraded
+                ? "degraded"
+                : "error";
+        return {
+            section: {
+                name: "preflight",
+                status,
+                ok: preflight.ok || preflight.degraded,
+                exitCode: preflight.ok ? 0 : 1,
+                lines: [...preflight.lines],
+                shaMatch: false,
+                durationMs: elapsedMs(started),
+                detail: toolchainPreflightToDict(preflight),
+            },
+            preflight,
+        };
+    }
+    catch (exc) {
+        return {
+            section: {
+                name: "preflight",
+                status: "error",
+                ok: false,
+                exitCode: 2,
+                lines: [`[deft preflight] toolchain status: error (session continues): ${String(exc)}`],
+                shaMatch: false,
+                durationMs: elapsedMs(started),
+            },
+            preflight: null,
+        };
+    }
+}
+/**
+ * agents:refresh orientation section (#3286).
+ * Always plans against live AGENTS.md so local managed-section edits are
+ * detected (deposit fingerprint alone is insufficient). Content-current →
+ * one-line sha-match phrasing; deposit-sha is recorded for orientation telemetry.
+ */
+export function runAgentsRefreshOrientationSection(projectRoot, options) {
+    const started = performance.now();
+    void options.prior;
+    try {
+        const apply = options.apply ?? applyAgentsRefresh;
+        const result = apply(projectRoot, {});
+        if (result.state === "current") {
+            const line = formatDepositShaMatchLine("agents:refresh");
+            return {
+                name: "agents_refresh",
+                status: "sha_match",
+                ok: true,
+                exitCode: 0,
+                lines: [line],
+                shaMatch: true,
+                depositSha: options.depositSha,
+                durationMs: elapsedMs(started),
+                detail: { state: result.state, wrote: result.wrote },
+            };
+        }
+        if (result.state === "template-missing" ||
+            result.state === "template-malformed" ||
+            result.state === "unreadable") {
+            return {
+                name: "agents_refresh",
+                status: "error",
+                ok: false,
+                exitCode: 2,
+                lines: [`[deft agents:refresh] failed: ${result.state}`],
+                shaMatch: false,
+                depositSha: options.depositSha,
+                durationMs: elapsedMs(started),
+                detail: { state: result.state },
+            };
+        }
+        const wrote = result.wrote;
+        const msg = wrote
+            ? `[deft agents:refresh] updated (state=${result.state})`
+            : `[deft agents:refresh] state=${result.state}`;
+        return {
+            name: "agents_refresh",
+            status: "ok",
+            ok: true,
+            exitCode: 0,
+            lines: [msg],
+            shaMatch: false,
+            depositSha: options.depositSha,
+            durationMs: elapsedMs(started),
+            detail: { state: result.state, wrote },
+        };
+    }
+    catch (exc) {
+        // Fail-open for session:start composition, but do NOT persist as ok —
+        // next session must retry (Greptile #3286 P1).
+        return {
+            name: "agents_refresh",
+            status: "error",
+            ok: false,
+            exitCode: 2,
+            lines: [`[deft agents:refresh] error (session continues): ${String(exc)}`],
+            shaMatch: false,
+            depositSha: options.depositSha,
+            durationMs: elapsedMs(started),
+        };
+    }
+}
+/**
+ * verify:cache-fresh orientation section (#3286).
+ * Always runs the live evaluate (age + drift). Deposit fingerprint is recorded
+ * for orientation telemetry only — it must not suppress triage-cache freshness.
+ * When evaluate is already clean, surface a one-line sha-match-style no-op only
+ * if the message is the canonical deposit phrase (not used for shortcuts).
+ */
+export function runCacheFreshOrientationSection(projectRoot, options) {
+    const started = performance.now();
+    void options.prior;
+    void options.now;
+    try {
+        const evaluate = options.evaluateFn ?? evaluateCacheFresh;
+        const consumerDeposit = !isFrameworkRepoRoot(projectRoot);
+        // Consumer deposits often have no triage cache. Treat that as a named
+        // bootstrap cause (dirty), never a generic orientation `error` (#3335).
+        // Framework source still evaluates live; missing cache stays non-green
+        // (#3286) so gated verify re-runs cache_fresh.
+        const result = evaluate(projectRoot, {
+            allowMissingBootstrap: false,
+            autoPopulateEmpty: false,
+            ...options.evaluateOptions,
+        });
+        const ok = result.code === 0;
+        const missingCache = result.code === 2 && /not found|bootstrap/i.test(result.message);
+        const namedCause = missingCache
+            ? consumerDeposit
+                ? `[deft cache-fresh] triage cache not populated (consumer deposit) — not a toolchain failure. Recovery: run \`deft triage:bootstrap\` if you need the queue.`
+                : result.message
+            : result.message;
+        // Tag as sha_match only when message already uses the canonical phrase
+        // (e.g. tests inject it) — never invent a shortcut past evaluate.
+        const shaMatch = ok && result.message.includes(DEPOSIT_SHA_MATCH_NOOP);
+        const status = shaMatch
+            ? "sha_match"
+            : ok
+                ? "ok"
+                : missingCache
+                    ? "dirty"
+                    : result.code === 2
+                        ? "error"
+                        : "dirty";
+        return {
+            name: "cache_fresh",
+            status,
+            ok,
+            exitCode: result.code,
+            lines: [namedCause],
+            shaMatch,
+            depositSha: options.depositSha,
+            durationMs: elapsedMs(started),
+            detail: { code: result.code, missing_cache: missingCache },
+        };
+    }
+    catch (exc) {
+        return {
+            name: "cache_fresh",
+            status: "error",
+            ok: false,
+            exitCode: 2,
+            lines: [`[deft cache-fresh] error (session continues): ${String(exc)}`],
+            shaMatch: false,
+            depositSha: options.depositSha,
+            durationMs: elapsedMs(started),
+        };
+    }
+}
+function toSurface(section, now) {
+    return surfaceRecord(section.ok, section.exitCode, now, section.lines[0]);
+}
+/**
+ * Run the composed orientation sections for a mutation cold session:start.
+ */
+export function runOrientationCompression(options) {
+    const projectRoot = options.projectRoot;
+    const now = options.now ?? new Date();
+    const compact = resolveSessionCompact(options);
+    const depositSha = computeDepositSha({
+        projectRoot,
+        frameworkRoot: options.frameworkRoot ?? projectRoot,
+        ...options.depositShaOptions,
+    });
+    const prior = readOrientationState(projectRoot);
+    const sections = [];
+    let preflightResult = null;
+    if (options.includeDoctor !== false) {
+        const doctor = options.doctorSection !== undefined
+            ? options.doctorSection
+            : runDoctorOrientationSection(projectRoot, {
+                now,
+                seams: options.doctorSeams,
+            });
+        if (doctor !== null)
+            sections.push(doctor);
+    }
+    if (options.includePreflight !== false) {
+        const { section, preflight } = runPreflightOrientationSection(projectRoot, {
+            frameworkRoot: options.frameworkRoot,
+            result: options.toolchainPreflight,
+            preflightOptions: options.toolchainPreflightOptions,
+        });
+        preflightResult = preflight;
+        if (section !== null)
+            sections.push(section);
+    }
+    if (options.includeAgentsRefresh !== false) {
+        const agents = options.agentsRefreshSection !== undefined
+            ? options.agentsRefreshSection
+            : runAgentsRefreshOrientationSection(projectRoot, {
+                depositSha,
+                prior,
+                now,
+            });
+        if (agents !== null)
+            sections.push(agents);
+    }
+    if (options.includeCacheFresh !== false) {
+        const cache = options.cacheFreshSection !== undefined
+            ? options.cacheFreshSection
+            : runCacheFreshOrientationSection(projectRoot, {
+                depositSha,
+                prior,
+                now,
+                evaluateOptions: options.cacheFreshOptions,
+            });
+        if (cache !== null)
+            sections.push(cache);
+    }
+    const lines = compact
+        ? formatOrientationCompactLines(sections)
+        : formatOrientationVerboseLines(sections);
+    const byName = (n) => sections.find((s) => s.name === n);
+    const state = {
+        schema_version: 1,
+        deposit_sha: depositSha,
+        updated_at: now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+        ...(byName("agents_refresh")
+            ? { agents_refresh: toSurface(byName("agents_refresh"), now) }
+            : {}),
+        ...(byName("cache_fresh")
+            ? { cache_fresh: toSurface(byName("cache_fresh"), now) }
+            : {}),
+        ...(byName("doctor")
+            ? { doctor: toSurface(byName("doctor"), now) }
+            : {}),
+        ...(byName("preflight")
+            ? { preflight: toSurface(byName("preflight"), now) }
+            : {}),
+    };
+    if (options.persistState !== false) {
+        try {
+            writeOrientationState(projectRoot, state);
+        }
+        catch {
+            // fail-open
+        }
+    }
+    return {
+        depositSha,
+        compact,
+        sections,
+        lines,
+        orientationCallCount: sections.length,
+        later: {
+            status: ORIENTATION_LATER_STATUS,
+            command: ORIENTATION_LATER_COMMAND,
+            trigger: ORIENTATION_GRADUATION_TRIGGER,
+        },
+        preflight: preflightResult,
+        state,
+    };
+}
+export { computeDepositSha, DEPOSIT_SHA_MATCH_NOOP, depositShaMatches, formatDepositShaMatchLine, } from "./deposit-sha.js";
+//# sourceMappingURL=orientation-compression.js.map

package/dist/session/orientation-state.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Persisted orientation deposit fingerprint (#3286).
+ *
+ * Enables agents:refresh / verify:cache-fresh one-line sha-match no-ops on
+ * repeat sessions when payload + templates + engine are unchanged.
+ */
+export declare const ORIENTATION_STATE_REL: string;
+export declare const ORIENTATION_STATE_SCHEMA: 1;
+export interface OrientationSurfaceRecord {
+    readonly ok: boolean;
+    readonly ts: string;
+    readonly exit_code: number;
+    readonly message?: string;
+}
+export interface OrientationState {
+    readonly schema_version: typeof ORIENTATION_STATE_SCHEMA;
+    readonly deposit_sha: string;
+    readonly updated_at: string;
+    readonly agents_refresh?: OrientationSurfaceRecord;
+    readonly cache_fresh?: OrientationSurfaceRecord;
+    readonly doctor?: OrientationSurfaceRecord;
+    readonly preflight?: OrientationSurfaceRecord;
+}
+export declare function orientationStatePath(projectRoot: string): string;
+export declare function parseOrientationState(raw: unknown): OrientationState | null;
+export declare function readOrientationState(projectRoot: string): OrientationState | null;
+export declare function writeOrientationState(projectRoot: string, state: OrientationState): string;
+export declare function surfaceRecord(ok: boolean, exitCode: number, now: Date, message?: string): OrientationSurfaceRecord;
+//# sourceMappingURL=orientation-state.d.ts.map

package/dist/session/orientation-state.js

@@ -0,0 +1,85 @@
+/**
+ * Persisted orientation deposit fingerprint (#3286).
+ *
+ * Enables agents:refresh / verify:cache-fresh one-line sha-match no-ops on
+ * repeat sessions when payload + templates + engine are unchanged.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+export const ORIENTATION_STATE_REL = join(".deft", "orientation-state.json");
+export const ORIENTATION_STATE_SCHEMA = 1;
+export function orientationStatePath(projectRoot) {
+    return join(resolve(projectRoot), ORIENTATION_STATE_REL);
+}
+function parseRecord(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const rec = raw;
+    if (typeof rec.ok !== "boolean")
+        return undefined;
+    if (typeof rec.ts !== "string" || rec.ts.trim().length === 0)
+        return undefined;
+    const exit = typeof rec.exit_code === "number" ? rec.exit_code : rec.ok ? 0 : 1;
+    return {
+        ok: rec.ok,
+        ts: rec.ts,
+        exit_code: exit,
+        message: typeof rec.message === "string" ? rec.message : undefined,
+    };
+}
+export function parseOrientationState(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const rec = raw;
+    if (typeof rec.deposit_sha !== "string" || rec.deposit_sha.trim().length === 0)
+        return null;
+    if (typeof rec.updated_at !== "string" || rec.updated_at.trim().length === 0)
+        return null;
+    const schema = typeof rec.schema_version === "number" ? rec.schema_version : ORIENTATION_STATE_SCHEMA;
+    if (schema !== ORIENTATION_STATE_SCHEMA)
+        return null;
+    return {
+        schema_version: ORIENTATION_STATE_SCHEMA,
+        deposit_sha: rec.deposit_sha.trim(),
+        updated_at: rec.updated_at.trim(),
+        agents_refresh: parseRecord(rec.agents_refresh),
+        cache_fresh: parseRecord(rec.cache_fresh),
+        doctor: parseRecord(rec.doctor),
+        preflight: parseRecord(rec.preflight),
+    };
+}
+export function readOrientationState(projectRoot) {
+    const path = orientationStatePath(projectRoot);
+    if (!existsSync(path))
+        return null;
+    try {
+        const text = readFileSync(path, "utf8");
+        return parseOrientationState(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeOrientationState(projectRoot, state) {
+    const path = orientationStatePath(projectRoot);
+    const parent = dirname(path);
+    mkdirSync(parent, { recursive: true });
+    const body = `${JSON.stringify(state, null, 2)}\n`;
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: body,
+        mode: "replace",
+    });
+    return path;
+}
+export function surfaceRecord(ok, exitCode, now, message) {
+    return {
+        ok,
+        ts: now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+        exit_code: exitCode,
+        ...(message !== undefined ? { message } : {}),
+    };
+}
+//# sourceMappingURL=orientation-state.js.map

package/dist/session/session-start.d.ts

@@ -1,12 +1,15 @@
 import { type HostContentSurfaceSeams } from "../platform/host-content-surface.js";
 import { type EnvironmentContext } from "../platform/shell-context.js";
 import { type CeremonyDialInputs, type CeremonyDialSelection, type ProvisionalCeremonyEstimateHints } from "../policy/ceremony-dial.js";
+import { type CeremonyStartTierProvenance } from "../policy/ceremony-dial-escalation.js";
 import { type ProbeScmReadinessOptions, type ScmReadinessReport } from "../scm/readiness.js";
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import { type DetectHardEffortBudgetInput } from "./effort-budget.js";
 import type { GitRunner } from "./git.js";
+import { type OrientationBundle, type RunOrientationOptions } from "./orientation-compression.js";
 import { type ReleaseAvailabilityProbeOptions } from "./release-availability.js";
 import { type RitualState, ritualStatePath } from "./ritual-sentinel.js";
+import { type ToolchainPreflightOptions, type ToolchainPreflightResult } from "./toolchain-preflight.js";
 export declare const SESSION_POSTURES: readonly ["read-only", "mutation"];
 export type SessionPosture = (typeof SESSION_POSTURES)[number];
 export declare const READ_ONLY_POSTURE: SessionPosture;
@@ -123,6 +126,34 @@ export interface SessionStartOptions {
      * loads plan.policy.ceremonyDial and applies inputs (after provisional fill).
      */
     readonly ceremonyDial?: CeremonyDialSelection;
+    /**
+     * #3319: start-tier provenance hint. CLI `--ceremony-depth` / harness pin
+     * should pass `external-pin`. Policy override is inferred as `operator`.
+     */
+    readonly ceremonyDialStartTierProvenance?: CeremonyStartTierProvenance;
+    /**
+     * #3282: done-gate toolchain preflight seams (tests inject result or probe).
+     * When omitted, runs live preflight after verify_tools on cold path.
+     * #3286: preflight is composed into orientation sections with doctor +
+     * deposit-sha fast-paths for agents:refresh / cache-fresh.
+     */
+    readonly toolchainPreflight?: ToolchainPreflightResult | null;
+    readonly toolchainPreflightOptions?: ToolchainPreflightOptions;
+    /** #3282: disable run-summary emission (tests). */
+    readonly emitRunSummary?: boolean;
+    /** #3282: framework root for CLI dist probe (defaults to projectRoot). */
+    readonly frameworkRoot?: string;
+    /**
+     * #3286: compact orientation output (terse machine lines). Default verbose.
+     * CLI: `--compact`; env: `DEFT_SESSION_COMPACT=1`.
+     */
+    readonly compact?: boolean;
+    /**
+     * #3286: orientation compression seams (tests inject full bundle or partial
+     * section overrides). When `orientation === null`, skip composition entirely.
+     */
+    readonly orientation?: OrientationBundle | null;
+    readonly orientationOptions?: Partial<RunOrientationOptions>;
 }
 /** Format preferred `session:start` recovery command for cold vs re-arm (#2992). */
 export declare function formatSessionStartRecoveryCommand(tier?: SessionCeremonyTier): string;