vigiles 25.0.0 → 26.0.0

package/dist/core/adopt.d.ts

@@ -23,6 +23,12 @@ export type AdoptTier = "structured" | "raw";
 export interface AdoptResult {
     /** Generated `.spec.ts` source (compiles back to ~the original file). */
     source: string;
+    /**
+     * Backticked paths that RESOLVED at adoption time and were emitted as verified
+     * `file()` refs. Empty when no `exists` predicate was supplied (the faithful,
+     * extract-nothing behaviour) or when nothing resolved.
+     */
+    adoptedRefs?: readonly string[];
     /**
      * `structured` = a clean `##`-headed file mapped 1:1 to sections (the diff is
      * just the canonical h1 + whitespace). `raw` = a heading-less or
@@ -48,6 +54,47 @@ export interface AdoptedSpec {
     maxSectionLines?: number;
     tier: AdoptTier;
 }
+/**
+ * Render a section as a template, turning every backticked path that RESOLVES
+ * TODAY into a verified `${file("…")}` reference.
+ *
+ * WHY THIS EXISTS. Adoption used to transcribe faithfully and extract NOTHING —
+ * `rules: {}`, every reference left as inert prose — on the stated grounds that
+ * cross-referencing is `strengthen`'s later job. An adopter measured what that
+ * trade actually costs (2026-08-28, a 51-skill monorepo): running
+ * `vigiles init --target=CLAUDE.md` turned the file into one opaque template with
+ * zero refs extracted, so "the price is paid immediately — the file becomes a
+ * build artifact, hand edits are blocked by a hook, every backtick is escaped —
+ * while the benefit is deferred until a human rewrites every reference by hand."
+ * The checker was never the problem: he hand-wrote two `file()` calls and compile
+ * correctly reported `[stale-file]`, exit 1. The ADOPTION PATH did not populate it,
+ * so nobody reached the value and the second step never happened.
+ *
+ * WHY RESOLVE-NOW IS THE RIGHT FILTER, and not a heuristic. The undecidable
+ * question is "is this OUR path or a path inside the third-party repo this
+ * document DESCRIBES?" — the same wall that made `doc-refs` default to off after
+ * scoring 0 true positives, and that the adopter hit independently (1560
+ * path-shaped strings in his corpus, 907 unresolvable, single-digit true
+ * positives after filtering; almost all the rest were paths in repos his skills
+ * merely describe). Asking instead "does it resolve HERE, right now?" sidesteps
+ * it: a described repo's path does not exist locally, so it is never emitted.
+ *
+ * The consequences are the ones adoption needs:
+ *  - ZERO new failures at adoption time — only already-green refs are emitted, so
+ *    `compile` cannot start red on a file that was fine a second earlier;
+ *  - value from the FIRST compile rather than after a manual pass — the ref goes
+ *    red exactly when the file moves, which is the entire point of marking it;
+ *  - a false emit is benign (an extra verified ref), while a false SKIP costs
+ *    only what the old behaviour already cost.
+ *
+ * Fence-awareness goes through the shared `fencedLineFlags` oracle, never a
+ * private toggle: a path inside a fenced block is example code, and hand-rolled
+ * fence state is the exact defect that oracle exists to make unrepresentable.
+ */
+export declare function refInterpolatedTemplate(content: string, exists: (p: string) => boolean): {
+    template: string;
+    refs: string[];
+};
 /**
  * Parse an instruction file's markdown into the faithful `instructionFile()` spec FIELDS.
  * The shared core of {@link adoptMarkdown} and the round-trip tests.
@@ -62,7 +109,9 @@ export declare function adoptToSpec(markdown: string, target: string): AdoptedSp
  * Convert an instruction file's markdown into a faithful `instructionFile()` spec source
  * (the deliverable `init` writes).
  */
-export declare function adoptMarkdown(markdown: string, target: string): AdoptResult;
+export declare function adoptMarkdown(markdown: string, target: string, opts?: {
+    readonly exists?: (p: string) => boolean;
+}): AdoptResult;
 export interface AdoptSurfaceResult {
     /** Generated `.spec.ts` source. */
     source: string;

package/dist/core/adopt.js

@@ -20,6 +20,7 @@
  * `strengthen`'s separate, later job; adoption is lossless transcription.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.refInterpolatedTemplate = refInterpolatedTemplate;
 exports.adoptToSpec = adoptToSpec;
 exports.adoptMarkdown = adoptMarkdown;
 exports.adoptSkill = adoptSkill;
@@ -107,28 +108,119 @@ function tsTemplate(s) {
         .replace(/\$\{/g, "\\${");
     return "`" + esc + "`";
 }
-function renderSpecSource(spec) {
+/**
+ * A backticked token that looks like a repo-relative path: contains a slash and
+ * no whitespace. Deliberately loose — the DECIDING filter is not the shape, it is
+ * whether the path RESOLVES (see {@link refInterpolatedTemplate}).
+ */
+const PATH_LIKE = /`([^`\s]+)`/g;
+/** Whether a backticked token may be adopted as a verified `file()` reference. */
+function adoptableRef(token, exists) {
+    // A path claim, not a symbol or a command: it has a separator.
+    if (!token.includes("/"))
+        return false;
+    // Someone else's world — a URL, an absolute path, a home path, an escape.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(token))
+        return false;
+    if (token.startsWith("/") || token.startsWith("~"))
+        return false;
+    if (token.includes(".."))
+        return false;
+    // 🔴 THE WHOLE DESIGN IS THIS LINE. Adoption emits a ref ONLY for a path that
+    // resolves in THIS repo right now.
+    return exists(token);
+}
+/**
+ * Render a section as a template, turning every backticked path that RESOLVES
+ * TODAY into a verified `${file("…")}` reference.
+ *
+ * WHY THIS EXISTS. Adoption used to transcribe faithfully and extract NOTHING —
+ * `rules: {}`, every reference left as inert prose — on the stated grounds that
+ * cross-referencing is `strengthen`'s later job. An adopter measured what that
+ * trade actually costs (2026-08-28, a 51-skill monorepo): running
+ * `vigiles init --target=CLAUDE.md` turned the file into one opaque template with
+ * zero refs extracted, so "the price is paid immediately — the file becomes a
+ * build artifact, hand edits are blocked by a hook, every backtick is escaped —
+ * while the benefit is deferred until a human rewrites every reference by hand."
+ * The checker was never the problem: he hand-wrote two `file()` calls and compile
+ * correctly reported `[stale-file]`, exit 1. The ADOPTION PATH did not populate it,
+ * so nobody reached the value and the second step never happened.
+ *
+ * WHY RESOLVE-NOW IS THE RIGHT FILTER, and not a heuristic. The undecidable
+ * question is "is this OUR path or a path inside the third-party repo this
+ * document DESCRIBES?" — the same wall that made `doc-refs` default to off after
+ * scoring 0 true positives, and that the adopter hit independently (1560
+ * path-shaped strings in his corpus, 907 unresolvable, single-digit true
+ * positives after filtering; almost all the rest were paths in repos his skills
+ * merely describe). Asking instead "does it resolve HERE, right now?" sidesteps
+ * it: a described repo's path does not exist locally, so it is never emitted.
+ *
+ * The consequences are the ones adoption needs:
+ *  - ZERO new failures at adoption time — only already-green refs are emitted, so
+ *    `compile` cannot start red on a file that was fine a second earlier;
+ *  - value from the FIRST compile rather than after a manual pass — the ref goes
+ *    red exactly when the file moves, which is the entire point of marking it;
+ *  - a false emit is benign (an extra verified ref), while a false SKIP costs
+ *    only what the old behaviour already cost.
+ *
+ * Fence-awareness goes through the shared `fencedLineFlags` oracle, never a
+ * private toggle: a path inside a fenced block is example code, and hand-rolled
+ * fence state is the exact defect that oracle exists to make unrepresentable.
+ */
+function refInterpolatedTemplate(content, exists) {
+    const fenced = (0, markdown_js_1.fencedLineFlags)(content);
+    const refs = [];
+    const rendered = content
+        .split("\n")
+        .map((line, i) => {
+        if (fenced[i])
+            return tsTemplate(line).slice(1, -1);
+        let out = "";
+        let last = 0;
+        for (const m of line.matchAll(PATH_LIKE)) {
+            const token = m[1];
+            if (!adoptableRef(token, exists))
+                continue;
+            out += tsTemplate(line.slice(last, m.index)).slice(1, -1);
+            out += "${file(" + JSON.stringify(token) + ")}";
+            refs.push(token);
+            last = m.index + m[0].length;
+        }
+        return out + tsTemplate(line.slice(last)).slice(1, -1);
+    })
+        .join("\n");
+    return { template: "`" + rendered + "`", refs };
+}
+function renderSpecSource(spec, exists) {
     const targetLine = spec.target !== "CLAUDE.md"
         ? `\n  target: ${JSON.stringify(spec.target)},`
         : "";
     const maxLine = spec.maxSectionLines !== undefined
         ? `\n  maxSectionLines: ${String(spec.maxSectionLines)},`
         : "";
+    const adopted = [];
     const entries = Object.entries(spec.sections)
-        .map(([key, content]) => `    ${JSON.stringify(key)}: ${tsTemplate(content)},`)
+        .map(([key, content]) => {
+        if (!exists)
+            return `    ${JSON.stringify(key)}: ${tsTemplate(content)},`;
+        const { template, refs } = refInterpolatedTemplate(content, exists);
+        adopted.push(...refs);
+        return `    ${JSON.stringify(key)}: ${template},`;
+    })
         .join("\n");
     const sectionsBlock = entries
         ? `\n  sections: {\n${entries}\n  },`
         : `\n  sections: {},`;
-    return `// Adopted from ${spec.target} by \`vigiles init\` — faithful by default.
+    const source = `// Adopted from ${spec.target} by \`vigiles init\` — faithful by default.
 // Each heading became a prose section; no rules were inferred. Run the
 // \`/strengthen\` skill to upgrade prose to verified enforce()/guard() rules.
-import { instructionFile } from "vigiles/spec";
+import { instructionFile${adopted.length ? ", file" : ""} } from "vigiles/spec";
 
 export default instructionFile({${targetLine}${maxLine}${sectionsBlock}
   rules: {},
 });
 `;
+    return { source, refs: adopted };
 }
 /**
  * Parse an instruction file's markdown into the faithful `instructionFile()` spec FIELDS.
@@ -192,12 +284,14 @@ function adoptToSpec(markdown, target) {
  * Convert an instruction file's markdown into a faithful `instructionFile()` spec source
  * (the deliverable `init` writes).
  */
-function adoptMarkdown(markdown, target) {
+function adoptMarkdown(markdown, target, opts = {}) {
     const spec = adoptToSpec(markdown, target);
+    const { source, refs } = renderSpecSource(spec, opts.exists);
     return {
-        source: renderSpecSource(spec),
+        source,
         tier: spec.tier,
         sectionCount: Object.keys(spec.sections).length,
+        adoptedRefs: refs,
     };
 }
 // Consumes the WHOLE leading frontmatter block (through its closing `---` and the

package/dist/core/bash-effects.d.ts

@@ -133,6 +133,17 @@ export interface NormalizedLeaf {
      */
     readonly chdir: string | null;
 }
+/**
+ * Known short↔long flag aliases. Deliberately small and operation-relevant:
+ * a caller always gates on the head (e.g. only treats `index-url` as supply-chain
+ * when the head is `pip`), so recording both forms unconditionally is safe.
+ */
+/** @internal — read by `bash-equivalents.ts` to generate shell-equivalent variants. */
+export declare const SHORT_TO_LONG: Readonly<Record<string, string>>;
+/** @internal — read by `bash-equivalents.ts` to generate shell-equivalent variants. */
+export declare const LONG_TO_SHORT: Readonly<Record<string, string>>;
+/** @internal — read by `bash-equivalents.ts` to generate shell-equivalent variants. */
+export declare const WRAPPER_HEADS: Set<string>;
 /**
  * Extract every simple command as a {@link NormalizedLeaf} — the operation-level
  * twin of {@link leafCommands}. Same AST-backed structural coverage (a leaf nested

package/dist/core/bash-effects.js

@@ -24,6 +24,7 @@
  * See `research/bash-effect-classification.md` for the full design rationale.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WRAPPER_HEADS = exports.LONG_TO_SHORT = exports.SHORT_TO_LONG = void 0;
 exports.classifyBashCommand = classifyBashCommand;
 exports.isReadOnlyBash = isReadOnlyBash;
 exports.leafCommands = leafCommands;
@@ -462,13 +463,15 @@ function leafCommands(command) {
  * a caller always gates on the head (e.g. only treats `index-url` as supply-chain
  * when the head is `pip`), so recording both forms unconditionally is safe.
  */
-const SHORT_TO_LONG = {
+/** @internal — read by `bash-equivalents.ts` to generate shell-equivalent variants. */
+exports.SHORT_TO_LONG = {
     f: "force",
     n: "no-verify",
     r: "recursive",
     i: "index-url",
 };
-const LONG_TO_SHORT = {
+/** @internal — read by `bash-equivalents.ts` to generate shell-equivalent variants. */
+exports.LONG_TO_SHORT = {
     force: "f",
     "no-verify": "n",
     recursive: "r",
@@ -480,17 +483,22 @@ const LONG_TO_SHORT = {
  * truly dynamic segment (command substitution, arithmetic, a non-HOME parameter)
  * — such a word can't be soundly reduced to a literal operation token.
  */
-function normalizeParts(parts) {
+function normalizeParts(parts, inDoubleQuotes = false, unescape = false) {
     if (!parts)
         return null;
     let out = "";
     for (const p of parts) {
         const t = sh.syntax.NodeType(p);
-        if (t === "Lit" || t === "SglQuoted") {
+        if (t === "Lit") {
+            out += unescape
+                ? unescapeLit(p.Value ?? "", inDoubleQuotes)
+                : (p.Value ?? "");
+        }
+        else if (t === "SglQuoted") {
             out += p.Value ?? "";
         }
         else if (t === "DblQuoted") {
-            const inner = normalizeParts(p.Parts);
+            const inner = normalizeParts(p.Parts, true, unescape);
             if (inner === null)
                 return null;
             out += inner;
@@ -508,6 +516,25 @@ function normalizeParts(parts) {
     }
     return out;
 }
+/**
+ * Resolve the backslashes a shell removes before it runs a word. mvdan-sh keeps
+ * them as written (`g\it` parses as `Lit("g\\it")`), yet `sh -c 'g\it --version'`
+ * runs git: outside quotes a backslash makes the next character literal and is
+ * itself dropped; inside double quotes it does so only before `$`, `` ` ``, `"`, `\\`
+ * and a newline. Without this, `g\it push --force` normalized to head `g\it` — a
+ * spelling the shell reads as the dangerous command and a `runs("git push")` guard
+ * did not (found 2026-09-02 by a reader, not by the battery, which shares this
+ * normalizer and so could not). Deliberately NOT expansion: `$VAR`, `eval`, `$(…)`
+ * and friends still return null one level up.
+ */
+function unescapeLit(raw, inDoubleQuotes) {
+    if (!raw.includes("\\"))
+        return raw;
+    const joined = raw.replace(/\\\n/g, ""); // `\<newline>` is a continuation: both go
+    return inDoubleQuotes
+        ? joined.replace(/\\([$`"\\])/g, "$1")
+        : joined.replace(/\\(.)/g, "$1");
+}
 /** Normalize a command head to its basename, stripping one leading backslash. */
 function normalizeHead(raw) {
     const unescaped = raw.startsWith("\\") ? raw.slice(1) : raw;
@@ -521,9 +548,9 @@ function buildFlags(args) {
         if (!name)
             return;
         flags.add(name);
-        if (name.length === 1 && SHORT_TO_LONG[name])
-            flags.add(SHORT_TO_LONG[name]);
-        const short = LONG_TO_SHORT[name];
+        if (name.length === 1 && exports.SHORT_TO_LONG[name])
+            flags.add(exports.SHORT_TO_LONG[name]);
+        const short = exports.LONG_TO_SHORT[name];
         if (short)
             flags.add(short);
     };
@@ -554,7 +581,8 @@ function buildFlags(args) {
 // `sudo timeout 5 rm -rf /` unwraps fully). A wrapper with no following command
 // (bare `env`, `env -i`) is preserved as-is, so the env-dump predicate still fires.
 // ---------------------------------------------------------------------------
-const WRAPPER_HEADS = new Set([
+/** @internal — read by `bash-equivalents.ts` to generate shell-equivalent variants. */
+exports.WRAPPER_HEADS = new Set([
     "env",
     "command",
     "nice",
@@ -677,7 +705,7 @@ function stripWrappers(argv) {
     let cur = argv;
     for (let guard = 0; guard < 8; guard++) {
         const head = cur[0];
-        if (head === undefined || !WRAPPER_HEADS.has(head))
+        if (head === undefined || !exports.WRAPPER_HEADS.has(head))
             break;
         const valueOpts = WRAPPER_VALUE_OPTS[head] ?? new Set();
         const chdirOpts = WRAPPER_CHDIR_OPTS[head] ?? new Set();
@@ -1069,12 +1097,24 @@ function collectAssigns(node) {
 function normalizeCallExpr(node, redirs) {
     if (sh.syntax.NodeType(node) !== "CallExpr" || !node.Args?.length)
         return null;
-    const headRaw = normalizeParts(node.Args[0]?.Parts);
+    const headRaw = normalizeParts(node.Args[0]?.Parts, false, true);
     if (headRaw === null)
         return null; // dynamic head → not normalizable
     const rawHead = normalizeHead(headRaw);
+    // Backslash resolution answers "what OPERATION is this" — the head and its
+    // FLAGS — and must not touch a PATH operand. The two need opposite answers for
+    // the SAME bytes: `sh` reads `--fo\rce` as `--force` (so a `{force:true}` guard
+    // that missed it was open), while `\\SERVER\SHARE\repo\SECRETS\x` is a real
+    // Windows UNC path whose backslashes a denylist must keep, or the write it
+    // names stops matching `secrets` and the guard allows it. A word starting `-`
+    // is never a path, so the split is decidable per word rather than guessed.
     const rawArgs = node.Args.slice(1)
-        .map((w) => normalizeParts(w.Parts))
+        .map((w) => {
+        const raw = normalizeParts(w.Parts);
+        if (raw === null || !raw.startsWith("-"))
+            return raw;
+        return normalizeParts(w.Parts, false, true) ?? raw;
+    })
         .filter((w) => w !== null);
     // Resolve through any command-wrapper (`env`/`command`/`sudo`/`timeout`/…) so
     // the leaf reflects the REAL operation, not the wrapper head.

package/dist/core/bash-equivalents.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Does `variant` perform every operation `seed` performs?
+ *
+ * Not string equality and not set equality: a wrapper adds a leaf (`sudo` itself),
+ * so the test is CONTAINMENT — every dangerous leaf of the seed still appears.
+ */
+export declare function sameOperation(seed: string, variant: string): boolean;
+/**
+ * Every shell-equivalent rewrite of `seed` the families can produce.
+ *
+ * 🔴 A candidate that does NOT satisfy {@link sameOperation} THROWS rather than
+ * being dropped. A silent drop would hide a generator bug behind a smaller
+ * corpus — the battery would quietly shrink and still look like it ran.
+ * A family that does not APPLY (no flag to quote) yields nothing, which is
+ * different from producing something wrong.
+ */
+export declare function equivalentCommands(seed: string): readonly string[];
+//# sourceMappingURL=bash-equivalents.d.ts.map

package/dist/core/bash-equivalents.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sameOperation = sameOperation;
+exports.equivalentCommands = equivalentCommands;
+/**
+ * Shell-EQUIVALENT rewrites of a dangerous command — the generator behind the
+ * metamorphic disaster battery.
+ *
+ * WHY THIS EXISTS. `DISASTER_CATALOG` is seven commands a human labelled
+ * dangerous, written one way each. Measured 2026-09-02: the compiled guard behind
+ * the published "2/7 → 7/7" headline blocked all seven seeds and only 8 of 30
+ * shell-equivalent rewrites of them — `git push "--force" origin main` (a quoted
+ * flag), `sudo git push --force`, `/usr/bin/git push --force`. The number was
+ * true and it was measured on the only forms anyone had written down.
+ *
+ * WHY A GENERATOR AND NOT MORE HAND-WRITTEN ROWS. Adding rows by hand closes the
+ * forms you thought of, which is the same bounded set that produced the gap. The
+ * escape space is not enumerable by memory.
+ *
+ * WHY THIS NEEDS NO ORACLE — the part that makes it sound rather than clever.
+ * Generating a NEW dangerous command would need a human to label it. This
+ * generates only REWRITES of an already-labelled one, so:
+ *
+ *   dangerous  ← inherited from the seed a human labelled
+ *   same thing ← decided by `leafCommandsNormalized`, our own normalizer
+ *
+ * Neither half is a new judgement. This is metamorphic testing (Chen et al.,
+ * 1998): with no oracle for a fresh input, assert instead that a
+ * semantics-preserving transform does not change the verdict.
+ *
+ * WHERE IT STOPS, and why the boundary is not a policy choice. The transform
+ * families are exactly the ones the normalizer collapses. `eval`, `sh -c`, a
+ * `$VAR` head, base64 — the normalizer returns null for those, so a variant
+ * built from them CANNOT pass the self-check and is never emitted. That is the
+ * correct boundary: a guard built on `runs()` genuinely cannot see through
+ * `eval "$(echo … | base64 -d)"`, so emitting it would call a correct guard
+ * broken — the crying-wolf failure that gets a check switched off.
+ */
+const bash_effects_js_1 = require("./bash-effects.js");
+/** The operation a leaf performs, ignoring how it was spelled. */
+function operationKey(leaf) {
+    return JSON.stringify([
+        leaf.head,
+        leaf.args.filter((a) => a !== "" && !a.startsWith("-")),
+        [...leaf.flags].sort(),
+    ]);
+}
+/**
+ * Does `variant` perform every operation `seed` performs?
+ *
+ * Not string equality and not set equality: a wrapper adds a leaf (`sudo` itself),
+ * so the test is CONTAINMENT — every dangerous leaf of the seed still appears.
+ */
+function sameOperation(seed, variant) {
+    const a = (0, bash_effects_js_1.leafCommandsNormalized)(seed);
+    const b = (0, bash_effects_js_1.leafCommandsNormalized)(variant);
+    if (a.length === 0 || b.length === 0)
+        return false;
+    const keys = new Set(b.map(operationKey));
+    return a.every((leaf) => keys.has(operationKey(leaf)));
+}
+/** Wrappers that pass a command through unchanged, one representative form each. */
+const WRAPPER_PREFIXES = [...bash_effects_js_1.WRAPPER_HEADS]
+    .filter((w) => w !== "xargs" && w !== "nohup")
+    .map((w) => w === "timeout" ? "timeout 30" : w === "nice" ? "nice -n 5" : w);
+const FAMILIES = [
+    {
+        name: "quoted flag",
+        // `getLiteral` returns null for a quoted word and `leafCommands` filters
+        // nulls, so this is the family that made a flag VANISH from argv.
+        rewrite: (c) => [...c.matchAll(/(?<=\s)(--?[A-Za-z][\w-]*)(?=\s|$)/g)].flatMap((m) => [
+            c.replace(m[1], `"${m[1]}"`),
+            c.replace(m[1], `'${m[1]}'`),
+        ]),
+    },
+    {
+        name: "flag alias",
+        rewrite: (c) => {
+            const out = [];
+            for (const [long, short] of Object.entries(bash_effects_js_1.LONG_TO_SHORT))
+                if (c.includes(`--${long}`))
+                    out.push(c.replace(`--${long}`, `-${short}`));
+            for (const [short, long] of Object.entries(bash_effects_js_1.SHORT_TO_LONG)) {
+                const re = new RegExp(`(?<=\\s)-${short}(?=\\s|$)`);
+                if (re.test(c))
+                    out.push(c.replace(re, `--${long}`));
+            }
+            return out;
+        },
+    },
+    {
+        name: "absolute or escaped head",
+        rewrite: (c) => {
+            const head = c.trimStart().split(/\s+/)[0];
+            if (!head || head.includes("/") || head.startsWith("\\"))
+                return [];
+            const rest = c.trimStart().slice(head.length);
+            return [
+                `/usr/bin/${head}${rest}`,
+                `/bin/${head}${rest}`,
+                `\\${head}${rest}`,
+            ];
+        },
+    },
+    {
+        name: "wrapper prefix",
+        rewrite: (c) => WRAPPER_PREFIXES.map((w) => `${w} ${c.trimStart()}`),
+    },
+    // The four families below are the shell's OWN obfuscations — what promptfoo's
+    // base64/leetspeak strategies are for a model, these are for `sh`: the shell
+    // itself decodes them, so they pass the equivalence check, and a guard that
+    // matches the source string (a grep, a substring) does not see them.
+    {
+        // `g""it`, `"git"`, `gi"t"` — a quote pair inside or around a word is removed
+        // by the shell before the word runs; a substring guard sees the quotes.
+        name: "quoted head",
+        rewrite: (c) => {
+            const { head, rest } = splitHead(c);
+            if (!head || !/^[A-Za-z][\w.-]*$/.test(head))
+                return [];
+            return [
+                `${head.slice(0, 1)}""${head.slice(1)}${rest}`,
+                `"${head}"${rest}`,
+                `${head.slice(0, -1)}"${head.slice(-1)}"${rest}`,
+            ];
+        },
+    },
+    {
+        // `$'git'` — ANSI-C quoting; with no escape inside it is the plain word.
+        name: "ansi-c quoted head",
+        rewrite: (c) => {
+            const { head, rest } = splitHead(c);
+            if (!head || !/^[A-Za-z][\w.-]*$/.test(head))
+                return [];
+            return [`$'${head}'${rest}`];
+        },
+    },
+    {
+        // `g\it` — a backslash before an ordinary character is that character.
+        // Distinct from the leading `\git` in "absolute or escaped head": that one
+        // is the alias-bypass idiom people actually type; this one nobody types,
+        // which is exactly why a hand-written matcher never lists it.
+        name: "escaped character in head",
+        rewrite: (c) => {
+            const { head, rest } = splitHead(c);
+            if (!head || !/^[A-Za-z]{2,}[\w.-]*$/.test(head))
+                return [];
+            return [`${head.slice(0, 1)}\\${head.slice(1)}${rest}`];
+        },
+    },
+    {
+        // `git   push    --force` / `git<TAB>push<TAB>--force` — any run of blanks
+        // between words is one separator to the shell; blanks inside quotes are kept.
+        name: "whitespace between words",
+        rewrite: (c) => [joinWords(c, "   "), joinWords(c, "\t")],
+    },
+    {
+        // A leading `NAME=value` is an ENVIRONMENT ASSIGNMENT scoped to this one
+        // command, not an argument to it: the shell strips the assignments and runs
+        // what follows, so `FOO=1 git push --force` IS `git push --force`. Named by
+        // an adopter (2026-08-28) as a form their own guard's tests did not cover.
+        //
+        // Our compiled guard already blocked it — `runs()` reads the parsed leaf, so
+        // the assignments were never in its way. A guard that greps the command
+        // STRING has no such luck, and that is who the battery exists for.
+        name: "env assignment prefix",
+        rewrite: (c) => {
+            const cmd = c.trimStart();
+            return [`FOO=1 ${cmd}`, `GIT_TERMINAL_PROMPT=0 LC_ALL=C ${cmd}`];
+        },
+    },
+];
+/** The first word of a command and everything after it, leading blanks dropped. */
+function splitHead(cmd) {
+    const trimmed = cmd.trimStart();
+    const head = trimmed.split(/\s+/)[0] ?? "";
+    return { head, rest: trimmed.slice(head.length) };
+}
+/**
+ * Replace every run of blanks OUTSIDE quotes with `sep`. Quote-aware by hand
+ * because the point is to re-spell the SOURCE; a run inside `'skip hooks'` is
+ * data and must survive as written.
+ */
+function joinWords(cmd, sep) {
+    let out = "";
+    let quote = null;
+    let i = 0;
+    const src = cmd.trim();
+    while (i < src.length) {
+        const ch = src[i] ?? "";
+        if (quote) {
+            out += ch;
+            if (ch === quote)
+                quote = null;
+            i++;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+            out += ch;
+            i++;
+        }
+        else if (ch === " " || ch === "\t") {
+            while (src[i] === " " || src[i] === "\t")
+                i++;
+            out += sep;
+        }
+        else {
+            out += ch;
+            i++;
+        }
+    }
+    return out;
+}
+/**
+ * Every shell-equivalent rewrite of `seed` the families can produce.
+ *
+ * 🔴 A candidate that does NOT satisfy {@link sameOperation} THROWS rather than
+ * being dropped. A silent drop would hide a generator bug behind a smaller
+ * corpus — the battery would quietly shrink and still look like it ran.
+ * A family that does not APPLY (no flag to quote) yields nothing, which is
+ * different from producing something wrong.
+ */
+function equivalentCommands(seed) {
+    const out = new Set();
+    for (const family of FAMILIES) {
+        for (const candidate of family.rewrite(seed)) {
+            if (candidate === seed)
+                continue;
+            if (!sameOperation(seed, candidate)) {
+                throw new Error(`bash-equivalents: family "${family.name}" produced a NON-equivalent ` +
+                    `rewrite of ${JSON.stringify(seed)}: ${JSON.stringify(candidate)}. ` +
+                    `A variant that changes the operation would blame a correct guard.`);
+            }
+            out.add(candidate);
+        }
+    }
+    return [...out];
+}
+//# sourceMappingURL=bash-equivalents.js.map

package/dist/core/coverage.d.ts

@@ -35,11 +35,11 @@ export declare function readNpmScripts(basePath: string): string[];
  * Collect commands documented in specs by loading spec source files directly.
  * Reads the structured `commands` field — no markdown parsing.
  */
-export declare function collectDocumentedCommands(basePath: string, specs?: ClaudeSpec[]): Set<string>;
+export declare function collectDocumentedCommands(basePath: string, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): Set<string>;
 /**
  * Compute script coverage: what % of npm scripts are documented in specs.
  */
-export declare function computeScriptCoverage(basePath: string, threshold?: number, specs?: ClaudeSpec[]): CoverageMetric;
+export declare function computeScriptCoverage(basePath: string, threshold: number | undefined, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): CoverageMetric;
 /**
  * Compute linter rule coverage from pre-computed totals.
  * The actual linter scanning is done by the existing discover() in cli.ts.
@@ -48,7 +48,7 @@ export declare function computeLinterRuleCoverage(enabled: number, documented: n
 /**
  * Check all coverage metrics against thresholds.
  */
-export declare function checkCoverage(basePath: string, thresholds: CoverageThresholds, linterEnabled: number, linterDocumented: number, specs?: ClaudeSpec[]): CoverageReport;
+export declare function checkCoverage(basePath: string, thresholds: CoverageThresholds, linterEnabled: number, linterDocumented: number, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): CoverageReport;
 /**
  * Format coverage report as human-readable text.
  */