vigiles 12.0.0 → 12.2.0

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/scaffold-test.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.scaffoldTest = scaffoldTest;
 exports.formatScaffolds = formatScaffolds;
 /**
- * `vigiles scaffold-test` — the deterministic test-gen engine (B1 v0).
+ * The deterministic test-gen engine (B1 v0) — skill-internal (the `test-harness`
+ * skill drives it; there is no standalone CLI verb).
  *
  * Free-form in, a RUNNABLE starter test out. Given an existing hand-written
  * skill / subagent / hook, emit a scaffolded `*.harness.mjs` / `*.eval.mjs` at the
@@ -35,7 +36,7 @@ function header(title, run) {
         "/**",
         ` * ${title}`,
         " *",
-        " * Generated by `vigiles scaffold-test` — a STARTER, not a finished test. Fill in",
+        " * Generated by vigiles (the test-harness skill) — a STARTER, not a finished test. Fill in",
         " * the TODOs (they're where a human/model must supply judgement), then run:",
         ` *   ${run}`,
         " */",

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.2.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/debug-my-harness/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: debug-my-harness
+description: Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the harness actually did. NOT for writing new rules (use strengthen) or editing the spec (use edit-spec).
+---
+
+Diagnose harness misbehavior from the **flight recorder** — the local, append-only ledger
+at `.vigiles/runs.jsonl` that vigiles writes as your harness runs. It records what actually
+happened, so you debug from evidence instead of guessing.
+
+## What's in the ledger
+
+One JSON record per line, each with a `kind`:
+
+- `hook` — a compiled-hook gate decision: `{event, decision: allow|deny|ask, mode: enforce|observe, rule, cmd, reason}`.
+- `agent` — a subagent tool-contract decision: `{name, tool, allowed, reason}` (a `false` = the agent went outside its lane).
+- `skill` — a skill activation: `{name, fired}`.
+- `eval` — a measured metric: `{name, metric, value}` (e.g. trigger-rate recall/precision).
+- `capability-diff` — a blast-radius change: `{pr, added, removed, widened}`.
+
+## Instructions
+
+### Step 1: Read the ledger
+
+Read `.vigiles/runs.jsonl` (JSONL — one record per line; tolerate a torn last line). If it's
+absent or empty, say so — there's nothing recorded yet; suggest running the harness (or
+`vigiles audit`) first. Do NOT fabricate records.
+
+### Step 2: Answer the specific question, evidence-first
+
+Match the user's question to the ledger:
+
+- **"Why did skill X stop firing / why does the wrong one run?"** — count `skill` fires by
+  name over time. If X's fire-rate dropped, look for a sibling that fired on the same kinds
+  of prompts (a **selection collision**) and check their descriptions for overlap. Recommend
+  differentiating or merging the descriptions.
+- **"Why didn't my hook block that?"** — find `hook` records for the event. A `decision:
+allow` on something that should be denied, or `mode: observe` (shadow, never blocks), or
+  the absence of any record, tells you which. Recommend flipping `observe`→`enforce` or
+  fixing the gate logic.
+- **"Did a subagent misbehave?"** — list `agent` records with `allowed: false`: the agent
+  reached for a tool outside its declared contract. Point at the contract to tighten or widen.
+- **"Is it getting worse?"** — compare `eval` metric values (recall/precision) across runs;
+  a downward trend is drift (often after a harness/model upgrade).
+
+### Step 3: Recommend a fix, tied to the evidence
+
+Prefer **promoting an ignored-but-decidable rule from prose to a deterministic gate**: a
+repeated `agent` violation or a rule the agent keeps breaking → a compiled hook or a tighter
+tool-contract (the `strengthen` skill can help). A description collision → differentiate the
+skill descriptions. Always cite the specific records you based the diagnosis on.
+
+### Step 4: Offer the next step
+
+If the fix is a spec change, hand off to `edit-spec`. If it's promoting guidance to a linter
+rule, hand off to `strengthen`. If a behavioral claim needs measuring (does the skill fire
+now?), hand off to `test-harness` (`measureTriggerRate`).

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