vigiles 12.0.0 → 12.2.0

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-commands.d.ts

@@ -11,7 +11,7 @@
  * recognizes exactly these, so this list can't silently drift from the code.
  */
 /** Human-facing verbs (printed in help; typed by a human/agent/CI). */
-export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "audit", "scaffold-test", "generate", "hook-runtime"];
+export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "audit", "generate", "hook-runtime"];
 /** Runtime entrypoint kinds under `vigiles hook-runtime <kind>` (emitted, not typed). */
 export declare const HOOK_RUNTIME_KINDS: readonly ["run-program", "agent", "agent-start", "agent-done", "skill", "skill-tool", "skill-start", "skill-done", "run-skill", "intercept-tool", "guard", "action", "refs", "eval-lock-nudge", "effect-enter", "effect-exit"];
 export type Verb = (typeof VERBS)[number];

package/dist/cli-commands.js

@@ -22,7 +22,6 @@ exports.VERBS = [
     "test",
     "eval",
     "audit",
-    "scaffold-test",
     "generate",
     "hook-runtime",
 ];

package/dist/cli.js

@@ -22,8 +22,6 @@ const cli_flags_js_1 = require("./cli-flags.js");
 const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
-const scaffold_test_js_1 = require("./scaffold-test.js");
-const effects_js_1 = require("./core/effects.js");
 const scan_js_1 = require("./scan.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
 const dialect_drift_js_1 = require("./dialect-drift.js");
@@ -52,6 +50,7 @@ const hook_install_js_1 = require("./hook-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const observe_js_1 = require("./observe.js");
 const effect_region_js_1 = require("./adapters/claude-code/effect-region.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
 const refs_js_1 = require("./core/refs.js");
@@ -676,6 +675,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 +1027,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 +1124,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 +2781,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 +
@@ -3577,135 +3610,6 @@ function capabilitiesOfReport(report, dialect) {
     }));
     return (0, generate_harness_js_1.computeHarnessCapabilities)(agents, dialect);
 }
-/**
- * The plugin's declared name for the namespaced skill id, read from the layout's
- * manifest (adapter-aware path, not a hardcoded `.claude-plugin/`), falling back to
- * the dir basename. JSON manifests only for now (a TOML/Codex manifest → basename).
- */
-function pluginNameFor(dir, manifestPath) {
-    try {
-        const manifest = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, manifestPath), "utf-8"));
-        if (typeof manifest.name === "string" && manifest.name)
-            return manifest.name;
-    }
-    catch {
-        /* missing / non-JSON manifest → fall back */
-    }
-    return (0, node_path_1.basename)(dir);
-}
-/** Enrich an untested Surface with the metadata the right template needs. */
-/** Extract `"name": type` fields from one rendered `vigiles:ok`/`err` shape block. */
-function parseContractFields(block) {
-    const fields = [];
-    const re = /"([^"]+)"\s*:\s*(string\[\]|string|number|boolean)/g;
-    let m;
-    while ((m = re.exec(block)) !== null) {
-        fields.push({ name: m[1], type: m[2] });
-    }
-    return fields;
-}
-/**
- * Parse a subagent's compiled `## Output contract` (the `vigiles:ok` / `vigiles:err`
- * blocks the compiler emits) back into a typed `ResultContract`, so the generator
- * can write an `assertAgentOk` test against the real fields. Returns null when the
- * agent has no result() contract.
- */
-function parseResultContract(md) {
-    const ok = /```vigiles:ok\n([\s\S]*?)```/.exec(md);
-    const err = /```vigiles:err\n([\s\S]*?)```/.exec(md);
-    if (!ok && !err)
-        return null;
-    const okFields = ok ? parseContractFields(ok[1]) : [];
-    const errFields = err ? parseContractFields(err[1]) : [];
-    if (okFields.length === 0 && errFields.length === 0)
-        return null;
-    return { ok: okFields, err: errFields };
-}
-function scaffoldInputFor(s, report, pluginName, dir, dialect) {
-    const base = { kind: s.kind, name: s.name, path: s.path };
-    switch (s.kind) {
-        case "skill": {
-            const sk = report.skills.find((x) => x.name === s.name);
-            return { ...base, pluginName, userInvoked: sk?.userInvoked };
-        }
-        case "agent": {
-            const ag = report.agents.find((x) => x.name === s.name);
-            const tools = ag?.tools ?? null;
-            const sideEffectingTools = tools
-                ? (0, effects_js_1.effectSurface)(tools, dialect).sideEffecting
-                : undefined;
-            let resultContract = null;
-            try {
-                resultContract = parseResultContract((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, s.path), "utf-8"));
-            }
-            catch {
-                // agent .md unreadable → no contract to generate against
-            }
-            return { ...base, tools, sideEffectingTools, resultContract };
-        }
-        case "hook":
-            return { ...base, hookCommand: `bash ${s.path}` };
-    }
-}
-/**
- * `vigiles scaffold-test [dir]` — generate a runnable STARTER test for each
- * untested skill/agent/hook (B1, test-gen from free-form). Reuses the
- * untested-surface detector for the list + `scan` for the metadata, then emits the
- * cheapest meaningful tier per kind (hook → `runHook`, skill → `measureTriggerRate`,
- * subagent → `runHarnessTest`) at the surface's suggested test path. Dry-run by
- * default (prints the scaffolds); `--write` creates the files (never clobbering an
- * existing one); `--json` for the agent-consumable `{ path, content }[]`.
- */
-function handleScaffoldTest(restArgs, args) {
-    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
-    const write = args.includes("--write");
-    const json = args.includes("--json");
-    const harnessFlag = harnessFlagFrom(args);
-    const adapter = harnessFlag
-        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
-        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
-    const { untested } = (0, test_coverage_js_1.findUntestedSurfaces)({
-        basePath: dir,
-        layout: adapter.layout,
-    });
-    const report = (0, scan_js_1.scanPlugin)(dir, adapter.layout, adapter.dialect);
-    const pluginName = pluginNameFor(dir, adapter.layout.manifestPath);
-    const scaffolds = untested.map((s) => (0, scaffold_test_js_1.scaffoldTest)(scaffoldInputFor(s, report, pluginName, dir, adapter.dialect)));
-    if (json) {
-        console.log(JSON.stringify(scaffolds, null, 2));
-        return;
-    }
-    if (!write) {
-        console.log((0, scaffold_test_js_1.formatScaffolds)(scaffolds));
-        for (const s of scaffolds) {
-            console.log(`\n# ${s.path}\n`);
-            console.log(s.content);
-        }
-        if (scaffolds.length > 0) {
-            console.log("Re-run with --write to create these files.");
-        }
-        return;
-    }
-    const written = [];
-    const skipped = [];
-    for (const s of scaffolds) {
-        const target = (0, node_path_1.resolve)(dir, s.path);
-        if ((0, node_fs_1.existsSync)(target)) {
-            skipped.push(s.path);
-            continue;
-        }
-        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
-        (0, node_fs_1.writeFileSync)(target, s.content);
-        written.push(s.path);
-    }
-    for (const p of written)
-        console.log(`✓ wrote ${p}`);
-    for (const p of skipped)
-        console.log(`⊘ skipped ${p} (already exists)`);
-    if (written.length === 0 && skipped.length === 0) {
-        console.log("Nothing to scaffold — every surface already has a test.");
-    }
-}
 function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
@@ -3722,7 +3626,6 @@ function printUsage(command) {
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)");
     console.log("                                 --update records each named eval's result to a committed lock (run locally on your subscription)");
     console.log("                                 --check verifies committed eval results against current inputs WITHOUT a model — the CI staleness gate");
-    console.log("  vigiles scaffold-test [dir]    Generate a starter test for each untested skill/agent/hook (--write, --json)");
     console.log("");
     console.log("Examples:");
     console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
@@ -3828,6 +3731,11 @@ function skillStartCommand(target) {
         process.exit(2);
     }
     (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
+    // Record the fire in the flight recorder: the skill NAME is the parent dir of
+    // its SKILL.md (skills/<name>/SKILL.md), falling back to the raw target.
+    const parts = target.replace(/\\/g, "/").split("/").filter(Boolean);
+    const name = parts.length >= 2 ? parts[parts.length - 2] : (parts[0] ?? target);
+    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true });
     console.log(`Active skill: ${target}`);
 }
 /**
@@ -3928,6 +3836,13 @@ function agentHookCommand() {
         return;
     const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(cwd, tool, command);
     if (!decision.allow) {
+        (0, observe_js_1.appendObservation)({
+            kind: "agent",
+            name: (0, agent_runtime_js_1.readActiveAgent)(cwd) ?? "unknown",
+            tool,
+            allowed: false,
+            reason: decision.message,
+        });
         console.error(decision.message);
         process.exit(2);
     }
@@ -4476,10 +4391,26 @@ function emitGate(decision, on, mode, file) {
     const action = (0, hook_program_js_1.gateAction)(decision, mode);
     switch (action.kind) {
         case "block":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: "deny",
+                mode: "enforce",
+                rule: file,
+                reason: action.reason,
+            });
             console.error(action.reason);
             process.exit(2);
             return;
         case "ask":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: "ask",
+                mode: "enforce",
+                rule: file,
+                reason: action.reason,
+            });
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
                     hookEventName: on,
@@ -4489,6 +4420,14 @@ function emitGate(decision, on, mode, file) {
             }) + "\n");
             return;
         case "observe":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: action.would,
+                mode: "observe",
+                rule: file,
+                reason: action.reason,
+            });
             recordObservation(file, on, action.would, action.reason);
             console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
             return; // exit 0 — observe never blocks
@@ -5078,10 +5017,14 @@ async function main() {
                 // Surfaced in the AuditReport (the report's "Create spec" command-emit
                 // buttons read it) and the terminal nudge below.
                 const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile);
+                // Read the local flight recorder ONCE — feeds both the JSON report
+                // (structured summary, the product boundary) and the terminal render.
+                const ledgerRecords = (0, observe_js_1.readObservations)(root);
                 const auditReport = (0, audit_report_js_1.buildAuditReport)(report, {
                     harness: adapter.name,
                     vigilesVersion: getVersion(),
                     adoptableSurfaces,
+                    observations: (0, observe_js_1.summarizeObservations)(ledgerRecords),
                 });
                 const sc = auditReport.score;
                 const plan = (0, optimize_js_1.optimize)(report);
@@ -5112,6 +5055,12 @@ async function main() {
                         .length);
                     if (fireNudge)
                         console.log("\n" + fireNudge);
+                    // The flight recorder: a compact summary of what the harness actually
+                    // DID in real sessions (hook/agent decisions), read off the local
+                    // agent-readable ledger. Empty (skipped) until something is recorded.
+                    const ledgerSummary = (0, observe_js_1.formatLedgerSummary)(ledgerRecords);
+                    if (ledgerSummary)
+                        console.log("\n" + ledgerSummary);
                 }
                 // ONE read-vs-run decision for the EXECUTING checks (live MCP + skill
                 // firing). A plain `audit` is a deterministic READ; these run only on
@@ -5145,6 +5094,21 @@ async function main() {
                     // default; `--fail-on-widen` exits non-zero (the opt-in CI gate).
                     const beforeReport = (0, scan_js_1.scanPlugin)((0, node_path_1.resolve)(capBase), adapter.layout, adapter.dialect);
                     const diff = (0, capability_diff_js_1.diffCapabilities)(capabilitiesOfReport(beforeReport, adapter.dialect), capabilitiesOfReport(report, adapter.dialect));
+                    // Feed the flight recorder: the blast-radius change (moat #2) as a record.
+                    // Write to the AUDITED root's ledger (not the caller's cwd) — the same
+                    // `root` the audit reads back via `readObservations(root)`, so a
+                    // `vigiles audit ./after --capability-diff=./before` from a parent dir
+                    // records into ./after/.vigiles/, not the parent workspace.
+                    (0, observe_js_1.appendObservation)({
+                        kind: "capability-diff",
+                        added: [
+                            ...diff.addedSideEffecting,
+                            ...diff.addedUnknown,
+                            ...diff.addedReadOnly,
+                        ],
+                        removed: [...diff.removed],
+                        widened: diff.widened,
+                    }, root);
                     console.log(json
                         ? JSON.stringify({ capabilityDiff: diff }, null, 2)
                         : "\n" + (0, capability_diff_js_1.formatCapabilityDiff)(diff));
@@ -5243,9 +5207,6 @@ async function main() {
             }
             break;
         }
-        case "scaffold-test":
-            handleScaffoldTest(restArgs, args);
-            break;
         // --- Plumbing ---
         case "generate":
             await handleGenerate(restArgs, args);

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