@deftai/directive-core 0.68.1 → 0.70.0

package/dist/resolution/package-manager.js

@@ -0,0 +1,103 @@
+/**
+ * Package-manager abstraction for the resolution spine (#2197, from #2264).
+ *
+ * The documented install/upgrade path historically hard-coded npm
+ * (`npm i -g @deftai/directive`). pnpm-managed setups have no first-class
+ * flow, and mixing an npm global into a pnpm environment breaks PATH/shim/store
+ * consistency. This module makes the *command rendering* package-manager aware
+ * so the resolution plan and doctor emit the right form for the active manager.
+ *
+ * Two load-bearing facts keep this small (locked on issue #2197):
+ *   1. NO additional registry. pnpm resolves from the same npm registry
+ *      (`registry.npmjs.org`) by default; the published `@deftai/directive`
+ *      tarball is unchanged. No renderer here ever emits a `--registry` flag.
+ *   2. The internal `.deft/.cli/<platform>` sandbox vendoring STAYS on npm
+ *      (its `node_modules/.bin` layout is validated by `integrity.ts` and is
+ *      gitignored / package-manager-invisible). Only the global, project-local,
+ *      ephemeral, and upgrade command forms vary by package manager.
+ *
+ * Every function here is PURE (no I/O): detection consumes an injected fact-set
+ * so the whole surface is unit-testable without touching the filesystem or env.
+ */
+export const PACKAGE_MANAGERS = ["npm", "pnpm"];
+export const DEFAULT_PACKAGE_MANAGER = "npm";
+/** Canonical published engine package name. */
+export const ENGINE_PACKAGE = "@deftai/directive";
+function normalizePackageManager(value) {
+    const v = value.trim().toLowerCase();
+    if (v.startsWith("pnpm"))
+        return "pnpm";
+    if (v.startsWith("npm"))
+        return "npm";
+    return null;
+}
+/**
+ * Detect the active package manager. Precedence (first match wins):
+ *   1. `DEFT_PACKAGE_MANAGER` env override
+ *   2. `packageManager` field / Corepack shim
+ *   3. `pnpm-lock.yaml` present
+ *   4. `npm_config_user_agent` (set by the manager that spawned the process)
+ *   5. default: npm
+ */
+export function detectPackageManager(input = {}) {
+    const env = input.env ?? {};
+    const override = env.DEFT_PACKAGE_MANAGER;
+    if (typeof override === "string" && override.trim() !== "") {
+        const pm = normalizePackageManager(override);
+        if (pm)
+            return pm;
+    }
+    if (input.packageManagerField != null && input.packageManagerField.trim() !== "") {
+        const pm = normalizePackageManager(input.packageManagerField);
+        if (pm)
+            return pm;
+    }
+    if (input.pnpmLockPresent)
+        return "pnpm";
+    const ua = env.npm_config_user_agent;
+    if (typeof ua === "string" && ua.trim() !== "") {
+        const pm = normalizePackageManager(ua);
+        if (pm)
+            return pm;
+    }
+    return DEFAULT_PACKAGE_MANAGER;
+}
+/**
+ * Render a global install command, e.g. `npm i -g @deftai/directive@0.65.0`
+ * (npm) or `pnpm add -g @deftai/directive@0.65.0` (pnpm). `spec` is the full
+ * package spec including any `@version` suffix.
+ */
+export function renderGlobalInstall(pm, spec = ENGINE_PACKAGE) {
+    return pm === "pnpm" ? `pnpm add -g ${spec}` : `npm i -g ${spec}`;
+}
+/**
+ * Render a project-local (dev-dependency) install command. pnpm-managed repos
+ * that prefer not to install globally use this.
+ */
+export function renderProjectInstall(pm, spec = ENGINE_PACKAGE) {
+    return pm === "pnpm" ? `pnpm add -D ${spec}` : `npm install --save-dev ${spec}`;
+}
+/**
+ * Render an ephemeral (no-install) invocation, e.g. `npx @deftai/directive update`
+ * (npm) or `pnpm dlx @deftai/directive update` (pnpm).
+ */
+export function renderEphemeral(pm, subcommand, pkg = ENGINE_PACKAGE) {
+    const runner = pm === "pnpm" ? "pnpm dlx" : "npx";
+    const tail = subcommand.trim() === "" ? "" : ` ${subcommand.trim()}`;
+    return `${runner} ${pkg}${tail}`;
+}
+/**
+ * Render the full command matrix for a package manager at a given spec
+ * (defaults to `@latest`). Single-sourced so docs, doctor, and the plan all
+ * derive from the same renderers.
+ */
+export function renderPackageManagerCommands(pm, spec = `${ENGINE_PACKAGE}@latest`) {
+    return {
+        packageManager: pm,
+        globalInstall: renderGlobalInstall(pm, spec),
+        projectInstall: renderProjectInstall(pm, spec),
+        ephemeralUpdate: renderEphemeral(pm, "update"),
+        upgradeOneLiner: renderGlobalInstall(pm, `${ENGINE_PACKAGE}@latest`),
+    };
+}
+//# sourceMappingURL=package-manager.js.map

package/dist/resolution/pin.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+/** The canonical committed dependency the pin lives on. */
+export declare const PIN_DEPENDENCY_NAME = "@deftai/directive";
+/** A parsed semver triple (prerelease / build metadata dropped). */
+export type SemverTriple = readonly [number, number, number];
+/** Parse a semver prefix (`major.minor.patch`); null when not exact semver. */
+export declare function parseSemver(version: string | null | undefined): SemverTriple | null;
+/** True when `version` is an EXACT pin (no range operators like `^` / `~` / `*`). */
+export declare function isExactPin(version: string | null | undefined): boolean;
+/** Compare two versions: -1 (a<b), 0 (a==b), 1 (a>b); null when either is unparseable. */
+export declare function compareSemver(a: string | null, b: string | null): -1 | 0 | 1 | null;
+/** True when `a >= b` under semver ordering; false when either is unparseable. */
+export declare function semverGte(a: string | null, b: string | null): boolean;
+export interface PinReadSeams {
+    readonly isFile?: (p: string) => boolean;
+    readonly readText?: (p: string) => string | null;
+}
+export interface PinReadResult {
+    /** Exact pinned version (no `v` prefix), or null when absent / non-exact. */
+    readonly pinVersion: string | null;
+    /** Raw devDependency spec string as written, or null. */
+    readonly rawSpec: string | null;
+    /** `package.json` declares `"private": true`. */
+    readonly isPrivate: boolean;
+    /** The pin spec is present but NOT an exact version (range operator used). */
+    readonly nonExact: boolean;
+}
+/**
+ * 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 declare function readPin(projectRoot: string, seams?: PinReadSeams): PinReadResult;
+export interface ReconcileInputs {
+    /** Canonical pin from `package.json`. */
+    readonly pinVersion: string | null;
+    /** Reachable engine version, or null when unreachable. */
+    readonly engineVersion: string | null;
+    /** `.deft/core/VERSION` content marker, or null. */
+    readonly contentVersion: string | null;
+    /** AGENTS.md managed-section `sha=`, or null. */
+    readonly managedSectionSha: string | null;
+    /** The sha the engine would stamp for the current payload, when known. */
+    readonly expectedManagedSectionSha?: string | null;
+}
+export interface ReconcileResult {
+    /** No mismatches detected against the pin. */
+    readonly consistent: boolean;
+    /** Deposited content (`VERSION`) is behind the pin (needs forward-migration). */
+    readonly contentBehindPin: boolean;
+    /** The managed-section sha is present but disagrees with the expected sha. */
+    readonly managedShaMismatch: boolean;
+    /** Human-facing mismatch reasons (empty when consistent). */
+    readonly mismatches: readonly string[];
+}
+/**
+ * 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 declare function reconcileVersions(inputs: ReconcileInputs): ReconcileResult;
+//# sourceMappingURL=pin.d.ts.map

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