vigiles 11.0.0 → 12.1.0

package/.claude-plugin/plugin.json

@@ -39,6 +39,15 @@
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/refs-nudge.sh"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/eval-lock-nudge.sh"
+          }
+        ]
       }
     ],
     "SessionStart": [

package/README.md

@@ -197,7 +197,8 @@ stray `git push` is caught before it happens. No model, no key, on every commit.
 _"65% fewer tokens." Says who?_ vigiles[^name] A/Bs the claim on real coding tasks and reports
 the token bill, whether it hit its target, and whether the code still works. promptfoo
 and DeepEval bill **per token, every run**; vigiles runs on your own Claude Pro/Max
-subscription. **[Measure a skill →](docs/measuring-skills.md)**
+subscription. Evals run locally — a committed lock then lets **CI catch stale results with no
+model call**. **[Measure a skill →](docs/measuring-skills.md)**
 
 ## Quick start
 
@@ -225,13 +226,17 @@ npx vigiles init   # adopts your files (non-destructive — eject reverses), add
 
 Interactive in a terminal, non-interactive for agents/CI (or `--yes`).
 
-**You don't hand-write any of this — your agent does.** `init` installs
-model-invocable skills, so a plain-English ask does the work:
+**Adoption is smooth: one command, then your agent does the rest.** `init` installs
+the **skills and hooks**, so a plain-English ask does the work — no specs to
+hand-write, no hooks to wire:
 
-- _"test my skills"_ → scaffolds **and runs** a trigger/behaviour test (`test-harness`)
+- _"test my skills"_ → scaffolds **and runs** a trigger/behaviour test, then commits its result so CI can check it (`test-harness`)
 - _"harden my rules"_ → upgrades prose guidance into enforced linter rules (`strengthen`)
 - _"add a rule to my CLAUDE.md"_ → edits the source and recompiles (`edit-spec`)
 
+The **hooks** keep it honest in-loop — nudging the agent to mark a reference or
+refresh a stale eval — so there are no chores to remember.
+
 <details>
 <summary>What <code>init</code> sets up</summary>
 
@@ -249,7 +254,7 @@ JS **or** TS (`*.harness.{mjs,ts}`) — run with `npx vigiles test`.
 ## FAQ
 
 - **Isn't this just a markdown linter?** No — it checks whether your instruction file is _true_ (every path/script/symbol/rule exists and is enabled), then tests and measures your harness. A style linter can't do any of that.
-- **Do I have to write TypeScript?** No — your agent writes the spec (`init` adopts your CLAUDE.md into one), or plain markdown lints with zero new files. Compiler-grade guarantees are opt-in, like TS's `strict`.
+- **Do I have to write TypeScript?** No — your agent writes the spec (`init` adopts your CLAUDE.md into one), or plain markdown lints with zero new files. Compiler-grade guarantees are opt-in, like TS's `strict` ([why?](docs/faq.md#why-are-the-strongest-guarantees-opt-in-not-the-default)).
 - **Non-JS repo?** `npx vigiles lint` verifies your CLAUDE.md with no install (Ruff/Clippy/Pylint/… too).
 
 **[Full FAQ →](docs/faq.md)**

package/action.yml

@@ -7,7 +7,11 @@ branding:
 
 inputs:
   command:
-    description: "Which vigiles command to run: 'lint' (verify references + integrity + coverage) or 'compile' (specs → markdown)."
+    description: >
+      Which vigiles command to run: 'lint' (verify references + integrity +
+      coverage), 'compile' (specs → markdown), or 'eval-check' (verify committed
+      eval locks against current inputs — the staleness gate; runs NO model, so
+      it is the CI-safe half of evals you produce locally with `vigiles eval --update`).
     required: false
     default: "lint"
   paths:
@@ -65,7 +69,14 @@ runs:
         set -euo pipefail
 
         cmd="${VIGILES_COMMAND:-lint}"
-        args=("$cmd")
+        # 'eval-check' is the CI staleness gate — it maps to the real verb
+        # `eval --check` (verify committed locks vs current inputs, NO model).
+        # Real evals run locally on a subscription (`eval --update`), never in CI.
+        if [[ "$cmd" == "eval-check" ]]; then
+          args=("eval" "--check")
+        else
+          args=("$cmd")
+        fi
 
         # paths: split on commas and whitespace into positional args.
         paths="${VIGILES_PATHS:-}"

package/dist/adapter-conformance.js

@@ -67,6 +67,12 @@ function checkAdapterConformance(adapter) {
         need(adapter.hookProtocol !== undefined, "capabilities.shellHooks is true but hookProtocol is missing");
         if (adapter.hookProtocol) {
             need(Number.isInteger(adapter.hookProtocol.blockExitCode), "hookProtocol.blockExitCode is not an integer");
+            // A shell-hook harness must declare WHICH events can inject developer
+            // context (`additionalContext`). Encoding it makes "can this harness
+            // deliver an inject hook?" a tested contract — the gap that let Codex's
+            // inject support sit unverified in prose. Empty would mean the harness
+            // can't inject context from a hook at all; every harness we support can.
+            need(adapter.hookProtocol.injectableEvents.length > 0, "hookProtocol.injectableEvents is empty — a shell-hook harness must declare the events that honor additionalContext injection (or it can't deliver an inject/nudge hook)");
             portNames.push(["hookProtocol", adapter.hookProtocol.name]);
         }
     }

package/dist/adapter-registry.d.ts

@@ -83,4 +83,24 @@ export declare function resolveHarnessSelection(opts: {
     flag?: string;
     configHarness?: string | readonly string[];
 }): HarnessSelection;
+/**
+ * The FULL adapter set a compile-time INSTALL should fan out to. Unlike
+ * `resolveHarnessSelection` (which picks ONE dialect for a single-output compile,
+ * since you emit a markdown file in one harness's format), an install writes the
+ * SAME artifact into EVERY enabled harness's native config — so a repo targeting
+ * both harnesses gets a compiled hook in `.claude/settings.json` AND
+ * `.codex/config.toml`, not just the first. Precedence mirrors the single picker:
+ *
+ *   1. `--harness=` flag → just that one (an explicit override is singular).
+ *   2. config `harness` list → ALL of them (the multi-harness fan-out).
+ *   3. no config → auto-detect → the one detected.
+ *
+ * Returns ≥1 adapter, de-duplicated by name (a config that lists a harness twice,
+ * or an alias + its canonical, collapses to one install).
+ */
+export declare function resolveHarnessAdapters(opts: {
+    root: string;
+    flag?: string;
+    configHarness?: string | readonly string[];
+}): HarnessAdapter[];
 //# sourceMappingURL=adapter-registry.d.ts.map

package/dist/adapter-registry.js

@@ -9,6 +9,7 @@ exports.adapterForInstructionFile = adapterForInstructionFile;
 exports.resolveAdapter = resolveAdapter;
 exports.normalizeHarnessList = normalizeHarnessList;
 exports.resolveHarnessSelection = resolveHarnessSelection;
+exports.resolveHarnessAdapters = resolveHarnessAdapters;
 const adapter_js_1 = require("./adapters/claude-code/adapter.js");
 const adapter_js_2 = require("./adapters/codex/adapter.js");
 /** The default adapter when detection finds no harness markers. */
@@ -127,4 +128,30 @@ function resolveHarnessSelection(opts) {
     }
     return { kind: "ok", adapter: det.adapter };
 }
+/**
+ * The FULL adapter set a compile-time INSTALL should fan out to. Unlike
+ * `resolveHarnessSelection` (which picks ONE dialect for a single-output compile,
+ * since you emit a markdown file in one harness's format), an install writes the
+ * SAME artifact into EVERY enabled harness's native config — so a repo targeting
+ * both harnesses gets a compiled hook in `.claude/settings.json` AND
+ * `.codex/config.toml`, not just the first. Precedence mirrors the single picker:
+ *
+ *   1. `--harness=` flag → just that one (an explicit override is singular).
+ *   2. config `harness` list → ALL of them (the multi-harness fan-out).
+ *   3. no config → auto-detect → the one detected.
+ *
+ * Returns ≥1 adapter, de-duplicated by name (a config that lists a harness twice,
+ * or an alias + its canonical, collapses to one install).
+ */
+function resolveHarnessAdapters(opts) {
+    const { root, flag, configHarness } = opts;
+    if (flag !== undefined && flag !== "")
+        return [resolveAdapter(root, flag)];
+    const list = normalizeHarnessList(configHarness);
+    const adapters = list.length > 0
+        ? list.map((h) => resolveAdapter(root, h))
+        : [detectAdapterResult(root).adapter];
+    const seen = new Set();
+    return adapters.filter((a) => !seen.has(a.name) && seen.add(a.name));
+}
 //# sourceMappingURL=adapter-registry.js.map

package/dist/adapters/claude-code/hook-protocol.js

@@ -6,5 +6,9 @@ exports.claudeCodeHookProtocol = {
     blockExitCode: 2,
     denyDecisionValues: ["block", "deny"],
     eventEnvVars: [],
+    // Events that honor `hookSpecificOutput.additionalContext` (developer-context
+    // injection). Covers vigiles's shipped inject hooks: the SessionStart lint
+    // summary and the PostToolUse refs / eval-lock nudges.
+    injectableEvents: ["SessionStart", "UserPromptSubmit", "PostToolUse"],
 };
 //# sourceMappingURL=hook-protocol.js.map

package/dist/adapters/claude-code/runtime.js

@@ -22,6 +22,18 @@ exports.claudeCodeRuntime = {
             },
         };
     },
+    /**
+     * Claude Code keys on **major.minor**: a minor/major bump is where the system
+     * prompt + tool defs actually move (0.2 → 1.0 → 2.0 → 2.1, ~quarterly), while
+     * the daily patch stream rarely changes behavior — so keying patches would
+     * churn the cache for no signal. Falls back to the trimmed raw string when no
+     * semver is found. (If a specific patch is known to matter, clear the cache or
+     * bump `CACHE_FORMAT_VERSION`.)
+     */
+    versionKey(raw) {
+        const m = /(\d+)\.(\d+)\.\d+/.exec(raw);
+        return m ? `${m[1]}.${m[2]}` : raw.trim();
+    },
 };
 /**
  * Build the spawn env that points the agent CLI at the mock model: the caller's

package/dist/adapters/codex/eval.js

@@ -195,6 +195,9 @@ exports.codexEvalDriver = {
     runner: codexEvalAgentRunner,
     parse: parseCodexEvalRun,
     runError: codexRunError,
+    // The harness identity → folded into the trigger-rate lock hash, so a report
+    // recorded on Claude Code is STALE if the eval is switched to Codex (and v.v.).
+    harness: "codex",
 };
 /**
  * Spawn real `codex exec --json` for the eval tier (real model, the user's codex

package/dist/adapters/codex/hook-protocol.d.ts

@@ -1,9 +1,17 @@
 /**
- * codexHookProtocol — EXPERIMENTAL, internal-only. Codex's hook wire protocol.
+ * codexHookProtocol — Codex's hook wire protocol.
  * Finding: it is essentially IDENTICAL to Claude Code's (exit 2 / `decision:block`
  * / `permissionDecision:deny`) — the thin `HookProtocol` port was the right call.
  * The genuine deltas are the env vars a hook receives + the TOML config format
  * (the latter lives in PluginLayout.settingsFormat, not here).
+ *
+ * Context injection (`hookSpecificOutput.additionalContext`) is ALSO shared — same
+ * shape, confirmed against the official Codex hooks docs
+ * (developers.openai.com/codex/hooks): supported on SessionStart, UserPromptSubmit,
+ * PreToolUse, PostToolUse, SubagentStart. (Earlier docs called this "deferred" —
+ * it is not.) So vigiles's PostToolUse nudges + SessionStart summary deliver on
+ * Codex unchanged. Caveats: Stop/SubagentStop/PreCompact carry no context, and
+ * Codex marks a hook run failed if it emits an unsupported field for the event.
  */
 import type { HookProtocol } from "../../core/hook-protocol.js";
 export declare const codexHookProtocol: HookProtocol;

package/dist/adapters/codex/hook-protocol.js

@@ -8,6 +8,16 @@ exports.codexHookProtocol = {
     // Codex matchers are anchored regexes (`matcher = "^Bash$"`), unlike Claude
     // Code's exact tool name / `A|B` alternation.
     matcherStyle: "regex",
+    // Events that honor `hookSpecificOutput.additionalContext` on Codex, per the
+    // official hooks docs. Includes the events vigiles's shipped hooks use
+    // (PostToolUse, SessionStart), so those nudges reach the Codex agent too.
+    injectableEvents: [
+        "SessionStart",
+        "UserPromptSubmit",
+        "PreToolUse",
+        "PostToolUse",
+        "SubagentStart",
+    ],
     eventEnvVars: [
         "session_id",
         "cwd",

package/dist/adapters/codex/runtime.js

@@ -22,6 +22,16 @@ exports.codexRuntime = {
     wireMock(baseUrl) {
         return { args: codexMockArgs(baseUrl), env: codexMockEnv() };
     },
+    /**
+     * Codex opts OUT of version partitioning (`""`). It is perpetual `0.x` where
+     * the *minor* is the patch cadence (~2 bumps/week, 134 minors in 14 months), so
+     * keying `major.minor` like Claude Code would churn the cache/lock weekly. With
+     * no stable behavior boundary in the version string, Codex relies on the dated
+     * model id + `evalApiVersion` for staleness instead. See research/cache-invalidation.md.
+     */
+    versionKey(_raw) {
+        return "";
+    },
 };
 /**
  * The PROVEN `-c` flag array that points `codex exec` at a mock served at

package/dist/adapters/opencode/runtime.js

@@ -17,5 +17,9 @@ exports.opencodeRuntime = {
             },
         };
     },
+    /** Prototype: opts out of version partitioning (like Codex). */
+    versionKey(_raw) {
+        return "";
+    },
 };
 //# sourceMappingURL=runtime.js.map

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

@@ -13,7 +13,7 @@
 /** 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"];
 /** 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", "effect-enter", "effect-exit"];
+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];
 export type HookRuntimeKind = (typeof HOOK_RUNTIME_KINDS)[number];
 //# sourceMappingURL=cli-commands.d.ts.map

package/dist/cli-commands.js

@@ -41,6 +41,7 @@ exports.HOOK_RUNTIME_KINDS = [
     "guard",
     "action",
     "refs",
+    "eval-lock-nudge",
     "effect-enter",
     "effect-exit",
 ];