vigiles 30.0.2 → 31.0.0

package/dist/core/refs.js

@@ -70,11 +70,11 @@ function symbolRefs(markdown) {
  * file must exist and define the named symbol. `basePath` is the directory the
  * paths resolve against (the instruction file's own directory).
  */
-function verifySymbolRefs(markdown, basePath) {
+async function verifySymbolRefs(markdown, basePath) {
     const errors = [];
     for (const ref of symbolRefs(markdown)) {
         const full = (0, node_path_1.resolve)(basePath, ref.file);
-        const support = (0, symbols_js_1.langForFile)(ref.file);
+        const support = await (0, symbols_js_1.langForFile)(ref.file);
         if (!(0, node_fs_1.existsSync)(full)) {
             errors.push({ ...ref, reason: `File not found: "${ref.file}"` });
         }
@@ -84,15 +84,12 @@ function verifySymbolRefs(markdown, basePath) {
                 reason: `Unsupported language for symbol check: "${ref.file}"`,
             });
         }
-        else if (support.kind === "grammar-missing") {
-            // NOT "unsupported": the language is one this tool parses, the optional grammar just is
-            // not installed here. Saying it the other way would report an un-run check as a verdict.
-            errors.push({
-                ...ref,
-                reason: `Symbol not checked: the ${support.id} grammar is not installed (npm i -D ${support.pkg})`,
-            });
+        else if (support.kind === "grammar-load-failed") {
+            // NOT "unsupported" and NOT "not defined": the language is one this tool parses, its
+            // grammar failed to load here. Either other wording would report an un-run check as a verdict.
+            errors.push({ ...ref, reason: (0, symbols_js_1.notCheckedReason)(support) });
         }
-        else if (!(0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol)) {
+        else if (!(await (0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol))) {
             errors.push({
                 ...ref,
                 reason: `"${ref.symbol}" is not defined in ${ref.file}`,
@@ -149,9 +146,9 @@ function unmarkedCodeRefs(markdown) {
  * code-shaped span that ought to be a mark. The shared detector behind both the
  * `vigiles refs` CLI and the PostToolUse refs-hook.
  */
-function collectRefIssues(markdown, basePath) {
+async function collectRefIssues(markdown, basePath) {
     const out = [];
-    for (const b of verifySymbolRefs(markdown, basePath)) {
+    for (const b of await verifySymbolRefs(markdown, basePath)) {
         out.push(`line ${String(b.line)}: ${b.reason}`);
     }
     for (const u of unmarkedCodeRefs(markdown)) {

package/dist/core/spec.js

@@ -1,4 +1,9 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles/spec` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-spec.api.md`, which
+// `npm run api:check` fails on.
 /**
  * vigiles v2 — Executable specification system.
  *

package/dist/core/symbols.d.ts

@@ -1,30 +1,33 @@
 import { Lang } from "@ast-grep/napi";
-/** Which optional grammars this process actually has. Exported so a report can say so. */
-export declare function installedGrammars(): ReadonlySet<string>;
-/** A language key accepted by ast-grep's `parse` (core enum or registered id). */
-type LangKey = Lang | string;
+import { type WasmLang } from "./tree-sitter-wasm.js";
+/** A language key: an `@ast-grep/napi` built-in, or one of the WASM grammars. */
+type LangKey = Lang | WasmLang;
 /**
  * Whether this file's language can be parsed HERE, and if not, which of the two reasons.
  *
- * 🔴 THE THREE CASES ARE SEPARATE MEMBERS BECAUSE THEY ARE SEPARATE FACTS. The previous
- * signature was `LangKey | null`, where `null` meant "extension not in the table" and callers
- * printed "Unsupported language for symbol check". Making the grammars optional would have
- * given that same `null` a second meaning — "the language IS ours, the package is simply not
- * installed" — and both callers would have kept printing the first sentence. That is the
- * failure this codebase exists to catch: a check that did not run, reported in the words of a
- * check that did. A union makes the compiler demand the distinction at every call site.
+ * 🔴 THE THREE CASES ARE SEPARATE MEMBERS BECAUSE THEY ARE SEPARATE FACTS. "Extension not in
+ * the table" and "the language IS ours but its grammar failed to load in this process" must not
+ * share one `null`: both callers would print the first sentence, and a check that did not run
+ * would read as a verdict. With WASM grammars shipped as a regular dependency there is no
+ * install or platform gap left, so `grammar-load-failed` should not happen — but if the runtime
+ * genuinely cannot load, the report carries the loader's own error text, never "not defined"
+ * and never an install instruction the user cannot act on.
  */
 export type LangSupport = {
     readonly kind: "ready";
     readonly lang: LangKey;
 } | {
-    readonly kind: "grammar-missing";
-    readonly id: string;
-    readonly pkg: string;
+    readonly kind: "grammar-load-failed";
+    readonly lang: WasmLang;
+    readonly error: string;
 } | {
     readonly kind: "unsupported";
 };
-export declare function langForFile(file: string): LangSupport;
+export declare function langForFile(file: string): Promise<LangSupport>;
+/** The one sentence both callers print for a symbol reference that could not be checked. */
+export declare function notCheckedReason(support: Extract<LangSupport, {
+    kind: "grammar-load-failed";
+}>): string;
 /** A symbol definition found in a file. */
 export interface SymbolDef {
     /** The defined identifier, e.g. "parseConfig". */
@@ -36,10 +39,13 @@ export interface SymbolDef {
     /** 1-based line of the definition. */
     readonly line: number;
 }
-/** Extract the symbols defined in a single file's source. */
-export declare function definedSymbols(code: string, lang: LangKey): SymbolDef[];
+/**
+ * Extract the symbols defined in a single file's source. Async because the Python / Ruby / Rust
+ * grammars are WebAssembly, whose instantiation is async; the napi languages resolve at once.
+ */
+export declare function definedSymbols(code: string, lang: LangKey): Promise<SymbolDef[]>;
 /** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
-export declare function definedSymbolsInFile(file: string): SymbolDef[];
+export declare function definedSymbolsInFile(file: string): Promise<SymbolDef[]>;
 /**
  * Whether `file` defines a top-level (or scoped) symbol named `name`. This is
  * the whole check for a file-qualified reference (`path#symbol`): we parse the
@@ -47,6 +53,6 @@ export declare function definedSymbolsInFile(file: string): SymbolDef[];
  * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
  * typed dynamic symbols resolve without running Sorbet / the TS compiler.
  */
-export declare function fileDefinesSymbol(file: string, name: string): boolean;
+export declare function fileDefinesSymbol(file: string, name: string): Promise<boolean>;
 export {};
 //# sourceMappingURL=symbols.d.ts.map

package/dist/core/symbols.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.installedGrammars = installedGrammars;
 exports.langForFile = langForFile;
+exports.notCheckedReason = notCheckedReason;
 exports.definedSymbols = definedSymbols;
 exports.definedSymbolsInFile = definedSymbolsInFile;
 exports.fileDefinesSymbol = fileDefinesSymbol;
@@ -21,60 +21,32 @@ exports.fileDefinesSymbol = fileDefinesSymbol;
  * delegated. Ambiguity (a name defined in several files) is reported, not guessed.
  */
 const node_fs_1 = require("node:fs");
-const node_module_1 = require("node:module");
+const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const napi_1 = require("@ast-grep/napi");
+const tree_sitter_wasm_js_1 = require("./tree-sitter-wasm.js");
 /**
- * The non-web grammars, as OPTIONAL packages keyed by the id ast-grep registers them under.
+ * Python, Ruby and Rust are parsed by WebAssembly builds of their tree-sitter grammars
+ * (`./tree-sitter-wasm.ts`); TypeScript, TSX, JavaScript and CSS by the grammars built into
+ * `@ast-grep/napi`.
  *
- * 🔴 WHY OPTIONAL, AND WHY IT IS NOT A PREFERENCE. These three are the only packages in this
- * dependency tree carrying a `postinstall` (measured 2026-09-20 with `npm query
- * ":attr(scripts, [postinstall])"`). Since pnpm 10 a consumer's install FAILS on an
- * unapproved lifecycle script, so every downstream project installing vigiles with pnpm got
- * `ERR_PNPM_IGNORED_BUILDS` and a non-zero exit — for grammars most of them never use. The web
- * grammars every user does need (TypeScript, TSX, JavaScript, CSS) are built into
- * `@ast-grep/napi` and cost nothing.
- *
- * They load through `createRequire` rather than `await import()` on purpose: the packages are
- * CommonJS (`"main": "index.js"`, no `exports`), so a synchronous require works and NOTHING in
- * this module's public surface has to become async. Measured, not assumed.
+ * 🔴 WHY NOT `@ast-grep/lang-*` ANY MORE (#257). Those native grammars were the only packages in
+ * the tree carrying a `postinstall`, and since pnpm 10 an unapproved dependency build script
+ * FAILS a consumer's install (`ERR_PNPM_IGNORED_BUILDS`) — for every `pnpm add vigiles`, whether
+ * or not the project has a single `.py` file. Making them optional peers stopped the failure but
+ * moved the cost onto the user: a `.py` reference then reported "grammar not installed" after an
+ * upgrade. The WASM grammars are a plain dependency with no install script and no native
+ * binary, so they are simply there. `src/package-install-scripts.e2e.test.ts` holds both halves
+ * against the packed tarball: no install script in the tree, and a `.py` lookup that works
+ * right after a default install.
  */
-const OPTIONAL_GRAMMARS = {
-    python: "@ast-grep/lang-python",
-    rust: "@ast-grep/lang-rust",
-    ruby: "@ast-grep/lang-ruby",
-};
-// Anchored on THIS module's own file, not on the consumer's project root. Under pnpm a
-// consumer's root does not contain our transitive packages at all — the same addressing
-// mistake that made every hook fail there — and these grammars are OUR optional dependencies,
-// so they resolve from where this file lives. `__filename` rather than `import.meta.url`
-// because this package compiles to CommonJS (`module: Node16`, `main: ./dist/test.js`).
-const require_ = (0, node_module_1.createRequire)(__filename);
-/** Registered grammar ids, populated on first use. `null` until then. */
-let loaded = null;
-function ensureRegistered() {
-    if (loaded)
-        return loaded;
-    const dynamic = {};
-    const present = new Set();
-    for (const [id, pkg] of Object.entries(OPTIONAL_GRAMMARS)) {
-        try {
-            dynamic[id] = require_(pkg);
-            present.add(id);
-        }
-        catch {
-            // Absent by design: an optional dependency the consumer did not install. The caller is
-            // told WHICH id is missing (see `langForFile`), so "not checked" never reads as "clean".
-        }
-    }
-    if (present.size > 0)
-        (0, napi_1.registerDynamicLanguage)(dynamic);
-    loaded = present;
-    return loaded;
-}
-/** Which optional grammars this process actually has. Exported so a report can say so. */
-function installedGrammars() {
-    return ensureRegistered();
+const WASM_LANGS = new Set([
+    "python",
+    "ruby",
+    "rust",
+]);
+function isWasmLang(key) {
+    return typeof key === "string" && WASM_LANGS.has(key);
 }
 const EXT_LANG = {
     ".ts": napi_1.Lang.TypeScript,
@@ -93,28 +65,26 @@ const EXT_LANG = {
     ".rb": "ruby",
     ".rbi": "ruby",
 };
-function langForFile(file) {
+async function langForFile(file) {
     const key = file.endsWith(".d.ts")
         ? napi_1.Lang.TypeScript
         : EXT_LANG[(0, node_path_1.extname)(file).toLowerCase()];
     if (key === undefined)
         return { kind: "unsupported" };
-    // A string key is one of the dynamically registered grammars; the enum members are built in.
-    if (typeof key === "string" && key in OPTIONAL_GRAMMARS) {
-        if (!ensureRegistered().has(key))
-            return { kind: "grammar-missing", id: key, pkg: OPTIONAL_GRAMMARS[key] };
+    if (isWasmLang(key)) {
+        // Lazy: the first .py/.rb/.rs reference starts the runtime; later ones hit the cache.
+        const error = await (0, tree_sitter_wasm_js_1.loadWasmGrammar)(key);
+        if (error !== null)
+            return { kind: "grammar-load-failed", lang: key, error };
     }
     return { kind: "ready", lang: key };
 }
-const ID_KINDS = new Set(["identifier", "constant", "type_identifier"]);
-const SCOPE_KINDS = new Set([
-    "class_declaration",
-    "class_definition",
-    "class",
-    "module",
-    "interface_declaration",
-    "enum_declaration",
-]);
+/** The one sentence both callers print for a symbol reference that could not be checked. */
+function notCheckedReason(support) {
+    return `Symbol not checked: the ${support.lang} grammar failed to load: ${support.error}`;
+}
+const ID_KINDS = new Set(tree_sitter_wasm_js_1.ID_KINDS);
+const SCOPE_KINDS = new Set(tree_sitter_wasm_js_1.SCOPE_KINDS);
 function recordNode(node, scope, out) {
     const line = node.range().start.line + 1;
     const nameNode = node.field("name");
@@ -128,9 +98,13 @@ function recordNode(node, scope, out) {
         out.push({ name: left.text(), kind: node.kind(), scope, line });
     }
 }
-/** Extract the symbols defined in a single file's source. */
-function definedSymbols(code, lang) {
-    ensureRegistered();
+/**
+ * Extract the symbols defined in a single file's source. Async because the Python / Ruby / Rust
+ * grammars are WebAssembly, whose instantiation is async; the napi languages resolve at once.
+ */
+async function definedSymbols(code, lang) {
+    if (isWasmLang(lang))
+        return (0, tree_sitter_wasm_js_1.wasmDefinedSymbols)(code, lang);
     const out = [];
     const walk = (node, scope) => {
         recordNode(node, scope, out);
@@ -143,17 +117,20 @@ function definedSymbols(code, lang) {
     return out;
 }
 /** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
-function definedSymbolsInFile(file) {
-    const support = langForFile(file);
+async function definedSymbolsInFile(file) {
+    const support = await langForFile(file);
     if (support.kind !== "ready")
         return [];
-    const lang = support.lang;
+    let code;
     try {
-        return definedSymbols((0, node_fs_1.readFileSync)(file, "utf-8"), lang);
+        code = await (0, promises_1.readFile)(file, "utf-8");
     }
     catch {
         return [];
     }
+    // Deliberately OUTSIDE the try: a parser failure is not an empty file. Swallowing it would
+    // turn "could not parse" into "is not defined" — a check that did not run, read as a verdict.
+    return definedSymbols(code, support.lang);
 }
 // A co-located declaration file that may declare symbols the source defines
 // dynamically (Sorbet `.rbi`, TypeScript `.d.ts`) — checked as a fallback so a
@@ -173,15 +150,15 @@ const DECL_SIBLING = {
  * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
  * typed dynamic symbols resolve without running Sorbet / the TS compiler.
  */
-function fileDefinesSymbol(file, name) {
-    if (definedSymbolsInFile(file).some((d) => d.name === name))
+async function fileDefinesSymbol(file, name) {
+    if ((await definedSymbolsInFile(file)).some((d) => d.name === name))
         return true;
     const ext = (0, node_path_1.extname)(file);
     const decl = DECL_SIBLING[ext];
     if (decl && !file.endsWith(decl)) {
         const sibling = file.slice(0, -ext.length) + decl;
         if ((0, node_fs_1.existsSync)(sibling) &&
-            definedSymbolsInFile(sibling).some((d) => d.name === name)) {
+            (await definedSymbolsInFile(sibling)).some((d) => d.name === name)) {
             return true;
         }
     }

package/dist/core/tree-sitter-wasm.d.ts

@@ -0,0 +1,24 @@
+/** The grammars this module parses, keyed by the id used in `tree-sitter-<id>.wasm`. */
+export type WasmLang = "python" | "ruby" | "rust";
+/** A definition found by the walk — the same shape `symbols.ts` exports as `SymbolDef`. */
+export interface WasmSymbolDef {
+    readonly name: string;
+    readonly kind: string;
+    readonly scope: string;
+    readonly line: number;
+}
+/**
+ * Node kinds that open a scope (their `name` becomes the `scope` of everything inside), and the
+ * kinds a `left` field must have to count as an assignment-style definition. ONE list for both
+ * walkers — the napi one in `symbols.ts` and the one below — so they cannot drift apart.
+ */
+export declare const SCOPE_KINDS: readonly string[];
+export declare const ID_KINDS: readonly string[];
+/**
+ * Load `lang`'s grammar once per process. Resolves to `null` on success, or the load error's own
+ * text — the caller reports it verbatim as "not checked", never as a missing symbol.
+ */
+export declare function loadWasmGrammar(lang: WasmLang): Promise<string | null>;
+/** Parse `code` and return its definitions. Rejects on a parse failure — never resolves []. */
+export declare function wasmDefinedSymbols(code: string, lang: WasmLang): Promise<WasmSymbolDef[]>;
+//# sourceMappingURL=tree-sitter-wasm.d.ts.map

package/dist/core/tree-sitter-wasm.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ID_KINDS = exports.SCOPE_KINDS = void 0;
+exports.loadWasmGrammar = loadWasmGrammar;
+exports.wasmDefinedSymbols = wasmDefinedSymbols;
+/**
+ * vigiles — the Python / Ruby / Rust parsers, as WebAssembly, on the main thread.
+ *
+ * WHY WASM (#257). These three used to be `@ast-grep/lang-*` native grammars, the only packages
+ * in our tree with a `postinstall`; since pnpm 10 an unapproved dependency build script fails a
+ * consumer's install (`ERR_PNPM_IGNORED_BUILDS`). `@vscode/tree-sitter-wasm` (Microsoft, MIT)
+ * ships prebuilt `.wasm` grammars plus the web-tree-sitter runtime with no dependencies and no
+ * install scripts: a plain dependency, nothing for the consumer to approve or add.
+ *
+ * WHY ASYNC, AND WHY NO WORKER. WebAssembly instantiation is async (`Parser.init()`,
+ * `Language.load()`). The first cut kept the symbol check synchronous behind a worker thread
+ * and `Atomics.wait`, because `compileClaude` & co. were public and synchronous. They are no
+ * longer public (same major), so the check is async end to end and this module simply awaits.
+ *
+ * LAZY. Nothing loads at import: the runtime is `import()`ed on the first `.py` / `.rb` / `.rs`
+ * reference, and each grammar is loaded once per process.
+ */
+const promises_1 = require("node:fs/promises");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+/**
+ * Node kinds that open a scope (their `name` becomes the `scope` of everything inside), and the
+ * kinds a `left` field must have to count as an assignment-style definition. ONE list for both
+ * walkers — the napi one in `symbols.ts` and the one below — so they cannot drift apart.
+ */
+exports.SCOPE_KINDS = [
+    "class_declaration",
+    "class_definition",
+    "class",
+    "module",
+    "interface_declaration",
+    "enum_declaration",
+];
+exports.ID_KINDS = [
+    "identifier",
+    "constant",
+    "type_identifier",
+];
+// Anchored on THIS file, like every other resolution in the package: under pnpm the consumer's
+// root does not contain our dependencies. `__filename` because the package compiles to CommonJS.
+const require_ = (0, node_module_1.createRequire)(__filename);
+const PKG = "@vscode/tree-sitter-wasm";
+let runtime = null;
+const languages = new Map();
+async function startRuntime() {
+    const entry = require_.resolve(PKG);
+    // The runtime is a UMD/CommonJS module: `import()` exposes it as `default`.
+    const mod = (await import(PKG));
+    const rt = mod.default ?? mod;
+    await rt.Parser.init();
+    return { rt, dir: (0, node_path_1.dirname)(entry), parser: new rt.Parser() };
+}
+async function language(id) {
+    runtime ??= startRuntime();
+    const { rt, dir } = await runtime;
+    let lang = languages.get(id);
+    if (lang === undefined) {
+        lang = (0, promises_1.readFile)((0, node_path_1.join)(dir, `tree-sitter-${id}.wasm`)).then((bytes) => rt.Language.load(bytes));
+        languages.set(id, lang);
+    }
+    return lang;
+}
+/** First line only: Node appends a multi-line "Require stack:" that would split one finding. */
+function firstLine(e) {
+    const text = e instanceof Error ? e.message : String(e);
+    return text.split("\n")[0];
+}
+const loadResult = new Map();
+/**
+ * Load `lang`'s grammar once per process. Resolves to `null` on success, or the load error's own
+ * text — the caller reports it verbatim as "not checked", never as a missing symbol.
+ */
+function loadWasmGrammar(lang) {
+    let result = loadResult.get(lang);
+    if (result === undefined) {
+        result = language(lang).then(() => null, (e) => firstLine(e));
+        loadResult.set(lang, result);
+    }
+    return result;
+}
+/**
+ * THE PREVIOUS WALK, NOT A QUERY: every node with a `name` field (its text), plus every node whose
+ * `left` field is a bare identifier / constant / type_identifier, with the nearest enclosing
+ * class/module name as `scope`. The native-grammar code had no per-language patterns to
+ * translate; a tags.scm-style query would be a DIFFERENT, narrower definition of "defined".
+ */
+function extract(root) {
+    const scopeKinds = new Set(exports.SCOPE_KINDS);
+    const idKinds = new Set(exports.ID_KINDS);
+    const out = [];
+    const walk = (node, scope) => {
+        const line = node.startPosition.row + 1;
+        const name = node.childForFieldName("name");
+        if (name)
+            out.push({ name: name.text, kind: node.type, scope, line });
+        const left = node.childForFieldName("left");
+        if (left && idKinds.has(left.type))
+            out.push({ name: left.text, kind: node.type, scope, line });
+        const next = scopeKinds.has(node.type) && name ? name.text : scope;
+        for (const child of node.children)
+            walk(child, next);
+    };
+    walk(root, "");
+    return out;
+}
+/** Parse `code` and return its definitions. Rejects on a parse failure — never resolves []. */
+async function wasmDefinedSymbols(code, lang) {
+    const grammar = await language(lang);
+    // `runtime` is set by `language()`; one parser, re-pointed per call. Safe without a lock:
+    // setLanguage → parse → walk runs to completion with no `await` in between.
+    const { parser } = await runtime;
+    parser.setLanguage(grammar);
+    const tree = parser.parse(code);
+    if (!tree)
+        throw new Error(`tree-sitter (${lang}) returned no syntax tree`);
+    try {
+        return extract(tree.rootNode);
+    }
+    finally {
+        tree.delete();
+    }
+}
+//# sourceMappingURL=tree-sitter-wasm.js.map

package/dist/eval-surface.js

@@ -1,4 +1,9 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles/eval` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-eval.api.md`, which
+// `npm run api:check` fails on.
 /**
  * `vigiles/eval` — the **paid** surface: every runtime export here can call a
  * model, and therefore can spend money.

package/dist/hook-install.js

@@ -265,15 +265,30 @@ function mergeHooksJson(existing, compiled, hookPath) {
     const before = existing.hooks ?? {};
     const rewritten = Object.fromEntries(Object.entries(compiled).map(([event, entries]) => [
         event,
-        [
-            ...(before[event] ?? [])
-                .map((e) => withoutHookCommands(e, hookPath))
-                .filter((e) => e !== null),
-            ...entries,
-        ],
+        replaceInPlace(before[event] ?? [], (e) => withoutHookCommands(e, hookPath), entries),
     ]));
     return { ...existing, hooks: { ...before, ...rewritten } };
 }
+/**
+ * Put `fresh` where this hook's old entry stood, not at the end. Appending made
+ * a recompile whose wiring changed read as a reshuffle: measured on a real
+ * settings.json, one guard gained `|| exit 2` and the diff showed three entries
+ * swapping places. `strip` returns the entry unchanged when it is not ours, a
+ * narrowed entry when it shared a matcher with ours, or null when it was only
+ * ours. A hook wired for the first time is still appended.
+ */
+function replaceInPlace(list, strip, fresh) {
+    const at = list.findIndex((e) => strip(e) !== e);
+    const slot = at === -1 ? list.length : at;
+    return [
+        ...list.flatMap((e, i) => {
+            const kept = strip(e);
+            const here = kept === null ? [] : [kept];
+            return i === slot ? [...here, ...fresh] : here;
+        }),
+        ...(slot === list.length ? fresh : []),
+    ];
+}
 /** Flatten a CC-shaped entry to Codex's flat `{matcher?, command}` form. */
 function toTomlEntries(entries) {
     return entries.flatMap((e) => e.hooks.map((h) => e.matcher === undefined
@@ -291,10 +306,8 @@ function mergeHooksToml(existing, compiled, hookPath) {
     const before = existing.hooks ?? {};
     const rewritten = Object.fromEntries(Object.entries(compiled).map(([event, entries]) => [
         event,
-        [
-            ...(before[event] ?? []).filter((e) => !managesHook({ hooks: [{ type: "command", command: e.command }] }, hookPath)),
-            ...toTomlEntries(entries),
-        ],
+        replaceInPlace(before[event] ?? [], (e) => managesHook({ hooks: [{ type: "command", command: e.command }] }, hookPath) ? null : e, // prettier-ignore
+        toTomlEntries(entries)),
     ]));
     return { ...existing, hooks: { ...before, ...rewritten } };
 }

package/dist/hook.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.admissibleWrites = exports.isStateWrite = exports.isStateNeed = exports.isValidStateKey = exports.stateFact = exports.record = exports.state = exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.invalidToolPatterns = exports.matchesTool = exports.outcomeWrites = exports.injectionOf = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.experimental_defineReact = exports.inject = exports.experimental_defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.experimental_defineStopGate = exports.experimental_definePromptGate = exports.experimental_defineFileGate = exports.experimental_defineHook = void 0;
 exports.leafCommandsNormalized = exports.HookStateError = exports.durationSeconds = void 0;
+// 🔴 PUBLIC ENTRY POINT `vigiles/hook` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-hook.api.md`, which
+// `npm run api:check` fails on.
 /**
  * `vigiles/hook` — the **closed vocabulary** for authoring a compiled hook.
  *

package/dist/jest.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+// 🔴 PUBLIC ENTRY POINT `vigiles/jest` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-jest.api.md`, which
+// `npm run api:check` fails on.
 /* eslint-disable max-params, @typescript-eslint/no-explicit-any --
    The matcher signatures mirror the runtime vigilesMatchers (positional args);
    `Check<any>` matches the runtime generic for the type-only augmentation. */

package/dist/linting.d.ts

@@ -1,34 +1,17 @@
 /**
- * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
- * files. The spec builders/types that describe a CLAUDE.md, a SKILL.md or an
- * agent, plus the public compile entry points, under one concern-named import.
+ * `vigiles/linting` — Pillar 1 entry point: what a spec AUTHOR imports to describe a CLAUDE.md,
+ * a SKILL.md or an agent — the builders, the verified-reference constructors and their types.
+ * Compiling is the CLI's job (`vigiles compile` / `vigiles lint`), not this subpath's.
  *
- * Curated (named, not `export *`) so the internal compiler validators, hash
- * helpers, and the linter cross-reference ENGINE stay out of the public surface,
- * the api reports, and the docs site (the CLI imports those from the source).
+ * Curated (named, not `export *`) so the internal compiler, validators, hash helpers and the
+ * linter cross-reference ENGINE stay out of the public surface, the api reports and the docs.
  *
- * 🔴 THAT SENTENCE USED TO BE FALSE, and so did the one after it (fixed
- * 2026-08-21). The file claimed to be curated while `export * from
- * "./core/spec.js"` sat one line below it, and it claimed "the spec builders are
- * also at the package root (`vigiles`)" — measured against `vigiles.api.md`: 191
- * exports there and zero matches for `claude`, `agent`, `enforce` or `result`.
- * The builders' second door is `vigiles/spec`, not the root. Both claims read as
- * documentation of a decision and were descriptions of the opposite one; a
- * header nobody re-reads is where an `export *` hides best.
- *
- * WHAT THE CURATION DROPS (28 symbols, measured — nothing in this repo imported
- * any of them from here; every in-repo user takes them from `vigiles/spec`, and
- * the one live consumer of this subpath in the docs takes `compileAgent`): the
- * typed-COMPOSITION family — `experimental_pipe`/`_pipeStep`/`_start`/
- * `_andThen`/`_needs`, `Pipeline`, `PipeStep`, `Supplies`, `Handoff`,
- * `NeedsContract`, `OkOf`, `TypedAgentSpec`, `TypedOutcome`, `Shape`,
- * `OutputFieldType` and the `result()` builder. Those verify HANDOFFS between
- * workers; they compile to nothing and lint nothing, so they are not pillar 1.
- *
- * ⚠️ The cut is not a clean slice along that line, and pretending otherwise
- * would strand a signature: the `result()` FUNCTION leaves, but the
- * `OutputContract` TYPE stays, because `compileAgent`/`compileSkill` name it in
- * their own types. A consumer who needs to BUILD one imports `vigiles/spec`.
+ * WHAT THE CURATION DROPS (28 symbols, measured 2026-08-21 — nothing in this repo imported any
+ * of them from here; every in-repo user takes them from `vigiles/spec`): the typed-COMPOSITION
+ * family — `experimental_pipe`/`_pipeStep`/`_start`/`_andThen`/`_needs`, `Pipeline`, `PipeStep`,
+ * `Supplies`, `Handoff`, `NeedsContract`, `OkOf`, `TypedAgentSpec`, `TypedOutcome`, `Shape`,
+ * `OutputFieldType` and the `result()` builder. Those verify HANDOFFS between workers; they
+ * compile to nothing and lint nothing, so they are not pillar 1.
  */
 export { instructionFile, prose, experimental_effect, enforce, guidance, guard, file, cmd, symbol, ref, dir, glob, project, experimental_skill, experimental_agent, 
 /** @deprecated Renamed to `instructionFile`. Removed one major AFTER the one that introduces it. */
@@ -38,6 +21,4 @@ instructions,
 /** @deprecated Renamed to `experimental_agent`. Removed one major AFTER the one that introduces it. */
 agent, } from "./core/spec.js";
 export { BUILTIN_LINTERS, type BuiltinLinter, type LinterRule, type VigilesRef, type EnforcementRef, type KnownLinterRules, type KnownProjectFiles, type KnownNpmScripts, type KnownAgentName, type StrictLinterRule, type StrictFile, type StrictCmd, type ToolVocabulary, type OpenToolVocabulary, type AllowedAt, type AuthoredPurity, type EnforceRule, type GuidanceRule, type GuardRule, type Rule, type VerifiedPath, type VerifiedCmd, type VerifiedRef, type VerifiedDir, type VerifiedGlob, type FileRef, type CmdRef, type SkillRef, type SymbolRef, type DirRef, type GlobRef, type Ref, type EffectRegion, type InstructionFragment, type InstructionTarget, type ClaudeSpec, type Gate, type RoleGate, type ProjectRole, type SkillInput, type SkillStep, type SkillSpec, type SkillSpecInput, type AgentSpec, type AgentSpecInput, type Railway, type RailwayStep, type OutputContract, } from "./core/spec.js";
-export { compileClaude, compileSkill, compileAgent, compileRailway, CompileError, } from "./core/compile.js";
-export type { CompileClaudeOptions, CompileClaudeResult, CompileSkillResult, CompileAgentResult, CompileRailwayOptions, CompileRailwayResult, } from "./core/compile.js";
 //# sourceMappingURL=linting.d.ts.map