vigiles 28.0.0 → 29.0.0

package/README.md

@@ -260,7 +260,7 @@ Targets Claude Code and Codex out of the box, or [your own harness](docs/authori
 **[vigiles.sh](https://vigiles.sh)** is the live demo — grade any repo in your browser. The **[docs index](docs/README.md)** is the full map, grouped by what you're doing:
 
 - **Guides** — [verify instruction files](docs/verifying-instruction-files.md) · [test your harness](docs/harness-testing.md) · [measure a skill](docs/measuring-skills.md) · [ship a plugin](docs/for-plugin-authors.md) · [Codex & other harnesses](docs/harnesses.md)
-- **Reference** — [CLI](docs/cli.md) · [rules matrix](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix) · [testing API](docs/testing-api.md) · [full API](https://zernie.github.io/vigiles/api/)
+- **Reference** — [CLI](docs/cli.md) · [configuration](docs/configuration.md) · [rules matrix](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix) · [testing API](docs/testing-api.md) · [full API](https://zernie.github.io/vigiles/api/)
 - **Explanation** — [what it catches](docs/what-vigiles-catches.md) · [how it compares](docs/comparison.md) · [FAQ](docs/faq.md)
 
 > **A name starting with `experimental_` is not covered by semver.** It may change

package/dist/adapter-registry.d.ts

@@ -11,6 +11,7 @@
  * wins regardless of order.
  */
 import type { HarnessAdapter } from "./core/adapter.js";
+import type { HarnessDeclaration } from "./core/types.js";
 /** The default adapter when detection finds no harness markers. */
 export declare const defaultAdapter: HarnessAdapter;
 /** All registered adapters. detect() specificity (not order) breaks ties. */
@@ -113,4 +114,42 @@ export declare function resolveHarnessAdapters(opts: {
     flag?: string;
     configHarness?: string | readonly string[];
 }): HarnessAdapter[];
+/**
+ * One declared harness, resolved: the adapter its KEY names, and the extra
+ * surface roots declared under it, normalized.
+ *
+ * The pair is the whole point of the nested shape. Under the two flat keys the
+ * roots were global and the harness list was ordered, so the layout a root was
+ * read under was decided by array position; here the layout comes from the key
+ * the root sits under, so there is no order to get wrong and nothing to guess.
+ */
+export interface DeclaredHarness {
+    readonly adapter: HarnessAdapter;
+    /** Normalized `.vigilesrc.json#harnesses.<name>.roots`, in declaration order. */
+    readonly roots: readonly string[];
+}
+/**
+ * The declared harness NAMES, in declaration order — the `string[]` every
+ * existing single-dialect picker already takes.
+ *
+ * Deliberately NOT resolving adapters: `resolveHarnessSelection` /
+ * `resolveHarnessAdapters` resolve (and throw on) an unknown name themselves,
+ * and two places deciding what an unknown name means is how the two error
+ * wordings would drift.
+ */
+export declare function declaredHarnessNames(harnesses?: Readonly<Record<string, HarnessDeclaration>>): string[];
+/**
+ * Every declared harness with its roots, in declaration order.
+ *
+ * Throws on an unknown key, through the SAME `resolveAdapter` the `--harness=`
+ * flag goes through — so `{"claud-code": {}}` fails with the identical
+ * `Unknown harness "claud-code". Known: claude-code, codex.` a bad flag gets.
+ * That was already the loud half of the old shape and it is kept verbatim.
+ *
+ * Aliases collapse: `{"claude": {"roots":["a"]}, "claude-code": {"roots":["b"]}}`
+ * is ONE Claude Code declaration reading both roots, not two competing ones —
+ * the same de-duplication `resolveHarnessAdapters` does, extended to carry the
+ * union of what each spelling declared.
+ */
+export declare function resolveDeclaredHarnesses(root: string, harnesses?: Readonly<Record<string, HarnessDeclaration>>): DeclaredHarness[];
 //# sourceMappingURL=adapter-registry.d.ts.map

package/dist/adapter-registry.js

@@ -10,6 +10,9 @@ exports.resolveAdapter = resolveAdapter;
 exports.normalizeHarnessList = normalizeHarnessList;
 exports.resolveHarnessSelection = resolveHarnessSelection;
 exports.resolveHarnessAdapters = resolveHarnessAdapters;
+exports.declaredHarnessNames = declaredHarnessNames;
+exports.resolveDeclaredHarnesses = resolveDeclaredHarnesses;
+const surface_scopes_js_1 = require("./core/surface-scopes.js");
 const compose_js_1 = require("./core/compose.js");
 const adapter_js_1 = require("./adapters/claude-code/adapter.js");
 const adapter_js_2 = require("./adapters/codex/adapter.js");
@@ -181,4 +184,46 @@ function resolveHarnessAdapters(opts) {
     const seen = new Set();
     return adapters.filter((a) => !seen.has(a.name) && seen.add(a.name));
 }
+/**
+ * The declared harness NAMES, in declaration order — the `string[]` every
+ * existing single-dialect picker already takes.
+ *
+ * Deliberately NOT resolving adapters: `resolveHarnessSelection` /
+ * `resolveHarnessAdapters` resolve (and throw on) an unknown name themselves,
+ * and two places deciding what an unknown name means is how the two error
+ * wordings would drift.
+ */
+function declaredHarnessNames(harnesses) {
+    return normalizeHarnessList(Object.keys(harnesses ?? {}));
+}
+/**
+ * Every declared harness with its roots, in declaration order.
+ *
+ * Throws on an unknown key, through the SAME `resolveAdapter` the `--harness=`
+ * flag goes through — so `{"claud-code": {}}` fails with the identical
+ * `Unknown harness "claud-code". Known: claude-code, codex.` a bad flag gets.
+ * That was already the loud half of the old shape and it is kept verbatim.
+ *
+ * Aliases collapse: `{"claude": {"roots":["a"]}, "claude-code": {"roots":["b"]}}`
+ * is ONE Claude Code declaration reading both roots, not two competing ones —
+ * the same de-duplication `resolveHarnessAdapters` does, extended to carry the
+ * union of what each spelling declared.
+ */
+function resolveDeclaredHarnesses(root, harnesses) {
+    const out = [];
+    for (const [key, decl] of Object.entries(harnesses ?? {})) {
+        const adapter = resolveAdapter(root, key);
+        const roots = [...(0, surface_scopes_js_1.normalizeSurfaceRoots)(decl?.roots)];
+        const prev = out.find((d) => d.adapter.name === adapter.name);
+        if (prev) {
+            for (const r of roots)
+                if (!prev.roots.includes(r))
+                    prev.roots.push(r);
+        }
+        else {
+            out.push({ adapter, roots });
+        }
+    }
+    return out;
+}
 //# sourceMappingURL=adapter-registry.js.map

package/dist/adapter.d.ts

@@ -21,6 +21,14 @@ export type { PluginLayout } from "./core/layout.js";
 export type { HarnessRuntime } from "./core/runtime.js";
 export type { HookProtocol } from "./core/hook-protocol.js";
 export type { ModelMock } from "./core/model-mock.js";
+/**
+ * The `claims(path)` helper every shipped adapter uses: derive "is this path
+ * mine?" from the adapter's own `PluginLayout`, so a layout that moves takes its
+ * claim with it. Override `claims` by hand only for a location the layout fields
+ * cannot express. See `core/surface-discovery.ts` for why a claim is a question
+ * about a PATH and never about a root.
+ */
+export { layoutClaims } from "./core/surface-discovery.js";
 export { checkAdapterConformance, assertAdapterConformance, assertAdapterLoadsHooks, assertHarnessTestable, type ConformanceResult, } from "./adapter-conformance.js";
 export { ADAPTERS, defaultAdapter, detectAdapter, detectAdapterResult, resolveAdapter, getAdapter, type DetectResult, } from "./adapter-registry.js";
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAdapter = exports.resolveAdapter = exports.detectAdapterResult = exports.detectAdapter = exports.defaultAdapter = exports.ADAPTERS = exports.assertHarnessTestable = exports.assertAdapterLoadsHooks = exports.assertAdapterConformance = exports.checkAdapterConformance = void 0;
+exports.getAdapter = exports.resolveAdapter = exports.detectAdapterResult = exports.detectAdapter = exports.defaultAdapter = exports.ADAPTERS = exports.assertHarnessTestable = exports.assertAdapterLoadsHooks = exports.assertAdapterConformance = exports.checkAdapterConformance = exports.layoutClaims = void 0;
+/**
+ * The `claims(path)` helper every shipped adapter uses: derive "is this path
+ * mine?" from the adapter's own `PluginLayout`, so a layout that moves takes its
+ * claim with it. Override `claims` by hand only for a location the layout fields
+ * cannot express. See `core/surface-discovery.ts` for why a claim is a question
+ * about a PATH and never about a root.
+ */
+var surface_discovery_js_1 = require("./core/surface-discovery.js");
+Object.defineProperty(exports, "layoutClaims", { enumerable: true, get: function () { return surface_discovery_js_1.layoutClaims; } });
 var adapter_conformance_js_1 = require("./adapter-conformance.js");
 Object.defineProperty(exports, "checkAdapterConformance", { enumerable: true, get: function () { return adapter_conformance_js_1.checkAdapterConformance; } });
 Object.defineProperty(exports, "assertAdapterConformance", { enumerable: true, get: function () { return adapter_conformance_js_1.assertAdapterConformance; } });

package/dist/adapters/claude-code/adapter.js

@@ -11,6 +11,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const dialect_js_1 = require("./dialect.js");
 const layout_js_1 = require("./layout.js");
+const surface_discovery_js_1 = require("../../core/surface-discovery.js");
 const runtime_js_1 = require("./runtime.js");
 const hook_protocol_js_1 = require("./hook-protocol.js");
 const model_mock_js_1 = require("./model-mock.js");
@@ -32,6 +33,11 @@ exports.claudeCodeAdapter = {
     // Imported inside the thunk, not at the top: a top-level import runs at module
     // init and would pull the whole test/compiler graph back in.
     harnessTestDriver: async () => (await import("../../harness-test.js")).claudeCodeDriver,
+    // Derived from the layout, never listed again here — see `claims` on
+    // `HarnessAdapter` for why this method takes a PATH and not a root.
+    claims(path) {
+        return (0, surface_discovery_js_1.layoutClaims)(layout_js_1.claudeCodeLayout, path);
+    },
     detect(root) {
         // Most specific signal wins: a plugin manifest (3) > repo settings (2) >
         // a bare CLAUDE.md (1, weak — many tools also read it / AGENTS.md).

package/dist/adapters/claude-code/layout.d.ts

@@ -2,6 +2,11 @@
  * claudeCodeLayout — the Claude Code plugin/repo layout (the `PluginLayout`
  * port's reference implementation). `loadPlugin` defaults to it; a Codex adapter
  * defines a sibling `codexLayout` and passes it to the same loader.
+ * 🔴 THE PATHS BELOW ARE DOCUMENTED IN `docs/configuration.md`. Change any of
+ * them — `instructionFile`, `surfaceDirs`, `userSurfaceRoot`, `rulesDir` — and
+ * that page is wrong until you edit it too. The page marks this symbol with
+ * `vigiles:symbol`, so RENAMING it turns `vigiles lint` red and forces the
+ * edit; changing a VALUE in place does not, and nothing today catches that.
  */
 import type { PluginLayout } from "../../core/layout.js";
 export declare const claudeCodeLayout: PluginLayout;

package/dist/adapters/claude-code/plugin-loader.d.ts

@@ -10,7 +10,16 @@
 import type { PluginLayout } from "../../core/layout.js";
 import { loadPlugin as loadPluginWith, resolveHarness as resolveHarnessWith } from "../../plugin-loader.js";
 export type { LoadedPlugin } from "../../plugin-loader.js";
-/** Load the real Claude Code harness at `pluginPath` (defaults to `claudeCodeLayout`). */
+/**
+ * Load the real Claude Code harness at `pluginPath` (defaults to `claudeCodeLayout`).
+ *
+ * 🔴 DELIBERATELY NOT FORWARDING an `ExcludeSet`. The generic loader takes one
+ * (`.vigilesrc.json#exclude` filters surface discovery), but this is the PUBLIC
+ * `vigiles/claude-code` face, and a parameter whose type and constructor are both
+ * internal would land in the published surface as a name no consumer can write.
+ * In-repo callers that hold an ExcludeSet — `scan.ts` — import the composition
+ * root directly, which is where the layout is required anyway.
+ */
 export declare function loadPlugin(pluginPath: string, layout?: PluginLayout): ReturnType<typeof loadPluginWith>;
 /**
  * Resolve the effective harness for a test/eval (arm) under the Claude Code

package/dist/adapters/claude-code/plugin-loader.js

@@ -4,7 +4,16 @@ exports.loadPlugin = loadPlugin;
 exports.resolveHarness = resolveHarness;
 const plugin_loader_js_1 = require("../../plugin-loader.js");
 const layout_js_1 = require("./layout.js");
-/** Load the real Claude Code harness at `pluginPath` (defaults to `claudeCodeLayout`). */
+/**
+ * Load the real Claude Code harness at `pluginPath` (defaults to `claudeCodeLayout`).
+ *
+ * 🔴 DELIBERATELY NOT FORWARDING an `ExcludeSet`. The generic loader takes one
+ * (`.vigilesrc.json#exclude` filters surface discovery), but this is the PUBLIC
+ * `vigiles/claude-code` face, and a parameter whose type and constructor are both
+ * internal would land in the published surface as a name no consumer can write.
+ * In-repo callers that hold an ExcludeSet — `scan.ts` — import the composition
+ * root directly, which is where the layout is required anyway.
+ */
 function loadPlugin(pluginPath, layout = layout_js_1.claudeCodeLayout) {
     return (0, plugin_loader_js_1.loadPlugin)(pluginPath, layout);
 }

package/dist/adapters/codex/adapter.js

@@ -17,6 +17,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const dialect_js_1 = require("./dialect.js");
 const layout_js_1 = require("./layout.js");
+const surface_discovery_js_1 = require("../../core/surface-discovery.js");
 const runtime_js_1 = require("./runtime.js");
 const hook_protocol_js_1 = require("./hook-protocol.js");
 const model_mock_js_1 = require("./model-mock.js");
@@ -38,6 +39,11 @@ exports.codexAdapter = {
     hookProtocol: hook_protocol_js_1.codexHookProtocol,
     modelMock: model_mock_js_1.codexModelMock,
     harnessTestDriver: async () => (await import("./driver.js")).codexDriver,
+    // Derived from the layout, never listed again here — see `claims` on
+    // `HarnessAdapter` for why this method takes a PATH and not a root.
+    claims(path) {
+        return (0, surface_discovery_js_1.layoutClaims)(layout_js_1.codexLayout, path);
+    },
     detect(root) {
         // A `.codex/config.toml` is a strong signal; a bare AGENTS.md is weak (many
         // harnesses read it). (Unused while unregistered — kept for symmetry.)

package/dist/adapters/codex/layout.d.ts

@@ -1,15 +1,61 @@
 /**
- * codexLayout — EXPERIMENTAL, internal-only. A prototype `PluginLayout` for
- * Codex: `.codex/` conventions, `config.toml` (TOML) hooks, `AGENTS.md`,
- * `${PLUGIN_ROOT}`. Validates the layout port + the settings-format axis against
- * real Codex shapes. NOT exported / NOT registered.
+ * codexLayout — the OpenAI Codex `PluginLayout`: `.agents/skills` skills,
+ * `.codex/config.toml` (TOML) settings/hooks, `AGENTS.md`, `${PLUGIN_ROOT}`.
+ * Exported as `vigiles/codex` and registered in `src/adapter-registry.ts`.
  *
- * Findings surfaced by writing it (see research/codex-prototype-findings.md):
+ * 🔴 SKILLS LIVE AT `.agents/skills`, NOT `.codex/skills`. This descriptor said
+ * `.codex` + `skills` until 2026-09-21 — so the loader read `<root>/skills` and
+ * reported it under a `.codex/skills/…` key, and a real Codex repo's skills were
+ * read as ZERO. Verbatim from the vendor page
+ * (`https://learn.chatgpt.com/docs/build-skills`, redirected from
+ * `developers.openai.com/codex/skills`), fetched 2026-09-21:
+ *
+ * > Codex scans `.agents/skills` in every directory from your current working
+ * > directory up to the repository root.
+ *
+ * The same page lists `$HOME/.agents/skills` ("any skills checked into the
+ * user's personal folder") and `/etc/codex/skills` as the other scopes, and
+ * never mentions `.codex/skills` at all. Corroborated in-repo by
+ * `src/cli-install.e2e.test.ts`, which drives the real `skills` CLI and finds the
+ * install at `~/.agents/skills/`.
+ *
+ * 🔴 KNOWN LIMITATION — WALK-UP IS STILL NOT EXPRESSED, AND NOT BY OVERSIGHT.
+ * The vendor scans `.agents/skills` in EVERY directory from the cwd up to the
+ * repository root; `PluginLayout` names a single root-relative dir, so this
+ * descriptor covers only `<root>/.agents/skills`. A skill in a SUBDIRECTORY's own
+ * `.agents/skills` is still invisible.
+ *
+ * The 2026-09-21 discovery refactor (`src/core/surface-discovery.ts`) did NOT
+ * close it, and the reason is the refactor's own bound: discovery looks in the
+ * repo root and its depth-1 dot-directories, because an unbounded walk grades
+ * vendored third-party trees as the project's own work (#240, measured by the
+ * reporter at 53 vendored skills beside 37 real ones). Reaching a subpackage's
+ * `.agents/skills` means walking arbitrary directories, which is exactly what
+ * that bound refuses, so the gap is a deliberate trade and not a TODO.
+ *
+ * What it costs in practice: for `vigiles audit` AT THE REPO ROOT — the normal
+ * invocation — the root IS the whole walk-up chain, so nothing is missed. The
+ * gap is a monorepo subpackage keeping its own `.agents/skills`; point vigiles
+ * at that subdirectory to audit it.
+ *
+ * ⚠️ `installCodexSkills` (`./eval.ts`) still writes the eval tier's skills to
+ * `<cwd>/.codex/skills/`, and its comment claims that path was validated live
+ * against the binary (`eval.test.ts` carries a captured transcript reading
+ * `/tmp/cxreal/.codex/skills/…`). That is MEASURED evidence for an older Codex
+ * and it contradicts the page above; it is deliberately left alone until someone
+ * re-measures against the current binary. Do not "align" it from the docs alone.
+ *
+ * Other findings from the prototype (see research/codex-prototype-findings.md):
  * - Codex has no separate JSON *manifest* — `config.toml` carries everything; we
  *   point `manifestPath` at it (its JSON parse simply fails → the loader falls
  *   through to the TOML `settingsPath`). The manifest field is CC-JSON-shaped.
  * - MCP detection (`mcpConfigFile`/`mcpManifestKey`) is JSON-shaped, so it won't
  *   see Codex's `[mcp_servers]` TOML table — a known layout-port gap.
+ * 🔴 THE PATHS BELOW ARE DOCUMENTED IN `docs/configuration.md`. Change any of
+ * them — `instructionFile`, `surfaceDirs`, `userSurfaceRoot`, `rulesDir` — and
+ * that page is wrong until you edit it too. The page marks this symbol with
+ * `vigiles:symbol`, so RENAMING it turns `vigiles lint` red and forces the
+ * edit; changing a VALUE in place does not, and nothing today catches that.
  */
 import type { PluginLayout } from "../../core/layout.js";
 export declare const codexLayout: PluginLayout;

package/dist/adapters/codex/layout.js

@@ -8,14 +8,23 @@ exports.codexLayout = {
     settingsPath: ".codex/config.toml",
     settingsFormat: "toml",
     instructionFile: "AGENTS.md",
-    surfaceDirs: ["skills", "prompts"],
-    skillDir: "skills",
+    // Surfaces carry their OWN prefix and `materializeRoot` is "" — the OpenCode
+    // style, not the Claude Code one. Codex's skills and its prompts do NOT share a
+    // parent (`.agents/` vs `.codex/`), so no single `materializeRoot` can name
+    // both; spelling each dir in full is the only shape that keeps the reported key
+    // equal to the real on-disk path.
+    surfaceDirs: [".agents/skills", "prompts"],
+    skillDir: ".agents/skills",
     agentDir: "", // Codex `[agents]` is a TOML concurrency table, not a subagent dir
+    // Custom prompts are documented ONLY at `~/.codex/prompts` (user-global,
+    // top-level `.md`, and marked deprecated in favour of skills). No repo-level
+    // location is documented, so this prototype's root-level `prompts/` is left as
+    // it was rather than moved on a guess.
     commandDir: "prompts",
-    materializeRoot: ".codex",
+    materializeRoot: "",
     pluginRootToken: "${PLUGIN_ROOT}",
     mcpConfigFile: ".mcp.json",
     mcpManifestKey: "mcp_servers",
-    intraRefDirs: ["skills", "prompts", "hooks"],
+    intraRefDirs: [".agents/skills", "prompts", "hooks"],
 };
 //# sourceMappingURL=layout.js.map

package/dist/adapters/opencode/adapter.js

@@ -19,6 +19,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const dialect_js_1 = require("./dialect.js");
 const layout_js_1 = require("./layout.js");
+const surface_discovery_js_1 = require("../../core/surface-discovery.js");
 const runtime_js_1 = require("./runtime.js");
 const model_mock_js_1 = require("./model-mock.js");
 exports.opencodeAdapter = {
@@ -36,6 +37,11 @@ exports.opencodeAdapter = {
     runtime: runtime_js_1.opencodeRuntime,
     modelMock: model_mock_js_1.opencodeModelMock,
     // No hookProtocol: OpenCode hooks are code modules, not shell processes.
+    // Derived from the layout, never listed again here — see `claims` on
+    // `HarnessAdapter` for why this method takes a PATH and not a root.
+    claims(path) {
+        return (0, surface_discovery_js_1.layoutClaims)(layout_js_1.opencodeLayout, path);
+    },
     detect(root) {
         // An `opencode.json` is a strong signal; a bare AGENTS.md is weak (many
         // harnesses read it). (Unused while unregistered — kept for symmetry.)