@deftai/directive-core 0.68.0 → 0.69.0

package/dist/init-deposit/init-dispatch.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Universal adoption dispatcher for `directive init` (#2265 / epic #2203).
+ *
+ * `directive init` is the ONE entrypoint a first-time adopter runs regardless of
+ * their directory state. This module classifies the directory via the shared
+ * keystone `classify()`/`plan()` fact-set (#2264, consumed read-only) and
+ * dispatches to exactly one of four paths, always printing a concise state
+ * summary plus exactly one recommended next action:
+ *
+ *   - `scaffold`           — empty greenfield dir; deposit Directive.
+ *   - `brownfield-install` — app code but no Directive deposit; install support
+ *                            beside the app code without disturbing it.
+ *   - `delegate-update`    — already initialized; DELEGATE to `update` with an
+ *                            explicit disclosure line. init never silently
+ *                            refreshes under its own name (the #2199 anti-pattern)
+ *                            and never re-scaffolds an existing install.
+ *   - `route-migrate`      — legacy / pre-cutover layout; route to `migrate`.
+ *
+ * Logic is single-sourced: each delegate branch CALLS the existing narrow verb
+ * (`runInitDepositCli` / `runRefreshDepositCli` / `runMigrateCli`) — the
+ * dispatcher never re-implements deposit, refresh, or migrate behavior.
+ */
+import type { ResolutionFacts, ResolutionPlan } from "@deftai/directive-types";
+import { type ClassifySeams } from "../resolution/index.js";
+import { type RunInitDepositCliOptions } from "./init-deposit.js";
+import { type RunMigrateCliOptions } from "./migrate.js";
+import { type RunRefreshDepositCliOptions } from "./refresh.js";
+import type { InitDepositIo } from "./scaffold.js";
+/** The four adoption paths `directive init` dispatches into. */
+export type InitDispatchDecision = "scaffold" | "brownfield-install" | "delegate-update" | "route-migrate";
+/** Human-readable state label per decision, used in the printed summary. */
+export declare const INIT_DISPATCH_STATE_LABEL: Record<InitDispatchDecision, string>;
+/**
+ * Explicit disclosure printed BEFORE delegating an already-initialized project
+ * to `update`. Its presence is what keeps `init` from silently masquerading as
+ * `update` (the #2199 anti-pattern): the user always sees that init delegated.
+ */
+export declare const UPDATE_DELEGATION_DISCLOSURE = "Existing install detected \u2014 refreshing via `update` (init delegates to update; it does not re-scaffold).";
+/**
+ * Collapse the shared resolution {@link ResolutionPlan} + fact-set onto one of
+ * the four init dispatch decisions. There is no second classifier: `plan.mode`
+ * is the single source of truth, and the empty-vs-brownfield split reads the
+ * `hasAppCode`/`hasGit` facts already produced by `classify()`.
+ */
+export declare function decideInitDispatch(facts: ResolutionFacts, resolutionPlan: ResolutionPlan): InitDispatchDecision;
+export interface InitDispatchClassification {
+    readonly decision: InitDispatchDecision;
+    readonly plan: ResolutionPlan;
+    readonly facts: ResolutionFacts;
+}
+/**
+ * Run the up-front dispatch classifier. Reuses the keystone `classify()`
+ * fact-set + `plan()` precedence table — no second classifier lives here.
+ */
+export declare function classifyInitDispatch(projectDir: string, classifySeams?: ClassifySeams): InitDispatchClassification;
+/** The single recommended next-action line for a decision. */
+export declare function initDispatchNextAction(decision: InitDispatchDecision, resolutionPlan: ResolutionPlan): string;
+/** Print the concise state summary + exactly one recommended next action. */
+export declare function printInitDispatchSummary(io: InitDepositIo, decision: InitDispatchDecision, resolutionPlan: ResolutionPlan): void;
+/** Machine-readable payload emitted for `--dry-run`/`--plan` (no execution). */
+export declare function buildInitDispatchDryRunJson(projectDir: string, classification: InitDispatchClassification): Record<string, unknown>;
+/**
+ * Injectable delegate seams. Defaults are the real narrow-verb CLIs; tests
+ * inject fakes to assert single-sourced delegation without touching the fs.
+ */
+export interface InitDispatchSeams {
+    readonly classifySeams?: ClassifySeams;
+    readonly runScaffold?: (options: RunInitDepositCliOptions) => Promise<number>;
+    readonly runRefresh?: (options: RunRefreshDepositCliOptions) => Promise<number>;
+    readonly runMigrate?: (options: RunMigrateCliOptions) => number;
+}
+export interface RunInitDispatchCliOptions {
+    readonly projectDir: string;
+    readonly jsonOut: boolean;
+    readonly nonInteractive: boolean;
+    /** `--dry-run`/`--plan`: print the classified plan without executing. */
+    readonly dryRun: boolean;
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: InitDispatchSeams;
+}
+/**
+ * CLI-facing entrypoint for `directive init`. Classifies, prints a state summary
+ * + one next action, then either stops (`--dry-run`) or delegates to the narrow
+ * verb for the resolved decision. The summary/disclosure use the `printf`
+ * channel (stderr under `--json`) so that in JSON mode stdout stays a SINGLE
+ * JSON object — the delegate's result, or the dry-run plan.
+ */
+export declare function runInitDispatchCli(options: RunInitDispatchCliOptions): Promise<number>;
+//# sourceMappingURL=init-dispatch.d.ts.map

package/dist/init-deposit/init-dispatch.js

@@ -0,0 +1,170 @@
+/**
+ * Universal adoption dispatcher for `directive init` (#2265 / epic #2203).
+ *
+ * `directive init` is the ONE entrypoint a first-time adopter runs regardless of
+ * their directory state. This module classifies the directory via the shared
+ * keystone `classify()`/`plan()` fact-set (#2264, consumed read-only) and
+ * dispatches to exactly one of four paths, always printing a concise state
+ * summary plus exactly one recommended next action:
+ *
+ *   - `scaffold`           — empty greenfield dir; deposit Directive.
+ *   - `brownfield-install` — app code but no Directive deposit; install support
+ *                            beside the app code without disturbing it.
+ *   - `delegate-update`    — already initialized; DELEGATE to `update` with an
+ *                            explicit disclosure line. init never silently
+ *                            refreshes under its own name (the #2199 anti-pattern)
+ *                            and never re-scaffolds an existing install.
+ *   - `route-migrate`      — legacy / pre-cutover layout; route to `migrate`.
+ *
+ * Logic is single-sourced: each delegate branch CALLS the existing narrow verb
+ * (`runInitDepositCli` / `runRefreshDepositCli` / `runMigrateCli`) — the
+ * dispatcher never re-implements deposit, refresh, or migrate behavior.
+ */
+import { resolve } from "node:path";
+import { classify, plan } from "../resolution/index.js";
+import { runInitDepositCli } from "./init-deposit.js";
+import { runMigrateCli } from "./migrate.js";
+import { runRefreshDepositCli } from "./refresh.js";
+/** Human-readable state label per decision, used in the printed summary. */
+export const INIT_DISPATCH_STATE_LABEL = {
+    scaffold: "empty directory (greenfield)",
+    "brownfield-install": "brownfield project (app code, no Directive deposit)",
+    "delegate-update": "already initialized",
+    "route-migrate": "legacy / pre-cutover layout",
+};
+/**
+ * Explicit disclosure printed BEFORE delegating an already-initialized project
+ * to `update`. Its presence is what keeps `init` from silently masquerading as
+ * `update` (the #2199 anti-pattern): the user always sees that init delegated.
+ */
+export const UPDATE_DELEGATION_DISCLOSURE = "Existing install detected — refreshing via `update` (init delegates to update; it does not re-scaffold).";
+/**
+ * Collapse the shared resolution {@link ResolutionPlan} + fact-set onto one of
+ * the four init dispatch decisions. There is no second classifier: `plan.mode`
+ * is the single source of truth, and the empty-vs-brownfield split reads the
+ * `hasAppCode`/`hasGit` facts already produced by `classify()`.
+ */
+export function decideInitDispatch(facts, resolutionPlan) {
+    if (resolutionPlan.mode === "migrate")
+        return "route-migrate";
+    if (resolutionPlan.mode === "init") {
+        return facts.hasAppCode || facts.hasGit ? "brownfield-install" : "scaffold";
+    }
+    // Deposit present (proceed | update | install-* | blocked): the install exists,
+    // so `update` owns the engine/content dimension. init delegates.
+    return "delegate-update";
+}
+/**
+ * Run the up-front dispatch classifier. Reuses the keystone `classify()`
+ * fact-set + `plan()` precedence table — no second classifier lives here.
+ */
+export function classifyInitDispatch(projectDir, classifySeams = {}) {
+    const facts = classify(projectDir, classifySeams);
+    const resolutionPlan = plan(facts, {});
+    return { decision: decideInitDispatch(facts, resolutionPlan), plan: resolutionPlan, facts };
+}
+/** The single recommended next-action line for a decision. */
+export function initDispatchNextAction(decision, resolutionPlan) {
+    switch (decision) {
+        case "scaffold":
+            return "Next: scaffolding a fresh Directive deposit (.deft/core, AGENTS.md managed section, xbrief/ layout).";
+        case "brownfield-install":
+            return "Next: installing Directive support beside your app code (app source is left untouched); then extract a brownfield spec and set up xbrief/.";
+        case "delegate-update":
+            return "Next: refreshing the existing install via `update`.";
+        case "route-migrate":
+            return `Next: routing to \`migrate\`. ${resolutionPlan.nextAction.remediation}`;
+        default: {
+            const exhaustive = decision;
+            throw new Error(`unhandled init dispatch decision: ${String(exhaustive)}`);
+        }
+    }
+}
+/** Print the concise state summary + exactly one recommended next action. */
+export function printInitDispatchSummary(io, decision, resolutionPlan) {
+    io.printf(`\n[directive init] State: ${INIT_DISPATCH_STATE_LABEL[decision]}\n`);
+    io.printf(`[directive init] ${initDispatchNextAction(decision, resolutionPlan)}\n`);
+    for (const warning of resolutionPlan.warnings) {
+        io.printf(`[directive init] Note: ${warning}\n`);
+    }
+}
+/** Machine-readable payload emitted for `--dry-run`/`--plan` (no execution). */
+export function buildInitDispatchDryRunJson(projectDir, classification) {
+    return {
+        success: true,
+        action: "init",
+        dry_run: true,
+        dispatch: classification.decision,
+        mode: classification.plan.mode,
+        project_dir: projectDir,
+        next_action: classification.plan.nextAction,
+        warnings: classification.plan.warnings,
+    };
+}
+/**
+ * CLI-facing entrypoint for `directive init`. Classifies, prints a state summary
+ * + one next action, then either stops (`--dry-run`) or delegates to the narrow
+ * verb for the resolved decision. The summary/disclosure use the `printf`
+ * channel (stderr under `--json`) so that in JSON mode stdout stays a SINGLE
+ * JSON object — the delegate's result, or the dry-run plan.
+ */
+export async function runInitDispatchCli(options) {
+    const projectDir = resolve(options.projectDir);
+    const seams = options.seams ?? {};
+    const io = {
+        printf: (text) => {
+            if (options.jsonOut)
+                options.writeErr(text);
+            else
+                options.writeOut(text);
+        },
+    };
+    const classification = classifyInitDispatch(projectDir, seams.classifySeams ?? {});
+    const { decision, plan: resolutionPlan } = classification;
+    printInitDispatchSummary(io, decision, resolutionPlan);
+    if (options.dryRun) {
+        if (options.jsonOut) {
+            options.writeOut(`${JSON.stringify(buildInitDispatchDryRunJson(projectDir, classification), null, 2)}\n`);
+        }
+        return 0;
+    }
+    switch (decision) {
+        case "scaffold":
+        case "brownfield-install": {
+            const runScaffold = seams.runScaffold ?? runInitDepositCli;
+            return runScaffold({
+                projectDir,
+                jsonOut: options.jsonOut,
+                nonInteractive: options.nonInteractive,
+                writeOut: options.writeOut,
+                writeErr: options.writeErr,
+            });
+        }
+        case "delegate-update": {
+            io.printf(`\n[directive init] ${UPDATE_DELEGATION_DISCLOSURE}\n`);
+            const runRefresh = seams.runRefresh ?? runRefreshDepositCli;
+            return runRefresh({
+                projectDir,
+                jsonOut: options.jsonOut,
+                nonInteractive: options.nonInteractive,
+                upgrade: false,
+                writeOut: options.writeOut,
+                writeErr: options.writeErr,
+            });
+        }
+        case "route-migrate": {
+            const runMigrate = seams.runMigrate ?? runMigrateCli;
+            return runMigrate({
+                projectDir,
+                jsonOut: options.jsonOut,
+                writeOut: options.writeOut,
+                writeErr: options.writeErr,
+            });
+        }
+        default: {
+            const exhaustive = decision;
+            throw new Error(`unhandled init dispatch decision: ${String(exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=init-dispatch.js.map

package/dist/init-deposit/refresh.d.ts

@@ -7,6 +7,9 @@
  *
  * Refs #1942, #1430, #1671.
  */
+import type { ResolutionFacts, ResolutionPlan } from "@deftai/directive-types";
+import { type ClassifySeams, type EngineInstallRunner, type EngineResolution, type LadderFacts, type ReprojectRunner } from "../resolution/index.js";
+import { type GitLsFiles } from "./gitignore.js";
 import { type InitDepositArgs } from "./init-deposit.js";
 import { type LegacyLayoutDetection } from "./legacy-detect.js";
 import { type InitDepositIo } from "./scaffold.js";
@@ -33,18 +36,92 @@ export interface RefreshDepositSeams {
     nowIso?: () => string;
     gitPorcelain?: (projectRoot: string) => string | null;
     detectLegacy?: (projectDir: string) => LegacyLayoutDetection;
+    /**
+     * #2266: `git ls-files` probe threaded into the non-destructive `.gitignore`
+     * upkeep so the refresh never invokes a destructive `git rm --cached` path.
+     */
+    gitLsFiles?: GitLsFiles;
 }
+/**
+ * The four states `directive update` classifies an EXISTING install into BEFORE
+ * any copy (#2266). Derived from the keystone `classify()`/`plan()` spine
+ * (#2264) — there is exactly one classifier in the system; this maps the shared
+ * {@link ResolutionPlan} onto the narrow update-verb contract.
+ *
+ * - `not-initialized`     — no Directive footprint at all; STOP, hint `init`.
+ * - `current`             — initialized and already up to date; refresh is a no-op.
+ * - `updated`             — initialized and the refresh forward-migrates content.
+ * - `migration-required`  — pre-cutover artifacts; `update` is not enough.
+ */
+export type UpdateState = "not-initialized" | "current" | "updated" | "migration-required";
+export interface UpdateClassification {
+    readonly state: UpdateState;
+    readonly plan: ResolutionPlan;
+    readonly facts: ResolutionFacts;
+}
+/** The exact refusal shown when `update` runs against an un-initialized project. */
+export declare const NOT_INITIALIZED_MESSAGE = "This project is not initialized. Run directive init.";
+/** `update` refused because the project has no install / needs a different verb. */
+export declare const UPDATE_REFUSED_EXIT_CODE = 1;
+/**
+ * Collapse the shared resolution {@link ResolutionPlan} onto the four update
+ * states. Pre-cutover wins over everything (migrate before any refresh); a
+ * project with no footprint is not-initialized; an initialized project that the
+ * spine says can `proceed` is already current; everything else (deposit
+ * reconstitution, content behind pin, engine self-heal) is an `updated` refresh.
+ */
+export declare function updateStateFromPlan(facts: ResolutionFacts, resolutionPlan: ResolutionPlan): UpdateState;
+/**
+ * Run the up-front four-state classifier (#2266). Reuses the keystone
+ * `classify()` fact-set + `plan()` precedence table — no second classifier.
+ */
+export declare function classifyUpdateState(projectDir: string, classifySeams?: ClassifySeams): UpdateClassification;
+export interface SelfHealSeams {
+    /** Pre-computed ladder facts; when omitted, cheap local probes build them. */
+    readonly ladderFacts?: LadderFacts;
+    /** Injected side-effecting install runner; when omitted, the install is deferred. */
+    readonly engineInstallRunner?: EngineInstallRunner;
+    /** Injected content re-projection after a fresh install. */
+    readonly reproject?: ReprojectRunner;
+}
+/**
+ * Cheap, non-networked ladder facts for the default self-heal path. The global
+ * engine version is whatever `classify()` already probed; the local sandbox
+ * engine integrity is a filesystem check. `registryUp`/`globalPrefixWritable`
+ * default optimistic so the ladder surfaces the canonical `npm i -g` remediation
+ * when no install runner is wired.
+ */
+export declare function buildDefaultLadderFacts(projectDir: string, facts: ResolutionFacts): LadderFacts;
+/**
+ * Self-heal a mismatched / unreachable engine by DELEGATING to the keystone
+ * global-first ladder (`resolveEngine`, #2264). The refresh's content copy comes
+ * from the resolved content package and does not itself require the engine, so
+ * this is a best-effort heal that prints the ladder trace and remediation; when
+ * a caller wires an install runner, the ladder performs the install with zero
+ * manual npm/PATH steps (#2266 a3).
+ */
+export declare function selfHealEngine(projectDir: string, facts: ResolutionFacts, io: InitDepositIo, seams?: SelfHealSeams): EngineResolution;
 /** Framework-managed uncommitted paths after refresh (#1671). */
 export declare function frameworkRefreshSideEffects(projectDir: string, readPorcelain?: (root: string) => string | null): string[];
 export declare function printRefreshSideEffects(io: InitDepositIo, files: readonly string[]): void;
 export declare function buildVersionSkewNotice(engineVersion: string, contentVersion: string, previousDepositVersion: string | null): string | null;
-export declare function buildUpdateSummaryJson(result: RefreshDepositResult, options: RefreshDepositArgs): Record<string, unknown>;
-export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo): void;
+export declare function buildUpdateSummaryJson(result: RefreshDepositResult, options: RefreshDepositArgs, updateState?: UpdateState): Record<string, unknown>;
+export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo, updateState?: UpdateState): void;
 export declare function runRefreshDeposit(args: RefreshDepositArgs, io: InitDepositIo, seams?: RefreshDepositSeams): Promise<RefreshDepositResult>;
 export interface RunRefreshDepositCliOptions extends RefreshDepositArgs {
     readonly writeOut: (text: string) => void;
     readonly writeErr: (text: string) => void;
     readonly seams?: RefreshDepositSeams;
+    /** #2266: print the classified plan without executing the refresh (`--dry-run`/`--plan`). */
+    readonly dryRun?: boolean;
+    /** #2266: seams for the up-front four-state classifier (default: real fs + engine probe). */
+    readonly classifySeams?: ClassifySeams;
+    /** #2266: pre-computed engine-ladder facts for the self-heal delegation (default: probed). */
+    readonly ladderFacts?: LadderFacts;
+    /** #2266: injected engine install runner for the ladder self-heal (default: deferred). */
+    readonly engineInstallRunner?: EngineInstallRunner;
+    /** #2266: injected content re-projection after a self-heal install. */
+    readonly reproject?: ReprojectRunner;
 }
 /** CLI-facing wrapper: runs refresh, emits JSON or wizard UX, returns exit code. */
 export declare function runRefreshDepositCli(options: RunRefreshDepositCliOptions): Promise<number>;

package/dist/init-deposit/refresh.js

@@ -8,6 +8,7 @@
  * Refs #1942, #1430, #1671.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
@@ -16,12 +17,92 @@ import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.j
 import { readCorePackageVersion } from "../engine-version.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
+import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { gitPorcelain } from "../story-ready/git.js";
+import { ensureInitGitignoreLines } from "./gitignore.js";
 import { depositStagePaths, isInstallerManagedPath, printCommitGuidance } from "./hygiene.js";
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
 import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeInstallManifest, } from "./scaffold.js";
+/** The exact refusal shown when `update` runs against an un-initialized project. */
+export const NOT_INITIALIZED_MESSAGE = "This project is not initialized. Run directive init.";
+/** `update` refused because the project has no install / needs a different verb. */
+export const UPDATE_REFUSED_EXIT_CODE = 1;
+/** A project is initialized when it carries ANY Directive footprint. */
+function isInitialized(facts) {
+    return facts.hasDeftCore || facts.hasManagedSection || facts.pinVersion !== null;
+}
+/**
+ * Collapse the shared resolution {@link ResolutionPlan} onto the four update
+ * states. Pre-cutover wins over everything (migrate before any refresh); a
+ * project with no footprint is not-initialized; an initialized project that the
+ * spine says can `proceed` is already current; everything else (deposit
+ * reconstitution, content behind pin, engine self-heal) is an `updated` refresh.
+ */
+export function updateStateFromPlan(facts, resolutionPlan) {
+    if (resolutionPlan.mode === "migrate")
+        return "migration-required";
+    if (!isInitialized(facts))
+        return "not-initialized";
+    if (resolutionPlan.mode === "proceed")
+        return "current";
+    return "updated";
+}
+/**
+ * Run the up-front four-state classifier (#2266). Reuses the keystone
+ * `classify()` fact-set + `plan()` precedence table — no second classifier.
+ */
+export function classifyUpdateState(projectDir, classifySeams = {}) {
+    const facts = classify(projectDir, classifySeams);
+    const resolutionPlan = plan(facts, {});
+    return { state: updateStateFromPlan(facts, resolutionPlan), plan: resolutionPlan, facts };
+}
+/**
+ * Cheap, non-networked ladder facts for the default self-heal path. The global
+ * engine version is whatever `classify()` already probed; the local sandbox
+ * engine integrity is a filesystem check. `registryUp`/`globalPrefixWritable`
+ * default optimistic so the ladder surfaces the canonical `npm i -g` remediation
+ * when no install runner is wired.
+ */
+export function buildDefaultLadderFacts(projectDir, facts) {
+    const integrity = checkLocalEngineIntegrity(projectDir);
+    return {
+        pinVersion: facts.pinVersion,
+        globalEngineVersion: facts.engineReachable ? facts.engineVersion : null,
+        localEngine: integrity.present ? { version: null, integrity } : null,
+        registryUp: true,
+        globalPrefixWritable: true,
+        stagedTarballAvailable: false,
+        platform: osPlatform(),
+    };
+}
+/**
+ * Self-heal a mismatched / unreachable engine by DELEGATING to the keystone
+ * global-first ladder (`resolveEngine`, #2264). The refresh's content copy comes
+ * from the resolved content package and does not itself require the engine, so
+ * this is a best-effort heal that prints the ladder trace and remediation; when
+ * a caller wires an install runner, the ladder performs the install with zero
+ * manual npm/PATH steps (#2266 a3).
+ */
+export function selfHealEngine(projectDir, facts, io, seams = {}) {
+    const ladderFacts = seams.ladderFacts ?? buildDefaultLadderFacts(projectDir, facts);
+    const resolution = resolveEngine(ladderFacts, {
+        installRunner: seams.engineInstallRunner,
+        reproject: seams.reproject,
+    });
+    io.printf(`\n[deft update] engine self-heal (global-first ladder): ${resolution.trace}\n`);
+    if (!resolution.selfHealed && !resolution.decision.usable) {
+        io.printf(`[deft update] ${resolution.decision.reason}\n`);
+        if (resolution.decision.rung === "install-global") {
+            const suffix = facts.pinVersion ? `@${facts.pinVersion}` : "";
+            const spec = `${ENGINE_PACKAGE}${suffix}`;
+            io.printf(`  Remediation: ${renderGlobalInstall("npm", spec)}\n`);
+            io.printf(`               (pnpm: ${renderGlobalInstall("pnpm", spec)})\n`);
+        }
+    }
+    return resolution;
+}
 function normalizeVersion(version) {
     return version.trim().replace(/^v/, "");
 }
@@ -199,10 +280,11 @@ export function buildVersionSkewNotice(engineVersion, contentVersion, previousDe
     }
     return null;
 }
-export function buildUpdateSummaryJson(result, options) {
+export function buildUpdateSummaryJson(result, options, updateState) {
     return {
         success: true,
         action: "upgrade",
+        ...(updateState ? { update_state: updateState } : {}),
         version: result.engineVersion,
         project_dir: result.projectDir,
         deft_dir: result.deftDir,
@@ -229,10 +311,13 @@ export function buildUpdateSummaryJson(result, options) {
         agents_md_updated: result.agentsMdUpdated,
     };
 }
-export function printUpdateComplete(result, io) {
+export function printUpdateComplete(result, io, updateState) {
     io.printf("\n✓ Deft framework payload refreshed.\n\n");
     io.printf(`  Location     : ${result.deftDir}\n`);
     io.printf(`  Content      : v${normalizeVersion(result.contentVersion)}\n`);
+    if (updateState) {
+        io.printf(`  State        : ${updateState}\n`);
+    }
     io.printf(`  AGENTS.md    : ${result.agentsMdUpdated ? "updated" : "already current"}\n`);
     if (result.versionSkewNotice) {
         io.printf(`\n${result.versionSkewNotice}\n`);
@@ -283,6 +368,12 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     syncBareVersionMarker(projectDir, contentVersion);
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
     await depositNeutralization(projectDir, io);
+    // #2266: non-destructive `.gitignore` upkeep for framework-owned paths. This
+    // NEVER un-tracks a committed deposit -- `ensureInitGitignoreLines` only writes
+    // `.gitignore` and leaves an already-tracked `.deft/core` tracked. The
+    // destructive `git rm --cached .deft/core` un-track is the deliberate
+    // `migrate --untrack-core` step (#2269), not `update`.
+    ensureInitGitignoreLines(projectDir, io, { gitLsFiles: seams.gitLsFiles });
     let taskfileWired = false;
     if (args.nonInteractive) {
         taskfileWired = ensureTaskfile(projectDir, io);
@@ -309,6 +400,59 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         stagedPaths,
     };
 }
+function buildRefusalJson(state, projectDir, message, command) {
+    return {
+        success: false,
+        action: "update",
+        update_state: state,
+        project_dir: projectDir,
+        message,
+        next_action: { command },
+    };
+}
+/** Emit the `not-initialized` refusal: STOP, hint `init`, never write a partial install. */
+function emitNotInitialized(options, io, projectDir) {
+    io.printf(`${NOT_INITIALIZED_MESSAGE}\n`);
+    if (options.jsonOut) {
+        options.writeOut(`${JSON.stringify(buildRefusalJson("not-initialized", projectDir, NOT_INITIALIZED_MESSAGE, "directive init"), null, 2)}\n`);
+    }
+    return UPDATE_REFUSED_EXIT_CODE;
+}
+/** Emit the `migration-required` refusal: `update` is not enough; point at init/migrate. */
+function emitMigrationRequired(options, io, projectDir, classification) {
+    const remediation = classification.plan.nextAction.remediation;
+    const message = `directive update: this project requires migration before it can be refreshed. ${remediation}`;
+    io.printf(`${message}\n`);
+    if (options.jsonOut) {
+        options.writeOut(`${JSON.stringify(buildRefusalJson("migration-required", projectDir, message, classification.plan.nextAction.command ?? "directive init"), null, 2)}\n`);
+    }
+    return UPDATE_REFUSED_EXIT_CODE;
+}
+/** Emit the classified plan for `--dry-run`/`--plan` without executing the refresh. */
+function emitDryRunPlan(options, io, projectDir, classification) {
+    const { state, plan: resolutionPlan } = classification;
+    io.printf(`\n[deft update] dry-run -- classified plan (no changes written):\n`);
+    io.printf(`  State        : ${state}\n`);
+    io.printf(`  Mode         : ${resolutionPlan.mode}\n`);
+    io.printf(`  Root cause   : ${resolutionPlan.nextAction.rootCause}\n`);
+    io.printf(`  Remediation  : ${resolutionPlan.nextAction.remediation}\n`);
+    for (const warning of resolutionPlan.warnings) {
+        io.printf(`  Warning      : ${warning}\n`);
+    }
+    if (options.jsonOut) {
+        options.writeOut(`${JSON.stringify({
+            success: true,
+            action: "update",
+            dry_run: true,
+            update_state: state,
+            mode: resolutionPlan.mode,
+            project_dir: projectDir,
+            next_action: resolutionPlan.nextAction,
+            warnings: resolutionPlan.warnings,
+        }, null, 2)}\n`);
+    }
+    return 0;
+}
 /** CLI-facing wrapper: runs refresh, emits JSON or wizard UX, returns exit code. */
 export async function runRefreshDepositCli(options) {
     const io = {
@@ -321,14 +465,42 @@ export async function runRefreshDepositCli(options) {
             }
         },
     };
+    // #2266: classify up front (BEFORE any copy) and gate on the four states.
+    // Legacy layouts keep their existing refusal path (thrown by runRefreshDeposit
+    // and handled below), so classification is skipped for them.
+    const projectDir = resolve(options.projectDir);
+    const detectLegacy = options.seams?.detectLegacy ?? detectLegacyLayout;
+    let classification = null;
+    if (!detectLegacy(projectDir).legacy) {
+        classification = classifyUpdateState(projectDir, options.classifySeams ?? {});
+        if (classification.state === "not-initialized") {
+            return emitNotInitialized(options, io, projectDir);
+        }
+        if (classification.state === "migration-required") {
+            return emitMigrationRequired(options, io, projectDir, classification);
+        }
+        if (options.dryRun) {
+            return emitDryRunPlan(options, io, projectDir, classification);
+        }
+        // #2266 a3: self-heal a mismatched / unreachable engine via the keystone
+        // global-first ladder before the refresh proceeds.
+        if (!classification.facts.engineReachable) {
+            selfHealEngine(projectDir, classification.facts, io, {
+                ladderFacts: options.ladderFacts,
+                engineInstallRunner: options.engineInstallRunner,
+                reproject: options.reproject,
+            });
+        }
+    }
     try {
         const result = await runRefreshDeposit(options, io, options.seams);
+        const state = classification?.state;
         if (options.jsonOut) {
-            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson(result, options), null, 2)}\n`);
-            printUpdateComplete(result, { printf: options.writeErr });
+            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson(result, options, state), null, 2)}\n`);
+            printUpdateComplete(result, { printf: options.writeErr }, state);
         }
         else {
-            printUpdateComplete(result, io);
+            printUpdateComplete(result, io, state);
         }
         return 0;
     }

package/dist/init-deposit/scaffold.d.ts

@@ -27,6 +27,31 @@ export interface InstallManifestFields {
 }
 export declare function buildInstallManifestText(fields: InstallManifestFields): string;
 export declare function writeInstallManifest(projectDir: string, deftDir: string, fields: InstallManifestFields): string;
+/** Canonical committed pin dependency name (mirrors resolution/pin.ts). */
+export declare const PIN_DEPENDENCY_NAME = "@deftai/directive";
+export interface EnsurePackageJsonPinResult {
+    readonly changed: boolean;
+    /** Exact version written to the devDependency pin. */
+    readonly pinVersion: string;
+    /** A fresh package.json was created (vs. an existing one updated). */
+    readonly created: boolean;
+}
+/**
+ * Write the committed `package.json` version pin on `@deftai/directive`
+ * (exact devDependency; `"private": true` preserved) so the resolution spine
+ * has a canonical, npm-native pin to read before directive runs. This unblocks
+ * #2269 (which is gated on the pin existing).
+ *
+ * Behavior:
+ *  - existing `package.json`  -> the exact devDependency pin is set/updated;
+ *    an existing `"private"` value is preserved verbatim (never clobbered).
+ *  - absent `package.json`    -> a minimal `{ "private": true, ... }` is created.
+ *  - idempotent               -> re-running with the same pin makes no change.
+ *
+ * This is a deposit primitive; wiring it into the `init` verb flow is owned by
+ * #2265 (the init-consumes-plan child), per the #2264 scope guard.
+ */
+export declare function ensurePackageJsonPin(projectDir: string, version: string, io: InitDepositIo): EnsurePackageJsonPinResult;
 export declare function writeAgentsMd(projectDir: string, deftDir: string, io: InitDepositIo): boolean;
 export declare function writeConsumerVbrief(projectDir: string, deftDir: string, io: InitDepositIo): Promise<boolean>;
 export declare function writeAgentsSkills(projectDir: string, io: InitDepositIo): boolean;