vigiles 5.2.0 → 7.0.0

package/dist/harness-assert.js

@@ -8,6 +8,8 @@ exports.assertNotCreated = assertNotCreated;
 exports.assertServedTurns = assertServedTurns;
 exports.assertHookBlocked = assertHookBlocked;
 exports.assertHookAllowed = assertHookAllowed;
+exports.assertHookDenies = assertHookDenies;
+exports.assertHookAllows = assertHookAllows;
 exports.egressHosts = egressHosts;
 exports.assertNoEgress = assertNoEgress;
 exports.assertEgressOnly = assertEgressOnly;
@@ -58,6 +60,7 @@ exports.assertTriggerRate = assertTriggerRate;
  *     vitest and jest, so the same object supports both.
  */
 const harness_test_js_1 = require("./harness-test.js");
+const hook_program_js_1 = require("./core/hook-program.js");
 const check_js_1 = require("./check.js");
 const agent_result_js_1 = require("./adapters/claude-code/agent-result.js");
 const stats_js_1 = require("./stats.js");
@@ -137,6 +140,33 @@ function assertHookAllowed(r) {
         fail(`expected the hook to allow, but it blocked (exit ${String(r.exitCode)}, decision ${String(r.decision)})`);
     }
 }
+/** Render a {@link HookProgramOutcome} for an assertion message. */
+function describeOutcome(o) {
+    if (o.kind === "decision")
+        return `${o.decision.kind} (a gate decision)`;
+    if (o.kind === "injection")
+        return `an injection`;
+    return `${o.reaction.kind} (a reaction)`;
+}
+/**
+ * Assert a COMPILED hook (a `vigiles/hook` program) denies an event — evaluated
+ * in-process, no subprocess, no model. The cheapest way to test a gate's logic:
+ * pass the hook's default export and a raw event. (For the wired-into-the-real-CLI
+ * check, use {@link assertHookBlocked} over `runHook`.)
+ */
+function assertHookDenies(hook, event) {
+    const o = (0, hook_program_js_1.runHookProgram)(hook, event);
+    if (o.kind !== "decision" || o.decision.kind !== "deny") {
+        fail(`expected the hook to deny, got ${describeOutcome(o)}`);
+    }
+}
+/** Assert a COMPILED hook allows an event (in-process). The twin of {@link assertHookDenies}. */
+function assertHookAllows(hook, event) {
+    const o = (0, hook_program_js_1.runHookProgram)(hook, event);
+    if (o.kind !== "decision" || o.decision.kind !== "allow") {
+        fail(`expected the hook to allow, got ${describeOutcome(o)}`);
+    }
+}
 const hostPort = (e) => `${e.host}:${String(e.port)}`;
 /** The `host:port` strings a run attempted, e.g. `["registry.npmjs.org:443"]`. */
 function egressHosts(r) {

package/dist/hook-install.d.ts

@@ -0,0 +1,43 @@
+/** The agnostic, committed home for hook SOURCE — one dir, cross-adapter. */
+export declare const HOOKS_DIR = ".vigiles/hooks";
+/** The committed home for registered context-provider SOURCE (v2). */
+export declare const PROVIDERS_DIR = ".vigiles/providers";
+/** Discover hook source files under {@link HOOKS_DIR} (stamps excluded). */
+export declare function discoverHookFiles(cwd: string): string[];
+/** Discover registered-provider source files under {@link PROVIDERS_DIR}. */
+export declare function discoverProviderFiles(cwd: string): string[];
+interface CommandHook {
+    readonly type: "command";
+    readonly command: string;
+}
+interface HookEntry {
+    readonly matcher?: string;
+    readonly hooks: readonly CommandHook[];
+}
+/** The CC-shaped structured block a compiled hook program carries. */
+export type CompiledHooks = Record<string, readonly HookEntry[]>;
+interface SettingsJson {
+    hooks?: Record<string, HookEntry[]>;
+    [k: string]: unknown;
+}
+/**
+ * Idempotently merge a compiled hook's block into an existing `settings.json`
+ * object. Entries managed by THIS hook file (the runtime command references
+ * `hookPath`) are replaced; every unrelated entry — including the user's own
+ * hand-written hooks — is preserved.
+ */
+export declare function mergeHooksJson(existing: SettingsJson, compiled: CompiledHooks, hookPath: string): SettingsJson;
+interface TomlHookEntry {
+    matcher?: string;
+    command: string;
+}
+interface ConfigToml {
+    hooks?: Record<string, TomlHookEntry[]>;
+    [k: string]: unknown;
+}
+/** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */
+export declare function mergeHooksToml(existing: ConfigToml, compiled: CompiledHooks, hookPath: string): ConfigToml;
+/** Serialize a merged config back to its on-disk text (with trailing newline). */
+export declare function serializeConfig(merged: Record<string, unknown>, format: "json" | "toml"): string;
+export {};
+//# sourceMappingURL=hook-install.d.ts.map

package/dist/hook-install.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDERS_DIR = exports.HOOKS_DIR = void 0;
+exports.discoverHookFiles = discoverHookFiles;
+exports.discoverProviderFiles = discoverProviderFiles;
+exports.mergeHooksJson = mergeHooksJson;
+exports.mergeHooksToml = mergeHooksToml;
+exports.serializeConfig = serializeConfig;
+/**
+ * Hook installation — the bridge from a typed hook program to a wired harness,
+ * folded into `vigiles compile` (there is no stray `compile-hook` verb; the
+ * cohesive-cli-surface rule).
+ *
+ * The typed hook program is harness-NEUTRAL — it imports `vigiles/hook` and
+ * compiles to whatever harness — so its SOURCE lives in the agnostic,
+ * committed {@link HOOKS_DIR} (`.vigiles/hooks/`), never in a harness's own
+ * `.claude/`. `compile` discovers each hook there, compiles it, and MERGES the
+ * result into the active harness's native config (`.claude/settings.json` JSON
+ * / `config.toml` TOML) — so the harness is actually wired, not handed a
+ * paste-this block. The merge is idempotent: an entry is keyed by the runtime
+ * command's hook PATH, so recompiling updates in place and never duplicates,
+ * while a user's own hand-written hooks are preserved untouched. One source dir
+ * also means basenames are unique, so the stamp can key on the basename safely.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const toml_1 = require("@iarna/toml");
+/** The agnostic, committed home for hook SOURCE — one dir, cross-adapter. */
+exports.HOOKS_DIR = ".vigiles/hooks";
+/** The committed home for registered context-provider SOURCE (v2). */
+exports.PROVIDERS_DIR = ".vigiles/providers";
+/** A JS/TS hook source file (the `.json` stamp sidecar is never matched). */
+const HOOK_SOURCE_RE = /\.(?:mjs|cjs|js|mts|cts|ts)$/;
+/** List JS/TS source files under `dir` (relative to cwd), stamps excluded. */
+function discoverSources(cwd, dir) {
+    const abs = (0, node_path_1.join)(cwd, dir);
+    if (!(0, node_fs_1.existsSync)(abs))
+        return [];
+    return (0, node_fs_1.readdirSync)(abs)
+        .filter((f) => HOOK_SOURCE_RE.test(f) && !f.endsWith(".d.ts"))
+        .sort()
+        .map((f) => (0, node_path_1.join)(dir, f));
+}
+/** Discover hook source files under {@link HOOKS_DIR} (stamps excluded). */
+function discoverHookFiles(cwd) {
+    return discoverSources(cwd, exports.HOOKS_DIR);
+}
+/** Discover registered-provider source files under {@link PROVIDERS_DIR}. */
+function discoverProviderFiles(cwd) {
+    return discoverSources(cwd, exports.PROVIDERS_DIR);
+}
+/** True when an entry's command routes through the runtime for `hookPath`. */
+function managesHook(entry, hookPath) {
+    return entry.hooks.some((h) => h.command.includes(hookPath));
+}
+/**
+ * Idempotently merge a compiled hook's block into an existing `settings.json`
+ * object. Entries managed by THIS hook file (the runtime command references
+ * `hookPath`) are replaced; every unrelated entry — including the user's own
+ * hand-written hooks — is preserved.
+ */
+function mergeHooksJson(existing, compiled, hookPath) {
+    const hooks = { ...(existing.hooks ?? {}) };
+    for (const [event, entries] of Object.entries(compiled)) {
+        const kept = (hooks[event] ?? []).filter((e) => !managesHook(e, hookPath));
+        hooks[event] = [...kept, ...entries];
+    }
+    return { ...existing, hooks };
+}
+/** Flatten a CC-shaped entry to Codex's flat `{matcher?, command}` form. */
+function toTomlEntries(entries) {
+    return entries.flatMap((e) => e.hooks.map((h) => e.matcher === undefined
+        ? { command: h.command }
+        : { matcher: e.matcher, command: h.command }));
+}
+/** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */
+function mergeHooksToml(existing, compiled, hookPath) {
+    const hooks = { ...(existing.hooks ?? {}) };
+    for (const [event, entries] of Object.entries(compiled)) {
+        const kept = (hooks[event] ?? []).filter((e) => !e.command.includes(hookPath));
+        hooks[event] = [...kept, ...toTomlEntries(entries)];
+    }
+    return { ...existing, hooks };
+}
+/** Serialize a merged config back to its on-disk text (with trailing newline). */
+function serializeConfig(merged, format) {
+    return format === "toml"
+        ? (0, toml_1.stringify)(merged).trimEnd() + "\n"
+        : JSON.stringify(merged, null, 2) + "\n";
+}
+//# sourceMappingURL=hook-install.js.map

package/dist/hook.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `vigiles/hook` — the **closed vocabulary** for authoring a compiled hook.
+ *
+ * A hook today is opaque shell (`bash guard.sh`): un-analyzable, and the author
+ * hand-writes the fragile parts (exit code, JSON field, a `grep` matcher) that
+ * cause the #1 verified hook pain — FALSE CONFIDENCE (a guardrail that looks
+ * like it blocks but silently doesn't). Invert it: author a **pure typed
+ * function** `(event) => Decision` against THIS surface, and `vigiles
+ * compile` emits the harness protocol for you. The whole false-confidence
+ * class becomes UNREPRESENTABLE — you never write the exit code or the field.
+ *
+ * The roles, each with its own output type so a category mistake is a `tsc`
+ * error, not a silent no-op:
+ *   - `defineHook` / `defineFileGate` — a **gate** returns a `Decision`
+ *     (`allow`/`deny`/`ask`); `deny` is the only thing that blocks.
+ *   - `definePromptGate` — a **prompt gate** (UserPromptSubmit) sees the prompt
+ *     TEXT and may `deny` to block it (a security filter).
+ *   - `defineStopGate` — a **stop gate** (Stop/SubagentStop) may `deny` to keep
+ *     the agent going (gate-until-tests-pass).
+ *   - `defineInject` — an **inject** returns an `Injection` (context text); it
+ *     has no `deny`, so "block on a SessionStart hook" won't compile.
+ *   - `defineReact` — a **react** (PostToolUse) returns a `Reaction`; it sees the
+ *     tool RESPONSE, its `run(cmd)` is effect-classified at construction, and it
+ *     can't block (the tool already ran).
+ *
+ * Every gate takes a `mode`: `enforce` (default, blocks) or `observe` (the
+ * shadow/rollout mode — records what it WOULD block, never blocks). `observe` is
+ * harness-neutral (it just exits 0 + writes a local record).
+ *
+ * Matching is AST-backed (`command.runs("git push", { force })`), so it catches
+ * `cd x && git push -f` that the native `Bash(git:*)` glob misses.
+ *
+ * A gate may also decide on EXTERNAL STATE by declaring `needs` (e.g.
+ * `needs: ["git.branch"]`): the trusted runtime gathers those read-only facts and
+ * hands them in as `e.ctx` — the hook still does zero I/O, and reading an
+ * undeclared fact is a `tsc` error. Built-ins:
+ * `git.branch`/`git.isDirty`/`git.root`/`cwd`/`os.platform`/`env.isCI`. For a
+ * one-off off-catalog fact, the lightweight opt-out is an
+ * inline `provide(name, cmd)` (read-only) or `dangerously(name, cmd)` (the loud
+ * escape) right in `needs`. See `research/hook-context-providers.md`.
+ *
+ * ⚠️ Honest scope: compile/verify fix the hook's AUTHORING + LOGIC. They do NOT
+ * change DELIVERY — Claude Code's own subagent-bypass (#34692) means a
+ * PreToolUse hook (compiled or hand-written) does not fire for a subagent's
+ * tool calls. A gate is a strong default, never an unbypassable wall. See
+ * `docs/compiled-hooks.md`.
+ */
+export { defineHook, defineFileGate, definePromptGate, defineStopGate, tool, tools, allow, deny, ask, commandView, pathView, gateAction, hookMode, defineInject, inject, defineReact, run, notice, nothing, responseView, decideProgram, decideFileGate, decidePromptGate, decideStopGate, runInject, runReact, runHookProgram, decisionExitCode, dispatchKind, hookRouting, hookNeeds, compileHookProgram, checkHookImports, stampHook, verifyHookStamp, HookCompileError, } from "./core/hook-program.js";
+export type { Decision, HookMode, GateAction, CommandView, PathView, ResponseView, BashToolEvent, FileToolEvent, PromptEvent, StopEvent, ReactEvent, SessionEvent, HookProgram, FileGateHook, PromptGateHook, StopGateHook, InjectHook, ReactHook, AnyHook, DispatchKind, Injection, Reaction, RunReaction, CompiledHookProgram, CompileHookOptions, RawHookEvent, HookProgramOutcome, } from "./core/hook-program.js";
+export { provide, dangerously, defineProvider, provider, } from "./core/hook-providers.js";
+export type { ProviderName, ProviderResults, HookCtx, NeedSpec, InlineProvider, RegisteredProvider, RegisteredRef, ProviderRegistry, } from "./core/hook-providers.js";
+//# sourceMappingURL=hook.d.ts.map

package/dist/hook.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.defineReact = exports.inject = exports.defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.tool = exports.defineStopGate = exports.definePromptGate = exports.defineFileGate = exports.defineHook = void 0;
+/**
+ * `vigiles/hook` — the **closed vocabulary** for authoring a compiled hook.
+ *
+ * A hook today is opaque shell (`bash guard.sh`): un-analyzable, and the author
+ * hand-writes the fragile parts (exit code, JSON field, a `grep` matcher) that
+ * cause the #1 verified hook pain — FALSE CONFIDENCE (a guardrail that looks
+ * like it blocks but silently doesn't). Invert it: author a **pure typed
+ * function** `(event) => Decision` against THIS surface, and `vigiles
+ * compile` emits the harness protocol for you. The whole false-confidence
+ * class becomes UNREPRESENTABLE — you never write the exit code or the field.
+ *
+ * The roles, each with its own output type so a category mistake is a `tsc`
+ * error, not a silent no-op:
+ *   - `defineHook` / `defineFileGate` — a **gate** returns a `Decision`
+ *     (`allow`/`deny`/`ask`); `deny` is the only thing that blocks.
+ *   - `definePromptGate` — a **prompt gate** (UserPromptSubmit) sees the prompt
+ *     TEXT and may `deny` to block it (a security filter).
+ *   - `defineStopGate` — a **stop gate** (Stop/SubagentStop) may `deny` to keep
+ *     the agent going (gate-until-tests-pass).
+ *   - `defineInject` — an **inject** returns an `Injection` (context text); it
+ *     has no `deny`, so "block on a SessionStart hook" won't compile.
+ *   - `defineReact` — a **react** (PostToolUse) returns a `Reaction`; it sees the
+ *     tool RESPONSE, its `run(cmd)` is effect-classified at construction, and it
+ *     can't block (the tool already ran).
+ *
+ * Every gate takes a `mode`: `enforce` (default, blocks) or `observe` (the
+ * shadow/rollout mode — records what it WOULD block, never blocks). `observe` is
+ * harness-neutral (it just exits 0 + writes a local record).
+ *
+ * Matching is AST-backed (`command.runs("git push", { force })`), so it catches
+ * `cd x && git push -f` that the native `Bash(git:*)` glob misses.
+ *
+ * A gate may also decide on EXTERNAL STATE by declaring `needs` (e.g.
+ * `needs: ["git.branch"]`): the trusted runtime gathers those read-only facts and
+ * hands them in as `e.ctx` — the hook still does zero I/O, and reading an
+ * undeclared fact is a `tsc` error. Built-ins:
+ * `git.branch`/`git.isDirty`/`git.root`/`cwd`/`os.platform`/`env.isCI`. For a
+ * one-off off-catalog fact, the lightweight opt-out is an
+ * inline `provide(name, cmd)` (read-only) or `dangerously(name, cmd)` (the loud
+ * escape) right in `needs`. See `research/hook-context-providers.md`.
+ *
+ * ⚠️ Honest scope: compile/verify fix the hook's AUTHORING + LOGIC. They do NOT
+ * change DELIVERY — Claude Code's own subagent-bypass (#34692) means a
+ * PreToolUse hook (compiled or hand-written) does not fire for a subagent's
+ * tool calls. A gate is a strong default, never an unbypassable wall. See
+ * `docs/compiled-hooks.md`.
+ */
+var hook_program_js_1 = require("./core/hook-program.js");
+// gate vocabulary
+Object.defineProperty(exports, "defineHook", { enumerable: true, get: function () { return hook_program_js_1.defineHook; } });
+Object.defineProperty(exports, "defineFileGate", { enumerable: true, get: function () { return hook_program_js_1.defineFileGate; } });
+Object.defineProperty(exports, "definePromptGate", { enumerable: true, get: function () { return hook_program_js_1.definePromptGate; } });
+Object.defineProperty(exports, "defineStopGate", { enumerable: true, get: function () { return hook_program_js_1.defineStopGate; } });
+Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return hook_program_js_1.tool; } });
+Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return hook_program_js_1.tools; } });
+Object.defineProperty(exports, "allow", { enumerable: true, get: function () { return hook_program_js_1.allow; } });
+Object.defineProperty(exports, "deny", { enumerable: true, get: function () { return hook_program_js_1.deny; } });
+Object.defineProperty(exports, "ask", { enumerable: true, get: function () { return hook_program_js_1.ask; } });
+Object.defineProperty(exports, "commandView", { enumerable: true, get: function () { return hook_program_js_1.commandView; } });
+Object.defineProperty(exports, "pathView", { enumerable: true, get: function () { return hook_program_js_1.pathView; } });
+Object.defineProperty(exports, "gateAction", { enumerable: true, get: function () { return hook_program_js_1.gateAction; } });
+Object.defineProperty(exports, "hookMode", { enumerable: true, get: function () { return hook_program_js_1.hookMode; } });
+// inject vocabulary
+Object.defineProperty(exports, "defineInject", { enumerable: true, get: function () { return hook_program_js_1.defineInject; } });
+Object.defineProperty(exports, "inject", { enumerable: true, get: function () { return hook_program_js_1.inject; } });
+// react vocabulary
+Object.defineProperty(exports, "defineReact", { enumerable: true, get: function () { return hook_program_js_1.defineReact; } });
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return hook_program_js_1.run; } });
+Object.defineProperty(exports, "notice", { enumerable: true, get: function () { return hook_program_js_1.notice; } });
+Object.defineProperty(exports, "nothing", { enumerable: true, get: function () { return hook_program_js_1.nothing; } });
+Object.defineProperty(exports, "responseView", { enumerable: true, get: function () { return hook_program_js_1.responseView; } });
+// runtime + decode (used by the `vigiles hook-runtime run-program` runtime and tests)
+Object.defineProperty(exports, "decideProgram", { enumerable: true, get: function () { return hook_program_js_1.decideProgram; } });
+Object.defineProperty(exports, "decideFileGate", { enumerable: true, get: function () { return hook_program_js_1.decideFileGate; } });
+Object.defineProperty(exports, "decidePromptGate", { enumerable: true, get: function () { return hook_program_js_1.decidePromptGate; } });
+Object.defineProperty(exports, "decideStopGate", { enumerable: true, get: function () { return hook_program_js_1.decideStopGate; } });
+Object.defineProperty(exports, "runInject", { enumerable: true, get: function () { return hook_program_js_1.runInject; } });
+Object.defineProperty(exports, "runReact", { enumerable: true, get: function () { return hook_program_js_1.runReact; } });
+Object.defineProperty(exports, "runHookProgram", { enumerable: true, get: function () { return hook_program_js_1.runHookProgram; } });
+Object.defineProperty(exports, "decisionExitCode", { enumerable: true, get: function () { return hook_program_js_1.decisionExitCode; } });
+Object.defineProperty(exports, "dispatchKind", { enumerable: true, get: function () { return hook_program_js_1.dispatchKind; } });
+Object.defineProperty(exports, "hookRouting", { enumerable: true, get: function () { return hook_program_js_1.hookRouting; } });
+Object.defineProperty(exports, "hookNeeds", { enumerable: true, get: function () { return hook_program_js_1.hookNeeds; } });
+// compile + integrity
+Object.defineProperty(exports, "compileHookProgram", { enumerable: true, get: function () { return hook_program_js_1.compileHookProgram; } });
+Object.defineProperty(exports, "checkHookImports", { enumerable: true, get: function () { return hook_program_js_1.checkHookImports; } });
+Object.defineProperty(exports, "stampHook", { enumerable: true, get: function () { return hook_program_js_1.stampHook; } });
+Object.defineProperty(exports, "verifyHookStamp", { enumerable: true, get: function () { return hook_program_js_1.verifyHookStamp; } });
+Object.defineProperty(exports, "HookCompileError", { enumerable: true, get: function () { return hook_program_js_1.HookCompileError; } });
+var hook_providers_js_1 = require("./core/hook-providers.js");
+Object.defineProperty(exports, "provide", { enumerable: true, get: function () { return hook_providers_js_1.provide; } });
+Object.defineProperty(exports, "dangerously", { enumerable: true, get: function () { return hook_providers_js_1.dangerously; } });
+Object.defineProperty(exports, "defineProvider", { enumerable: true, get: function () { return hook_providers_js_1.defineProvider; } });
+Object.defineProperty(exports, "provider", { enumerable: true, get: function () { return hook_providers_js_1.provider; } });
+//# sourceMappingURL=hook.js.map

package/dist/leaderboard.d.ts

@@ -32,4 +32,10 @@ export declare function scoreReport(r: ScanReport): {
 export declare function rankPlugins(dirs: readonly string[]): PluginScore[];
 /** Format a ranked leaderboard as human-readable text. */
 export declare function formatLeaderboard(scores: readonly PluginScore[]): string;
+/**
+ * Format a ranked leaderboard as a Markdown table — the PUBLISHABLE form (a README,
+ * a gist, the leaderboard site). Shows the top 2 deductions per plugin; the full
+ * breakdown is in `--json`. Sibling of the plain-text {@link formatLeaderboard}.
+ */
+export declare function formatLeaderboardMarkdown(scores: readonly PluginScore[]): string;
 //# sourceMappingURL=leaderboard.d.ts.map

package/dist/leaderboard.js

@@ -16,8 +16,27 @@ exports.gradeFor = gradeFor;
 exports.scoreReport = scoreReport;
 exports.rankPlugins = rankPlugins;
 exports.formatLeaderboard = formatLeaderboard;
+exports.formatLeaderboardMarkdown = formatLeaderboardMarkdown;
+const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const scan_js_1 = require("./scan.js");
+/** The plugin's declared name (`.claude-plugin/plugin.json`), for a real label in
+ * the ranking instead of a SHA-pinned dir basename. Falls back to the basename. */
+function pluginLabel(dir) {
+    const p = (0, node_path_1.join)(dir, ".claude-plugin", "plugin.json");
+    if ((0, node_fs_1.existsSync)(p)) {
+        try {
+            const name = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"))
+                .name;
+            if (typeof name === "string" && name.length > 0)
+                return name;
+        }
+        catch {
+            // fall through to the basename
+        }
+    }
+    return (0, node_path_1.basename)(dir) || dir;
+}
 // Penalty weights — broken-at-runtime costs most, footguns less, nudges least.
 const W_MISSING_HOOK = 15; // a hook script that doesn't exist → never runs
 const W_NO_DESCRIPTION = 10; // a skill with no usable description → can't trigger
@@ -139,7 +158,7 @@ function rankPlugins(dirs) {
         const { score, issues } = scoreReport(report);
         return {
             dir,
-            name: (0, node_path_1.basename)(dir) || dir,
+            name: pluginLabel(dir),
             score,
             grade: gradeFor(score),
             issues,
@@ -164,4 +183,27 @@ function formatLeaderboard(scores) {
     out.push("", "Structural health only (no model). Weights: missing hook -15, no-description", "skill -10, broken intra-plugin ref -8, agent-without-tool-contract -5,", "untested surface -3.");
     return out.join("\n");
 }
+const LEADERBOARD_METHOD = "_Structural health only (deterministic, no model): missing hook −15, " +
+    "no-description skill −10, broken intra-plugin ref −8, " +
+    "agent-without-tool-contract −5, untested surface −3. " +
+    "Behavioural columns (trigger-rate, collisions, egress) stack on top._";
+/**
+ * Format a ranked leaderboard as a Markdown table — the PUBLISHABLE form (a README,
+ * a gist, the leaderboard site). Shows the top 2 deductions per plugin; the full
+ * breakdown is in `--json`. Sibling of the plain-text {@link formatLeaderboard}.
+ */
+function formatLeaderboardMarkdown(scores) {
+    const lines = [
+        `### Plugin health leaderboard (${String(scores.length)} scanned)`,
+        "",
+        "| # | grade | score | plugin | top issues |",
+        "| --: | :--: | --: | :-- | :-- |",
+    ];
+    scores.forEach((s, i) => {
+        const issues = s.issues.length > 0 ? s.issues.slice(0, 2).join("; ") : "— clean";
+        lines.push(`| ${String(i + 1)} | ${s.grade} | ${String(s.score)} | \`${s.name}\` | ${issues} |`);
+    });
+    lines.push("", LEADERBOARD_METHOD);
+    return lines.join("\n");
+}
 //# sourceMappingURL=leaderboard.js.map

package/dist/linting.d.ts

@@ -1,10 +1,14 @@
 /**
  * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
- * files. Re-exports the spec builders/types, the compiler, and the linter
- * cross-referencing engine under one concern-named import. This is the canonical
- * pillar-1 surface; the spec builders are also at the package root (`vigiles`).
+ * files. Re-exports the spec builders/types + the public compile entry points
+ * under one concern-named import. This is the canonical pillar-1 surface; the
+ * spec builders are also at the package root (`vigiles`).
+ *
+ * Curated (named, not `export *`) so the internal compiler validators, hash
+ * helpers, and the linter cross-reference ENGINE stay out of the public surface,
+ * the api reports, and the docs site (the CLI imports those from the source).
  */
 export * from "./core/spec.js";
-export * from "./core/compile.js";
-export * from "./core/linters.js";
+export { compileClaude, compileSkill, compileAgent, compileRailway, CompileError, } from "./core/compile.js";
+export type { CompileClaudeOptions, CompileClaudeResult, CompileSkillResult, CompileAgentResult, CompileRailwayOptions, CompileRailwayResult, } from "./core/compile.js";
 //# sourceMappingURL=linting.d.ts.map

package/dist/linting.js

@@ -14,13 +14,25 @@ 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.compileRailway = exports.compileAgent = exports.compileSkill = exports.compileClaude = void 0;
 /**
  * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
- * files. Re-exports the spec builders/types, the compiler, and the linter
- * cross-referencing engine under one concern-named import. This is the canonical
- * pillar-1 surface; the spec builders are also at the package root (`vigiles`).
+ * files. Re-exports the spec builders/types + the public compile entry points
+ * under one concern-named import. This is the canonical pillar-1 surface; the
+ * spec builders are also at the package root (`vigiles`).
+ *
+ * Curated (named, not `export *`) so the internal compiler validators, hash
+ * helpers, and the linter cross-reference ENGINE stay out of the public surface,
+ * the api reports, and the docs site (the CLI imports those from the source).
  */
+// The spec authoring builders (claude/enforce/guidance/file/cmd/agent/skill/…).
 __exportStar(require("./core/spec.js"), exports);
-__exportStar(require("./core/compile.js"), exports);
-__exportStar(require("./core/linters.js"), exports);
+// Compile: only the public entry points + their option/result types.
+var compile_js_1 = require("./core/compile.js");
+Object.defineProperty(exports, "compileClaude", { enumerable: true, get: function () { return compile_js_1.compileClaude; } });
+Object.defineProperty(exports, "compileSkill", { enumerable: true, get: function () { return compile_js_1.compileSkill; } });
+Object.defineProperty(exports, "compileAgent", { enumerable: true, get: function () { return compile_js_1.compileAgent; } });
+Object.defineProperty(exports, "compileRailway", { enumerable: true, get: function () { return compile_js_1.compileRailway; } });
+// core/linters is the cross-reference ENGINE (checkLinterRule/editDistance/…),
+// consumed by compile — not part of the public authoring surface.
 //# sourceMappingURL=linting.js.map

package/dist/optimize.js

@@ -66,7 +66,7 @@ const ACTION_LABEL = {
     fix: "FIX",
     differentiate: "DIFFERENTIATE",
 };
-const measureHint = (dir) => `\`vigiles scan ${dir} --trigger\` — real-model, runs on your subscription`;
+const measureHint = (dir) => `\`vigiles measure ${dir} --prompts=<file>\` — real-model, runs on your subscription`;
 /** Render an optimization plan for the CLI. */
 function formatOptimize(rep) {
     const head = `Harness health: ${String(rep.score)}/100 (${rep.grade}) — ${rep.dir}`;

package/dist/scaffold-test.d.ts

@@ -1,6 +1,21 @@
 export type SurfaceKind = "skill" | "agent" | "hook";
 /** The cheapest meaningful tier for a surface kind (mirrors the test-harness skill). */
 export type TestTier = "unit" | "harness" | "eval";
+/** One field of a subagent's `result()` contract, parsed from its compiled `.md`. */
+export interface ContractField {
+    readonly name: string;
+    /** The `OutputFieldType` literal: `"string" | "number" | "boolean" | "string[]"`. */
+    readonly type: string;
+}
+/**
+ * A subagent's typed `result(ok, err)` outcome contract — the typed-spec payoff
+ * the generator turns into a real `assertAgentOk` test (no LLM judge). Parsed from
+ * the `vigiles:ok` / `vigiles:err` blocks the compiler emits into the agent `.md`.
+ */
+export interface ResultContract {
+    readonly ok: readonly ContractField[];
+    readonly err: readonly ContractField[];
+}
 /** What the generator needs to know about a surface to scaffold its test. */
 export interface ScaffoldInput {
     readonly kind: SurfaceKind;
@@ -14,6 +29,19 @@ export interface ScaffoldInput {
     readonly userInvoked?: boolean;
     /** A subagent's declared tool contract (drives the assertion hint); null = inherits all. */
     readonly tools?: readonly string[] | null;
+    /**
+     * The side-effecting tools in the contract (`effectSurface(tools).sideEffecting`,
+     * computed by the CLI with the resolved dialect — kept harness-agnostic here). A
+     * non-empty list drives a generated SAFETY check: the agent's "hole" is mocked/denied
+     * and asserted to stay in its lane — the typed `tools` contract writing its own test.
+     */
+    readonly sideEffectingTools?: readonly string[];
+    /**
+     * The subagent's `result()` contract parsed from its compiled `.md`. Present →
+     * the generator emits a deterministic `assertAgentOk` outcome test (no LLM judge);
+     * the single most-concrete "the typed spec wrote your test" payoff.
+     */
+    readonly resultContract?: ResultContract | null;
     /** How the CLI invokes the hook (e.g. `bash hooks/pre-edit.sh`); a TODO when unknown. */
     readonly hookCommand?: string;
 }