vigiles 26.2.0 → 27.0.0

package/dist/core/bash-effects.js

@@ -32,11 +32,26 @@ exports.stripWrappers = stripWrappers;
 exports.leafCommandsNormalized = leafCommandsNormalized;
 exports.leafArgvSource = leafArgvSource;
 exports.commandWords = commandWords;
-// mvdan-sh is a CJS package (GopherJS build) with no bundled TypeScript types.
-// The project compiles to CommonJS (Node16, no "type":"module"), so plain
-// require() works and is the idiomatic pattern here (see linters.ts).
-const _sh = require("mvdan-sh");
-const sh = _sh;
+/**
+ * The parser is loaded ON FIRST PARSE, not at module load — `sh()` memoizes it.
+ *
+ * WHY, measured 2026-09-08 (Node 22.22.2, `tools/measure-hook-startup.mjs`):
+ * `require("mvdan-sh")` is a GopherJS build and costs ~100 ms on top of a 42 ms
+ * bare Node start. This module sits in the import graph of `core/hook-program.ts`
+ * (and `core/hook-providers.ts`), which the compiled-hook RUNTIME loads on EVERY
+ * matching tool call. Only a BASH predicate ever parses: `decideProgram` returns
+ * `allow()` before building a `commandView` when the tool is not Bash, so a file
+ * gate, an inject, a react or a stop gate never reaches this file's functions at
+ * all — and used to pay ~100 ms per tool call for a parser it never called.
+ *
+ * The deferral is CLEAN because the boundary is real, not a trick: every entry
+ * point here starts by parsing, so there is no path that touches `sh()` without
+ * needing the parser. A bash gate still pays, and that cost is the work it asked
+ * for. Do NOT hoist this back to a top-level `require` — `src/hook-runtime-graph.test.ts`
+ * asserts `mvdan-sh` is absent from a non-Bash decision's module graph.
+ */
+let _sh;
+const sh = () => (_sh ??= require("mvdan-sh"));
 // ---------------------------------------------------------------------------
 // Redirect operator codes from mvdan-sh (empirically confirmed via probe).
 // Op values:
@@ -234,7 +249,7 @@ function getLiteral(word) {
     const part = word.Parts[0];
     if (!part)
         return null;
-    if (sh.syntax.NodeType(part) === "Lit")
+    if (sh().syntax.NodeType(part) === "Lit")
         return part.Value ?? null;
     return null;
 }
@@ -245,7 +260,7 @@ function getLiteralDeep(word) {
     const p = word.Parts[0];
     if (!p)
         return null;
-    const t = sh.syntax.NodeType(p);
+    const t = sh().syntax.NodeType(p);
     if (t === "Lit")
         return p.Value ?? null;
     if (t === "DblQuoted") {
@@ -253,7 +268,7 @@ function getLiteralDeep(word) {
         if (!inner.Parts || inner.Parts.length !== 1)
             return null;
         const ip = inner.Parts[0];
-        if (!ip || sh.syntax.NodeType(ip) !== "Lit")
+        if (!ip || sh().syntax.NodeType(ip) !== "Lit")
             return null;
         return ip.Value ?? null;
     }
@@ -346,7 +361,7 @@ function classifyStmt(stmt) {
 }
 /** Classify a Cmd node (the typed command inside a Stmt). */
 function classifyCmd(cmd) {
-    const t = sh.syntax.NodeType(cmd);
+    const t = sh().syntax.NodeType(cmd);
     switch (t) {
         case "CallExpr":
             return classifyCall(cmd);
@@ -386,10 +401,10 @@ function classifyStmtList(stmts) {
 /** Returns true if the AST contains a ProcSubst node anywhere. */
 function hasProcSubst(root) {
     let found = false;
-    sh.syntax.Walk(root, (node) => {
+    sh().syntax.Walk(root, (node) => {
         if (found)
             return false;
-        if (sh.syntax.NodeType(node) === "ProcSubst") {
+        if (sh().syntax.NodeType(node) === "ProcSubst") {
             found = true;
             return false;
         }
@@ -411,7 +426,7 @@ function hasProcSubst(root) {
 function classifyBashCommand(command) {
     let file;
     try {
-        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+        file = sh().syntax.NewParser().Parse(command, "cmd.sh");
     }
     catch {
         // mvdan-sh throws a Go error object (not an Error instance) on parse failure.
@@ -443,14 +458,14 @@ function isReadOnlyBash(command) {
 function leafCommands(command) {
     let file;
     try {
-        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+        file = sh().syntax.NewParser().Parse(command, "cmd.sh");
     }
     catch {
         return [];
     }
     const out = [];
-    sh.syntax.Walk(file, (node) => {
-        if (sh.syntax.NodeType(node) === "CallExpr" && node.Args) {
+    sh().syntax.Walk(file, (node) => {
+        if (sh().syntax.NodeType(node) === "CallExpr" && node.Args) {
             const argv = node.Args.map((w) => getLiteral(w)).filter((s) => s !== null);
             if (argv.length > 0)
                 out.push(argv);
@@ -489,7 +504,7 @@ function normalizeParts(parts, inDoubleQuotes = false, unescape = false) {
         return null;
     let out = "";
     for (const p of parts) {
-        const t = sh.syntax.NodeType(p);
+        const t = sh().syntax.NodeType(p);
         if (t === "Lit") {
             out += unescape
                 ? unescapeLit(p.Value ?? "", inDoubleQuotes)
@@ -782,14 +797,14 @@ function stripWrappers(argv) {
 function leafCommandsNormalized(command) {
     let file;
     try {
-        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+        file = sh().syntax.NewParser().Parse(command, "cmd.sh");
     }
     catch {
         return [];
     }
     const out = [];
-    sh.syntax.Walk(file, (node) => {
-        if (sh.syntax.NodeType(node) !== "Stmt" || !node.Cmd)
+    sh().syntax.Walk(file, (node) => {
+        if (sh().syntax.NodeType(node) !== "Stmt" || !node.Cmd)
             return true;
         const leaf = normalizeCallExpr(node.Cmd, node.Redirs ?? []);
         if (leaf)
@@ -815,7 +830,7 @@ function sourceParts(parts) {
         return null;
     let out = "";
     for (const p of parts) {
-        const t = sh.syntax.NodeType(p);
+        const t = sh().syntax.NodeType(p);
         if (t === "Lit" || t === "SglQuoted") {
             out += p.Value ?? "";
         }
@@ -880,7 +895,7 @@ function sourceParts(parts) {
 function leafArgvSource(command) {
     let file;
     try {
-        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+        file = sh().syntax.NewParser().Parse(command, "cmd.sh");
     }
     catch {
         return [];
@@ -913,7 +928,7 @@ function leafArgvSource(command) {
     const descend = (node) => {
         if (!node)
             return false;
-        switch (sh.syntax.NodeType(node)) {
+        switch (sh().syntax.NodeType(node)) {
             case "Stmt":
                 // `cmd &` runs in a background SUBSHELL, so a terminator inside it never
                 // reaches this shell (measured: `exit 0 & ./x.sh` runs `./x.sh`).
@@ -1002,14 +1017,14 @@ function terminates(call) {
  */
 function mayTerminate(node) {
     let found = false;
-    sh.syntax.Walk(node, (n) => {
+    sh().syntax.Walk(node, (n) => {
         if (found)
             return false;
         // A function BODY is not executed where it is written, so a `return`/`exit`
         // inside one says nothing about control here.
-        if (sh.syntax.NodeType(n) === "FuncDecl")
+        if (sh().syntax.NodeType(n) === "FuncDecl")
             return false;
-        if (sh.syntax.NodeType(n) === "CallExpr" && terminates(n))
+        if (sh().syntax.NodeType(n) === "CallExpr" && terminates(n))
             found = true;
         return !found;
     });
@@ -1105,7 +1120,7 @@ function collectAssigns(node) {
  * wraps it) to a {@link NormalizedLeaf}, or null if it isn't one / has a dynamic head.
  */
 function normalizeCallExpr(node, redirs) {
-    if (sh.syntax.NodeType(node) !== "CallExpr" || !node.Args?.length)
+    if (sh().syntax.NodeType(node) !== "CallExpr" || !node.Args?.length)
         return null;
     const headRaw = normalizeParts(node.Args[0]?.Parts, false, true);
     if (headRaw === null)
@@ -1249,14 +1264,14 @@ function commandWords(command) {
 function commandWordsAt(command, depth) {
     let file;
     try {
-        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+        file = sh().syntax.NewParser().Parse(command, "cmd.sh");
     }
     catch {
         return null;
     }
     const out = [];
-    sh.syntax.Walk(file, (node) => {
-        if (sh.syntax.NodeType(node) === "CallExpr" && node.Args?.length)
+    sh().syntax.Walk(file, (node) => {
+        if (sh().syntax.NodeType(node) === "CallExpr" && node.Args?.length)
             fileOperandsOf(node.Args, depth, out);
         return true;
     });

package/dist/core/compile.d.ts

@@ -1,9 +1,3 @@
-/**
- * vigiles v2 — Compiler: spec → markdown.
- *
- * Reads .spec.ts files, validates references, and produces
- * markdown instruction files with integrity hashes.
- */
 import type { ClaudeSpec, SkillSpec, AgentSpec, Railway } from "./spec.js";
 import type { LinterCheckResult } from "./linters.js";
 import type { HarnessDialect } from "./dialect.js";

package/dist/core/compile.js

@@ -1,10 +1,4 @@
 "use strict";
-/**
- * vigiles v2 — Compiler: spec → markdown.
- *
- * Reads .spec.ts files, validates references, and produces
- * markdown instruction files with integrity hashes.
- */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -27,6 +21,10 @@ exports.validateRailway = validateRailway;
 exports.compileRailway = compileRailway;
 exports.checkFileHash = checkFileHash;
 exports.adoptDiff = adoptDiff;
+/**
+ * Compiler: spec → markdown with SHA-256 hash, linter verification, reference validation; compileClaude/compileSkill/compileAgent (subagents: frontmatter + verified tool contract + body marks + result-contract Output section) + compileRailway/validateRailway (orchestrator command over flat workers; delegate-target resolution + bounded recovery) + purity-floor enforcement (purityViolations: a pure/bounded contract rejects a tool looser than its floor; absent tools = inherits-all = checked as the '*' wildcard, never trivially pure) + emits a <!-- vigiles:purity:LEVEL --> marker on a compiled agent OR skill (dangerously-unrestricted → the neutral runtime level unrestricted) so the runtime PreToolUse gate can read+enforce the declared floor (parseAgentPurity/parseSkillPurity → decidePurityGate). renderFragment/validateRefs also handle the effect() EffectRegion fragment — rendering its body wrapped in <!-- vigiles:effect -->…<!-- /vigiles:effect --> markers (inside the integrity hash) and recursing to verify inner file()/cmd() refs.
+ * Compile gates added 2026-06-20: a generous DEFAULT_MAX_SECTION_LINES=200 guard on every named prose section (claude + agent), overridable via maxSectionLines (TS types can't bound string length); agent disallowedTools verified via disallowedToolIssues (a close typo blocks nothing); a forked skill's output renders the SAME ## Output contract via renderOutputContract, and output without context:'fork' is the output-without-fork error; effect() in a skill body is the effect-in-skill error (effect() is a SUBAGENT primitive — a skill has no call→return region to scope; it declares a purity floor + context:fork instead)
+ */
 const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
 const js_yaml_1 = __importDefault(require("js-yaml"));
@@ -321,6 +319,12 @@ function compileRule(id, rule) {
 // an egregious dump (a whole essay pasted into one section / prose``).
 // Override per spec with `maxSectionLines`; `maxTokens` is the global backstop.
 const DEFAULT_MAX_SECTION_LINES = 200;
+// A key-files entry is a POINTER, not an essay: the prose about why a file is
+// shaped the way it is belongs in that file's own header, where it is read when
+// the file is opened. Calibrated against this repo on 2026-09-08 — 285 entries,
+// median 371 chars, longest 4782 — so 800 names the paragraphs without firing
+// on an ordinary one-line description.
+const DEFAULT_MAX_KEYFILE_CHARS = 800;
 function validateSectionContent(name, text, maxSectionLines) {
     const errors = [];
     const contentLines = text.split("\n");
@@ -392,6 +396,12 @@ function compileKeyFilesSection(spec, basePath) {
         const err = validateFileRef(filePath, basePath);
         if (err)
             errors.push(err);
+        if (desc.length > DEFAULT_MAX_KEYFILE_CHARS) {
+            errors.push({
+                type: "section-too-long",
+                message: `Key file "${filePath}" has a ${String(desc.length)}-character description (max ${String(DEFAULT_MAX_KEYFILE_CHARS)}). A key-files entry is a pointer; move the reasoning into that file's own header comment, where a reader meets it on opening the file.`,
+            });
+        }
     }
     return { lines: [lines.join("\n")], errors };
 }

package/dist/core/hook-program.d.ts

@@ -313,18 +313,12 @@ export interface BashToolEvent<N extends readonly NeedSpec[] = readonly Provider
 /** A hook program: where it fires + the pure decision. */
 export interface HookProgram<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly on: string;
-    readonly match: {
-        readonly tool: string;
-    };
     /** `enforce` (default) blocks on a `deny`; `observe` records + allows. */
     readonly mode?: HookMode;
     /** Declared context providers the trusted runtime gathers into `e.ctx`. */
     readonly needs?: N;
     readonly decide: (e: BashToolEvent<N>) => Decision;
 }
-export declare const tool: (name: string) => {
-    tool: string;
-};
 /**
  * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
  * Imported and CALLED as `experimental_defineHook` — do not alias the prefix away at

package/dist/core/hook-program.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nothing = exports.notice = exports.run = exports.inject = exports.tools = exports.HookCompileError = exports.tool = exports.ask = exports.deny = exports.allow = void 0;
+exports.nothing = exports.notice = exports.run = exports.inject = exports.tools = exports.HookCompileError = exports.ask = exports.deny = exports.allow = void 0;
 exports.matchesTool = matchesTool;
 exports.invalidToolPatterns = invalidToolPatterns;
 exports.gateAction = gateAction;
@@ -76,8 +76,20 @@ exports.isLoadPathRepairEvent = isLoadPathRepairEvent;
  */
 const bash_effects_js_1 = require("./bash-effects.js");
 const hash_js_1 = require("./hash.js");
-const toml_1 = require("@iarna/toml");
+/**
+ * `@iarna/toml` is required LAZILY, at the one call site that serializes a Codex
+ * TOML settings block — never at module load. MEASURED 2026-09-08 (Node 22.22.2,
+ * `tools/measure-hook-startup.mjs`): the top-level import cost 56 ms of a
+ * ~170 ms `require("dist/core/hook-program.js")`, and this module is on the hot
+ * path of `vigiles hook-runtime run-program`, which runs on EVERY matching tool
+ * call. A hook DECIDES; it never serializes a settings block, so it paid 56 ms
+ * per tool call for a compile-time dependency. Keep it a call-site require —
+ * hoisting it back to the top is the regression, and `src/hook-runtime-graph.test.ts`
+ * fails if `@iarna/toml` reappears in a decision's module graph.
+ */
+const stringifyToml = (value) => require("@iarna/toml").stringify(value);
 const hook_events_js_1 = require("./hook-events.js");
+const tool_contract_js_1 = require("./tool-contract.js");
 const merge_conflict_js_1 = require("./merge-conflict.js");
 const hook_providers_js_1 = require("./hook-providers.js");
 const hook_state_js_1 = require("./hook-state.js");
@@ -131,6 +143,8 @@ function matchesTool(tools, name) {
         return false;
     }
 }
+/** Regex metacharacters — an entry containing one is a PATTERN, not a name. */
+const REGEX_META = /[.*+?^${}()|[\]\\]/;
 /** Tool patterns that are not valid regexes — rejected at compile, see {@link matchesTool}. */
 function invalidToolPatterns(tools) {
     return tools.filter((t) => {
@@ -595,8 +609,6 @@ function commandView(raw, root) {
             normalized.some((leaf) => isBareShellLeaf(leaf.argv)),
     };
 }
-const tool = (name) => ({ tool: name });
-exports.tool = tool;
 /**
  * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
  * Imported and CALLED as `experimental_defineHook` — do not alias the prefix away at
@@ -624,7 +636,18 @@ function experimental_defineHook(p) {
 function decideProgram(program, rawEvent, ctx = {}, root = typeof rawEvent.cwd === "string"
     ? rawEvent.cwd
     : undefined) {
-    if (rawEvent.tool_name !== program.match.tool)
+    // A bash gate is Bash BY CONSTRUCTION — `BashToolEvent.tool` is the literal
+    // "Bash" and every one of the 34 call sites in both repos wrote
+    // `match: tool("Bash")`. The field carried no information and one real risk:
+    // `match: tool("Edit")` type-checked, compiled, wired a PreToolUse matcher
+    // `Edit`, fired on edits, built `commandView("")` from a missing
+    // `tool_input.command`, found every predicate false and returned allow() — a
+    // silently dead guard, which is the exact class the header above says this
+    // subsystem eliminates. Worse, the comparison was `!==` while every sibling
+    // role routes through `matchesTool`; that runtime/emit disagreement is the
+    // one MEASURED and fixed for reacts on 2026-08-12 (see the header), and it
+    // survived here on the flagship role. Removed 2026-09-08.
+    if (rawEvent.tool_name !== "Bash")
         return (0, exports.allow)();
     const command = typeof rawEvent.tool_input?.command === "string"
         ? rawEvent.tool_input.command
@@ -694,7 +717,8 @@ function hookRouting(hook) {
             return { on: hook.on };
         return { on: hook.on, matcher: hook.match.tools.join("|") };
     }
-    return { on: hook.on, matcher: hook.match.tool };
+    // Bash by construction — see decideProgram; the author no longer declares it.
+    return { on: hook.on, matcher: "Bash" };
 }
 /** Apply a harness's matcher style to the neutral `A|B` matcher join. */
 function styleMatcher(matcher, protocol) {
@@ -712,7 +736,7 @@ function renderSettingsBlock(on, matcher, gateCommand, format) {
         const entry = matcher === undefined
             ? { command: gateCommand }
             : { matcher, command: gateCommand };
-        return (0, toml_1.stringify)({ hooks: { [on]: [entry] } }).trim();
+        return stringifyToml({ hooks: { [on]: [entry] } }).trim();
     }
     const entry = matcher === undefined
         ? { hooks: [{ type: "command", command: gateCommand }] }
@@ -747,6 +771,23 @@ function compileHookProgram(source, hook, opts = {}) {
             throw new HookCompileError(`invalid tool matcher pattern(s): ${bad.join(", ")} — a tool matcher is a ` +
                 `regex (that is why "Edit|Write" works), so it must parse as one.`);
         }
+        // …and a VALID regex can still be a dead matcher. `tools("Edt")` parses
+        // fine, wires a matcher `Edt`, and the hook never fires — the same defect
+        // the event check below rejects, on the axis it did not cover.
+        //
+        // Only an entry with NO regex metacharacter is read as a literal tool NAME.
+        // A matcher IS a regex — `tools("mcp__github__.*")` is correct and must not
+        // be cross-referenced as a name — so the check is scoped to the spellings a
+        // typo actually produces. MCP names are skipped inside verifyToolContract
+        // itself (dialect.mcpToolPattern), so a fully-spelled server tool passes on
+        // both counts.
+        if (opts.dialect) {
+            const literal = hook.match.tools.filter((t) => !REGEX_META.test(t));
+            const badNames = (0, hook_events_js_1.authoringIssues)((0, tool_contract_js_1.verifyToolContract)(literal, opts.dialect));
+            if (badNames.length > 0) {
+                throw new HookCompileError(badNames[0].message);
+            }
+        }
     }
     // A hook registered under an event the harness never fires is dead — reject
     // it. AUTHORING is a closed world (you are writing this hook now, against the

package/dist/core/linters.d.ts

@@ -7,8 +7,17 @@
  *   Ktlint, Checkstyle, golangci-lint (CLI),
  *   Cedar (filesystem policies for AWS Bedrock AgentCore / Vectimus).
  *
- * This is the core moat — no other tool resolves rules across 11 catalog APIs
- * (10 linters + Cedar policy language) and checks config-enabled status.
+ * Across 11 catalog APIs (10 linters + Cedar policy language): a rule name is
+ * RESOLVED against the linter's own catalog rather than matched as a string, and
+ * its enabled state is read from the project's config.
+ *
+ * An exclusivity claim stood here ("the core moat — no other tool ..."). Removed
+ * 2026-09-08 for two independent reasons, noted rather than deleted silently so
+ * it is not restored as a wording change: it rested on a competitor matrix
+ * checked against DOCUMENTATION rather than a run (the same matrix put a false
+ * claim on the landing page, see tools/measure-validate-overlap.mjs), and this
+ * repository is public, where the `no-product-strategy-here` rule forbids
+ * competitive positioning outright. Describe the mechanism; let a reader compare.
  */
 import { editDistance } from "./edit-distance.js";
 export type { ConfigEnabledStatus, DiscoveredRules, LinterAdapter, LinterCapabilities, } from "./linter-adapter.js";

package/dist/core/linters.js

@@ -8,8 +8,17 @@
  *   Ktlint, Checkstyle, golangci-lint (CLI),
  *   Cedar (filesystem policies for AWS Bedrock AgentCore / Vectimus).
  *
- * This is the core moat — no other tool resolves rules across 11 catalog APIs
- * (10 linters + Cedar policy language) and checks config-enabled status.
+ * Across 11 catalog APIs (10 linters + Cedar policy language): a rule name is
+ * RESOLVED against the linter's own catalog rather than matched as a string, and
+ * its enabled state is read from the project's config.
+ *
+ * An exclusivity claim stood here ("the core moat — no other tool ..."). Removed
+ * 2026-09-08 for two independent reasons, noted rather than deleted silently so
+ * it is not restored as a wording change: it rested on a competitor matrix
+ * checked against DOCUMENTATION rather than a run (the same matrix put a false
+ * claim on the landing page, see tools/measure-validate-overlap.mjs), and this
+ * repository is public, where the `no-product-strategy-here` rule forbids
+ * competitive positioning outright. Describe the mechanism; let a reader compare.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LINTERS = exports.editDistance = void 0;
@@ -671,7 +680,7 @@ const stylelintConfigEnabled = createCachedChecker((basePath) => {
  * `enforce("ruff/...")` reported `enabled: "unknown"`; `touch dummy.py` in the
  * same repo flipped the identical rule to "enabled" and an out-of-select rule
  * to "disabled". The failure was SILENT because only "disabled" is ever
- * surfaced as a finding (src/core/compile.ts, src/cli.ts) — "unknown" reads as
+ * surfaced as a finding (src/core/compile.ts, src/cli-main.ts) — "unknown" reads as
  * clean, so a genuinely disabled rule passed its check.
  *
  * A directory works where a synthesized filename does not, including the case

package/dist/core/types.d.ts

@@ -83,7 +83,7 @@ export interface OrphansConfig {
  */
 export interface TestCoverageConfig {
     /** Globs of test files that count as coverage. */
-    testGlobs?: readonly string[];
+    include?: readonly string[];
     /** Extra ignore globs. */
     exclude?: readonly string[];
     /**
@@ -215,7 +215,9 @@ export interface RulesConfig {
      * Flag a hook command that references a script file which doesn't exist on
      * disk (with `${CLAUDE_PLUGIN_ROOT}` resolved) — the hook silently never runs.
      * FP-safe: skips unresolved `$VAR` paths, existence-guarded one-liners, and
-     * inline commands. Matches Anthropic's own `claude plugin validate`. Default
+     * inline commands. NOT covered by Anthropic's `claude plugin validate` — the
+     * "matches" claim here was measured false on 2026-09-08 (Claude Code 2.1.263;
+     * see docs/rules/hook-script-exists.md). Default
      * "warn"; "error" gates CI. Same detector as `scan` (hooks status "missing").
      */
     "hook-script-exists"?: RuleSeverity;

package/dist/coverage-evidence.d.ts

@@ -104,7 +104,7 @@ export declare function hookScriptRefs(manifestText: string | undefined, layout:
  */
 export declare function evidenceFor(_surface: CoverableSurface, _test: PreparedTest, colocated: boolean, configured?: boolean): CoverageEvidence | null;
 /**
- * The `{surface}` placeholder in a user's `testGlobs` — the ONE thing that makes
+ * The `{surface}` placeholder in a user's `include` — the ONE thing that makes
  * a centralized test layout expressible without weakening what coverage MEANS.
  *
  * The retired `declared` and `name-mentioned` tiers died because they could

package/dist/coverage-evidence.js

@@ -195,7 +195,7 @@ const SCRIPT_RE = (0, source_refs_js_1.scriptRefPattern)();
  * - As the full suffix `.eval.mjs` it was a MONEY HAZARD — `foo.eval.ts` fell
  *   into the free branch and would have spent real model calls on every push.
  * - As the bare INFIX `.eval.` it made a FALSE GRANT — `parser.eval.test.ts`,
- *   an ordinary deterministic test discovered by a `testGlobs` of
+ *   an ordinary deterministic test discovered by an `include` of
  *   `**\/*.test.ts`, was credited to the paid tier and dropped from the free
  *   one. `vigiles eval` globs `**\/*.eval.{mjs,cjs,js,mts,cts,ts}`, so that name
  *   is not discoverable by the eval runner at all: the surface was reported
@@ -286,7 +286,7 @@ function evidenceFor(_surface, _test, colocated, configured = false) {
     return configured ? "configured" : null;
 }
 /**
- * The `{surface}` placeholder in a user's `testGlobs` — the ONE thing that makes
+ * The `{surface}` placeholder in a user's `include` — the ONE thing that makes
  * a centralized test layout expressible without weakening what coverage MEANS.
  *
  * The retired `declared` and `name-mentioned` tiers died because they could

package/dist/exclude.js

@@ -3,78 +3,14 @@ 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.
+ * The ONE exclusion policy for every walk that polices the user's repository (#192) — the parsed `.vigilesrc.json#exclude` as an `ExcludeSet`, built ONCE where `loadConfig()` runs and taken as a REQUIRED parameter by every in-scope discovery (`findSpecs`, `findInstructionFiles`, `discoverNestedBundles`, `collectDocumentedRules`, `gatherInstructionFiles` in cli.ts; the string face handed to `findDocRefs`, `findOrphanDocs` (`repoExclude`), `findUntestedSurfaces`/`skillTestNudge`, `discoverScripts`, `computeScriptCoverage`).
+ * Two faces: `globIgnore` (an `IgnoreLike` keyed on the path's position relative to the REPO root, so a glob rooted below it — `vigiles lint some/dir` — still applies a root-relative exclude) and `ignore` (the normalized string list for pure core detectors that glob from the root).
+ * A bare directory name excludes its subtree, as tsconfig/ESLint do — measured 2026-09-03: glob's own string `ignore` treated `bench` and `bench/` as matching NOTHING while the minimatch helper in `discoverNestedBundles` accepted them, so the two walks that honoured `exclude` disagreed.
+ * The floor (node_modules/dist/.git/.vigiles) lives here, not per walk.
+ * `exclude` filters DISCOVERY only: an explicitly named path is processed and ONE line names the pattern it matched (rg/tsc semantics with ESLint's loudness; never prettier's silent 'all clean').
+ * Rule-level `orphans.exclude` / `untested-*` `exclude` NARROW (union with the floor), never override.
+ * The header carries the exception table — `validateGlobRef` (reference verification), `specReferencedElsewhere` (eject safety), `expandGlobs` (a typed argument), surface walks inside a bundle, and internal machinery — so the next reader does not 'fix' them.
+ * Enforced by the ESLint discovery guard (eslint.config.mjs: `globSync` without `ignore`, a literal in an ignore list, a raw `readdirSync` in cli.ts) and the source gate in exclude-cli.test.ts
  */
 const minimatch_1 = require("minimatch");
 const node_path_1 = require("node:path");

package/dist/hook-install.js

@@ -27,7 +27,13 @@ exports.serializeConfig = serializeConfig;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const toml_1 = require("@iarna/toml");
+/**
+ * Lazy for the same reason as in `core/hook-program.ts` — and this module is
+ * reached from the hook runtime through `hook-state-store.ts` (`normalizeHookRef`),
+ * so a top-level import here put `@iarna/toml` back into the graph of every hook
+ * decision even after that one was fixed. Measured 2026-09-08: 56 ms per spawn.
+ */
+const stringifyToml = (value) => require("@iarna/toml").stringify(value);
 /** The agnostic, committed home for hook SOURCE — one dir, cross-adapter. */
 exports.HOOKS_DIR = ".vigiles/hooks";
 /** The committed home for registered context-provider SOURCE (v2). */
@@ -152,7 +158,7 @@ function mergeHooksToml(existing, compiled, hookPath) {
 /** Serialize a merged config back to its on-disk text (with trailing newline). */
 function serializeConfig(merged, format) {
     return format === "toml"
-        ? (0, toml_1.stringify)(merged).trimEnd() + "\n"
+        ? stringifyToml(merged).trimEnd() + "\n"
         : JSON.stringify(merged, null, 2) + "\n";
 }
 //# sourceMappingURL=hook-install.js.map