vigiles 18.0.0 → 18.1.1

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

@@ -68,8 +68,11 @@ export type EmitFieldSchema = {
     readonly items: {
         readonly type: "string";
     };
+} | {
+    readonly type: "string";
+    readonly enum: readonly string[];
 };
-/** The `track` discriminator's schema — the only enum this surface emits. */
+/** The `track` discriminator's schema — the enum this module owns, not the author's. */
 export interface EmitTrackSchema {
     readonly type: "string";
     readonly enum: readonly ["ok", "err"];

package/dist/experimental-emit.js

@@ -62,6 +62,11 @@ const agent_result_js_1 = require("./adapters/claude-code/agent-result.js");
 /** The default tool name, when `options.name` is not given. */
 const DEFAULT_EMIT_TOOL = "emit_result";
 function fieldSchema(type) {
+    // An enum reaches the model as a JSON-Schema `enum`, which is the whole point: the
+    // permitted values travel WITH the tool definition instead of living in prose the
+    // model may or may not have read.
+    if (typeof type !== "string")
+        return { type: "string", enum: [...type] };
     switch (type) {
         case "string":
             return { type: "string" };
@@ -189,8 +194,41 @@ function isEmitCall(observed, name) {
  */
 function experimental_parseEmitted(toolCalls, contract, options = {}) {
     const name = options.name ?? DEFAULT_EMIT_TOOL;
-    const calls = toolCalls.filter((c) => isEmitCall(c.name, name));
+    const all = toolCalls.filter((c) => isEmitCall(c.name, name));
+    // 🔴 A CALL THAT ERRORED IS NOT AN EMISSION, AND USED TO PARSE AS ONE.
+    //
+    // Measured 2026-08-19: a permission-denied call carrying a perfectly valid payload
+    // returned `{"kind":"ok", …}`, because this function filtered by NAME and never looked
+    // at `ToolCall.isError` — a field that has been on the type all along. The call never
+    // reached the server; the reader reported success. That is the exact shape of defect
+    // this channel exists to remove from the fenced rail, reproduced inside the channel.
+    //
+    // Denial is not hypothetical: it is what a wrong `allowedTools` spelling produces, and
+    // MCP tool names mangle per host (`mcp__plugin_<plugin>_<server>__emit_result` on Claude
+    // Code, two segments on Codex), so mis-spelling it is the likely case, not the exotic one.
+    //
+    // The errored calls get their OWN branch rather than being dropped or counted, because
+    // all three collapses lie in a different direction:
+    //   - counting them → this defect, success for a call nobody received;
+    //   - dropping them silently → "no tool call in the run", which sends the reader to the
+    //     skill's instructions when the fault is in permissions;
+    //   - lumping them with "called twice" → a model that retries a denied call produces a
+    //     true signal under a false name. (Observed: two denials in one run.)
+    // A successful call ALONGSIDE a denied one is one successful emission; the denial is
+    // mentioned, not fatal, because the contract was in fact satisfied.
+    // `isError` is a required boolean on ToolCall, so truthiness is exact here.
+    const errored = all.filter((c) => c.isError);
+    const calls = all.filter((c) => !c.isError);
     if (calls.length === 0) {
+        if (errored.length > 0) {
+            return {
+                kind: "malformed",
+                reason: `the \`${name}\` call itself errored or was denied ` +
+                    `(${String(errored.length)} attempt${errored.length === 1 ? "" : "s"}); nothing reached the ` +
+                    `server, so nothing was emitted. Check the tool's permissions and the exact spelling ` +
+                    `in \`allowedTools\` — MCP names are host-mangled.`,
+            };
+        }
         return { kind: "malformed", reason: `no \`${name}\` tool call in the run` };
     }
     if (calls.length > 1) {

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/scaffold-test.js

@@ -118,6 +118,10 @@ assertTriggerRate(report, { min: 0.8, maxFalsePositive: 0.3 });
 }
 /** A JSON value placeholder for an `OutputFieldType`, for the `vigiles:ok` block. */
 function placeholderFor(type) {
+    // An enum's placeholder must be a MEMBER, or the scaffolded test fails the moment it
+    // is run — a generated test that cannot pass teaches the author to distrust the tool.
+    if (Array.isArray(type) && type.length > 0)
+        return type[0];
     switch (type) {
         case "number":
             return 1;

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",
     }));
 }