vigiles 28.0.0 → 29.1.0

package/dist/core/validate.js

@@ -2,8 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_RULES = void 0;
 exports.findInstructionFiles = findInstructionFiles;
-exports.normalizeSeverity = normalizeSeverity;
-exports.asStringArray = asStringArray;
 exports.loadConfig = loadConfig;
 exports.parseRules = parseRules;
 exports.validate = validate;
@@ -14,6 +12,25 @@ const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
 const node_path_1 = require("node:path");
 const cosmiconfig_1 = require("cosmiconfig");
+// 🔴 A TOP-LEVEL IMPORT, and the lazy `require` it replaced is recorded because
+// the instinct to reintroduce it is correct-sounding: Zod is a ~45 ms cold
+// import and this module is on the CLI's barrel. Two measured facts settle it.
+//
+// (1) It does not reach the HOT rail at all. A compiled hook's decision
+//     (`vigiles hook-runtime run-program`) never loads the verb barrel — the
+//     dispatcher shim in `src/cli.ts` branches before it, and
+//     `src/hook-runtime-graph.test.ts` fails the day that stops being true — so
+//     it never loads this file, lazily or otherwise.
+// (2) On the rails that DO load the barrel (the PostToolUse `refs` and
+//     `eval-lock-nudge` nudges) the floor is ~316 ms of Node startup plus ~85
+//     existing requires, against which 45 ms is ~13%, not a breach.
+//
+// And the attempt is on record as well: an in-body `require("./config-schema")`
+// resolves in `dist` (CommonJS) and NOT under vitest, which imports the `.ts`
+// sources — it failed every suite that touches `loadConfig`. A deferral that
+// only works in one of the two worlds the code runs in is not one line of
+// hygiene, it is a second module system.
+const config_schema_js_1 = require("./config-schema.js");
 // ---------------------------------------------------------------------------
 // Constants & regex
 // ---------------------------------------------------------------------------
@@ -21,7 +38,6 @@ const GUIDANCE_RE = /\*\*Guidance only\*\*/;
 const DISABLE_RE = /<!--\s*vigiles-disable\s*-->/;
 const RULE_HEADER_RE = /^###\s+(.+)$/;
 const CHECKBOX_RE = /^- \[([ xX])\]\s+(.+)$/;
-const VALID_MARKERS = ["headings", "checkboxes"];
 // ---------------------------------------------------------------------------
 // Default config
 // ---------------------------------------------------------------------------
@@ -31,103 +47,25 @@ const VALID_MARKERS = ["headings", "checkboxes"];
 const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
-exports.DEFAULT_RULES = {
-    // 🔴 BOTH DROP TO "warn", and that is a deliberate behaviour change.
-    //
-    // They used to feed the exit code directly and could not be tiered at all
-    // (#181), so a single unreferenced doc turned a PR red with no way to say
-    // "report it, do not block". Naming them as rules made the contradiction
-    // visible: both are HEURISTIC-BEHAVIORAL (an NCD similarity proxy, an
-    // "unreferenced" guess that an OSS sweep measured at ~100% false positives on
-    // nav-managed doc sites), and this repo's own calibration rule is that a
-    // heuristic never defaults to `error` because it cries wolf. `orphan-docs`
-    // already DECLARED `warn` in its meta while behaving as `error` — the gate
-    // caught that disagreement the moment the rule was registered properly.
-    //
-    // Set either to `"error"` to keep the old blocking behaviour.
-    // Hard error, like `compile` itself: a dead reference is decidable from the
-    // filesystem, not a proxy — the calibration rule's `external-decidable` tier.
-    "spec-refs": "error",
-    "orphan-docs": "warn",
-    "duplicate-rules": "warn",
-    "require-instructions-spec": "warn",
-    // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
-    // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong
-    // default (it would nag about vendored/fixture/bench skills); the coverage that
-    // matters is the `untested-*` rules ("every skill/agent/hook ships with a test
-    // or eval"). Set `require-skill-spec` explicitly if your team wants every skill
-    // spec-managed.
-    "require-skill-spec": false,
-    integrity: "warn",
-    coverage: false,
-    // Per-kind surface-coverage: a skill/agent/hook must ship with a test or eval.
-    "untested-skill": "warn",
-    "untested-subagent": "warn",
-    "untested-hook": "warn",
-    "unmarked-refs": "warn",
-    // High-precision (never-available + close typos only), so on by default at warn.
-    "subagent-tool-contract": "warn",
-    // High-precision (close typos only), on by default at warn.
-    "hook-events": "warn",
-    // Missing required frontmatter (name/description) — on by default at warn.
-    "subagent-frontmatter": "warn",
-    // A declared MCP server with no command/url can't start — on by default at warn.
-    "mcp-config": "warn",
-    // Best-practice nudge (skills load without frontmatter) — warn, not error.
-    "skill-frontmatter": "warn",
-    // High-precision (gated on a declared MCP set; built-ins allowlisted) — warn.
-    "mcp-tool-resolves": "warn",
-    // A hook script referenced but missing never runs — on by default at warn.
-    "hook-script-exists": "warn",
-    // Discovery nudge toward compiled hooks (one finding) — default OFF: it's a
-    // recommendation, not a defect (the hand-written shell lane stays first-class),
-    // so it shouldn't fire unasked. Set "warn"/"error" to opt in.
-    "prefer-compiled-hooks": false,
-    // High-precision (close-typo only) deny-list mirror of subagent-tool-contract.
-    "disallowed-tools-contract": "warn",
-    // Deterministic NCD precision proxy (near-identical skill descriptions) — warn.
-    "description-overlap": "warn",
-    // A model-invocable skill's description so long the trigger signal is buried —
-    // WARN only (heuristic proxy, generous 500-char budget); never gates.
-    "skill-description-budget": "warn",
-    // Malformed-YAML frontmatter — WARN only (js-yaml is stricter than some loaders).
-    "frontmatter-valid": "warn",
-    // A mcp_tool hook incomplete / targeting an undeclared server — on by default at warn.
-    "mcp-hook-target-resolves": "warn",
-    // Lethal-trifecta capability set-intersection (read-private + ingest-untrusted +
-    // exfiltrate in one unit) — WARN by default (don't-cry-wolf rollout); raise to error.
-    "lethal-trifecta": "warn",
-    // A SKILL.md body referencing a missing bundled resource — WARN by default
-    // (don't-cry-wolf rollout, FP-safe); raise to error to gate CI.
-    "skill-resource-resolves": "warn",
-    // A SKILL.md missing its opening `---` fence (invisible skill) — WARN by
-    // default (FP-safe key whitelist); raise to error to gate CI.
-    "skill-missing-fence": "warn",
-    // Functional dirs nested inside `.claude-plugin/` (invisible surfaces) — WARN
-    // by default; raise to error to gate CI.
-    "plugin-dir-layout": "warn",
-    // A lethal trifecta emerging across a delegation edge (combined blast radius) —
-    // WARN by default (don't-cry-wolf rollout); raise to error to gate CI.
-    "delegation-trifecta": "warn",
-    // A hook that looks like it blocks but silently doesn't (#19009) — WARN by
-    // default (FP-safe literal patterns); raise to error to gate CI.
-    "hook-block-ineffective": "warn",
-    // A hook matcher that doesn't fire as written (tool typo, an MCP pattern
-    // that matches no tool name, or one too narrow for real server names) — WARN
-    // by default (high-precision); raise to error to gate CI.
-    "hook-matcher": "warn",
-    // Builder calls quoted inside ```ts fences in markdown — default OFF. Measured
-    // over 2 582 markdown files across two repos: 52 refs, 0 true positives, and
-    // every error raised was a false one (a design sketch's `cmd("npm test")`, a
-    // vendored third-party CLAUDE.md). A fence in prose is a DRAWING of config;
-    // reading it as config is the defect. Opt in where markdown IS the source.
-    "doc-refs": false,
-};
-const DEFAULT_CONFIG = {
-    ruleMarkers: ["headings", "checkboxes"],
-    rules: exports.DEFAULT_RULES,
-    files: DEFAULT_FILES,
-};
+/**
+ * The shipped default severity of every rule — DERIVED from the schema, never
+ * listed twice.
+ *
+ * It used to be the literal beside the type, which is exactly the pair that
+ * drifts: `rule-meta.test.ts` already cross-checks each rule's documented
+ * `defaultSeverity` against this object, and it could only ever catch a doc that
+ * disagreed with the literal, never a literal that disagreed with what parsing
+ * actually produced. Reading it out of the parser closes that gap: this IS what
+ * a `{}` config loads as.
+ */
+exports.DEFAULT_RULES = defaultConfig()
+    .rules;
+/** The default rule markers — read from the schema, like every other default. */
+const DEFAULT_MARKERS = defaultConfig().ruleMarkers;
+/** A freshly parsed empty config — the defaults, straight from the schema. */
+function defaultConfig() {
+    return config_schema_js_1.vigilesConfigSchema.parse({});
+}
 // ---------------------------------------------------------------------------
 // Instruction file discovery
 // ---------------------------------------------------------------------------
@@ -139,41 +77,7 @@ function findInstructionFiles(cwd = process.cwd(), configFiles) {
 // Config loading
 // ---------------------------------------------------------------------------
 /**
- * ESLint users write `"off"` / `0` / `1` / `2` for severity; normalize to
- * vigiles's `"warn" | "error" | false` so a rule the user meant to DISABLE
- * (`"off"`) or GATE (`2`) actually does — instead of a truthy string / number
- * silently rendering as a non-gating warn (issue #112 + numeric severities). The
- * array form `[sev, opts]` recurses on the head. An unrecognized value is left
- * as-is (it renders as a warn, the pre-existing behavior).
- */
-function normalizeSeverity(v) {
-    if (Array.isArray(v))
-        return [normalizeSeverity(v[0]), v[1]];
-    if (v === "off" || v === 0 || v === false)
-        return false;
-    if (v === "error" || v === 2)
-        return "error";
-    if (v === "warn" || v === 1)
-        return "warn";
-    return v;
-}
-/**
- * Coerce a config value that should be a `string[]`: a bare STRING becomes a
- * one-element array (the natural first-value mistake), so `exclude` /
- * `orphans.include` don't silently iterate a string's CHARACTERS as globs — a
- * no-op at best, and garbage "orphan" matches (`.`, `/`, `README.md`) at worst.
- * A non-string/array value falls back with a warning (the `ruleMarkers` pattern).
- */
-function asStringArray(v, fallback, key) {
-    if (typeof v === "string")
-        return [v];
-    if (Array.isArray(v))
-        return v.filter((x) => typeof x === "string");
-    console.warn(`Invalid ${key} in config: expected a string or string[], got ${JSON.stringify(v)}. Ignoring.`);
-    return fallback;
-}
-/**
- * Read `.vigilesrc.json`.
+ * Read and VALIDATE `.vigilesrc.json`.
  *
  * 🔴 `searchFrom` IS NOT A CONVENIENCE. cosmiconfig defaults to the process's
  * working directory and walks up — right for a CLI verb, where the user is
@@ -184,61 +88,69 @@ function asStringArray(v, fallback, key) {
  * "off" was never found. Nothing in the output distinguishes that from a project
  * that never configured the rule.
  *
- * Every CLI verb still calls this with no argument and is unaffected.
+ * 🔴 `onInvalid` IS THE ONE PLACE THE CALL SITES DIFFER, AND IT IS NOT A SPLIT
+ * IN WHAT IS CHECKED. Every reader validates; they disagree only about what a
+ * bad config is allowed to do to them. A VERB is a human standing at a prompt
+ * having just edited the file — `"throw"`, so the line they typed is refused out
+ * loud. A HOOK RAIL is a fresh process inside somebody's editing session, and a
+ * hook that dies on a malformed config turns a typo in a JSON file into a failed
+ * edit, which is a worse outcome than the nudge not firing — `"warn"`, print the
+ * same lines to stderr and carry on with the defaults.
+ *
+ * The two hook rails are `refsHookCommand` and `evalLockNudgeHookCommand`
+ * (`vigiles hook-runtime refs` / `eval-lock-nudge`, both registered as
+ * PostToolUse `Edit|Write` in `.claude-plugin/plugin.json`). Every other reader
+ * is a verb.
+ *
+ * ⚠️ THE SCHEMA MODULE IS REQUIRED IN-BODY, and that is hygiene rather than an
+ * optimization worth a paragraph: Zod is a ~45 ms cold import, `tsc` emits
+ * CommonJS across 230 separate files, so a `require` in a function body genuinely
+ * does not execute until the function is called. A rail that never reads a
+ * config never pays for the validator.
  */
-function loadConfig(searchFrom) {
+function loadConfig(searchFrom, { onInvalid = "throw" } = {}) {
+    let raw;
     try {
         const explorer = (0, cosmiconfig_1.cosmiconfigSync)("vigiles", {
             searchPlaces: [".vigilesrc.json"],
             mergeSearchPlaces: false,
         });
-        const result = explorer.search(searchFrom);
-        if (!result?.config)
-            return { ...DEFAULT_CONFIG };
-        const userConfig = result.config;
-        const config = {
-            ...DEFAULT_CONFIG,
-            ...userConfig,
-            // Normalize ESLint-idiom severities ("off"/0/1/2) across the merged rules,
-            // so a config value coerces to a real gating decision instead of a truthy
-            // string silently downgrading to warn.
-            rules: Object.fromEntries(Object.entries({ ...exports.DEFAULT_RULES, ...userConfig.rules }).map(([k, v]) => [k, normalizeSeverity(v)])),
-            files: Array.isArray(userConfig.files) ? userConfig.files : DEFAULT_FILES,
-        };
-        // Parse-don't-validate the array-shaped keys ONCE here: a bare string is
-        // accepted as [string]; anything else warns + falls back. Downstream code
-        // then always sees a real string[] (no char-by-char glob spread).
-        if (userConfig.exclude !== undefined)
-            config.exclude = asStringArray(userConfig.exclude, [], "exclude");
-        if (userConfig.sharedDirs !== undefined)
-            config.sharedDirs = asStringArray(userConfig.sharedDirs, [], "sharedDirs");
-        if (config.orphans) {
-            config.orphans = {
-                ...config.orphans,
-                include: config.orphans.include === undefined
-                    ? undefined
-                    : asStringArray(config.orphans.include, [], "orphans.include"),
-                exclude: config.orphans.exclude === undefined
-                    ? undefined
-                    : asStringArray(config.orphans.exclude, [], "orphans.exclude"),
-            };
-        }
-        if (!Array.isArray(config.ruleMarkers) ||
-            !config.ruleMarkers.every((m) => VALID_MARKERS.includes(m))) {
-            console.warn(`Invalid ruleMarkers in config: ${JSON.stringify(config.ruleMarkers)}. Using default.`);
-            config.ruleMarkers = [...DEFAULT_CONFIG.ruleMarkers];
-        }
-        return config;
+        raw = explorer.search(searchFrom)?.config;
     }
     catch {
-        return { ...DEFAULT_CONFIG };
+        // No file, unreadable file, malformed JSON — the defaults, as always. A
+        // config we CAN read and refuse is a different thing and is handled below.
+        return defaultConfig();
+    }
+    if (raw === undefined || raw === null)
+        return defaultConfig();
+    // The replaced keys get their own message BEFORE the schema's, because the
+    // reader is someone whose config used to work: `.strict()` would tell them
+    // "unknown key harness", which is true and useless. See REPLACED_KEYS.
+    const problems = [];
+    if (typeof raw === "object" && !Array.isArray(raw)) {
+        const present = config_schema_js_1.REPLACED_KEYS.filter((k) => k.key in raw);
+        if (present.length > 0)
+            problems.push((0, config_schema_js_1.replacedKeyMessage)(present));
+    }
+    if (problems.length === 0) {
+        const parsed = config_schema_js_1.vigilesConfigSchema.safeParse(raw);
+        if (parsed.success)
+            return parsed.data;
+        problems.push(...(0, config_schema_js_1.formatConfigIssues)(parsed.error.issues));
     }
+    if (onInvalid === "throw")
+        throw new config_schema_js_1.VigilesConfigError(problems.join("\n"));
+    for (const line of problems)
+        console.warn(`⚠ ${line}`);
+    console.warn("⚠ Using default configuration.");
+    return defaultConfig();
 }
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
 function parseRules(content, { ruleMarkers } = {}) {
-    const markers = ruleMarkers ?? DEFAULT_CONFIG.ruleMarkers;
+    const markers = ruleMarkers ?? DEFAULT_MARKERS;
     const lines = content.split("\n");
     const rules = [];
     let currentRule = null;

package/dist/exclude.d.ts

@@ -22,4 +22,24 @@ export interface ExcludeSet {
 }
 /** Parse `.vigilesrc.json#exclude` once, against `root`. */
 export declare function excludeSet(root: string, patterns: readonly string[] | undefined): ExcludeSet;
+/**
+ * Is this ABSOLUTE path dropped by `.vigilesrc.json#exclude`?
+ *
+ * The PREDICATE face, for a hand-rolled recursive walk that has an absolute path
+ * in hand and no glob (`readTree` in `src/plugin-loader.ts`, the bounded root
+ * walk in `src/surface-discovery-fs.ts`). A predicate rather than an
+ * `ExcludeSet` so the walk never has to remember which root the patterns are
+ * relative to: {@link excludedBy} closes over `excludes.root`, which is the REPO
+ * root and NOT the audited dir — `vigiles audit some/dir` must still honour a
+ * root-relative `exclude`.
+ *
+ * Lives HERE, beside the other two faces, because this file is the one
+ * exclusion policy (#192) and this was its third face living in one caller's
+ * private scope — which is how a second walk ends up writing a fourth.
+ */
+export type Excluded = (absPath: string) => boolean;
+/** The default: exclude nothing (every caller that passes no `ExcludeSet`). */
+export declare const excludesNothing: Excluded;
+/** The {@link Excluded} face of an `ExcludeSet`, or {@link excludesNothing}. */
+export declare function excludedBy(excludes: ExcludeSet | undefined): Excluded;
 //# sourceMappingURL=exclude.d.ts.map

package/dist/exclude.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXCLUDE_FLOOR = void 0;
+exports.excludesNothing = exports.EXCLUDE_FLOOR = void 0;
 exports.excludeSet = excludeSet;
+exports.excludedBy = excludedBy;
 /**
  * The ONE exclusion policy for every walk that polices the user's repository (#192) — the parsed `.vigilesrc.json#exclude` as an `ExcludeSet`, built ONCE where `loadConfig()` runs and taken as a REQUIRED parameter by every in-scope discovery (`findSpecs`, `findInstructionFiles`, `discoverNestedBundles`, `collectDocumentedRules`, `gatherInstructionFiles` in cli.ts; the string face handed to `findDocRefs`, `findOrphanDocs` (`repoExclude`), `findUntestedSurfaces`/`skillTestNudge`, `discoverScripts`, `computeScriptCoverage`).
  * Two faces: `globIgnore` (an `IgnoreLike` keyed on the path's position relative to the REPO root, so a glob rooted below it — `vigiles lint some/dir` — still applies a root-relative exclude) and `ignore` (the normalized string list for pure core detectors that glob from the root).
@@ -65,4 +66,13 @@ function excludeSet(root, patterns) {
         explain,
     };
 }
+/** The default: exclude nothing (every caller that passes no `ExcludeSet`). */
+const excludesNothing = () => false;
+exports.excludesNothing = excludesNothing;
+/** The {@link Excluded} face of an `ExcludeSet`, or {@link excludesNothing}. */
+function excludedBy(excludes) {
+    if (!excludes)
+        return exports.excludesNothing;
+    return (abs) => excludes.matches((0, node_path_1.relative)(excludes.root, abs));
+}
 //# sourceMappingURL=exclude.js.map

package/dist/layout-registry.d.ts

@@ -0,0 +1,14 @@
+import type { PluginLayout } from "./core/layout.js";
+/** Every SHIPPED harness layout, in registry order. */
+export declare const REGISTERED_LAYOUTS: readonly PluginLayout[];
+/**
+ * "Is this repo-relative path read by some harness vigiles knows about?" — one
+ * predicate per registered layout, the input to `unclaimedSurfaces`.
+ *
+ * Note it is the layouts of every REGISTERED harness, not of the DETECTED one.
+ * A repo carrying both `.claude/skills` and `.agents/skills` has each half
+ * claimed by a different harness and neither is a finding; a repo whose skills
+ * sit under `.ai/` has them claimed by nobody, and that is the finding (#240).
+ */
+export declare const registeredClaims: ReadonlyArray<(path: string) => boolean>;
+//# sourceMappingURL=layout-registry.d.ts.map

package/dist/layout-registry.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registeredClaims = exports.REGISTERED_LAYOUTS = void 0;
+/**
+ * The registered harnesses' LAYOUTS, as pure data — the claim side of surface
+ * discovery, available where the adapter bundle is not.
+ *
+ * 🔴 WHY THIS IS NOT JUST `ADAPTERS.map(a => a.layout)`. `src/adapter-registry.ts`
+ * imports the full `HarnessAdapter` bundles, and an adapter's `detect(root)` does
+ * real filesystem work — so that module pulls `node:fs` in. `src/scan-files.ts`
+ * is the BROWSER-SAFE twin of the scan ("NO filesystem, NO child_process, NO disk
+ * I/O at all") and needs exactly one thing from the registry: which paths a
+ * shipped harness reads. A `PluginLayout` is a plain object of strings, so this
+ * list is importable from both sides.
+ *
+ * The drift that split lists invite is CHECKED, not hoped for:
+ * `src/layout-registry.test.ts` asserts this list is exactly the layouts the
+ * `ADAPTERS` registry carries, and that every adapter's `claims` agrees with
+ * `layoutClaims` over its own layout — so adding a harness to one registry and
+ * not the other fails a test instead of quietly halving discovery.
+ */
+const layout_js_1 = require("./adapters/claude-code/layout.js");
+const layout_js_2 = require("./adapters/codex/layout.js");
+const surface_discovery_js_1 = require("./core/surface-discovery.js");
+/** Every SHIPPED harness layout, in registry order. */
+exports.REGISTERED_LAYOUTS = [
+    layout_js_1.claudeCodeLayout,
+    layout_js_2.codexLayout,
+];
+/**
+ * "Is this repo-relative path read by some harness vigiles knows about?" — one
+ * predicate per registered layout, the input to `unclaimedSurfaces`.
+ *
+ * Note it is the layouts of every REGISTERED harness, not of the DETECTED one.
+ * A repo carrying both `.claude/skills` and `.agents/skills` has each half
+ * claimed by a different harness and neither is a finding; a repo whose skills
+ * sit under `.ai/` has them claimed by nobody, and that is the finding (#240).
+ */
+exports.registeredClaims = exports.REGISTERED_LAYOUTS.map((l) => (path) => (0, surface_discovery_js_1.layoutClaims)(l, path));
+//# sourceMappingURL=layout-registry.js.map

package/dist/plugin-loader.d.ts

@@ -1,4 +1,5 @@
 import type { PluginLayout } from "./core/layout.js";
+import type { ExcludeSet } from "./exclude.js";
 export interface LoadedPlugin {
     /** A `.claude/settings.json`-shaped object with hooks resolved. */
     readonly settings: {
@@ -29,8 +30,55 @@ export interface LoadedPlugin {
  * 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.
  */
-export declare function loadPlugin(pluginPath: string, layout: PluginLayout): LoadedPlugin;
+export declare function loadPlugin(pluginPath: string, layout: PluginLayout, excludes?: ExcludeSet, surfaceRoots?: readonly string[]): LoadedPlugin;
+/**
+ * ONE declared harness for {@link loadPlugins}: the layout to read the repo
+ * under, and the extra roots declared for THAT harness.
+ */
+export interface HarnessLoad {
+    readonly layout: PluginLayout;
+    readonly roots?: readonly string[];
+}
+/**
+ * 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.
+ */
+export declare function loadPlugins(pluginPath: string, harnesses: readonly HarnessLoad[], excludes?: ExcludeSet): LoadedPlugin;
 export declare function danglingRefs(root: string, layout: PluginLayout): string[];
 /**
  * Resolve the effective harness for a test/eval (arm): load the plugin if given,