vigiles 25.0.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/eval-cache.d.ts

@@ -6,6 +6,13 @@ export type CacheMode = "off" | "read" | "readwrite";
 export interface CacheKeyInput {
     readonly task: string;
     readonly model: string;
+    /**
+     * Reasoning budget (`--effort`). Keyed for the same reason `model` is: it moves
+     * the output distribution, so a replay across effort levels would serve a result
+     * the caller did not ask for. `undefined` (the harness default) drops out of the
+     * hash via JSON, so entries recorded before effort existed stay valid.
+     */
+    readonly effort?: string | number;
     readonly tools: readonly string[];
     /** The resolved fixture + arm + plugin files written before the run. */
     readonly files: Record<string, string>;

package/dist/eval-lock.d.ts

@@ -33,6 +33,18 @@ export declare const DEFAULT_LOCK_DIR = ".vigiles/eval-locks";
 export interface EvalLockInputs {
     /** Model id used (folded in; a floating alias can't detect weight drift — warned). */
     readonly model: string;
+    /**
+     * Reasoning budget (`--effort`) the run was pinned to, or undefined for the
+     * harness default. Hashed because it steers the model — the criterion this
+     * interface already states — so a committed report recorded at one effort is
+     * STALE for a run at another. `undefined` is dropped by `JSON.stringify`, so
+     * locks committed before effort existed keep their hash and still replay.
+     *
+     * Caveat kept honest: "omitted" means the harness's own default, which is
+     * per-model and can move between builds — reproducible only modulo that, the
+     * same class of provenance caveat as `harnessVersion` below.
+     */
+    readonly effort?: string | number;
     /**
      * A hand-bumped behavior epoch the project owns (`.vigilesrc.json`
      * `eval.apiVersion`), bumped when a harness-side change YOU made (a CLAUDE.md
@@ -71,6 +83,13 @@ export interface EvalLock {
     readonly inputsHash: string;
     /** The model id the report was produced against (for the drift warning). */
     readonly model: string;
+    /**
+     * The effort the report was produced at, or undefined for the harness default
+     * (provenance; already in the hash). Recorded because the complaint that
+     * motivated effort support was not only that it could not be SET — it was that
+     * nothing in the run record said which effort produced the numbers.
+     */
+    readonly effort?: string | number;
     /** The harness version token at record time (provenance; already in the hash). */
     readonly harnessVersionKey: string;
     /** The behavior epoch at record time (provenance; already in the hash). */
@@ -142,6 +161,7 @@ export declare function buildLock(args: {
     readonly name: string;
     readonly inputsHash: string;
     readonly model: string;
+    readonly effort?: string | number;
     readonly harnessVersionKey: string;
     readonly evalApiVersion: number;
     readonly builtAt: string;

package/dist/eval.d.ts

@@ -46,6 +46,13 @@ export interface EvalArm {
      * use the eval-level model. See `research/eval-architecture.md` (model strategy).
      */
     readonly model?: string;
+    /**
+     * Reasoning budget for the run (`claude --effort`, e.g. `"low"` or an integer).
+     * Lives here beside `model` because it is part of the MEASUREMENT — it moves the
+     * output distribution, not the sample size — so it is hashed into the lock and
+     * the cache, and never read from an env var. Omit for the harness default.
+     */
+    readonly effort?: string | number;
 }
 /** Per-run resource use, parsed from the terminal `result` event (0 when absent). */
 export interface EvalUsage {
@@ -95,6 +102,13 @@ export interface EvalSpec<M extends Metrics> {
     readonly trials?: number;
     /** Model alias. Default "haiku". */
     readonly model?: string;
+    /**
+     * Reasoning budget for the run (`claude --effort`, e.g. `"low"` or an integer).
+     * Lives here beside `model` because it is part of the MEASUREMENT — it moves the
+     * output distribution, not the sample size — so it is hashed into the lock and
+     * the cache, and never read from an env var. Omit for the harness default.
+     */
+    readonly effort?: string | number;
     /** Tools the agent may use. Default: Read Edit Write Bash. */
     readonly allowedTools?: readonly string[];
     /** Per-run timeout ms. Default 240000. */
@@ -229,6 +243,19 @@ export interface AgentRunArgs {
     readonly task: string;
     readonly cwd: string;
     readonly model: string;
+    /**
+     * Reasoning-budget level for the run (`claude --effort`). Part of the
+     * MEASUREMENT, not a run knob: it changes the model's output distribution, not
+     * the sample size — so it lives on the spec next to `model` (never an env),
+     * and it is hashed into both the cache key and the eval lock. Deliberately
+     * `string | number` rather than a literal union: the binary accepts an alias
+     * map, is case-insensitive, and takes an integer budget, and its own valid set
+     * MOVED between builds (2.1.42 had no `xhigh`, 2.1.257 does) — a hard-coded
+     * union would reject a valid level after any upstream addition. A wrong value
+     * is caught at RUNTIME instead, by {@link effortRejection}, which is what the
+     * binary actually tells us. Omit for the harness default.
+     */
+    readonly effort?: string | number;
     readonly tools: readonly string[];
     readonly hasSettings: boolean;
     readonly pluginDir: string | undefined;
@@ -260,10 +287,74 @@ export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
  * regression to an always-merge would otherwise silently defeat ephemerality and
  * leak the host environment into an untrusted, model-driven run.
  */
-export declare function resolveSpawnEnv(a: Pick<AgentRunArgs, "env" | "replaceEnv">, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
-/** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
-export declare function spawnAgent(a: AgentRunArgs): Promise<RunOut>;
+export declare function resolveSpawnEnv(a: Pick<AgentRunArgs, "env" | "replaceEnv" | "effort">, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare function pinEffortEnv(env: NodeJS.ProcessEnv, effort: string | number | undefined): NodeJS.ProcessEnv;
+/**
+ * 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}.
+ */
+export declare function effortRejection(out: RunOut): string | 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.
+ */
+export declare function withEffortGuard(runner: AgentRunner): AgentRunner;
+/**
+ * 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`.
+ */
+export declare function buildAgentArgs(a: AgentRunArgs): string[];
+/**
+ * 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.
+ */
+export declare const spawnAgent: AgentRunner;
 /**
  * Run the eval: every arm × every trial against the real `claude` CLI, with the
  * metric computed per run and aggregated per arm. Requires `claude` on PATH and
@@ -320,6 +411,13 @@ export interface MeasureSpec {
     readonly trials?: number;
     /** Model alias. Default "sonnet" — measure on the model your users run. */
     readonly model?: string;
+    /**
+     * Reasoning budget for the run (`claude --effort`, e.g. `"low"` or an integer).
+     * Lives here beside `model` because it is part of the MEASUREMENT — it moves the
+     * output distribution, not the sample size — so it is hashed into the lock and
+     * the cache, and never read from an env var. Omit for the harness default.
+     */
+    readonly effort?: string | number;
     /** Tools the agent may use. */
     readonly allowedTools?: readonly string[];
     /** Per-run timeout ms. */
@@ -375,6 +473,13 @@ export interface ArmsMeasureSpec {
     readonly model?: string;
     readonly allowedTools?: readonly string[];
     readonly timeoutMs?: number;
+    /**
+     * Reasoning budget for the run (`claude --effort`, e.g. `"low"` or an integer).
+     * Lives here beside `model` because it is part of the MEASUREMENT — it moves the
+     * output distribution, not the sample size — so it is hashed into the lock and
+     * the cache, and never read from an env var. Omit for the harness default.
+     */
+    readonly effort?: string | number;
     readonly spacingSec?: number;
 }
 /** Per-arm {@link CheckReport}s — `arms[name].perCheck[i]` aligns across arms. */
@@ -471,6 +576,7 @@ export declare function runSkillSelectionTrial(args: {
     readonly runner: AgentRunner;
     readonly parse?: ModelOutputParser;
     readonly model: string;
+    readonly effort?: string | number;
     readonly tools?: readonly string[];
     readonly timeoutMs?: number;
     readonly fixture?: Record<string, string>;
@@ -658,6 +764,13 @@ export interface TriggerRateSpec {
      * 0.50 on haiku vs 0.90 on Sonnet). Override for a cheaper-but-pessimistic run.
      */
     readonly model?: string;
+    /**
+     * Reasoning budget for the run (`claude --effort`, e.g. `"low"` or an integer).
+     * Lives here beside `model` because it is part of the MEASUREMENT — it moves the
+     * output distribution, not the sample size — so it is hashed into the lock and
+     * the cache, and never read from an env var. Omit for the harness default.
+     */
+    readonly effort?: string | number;
     /**
      * Minimum model tier this eval may run on (haiku<sonnet<opus by family). The
      * run **fails** if the resolved `model` is weaker — trigger-rate under-measures