vigiles 28.0.0 → 29.1.0

package/dist/plugin-loader.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPlugin = loadPlugin;
+exports.loadPlugins = loadPlugins;
 exports.danglingRefs = danglingRefs;
 exports.resolveHarness = resolveHarness;
 /**
@@ -37,6 +38,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const toml_1 = require("@iarna/toml");
 const hash_js_1 = require("./core/hash.js");
+const exclude_js_1 = require("./exclude.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");
@@ -140,13 +142,20 @@ function readHooks(root, layout) {
  * `entryOf` has already cleared would cost a syscall per directory to answer a
  * question that cannot come out differently.
  */
-function readTree(dir, base) {
+function readTree(dir, base, excluded = exclude_js_1.excludesNothing) {
     const out = {};
     for (const entry of (0, node_fs_1.readdirSync)(dir)) {
         const full = (0, node_path_1.join)(dir, entry);
+        // `.vigilesrc.json#exclude`, applied HERE — per entry, inside the recursion —
+        // and not merely at the surface-dir entry point. A vendored tree is usually
+        // excluded at its own root (`bench`, `vendor/corpus`), which is a descendant
+        // of a surface dir, so a check that only guarded the walk's start would let
+        // every one of its files into the file map the whole report is computed from.
+        if (excluded(full))
+            continue;
         const { kind, size } = (0, fs_walk_js_1.entryOf)(full);
         if (kind === "dir")
-            Object.assign(out, readTree(full, base));
+            Object.assign(out, readTree(full, base, excluded));
         // The cap keeps a stray binary out of the in-memory file map, and the size
         // comes from the SAME stat that classified the entry. Asking a second time
         // needed its own `catch` — reachable only if the file vanished between the two
@@ -162,9 +171,21 @@ function readTree(dir, base) {
  * the files (CLAUDE.md + skills + agents + commands) to write into the test
  * sandbox, and `warnings` for surfaces the deterministic tier can't drive. Merge
  * `settings` with any inline settings and spread `files` into the fixture.
+ *
+ * `surfaceRoots` is this function's parameter name for what the repo owner
+ * writes as `.vigilesrc.json#harnesses["<name>"].roots` — extra repo-relative
+ * bases to read `<base>/<surfaceDir>/…` from, for a repo that keeps its skills
+ * somewhere no harness reads by default. The config key is nested UNDER a
+ * harness name precisely so a root cannot be declared without saying whose
+ * layout reads it; this parameter receives one harness's slice of that, which
+ * is why it is still a bare list here. `excludes` still wins over it:
+ * both the per-tree check in {@link materializeSurfaces} and `readTree` drop an
+ * excluded path whatever declared it, so a root that is declared AND excluded is
+ * read exactly as if it had never been declared.
  */
-function loadPlugin(pluginPath, layout) {
+function loadPlugin(pluginPath, layout, excludes, surfaceRoots) {
     const root = (0, node_path_1.resolve)(pluginPath);
+    const excluded = (0, exclude_js_1.excludedBy)(excludes);
     const hooks = readHooks(root, layout);
     // Expand the plugin-root token to the real absolute path so the actual hook
     // scripts execute — we test the shipped wiring, not a reimplementation.
@@ -174,11 +195,11 @@ function loadPlugin(pluginPath, layout) {
     const files = {};
     const sources = {};
     const instructions = (0, node_path_1.join)(root, layout.instructionFile);
-    if ((0, node_fs_1.existsSync)(instructions)) {
+    if ((0, node_fs_1.existsSync)(instructions) && !excluded(instructions)) {
         files[layout.instructionFile] = (0, node_fs_1.readFileSync)(instructions, "utf-8");
         sources[layout.instructionFile] = instructions;
     }
-    const surfaces = materializeSurfaces(root, layout, files, sources);
+    const surfaces = materializeSurfaces(root, layout, files, sources, excluded, surfaceRoots);
     return {
         settings: resolvedHooks ? { hooks: resolvedHooks } : {},
         files,
@@ -186,6 +207,69 @@ function loadPlugin(pluginPath, layout) {
         warnings: pluginWarnings(root, surfaces, resolvedHooks, files, layout),
     };
 }
+/**
+ * Load the repo once PER DECLARED HARNESS and merge the results into one
+ * `LoadedPlugin` (#240).
+ *
+ * 🔴 THE MERGE IS WHY THIS EXISTS, AND THE DEDUPLICATION IS ITS WHOLE CONTRACT.
+ * A repo that declares two harnesses is a repo whose grade must cover both — the
+ * flat `harness` array could not do that, because whichever name sat first
+ * decided the ONE layout everything was read under: measured on a repo with
+ * `AGENTS.md` + `.ai/skills/alpha/SKILL.md`, Claude-Code-first graded the skill
+ * and reported 0 chars of always-loaded instructions, Codex-first read
+ * `AGENTS.md` and reported no skill at all. Neither order produced both halves.
+ *
+ * ⚠️ AND THE OBVIOUS FIX HAS AN OBVIOUS SECOND BUG: a repo honest enough to say
+ * one tree serves both tools would then have that tree read twice and every
+ * skill in it counted twice, so declaring the truth would lower the grade. So the
+ * merge keys on the REAL ON-DISK PATH (`sources`), not on the materialized key:
+ * the first harness to claim a file keeps it, later ones skip it, and the counts
+ * are of files rather than of claims. Keying on the materialized key would not
+ * do — two layouts can reach one file under two different keys (`.ai/.agents`
+ * + `skills` and `.ai` + `.agents/skills` are the same directory), and that is
+ * exactly the case an honest dual declaration produces.
+ *
+ * Settings come from the FIRST harness that yields any, and the file-map merge
+ * is first-wins for the same reason: the primary harness is the one whose
+ * dialect the report is rendered in, so its reading of a shared path is the one
+ * the rest of the report is consistent with.
+ */
+function loadPlugins(pluginPath, harnesses, excludes) {
+    const loads = harnesses.map((h) => loadPlugin(pluginPath, h.layout, excludes, h.roots));
+    /* v8 ignore next -- callers always pass >=1; the guard keeps the type honest */
+    if (loads.length <= 1)
+        return loads[0] ?? EMPTY_LOAD;
+    const files = {};
+    const sources = {};
+    const seenOnDisk = new Set();
+    const warnings = [];
+    let settings = {};
+    for (const load of loads) {
+        for (const [key, content] of Object.entries(load.files)) {
+            // A file with no recorded source is one the loader synthesized rather than
+            // read (there are none today); key it by its own key so it still dedupes.
+            const onDisk = load.sources[key] ?? key;
+            if (seenOnDisk.has(onDisk))
+                continue;
+            seenOnDisk.add(onDisk);
+            files[key] = content;
+            sources[key] = onDisk;
+        }
+        for (const w of load.warnings)
+            if (!warnings.includes(w))
+                warnings.push(w);
+        if (settings.hooks === undefined && load.settings.hooks !== undefined)
+            settings = load.settings;
+    }
+    return { settings, files, sources, warnings };
+}
+/** The shape `loadPlugins` returns for an empty harness list. */
+const EMPTY_LOAD = {
+    settings: {},
+    files: {},
+    sources: {},
+    warnings: [],
+};
 /**
  * Materialize every model surface (skills/agents/commands) into `files`, and
  * record each file's real on-disk path in `sources`. Best-effort (headless
@@ -214,8 +298,9 @@ function surfaceHasLoadable(layout, surface, tree) {
         ? keys.some((k) => (0, node_path_1.basename)(k) === "SKILL.md")
         : keys.some((k) => k.endsWith(".md"));
 }
-function materializeSurfaces(root, layout, files, sources) {
+function materializeSurfaces(root, layout, files, sources, excluded = exclude_js_1.excludesNothing, surfaceRoots) {
     const counts = {};
+    const harnessCounts = {};
     const isDir = (p) => (0, node_fs_1.existsSync)(p) && (0, node_fs_1.statSync)(p).isDirectory();
     /**
      * One surface dir's tree, or `{}` when there is nothing to read.
@@ -226,7 +311,9 @@ function materializeSurfaces(root, layout, files, sources) {
      * per-entry one and that function says why; a shared skills dir linked in from
      * outside is still read.
      */
-    const surfaceTree = (dir) => isDir(dir) && (0, fs_walk_js_1.walkableRoot)(dir, root) ? readTree(dir, dir) : {};
+    const surfaceTree = (dir) => isDir(dir) && (0, fs_walk_js_1.walkableRoot)(dir, root) && !excluded(dir)
+        ? readTree(dir, dir, excluded)
+        : {};
     /** Every surface tree of one scope, read once, keyed by surface dir. */
     const scopeTrees = (base) => {
         const trees = new Map();
@@ -245,13 +332,24 @@ function materializeSurfaces(root, layout, files, sources) {
     const userTrees = layout.userSurfaceRoot !== undefined
         ? scopeTrees(layout.userSurfaceRoot)
         : new Map();
+    // Declared roots are read HERE, up front and once, for the same reason the two
+    // above are: `surfaceSource` needs to know which of them hold anything before
+    // it can decide the scope list, and re-reading them afterwards would be a
+    // second walk that could disagree with the first.
+    const declaredRoots = (0, surface_scopes_js_1.normalizeSurfaceRoots)(surfaceRoots);
+    const declaredTrees = new Map();
+    for (const base of declaredRoots)
+        declaredTrees.set(base, scopeTrees(base));
     /** 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 n = Object.keys(tree).length;
+            counts[surface] = (counts[surface] ?? 0) + n;
+            if (scope.declared !== true)
+                harnessCounts[surface] = (harnessCounts[surface] ?? 0) + n;
         }
     };
     /**
@@ -288,6 +386,12 @@ function materializeSurfaces(root, layout, files, sources) {
                 add((0, node_path_1.join)(base, dir, rel), content, (0, node_path_1.join)(root, base, dir, rel));
         }
     };
+    /** The already-read trees a scope materializes from — never a second walk. */
+    const treesOf = (scope) => scope.declared === true
+        ? (declaredTrees.get(scope.base) ?? new Map())
+        : scope.base === ""
+            ? rootTrees
+            : userTrees;
     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),
@@ -295,6 +399,7 @@ function materializeSurfaces(root, layout, files, sources) {
         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),
+        declaredRoots,
     });
     switch (source.kind) {
         case "single-skill": {
@@ -303,19 +408,20 @@ function materializeSurfaces(root, layout, files, sources) {
             // No `walkableRoot` here on purpose: `root` is the directory the CALLER
             // named (`vigiles audit <dir>`), not one this walk discovered, and refusing
             // to read the path someone explicitly pointed at is not a containment rule.
-            const tree = readTree(root, root);
+            const tree = readTree(root, root, excluded);
             for (const [rel, content] of Object.entries(tree)) {
                 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;
-            return { counts, scopes: [] };
+            harnessCounts[layout.skillDir] = counts[layout.skillDir];
+            return { counts, harnessCounts, scopes: [] };
         }
         case "scopes": {
             (0, surface_scopes_js_1.assertDistinctScopeKeys)(source.scopes, layout.name);
             for (const scope of source.scopes)
-                materializeScope(scope, scope.base === "" ? rootTrees : userTrees);
+                materializeScope(scope, treesOf(scope));
             materializeRules();
-            return { counts, scopes: source.scopes };
+            return { counts, harnessCounts, scopes: source.scopes };
         }
         /* v8 ignore next 2 -- exhaustiveness guard, unreachable given SurfaceSource */
         default:
@@ -329,9 +435,9 @@ 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, scopes }, hooks, files, layout) {
+function pluginWarnings(root, { counts, harnessCounts, scopes }, hooks, files, layout) {
     const warnings = [];
-    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, counts);
+    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, harnessCounts);
     if (multiScope !== undefined)
         warnings.push(multiScope);
     if (counts.agents) {

package/dist/scan-core.d.ts

@@ -37,6 +37,25 @@ export interface SurfaceClassifier {
     readonly isRule: (f: string) => boolean;
 }
 export declare function makeClassifier(layout: PluginLayout): SurfaceClassifier;
+/**
+ * ONE classifier over SEVERAL layouts — a path is a skill if ANY declared
+ * harness would read it as one.
+ *
+ * 🔴 IT EXISTS BECAUSE A MERGED FILE MAP HAS NO SINGLE LAYOUT. A repo declaring
+ * `{"harnesses": {"claude-code": {…}, "codex": {}}}` is read under BOTH layouts
+ * and the two file maps merge into one, at which point classifying with one
+ * layout drops the other's surfaces on the floor — Codex's `prompts/x.md` is not
+ * a Claude Code command, and silently counting it as nothing is the same shape of
+ * bug as reading no surfaces and grading A (100).
+ *
+ * `agentName` answers from the FIRST layout that calls the path an agent, so the
+ * name is always the one the layout that claimed it would give — never a name
+ * derived under a layout that would not have read the file at all.
+ *
+ * A single-layout list behaves byte-identically to {@link makeClassifier}, which
+ * is what lets every existing caller keep passing one layout.
+ */
+export declare function makeUnionClassifier(layouts: readonly PluginLayout[]): SurfaceClassifier;
 /** The plugin-root + materialize-root + dialect context skill scanning needs. */
 export interface SkillScanContext {
     readonly root: string;

package/dist/scan-core.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeClassifier = makeClassifier;
+exports.makeUnionClassifier = makeUnionClassifier;
 exports.remapFindingPaths = remapFindingPaths;
 exports.detectOwnTestSignal = detectOwnTestSignal;
 exports.scanSkills = scanSkills;
@@ -199,6 +200,35 @@ function makeClassifier(layout) {
         agentName: (f) => isAgent(f) ? (0, layout_js_1.agentSurfaceName)(f, layout.agentDir) : null,
     };
 }
+/**
+ * ONE classifier over SEVERAL layouts — a path is a skill if ANY declared
+ * harness would read it as one.
+ *
+ * 🔴 IT EXISTS BECAUSE A MERGED FILE MAP HAS NO SINGLE LAYOUT. A repo declaring
+ * `{"harnesses": {"claude-code": {…}, "codex": {}}}` is read under BOTH layouts
+ * and the two file maps merge into one, at which point classifying with one
+ * layout drops the other's surfaces on the floor — Codex's `prompts/x.md` is not
+ * a Claude Code command, and silently counting it as nothing is the same shape of
+ * bug as reading no surfaces and grading A (100).
+ *
+ * `agentName` answers from the FIRST layout that calls the path an agent, so the
+ * name is always the one the layout that claimed it would give — never a name
+ * derived under a layout that would not have read the file at all.
+ *
+ * A single-layout list behaves byte-identically to {@link makeClassifier}, which
+ * is what lets every existing caller keep passing one layout.
+ */
+function makeUnionClassifier(layouts) {
+    const cs = layouts.map(makeClassifier);
+    const any = (pick) => (f) => cs.some((c) => pick(c)(f));
+    return {
+        isSkill: any((c) => c.isSkill),
+        isAgent: any((c) => c.isAgent),
+        isCommand: any((c) => c.isCommand),
+        isRule: any((c) => c.isRule),
+        agentName: (f) => cs.find((c) => c.isAgent(f))?.agentName(f) ?? null,
+    };
+}
 function skillName(path) {
     return (path
         .replace(/\/SKILL\.md$/, "")

package/dist/scan-files.js

@@ -49,6 +49,8 @@ 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_discovery_js_1 = require("./core/surface-discovery.js");
+const layout_registry_js_1 = require("./layout-registry.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");
@@ -231,6 +233,7 @@ function surfaceHasLoadable(layout, surface, tree) {
 function materializeSurfaces(files, layout, acc, repoName) {
     const { out, sources } = acc;
     const counts = {};
+    const harnessCounts = {};
     const scopeTrees = (base) => {
         const trees = new Map();
         for (const surface of layout.surfaceDirs) {
@@ -255,7 +258,10 @@ function materializeSurfaces(files, layout, acc, repoName) {
             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 n = Object.keys(tree).length;
+            counts[surface] = (counts[surface] ?? 0) + n;
+            if (scope.declared !== true)
+                harnessCounts[surface] = (harnessCounts[surface] ?? 0) + n;
         }
     };
     const source = (0, surface_scopes_js_1.surfaceSource)(layout, {
@@ -276,13 +282,14 @@ 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;
-            return { counts, scopes: [] };
+            harnessCounts[layout.skillDir] = counts[layout.skillDir];
+            return { counts, harnessCounts, scopes: [] };
         }
         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 };
+            return { counts, harnessCounts, scopes: source.scopes };
         }
     }
 }
@@ -371,9 +378,9 @@ function danglingRefs(files, layout, rootName) {
 // ---------------------------------------------------------------------------
 // Warnings (mirrors plugin-loader.ts pluginWarnings)
 // ---------------------------------------------------------------------------
-function pluginWarnings(files, layout, { counts, scopes }, hooks, materialized, rootName) {
+function pluginWarnings(files, layout, { counts, harnessCounts, scopes }, hooks, materialized, rootName) {
     const warnings = [];
-    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, counts);
+    const multiScope = (0, surface_scopes_js_1.multiScopeWarning)(scopes, harnessCounts);
     if (multiScope !== undefined)
         warnings.push(multiScope);
     if (counts.agents) {
@@ -550,6 +557,9 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,
         skillFenceIssues: skillFenceFindings,
+        // The browser twin has the WHOLE fetched key set in hand, so discovery needs
+        // no walk here — the pure classifier re-applies the same bounded-root rule.
+        unclaimedSurfaces: (0, surface_discovery_js_1.unclaimedSurfaceFindings)(Object.keys(files), layout_registry_js_1.REGISTERED_LAYOUTS),
         pluginLayoutIssues: (0, plugin_dir_layout_js_1.pluginDirLayoutIssues)((0, posix_path_js_1.join)(exports.BROWSER_ROOT, (0, posix_path_js_1.dirname)(lay.manifestPath)), [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: exists, isDirectory: mapIsDirectory(files) }),
         delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
         hookBlockFindings: (0, event_capability_js_1.blockIneffectiveEventsOf)(dialect).length > 0

package/dist/scan.d.ts

@@ -12,6 +12,7 @@
  * stack on top later; this core stays pure so it runs anywhere in CI for free.
  */
 import type { PluginLayout } from "./core/layout.js";
+import type { ExcludeSet } from "./exclude.js";
 import type { HarnessDialect } from "./core/dialect.js";
 import type { ToolIssue } from "./core/tool-contract.js";
 import { type HookEventIssue } from "./core/hook-events.js";
@@ -25,6 +26,7 @@ import type { TrifectaFinding } from "./core/lethal-trifecta.js";
 import type { SkillResourceFinding } from "./core/skill-resources.js";
 import type { SkillFenceFinding } from "./core/skill-missing-fence.js";
 import { type PluginLayoutFinding } from "./core/plugin-dir-layout.js";
+import { type UnclaimedSurfaceFinding } from "./core/surface-discovery.js";
 import type { DelegationTrifectaFinding } from "./core/delegation-trifecta.js";
 import { type HookBlockFinding } from "./core/hook-block-ineffective.js";
 import { type HookMatcherFinding } from "./core/hook-matcher.js";
@@ -283,6 +285,14 @@ export interface ScanReport {
      * and the `plugin-dir-layout` lint rule (one detector, no drift).
      */
     readonly pluginLayoutIssues: readonly PluginLayoutFinding[];
+    /**
+     * Surface directories found by SHAPE in the bounded root set that NO
+     * registered harness claims — a harness sitting somewhere vigiles does not
+     * read, reported instead of silently graded around (#240). Computed by
+     * `core/surface-discovery.ts` from paths alone; shared with the browser twin
+     * (one detector, no drift).
+     */
+    readonly unclaimedSurfaces: readonly UnclaimedSurfaceFinding[];
     /**
      * Lethal trifectas that EMERGE across a delegation edge — a subagent whose
      * effective (own ∪ delegated-to) capability holds all three legs though no
@@ -386,10 +396,63 @@ export interface ScanReport {
         unrestricted: number;
     };
 }
+/**
+ * ONE harness a scan reads the repo under — the resolved form of a
+ * `.vigilesrc.json#harnesses` entry (#240).
+ *
+ * All three parts travel together on purpose. The LAYOUT says where this harness
+ * reads and what a surface is there; the DIALECT says what it understands (and
+ * carries its own instruction budget, in its own unit); the ROOTS are the extra
+ * places this repo's owner says that harness's surfaces also live. Splitting
+ * them is how a root came to be read under a layout nobody chose for it.
+ */
+export interface ScanHarness {
+    readonly layout: PluginLayout;
+    readonly dialect: HarnessDialect;
+    readonly roots: readonly string[];
+}
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect, opts?: {
     sharedDirs?: readonly string[];
     sharedDirsRoot?: string;
+    /**
+     * The repo's `.vigilesrc.json#exclude`, so surface DISCOVERY honours it.
+     *
+     * It rides in `opts` rather than as a fifth positional parameter because ~25
+     * call sites pass the first three and nothing else; a required parameter here
+     * would be twenty-odd mechanical edits for one behavioural change.
+     *
+     * ⚠️ Omitting it is NOT "the repo excludes nothing" — it is "this caller has
+     * no ExcludeSet to give", and the walk then reads everything. Today only
+     * `audit` supplies one; the `lint` rule checkers below still do not (they
+     * share a `(config, silent, adapter, root)` signature through `overBundles`).
+     */
+    excludes?: ExcludeSet;
+    /**
+     * The repo's `.vigilesrc.json#harnesses`, resolved — every declared harness
+     * with its own layout, dialect and roots, IN DECLARATION ORDER.
+     *
+     * 🔴 THE LIST IS READ WHOLE, AND THAT IS THE FIX (#240). The repo is loaded
+     * once per entry, each under its OWN layout, and the file maps merge
+     * (deduplicated by on-disk path, so one tree serving two harnesses is
+     * counted once). Under the flat `harness` array only the first entry's
+     * layout was ever used, so a repo declaring both got its skills OR its
+     * instruction file depending on which name it happened to list first, and no
+     * order gave it both.
+     *
+     * The first entry is the PRIMARY: it supplies the dialect every
+     * dialect-shaped check runs under and the `harness` the report is labelled
+     * with. The INSTRUCTION FILE is the deliberate exception — it comes from the
+     * first declared harness whose instruction file is actually present, because
+     * reporting "no instruction file" for a repo holding the other declared
+     * harness's one is the half of the bug that has nothing to do with skills.
+     *
+     * Rides in `opts` for the same reason `excludes` does: ~25 call sites pass
+     * the first three positionals and nothing else. Omitting it means "this
+     * caller has no declaration to pass" and the scan runs single-harness on the
+     * positional `layout`/`dialect`, exactly as before.
+     */
+    harnesses?: readonly ScanHarness[];
 }): ScanReport;
 /**
  * LIVE MCP tool resolution for a scanned plugin — the dynamic check no static

package/dist/scan.js

@@ -35,10 +35,26 @@ exports.expandMarketplace = expandMarketplace;
 exports.formatScanReport = formatScanReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
+// The COMPOSITION-ROOT loader, not the `vigiles/claude-code` wrapper: this
+// module always passes a layout explicitly (it never wanted the wrapper's
+// Claude Code default), and only the generic one takes the `ExcludeSet` that
+// makes `.vigilesrc.json#exclude` reach surface discovery.
+const plugin_loader_js_1 = require("./plugin-loader.js");
+// 🔴 A FINDING, NOT A FORMALITY, and one nothing else in the repo could see: this
+// module is listed as a harness-agnostic detector, yet it imports the Claude Code
+// adapter to use as a DEFAULT (`scanPlugin`'s `dialect`/`layout` parameters, and
+// four more sites below). `boundaries/dependencies` does not catch it because it
+// deliberately leaves this file unclassified; the CC-literal rule does not catch
+// it because `\.claude` needs the dot and this path spells `/claude-code/`.
+// Keeping the CC default is the stated backwards-compatibility guarantee, so this
+// is real debt with a known shape — the default belongs to the CALLER (the CLI
+// already resolves an adapter), not to the detector.
+// eslint-disable-next-line local/no-harness-names -- see above
 const layout_js_1 = require("./adapters/claude-code/layout.js");
+// eslint-disable-next-line local/no-harness-names -- see above
 const dialect_js_1 = require("./adapters/claude-code/dialect.js");
 const plugin_loader_js_2 = require("./plugin-loader.js");
+const score_core_js_1 = require("./score-core.js");
 const skill_refs_js_1 = require("./skill-refs.js");
 const hook_events_js_1 = require("./core/hook-events.js");
 const mcp_config_js_1 = require("./core/mcp-config.js");
@@ -49,6 +65,9 @@ const mcp_contract_message_js_1 = require("./core/mcp-contract-message.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
 const merge_conflict_js_1 = require("./core/merge-conflict.js");
 const plugin_dir_layout_js_1 = require("./core/plugin-dir-layout.js");
+const surface_discovery_js_1 = require("./core/surface-discovery.js");
+const surface_discovery_fs_js_1 = require("./surface-discovery-fs.js");
+const layout_registry_js_1 = require("./layout-registry.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_js_1 = require("./test-coverage.js");
@@ -139,8 +158,23 @@ function ownTestSignalOnDisk(dir) {
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts = {}) {
     const lay = layout ?? layout_js_1.claudeCodeLayout;
-    const cls = (0, scan_core_js_1.makeClassifier)(lay);
-    const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
+    // The declared harnesses, or the single positional one — so every path below
+    // is the multi-harness path and a one-entry list is not a second code path.
+    const declared = opts.harnesses && opts.harnesses.length > 0
+        ? opts.harnesses
+        : [{ layout: lay, dialect, roots: [] }];
+    // A path is a surface if ANY declared harness reads it as one. Classifying a
+    // merged file map with one layout would drop the other harness's surfaces
+    // silently — the same shape of miss as grading a scan that opened nothing.
+    const cls = (0, scan_core_js_1.makeUnionClassifier)(declared.map((h) => h.layout));
+    const loaded = (0, plugin_loader_js_1.loadPlugins)(dir, declared.map((h) => ({ layout: h.layout, roots: h.roots })), opts.excludes);
+    // WHICH harness's instruction file this repo actually has. The first declared
+    // one that is present, not the first one declared: a repo listing
+    // `claude-code` before `codex` and shipping only `AGENTS.md` has an
+    // instruction file, and saying it does not was half of #240's wrong grade.
+    // Its dialect carries the budget the weight below is measured against, so the
+    // file named and the limit it is judged by come from the same harness.
+    const instructionHarness = declared.find((h) => loaded.files[h.layout.instructionFile] !== undefined) ?? declared[0];
     // Parse the raw `settings.hooks` ONCE at the boundary (parse-don't-validate):
     // tolerant of the Claude Code nested shape AND the Codex flat shape, so every
     // hook detector below consumes typed `HookRegistration[]` instead of re-walking
@@ -157,10 +191,11 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
     const eventNames = (0, hook_normalize_js_1.hookEventNames)(loaded.settings.hooks);
     const allHookEventIssues = (0, hook_events_js_1.verifyHookEvents)(eventNames, dialect);
     const hookEventIssues = (0, hook_events_js_1.scoredIssues)(allHookEventIssues);
-    const instructions = loaded.files[lay.instructionFile] !== undefined
+    const instructionFile = instructionHarness.layout.instructionFile;
+    const instructions = loaded.files[instructionFile] !== undefined
         ? {
-            file: lay.instructionFile,
-            hasSpec: (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.resolve)(dir), `${lay.instructionFile}.spec.ts`)),
+            file: instructionFile,
+            hasSpec: (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.resolve)(dir), `${instructionFile}.spec.ts`)),
         }
         : null;
     const mcpServers = collectMcpServers((0, node_path_1.resolve)(dir), lay);
@@ -188,7 +223,17 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
     // deterministic tier (`Tested`), and the real-model tier (`Evaluated`). The
     // tiers differ in cost, cadence AND in the question they answer, so collapsing
     // them here would make the difference unrecoverable downstream.
-    const coverage = (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir, layout: lay });
+    const coverage = (0, test_coverage_js_1.findUntestedSurfaces)({
+        basePath: dir,
+        layout: lay,
+        // The SAME `.vigilesrc.json#exclude`, in this walk's string face. Untested-
+        // surface discovery is a second walk over the same trees, so leaving it out
+        // would have excluded a skill from the GRADE while still naming it in
+        // "Untested surfaces: 1" — a report contradicting itself about whether the
+        // file exists. `exclude` here NARROWS (it unions with DEFAULT_IGNORE), which
+        // is the documented relationship between the repo floor and a rule's own list.
+        exclude: opts.excludes ? [...opts.excludes.ignore] : undefined,
+    });
     const caveats = (0, test_coverage_js_1.coverageCaveats)(coverage);
     return {
         dir,
@@ -229,6 +274,11 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,
         skillFenceIssues: skillFenceFindings,
+        unclaimedSurfaces: (0, surface_discovery_js_1.unclaimedSurfaceFindings)((0, surface_discovery_fs_js_1.boundedSurfacePaths)((0, node_path_1.resolve)(dir), opts.excludes), layout_registry_js_1.REGISTERED_LAYOUTS, declared.map((h) => ({
+            harness: h.layout.name,
+            layout: h.layout,
+            roots: h.roots,
+        }))),
         pluginLayoutIssues: (0, plugin_dir_layout_js_1.pluginDirLayoutIssues)((0, node_path_1.resolve)(dir, (0, node_path_1.dirname)(lay.manifestPath)), 
         // The hooks dir is a misplaceable functional surface too, but it lives in
         // the layout as a convention PATH (`hooks/hooks.json`), not in surfaceDirs
@@ -257,8 +307,13 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
                 return (0, node_fs_1.existsSync)(p) ? nodeReadFile(p) : undefined;
             }).map(merge_conflict_js_1.mergeConflictWarning),
         ],
-        instructionWeight: dialect.instructionBudget
-            ? (0, instruction_weight_js_1.weighInstructions)(readAlwaysLoaded(dir, dialect.instructionBudget), dialect.instructionBudget)
+        // Measured under the dialect whose instruction file this repo HAS — see
+        // `instructionHarness`. A budget is a harness's own number in a harness's own
+        // unit (Claude Code counts 40 000 chars, Codex 32 768 bytes), so there is no
+        // meaningful sum across two; reporting the one that owns the file that
+        // exists is the only reading that is true of something.
+        instructionWeight: instructionHarness.dialect.instructionBudget
+            ? (0, instruction_weight_js_1.weighInstructions)(readAlwaysLoaded(dir, instructionHarness.dialect.instructionBudget), instructionHarness.dialect.instructionBudget)
             : null,
         untested: coverage.untested.length,
         untestedHarness: coverage.harness.untested.length,
@@ -588,6 +643,11 @@ function formatScanReport(r) {
     out.push(...section("Skill bundled resources", r.skillResourceIssues.map((s) => `  ✗ ${s.name}: ${s.finding.ref} (line ${String(s.finding.line)}) — bundled resource not found`)));
     out.push(...section("Invisible skills (missing frontmatter fence)", r.skillFenceIssues.map((s) => `  ✗ ${s.name} (${s.path}): opens with \`${s.finding.key}:\` but no \`---\` fence — loads as body, never fires`)));
     out.push(...section("Misplaced plugin directories", r.pluginLayoutIssues.map((p) => `  ✗ ${p.message}`)));
+    // A harness sitting where no adapter reads (#240). Printed as a ✗ section like
+    // any other structural defect, because that is what it is: the grade above it
+    // was computed without this directory in it, and the old behaviour was to say
+    // nothing at all while returning A (100/100).
+    out.push(...section("Surfaces no harness reads", r.unclaimedSurfaces.map((u) => `  ✗ ${u.message}`)));
     out.push(...section("Lethal trifecta across delegation (blast radius)", r.delegationTrifecta.map((d) => `  ⚠ ${d.finding.name} (${d.path}): ${d.finding.message}`)));
     out.push(...section("Ineffective hook guards (false confidence)", r.hookBlockFindings.map((h) => `  ✗ [${h.event}] ${h.scriptPath ?? "(inline)"}: ${h.message}`)));
     out.push(...section("Hook matchers that don't fire as written", r.hookMatcherFindings.map((m) => `  ✗ ${m.message}`)));
@@ -658,6 +718,7 @@ function formatScanReport(r) {
         r.skillResourceIssues.length +
         r.skillFenceIssues.length +
         r.pluginLayoutIssues.length +
+        r.unclaimedSurfaces.length +
         r.hookBlockFindings.length +
         r.hookMatcherFindings.length +
         // Only HARD trifectas (✗) count as STRUCTURAL defects here. Both severities are
@@ -667,9 +728,15 @@ function formatScanReport(r) {
         // "broken" in the CLI summary is a separate, louder call. The delegation-trifecta
         // ⚠ risk is ungraded and does NOT count either.
         r.trifectaFindings.filter((t) => t.finding.severity === "hard").length;
-    out.push(broken === 0
-        ? "✓ no structural issues found"
-        : `⚠ ${String(broken)} structural issue(s) — see ✗/⚠ above`);
+    out.push(broken > 0
+        ? `⚠ ${String(broken)} structural issue(s) — see ✗/⚠ above`
+        : // 🔴 "NOTHING WAS FOUND" IS NOT "NOTHING IS WRONG" (#240). With zero
+            // surfaces read, `broken` is zero for want of anything to count, and this
+            // line was the sentence the reporter quoted under an A (100): a repo whose
+            // 37 skills sat in a directory this tool does not know by name.
+            (0, score_core_js_1.isEmptyMachine)(r)
+                ? "⚠ nothing to check — 0 skills, 0 agents, 0 commands were read"
+                : "✓ no structural issues found");
     return out.join("\n");
 }
 //# sourceMappingURL=scan.js.map