@deftai/directive-core 0.68.1 → 0.69.0

package/dist/resolution/pin.js

@@ -0,0 +1,169 @@
+/**
+ * Version pin + reconciliation for the resolution spine (#2264, absorbs #2199).
+ *
+ * The committed `package.json` devDependency on `@deftai/directive` (exact,
+ * `"private": true`) is the CANONICAL pin — read before directive runs, npm-native
+ * so the engine ladder stays plain npm. This module reads that pin and reconciles
+ * it against the reachable engine version, the `.deft/core/VERSION` content marker,
+ * and the AGENTS.md managed-section `sha=`.
+ *
+ * Semver helpers here are the single comparison primitive reused by the skew
+ * policy and the engine ladder so version ordering is defined in exactly one place.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The canonical committed dependency the pin lives on. */
+export const PIN_DEPENDENCY_NAME = "@deftai/directive";
+const BARE_SEMVER_RE = /^\d+\.\d+\.\d+([-+][0-9A-Za-z.-]+)?$/;
+const EXACT_SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?$/;
+/** Parse a semver prefix (`major.minor.patch`); null when not exact semver. */
+export function parseSemver(version) {
+    if (typeof version !== "string")
+        return null;
+    const normalized = version.trim().replace(/^v/i, "");
+    const match = EXACT_SEMVER_RE.exec(normalized);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `version` is an EXACT pin (no range operators like `^` / `~` / `*`). */
+export function isExactPin(version) {
+    if (typeof version !== "string")
+        return false;
+    return BARE_SEMVER_RE.test(version.trim().replace(/^v/i, ""));
+}
+/** Compare two versions: -1 (a<b), 0 (a==b), 1 (a>b); null when either is unparseable. */
+export function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (pa === null || pb === null)
+        return null;
+    for (let i = 0; i < 3; i += 1) {
+        const av = pa[i] ?? 0;
+        const bv = pb[i] ?? 0;
+        if (av > bv)
+            return 1;
+        if (av < bv)
+            return -1;
+    }
+    return 0;
+}
+/** True when `a >= b` under semver ordering; false when either is unparseable. */
+export function semverGte(a, b) {
+    const cmp = compareSemver(a, b);
+    return cmp === 0 || cmp === 1;
+}
+function defaultIsFile(p) {
+    try {
+        return existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+function defaultReadText(p) {
+    try {
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function readDependencySpec(pkg) {
+    for (const block of ["devDependencies", "dependencies"]) {
+        const deps = pkg[block];
+        if (typeof deps === "object" && deps !== null && !Array.isArray(deps)) {
+            const spec = deps[PIN_DEPENDENCY_NAME];
+            if (typeof spec === "string" && spec.trim().length > 0) {
+                return spec.trim();
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Read the committed `package.json` pin on `@deftai/directive`. The pin is
+ * canonical only when it is an EXACT version; a range spec is reported via
+ * `nonExact` so callers can warn rather than silently trusting a floating range.
+ */
+export function readPin(projectRoot, seams = {}) {
+    const isFile = seams.isFile ?? defaultIsFile;
+    const readText = seams.readText ?? defaultReadText;
+    const absent = {
+        pinVersion: null,
+        rawSpec: null,
+        isPrivate: false,
+        nonExact: false,
+    };
+    const path = join(projectRoot, "package.json");
+    if (!isFile(path))
+        return absent;
+    const text = readText(path);
+    if (text === null)
+        return absent;
+    let pkg;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return absent;
+        pkg = parsed;
+    }
+    catch {
+        return absent;
+    }
+    const isPrivate = pkg.private === true;
+    const rawSpec = readDependencySpec(pkg);
+    if (rawSpec === null)
+        return { pinVersion: null, rawSpec: null, isPrivate, nonExact: false };
+    if (!isExactPin(rawSpec)) {
+        return { pinVersion: null, rawSpec, isPrivate, nonExact: true };
+    }
+    return {
+        pinVersion: rawSpec.replace(/^v/i, ""),
+        rawSpec,
+        isPrivate,
+        nonExact: false,
+    };
+}
+/**
+ * Reconcile the pin against the engine, the deposited content marker, and the
+ * AGENTS managed-section sha. The managed-section `sha=` is part of the
+ * reconciliation, not just `VERSION` (per the #2264 acceptance).
+ */
+export function reconcileVersions(inputs) {
+    const { pinVersion, engineVersion, contentVersion, managedSectionSha } = inputs;
+    const mismatches = [];
+    const contentCmp = compareSemver(contentVersion, pinVersion);
+    const contentBehindPin = contentCmp === -1;
+    if (contentBehindPin) {
+        mismatches.push(`.deft/core/VERSION (${contentVersion}) is behind the package.json pin (${pinVersion}); content forward-migration required`);
+    }
+    else if (contentCmp === 1) {
+        mismatches.push(`.deft/core/VERSION (${contentVersion}) is ahead of the package.json pin (${pinVersion})`);
+    }
+    if (engineVersion !== null && pinVersion !== null) {
+        const engineCmp = compareSemver(engineVersion, pinVersion);
+        if (engineCmp === -1) {
+            mismatches.push(`engine (${engineVersion}) is behind the package.json pin (${pinVersion})`);
+        }
+    }
+    let managedShaMismatch = false;
+    const expected = inputs.expectedManagedSectionSha;
+    if (typeof expected === "string" && expected.length > 0) {
+        if (managedSectionSha === null) {
+            managedShaMismatch = true;
+            mismatches.push("AGENTS.md managed-section sha is absent but an expected sha is known");
+        }
+        else if (managedSectionSha !== expected) {
+            managedShaMismatch = true;
+            mismatches.push(`AGENTS.md managed-section sha (${managedSectionSha}) does not match expected (${expected})`);
+        }
+    }
+    return {
+        consistent: mismatches.length === 0,
+        contentBehindPin,
+        managedShaMismatch,
+        mismatches,
+    };
+}
+//# sourceMappingURL=pin.js.map

package/dist/resolution/plan.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The single ordered precedence table for the resolution spine (#2264 / epic #2203).
+ *
+ * `plan()` takes the orthogonal fact-set from `classify()` and collapses it into
+ * exactly ONE recommended action, emitting the versioned public
+ * {@link ResolutionPlan} schema. This is the single source of truth every
+ * consumption context (init / update / doctor / headless) derives from — there
+ * is no second classifier downstream (closes the #537 split-source drift risk).
+ *
+ * SCOPE (keystone): this delivers the decision spine. It does NOT rewire the
+ * user-facing behavior of init / update / doctor / headless (children B–E,
+ * #2265–#2268), which consume `plan()`. The `files` array is therefore empty in
+ * the spine; downstream children populate it.
+ */
+import type { PlanPolicy, ResolutionFacts, ResolutionFile, ResolutionPlan } from "@deftai/directive-types";
+import type { LadderDecision } from "./engine-ladder.js";
+import { type PackageManager } from "./package-manager.js";
+import { type SkewResult } from "./skew-policy.js";
+export interface PlanOptions {
+    /**
+     * Pre-computed engine ladder decision, supplied when the global engine is
+     * unreachable and the caller resolved it via `decideEngineLadder`/`resolveEngine`
+     * (warm sandbox / cold sandbox / registry-down). When omitted, `plan()` uses the
+     * in-process reachable engine facts.
+     */
+    readonly engineResolution?: LadderDecision | null;
+    /** Pre-computed skew result; when omitted `plan()` computes it from facts + policy. */
+    readonly skew?: SkewResult | null;
+    /** Interactive session (a human can answer a skew prompt). */
+    readonly interactive?: boolean;
+    /** Environment map for the `DEFT_ACCEPT_ENGINE_SKEW` escape hatch. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** The `--accept-engine-jump` flag was supplied. */
+    readonly acceptEngineJump?: boolean;
+    /** Platform id, used only to render the sandbox install command. */
+    readonly platform?: string;
+    /**
+     * Files a downstream consumer has already materialised for the plan to carry
+     * in {@link ResolutionPlan.files}. The keystone spine leaves `files` empty;
+     * children (the #2268 headless emitter) collect the file set out-of-band and
+     * thread it here so the emitted manifest is single-sourced from `plan()`
+     * rather than a separate "what would init produce" reimplementation. When
+     * omitted, `files` stays empty exactly as before.
+     */
+    readonly files?: readonly ResolutionFile[];
+    /**
+     * Active package manager for rendering install/upgrade command strings
+     * (#2197). Defaults to npm so existing behaviour and tests are unchanged;
+     * callers detect the manager via `detectPackageManager()` and thread it here.
+     * The sandbox (`install-sandbox`) rung stays on npm regardless of this value
+     * -- the `.deft/.cli/<platform>` layout is npm-shaped and package-manager
+     * invisible (locked non-goal, issue #2197).
+     */
+    readonly packageManager?: PackageManager;
+}
+/**
+ * The single ordered precedence table. First matching row wins; each `plan()`
+ * call returns exactly one recommended action.
+ *
+ * When `options.files` is supplied, the resolved plan carries that file set in
+ * {@link ResolutionPlan.files} (the #2268 headless single-sourcing seam); the
+ * precedence decision itself is unchanged. With no `files` option the array
+ * stays empty exactly as the keystone spine emitted it.
+ */
+export declare function plan(facts: ResolutionFacts, policy?: PlanPolicy, options?: PlanOptions): ResolutionPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/resolution/plan.js

@@ -0,0 +1,219 @@
+/**
+ * The single ordered precedence table for the resolution spine (#2264 / epic #2203).
+ *
+ * `plan()` takes the orthogonal fact-set from `classify()` and collapses it into
+ * exactly ONE recommended action, emitting the versioned public
+ * {@link ResolutionPlan} schema. This is the single source of truth every
+ * consumption context (init / update / doctor / headless) derives from — there
+ * is no second classifier downstream (closes the #537 split-source drift risk).
+ *
+ * SCOPE (keystone): this delivers the decision spine. It does NOT rewire the
+ * user-facing behavior of init / update / doctor / headless (children B–E,
+ * #2265–#2268), which consume `plan()`. The `files` array is therefore empty in
+ * the spine; downstream children populate it.
+ */
+import { RESOLUTION_PLAN_SCHEMA_VERSION } from "@deftai/directive-types";
+import { ENGINE_PACKAGE, renderEphemeral, renderGlobalInstall, } from "./package-manager.js";
+import { reconcileVersions } from "./pin.js";
+import { evaluateSkew } from "./skew-policy.js";
+const RUNG_TO_MODE = {
+    global: "proceed",
+    local: "proceed",
+    "install-global": "install-global",
+    "install-sandbox": "install-sandbox",
+    "install-staged": "install-staged",
+    "hard-fail": "blocked",
+};
+function pinSuffix(pinVersion) {
+    return pinVersion ? `@${pinVersion}` : "@<pin>";
+}
+function makePlan(mode, nextAction, warnings) {
+    return {
+        schemaVersion: RESOLUTION_PLAN_SCHEMA_VERSION,
+        mode,
+        files: [],
+        nextAction,
+        warnings,
+    };
+}
+function legacyVbriefWarning(facts) {
+    if (facts.hasVbrief && !facts.hasXbrief) {
+        return "legacy vbrief/ tree present without xbrief/; run `directive migrate:xbrief`";
+    }
+    return null;
+}
+/** Resolve the effective engine version from either the ladder decision or in-process facts. */
+function effectiveEngineVersion(facts, engineResolution) {
+    if (engineResolution?.usable)
+        return engineResolution.resolvedVersion;
+    if (facts.engineReachable)
+        return facts.engineVersion;
+    return null;
+}
+function contentStale(facts) {
+    const recon = reconcileVersions({
+        pinVersion: facts.pinVersion,
+        engineVersion: facts.engineVersion,
+        contentVersion: facts.deftCorePayloadVersion,
+        managedSectionSha: facts.managedSectionSha,
+    });
+    if (recon.contentBehindPin)
+        return true;
+    // A deposit that carries no readable managed-section sha is treated as stale.
+    if (facts.hasManagedSection && facts.managedSectionSha === null)
+        return true;
+    return false;
+}
+/**
+ * The single ordered precedence table. First matching row wins; each `plan()`
+ * call returns exactly one recommended action.
+ *
+ * When `options.files` is supplied, the resolved plan carries that file set in
+ * {@link ResolutionPlan.files} (the #2268 headless single-sourcing seam); the
+ * precedence decision itself is unchanged. With no `files` option the array
+ * stays empty exactly as the keystone spine emitted it.
+ */
+export function plan(facts, policy = {}, options = {}) {
+    const resolved = resolvePlan(facts, policy, options);
+    const files = options.files ?? [];
+    return files.length === 0 ? resolved : { ...resolved, files };
+}
+function resolvePlan(facts, policy, options) {
+    const warnings = [];
+    const pm = options.packageManager ?? "npm";
+    const legacyWarning = legacyVbriefWarning(facts);
+    if (legacyWarning)
+        warnings.push(legacyWarning);
+    // Row 1: pre-cutover artifacts must migrate before anything else.
+    if (facts.preCutoverArtifacts) {
+        return makePlan("migrate", {
+            command: null,
+            rootCause: "pre-v0.20 document-model artifacts detected",
+            remediation: "Migrate with the frozen pre-v0.20 bridge before any gate runs. See UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068).",
+        }, warnings);
+    }
+    // Row 2: no usable deposit — deposit / reconstitute one.
+    if (!facts.hasDeftCore) {
+        const rootCause = facts.hasManagedSection
+            ? "AGENTS.md carries a managed section but the .deft/core/ payload is absent (hybrid deposit not reconstituted)"
+            : facts.hasAppCode || facts.hasGit
+                ? "brownfield project without a Deft deposit"
+                : "greenfield project without a Deft deposit";
+        return makePlan("init", {
+            command: renderEphemeral(pm, "init"),
+            rootCause,
+            remediation: "Deposit (or reconstitute) the .deft/core/ payload with `directive init`.",
+        }, warnings);
+    }
+    // Row 3+: deposit present — resolve the engine dimension.
+    const engineResolution = options.engineResolution ?? null;
+    // 3a: a supplied ladder decision that requires an install (global engine
+    // unreachable path: warm/cold sandbox, registry-down).
+    if (engineResolution && !engineResolution.usable) {
+        const mode = RUNG_TO_MODE[engineResolution.rung];
+        return planForInstallRung(engineResolution, mode, facts, options, warnings);
+    }
+    const effectiveEngine = effectiveEngineVersion(facts, engineResolution);
+    // 3b: no engine reachable and no ladder resolution supplied — cannot resolve.
+    if (effectiveEngine === null) {
+        return makePlan("blocked", {
+            command: null,
+            rootCause: "no Directive engine is reachable in the execution environment",
+            remediation: "Resolve the engine via the global-first ladder (resolveEngine) / bootstrap before running any gate.",
+        }, warnings);
+    }
+    // 3c: no committed pin — cannot reconcile; proceed but warn.
+    if (facts.pinVersion === null) {
+        warnings.push("no committed package.json pin on @deftai/directive; skipping engine/pin reconciliation");
+        return makePlan("proceed", {
+            command: null,
+            rootCause: `engine ${effectiveEngine} reachable; no pin to reconcile against`,
+            remediation: "Run the requested gate. Consider committing an exact pin (unblocks #2269).",
+        }, warnings);
+    }
+    // 3d: reconcile engine against the pin via the three-band skew policy.
+    const skew = options.skew ??
+        evaluateSkew(effectiveEngine, facts.pinVersion, {
+            engineSkewWindow: policy.engineSkewWindow,
+            acceptEngineJump: options.acceptEngineJump,
+            interactive: options.interactive,
+            env: options.env,
+        });
+    if (skew.message)
+        warnings.push(skew.message);
+    switch (skew.decision) {
+        case "reject-global":
+            return makePlan("install-global", {
+                command: renderGlobalInstall(pm, `${ENGINE_PACKAGE}${pinSuffix(facts.pinVersion)}`),
+                rootCause: `engine ${effectiveEngine} is behind pin ${facts.pinVersion}`,
+                remediation: "Install the pinned engine (or fall through the ladder to a local install).",
+            }, warnings);
+        case "fail-closed":
+            return makePlan("blocked", {
+                command: `directive <gate> --accept-engine-jump`,
+                rootCause: `engine ${effectiveEngine} is a large jump ahead of pin ${facts.pinVersion}`,
+                remediation: "Confirm the jump with --accept-engine-jump or DEFT_ACCEPT_ENGINE_SKEW=1 after reviewing the delta.",
+            }, warnings);
+        case "prompt":
+            return makePlan("blocked", {
+                command: null,
+                rootCause: `engine ${effectiveEngine} is a large jump ahead of pin ${facts.pinVersion} (interactive)`,
+                remediation: "Prompt the operator to confirm the engine jump, or pass --accept-engine-jump.",
+            }, warnings);
+        default: {
+            // proceed-silent | proceed-loud-update
+            if (skew.requiresUpdateFirst || contentStale(facts)) {
+                return makePlan("update", {
+                    command: renderEphemeral(pm, "update"),
+                    rootCause: skew.requiresUpdateFirst
+                        ? `engine ${effectiveEngine} is ahead of pin ${facts.pinVersion} within the skew window`
+                        : `deposited content is behind pin ${facts.pinVersion}`,
+                    remediation: "Forward-migrate content with `directive update`, then run the gate.",
+                }, warnings);
+            }
+            return makePlan("proceed", {
+                command: null,
+                rootCause: `engine ${effectiveEngine} matches pin ${facts.pinVersion} and content is current`,
+                remediation: "Run the requested gate.",
+            }, warnings);
+        }
+    }
+}
+function planForInstallRung(engineResolution, mode, facts, options, warnings) {
+    const platform = options.platform ?? "<platform>";
+    const pm = options.packageManager ?? "npm";
+    const pinnedSuffix = pinSuffix(facts.pinVersion);
+    const withTrace = [...warnings, `ladder: ${engineResolution.trace}`];
+    switch (mode) {
+        case "install-global":
+            return makePlan("install-global", {
+                command: renderGlobalInstall(pm, `${ENGINE_PACKAGE}${pinnedSuffix}`),
+                rootCause: engineResolution.reason,
+                remediation: pm === "pnpm"
+                    ? "Install the pinned engine into the pnpm global bin (ensure PNPM_HOME is on PATH; run `pnpm setup` if needed)."
+                    : "Install the pinned engine into the global npm prefix.",
+            }, withTrace);
+        case "install-sandbox":
+            // Locked non-goal (#2197): the .deft/.cli/<platform> sandbox stays on npm
+            // regardless of the caller's package manager -- its node_modules/.bin
+            // layout is npm-shaped and validated by integrity.ts.
+            return makePlan("install-sandbox", {
+                command: `npm install --prefix .deft/.cli/${platform} @deftai/directive${pinnedSuffix}`,
+                rootCause: engineResolution.reason,
+                remediation: "Install the pinned engine into the sandbox-local .deft/.cli/<platform> prefix.",
+            }, withTrace);
+        case "install-staged":
+            return makePlan("install-staged", {
+                command: null,
+                rootCause: engineResolution.reason,
+                remediation: "Install from the pre-staged tarball / vendored payload (registry is down).",
+            }, withTrace);
+        default:
+            return makePlan("blocked", {
+                command: null,
+                rootCause: engineResolution.reason,
+                remediation: "Stage a Directive payload (registry down and no staged tarball).",
+            }, withTrace);
+    }
+}
+//# sourceMappingURL=plan.js.map

package/dist/resolution/skew-policy.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Three-band engine-vs-pin skew policy for the resolution spine (#2264, #2199).
+ *
+ * Content is always forward-migrated (`update`) before any gate runs; this
+ * policy governs whether a globally-reachable engine that differs from the pin
+ * may be used, and how loudly:
+ *
+ * - `engine == pin`                        -> proceed silently (trace only).
+ * - `engine > pin` within the skew window  -> proceed, emit a loud delta, `update` first.
+ * - `engine > pin` beyond the window       -> fail closed non-interactively (require
+ *                                              `--accept-engine-jump`; prompt when interactive).
+ *                                              `DEFT_ACCEPT_ENGINE_SKEW=1` is the CI escape.
+ * - `engine < pin`                         -> reject the global, fall through the ladder.
+ */
+/** Default skew window pre-1.0, measured in minor versions. */
+export declare const DEFAULT_ENGINE_SKEW_WINDOW = 3;
+/** Environment variable that acts as the CI / non-interactive escape hatch. */
+export declare const ACCEPT_ENGINE_SKEW_ENV = "DEFT_ACCEPT_ENGINE_SKEW";
+export type SkewBand = "match" | "within-window" | "beyond-window" | "engine-behind" | "unknown";
+export type SkewDecision = "proceed-silent" | "proceed-loud-update" | "prompt" | "fail-closed" | "reject-global";
+export interface SkewOptions {
+    /** Skew window (minor versions pre-1.0; ignored post-1.0 where "same major" applies). */
+    readonly engineSkewWindow?: number | null;
+    /** The `--accept-engine-jump` flag was supplied. */
+    readonly acceptEngineJump?: boolean;
+    /** Whether the session is interactive (a human can answer a prompt). */
+    readonly interactive?: boolean;
+    /** Environment map for the `DEFT_ACCEPT_ENGINE_SKEW` escape hatch. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface SkewResult {
+    readonly band: SkewBand;
+    readonly decision: SkewDecision;
+    /** Loud delta / fail-closed message, or null when silent. */
+    readonly message: string | null;
+    /** The recommended flow must run `update` before proceeding. */
+    readonly requiresUpdateFirst: boolean;
+    /** An escape hatch (flag or env) was used to permit a beyond-window jump. */
+    readonly escapeHatchUsed: boolean;
+}
+/**
+ * Evaluate the three-band skew policy for a reachable engine against the pin.
+ * Unparseable versions fail closed (a version we cannot order is not safe to run).
+ */
+export declare function evaluateSkew(engineVersion: string | null, pinVersion: string | null, opts?: SkewOptions): SkewResult;
+//# sourceMappingURL=skew-policy.d.ts.map

package/dist/resolution/skew-policy.js

@@ -0,0 +1,120 @@
+/**
+ * Three-band engine-vs-pin skew policy for the resolution spine (#2264, #2199).
+ *
+ * Content is always forward-migrated (`update`) before any gate runs; this
+ * policy governs whether a globally-reachable engine that differs from the pin
+ * may be used, and how loudly:
+ *
+ * - `engine == pin`                        -> proceed silently (trace only).
+ * - `engine > pin` within the skew window  -> proceed, emit a loud delta, `update` first.
+ * - `engine > pin` beyond the window       -> fail closed non-interactively (require
+ *                                              `--accept-engine-jump`; prompt when interactive).
+ *                                              `DEFT_ACCEPT_ENGINE_SKEW=1` is the CI escape.
+ * - `engine < pin`                         -> reject the global, fall through the ladder.
+ */
+import { compareSemver, parseSemver } from "./pin.js";
+/** Default skew window pre-1.0, measured in minor versions. */
+export const DEFAULT_ENGINE_SKEW_WINDOW = 3;
+/** Environment variable that acts as the CI / non-interactive escape hatch. */
+export const ACCEPT_ENGINE_SKEW_ENV = "DEFT_ACCEPT_ENGINE_SKEW";
+function resolveWindow(opts) {
+    const raw = opts.engineSkewWindow;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= 0)
+        return raw;
+    return DEFAULT_ENGINE_SKEW_WINDOW;
+}
+function escapeHatchActive(opts) {
+    if (opts.acceptEngineJump === true)
+        return true;
+    const env = opts.env ?? process.env;
+    return env[ACCEPT_ENGINE_SKEW_ENV] === "1";
+}
+/**
+ * Classify the `engine > pin` skew band. Pre-1.0 (pin major 0) the window is
+ * measured in minors; post-1.0 the window collapses to "same major".
+ */
+function classifyAheadBand(engine, pin, window) {
+    const [engineMajor, engineMinor] = engine;
+    const [pinMajor, pinMinor] = pin;
+    if (pinMajor === 0) {
+        if (engineMajor > 0)
+            return "beyond-window";
+        return engineMinor - pinMinor <= window ? "within-window" : "beyond-window";
+    }
+    return engineMajor === pinMajor ? "within-window" : "beyond-window";
+}
+/**
+ * Evaluate the three-band skew policy for a reachable engine against the pin.
+ * Unparseable versions fail closed (a version we cannot order is not safe to run).
+ */
+export function evaluateSkew(engineVersion, pinVersion, opts = {}) {
+    const engine = parseSemver(engineVersion);
+    const pin = parseSemver(pinVersion);
+    if (engine === null || pin === null) {
+        return {
+            band: "unknown",
+            decision: "fail-closed",
+            message: `cannot order engine (${engineVersion ?? "unknown"}) against pin (${pinVersion ?? "unknown"}); refusing to run an unorderable engine`,
+            requiresUpdateFirst: false,
+            escapeHatchUsed: false,
+        };
+    }
+    const cmp = compareSemver(engineVersion, pinVersion);
+    if (cmp === 0) {
+        return {
+            band: "match",
+            decision: "proceed-silent",
+            message: null,
+            requiresUpdateFirst: false,
+            escapeHatchUsed: false,
+        };
+    }
+    if (cmp === -1) {
+        return {
+            band: "engine-behind",
+            decision: "reject-global",
+            message: `engine ${engineVersion} is behind pin ${pinVersion}; rejecting global engine and falling through the ladder`,
+            requiresUpdateFirst: false,
+            escapeHatchUsed: false,
+        };
+    }
+    // engine > pin
+    const window = resolveWindow(opts);
+    const band = classifyAheadBand(engine, pin, window);
+    if (band === "within-window") {
+        return {
+            band,
+            decision: "proceed-loud-update",
+            message: `engine ${engineVersion} is ahead of pin ${pinVersion} within the skew window; proceeding after content update`,
+            requiresUpdateFirst: true,
+            escapeHatchUsed: false,
+        };
+    }
+    // beyond-window
+    if (escapeHatchActive(opts)) {
+        return {
+            band,
+            decision: "proceed-loud-update",
+            message: `engine ${engineVersion} is a large jump ahead of pin ${pinVersion}; accepted via escape hatch (--accept-engine-jump / ${ACCEPT_ENGINE_SKEW_ENV}=1)`,
+            requiresUpdateFirst: true,
+            escapeHatchUsed: true,
+        };
+    }
+    if (opts.interactive === true) {
+        return {
+            band,
+            decision: "prompt",
+            message: `engine ${engineVersion} is a large jump ahead of pin ${pinVersion}; prompt the operator to confirm (or pass --accept-engine-jump)`,
+            requiresUpdateFirst: true,
+            escapeHatchUsed: false,
+        };
+    }
+    return {
+        band,
+        decision: "fail-closed",
+        message: `engine ${engineVersion} is a large jump ahead of pin ${pinVersion}; failing closed. Re-run with --accept-engine-jump or ${ACCEPT_ENGINE_SKEW_ENV}=1`,
+        requiresUpdateFirst: false,
+        escapeHatchUsed: false,
+    };
+}
+//# sourceMappingURL=skew-policy.js.map

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

@@ -1,3 +1,4 @@
+import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { GitRunner } from "./git.js";
 import { ritualStatePath } from "./ritual-sentinel.js";
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
@@ -30,6 +31,7 @@ export interface SessionStartOptions {
     readonly verifyTools?: (output: (line: string) => void) => {
         exitCode: number;
     };
+    readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
 }
 export declare function parseDeferrals(rawValues: readonly string[]): {
     deferrals: Record<string, string>;