vigiles 31.0.0 → 31.0.1

package/dist/core/coverage.d.ts

@@ -8,6 +8,7 @@
  * Configurable thresholds in .vigilesrc.json trigger warnings or errors when
  * coverage drops below the minimum.
  */
+import { type GlobIgnore } from "./glob-ignore.js";
 import type { CoverageThresholds } from "./types.js";
 import type { ClaudeSpec } from "./spec.js";
 export interface CoverageMetric {
@@ -35,11 +36,11 @@ export declare function readNpmScripts(basePath: string): string[];
  * Collect commands documented in specs by loading spec source files directly.
  * Reads the structured `commands` field — no markdown parsing.
  */
-export declare function collectDocumentedCommands(basePath: string, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): Set<string>;
+export declare function collectDocumentedCommands(basePath: string, specs: ClaudeSpec[] | undefined, ignore: GlobIgnore): Set<string>;
 /**
  * Compute script coverage: what % of npm scripts are documented in specs.
  */
-export declare function computeScriptCoverage(basePath: string, threshold: number | undefined, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): CoverageMetric;
+export declare function computeScriptCoverage(basePath: string, threshold: number | undefined, specs: ClaudeSpec[] | undefined, ignore: GlobIgnore): CoverageMetric;
 /**
  * Compute linter rule coverage from pre-computed totals.
  * The actual linter scanning is done by the existing discover() in cli.ts.
@@ -48,7 +49,7 @@ export declare function computeLinterRuleCoverage(enabled: number, documented: n
 /**
  * Check all coverage metrics against thresholds.
  */
-export declare function checkCoverage(basePath: string, thresholds: CoverageThresholds, linterEnabled: number, linterDocumented: number, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): CoverageReport;
+export declare function checkCoverage(basePath: string, thresholds: CoverageThresholds, linterEnabled: number, linterDocumented: number, specs: ClaudeSpec[] | undefined, ignore: GlobIgnore): CoverageReport;
 /**
  * Format coverage report as human-readable text.
  */

package/dist/core/coverage.js

@@ -20,6 +20,7 @@ const node_fs_1 = require("node:fs");
 const integrity_js_1 = require("./integrity.js");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./glob-ignore.js");
 const compile_js_1 = require("./compile.js");
 // ---------------------------------------------------------------------------
 // Script coverage
@@ -50,12 +51,12 @@ function collectDocumentedCommands(basePath, specs, ignore) {
     // Fallback: scan compiled markdown for spec file references, then
     // load the compiled JS spec from dist/. If that fails, try to
     // extract commands from the compiled output (last resort).
-    // `ignore` is the repo's ExcludeSet string face (src/exclude.ts): the floor
-    // plus `.vigilesrc.json#exclude`, required so this fallback cannot walk a
+    // `ignore` is the repo's `ExcludeSet.globIgnore` (src/exclude.ts, correct
+    // from any cwd) or patterns relative to `basePath`, required so this fallback cannot walk a
     // vendored corpus the repo excluded (#192). The CLI always passes `specs`,
     // so this branch is reached by the library path and tests only.
     const mdFiles = (0, glob_1.globSync)("**/*.md", {
-        ignore: [...ignore],
+        ignore: (0, glob_ignore_js_1.withIgnored)([], ignore),
         cwd: basePath,
     });
     for (const mdFile of mdFiles) {

package/dist/core/doc-refs.d.ts

@@ -17,6 +17,7 @@
  * in markdown is explicitly out of scope — use eslint-plugin-markdown or
  * twoslash for that.
  */
+import { type GlobIgnore } from "./glob-ignore.js";
 export type DocRefKind = "enforce" | "file" | "cmd" | "ref";
 export interface DocRef {
     readonly file: string;
@@ -40,7 +41,8 @@ export interface DocRefReport {
 }
 export interface FindDocRefsOptions {
     readonly basePath?: string;
-    readonly ignore?: readonly string[];
+    /** The repo exclude (`ExcludeSet.globIgnore`), or patterns relative to `basePath`. */
+    readonly ignore?: GlobIgnore;
 }
 interface ExtractResult {
     refs: DocRef[];

package/dist/core/doc-refs.js

@@ -29,6 +29,7 @@ const node_fs_1 = require("node:fs");
 const typescript_1 = __importDefault(require("typescript"));
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./glob-ignore.js");
 const linters_js_1 = require("./linters.js");
 const compile_js_1 = require("./compile.js");
 // ---------------------------------------------------------------------------
@@ -239,7 +240,7 @@ function validateRefs(refs, basePath) {
  */
 function findDocRefs(options = {}) {
     const basePath = options.basePath ?? process.cwd();
-    const ignore = [...DEFAULT_IGNORE, ...(options.ignore ?? [])];
+    const ignore = (0, glob_ignore_js_1.withIgnored)(DEFAULT_IGNORE, options.ignore);
     const files = (0, glob_1.globSync)("**/*.md", { cwd: basePath, ignore });
     const allRefs = [];
     let filesIgnored = 0;

package/dist/core/frame.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The frame of a path — WHICH DIRECTORY it is relative to — named by its TYPE
+ * rather than by a comment (#281).
+ *
+ * 🔴 WHY THIS EXISTS. Every path the CLI handled was a bare `string`, so a path
+ * relative to a nested bundle, one relative to the repository and an absolute one
+ * were the same type, and nothing stopped a caller from printing the wrong one.
+ * `overBundles` handed each check ONE `root: string` that had to be the discovery
+ * base, the base of the config's globs AND the frame of every printed path at
+ * once. Under `bundles: "all"` that root was the nested bundle, so `include`
+ * resolved from the wrong directory and `::warning file=skills/x/SKILL.md` named a
+ * file that did not exist from where the command ran — while a root-bundle skill
+ * of the same name made the annotation land on the WRONG real file, which looks
+ * like success.
+ *
+ * Three frames, two of them branded:
+ *   - {@link RepoPath} — relative to {@link Frame.root}, the directory whose
+ *     `.vigilesrc.json` governs the run. Every printed or annotated path.
+ *   - {@link BundlePath} — relative to one {@link Bundle}'s own directory. What a
+ *     per-bundle scan reports.
+ *   - an absolute path — a plain `string`, the only thing the filesystem takes.
+ *
+ * The brand is `Opaque` from `ts-essentials` (a `unique symbol` key, so no object
+ * literal can forge it), imported as a TYPE ONLY: nothing of it survives the
+ * build. It must not reach a public `.d.ts` either — this module is internal and
+ * the API report (`api-surface/*.api.md`) is the gate that would show a leak.
+ *
+ * 🔴 THE ONE CONVERSION POINT. A `RepoPath` is minted here and nowhere else:
+ * {@link Frame.repo} from an absolute path, {@link Bundle.path} from a
+ * `BundlePath`. A cast to `RepoPath` outside this file is refused by ESLint
+ * (`no-restricted-syntax` in `eslint.config.mjs`), so "where did this path get its
+ * frame" always has the answer "in frame.ts".
+ *
+ * WHAT IS UNREPRESENTABLE AND WHAT IS ONLY DETECTABLE. The CLI's output boundary
+ * (`ghAnnotate`, the per-bundle check context) takes `RepoPath`, so handing it a
+ * bundle-relative or absolute string is a tsc error. Upstream of that, scan-core
+ * keeps reporting plain bundle-relative strings, because its browser twin
+ * (`scan-files.ts`) shares those shapes and has no filesystem to have a frame
+ * over. {@link Bundle.scanned} is the seam where such a string gets its frame;
+ * a relative string that is secretly repo-relative still passes it, and that
+ * residue is caught by tests, not by the compiler.
+ *
+ * NODE-FREE: path ops come from `../posix-path.js`, and the caller supplies the
+ * working directory, so this module has no process state of its own.
+ */
+import type { Opaque } from "ts-essentials";
+/** A `/`-separated path relative to {@link Frame.root}. `.` is the root itself. */
+export type RepoPath = Opaque<string, "RepoPath">;
+/** A `/`-separated path relative to one {@link Bundle}'s own directory. */
+export type BundlePath = Opaque<string, "BundlePath">;
+/** One scored directory: the lint target itself, or a nested plugin bundle. */
+export interface Bundle {
+    /** Absolute directory of the bundle. */
+    readonly abs: string;
+    /** Where the bundle sits, from the frame root (`.` when it IS the root). */
+    readonly at: RepoPath;
+    /** A path this bundle's scan reported, re-expressed from the frame root. */
+    path(p: BundlePath): RepoPath;
+    /**
+     * The seam for scan-core's plain strings, which are bundle-relative by
+     * contract (see the header). An ABSOLUTE string is accepted too and converted
+     * directly — `hook-block-ineffective` reports its script that way.
+     */
+    scanned(p: string): RepoPath;
+}
+/** The single owner of "relative to which directory", built once per command. */
+export interface Frame {
+    /** Absolute directory every {@link RepoPath} is relative to. */
+    readonly root: string;
+    /** The one conversion from an absolute path. Throws on a relative input. */
+    repo(abs: string): RepoPath;
+    /** Describe the bundle at an absolute directory, in this frame. */
+    bundle(abs: string): Bundle;
+}
+/**
+ * The frame for a command run from `cwd` against `target` (absolute).
+ *
+ * The root is `cwd` — where `loadConfig()` read `.vigilesrc.json` (it does not
+ * walk up; measured 2026-09-23) — UNLESS the target lies outside it. A foreign
+ * target (`vigiles lint ../other`) is somebody else's repository, and its paths
+ * mean something from ITS root; relative to `cwd` they would all start with
+ * `../`, and a foreign lint must never let the caller's own files satisfy the
+ * target's `sharedDirs` references. That exception was `sharedDirsRootFor` in
+ * the CLI, applied to `sharedDirs` alone; it is owned here now, so `include`,
+ * `exclude`, `sharedDirs` and every printed path agree on one root.
+ */
+export declare function frameFor(cwd: string, target: string): Frame;
+/** The frame rooted at an absolute directory. */
+export declare function frameAt(root: string): Frame;
+//# sourceMappingURL=frame.d.ts.map

package/dist/core/frame.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.frameFor = frameFor;
+exports.frameAt = frameAt;
+const posix_path_js_1 = require("../posix-path.js");
+/**
+ * Node on Windows hands out `C:\\repo`, and `../posix-path.js` recognises only a leading `/`
+ * as absolute. The frame works in `/`-separated form, so every path entering it passes here:
+ * backslashes become `/`, and a drive-letter path (`C:/…`) counts as absolute.
+ */
+function slashed(p) {
+    return p.replaceAll("\\", "/");
+}
+function isAbs(p) {
+    return (0, posix_path_js_1.isAbsolute)(p) || /^[A-Za-z]:\//.test(p);
+}
+/** `rel` is `abs`'s position below `root` when it does not climb out. */
+function isBelow(rel) {
+    return rel === "" || (rel !== ".." && !rel.startsWith("../"));
+}
+/**
+ * The frame for a command run from `cwd` against `target` (absolute).
+ *
+ * The root is `cwd` — where `loadConfig()` read `.vigilesrc.json` (it does not
+ * walk up; measured 2026-09-23) — UNLESS the target lies outside it. A foreign
+ * target (`vigiles lint ../other`) is somebody else's repository, and its paths
+ * mean something from ITS root; relative to `cwd` they would all start with
+ * `../`, and a foreign lint must never let the caller's own files satisfy the
+ * target's `sharedDirs` references. That exception was `sharedDirsRootFor` in
+ * the CLI, applied to `sharedDirs` alone; it is owned here now, so `include`,
+ * `exclude`, `sharedDirs` and every printed path agree on one root.
+ */
+function frameFor(cwd, target) {
+    return frameAt(isBelow((0, posix_path_js_1.relative)(slashed(cwd), slashed(target))) ? cwd : target);
+}
+/** The frame rooted at an absolute directory. */
+function frameAt(root) {
+    const base = (0, posix_path_js_1.normalize)(slashed(root));
+    const repo = (raw) => {
+        const abs = slashed(raw);
+        if (!isAbs(abs))
+            throw new Error(`frame.repo() takes an absolute path, got "${raw}" — a relative string has no frame to convert from`);
+        return ((0, posix_path_js_1.relative)(base, abs) || ".");
+    };
+    const bundle = (raw) => {
+        const dir = (0, posix_path_js_1.normalize)(slashed(raw));
+        const path = (p) => repo((0, posix_path_js_1.join)(dir, p));
+        return {
+            abs: dir,
+            at: repo(dir),
+            path,
+            // The ONE place a plain string is taken to be bundle-relative.
+            scanned: (p) => (isAbs(slashed(p)) ? repo(p) : path(p)),
+        };
+    };
+    return { root: base, repo, bundle };
+}
+//# sourceMappingURL=frame.js.map

package/dist/core/glob-ignore.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One `ignore` for `globSync` out of a detector's own string floor plus the
+ * repository's exclude — glob takes EITHER a pattern list OR one `IgnoreLike`,
+ * never both, so a detector that has both needs this union.
+ *
+ * 🔴 WHY THE REPO EXCLUDE ARRIVES AS AN `IgnoreLike` AND NOT AS STRINGS (#281).
+ * `ExcludeSet` used to hand detectors a string list whose patterns were relative
+ * to the repository root, with the precondition "only correct for a glob rooted
+ * AT that root" written in a comment. Two callers globbed from a nested bundle
+ * and broke it silently: a root-relative `skills/lonely` dropped
+ * `plugins/p/skills/lonely`, and the real exclusion never reached the bundle.
+ * `ExcludeSet.globIgnore` computes each candidate's position from the repo root
+ * itself, so it is correct from ANY glob `cwd`; the string face was retired.
+ *
+ * A plain string list is still accepted — for a direct library caller whose
+ * patterns are, by that caller's own contract, relative to the `cwd` it globs
+ * from. That is the one frame a string can safely carry.
+ */
+import { type IgnoreLike } from "glob";
+/** What a detector takes for "also skip these". */
+export type GlobIgnore = readonly string[] | IgnoreLike;
+/**
+ * `floor` (patterns relative to the glob's `cwd`) plus `extra`, in the form
+ * `globSync`'s `ignore` option accepts. Stays a plain list when both halves are
+ * lists, so a string-only caller sees exactly the glob behaviour it always had.
+ */
+export declare function withIgnored(floor: readonly string[], extra: GlobIgnore | undefined): string[] | IgnoreLike;
+//# sourceMappingURL=glob-ignore.d.ts.map

package/dist/core/glob-ignore.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withIgnored = withIgnored;
+/**
+ * One `ignore` for `globSync` out of a detector's own string floor plus the
+ * repository's exclude — glob takes EITHER a pattern list OR one `IgnoreLike`,
+ * never both, so a detector that has both needs this union.
+ *
+ * 🔴 WHY THE REPO EXCLUDE ARRIVES AS AN `IgnoreLike` AND NOT AS STRINGS (#281).
+ * `ExcludeSet` used to hand detectors a string list whose patterns were relative
+ * to the repository root, with the precondition "only correct for a glob rooted
+ * AT that root" written in a comment. Two callers globbed from a nested bundle
+ * and broke it silently: a root-relative `skills/lonely` dropped
+ * `plugins/p/skills/lonely`, and the real exclusion never reached the bundle.
+ * `ExcludeSet.globIgnore` computes each candidate's position from the repo root
+ * itself, so it is correct from ANY glob `cwd`; the string face was retired.
+ *
+ * A plain string list is still accepted — for a direct library caller whose
+ * patterns are, by that caller's own contract, relative to the `cwd` it globs
+ * from. That is the one frame a string can safely carry.
+ */
+const glob_1 = require("glob");
+function isPatternList(x) {
+    return Array.isArray(x);
+}
+/**
+ * `floor` (patterns relative to the glob's `cwd`) plus `extra`, in the form
+ * `globSync`'s `ignore` option accepts. Stays a plain list when both halves are
+ * lists, so a string-only caller sees exactly the glob behaviour it always had.
+ */
+function withIgnored(floor, extra) {
+    if (extra === undefined)
+        return [...floor];
+    if (isPatternList(extra))
+        return [...floor, ...extra];
+    const own = new glob_1.Ignore([...floor], {});
+    return {
+        ignored: (p) => own.ignored(p) || extra.ignored?.(p) === true,
+        childrenIgnored: (p) => own.childrenIgnored(p) || extra.childrenIgnored?.(p) === true,
+    };
+}
+//# sourceMappingURL=glob-ignore.js.map

package/dist/core/orphans.d.ts

@@ -11,6 +11,7 @@
  * references (markdown links and backtick paths). Works against source
  * README plus compiled CLAUDE.md — no spec loading required.
  */
+import { type GlobIgnore } from "./glob-ignore.js";
 import type { PluginLayout } from "./layout.js";
 export interface OrphanReport {
     /** Include globs that were scanned. */
@@ -35,12 +36,13 @@ export interface FindOrphansOptions {
     /** Glob patterns to exclude within the include scope (orphan CANDIDACY only). */
     readonly exclude?: readonly string[];
     /**
-     * The repo-wide `.vigilesrc.json#exclude` (the ExcludeSet string face,
-     * src/exclude.ts). Applied to BOTH walks — candidates AND the reference scan —
+     * The repo-wide `.vigilesrc.json#exclude` (`ExcludeSet.globIgnore`,
+     * src/exclude.ts — correct from any glob cwd; a plain list is relative to
+     * `basePath`). Applied to BOTH walks — candidates AND the reference scan —
      * so an excluded corpus can neither be an orphan nor keep one alive (#192).
      * The CLI always passes it; a direct library caller may omit it.
      */
-    readonly repoExclude?: readonly string[];
+    readonly repoExclude?: GlobIgnore;
     /**
      * Harnesses whose surface files (instruction file, `SKILL.md`, subagents,
      * commands) are load-bearing by location and thus never orphan CANDIDATES

package/dist/core/orphans.js

@@ -18,6 +18,7 @@ exports.formatOrphanReport = formatOrphanReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./glob-ignore.js");
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
@@ -100,7 +101,7 @@ function isOrphanExempt(absPath) {
 function collectDocs(basePath, include, ignore, layouts) {
     const docs = new Set();
     for (const pattern of include) {
-        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
+        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore })) {
             if (isHarnessLoadedFile(p, layouts))
                 continue; // harness files are never orphans
             if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
@@ -160,13 +161,13 @@ function findOrphanDocs(options = {}) {
     // CANDIDATE nor a SOURCE of references (a link from inside it must not keep a
     // doc alive). The rule's own `exclude` only narrows candidacy: a doc kept out
     // of the orphan list can still reference others. Union, never override.
-    const repoExclude = options.repoExclude ?? [];
-    const ignore = [...DEFAULT_IGNORE, ...repoExclude, ...userExclude];
+    const repoExclude = options.repoExclude;
+    const ignore = (0, glob_ignore_js_1.withIgnored)([...DEFAULT_IGNORE, ...userExclude], repoExclude);
     const layouts = options.layouts ?? [];
     const allDocs = collectDocs(basePath, include, ignore, layouts);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
-        ignore: [...DEFAULT_IGNORE, ...repoExclude],
+        ignore: (0, glob_ignore_js_1.withIgnored)(DEFAULT_IGNORE, repoExclude),
     });
     const referencedBy = new Map();
     for (const mdPath of allMarkdown) {

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "31.0.0",
+  "version": "31.0.1",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",
@@ -109,7 +109,7 @@
     "@typescript-eslint/eslint-plugin": "^8.58.0",
     "@typescript-eslint/parser": "^8.58.0",
     "@vitest/coverage-v8": "^4.1.8",
-    "conventional-changelog-conventionalcommits": "^10.3.0",
+    "conventional-changelog-conventionalcommits": "9.3.1",
     "eslint": "^10.1.0",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-boundaries": "^6.0.2",
@@ -118,6 +118,7 @@
     "jest": "^30.4.2",
     "picomatch": "^4.0.4",
     "prettier": "^3.8.1",
+    "semantic-release": "25.0.9",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.19",
     "typescript": "^5.9.3",