vigiles 30.0.2 → 31.0.1

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

@@ -8,12 +8,10 @@ export interface ExcludeSet {
     /** The user's patterns, as written (for messages). */
     readonly patterns: readonly string[];
     /**
-     * The string-list face for a glob rooted AT `root`: the floor, then each user
-     * pattern normalized so a bare directory name excludes its subtree (`bench` →
-     * `bench`, `bench/**`), which is what "tsconfig-style" promises.
+     * The function face for `globSync`, correct whatever the glob's `cwd` is. A
+     * bare directory name excludes its subtree (`bench` → `bench`, `bench/**`),
+     * which is what "tsconfig-style" promises.
      */
-    readonly ignore: readonly string[];
-    /** The function face for `globSync`, correct whatever the glob's `cwd` is. */
     readonly globIgnore: IgnoreLike;
     /** Is this root-relative path excluded (floor or user pattern)? */
     matches(rel: string): boolean;

package/dist/exclude.js

@@ -4,8 +4,9 @@ exports.excludesNothing = exports.EXCLUDE_FLOOR = void 0;
 exports.excludeSet = excludeSet;
 exports.excludedBy = excludedBy;
 /**
- * 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).
+ * 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 `globIgnore` face handed to `findDocRefs`, `findOrphanDocs` (`repoExclude`), `discoverScripts`, `computeScriptCoverage`; the whole set to `findUntestedSurfaces`/`skillTestNudge`/`scanPlugin`).
+ * Faces: `globIgnore` (an `IgnoreLike` keyed on the path's position relative to the REPO root, so a glob rooted anywhere — `vigiles lint some/dir`, a nested bundle — still applies a root-relative exclude), `matches`/`explain` (a root-relative path), and `excludedBy` below (an absolute path).
+ * 🔴 There is deliberately NO string-list face any more (#281). It was `ignore`, correct only for a glob rooted AT `root` — a precondition that lived in a comment, and two callers that globbed from a nested bundle broke it: the repo exclude never reached the bundle, and a root-relative pattern aliased into it. `core/glob-ignore.ts` unions a detector's own string floor with `globIgnore` instead.
  * 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').
@@ -57,7 +58,6 @@ function excludeSet(root, patterns) {
     return {
         root,
         patterns: user,
-        ignore: [...exports.EXCLUDE_FLOOR, ...user.flatMap((p) => [p, `${p}/**`])],
         globIgnore: {
             ignored: (p) => matches(relOf(p)),
             childrenIgnored: (p) => matches(relOf(p)),

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

package/dist/linting.js

@@ -1,38 +1,26 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles/linting` — 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-linting.api.md`, which
+// `npm run api:check` fails on.
 /**
- * `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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.compileRailway = exports.compileAgent = exports.compileSkill = exports.compileClaude = exports.BUILTIN_LINTERS = exports.agent = exports.instructions = exports.claude = exports.experimental_agent = exports.experimental_skill = exports.project = exports.glob = exports.dir = exports.ref = exports.symbol = exports.cmd = exports.file = exports.guard = exports.guidance = exports.enforce = exports.experimental_effect = exports.prose = exports.instructionFile = void 0;
+exports.BUILTIN_LINTERS = exports.agent = exports.instructions = exports.claude = exports.experimental_agent = exports.experimental_skill = exports.project = exports.glob = exports.dir = exports.ref = exports.symbol = exports.cmd = exports.file = exports.guard = exports.guidance = exports.enforce = exports.experimental_effect = exports.prose = exports.instructionFile = void 0;
 // --- the spec authoring builders: rules, refs, prose, and the three spec kinds ---
 var spec_js_1 = require("./core/spec.js");
 // instruction files
@@ -67,12 +55,11 @@ Object.defineProperty(exports, "instructions", { enumerable: true, get: function
 Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return spec_js_1.agent; } });
 var spec_js_2 = require("./core/spec.js");
 Object.defineProperty(exports, "BUILTIN_LINTERS", { enumerable: true, get: function () { return spec_js_2.BUILTIN_LINTERS; } });
-// Compile: only the public entry points + their option/result types.
-var compile_js_1 = require("./core/compile.js");
-Object.defineProperty(exports, "compileClaude", { enumerable: true, get: function () { return compile_js_1.compileClaude; } });
-Object.defineProperty(exports, "compileSkill", { enumerable: true, get: function () { return compile_js_1.compileSkill; } });
-Object.defineProperty(exports, "compileAgent", { enumerable: true, get: function () { return compile_js_1.compileAgent; } });
-Object.defineProperty(exports, "compileRailway", { enumerable: true, get: function () { return compile_js_1.compileRailway; } });
+// NO COMPILE ENTRY POINTS HERE (removed in the major that ships #257). `compileClaude`,
+// `compileSkill`, `compileAgent`, `compileRailway` and their option/result types were public
+// with no external caller — measured across the repos that depend on vigiles, every import is a
+// spec builder — and the promise froze them synchronous while the symbol check they run became
+// async. Spec authors run `vigiles compile`; the CLI imports the compiler from source.
 // core/linters is the cross-reference ENGINE (checkLinterRule/editDistance/…),
 // consumed by compile — not part of the public authoring surface.
 //# sourceMappingURL=linting.js.map

package/dist/scan.d.ts

@@ -423,9 +423,9 @@ export declare function scanPlugin(dir: string, layout: PluginLayout, dialect: H
      * would be twenty-odd mechanical edits for one behavioural change.
      *
      * ⚠️ Omitting it is NOT "the repo excludes nothing" — it is "this caller has
-     * no ExcludeSet to give", and the walk then reads everything. Today only
-     * `audit` supplies one; the `lint` rule checkers below still do not (they
-     * share a `(config, silent, adapter, root)` signature through `overBundles`).
+     * no ExcludeSet to give", and the walk then reads everything. `audit` and
+     * every `lint` rule checker supply one (the checkers through the per-bundle
+     * context `overBundles` builds, so a new checker cannot forget it).
      */
     excludes?: ExcludeSet;
     /**

package/dist/scan.js

@@ -230,13 +230,14 @@ function scanPlugin(dir, layout, dialect, opts = {}) {
     const coverage = (0, test_coverage_js_1.findUntestedSurfaces)({
         basePath: dir,
         layout: lay,
-        // The SAME `.vigilesrc.json#exclude`, in this walk's string face. Untested-
-        // surface discovery is a second walk over the same trees, so leaving it out
-        // would have excluded a skill from the GRADE while still naming it in
-        // "Untested surfaces: 1" — a report contradicting itself about whether the
-        // file exists. `exclude` here NARROWS (it unions with DEFAULT_IGNORE), which
-        // is the documented relationship between the repo floor and a rule's own list.
-        exclude: opts.excludes ? [...opts.excludes.ignore] : undefined,
+        // The SAME `.vigilesrc.json#exclude`. Untested-surface discovery is a
+        // second walk over the same trees, so leaving it out would have excluded a
+        // skill from the GRADE while still naming it in "Untested surfaces: 1" — a
+        // report contradicting itself about whether the file exists. Passed WHOLE,
+        // not as a pattern list: `dir` is often not the repo root (`audit plugins/p`),
+        // and a root-relative list globbed from here matched nothing it named —
+        // `inventory.skills: 1` beside `untested: 2` (#281, D7).
+        excludes: opts.excludes,
     });
     const caveats = (0, test_coverage_js_1.coverageCaveats)(coverage);
     return {

package/dist/test-coverage.d.ts

@@ -60,6 +60,8 @@
  * magnitude in cost without saying which. {@link UntestedReport} therefore carries
  * a per-tier {@link CoverageTier} alongside the (unchanged) union fields.
  */
+import { type ExcludeSet } from "./exclude.js";
+import type { RepoPath } from "./core/frame.js";
 import { type PluginLayout } from "./core/layout.js";
 import { type CoverageEvidence, type EvidenceCounts } from "./coverage-evidence.js";
 export type SurfaceKind = "skill" | "agent" | "hook";
@@ -185,8 +187,14 @@ export interface UntestedReport {
     readonly evals: CoverageTier;
 }
 export interface TestCoverageOptions {
-    /** Repository root. Defaults to `process.cwd()`. */
+    /** The bundle whose surfaces are discovered. Defaults to `process.cwd()`. */
     readonly basePath?: string;
+    /**
+     * The directory `include`, `exclude`, the coverage artifact and every REPORTED
+     * path are relative to — where `.vigilesrc.json` lives. Defaults to `basePath`.
+     * Differs from it for a nested bundle under `bundles: "all"` (#281).
+     */
+    readonly root?: string;
     /** Scan skills under `skills/` and `.claude/skills/`. Default true. */
     readonly skills?: boolean;
     /** Scan subagents under `agents/` and `.claude/agents/`. Default true. */
@@ -210,8 +218,17 @@ export interface TestCoverageOptions {
      * `mjs` was silently ignored on any TypeScript-shaped repo.
      */
     readonly testExtension?: string;
-    /** Extra ignore globs (added to node_modules/dist/.git/.vigiles). */
+    /**
+     * The rule's own `exclude` globs, relative to `root` (added to
+     * node_modules/dist/.git/.vigiles). NARROWS on top of {@link excludes}.
+     */
     readonly exclude?: readonly string[];
+    /**
+     * The repo-wide `.vigilesrc.json#exclude`. It carries its own root, so it is
+     * applied correctly whichever directory is being discovered — a string list
+     * here was correct only when that directory WAS the repo root (#281).
+     */
+    readonly excludes?: ExcludeSet;
     /**
      * Harness layout — where skills/agents live, the plugin-root token, the
      * manifest/settings paths. Defaults to Claude Code; a non-CC adapter passes its
@@ -266,7 +283,7 @@ export declare function coverageEvidenceCounts(report: UntestedReport): Evidence
  * Returns `null` when the edited file isn't a skill/agent surface, or when it is
  * covered on both tiers. Never throws — a nudge must not disrupt an edit.
  */
-export declare function skillTestNudge(filePath: string, options: TestCoverageOptions): string | null;
+export declare function skillTestNudge(filePath: RepoPath, options: TestCoverageOptions): string | null;
 /**
  * What the PAID eval tier measures for a surface of this kind — or `null` when
  * it measures nothing for it.

package/dist/test-coverage.js

@@ -71,10 +71,13 @@ exports.coverageCaveats = coverageCaveats;
 exports.formatUntestedReport = formatUntestedReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const minimatch_1 = require("minimatch");
 const test_file_ext_js_1 = require("./core/test-file-ext.js");
 const assert_never_js_1 = require("./core/assert-never.js");
 const ts_runner_caps_js_1 = require("./ts-runner-caps.js");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./core/glob-ignore.js");
+const exclude_js_1 = require("./exclude.js");
 const layout_js_1 = require("./core/layout.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
 const coverage_artifact_js_1 = require("./coverage-artifact.js");
@@ -427,27 +430,47 @@ function tierOf(considered, tests, index, tier, globs) {
  */
 function findUntestedSurfaces(options) {
     const basePath = options.basePath ?? process.cwd();
+    const root = options.root ?? basePath;
     const { layout } = options;
-    const ignore = [...DEFAULT_IGNORE, ...(options.exclude ?? [])];
+    const ruleIgnore = [...DEFAULT_IGNORE, ...(options.exclude ?? [])];
+    const ignore = (0, glob_ignore_js_1.withIgnored)(ruleIgnore, options.excludes?.globIgnore);
     const globs = options.include ?? DEFAULT_TEST_GLOBS;
-    const surfaces = [];
+    // #281: surfaces are FOUND under the bundle and then re-expressed from `root`,
+    // so every later comparison (colocation, `{surface}` globs, the run index,
+    // exclude, the printed path) happens in ONE frame.
+    const prefix = (0, node_path_1.relative)(root, basePath).split(node_path_1.sep).join("/");
+    const toRoot = (s) => prefix === "" ? s : { ...s, path: `${prefix}/${s.path}` };
+    const repoExcluded = (0, exclude_js_1.excludedBy)(options.excludes);
+    const excluded = (p) => ruleIgnore.some((g) => (0, minimatch_1.minimatch)(p, g, { dot: true })) ||
+        repoExcluded((0, node_path_1.join)(root, p));
+    // Discovery globs from the BUNDLE, so it gets only the frame-free floor; the
+    // rule's patterns are root-relative and the repo's carry their own root, so
+    // both are applied below, to the root-relative path.
+    const floor = [...DEFAULT_IGNORE];
+    const found = [];
     if (options.skills !== false)
-        surfaces.push(...discoverSkills(basePath, ignore, layout));
+        found.push(...discoverSkills(basePath, floor, layout));
     if (options.agents !== false)
-        surfaces.push(...discoverAgents(basePath, ignore, layout));
+        found.push(...discoverAgents(basePath, floor, layout));
     if (options.hooks !== false)
-        surfaces.push(...discoverHooks(basePath, layout));
+        found.push(...discoverHooks(basePath, layout));
+    // Hooks were never subject to `ignore` (a compiled hook lives under the
+    // default-ignored `.vigiles/`); keep that, and re-apply exclude to the kinds
+    // whose discovery glob used it — now from `root`, where the patterns live.
+    const surfaces = found
+        .map(toRoot)
+        .filter((s) => s.kind === "hook" || !excluded(s.path));
     // Every skill/agent/hook is held to the requirement — only an explicit
     // `vigiles:ignore-test` marker exempts a surface (a visible, deliberate skip).
     const considered = surfaces.filter((s) => !s.ignored);
     const exempt = surfaces.length - considered.length;
-    const tests = discoverTests(basePath, globs, ignore);
+    const tests = discoverTests(root, globs, ignore);
     const split = partitionTests(tests);
     // The run record, if there is one. NO artifact ⇒ an empty index ⇒ every
     // decision below falls through to colocation, byte-for-byte as before: a fresh
     // clone and someone else's repo must not get one extra nudge from this tier.
-    const runIndex = (0, coverage_artifact_js_1.indexRuns)((0, coverage_artifact_js_1.readCoverageArtifact)(basePath), (p) => {
-        const abs = (0, node_path_1.join)(basePath, p);
+    const runIndex = (0, coverage_artifact_js_1.indexRuns)((0, coverage_artifact_js_1.readCoverageArtifact)(root), (p) => {
+        const abs = (0, node_path_1.join)(root, p);
         return (0, node_fs_1.existsSync)(abs) ? (0, coverage_artifact_js_1.surfaceSha)(read(abs)) : null;
     }, 
     // The SCRIPT that did the exercising has to still be here too — a deleted or
@@ -455,7 +478,7 @@ function findUntestedSurfaces(options) {
     // record is permanent, unfalsifiable coverage. `canonicalScript` first: one
     // file has several legitimate spellings (`x.mjs`, `./x.mjs`, absolute), and
     // the artifact records whichever one was typed.
-    (by) => (0, node_fs_1.existsSync)((0, node_path_1.join)(basePath, (0, coverage_artifact_js_1.canonicalScript)(by, basePath))));
+    (by) => (0, node_fs_1.existsSync)((0, node_path_1.join)(root, (0, coverage_artifact_js_1.canonicalScript)(by, root))));
     const union = tierOf(considered, tests, runIndex, undefined, globs);
     return {
         total: considered.length,
@@ -477,8 +500,8 @@ function findUntestedSurfaces(options) {
         }),
         legacyCoversFiles: tests
             .map((t) => t.path)
-            .filter((path) => read((0, node_path_1.join)(basePath, path)).includes(LEGACY_COVERS)),
-        retiredTestNames: retiredTestNamesFor(basePath, union.untested),
+            .filter((path) => read((0, node_path_1.join)(root, path)).includes(LEGACY_COVERS)),
+        retiredTestNames: retiredTestNamesFor(root, union.untested),
         decisions: union.decisions,
         harness: tierOf(considered, split.harness, runIndex, "harness", globs),
         evals: tierOf(considered, split.evals, runIndex, "eval", globs),
@@ -549,9 +572,12 @@ function skillTestNudge(filePath, options) {
     catch {
         return null; // a broken scan must never surface as a broken edit
     }
-    const norm = (p) => p.replaceAll("\\", "/");
-    const target = norm(filePath);
-    const isTarget = (s) => norm(s.path) === target || target.endsWith(`/${norm(s.path)}`);
+    // 🔴 EQUALITY, IN ONE FRAME (#281, D6). This used to accept any path ENDING in
+    // a surface's path, so editing `plugins/p/skills/x/SKILL.md` matched the root
+    // bundle's `skills/x/SKILL.md` and reported THAT skill's coverage as the
+    // edited one's. The caller now hands a `RepoPath` and the report's paths are
+    // relative to the same `root`, so a suffix has nothing left to rescue.
+    const isTarget = (s) => s.path === filePath;
     const untested = report.untested.find(isTarget);
     if (untested)
         return (`vigiles: you edited ${untested.path}, and nothing measures whether it ` +

package/dist/test.js

@@ -1,4 +1,9 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles` — 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.api.md`, which
+// `npm run api:check` fails on.
 /**
  * `vigiles` (the package root) — the **free** testing surface: everything you can
  * run without a model call, and therefore without a bill.

package/dist/vitest.mjs

@@ -1,3 +1,8 @@
+// 🔴 PUBLIC ENTRY POINT `vigiles/vitest` — 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-vitest.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),
    and `Matchers<T = any>` must match @vitest/expect's generic default to merge. */