vigiles 12.0.0 → 12.1.0

package/README.md

@@ -254,7 +254,7 @@ JS **or** TS (`*.harness.{mjs,ts}`) — run with `npx vigiles test`.
 ## FAQ
 
 - **Isn't this just a markdown linter?** No — it checks whether your instruction file is _true_ (every path/script/symbol/rule exists and is enabled), then tests and measures your harness. A style linter can't do any of that.
-- **Do I have to write TypeScript?** No — your agent writes the spec (`init` adopts your CLAUDE.md into one), or plain markdown lints with zero new files. Compiler-grade guarantees are opt-in, like TS's `strict`.
+- **Do I have to write TypeScript?** No — your agent writes the spec (`init` adopts your CLAUDE.md into one), or plain markdown lints with zero new files. Compiler-grade guarantees are opt-in, like TS's `strict` ([why?](docs/faq.md#why-are-the-strongest-guarantees-opt-in-not-the-default)).
 - **Non-JS repo?** `npx vigiles lint` verifies your CLAUDE.md with no install (Ruff/Clippy/Pylint/… too).
 
 **[Full FAQ →](docs/faq.md)**

package/dist/claude-code.d.ts

@@ -10,6 +10,8 @@ export * from "./mock-model.js";
 export { claudeCodeDriver, buildClaudeArgs, parseClaudeRun, claudeAvailable, } from "./harness-test.js";
 export * from "./adapters/claude-code/dialect.js";
 export { agent, skill, type ClaudeCodeToolVocabulary, } from "./adapters/claude-code/typed-spec.js";
+export { measureSelectionMatrix, assertNoCollision, formatSelectionReport, } from "./scan-behavioral.js";
+export type { SelectionReport, SkillSelectionStat, SelectionOptions, SelectionMatrixOptions, } from "./scan-behavioral.js";
 export * from "./adapters/claude-code/layout.js";
 export * from "./adapters/claude-code/runtime.js";
 export * from "./adapters/claude-code/hook-protocol.js";

package/dist/claude-code.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.skill = exports.agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
+exports.formatSelectionReport = exports.assertNoCollision = exports.measureSelectionMatrix = exports.skill = exports.agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
 /**
  * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
  * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
@@ -42,6 +42,14 @@ __exportStar(require("./adapters/claude-code/dialect.js"), exports);
 var typed_spec_js_1 = require("./adapters/claude-code/typed-spec.js");
 Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return typed_spec_js_1.agent; } });
 Object.defineProperty(exports, "skill", { enumerable: true, get: function () { return typed_spec_js_1.skill; } });
+// Selection-collision — a Claude-Code-ONLY behavioral measurement (Codex has no
+// skill-selection event to read), so it lives on this surface, not the agnostic
+// `vigiles/testing`. `measureSelectionMatrix` builds the N×N "which skill fired?"
+// matrix (diagonal = recall, off-diagonal = collision); `assertNoCollision` gates it.
+var scan_behavioral_js_1 = require("./scan-behavioral.js");
+Object.defineProperty(exports, "measureSelectionMatrix", { enumerable: true, get: function () { return scan_behavioral_js_1.measureSelectionMatrix; } });
+Object.defineProperty(exports, "assertNoCollision", { enumerable: true, get: function () { return scan_behavioral_js_1.assertNoCollision; } });
+Object.defineProperty(exports, "formatSelectionReport", { enumerable: true, get: function () { return scan_behavioral_js_1.formatSelectionReport; } });
 __exportStar(require("./adapters/claude-code/layout.js"), exports);
 __exportStar(require("./adapters/claude-code/runtime.js"), exports);
 __exportStar(require("./adapters/claude-code/hook-protocol.js"), exports);

package/dist/cli.js

@@ -676,6 +676,7 @@ function lintExitCode(report) {
         report.hookScriptErrors > 0 ||
         report.disallowedToolErrors > 0 ||
         report.descriptionOverlapErrors > 0 ||
+        report.descriptionBudgetErrors > 0 ||
         report.frontmatterValidErrors > 0 ||
         report.mcpHookErrors > 0 ||
         report.preferCompiledHookErrors > 0 ||
@@ -1027,6 +1028,10 @@ async function runLint(restArgs, flags, config) {
     // 7k. Description-overlap — two model-invocable skills with near-identical
     // descriptions collide in the selector (deterministic NCD precision proxy).
     const descriptionOverlap = checkDescriptionOverlap(config, silent, adapter);
+    // 7k². Skill-description-budget — a model-invocable skill whose description is
+    // so long the trigger signal is buried (heuristic proxy; degrades recall +
+    // precision). Generous 500-char budget; warn-tier, never gates.
+    const descriptionBudget = checkDescriptionBudget(config, silent, adapter);
     // 7l. Frontmatter-valid — a `---` block that isn't valid YAML (warn; js-yaml is
     // stricter than some loaders, so verify before enforcing).
     const frontmatterValid = checkFrontmatterValid(config, silent, adapter);
@@ -1120,6 +1125,8 @@ async function runLint(restArgs, flags, config) {
         disallowedToolErrors: disallowedTools.errors,
         descriptionOverlapIssues: descriptionOverlap.issues,
         descriptionOverlapErrors: descriptionOverlap.errors,
+        descriptionBudgetIssues: descriptionBudget.issues,
+        descriptionBudgetErrors: descriptionBudget.errors,
         frontmatterValidIssues: frontmatterValid.issues,
         frontmatterValidErrors: frontmatterValid.errors,
         mcpHookIssues: mcpHookTargets.issues,
@@ -2775,6 +2782,33 @@ function checkDescriptionOverlap(config, silent, adapter) {
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
+/**
+ * Apply the `skill-description-budget` rule: a model-invocable skill whose
+ * description is so long the trigger signal is buried — the selector weighs the
+ * opening most, so a bloated description hurts recall + precision. A
+ * deterministic heuristic proxy (generous 500-char budget). Reuses `scanPlugin`'s
+ * `descriptionBudgetIssues`. Warning by default; "error" gates CI.
+ */
+function checkDescriptionBudget(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-description-budget"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).descriptionBudgetIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nSkill-description-budget check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
 /**
  * Apply the `lethal-trifecta` rule: a unit (subagent / model-invocable skill)
  * whose declared tools hold all three legs (read-private + ingest-untrusted +

package/dist/core/rule-meta.js

@@ -202,6 +202,14 @@ exports.RULE_META = {
         summary: "Two model-invocable skills aren't near-identical (wrong one fires).",
         detector: "findDescriptionOverlaps",
     },
+    "skill-description-budget": {
+        id: "skill-description-budget",
+        bucket: "heuristic-behavioral",
+        surface: ["skill"],
+        defaultSeverity: "warn",
+        summary: "A model-invocable skill's description isn't so long the trigger is buried.",
+        detector: "findDescriptionBudgetIssues",
+    },
     "frontmatter-valid": {
         id: "frontmatter-valid",
         bucket: "heuristic-behavioral",

package/dist/core/skill-description-budget.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Skill-description budget — a DETERMINISTIC proxy for a behavioral risk, and the
+ * deterministic sibling of {@link findDescriptionOverlaps}. A model-invocable
+ * skill is selected on its `description`, and the selector weighs the OPENING of
+ * it most; a long, buried description dilutes the trigger signal and degrades
+ * both recall ("did it fire when it should?") and precision ("did it stay quiet
+ * when it shouldn't?"). This catches a trigger-class problem with NO model.
+ *
+ * HEURISTIC-BEHAVIORAL bucket: the threshold is a PROXY (no character count
+ * PROVES a description triggers badly), so the ceiling is WARN — it never gates.
+ * Calibrated FP-safe: the default budget (500 chars) sits well above a normal
+ * one-to-three-sentence description, so only a genuinely bloated description
+ * fires. Reports the per-skill overflow, never a unilateral defect.
+ */
+/** A skill identified by name + its trigger-surface description. */
+export interface BudgetedSurface {
+    readonly name: string;
+    readonly description: string;
+}
+export interface DescriptionBudgetIssue {
+    readonly name: string;
+    /** Length of the description in characters. */
+    readonly length: number;
+    /** The budget it exceeded. */
+    readonly budget: number;
+    readonly message: string;
+}
+/**
+ * The default description-length budget, in characters. A concise what+when
+ * description is comfortably under this; only a bloated one (multiple long
+ * sentences, embedded examples, disambiguation prose) exceeds it. Generous on
+ * purpose — warn-tier, don't cry wolf. Exported so a caller / test sees it.
+ */
+export declare const DEFAULT_DESCRIPTION_BUDGET = 500;
+/**
+ * Find model-invocable skills whose `description` exceeds `budget` characters.
+ * Returns one {@link DescriptionBudgetIssue} per over-budget skill, longest
+ * first. Pure; pass only the surfaces that compete for auto-selection
+ * (model-invocable, described) so a user-invoked skill isn't a false alarm.
+ */
+export declare function findDescriptionBudgetIssues(surfaces: readonly BudgetedSurface[], budget?: number): DescriptionBudgetIssue[];
+//# sourceMappingURL=skill-description-budget.d.ts.map

package/dist/core/skill-description-budget.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Skill-description budget — a DETERMINISTIC proxy for a behavioral risk, and the
+ * deterministic sibling of {@link findDescriptionOverlaps}. A model-invocable
+ * skill is selected on its `description`, and the selector weighs the OPENING of
+ * it most; a long, buried description dilutes the trigger signal and degrades
+ * both recall ("did it fire when it should?") and precision ("did it stay quiet
+ * when it shouldn't?"). This catches a trigger-class problem with NO model.
+ *
+ * HEURISTIC-BEHAVIORAL bucket: the threshold is a PROXY (no character count
+ * PROVES a description triggers badly), so the ceiling is WARN — it never gates.
+ * Calibrated FP-safe: the default budget (500 chars) sits well above a normal
+ * one-to-three-sentence description, so only a genuinely bloated description
+ * fires. Reports the per-skill overflow, never a unilateral defect.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DESCRIPTION_BUDGET = void 0;
+exports.findDescriptionBudgetIssues = findDescriptionBudgetIssues;
+/**
+ * The default description-length budget, in characters. A concise what+when
+ * description is comfortably under this; only a bloated one (multiple long
+ * sentences, embedded examples, disambiguation prose) exceeds it. Generous on
+ * purpose — warn-tier, don't cry wolf. Exported so a caller / test sees it.
+ */
+exports.DEFAULT_DESCRIPTION_BUDGET = 500;
+/**
+ * Find model-invocable skills whose `description` exceeds `budget` characters.
+ * Returns one {@link DescriptionBudgetIssue} per over-budget skill, longest
+ * first. Pure; pass only the surfaces that compete for auto-selection
+ * (model-invocable, described) so a user-invoked skill isn't a false alarm.
+ */
+function findDescriptionBudgetIssues(surfaces, budget = exports.DEFAULT_DESCRIPTION_BUDGET) {
+    const issues = [];
+    for (const s of surfaces) {
+        const length = Array.from(s.description).length;
+        if (length <= budget)
+            continue;
+        issues.push({
+            name: s.name,
+            length,
+            budget,
+            message: `skill "${s.name}" has a ${String(length)}-char description (budget ${String(budget)}) — the selector weighs the opening most, so a long description buries the trigger signal and hurts recall + precision. Tighten it to a concise what + when.`,
+        });
+    }
+    return issues.sort((a, b) => b.length - a.length);
+}
+//# sourceMappingURL=skill-description-budget.js.map

package/dist/core/types.d.ts

@@ -202,6 +202,15 @@ export interface RulesConfig {
      * as `scan` (descriptionOverlaps).
      */
     "description-overlap"?: RuleSeverity;
+    /**
+     * Flag a model-invocable skill whose `description` is so long the trigger
+     * signal is buried — the selector weighs the opening most, so a bloated
+     * description hurts recall + precision. A DETERMINISTIC heuristic proxy for a
+     * `--trigger`-class behavioral bug; calibrated FP-safe (generous default
+     * budget, 500 chars). Default "warn" — a proxy, never gates. Same detector as
+     * `scan` (descriptionBudgetIssues).
+     */
+    "skill-description-budget"?: RuleSeverity;
     /**
      * Flag a skill/agent whose `---` frontmatter block EXISTS but isn't valid YAML
      * — fields may not parse as intended. CAVEAT: a real YAML parser (js-yaml) is

package/dist/core/validate.js

@@ -67,6 +67,9 @@ exports.DEFAULT_RULES = {
     "disallowed-tools-contract": "warn",
     // Deterministic NCD precision proxy (near-identical skill descriptions) — warn.
     "description-overlap": "warn",
+    // A model-invocable skill's description so long the trigger signal is buried —
+    // WARN only (heuristic proxy, generous 500-char budget); never gates.
+    "skill-description-budget": "warn",
     // Malformed-YAML frontmatter — WARN only (js-yaml is stricter than some loaders).
     "frontmatter-valid": "warn",
     // A mcp_tool hook incomplete / targeting an undeclared server — on by default at warn.

package/dist/doc-command-coverage.d.ts

@@ -0,0 +1,20 @@
+/** The hidden runtime umbrella — not a human-facing verb to document. */
+export declare const COVERAGE_EXEMPT: readonly ["hook-runtime"];
+/**
+ * Whether `verb` appears in a COMMAND context anywhere in `content`:
+ * `vigiles <verb>` or a backtick-prefixed `` `<verb> ``. Generous on purpose
+ * (see the file header) — over-counting a verb as documented is the SAFE
+ * direction; under-counting would cry wolf.
+ */
+export declare function verbMentioned(verb: string, content: string): boolean;
+/**
+ * Find public verbs not MENTIONED in any of the given doc files. Pure — the
+ * caller supplies file contents (so it runs over the repo's `docs/` in a test,
+ * or any file set). `verbs` defaults to the canonical {@link VERBS}; `exempt`
+ * drops the hidden umbrella.
+ */
+export declare function findUndocumentedVerbs(docs: readonly {
+    readonly path: string;
+    readonly content: string;
+}[], verbs?: readonly string[], exempt?: readonly string[]): string[];
+//# sourceMappingURL=doc-command-coverage.d.ts.map

package/dist/doc-command-coverage.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COVERAGE_EXEMPT = void 0;
+exports.verbMentioned = verbMentioned;
+exports.findUndocumentedVerbs = findUndocumentedVerbs;
+/**
+ * Doc-command coverage — the INVERSE of self-command-refs, and the deterministic
+ * FLOOR under the `document-the-why` rule. self-command-refs checks that every
+ * `vigiles <cmd>` reference in the docs resolves to a REAL command (docs → code).
+ * This checks the other direction (code → docs): every public CLI VERB must be
+ * MENTIONED somewhere under `docs/`, so a verb shipped without a doc home is a
+ * failing test, not a thing a reader discovers is missing.
+ *
+ * HIGH-PRECISION, and biased toward NOT crying wolf: the risk here is a FALSE
+ * "undocumented" alarm on a verb that IS documented, so "mentioned" is matched
+ * GENEROUSLY — a verb counts as documented if it appears in a COMMAND context:
+ * `vigiles <verb>` (covers `npx vigiles <verb>`) OR a backtick immediately
+ * followed by the verb (`` `<verb>` ``, `` `<verb> ./x` ``). A bare English word
+ * ("test", "audit", "eval", "compile" all double as prose) is NOT enough — it
+ * must sit in a command context — so the check still fires on a genuinely
+ * undocumented verb while never flagging a documented one.
+ *
+ * `hook-runtime` is excluded by default: it is the HIDDEN runtime-entrypoint
+ * umbrella (cohesive-cli-surface keeps it OUT of the human verb surface), not a
+ * verb a user is expected to read about beside `audit`/`lint`. Source of truth
+ * for the verb set: {@link VERBS}.
+ */
+const cli_commands_js_1 = require("./cli-commands.js");
+/** The hidden runtime umbrella — not a human-facing verb to document. */
+exports.COVERAGE_EXEMPT = ["hook-runtime"];
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Whether `verb` appears in a COMMAND context anywhere in `content`:
+ * `vigiles <verb>` or a backtick-prefixed `` `<verb> ``. Generous on purpose
+ * (see the file header) — over-counting a verb as documented is the SAFE
+ * direction; under-counting would cry wolf.
+ */
+function verbMentioned(verb, content) {
+    const esc = escapeRegExp(verb);
+    return new RegExp(String.raw `(\bvigiles\s+|\x60)${esc}\b`).test(content);
+}
+/**
+ * Find public verbs not MENTIONED in any of the given doc files. Pure — the
+ * caller supplies file contents (so it runs over the repo's `docs/` in a test,
+ * or any file set). `verbs` defaults to the canonical {@link VERBS}; `exempt`
+ * drops the hidden umbrella.
+ */
+function findUndocumentedVerbs(docs, verbs = cli_commands_js_1.VERBS, exempt = exports.COVERAGE_EXEMPT) {
+    const mentioned = new Set();
+    for (const { content } of docs) {
+        for (const verb of verbs) {
+            if (!mentioned.has(verb) && verbMentioned(verb, content))
+                mentioned.add(verb);
+        }
+    }
+    return verbs.filter((v) => !exempt.includes(v) && !mentioned.has(v));
+}
+//# sourceMappingURL=doc-command-coverage.js.map

package/dist/eval-cost.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Eval cost transparency — make what a real-model run SPENT impossible to miss.
+ * vigiles's whole affordability pitch is "runs on your Claude subscription, not a
+ * metered API," so every real-model run should say — out loud — how many tokens it
+ * spent, the API-equivalent dollar cost, and (loudly) if it was billed to a
+ * METERED API key instead of your subscription.
+ *
+ * HONEST SCOPE: we surface tokens + the API-equivalent `$` (`total_cost_usd` from
+ * the `claude` CLI) + a running session tally. We deliberately do NOT show a
+ * "% of your subscription" — Anthropic does not expose a subscription's quota or
+ * limit programmatically (and the real limits are rolling rate windows, not a
+ * dollar bucket), so any percentage would be fiction. See docs/eval-architecture.md.
+ *
+ * Pure + injectable (env + an output sink), so the whole thing is unit-tested
+ * without a model or a real key.
+ */
+import type { EvalUsage, ArmUsage, EvalReport } from "./eval.js";
+/** A normalized cost/token snapshot — the common shape a report renders from. */
+export interface CostSummary {
+    /** API-equivalent cost (`total_cost_usd`) — the number that matters. */
+    readonly costUsd: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheCreationTokens: number;
+    readonly cacheReadTokens: number;
+}
+/** Total tokens across all four billing buckets. */
+export declare function totalTokens(c: CostSummary): number;
+/** A per-run {@link EvalUsage} → the common snapshot. */
+export declare function costFromRun(u: EvalUsage): CostSummary;
+/** An aggregated per-arm {@link ArmUsage} → the common snapshot. */
+export declare function costFromArm(u: ArmUsage): CostSummary;
+/** Sum any number of snapshots (e.g. every arm of an A/B). */
+export declare function sumCosts(costs: readonly CostSummary[]): CostSummary;
+/** The whole-{@link EvalReport} cost — every arm summed. */
+export declare function costFromEvalReport(report: EvalReport): CostSummary;
+/**
+ * How the run was billed. `metered` is true when a real Anthropic API key is in
+ * the environment — the `claude` CLI bills those PER TOKEN, whereas a
+ * subscription run (auth via `~/.claude`, no key var) costs $0 beyond the sub.
+ * The mock/deterministic tier never reaches here (it has no real cost), so a
+ * present key means a real metered run.
+ */
+export interface Billing {
+    readonly metered: boolean;
+    /** Which env var carried the key (for the actionable "unset X" message). */
+    readonly keyVar: string | null;
+}
+export declare function detectBilling(env?: NodeJS.ProcessEnv): Billing;
+/** Add a run to the running session total and return the new total. */
+export declare function recordSessionCost(c: CostSummary): CostSummary;
+/** The session total so far. */
+export declare function sessionCost(): CostSummary;
+/** Reset the session tally (test seam). */
+export declare function resetSessionCost(): void;
+/**
+ * The human-readable cost block for a run. Shows tokens + API-equivalent `$`, the
+ * billed-to line (a LOUD warning + an actionable fix when metered, a green ✅ when
+ * on the subscription), and the session tally when it exceeds this run.
+ */
+export declare function formatCostSummary(c: CostSummary, opts: {
+    billing: Billing;
+    session?: CostSummary | null;
+}): string;
+/**
+ * Record `c` into the session tally and emit its cost block. The default sink is
+ * stderr (so a run's cost never pollutes `--json` stdout). Injectable env + sink
+ * keep it fully testable. Returns the emitted text (also handy for a skill to
+ * relay to the user).
+ */
+export declare function emitCostSummary(c: CostSummary, opts?: {
+    env?: NodeJS.ProcessEnv;
+    out?: (s: string) => void;
+}): string;
+//# sourceMappingURL=eval-cost.d.ts.map

package/dist/eval-cost.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.totalTokens = totalTokens;
+exports.costFromRun = costFromRun;
+exports.costFromArm = costFromArm;
+exports.sumCosts = sumCosts;
+exports.costFromEvalReport = costFromEvalReport;
+exports.detectBilling = detectBilling;
+exports.recordSessionCost = recordSessionCost;
+exports.sessionCost = sessionCost;
+exports.resetSessionCost = resetSessionCost;
+exports.formatCostSummary = formatCostSummary;
+exports.emitCostSummary = emitCostSummary;
+const ZERO = {
+    costUsd: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheCreationTokens: 0,
+    cacheReadTokens: 0,
+};
+/** Total tokens across all four billing buckets. */
+function totalTokens(c) {
+    return (c.inputTokens + c.outputTokens + c.cacheCreationTokens + c.cacheReadTokens);
+}
+/** A per-run {@link EvalUsage} → the common snapshot. */
+function costFromRun(u) {
+    return {
+        costUsd: u.costUsd,
+        inputTokens: u.inputTokens,
+        outputTokens: u.outputTokens,
+        cacheCreationTokens: u.cacheCreationTokens,
+        cacheReadTokens: u.cacheReadTokens,
+    };
+}
+/** An aggregated per-arm {@link ArmUsage} → the common snapshot. */
+function costFromArm(u) {
+    return {
+        costUsd: u.totalCostUsd,
+        inputTokens: u.totalInputTokens,
+        outputTokens: u.totalOutputTokens,
+        cacheCreationTokens: u.totalCacheCreationTokens,
+        cacheReadTokens: u.totalCacheReadTokens,
+    };
+}
+/** Sum any number of snapshots (e.g. every arm of an A/B). */
+function sumCosts(costs) {
+    return costs.reduce((a, c) => ({
+        costUsd: a.costUsd + c.costUsd,
+        inputTokens: a.inputTokens + c.inputTokens,
+        outputTokens: a.outputTokens + c.outputTokens,
+        cacheCreationTokens: a.cacheCreationTokens + c.cacheCreationTokens,
+        cacheReadTokens: a.cacheReadTokens + c.cacheReadTokens,
+    }), ZERO);
+}
+/** The whole-{@link EvalReport} cost — every arm summed. */
+function costFromEvalReport(report) {
+    return sumCosts(Object.values(report.arms).map((a) => costFromArm(a.usage)));
+}
+const KEY_VARS = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"];
+function detectBilling(env = process.env) {
+    for (const v of KEY_VARS) {
+        const val = env[v];
+        if (val !== undefined && val.trim() !== "")
+            return { metered: true, keyVar: v };
+    }
+    return { metered: false, keyVar: null };
+}
+// --- Session tally (within one process) ------------------------------------
+let SESSION = ZERO;
+/** Add a run to the running session total and return the new total. */
+function recordSessionCost(c) {
+    SESSION = sumCosts([SESSION, c]);
+    return SESSION;
+}
+/** The session total so far. */
+function sessionCost() {
+    return SESSION;
+}
+/** Reset the session tally (test seam). */
+function resetSessionCost() {
+    SESSION = ZERO;
+}
+// --- Formatting ------------------------------------------------------------
+function fmtUsd(n) {
+    return `$${n < 0.01 && n > 0 ? n.toFixed(4) : n.toFixed(2)}`;
+}
+function fmtInt(n) {
+    return Math.round(n).toLocaleString("en-US");
+}
+function fmtK(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(Math.round(n));
+}
+/**
+ * The human-readable cost block for a run. Shows tokens + API-equivalent `$`, the
+ * billed-to line (a LOUD warning + an actionable fix when metered, a green ✅ when
+ * on the subscription), and the session tally when it exceeds this run.
+ */
+function formatCostSummary(c, opts) {
+    const lines = [];
+    lines.push(`  Spent: ${fmtInt(totalTokens(c))} tokens ` +
+        `(${fmtK(c.inputTokens)} in · ${fmtK(c.outputTokens)} out · ${fmtK(c.cacheReadTokens)} cache) ` +
+        `· ~${fmtUsd(c.costUsd)} API-equivalent`);
+    if (opts.billing.metered) {
+        const v = opts.billing.keyVar ?? "ANTHROPIC_API_KEY";
+        lines.push(`  ⚠ Billed to: METERED API (${v} is set) — you paid ~${fmtUsd(c.costUsd)} this run.`, `     Run it free on your Claude subscription: unset ${v}, then \`claude login\`.`);
+    }
+    else {
+        lines.push(`  Billed to: your Claude subscription — $0 metered ✅`);
+    }
+    if (opts.session && opts.session.costUsd > c.costUsd) {
+        lines.push(`  Session so far: ${fmtInt(totalTokens(opts.session))} tokens · ~${fmtUsd(opts.session.costUsd)} API-equivalent`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Record `c` into the session tally and emit its cost block. The default sink is
+ * stderr (so a run's cost never pollutes `--json` stdout). Injectable env + sink
+ * keep it fully testable. Returns the emitted text (also handy for a skill to
+ * relay to the user).
+ */
+function emitCostSummary(c, opts = {}) {
+    // A no-cost run (a replay, a zero-trial eval) has nothing to report.
+    if (totalTokens(c) === 0 && c.costUsd === 0)
+        return "";
+    const billing = detectBilling(opts.env ?? process.env);
+    const session = recordSessionCost(c);
+    const text = formatCostSummary(c, { billing, session });
+    (opts.out ??
+        ((s) => {
+            console.error(s);
+        }))(text);
+    return text;
+}
+//# sourceMappingURL=eval-cost.js.map

package/dist/eval.d.ts

@@ -327,6 +327,8 @@ export interface CheckRate {
 export interface CheckReport {
     readonly n: number;
     readonly perCheck: readonly CheckRate[];
+    /** Cost / latency / token totals for the run (the same source as `runEval`). */
+    readonly usage: ArmUsage;
 }
 /**
  * Score a check vocabulary across trials — the scored counterpart to
@@ -714,6 +716,8 @@ export interface TriggerRateReport {
      * `n` means the measurement is thin (e.g. a Codex usage limit was hit); re-run.
      */
     readonly errored?: number;
+    /** Cost / tokens SPENT across all runs (relevant + irrelevant) — feeds the cost summary. */
+    readonly usage: ArmUsage;
 }
 /**
  * An eval-tier transport: how to RUN a real harness turn and PARSE its output.

package/dist/eval.js

@@ -67,6 +67,7 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
+const eval_cost_js_1 = require("./eval-cost.js");
 const proofs_js_1 = require("./core/proofs.js");
 const harness_test_js_1 = require("./harness-test.js");
 const eval_cache_js_1 = require("./eval-cache.js");
@@ -144,7 +145,11 @@ function spawnAgent(a) {
  * `runEvalWith` with the real agent runner.
  */
 async function runEval(spec) {
-    return runEvalWith(spec, spawnAgent);
+    const report = await runEvalWith(spec, spawnAgent);
+    // Surface what the run spent — tokens + API-equivalent $, and a LOUD warning if
+    // it was billed to a metered API key instead of the subscription. See eval-cost.ts.
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromEvalReport)(report));
+    return report;
 }
 /**
  * Score a check vocabulary across trials — the scored counterpart to
@@ -201,6 +206,7 @@ async function measureWith(spec, runner) {
                     n: s?.n ?? 0,
                 };
             }),
+            usage: arm?.usage ?? aggregateUsage([]),
         };
     }
     finally {
@@ -211,7 +217,9 @@ async function measureWith(spec, runner) {
 /* v8 ignore start -- real claude subprocess; thin wrapper over measureWith */
 /** Score a check vocabulary across trials against the real `claude` CLI. */
 async function measure(spec) {
-    return measureWith(spec, spawnAgent);
+    const report = await measureWith(spec, spawnAgent);
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromArm)(report.usage));
+    return report;
 }
 /** Score checks across arms (injectable runner). Reuses `runEvalWith`. */
 async function measureArmsWith(spec, runner) {
@@ -245,6 +253,7 @@ async function measureArmsWith(spec, runner) {
                         n: s?.n ?? 0,
                     };
                 }),
+                usage: arm.usage,
             };
         }
         return { arms };
@@ -278,7 +287,10 @@ function stubArmPluginDirs(arms) {
 /* v8 ignore start -- real claude subprocess; thin wrapper over measureArmsWith */
 /** Score checks across arms against the real `claude` CLI. */
 async function measureArms(spec) {
-    return measureArmsWith(spec, spawnAgent);
+    const report = await measureArmsWith(spec, spawnAgent);
+    // Sum every arm's spend — an A/B run pays for both arms.
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.sumCosts)(Object.values(report.arms).map((a) => (0, eval_cost_js_1.costFromArm)(a.usage))));
+    return report;
 }
 /* v8 ignore stop */
 /**
@@ -1496,13 +1508,17 @@ async function runTriggerTrial(prompt, cfg, runner) {
             pluginDir: cfg.pluginDir,
             timeoutMs: cfg.timeoutMs,
         });
+        // Usage comes from the parser (harness-neutral: Claude + Codex both fill it),
+        // and a run costs tokens even when it errors — so accumulate it either way.
+        const ctx = makeContext(cwd, out, cfg.parse);
         // An errored/rate-limited turn is NOT a "skill didn't fire" miss — it's
         // excluded from the rate, so e.g. a Codex usage limit can't read as recall 0.
         if (cfg.runError?.(out))
-            return { fired: 0, errored: true };
+            return { fired: 0, errored: true, usage: ctx.usage };
         return {
-            fired: cfg.fired(makeContext(cwd, out, cfg.parse)) ? 1 : 0,
+            fired: cfg.fired(ctx) ? 1 : 0,
             errored: false,
+            usage: ctx.usage,
         };
     }
     finally {
@@ -1539,6 +1555,7 @@ async function runTriggerSet(prompts, cfg, runner) {
         fired: firedBy.reduce((a, b) => a + b, 0),
         n: trialsBy.reduce((a, b) => a + b, 0),
         errored,
+        usages: outcomes.map((o) => o.usage),
     };
 }
 /**
@@ -1624,6 +1641,7 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
                 perPrompt: relevant.perPrompt,
                 competitors,
                 errored: positiveOrUndefined(relevant.errored),
+                usage: aggregateUsage(relevant.usages),
             };
             if ((spec.irrelevantPrompts?.length ?? 0) === 0)
                 return base;
@@ -1635,6 +1653,8 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
                 falsePositiveRate: irrelevant.n > 0 ? irrelevant.fired / irrelevant.n : 0,
                 precision: fires > 0 ? relevant.fired / fires : undefined,
                 perIrrelevant: irrelevant.perPrompt,
+                // Total cost across BOTH sets (the precision runs cost tokens too).
+                usage: aggregateUsage([...relevant.usages, ...irrelevant.usages]),
             };
         });
     }
@@ -1654,7 +1674,10 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
  */
 async function measureTriggerRate(spec, opts = {}) {
     const d = opts.evalDriver ?? exports.claudeEvalDriver;
-    return measureTriggerRateWith(spec, d.runner, d.parse, d.runError, d.harness ?? "claude-code");
+    const report = await measureTriggerRateWith(spec, d.runner, d.parse, d.runError, d.harness ?? "claude-code");
+    // Surface what the run spent (tokens + API-equivalent $ + metered warning).
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromArm)(report.usage));
+    return report;
 }
 /* v8 ignore stop */
 /** Format a trigger-rate report: overall %, then each prompt's rate. */

package/dist/research-index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Research-index completeness — the deterministic FLOOR keeping the `research/`
+ * corpus and its index (`research/CLAUDE.md.spec.ts`) in sync. The spec's
+ * `keyFiles` map is the AGENT-FACING index of every research doc; the compiler
+ * already verifies the OTHER direction (every indexed path EXISTS, else
+ * `vigiles compile` fails), so the only open gap is a doc that was ADDED but
+ * never indexed. This check closes it: every `research/*.md` (except the
+ * human-facing `README.md`) must appear in the index, or the dogfood test fails.
+ *
+ * Pure — the caller supplies the doc filenames and the index content (the spec
+ * source, where an entry is AUTHORED), so it runs over the real `research/` dir
+ * in a test or over any file set. Bidirectional sync = compiler (index ⊆ docs)
+ * + this check (docs ⊆ index).
+ */
+/** Docs that are the index itself / human front-door, not indexed entries. */
+export declare const INDEX_EXEMPT: readonly ["README.md"];
+/**
+ * Research doc basenames (e.g. `roadmap.md`) NOT referenced anywhere in
+ * `indexContent`. A doc counts as indexed if its repo-relative path
+ * (`research/<name>.md`) appears in the index — the exact form the spec's
+ * `keyFiles` keys use. Exempt docs (the README) are never flagged.
+ */
+export declare function unindexedResearchDocs(docFilenames: readonly string[], indexContent: string, exempt?: readonly string[]): string[];
+/**
+ * Index entries pointing at a `research/<name>.md` that no longer exists on
+ * disk. The compiler catches this at compile time (a missing `keyFiles` path is
+ * a compile error), so this is a belt-and-suspenders reader for a test that
+ * wants to assert it directly without invoking the compiler.
+ */
+export declare function deadIndexEntries(docFilenames: readonly string[], indexContent: string): string[];
+//# sourceMappingURL=research-index.d.ts.map

package/dist/research-index.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Research-index completeness — the deterministic FLOOR keeping the `research/`
+ * corpus and its index (`research/CLAUDE.md.spec.ts`) in sync. The spec's
+ * `keyFiles` map is the AGENT-FACING index of every research doc; the compiler
+ * already verifies the OTHER direction (every indexed path EXISTS, else
+ * `vigiles compile` fails), so the only open gap is a doc that was ADDED but
+ * never indexed. This check closes it: every `research/*.md` (except the
+ * human-facing `README.md`) must appear in the index, or the dogfood test fails.
+ *
+ * Pure — the caller supplies the doc filenames and the index content (the spec
+ * source, where an entry is AUTHORED), so it runs over the real `research/` dir
+ * in a test or over any file set. Bidirectional sync = compiler (index ⊆ docs)
+ * + this check (docs ⊆ index).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INDEX_EXEMPT = void 0;
+exports.unindexedResearchDocs = unindexedResearchDocs;
+exports.deadIndexEntries = deadIndexEntries;
+/** Docs that are the index itself / human front-door, not indexed entries. */
+exports.INDEX_EXEMPT = ["README.md"];
+/**
+ * Research doc basenames (e.g. `roadmap.md`) NOT referenced anywhere in
+ * `indexContent`. A doc counts as indexed if its repo-relative path
+ * (`research/<name>.md`) appears in the index — the exact form the spec's
+ * `keyFiles` keys use. Exempt docs (the README) are never flagged.
+ */
+function unindexedResearchDocs(docFilenames, indexContent, exempt = exports.INDEX_EXEMPT) {
+    return docFilenames.filter((name) => !exempt.includes(name) && !indexContent.includes(`research/${name}`));
+}
+/**
+ * Index entries pointing at a `research/<name>.md` that no longer exists on
+ * disk. The compiler catches this at compile time (a missing `keyFiles` path is
+ * a compile error), so this is a belt-and-suspenders reader for a test that
+ * wants to assert it directly without invoking the compiler.
+ */
+function deadIndexEntries(docFilenames, indexContent) {
+    const present = new Set(docFilenames);
+    const refs = indexContent.matchAll(/research\/([\w.-]+\.md)/g);
+    const dead = new Set();
+    for (const m of refs) {
+        const name = m[1];
+        if (!present.has(name))
+            dead.add(name);
+    }
+    return [...dead];
+}
+//# sourceMappingURL=research-index.js.map

package/dist/scan-behavioral.d.ts

@@ -135,6 +135,48 @@ export declare function measurePluginSelectionWith(dir: string, promptSet: Trigg
 export declare function measurePluginSelection(dir: string, promptSet: TriggerPromptSet, opts?: SelectionOptions): Promise<SelectionReport>;
 /** Format the selection-collision matrix as a scan-report section. */
 export declare function formatSelectionReport(r: SelectionReport): string;
+/** Options for {@link measureSelectionMatrix}: {@link SelectionOptions} plus an
+ * optional explicit prompt set (auto-derived from descriptions when omitted). */
+export interface SelectionMatrixOptions extends SelectionOptions {
+    /**
+     * Per-skill recall prompts. Omit for ZERO-SETUP — prompts are auto-derived
+     * from each skill's description (the same generator the audit trigger tier
+     * uses). Supply your own for a curated collision benchmark; only the `prompts`
+     * array per skill is read (any `irrelevant` bank is ignored here).
+     */
+    readonly prompts?: TriggerPromptSet;
+}
+/**
+ * Measure a plugin's skill-SELECTION collision matrix — "when I ask for skill i's
+ * job, does ONLY skill i fire?" The first-class, assertable form of the cross-skill
+ * collision measurement (pair with {@link assertNoCollision}). The matrix diagonal
+ * is recall; off-diagonal mass is collision — skill j hijacking skill i's prompt,
+ * the failure that breaks a multi-skill plugin and that per-skill trigger-rate
+ * (each skill in ISOLATION) structurally can't see.
+ *
+ * ZERO-SETUP: with no `prompts`, they're derived from each model-invocable skill's
+ * description. Claude Code only (Codex has no skill-selection event to read); needs
+ * the `claude` CLI + model auth, else `available: false`. Thin promotion of
+ * {@link measurePluginSelection}. See research/plugin-selection-collision.md.
+ */
+export declare function measureSelectionMatrix(dir: string, opts?: SelectionMatrixOptions): Promise<SelectionReport>;
+/**
+ * Injectable core of {@link measureSelectionMatrix} (for tests): auto-derive the
+ * prompts (unless supplied) and drive the matrix via a fake/real probe.
+ */
+export declare function measureSelectionMatrixWith(dir: string, probe: HarnessProbe, opts?: SelectionMatrixOptions): Promise<SelectionReport>;
+/**
+ * Assert a plugin's skills don't hijack each other — the gate over a
+ * {@link SelectionReport} from {@link measureSelectionMatrix}. `maxOffDiagonal`
+ * caps EACH skill's collision rate (fraction of its own prompts on which a SIBLING
+ * fired); `maxPluginCollision` caps the plugin-wide rate. With neither set it
+ * demands ZERO collision. THROWS (never a silent green) when nothing was measured
+ * — an unavailable harness or a zero-run report is a gap, not a pass.
+ */
+export declare function assertNoCollision(report: SelectionReport, opts?: {
+    maxOffDiagonal?: number;
+    maxPluginCollision?: number;
+}): void;
 /** Does a skill description assert a hard constraint (→ an adversarial-gate candidate)? */
 export declare function isGateDescription(description: string): boolean;
 /** A skill considered for gate detection — name + its (model-visible) description. */

package/dist/scan-behavioral.js

@@ -22,6 +22,9 @@ exports.buildSelectionReport = buildSelectionReport;
 exports.measurePluginSelectionWith = measurePluginSelectionWith;
 exports.measurePluginSelection = measurePluginSelection;
 exports.formatSelectionReport = formatSelectionReport;
+exports.measureSelectionMatrix = measureSelectionMatrix;
+exports.measureSelectionMatrixWith = measureSelectionMatrixWith;
+exports.assertNoCollision = assertNoCollision;
 exports.isGateDescription = isGateDescription;
 exports.detectGateSkills = detectGateSkills;
 exports.gateRubric = gateRubric;
@@ -33,6 +36,7 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_child_process_1 = require("node:child_process");
 const scan_js_1 = require("./scan.js");
+const audit_prompts_js_1 = require("./audit-prompts.js");
 const judge_js_1 = require("./judge.js");
 const eval_js_1 = require("./eval.js");
 const harness_assert_js_1 = require("./harness-assert.js");
@@ -397,6 +401,69 @@ function formatSelectionReport(r) {
     }
     return lines.join("\n");
 }
+/**
+ * Measure a plugin's skill-SELECTION collision matrix — "when I ask for skill i's
+ * job, does ONLY skill i fire?" The first-class, assertable form of the cross-skill
+ * collision measurement (pair with {@link assertNoCollision}). The matrix diagonal
+ * is recall; off-diagonal mass is collision — skill j hijacking skill i's prompt,
+ * the failure that breaks a multi-skill plugin and that per-skill trigger-rate
+ * (each skill in ISOLATION) structurally can't see.
+ *
+ * ZERO-SETUP: with no `prompts`, they're derived from each model-invocable skill's
+ * description. Claude Code only (Codex has no skill-selection event to read); needs
+ * the `claude` CLI + model auth, else `available: false`. Thin promotion of
+ * {@link measurePluginSelection}. See research/plugin-selection-collision.md.
+ */
+async function measureSelectionMatrix(dir, opts = {}) {
+    return measurePluginSelection(dir, resolveSelectionPrompts(dir, opts), opts);
+}
+/**
+ * Injectable core of {@link measureSelectionMatrix} (for tests): auto-derive the
+ * prompts (unless supplied) and drive the matrix via a fake/real probe.
+ */
+async function measureSelectionMatrixWith(dir, probe, opts = {}) {
+    return measurePluginSelectionWith(dir, resolveSelectionPrompts(dir, opts), probe, opts);
+}
+/** The prompts for a selection run: explicit if given, else auto-derived from the
+ * model-invocable skills' descriptions (the zero-setup path). */
+function resolveSelectionPrompts(dir, opts) {
+    return (opts.prompts ??
+        (0, audit_prompts_js_1.autoTriggerPrompts)((0, scan_js_1.scanPlugin)(dir)
+            .skills.filter((s) => !s.userInvoked && s.hasDescription)
+            .map((s) => ({ name: s.name, description: s.description ?? "" }))));
+}
+/**
+ * Assert a plugin's skills don't hijack each other — the gate over a
+ * {@link SelectionReport} from {@link measureSelectionMatrix}. `maxOffDiagonal`
+ * caps EACH skill's collision rate (fraction of its own prompts on which a SIBLING
+ * fired); `maxPluginCollision` caps the plugin-wide rate. With neither set it
+ * demands ZERO collision. THROWS (never a silent green) when nothing was measured
+ * — an unavailable harness or a zero-run report is a gap, not a pass.
+ */
+function assertNoCollision(report, opts = {}) {
+    if (!report.available)
+        throw new Error(`selection matrix unavailable — ${report.note ?? "n/a"}`);
+    if (report.n === 0)
+        throw new Error(`selection matrix measured nothing — ${report.note ?? "no runs"}`);
+    // Enforce the per-skill ceiling when asked, OR by default (name = NoCollision);
+    // if only the plugin-wide cap is given, don't also silently demand zero per-skill.
+    const maxOff = opts.maxOffDiagonal ??
+        (opts.maxPluginCollision === undefined ? 0 : undefined);
+    if (maxOff !== undefined) {
+        const worst = report.perSkill
+            .filter((s) => s.n > 0)
+            .reduce((w, s) => (w && w.collisionRate >= s.collisionRate ? w : s), undefined);
+        if (worst && worst.collisionRate > maxOff) {
+            const top = worst.collidesWith[0];
+            const tail = top ? ` (top collider: ${top.skill} ${pct(top.rate)})` : "";
+            throw new Error(`expected each skill's collision rate ≤ ${String(maxOff)}, but ${worst.skill} = ${worst.collisionRate.toFixed(2)}${tail}`);
+        }
+    }
+    if (opts.maxPluginCollision !== undefined &&
+        report.collisionRate > opts.maxPluginCollision) {
+        throw new Error(`expected plugin collision rate ≤ ${String(opts.maxPluginCollision)}, got ${report.collisionRate.toFixed(2)}`);
+    }
+}
 // ─── Enforcement-gate detection (for the adversarial-gate eval) ───────────────
 //
 // A skill whose description states a HARD CONSTRAINT ("always write tests first",

package/dist/scan.d.ts

@@ -17,6 +17,7 @@ import { type ToolIssue } from "./core/tool-contract.js";
 import { type HookEventIssue } from "./core/hook-events.js";
 import { type McpIssue } from "./core/mcp-config.js";
 import { type DescriptionOverlap } from "./core/description-overlap.js";
+import { type DescriptionBudgetIssue } from "./core/skill-description-budget.js";
 import { type McpToolIssue } from "./core/mcp-tool.js";
 import { type McpContractToolError } from "./core/mcp.js";
 import { type McpHookIssue } from "./core/mcp-hook.js";
@@ -28,8 +29,6 @@ import { type DelegationTrifectaFinding } from "./core/delegation-trifecta.js";
 import { type HookBlockFinding } from "./core/hook-block-ineffective.js";
 import { type HookMatcherFinding } from "./core/hook-matcher.js";
 import { type PurityLevel, type EffectSurface } from "./core/effects.js";
-/** A named writing system. The label `unexpectedScript` reports + the config's expectation parse into this. */
-export type Script = "Latin" | "Cyrillic" | "Han" | "Japanese" | "Korean" | "Arabic" | "Hebrew" | "Greek" | "Devanagari" | "Thai";
 export interface ScanSkill {
     readonly name: string;
     readonly path: string;
@@ -41,15 +40,6 @@ export interface ScanSkill {
      */
     readonly description?: string;
     readonly userInvoked: boolean;
-    /**
-     * The description's dominant script when it DIFFERS from the expected one
-     * (default `"Latin"`), else null. The model's skill-selection context is
-     * English-centric, so a description in another script carries a cross-language
-     * trigger risk — it may under-fire on English prompts. A RISK flag, not a
-     * defect (a language-matched audience is fine); measure the real gap with the
-     * `audit` trigger tier / `measureTriggerRate`.
-     */
-    readonly descriptionScript: Script | null;
     /**
      * SKILL.md body references to a bundled file (`scripts/`/`references/`/`assets/`
      * or a relative markdown link with an extension) that don't resolve on disk
@@ -221,6 +211,8 @@ export interface ScanReport {
     readonly mcpHookIssues: readonly McpHookIssue[];
     /** Pairs of model-invocable skills whose descriptions are near-identical (precision collision). */
     readonly descriptionOverlaps: readonly DescriptionOverlap[];
+    /** Model-invocable skills whose description is so long the trigger signal is buried. */
+    readonly descriptionBudgetIssues: readonly DescriptionBudgetIssue[];
     /**
      * Lethal-trifecta findings across subagents + model-invocable skills — a unit
      * holding all three legs (read-private + ingest-untrusted + exfiltrate). Each
@@ -299,18 +291,6 @@ export interface SurfaceClassifier {
     readonly isAgent: (f: string) => boolean;
     readonly isCommand: (f: string) => boolean;
 }
-/**
- * The description's dominant alphabetic script when it DIFFERS from `expected`
- * (default `"Latin"`) — the cross-language trigger-risk signal. The model's
- * skill-selection context is English-centric, so a description written mostly in
- * another script may under-fire on English prompts. `expected` is a configurable
- * default, not a value judgement: a Russian-targeted pack sets it to `"Cyrillic"`
- * so its Cyrillic descriptions pass and an English one is flagged instead.
- * Returns null when the dominant script IS the expected one (or there's no
- * alphabetic content). Shared by `scan` and the future lint rule (one detector,
- * no drift). The ≥20% guard avoids a near-empty string tripping on one letter.
- */
-export declare function unexpectedScript(text: string, expected?: Script): Script | null;
 /**
  * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
  * runtime entrypoint; any other hook command is hand-written (a shell script or

package/dist/scan.js

@@ -13,7 +13,6 @@
  * stack on top later; this core stays pure so it runs anywhere in CI for free.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unexpectedScript = unexpectedScript;
 exports.isManagedHookCommand = isManagedHookCommand;
 exports.preferCompiledHooksMessage = preferCompiledHooksMessage;
 exports.scanPlugin = scanPlugin;
@@ -35,6 +34,7 @@ const hook_normalize_js_1 = require("./core/hook-normalize.js");
 const linters_js_1 = require("./core/linters.js");
 const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
 const description_overlap_js_1 = require("./core/description-overlap.js");
+const skill_description_budget_js_1 = require("./core/skill-description-budget.js");
 const mcp_tool_js_1 = require("./core/mcp-tool.js");
 const mcp_js_1 = require("./core/mcp.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
@@ -111,58 +111,6 @@ function skillName(path) {
         .split("/")
         .pop() ?? path);
 }
-// [Unicode \p{Script=…} property value (Node native, no dependency), our Script
-// label]. Japanese kana fold to "Japanese". Latin is the DEFAULT expectation (the
-// selector is English-centric), but it's just a default — a language-matched pack
-// can declare a different expectation, and then the OTHER script is the mismatch.
-const SCRIPTS = [
-    ["Latin", "Latin"],
-    ["Cyrillic", "Cyrillic"],
-    ["Han", "Han"],
-    ["Hiragana", "Japanese"],
-    ["Katakana", "Japanese"],
-    ["Hangul", "Korean"],
-    ["Arabic", "Arabic"],
-    ["Hebrew", "Hebrew"],
-    ["Greek", "Greek"],
-    ["Devanagari", "Devanagari"],
-    ["Thai", "Thai"],
-];
-/** Letter counts per named script label (Japanese kana folded together). */
-function scriptCounts(text) {
-    const counts = new Map();
-    for (const [script, label] of SCRIPTS) {
-        const n = (text.match(new RegExp(`\\p{Script=${script}}`, "gu")) ?? [])
-            .length;
-        if (n > 0)
-            counts.set(label, (counts.get(label) ?? 0) + n);
-    }
-    return counts;
-}
-/**
- * The description's dominant alphabetic script when it DIFFERS from `expected`
- * (default `"Latin"`) — the cross-language trigger-risk signal. The model's
- * skill-selection context is English-centric, so a description written mostly in
- * another script may under-fire on English prompts. `expected` is a configurable
- * default, not a value judgement: a Russian-targeted pack sets it to `"Cyrillic"`
- * so its Cyrillic descriptions pass and an English one is flagged instead.
- * Returns null when the dominant script IS the expected one (or there's no
- * alphabetic content). Shared by `scan` and the future lint rule (one detector,
- * no drift). The ≥20% guard avoids a near-empty string tripping on one letter.
- */
-function unexpectedScript(text, expected = "Latin") {
-    const counts = scriptCounts(text);
-    let total = 0;
-    let dominant = null;
-    for (const [label, count] of counts) {
-        total += count;
-        if (!dominant || count > dominant.count)
-            dominant = { label, count };
-    }
-    if (!dominant || dominant.label === expected)
-        return null;
-    return dominant.count / total >= 0.2 ? dominant.label : null;
-}
 /**
  * The first prose paragraph of a SKILL.md body (after the frontmatter and any
  * leading `#` headings) — Claude Code's FALLBACK skill description when the
@@ -236,7 +184,6 @@ function scanSkills(files, cls, ctx) {
             hasDescription: Boolean(effectiveDesc && effectiveDesc.length >= 20),
             description: effectiveDesc?.trim(),
             userInvoked,
-            descriptionScript: effectiveDesc ? unexpectedScript(effectiveDesc) : null,
             resourceIssues,
             trifecta,
             // A SKILL.md opening with `name:`/`description:` but no `---` fence loads
@@ -254,7 +201,7 @@ function scanSkills(files, cls, ctx) {
  * logic as `scanSkills` (frontmatter `description` ← first body paragraph), then
  * the NCD precision-proxy. See description-overlap.ts.
  */
-function descriptionOverlapsFor(files, cls) {
+function modelInvocableSkillSurfaces(files, cls) {
     const surfaces = [];
     for (const [path, md] of Object.entries(files)) {
         if (!cls.isSkill(path))
@@ -267,7 +214,18 @@ function descriptionOverlapsFor(files, cls) {
             continue;
         surfaces.push({ name: fm.name ?? skillName(path), description });
     }
-    return (0, description_overlap_js_1.findDescriptionOverlaps)(surfaces);
+    return surfaces;
+}
+function descriptionOverlapsFor(files, cls) {
+    return (0, description_overlap_js_1.findDescriptionOverlaps)(modelInvocableSkillSurfaces(files, cls));
+}
+/**
+ * Model-invocable skills whose description is so long the trigger signal is
+ * buried (heuristic proxy; degrades recall + precision). Same surfaces as the
+ * overlap check. See skill-description-budget.ts.
+ */
+function descriptionBudgetFor(files, cls) {
+    return (0, skill_description_budget_js_1.findDescriptionBudgetIssues)(modelInvocableSkillSurfaces(files, cls));
 }
 function scanAgents(files, dialect, declaredServers, cls) {
     const out = [];
@@ -797,6 +755,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         mcpIssues: (0, mcp_config_js_1.verifyMcpServers)(mcpServers),
         mcpHookIssues: (0, mcp_hook_js_1.verifyMcpHookTargets)(loaded.settings.hooks, declaredServers, dialect),
         descriptionOverlaps: descriptionOverlapsFor(loaded.files, cls),
+        descriptionBudgetIssues: descriptionBudgetFor(loaded.files, cls),
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,
         skillFenceIssues: skillFenceFindings,
@@ -923,7 +882,7 @@ function section(title, lines, count = lines.length) {
         return [];
     return [`${title} (${String(count)}):`, ...lines, ""];
 }
-/** One skill's report line: ✓/⚠ + name + notes (no-trigger, user-invoked, language risk). */
+/** One skill's report line: ✓/⚠ + name + notes (no-trigger, user-invoked). */
 function skillLine(s) {
     if (!s.hasDescription) {
         return `  ⚠ ${s.name} (no usable description — no frontmatter description and no body text — can't trigger)`;
@@ -931,11 +890,7 @@ function skillLine(s) {
     const notes = [];
     if (s.userInvoked)
         notes.push("user-invoked");
-    if (s.descriptionScript) {
-        notes.push(`description in ${s.descriptionScript} — cross-language trigger risk`);
-    }
-    const mark = s.descriptionScript ? "⚠" : "✓";
-    return `  ${mark} ${s.name}${notes.length ? ` (${notes.join("; ")})` : ""}`;
+    return `  ✓ ${s.name}${notes.length ? ` (${notes.join("; ")})` : ""}`;
 }
 /** One agent's report block: ✗ (broken contract) / ⚠ (inherits all) / ✓ + issues + purity. */
 function agentLines(a) {
@@ -1002,6 +957,7 @@ function formatScanReport(r) {
     out.push(...section("MCP config", r.mcpIssues.map((i) => `  ✗ ${i.message}`)));
     out.push(...section("MCP hook targets", r.mcpHookIssues.map((i) => `  ✗ ${i.message}`)));
     out.push(...section("Description overlap (precision risk)", r.descriptionOverlaps.map((o) => `  ⚠ ${o.message}`)));
+    out.push(...section("Description budget (trigger-signal risk)", r.descriptionBudgetIssues.map((o) => `  ⚠ ${o.message}`)));
     out.push(...section("Lethal trifecta (prompt-injection exfil risk)", r.trifectaFindings.map((t) => `  ${t.finding.severity === "hard" ? "✗" : "⚠"} ${t.kind} ${t.name} (${t.path}): ${t.finding.message}`)));
     out.push(...section("Skill bundled resources", r.skillResourceIssues.map((s) => `  ✗ ${s.name}: ${s.finding.ref} (line ${String(s.finding.line)}) — bundled resource not found`)));
     out.push(...section("Invisible skills (missing frontmatter fence)", r.skillFenceIssues.map((s) => `  ✗ ${s.name} (${s.path}): opens with \`${s.finding.key}:\` but no \`---\` fence — loads as body, never fires`)));
@@ -1028,13 +984,6 @@ function formatScanReport(r) {
     if (warnings.length > 0) {
         out.push("Warnings:", ...warnings.map((w) => `  - ${w}`), "");
     }
-    // Cross-language trigger risk is a RISK, not a structural defect (a
-    // language-matched audience is fine), so it's reported separately from the
-    // verdict — it points at the behavioral column, it doesn't fail the scan.
-    const mismatched = r.skills.filter((s) => s.descriptionScript);
-    if (mismatched.length > 0) {
-        out.push(`⚠ ${String(mismatched.length)} skill(s) have descriptions in an unexpected script (cross-language trigger risk) — measure with \`vigiles measure\``, "");
-    }
     // Skill-metadata is a RECOMMENDATION, not a structural defect (the skill loads
     // via fallbacks) — reported as a soft note, never counted in the verdict.
     if (r.skillMetaIssues.length > 0) {

package/dist/setup-plan.d.ts

@@ -95,7 +95,7 @@ export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "unt
  * keep their own default severities. Named for the group taxonomy
  * (research/install-enforcement-dx.md).
  */
-export declare const NUDGE_RULES: readonly ["frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher"];
+export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher"];
 export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
     harness: string | string[];
     strict: boolean;

package/dist/setup-plan.js

@@ -121,6 +121,7 @@ exports.WORKFLOW_RULES = [
  * (research/install-enforcement-dx.md).
  */
 exports.NUDGE_RULES = [
+    "skill-description-budget",
     "frontmatter-valid",
     "skill-frontmatter",
     "prefer-compiled-hooks",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",

package/skills/adopt-spec/SKILL.md

@@ -7,7 +7,16 @@ argument-hint: <path to CLAUDE.md, defaults to CLAUDE.md>
 
 Start a typed `CLAUDE.md.spec.ts` from an existing hand-written CLAUDE.md (or AGENTS.md). This is the non-destructive adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
 
-> **Faithful by default, and reversible.** Adoption is non-destructive: the goal is a spec that compiles back to the user's existing file as closely as possible — preserve every rule, command, key file, and prose section. Don't upgrade `guidance()` to `enforce()` here; that's a separate, opt-in step (the `strengthen` skill). And it's never a one-way door — `vigiles eject <file>` hands the file back as plain hand-owned markdown anytime. For the lightest touch with no spec at all, inline `<!-- vigiles:enforce ... -->` comments are verified by `vigiles lint` with the same engine.
+## Adoption rules
+
+Adoption is the **safe, faithful on-ramp — never an upgrade in disguise.** These are non-negotiable:
+
+- **Faithful.** Preserve every rule, command, key file, and prose section as-is. Invent nothing — the spec must compile back to ~the user's existing file.
+- **Non-destructive.** Never edit the original `CLAUDE.md` / `AGENTS.md`. Only write the new `.spec.ts`. Never auto-`compile` over the file — switching it to spec-managed is a separate, explicit step the user runs with a diff to review.
+- **Don't escalate enforcement.** Keep `guidance()` as `guidance()`. Upgrading to `enforce()` has a cost (config/plugins, possible false positives) and is a separate opt-in step — the `strengthen` skill. Adoption is **not** turning on strict / `workflow` gating.
+- **Reversible.** `vigiles eject <file>` hands the file back as plain hand-owned markdown anytime — it's never a one-way door. Tell the user this.
+- **Ask before writing.** Present the generated spec and a conversion summary first; write only on the user's yes.
+- **A lighter touch exists.** For no spec at all, inline `<!-- vigiles:enforce ... -->` comments are verified by `vigiles lint` with the same engine.
 
 ## Instructions
 

package/skills/edit-spec/SKILL.md

@@ -136,6 +136,7 @@ If the vigiles plugin is installed (`/plugin marketplace add zernie/vigiles` the
 
 ## Important
 
+- **Do what's asked; don't silently escalate enforcement.** Add the rule the user asked for. If making it an `enforce()` would need a linter-config edit or a plugin install (a cost), or if it could fail a clean CI, **say so and let the user choose** — don't change linter config or flip on strict / `workflow` gating on your own. A pure win (a rule that's already enabled) you can just apply. The `strengthen` skill owns `guidance()` → `enforce()` upgrades.
 - **Never edit CLAUDE.md or AGENTS.md directly** — they have a vigiles hash comment and are build artifacts
 - **The spec is TypeScript** — you get type checking, autocomplete, and verified references
 - **`enforce()` rules are verified** — the compiler checks the rule exists AND is enabled in your linter config

package/skills/strengthen/SKILL.md

@@ -5,6 +5,10 @@ description: Upgrade a vigiles spec's guidance() rules to enforce() — scan the
 
 Scan spec files for `guidance()` rules and suggest `enforce()` replacements backed by real linter rules.
 
+## Principle: auto the free wins, nudge for the costs
+
+The dividing line is **cost, not strictness**. A `guidance()` → `enforce()` swap where the linter rule **already exists and is enabled** is a pure win — free, reversible, no false-positive risk — so apply it (Tier 1 below). Anything that **costs** something — editing linter config, installing a plugin, or a change that could fail a clean CI — is the user's call: **present it with the tradeoff spelled out and let them choose** (Tiers 2–4). Never silently edit config, install a dependency, or escalate the repo into strict gating. This is the `init` enforcement model (structural = on by default, workflow/strict = opt-in) applied at edit time.
+
 ## Instructions
 
 ### Step 0: Choose Mode

package/skills/test-harness/SKILL.md

@@ -190,6 +190,23 @@ job that asserts the capability is present, run **`vigiles test --no-skip`** so
 skipped tier fails — a green-with-skips is untested surface. Keep unit +
 deterministic tests in CI (free); run evals locally or on a schedule with auth.
 
+### After a real-model run: TELL THE USER WHAT IT SPENT
+
+Whenever you run a real-model eval (`runEval` / `measureArms` / `measureTriggerRate`
+/ `measure`), **surface the spend to the user in your reply** — don't let a paid run
+be silent. `runEval` prints a cost block to stderr and every report carries `usage`
+(`report.arms[*].usage`: `totalCostUsd` + token counts). Relay, in plain words:
+
+- **tokens spent** and the **API-equivalent `$`** (`total_cost_usd` — what it _would_
+  cost at metered API rates);
+- **how it was billed** — "on your Claude subscription (**$0 metered**)" if you're
+  logged in, or a **⚠ warning** if `ANTHROPIC_API_KEY` is set (that run was billed
+  **per token** — tell them to unset it and `claude login` to run free).
+
+We do **not** show "% of your subscription" — Anthropic doesn't expose a plan's
+quota, so any percentage would be invented. Tokens + API-equivalent `$` + the
+billed-to line is the honest, complete picture. Keep the user's cost visible, always.
+
 ## Step 5 — Lock the eval so CI stays honest (you do this automatically)
 
 Real-model evals run on the user's subscription — locally, never in CI. So **as