vigiles 25.1.0 → 26.0.0

package/dist/core/coverage.js

@@ -36,7 +36,7 @@ function readNpmScripts(basePath) {
  * Collect commands documented in specs by loading spec source files directly.
  * Reads the structured `commands` field — no markdown parsing.
  */
-function collectDocumentedCommands(basePath, specs) {
+function collectDocumentedCommands(basePath, specs, ignore) {
     const commands = new Set();
     if (specs) {
         for (const spec of specs) {
@@ -50,8 +50,12 @@ function collectDocumentedCommands(basePath, specs) {
     // Fallback: scan compiled markdown for spec file references, then
     // load the compiled JS spec from dist/. If that fails, try to
     // extract commands from the compiled output (last resort).
+    // `ignore` is the repo's ExcludeSet string face (src/exclude.ts): the floor
+    // plus `.vigilesrc.json#exclude`, required so this fallback cannot walk a
+    // vendored corpus the repo excluded (#192). The CLI always passes `specs`,
+    // so this branch is reached by the library path and tests only.
     const mdFiles = (0, glob_1.globSync)("**/*.md", {
-        ignore: ["node_modules/**", "dist/**", ".vigiles/**"],
+        ignore: [...ignore],
         cwd: basePath,
     });
     for (const mdFile of mdFiles) {
@@ -92,9 +96,9 @@ function collectDocumentedCommands(basePath, specs) {
 /**
  * Compute script coverage: what % of npm scripts are documented in specs.
  */
-function computeScriptCoverage(basePath, threshold, specs) {
+function computeScriptCoverage(basePath, threshold, specs, ignore) {
     const allScripts = readNpmScripts(basePath);
-    const documented = collectDocumentedCommands(basePath, specs);
+    const documented = collectDocumentedCommands(basePath, specs, ignore);
     const covered = [];
     const uncovered = [];
     for (const script of allScripts) {
@@ -146,13 +150,13 @@ function computeLinterRuleCoverage(enabled, documented, threshold) {
 /**
  * Check all coverage metrics against thresholds.
  */
-function checkCoverage(basePath, thresholds, linterEnabled, linterDocumented, specs) {
+function checkCoverage(basePath, thresholds, linterEnabled, linterDocumented, specs, ignore) {
     const metrics = [];
     // Linter rule coverage
     const linterMetric = computeLinterRuleCoverage(linterEnabled, linterDocumented, thresholds.linterRules);
     metrics.push(linterMetric);
     // Script coverage
-    const scriptMetric = computeScriptCoverage(basePath, thresholds.scripts, specs);
+    const scriptMetric = computeScriptCoverage(basePath, thresholds.scripts, specs, ignore);
     metrics.push(scriptMetric);
     const passing = metrics.every((m) => m.passing);
     return { metrics, passing };

package/dist/core/hook-program.js

@@ -489,7 +489,48 @@ function commandView(raw, root) {
         raw,
         runs(program, opts) {
             const tokens = program.split(/\s+/).filter(Boolean);
-            return leaves.some((argv) => runsSeq(argv, tokens) && (opts?.force ? hasForce(argv) : true));
+            // 🔴 READS RAW **AND** NORMALIZED ARGV — the same union `touches` already
+            // uses, and for the same reason. This matcher read only `leaves` (raw), so
+            // three ordinary rewrites walked past a guard that blocks the plain form.
+            // MEASURED 2026-09-02 on the shipped dogfood artifact behind the public
+            // 7/7 claim (`examples/harness/safe-bash-guard.mjs`):
+            //   git push --force origin main            exit 2  blocked
+            //   git push "--force" origin main          exit 0  ALLOWED
+            //   sudo git push --force origin main       exit 0  ALLOWED
+            //   /usr/bin/git push --force origin main   exit 0  ALLOWED
+            // Across 30 shell-equivalent variants of the seven catalog seeds the guard
+            // blocked 8. The seeds were 7/7 — the number was true and measured on the
+            // only forms anyone had written down.
+            //
+            // The quoting case is the sharpest: `getLiteral` (bash-effects) returns
+            // null for a quoted word, and `leafCommands` FILTERS nulls, so
+            // `git push "--force" origin main` arrives as [git, push, origin, main] —
+            // a NON-force push. The force check was answering correctly about an argv
+            // that had already lost the flag.
+            //
+            // Force is asked of the NORMALIZED leaf via `hasFlag`, not by re-scanning
+            // strings: short clusters are already split (`-rf`→r,f) and each flag is
+            // recorded in both short and long form, so `-f` and `--force` are one
+            // question. The raw half stays because it is what an exact-literal match
+            // is for; neither half alone is enough, which is exactly what the comment
+            // on `touches` says about its own union.
+            const rawHit = leaves.some((argv) => runsSeq(argv, tokens) && (opts?.force ? hasForce(argv) : true));
+            if (rawHit)
+                return true;
+            // A FLAG named in the pattern is asked of `hasFlag`, not matched as a
+            // literal token. The normalized leaf already records every flag in BOTH
+            // short and long form, so `runs("git commit --no-verify")` also catches
+            // `git commit -n` — which the literal path cannot, because `-n` is simply
+            // a different string. Found by the generated battery on its first real
+            // run: 72/73, and the one miss was exactly this
+            // (`git commit -n -m 'skip hooks'`). The `{force:true}` option exists
+            // because force needed this for `-f`; every other flag needed it too and
+            // nobody noticed, since nobody wrote the short form down by hand.
+            const flagTokens = tokens.filter((t) => t.startsWith("-"));
+            const plainTokens = tokens.filter((t) => !t.startsWith("-"));
+            return normalized.some((leaf) => runsSeq(leaf.argv, plainTokens) &&
+                flagTokens.every((t) => leaf.hasFlag(t.replace(/^-+/, ""))) &&
+                (opts?.force ? leaf.hasFlag("force", "f") : true));
         },
         isSideEffecting: () => (0, bash_effects_js_1.classifyBashCommand)(raw) === "side-effecting",
         // Both of these are DENYLIST matchers, so both break an undecidable verdict
@@ -532,7 +573,12 @@ function commandView(raw, root) {
         // normalized ones, and a gate built on both had a silent hole).
         writesTo: (prefixes) => matchedWriteTargets(prefixes).length > 0,
         writeTargets: matchedWriteTargets,
-        pipesToShell: () => leaves.some(isBareShellLeaf),
+        // Same union, same reason: `curl … | /bin/sh` and `curl … | sudo sh` are a
+        // pipe-to-shell, and a raw-only check misses both (`isBareShellLeaf` tests
+        // the head literally, and the normalizer is what reduces `/bin/sh`→`sh` and
+        // strips the wrapper).
+        pipesToShell: () => leaves.some(isBareShellLeaf) ||
+            normalized.some((leaf) => isBareShellLeaf(leaf.argv)),
     };
 }
 const tool = (name) => ({ tool: name });

package/dist/core/orphans.d.ts

@@ -32,8 +32,15 @@ export interface FindOrphansOptions {
      * or to your project's doc globs (e.g. `["wiki/**\/*.md"]`) to override.
      */
     readonly include?: readonly string[];
-    /** Glob patterns to exclude within the include scope. */
+    /** Glob patterns to exclude within the include scope (orphan CANDIDACY only). */
     readonly exclude?: readonly string[];
+    /**
+     * The repo-wide `.vigilesrc.json#exclude` (the ExcludeSet string face,
+     * src/exclude.ts). Applied to BOTH walks — candidates AND the reference scan —
+     * so an excluded corpus can neither be an orphan nor keep one alive (#192).
+     * The CLI always passes it; a direct library caller may omit it.
+     */
+    readonly repoExclude?: readonly string[];
     /**
      * Harnesses whose surface files (instruction file, `SKILL.md`, subagents,
      * commands) are load-bearing by location and thus never orphan CANDIDATES

package/dist/core/orphans.js

@@ -153,12 +153,18 @@ function findOrphanDocs(options = {}) {
     const basePath = options.basePath ?? process.cwd();
     const include = options.include ?? DEFAULT_INCLUDE;
     const userExclude = options.exclude ?? [];
-    const ignore = [...DEFAULT_IGNORE, ...userExclude];
+    // Two exclusions with two jobs (#192). `repoExclude` is the repo-wide
+    // `.vigilesrc.json#exclude` — a vendored corpus is neither an orphan
+    // CANDIDATE nor a SOURCE of references (a link from inside it must not keep a
+    // doc alive). The rule's own `exclude` only narrows candidacy: a doc kept out
+    // of the orphan list can still reference others. Union, never override.
+    const repoExclude = options.repoExclude ?? [];
+    const ignore = [...DEFAULT_IGNORE, ...repoExclude, ...userExclude];
     const layouts = options.layouts ?? [];
     const allDocs = collectDocs(basePath, include, ignore, layouts);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
-        ignore: [...DEFAULT_IGNORE],
+        ignore: [...DEFAULT_IGNORE, ...repoExclude],
     });
     const referencedBy = new Map();
     for (const mdPath of allMarkdown) {

package/dist/core/types.d.ts

@@ -409,12 +409,20 @@ export interface VigilesConfig {
     bundles?: "root" | "all";
     orphans?: OrphansConfig;
     /**
-     * Glob patterns of instruction/skill files to EXCLUDE from `lint` discovery
-     * (tsconfig-style, relative to the repo root). Use it for vendored or
-     * benchmark fixtures the repo's own lint shouldn't police — e.g.
-     * `["bench/**"]` so a third-party `CLAUDE.md` injected verbatim as a benchmark
-     * arm isn't held to `require-instructions-spec`. `node_modules`/`dist` are always
-     * excluded.
+     * Paths and globs the repo's own tooling does NOT police — vendored corpora,
+     * benchmark fixtures, frozen reproductions (tsconfig-style, relative to the
+     * repo root; a bare directory name such as `"bench"` excludes its subtree, as
+     * do `"bench/"` and `"bench/**"`). `node_modules`/`dist`/`.git`/`.vigiles` are
+     * always excluded.
+     *
+     * ONE filter, every pass (#192): `compile` does not load an excluded spec,
+     * `lint` does not discover an excluded instruction file, nested bundle, doc, or
+     * surface, `audit` does not read an excluded instruction file, and
+     * `test`/`eval` do not discover an excluded script. It filters DISCOVERY only:
+     * a path you name on the command line is still processed, and one line says
+     * which pattern it matched. The rule-level `orphans.exclude` and
+     * `untested-*` `exclude` NARROW their own rule further and never re-admit a
+     * path excluded here (union, not override). Parsed once in `src/exclude.ts`.
      */
     exclude?: readonly string[];
     /**

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/test.d.ts

@@ -60,7 +60,7 @@ export { experimental_emitTool, experimental_parseEmitted, experimental_assertEm
 export { loadHook } from "./load-hook.js";
 export { evalChecks, assertChecks, tool, toolWith, notTool, onlyTools, skill, output, hookFired, received, turns, wrote, didNotWrite, subagent, blocked, allowed, mcp, cost, latency, tokens, inputTokens, outputTokens, cacheTokens, } from "./check.js";
 export type { ArgMatcher, Check, CheckJSON, CheckResult, JudgeFn, } from "./check.js";
-export { DISASTER_CATALOG, verifyGuardrail, unblockedDisasters, assertBlocksDisasters, formatGuardrailReport, } from "./guardrail-check.js";
+export { DISASTER_CATALOG, verifyGuardrail, unblockedDisasters, assertBlocksDisasters, formatGuardrailReport, experimental_alternateSpellings, } from "./guardrail-check.js";
 export type { DisasterEvent, DisasterCategory, GuardrailResult, VerifyGuardrailOptions, } from "./guardrail-check.js";
 export * from "./tool-stub.js";
 export { runHarnessTest, runHarness, parseToolCalls, parseSubagents, parseResultEvent, parseOutput, parseHooks, decideSandbox, specTrusted, sandboxAvailable, } from "./harness-test.js";

package/dist/test.js

@@ -66,8 +66,8 @@ 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.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.parseHooks = exports.parseOutput = exports.parseResultEvent = exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.recordCheck = void 0;
-exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = void 0;
+exports.specTrusted = exports.decideSandbox = exports.parseHooks = exports.parseOutput = exports.parseResultEvent = exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.experimental_alternateSpellings = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.recordCheck = void 0;
+exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.sandboxAvailable = void 0;
 // --- reporting: how much did this script actually do? ---
 // `vigiles test` can otherwise see only an exit code, so a file that runs NOTHING
 // prints the same `✓` as one that ran and passed (measured 2026-08-08 on a file
@@ -152,6 +152,7 @@ Object.defineProperty(exports, "verifyGuardrail", { enumerable: true, get: funct
 Object.defineProperty(exports, "unblockedDisasters", { enumerable: true, get: function () { return guardrail_check_js_1.unblockedDisasters; } });
 Object.defineProperty(exports, "assertBlocksDisasters", { enumerable: true, get: function () { return guardrail_check_js_1.assertBlocksDisasters; } });
 Object.defineProperty(exports, "formatGuardrailReport", { enumerable: true, get: function () { return guardrail_check_js_1.formatGuardrailReport; } });
+Object.defineProperty(exports, "experimental_alternateSpellings", { enumerable: true, get: function () { return guardrail_check_js_1.experimental_alternateSpellings; } });
 // Tool stubs on PATH (rung R2): shadow a CLI tool with a recorded canned result.
 __exportStar(require("./tool-stub.js"), exports);
 // The assembled machine — AGNOSTIC SURFACE ONLY. The Claude-Code transport

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "25.1.0",
+  "version": "26.0.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",