@deftai/directive-core 0.68.0 → 0.69.0

package/dist/doctor/constants.d.ts

@@ -1,3 +1,4 @@
+import { type PackageManager } from "../resolution/package-manager.js";
 export declare const UV_INSTALL_URL = "https://docs.astral.sh/uv/";
 export declare const UPGRADING_DOC_URL = "https://github.com/deftai/directive/blob/master/content/UPGRADING.md";
 export declare const GO_BRIDGE_RELEASES_URL = "https://github.com/deftai/directive/releases";
@@ -18,6 +19,14 @@ export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/ag
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export declare const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+/**
+ * Render the canonical upgrade one-liner for the active package manager (#2197).
+ * Defaults to npm (`CANONICAL_UPGRADE_COMMAND`) so existing callers are
+ * unchanged; pass `pnpm` to emit the pnpm form
+ * (`pnpm add -g @deftai/directive@latest`). Consumed by the doctor
+ * payload-staleness recommendation (`payload-staleness.ts`).
+ */
+export declare function upgradeCommandFor(pm?: PackageManager): string;
 /** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
 export declare const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest && deft update";
 export declare const CLEAN_WINDOW_HOURS = 24;

package/dist/doctor/constants.js

@@ -1,3 +1,4 @@
+import { ENGINE_PACKAGE, renderGlobalInstall, } from "../resolution/package-manager.js";
 export const UV_INSTALL_URL = "https://docs.astral.sh/uv/";
 // Stable, version-neutral upgrade signposts (#1912). Core principle: never bake
 // the upgrade command/version into the artifact being upgraded -- bake in a
@@ -60,6 +61,16 @@ export const DEFT_REPO_POSITIVE_MARKERS = [
 export const EXPECTED_CONTENT_DIRS = ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+/**
+ * Render the canonical upgrade one-liner for the active package manager (#2197).
+ * Defaults to npm (`CANONICAL_UPGRADE_COMMAND`) so existing callers are
+ * unchanged; pass `pnpm` to emit the pnpm form
+ * (`pnpm add -g @deftai/directive@latest`). Consumed by the doctor
+ * payload-staleness recommendation (`payload-staleness.ts`).
+ */
+export function upgradeCommandFor(pm = "npm") {
+    return renderGlobalInstall(pm, `${ENGINE_PACKAGE}@latest`);
+}
 /** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
 export const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = `${CANONICAL_UPGRADE_COMMAND} && deft update`;
 export const CLEAN_WINDOW_HOURS = 24;

package/dist/doctor/main.d.ts

@@ -1,3 +1,49 @@
-import type { DoctorSeams } from "./types.js";
+import { type ResolutionFacts } from "../resolution/index.js";
+import { createPlainSink } from "./output.js";
+import type { DoctorSeams, Finding, ResolutionSummary } from "./types.js";
 export declare function cmdDoctor(args: readonly string[], seams?: DoctorSeams): number;
+/**
+ * Never emit a bare `task ...` remediation in a project without Taskfile wiring
+ * (#2267). The `directive` surface always works; `task deft:X` is optional and
+ * only present when the consumer wired the include. `plan()` already emits the
+ * `directive` / `npx` / `npm` surface, so this guard is a defensive invariant:
+ * any `task`-prefixed command is rewritten to the `directive` surface unless the
+ * project actually has the include.
+ */
+/**
+ * Detect Taskfile wiring through the injected seam (#2267). Mirrors
+ * `classifyTaskfileInclude` but routes the filesystem read through
+ * `seams.readText` so the resolution decision stays deterministic + injectable
+ * in tests -- unlike a direct `classifyTaskfileInclude(projectRoot)` call, which
+ * bypasses every other seam-flowed probe in `runResolutionDecision`.
+ */
+export declare function resolveTaskfileWiring(projectRoot: string, seams: DoctorSeams): boolean;
+export declare function enforceDirectiveSurface(command: string | null, hasTaskfileWiring: boolean): string | null;
+/** Human-facing operating mode derived from the orthogonal fact-set. */
+export declare function resolveOperatingMode(facts: ResolutionFacts): string;
+/**
+ * Single engine/pin/VERSION reconciliation line. `reconcileVersions` flags
+ * content-behind/ahead and engine-behind; engine-ahead skew is folded in here so
+ * the line is the one version-state summary the operator reads.
+ */
+export declare function resolveReconciliationLine(facts: ResolutionFacts): string;
+/**
+ * Probe `.deft/.cli/<platform>` across platforms and report presence + skew. A
+ * partial install, or a mix of present + absent platforms, is engine skew: a
+ * gate can pass on one platform and fail on another. Read-only.
+ */
+export declare function resolvePlatformSkew(projectRoot: string, seams: DoctorSeams): {
+    line: string;
+    skewDetected: boolean;
+    findings: Finding[];
+};
+/**
+ * The single read-only decision surface (#2267). Reuses the shared keystone
+ * `classify()` + `plan()` (the ONE classifier) to emit the operating mode, the
+ * engine/pin/VERSION reconciliation, cross-platform skew, and exactly ONE
+ * primary `Next command:` with a root-cause + remediation rationale. Secondary
+ * migration advice (`plan()` warnings) is suppressed until the primary blocker
+ * clears. Mutates nothing.
+ */
+export declare function runResolutionDecision(projectRoot: string, jsonMode: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (f: Finding) => void, seams: DoctorSeams): ResolutionSummary;
 //# sourceMappingURL=main.d.ts.map

package/dist/doctor/main.js

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
 import { contentRoot } from "../content-root.js";
+import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
+import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
 import { runChecks } from "./checks.js";
 import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
@@ -10,11 +12,33 @@ import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } fro
 import { pythonJsonDump } from "./json.js";
 import { parseInstallRootFromAgentsMd } from "./manifest.js";
 import { createPlainSink } from "./output.js";
-import { resolveDefaultFrameworkRoot, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
+import { readTextSafe, resolveDefaultFrameworkRoot, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
 import { runPayloadStalenessCheck } from "./payload-staleness.js";
 import { runLocalSignpostChecks } from "./signpost-checks.js";
-import { classifyTaskfileInclude, formatMissingIncludeSnippet, resolveConsumerTaskfile, } from "./taskfile.js";
+import { classifyTaskfileInclude, formatMissingIncludeSnippet, includesBlockHasDeftTaskfile, resolveConsumerTaskfile, } from "./taskfile.js";
 import { defaultWhich } from "./which.js";
+const DEFAULT_RESOLUTION_PLATFORMS = ["linux", "darwin", "win32"];
+/**
+ * Read the `packageManager` field (Corepack) from a project package.json, or
+ * null when absent/unreadable. Lets the doctor detect a pnpm project that has
+ * no `pnpm-lock.yaml` yet (fresh Corepack clone) for the #2197 upgrade hint.
+ */
+function readPackageManagerField(packageJsonPath, readTextFn) {
+    const raw = readTextFn(packageJsonPath);
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const field = parsed.packageManager;
+            return typeof field === "string" ? field : null;
+        }
+    }
+    catch {
+        // Malformed package.json -- fall through to null (npm default).
+    }
+    return null;
+}
 export function cmdDoctor(args, seams = {}) {
     const flags = parseDoctorFlags(args);
     if (flags.unknown.length > 0) {
@@ -145,12 +169,27 @@ export function cmdDoctor(args, seams = {}) {
     if (flags.network) {
         sink.info(NETWORK_DISCLOSURE_LINE);
         sink.info("Checking payload staleness from install manifest...");
+        // Detect the package manager for the upgrade recommendation from signals
+        // that are meaningful for a globally-installed CLI: the explicit
+        // DEFT_PACKAGE_MANAGER override, the project's `packageManager` field
+        // (Corepack), and the project's pnpm-lock.yaml. We deliberately do NOT
+        // consult the ambient npm_config_user_agent here (it is set by whatever
+        // shell/script spawned the process, not by the consumer's project) so the
+        // recommendation is a stable property of the project (#2197).
+        const readTextForPm = seams.readText ?? readTextSafe;
+        const isFileForPm = seams.isFile ?? ((p) => existsSync(p));
+        const packageManager = detectPackageManager({
+            env: { DEFT_PACKAGE_MANAGER: process.env.DEFT_PACKAGE_MANAGER },
+            packageManagerField: readPackageManagerField(join(projectRoot, "package.json"), readTextForPm),
+            pnpmLockPresent: isFileForPm(join(projectRoot, "pnpm-lock.yaml")),
+        });
         runPayloadStalenessCheck(projectRoot, sink, addFinding, {
             frameworkRoot,
             readText: seams.readText,
             isFile: seams.isFile,
             runGitLsRemote: seams.runGitLsRemote,
             runNpmViewVersion: seams.runNpmViewVersion,
+            packageManager,
         });
     }
     else {
@@ -213,8 +252,21 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
+    sink.info("Checking USER.md resolution...");
+    const userMd = runUserMdResolutionCheck(projectRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
     sink.info("Checking optional root Taskfile.yml include...");
     runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams);
+    let resolution = null;
+    if (!runningInsideDeftRepo(projectRoot, seams)) {
+        if (!jsonMode) {
+            sink.blank();
+            sink.info("Resolution -- operating mode + single next action (from shared plan())...");
+        }
+        resolution = runResolutionDecision(projectRoot, jsonMode, sink, addFinding, seams);
+    }
     const errorCount = findings.filter((f) => f.severity === "error").length;
     const warningCount = findings.filter((f) => f.severity === "warning").length;
     const exitCode = errorCount > 0 ? 1 : 0;
@@ -232,6 +284,28 @@ export function cmdDoctor(args, seams = {}) {
             findings,
             summary: { errors: errorCount, warnings: warningCount },
             project_root: projectRoot,
+            user_md: {
+                path: userMd.path,
+                rung: userMd.rung,
+                found: userMd.found,
+                diagnostic: userMd.diagnostic,
+            },
+            ...(resolution
+                ? {
+                    resolution: {
+                        mode: resolution.mode,
+                        operating_mode: resolution.operatingMode,
+                        reconciliation: resolution.reconciliation,
+                        platform_skew: resolution.platformSkew,
+                        platform_skew_detected: resolution.platformSkewDetected,
+                        action_required: resolution.actionRequired,
+                        next_command: resolution.nextCommand,
+                        root_cause: resolution.rootCause,
+                        remediation: resolution.remediation,
+                        warnings: resolution.warnings,
+                    },
+                }
+                : {}),
         };
         process.stdout.write(`${pythonJsonDump(payload)}\n`);
         return exitCode;
@@ -513,4 +587,280 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
         file: taskfilePath,
     });
 }
+/**
+ * Surface the resolved USER.md path + which search rung matched (#2271) so the
+ * resolution boundary is visible in doctor output. Uses the shared first-hit-
+ * wins resolver, which never throws: an absent USER.md degrades to a `no
+ * USER.md found; using defaults` diagnostic. This check never fails the doctor
+ * — it emits a `skip`-severity finding (informational) in both states.
+ */
+function runUserMdResolutionCheck(projectRoot, sink, addFinding, seams) {
+    const resolveFn = seams.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
+    const result = resolveFn(projectRoot);
+    // Sanitize newlines on the data-derived path/diagnostic before it lands in a
+    // rendered bullet (CWE-116).
+    const safePath = result.path.replace(/\r?\n/g, " ");
+    const safeDiagnostic = result.diagnostic.replace(/\r?\n/g, " ");
+    if (result.found) {
+        sink.success(`USER.md resolved (${result.rung}): ${safePath}`);
+    }
+    else {
+        sink.info(`USER.md: ${safeDiagnostic}`);
+    }
+    addFinding({
+        severity: "skip",
+        message: result.found ? `USER.md resolved (${result.rung}): ${safePath}` : safeDiagnostic,
+        check: "user-md-resolution",
+        status: result.found ? "resolved" : "defaulted",
+        path: safePath,
+        rung: result.rung,
+        found: result.found,
+    });
+    return result;
+}
+/**
+ * Never emit a bare `task ...` remediation in a project without Taskfile wiring
+ * (#2267). The `directive` surface always works; `task deft:X` is optional and
+ * only present when the consumer wired the include. `plan()` already emits the
+ * `directive` / `npx` / `npm` surface, so this guard is a defensive invariant:
+ * any `task`-prefixed command is rewritten to the `directive` surface unless the
+ * project actually has the include.
+ */
+/**
+ * Detect Taskfile wiring through the injected seam (#2267). Mirrors
+ * `classifyTaskfileInclude` but routes the filesystem read through
+ * `seams.readText` so the resolution decision stays deterministic + injectable
+ * in tests -- unlike a direct `classifyTaskfileInclude(projectRoot)` call, which
+ * bypasses every other seam-flowed probe in `runResolutionDecision`.
+ */
+export function resolveTaskfileWiring(projectRoot, seams) {
+    const readText = seams.readText ??
+        ((path) => {
+            try {
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        });
+    for (const name of ["Taskfile.yml", "Taskfile.yaml"]) {
+        const text = readText(join(projectRoot, name));
+        if (text !== null) {
+            return includesBlockHasDeftTaskfile(text.replace(/^\uFEFF/, ""));
+        }
+    }
+    return false;
+}
+export function enforceDirectiveSurface(command, hasTaskfileWiring) {
+    if (command === null) {
+        return null;
+    }
+    if (!hasTaskfileWiring && /^\s*task\s+/.test(command)) {
+        return command.replace(/^\s*task\s+/, "directive ");
+    }
+    return command;
+}
+/** Human-facing operating mode derived from the orthogonal fact-set. */
+export function resolveOperatingMode(facts) {
+    if (facts.preCutoverArtifacts) {
+        return "pre-cutover (pre-v0.20 document model -- migrate first)";
+    }
+    if (!facts.hasDeftCore) {
+        if (facts.hasManagedSection) {
+            return "hybrid (managed AGENTS.md present; .deft/core/ payload not reconstituted)";
+        }
+        return facts.hasAppCode || facts.hasGit
+            ? "brownfield (existing project, no Deft deposit)"
+            : "greenfield (no Deft deposit)";
+    }
+    return facts.hasManagedSection
+        ? "hybrid (vendored .deft/core/ + managed AGENTS.md)"
+        : "vendored (.deft/core/ deposit, no managed AGENTS.md section)";
+}
+/**
+ * Single engine/pin/VERSION reconciliation line. `reconcileVersions` flags
+ * content-behind/ahead and engine-behind; engine-ahead skew is folded in here so
+ * the line is the one version-state summary the operator reads.
+ */
+export function resolveReconciliationLine(facts) {
+    const engine = facts.engineVersion ?? "unreachable";
+    const content = facts.deftCorePayloadVersion ?? "none";
+    const pin = facts.pinVersion ?? "none";
+    const recon = reconcileVersions({
+        pinVersion: facts.pinVersion,
+        engineVersion: facts.engineVersion,
+        contentVersion: facts.deftCorePayloadVersion,
+        managedSectionSha: facts.managedSectionSha,
+    });
+    const notes = [...recon.mismatches];
+    if (facts.engineVersion !== null && facts.pinVersion !== null) {
+        const skew = evaluateSkew(facts.engineVersion, facts.pinVersion, {});
+        if (skew.band === "within-window" || skew.band === "beyond-window") {
+            notes.push(skew.message ?? `engine ${facts.engineVersion} ahead of pin ${facts.pinVersion}`);
+        }
+    }
+    // Without a committed pin there is nothing to reconcile against, so never
+    // claim "aligned" — that would contradict a Next command that tells the
+    // operator to init / commit a pin (Greptile #2283 display-accuracy).
+    let rawVerdict;
+    if (facts.pinVersion === null) {
+        rawVerdict =
+            facts.engineVersion === null && facts.deftCorePayloadVersion === null
+                ? "nothing to reconcile yet (no engine, pin, or deposited content)"
+                : "no committed package.json pin to reconcile against";
+    }
+    else {
+        rawVerdict = notes.length === 0 ? "current (engine/pin/content aligned)" : notes.join("; ");
+    }
+    // Sanitize newlines so a data-derived version/mismatch string can't break out
+    // of the rendered bullet (CWE-116).
+    const verdict = rawVerdict.replace(/\r?\n/g, " ");
+    return `engine ${engine}, content ${content}, pin ${pin} -- ${verdict}`;
+}
+/**
+ * Probe `.deft/.cli/<platform>` across platforms and report presence + skew. A
+ * partial install, or a mix of present + absent platforms, is engine skew: a
+ * gate can pass on one platform and fail on another. Read-only.
+ */
+export function resolvePlatformSkew(projectRoot, seams) {
+    const platforms = seams.resolutionPlatforms ?? DEFAULT_RESOLUTION_PLATFORMS;
+    const isFile = seams.isFile ?? ((p) => existsSync(p));
+    const isDir = seams.isDir ??
+        ((p) => {
+            try {
+                return statSync(p).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    const states = [];
+    let anyPresent = false;
+    let anyAbsent = false;
+    let anyPartial = false;
+    for (const platform of platforms) {
+        const result = checkLocalEngineIntegrity(projectRoot, { platform, isFile, isDir });
+        if (result.usable) {
+            states.push(`${platform} intact`);
+            anyPresent = true;
+        }
+        else if (result.partial) {
+            states.push(`${platform} partial (missing ${result.missingMarkers.join(", ")})`);
+            anyPresent = true;
+            anyPartial = true;
+        }
+        else {
+            states.push(`${platform} absent`);
+            anyAbsent = true;
+        }
+    }
+    const skewDetected = anyPartial || (anyPresent && anyAbsent);
+    const findings = [];
+    if (!anyPresent) {
+        return {
+            line: "no sandbox-local engines (.deft/.cli/<platform> absent on all probed platforms)",
+            skewDetected: false,
+            findings,
+        };
+    }
+    let line = `.deft/.cli -> ${states.join("; ")}`;
+    if (skewDetected) {
+        line += " -- cross-platform engine skew detected";
+        findings.push({
+            severity: "warning",
+            message: `Cross-platform .deft/.cli engine skew: ${states.join("; ")}. A partial or platform-divergent local engine can make gates pass on one platform and fail on another; reconcile with a clean per-platform install.`,
+            check: "resolution:platform-skew",
+            status: "skew",
+            platforms: [...platforms],
+        });
+    }
+    return { line, skewDetected, findings };
+}
+/**
+ * The single read-only decision surface (#2267). Reuses the shared keystone
+ * `classify()` + `plan()` (the ONE classifier) to emit the operating mode, the
+ * engine/pin/VERSION reconciliation, cross-platform skew, and exactly ONE
+ * primary `Next command:` with a root-cause + remediation rationale. Secondary
+ * migration advice (`plan()` warnings) is suppressed until the primary blocker
+ * clears. Mutates nothing.
+ */
+export function runResolutionDecision(projectRoot, jsonMode, sink, addFinding, seams) {
+    const facts = classify(projectRoot, {
+        ...(seams.isFile ? { isFile: seams.isFile } : {}),
+        ...(seams.isDir ? { isDir: seams.isDir } : {}),
+        ...(seams.readText ? { readText: seams.readText } : {}),
+        ...(seams.engineProbe ? { engineProbe: seams.engineProbe } : {}),
+    });
+    const plan = resolvePlan(facts, {}, { platform: process.platform, interactive: false });
+    const operatingMode = resolveOperatingMode(facts);
+    const reconciliation = resolveReconciliationLine(facts);
+    const skew = resolvePlatformSkew(projectRoot, seams);
+    const hasTaskfileWiring = resolveTaskfileWiring(projectRoot, seams);
+    const nextCommand = enforceDirectiveSurface(plan.nextAction.command, hasTaskfileWiring);
+    const actionRequired = plan.mode !== "proceed";
+    // Sanitize newlines on data-derived strings before they land in a rendered
+    // bullet (CWE-116); root cause / remediation can carry version substrings.
+    const rootCauseLine = plan.nextAction.rootCause.replace(/\r?\n/g, " ");
+    const remediationLine = plan.nextAction.remediation.replace(/\r?\n/g, " ");
+    if (!jsonMode) {
+        sink.raw(`Operating mode: ${operatingMode}`);
+        sink.raw(`Version reconciliation: ${reconciliation}`);
+        sink.raw(`Cross-platform engine: ${skew.line}`);
+        if (actionRequired) {
+            sink.blank();
+            sink.warn("Primary next action (resolve this first; secondary migration advice is deferred until it clears):");
+            sink.raw(`  Root cause: ${rootCauseLine}`);
+            sink.raw(nextCommand
+                ? `Next command: ${nextCommand}`
+                : "Next command: (manual -- no single command)");
+            sink.raw(`  Does / why safe: ${remediationLine}`);
+        }
+        else {
+            // Derive the proceed line from plan() so it never over-claims "aligned"
+            // in the no-pin case (Greptile #2283).
+            sink.success(`Resolution: proceed -- ${rootCauseLine}.`);
+            // Only once the primary blocker has cleared do we surface the ordered
+            // secondary notes (legacy vbrief migrate, no-pin advisory, ...).
+            for (const warning of plan.warnings) {
+                sink.info(`note: ${warning.replace(/\r?\n/g, " ")}`);
+            }
+        }
+    }
+    for (const finding of skew.findings) {
+        addFinding(finding);
+    }
+    if (actionRequired) {
+        addFinding({
+            severity: "warning",
+            message: `Next command: ${nextCommand ?? "(manual)"} -- ${rootCauseLine}`,
+            check: "resolution",
+            status: plan.mode,
+            mode: plan.mode,
+            next_command: nextCommand,
+            root_cause: rootCauseLine,
+            remediation: remediationLine,
+            operating_mode: operatingMode,
+        });
+    }
+    else {
+        addFinding({
+            severity: "skip",
+            message: "resolution: proceed -- no primary action required",
+            check: "resolution",
+            status: "proceed",
+        });
+    }
+    return {
+        operatingMode,
+        reconciliation,
+        platformSkew: skew.line,
+        platformSkewDetected: skew.skewDetected,
+        mode: plan.mode,
+        actionRequired,
+        nextCommand,
+        rootCause: plan.nextAction.rootCause,
+        remediation: plan.nextAction.remediation,
+        warnings: plan.warnings,
+    };
+}
 //# sourceMappingURL=main.js.map

package/dist/doctor/payload-staleness.d.ts

@@ -1,3 +1,4 @@
+import type { PackageManager } from "../resolution/package-manager.js";
 import type { OutputSink } from "./output.js";
 import type { Finding } from "./types.js";
 export interface PayloadStalenessSeams {
@@ -12,6 +13,13 @@ export interface PayloadStalenessSeams {
         ok: boolean;
         version: string;
     };
+    /**
+     * Active package manager for rendering the upgrade recommendation (#2197).
+     * Defaults to npm so existing behaviour/tests are unchanged; the doctor entry
+     * detects the manager and threads it here so a pnpm consumer sees the pnpm
+     * upgrade one-liner (`pnpm add -g @deftai/directive@latest`).
+     */
+    readonly packageManager?: PackageManager;
 }
 export declare function runPayloadStalenessCheck(projectRoot: string, sink: OutputSink, addFinding: (finding: Finding) => void, seams?: PayloadStalenessSeams): void;
 //# sourceMappingURL=payload-staleness.d.ts.map

package/dist/doctor/payload-staleness.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { detectCanonicalVendoredManifest, isNpmManaged } from "../init-deposit/migrate.js";
-import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME, VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND, } from "./constants.js";
+import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME, upgradeCommandFor, VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND, } from "./constants.js";
 import { locateManifest, parseInstallManifest } from "./manifest.js";
 import { readTextSafe, resolveDefaultFrameworkRoot } from "./paths.js";
 function isDeftFrameworkRepo(projectRoot, readText = readTextSafe) {
@@ -92,12 +92,14 @@ function emitUnverified(checkName, reason, sink, addFinding) {
         status: "unverified",
     });
 }
-function resolveUpgradeCommand(projectRoot, manifest, isFile) {
-    const vendoredManifest = detectCanonicalVendoredManifest(projectRoot, isFile);
-    if (vendoredManifest !== null && isNpmManaged(manifest)) {
-        return VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND;
-    }
-    return CANONICAL_UPGRADE_COMMAND;
+function resolveUpgradeCommand(projectRoot, manifest, isFile, pm = "npm") {
+    const vendored = detectCanonicalVendoredManifest(projectRoot, isFile) !== null && isNpmManaged(manifest);
+    if (pm === "pnpm") {
+        // Same registry, same tarball -- only the command form differs (#2197).
+        const upgrade = upgradeCommandFor("pnpm");
+        return vendored ? `${upgrade} && deft update` : upgrade;
+    }
+    return vendored ? VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND : CANONICAL_UPGRADE_COMMAND;
 }
 function emitStale(checkName, installedLabel, remoteLabel, ref, upgradeCommand, sink, addFinding, extras = {}, behindWord = "remote") {
     const msg = `Framework payload is stale (installed ${installedLabel} behind ${behindWord} ${remoteLabel} for ref '${ref}'). ` +
@@ -163,7 +165,8 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
         return;
     }
     const manifest = parseInstallManifest(text);
-    const upgradeCommand = resolveUpgradeCommand(projectRoot, manifest, isFile);
+    const activePm = seams.packageManager ?? "npm";
+    const upgradeCommand = resolveUpgradeCommand(projectRoot, manifest, isFile, activePm);
     const installedSha = (manifest.sha ?? "").trim();
     const ref = (manifest.ref ?? manifest.tag ?? "").trim();
     const tag = (manifest.tag ?? "").trim();

package/dist/doctor/types.d.ts

@@ -1,4 +1,7 @@
 import type { AdvisoryEvaluateResult } from "../agents-md-advisory/evaluate.js";
+import type { EngineProbeResult } from "../resolution/classify.js";
+import type { ResolutionMode } from "../resolution/index.js";
+import type { ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 export declare const EXIT_CLEAN = 0;
 export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
@@ -25,6 +28,34 @@ export interface Finding {
     readonly status?: string;
     readonly [key: string]: unknown;
 }
+/**
+ * The single read-only decision surface derived from the shared keystone
+ * `plan()` (#2267 / epic #2203). `plan()` is the ONE classifier: doctor never
+ * re-derives the mode here, it only renders the mode + the single ordered next
+ * action plus the operating-mode / reconciliation / cross-platform-skew context.
+ */
+export interface ResolutionSummary {
+    /** Human-facing operating mode (hybrid / vendored / greenfield / ...). */
+    readonly operatingMode: string;
+    /** engine/pin/VERSION reconciliation verdict line. */
+    readonly reconciliation: string;
+    /** Cross-platform `.deft/.cli/<platform>` engine presence + skew line. */
+    readonly platformSkew: string;
+    /** True when the platform installs diverge (present/partial/absent mix). */
+    readonly platformSkewDetected: boolean;
+    /** Resolved mode from `plan()` (the single classifier). */
+    readonly mode: ResolutionMode;
+    /** True when the resolved mode requires operator action (mode !== "proceed"). */
+    readonly actionRequired: boolean;
+    /** The ONE primary next command, directive-surfaced; null for manual actions. */
+    readonly nextCommand: string | null;
+    /** Why the primary action is recommended. */
+    readonly rootCause: string;
+    /** What the remediation does + why it is safe. */
+    readonly remediation: string;
+    /** Ordered secondary warnings from `plan()` (informational, not directives). */
+    readonly warnings: readonly string[];
+}
 export interface DoctorFlags {
     readonly session: boolean;
     readonly fix: boolean;
@@ -79,5 +110,22 @@ export interface DoctorSeams {
     readonly readYn?: (prompt: string, defaultYes: boolean) => boolean;
     readonly writeText?: (path: string, content: string) => void;
     readonly now?: () => Date;
+    /**
+     * Engine-reachability probe threaded into the shared `classify()`. Injected so
+     * the resolution decision stays deterministic + offline in tests; the default
+     * shells out to `directive --version` / `deft --version`.
+     */
+    readonly engineProbe?: () => EngineProbeResult;
+    /**
+     * Platform ids probed for cross-platform `.deft/.cli/<platform>` engine skew.
+     * Defaults to `["linux", "darwin", "win32"]`.
+     */
+    readonly resolutionPlatforms?: readonly string[];
+    /**
+     * USER.md resolver seam (#2271). Injected so the doctor USER.md-resolution
+     * surface stays deterministic + offline in tests. Defaults to the shared
+     * first-hit-wins resolver scoped to the project root.
+     */
+    readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
+export * as resolution from "./resolution/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as session from "./session/index.js";
@@ -42,6 +43,7 @@ export * as slice from "./slice/index.js";
 export * as storyReady from "./story-ready/index.js";
 export * as swarm from "./swarm/index.js";
 export * as triage from "./triage/index.js";
+export * as userConfig from "./user-config/index.js";
 export * as validateContent from "./validate-content/index.js";
 export * as vbriefActivate from "./vbrief-activate/index.js";
 export * as vbriefBuild from "./vbrief-build/index.js";

package/dist/index.js

@@ -35,6 +35,7 @@ export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
+export * as resolution from "./resolution/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as session from "./session/index.js";
@@ -42,6 +43,7 @@ export * as slice from "./slice/index.js";
 export * as storyReady from "./story-ready/index.js";
 export * as swarm from "./swarm/index.js";
 export * as triage from "./triage/index.js";
+export * as userConfig from "./user-config/index.js";
 export * as validateContent from "./validate-content/index.js";
 export * as vbriefActivate from "./vbrief-activate/index.js";
 export * as vbriefBuild from "./vbrief-build/index.js";