vigiles 18.1.0 → 18.1.2

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -93,6 +93,11 @@ export declare function interpreterArgs(file: string, caps: NodeCaps, entry?: st
 export declare function discoverScripts(patterns: readonly string[], defaultGlob: string, cwd: string): string[];
 /** Extra wiring for {@link runScripts}. */
 export interface RunScriptsOptions {
+    /**
+     * How many scripts may run at once. Omitted → decided from `entry`: `test`
+     * fans out across the cores, `eval` stays at 1. See {@link runScripts}.
+     */
+    readonly concurrency?: number;
     /**
      * A program to run INSTEAD of each script, with the script's path as its one
      * argument. `vigiles eval` passes `dist/eval-entry.js`; `vigiles test` passes
@@ -116,7 +121,7 @@ export interface RunScriptsOptions {
  * record them (`.vigiles/coverage.json`) and coverage can answer "tested?" from
  * execution rather than from a matching file name.
  */
-export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv, opts?: RunScriptsOptions): ScriptRunResult[];
+export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv, opts?: RunScriptsOptions): Promise<ScriptRunResult[]>;
 /**
  * Whether any script FAILED. Neither a skip nor a vacuous run counts: the first
  * declined to run, the second ran and verified nothing, and neither is evidence

package/dist/adapters/claude-code/run-scripts.js

@@ -22,9 +22,10 @@ exports.formatScriptSummary = formatScriptSummary;
  * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
  */
 const node_child_process_1 = require("node:child_process");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
+const node_os_2 = require("node:os");
 const glob_1 = require("glob");
 const check_count_js_1 = require("../../check-count.js");
 /**
@@ -178,42 +179,95 @@ function readCheckReport(path) {
  * record them (`.vigiles/coverage.json`) and coverage can answer "tested?" from
  * execution rather than from a matching file name.
  */
-function runScripts(files, cwd, env = {}, opts = {}) {
+async function runScripts(files, cwd, env = {}, opts = {}) {
     const caps = (0, ts_runner_caps_js_2.detectNodeCaps)(cwd);
-    const results = [];
-    const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-checks-"));
-    try {
-        files.forEach((file, i) => {
-            let argv;
-            try {
-                argv = interpreterArgs(file, caps, opts.entry);
-            }
-            catch (e) {
-                console.error(`✗ ${file}: ${e.message}`);
-                results.push({ file, code: 1, status: "fail" });
-                return;
-            }
-            const countFile = (0, node_path_1.join)(countDir, `${String(i)}.count`);
-            const res = (0, node_child_process_1.spawnSync)("node", argv, {
-                cwd,
-                stdio: "inherit",
-                env: { ...process.env, ...env, [check_count_js_1.CHECK_COUNT_ENV]: countFile },
-            });
-            const code = res.status ?? 1;
+    const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_2.tmpdir)(), "vigiles-checks-"));
+    // 🔴 THE DEFAULT IS DECIDED BY `entry`, NOT BY A FLAG, because the two commands
+    // that share this runner have OPPOSITE right answers and the caller already
+    // distinguishes them:
+    //
+    //   `test` passes no entry — every script is a `*.harness.*` file, which is free
+    //   and deterministic BY CONSTRUCTION (the harness tier drives the agent CLI
+    //   against a mock model with no API key, and anything that spends money lives
+    //   behind `vigiles/eval` with a `paid_` prefix). Nothing here can bill, so the
+    //   only reason to serialize was that we always had.
+    //
+    //   `eval` passes an entry — every script spends real model quota. Running those
+    //   N-at-a-time multiplies spend and collides with rate limits, so it stays at 1.
+    //
+    // Measured motivation: 48 harness files in one consumer repo took 1m48s in CI as
+    // a strict queue, on a runner with cores sitting idle.
+    const parallel = Math.max(1, opts.concurrency ?? (opts.entry ? 1 : Math.min(8, (0, node_os_1.availableParallelism)())));
+    // Output is BUFFERED per child and printed when that child exits, rather than
+    // inherited. This is the real cost of concurrency and the reason it was not
+    // free: with `stdio: "inherit"` two children write to the same terminal at once
+    // and 48 reports shred into each other. Buffering keeps each report whole and
+    // attributable; what it gives up is live streaming, which only matters when one
+    // script is slow AND alone — i.e. exactly the `eval` case, where parallel is 1
+    // and the buffer is flushed as soon as the single child ends anyway.
+    const runOne = (file, i) => new Promise((resolveRun) => {
+        let argv;
+        try {
+            argv = interpreterArgs(file, caps, opts.entry);
+        }
+        catch (e) {
+            console.error(`✗ ${file}: ${e.message}`);
+            resolveRun({ file, code: 1, status: "fail" });
+            return;
+        }
+        const countFile = (0, node_path_1.join)(countDir, `${String(i)}.count`);
+        const child = (0, node_child_process_1.spawn)("node", argv, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, ...env, [check_count_js_1.CHECK_COUNT_ENV]: countFile },
+        });
+        const chunks = [];
+        child.stdout.on("data", (c) => chunks.push(c));
+        child.stderr.on("data", (c) => chunks.push(c));
+        const finish = (code) => {
+            process.stdout.write(Buffer.concat(chunks));
             const report = readCheckReport(countFile);
-            results.push({
+            resolveRun({
                 file,
                 code,
                 status: statusFor(code, report?.checks),
                 checks: report?.checks,
                 ...(report ? { surfaces: report.surfaces } : {}),
             });
+        };
+        // `error` fires when the process could not be spawned at all; without this
+        // the promise would never settle and the whole run would hang silently —
+        // which is worse than any failure it could report.
+        child.on("error", (e) => {
+            chunks.push(Buffer.from(`✗ ${file}: ${e.message}\n`));
+            finish(1);
+        });
+        child.on("close", (code) => {
+            finish(code ?? 1);
         });
+    });
+    try {
+        // Results are stored BY INDEX so the reported order is the discovery order,
+        // whatever order the children happen to finish in. A run whose output reorders
+        // itself between invocations reads as flaky even when every result is stable.
+        const results = new Array(files.length);
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= files.length)
+                    return;
+                results[i] = await runOne(files[i], i);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(parallel, files.length) }, () => {
+            return worker();
+        }));
+        return results;
     }
     finally {
         (0, node_fs_1.rmSync)(countDir, { recursive: true, force: true });
     }
-    return results;
 }
 /**
  * Whether any script FAILED. Neither a skip nor a vacuous run counts: the first

package/dist/cli.js

@@ -1141,7 +1141,23 @@ async function runLint(restArgs, flags, config) {
     // `<!-- vigiles:ignore-file -->` (whole file). Same engine as spec.ts.
     if (!silent)
         console.log("\nMarkdown code block refs:\n");
-    const docRefReport = (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd() });
+    // 🔴 `config.exclude` REACHES THIS PASS. It did not, and that single omission is
+    // why `lint` could not exit 0 on a repository that vendors other people's
+    // markdown: this walker globs `**/*.md` from the repo root, so a third-party
+    // `CLAUDE.md` captured verbatim as benchmark data was held to the same ref
+    // validation as the repo's own docs — and the one config field documented to
+    // stop exactly that ("vendored or benchmark fixtures the repo's own lint
+    // shouldn't police") was never handed over.
+    //
+    // Measured on a consumer repo 2026-08-19: 9 broken refs, 8 of them inside a
+    // directory the user had explicitly listed in `exclude`, all 9 still reported.
+    // With no way to reach 0 the step was made `continue-on-error: true`, and a lint
+    // whose exit code is discarded gates nothing — after which hand-written CI steps
+    // grew to do the gating instead. One unpassed argument, that whole chain.
+    const docRefReport = (0, doc_refs_js_1.findDocRefs)({
+        basePath: process.cwd(),
+        ignore: config?.exclude,
+    });
     if (!silent) {
         for (const line of (0, doc_refs_js_1.formatDocRefReport)(docRefReport).split("\n")) {
             console.log(`  ${line}`);
@@ -4366,7 +4382,7 @@ async function handleRunScripts(kind, args, restArgs) {
     // An eval file DESCRIBES its eval; `dist/eval-entry.js` is what imports the
     // description and runs what it declares. A harness script is still its own
     // program (it is free, so "import spends money" never applied to it).
-    const results = (0, run_scripts_js_1.runScripts)(files, cwd, env, {
+    const results = await (0, run_scripts_js_1.runScripts)(files, cwd, env, {
         ...(kind === "eval" ? { entry: (0, node_path_1.resolve)(__dirname, "eval-entry.js") } : {}),
     });
     // Write down WHAT the run exercised, so `lint`/`audit` can answer "tested?"

package/dist/core/compile.js

@@ -5,6 +5,9 @@
  * Reads .spec.ts files, validates references, and produces
  * markdown instruction files with integrity hashes.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeHash = computeHash;
 exports.addHash = addHash;
@@ -25,6 +28,7 @@ exports.checkFileHash = checkFileHash;
 exports.adoptDiff = adoptDiff;
 const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const node_path_1 = require("node:path");
 const hash_js_1 = require("./hash.js");
 const integrity_js_1 = require("./integrity.js");
@@ -626,12 +630,52 @@ function collectSkillRefs(spec) {
  * argument-hint, tools). Default is `"claude-code"` so callers that pass no
  * dialect get byte-identical output to before.
  */
+/**
+ * A frontmatter scalar, quoted only when leaving it bare would not survive YAML.
+ *
+ * 🔴 WHY THIS EXISTS. `description: ${spec.description}` interpolated the value
+ * raw, so a description containing a colon-space — `"…измеряет, где замер врёт:
+ * неаналоги в выборке"` — emitted frontmatter that is not valid YAML. Measured
+ * 2026-08-19 on two real skills: right after `vigiles compile`, `skillContract()`
+ * reported `malformed: true` and `declared: []`. The file LOOKS like it declares
+ * `allowed-tools`; a strict parser reads nothing, so the skill silently inherits
+ * every tool the session grants.
+ *
+ * That is the exact defect `frontmatter-valid` exists to report — i.e. the
+ * blessed path produced the thing the product hunts for. Worse, it PUNISHED the
+ * fix: a human who quoted the value by hand got a hash mismatch on the next lint
+ * ("manually edited after compilation"), and recompiling silently reverted them.
+ *
+ * The test is a ROUND TRIP rather than a list of dangerous characters: emit it,
+ * read it back with the same loader the linter uses, and quote only if what comes
+ * back is not the string that went in. Consequences of that choice:
+ *   - a value that was already safe is emitted byte-identically, so no existing
+ *     compiled file churns and no integrity hash moves;
+ *   - the set of "dangerous" inputs never has to be enumerated or maintained —
+ *     YAML itself decides, so `#`, `[`, `&`, `*`, leading/trailing space, `yes`,
+ *     `null` and everything else are covered without being listed.
+ */
+function yamlScalar(value) {
+    try {
+        const parsed = js_yaml_1.default.load(`v: ${value}`);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            parsed.v === value) {
+            return value;
+        }
+    }
+    catch {
+        // Did not parse at all — definitively needs quoting.
+    }
+    // A JSON string IS a YAML double-quoted scalar, escaping included.
+    return JSON.stringify(value);
+}
 function renderSkillFrontmatter(spec, profile = "claude-code") {
     const fm = [
         "---",
         "",
-        `name: ${spec.name}`,
-        `description: ${spec.description}`,
+        `name: ${yamlScalar(spec.name)}`,
+        `description: ${yamlScalar(spec.description)}`,
     ];
     // The CC-only keys below are inert in a minimal (Codex/OpenCode) SKILL.md, so
     // they're omitted entirely under that profile.
@@ -645,7 +689,7 @@ function renderSkillFrontmatter(spec, profile = "claude-code") {
             ? renderArgumentHint(spec.inputs)
             : spec.argumentHint;
         if (argHint)
-            fm.push(`argument-hint: ${argHint}`);
+            fm.push(`argument-hint: ${yamlScalar(argHint)}`);
         if (spec.tools && spec.tools.length > 0) {
             // A Claude Code SKILL declares its tool contract under `allowed-tools`
             // (NOT `tools:` — that's the SUBAGENT key), as a real YAML sequence. Flow
@@ -839,11 +883,14 @@ function validateAgentTools(tools, dialect) {
 }
 /** Build the subagent YAML frontmatter (name / description / model / tools). */
 function renderAgentFrontmatter(spec) {
+    // Same round-trip quoting as the skill renderer — a subagent description is
+    // written just as freely and breaks its frontmatter the same way. See
+    // {@link yamlScalar}.
     const fm = [
         "---",
         "",
-        `name: ${spec.name}`,
-        `description: ${spec.description}`,
+        `name: ${yamlScalar(spec.name)}`,
+        `description: ${yamlScalar(spec.description)}`,
     ];
     if (spec.model !== undefined)
         fm.push(`model: ${spec.model}`);

package/dist/core/description-overlap.d.ts

@@ -2,9 +2,21 @@
 export interface DescribedSurface {
     readonly name: string;
     readonly description: string;
+    /**
+     * Repo-relative path to report the surface at. Optional for callers that have
+     * no path, but REQUIRED in practice to keep the message actionable: since the
+     * loader started reading BOTH discovery levels, a repo that keeps a copy of a
+     * skill in `skills/` and `.claude/skills/` yields two surfaces with the SAME
+     * name, and "skills \"dup\" and \"dup\" have near-identical descriptions" names
+     * neither file. Measured on `nyldn/claude-octopus`: 50 such pairs. The path is
+     * the only thing that distinguishes them.
+     */
+    readonly where?: string;
 }
 export interface DescriptionOverlap {
+    /** Display label for the first skill — `"name"`, or `"name" (path)`. */
     readonly a: string;
+    /** Display label for the second skill — `"name"`, or `"name" (path)`. */
     readonly b: string;
     /** 0–1, higher = more alike (1 − NCD), rounded to 2 dp. */
     readonly similarity: number;
@@ -17,11 +29,5 @@ export interface DescriptionOverlap {
  * the calibrated value.
  */
 export declare const OVERLAP_NCD_CUTOFF = 0.2;
-/**
- * Find near-duplicate description pairs among `surfaces`. Returns one
- * {@link DescriptionOverlap} per pair whose NCD is below `cutoff`, most-similar
- * first. Pure; pass only the surfaces that actually compete for auto-selection
- * (model-invocable, described) so a user-invoked pair isn't a false alarm.
- */
 export declare function findDescriptionOverlaps(surfaces: readonly DescribedSurface[], cutoff?: number): DescriptionOverlap[];
 //# sourceMappingURL=description-overlap.d.ts.map

package/dist/core/description-overlap.js

@@ -31,6 +31,10 @@ exports.OVERLAP_NCD_CUTOFF = 0.2;
  * first. Pure; pass only the surfaces that actually compete for auto-selection
  * (model-invocable, described) so a user-invoked pair isn't a false alarm.
  */
+/** `"name"`, or `"name" (path)` when the caller supplied one. */
+function label(s) {
+    return s.where === undefined ? `"${s.name}"` : `"${s.name}" (${s.where})`;
+}
 function findDescriptionOverlaps(surfaces, cutoff = exports.OVERLAP_NCD_CUTOFF) {
     const overlaps = [];
     for (let i = 0; i < surfaces.length; i++) {
@@ -38,13 +42,13 @@ function findDescriptionOverlaps(surfaces, cutoff = exports.OVERLAP_NCD_CUTOFF)
             const d = (0, ncd_js_1.ncd)(surfaces[i].description, surfaces[j].description);
             if (d >= cutoff)
                 continue;
-            const a = surfaces[i].name;
-            const b = surfaces[j].name;
+            const a = label(surfaces[i]);
+            const b = label(surfaces[j]);
             overlaps.push({
                 a,
                 b,
                 similarity: Math.round((1 - d) * 100) / 100,
-                message: `skills "${a}" and "${b}" have near-identical descriptions (${String(Math.round((1 - d) * 100))}% alike) — the model can't reliably tell them apart, so the wrong one may fire. Differentiate their descriptions.`,
+                message: `skills ${a} and ${b} have near-identical descriptions (${String(Math.round((1 - d) * 100))}% alike) — the model can't reliably tell them apart, so the wrong one may fire. Differentiate their descriptions.`,
             });
         }
     }

package/dist/core/doc-refs.js

@@ -18,11 +18,15 @@
  * in markdown is explicitly out of scope — use eslint-plugin-markdown or
  * twoslash for that.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractDocRefs = extractDocRefs;
 exports.findDocRefs = findDocRefs;
 exports.formatDocRefReport = formatDocRefReport;
 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 linters_js_1 = require("./linters.js");
@@ -44,7 +48,7 @@ const TS_LANGS = new Set(["ts", "typescript", "js", "javascript"]);
 // doesn't accidentally disable validation.
 const IGNORE_BLOCK_RE = /^\s{0,3}<!--\s*vigiles:ignore\s*-->\s*$/;
 const IGNORE_FILE_RE = /^\s{0,3}<!--\s*vigiles:ignore-file\s*-->\s*$/m;
-const CALL_RE = /\b(enforce|file|cmd|ref)\(\s*["']([^"'\n]+)["']/g;
+const KINDS = new Set(["enforce", "file", "cmd", "ref"]);
 const PLACEHOLDER_RE = /[<>]/;
 /**
  * Error-message patterns that mean "tool not available in this env" rather
@@ -57,6 +61,66 @@ const UNVERIFIABLE_PATTERNS = [
     /not found on PATH/i,
     /No Cedar policies found/i,
 ];
+/**
+ * The builder calls in one fenced block, found by PARSING it rather than by
+ * matching text.
+ *
+ * 🔴 WHY THIS IS NOT A REGEX ANY MORE. The previous form was
+ * `/\b(enforce|file|cmd|ref)\(\s*["']([^"'\n]+)["']/g`, and four of these six
+ * inputs were classified wrongly (measured 2026-08-19):
+ *
+ *   ctx.file("OUT")          → matched, though it is a method on some other
+ *                              object. A live instance of this sat in a real
+ *                              repository's notes and was reported as a broken
+ *                              ref for weeks.
+ *   obj.cmd("npm test")      → matched, same reason
+ *   // cmd("npm test")       → matched, though it is a comment
+ *   const s = 'cmd("x")'     → matched, though it is a string
+ *   myFile("x")              → correctly skipped
+ *   cmd("npm test")          → correctly matched
+ *
+ * `\b` sits happily after a `.`, so every member call read as a builder call,
+ * and a regex has no notion of comments or string literals at all. Parsing makes
+ * all four INEXPRESSIBLE rather than individually patched: the AST only offers a
+ * call whose callee is a bare identifier, and comments and string bodies are not
+ * call expressions in the first place.
+ *
+ * `typescript` is already a runtime dependency of this package, so this costs no
+ * new install — the parser was in the box the whole time.
+ */
+function callsIn(blockLines, file) {
+    if (blockLines.length === 0)
+        return [];
+    const src = blockLines.map((b) => b.text).join("\n");
+    const firstLine = blockLines[0].lineNo;
+    const sf = typescript_1.default.createSourceFile("block.ts", src, typescript_1.default.ScriptTarget.Latest, 
+    /* setParentNodes */ true, typescript_1.default.ScriptKind.TS);
+    const out = [];
+    const visit = (node) => {
+        if (typescript_1.default.isCallExpression(node) && typescript_1.default.isIdentifier(node.expression)) {
+            const kind = node.expression.text;
+            if (KINDS.has(kind)) {
+                const arg = node.arguments[0];
+                // Only a plain string literal is a ref we can resolve. A template with
+                // substitutions, a variable, or a computed value is not something this
+                // pass can check, and guessing at it is how false reports start.
+                if (arg &&
+                    (typescript_1.default.isStringLiteral(arg) || typescript_1.default.isNoSubstitutionTemplateLiteral(arg))) {
+                    const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                    out.push({
+                        file,
+                        line: firstLine + line,
+                        kind: kind,
+                        value: arg.text,
+                    });
+                }
+            }
+        }
+        typescript_1.default.forEachChild(node, visit);
+    };
+    visit(sf);
+    return out;
+}
 /** @internal */ function extractDocRefs(content, file) {
     const lines = content.split("\n");
     const refs = [];
@@ -88,16 +152,7 @@ const UNVERIFIABLE_PATTERNS = [
                         blocksIgnored++;
                     }
                     else {
-                        for (const { lineNo, text } of blockLines) {
-                            for (const m of text.matchAll(CALL_RE)) {
-                                refs.push({
-                                    file,
-                                    line: lineNo,
-                                    kind: m[1],
-                                    value: m[2],
-                                });
-                            }
-                        }
+                        refs.push(...callsIn(blockLines, file));
                     }
                 }
                 fenceChar = null;

package/dist/core/surface-scopes.d.ts

@@ -0,0 +1,110 @@
+/**
+ * WHERE a repo's model surfaces (skills/agents/commands) live — and the key each
+ * one is materialized under.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE LOADER USED TO CHOOSE. It read the repo-root
+ * `skills/` **or** the project-level `.claude/skills/` — never both — and
+ * materialized whichever it picked under the SAME canonical
+ * `<materializeRoot>/<surface>/…` key. Two real files, one key: the loser was
+ * never read, and the winner's content sat under the loser's name. Measured
+ * 2026-08-18 on `nyldn/claude-octopus` (pinned corpus): **50 skill names exist in
+ * both `skills/` and `.claude/skills/`, and all 50 pairs differ** — the `.claude/`
+ * copies carry multi-line unquoted `description:` blocks that a strict YAML
+ * loader rejects. vigiles reported those fifty skills as clean without ever
+ * having opened the files it named.
+ *
+ * The vendor settles it — Claude Code loads BOTH, in two namespaces:
+ *
+ * > Plugin skills use a `plugin-name:skill-name` namespace, so they can't
+ * > conflict with other levels.
+ * > For example, `my-plugin/skills/deploy/SKILL.md` becomes `/my-plugin:deploy`
+ * > and loads alongside a `deploy` skill in your project's `.claude/skills/`.
+ * > — https://code.claude.com/docs/en/skills § "Where skills live"
+ *
+ * So "pick one" was never a tie-break to get right; it was a question that has no
+ * answer, asked because the key shape forced one. The fix removes the question:
+ * every scope present is read, and **a scope's key prefix is derived from the
+ * scope, not from a winner**, so two files can no longer claim one key.
+ *
+ * Node-free and IO-free on purpose: the disk loader (`src/plugin-loader.ts`) and
+ * the browser file-map twin (`src/scan-files.ts`) each probe their own storage
+ * and call THIS for the decision, so the pair that this repo has repeatedly been
+ * bitten by fixing on one side only cannot disagree about scoping.
+ */
+import type { PluginLayout } from "./layout.js";
+/**
+ * One discovery level, and the prefix its files are materialized under.
+ *
+ * `base` is the repo-relative dir the surfaces really live under (`""` = the repo
+ * root, the published-plugin shape; `.claude` = the plain-user project shape).
+ * `materializeUnder` is the prefix prepended to `<surface>/<rel>` to form the
+ * `LoadedPlugin.files` key.
+ */
+export interface SurfaceScope {
+    /** Repo-relative dir holding `<surface>/…`; `""` for the repo root. */
+    readonly base: string;
+    /** Key prefix for this scope's files; `""` for none. */
+    readonly materializeUnder: string;
+    /** Human label for warnings — `plugin` (root) or `project` (`.claude/`). */
+    readonly label: string;
+}
+/** Which shape the audited target is, and every scope to read from it. */
+export type SurfaceSource = {
+    readonly kind: "single-skill";
+    readonly skillName: string;
+} | {
+    readonly kind: "scopes";
+    readonly scopes: readonly SurfaceScope[];
+};
+/** What the caller must probe on its own storage for {@link surfaceSource}. */
+export interface SurfaceProbe {
+    /** A `<root>/SKILL.md` exists — the target IS one skill dir. */
+    readonly hasRootSkillFile: boolean;
+    /** Name to give that single skill (the target dir's basename). */
+    readonly skillName: string;
+    /** Some `<root>/<surface>/` holds a loadable file. */
+    readonly rootHasLoadable: boolean;
+    /** A plugin manifest or the hooks convention path exists. */
+    readonly isPluginShaped: boolean;
+    /** Some `<root>/<userSurfaceRoot>/<surface>/` holds a loadable file. */
+    readonly userHasLoadable: boolean;
+}
+/**
+ * Classify the target and list every scope to read, HIGHEST-PRECEDENCE FIRST.
+ *
+ * Precedence decides only one thing: which scope keeps the canonical
+ * `<materializeRoot>/…` key. The project scope takes it, because that key IS
+ * where a project skill lives — `.claude/skills/deploy/SKILL.md` is loaded from
+ * exactly that path and answers to `/deploy`. A plugin scope keeps its own real
+ * location (`skills/deploy/SKILL.md`), which is likewise where the harness reads
+ * it from, under `/plugin:deploy`. Nothing is relocated on top of something else.
+ *
+ * 🔴 THE COLLISION IS STRUCTURAL, NOT CHECKED. Only the FIRST scope is relocated;
+ * every later one keeps `base` as its prefix. Since the first scope is the only
+ * one that can produce a `<materializeRoot>/…` key, and every other prefix is a
+ * distinct real directory, two scopes cannot mint the same key — there is no
+ * ordering, no "if already taken", and no last-write-wins to get wrong.
+ * {@link assertDistinctScopeKeys} is the LOUD backstop for a future
+ * `PluginLayout` that breaks the premise (e.g. one naming `.claude` as BOTH its
+ * `materializeRoot` and a second scope's base).
+ */
+export declare function surfaceSource(layout: PluginLayout, probe: SurfaceProbe): SurfaceSource;
+/** The `LoadedPlugin.files` key for one file under one scope. */
+export declare function scopeKey(scope: SurfaceScope, surface: string, rel: string): string;
+/**
+ * Throw when two scopes would mint the same key prefix. Unreachable for every
+ * shipped layout (see {@link surfaceSource}) — it exists so a NEW layout that
+ * breaks the premise fails loudly at load, rather than silently dropping a
+ * surface file the way the shadowing bug did for a year.
+ */
+export declare function assertDistinctScopeKeys(scopes: readonly SurfaceScope[], layoutName: string): void;
+/**
+ * The warning to emit when more than one scope is present. Both scopes load in a
+ * real session under DIFFERENT names, but the deterministic sandbox is a project
+ * dir — it registers the project scope only, so a plugin-scope skill sitting at
+ * `skills/…` in the fixture never activates there (the footgun
+ * `unregisteredSkillFiles` already warns about for inline arm files). Say so,
+ * rather than quietly relocating one on top of the other.
+ */
+export declare function multiScopeWarning(scopes: readonly SurfaceScope[], counts: Record<string, number>): string | undefined;
+//# sourceMappingURL=surface-scopes.d.ts.map

package/dist/core/surface-scopes.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.surfaceSource = surfaceSource;
+exports.scopeKey = scopeKey;
+exports.assertDistinctScopeKeys = assertDistinctScopeKeys;
+exports.multiScopeWarning = multiScopeWarning;
+/**
+ * Classify the target and list every scope to read, HIGHEST-PRECEDENCE FIRST.
+ *
+ * Precedence decides only one thing: which scope keeps the canonical
+ * `<materializeRoot>/…` key. The project scope takes it, because that key IS
+ * where a project skill lives — `.claude/skills/deploy/SKILL.md` is loaded from
+ * exactly that path and answers to `/deploy`. A plugin scope keeps its own real
+ * location (`skills/deploy/SKILL.md`), which is likewise where the harness reads
+ * it from, under `/plugin:deploy`. Nothing is relocated on top of something else.
+ *
+ * 🔴 THE COLLISION IS STRUCTURAL, NOT CHECKED. Only the FIRST scope is relocated;
+ * every later one keeps `base` as its prefix. Since the first scope is the only
+ * one that can produce a `<materializeRoot>/…` key, and every other prefix is a
+ * distinct real directory, two scopes cannot mint the same key — there is no
+ * ordering, no "if already taken", and no last-write-wins to get wrong.
+ * {@link assertDistinctScopeKeys} is the LOUD backstop for a future
+ * `PluginLayout` that breaks the premise (e.g. one naming `.claude` as BOTH its
+ * `materializeRoot` and a second scope's base).
+ */
+function surfaceSource(layout, probe) {
+    if (layout.skillDir && probe.hasRootSkillFile) {
+        return { kind: "single-skill", skillName: probe.skillName };
+    }
+    const scopes = [];
+    if (layout.userSurfaceRoot !== undefined && probe.userHasLoadable) {
+        scopes.push({
+            base: layout.userSurfaceRoot,
+            materializeUnder: layout.materializeRoot,
+            label: "project",
+        });
+    }
+    if (probe.rootHasLoadable || probe.isPluginShaped) {
+        scopes.push({
+            base: "",
+            materializeUnder: scopes.length === 0 ? layout.materializeRoot : "",
+            label: "plugin",
+        });
+    }
+    // A layout with no user root and nothing at the root still has to read the
+    // project shape, or a plain repo would load as an empty machine — the reason
+    // `userSurfaceRoot` exists. An empty list means genuinely nothing loadable.
+    if (scopes.length === 0 && layout.userSurfaceRoot !== undefined) {
+        scopes.push({
+            base: layout.userSurfaceRoot,
+            materializeUnder: layout.materializeRoot,
+            label: "project",
+        });
+    }
+    return { kind: "scopes", scopes };
+}
+/** The `LoadedPlugin.files` key for one file under one scope. */
+function scopeKey(scope, surface, rel) {
+    return [scope.materializeUnder, surface, rel]
+        .filter((s) => s !== "")
+        .join("/");
+}
+/**
+ * Throw when two scopes would mint the same key prefix. Unreachable for every
+ * shipped layout (see {@link surfaceSource}) — it exists so a NEW layout that
+ * breaks the premise fails loudly at load, rather than silently dropping a
+ * surface file the way the shadowing bug did for a year.
+ */
+function assertDistinctScopeKeys(scopes, layoutName) {
+    const seen = new Map();
+    for (const s of scopes) {
+        const prev = seen.get(s.materializeUnder);
+        if (prev !== undefined) {
+            throw new Error(`layout "${layoutName}": surface scopes "${prev}" and "${s.base}" both materialize under ` +
+                `"${s.materializeUnder || "<repo root>"}" — one would silently shadow the other. ` +
+                `Give each scope a distinct materialize prefix (see src/core/surface-scopes.ts).`);
+        }
+        seen.set(s.materializeUnder, s.base);
+    }
+}
+/**
+ * The warning to emit when more than one scope is present. Both scopes load in a
+ * real session under DIFFERENT names, but the deterministic sandbox is a project
+ * dir — it registers the project scope only, so a plugin-scope skill sitting at
+ * `skills/…` in the fixture never activates there (the footgun
+ * `unregisteredSkillFiles` already warns about for inline arm files). Say so,
+ * rather than quietly relocating one on top of the other.
+ */
+function multiScopeWarning(scopes, counts) {
+    if (scopes.length < 2)
+        return undefined;
+    const total = Object.values(counts).reduce((a, b) => a + b, 0);
+    return (`repo carries surfaces at TWO discovery levels (${scopes
+        .map((s) => `${s.label} → ${s.base === "" ? "<repo root>" : s.base}/`)
+        .join(", ")}); ${String(total)} file(s) were read from both. Claude Code loads both — ` +
+        `a plugin skill as \`/<plugin>:<name>\`, a project skill as \`/<name>\` — so a name in both ` +
+        `places is TWO surfaces, not one. The deterministic sandbox is a project dir and registers ` +
+        `the project scope only; install the plugin scope with \`pluginDir\` to exercise it.`);
+}
+//# sourceMappingURL=surface-scopes.js.map

package/dist/plugin-loader.js

@@ -39,6 +39,7 @@ const toml_1 = require("@iarna/toml");
 const hash_js_1 = require("./core/hash.js");
 const fs_walk_js_1 = require("./fs-walk.js");
 const source_refs_js_1 = require("./core/source-refs.js");
+const surface_scopes_js_1 = require("./core/surface-scopes.js");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
 /** Parse a JSON file, or null on any error (missing / malformed). */
 function safeReadJson(path) {
@@ -177,19 +178,35 @@ function loadPlugin(pluginPath, layout) {
         files[layout.instructionFile] = (0, node_fs_1.readFileSync)(instructions, "utf-8");
         sources[layout.instructionFile] = instructions;
     }
-    const counts = materializeSurfaces(root, layout, files, sources);
+    const surfaces = materializeSurfaces(root, layout, files, sources);
     return {
         settings: resolvedHooks ? { hooks: resolvedHooks } : {},
         files,
         sources,
-        warnings: pluginWarnings(root, counts, resolvedHooks, files, layout),
+        warnings: pluginWarnings(root, surfaces, resolvedHooks, files, layout),
     };
 }
+/**
+ * Materialize every model surface (skills/agents/commands) into `files`, and
+ * record each file's real on-disk path in `sources`. Best-effort (headless
+ * activation of plugin skills/subagents/commands is not guaranteed; the body is
+ * present to read).
+ *
+ * EVERY discovery level present is read — the repo-root `<surface>` (the
+ * published-plugin / skills-library shape) AND the project-level
+ * `<userSurfaceRoot>/<surface>` (the shape a plain Claude Code user has). The
+ * loader used to read one OR the other and materialize the winner under the
+ * loser's canonical key; `src/core/surface-scopes.ts` carries the measurement
+ * that killed that, and the vendor quote that settles which one the harness
+ * loads (both, in different namespaces). The KEY now comes from the scope, so
+ * two files can no longer claim one. Plus the single-skill-directory case
+ * (`<root>/SKILL.md`), so pointing at one skill dir works. Returns the
+ * per-surface counts (drives the surface warnings).
+ */
 /**
  * A surface holds a LOADABLE file — a `<name>/SKILL.md` for skills, a `.md` for
  * agents/commands. A stray non-surface file (`skills/README.md`, `.gitkeep`) does
- * NOT count, else it would mark the root populated and shadow a plain user's real
- * `.claude/skills`.
+ * NOT count, else an empty-but-present dir would mark a scope populated.
  */
 function surfaceHasLoadable(layout, surface, tree) {
     const keys = Object.keys(tree);
@@ -197,30 +214,6 @@ function surfaceHasLoadable(layout, surface, tree) {
         ? keys.some((k) => (0, node_path_1.basename)(k) === "SKILL.md")
         : keys.some((k) => k.endsWith(".md"));
 }
-/**
- * Classify the repo shape from disk, with EXPLICIT precedence:
- *  1. a `<root>/SKILL.md` → the target IS one skill dir (single-skill).
- *  2. any root-surface with LOADABLE content, OR a plugin manifest / hooks
- *     convention → read the ROOT surfaces. A plugin ships from its manifest even
- *     with no root surface dirs, so its dev `.claude/…` is never a fallback.
- *  3. else, if the layout declares a user-surface root → a plain user repo.
- *  4. else → nothing loadable.
- * Pure over the pre-read `rootTrees` + a few existence checks — one place to test.
- */
-function classifySurfaceSource(root, layout, rootTrees) {
-    if (layout.skillDir && (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "SKILL.md"))) {
-        return { kind: "single-skill", skillName: (0, node_path_1.basename)(root) };
-    }
-    const rootHasLoadable = layout.surfaceDirs.some((s) => surfaceHasLoadable(layout, s, rootTrees.get(s) ?? {}));
-    const isPluginShaped = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.manifestPath)) ||
-        (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.hooksConventionPath));
-    if (rootHasLoadable || isPluginShaped)
-        return { kind: "root" };
-    if (layout.userSurfaceRoot !== undefined) {
-        return { kind: "user", sub: layout.userSurfaceRoot };
-    }
-    return { kind: "none" };
-}
 function materializeSurfaces(root, layout, files, sources) {
     const counts = {};
     const isDir = (p) => (0, node_fs_1.existsSync)(p) && (0, node_fs_1.statSync)(p).isDirectory();
@@ -234,15 +227,41 @@ function materializeSurfaces(root, layout, files, sources) {
      * outside is still read.
      */
     const surfaceTree = (dir) => isDir(dir) && (0, fs_walk_js_1.walkableRoot)(dir, root) ? readTree(dir, dir) : {};
-    // Read each ROOT-level surface tree once (keys relative to the surface dir).
-    const rootTrees = new Map();
-    for (const surface of layout.surfaceDirs)
-        rootTrees.set(surface, surfaceTree((0, node_path_1.join)(root, surface)));
+    /** Every surface tree of one scope, read once, keyed by surface dir. */
+    const scopeTrees = (base) => {
+        const trees = new Map();
+        for (const surface of layout.surfaceDirs)
+            trees.set(surface, surfaceTree((0, node_path_1.join)(root, base, surface)));
+        return trees;
+    };
+    const hasLoadable = (trees) => layout.surfaceDirs.some((s) => surfaceHasLoadable(layout, s, trees.get(s) ?? {}));
     const add = (key, content, onDisk) => {
         files[key] = content;
         sources[key] = onDisk;
     };
-    const source = classifySurfaceSource(root, layout, rootTrees);
+    // Both candidate scopes are read ONCE, up front, because the decision needs to
+    // know whether each holds anything — and then the same trees are materialized.
+    const rootTrees = scopeTrees("");
+    const userTrees = layout.userSurfaceRoot !== undefined
+        ? scopeTrees(layout.userSurfaceRoot)
+        : new Map();
+    /** Copy one scope's already-read trees into `files`, keyed by that scope. */
+    const materializeScope = (scope, trees) => {
+        for (const surface of layout.surfaceDirs) {
+            const tree = trees.get(surface) ?? {};
+            for (const [rel, content] of Object.entries(tree))
+                add((0, surface_scopes_js_1.scopeKey)(scope, surface, rel), content, (0, node_path_1.join)(root, scope.base, surface, rel));
+            counts[surface] = (counts[surface] ?? 0) + Object.keys(tree).length;
+        }
+    };
+    const source = (0, surface_scopes_js_1.surfaceSource)(layout, {
+        hasRootSkillFile: (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "SKILL.md")),
+        skillName: (0, node_path_1.basename)(root),
+        rootHasLoadable: hasLoadable(rootTrees),
+        isPluginShaped: (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.manifestPath)) ||
+            (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.hooksConventionPath)),
+        userHasLoadable: hasLoadable(userTrees),
+    });
     switch (source.kind) {
         case "single-skill": {
             // Materialize the WHOLE skill dir under the canonical skills key, so its
@@ -255,31 +274,18 @@ function materializeSurfaces(root, layout, files, sources) {
                 add((0, node_path_1.join)(layout.materializeRoot, layout.skillDir, source.skillName, rel), content, (0, node_path_1.join)(root, rel));
             }
             counts[layout.skillDir] = Object.keys(tree).length;
-            break;
+            return { counts, scopes: [] };
         }
-        case "root":
-        case "user": {
-            const base = source.kind === "user" ? (0, node_path_1.join)(root, source.sub) : root;
-            for (const surface of layout.surfaceDirs) {
-                const dir = (0, node_path_1.join)(base, surface);
-                // Root surfaces were pre-read; user surfaces are read fresh here.
-                const tree = source.kind === "root"
-                    ? (rootTrees.get(surface) ?? {})
-                    : surfaceTree(dir);
-                for (const [rel, content] of Object.entries(tree)) {
-                    add((0, node_path_1.join)(layout.materializeRoot, surface, rel), content, (0, node_path_1.join)(dir, rel));
-                }
-                counts[surface] = Object.keys(tree).length;
-            }
-            break;
+        case "scopes": {
+            (0, surface_scopes_js_1.assertDistinctScopeKeys)(source.scopes, layout.name);
+            for (const scope of source.scopes)
+                materializeScope(scope, scope.base === "" ? rootTrees : userTrees);
+            return { counts, scopes: source.scopes };
         }
-        case "none":
-            break;
         /* v8 ignore next 2 -- exhaustiveness guard, unreachable given SurfaceSource */
         default:
-            (0, hash_js_1.assertNever)(source);
+            return (0, hash_js_1.assertNever)(source);
     }
-    return counts;
 }
 /**
  * Flag surfaces present-but-not-deterministically-exercisable. Subagents
@@ -288,8 +294,11 @@ function materializeSurfaces(root, layout, files, sources) {
  * the eval tier. MCP servers aren't wired by the loader at all. And a plugin
  * that yields neither hooks nor files would otherwise be a silent empty machine.
  */
-function pluginWarnings(root, counts, hooks, files, layout) {
+function pluginWarnings(root, { counts, scopes }, hooks, files, layout) {
     const warnings = [];
+    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, counts);
+    if (multiScope !== undefined)
+        warnings.push(multiScope);
     if (counts.agents) {
         warnings.push(`plugin defines ${String(counts.agents)} subagent file(s) under agents/ — these run only under a real model; test them at the eval tier (runEval), not the deterministic mock.`);
     }

package/dist/scan-core.d.ts

@@ -109,7 +109,12 @@ export declare function skillRefSources(files: Record<string, string>, cls: Surf
     readonly root: string;
     readonly sources?: Record<string, string>;
 }): SkillRefSource[];
-export declare function descriptionOverlapsFor(files: Record<string, string>, cls: SurfaceClassifier): DescriptionOverlap[];
+/** Where a materialized key really lives — for reporting a surface by path. */
+export interface SurfacePathContext {
+    readonly root: string;
+    readonly sources?: Record<string, string>;
+}
+export declare function descriptionOverlapsFor(files: Record<string, string>, cls: SurfaceClassifier, where?: SurfacePathContext): DescriptionOverlap[];
 /**
  * Model-invocable skills whose description is so long the trigger signal is
  * buried (heuristic proxy; degrades recall + precision). Same surfaces as the

package/dist/scan-core.js

@@ -408,7 +408,7 @@ function skillRefSources(files, cls, ctx) {
  * logic as `scanSkills` (frontmatter `description` ← first body paragraph), then
  * the NCD precision-proxy. See description-overlap.ts.
  */
-function modelInvocableSkillSurfaces(files, cls) {
+function modelInvocableSkillSurfaces(files, cls, where) {
     const surfaces = [];
     for (const [path, md] of Object.entries(files)) {
         if (!cls.isSkill(path))
@@ -419,12 +419,24 @@ function modelInvocableSkillSurfaces(files, cls) {
         const description = fm.description ?? firstBodyParagraph(md);
         if (!description || description.length < 20)
             continue;
-        surfaces.push({ name: fm.name ?? skillName(path), description });
+        surfaces.push({
+            name: fm.name ?? skillName(path),
+            description,
+            // The NAME alone stopped identifying a surface once the loader began
+            // reading both discovery levels: a repo carrying `skills/x` AND
+            // `.claude/skills/x` has two skills called `x`. Report the real path
+            // (never the synthetic key) so the pair is actionable.
+            ...(where
+                ? {
+                    where: reportedSurfacePath(path, where.sources?.[path], where.root),
+                }
+                : {}),
+        });
     }
     return surfaces;
 }
-function descriptionOverlapsFor(files, cls) {
-    return (0, description_overlap_js_1.findDescriptionOverlaps)(modelInvocableSkillSurfaces(files, cls));
+function descriptionOverlapsFor(files, cls, where) {
+    return (0, description_overlap_js_1.findDescriptionOverlaps)(modelInvocableSkillSurfaces(files, cls, where));
 }
 /**
  * Model-invocable skills whose description is so long the trigger signal is
@@ -834,9 +846,31 @@ function collectDelegationTrifecta(agents, dialect) {
             delegatesTo: canDispatch ? allNames.filter((n) => n !== a.name) : [],
         };
     });
-    const pathByName = new Map(agents.map((a) => [a.name, a.path]));
+    // 🔴 A NAME IS NOT AN IDENTITY HERE, and this map used to assume it was.
+    // `new Map(agents.map((a) => [a.name, a.path]))` keeps the LAST entry for a
+    // repeated key, so when the same agent name exists in two discovery scopes —
+    // `agents/foo.md` and `.claude/agents/foo.md`, which Claude registers in
+    // DIFFERENT namespaces — a finding about the first was reported against the
+    // second's file. A lethal-trifecta finding that names the wrong file is worse
+    // than one that names none: it sends the reader to audit innocent code and
+    // leaves the real surface unexamined.
+    //
+    // Until identity is scope-qualified through the whole delegation pipeline (the
+    // proper fix, and a larger one — `finding.name` itself carries only the bare
+    // name), an ambiguous name resolves to NO path rather than to an arbitrary one.
+    // Nothing changes for the overwhelmingly common case of distinct names.
+    const pathByName = new Map();
+    const ambiguous = new Set();
+    for (const a of agents) {
+        if (pathByName.has(a.name))
+            ambiguous.add(a.name);
+        else
+            pathByName.set(a.name, a.path);
+    }
     return (0, delegation_trifecta_js_1.delegationTrifectaIssues)(nodes, dialect).map((finding) => ({
-        path: pathByName.get(finding.name) ?? "",
+        path: ambiguous.has(finding.name)
+            ? ""
+            : (pathByName.get(finding.name) ?? ""),
         finding,
     }));
 }

package/dist/scan-files.js

@@ -48,6 +48,7 @@ const mcp_config_js_1 = require("./core/mcp-config.js");
 const agent_plugins_js_1 = require("./core/agent-plugins.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
 const plugin_dir_layout_js_1 = require("./core/plugin-dir-layout.js");
+const surface_scopes_js_1 = require("./core/surface-scopes.js");
 const hook_block_ineffective_js_1 = require("./core/hook-block-ineffective.js");
 const hook_matcher_js_1 = require("./core/hook-matcher.js");
 const test_coverage_files_js_1 = require("./test-coverage-files.js");
@@ -209,49 +210,63 @@ function hasMcp(files, layout) {
         return true;
     return readManifest(files, layout)?.[layout.mcpManifestKey] !== undefined;
 }
-/** Mirror of plugin-loader.ts `surfaceHasLoadable`. */
+// ---------------------------------------------------------------------------
+// Surface materialization (mirrors plugin-loader.ts materializeSurfaces)
+// ---------------------------------------------------------------------------
+/**
+ * Mirror of plugin-loader.ts `surfaceHasLoadable`. The SCOPING DECISION itself is
+ * not mirrored — it lives once, IO-free, in `src/core/surface-scopes.ts`, and both
+ * engines call it. That pair used to be two copies of the same precedence rules,
+ * which is exactly the shape this repo keeps getting bitten by fixing on one side.
+ */
 function surfaceHasLoadable(layout, surface, tree) {
     const keys = Object.keys(tree);
     return surface === layout.skillDir
         ? keys.some((k) => (0, posix_path_js_1.basename)(k) === "SKILL.md")
         : keys.some((k) => k.endsWith(".md"));
 }
-/** Mirror of plugin-loader.ts `classifySurfaceSource`, over the file map. */
-function classifySurfaceSource(files, layout, rootTrees, repoName) {
-    if (layout.skillDir && hasFile(files, "SKILL.md")) {
-        // Disk mirrors the CLI: a nameless root SKILL.md takes the audited dir's
-        // basename. In-browser there's no real dir, so use the repo name when the
-        // caller (runAudit) supplies it, else the synthetic BROWSER_ROOT basename.
-        return {
-            kind: "single-skill",
-            skillName: repoName ?? (0, posix_path_js_1.basename)(exports.BROWSER_ROOT),
-        };
-    }
-    const rootHasLoadable = layout.surfaceDirs.some((s) => surfaceHasLoadable(layout, s, rootTrees.get(s) ?? {}));
-    const isPluginShaped = hasFile(files, layout.manifestPath) ||
-        hasFile(files, layout.hooksConventionPath);
-    if (rootHasLoadable || isPluginShaped)
-        return { kind: "root" };
-    if (layout.userSurfaceRoot !== undefined) {
-        return { kind: "user", sub: layout.userSurfaceRoot };
-    }
-    return { kind: "none" };
-}
 /** Mirror of plugin-loader.ts `materializeSurfaces`, over the file map. */
 function materializeSurfaces(files, layout, acc, repoName) {
     const { out, sources } = acc;
     const counts = {};
-    const rootTrees = new Map();
-    for (const surface of layout.surfaceDirs) {
-        if (isDirRel(files, surface)) {
-            rootTrees.set(surface, readTreeUnder(files, surface, surface));
+    const scopeTrees = (base) => {
+        const trees = new Map();
+        for (const surface of layout.surfaceDirs) {
+            const dirRel = base === "" ? surface : `${base}/${surface}`;
+            trees.set(surface, isDirRel(files, dirRel) ? readTreeUnder(files, dirRel, dirRel) : {});
         }
-    }
+        return trees;
+    };
+    const hasLoadable = (trees) => layout.surfaceDirs.some((s) => surfaceHasLoadable(layout, s, trees.get(s) ?? {}));
     const add = (key, content, onDisk) => {
         out[key] = content;
         sources[key] = onDisk;
     };
-    const source = classifySurfaceSource(files, layout, rootTrees, repoName);
+    const rootTrees = scopeTrees("");
+    const userTrees = layout.userSurfaceRoot !== undefined
+        ? scopeTrees(layout.userSurfaceRoot)
+        : new Map();
+    /** Mirror of the disk loader's `materializeScope`. */
+    const materializeScope = (scope, trees) => {
+        for (const surface of layout.surfaceDirs) {
+            const tree = trees.get(surface) ?? {};
+            const dirRel = scope.base === "" ? surface : `${scope.base}/${surface}`;
+            for (const [rel, content] of Object.entries(tree))
+                add((0, surface_scopes_js_1.scopeKey)(scope, surface, rel), content, (0, posix_path_js_1.join)(exports.BROWSER_ROOT, dirRel, rel));
+            counts[surface] = (counts[surface] ?? 0) + Object.keys(tree).length;
+        }
+    };
+    const source = (0, surface_scopes_js_1.surfaceSource)(layout, {
+        hasRootSkillFile: Boolean(layout.skillDir) && hasFile(files, "SKILL.md"),
+        // Disk mirrors the CLI: a nameless root SKILL.md takes the audited dir's
+        // basename. In-browser there's no real dir, so use the repo name when the
+        // caller (runAudit) supplies it, else the synthetic BROWSER_ROOT basename.
+        skillName: repoName ?? (0, posix_path_js_1.basename)(exports.BROWSER_ROOT),
+        rootHasLoadable: hasLoadable(rootTrees),
+        isPluginShaped: hasFile(files, layout.manifestPath) ||
+            hasFile(files, layout.hooksConventionPath),
+        userHasLoadable: hasLoadable(userTrees),
+    });
     switch (source.kind) {
         case "single-skill": {
             const tree = readTreeUnder(files, "", "");
@@ -259,29 +274,15 @@ function materializeSurfaces(files, layout, acc, repoName) {
                 add((0, posix_path_js_1.join)(layout.materializeRoot, layout.skillDir, source.skillName, rel), content, (0, posix_path_js_1.join)(exports.BROWSER_ROOT, rel));
             }
             counts[layout.skillDir] = Object.keys(tree).length;
-            break;
+            return { counts, scopes: [] };
         }
-        case "root":
-        case "user": {
-            const baseRel = source.kind === "user" ? source.sub : "";
-            for (const surface of layout.surfaceDirs) {
-                const dirRel = baseRel === "" ? surface : `${baseRel}/${surface}`;
-                const tree = source.kind === "root"
-                    ? (rootTrees.get(surface) ?? {})
-                    : isDirRel(files, dirRel)
-                        ? readTreeUnder(files, dirRel, dirRel)
-                        : {};
-                for (const [rel, content] of Object.entries(tree)) {
-                    add((0, posix_path_js_1.join)(layout.materializeRoot, surface, rel), content, (0, posix_path_js_1.join)(exports.BROWSER_ROOT, dirRel, rel));
-                }
-                counts[surface] = Object.keys(tree).length;
-            }
-            break;
+        case "scopes": {
+            (0, surface_scopes_js_1.assertDistinctScopeKeys)(source.scopes, layout.name);
+            for (const scope of source.scopes)
+                materializeScope(scope, scope.base === "" ? rootTrees : userTrees);
+            return { counts, scopes: source.scopes };
         }
-        case "none":
-            break;
     }
-    return counts;
 }
 // ---------------------------------------------------------------------------
 // Dangling intra-plugin refs (mirrors plugin-loader.ts danglingRefs)
@@ -368,8 +369,11 @@ function danglingRefs(files, layout, rootName) {
 // ---------------------------------------------------------------------------
 // Warnings (mirrors plugin-loader.ts pluginWarnings)
 // ---------------------------------------------------------------------------
-function pluginWarnings(files, layout, counts, hooks, materialized, rootName) {
+function pluginWarnings(files, layout, { counts, scopes }, hooks, materialized, rootName) {
     const warnings = [];
+    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, counts);
+    if (multiScope !== undefined)
+        warnings.push(multiScope);
     if (counts.agents) {
         warnings.push(`plugin defines ${String(counts.agents)} subagent file(s) under agents/ — these run only under a real model; test them at the eval tier (runEval), not the deterministic mock.`);
     }
@@ -411,12 +415,12 @@ function loadPluginFromFiles(files, layout, repoName) {
         out[layout.instructionFile] = instructionText;
         sources[layout.instructionFile] = (0, posix_path_js_1.join)(exports.BROWSER_ROOT, layout.instructionFile);
     }
-    const counts = materializeSurfaces(files, layout, { out, sources }, repoName);
+    const surfaces = materializeSurfaces(files, layout, { out, sources }, repoName);
     return {
         settings: resolvedHooks ? { hooks: resolvedHooks } : {},
         files: out,
         sources,
-        warnings: pluginWarnings(files, layout, counts, resolvedHooks, out, repoName ?? (0, posix_path_js_1.basename)(exports.BROWSER_ROOT)),
+        warnings: pluginWarnings(files, layout, surfaces, resolvedHooks, out, repoName ?? (0, posix_path_js_1.basename)(exports.BROWSER_ROOT)),
     };
 }
 // ---------------------------------------------------------------------------
@@ -536,7 +540,10 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
         skillMetaIssues: remap((0, scan_core_js_1.skillMetaIssuesFor)(loaded.files, cls)),
         mcpIssues: (0, mcp_config_js_1.verifyMcpServers)(mcpServers),
         mcpHookIssues: (0, mcp_hook_js_1.verifyMcpHookTargets)(loaded.settings.hooks, declaredServers, dialect),
-        descriptionOverlaps: (0, scan_core_js_1.descriptionOverlapsFor)(loaded.files, cls),
+        descriptionOverlaps: (0, scan_core_js_1.descriptionOverlapsFor)(loaded.files, cls, {
+            root: exports.BROWSER_ROOT,
+            sources: loaded.sources,
+        }),
         descriptionBudgetIssues: (0, scan_core_js_1.descriptionBudgetFor)(loaded.files, cls),
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,

package/dist/scan.js

@@ -219,7 +219,10 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         skillMetaIssues: remap((0, scan_core_js_1.skillMetaIssuesFor)(loaded.files, cls)),
         mcpIssues: (0, mcp_config_js_1.verifyMcpServers)(mcpServers),
         mcpHookIssues: (0, mcp_hook_js_1.verifyMcpHookTargets)(loaded.settings.hooks, declaredServers, dialect),
-        descriptionOverlaps: (0, scan_core_js_1.descriptionOverlapsFor)(loaded.files, cls),
+        descriptionOverlaps: (0, scan_core_js_1.descriptionOverlapsFor)(loaded.files, cls, {
+            root: (0, node_path_1.resolve)(dir),
+            sources: loaded.sources,
+        }),
         descriptionBudgetIssues: (0, scan_core_js_1.descriptionBudgetFor)(loaded.files, cls),
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,

package/dist/score-explainer.js

@@ -41,7 +41,10 @@ function overlapExplanations(report) {
         symptom: "wrong-skill-fires",
         cause: o.message,
         detector: "description-overlap",
-        fix: `Differentiate the descriptions of "${o.a}" and "${o.b}" (${o.similarity} similar) — the selector picks by description, so near-identical text makes it fire the wrong one.`,
+        // `o.a`/`o.b` are already display LABELS (quoted name, plus the file path
+        // when the caller had one) — a bare name is ambiguous now that both
+        // discovery levels are read and the same name can appear twice.
+        fix: `Differentiate the descriptions of ${o.a} and ${o.b} (${o.similarity} similar) — the selector picks by description, so near-identical text makes it fire the wrong one.`,
         confidence: "possible",
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "18.1.0",
+  "version": "18.1.2",
   "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",

package/skills/linter-docs/pylint.md

@@ -209,6 +209,8 @@ The module must be importable from `PYTHONPATH`. For a local checker, put it in
 
 ### vigiles enforce() reference
 
+<!-- vigiles:ignore -->
+
 ```typescript
 enforce(
   "pylint/no-direct-db-query",

package/skills/linter-docs/rubocop.md

@@ -209,6 +209,8 @@ Custom/NoDirectDbQuery:
 
 ### vigiles enforce() reference
 
+<!-- vigiles:ignore -->
+
 ```typescript
 enforce(
   "rubocop/Custom/NoDirectDbQuery",