@deftai/directive-core 0.76.0 → 0.77.0

package/dist/agents-md-budget/evaluate.d.ts

@@ -4,7 +4,11 @@ export type OutputStream = "stdout" | "stderr" | "none";
 /**
  * Layered absolute north-star for the always-on managed surface (#2372 / #2450 / #2452).
  *
- * `ABSOLUTE_MANAGED_MAX_BYTES` is the relocation north-star (<=8192 B / ~2k tok).
+ * `ABSOLUTE_MANAGED_MAX_BYTES` is the managed-section relocation north-star (<=8192 B / ~2k tok)
+ * — Phase-2 success bar. `COMBINED_ALWAYS_ON_MAX_BYTES` is the Phase-3 combined always-on
+ * north-star (managed + DD-3 + hooks), raised to 9 KB after diminishing returns on further
+ * thinning (#2531 closeout).
+ *
  * When `plan.policy.agentsMdBudget.absoluteMaxBytes` is set, growth past that seeded
  * ratchet fails closed; distance-to-north-star is always reported. Optional release-gate
  * north-star enforcement: DEFT_AGENTS_MD_BUDGET_ENFORCE_NORTH_STAR=1 (waiver:
@@ -17,6 +21,9 @@ export type OutputStream = "stdout" | "stderr" | "none";
  */
 export declare const ABSOLUTE_MANAGED_MAX_BYTES = 8192;
 export declare const ABSOLUTE_MANAGED_MAX_TOKENS = 2000;
+/** Phase-3 combined always-on north-star (managed + DD-3 + hooks) — 9 KB (#2531). */
+export declare const COMBINED_ALWAYS_ON_MAX_BYTES = 9216;
+export declare const COMBINED_ALWAYS_ON_MAX_TOKENS = 2304;
 /** Bootstrap host hooks are 0 B until #2438 ships. */
 export declare const BOOTSTRAP_HOOK_BYTES = 0;
 /** Rough UTF-8 bytes-per-token estimate for advisory reporting (~8192 B ≈ ~2048 tok). */

package/dist/agents-md-budget/evaluate.js

@@ -7,7 +7,11 @@ import { measureSkillFrontmatter } from "./skill-frontmatter.js";
 /**
  * Layered absolute north-star for the always-on managed surface (#2372 / #2450 / #2452).
  *
- * `ABSOLUTE_MANAGED_MAX_BYTES` is the relocation north-star (<=8192 B / ~2k tok).
+ * `ABSOLUTE_MANAGED_MAX_BYTES` is the managed-section relocation north-star (<=8192 B / ~2k tok)
+ * — Phase-2 success bar. `COMBINED_ALWAYS_ON_MAX_BYTES` is the Phase-3 combined always-on
+ * north-star (managed + DD-3 + hooks), raised to 9 KB after diminishing returns on further
+ * thinning (#2531 closeout).
+ *
  * When `plan.policy.agentsMdBudget.absoluteMaxBytes` is set, growth past that seeded
  * ratchet fails closed; distance-to-north-star is always reported. Optional release-gate
  * north-star enforcement: DEFT_AGENTS_MD_BUDGET_ENFORCE_NORTH_STAR=1 (waiver:
@@ -20,6 +24,9 @@ import { measureSkillFrontmatter } from "./skill-frontmatter.js";
  */
 export const ABSOLUTE_MANAGED_MAX_BYTES = 8192;
 export const ABSOLUTE_MANAGED_MAX_TOKENS = 2000;
+/** Phase-3 combined always-on north-star (managed + DD-3 + hooks) — 9 KB (#2531). */
+export const COMBINED_ALWAYS_ON_MAX_BYTES = 9216;
+export const COMBINED_ALWAYS_ON_MAX_TOKENS = 2304;
 /** Bootstrap host hooks are 0 B until #2438 ships. */
 export const BOOTSTRAP_HOOK_BYTES = 0;
 /** Rough UTF-8 bytes-per-token estimate for advisory reporting (~8192 B ≈ ~2048 tok). */
@@ -186,7 +193,7 @@ function formatNorthStarOverage(measure) {
     return formatNorthStarOverageBytes(measure.bytes - ABSOLUTE_MANAGED_MAX_BYTES, measure.estimatedTokens - ABSOLUTE_MANAGED_MAX_TOKENS);
 }
 function formatCombinedNorthStarOverage(bootstrap) {
-    return formatNorthStarOverageBytes(bootstrap.totalBytes - ABSOLUTE_MANAGED_MAX_BYTES, bootstrap.totalEstimatedTokens - ABSOLUTE_MANAGED_MAX_TOKENS);
+    return formatNorthStarOverageBytes(bootstrap.totalBytes - COMBINED_ALWAYS_ON_MAX_BYTES, bootstrap.totalEstimatedTokens - COMBINED_ALWAYS_ON_MAX_TOKENS);
 }
 function formatNorthStarDistance(measure) {
     const overBytes = measure.bytes - ABSOLUTE_MANAGED_MAX_BYTES;
@@ -200,14 +207,14 @@ function formatNorthStarDistance(measure) {
         `${formatNorthStarOverage(measure)}).`);
 }
 function formatCombinedNorthStarDistance(bootstrap) {
-    const overBytes = bootstrap.totalBytes - ABSOLUTE_MANAGED_MAX_BYTES;
-    const overTokens = bootstrap.totalEstimatedTokens - ABSOLUTE_MANAGED_MAX_TOKENS;
+    const overBytes = bootstrap.totalBytes - COMBINED_ALWAYS_ON_MAX_BYTES;
+    const overTokens = bootstrap.totalEstimatedTokens - COMBINED_ALWAYS_ON_MAX_TOKENS;
     if (overBytes <= 0 && overTokens <= 0) {
         return (`north-star: combined always-on ${bootstrap.totalBytes} bytes ` +
             `(~${bootstrap.totalEstimatedTokens} tok) within ` +
-            `≤${ABSOLUTE_MANAGED_MAX_BYTES} B / ~${ABSOLUTE_MANAGED_MAX_TOKENS} tok target.`);
+            `≤${COMBINED_ALWAYS_ON_MAX_BYTES} B / ~${COMBINED_ALWAYS_ON_MAX_TOKENS} tok target.`);
     }
-    return (`north-star: combined always-on ≤${ABSOLUTE_MANAGED_MAX_BYTES} B / ~${ABSOLUTE_MANAGED_MAX_TOKENS} tok ` +
+    return (`north-star: combined always-on ≤${COMBINED_ALWAYS_ON_MAX_BYTES} B / ~${COMBINED_ALWAYS_ON_MAX_TOKENS} tok ` +
         `(current ${bootstrap.totalBytes} bytes / ~${bootstrap.totalEstimatedTokens} tok — ` +
         `${formatCombinedNorthStarOverage(bootstrap)}).`);
 }
@@ -224,12 +231,24 @@ function formatBootstrapItemization(bootstrap) {
 }
 function formatAbsoluteAdvisory(bootstrap) {
     const measure = bootstrap.managed;
+    const overManagedBytes = measure.bytes > ABSOLUTE_MANAGED_MAX_BYTES;
+    const overManagedTokens = measure.estimatedTokens > ABSOLUTE_MANAGED_MAX_TOKENS;
+    const overCombinedBytes = bootstrap.totalBytes > COMBINED_ALWAYS_ON_MAX_BYTES;
+    const overCombinedTokens = bootstrap.totalEstimatedTokens > COMBINED_ALWAYS_ON_MAX_TOKENS;
+    const violationLines = [];
+    if (overManagedBytes || overManagedTokens) {
+        violationLines.push(`  Managed section alone: ${measure.bytes} bytes (~${measure.estimatedTokens} tok) exceeds the north-star ` +
+            `of ${ABSOLUTE_MANAGED_MAX_BYTES} bytes / ~${ABSOLUTE_MANAGED_MAX_TOKENS} tok ` +
+            `(OVER: ${formatNorthStarOverage(measure)}).`);
+    }
+    if (overCombinedBytes || overCombinedTokens) {
+        violationLines.push(`  Combined always-on: ${bootstrap.totalBytes} bytes (~${bootstrap.totalEstimatedTokens} tok) exceeds the north-star ` +
+            `of ${COMBINED_ALWAYS_ON_MAX_BYTES} bytes / ~${COMBINED_ALWAYS_ON_MAX_TOKENS} tok ` +
+            `(OVER: ${formatCombinedNorthStarOverage(bootstrap)}).`);
+    }
     return (`⚠ verify:agents-md-budget: always-on bootstrap advisory — ` +
         `${formatBootstrapItemization(bootstrap)}.\n` +
-        `  Managed section alone: ${measure.bytes} bytes (~${measure.estimatedTokens} tok) exceeds the north-star ` +
-        `of ${ABSOLUTE_MANAGED_MAX_BYTES} bytes / ~${ABSOLUTE_MANAGED_MAX_TOKENS} tok ` +
-        `(OVER: ${formatNorthStarOverage(measure)}).\n` +
-        `  ${formatCombinedNorthStarDistance(bootstrap)}\n` +
+        `${violationLines.join("\n")}\n` +
         "  Advisory only — set plan.policy.agentsMdBudget.absoluteMaxBytes to enable " +
         "fail-closed managed growth ratchet (#2452).\n" +
         "  Optional DD-3 ratchet: plan.policy.agentsMdBudget.skillFrontmatterMaxBytes (#2463).\n" +
@@ -268,13 +287,29 @@ function formatSkillFrontmatterRefusal(bootstrap, skillFrontmatterMaxBytes, proj
 }
 function formatNorthStarRefusal(bootstrap, projectRoot) {
     const measure = bootstrap.managed;
-    const overBytes = bootstrap.totalBytes - ABSOLUTE_MANAGED_MAX_BYTES;
-    return (`❌ verify:agents-md-budget: combined always-on surface exceeds the north-star ceiling ` +
+    const overNorthStarManaged = measure.bytes > ABSOLUTE_MANAGED_MAX_BYTES ||
+        measure.estimatedTokens > ABSOLUTE_MANAGED_MAX_TOKENS;
+    const overNorthStarCombined = bootstrap.totalBytes > COMBINED_ALWAYS_ON_MAX_BYTES ||
+        bootstrap.totalEstimatedTokens > COMBINED_ALWAYS_ON_MAX_TOKENS;
+    const headline = overNorthStarManaged && overNorthStarCombined
+        ? "managed and combined always-on surfaces exceed the north-star ceiling"
+        : overNorthStarManaged
+            ? "managed section exceeds the north-star ceiling"
+            : "combined always-on surface exceeds the north-star ceiling";
+    const detailLines = [];
+    if (overNorthStarManaged) {
+        detailLines.push(`   managed section: ${measure.bytes}/${ABSOLUTE_MANAGED_MAX_BYTES} bytes ` +
+            `(OVER: ${formatNorthStarOverage(measure)})`);
+    }
+    if (overNorthStarCombined) {
+        detailLines.push(`   combined always-on: ${bootstrap.totalBytes}/${COMBINED_ALWAYS_ON_MAX_BYTES} bytes ` +
+            `(OVER: ${formatCombinedNorthStarOverage(bootstrap)})`);
+    }
+    return (`❌ verify:agents-md-budget: ${headline} ` +
         `(project_root=${projectRoot}, release-gate mode).\n` +
         `   ${formatBootstrapItemization(bootstrap)}\n` +
-        `   managed section: ${measure.bytes}/${ABSOLUTE_MANAGED_MAX_BYTES} bytes\n` +
-        `   combined OVER by ${overBytes} bytes vs north-star\n` +
-        "   Thin the managed section and/or tier DD-3 skills toward the <=8192 B target,\n" +
+        `${detailLines.join("\n")}\n` +
+        "   Thin the managed section and/or tier DD-3 skills toward the combined ≤9 KB target,\n" +
         "   or set DEFT_ALLOW_ABSOLUTE_BUDGET_WAIVER=1 for a time-boxed operator waiver (#2452).");
 }
 function enforceNorthStarEnabled() {
@@ -287,8 +322,8 @@ function attachNorthStarNote(result, bootstrap, options) {
     const measure = bootstrap.managed;
     const overManagedBytes = measure.bytes > ABSOLUTE_MANAGED_MAX_BYTES;
     const overManagedTokens = measure.estimatedTokens > ABSOLUTE_MANAGED_MAX_TOKENS;
-    const overCombinedBytes = bootstrap.totalBytes > ABSOLUTE_MANAGED_MAX_BYTES;
-    const overCombinedTokens = bootstrap.totalEstimatedTokens > ABSOLUTE_MANAGED_MAX_TOKENS;
+    const overCombinedBytes = bootstrap.totalBytes > COMBINED_ALWAYS_ON_MAX_BYTES;
+    const overCombinedTokens = bootstrap.totalEstimatedTokens > COMBINED_ALWAYS_ON_MAX_TOKENS;
     if (options.advisoryOnly) {
         if (!overManagedBytes && !overManagedTokens && !overCombinedBytes && !overCombinedTokens) {
             return result;
@@ -445,8 +480,8 @@ export function evaluate(projectRoot, options = {}) {
     }
     const overNorthStarManaged = measure.bytes > ABSOLUTE_MANAGED_MAX_BYTES ||
         measure.estimatedTokens > ABSOLUTE_MANAGED_MAX_TOKENS;
-    const overNorthStarCombined = bootstrap.totalBytes > ABSOLUTE_MANAGED_MAX_BYTES ||
-        bootstrap.totalEstimatedTokens > ABSOLUTE_MANAGED_MAX_TOKENS;
+    const overNorthStarCombined = bootstrap.totalBytes > COMBINED_ALWAYS_ON_MAX_BYTES ||
+        bootstrap.totalEstimatedTokens > COMBINED_ALWAYS_ON_MAX_TOKENS;
     if (enforceNorthStarEnabled() &&
         (overNorthStarManaged || overNorthStarCombined) &&
         !northStarWaiverActive()) {

package/dist/content-contracts/skills/skill-frontmatter.js

@@ -11,6 +11,10 @@ const EXCLUDED_PARTS = new Set([
     "node_modules",
     "__pycache__",
     ".pytest_cache",
+    ".deft-scratch",
+    ".deft-cache",
+    "coverage",
+    "dist",
 ]);
 function frontmatter(text) {
     if (!text.startsWith("---")) {

package/dist/doctor/constants.js

@@ -29,13 +29,13 @@ export const DOCTOR_ALLOWED_FLAGS = [
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
 export const NPM_PACKAGE_NAME = "@deftai/directive";
 // #2182: payload-staleness is the only doctor check that can reach a network
-// endpoint (git ls-remote against the framework's git remote, falling back to
-// `npm view` against the npm registry). It is OFF by default (offline tier)
+// endpoint (git ls-remote verifies the pinned ref and `npm view` compares a
+// release-tag install with the latest stable package). It is OFF by default (offline tier)
 // and requires the explicit `--network` flag; this line discloses exactly
 // which tool + registry class it may contact BEFORE the check runs, and the
 // skip line tells an offline run how to opt in.
 export const NETWORK_DISCLOSURE_LINE = "[deft doctor] --network: this run may contact your git remote (framework " +
-    "repo host) and, as a fallback, the npm registry (registry.npmjs.org) to " +
+    "repo host) and the npm registry (registry.npmjs.org) to " +
     `look up the latest ${NPM_PACKAGE_NAME} version.`;
 export const PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE = "skip -- offline tier (default). Run `deft doctor --network` to check " +
     "framework currency against your git remote and the npm registry " +

package/dist/doctor/index.d.ts

@@ -8,6 +8,7 @@ export * from "./main.js";
 export * from "./manifest.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
+export * from "./release-availability.js";
 export * from "./taskfile.js";
 export * from "./types.js";
 export * from "./which.js";

package/dist/doctor/index.js

@@ -8,6 +8,7 @@ export * from "./main.js";
 export * from "./manifest.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
+export * from "./release-availability.js";
 export * from "./taskfile.js";
 export * from "./types.js";
 export * from "./which.js";

package/dist/doctor/main.js

@@ -163,7 +163,8 @@ export function cmdDoctor(args, seams = {}) {
         sink.blank();
     }
     // #2182: payload-staleness is the only doctor check that can reach a
-    // registry (git remote, then npm as a fallback). It stays in the OFFLINE
+    // registry (git verifies the pin; npm compares stable release availability).
+    // It stays in the OFFLINE
     // tier (skipped) unless the operator explicitly opts into the NETWORK tier
     // via `--network`, and the tool + registry class is disclosed BEFORE the
     // check runs -- never silently, never as a side effect of a read-only

package/dist/doctor/payload-staleness.js

@@ -4,6 +4,7 @@ import { detectCanonicalVendoredManifest, isNpmManaged } from "../init-deposit/m
 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";
+import { evaluateReleaseAvailability } from "./release-availability.js";
 function isDeftFrameworkRepo(projectRoot, readText = readTextSafe) {
     try {
         const agents = join(projectRoot, "AGENTS.md");
@@ -38,42 +39,6 @@ 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",
@@ -82,6 +47,25 @@ function defaultNpmViewVersion() {
     const version = (proc.stdout ?? "").trim().split("\n")[0]?.trim() ?? "";
     return { ok: proc.status === 0 && version.length > 0, version };
 }
+function emitReleaseAvailable(checkName, installedVersion, latestVersion, ref, upgradeCommand, sink, addFinding) {
+    const msg = `Newer framework release available (installed v${installedVersion}; ` +
+        `latest v${latestVersion} from npm registry). ` +
+        `Recommendation: run \`${upgradeCommand}\`.`;
+    sink.warn(msg);
+    addFinding({
+        severity: "warning",
+        message: msg,
+        check: checkName,
+        status: "stale",
+        staleness_kind: "newer-release",
+        ref,
+        installed_version: installedVersion,
+        latest_version: latestVersion,
+        remote_version: latestVersion,
+        resolver: "npm-view",
+        suggestion: upgradeCommand,
+    });
+}
 function emitUnverified(checkName, reason, sink, addFinding) {
     const msg = `payload currency UNVERIFIED — ${reason}`;
     sink.warn(msg);
@@ -101,8 +85,8 @@ function resolveUpgradeCommand(projectRoot, manifest, isFile, pm = "npm") {
     }
     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}'). ` +
+function emitStale(checkName, installedLabel, remoteLabel, ref, upgradeCommand, sink, addFinding, extras = {}) {
+    const msg = `Framework payload is stale (installed ${installedLabel} behind remote ${remoteLabel} for ref '${ref}'). ` +
         `Recommendation: run \`${upgradeCommand}\` from any shell with Node ≥ 20.`;
     sink.warn(msg);
     addFinding({
@@ -209,37 +193,52 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
     catch {
         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, upgradeCommand, sink, addFinding, { installed_sha: installedSha, remote_sha: remoteSha, resolver: "git-ls-remote" });
-            return;
-        }
+    const remoteSha = remoteResult.ok ? parseRemoteSha(remoteResult.stdout) : "";
+    if (remoteSha && installedSha !== remoteSha) {
+        emitStale(checkName, `sha ${installedSha.slice(0, 8)}...`, `sha ${remoteSha.slice(0, 8)}...`, ref, upgradeCommand, sink, addFinding, {
+            installed_sha: installedSha,
+            remote_sha: remoteSha,
+            resolver: "git-ls-remote",
+            staleness_kind: "pinned-ref-moved",
+        });
+        return;
     }
-    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, upgradeCommand, 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)`);
+    const installedCandidate = (tag || ref).trim().replace(/^refs\/tags\//, "");
+    const applicability = evaluateReleaseAvailability(installedCandidate, null);
+    if (applicability.status === "not-applicable") {
+        if (remoteSha && installedSha === remoteSha) {
+            sink.info(`${checkName}: current (sha matches remote; ref is not a release tag)`);
             return;
         }
-        sink.info(`${checkName}: current (installed version >= npm registry)`);
+        const reason = remoteResult.ok
+            ? "ls-remote produced no sha; ref is not a release tag"
+            : "could not reach remote; ref is not a release tag";
+        sink.info(`${checkName}: skip -- ${reason}`);
+        emitUnverified(checkName, reason, sink, addFinding);
+        return;
+    }
+    let npmResult;
+    try {
+        npmResult = runNpmView();
+    }
+    catch {
+        npmResult = { ok: false, version: "" };
+    }
+    const availability = evaluateReleaseAvailability(installedCandidate, npmResult.ok ? npmResult.version : null);
+    if (availability.status === "available") {
+        emitReleaseAvailable(checkName, availability.installedVersion, availability.latestVersion, ref, upgradeCommand, sink, addFinding);
+        return;
+    }
+    if (availability.status === "current") {
+        sink.info(`${checkName}: current (installed release >= npm latest)`);
+        return;
+    }
+    if (availability.status === "prerelease-ignored") {
+        sink.info(`${checkName}: current (npm candidate is a prerelease; stable install retained)`);
         return;
     }
     const reason = remoteResult.ok
-        ? "ls-remote produced no sha and npm registry fallback unavailable"
+        ? "npm registry release lookup unavailable or returned a non-publishable version"
         : "could not reach remote (git ls-remote / npm view both unavailable)";
     sink.info(`${checkName}: skip -- ${reason}`);
     emitUnverified(checkName, reason, sink, addFinding);

package/dist/doctor/release-availability.d.ts

@@ -0,0 +1,28 @@
+/** Outcomes produced by the reusable latest-release comparison. */
+export type ReleaseAvailabilityStatus = "available" | "current" | "prerelease-ignored" | "not-applicable" | "unverified";
+/** Network resolver that supplied the latest published version. */
+export type ReleaseAvailabilityResolver = "npm-view";
+/** Typed result consumed by doctor today and safe-idle upgrade prompting later. */
+export type ReleaseAvailabilityResult = {
+    readonly status: "available" | "current" | "prerelease-ignored";
+    readonly installedVersion: string;
+    readonly latestVersion: string;
+    readonly resolver: ReleaseAvailabilityResolver;
+} | {
+    readonly status: "not-applicable";
+    readonly installedVersion: null;
+    readonly latestVersion: string | null;
+    readonly resolver: ReleaseAvailabilityResolver;
+} | {
+    readonly status: "unverified";
+    readonly installedVersion: string;
+    readonly latestVersion: null;
+    readonly resolver: ReleaseAvailabilityResolver;
+};
+/**
+ * Compare an installed release with a resolver-provided latest release.
+ * Stable installs deliberately ignore prerelease candidates even when their
+ * numeric core is newer.
+ */
+export declare function evaluateReleaseAvailability(installed: string, latest: string | null, resolver?: ReleaseAvailabilityResolver): ReleaseAvailabilityResult;
+//# sourceMappingURL=release-availability.d.ts.map

package/dist/doctor/release-availability.js

@@ -0,0 +1,35 @@
+import { comparePublishableVersions, isPrereleaseTag, isPublishable } from "../release/version.js";
+function normalizePublishableVersion(version) {
+    if (version === null)
+        return null;
+    const candidate = version.trim().replace(/^refs\/tags\//, "");
+    if (!candidate || !isPublishable(candidate))
+        return null;
+    return candidate.replace(/^v/, "");
+}
+/**
+ * Compare an installed release with a resolver-provided latest release.
+ * Stable installs deliberately ignore prerelease candidates even when their
+ * numeric core is newer.
+ */
+export function evaluateReleaseAvailability(installed, latest, resolver = "npm-view") {
+    const installedVersion = normalizePublishableVersion(installed);
+    const latestVersion = normalizePublishableVersion(latest);
+    if (installedVersion === null) {
+        return { status: "not-applicable", installedVersion, latestVersion, resolver };
+    }
+    if (latestVersion === null) {
+        return { status: "unverified", installedVersion, latestVersion, resolver };
+    }
+    if (!isPrereleaseTag(installedVersion) && isPrereleaseTag(latestVersion)) {
+        return { status: "prerelease-ignored", installedVersion, latestVersion, resolver };
+    }
+    const comparison = comparePublishableVersions(installedVersion, latestVersion);
+    return {
+        status: comparison < 0 ? "available" : "current",
+        installedVersion,
+        latestVersion,
+        resolver,
+    };
+}
+//# sourceMappingURL=release-availability.js.map

package/dist/eval/crud-telemetry.d.ts

@@ -1,4 +1,5 @@
-export declare const CRUD_METRICS_HISTORY_REL = "results/crud-metrics.jsonl";
+/** Relative path under the resolved metrics home for helped / value telemetry (#2545). */
+export declare const CRUD_METRICS_HISTORY_REL = "helped/crud-metrics.jsonl";
 export type CrudOperation = "create" | "read" | "update" | "delete";
 export type ByteDiffMinimality = "surgical" | "whole-file-rewrite";
 export interface CrudOperationMetric {
@@ -31,9 +32,9 @@ export declare function classifyByteDiffMinimality(before: string, after: string
     readonly kind: ByteDiffMinimality;
     readonly changedRatio: number;
 };
-/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1). */
-export declare function crudMetricsHistoryPath(projectRoot: string): string;
-/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1). */
+/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1 / #2545). */
+export declare function crudMetricsHistoryPath(projectRoot: string): string | null;
+/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1 / #2545). */
 export declare function persistCrudMetrics(projectRoot: string, metrics: readonly CrudOperationMetric[]): void;
 /**
  * Instrumented vBRIEF/xBRIEF CRUD chokepoint (#1703 Tier 1).

package/dist/eval/crud-telemetry.js

@@ -1,10 +1,11 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 import { readCorePackageVersion } from "../engine-version.js";
-import { resolveEvalPath } from "../layout/resolve.js";
+import { helpedMetricsHistoryPath } from "../metrics/resolve-metrics-home.js";
 import { scanVbrief } from "../vbrief-validate/conformance.js";
 import { validateVbriefSchema } from "../vbrief-validate/schema.js";
-export const CRUD_METRICS_HISTORY_REL = "results/crud-metrics.jsonl";
+/** Relative path under the resolved metrics home for helped / value telemetry (#2545). */
+export const CRUD_METRICS_HISTORY_REL = "helped/crud-metrics.jsonl";
 /** Whole-file rewrites change at least half of the bytes or re-serialize with high drift. */
 export const BYTE_DIFF_WHOLE_FILE_THRESHOLD = 0.5;
 function isRecord(value) {
@@ -85,16 +86,19 @@ function sanitizeInlineMessage(message) {
 function ensureParentDir(path) {
     mkdirSync(dirname(path), { recursive: true });
 }
-/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1). */
+/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1 / #2545). */
 export function crudMetricsHistoryPath(projectRoot) {
-    return resolveEvalPath(projectRoot, CRUD_METRICS_HISTORY_REL);
+    return helpedMetricsHistoryPath(projectRoot);
 }
-/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1). */
+/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1 / #2545). */
 export function persistCrudMetrics(projectRoot, metrics) {
     if (metrics.length === 0) {
         return;
     }
     const path = crudMetricsHistoryPath(projectRoot);
+    if (path === null) {
+        return;
+    }
     mkdirSync(dirname(path), { recursive: true });
     for (const metric of metrics) {
         appendFileSync(path, `${JSON.stringify(metric)}\n`, "utf8");

package/dist/eval/health.d.ts

@@ -1,5 +1,6 @@
 export declare const HEALTH_SCHEMA_VERSION: 1;
-export declare const HEALTH_HISTORY_REL = "results/health-history.jsonl";
+/** Relative path under the resolved metrics home for eval:health history (#2545). */
+export declare const HEALTH_HISTORY_REL = "health/health-history.jsonl";
 /** One static Tier-0 gate probe aggregated into the health score. */
 export interface GateProbeResult {
     readonly id: string;
@@ -37,15 +38,15 @@ export interface EvaluateHealthResult {
     readonly report: HealthReport | null;
     readonly message: string;
 }
-/** Absolute path to the versioned health history ledger. */
-export declare function healthHistoryPath(projectRoot: string): string;
+/** Absolute path to the versioned health history ledger (#2545). */
+export declare function healthHistoryPath(projectRoot: string): string | null;
 /** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
 export declare function detectWipCapUnsatisfiableNudge(projectRoot: string): ContradictionEvidence | null;
 /** Run all registered contradictory-gate detectors. */
 export declare function detectContradictoryGates(projectRoot: string): ContradictionEvidence[];
 /** Compute a 0-100 score from gate pass rate minus contradiction penalty. */
 export declare function computeHealthScore(gates: readonly GateProbeResult[], contradictions: readonly ContradictionEvidence[]): number;
-/** Append one health run to the versioned ledger (#1703 Tier 0). */
+/** Append one health run to the versioned ledger (#1703 Tier 0 / #2545). */
 export declare function persistHealthRun(projectRoot: string, report: HealthReport): void;
 /** Aggregate Tier-0 static gates into a versioned framework health score (#1703). */
 export declare function evaluateHealth(options?: EvaluateHealthOptions): EvaluateHealthResult;

package/dist/eval/health.js

@@ -3,7 +3,8 @@ import { dirname, resolve } from "node:path";
 import { agentsRefreshPlan } from "../doctor/agents-md.js";
 import { evaluate as evaluateEncoding } from "../encoding/evaluate.js";
 import { readCorePackageVersion } from "../engine-version.js";
-import { resolveEvalPath, resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { healthMetricsHistoryPath } from "../metrics/resolve-metrics-home.js";
 import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { classifyOnboarding, detectPriorState } from "../triage/welcome/prior-state.js";
 import { validateLinks } from "../validate-content/index.js";
@@ -11,7 +12,8 @@ import { evaluateConformance } from "../vbrief-validate/conformance.js";
 import { validateWipCapOnPlan } from "../vbrief-validate/plan-hooks.js";
 import { evaluateContentManifest } from "../verify-source/content-manifest.js";
 export const HEALTH_SCHEMA_VERSION = 1;
-export const HEALTH_HISTORY_REL = "results/health-history.jsonl";
+/** Relative path under the resolved metrics home for eval:health history (#2545). */
+export const HEALTH_HISTORY_REL = "health/health-history.jsonl";
 function sanitizeOneLine(value) {
     return value.replace(/\r?\n/g, " ");
 }
@@ -99,9 +101,9 @@ function probeContentManifest(projectRoot) {
         detail: result.code === 0 ? undefined : result.message.split("\n")[0],
     };
 }
-/** Absolute path to the versioned health history ledger. */
+/** Absolute path to the versioned health history ledger (#2545). */
 export function healthHistoryPath(projectRoot) {
-    return resolveEvalPath(projectRoot, HEALTH_HISTORY_REL);
+    return healthMetricsHistoryPath(projectRoot);
 }
 /** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
 export function detectWipCapUnsatisfiableNudge(projectRoot) {
@@ -154,9 +156,12 @@ export function computeHealthScore(gates, contradictions) {
     const penalty = contradictions.length * 15;
     return Math.max(0, base - penalty);
 }
-/** Append one health run to the versioned ledger (#1703 Tier 0). */
+/** Append one health run to the versioned ledger (#1703 Tier 0 / #2545). */
 export function persistHealthRun(projectRoot, report) {
     const path = healthHistoryPath(projectRoot);
+    if (path === null) {
+        return;
+    }
     mkdirSync(dirname(path), { recursive: true });
     appendFileSync(path, `${JSON.stringify(report)}\n`, "utf8");
 }
@@ -223,17 +228,20 @@ export function evaluateHealth(options = {}) {
         contradictions,
     };
     if (persist) {
-        try {
-            persistHealthRun(projectRoot, report);
-        }
-        catch (err) {
-            const persistError = `eval:health: failed to persist health history: ${String(err)}`;
-            const healthy = score === 100 && contradictions.length === 0;
-            return {
-                code: healthy ? 0 : 1,
-                report,
-                message: `${formatHumanReport(report)}\n${persistError}`,
-            };
+        const ledgerPath = healthHistoryPath(projectRoot);
+        if (ledgerPath !== null) {
+            try {
+                persistHealthRun(projectRoot, report);
+            }
+            catch (err) {
+                const persistError = `eval:health: failed to persist health history: ${String(err)}`;
+                const healthy = score === 100 && contradictions.length === 0;
+                return {
+                    code: healthy ? 0 : 1,
+                    report,
+                    message: `${formatHumanReport(report)}\n${persistError}`,
+                };
+            }
         }
     }
     const healthy = score === 100 && contradictions.length === 0;

package/dist/eval/readback.js

@@ -28,14 +28,8 @@ function parseJsonObjectOrNull(text) {
     return null;
 }
 function readHealthHistoryRows(projectRoot) {
-    let path;
-    try {
-        path = healthHistoryPath(projectRoot);
-    }
-    catch {
-        return []; // No xbrief/ layout; no health history.
-    }
-    if (!existsSync(path)) {
+    const path = healthHistoryPath(projectRoot);
+    if (path === null || !existsSync(path)) {
         return [];
     }
     let text;

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
+export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
 export * as platform from "./platform/index.js";