vigiles 4.0.1 → 4.1.0

package/dist/core/linters.js

@@ -461,7 +461,7 @@ function isEslintPluginRule(ruleName, basePath) {
 /**
  * Enumerate all rules for a CLI-based linter so `tryCliCheck` can emit
  * closest-match suggestions on typos. Result is cached per (linter,
- * basePath) so each linter's discovery CLI runs at most once per audit.
+ * basePath) so each linter's discovery CLI runs at most once per lint.
  */
 const CLI_RULE_SET_CACHE = new Map();
 function getCliRuleSet(linterName, basePath) {
@@ -561,7 +561,7 @@ function getCliRuleSet(linterName, basePath) {
 // The `vigiles/<id>` namespace lets specs declare mechanical checks that
 // vigiles itself runs (orphan docs, integrity, etc.) without delegating to
 // an external linter. Existence is verified at compile time against this
-// fixed catalog; the actual check runs at audit time.
+// fixed catalog; the actual check runs at lint time.
 // ---------------------------------------------------------------------------
 const VIGILES_INTERNAL_RULES = new Set(["orphan-docs"]);
 /** @internal */ function tryVigilesInternal(ctx) {

package/dist/core/orphans.js

@@ -28,6 +28,13 @@ const DEFAULT_IGNORE = [
     ".vigiles/**",
     ".git/**",
 ];
+/**
+ * A doc carrying this marker opts out of orphan detection — the inline escape
+ * hatch, mirroring `vigiles-disable require-spec` and `vigiles:ignore-test`.
+ * Use it for an intentionally-unreferenced doc (a changelog, a top-level index)
+ * that nothing else links to but is not rot.
+ */
+const DISABLE_RE = /<!--\s*vigiles-disable\s+orphan-docs\s*-->/;
 // Match markdown links ](path.md) or ](path.md#anchor)
 const LINK_RE = /\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
 // Match backtick code spans wrapping a path ending in .md
@@ -35,6 +42,27 @@ const BACKTICK_RE = /`([^`\s]+\.md)`/g;
 function normalizePath(p) {
     return p.replace(/^\.\//, "").replace(/\\/g, "/");
 }
+/** True when a doc opts out of orphan detection via the inline disable marker. */
+function isOrphanExempt(absPath) {
+    try {
+        return DISABLE_RE.test((0, node_fs_1.readFileSync)(absPath, "utf-8"));
+    }
+    catch {
+        return false; // unreadable — treat like any other doc
+    }
+}
+/** Discover docs under `include`, dropping any that carry the inline opt-out. */
+function collectDocs(basePath, include, ignore) {
+    const docs = new Set();
+    for (const pattern of include) {
+        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
+            if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
+                continue;
+            docs.add(normalizePath(p));
+        }
+    }
+    return docs;
+}
 function extractRefs(content) {
     const refs = [];
     for (const m of content.matchAll(LINK_RE))
@@ -43,6 +71,23 @@ function extractRefs(content) {
         refs.push(normalizePath(m[1]));
     return refs;
 }
+/**
+ * Repo-root-relative targets a reference could mean, from a given source file.
+ * Markdown links are conventionally **file-relative** (a `[x](foo.md)` in
+ * `research/README.md` points at `research/foo.md`, and `../docs/x.md` walks up),
+ * but docs also write **root-relative** paths (`research/foo.md` from anywhere).
+ * We credit both so a real link is never miscounted as an orphan.
+ */
+function refTargets(sourcePath, ref) {
+    const targets = new Set([ref]); // root-relative reading
+    const dir = sourcePath.includes("/")
+        ? sourcePath.slice(0, sourcePath.lastIndexOf("/"))
+        : "";
+    // file-relative reading: resolve against the source's directory.
+    const resolved = normalizePath(node_path_1.posix.normalize(dir ? `${dir}/${ref}` : ref));
+    targets.add(resolved);
+    return [...targets];
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -63,12 +108,7 @@ function findOrphanDocs(options = {}) {
     const include = options.include ?? DEFAULT_INCLUDE;
     const userExclude = options.exclude ?? [];
     const ignore = [...DEFAULT_IGNORE, ...userExclude];
-    const allDocs = new Set();
-    for (const pattern of include) {
-        const found = (0, glob_1.globSync)(pattern, { cwd: basePath, ignore });
-        for (const p of found)
-            allDocs.add(normalizePath(p));
-    }
+    const allDocs = collectDocs(basePath, include, ignore);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
         ignore: [...DEFAULT_IGNORE],
@@ -83,15 +123,17 @@ function findOrphanDocs(options = {}) {
         catch {
             continue;
         }
-        for (const target of extractRefs(content)) {
-            if (target === source)
-                continue;
-            let sources = referencedBy.get(target);
-            if (!sources) {
-                sources = new Set();
-                referencedBy.set(target, sources);
+        for (const rawRef of extractRefs(content)) {
+            for (const target of refTargets(source, rawRef)) {
+                if (target === source)
+                    continue;
+                let sources = referencedBy.get(target);
+                if (!sources) {
+                    sources = new Set();
+                    referencedBy.set(target, sources);
+                }
+                sources.add(source);
             }
-            sources.add(source);
         }
     }
     const orphans = [];
@@ -119,6 +161,7 @@ function formatOrphanReport(report) {
     ];
     for (const o of report.orphans)
         lines.push(`    ${o}`);
+    lines.push("  Fix: link each from another .md (README, a spec's Key Files, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  exclude it via .vigilesrc.json → `orphans.exclude` (or narrow `orphans.include`).");
     return lines.join("\n");
 }
 //# sourceMappingURL=orphans.js.map

package/dist/core/proofs.js

@@ -188,7 +188,7 @@ function findSimilarRules(rules, threshold = 0.5) {
  *
  * Throws a structured error on unknown rule kinds so that the caller (e.g.
  * runProofSuite) can surface a clear proof failure rather than letting an
- * `undefined` propagate into compressedSize and crash the audit.
+ * `undefined` propagate into compressedSize and crash the computation.
  */
 function ruleToText(rule) {
     switch (rule._kind) {

package/dist/core/refs.d.ts

@@ -29,7 +29,7 @@ export declare function symbolRefs(markdown: string): SymbolRef[];
 export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
 /**
  * Whether a span is a **linter-rule reference** that ought to be marked
- * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the audit can verify the
+ * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the lint can verify the
  * rule exists AND is enabled. High-signal only: a slash-scoped name with no file
  * extension. A function-call form `` `foo(args)` `` is reduced to its callee.
  *

package/dist/core/refs.js

@@ -109,7 +109,7 @@ const IGNORE_FILE = /<!--\s*vigiles:ignore-file\s*-->/;
 const IGNORE_LINE = /<!--\s*vigiles:ignore\s*-->/;
 /**
  * Whether a span is a **linter-rule reference** that ought to be marked
- * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the audit can verify the
+ * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the lint can verify the
  * rule exists AND is enabled. High-signal only: a slash-scoped name with no file
  * extension. A function-call form `` `foo(args)` `` is reduced to its callee.
  *
@@ -152,7 +152,7 @@ function collectRefIssues(markdown, basePath) {
     for (const u of unmarkedCodeRefs(markdown)) {
         out.push(`line ${String(u.line)}: \`${u.text}\` is an unmarked linter-rule ` +
             `reference — mark it as \`enforce("${u.text}")\` (typed spec) or ` +
-            `\`<!-- vigiles:enforce ${u.text} -->\` (markdown) so audit can verify ` +
+            `\`<!-- vigiles:enforce ${u.text} -->\` (markdown) so lint can verify ` +
             `it exists and is enabled, or add <!-- vigiles:ignore --> if it is prose`);
     }
     return out;

package/dist/core/sidecar.d.ts

@@ -4,7 +4,7 @@
  * Used by the post-session audit to know which targets exist and which
  * spec source / inputs each one tracks. The compile pipeline writes
  * these whenever a spec is built; readers (currently only session.ts)
- * consume them at audit time.
+ * consume them at verification time.
  *
  * This module is the ONLY place sidecars live now — the freshness rule
  * doesn't depend on them anymore.

package/dist/core/sidecar.js

@@ -5,7 +5,7 @@
  * Used by the post-session audit to know which targets exist and which
  * spec source / inputs each one tracks. The compile pipeline writes
  * these whenever a spec is built; readers (currently only session.ts)
- * consume them at audit time.
+ * consume them at verification time.
  *
  * This module is the ONLY place sidecars live now — the freshness rule
  * doesn't depend on them anymore.

package/dist/core/spec.d.ts

@@ -156,7 +156,7 @@ export declare function cmd(command: NoInfer<StrictCmd>): CmdRef;
  * Reference a symbol defined in a file — verified at compile time that the
  * named file exists AND defines the named symbol (via ast-grep, cross-language).
  * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
- * `audit` / `refs-hook` re-verify the same reference.
+ * `lint` / `refs-hook` re-verify the same reference.
  */
 export declare function symbol(file: NoInfer<StrictFile>, name: string): SymbolRef;
 /**

package/dist/core/spec.js

@@ -93,7 +93,7 @@ function cmd(command) {
  * Reference a symbol defined in a file — verified at compile time that the
  * named file exists AND defines the named symbol (via ast-grep, cross-language).
  * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
- * `audit` / `refs-hook` re-verify the same reference.
+ * `lint` / `refs-hook` re-verify the same reference.
  */
 function symbol(file, name) {
     return { _ref: "symbol", file: file, symbol: name };

package/dist/core/types.d.ts

@@ -97,7 +97,7 @@ export interface RulesConfig {
     "untested-surface"?: RuleWithOptions<TestCoverageConfig>;
     /**
      * Nudge (or block) when an instruction file has code-shaped references that
-     * aren't expressed as vigiles marks (so the audit can't verify them), or a
+     * aren't expressed as vigiles marks (so the lint can't verify them), or a
      * `vigiles:symbol` mark that points at a missing symbol. Drives the
      * PostToolUse refs-hook: "warn" (default) → a non-blocking nudge, "error" →
      * block the edit, false → off.
@@ -127,6 +127,16 @@ export interface VigilesConfig {
     }>;
     /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
     orphans?: OrphansConfig;
+    /**
+     * The harness(es) this repo targets — selects the compile dialect / skill
+     * frontmatter profile / instruction-file shape, instead of sniffing the cwd.
+     * A single name (`"codex"`) for the common single-harness repo, or an array
+     * (`["claude-code", "codex"]`) declaring the supported set. Written by
+     * `vigiles init`. Omitted → the CLI auto-detects (backwards-compatible).
+     * Canonical adapter names; `"claude"` is accepted as an alias for
+     * `"claude-code"`. See research/multi-harness-compile.md.
+     */
+    harness?: string | string[];
 }
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";

package/dist/core/validate.js

@@ -157,9 +157,9 @@ function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect
             const specPath = filePath + ".spec.ts";
             // Inline mode counts as a spec — any parseable
             // `<!-- vigiles:enforce ... -->` comment means the file is
-            // verified on `vigiles audit` even without a .spec.ts sibling.
+            // verified on `vigiles lint` even without a .spec.ts sibling.
             // Delegate to the real parser so a malformed marker can't
-            // satisfy require-spec with a rule that audit can't verify.
+            // satisfy require-spec with a rule that lint can't verify.
             const hasInline = (0, inline_js_1.hasInlineRules)(content) || (0, frontmatter_js_1.hasFrontmatterRules)(content);
             if (!(0, node_fs_1.existsSync)(specPath) && !hasInline) {
                 const msg = {

package/dist/e2e.d.ts

@@ -1,19 +1,16 @@
 /**
- * `vigiles/e2e` — the **deterministic** end-to-end tier (real sandbox + real
- * network, but a definite pass/fail).
+ * `vigiles/e2e` — DEPRECATED back-compat alias for [`vigiles/integration`](./integration.ts).
  *
- * Re-exports everything in [`vigiles/integration`](./integration.ts) and adds the
- * real-egress capability: `egressRoutes()` (probe whether allowlisted egress can
- * actually route) and — by re-export — `runHook` used with `egress: { allow }`
- * (allowlisted real outbound). Capability contract: needs a **routable rootless
- * sandbox + real network**, and each test self-skips via `egressRoutes()` where
- * that's unavailable. Still a **verification** tier — you assert pass/fail.
+ * There is no separate "e2e" tier: real **egress** is a *capability* of the
+ * harness/integration scope (`egressRoutes()` + `runHook`'s `egress: { allow }`),
+ * not a different kind of test — the old `e2e` barrel added exactly one symbol
+ * over `integration`, which is the definition of a non-tier. It now lives on
+ * `vigiles/integration`; this entry re-exports it unchanged so existing imports
+ * keep working. See `research/testing-api-design.md` Part 4 (two scopes, not
+ * four tiers). Prefer `vigiles/integration`.
  *
- * NOT here: **evals** (`runEval` / `measureTriggerRate` / `judge`). Those are a
- * different axis — **non-deterministic measurement** (real model, mean ± se), run
- * via `vigiles eval` on `*.eval.mjs`. Import them from
- * [`vigiles/eval`](./eval.ts) + [`vigiles/judge`](./judge.ts), not from here.
+ * NOT here: **evals** (`runEval` / `measure` / `measureTriggerRate` / `judge`) —
+ * those are non-deterministic measurement (`vigiles/eval`), a different axis.
  */
 export * from "./integration.js";
-export { egressRoutes } from "./run-hook.js";
 //# sourceMappingURL=e2e.d.ts.map

package/dist/e2e.js

@@ -14,26 +14,19 @@ 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.egressRoutes = void 0;
 /**
- * `vigiles/e2e` — the **deterministic** end-to-end tier (real sandbox + real
- * network, but a definite pass/fail).
+ * `vigiles/e2e` — DEPRECATED back-compat alias for [`vigiles/integration`](./integration.ts).
  *
- * Re-exports everything in [`vigiles/integration`](./integration.ts) and adds the
- * real-egress capability: `egressRoutes()` (probe whether allowlisted egress can
- * actually route) and — by re-export — `runHook` used with `egress: { allow }`
- * (allowlisted real outbound). Capability contract: needs a **routable rootless
- * sandbox + real network**, and each test self-skips via `egressRoutes()` where
- * that's unavailable. Still a **verification** tier — you assert pass/fail.
+ * There is no separate "e2e" tier: real **egress** is a *capability* of the
+ * harness/integration scope (`egressRoutes()` + `runHook`'s `egress: { allow }`),
+ * not a different kind of test — the old `e2e` barrel added exactly one symbol
+ * over `integration`, which is the definition of a non-tier. It now lives on
+ * `vigiles/integration`; this entry re-exports it unchanged so existing imports
+ * keep working. See `research/testing-api-design.md` Part 4 (two scopes, not
+ * four tiers). Prefer `vigiles/integration`.
  *
- * NOT here: **evals** (`runEval` / `measureTriggerRate` / `judge`). Those are a
- * different axis — **non-deterministic measurement** (real model, mean ± se), run
- * via `vigiles eval` on `*.eval.mjs`. Import them from
- * [`vigiles/eval`](./eval.ts) + [`vigiles/judge`](./judge.ts), not from here.
+ * NOT here: **evals** (`runEval` / `measure` / `measureTriggerRate` / `judge`) —
+ * those are non-deterministic measurement (`vigiles/eval`), a different axis.
  */
 __exportStar(require("./integration.js"), exports);
-// The real-egress capability probe (the egress-using runHook is already re-exported
-// via the integration→unit chain).
-var run_hook_js_1 = require("./run-hook.js");
-Object.defineProperty(exports, "egressRoutes", { enumerable: true, get: function () { return run_hook_js_1.egressRoutes; } });
 //# sourceMappingURL=e2e.js.map

package/dist/eval.d.ts

@@ -1,5 +1,7 @@
 import { type ToolCall, type Trace } from "./harness-test.js";
 import { type CacheMode } from "./eval-cache.js";
+import type { Check, CheckJSON } from "./check.js";
+import { type Comparison } from "./stats.js";
 /** One arm of the comparison: fixture overrides + settings (hooks) for this arm. */
 export interface EvalArm {
     /** Files written on top of the base fixture for this arm. */
@@ -172,6 +174,127 @@ export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
  * {@link runEvalWith} with the real agent runner.
  */
 export declare function runEval<M extends Metrics>(spec: EvalSpec<M>): Promise<EvalReport>;
+/** A task run N times, scored against a `Trace` check vocabulary. */
+export interface MeasureSpec {
+    /** Base fixture files written for every run (path → contents). */
+    readonly fixture?: Record<string, string>;
+    /** `.claude/settings.json` (hooks/permissions) for the run. */
+    readonly settings?: unknown;
+    /** A real plugin/repo to load (materialized) — see `EvalArm.plugin`. */
+    readonly plugin?: string;
+    /** A complete plugin dir to install natively (`--plugin-dir`) so skills activate. */
+    readonly pluginDir?: string;
+    /**
+     * Stub each skill BODY in `pluginDir` (frontmatter/trigger surface kept) before
+     * the run — for checks about whether a skill FIRES (`skill()`), not what it
+     * produces. A selected skill stops at selection instead of running its (often
+     * expensive) procedure, so a description/firing run costs a fraction of the
+     * tokens. Do NOT combine with `judged`/quality checks: the body is gone, so
+     * there's nothing to grade. Requires `pluginDir`. See {@link stubSkillBody}.
+     */
+    readonly stubSkillBodies?: boolean;
+    /** The task prompt given to the agent. */
+    readonly task: string;
+    /**
+     * The checks to score across the trials. Any check over the run is accepted:
+     * `Trace` checks (`tool`/`skill`/`output`/`mcp`/`judged`) and resource checks
+     * (`cost`/`latency`/`tokens`, which read the eval-only `usage`) — all fit
+     * `Check<RunContext>`.
+     */
+    readonly checks: readonly Check<RunContext>[];
+    /** Trials. Default 5. */
+    readonly trials?: number;
+    /** Model alias. Default "sonnet" — measure on the model your users run. */
+    readonly model?: string;
+    /** Tools the agent may use. */
+    readonly allowedTools?: readonly string[];
+    /** Per-run timeout ms. */
+    readonly timeoutMs?: number;
+    /** Seconds between runs. */
+    readonly spacingSec?: number;
+}
+/** One check's measured rate across the trials. */
+export interface CheckRate {
+    readonly check: CheckJSON;
+    /** Fraction of trials the check passed (0..1). */
+    readonly rate: number;
+    /** Standard error of the rate. */
+    readonly se: number;
+    /** pass^k — 1 iff the check passed on EVERY trial. */
+    readonly passK: number;
+    /** Trials observed. */
+    readonly n: number;
+}
+export interface CheckReport {
+    readonly n: number;
+    readonly perCheck: readonly CheckRate[];
+}
+/**
+ * Score a check vocabulary across trials — the scored counterpart to
+ * `assertChecks` (strict). Each check yields a `rate ± se` and `pass^k` over `n`
+ * runs. Reuses the tested `runEvalWith` aggregation (one arm), so the loop,
+ * cache, concurrency, and stats come for free. Exported with an injectable
+ * `runner` so the orchestration is unit-testable without a model.
+ */
+export declare function measureWith(spec: MeasureSpec, runner: AgentRunner): Promise<CheckReport>;
+/** Score a check vocabulary across trials against the real `claude` CLI. */
+export declare function measure(spec: MeasureSpec): Promise<CheckReport>;
+/** A task scored against checks across NAMED arms (the harness variable on/off). */
+export interface ArmsMeasureSpec {
+    readonly fixture?: Record<string, string>;
+    /** The arms to compare (settings / plugin / pluginDir per arm). */
+    readonly arms: Record<string, EvalArm>;
+    readonly task: string;
+    readonly checks: readonly Check<RunContext>[];
+    /**
+     * Stub each arm's skill BODIES (frontmatter kept) before the run — the A/B
+     * counterpart to {@link MeasureSpec.stubSkillBodies}. For firing comparisons
+     * (does description variant A fire more than B?), every arm that sets
+     * `pluginDir` is repackaged with bodies stripped so each run stops at
+     * selection — a fraction of the tokens. Arms without a `pluginDir` are left
+     * untouched. Don't combine with `judged`/quality checks. See {@link stubSkillBody}.
+     */
+    readonly stubSkillBodies?: boolean;
+    readonly trials?: number;
+    readonly model?: string;
+    readonly allowedTools?: readonly string[];
+    readonly timeoutMs?: number;
+    readonly spacingSec?: number;
+}
+/** Per-arm {@link CheckReport}s — `arms[name].perCheck[i]` aligns across arms. */
+export interface ArmsCheckReport {
+    readonly arms: Record<string, CheckReport>;
+}
+/** Score checks across arms (injectable runner). Reuses `runEvalWith`. */
+export declare function measureArmsWith(spec: ArmsMeasureSpec, runner: AgentRunner): Promise<ArmsCheckReport>;
+/** Score checks across arms against the real `claude` CLI. */
+export declare function measureArms(spec: ArmsMeasureSpec): Promise<ArmsCheckReport>;
+/**
+ * Welch significance on one check's rate between two arms (`arm` vs `baseline`),
+ * by index in `perCheck`. So "the gated arm resolves the skill significantly more
+ * than vanilla" is a p-value, not a vibe. Reuses `welchTTest` from stats.ts.
+ */
+export declare function compareCheck(report: ArmsCheckReport, baseline: string, arm: string, checkIndex: number): Comparison;
+/** Format a {@link CheckReport}: one line per check with its rate ± se and pass^k. */
+export declare function formatCheckReport(report: CheckReport): string;
+/**
+ * The scored gate (Phase 4): throw if any check's measured rate is below `min` —
+ * the `measure` counterpart to `assertChecks` (strict). Reads the rate, not a
+ * single run, so it never trips on one noisy trial.
+ */
+export declare function assertRates(report: CheckReport, opts: {
+    min: number;
+}): void;
+/**
+ * Serialize a {@link CheckReport} to JUnit XML (Phase 4) — each check a
+ * `<testcase>`, failing when its rate is below `min`. Because a check is *data*,
+ * this falls out for free: CI test reporters, regression baselines, and a
+ * promptfoo bridge all consume the same shape.
+ */
+export declare function checkReportToJUnit(report: CheckReport, opts?: {
+    min?: number;
+    name?: string;
+}): string;
 /** Parse per-run cost/latency/tokens from a stream — pure, model-free. */
 export declare function parseUsage(stdout: string): EvalUsage;
 /** Aggregate per-run metrics: mean for numbers, fraction-true (0..1) for booleans. */
@@ -209,8 +332,19 @@ export declare function formatEvalReport(report: EvalReport): string;
  * (reuse the bare predicates, e.g. `(t) => skillResolved(t, "x:y")`).
  */
 export interface TriggerRateSpec {
-    /** Plugin dir installed natively (`--plugin-dir`) so its skills/commands activate. */
-    readonly pluginDir: string;
+    /**
+     * Plugin dir installed natively (`--plugin-dir`) so its skills/commands
+     * activate. Provide this OR {@link skillsDir}, not both.
+     */
+    readonly pluginDir?: string;
+    /**
+     * A directory of LOOSE skills (`<skillsDir>/<name>/SKILL.md`, e.g. a repo's
+     * `.claude/skills`) to trigger-test directly. vigiles packages them into a
+     * throwaway `--plugin-dir` for you and removes it afterward — the one-liner
+     * for repo-local skills that aren't a published plugin. Provide this OR
+     * {@link pluginDir}, not both.
+     */
+    readonly skillsDir?: string;
     /** The varied prompts to test the trigger against. */
     readonly prompts: readonly string[];
     /**
@@ -223,6 +357,30 @@ export interface TriggerRateSpec {
     readonly irrelevantPrompts?: readonly string[];
     /** Did the behaviour fire on this run? e.g. `(t) => skillResolved(t, "x:y")`. */
     readonly fired: (trace: Trace) => boolean;
+    /**
+     * Replace each skill's BODY with a no-op stub (keeping its frontmatter — name +
+     * description) before running. Trigger-rate is decided by the frontmatter alone
+     * (the model selects a skill before its body loads), so stubbing the body can't
+     * change what's measured but stops the run from executing an expensive
+     * procedure once the skill fires — far cheaper, faster, side-effect-free. All
+     * skills' descriptions stay present, so the selection competition is faithful.
+     * Default false (off) for now; recommended `true` for trigger evals. See
+     * {@link stubSkillBody}.
+     */
+    readonly stubSkillBodies?: boolean;
+    /**
+     * Minimum number of prompts each set (relevant + irrelevant) must have. A
+     * handful of prompts can't tell a real recall/precision rate from noise, so
+     * the run is rejected before it spends a token. Default 10; lower it
+     * deliberately for a genuinely narrow skill.
+     */
+    readonly minPrompts?: number;
+    /**
+     * Reject the run when two prompts in a set are closer than this in NCD
+     * (gzip-based distance, 0..1; 0 = identical) — near-duplicate prompts inflate
+     * a rate without testing varied phrasings. Default 0.3 (the rule-dup threshold).
+     */
+    readonly minDistance?: number;
     /** Trials per prompt. Default 1. */
     readonly trials?: number;
     /** Model alias. Default "haiku". */
@@ -263,6 +421,63 @@ export interface TriggerRateReport {
     /** Per-prompt stats for the irrelevant set. Present with irrelevant prompts. */
     readonly perIrrelevant?: readonly PromptTriggerStat[];
 }
+/**
+ * Package loose `<skillsDir>/<name>/SKILL.md` skills into a throwaway plugin dir
+ * that `claude --plugin-dir` accepts — so repo-local skills (e.g. `.claude/skills`)
+ * can be trigger-tested without hand-rolling a `plugin.json`. Writes a minimal
+ * `.claude-plugin/plugin.json` and copies each `<name>/` (recursively, so
+ * `references/` etc. come along) under `skills/<name>/`. Returns the temp plugin
+ * dir; the caller removes it (`measureTriggerRate` does). Throws if the directory
+ * is missing or holds no `<name>/SKILL.md`.
+ */
+export declare function packageSkillsDir(skillsDir: string, opts?: {
+    name?: string;
+    stub?: boolean;
+}): string;
+/**
+ * Rewrite a SKILL.md to keep its YAML frontmatter (the trigger surface — name +
+ * description) but replace the body with a no-op stub. Trigger-rate is a property
+ * of the frontmatter ONLY: the model picks a skill from its name + description
+ * before the body is ever loaded, so the body is causally downstream of selection
+ * and irrelevant to whether the skill fires. Stubbing it lets a trigger run stop
+ * AT selection instead of executing an expensive multi-step procedure — cheaper,
+ * faster, and side-effect-free, without changing what's measured. Pure.
+ */
+export declare function stubSkillBody(skillMd: string): string;
+/**
+ * Build a throwaway plugin dir mirroring `pluginDir`'s skills with their BODIES
+ * stripped (frontmatter kept) — the trigger surface a description/firing check
+ * needs, without paying to run each skill's procedure. Keeps the original plugin
+ * NAME so `<name>:<skill>` ids still match. The caller removes the returned dir.
+ * See {@link stubSkillBody} for why the body is irrelevant to selection.
+ */
+export declare function stubbedPluginDir(pluginDir: string): string;
+/**
+ * Distance between two prompts in ~0..1 (0 = identical, higher = more
+ * different) via Normalized Compression Distance over the normalized text.
+ * Reuses {@link ncd} from the proof engine.
+ */
+export declare function promptDistance(a: string, b: string): number;
+export interface PromptDiversityIssue {
+    readonly kind: "too-few" | "too-similar";
+    readonly message: string;
+}
+/**
+ * Deterministically check a prompt set is big and varied enough to measure a
+ * trigger rate: at least `minPrompts` entries, and no two closer than
+ * `minDistance` in NCD. Pure — no model. `label` names the set in messages.
+ */
+export declare function checkPromptDiversity(prompts: readonly string[], opts?: {
+    minPrompts?: number;
+    minDistance?: number;
+    label?: string;
+}): PromptDiversityIssue[];
+/** Throw if a prompt set isn't big/varied enough. See {@link checkPromptDiversity}. */
+export declare function assertPromptDiversity(prompts: readonly string[], opts?: {
+    minPrompts?: number;
+    minDistance?: number;
+    label?: string;
+}): void;
 /**
  * Trigger-rate orchestration — every prompt × trial via `runner`, the `fired`
  * predicate evaluated per run and aggregated into an overall + per-prompt rate.