@deftai/directive-core 0.75.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

@@ -1,12 +1,17 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { getOpenPackageDefaultInstallTier, resolveOpenPackageTierSkills, } from "../packaging/openpackage-tiers.js";
 import { AGENTS_MANAGED_CLOSE } from "../platform/constants.js";
 import { resolveAgentsMdBudget, } from "../policy/agents-md-budget.js";
 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:
@@ -19,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). */
@@ -123,12 +131,23 @@ function resolveHarnessProfile(budget, projectRoot) {
     }
     return "none";
 }
-function resolveSkillFrontmatterTier(budget) {
+function resolveBootstrapSkillTier(budget, projectRoot) {
     const env = process.env.DEFT_AGENTS_MD_BUDGET_SKILL_TIER?.trim();
     if (env === "daily-core" || env === "all" || env === "none") {
         return env;
     }
-    return budget?.skillFrontmatterTier ?? "all";
+    if (budget?.skillFrontmatterTier !== undefined) {
+        return budget.skillFrontmatterTier;
+    }
+    try {
+        if (getOpenPackageDefaultInstallTier(projectRoot) === "daily-core") {
+            return "daily-core";
+        }
+    }
+    catch {
+        // No OpenPackage manifest at this project root — fall through.
+    }
+    return "all";
 }
 /** Measure managed + DD-3 skill frontmatter + bootstrap hooks. */
 export function measureBootstrapSurface(projectRoot, managedText, budget) {
@@ -137,11 +156,19 @@ export function measureBootstrapSurface(projectRoot, managedText, budget) {
         return managedResult;
     }
     const harnessProfile = resolveHarnessProfile(budget, projectRoot);
-    const tier = resolveSkillFrontmatterTier(budget);
+    const tier = resolveBootstrapSkillTier(budget, projectRoot);
+    let dailyCoreSkills;
+    try {
+        dailyCoreSkills = resolveOpenPackageTierSkills(projectRoot, "daily-core");
+    }
+    catch {
+        // Maintainer trees without packaging/openpackage fall back to hardcoded daily-core.
+    }
     const skillFrontmatter = measureSkillFrontmatter(projectRoot, {
         harnessProfile,
         tier,
         bytesPerToken: ABSOLUTE_BYTES_PER_TOKEN_ESTIMATE,
+        dailyCoreSkills,
     });
     const totalBytes = managedResult.bytes + skillFrontmatter.bytes + BOOTSTRAP_HOOK_BYTES;
     return {
@@ -166,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;
@@ -180,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)}).`);
 }
@@ -204,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" +
@@ -248,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() {
@@ -267,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;
@@ -425,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/agents-md-budget/skill-frontmatter.d.ts

@@ -27,6 +27,8 @@ export interface MeasureSkillFrontmatterOptions {
     readonly tier?: SkillFrontmatterTier;
     readonly harnessProfile?: HarnessProfile;
     readonly bytesPerToken?: number;
+    /** Override daily-core skill names (from OpenPackage resolveTierSkills). */
+    readonly dailyCoreSkills?: readonly string[];
 }
 /** Measure harness-injected skill frontmatter bytes for the configured profile/tier. */
 export declare function measureSkillFrontmatter(projectRoot: string, options?: MeasureSkillFrontmatterOptions): SkillFrontmatterMeasure;

package/dist/agents-md-budget/skill-frontmatter.js

@@ -61,14 +61,14 @@ function listSkillDirs(skillsRoot) {
         .map((entry) => entry.name)
         .sort();
 }
-function skillMatchesTier(skillName, tier) {
+function skillInSelectedTier(skillName, tier, dailyCore) {
     if (tier === "none") {
         return false;
     }
     if (tier === "all") {
         return true;
     }
-    return DAILY_CORE_SET.has(skillName);
+    return dailyCore.has(skillName);
 }
 /** Measure harness-injected skill frontmatter bytes for the configured profile/tier. */
 export function measureSkillFrontmatter(projectRoot, options = {}) {
@@ -76,6 +76,7 @@ export function measureSkillFrontmatter(projectRoot, options = {}) {
     const tier = options.tier ?? "all";
     const bytesPerToken = options.bytesPerToken ?? 4;
     const skillsRoot = options.skillsRoot ?? defaultSkillsRoot(projectRoot);
+    const dailyCore = options.dailyCoreSkills !== undefined ? new Set(options.dailyCoreSkills) : DAILY_CORE_SET;
     if (harnessProfile === "none" || tier === "none") {
         return {
             bytes: 0,
@@ -88,7 +89,7 @@ export function measureSkillFrontmatter(projectRoot, options = {}) {
     }
     const entries = [];
     for (const skillName of listSkillDirs(skillsRoot)) {
-        if (!skillMatchesTier(skillName, tier)) {
+        if (!skillInSelectedTier(skillName, tier, dailyCore)) {
             continue;
         }
         const skillPath = join(skillsRoot, skillName, "SKILL.md");

package/dist/cache/operations.d.ts

@@ -1,7 +1,9 @@
+import { ProjectionContainmentError } from "../fs/projection-containment.js";
 import { type CacheCaps, type EntryUsage } from "./quota.js";
 import { SCANNER_VERSION } from "./scanner.js";
 import { type Clock } from "./time.js";
 import type { CacheGetOptions, CachePutOptions, GetResult, PutResult } from "./types.js";
+export { ProjectionContainmentError as CacheContainmentError };
 /** Write a cache entry (mirrors `cache.cache_put`). */
 export declare function cachePut(source: string, key: string, raw: Record<string, unknown>, options?: CachePutOptions): PutResult;
 /** Read a cache entry (mirrors `cache.cache_get`). */

package/dist/cache/operations.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { pyRepr } from "../scm/py-format.js";
 import { ALLOWED_SOURCES, REPO_RE, SOURCE_TTL_SECONDS } from "./constants.js";
 import { CacheCapBreachedError, CacheError, CacheNotFoundError, CacheValidationError, } from "./errors.js";
@@ -10,6 +11,15 @@ import { enforceCaps, predictEvictionSet, resolveCaps, } from "./quota.js";
 import { flagsForMeta, SCANNER_VERSION, scan } from "./scanner.js";
 import { addSeconds, parseIso, systemClock, utcIso } from "./time.js";
 import { validateMeta } from "./validate.js";
+export { ProjectionContainmentError as CacheContainmentError };
+/** Refuse symlink-escaping `.deft-cache` before mkdir/read/write (#2470). */
+function assertWritableCachePath(cacheRoot, ...segments) {
+    const cacheAbs = resolve(cacheRoot);
+    const projectDir = dirname(cacheAbs);
+    const target = segments.length > 0 ? join(cacheAbs, ...segments) : cacheAbs;
+    assertProjectionContained(projectDir, target);
+    return target;
+}
 function renderContent(source, raw) {
     if (source === "github-issue") {
         const number = raw.number;
@@ -82,6 +92,7 @@ export function cachePut(source, key, raw, options = {}) {
     }
     const expires = addSeconds(fetched, ttl);
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    assertWritableCachePath(cacheRoot);
     const edir = entryDir(source, key, cacheRoot);
     const rawText = pythonJsonDump(raw);
     const rawSize = Buffer.byteLength(rawText, "utf8");
@@ -182,6 +193,7 @@ export function cachePut(source, key, raw, options = {}) {
 export function cacheGet(source, key, options = {}) {
     const clock = options.clock ?? systemClock;
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    assertWritableCachePath(cacheRoot);
     const allowStale = options.allowStale ?? true;
     const edir = entryDir(source, key, cacheRoot);
     const metaRelPath = `${source}/${key}/meta.json`;
@@ -220,6 +232,7 @@ export function cacheInvalidate(source, key, options = {}) {
     const clock = options.clock ?? systemClock;
     validateKey(source, key);
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    assertWritableCachePath(cacheRoot);
     const edir = entryDir(source, key, cacheRoot);
     const existed = existsSync(edir);
     if (existed)
@@ -252,6 +265,7 @@ export function cachePrune(options = {}) {
         throw new CacheError(`--older-than-days must be >= 0 (got ${JSON.stringify(olderThanDays)})`);
     }
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    assertWritableCachePath(cacheRoot);
     if (!existsSync(cacheRoot))
         return [];
     const cutoff = addSeconds(clock.now(), -olderThanDays * 24 * 60 * 60);
@@ -313,6 +327,7 @@ function collectMetaPathsUnder(srcRoot) {
 export function cachePruneToCap(options = {}) {
     const clock = options.clock ?? systemClock;
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    assertWritableCachePath(cacheRoot);
     const resolved = options.caps ?? resolveCaps();
     if (!resolved.maxBytes && !resolved.maxEntries)
         return [];

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).