vigiles 6.0.0 → 8.0.0

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.js

@@ -45,21 +45,35 @@ function header(title, run) {
 function hookScaffold(input) {
     const cmd = input.hookCommand ?? `bash ${input.path}`;
     return `${header(`Starter unit test for the \`${input.name}\` hook.`, `npx vigiles test ${suggestedPath(input)}`)}
-import { runHook, assertHookAllowed } from "vigiles/unit";
+import {
+  runHook,
+  assertHookAllowed,
+  verifyGuardrail,
+  formatGuardrailReport,
+  // assertBlocksDisasters, // uncomment to gate CI on the battery (see below)
+} from "vigiles/unit";
+
+const cmd = ${JSON.stringify(cmd)};
 
+// 1) A benign event should pass through.
 // TODO: set the event + input your hook actually inspects (PreToolUse/Bash shown).
-const event = {
+const benign = {
   hook_event_name: "PreToolUse",
   tool_name: "Bash",
   tool_input: { command: "echo hello" },
 };
+assertHookAllowed(runHook(cmd, benign));
+console.log("✓ ${input.name}: allowed the benign event");
 
-const r = runHook(${JSON.stringify(cmd)}, event);
+// 2) SAFETY: if this is a guard, PROVE it blocks the dangerous battery (the #1 hook
+//    pain is a guard that silently doesn't — exit 1 instead of 2, wrong jq path, …).
+//    This prints a coverage map; it does NOT fail by default (your hook may not be
+//    meant to block all of these).
+console.log(formatGuardrailReport(cmd, verifyGuardrail(cmd)));
 
-// TODO: assert the decision you expect. Use assertHookBlocked(r) for the deny case
-// (and a second runHook with the input that SHOULD be blocked).
-assertHookAllowed(r);
-console.log("✓ ${input.name}: hook allowed the benign event");
+// 3) To GATE CI: declare what this guard MUST block, then assert it. Uncomment +
+//    pick the categories your hook is responsible for:
+// assertBlocksDisasters(cmd, { categories: ["destructive-git"] });
 `;
 }
 /** A skill → the eval tier (`measureTriggerRate`): does its description FIRE? */

package/dist/scan-behavioral.d.ts

@@ -70,4 +70,64 @@ export declare function probePluginTriggersWith(dir: string, promptSet: TriggerP
 export declare function probePluginTriggers(dir: string, promptSet: TriggerPromptSet, opts?: ProbeOptions): Promise<BehavioralReport>;
 /** Format the behavioral column as a scan-report section. */
 export declare function formatBehavioralReport(b: BehavioralReport): string;
+/** Knobs for the selection-collision measurement. */
+export interface SelectionOptions {
+    /** Repeats per prompt (default 1). */
+    readonly trials?: number;
+    /** Selector model — defaults to Sonnet (a weaker model under-selects). */
+    readonly model?: string;
+    /** Parallel runs across the prompts × trials grid (default 1). */
+    readonly concurrency?: number;
+    /** Which harness drives it (default `"claude-code"`; others report n/a). */
+    readonly harness?: ProbeHarness;
+}
+/** One run's outcome for the matrix: which of the plugin's OWN skills fired. */
+interface SelectionRun {
+    readonly intended: string;
+    readonly firedBare: readonly string[];
+}
+export interface SkillSelectionStat {
+    readonly skill: string;
+    /** Fraction of its own prompts on which it fired (matrix diagonal). */
+    readonly recall: number;
+    /** Fraction of its own prompts on which a SIBLING skill also/instead fired. */
+    readonly collisionRate: number;
+    /** Non-errored runs measured for this skill. */
+    readonly n: number;
+    /** Sibling skills that fired on this skill's prompts, by rate (desc, rate>0). */
+    readonly collidesWith: readonly {
+        readonly skill: string;
+        readonly rate: number;
+    }[];
+}
+export interface SelectionReport {
+    /** False when the harness CLI / auth is absent, or the harness has no selector. */
+    readonly available: boolean;
+    /** Matrix axes — the plugin's model-invocable skill names (bare). */
+    readonly skills: readonly string[];
+    /** matrix[i][j] = times skill j fired when skill i's prompt was given. */
+    readonly matrix: readonly (readonly number[])[];
+    readonly perSkill: readonly SkillSelectionStat[];
+    /** Plugin-level: fraction of all runs where a non-intended skill fired. */
+    readonly collisionRate: number;
+    readonly n: number;
+    readonly note?: string;
+}
+/**
+ * Pure aggregation: fold per-run fired-skill sets into the N×N selection matrix +
+ * per-skill recall/collision + the plugin-level collision rate. Separated from the
+ * model-driving so it's unit-testable with synthetic runs (no model).
+ */
+export declare function buildSelectionReport(skills: readonly string[], runs: readonly SelectionRun[]): SelectionReport;
+/** The injectable core (for tests): drive the matrix via a fake/real probe. */
+export declare function measurePluginSelectionWith(dir: string, promptSet: TriggerPromptSet, probe: HarnessProbe, opts?: SelectionOptions): Promise<SelectionReport>;
+/**
+ * Measure a plugin's cross-skill selection-collision matrix against the real
+ * harness (Claude Code only — Codex has no skill-selection event). Needs the
+ * `claude` CLI + model auth; degrades to `available: false` otherwise.
+ */
+export declare function measurePluginSelection(dir: string, promptSet: TriggerPromptSet, opts?: SelectionOptions): Promise<SelectionReport>;
+/** Format the selection-collision matrix as a scan-report section. */
+export declare function formatSelectionReport(r: SelectionReport): string;
+export {};
 //# sourceMappingURL=scan-behavioral.d.ts.map