@deftai/directive-core 0.56.1 → 0.57.0

package/dist/content-contracts/standards/_helpers.js

@@ -63,6 +63,10 @@ const SKIP_DIRS = new Set([
     "dist",
     "tests",
     ".deft-cache",
+    // node_modules holds third-party markdown (dependency READMEs) that is not
+    // framework content; scanning it produced volatile, version-pinned cases that
+    // broke CI when dependency versions drifted (#1993 follow-up).
+    "node_modules",
 ]);
 const MIGRATION_ARTIFACT_TREES = ["vbrief/migration"];
 export function isMigrationArtifact(rel) {

package/dist/doctor/checks.d.ts

@@ -14,6 +14,11 @@ export declare function checkInstallPathConsistency(projectRoot: string, install
  * `skip` for the canonical / greenfield layout (nothing to signpost).
  */
 export declare function checkLegacyLayout(projectRoot: string, seams?: CheckSeams): CheckResult;
+/**
+ * #1997: signpost a canonical-vendored `.deft/core/` deposit that has not yet
+ * been stamped npm-managed. Local-only (no network).
+ */
+export declare function checkCanonicalVendoredNpmSignpost(projectRoot: string, seams?: CheckSeams): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {
     isDir?: (p: string) => boolean;

package/dist/doctor/checks.js

@@ -1,8 +1,9 @@
 import { join } from "node:path";
 import { detectLegacyLayout, legacyLayoutSignpostLine, } from "../init-deposit/legacy-detect.js";
+import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY, NPM_MANAGED_SENTINEL_VALUE, } from "../init-deposit/migrate.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
-import { GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL } from "./constants.js";
-import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestTagToVersion, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
+import { CANONICAL_UPGRADE_COMMAND, GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL, } from "./constants.js";
+import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
 import { readTextSafe } from "./paths.js";
 function readText(path, seams) {
     return (seams.readText ?? readTextSafe)(path);
@@ -312,11 +313,63 @@ export function checkLegacyLayout(projectRoot, seams = {}) {
         },
     };
 }
+/**
+ * #1997: signpost a canonical-vendored `.deft/core/` deposit that has not yet
+ * been stamped npm-managed. Local-only (no network).
+ */
+export function checkCanonicalVendoredNpmSignpost(projectRoot, seams = {}) {
+    const readText = seams.readText ?? readTextSafe;
+    const isFile = seams.isFile ?? ((p) => readText(p) !== null);
+    const manifestPath = detectCanonicalVendoredManifest(projectRoot, isFile);
+    if (manifestPath === null) {
+        return {
+            name: "canonical-vendored-npm-signpost",
+            status: "skip",
+            detail: "No canonical-vendored .deft/core/ deposit (nothing to signpost).",
+            data: { canonical_vendored: false },
+        };
+    }
+    const text = readText(manifestPath);
+    if (text === null) {
+        return {
+            name: "canonical-vendored-npm-signpost",
+            status: "skip",
+            detail: "Canonical-vendored manifest unreadable.",
+            data: { canonical_vendored: true },
+        };
+    }
+    const manifest = parseInstallManifest(text);
+    if (isNpmManaged(manifest)) {
+        return {
+            name: "canonical-vendored-npm-signpost",
+            status: "skip",
+            detail: "Deposit is already npm-managed (hybrid).",
+            data: { canonical_vendored: true, npm_managed: true },
+        };
+    }
+    const detail = "Canonical-vendored install (.deft/core/) is not yet npm-managed. " +
+        "Post-freeze upgrades run via npm: install the engine with " +
+        `\`${CANONICAL_UPGRADE_COMMAND}\`, then run \`directive migrate\` ` +
+        `to stamp provenance. See ${UPGRADING_DOC_URL}.`;
+    return {
+        name: "canonical-vendored-npm-signpost",
+        status: "fail",
+        detail,
+        data: {
+            canonical_vendored: true,
+            npm_managed: false,
+            manifest_path: manifestPath,
+            sentinel_key: NPM_MANAGED_SENTINEL_KEY,
+            sentinel_value: NPM_MANAGED_SENTINEL_VALUE,
+            upgrading_doc_url: UPGRADING_DOC_URL,
+        },
+    };
+}
 export function deriveExitCode(checks, errors) {
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
     }
-    if (checks.some((c) => c.status === "fail")) {
+    if (checks.some((c) => c.status === "fail" && c.name !== "canonical-vendored-npm-signpost")) {
         return 1;
     }
     return 0;
@@ -349,6 +402,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
         });
         checks.push(checkManifestAgreement(projectRoot, null, seams));
         checks.push(checkLegacyLayout(projectRoot, seams));
+        checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
         return {
             projectRoot,
             installRoot: null,
@@ -362,6 +416,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkManifestAgreement(projectRoot, installRoot, seams));
     checks.push(checkInstallPathConsistency(projectRoot, installRoot, seams));
     checks.push(checkLegacyLayout(projectRoot, seams));
+    checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
     return {
         projectRoot,
         installRoot,

package/dist/doctor/constants.d.ts

@@ -10,7 +10,9 @@ export declare const DOCTOR_ALLOWED_FLAGS: readonly ["--session", "--fix", "--re
 export declare const EXPECTED_FRAMEWORK_DIRS: readonly ["tasks", "scripts", "vbrief"];
 export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/agents-entry.md", "content/skills/deft-directive-build/SKILL.md"];
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
-export declare const CANONICAL_UPGRADE_COMMAND = "deft-install --yes --upgrade --repo-root . --json";
+/** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
+export declare const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+export declare const NPM_PACKAGE_NAME = "@deftai/directive";
 export declare const CLEAN_WINDOW_HOURS = 24;
 export declare const DIRTY_WINDOW_HOURS = 4;
 export declare const ENV_STATE_PATH = "DEFT_DOCTOR_STATE_PATH";

package/dist/doctor/constants.js

@@ -41,7 +41,9 @@ export const DEFT_REPO_POSITIVE_MARKERS = [
 // same check works for a source checkout (content/<dir>) and a flattened
 // consumer deposit (<dir>).
 export const EXPECTED_CONTENT_DIRS = ["languages", "strategies", "skills", "templates"];
-export const CANONICAL_UPGRADE_COMMAND = "deft-install --yes --upgrade --repo-root . --json";
+/** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
+export const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+export const NPM_PACKAGE_NAME = "@deftai/directive";
 export const CLEAN_WINDOW_HOURS = 24;
 export const DIRTY_WINDOW_HOURS = 4;
 export const ENV_STATE_PATH = "DEFT_DOCTOR_STATE_PATH";

package/dist/doctor/main.js

@@ -10,6 +10,7 @@ import { pythonJsonDump } from "./json.js";
 import { createPlainSink } from "./output.js";
 import { 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 { defaultWhich } from "./which.js";
 export function cmdDoctor(args, seams = {}) {
@@ -33,6 +34,11 @@ export function cmdDoctor(args, seams = {}) {
         const state = (seams.readState ?? readState)(projectRoot);
         const decision = decideThrottle(state, nowFn());
         if (decision.skip) {
+            const throttleFindings = [];
+            const throttleSink = createPlainSink({ jsonMode, quietMode });
+            runLocalSignpostChecks(projectRoot, throttleSink, (finding) => {
+                throttleFindings.push(finding);
+            }, seams);
             const hint = decision.dirty
                 ? "run `deft doctor --full` to re-probe or address findings"
                 : "--full forces";
@@ -45,12 +51,17 @@ export function cmdDoctor(args, seams = {}) {
                     last_error_count: decision.lastErrorCount,
                     next_eligible_at: formatIsoZ(decision.nextEligibleAt),
                     hint,
+                    ...(throttleFindings.length > 0 ? { signpost_findings: throttleFindings } : {}),
                 };
                 process.stdout.write(`${pythonJsonDump(payload)}\n`);
             }
             else {
                 process.stdout.write(`${renderDoctorStatusLine(decision, nowFn())}\n`);
             }
+            const signpostWarnings = throttleFindings.filter((f) => f.severity === "warning").length;
+            if (signpostWarnings > 0 && !jsonMode) {
+                throttleSink.finalWarn(`Signpost advisory: ${signpostWarnings} local layout / npm-migration note(s) above (throttle-skipped full probe).`);
+            }
             return decision.dirty ? 1 : 0;
         }
     }
@@ -239,6 +250,19 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                 sink.info(`${name}: skip -- ${detail}`);
                 continue;
             }
+            if ((name === "legacy-layout" || name === "canonical-vendored-npm-signpost") &&
+                status === "fail") {
+                sink.warn(`${name}: ${detail}`);
+                addFinding({
+                    severity: "warning",
+                    message: detail || `${name} ${status}`,
+                    check: `install-integrity:${name}`,
+                    install_check: name,
+                    status,
+                    data: entry.data ?? {},
+                });
+                continue;
+            }
             if (status === "error") {
                 sink.error(`${name}: error -- ${detail}`);
             }

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

@@ -8,6 +8,10 @@ export interface PayloadStalenessSeams {
         ok: boolean;
         stdout: string;
     };
+    readonly runNpmViewVersion?: () => {
+        ok: boolean;
+        version: string;
+    };
 }
 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,13 +1,13 @@
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
-import { CANONICAL_UPGRADE_COMMAND } from "./constants.js";
+import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME } from "./constants.js";
 import { locateManifest, parseInstallManifest } from "./manifest.js";
 import { readTextSafe, resolveDefaultFrameworkRoot } from "./paths.js";
 function isDeftFrameworkRepo(projectRoot, readText = readTextSafe) {
     try {
         const agents = join(projectRoot, "AGENTS.md");
         const text = readText(agents);
-        return text !== null && text.includes("Deft — Development Framework (deft repo)");
+        return text?.includes("Deft — Development Framework (deft repo)") ?? false;
     }
     catch {
         return false;
@@ -37,6 +37,74 @@ function parseRemoteSha(stdout) {
     const firstLine = stdout.split("\n").find((ln) => ln.trim()) ?? "";
     return firstLine.trim().split(/\s+/)[0] ?? "";
 }
+function parseSemver(version) {
+    const normalized = version.trim().replace(/^v/i, "");
+    const parts = [];
+    for (const segment of normalized.split(".")) {
+        const numeric = Number.parseInt(segment.split("-")[0] ?? "", 10);
+        if (Number.isNaN(numeric)) {
+            break;
+        }
+        parts.push(numeric);
+    }
+    return parts.length > 0 ? parts : [0];
+}
+function semverLessThan(left, right) {
+    const a = parseSemver(left);
+    const b = parseSemver(right);
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i += 1) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (av < bv) {
+            return true;
+        }
+        if (av > bv) {
+            return false;
+        }
+    }
+    return false;
+}
+function manifestVersion(ref, tag) {
+    const candidate = (tag || ref).trim().replace(/^refs\/tags\//, "");
+    const normalized = candidate.replace(/^v/i, "");
+    if (!/^\d+(?:\.\d+)*/.test(normalized)) {
+        return "";
+    }
+    return normalized;
+}
+function defaultNpmViewVersion() {
+    const proc = spawnSync("npm", ["view", NPM_PACKAGE_NAME, "version"], {
+        encoding: "utf8",
+        timeout: 15_000,
+    });
+    const version = (proc.stdout ?? "").trim().split("\n")[0]?.trim() ?? "";
+    return { ok: proc.status === 0 && version.length > 0, version };
+}
+function emitUnverified(checkName, reason, sink, addFinding) {
+    const msg = `payload currency UNVERIFIED — ${reason}`;
+    sink.warn(msg);
+    addFinding({
+        severity: "warning",
+        message: msg,
+        check: checkName,
+        status: "unverified",
+    });
+}
+function emitStale(checkName, installedLabel, remoteLabel, ref, sink, addFinding, extras = {}, behindWord = "remote") {
+    const msg = `Framework payload is stale (installed ${installedLabel} behind ${behindWord} ${remoteLabel} for ref '${ref}'). ` +
+        `Recommendation: run \`${CANONICAL_UPGRADE_COMMAND}\` from any shell with Node ≥ 20.`;
+    sink.warn(msg);
+    addFinding({
+        severity: "warning",
+        message: msg,
+        check: checkName,
+        status: "stale",
+        ref,
+        suggestion: CANONICAL_UPGRADE_COMMAND,
+        ...extras,
+    });
+}
 export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams = {}) {
     const checkName = "payload-staleness";
     const readText = seams.readText ?? readTextSafe;
@@ -48,6 +116,7 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
             message: "inside framework repo (no install manifest)",
             check: checkName,
             status: "skip",
+            reason: "not-applicable",
         });
         return;
     }
@@ -64,7 +133,13 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
     }
     if (manifestPath === null || !isFile(manifestPath)) {
         sink.info(`${checkName}: skip -- no install manifest found (pre-v0.28 or legacy state)`);
-        addFinding({ severity: "skip", message: "no manifest", check: checkName, status: "skip" });
+        addFinding({
+            severity: "skip",
+            message: "no manifest",
+            check: checkName,
+            status: "skip",
+            reason: "not-applicable",
+        });
         return;
     }
     const text = readText(manifestPath);
@@ -75,12 +150,14 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
             message: "manifest unreadable",
             check: checkName,
             status: "skip",
+            reason: "not-applicable",
         });
         return;
     }
     const manifest = parseInstallManifest(text);
     const installedSha = (manifest.sha ?? "").trim();
     const ref = (manifest.ref ?? manifest.tag ?? "").trim();
+    const tag = (manifest.tag ?? "").trim();
     if (!installedSha) {
         sink.info(`${checkName}: skip -- manifest has no sha (incomplete provenance)`);
         addFinding({
@@ -88,6 +165,7 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
             message: "no sha in manifest",
             check: checkName,
             status: "skip",
+            reason: "not-applicable",
         });
         return;
     }
@@ -98,6 +176,7 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
             message: "no ref/tag in manifest",
             check: checkName,
             status: "skip",
+            reason: "not-applicable",
         });
         return;
     }
@@ -110,56 +189,47 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
             });
             return { ok: proc.status === 0, stdout: proc.stdout ?? "" };
         });
+    const runNpmView = seams.runNpmViewVersion ?? defaultNpmViewVersion;
     let remoteResult;
     try {
         remoteResult = runLsRemote(deftDir, ref);
     }
     catch {
-        sink.info(`${checkName}: skip -- could not probe remote (Error)`);
-        addFinding({
-            severity: "skip",
-            message: "remote probe failed",
-            check: checkName,
-            status: "skip",
-        });
-        return;
-    }
-    if (!remoteResult.ok) {
-        sink.info(`${checkName}: skip -- git ls-remote failed (no network or no origin)`);
-        addFinding({
-            severity: "skip",
-            message: "ls-remote unavailable",
-            check: checkName,
-            status: "skip",
-        });
-        return;
-    }
-    const remoteSha = parseRemoteSha(remoteResult.stdout);
-    if (!remoteSha) {
-        sink.info(`${checkName}: skip -- ls-remote produced no sha`);
-        addFinding({
-            severity: "skip",
-            message: "no remote sha",
-            check: checkName,
-            status: "skip",
-        });
-        return;
+        remoteResult = { ok: false, stdout: "" };
+    }
+    if (remoteResult.ok) {
+        const remoteSha = parseRemoteSha(remoteResult.stdout);
+        if (remoteSha) {
+            if (installedSha === remoteSha) {
+                sink.info(`${checkName}: current (sha matches remote)`);
+                return;
+            }
+            emitStale(checkName, `sha ${installedSha.slice(0, 8)}...`, `sha ${remoteSha.slice(0, 8)}...`, ref, sink, addFinding, { installed_sha: installedSha, remote_sha: remoteSha, resolver: "git-ls-remote" });
+            return;
+        }
     }
-    if (installedSha === remoteSha) {
-        sink.info(`${checkName}: current (sha matches remote)`);
+    const npmResult = runNpmView();
+    const installedVersion = manifestVersion(ref, tag);
+    if (npmResult.ok && installedVersion) {
+        if (semverLessThan(installedVersion, npmResult.version)) {
+            emitStale(checkName, `v${installedVersion}`, `v${npmResult.version}`, ref, sink, addFinding, {
+                installed_version: installedVersion,
+                remote_version: npmResult.version,
+                resolver: "npm-view",
+            }, "npm registry");
+            return;
+        }
+        if (installedVersion === npmResult.version.replace(/^v/i, "")) {
+            sink.info(`${checkName}: current (version matches npm registry)`);
+            return;
+        }
+        sink.info(`${checkName}: current (installed version >= npm registry)`);
         return;
     }
-    const msg = `Framework payload is stale (installed sha ${installedSha.slice(0, 8)}... behind remote ${remoteSha.slice(0, 8)}... for ref '${ref}'). Recommendation: run the canonical headless upgrader \`${CANONICAL_UPGRADE_COMMAND}\` from your project root to pull the latest payload (drop \`--json\` for human-readable output). On an installer binary predating the headless flags, download the latest deft-install from GitHub Releases first.`;
-    sink.warn(msg);
-    addFinding({
-        severity: "warning",
-        message: msg,
-        check: checkName,
-        status: "stale",
-        installed_sha: installedSha,
-        remote_sha: remoteSha,
-        ref,
-        suggestion: CANONICAL_UPGRADE_COMMAND,
-    });
+    const reason = remoteResult.ok
+        ? "ls-remote produced no sha and npm registry fallback unavailable"
+        : "could not reach remote (git ls-remote / npm view both unavailable)";
+    sink.info(`${checkName}: skip -- ${reason}`);
+    emitUnverified(checkName, reason, sink, addFinding);
 }
 //# sourceMappingURL=payload-staleness.js.map

package/dist/doctor/signpost-checks.d.ts

@@ -0,0 +1,9 @@
+import { type CheckSeams } from "./checks.js";
+import type { OutputSink } from "./output.js";
+import type { Finding } from "./types.js";
+export interface LocalSignpostSeams extends CheckSeams {
+    readonly runningInsideDeftRepo?: (root: string) => boolean;
+}
+/** Lightweight, local-only signpost probes for the throttle-skip path (#1997). */
+export declare function runLocalSignpostChecks(projectRoot: string, sink: OutputSink, addFinding: (finding: Finding) => void, seams?: LocalSignpostSeams): void;
+//# sourceMappingURL=signpost-checks.d.ts.map

package/dist/doctor/signpost-checks.js

@@ -0,0 +1,28 @@
+import { checkCanonicalVendoredNpmSignpost, checkLegacyLayout } from "./checks.js";
+import { runningInsideDeftRepo } from "./paths.js";
+/** Lightweight, local-only signpost probes for the throttle-skip path (#1997). */
+export function runLocalSignpostChecks(projectRoot, sink, addFinding, seams = {}) {
+    const insideDeft = seams.runningInsideDeftRepo?.(projectRoot) ?? runningInsideDeftRepo(projectRoot, seams);
+    if (insideDeft) {
+        return;
+    }
+    for (const result of [
+        checkLegacyLayout(projectRoot, seams),
+        checkCanonicalVendoredNpmSignpost(projectRoot, seams),
+    ]) {
+        if (result.status === "skip") {
+            continue;
+        }
+        if (result.status === "fail") {
+            sink.warn(result.detail);
+            addFinding({
+                severity: "warning",
+                message: result.detail,
+                check: result.name,
+                status: result.status,
+                data: result.data ?? {},
+            });
+        }
+    }
+}
+//# sourceMappingURL=signpost-checks.js.map

package/dist/preflight-cache/evaluate.js

@@ -148,6 +148,32 @@ function metaFetchedAt(metaPath) {
         return null;
     }
 }
+/**
+ * #1991: report whether a cache entry's upstream issue is terminal-closed.
+ *
+ * Reads the sibling raw.json (the cached issue payload) and returns true only
+ * when its `state` is positively "closed". Unknown / missing state returns
+ * false so we never exclude an entry we are not sure about. Closed issues are
+ * terminal: their `fetched_at` age is irrelevant to dispatch-queue freshness,
+ * and `cache:fetch-all --force` (open-only enumeration) can never refresh them,
+ * so the age gate must not wedge on them.
+ */
+function metaEntryIsTerminalClosed(metaPath) {
+    const rawPath = join(metaPath, "..", "raw.json");
+    if (!existsSync(rawPath))
+        return false;
+    try {
+        const raw = JSON.parse(readFileSync(rawPath, "utf8"));
+        if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+            const state = raw.state;
+            return typeof state === "string" && state.toLowerCase() === "closed";
+        }
+    }
+    catch {
+        /* unknown state -> keep in scope */
+    }
+    return false;
+}
 function loadScopeRules(projectRoot) {
     const defPath = join(projectRoot, "vbrief", "PROJECT-DEFINITION.vbrief.json");
     if (!existsSync(defPath))
@@ -398,10 +424,16 @@ export function evaluate(projectRoot, options = {}) {
         allMetaPaths.length > 0 &&
         scopedMetaPaths.length === 0 &&
         candState === "populated";
-    // Step 5: Oldest in-scope entry age + drift probe (#1886)
+    // Step 5: Oldest in-scope entry age + drift probe (#1886).
+    // #1991: judge age over OPEN entries only. Terminal-closed entries are
+    // excluded because `cache:fetch-all --force` (open-only enumeration) can never
+    // refresh their `fetched_at`, so including them would let a stale closed entry
+    // wedge the gate with no working recovery command.
+    const rawCandidatePaths = scopedMetaPaths.length > 0 ? scopedMetaPaths : allMetaPaths;
+    const ageCandidatePaths = rawCandidatePaths.filter((p) => !metaEntryIsTerminalClosed(p));
     let minFetchedAt = null;
     let minMetaPath = null;
-    for (const p of scopedMetaPaths.length > 0 ? scopedMetaPaths : allMetaPaths) {
+    for (const p of ageCandidatePaths) {
         const ts = metaFetchedAt(p);
         if (ts !== null && (minFetchedAt === null || ts < minFetchedAt)) {
             minFetchedAt = ts;
@@ -411,7 +443,11 @@ export function evaluate(projectRoot, options = {}) {
     const now = nowFn();
     const ageMs = minFetchedAt !== null ? now.getTime() - minFetchedAt.getTime() : Infinity;
     const ageH = ageMs / (1000 * 3600);
-    const stale = ageH > maxAgeHours;
+    // When every candidate is terminal-closed (non-empty input, no open entry to
+    // judge) there is nothing open whose age can be stale -> fresh. The truly
+    // empty-cache case (no entries at all) preserves its prior staleness result.
+    const allCandidatesClosed = minFetchedAt === null && rawCandidatePaths.length > 0;
+    const stale = allCandidatesClosed ? false : ageH > maxAgeHours;
     // Step 5b: --allow-stale bypass
     if (stale && allowStale) {
         const warning = [

package/dist/release-e2e/constants.d.ts

@@ -16,6 +16,10 @@ export declare const NPM_E2E_REHEARSAL_TAG = "e2e-rehearsal";
 export declare const NPM_INSTALL_TIMEOUT_SECONDS = 600;
 export declare const NPM_BUILD_TIMEOUT_SECONDS = 600;
 export declare const NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS = 180;
+export declare const NPM_PACK_TIMEOUT_SECONDS = 300;
+export declare const NPM_INSTALL_RUN_TIMEOUT_SECONDS = 300;
+/** Fail the install+run smoke when stderr/stdout carries a module-resolution error. */
+export declare const MODULE_NOT_FOUND_MARKERS: readonly ["Cannot find module", "ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"];
 export declare const RELEASE_ENTRYPOINT_TIMEOUT_SECONDS = 600;
 export declare const ROLLBACK_ENTRYPOINT_TIMEOUT_SECONDS = 300;
 export declare const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;

package/dist/release-e2e/constants.js

@@ -16,6 +16,14 @@ export const NPM_E2E_REHEARSAL_TAG = "e2e-rehearsal";
 export const NPM_INSTALL_TIMEOUT_SECONDS = 600;
 export const NPM_BUILD_TIMEOUT_SECONDS = 600;
 export const NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS = 180;
+export const NPM_PACK_TIMEOUT_SECONDS = 300;
+export const NPM_INSTALL_RUN_TIMEOUT_SECONDS = 300;
+/** Fail the install+run smoke when stderr/stdout carries a module-resolution error. */
+export const MODULE_NOT_FOUND_MARKERS = [
+    "Cannot find module",
+    "ERR_MODULE_NOT_FOUND",
+    "MODULE_NOT_FOUND",
+];
 export const RELEASE_ENTRYPOINT_TIMEOUT_SECONDS = 600.0;
 export const ROLLBACK_ENTRYPOINT_TIMEOUT_SECONDS = 300.0;
 export const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;

package/dist/release-e2e/npm-ops.d.ts

@@ -28,4 +28,17 @@ export declare function alignNpmPackageVersions(cloneDir: string, version: strin
  * Returns [ok, reason] like verifyDraftRelease / verifyTag.
  */
 export declare function rehearseNpmPublish(cloneDir: string, version: string, seams?: E2ESeams): [boolean, string];
+/**
+ * Publish-layout install+run smoke (#1996, #2010): pack the four
+ * @deftai/directive* packages, install the tarballs into a clean flat
+ * node_modules, then run `directive --version` (exit-0 liveness) and
+ * `directive doctor` (deep-import coverage) so import-resolution bugs like
+ * #1993 sub-problem 1 surface before a real npm publish. The smoke gates on
+ * module-not-found markers, NOT on the doctor's pass/fail verdict -- a full
+ * doctor check exits non-zero in a bare consumer layout, which is benign
+ * (#2010).
+ */
+export declare function rehearseNpmInstallAndRun(cloneDir: string, version: string, seams?: E2ESeams, options?: {
+    skipWorkspacePrep?: boolean;
+}): [boolean, string];
 //# sourceMappingURL=npm-ops.d.ts.map

package/dist/release-e2e/npm-ops.js

@@ -1,7 +1,7 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { defaultWhich, spawnText } from "../release/spawn.js";
-import { NPM_BUILD_TIMEOUT_SECONDS, NPM_E2E_REHEARSAL_TAG, NPM_INSTALL_TIMEOUT_SECONDS, NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS, NPM_PUBLISH_PACKAGES, } from "./constants.js";
+import { MODULE_NOT_FOUND_MARKERS, NPM_BUILD_TIMEOUT_SECONDS, NPM_E2E_REHEARSAL_TAG, NPM_INSTALL_RUN_TIMEOUT_SECONDS, NPM_INSTALL_TIMEOUT_SECONDS, NPM_PACK_TIMEOUT_SECONDS, NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS, NPM_PUBLISH_PACKAGES, } from "./constants.js";
 /**
  * npm publish dry-run rehearsal (#1910) -- the TS port of the
  * scripts/release_e2e.py helpers of the same name. Mirrors
@@ -148,4 +148,122 @@ export function rehearseNpmPublish(cloneDir, version, seams = {}) {
             `(types -> core -> content -> cli) at v${version}`,
     ];
 }
+function moduleResolutionFailure(output) {
+    for (const marker of MODULE_NOT_FOUND_MARKERS) {
+        if (output.includes(marker))
+            return marker;
+    }
+    return null;
+}
+/**
+ * Publish-layout install+run smoke (#1996, #2010): pack the four
+ * @deftai/directive* packages, install the tarballs into a clean flat
+ * node_modules, then run `directive --version` (exit-0 liveness) and
+ * `directive doctor` (deep-import coverage) so import-resolution bugs like
+ * #1993 sub-problem 1 surface before a real npm publish. The smoke gates on
+ * module-not-found markers, NOT on the doctor's pass/fail verdict -- a full
+ * doctor check exits non-zero in a bare consumer layout, which is benign
+ * (#2010).
+ */
+export function rehearseNpmInstallAndRun(cloneDir, version, seams = {}, options = {}) {
+    const which = resolveWhich(seams);
+    const npmPath = which("npm");
+    if (npmPath === null) {
+        return [true, "SKIP (npm not on PATH; Node-less operator)"];
+    }
+    const pnpmCmd = resolvePnpm(seams);
+    if (pnpmCmd === null) {
+        return [
+            false,
+            "npm present but neither pnpm nor corepack is on PATH -- " +
+                "cannot build the workspace for install+run smoke",
+        ];
+    }
+    const env = { ...process.env, DEFT_PROJECT_ROOT: cloneDir };
+    let ok = true;
+    let reason = "";
+    if (!options.skipWorkspacePrep) {
+        let [ok, reason] = runNpmStep([...pnpmCmd, "install", "--frozen-lockfile"], cloneDir, env, "pnpm install", NPM_INSTALL_TIMEOUT_SECONDS, seams);
+        if (!ok)
+            return [false, reason];
+        [ok, reason] = runNpmStep([...pnpmCmd, "-w", "run", "build"], cloneDir, env, "pnpm build", NPM_BUILD_TIMEOUT_SECONDS, seams);
+        if (!ok)
+            return [false, reason];
+        [ok, reason] = alignNpmPackageVersions(cloneDir, version);
+        if (!ok)
+            return [false, reason];
+    }
+    const packDir = join(cloneDir, ".deft-e2e-packs");
+    mkdirSync(packDir, { recursive: true });
+    const tgzPaths = [];
+    for (const pkg of NPM_PUBLISH_PACKAGES) {
+        const pkgDir = join(cloneDir, "packages", pkg);
+        [ok, reason] = runNpmStep([npmPath, "pack", "--pack-destination", packDir], pkgDir, env, `npm pack packages/${pkg}`, NPM_PACK_TIMEOUT_SECONDS, seams);
+        if (!ok)
+            return [false, reason];
+        const manifest = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+        if (manifest === null ||
+            typeof manifest.name !== "string" ||
+            typeof manifest.version !== "string") {
+            return [false, `version-align FAIL: invalid manifest in packages/${pkg}`];
+        }
+        const scoped = manifest.name.replaceAll("@", "").replaceAll("/", "-");
+        tgzPaths.push(join(packDir, `${scoped}-${manifest.version}.tgz`));
+    }
+    const consumerDir = join(cloneDir, ".deft-e2e-consumer");
+    mkdirSync(consumerDir, { recursive: true });
+    writeFileSync(join(consumerDir, "package.json"), `${JSON.stringify({ name: "deft-e2e-consumer", private: true, version: "0.0.0" }, null, 2)}\n`, "utf8");
+    const installArgs = [npmPath, "install", ...tgzPaths];
+    [ok, reason] = runNpmStep(installArgs, consumerDir, env, "npm install packed tarballs", NPM_INSTALL_RUN_TIMEOUT_SECONDS, seams);
+    if (!ok)
+        return [false, reason];
+    const spawn = seams.spawnText ?? spawnText;
+    const cliBin = join(consumerDir, "node_modules", "@deftai", "directive", "dist", "bin.js");
+    // Liveness probe (#2010): `--version` loads the cli + core engine via
+    // engineInfo(), exercising the cross-package import path that #1993 broke,
+    // and reliably exits 0 on a healthy install. This is the clean exit-0 gate;
+    // gating the smoke on the doctor's exit code instead is a false positive
+    // because a full doctor check exits non-zero in a bare consumer layout.
+    const versionRun = spawn(process.execPath, [cliBin, "--version"], {
+        cwd: consumerDir,
+        env,
+        timeoutMs: NPM_INSTALL_RUN_TIMEOUT_SECONDS * 1000,
+    });
+    const versionOut = `${versionRun.stdout ?? ""}\n${versionRun.stderr ?? ""}`;
+    let resolutionHit = moduleResolutionFailure(versionOut);
+    if (resolutionHit !== null) {
+        return [
+            false,
+            `install+run smoke: module resolution error on --version (${resolutionHit}): ${versionOut.trim().slice(-800)}`,
+        ];
+    }
+    if (versionRun.status !== 0) {
+        return [
+            false,
+            `install+run smoke: directive --version exited ${versionRun.status}: ${versionOut.trim().slice(-500)}`,
+        ];
+    }
+    // Deep-import probe (#2010): run the doctor verb to exercise the deeper
+    // cross-package import graph that #1993 sub-problem 1 broke. The doctor
+    // legitimately exits non-zero in a bare consumer layout (e.g. no root
+    // Taskfile.yml), so gate ONLY on the module-not-found markers, NOT on the
+    // doctor's pass/fail verdict.
+    const doctorRun = spawn(process.execPath, [cliBin, "doctor"], {
+        cwd: consumerDir,
+        env,
+        timeoutMs: NPM_INSTALL_RUN_TIMEOUT_SECONDS * 1000,
+    });
+    const doctorOut = `${doctorRun.stdout ?? ""}\n${doctorRun.stderr ?? ""}`;
+    resolutionHit = moduleResolutionFailure(doctorOut);
+    if (resolutionHit !== null) {
+        return [
+            false,
+            `install+run smoke: module resolution error on doctor (${resolutionHit}): ${doctorOut.trim().slice(-800)}`,
+        ];
+    }
+    return [
+        true,
+        `packed + installed 4 packages at v${version}; ran directive --version (exit 0) + doctor without module-not-found`,
+    ];
+}
 //# sourceMappingURL=npm-ops.js.map

package/dist/release-e2e/rehearsal.js

@@ -6,7 +6,7 @@ import { dispatchTaskRelease, dispatchTaskReleaseRollback } from "./entrypoint.j
 import { emit } from "./flags.js";
 import { verifyDraftRelease } from "./gh-ops.js";
 import { cloneRepoToTemp, pushMirror, setOriginToTempRepo, verifyTag } from "./git-ops.js";
-import { rehearseNpmPublish } from "./npm-ops.js";
+import { rehearseNpmInstallAndRun, rehearseNpmPublish } from "./npm-ops.js";
 export function runRehearsal(owner, slug, projectRoot, version = REHEARSAL_VERSION, seams = {}, skipNpm = false) {
     const repoFull = `${owner}/${slug}`;
     const mkdtemp = seams.mkdtemp ?? ((prefix) => mkdtempSync(join(tmpdir(), prefix)));
@@ -24,6 +24,10 @@ export function runRehearsal(owner, slug, projectRoot, version = REHEARSAL_VERSI
         ];
         if (!skipNpm) {
             steps.push(["npm publish dry-run", () => rehearseNpmPublish(cloneDir, version, seams)]);
+            steps.push([
+                "npm install+run smoke",
+                () => rehearseNpmInstallAndRun(cloneDir, version, seams, { skipWorkspacePrep: true }),
+            ]);
         }
         steps.push([
             "task release:rollback",
@@ -36,7 +40,9 @@ export function runRehearsal(owner, slug, projectRoot, version = REHEARSAL_VERSI
                 return [false, `${label}: ${reason}`];
             }
         }
-        const npmNote = skipNpm ? " (npm dry-run skipped)" : " -> npm publish dry-run";
+        const npmNote = skipNpm
+            ? " (npm dry-run skipped)"
+            : " -> npm publish dry-run -> npm install+run smoke";
         return [
             true,
             `pipeline-mirror rehearsal succeeded against ${repoFull} ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.56.1",
+  "version": "0.57.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -189,6 +189,10 @@
     "./init-deposit": {
       "types": "./dist/init-deposit/index.d.ts",
       "default": "./dist/init-deposit/index.js"
+    },
+    "./dist/*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
     }
   },
   "files": [
@@ -205,8 +209,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.56.1",
-    "@deftai/directive-types": "^0.56.1"
+    "@deftai/directive-content": "^0.57.0",
+    "@deftai/directive-types": "^0.57.0"
   },
   "scripts": {
     "build": "tsc -b",