@deftai/directive-core 0.74.0 → 0.76.0

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

@@ -1,9 +1,51 @@
+import { type AgentsMdBudget } from "../policy/agents-md-budget.js";
+import { type SkillFrontmatterMeasure } from "./skill-frontmatter.js";
 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).
+ * 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:
+ * DEFT_ALLOW_ABSOLUTE_BUDGET_WAIVER=1).
+ *
+ * DD-3 (harness-injected skill frontmatter) is measured and itemized (#2463).
+ * Managed `absoluteMaxBytes` remains the fail-closed ratchet for the rendered
+ * managed section; skill-frontmatter caps are advisory unless
+ * `skillFrontmatterMaxBytes` is set (or enforced via env).
+ */
+export declare const ABSOLUTE_MANAGED_MAX_BYTES = 8192;
+export declare const ABSOLUTE_MANAGED_MAX_TOKENS = 2000;
+/** 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). */
+export declare const ABSOLUTE_BYTES_PER_TOKEN_ESTIMATE = 4;
+/** Byte + estimated-token measure of the managed section body. */
+export interface ManagedSectionMeasure {
+    readonly bytes: number;
+    readonly estimatedTokens: number;
+}
+/** Itemized always-on bootstrap surface (managed + DD-3 + hooks). */
+export interface BootstrapMeasure {
+    readonly managed: ManagedSectionMeasure;
+    readonly skillFrontmatter: SkillFrontmatterMeasure;
+    readonly bootstrapHookBytes: number;
+    readonly totalBytes: number;
+    readonly totalEstimatedTokens: number;
+}
 /** Result of verify:agents-md-budget evaluation; three-state exit contract. */
 export interface EvaluateResult {
     readonly code: 0 | 1 | 2;
     readonly message: string;
     readonly stream: OutputStream;
+    /** North-star distance note (#2452); may accompany success or failure paths. */
+    readonly northStarMessage?: string;
+    readonly northStarStream?: OutputStream;
+    /** @deprecated Use northStarMessage — retained for one release of CLI compat. */
+    readonly advisoryMessage?: string;
+    /** @deprecated Use northStarStream — retained for one release of CLI compat. */
+    readonly advisoryStream?: OutputStream;
 }
 export interface EvaluateOptions {
     readonly quiet?: boolean;
@@ -26,6 +68,25 @@ export declare function countRegions(text: string): {
 } | {
     error: string;
 };
+/**
+ * Extract the managed-section span (open marker through close marker, inclusive).
+ *
+ * Returns an empty section when no markers are present — consistent with
+ * `countRegions` treating markerless files as entirely unmanaged.
+ */
+export declare function extractManagedSection(text: string): {
+    section: string;
+} | {
+    error: string;
+};
+/** Measure UTF-8 byte length and a rough token estimate for the managed section. */
+export declare function measureManagedSection(text: string): ManagedSectionMeasure | {
+    error: string;
+};
+/** Measure managed + DD-3 skill frontmatter + bootstrap hooks. */
+export declare function measureBootstrapSurface(projectRoot: string, managedText: string, budget: AgentsMdBudget | null): BootstrapMeasure | {
+    error: string;
+};
 /**
  * Pure evaluator for the AGENTS.md line-budget ratchet gate (#645).
  *

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

@@ -1,7 +1,29 @@
 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 { 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).
+ * 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:
+ * DEFT_ALLOW_ABSOLUTE_BUDGET_WAIVER=1).
+ *
+ * DD-3 (harness-injected skill frontmatter) is measured and itemized (#2463).
+ * Managed `absoluteMaxBytes` remains the fail-closed ratchet for the rendered
+ * managed section; skill-frontmatter caps are advisory unless
+ * `skillFrontmatterMaxBytes` is set (or enforced via env).
+ */
+export const ABSOLUTE_MANAGED_MAX_BYTES = 8192;
+export const ABSOLUTE_MANAGED_MAX_TOKENS = 2000;
+/** 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). */
+export const ABSOLUTE_BYTES_PER_TOKEN_ESTIMATE = 4;
 const OPEN_MARKER_PREFIX = "<!-- deft:managed-section";
 /**
  * Split AGENTS.md into managed / unmanaged line counts.
@@ -42,6 +64,257 @@ export function countRegions(text) {
     const managed = closeLine - openLine + 1;
     return { counts: { total, managed, unmanaged: total - managed } };
 }
+/**
+ * Extract the managed-section span (open marker through close marker, inclusive).
+ *
+ * Returns an empty section when no markers are present — consistent with
+ * `countRegions` treating markerless files as entirely unmanaged.
+ */
+export function extractManagedSection(text) {
+    const normalized = text.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    const openLine = lines.findIndex((l) => l.startsWith(OPEN_MARKER_PREFIX));
+    const closeLine = lines.findIndex((l) => l.trim().startsWith(AGENTS_MANAGED_CLOSE));
+    const openCount = lines.filter((l) => l.startsWith(OPEN_MARKER_PREFIX)).length;
+    const closeCount = lines.filter((l) => l.trim().startsWith(AGENTS_MANAGED_CLOSE)).length;
+    if (openLine === -1 && closeLine === -1) {
+        return { section: "" };
+    }
+    if (openLine === -1 ||
+        closeLine === -1 ||
+        closeLine < openLine ||
+        openCount > 1 ||
+        closeCount > 1) {
+        return {
+            error: "AGENTS.md managed-section markers are malformed " +
+                `(open@${openLine === -1 ? "none" : openLine + 1}×${openCount}, ` +
+                `close@${closeLine === -1 ? "none" : closeLine + 1}×${closeCount}); ` +
+                "expected a single <!-- deft:managed-section ... --> ... " +
+                "<!-- /deft:managed-section --> pair.",
+        };
+    }
+    return { section: lines.slice(openLine, closeLine + 1).join("\n") };
+}
+/** Measure UTF-8 byte length and a rough token estimate for the managed section. */
+export function measureManagedSection(text) {
+    const extracted = extractManagedSection(text);
+    if ("error" in extracted) {
+        return extracted;
+    }
+    const bytes = Buffer.byteLength(extracted.section, "utf8");
+    return {
+        bytes,
+        estimatedTokens: Math.ceil(bytes / ABSOLUTE_BYTES_PER_TOKEN_ESTIMATE),
+    };
+}
+function resolveHarnessProfile(budget, projectRoot) {
+    const env = process.env.DEFT_AGENTS_MD_BUDGET_HARNESS_PROFILE?.trim();
+    if (env === "cursor" || env === "none") {
+        return env;
+    }
+    if (budget?.harnessProfile !== undefined) {
+        return budget.harnessProfile;
+    }
+    const skillsRoot = join(projectRoot, "content", "skills");
+    if (existsSync(skillsRoot)) {
+        return "cursor";
+    }
+    return "none";
+}
+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;
+    }
+    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) {
+    const managedResult = measureManagedSection(managedText);
+    if ("error" in managedResult) {
+        return managedResult;
+    }
+    const harnessProfile = resolveHarnessProfile(budget, projectRoot);
+    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 {
+        managed: managedResult,
+        skillFrontmatter,
+        bootstrapHookBytes: BOOTSTRAP_HOOK_BYTES,
+        totalBytes,
+        totalEstimatedTokens: Math.ceil(totalBytes / ABSOLUTE_BYTES_PER_TOKEN_ESTIMATE),
+    };
+}
+function formatNorthStarOverageBytes(overBytes, overTokens) {
+    const parts = [];
+    if (overBytes > 0) {
+        parts.push(`${overBytes} bytes over`);
+    }
+    if (overTokens > 0) {
+        parts.push(`~${overTokens} tok over`);
+    }
+    return parts.join(", ");
+}
+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);
+}
+function formatNorthStarDistance(measure) {
+    const overBytes = measure.bytes - ABSOLUTE_MANAGED_MAX_BYTES;
+    const overTokens = measure.estimatedTokens - ABSOLUTE_MANAGED_MAX_TOKENS;
+    if (overBytes <= 0 && overTokens <= 0) {
+        return (`north-star: managed ${measure.bytes} bytes (~${measure.estimatedTokens} tok) within ` +
+            `≤${ABSOLUTE_MANAGED_MAX_BYTES} B / ~${ABSOLUTE_MANAGED_MAX_TOKENS} tok target.`);
+    }
+    return (`north-star: managed ≤${ABSOLUTE_MANAGED_MAX_BYTES} B / ~${ABSOLUTE_MANAGED_MAX_TOKENS} tok ` +
+        `(current ${measure.bytes} bytes / ~${measure.estimatedTokens} tok — ` +
+        `${formatNorthStarOverage(measure)}).`);
+}
+function formatCombinedNorthStarDistance(bootstrap) {
+    const overBytes = bootstrap.totalBytes - ABSOLUTE_MANAGED_MAX_BYTES;
+    const overTokens = bootstrap.totalEstimatedTokens - ABSOLUTE_MANAGED_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.`);
+    }
+    return (`north-star: combined always-on ≤${ABSOLUTE_MANAGED_MAX_BYTES} B / ~${ABSOLUTE_MANAGED_MAX_TOKENS} tok ` +
+        `(current ${bootstrap.totalBytes} bytes / ~${bootstrap.totalEstimatedTokens} tok — ` +
+        `${formatCombinedNorthStarOverage(bootstrap)}).`);
+}
+function formatBootstrapItemization(bootstrap) {
+    const { managed, skillFrontmatter, bootstrapHookBytes } = bootstrap;
+    const tierLabel = skillFrontmatter.harnessProfile === "none"
+        ? "none"
+        : `${skillFrontmatter.harnessProfile}/${skillFrontmatter.tier}`;
+    const skillPart = skillFrontmatter.bytes > 0
+        ? `skill-frontmatter ${skillFrontmatter.bytes} B (${tierLabel}, ${skillFrontmatter.skillCount} skills)`
+        : `skill-frontmatter 0 B (${tierLabel})`;
+    return (`bootstrap: managed ${managed.bytes} B, ${skillPart}, hooks ${bootstrapHookBytes} B; ` +
+        `combined ${bootstrap.totalBytes} B (~${bootstrap.totalEstimatedTokens} tok)`);
+}
+function formatAbsoluteAdvisory(bootstrap) {
+    const measure = bootstrap.managed;
+    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` +
+        "  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" +
+        "  Tier daily-core skills via OpenPackage or plan.policy.agentsMdBudget.skillFrontmatterTier.\n" +
+        "  Remediation: UPGRADING.md § Always-on bootstrap budget (DD-3).\n" +
+        "  The relative line ratchet (#645) remains fail-closed.");
+}
+function formatAbsoluteRefusal(bootstrap, absoluteMaxBytes, projectRoot) {
+    const measure = bootstrap.managed;
+    const overBytes = measure.bytes - absoluteMaxBytes;
+    return (`❌ verify:agents-md-budget: managed section grew past its absolute byte ratchet ` +
+        `(project_root=${projectRoot}).\n` +
+        `   managed section: ${measure.bytes}/${absoluteMaxBytes} bytes (OVER by ${overBytes})\n` +
+        `   ${formatBootstrapItemization(bootstrap)}\n` +
+        `   ${formatNorthStarDistance(measure)}\n` +
+        `   ${formatCombinedNorthStarDistance(bootstrap)}\n` +
+        "   AGENTS.md is a map, not a manual (#1882): push detail into a\n" +
+        "   reference doc (main.md / a pack / docs/) and leave a pointer,\n" +
+        "   rather than expanding AGENTS.md. See REFERENCES.md.\n" +
+        "   If the growth is deliberate, raise absoluteMaxBytes in\n" +
+        "   plan.policy.agentsMdBudget in PROJECT-DEFINITION (a reviewed diff). (#2452)");
+}
+function formatSkillFrontmatterRefusal(bootstrap, skillFrontmatterMaxBytes, projectRoot) {
+    const { skillFrontmatter } = bootstrap;
+    const overBytes = skillFrontmatter.bytes - skillFrontmatterMaxBytes;
+    return (`❌ verify:agents-md-budget: skill frontmatter grew past its DD-3 byte ratchet ` +
+        `(project_root=${projectRoot}).\n` +
+        `   skill-frontmatter: ${skillFrontmatter.bytes}/${skillFrontmatterMaxBytes} bytes ` +
+        `(OVER by ${overBytes}; tier ${skillFrontmatter.tier}, ${skillFrontmatter.skillCount} skills)\n` +
+        `   ${formatBootstrapItemization(bootstrap)}\n` +
+        `   ${formatCombinedNorthStarDistance(bootstrap)}\n` +
+        "   Tier deferred skills via OpenPackage (daily-core vs advanced) or shorten\n" +
+        "   SKILL.md descriptions. See UPGRADING.md § Always-on bootstrap budget (DD-3).\n" +
+        "   If the growth is deliberate, raise skillFrontmatterMaxBytes in\n" +
+        "   plan.policy.agentsMdBudget in PROJECT-DEFINITION (a reviewed diff). (#2463)");
+}
+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 ` +
+        `(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" +
+        "   or set DEFT_ALLOW_ABSOLUTE_BUDGET_WAIVER=1 for a time-boxed operator waiver (#2452).");
+}
+function enforceNorthStarEnabled() {
+    return process.env.DEFT_AGENTS_MD_BUDGET_ENFORCE_NORTH_STAR === "1";
+}
+function northStarWaiverActive() {
+    return process.env.DEFT_ALLOW_ABSOLUTE_BUDGET_WAIVER === "1";
+}
+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;
+    if (options.advisoryOnly) {
+        if (!overManagedBytes && !overManagedTokens && !overCombinedBytes && !overCombinedTokens) {
+            return result;
+        }
+        return {
+            ...result,
+            northStarMessage: formatAbsoluteAdvisory(bootstrap),
+            northStarStream: "stderr",
+            advisoryMessage: formatAbsoluteAdvisory(bootstrap),
+            advisoryStream: "stderr",
+        };
+    }
+    const distance = `${formatNorthStarDistance(measure)}\n   ${formatCombinedNorthStarDistance(bootstrap)}`;
+    return {
+        ...result,
+        northStarMessage: distance,
+        northStarStream: "stderr",
+        advisoryMessage: distance,
+        advisoryStream: "stderr",
+    };
+}
+function formatAbsoluteSummary(bootstrap, absoluteMaxBytes) {
+    const measure = bootstrap.managed;
+    return (`absolute managed ${measure.bytes}/${absoluteMaxBytes} bytes (~${measure.estimatedTokens} tok); ` +
+        `${formatBootstrapItemization(bootstrap)}`);
+}
 function formatRefusal(counts, managedMax, unmanagedMax, projectRoot) {
     const over = [];
     if (counts.managed > managedMax) {
@@ -106,19 +379,35 @@ export function evaluate(projectRoot, options = {}) {
         };
     }
     const counts = regionResult.counts;
+    const bootstrapResult = measureBootstrapSurface(root, text, budgetResult.budget);
+    if ("error" in bootstrapResult) {
+        return {
+            code: 2,
+            message: `❌ verify:agents-md-budget: ${bootstrapResult.error}`,
+            stream: "stderr",
+        };
+    }
+    const bootstrap = bootstrapResult;
+    const measure = bootstrap.managed;
+    const absoluteMaxBytes = budgetResult.budget?.absoluteMaxBytes;
+    const advisoryOnly = absoluteMaxBytes === undefined;
+    const skillFrontmatterMaxBytes = budgetResult.budget?.skillFrontmatterMaxBytes;
     if (budgetResult.source === "unset") {
         if (quiet) {
-            return { code: 0, message: "", stream: "none" };
+            return attachNorthStarNote({ code: 0, message: "", stream: "none" }, bootstrap, {
+                advisoryOnly,
+            });
         }
-        return {
+        return attachNorthStarNote({
             code: 0,
             message: "⚠ verify:agents-md-budget: no plan.policy.agentsMdBudget configured " +
                 `(managed=${counts.managed}, unmanaged=${counts.unmanaged} lines).\n` +
+                `  ${formatBootstrapItemization(bootstrap)}.\n` +
                 "  Seed a ratchet at current size to freeze growth (#645): set\n" +
                 "  plan.policy.agentsMdBudget.{managedMaxLines,unmanagedMaxLines} in " +
                 "PROJECT-DEFINITION.",
             stream: "stderr",
-        };
+        }, bootstrap, { advisoryOnly });
     }
     /* v8 ignore start -- defensive: source "typed" always carries a non-null budget. */
     if (budgetResult.budget === null) {
@@ -132,21 +421,54 @@ export function evaluate(projectRoot, options = {}) {
     const budget = budgetResult.budget;
     const overManaged = counts.managed > budget.managedMaxLines;
     const overUnmanaged = counts.unmanaged > budget.unmanagedMaxLines;
-    if (!overManaged && !overUnmanaged) {
-        if (quiet) {
-            return { code: 0, message: "", stream: "none" };
-        }
-        return {
-            code: 0,
-            message: `✓ verify:agents-md-budget: managed ${counts.managed}/${budget.managedMaxLines}, ` +
-                `unmanaged ${counts.unmanaged}/${budget.unmanagedMaxLines} lines (within ratchet).`,
-            stream: "stdout",
-        };
+    if (overManaged || overUnmanaged) {
+        return attachNorthStarNote({
+            code: 1,
+            message: formatRefusal(counts, budget.managedMaxLines, budget.unmanagedMaxLines, root),
+            stream: "stderr",
+        }, bootstrap, { advisoryOnly });
     }
-    return {
-        code: 1,
-        message: formatRefusal(counts, budget.managedMaxLines, budget.unmanagedMaxLines, root),
-        stream: "stderr",
-    };
+    if (absoluteMaxBytes !== undefined && measure.bytes > absoluteMaxBytes) {
+        return attachNorthStarNote({
+            code: 1,
+            message: formatAbsoluteRefusal(bootstrap, absoluteMaxBytes, root),
+            stream: "stderr",
+        }, bootstrap, { advisoryOnly: false });
+    }
+    if (skillFrontmatterMaxBytes !== undefined &&
+        bootstrap.skillFrontmatter.bytes > skillFrontmatterMaxBytes) {
+        return attachNorthStarNote({
+            code: 1,
+            message: formatSkillFrontmatterRefusal(bootstrap, skillFrontmatterMaxBytes, root),
+            stream: "stderr",
+        }, bootstrap, { advisoryOnly: false });
+    }
+    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;
+    if (enforceNorthStarEnabled() &&
+        (overNorthStarManaged || overNorthStarCombined) &&
+        !northStarWaiverActive()) {
+        return attachNorthStarNote({
+            code: 1,
+            message: formatNorthStarRefusal(bootstrap, root),
+            stream: "stderr",
+        }, bootstrap, { advisoryOnly: false });
+    }
+    const absoluteSummary = absoluteMaxBytes !== undefined ? `; ${formatAbsoluteSummary(bootstrap, absoluteMaxBytes)}` : "";
+    const bootstrapSummary = absoluteMaxBytes === undefined ? `; ${formatBootstrapItemization(bootstrap)}` : "";
+    if (quiet) {
+        return attachNorthStarNote({ code: 0, message: "", stream: "none" }, bootstrap, {
+            advisoryOnly,
+        });
+    }
+    return attachNorthStarNote({
+        code: 0,
+        message: `✓ verify:agents-md-budget: managed ${counts.managed}/${budget.managedMaxLines}, ` +
+            `unmanaged ${counts.unmanaged}/${budget.unmanagedMaxLines} lines (within ratchet)` +
+            `${absoluteSummary}${bootstrapSummary}.`,
+        stream: "stdout",
+    }, bootstrap, { advisoryOnly });
 }
 //# sourceMappingURL=evaluate.js.map

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

@@ -1,2 +1,3 @@
 export * from "./evaluate.js";
+export * from "./skill-frontmatter.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,2 +1,3 @@
 export * from "./evaluate.js";
+export * from "./skill-frontmatter.js";
 //# sourceMappingURL=index.js.map

package/dist/agents-md-budget/skill-frontmatter.d.ts

@@ -0,0 +1,35 @@
+/** Daily-core tier from spike #2370 / OpenPackage manifest (#2462). */
+export declare const DAILY_CORE_SKILL_NAMES: readonly ["deft-directive-setup", "deft-directive-sync", "deft-directive-build", "deft-directive-pre-pr", "deft-directive-review-cycle", "deft-directive-triage"];
+export type SkillFrontmatterTier = "daily-core" | "all" | "none";
+export type HarnessProfile = "cursor" | "none";
+/** Extract the YAML `description` field from a SKILL.md frontmatter block. */
+export declare function extractSkillDescription(text: string): string;
+/**
+ * Cursor `<agent_skill>` injection shape (DD-3 minimum).
+ * Uses repo-relative POSIX paths for stable cross-platform byte counts.
+ */
+export declare function formatCursorAgentSkill(relPath: string, description: string): string;
+export interface SkillFrontmatterEntry {
+    readonly skillName: string;
+    readonly relPath: string;
+    readonly bytes: number;
+}
+export interface SkillFrontmatterMeasure {
+    readonly bytes: number;
+    readonly estimatedTokens: number;
+    readonly skillCount: number;
+    readonly tier: SkillFrontmatterTier;
+    readonly harnessProfile: HarnessProfile;
+    readonly entries: readonly SkillFrontmatterEntry[];
+}
+export interface MeasureSkillFrontmatterOptions {
+    readonly skillsRoot?: string;
+    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;
+//# sourceMappingURL=skill-frontmatter.d.ts.map

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

@@ -0,0 +1,116 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+/** Daily-core tier from spike #2370 / OpenPackage manifest (#2462). */
+export const DAILY_CORE_SKILL_NAMES = [
+    "deft-directive-setup",
+    "deft-directive-sync",
+    "deft-directive-build",
+    "deft-directive-pre-pr",
+    "deft-directive-review-cycle",
+    "deft-directive-triage",
+];
+const DAILY_CORE_SET = new Set(DAILY_CORE_SKILL_NAMES);
+/** Extract the YAML `description` field from a SKILL.md frontmatter block. */
+export function extractSkillDescription(text) {
+    if (!text.startsWith("---")) {
+        return "";
+    }
+    const closing = text.indexOf("\n---", 3);
+    if (closing === -1) {
+        return "";
+    }
+    const frontmatter = text.slice(3, closing).replace(/^\r?\n/, "");
+    const lines = frontmatter.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        if (/^description:\s*>(-)?\s*$/.test(line)) {
+            const descLines = [];
+            for (let j = i + 1; j < lines.length; j += 1) {
+                const next = lines[j] ?? "";
+                if (!/^[ \t]/.test(next)) {
+                    break;
+                }
+                descLines.push(next.replace(/^[ \t]+/, ""));
+            }
+            return descLines.join("\n").trim();
+        }
+        const single = line.match(/^description:\s*(.+)$/);
+        if (single !== null && single[1] !== undefined) {
+            return single[1].trim();
+        }
+    }
+    return "";
+}
+/**
+ * Cursor `<agent_skill>` injection shape (DD-3 minimum).
+ * Uses repo-relative POSIX paths for stable cross-platform byte counts.
+ */
+export function formatCursorAgentSkill(relPath, description) {
+    const normalized = relPath.replace(/\\/g, "/");
+    return `<agent_skill fullPath="${normalized}">${description}</agent_skill>`;
+}
+function defaultSkillsRoot(projectRoot) {
+    return join(projectRoot, "content", "skills");
+}
+function listSkillDirs(skillsRoot) {
+    if (!existsSync(skillsRoot)) {
+        return [];
+    }
+    return readdirSync(skillsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+}
+function skillInSelectedTier(skillName, tier, dailyCore) {
+    if (tier === "none") {
+        return false;
+    }
+    if (tier === "all") {
+        return true;
+    }
+    return dailyCore.has(skillName);
+}
+/** Measure harness-injected skill frontmatter bytes for the configured profile/tier. */
+export function measureSkillFrontmatter(projectRoot, options = {}) {
+    const harnessProfile = options.harnessProfile ?? "cursor";
+    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,
+            estimatedTokens: 0,
+            skillCount: 0,
+            tier,
+            harnessProfile,
+            entries: [],
+        };
+    }
+    const entries = [];
+    for (const skillName of listSkillDirs(skillsRoot)) {
+        if (!skillInSelectedTier(skillName, tier, dailyCore)) {
+            continue;
+        }
+        const skillPath = join(skillsRoot, skillName, "SKILL.md");
+        if (!existsSync(skillPath)) {
+            continue;
+        }
+        const text = readFileSync(skillPath, "utf8");
+        const description = extractSkillDescription(text);
+        const relPath = posix.join("content", "skills", skillName, "SKILL.md");
+        const block = formatCursorAgentSkill(relPath, description);
+        const bytes = Buffer.byteLength(block, "utf8");
+        entries.push({ skillName, relPath, bytes });
+    }
+    const bytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+    return {
+        bytes,
+        estimatedTokens: Math.ceil(bytes / bytesPerToken),
+        skillCount: entries.length,
+        tier,
+        harnessProfile,
+        entries,
+    };
+}
+//# sourceMappingURL=skill-frontmatter.js.map

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`). */