vigiles 25.0.0 → 26.0.0

package/dist/eval.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = void 0;
+exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = exports.spawnAgent = exports.EFFORT_ENV_VAR = void 0;
 exports.resolveSpawnEnv = resolveSpawnEnv;
-exports.spawnAgent = spawnAgent;
+exports.pinEffortEnv = pinEffortEnv;
+exports.effortRejection = effortRejection;
+exports.withEffortGuard = withEffortGuard;
+exports.buildAgentArgs = buildAgentArgs;
 exports.unregisteredSkillFiles = unregisteredSkillFiles;
 exports.runEval = runEval;
 exports.measureWith = measureWith;
@@ -99,35 +102,136 @@ function writeFiles(cwd, files) {
  * leak the host environment into an untrusted, model-driven run.
  */
 function resolveSpawnEnv(a, base = process.env) {
-    return a.replaceEnv ? (a.env ?? {}) : { ...base, ...a.env };
+    const resolved = a.replaceEnv ? (a.env ?? {}) : { ...base, ...a.env };
+    return pinEffortEnv(resolved, a.effort);
 }
+/**
+ * The env var name the harness reads for the reasoning budget. It sits ABOVE the
+ * `--effort` flag in the CLI's own precedence chain, so passing the flag alone
+ * does NOT pin the level.
+ */
+exports.EFFORT_ENV_VAR = "CLAUDE_CODE_EFFORT_LEVEL";
+/**
+ * Pin the effort the run actually gets, so the recorded effort is the effort
+ * that ran.
+ *
+ * WHY THIS EXISTS AND WHY IT IS NOT OPTIONAL. Effort has THREE inputs — the
+ * `--effort` flag, the `effortLevel` settings key, and `CLAUDE_CODE_EFFORT_LEVEL`
+ * — and the env var wins over the flag. `EPHEMERAL_ALLOW_PREFIXES` passes
+ * `CLAUDE_*` through by design (the CLI reads several such knobs and dropping one
+ * is the failure mode), so an ambient `CLAUDE_CODE_EFFORT_LEVEL=max` in the
+ * author's shell survives even the SCRUBBED ephemeral env. Without this pin,
+ * hashing effort into the lock would make the lock CONFIDENTLY WRONG: it would
+ * record `low` over a run that executed at `max` — the exact defect the feature
+ * exists to prevent, reintroduced by the fix for it.
+ *
+ * Both directions matter, so both are handled:
+ *  - effort DECLARED  → set the var, overriding whatever the shell had.
+ *  - effort OMITTED   → DELETE an inherited var, so "omit" means the harness
+ *                       default rather than "whatever this machine happened to
+ *                       export". An omitted effort must not be a hidden input.
+ */
+function pinEffortEnv(env, effort) {
+    // Rebuilt WITHOUT the key rather than deleting or assigning `undefined`:
+    // omission has to be provable here, and whether a spawn drops an
+    // `undefined`-valued env entry is a Node-version detail we should not lean on.
+    const { [exports.EFFORT_ENV_VAR]: _inherited, ...rest } = env;
+    return effort === undefined
+        ? rest
+        : { ...rest, [exports.EFFORT_ENV_VAR]: String(effort) };
+}
+/**
+ * The harness's own rejection of an `--effort` value, or null. Pure.
+ *
+ * The CLI does NOT fail on a bad level — it prints this to stderr and silently
+ * runs at its default. That silent substitution is precisely the bug class this
+ * feature addresses (a number produced by a configuration nobody asked for), so
+ * a rejected value must never become a sample. Matched on the binary's own
+ * wording, the same shape as {@link isRateLimited}.
+ */
+function effortRejection(out) {
+    const text = `${out.stderr ?? ""}\n${out.stdout}`;
+    const m = /Unknown --effort value[^\n]*/.exec(text);
+    return m ? m[0].trim() : null;
+}
+/**
+ * Wrap a runner so a run the harness rejected on `--effort` FAILS LOUDLY.
+ *
+ * Applied ONCE, around the real runner, rather than as a guard repeated at each
+ * of the five `runner(...)` call sites — a guard per call site is the shape that
+ * left four of five compilers unprotected in #173.
+ *
+ * It THROWS rather than counting the trial as `runError`. A `runError` trial is
+ * dropped from the denominator, which is right for a transient (a rate limit) and
+ * wrong here: an unusable effort value is deterministic and repeatable, so every
+ * trial fails it and the run would report a rate computed over ZERO samples. A
+ * configuration mistake should stop the run and name itself.
+ */
+function withEffortGuard(runner) {
+    // 🔴 DELIBERATELY NOT `async`. An `async` wrapper turns the wrapped runner's
+    // SYNCHRONOUS throws into rejected promises, and the real runner refuses
+    // synchronously on purpose — `refuseDuringEvalLoad` / `refuseUnderForeignRunner`
+    // stop a paid eval from billing when a foreign test runner collects it. Making
+    // this `async` silently downgraded those refusals from "throws at the call" to
+    // "returns a promise that rejects", which `assert.throws` cannot see and an
+    // un-awaited caller would not notice. Caught by the full suite, not by the
+    // targeted one; pinned below by `withEffortGuard preserves a SYNCHRONOUS throw`.
+    return (a) => {
+        const pending = runner(a);
+        return pending.then((out) => {
+            const rejection = effortRejection(out);
+            if (rejection !== null) {
+                throw new Error(`the harness rejected effort ${JSON.stringify(a.effort)}: ${rejection}`);
+            }
+            return out;
+        });
+    };
+}
+/**
+ * Build the real runner's argv. Pure and exported so the FLAGS are provable —
+ * `spawnAgentRaw` is `v8 ignore`d (it spawns a subprocess), so an argv assembled
+ * inline there could not be asserted at all. Mirrors `buildCodexArgs`.
+ */
+function buildAgentArgs(a) {
+    return [
+        "-p",
+        a.task,
+        // stream-json (+ --verbose, required with -p) so the per-turn tool_use
+        // events survive into `ctx.toolCalls` — the unified Trace, same as the
+        // harness tier. The terminal `result` event still carries num_turns/output.
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--model",
+        a.model,
+        ...(a.effort !== undefined ? ["--effort", String(a.effort)] : []),
+        "--permission-mode",
+        "acceptEdits",
+        ...(a.pluginDir !== undefined
+            ? ["--plugin-dir", (0, node_path_1.resolve)(a.pluginDir)]
+            : []),
+        ...(a.hasSettings ? ["--settings", "settings.json"] : []),
+        "--allowedTools",
+        ...a.tools,
+    ];
+}
+/**
+ * The real `claude`-spawning runner (composition root). Exported so other
+ * real-model entries (e.g. the `audit` trigger tier) bind the same runner.
+ *
+ * The effort guard is composed in HERE, at the single definition, rather than at
+ * each of the places that bind this runner — so every consumer, including ones
+ * not yet written, is covered by construction. Guarding each call site instead is
+ * the shape that left four of five compilers unprotected in #173.
+ */
+exports.spawnAgent = withEffortGuard(spawnAgentRaw);
 /* v8 ignore start -- real claude subprocess; exercised by bench/, not the unit gate */
-/** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
-function spawnAgent(a) {
+/** The unguarded spawn itself; wrapped by {@link spawnAgent}, never bound raw. */
+function spawnAgentRaw(a) {
     (0, eval_load_phase_js_1.refuseDuringEvalLoad)("spawning `claude`");
     (0, foreign_runner_js_1.refuseUnderForeignRunner)("spawning `claude`");
     return new Promise((resolvePromise) => {
-        const args = [
-            "-p",
-            a.task,
-            // stream-json (+ --verbose, required with -p) so the per-turn tool_use
-            // events survive into `ctx.toolCalls` — the unified Trace, same as the
-            // harness tier. The terminal `result` event still carries num_turns/output.
-            "--output-format",
-            "stream-json",
-            "--verbose",
-            "--model",
-            a.model,
-            "--permission-mode",
-            "acceptEdits",
-            ...(a.pluginDir !== undefined
-                ? ["--plugin-dir", (0, node_path_1.resolve)(a.pluginDir)]
-                : []),
-            ...(a.hasSettings ? ["--settings", "settings.json"] : []),
-            "--allowedTools",
-            ...a.tools,
-        ];
+        const args = buildAgentArgs(a);
         const child = (0, node_child_process_1.spawn)(runtime_js_1.claudeCodeRuntime.agentBinary, args, {
             cwd: a.cwd,
             // The security-critical env resolution (overlay vs. scrubbed replacement)
@@ -194,7 +298,7 @@ function warnUnregisteredSkillArms(arms) {
 }
 async function runEval(spec) {
     warnUnregisteredSkillArms(spec.arms);
-    const report = await runEvalWith(spec, spawnAgent);
+    const report = await runEvalWith(spec, exports.spawnAgent);
     // Surface what the run spent — tokens + API-equivalent $, and a LOUD warning if
     // it was billed to a metered API key instead of the subscription. See eval-cost.ts.
     (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromEvalReport)(report));
@@ -237,6 +341,7 @@ async function measureWith(spec, runner) {
             task: spec.task,
             trials: spec.trials ?? 5,
             model: spec.model ?? "sonnet",
+            effort: spec.effort,
             allowedTools: spec.allowedTools,
             timeoutMs: spec.timeoutMs,
             spacingSec: spec.spacingSec,
@@ -266,7 +371,7 @@ async function measureWith(spec, runner) {
 /* v8 ignore start -- real claude subprocess; thin wrapper over measureWith */
 /** Score a check vocabulary across trials against the real `claude` CLI. */
 async function measure(spec) {
-    const report = await measureWith(spec, spawnAgent);
+    const report = await measureWith(spec, exports.spawnAgent);
     (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromArm)(report.usage));
     return report;
 }
@@ -283,6 +388,7 @@ async function measureArmsWith(spec, runner) {
             task: spec.task,
             trials: spec.trials ?? 5,
             model: spec.model ?? "sonnet",
+            effort: spec.effort,
             allowedTools: spec.allowedTools,
             timeoutMs: spec.timeoutMs,
             spacingSec: spec.spacingSec,
@@ -337,7 +443,7 @@ function stubArmPluginDirs(arms) {
 /** Score checks across arms against the real `claude` CLI. */
 async function measureArms(spec) {
     warnUnregisteredSkillArms(spec.arms);
-    const report = await measureArmsWith(spec, spawnAgent);
+    const report = await measureArmsWith(spec, exports.spawnAgent);
     // Sum every arm's spend — an A/B run pays for both arms.
     (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.sumCosts)(Object.values(report.arms).map((a) => (0, eval_cost_js_1.costFromArm)(a.usage))));
     return report;
@@ -552,6 +658,7 @@ async function runSkillSelectionTrial(args) {
             task: args.prompt,
             cwd,
             model: args.model,
+            effort: args.effort,
             tools: args.tools ?? ["Read", "Edit", "Write", "Bash", "Skill"],
             hasSettings: false,
             pluginDir: args.pluginDir,
@@ -637,6 +744,7 @@ async function runWithCache(runArgs, keyParts, runner, cfg) {
     const key = (0, eval_cache_js_1.cacheKey)({
         task: runArgs.task,
         model: runArgs.model,
+        effort: runArgs.effort,
         tools: runArgs.tools,
         files: keyParts.files,
         settings: keyParts.settings,
@@ -967,6 +1075,7 @@ async function executeTrial(spec, arm, trialIndex, runner, cfg) {
             cwd,
             // A model comparison is a harness A/B: an arm may override the model.
             model: arm.model ?? cfg.model,
+            effort: arm.effort ?? cfg.effort,
             tools: cfg.tools,
             hasSettings,
             pluginDir: arm.pluginDir,
@@ -1100,8 +1209,16 @@ async function withEvalLock(args, produce) {
     }
     if (!isDatedModel(args.model))
         warnFloatingModel(args.model);
+    // OVERLAP, DELIBERATE — do not delete this as dead. Effort reaches the hash
+    // twice: here (the CHOKEPOINT every seam passes through, so a future seam that
+    // forgets to fold effort into its own `inputs` is still covered) and inside
+    // each seam's `inputs` (which alone can see a PER-ARM override this line
+    // cannot). Measured 2026-09-01: removing either one alone leaves the suite
+    // green; removing BOTH fails `changing effort makes a committed lock STALE`.
+    // That is two populations covered, not one line duplicated.
     const inputsHash = (0, eval_lock_js_1.evalInputsHash)({
         model: args.model,
+        effort: args.effort,
         evalApiVersion: lock.evalApiVersion,
         inputs: args.inputs,
     });
@@ -1116,6 +1233,7 @@ async function withEvalLock(args, produce) {
         name: args.name,
         inputsHash,
         model: args.model,
+        effort: args.effort,
         harnessVersionKey: harnessVersion(),
         evalApiVersion: lock.evalApiVersion,
         builtAt: new Date().toISOString(),
@@ -1166,6 +1284,10 @@ function evalArmsInputs(spec, cfg) {
         const absRoot = arm.plugin ? (0, node_path_1.resolve)(process.cwd(), arm.plugin) : "";
         arms[name] = {
             model: arm.model ?? cfg.model,
+            // The per-ARM half of the overlap documented at `inputsHash` — the
+            // chokepoint sees only the eval-level effort, so an arm that overrides it
+            // would otherwise hash identically to its sibling.
+            effort: arm.effort ?? cfg.effort,
             tools: [...cfg.tools].sort(),
             files: stripPluginRoot(resolved.files, absRoot),
             settings: stripPluginRoot(resolved.settings, absRoot),
@@ -1203,6 +1325,7 @@ async function runEvalWith(spec, runner) {
     const backoffMs = spec.retryBackoffMs ?? 1000;
     const cfg = {
         model: spec.model ?? "haiku",
+        effort: spec.effort,
         tools: spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"],
         timeoutMs: spec.timeoutMs ?? 240000,
         cache: spec.cache ?? "off",
@@ -1232,7 +1355,7 @@ async function runEvalWith(spec, runner) {
     // resolveHarness/hashDir work). `check` replays the committed report below
     // without ever entering the run pool — so no model is driven in CI.
     const inputs = lock.mode === "off" ? undefined : evalArmsInputs(spec, cfg);
-    return withEvalLock({ name: spec.name, inputs, model: cfg.model, lock }, async () => {
+    return withEvalLock({ name: spec.name, inputs, model: cfg.model, effort: cfg.effort, lock }, async () => {
         const results = await runPool(units, concurrency, worker);
         const { arms, totalCostUsd } = aggregateArms(Object.keys(spec.arms), results);
         return { name: spec.name ?? "eval", trials, arms, totalCostUsd, aborted };
@@ -1285,7 +1408,7 @@ function formatEvalReport(report) {
  * The asymmetry reflects default-vs-injected, not a hexagonal violation.
  */
 exports.claudeEvalDriver = {
-    runner: spawnAgent,
+    runner: exports.spawnAgent,
     parse: parseClaudeRun,
     harness: "claude-code",
 };
@@ -1591,6 +1714,7 @@ async function runTriggerTrial(prompt, cfg, runner) {
             task: prompt,
             cwd,
             model: cfg.model,
+            effort: cfg.effort,
             tools: cfg.tools,
             hasSettings: false,
             pluginDir: cfg.pluginDir,
@@ -1690,6 +1814,7 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
         // Sonnet, not haiku: trigger-rate is a selection measurement and haiku
         // under-selects, producing false-negative recall (see TriggerRateSpec.model).
         model,
+        effort: spec.effort,
         tools: spec.allowedTools ?? ["Read", "Edit", "Write", "Bash", "Skill"],
         timeoutMs: spec.timeoutMs ?? 240000,
         spacing: (spec.spacingSec ?? 4) * 1000,
@@ -1715,6 +1840,7 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
                     ? [...spec.irrelevantPrompts]
                     : undefined,
                 model: cfg.model,
+                effort: cfg.effort,
                 tools: [...cfg.tools].sort(),
                 fixture: spec.fixture,
                 competitors,
@@ -1723,7 +1849,13 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
                 // STALE if the eval is switched to another harness.
                 harness,
             };
-        return await withEvalLock({ name: spec.name, inputs: triggerInputs, model: cfg.model, lock }, async () => {
+        return await withEvalLock({
+            name: spec.name,
+            inputs: triggerInputs,
+            model: cfg.model,
+            effort: cfg.effort,
+            lock,
+        }, async () => {
             const relevant = await runTriggerSet(spec.prompts, cfg, runner);
             const base = {
                 rate: relevant.n > 0 ? relevant.fired / relevant.n : 0,

package/dist/exclude.d.ts

@@ -0,0 +1,25 @@
+import type { IgnoreLike } from "glob";
+/** Always excluded, whatever the config says. Root-relative, like `exclude`. */
+export declare const EXCLUDE_FLOOR: readonly string[];
+/** The parsed `.vigilesrc.json#exclude`, in the forms a walk consumes. */
+export interface ExcludeSet {
+    /** Absolute repo root every pattern is relative to. */
+    readonly root: string;
+    /** The user's patterns, as written (for messages). */
+    readonly patterns: readonly string[];
+    /**
+     * The string-list face for a glob rooted AT `root`: the floor, then each user
+     * pattern normalized so a bare directory name excludes its subtree (`bench` →
+     * `bench`, `bench/**`), which is what "tsconfig-style" promises.
+     */
+    readonly ignore: readonly string[];
+    /** The function face for `globSync`, correct whatever the glob's `cwd` is. */
+    readonly globIgnore: IgnoreLike;
+    /** Is this root-relative path excluded (floor or user pattern)? */
+    matches(rel: string): boolean;
+    /** The pattern that excludes this root-relative path, or null when none does. */
+    explain(rel: string): string | null;
+}
+/** Parse `.vigilesrc.json#exclude` once, against `root`. */
+export declare function excludeSet(root: string, patterns: readonly string[] | undefined): ExcludeSet;
+//# sourceMappingURL=exclude.d.ts.map

package/dist/exclude.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCLUDE_FLOOR = void 0;
+exports.excludeSet = excludeSet;
+/**
+ * The ONE exclusion policy for every walk that polices the user's repository.
+ *
+ * `.vigilesrc.json#exclude` is documented as "tsconfig-style" — a list of paths or
+ * globs the repo's own lint should not police (vendored corpora, benchmark
+ * fixtures, frozen reproductions). Issue #192: it was honoured by three walks,
+ * ignored by six, and the three that honoured it did not agree with each other.
+ *
+ * 🔴 TWO DIALECTS WERE ALREADY IN `main`, AND THEY DISAGREED ON `"bench"`.
+ * `glob`'s string `ignore` treats a bare directory name as a file pattern:
+ * measured 2026-09-03 on glob 13, `ignore: ["bench"]` and `["bench/"]` exclude
+ * NOTHING, only `["bench/**"]` works. The minimatch helper inside
+ * `discoverNestedBundles` accepted the bare name. tsc and ESLint both treat the
+ * bare name as the directory (measured the same day). So a user who wrote the
+ * key the way its JSDoc promised got the nested-bundle pass filtered and every
+ * glob-backed pass unfiltered — with no way to tell from the output.
+ *
+ * This module is the fix in the shape the fence-parser fix took
+ * (`core/markdown.ts`): not one WALK — the walks legitimately have different
+ * scopes — but ONE PREDICATE, parsed once from config, that every walk consumes.
+ * It offers the predicate in the two forms a walk needs and nothing else:
+ *
+ *   - `globIgnore` — an `IgnoreLike` for `globSync`, keyed on the path's position
+ *     RELATIVE TO THE REPO ROOT, so a glob rooted below the root (`vigiles lint
+ *     some/dir`) still applies a root-relative `exclude` correctly. The string
+ *     list could not: `bench/**` relative to `some/dir` matches nothing.
+ *   - `ignore` — the normalized string list, for pure detectors in `core/` that
+ *     take an ignore list by injection and glob from the repo root themselves.
+ *   - `matches(rel)` / `explain(rel)` — for `readdirSync`-style walks and for the
+ *     one line printed when an explicitly named path is processed anyway.
+ *
+ * 🔴 EVERY IN-SCOPE WALK TAKES AN `ExcludeSet` AS A REQUIRED PARAMETER. The
+ * shape that let `findSpecs` go a year without the key was
+ * `exclude: readonly string[] = []` — optional-with-default lets a call site
+ * forget, and a forgotten argument is indistinguishable from an empty config.
+ * Do not reintroduce an optional `ExcludeSet` anywhere in scope.
+ *
+ * EXPLICITLY NAMED PATHS WIN, LOUDLY. Four tools were measured (2026-09-03):
+ * ripgrep and tsc process an explicitly named ignored file silently; ESLint
+ * skips it with a warning; prettier skips it and prints "All matched files use
+ * Prettier code style!" — the silent no-op this repo has burned itself on. vigiles
+ * takes the rg/tsc semantics (an argument is an instruction) with ESLint's
+ * loudness: the path is processed and ONE line says which pattern it matched.
+ * `exclude` filters DISCOVERY, never an argument.
+ *
+ * WHAT DELIBERATELY DOES NOT GO THROUGH THIS MODULE — so the next reader does not
+ * "fix" it (the classification is issue #192's comment):
+ *
+ *   - `core/compile.ts#validateGlobRef` — verifies a spec's own `glob()` reference
+ *     resolves to ≥1 file. That is reference verification of the user's claim
+ *     about the repo, not lint scope; excluding a dir must not make a true ref
+ *     false.
+ *   - `cli.ts#specReferencedElsewhere` — eject's "is this spec compiled anywhere
+ *     else" safety check. Wider is safer: a target under an excluded dir is still
+ *     a target that would be orphaned.
+ *   - `core/validate.ts#expandGlobs` — expands a pattern the user TYPED. An
+ *     argument wins (see above); it is not discovery.
+ *   - Surface walks INSIDE a bundle (`plugin-loader.ts#readTree`,
+ *     `skill-reachability.ts`): `exclude` applies at BUNDLE granularity via
+ *     `discoverNestedBundles`; a skill inside your own `skills/` is yours.
+ *   - Internal machinery that never enumerates the user's repo as lint surface:
+ *     eval temp installs (`eval.ts`, `adapters/codex/eval.ts`), the eval cache and
+ *     locks (`eval-cache.ts`, `eval-lock.ts`, `run-script.ts#snapshotTree`),
+ *     `.vigiles/hooks/` discovery (`hook-install.ts`, a fixed dir), sidecars
+ *     (`core/sidecar.ts`), linter catalogs / rulesDirs / toolchain paths
+ *     (`core/linters.ts`, `core/generate-schema.ts`, `core/generate-types.ts`),
+ *     `init`'s shallow adoptable-surface sweep (`cli.ts#discoverAdoptableSurfaces`)
+ *     and lint-config collection (`cli.ts#safeReaddir`), and
+ *     `core/generate-harness.ts` (an explicit, non-recursive dir argument).
+ *
+ * The floor (`node_modules`, `dist`, `.git`, `.vigiles`) lives here too, so a
+ * walk cannot carry its own private copy of it — the original `findSpecs` list
+ * lacked `.vigiles/**` while the three `core/` detectors had it.
+ */
+const minimatch_1 = require("minimatch");
+const node_path_1 = require("node:path");
+/** Always excluded, whatever the config says. Root-relative, like `exclude`. */
+exports.EXCLUDE_FLOOR = [
+    "node_modules/**",
+    "dist/**",
+    ".git/**",
+    ".vigiles/**",
+];
+/** `a\b\c` → `a/b/c`, drop a leading `./`, drop a trailing `/`. */
+function normalizeRel(rel) {
+    let r = rel
+        .split(node_path_1.sep)
+        .join("/")
+        .replace(/^(?:\.\/)+/, "");
+    while (r.endsWith("/"))
+        r = r.slice(0, -1);
+    return r;
+}
+/** Parse `.vigilesrc.json#exclude` once, against `root`. */
+function excludeSet(root, patterns) {
+    const user = (patterns ?? []).map(normalizeRel).filter((p) => p !== "");
+    const all = [...exports.EXCLUDE_FLOOR, ...user];
+    // One compiled matcher pair per pattern: the pattern itself and its subtree.
+    const compiled = all.map((p) => ({
+        pattern: p,
+        self: new minimatch_1.Minimatch(p, { dot: true }),
+        subtree: new minimatch_1.Minimatch(`${p}/**`, { dot: true }),
+    }));
+    const explain = (rel) => {
+        const r = normalizeRel(rel);
+        if (r === "" || r === "." || r.startsWith("../"))
+            return null;
+        for (const c of compiled) {
+            if (c.self.match(r) || c.subtree.match(r))
+                return c.pattern;
+        }
+        return null;
+    };
+    const matches = (rel) => explain(rel) !== null;
+    const relOf = (p) => normalizeRel((0, node_path_1.relative)(root, p.fullpath()));
+    return {
+        root,
+        patterns: user,
+        ignore: [...exports.EXCLUDE_FLOOR, ...user.flatMap((p) => [p, `${p}/**`])],
+        globIgnore: {
+            ignored: (p) => matches(relOf(p)),
+            childrenIgnored: (p) => matches(relOf(p)),
+        },
+        matches,
+        explain,
+    };
+}
+//# sourceMappingURL=exclude.js.map

package/dist/guardrail-check.d.ts

@@ -1,27 +1,3 @@
-/**
- * Guardrail verification — "prove your safety hook ACTUALLY blocks."
- *
- * The #1 verified Claude Code hook pain is FALSE CONFIDENCE: a developer ships a
- * PreToolUse safety hook, believes they're protected, and finds out otherwise only
- * when the agent force-pushes to main. The failure is silent — exit 1 instead of
- * exit 2, the wrong JSON field, PostToolUse-can't-block, a wrong `jq` path, a missing
- * `chmod +x` — all produce a hook that LOOKS like a guard and enforces nothing, with
- * no error. (Crosley: "three different teams believed they had blocked force pushes";
- * RFC #45427, closed not-planned. Full corpus: research/hook-pain-points.md.)
- *
- * This is the deterministic answer: feed a curated **disaster event** (`git push
- * --force`, `rm -rf /`, `git commit --no-verify`, `cat ~/.ssh/*`, `curl … | sh`) to
- * the hook via {@link runHook} and check the normalized decision is BLOCK. No model,
- * no API key, runs in CI, works on a hand-written hook with NO vigiles spec — it
- * verifies the hook's decision LOGIC, so it sidesteps CC's runtime delivery bugs
- * (the model routing around a tool entirely, #45427 / #32376) which it deliberately
- * does NOT claim to fix. (#34692, the old subagent-delivery gap, is fixed as of CC
- * 2.1.241 — see src/subagent-delivery.test.ts.)
- *
- * Pure-ish (wraps the existing runHook tier). The catalog is harness-neutral data;
- * the scaffold-test generator emits a test that calls these, and the same engine
- * backs an informational coverage report.
- */
 import { type RunHookOptions } from "./run-hook.js";
 /** A category of dangerous action a guard might be meant to block. */
 export type DisasterCategory = "destructive-git" | "destructive-fs" | "bypass-verification" | "secret-exfiltration" | "remote-code";
@@ -61,6 +37,49 @@ export interface VerifyGuardrailOptions extends RunHookOptions {
     /** The PreToolUse event name to wrap each disaster in (default "PreToolUse"). */
     readonly event?: string;
 }
+/**
+ * The same dangerous commands, spelled the other ways a shell reads identically.
+ *
+ * Takes a battery of hook test cases (shell commands wrapped as `PreToolUse`
+ * events — `DISASTER_CATALOG` is the shipped one) and returns MORE test cases:
+ * every command re-spelled with a quoted flag (`git push "--force"`), the short
+ * form of a flag (`-f`), an absolute or escaped head (`/usr/bin/git`, `\git`), or a
+ * pass-through wrapper (`sudo …`, `env …`). The shell runs each rewrite exactly as
+ * it runs the original. Feed them to `assertBlocksDisasters` alongside the
+ * originals:
+ *
+ *     assertBlocksDisasters(hook, {
+ *       events: [...DISASTER_CATALOG, ...experimental_alternateSpellings(DISASTER_CATALOG)],
+ *     });
+ *
+ * WHAT BREAKS WITHOUT IT. A guard whose rule is "the command contains `--force`"
+ * blocks all seven catalog commands, so the battery is green — and lets
+ * `git push "--force"` through, because the quotes make it a different string.
+ * Measured 2026-09-02 on the shipped dogfood guard BEFORE this existed: 7/7
+ * originals blocked, **8 of 30** hand-written re-spellings blocked.
+ *
+ * WHY THE OUTPUT IS TRUSTWORTHY. Nothing new is judged. "Dangerous" is inherited
+ * from the original a human put in the battery; "the same command" is decided by
+ * the shell parser vigiles already uses for `runs()`/`touches()` (see
+ * {@link sameOperation}). A rewrite that fails that check throws rather than being
+ * emitted, so the battery can never quietly shrink.
+ *
+ * It returns ONLY the rewrites (never the originals), so pass the originals
+ * alongside as above. Each rewrite keeps its original's `tool` and `category`
+ * and takes the original's id with an index suffix (`force-push~4`), so a report
+ * names which spelling got through.
+ *
+ * In promptfoo's vocabulary each rewrite rule here is a "strategy"; the difference
+ * is that promptfoo's encodings (base64, leetspeak) may or may not be decoded by the
+ * target, whereas every rewrite here is one the shell provably executes identically
+ * — a miss is a guard bug, never an ambiguous input.
+ *
+ * @experimental Days old with a single consumer (this repo's own dogfood) and no
+ * external use. The set of rewrite rules and the id-suffix shape are the parts most
+ * likely to move; the prefix says so at every call site, which an import line or a
+ * doc note cannot.
+ */
+export declare function experimental_alternateSpellings(events: readonly DisasterEvent[]): readonly DisasterEvent[];
 /**
  * Run a hook command against the disaster battery and report which events it blocks.
  * `hookCommand` is the exact shell the hook registers (e.g. `bash hooks/guard.sh` or

package/dist/guardrail-check.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DISASTER_CATALOG = void 0;
+exports.experimental_alternateSpellings = experimental_alternateSpellings;
 exports.verifyGuardrail = verifyGuardrail;
 exports.unblockedDisasters = unblockedDisasters;
 exports.assertBlocksDisasters = assertBlocksDisasters;
@@ -29,6 +30,7 @@ exports.formatGuardrailReport = formatGuardrailReport;
  * the scaffold-test generator emits a test that calls these, and the same engine
  * backs an informational coverage report.
  */
+const bash_equivalents_js_1 = require("./core/bash-equivalents.js");
 const run_hook_js_1 = require("./run-hook.js");
 /**
  * The curated battery. Deliberately small and high-signal: each is a textbook
@@ -99,6 +101,61 @@ function selectEvents(opts) {
     }
     return exports.DISASTER_CATALOG;
 }
+/**
+ * The same dangerous commands, spelled the other ways a shell reads identically.
+ *
+ * Takes a battery of hook test cases (shell commands wrapped as `PreToolUse`
+ * events — `DISASTER_CATALOG` is the shipped one) and returns MORE test cases:
+ * every command re-spelled with a quoted flag (`git push "--force"`), the short
+ * form of a flag (`-f`), an absolute or escaped head (`/usr/bin/git`, `\git`), or a
+ * pass-through wrapper (`sudo …`, `env …`). The shell runs each rewrite exactly as
+ * it runs the original. Feed them to `assertBlocksDisasters` alongside the
+ * originals:
+ *
+ *     assertBlocksDisasters(hook, {
+ *       events: [...DISASTER_CATALOG, ...experimental_alternateSpellings(DISASTER_CATALOG)],
+ *     });
+ *
+ * WHAT BREAKS WITHOUT IT. A guard whose rule is "the command contains `--force`"
+ * blocks all seven catalog commands, so the battery is green — and lets
+ * `git push "--force"` through, because the quotes make it a different string.
+ * Measured 2026-09-02 on the shipped dogfood guard BEFORE this existed: 7/7
+ * originals blocked, **8 of 30** hand-written re-spellings blocked.
+ *
+ * WHY THE OUTPUT IS TRUSTWORTHY. Nothing new is judged. "Dangerous" is inherited
+ * from the original a human put in the battery; "the same command" is decided by
+ * the shell parser vigiles already uses for `runs()`/`touches()` (see
+ * {@link sameOperation}). A rewrite that fails that check throws rather than being
+ * emitted, so the battery can never quietly shrink.
+ *
+ * It returns ONLY the rewrites (never the originals), so pass the originals
+ * alongside as above. Each rewrite keeps its original's `tool` and `category`
+ * and takes the original's id with an index suffix (`force-push~4`), so a report
+ * names which spelling got through.
+ *
+ * In promptfoo's vocabulary each rewrite rule here is a "strategy"; the difference
+ * is that promptfoo's encodings (base64, leetspeak) may or may not be decoded by the
+ * target, whereas every rewrite here is one the shell provably executes identically
+ * — a miss is a guard bug, never an ambiguous input.
+ *
+ * @experimental Days old with a single consumer (this repo's own dogfood) and no
+ * external use. The set of rewrite rules and the id-suffix shape are the parts most
+ * likely to move; the prefix says so at every call site, which an import line or a
+ * doc note cannot.
+ */
+function experimental_alternateSpellings(events) {
+    return events.flatMap((event) => {
+        const command = event.input["command"];
+        if (typeof command !== "string")
+            return [];
+        return (0, bash_equivalents_js_1.equivalentCommands)(command).map((variant, i) => ({
+            ...event,
+            id: `${event.id}~${String(i + 1)}`,
+            label: `${event.label} — spelled: ${variant}`,
+            input: { ...event.input, command: variant },
+        }));
+    });
+}
 /**
  * Run a hook command against the disaster battery and report which events it blocks.
  * `hookCommand` is the exact shell the hook registers (e.g. `bash hooks/guard.sh` or

package/dist/scan-behavioral.d.ts

@@ -89,6 +89,16 @@ export interface SelectionOptions {
     readonly trials?: number;
     /** Selector model — defaults to Sonnet (a weaker model under-selects). */
     readonly model?: string;
+    /**
+     * Reasoning budget (`claude --effort`) for the selector, or undefined for the
+     * harness default. Present for {@link measureSelectionMatrix}, the ASSERTABLE
+     * test primitive, where the configuration a number came from has to be pinnable.
+     *
+     * Deliberately NOT exposed as an `audit` CLI flag: `audit` is a local report,
+     * not a reproducibility surface, and a flag nobody can act on is surface without
+     * a use. The audit probe therefore leaves this unset and runs at the default.
+     */
+    readonly effort?: string | number;
     /** Parallel runs across the prompts × trials grid (default 1). */
     readonly concurrency?: number;
     /** Which harness drives it (default `"claude-code"`; others report n/a). */