vigiles 11.0.0 → 12.1.0

package/dist/cli.js

@@ -17,6 +17,7 @@ const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
 const validate_js_1 = require("./core/validate.js");
+const eval_lock_js_1 = require("./eval-lock.js");
 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");
@@ -675,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 ||
@@ -1026,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);
@@ -1119,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,
@@ -1601,7 +1609,19 @@ function specReferencedElsewhere(specFile, ejectedFile) {
 /** Full GitHub Actions workflow that wires the production `zernie/vigiles@v1`
  * Action (lint pillar) and, when the test pillar is set up, a deterministic
  * harness job. */
-function vigilesWorkflow(plan) {
+/** The npm package(s) that provide each harness's CLI binary — the deterministic
+ * harness tier spawns the real agent CLI against a mock model (no API key). A repo
+ * targeting both harnesses installs both. */
+function harnessTestBinaries(harnesses) {
+    const pkgs = [];
+    if (harnesses.includes("claude"))
+        pkgs.push("@anthropic-ai/claude-code");
+    if (harnesses.includes("codex"))
+        pkgs.push("@openai/codex");
+    // Fall back to Claude Code if the set is somehow empty (back-compatible default).
+    return (pkgs.length > 0 ? pkgs : ["@anthropic-ai/claude-code"]).join(" ");
+}
+function vigilesWorkflow(plan, harnesses) {
     const harness = plan.test
         ? `
   harness:
@@ -1615,8 +1635,23 @@ function vigilesWorkflow(plan) {
         with:
           node-version: "20"
       - run: npm install
-      - run: npm i -g @anthropic-ai/claude-code # mock tier needs the binary, no API key
+      - run: npm i -g ${harnessTestBinaries(harnesses)} # mock tier needs the binary, no API key
       - run: npx vigiles test
+
+  eval-check:
+    # Eval staleness gate — real-model evals run LOCALLY on your subscription
+    # (\`npx vigiles eval --update\`, which commits a lock); this job VERIFIES those
+    # committed results against the current inputs with NO model call. It stays a
+    # green no-op until you commit your first lock. See docs/harness-testing.md.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - uses: zernie/vigiles@v1
+        with:
+          command: eval-check
 `
         : "";
     return `name: vigiles
@@ -1687,7 +1722,7 @@ function rewriteRemovedSubcommands(content) {
  * commit hint). An existing workflow is never clobbered unless `--force`, but a
  * STALE one (old bare-`npx vigiles` API, or a removed subcommand) is reported
  * loudly instead of silently skipped — and rewritten in place with `--force`. */
-function wireGha(plan) {
+function wireGha(plan, harnesses) {
     const dir = (0, node_path_1.resolve)(process.cwd(), ".github", "workflows");
     const path = (0, node_path_1.resolve)(dir, "vigiles.yml");
     const rel = ".github/workflows/vigiles.yml";
@@ -1708,7 +1743,7 @@ function wireGha(plan) {
         }
         else if (workflowUsesStaleApi(content)) {
             if (plan.force) {
-                (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan));
+                (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan, harnesses));
                 console.log(`✓ Regenerated ${rel} (was a stale bare \`npx vigiles\`)`);
                 return [rel];
             }
@@ -1724,7 +1759,7 @@ function wireGha(plan) {
     }
     if (!(0, node_fs_1.existsSync)(dir))
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
-    (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan));
+    (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan, harnesses));
     console.log("✓ Created .github/workflows/vigiles.yml (uses zernie/vigiles@v1)");
     return [".github/workflows/vigiles.yml"];
 }
@@ -2130,6 +2165,36 @@ function installPlugins(harnesses) {
         console.log("");
         reportInstall(plan, runInstall(plan, exec));
     }
+    // Claude Code gets its hooks from the global marketplace plugin; Codex has no
+    // global store, so wire vigiles's proactive nudge hooks into the repo's
+    // .codex/config.toml directly (the idiomatic, repo-committed place).
+    if (harnesses.includes("codex"))
+        wireCodexHooks();
+}
+/**
+ * Wire vigiles's proactive nudge hooks into `.codex/config.toml` (idempotently).
+ * Codex honors `additionalContext` on `PostToolUse`, and these run as direct
+ * `npx vigiles hook-runtime …` commands (no plugin root / vendored script), so a
+ * Codex user gets the same eval-lock + refs nudges a Claude Code user gets from
+ * the marketplace plugin. The pure merge is `applyCodexPluginHooks` (unit-tested
+ * in setup-plan.test.ts) — this only does the read/parse/write IO.
+ */
+function wireCodexHooks() {
+    const path = (0, node_path_1.resolve)(process.cwd(), ".codex", "config.toml");
+    let config = {};
+    if ((0, node_fs_1.existsSync)(path)) {
+        try {
+            config = (0, toml_1.parse)((0, node_fs_1.readFileSync)(path, "utf-8"));
+        }
+        catch {
+            console.log("⚠ .codex/config.toml is not valid TOML — skipping Codex hook wiring (fix it, then re-run `vigiles init`).");
+            return;
+        }
+    }
+    const merged = (0, setup_plan_js_1.applyCodexPluginHooks)(config);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, (0, hook_install_js_1.serializeConfig)(merged, "toml"));
+    console.log("✓ Wired the eval-lock + refs nudge hooks into .codex/config.toml (commit it)");
 }
 /** Add/upgrade `vigiles` in the project's `devDependencies` (and move it out of
  * `dependencies` if it's there). Returns the files it wrote (for the commit
@@ -2293,7 +2358,7 @@ async function setup(args) {
     // CI — the production Action (+ a harness job when Pillar 2 is on).
     if (plan.gha) {
         console.log("");
-        written.push(...wireGha(plan));
+        written.push(...wireGha(plan, harnesses));
     }
     // Plugin/skill install — per-harness (Claude marketplace / Codex direct).
     if (plan.plugin) {
@@ -2717,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 +
@@ -3406,10 +3498,55 @@ async function handleGenerateHarness(args, restArgs) {
  * tier needs it, just like the node:test suite). `--trials=N` is forwarded to
  * eval scripts via the `VIGILES_TRIALS` env var.
  */
+/**
+ * Resolve the eval LOCK env from the `eval` flags. `--update` records each named
+ * eval's report to a committed `.vigiles/eval-locks/<name>.lock.json` (run locally
+ * on your subscription); `--check` (CI) verifies the committed result against the
+ * current inputs WITHOUT a model call. `--check` is a green NO-OP until the first
+ * lock is committed (smooth adoption). Returns the env to thread, or `"skip"` to
+ * exit green now. `--check`+`--update` together is a usage error (exit 2). The
+ * behavior epoch comes from `.vigilesrc.json` `eval.apiVersion` (committed).
+ */
+function resolveEvalLockEnv(args) {
+    const wantCheck = args.includes("--check");
+    const wantUpdate = args.includes("--update");
+    if (wantCheck && wantUpdate) {
+        console.error("vigiles eval: --check and --update are mutually exclusive (one verifies, one records).");
+        process.exit(2);
+    }
+    if (wantCheck &&
+        !(0, eval_lock_js_1.anyLocksCommitted)((0, node_path_1.resolve)(process.cwd(), eval_lock_js_1.DEFAULT_LOCK_DIR))) {
+        console.log("ℹ vigiles eval --check: no committed eval locks found — nothing to verify.\n" +
+            "  Run `vigiles eval --update` locally (on your subscription) and commit the\n" +
+            "  lock to enable the CI staleness gate.");
+        return "skip";
+    }
+    const env = {};
+    if (wantCheck)
+        env.VIGILES_EVAL_LOCK = "check";
+    if (wantUpdate)
+        env.VIGILES_EVAL_LOCK = "update";
+    if (wantCheck || wantUpdate) {
+        const apiVersion = (0, validate_js_1.loadConfig)().eval?.apiVersion;
+        if (apiVersion !== undefined)
+            env.VIGILES_EVAL_API_VERSION = String(apiVersion);
+    }
+    return env;
+}
 function handleRunScripts(kind, args, restArgs) {
     const cwd = process.cwd();
     // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
     const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
+    // The eval LOCK flags (`--check`/`--update`) are resolved BEFORE file discovery
+    // so mutual-exclusion + the cold-start no-op are honored regardless of file
+    // count. Returns the env to thread to scripts, or `"skip"` to exit green now.
+    let lockEnv = {};
+    if (kind === "eval") {
+        const r = resolveEvalLockEnv(args);
+        if (r === "skip")
+            return;
+        lockEnv = r;
+    }
     const files = (0, run_scripts_js_1.discoverScripts)(restArgs, defaultGlob, cwd);
     // `--min=N`: a CI gate asserts at least N scripts actually RAN — so a bad path,
     // a renamed file, or a glob that matched nothing fails LOUD instead of passing
@@ -3438,7 +3575,7 @@ function handleRunScripts(kind, args, restArgs) {
     // it's part of the measurement definition, so it belongs in the spec
     // (`model` / `minModel`), version-controlled, not a hidden override.
     const trialsFlag = args.find((a) => a.startsWith("--trials="));
-    const env = {};
+    const env = { ...lockEnv };
     if (trialsFlag)
         env.VIGILES_TRIALS = trialsFlag.split("=")[1];
     console.log(`Running ${String(files.length)} ${kind} file(s):\n`);
@@ -3617,6 +3754,8 @@ function printUsage(command) {
     console.log("                                 --serve opens a LIVE local report whose buttons create specs in one click (own repo only; loopback + token-guarded) · --no-serve to skip the prompt");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
     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:");
@@ -3932,6 +4071,9 @@ async function handleHookRuntime(kind, restArgs) {
         case "refs":
             refsHookCommand();
             return;
+        case "eval-lock-nudge":
+            evalLockNudgeHookCommand();
+            return;
         case "effect-enter":
             (0, effect_region_js_1.setEffectActive)(process.cwd());
             console.log("Effect boundary entered.");
@@ -3978,6 +4120,45 @@ const INSTRUCTION_FILE = /^(SKILL|CLAUDE|AGENTS)\.md$/;
 function isInstructionFile(file) {
     return INSTRUCTION_FILE.test((0, node_path_1.basename)(file));
 }
+/**
+ * PostToolUse-hook entrypoint: when the agent edits an eval input (a `SKILL.md`
+ * trigger surface or an `*.eval.*` script), and committed eval locks exist, inject
+ * a NON-BLOCKING reminder to re-run `vigiles eval --update`. Self-gating (silent
+ * until a lock is committed), never blocks, never runs an eval — a reminder, not a
+ * gate (the gate is `eval --check` in CI). The harness-neutral nudge lives in
+ * `evalLockNudge`; both CC and Codex deliver it as `additionalContext` on
+ * `PostToolUse` (confirmed — see docs/harness-testing-codex.md).
+ */
+function evalLockNudgeHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin → nothing to do */
+    }
+    let file = "";
+    try {
+        const j = JSON.parse(raw);
+        file = j.tool_input?.file_path ?? "";
+    }
+    catch {
+        /* malformed → nothing to do */
+    }
+    if (!file)
+        return;
+    const cwd = process.cwd();
+    const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
+    const msg = (0, eval_lock_js_1.evalLockNudge)(target, (0, node_path_1.resolve)(cwd, eval_lock_js_1.DEFAULT_LOCK_DIR));
+    if (!msg)
+        return;
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: msg,
+        },
+    }) + "\n");
+}
 /**
  * PostToolUse-hook entrypoint: when the agent edits an instruction file, force
  * every code reference to carry a file-qualified mark (`path.ext#symbol`) and
@@ -4153,31 +4334,63 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         : (0, hook_install_js_1.mergeHooksJson)(existing, compiled.hooks, file);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(settingsAbs), { recursive: true });
     (0, node_fs_1.writeFileSync)(settingsAbs, (0, hook_install_js_1.serializeConfig)(merged, format));
-    // Honest gap (no silent skips): the gate/deny path is exit-2 and cross-harness,
-    // but an inject/react hook's OUTPUT shape is confirmed only for Claude Code. On
-    // another harness it would emit CC-shaped output that may not be read — exactly
-    // the silent failure this feature exists to prevent. Flag it, loudly.
+    // No silent skips: warn loudly only where a hook's OUTPUT genuinely may not
+    // apply on this harness. INJECT's `additionalContext` shape is now CONFIRMED
+    // shared with Codex (per the official hooks docs), so an inject hook only
+    // warns when its event isn't in the harness's `injectableEvents`. REACT's
+    // output is still Claude-Code-confirmed only. The gate (deny→exit 2) path is
+    // cross-harness and never warns.
     const role = (0, hook_program_js_1.dispatchKind)(program);
-    const warning = adapter.name !== "claude-code" && (role === "inject" || role === "react")
-        ? `${role} output is only confirmed for Claude Code. On ${adapter.name}, ` +
-            `the gate (deny→exit 2) path works, but this hook's ${role} output is ` +
-            `CC-shaped and unverified — it may silently not apply. Use a gate hook on ` +
-            `${adapter.name} for now, or confirm against the real binary first ` +
-            `(research/compiled-hooks-codex.md §Deferred).`
-        : undefined;
+    const event = typeof program.on === "string" ? program.on : "";
+    const injectable = adapter.hookProtocol?.injectableEvents ?? [];
+    const matcher = (0, hook_program_js_1.hookRouting)(program).matcher;
+    let warning;
+    if (adapter.name !== "claude-code") {
+        if (role === "inject" && !injectable.includes(event)) {
+            warning =
+                `this inject hook targets "${event}", which ${adapter.name} does not ` +
+                    `honor for additionalContext — the injected text won't reach the agent. ` +
+                    `Use an event ${adapter.name} supports: ${injectable.join(", ")}.`;
+        }
+        else if (role === "react") {
+            warning =
+                `react output is confirmed only for Claude Code; on ${adapter.name} this ` +
+                    `hook's react output is unverified (the gate deny→exit 2 path IS ` +
+                    `cross-harness). Confirm against the real binary first.`;
+        }
+        else if (matcher !== undefined) {
+            // A tool-matched gate carries TOOL NAMES in its matcher. vigiles does not
+            // yet translate tool vocabularies across dialects, so a matcher authored
+            // with Claude Code names (`Edit`/`Write`/`Bash`) won't fire on a harness
+            // that names the same tools differently (Codex: `apply_patch`/`shell`).
+            // Warn LOUDLY rather than report a silently-non-firing success.
+            warning =
+                `this hook matches tool(s) "${matcher}" — if those are Claude Code tool ` +
+                    `names, they may not match ${adapter.name}'s vocabulary (e.g. ` +
+                    `apply_patch/shell), so the hook may not fire. Verify the matcher uses ` +
+                    `${adapter.name}'s tool names (cross-dialect matcher translation is not ` +
+                    `yet automatic).`;
+        }
+    }
     return { role, settingsPath: adapter.layout.settingsPath, warning };
 }
 /**
  * Compile + install every hook (explicit paths, else discovered under
- * `.vigiles/hooks/`) into the active harness's config. Returns false if any
- * hook failed to compile.
+ * `.vigiles/hooks/`) into EVERY enabled harness's config. A typed hook is
+ * harness-neutral, so when a repo targets both harnesses the SAME hook is merged
+ * into `.claude/settings.json` AND `.codex/config.toml` (each in its native
+ * format, with per-harness warnings) — never just the first. The harness set is
+ * resolved from the `--harness=` flag, else `config.harness`, else auto-detect.
+ * Returns false if any hook failed to compile for any harness.
  */
-async function installHooks(hookFiles, harnessFlag) {
+async function installHooks(hookFiles, harnessFlag, configHarness) {
     if (hookFiles.length === 0)
         return true;
-    const adapter = harnessFlag
-        ? (0, adapter_registry_js_1.resolveAdapter)(process.cwd(), harnessFlag)
-        : (0, adapter_registry_js_1.detectAdapterResult)(process.cwd()).adapter;
+    const adapters = (0, adapter_registry_js_1.resolveHarnessAdapters)({
+        root: process.cwd(),
+        flag: harnessFlag,
+        configHarness,
+    });
     // Validate registered providers first → the names a hook's provider() ref may
     // resolve to (an unsafe provider fails the whole compile, like a bad hook).
     let registeredProviders;
@@ -4194,10 +4407,13 @@ async function installHooks(hookFiles, harnessFlag) {
     let ok = true;
     for (const file of hookFiles) {
         try {
-            const r = await installHookFile(file, adapter, registeredProviders);
-            console.log(`✓ ${file} → ${r.settingsPath} (role: ${r.role}, harness: ${adapter.name})`);
-            if (r.warning)
-                console.warn(`⚠ ${r.warning}`);
+            // Fan out: the same compiled hook lands in each enabled harness's config.
+            for (const adapter of adapters) {
+                const r = await installHookFile(file, adapter, registeredProviders);
+                console.log(`✓ ${file} → ${r.settingsPath} (role: ${r.role}, harness: ${adapter.name})`);
+                if (r.warning)
+                    console.warn(`⚠ ${r.warning}`);
+            }
         }
         catch (e) {
             if (e instanceof hook_program_js_1.HookCompileError) {
@@ -4781,7 +4997,7 @@ async function main() {
             let valid = true;
             if (specs.length > 0)
                 valid = (await compile(specs, config, { harnessFlag })) && valid;
-            valid = (await installHooks(hooks, harnessFlag)) && valid;
+            valid = (await installHooks(hooks, harnessFlag, config.harness)) && valid;
             // Keep an existing whole-harness registry in sync (cheap, opt-in) so the
             // user never hand-runs `generate-harness`. Skipped when no harness.gen.ts.
             if (specs.length > 0)

package/dist/core/hook-protocol.d.ts

@@ -31,5 +31,20 @@ export interface HookProtocol {
      * Used by `compileHookProgram` when rendering the settings block.
      */
     readonly matcherStyle?: "exact" | "regex";
+    /**
+     * The events whose hook can inject **developer context** into the agent by
+     * printing `{ hookSpecificOutput: { hookEventName, additionalContext } }` on
+     * stdout. The inject *shape* is shared across Claude Code and Codex (so the
+     * runtime emits it once, not per-harness); the genuinely per-harness fact is
+     * **which events honor it** — and encoding it here is what makes "this harness
+     * can deliver an inject hook" a TESTED contract instead of an assumption. Both
+     * Claude Code and Codex support the main lifecycle events (SessionStart,
+     * UserPromptSubmit, PostToolUse); a few (Stop, SubagentStop, PreCompact) carry
+     * no context on either. An empty list means the harness cannot inject context
+     * from a hook at all. Verified for Codex against the official hooks docs
+     * (developers.openai.com/codex/hooks). The conformance kit asserts a
+     * shell-hook harness declares a non-empty set.
+     */
+    readonly injectableEvents: readonly string[];
 }
 //# sourceMappingURL=hook-protocol.d.ts.map

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/runtime.d.ts

@@ -34,5 +34,25 @@ export interface HarnessRuntime {
         readonly args: readonly string[];
         readonly env: Record<string, string>;
     };
+    /**
+     * Reduce a raw `--version` string to the **behaviorally-significant** token the
+     * cache + lock key on — so a harness upgrade that actually moves agent behavior
+     * (new system prompt / tool defs) invalidates a stale replay, while churn that
+     * doesn't shouldn't partition the key. **What counts as significant is
+     * per-harness**, which is exactly why this lives on the port rather than as a
+     * universal `major.minor` rule:
+     *
+     * - **Claude Code** is semver-ish — `major.minor` bumps roughly quarterly
+     *   (0.2 → 1.0 → 2.0 → 2.1 over 16 months) while patches ship ~daily — so it
+     *   returns `major.minor`: a real behavior boundary, rare enough not to churn.
+     * - **Codex** is perpetual `0.x` where the *minor* IS the patch cadence (~2
+     *   bumps/week), so `major.minor` would churn weekly — it returns `""`, opting
+     *   out of version partitioning and relying on the dated model id +
+     *   `evalApiVersion` instead.
+     *
+     * `""` means "don't partition on the harness version." Pure (no spawn — the
+     * caller resolves the raw string via `agentBinary --version`); unit-testable.
+     */
+    versionKey(raw: string): string;
 }
 //# sourceMappingURL=runtime.d.ts.map

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
@@ -346,6 +355,18 @@ export interface VigilesConfig {
     audit?: {
         measure?: boolean;
     };
+    /**
+     * `vigiles eval` preferences. `apiVersion` is the hand-bumped **behavior epoch**
+     * folded into the eval LOCK's input hash (`src/eval-lock.ts`): bump it when a
+     * harness-side change YOU made (a CLAUDE.md edit, a global hook) would shift
+     * eval outputs but isn't otherwise visible to the lock — so `vigiles eval
+     * --check` reports the committed eval results STALE and forces a local re-run.
+     * Default 1. Distinct from the (auto-resolved) `claude` CLI version, which is
+     * recorded as provenance but deliberately NOT hashed.
+     */
+    eval?: {
+        apiVersion?: number;
+    };
 }
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";

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