vigiles 29.1.0 → 30.0.1

package/dist/core/live-driver.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEventFiring = isEventFiring;
+/**
+ * Narrows the DRIVER, which an inline `d.firing.kind === "event"` does not:
+ * TypeScript narrows the discriminated PROPERTY, so the driver itself stays
+ * `HarnessLiveDriver` and passing it where an {@link EventFiringDriver} is
+ * wanted is still an error (measured — probe P2 in the design doc). The
+ * negative arm keeps its `caveat`, which is what the n/a note prints.
+ */
+function isEventFiring(d) {
+    return d.firing.kind === "event";
+}
+//# sourceMappingURL=live-driver.js.map

package/dist/core/markdown.d.ts

@@ -10,6 +10,29 @@
  * indices line up 1:1 with the caller's line array.
  */
 export declare function fencedLineFlags(src: string): boolean[];
+/**
+ * The document's PROSE, as CommonMark sees it: one entry per source line that
+ * carries author text, with fenced code, indented code, raw HTML blocks, inline
+ * code spans and inline HTML removed, and blank lines dropped.
+ *
+ * 🔴 WHY A CALLER MUST NOT DO THIS BY SPLITTING LINES. The module header already
+ * records that the naive `inFence = !inFence` toggle was copy-pasted into five
+ * detectors and is wrong on nested or unbalanced fences. The same applies to
+ * every other part of "what is the author actually saying here": a `<!-- -->`
+ * spanning three lines, a four-backtick block containing a bare three-backtick
+ * line, an indented continuation. The parser has all of it.
+ *
+ * What it also does, and what a hand-written reader gets wrong quietly: block
+ * parsing strips the leading INDENT, normalises CRLF, and drops trailing
+ * whitespace and trailing blank lines — so `@AGENTS.md`, `  @AGENTS.md`,
+ * `@AGENTS.md  ` and a CRLF-terminated copy all arrive as the same string
+ * (measured against this repo's markdown-it, 2026-09-21).
+ *
+ * ⚠️ THE ONE THING IT DOES NOT NORMALISE IS A UTF-8 BOM: markdown-it hands back
+ * `"\uFEFF@AGENTS.md"` for a BOM-prefixed first line, so this strips it. That is
+ * a measurement, not a precaution.
+ */
+export declare function proseLines(src: string): readonly string[];
 /** One fenced code block: its BODY (delimiters excluded) and where the body starts. */
 export interface FencedBlock {
     /** The block's contents, without the opening/closing fence lines. */

package/dist/core/markdown.js

@@ -1,31 +1,13 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fencedLineFlags = fencedLineFlags;
+exports.proseLines = proseLines;
 exports.fencedCodeBlocks = fencedCodeBlocks;
 exports.markdownRefs = markdownRefs;
-/**
- * vigiles — the ONE markdown-structure helper.
- *
- * Every place that needs to know "is this source line inside a fenced code
- * block?" routes through here, so no detector hand-rolls a fence toggle again.
- * The naive `inFence = !inFence` toggle (copy-pasted across five detectors
- * before this) is WRONG on nested / unbalanced fences: a 4-backtick block
- * containing a bare ``` line mis-toggles, and a `##` inside the block leaks out
- * as a real heading (demonstrated against `adopt`'s block splitter). Backed by
- * markdown-it (CommonMark) — the same "use the real parser, not regex"
- * discipline this repo already applies to Bash (mvdan-sh), code (ast-grep),
- * YAML (js-yaml), and TOML (@iarna/toml). Markdown was the one structured format
- * still parsed by hand.
- *
- * Node-free by construction: markdown-it is pure JS with no node builtins, so
- * this bundles clean in the browser scan engine (reached via skill-resources).
- */
-const markdown_it_1 = __importDefault(require("markdown-it"));
+const MarkdownIt = () => require("markdown-it");
 // One reusable parser; parse() is stateless across calls.
-const md = new markdown_it_1.default();
+let mdCached = null;
+const md = () => (mdCached ??= new (MarkdownIt())());
 /**
  * A SECOND parser, used only by {@link markdownRefs}, with link handling turned
  * down to "report exactly what the author wrote":
@@ -40,9 +22,16 @@ const md = new markdown_it_1.default();
  *   turn "a destination this tool declines to resolve" into "no destination at
  *   all". Skipping by scheme is the caller's job and it already does it.
  */
-const mdRefs = new markdown_it_1.default();
-mdRefs.normalizeLink = (url) => url;
-mdRefs.validateLink = () => true;
+let mdRefsCached = null;
+const mdRefs = () => {
+    if (mdRefsCached === null) {
+        const parser = new (MarkdownIt())();
+        parser.normalizeLink = (url) => url;
+        parser.validateLink = () => true;
+        mdRefsCached = parser;
+    }
+    return mdRefsCached;
+};
 /**
  * A boolean per source line (0-based): `true` when the line lies inside a fenced
  * code block (` ``` ` or `~~~`), the delimiter lines included — matching the
@@ -57,7 +46,7 @@ mdRefs.validateLink = () => true;
 function fencedLineFlags(src) {
     const lineCount = src.split("\n").length;
     const flags = new Array(lineCount).fill(false);
-    for (const tok of md.parse(src, {})) {
+    for (const tok of md().parse(src, {})) {
         // Only real ``` / ~~~ fences (a block-level token); markdown-it's `map` is
         // a [start, end) 0-based line range covering the delimiters + body.
         if (tok.type !== "fence" || tok.map === null)
@@ -68,6 +57,66 @@ function fencedLineFlags(src) {
     }
     return flags;
 }
+/**
+ * A THIRD parser, with `html: true`, used only by {@link proseLines}.
+ *
+ * The default `md` above has HTML disabled, so `<!-- maintainer note -->` comes
+ * back as ordinary paragraph TEXT rather than as an `html_block` token — which
+ * would put an author's commented-out line into the prose a caller is reading.
+ * Measured: with the default parser, `"<!-- note -->\n\n@AGENTS.md"` yields two
+ * prose lines; with this one, one. Enabling html on the shared parser would
+ * change what every existing caller sees, so this is a sibling rather than a
+ * setting, exactly as `mdRefs` is.
+ */
+let mdProseCached = null;
+const mdProse = () => (mdProseCached ??= new (MarkdownIt())({ html: true }));
+/**
+ * The document's PROSE, as CommonMark sees it: one entry per source line that
+ * carries author text, with fenced code, indented code, raw HTML blocks, inline
+ * code spans and inline HTML removed, and blank lines dropped.
+ *
+ * 🔴 WHY A CALLER MUST NOT DO THIS BY SPLITTING LINES. The module header already
+ * records that the naive `inFence = !inFence` toggle was copy-pasted into five
+ * detectors and is wrong on nested or unbalanced fences. The same applies to
+ * every other part of "what is the author actually saying here": a `<!-- -->`
+ * spanning three lines, a four-backtick block containing a bare three-backtick
+ * line, an indented continuation. The parser has all of it.
+ *
+ * What it also does, and what a hand-written reader gets wrong quietly: block
+ * parsing strips the leading INDENT, normalises CRLF, and drops trailing
+ * whitespace and trailing blank lines — so `@AGENTS.md`, `  @AGENTS.md`,
+ * `@AGENTS.md  ` and a CRLF-terminated copy all arrive as the same string
+ * (measured against this repo's markdown-it, 2026-09-21).
+ *
+ * ⚠️ THE ONE THING IT DOES NOT NORMALISE IS A UTF-8 BOM: markdown-it hands back
+ * `"\uFEFF@AGENTS.md"` for a BOM-prefixed first line, so this strips it. That is
+ * a measurement, not a precaution.
+ */
+function proseLines(src) {
+    const out = [];
+    for (const tok of mdProse().parse(src, {})) {
+        if (tok.type !== "inline")
+            continue;
+        let line = "";
+        for (const child of tok.children ?? []) {
+            if (child.type === "softbreak" || child.type === "hardbreak") {
+                out.push(line);
+                line = "";
+                continue;
+            }
+            // A code span and an inline `<!-- -->` are not the author's prose; the
+            // corpus that motivated this is full of `@dataclass`-shaped text inside
+            // them, and none of it names a file.
+            if (child.type === "code_inline" || child.type === "html_inline")
+                continue;
+            line += child.content;
+        }
+        out.push(line);
+    }
+    return out
+        .map((line) => line.replace(/^\uFEFF/, ""))
+        .filter((line) => line !== "");
+}
 /**
  * Every fenced code block in `src`, in document order — the same parser
  * {@link fencedLineFlags} uses, for callers that want the CONTENTS rather than a
@@ -94,7 +143,7 @@ function fencedLineFlags(src) {
  */
 function fencedCodeBlocks(src) {
     const out = [];
-    for (const tok of md.parse(src, {})) {
+    for (const tok of md().parse(src, {})) {
         if (tok.type !== "fence" || tok.map === null)
             continue;
         // `content` is the body only; `map[0]` is the OPENING delimiter's 0-based
@@ -146,7 +195,7 @@ function markdownRefs(src) {
         // lines of a real corpus are that.
         if (fenced[i] || (!line.includes("`") && !line.includes("](")))
             continue;
-        for (const tok of mdRefs.parseInline(line, {})) {
+        for (const tok of mdRefs().parseInline(line, {})) {
             refsInInline(tok.children ?? [], i + 1, out);
         }
     }

package/dist/core/orphans.js

@@ -40,8 +40,8 @@ const SKILL_FILE = "SKILL.md";
 /**
  * Files the HARNESS loads directly — its instruction file
  * (`layout.instructionFile`, e.g. `CLAUDE.md` / `AGENTS.md`), a skill
- * (`SKILL.md`), a subagent (`<agentDir>/*.md`), or a slash command
- * (`<commandDir>/*.md`) — are load-bearing by their NAME/LOCATION, not because
+ * (`SKILL.md`), a subagent (`<surfaces.agent>/*.md`), or a slash command
+ * (`<surfaces.command>/*.md`) — are load-bearing by their NAME/LOCATION, not because
  * another `.md` links to them. They are categorically NOT docs, so they are
  * never orphans even when `orphans.include` broadens to the whole repo.
  *
@@ -61,16 +61,18 @@ function isHarnessLoadedFile(path, layouts) {
         if (base === layout.instructionFile)
             return true;
         // Subagent / slash-command surfaces live at a REAL surface root — the repo
-        // root, the user-surface root (e.g. `.claude/`), or the materialize root —
-        // NOT any nested dir that merely shares the name. A doc under `docs/prompts/`
-        // is documentation, not Codex's `prompts` command surface.
+        // root or the user-surface root (e.g. `.claude/`) — NOT any nested dir that
+        // merely shares the name. A doc under `docs/prompts/` is documentation, not
+        // Codex's `prompts` command surface. (This listed the user-surface root and
+        // the materialize root separately; they are one field now, so the set it
+        // built is unchanged and can no longer hold two different values.)
         const roots = [
             "",
-            ...[layout.userSurfaceRoot, layout.materializeRoot]
+            ...[layout.userSurfaceRoot]
                 .filter((r) => !!r)
                 .map((r) => `${r}/`),
         ];
-        for (const dir of [layout.agentDir, layout.commandDir]) {
+        for (const dir of [layout.surfaces.agent, layout.surfaces.command]) {
             if (dir && roots.some((r) => norm.startsWith(`${r}${dir}/`))) {
                 return true;
             }

package/dist/core/settings-codec.d.ts

@@ -0,0 +1,17 @@
+export interface SettingsCodec {
+    /**
+     * For messages and the generated JSON Schema only. The core never branches
+     * on it — that is the whole reason this is a codec and not an enum, so a
+     * branch on this field would put the defect straight back.
+     */
+    readonly label: string;
+    /** Throws on malformed text; every caller today already catches. */
+    parse(text: string): Record<string, unknown>;
+    /** The inverse, with the trailing newline the harness's own tooling writes. */
+    render(value: Record<string, unknown>): string;
+}
+/** JSON settings (`.claude/settings.json`, `opencode.json`). */
+export declare const jsonSettingsCodec: SettingsCodec;
+/** TOML settings (Codex's `.codex/config.toml`). */
+export declare const tomlSettingsCodec: SettingsCodec;
+//# sourceMappingURL=settings-codec.d.ts.map

package/dist/core/settings-codec.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tomlSettingsCodec = exports.jsonSettingsCodec = void 0;
+/**
+ * `SettingsCodec` — the BYTES-TO-VALUE half of a harness's settings file, and
+ * the two encodings vigiles ships.
+ *
+ * 🔴 IT REPLACES A TWO-VALUED ENUM IN THE CORE. `PluginLayout.settingsFormat`
+ * was `"json" | "toml"`, and nine call sites branched on it: six about the
+ * ENCODING (parse a manifest, parse a settings file, serialize a merged
+ * config) and three about the hooks-entry SHAPE, which is a different question
+ * entirely and now lives on `HookProtocol`. Every one of those branches was a
+ * per-value `if`, so a third-party adapter whose settings are YAML could
+ * declare nothing the core would honour: the type had exactly two inhabitants
+ * and they were both ours.
+ *
+ * A codec closes that by construction — there is no enum left to be outside
+ * of. The grep that checks it is in the design: `'"json" | "toml"'` over
+ * `src/` must return only the adapter files that NAME their encoding, never a
+ * core module branching on one.
+ *
+ * ⚠️ WHAT A CODEC IS NOT: it does not know what the value MEANS. Whether a
+ * hooks entry nests `{matcher, hooks: [{type, command}]}` or is flat
+ * `{matcher, command}` is the harness's SHAPE, and it is `HookProtocol`'s —
+ * see `registration` there. Reading and writing an encoding, and reading and
+ * writing a shape, were the two halves `settingsFormat` was standing in for.
+ */
+/**
+ * 🔴 `@iarna/toml` IS REQUIRED LAZILY, AND THAT IS A MEASUREMENT, NOT A STYLE.
+ * The same wrapper exists in `hook-install.ts` and `core/hook-program.ts` with
+ * the reason recorded: a top-level import puts the TOML parser into the graph
+ * of every hook decision, because the hook runtime reaches those modules —
+ * measured 2026-09-08 at 56 ms per spawn. A codec that every `PluginLayout`
+ * now carries is reached from strictly MORE places than either of them, so a
+ * top-level import here would undo that fix and widen it. `tsc` lowers these
+ * to CommonJS, so the `require` genuinely does not run until a codec method is
+ * called, and a layout that is only READ (the common case) costs nothing.
+ */
+const toml = () => require("@iarna/toml");
+/** JSON settings (`.claude/settings.json`, `opencode.json`). */
+exports.jsonSettingsCodec = {
+    label: "json",
+    parse: (text) => JSON.parse(text),
+    render: (value) => JSON.stringify(value, null, 2) + "\n",
+};
+/** TOML settings (Codex's `.codex/config.toml`). */
+exports.tomlSettingsCodec = {
+    label: "toml",
+    parse: (text) => toml().parse(text),
+    // `trimEnd` before the newline: `stringifyToml` already ends with one, and
+    // two would be a diff on every write against a file the harness itself wrote.
+    render: (value) => toml()
+        .stringify(value)
+        .trimEnd() + "\n",
+};
+//# sourceMappingURL=settings-codec.js.map

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

@@ -124,8 +124,8 @@ export declare function discoverSurfaces(paths: readonly string[]): readonly Dis
  * (as `codexLayout` just did, `.codex/skills` → `.agents/skills`) moves its claim
  * with it and the two cannot drift.
  *
- * ⚠️ `materializeRoot` goes through {@link located} because `codexLayout` sets it
- * to `""` and a directory prefix of `""` is meaningless. It is DEFENCE IN DEPTH,
+ * ⚠️ The materialize prefix goes through {@link located} because `codexLayout`
+ * has none (`""`) and a directory prefix of `""` is meaningless. It is DEFENCE IN DEPTH,
  * not the load-bearing guard, and the difference was MEASURED rather than
  * assumed: removing this filter alone leaves `layoutClaims(codexLayout,
  * "src/index.ts")` at `false`, because the boundary form `path.startsWith(`${d}/`)`

package/dist/core/surface-discovery.js

@@ -168,8 +168,8 @@ function located(dir) {
  * (as `codexLayout` just did, `.codex/skills` → `.agents/skills`) moves its claim
  * with it and the two cannot drift.
  *
- * ⚠️ `materializeRoot` goes through {@link located} because `codexLayout` sets it
- * to `""` and a directory prefix of `""` is meaningless. It is DEFENCE IN DEPTH,
+ * ⚠️ The materialize prefix goes through {@link located} because `codexLayout`
+ * has none (`""`) and a directory prefix of `""` is meaningless. It is DEFENCE IN DEPTH,
  * not the load-bearing guard, and the difference was MEASURED rather than
  * assumed: removing this filter alone leaves `layoutClaims(codexLayout,
  * "src/index.ts")` at `false`, because the boundary form `path.startsWith(`${d}/`)`
@@ -186,9 +186,9 @@ function layoutLocations(layout) {
         if (d !== null)
             dirs.add(d);
     };
-    add(located(layout.materializeRoot));
+    add(located((0, layout_js_1.materializePrefix)(layout)));
     add(user);
-    for (const s of layout.surfaceDirs) {
+    for (const s of (0, layout_js_1.surfaceDirs)(layout)) {
         add(located(s));
         if (user !== null)
             add(located(`${user}/${s}`));
@@ -204,6 +204,11 @@ function layoutLocations(layout) {
         layout.settingsPath,
         layout.hooksConventionPath,
     ]) {
+        // `hooksConventionPath` is optional now — a harness whose hooks are code
+        // modules has none. Absent contributes no dir and no file, which is what
+        // the old `""` sentinel was filtered into below anyway.
+        if (p === undefined)
+            continue;
         const at = p.lastIndexOf("/");
         if (at > 0)
             add(p.slice(0, at));
@@ -216,7 +221,7 @@ function layoutLocations(layout) {
             layout.manifestPath,
             layout.settingsPath,
             layout.hooksConventionPath,
-        ].filter((f) => f !== ""),
+        ].filter((f) => f !== undefined && f !== ""),
     };
 }
 /**
@@ -269,7 +274,7 @@ function declaredRootClaims(layout, roots, path) {
 function declaredRootDirs(layout, roots) {
     const out = [];
     for (const r of roots)
-        for (const surface of layout.surfaceDirs) {
+        for (const surface of (0, layout_js_1.surfaceDirs)(layout)) {
             const dir = located(`${r}/${surface}`);
             if (dir !== null && !out.includes(dir))
                 out.push(dir);
@@ -365,7 +370,10 @@ function plural(kind, n) {
  * reader to move their skills somewhere no harness reads.
  */
 function knownHomes(layouts, kind) {
-    const dirOf = (l) => ({ skill: l.skillDir, agent: l.agentDir, command: l.commandDir })[kind];
+    // `DiscoveredKind` and `SurfaceKind` are the same three words; the cast is the
+    // one place they are related, and it is here rather than in the port because a
+    // discovered kind is a fact about a PATH the domain found, not about a layout.
+    const dirOf = (l) => l.surfaces[kind];
     const homes = new Set();
     for (const l of layouts) {
         const dir = located(dirOf(l));
@@ -410,15 +418,19 @@ function unclaimedSurfaceFindings(paths, layouts, declared) {
     for (const scope of declared ?? [])
         if (scope.roots.length > 0)
             claimers.push((path) => declaredRootClaims(scope.layout, scope.roots, path));
+    // The worked EXAMPLE config below names a harness, and it used to name a
+    // FIXED one — `claude-code`, spelled into the core, in a diagnostic shown to
+    // a repo that may target something else entirely. `layouts` was already in
+    // scope and already knew which harness the audit ran under; the example now
+    // reads the name off it. Empty `layouts` yields a placeholder rather than an
+    // invented name: an example that cannot be copied is better than one that
+    // names the wrong harness.
+    const exampleHarness = layouts[0]?.name ?? "<harness>";
     return unclaimedDirs(unclaimedSurfaces(discoverSurfaces(paths), claimers)).map((d) => ({
         ...d,
         message: `${d.dir}/ holds ${plural(d.kind, d.count)} that no harness vigiles knows about reads, ` +
             `so none of it is in this grade. Three ways out: keep it where it is and say so in ` +
-            // A worked EXAMPLE config in a diagnostic, and real debt: it names a
-            // harness the repo being audited may not even target, while `layouts` is
-            // already in scope here and knows which one it does.
-            // eslint-disable-next-line local/no-harness-names -- example config text
-            `.vigilesrc.json (\`{"harnesses":{"claude-code":{"roots":["${d.root === "" ? "." : d.root}"]}}}\` ` +
+            `.vigilesrc.json (\`{"harnesses":{"${exampleHarness}":{"roots":["${d.root === "" ? "." : d.root}"]}}}\` ` +
             `— see docs/configuration.md), audit it on its own ` +
             `(\`vigiles audit ${d.root === "" ? "." : d.root}\`), or move it somewhere a harness ` +
             `loads from (${knownHomes(layouts, d.kind)

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

@@ -5,7 +5,7 @@
  * 🔴 THIS EXISTS BECAUSE THE LOADER USED TO CHOOSE. It read the repo-root
  * `skills/` **or** the project-level `.claude/skills/` — never both — and
  * materialized whichever it picked under the SAME canonical
- * `<materializeRoot>/<surface>/…` key. Two real files, one key: the loser was
+ * `<materializePrefix>/<surface>/…` key. Two real files, one key: the loser was
  * never read, and the winner's content sat under the loser's name. Measured
  * 2026-08-18 on `nyldn/claude-octopus` (pinned corpus): **50 skill names exist in
  * both `skills/` and `.claude/skills/`, and all 50 pairs differ** — the `.claude/`
@@ -31,7 +31,7 @@
  * and call THIS for the decision, so the pair that this repo has repeatedly been
  * bitten by fixing on one side only cannot disagree about scoping.
  */
-import type { PluginLayout } from "./layout.js";
+import { type PluginLayout } from "./layout.js";
 /**
  * One discovery level, and the prefix its files are materialized under.
  *
@@ -60,6 +60,20 @@ export interface SurfaceScope {
 export type SurfaceSource = {
     readonly kind: "single-skill";
     readonly skillName: string;
+    /**
+     * The layout's skill dir, CARRIED rather than re-read by the consumer.
+     *
+     * 🔴 IT USED TO BE RE-DERIVED AT BOTH CONSUMERS, AND THE BRANCH THAT
+     * FOLLOWED WAS UNREACHABLE. `layout.surfaces.skill` is optional, so each
+     * of `plugin-loader.ts` and `scan-files.ts` narrowed it again and wrote a
+     * `return` for the `undefined` case — a case this variant is never
+     * constructed in, since the test below is the condition for making one.
+     * Two dead returns, in two engines that must agree, plus a comment in each
+     * explaining why the code beneath it cannot run. Carrying the value is the
+     * same construction the rest of this port uses: keep one copy, where it is
+     * KNOWN, instead of re-deriving it where it is not.
+     */
+    readonly skillDir: string;
 } | {
     readonly kind: "scopes";
     readonly scopes: readonly SurfaceScope[];
@@ -110,7 +124,7 @@ export declare function normalizeSurfaceRoots(roots: readonly string[] | undefin
  * 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
+ * `<materializePrefix>/…` 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
@@ -118,12 +132,18 @@ export declare function normalizeSurfaceRoots(roots: readonly string[] | undefin
  *
  * 🔴 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
+ * one that can produce a `<materializePrefix>/…` 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).
+ * `PluginLayout` that breaks the premise (e.g. one naming `.claude` as BOTH the
+ * materialize prefix and a second scope's base).
+ *
+ * ⚠️ HALF OF WHAT IT GUARDED IS NOW UNREPRESENTABLE. The premise used to have
+ * two ways to break: a declared root colliding with the prefix, and a layout
+ * whose `materializeRoot` differed from its `userSurfaceRoot` at all. The second
+ * field is gone — the prefix IS `userSurfaceRoot ?? ""` — so only the first
+ * remains, and this backstop is kept for it.
  */
 export declare function surfaceSource(layout: PluginLayout, probe: SurfaceProbe): SurfaceSource;
 /** The `LoadedPlugin.files` key for one file under one scope. */

package/dist/core/surface-scopes.js

@@ -5,6 +5,40 @@ exports.surfaceSource = surfaceSource;
 exports.scopeKey = scopeKey;
 exports.assertDistinctScopeKeys = assertDistinctScopeKeys;
 exports.multiScopeWarning = multiScopeWarning;
+/**
+ * WHERE a repo's model surfaces (skills/agents/commands) live — and the key each
+ * one is materialized under.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE LOADER USED TO CHOOSE. It read the repo-root
+ * `skills/` **or** the project-level `.claude/skills/` — never both — and
+ * materialized whichever it picked under the SAME canonical
+ * `<materializePrefix>/<surface>/…` key. Two real files, one key: the loser was
+ * never read, and the winner's content sat under the loser's name. Measured
+ * 2026-08-18 on `nyldn/claude-octopus` (pinned corpus): **50 skill names exist in
+ * both `skills/` and `.claude/skills/`, and all 50 pairs differ** — the `.claude/`
+ * copies carry multi-line unquoted `description:` blocks that a strict YAML
+ * loader rejects. vigiles reported those fifty skills as clean without ever
+ * having opened the files it named.
+ *
+ * The vendor settles it — Claude Code loads BOTH, in two namespaces:
+ *
+ * > Plugin skills use a `plugin-name:skill-name` namespace, so they can't
+ * > conflict with other levels.
+ * > For example, `my-plugin/skills/deploy/SKILL.md` becomes `/my-plugin:deploy`
+ * > and loads alongside a `deploy` skill in your project's `.claude/skills/`.
+ * > — https://code.claude.com/docs/en/skills § "Where skills live"
+ *
+ * So "pick one" was never a tie-break to get right; it was a question that has no
+ * answer, asked because the key shape forced one. The fix removes the question:
+ * every scope present is read, and **a scope's key prefix is derived from the
+ * scope, not from a winner**, so two files can no longer claim one key.
+ *
+ * Node-free and IO-free on purpose: the disk loader (`src/plugin-loader.ts`) and
+ * the browser file-map twin (`src/scan-files.ts`) each probe their own storage
+ * and call THIS for the decision, so the pair that this repo has repeatedly been
+ * bitten by fixing on one side only cannot disagree about scoping.
+ */
+const layout_js_1 = require("./layout.js");
 /**
  * The repo owner's `.vigilesrc.json#harnesses["<name>"].roots`, normalized — or
  * dropped. (The flat top-level `surfaceRoots` key this once read was removed in
@@ -44,7 +78,7 @@ function normalizeSurfaceRoots(roots) {
  * 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
+ * `<materializePrefix>/…` 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
@@ -52,29 +86,36 @@ function normalizeSurfaceRoots(roots) {
  *
  * 🔴 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
+ * one that can produce a `<materializePrefix>/…` 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).
+ * `PluginLayout` that breaks the premise (e.g. one naming `.claude` as BOTH the
+ * materialize prefix and a second scope's base).
+ *
+ * ⚠️ HALF OF WHAT IT GUARDED IS NOW UNREPRESENTABLE. The premise used to have
+ * two ways to break: a declared root colliding with the prefix, and a layout
+ * whose `materializeRoot` differed from its `userSurfaceRoot` at all. The second
+ * field is gone — the prefix IS `userSurfaceRoot ?? ""` — so only the first
+ * remains, and this backstop is kept for it.
  */
 function surfaceSource(layout, probe) {
-    if (layout.skillDir && probe.hasRootSkillFile) {
-        return { kind: "single-skill", skillName: probe.skillName };
+    const skillDir = layout.surfaces.skill;
+    if (skillDir !== undefined && probe.hasRootSkillFile) {
+        return { kind: "single-skill", skillName: probe.skillName, skillDir };
     }
     const scopes = [];
     if (layout.userSurfaceRoot !== undefined && probe.userHasLoadable) {
         scopes.push({
             base: layout.userSurfaceRoot,
-            materializeUnder: layout.materializeRoot,
+            materializeUnder: (0, layout_js_1.materializePrefix)(layout),
             label: "project",
         });
     }
     if (probe.rootHasLoadable || probe.isPluginShaped) {
         scopes.push({
             base: "",
-            materializeUnder: scopes.length === 0 ? layout.materializeRoot : "",
+            materializeUnder: scopes.length === 0 ? (0, layout_js_1.materializePrefix)(layout) : "",
             label: "plugin",
         });
     }
@@ -84,7 +125,7 @@ function surfaceSource(layout, probe) {
     if (scopes.length === 0 && layout.userSurfaceRoot !== undefined) {
         scopes.push({
             base: layout.userSurfaceRoot,
-            materializeUnder: layout.materializeRoot,
+            materializeUnder: (0, layout_js_1.materializePrefix)(layout),
             label: "project",
         });
     }
@@ -93,7 +134,7 @@ function surfaceSource(layout, probe) {
     // declaration says WHERE, the layout still says what a surface is and how it
     // is read. A root already serving as a scope's base is skipped (declaring
     // `.claude` to Claude Code is a no-op, not a second reading of one tree), and
-    // so is one equal to `materializeRoot` — that key belongs to the scope holding
+    // so is one equal to the materialize prefix — that key belongs to the scope holding
     // it, and two scopes minting one prefix is what {@link assertDistinctScopeKeys}
     // exists to refuse. Each keeps its OWN base as the key prefix, like a non-first
     // plugin scope, so nothing is relocated on top of anything.
@@ -107,7 +148,7 @@ function surfaceSource(layout, probe) {
     // `plugin-loader.test.ts` ("an EMPTY declared root does not cancel the project
     // scope"), which asserts the full key list both before and after filling it.
     for (const base of probe.declaredRoots ?? []) {
-        if (base === layout.materializeRoot)
+        if (base === (0, layout_js_1.materializePrefix)(layout))
             continue;
         if (scopes.some((sc) => sc.base === base))
             continue;

package/dist/core/validate.js

@@ -30,6 +30,7 @@ const cosmiconfig_1 = require("cosmiconfig");
 // 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 dialect_js_1 = require("./dialect.js");
 const config_schema_js_1 = require("./config-schema.js");
 // ---------------------------------------------------------------------------
 // Constants & regex
@@ -44,7 +45,12 @@ const CHECKBOX_RE = /^- \[([ xX])\]\s+(.+)$/;
 // The instruction filenames vigiles recognizes when no dialect is injected — a
 // validator-level default, not a harness dialect (the concrete dialects live in
 // the adapters; an injected ValidateOptions.dialect overrides this).
-const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
+//
+// 🔴 READ FROM `core/dialect.ts`, NOT RESTATED HERE, and NOT derived from the
+// adapter registry: `core ⊄ adapter`. The header on
+// `DEFAULT_INSTRUCTION_TARGETS` carries the measurement behind that refusal and
+// names the test that keeps this list and the registry in agreement instead.
+const INSTRUCTION_FILES = dialect_js_1.DEFAULT_INSTRUCTION_TARGETS;
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
 /**
@@ -130,8 +136,15 @@ function loadConfig(searchFrom, { onInvalid = "throw" } = {}) {
     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 (present.length > 0) {
+            // The names the user's OWN removed `harness` key held, so the worked
+            // example in the message shows their migration rather than a fixed pair
+            // of names spelled into the core. A non-string entry is dropped: this is
+            // a config we have already refused, so the message must survive garbage.
+            const legacy = raw.harness;
+            const names = (Array.isArray(legacy) ? legacy : legacy === undefined ? [] : [legacy]).filter((n) => typeof n === "string" && n.length > 0);
+            problems.push((0, config_schema_js_1.replacedKeyMessage)(present, names));
+        }
     }
     if (problems.length === 0) {
         const parsed = config_schema_js_1.vigilesConfigSchema.safeParse(raw);

package/dist/coverage-artifact.d.ts

@@ -1,9 +1,10 @@
 import type { ProbeOrigin, SurfaceProbe } from "./check-count.js";
+import { COVERAGE_ARTIFACT_FILE } from "./local-files.js";
 import type { Surface, SurfaceKind } from "./test-coverage.js";
 /** Bumped when the record shape changes in a non-additive way. */
 export declare const COVERAGE_ARTIFACT_VERSION = 1;
-/** The artifact filename under `.vigiles/`. */
-export declare const COVERAGE_ARTIFACT_FILE = "coverage.json";
+/** The artifact filename under `.vigiles/` — defined on the one local-files list. */
+export { COVERAGE_ARTIFACT_FILE };
 /**
  * Which runner produced a record. Mirrors the discovery split in
  * `test-coverage.ts`: `vigiles test` runs `*.harness.*` (free, every push),