vigiles 29.0.0 → 30.0.0

package/dist/adapter-conformance.d.ts

@@ -20,7 +20,7 @@ export declare function assertHarnessTestable(adapter: HarnessAdapter): {
 };
 /**
  * Behavioural conformance the pure checks can't reach: write a minimal settings
- * file in the adapter's declared `settingsFormat` (with a hook), load it through
+ * file using the adapter's OWN codec and registration shape, load it through
  * the adapter's `layout`, and assert the hooks actually came back. This is what
  * catches a layout that points at the right file but in the wrong format (the
  * JSON-vs-TOML trap) — the pure checker would pass it, the agent would silently

package/dist/adapter-conformance.js

@@ -19,6 +19,8 @@ const spec_js_1 = require("./core/spec.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
 const vocabulary_consistency_js_1 = require("./core/vocabulary-consistency.js");
 const event_capability_js_1 = require("./core/event-capability.js");
+const dialect_js_1 = require("./core/dialect.js");
+const layout_js_1 = require("./core/layout.js");
 const tmp_root_js_1 = require("./core/tmp-root.js");
 /** Check an adapter against the port contracts; returns the (possibly empty) failure list. */
 function checkAdapterConformance(adapter) {
@@ -27,12 +29,19 @@ function checkAdapterConformance(adapter) {
         if (!cond)
             failures.push(msg);
     };
-    const caps = adapter.capabilities;
-    // Widen to boolean so a malformed (non-TS) adapter that set this false is still
-    // caught at runtime — the literal `true` type would make a direct check redundant.
-    const refVerification = caps.referenceVerification;
+    // 🔴 THE KIT IS THE EXPLANATION, THE TYPE IS THE GATE. Every check below is
+    // now unreachable for an adapter authored in TypeScript: `HarnessAdapter` is
+    // an intersection of discriminated unions, so "declares the capability, ships
+    // no port" and "denies the capability, ships the port" are both compile
+    // errors. The checks stay for the two cases the type does not reach — a
+    // third-party adapter authored in JavaScript, and an object crossing a
+    // package boundary through a cast — and because a TypeScript error against a
+    // 4-member intersection reads badly next to a sentence naming the field.
+    //
+    // `capabilities.referenceVerification` was checked here and is gone. It was
+    // typed as the literal `true` on every adapter, so the check could not fail;
+    // a field that can hold one value carries no information.
     need(adapter.name.length > 0, "name is empty");
-    need(refVerification, "capabilities.referenceVerification must be true (every adapter does pillar 1)");
     // --- Pillar 1 (always required): dialect + layout ---
     need(adapter.dialect.builtinAgentTools.length > 0, "dialect has no builtinAgentTools");
     // The dialect's several name lists describe ONE vocabulary from different
@@ -52,9 +61,40 @@ function checkAdapterConformance(adapter) {
         for (const problem of (0, vocabulary_consistency_js_1.vocabularyProjectionProblems)(adapter.dialect.hookEventVocabulary, adapter.dialect.hookEvents, []))
             need(false, `hookEventVocabulary: ${problem}`);
     need(adapter.dialect.instructionTargets.length > 0, "dialect has no instructionTargets");
+    // The key set replaced a two-valued profile enum, which means a dialect can
+    // now declare a set that no code path honours. Both halves are checkable:
+    // a key the compiler cannot render is a declaration nothing acts on, and a
+    // dialect that drops `name` or `description` emits a SKILL.md with no identity.
+    for (const key of adapter.dialect.skillFrontmatterKeys)
+        need(dialect_js_1.RENDERABLE_SKILL_FRONTMATTER_KEYS.includes(key), `dialect.skillFrontmatterKeys names "${key}", which the compiler cannot render`);
+    for (const required of ["name", "description"])
+        need(adapter.dialect.skillFrontmatterKeys.includes(required), `dialect.skillFrontmatterKeys omits "${required}" — a SKILL.md without it has no identity`);
     need(adapter.layout.instructionFile.length > 0, "layout.instructionFile is empty");
     need(adapter.layout.manifestPath.length > 0, "layout.manifestPath is empty");
-    need(adapter.layout.surfaceDirs.length > 0, "layout has no surfaceDirs");
+    need((0, layout_js_1.surfaceDirs)(adapter.layout).length > 0, "layout.surfaces names no surface — at least one kind is required");
+    // A2: TypeScript has no non-empty-string type worth the ceremony (the
+    // template-literal `${string}${string}` trick matches `""` too), so the "no
+    // second spelling of absent" rule is a test for every optional path. An
+    // absent key already means "this harness has no such thing"; `""` would be a
+    // second one, and every reader would have to remember to test for both.
+    const optionalPaths = [
+        ["rulesDir", adapter.layout.rulesDir],
+        ["hookScriptsDir", adapter.layout.hookScriptsDir],
+        ["hooksConventionPath", adapter.layout.hooksConventionPath],
+        ["userSurfaceRoot", adapter.layout.userSurfaceRoot],
+        ["surfaces.skill", adapter.layout.surfaces.skill],
+        ["surfaces.agent", adapter.layout.surfaces.agent],
+        ["surfaces.command", adapter.layout.surfaces.command],
+    ];
+    for (const [field, value] of optionalPaths)
+        need(value === undefined || value.length > 0, `layout.${field} is "" — absence is spelled by omitting the key, never by an empty string`);
+    // A7: `hooksConventionPath` names a FILE, and every reader treats it as one
+    // (dirname it, parse it, round-trip it). `opencodeLayout` used to name the
+    // DIRECTORY `.opencode/plugin` there, so each of those readers was wrong
+    // about it in its own way. A basename with an extension is the cheapest
+    // statement of "this is a file" that does not touch the disk.
+    if (adapter.layout.hooksConventionPath !== undefined)
+        need(/\.[^./]+$/.test((0, node_path_1.basename)(adapter.layout.hooksConventionPath)), `layout.hooksConventionPath "${adapter.layout.hooksConventionPath}" has no file extension — it names a standalone hooks FILE, not a directory (omit it when the harness has none)`);
     need(typeof adapter.detect === "function", "detect is not a function");
     // --- Pillar 2 transport ports: required ONLY for the capabilities the
     // adapter declares. A pillar-1-only adapter (harnessTesting:false) may omit
@@ -65,9 +105,9 @@ function checkAdapterConformance(adapter) {
         ["dialect", adapter.dialect.name],
         ["layout", adapter.layout.name],
     ];
-    if (caps.harnessTesting) {
-        need(adapter.runtime !== undefined, "capabilities.harnessTesting is true but runtime is missing");
-        need(adapter.modelMock !== undefined, "capabilities.harnessTesting is true but modelMock is missing");
+    if (adapter.harnessTesting) {
+        need(adapter.runtime !== undefined, "harnessTesting is true but runtime is missing");
+        need(adapter.modelMock !== undefined, "harnessTesting is true but modelMock is missing");
         if (adapter.runtime) {
             need(adapter.runtime.agentBinary.length > 0, "runtime.agentBinary is empty");
             need(adapter.runtime.modelBaseUrlEnv.length > 0, "runtime.modelBaseUrlEnv is empty");
@@ -77,12 +117,30 @@ function checkAdapterConformance(adapter) {
             need(adapter.modelMock.modelEndpoint.length > 0, "modelMock.modelEndpoint is empty");
             portNames.push(["modelMock", adapter.modelMock.name]);
         }
+        // 🔴 THE CHECK THAT WAS MISSING, AND THE STATE IT MISSED WAS SHIPPING.
+        // This block checked `runtime` and `modelMock` and not the DRIVER, so
+        // `opencodeAdapter` — `harnessTesting: true`, both ports present, no thunk
+        // — passed conformance and threw at run time inside `runHarnessTest`. The
+        // type now makes that shape unwritable in TypeScript; this is the same
+        // statement for an adapter the type never saw.
+        need(typeof adapter.harnessTestDriver === "function", "harnessTesting is true but harnessTestDriver is missing — the runner has nothing to dispatch through");
+        // ⚠️ AND THE SAME STATEMENT FOR THE PORT ADDED BY #263, because the comment
+        // above describes a gap that has now recurred once. `liveDriver` is
+        // REQUIRED in this arm of the type, so TypeScript covers every adapter it
+        // compiles — and this function exists for the adapters it does not: a
+        // third-party JavaScript one, or a cast object. Without this line such an
+        // adapter passed conformance and threw later inside `modelAccessFor` or a
+        // behavioral probe, which is exactly how `opencodeAdapter` shipped.
+        need(typeof adapter.liveDriver === "function", "harnessTesting is true but liveDriver is missing — the executing tiers have no model access or probe to read");
     }
     else {
-        need(adapter.runtime === undefined && adapter.modelMock === undefined, "capabilities.harnessTesting is false — omit runtime/modelMock (a pillar-1-only adapter must not ship a half-wired transport)");
+        need(adapter.runtime === undefined &&
+            adapter.modelMock === undefined &&
+            adapter.harnessTestDriver === undefined &&
+            adapter.liveDriver === undefined, "harnessTesting is false — omit runtime/modelMock/harnessTestDriver/liveDriver (a pillar-1-only adapter must not ship a half-wired transport)");
     }
-    if (caps.shellHooks) {
-        need(adapter.hookProtocol !== undefined, "capabilities.shellHooks is true but hookProtocol is missing");
+    if (adapter.shellHooks) {
+        need(adapter.hookProtocol !== undefined, "shellHooks is true but hookProtocol is missing");
         if (adapter.hookProtocol) {
             need(Number.isInteger(adapter.hookProtocol.blockExitCode), "hookProtocol.blockExitCode is not an integer");
             // A shell-hook harness must declare WHICH events can inject developer
@@ -106,7 +164,7 @@ function checkAdapterConformance(adapter) {
         }
     }
     else {
-        need(adapter.hookProtocol === undefined, "capabilities.shellHooks is false — omit hookProtocol (hooks are code modules, not shell processes)");
+        need(adapter.hookProtocol === undefined, "shellHooks is false — omit hookProtocol (hooks are code modules, not shell processes)");
     }
     // Cross-port invariants — the kind of mismatch a copy-paste authoring slip
     // produces, that no single-port check would catch. Only the present ports.
@@ -115,8 +173,23 @@ function checkAdapterConformance(adapter) {
     }
     need(adapter.layout.pluginRootToken === adapter.dialect.pluginRootToken, "layout.pluginRootToken and dialect.pluginRootToken disagree");
     need(adapter.dialect.instructionTargets.includes(adapter.layout.instructionFile), `layout.instructionFile "${adapter.layout.instructionFile}" is not one of dialect.instructionTargets`);
-    need(adapter.layout.settingsFormat === "json" ||
-        adapter.layout.settingsFormat === "toml", `layout.settingsFormat "${adapter.layout.settingsFormat}" is not "json" | "toml"`);
+    // 🔴 THE ENUM CHECK THAT USED TO BE HERE IS DELETED, and its deletion is the
+    // ratchet rather than a loosening. It asserted
+    // `layout.settingsFormat === "json" || === "toml"` — the core re-checking a
+    // closed set it had itself declared, which is the tell that the "data" field
+    // was a hidden switch. With a CODEC there is no set to be outside of, so a
+    // third-party adapter whose settings are YAML is legal and every reader
+    // already handles it. What IS checked is the round trip, below: a codec has
+    // to be able to read back what it wrote.
+    need(adapter.layout.settings.label.length > 0, "layout.settings has no label");
+    try {
+        const probe = { vigilesConformance: { n: 1 } };
+        const back = adapter.layout.settings.parse(adapter.layout.settings.render(probe));
+        need(JSON.stringify(back) === JSON.stringify(probe), `layout.settings ("${adapter.layout.settings.label}") does not round-trip: rendered then parsed gave ${JSON.stringify(back)}`);
+    }
+    catch (e) {
+        need(false, `layout.settings ("${adapter.layout.settings.label}") threw on its own output: ${String(e)}`);
+    }
     // Behavioural: the dialect drives the compiler — its own built-in tool must
     // pass the subagent tool-contract check under this dialect.
     const tool = adapter.dialect.builtinAgentTools[0];
@@ -150,35 +223,43 @@ function assertAdapterConformance(adapter) {
  * runtime+modelMock so the caller can use them without re-checking for undefined.
  */
 function assertHarnessTestable(adapter) {
-    if (!adapter.capabilities.harnessTesting ||
-        !adapter.runtime ||
-        !adapter.modelMock) {
+    if (!adapter.harnessTesting || !adapter.runtime || !adapter.modelMock) {
         throw new Error(`Adapter "${adapter.name}" does not support harness testing (pillar 2): it is reference-verification-only (no mockable runtime). Use it for compile/scan/lint, not runHarnessTest/runEval.`);
     }
     return { runtime: adapter.runtime, modelMock: adapter.modelMock };
 }
 /**
  * Behavioural conformance the pure checks can't reach: write a minimal settings
- * file in the adapter's declared `settingsFormat` (with a hook), load it through
+ * file using the adapter's OWN codec and registration shape, load it through
  * the adapter's `layout`, and assert the hooks actually came back. This is what
  * catches a layout that points at the right file but in the wrong format (the
  * JSON-vs-TOML trap) — the pure checker would pass it, the agent would silently
  * run with zero hooks. Does filesystem IO, so it's a separate opt-in assert.
  */
 function assertAdapterLoadsHooks(adapter) {
+    // Only a shell-hook harness has a hooks file to round-trip; the caller
+    // (`adapter-contract.test.ts`) already skips the others loudly, and the type
+    // is what says so — `hookProtocol` is `?: never` on the `shellHooks: false`
+    // arm, so this narrowing is the union doing its job rather than a guard.
+    if (!adapter.shellHooks) {
+        throw new Error(`Adapter "${adapter.name}" declares shellHooks:false — there is no shell-hook settings round-trip to assert.`);
+    }
     const dir = (0, tmp_root_js_1.makeTmpDir)("conformance");
     try {
         const settingsAbs = (0, node_path_1.join)(dir, adapter.layout.settingsPath);
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(settingsAbs), { recursive: true });
-        const content = adapter.layout.settingsFormat === "toml"
-            ? '[[hooks.PreToolUse]]\ncommand = "echo conformance"\n'
-            : JSON.stringify({
-                hooks: { PreToolUse: [{ command: "echo conformance" }] },
-            });
+        // 🔴 THE FIXTURE IS NOW BUILT FROM THE PORTS, not from a format branch.
+        // It used to be `settingsFormat === "toml" ? <TOML text> : <JSON text>`,
+        // which tested the two encodings the CHECK knew about rather than the ones
+        // the ADAPTER declares — a third encoding would have been handed JSON and
+        // failed for the wrong reason. `registration` supplies the harness's entry
+        // SHAPE and `settings.render` its ENCODING, which is exactly the pair this
+        // assertion exists to prove is wired to the same file.
+        const content = adapter.layout.settings.render(adapter.hookProtocol.registration("PreToolUse", undefined, "echo conformance"));
         (0, node_fs_1.writeFileSync)(settingsAbs, content);
         const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, adapter.layout);
         if (!loaded.settings.hooks) {
-            throw new Error(`Adapter "${adapter.name}": loadPlugin read no hooks from a ${adapter.layout.settingsFormat} settings file at ${adapter.layout.settingsPath} — the settings-format wiring is broken.`);
+            throw new Error(`Adapter "${adapter.name}": loadPlugin read no hooks from a ${adapter.layout.settings.label} settings file at ${adapter.layout.settingsPath} — the settings codec / registration wiring is broken.`);
         }
     }
     finally {

package/dist/adapter-registry.d.ts

@@ -1,21 +1,68 @@
-/**
- * Adapter registry — the composition-root list the CLI uses to auto-detect which
- * harness a repo targets. The library API selects an adapter by import
- * (`vigiles/claude-code`); the CLI can't, so it walks this registry. Claude Code
- * is the default, so detection is backwards-compatible: an undetected repo (or a
- * repo with no adapter markers) resolves to Claude Code exactly as before.
- *
- * Adding a harness = add its `HarnessAdapter` to `ADAPTERS` (and a
- * `vigiles/<harness>` export). Order matters only if two adapters could both
- * match a repo; `detect()` returns a specificity score so the strongest signal
- * 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. */
-export declare const ADAPTERS: readonly HarnessAdapter[];
+/**
+ * All registered adapters. detect() specificity (not order) breaks ties.
+ *
+ * 🔴 `as const satisfies`, NOT a `readonly HarnessAdapter[]` ANNOTATION, and the
+ * difference is the whole of {@link HarnessName}. An annotation widens
+ * `name: "claude-code"` to `string`, so the registry cannot say which names
+ * exist and every consumer that needed to know had to write the list out again
+ * — which is how `ProbeHarness = "claude-code" | "codex"` and the lint rule's
+ * `DEFAULT_NAMES` came to be hand-maintained copies of this array. `satisfies`
+ * keeps the literal types while still checking each element against the port.
+ */
+export declare const ADAPTERS: readonly [{
+    readonly name: "claude-code";
+    readonly harnessTesting: true;
+    readonly shellHooks: true;
+    readonly subagents: true;
+    readonly dialect: import("./adapter.js").HarnessDialect;
+    readonly layout: import("./adapter.js").PluginLayout;
+    readonly runtime: import("./adapter.js").HarnessRuntime;
+    readonly hookProtocol: import("./adapter.js").HookProtocol;
+    readonly modelMock: import("./adapter.js").ModelMock;
+    readonly harnessTestDriver: () => Promise<import("./harness-test.js").HarnessTestDriver>;
+    readonly liveDriver: () => Promise<import("./core/live-driver.js").HarnessLiveDriver>;
+    readonly claims: (path: string) => boolean;
+    readonly detect: (exists: (repoRelative: string) => boolean) => import("./core/adapter.js").DetectSignal;
+    readonly advisories: (read: import("./core/adapter.js").InstallReader) => readonly string[];
+}, {
+    readonly name: "codex";
+    readonly harnessTesting: true;
+    readonly shellHooks: true;
+    readonly subagents: false;
+    readonly dialect: import("./adapter.js").HarnessDialect;
+    readonly layout: import("./adapter.js").PluginLayout;
+    readonly runtime: import("./adapter.js").HarnessRuntime;
+    readonly hookProtocol: import("./adapter.js").HookProtocol;
+    readonly modelMock: import("./adapter.js").ModelMock;
+    readonly harnessTestDriver: () => Promise<import("./harness-test.js").HarnessTestDriver>;
+    readonly liveDriver: () => Promise<import("./core/live-driver.js").HarnessLiveDriver>;
+    readonly claims: (path: string) => boolean;
+    readonly detect: (exists: (repoRelative: string) => boolean) => import("./core/adapter.js").DetectSignal;
+    readonly advisories: () => readonly string[];
+}];
+/**
+ * Every registered harness name, derived from {@link ADAPTERS} — `"claude-code"
+ * | "codex"` today, and whatever the array holds tomorrow.
+ *
+ * ⚠️ WHAT THIS DOES NOT CATCH, stated because the type looks stronger than it
+ * is: two adapters declaring the SAME name collapse the union silently (a union
+ * of duplicates is that one member), so this type would still read
+ * `"claude-code" | "codex"` with three adapters registered and two of them
+ * called `codex`. `adapter-contract.test.ts` asserts the set size instead —
+ * a test, because there is no type-level cardinality to assert against.
+ *
+ * ⚠️ AND IT IS NOT A CEILING ON COMPARING NAMES. A branded or literal string is
+ * still comparable to a string literal in TypeScript (`===` uses comparability,
+ * not assignability — measured in the redesign's section 7), so this type cannot
+ * make `adapter.name === "codex"` an error. What stops that is the
+ * `local/no-harness-names` lint rule; what this type does is remove the REASON
+ * to write such a comparison, by letting the one list be the only list.
+ */
+export type HarnessName = (typeof ADAPTERS)[number]["name"];
 /** The result of auto-detecting a harness from a repo's layout. */
 export interface DetectResult {
     readonly adapter: HarnessAdapter;

package/dist/adapter-registry.js

@@ -12,13 +12,37 @@ exports.resolveHarnessSelection = resolveHarnessSelection;
 exports.resolveHarnessAdapters = resolveHarnessAdapters;
 exports.declaredHarnessNames = declaredHarnessNames;
 exports.resolveDeclaredHarnesses = resolveDeclaredHarnesses;
+/**
+ * Adapter registry — the composition-root list the CLI uses to auto-detect which
+ * harness a repo targets. The library API selects an adapter by import
+ * (`vigiles/claude-code`); the CLI can't, so it walks this registry. Claude Code
+ * is the default, so detection is backwards-compatible: an undetected repo (or a
+ * repo with no adapter markers) resolves to Claude Code exactly as before.
+ *
+ * Adding a harness = add its `HarnessAdapter` to `ADAPTERS` (and a
+ * `vigiles/<harness>` export). Order matters only if two adapters could both
+ * match a repo; `detect()` returns a specificity score so the strongest signal
+ * wins regardless of order.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 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");
 /** The default adapter when detection finds no harness markers. */
 exports.defaultAdapter = adapter_js_1.claudeCodeAdapter;
-/** All registered adapters. detect() specificity (not order) breaks ties. */
+/**
+ * All registered adapters. detect() specificity (not order) breaks ties.
+ *
+ * 🔴 `as const satisfies`, NOT a `readonly HarnessAdapter[]` ANNOTATION, and the
+ * difference is the whole of {@link HarnessName}. An annotation widens
+ * `name: "claude-code"` to `string`, so the registry cannot say which names
+ * exist and every consumer that needed to know had to write the list out again
+ * — which is how `ProbeHarness = "claude-code" | "codex"` and the lint rule's
+ * `DEFAULT_NAMES` came to be hand-maintained copies of this array. `satisfies`
+ * keeps the literal types while still checking each element against the port.
+ */
 exports.ADAPTERS = [
     adapter_js_1.claudeCodeAdapter,
     adapter_js_2.codexAdapter,
@@ -35,12 +59,20 @@ exports.ADAPTERS = [
  * `research/audit-harness-dx.md`.
  */
 function detectAdapterResult(root) {
-    const scored = exports.ADAPTERS.map((a) => ({ a, score: a.detect(root) })).filter((s) => s.score > 0);
+    // 🔴 THE DOMAIN OWNS THE FILESYSTEM, THE ADAPTER OWNS THE QUESTION. `detect`
+    // used to be handed `root` and reach for `node:fs` itself, so an adapter
+    // could enumerate anything under it — the inversion `claims` exists to
+    // prevent, sitting right next to it. This predicate is the whole of what an
+    // adapter can do, and `adapter-properties.test.ts` asserts each one asks only
+    // about paths its own `claims` covers.
+    const exists = (repoRelative) => (0, node_fs_1.existsSync)((0, node_path_1.join)(root, repoRelative));
+    const scored = exports.ADAPTERS.map((a) => ({ a, signal: a.detect(exists) })).filter((s) => s.signal.specificity > 0);
     if (scored.length === 0) {
         return { adapter: exports.defaultAdapter, fallback: true, ambiguousWith: [] };
     }
-    const top = Math.max(...scored.map((s) => s.score));
-    let winners = scored.filter((s) => s.score === top).map((s) => s.a);
+    const top = Math.max(...scored.map((s) => s.signal.specificity));
+    const atTop = scored.filter((s) => s.signal.specificity === top);
+    let winners = atTop.map((s) => s.a);
     // Mirror-collapse: the only false-"both" tie is at the weak instruction-file level
     // (top === 1 — Claude Code via CLAUDE.md, Codex via AGENTS.md). When those two files
     // are a MIRROR (symlink or byte-identical, per detectInstructionMirror), that's ONE
@@ -49,13 +81,49 @@ function detectAdapterResult(root) {
     // so it resolves to Claude Code without a spurious "matches claude-code, codex" notice.
     // A genuine dual instruction file (different content, or a real .codex/config.toml at
     // score 3) is NOT a mirror at top 1 → stays ambiguous, exactly as it should.
+    //
+    // 🔴 IT USED TO NAME A HARNESS TO DO THIS — `winners.some(w => w.name ===
+    // "codex")` and then `filter(w => w.name !== "codex")`, in the composition
+    // root, with the tie-break decided by which literal was typed here. What the
+    // rule is actually about is the KIND of marker that matched, which is what
+    // `DetectSignal.via` now carries: every winner matched only by its
+    // instruction file, and those files are a mirror, so it is one config. A
+    // third harness reading `AGENTS.md` now collapses correctly with no edit
+    // here. Which single adapter survives is settled just below.
     if (winners.length > 1 &&
-        top === 1 &&
-        winners.some((w) => w.name === "codex") &&
-        (0, compose_js_1.detectInstructionMirror)(root) !== null) {
-        // At top === 1 with a mirror, both files exist so Claude Code (CLAUDE.md) is
-        // always a co-winner — dropping codex leaves a non-empty set.
-        winners = winners.filter((w) => w.name !== "codex");
+        atTop.every((s) => s.signal.via === "instruction-file")) {
+        if ((0, compose_js_1.detectInstructionMirror)(root) !== null) {
+            // 🔴 THE MIRROR SAYS THESE ARE ONE CONFIG. IT DOES NOT SAY WHOSE — and a
+            // first draft of this collapse read the symlink's DIRECTION as if it did,
+            // keeping whichever adapter reads the link's real target. That silently
+            // reversed a repo with `CLAUDE.md -> AGENTS.md`: the audit selected the
+            // AGENTS-reading harness and then looked for its surfaces, missing
+            // `.claude/skills` entirely. The direction is a BRIDGING artifact — an
+            // AGENTS-first repository adds the `CLAUDE.md` link precisely so that
+            // Claude Code works — so if anything it is evidence FOR the linking
+            // side, and certainly not against it. Byte-identical mirrors (what
+            // rulesync and Ruler produce) carry no direction at all, which is the
+            // same problem with the ambiguity visible instead of hidden.
+            //
+            // So BOTH shapes are treated the same way: the collapse still has to
+            // produce ONE answer, because that is its whole job — the files are one
+            // config, and a "matches claude-code, codex" notice would be wrong — and
+            // the tie is broken by REGISTRY ORDER, deterministically, with the reason
+            // written here rather than left to whoever reads `winners[0]` later.
+            // That is the answer this repository shipped before the collapse was
+            // rewritten to stop naming a harness, reached without comparing a name
+            // against a literal in this file.
+            //
+            // ⏳ WHAT IS GENUINELY OPEN, stated rather than buried: a repository that
+            // means an AGENTS-reading harness AND keeps a `CLAUDE.md` bridge has no
+            // way to say so at this level, and registry order will answer Claude
+            // Code. The signal that would settle it is a STRONGER marker (a real
+            // `.codex/config.toml`, an explicit `harness` in config, `--harness=`),
+            // all of which already outrank this branch — `atTop.every(via ===
+            // "instruction-file")` is exactly the guard that keeps them from
+            // reaching here. Guessing from the link direction is not a substitute.
+            winners = [winners[0]];
+        }
     }
     return {
         adapter: winners[0],

package/dist/adapter.d.ts

@@ -17,7 +17,28 @@
  */
 export type { HarnessAdapter, AdapterCapabilities } from "./core/adapter.js";
 export type { HarnessDialect } from "./core/dialect.js";
-export type { PluginLayout } from "./core/layout.js";
+export type { PluginLayout, SurfaceDirs, SurfaceKind } from "./core/layout.js";
+export { executableSourceDirs, materializePrefix, surfaceDirs, } from "./core/layout.js";
+/**
+ * The instruction-chain vocabulary `PluginLayout.instructionChain` speaks.
+ *
+ * Exported because the method is on the port: without these an adapter author
+ * cannot write a return type, which makes the interface unimplementable from
+ * outside this package. `EMPTY_CHAIN` is the honest answer for a harness with no
+ * instruction surface — spelling out five empty arrays at each such site invites
+ * one of them to be forgotten.
+ */
+export type { InstructionChain, InstructionRole, InstructionScope, LoadedInstruction, NamedImport, NotLoadedReason, PatternFrom, UnloadedInstruction, } from "./core/instruction-chain.js";
+export { EMPTY_CHAIN } from "./core/instruction-chain.js";
+/**
+ * ⚠️ `SettingsCodec` was in the same position and is exported here for the same
+ * reason: `PluginLayout.settings` has been typed as one since the codec landed,
+ * and the authoring barrel never re-exported it, so `docs/adapter-api.md`
+ * documents a field whose type a third party could not name. One line, and the
+ * alternative is a port that cannot be implemented from outside.
+ */
+export type { SettingsCodec } from "./core/settings-codec.js";
+export { jsonSettingsCodec, tomlSettingsCodec } from "./core/settings-codec.js";
 export type { HarnessRuntime } from "./core/runtime.js";
 export type { HookProtocol } from "./core/hook-protocol.js";
 export type { ModelMock } from "./core/model-mock.js";
@@ -30,5 +51,5 @@ export type { ModelMock } from "./core/model-mock.js";
  */
 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";
+export { ADAPTERS, defaultAdapter, detectAdapter, detectAdapterResult, resolveAdapter, getAdapter, type DetectResult, type HarnessName, } from "./adapter-registry.js";
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.js

@@ -1,6 +1,18 @@
 "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 = exports.layoutClaims = void 0;
+exports.getAdapter = exports.resolveAdapter = exports.detectAdapterResult = exports.detectAdapter = exports.defaultAdapter = exports.ADAPTERS = exports.assertHarnessTestable = exports.assertAdapterLoadsHooks = exports.assertAdapterConformance = exports.checkAdapterConformance = exports.layoutClaims = exports.tomlSettingsCodec = exports.jsonSettingsCodec = exports.EMPTY_CHAIN = exports.surfaceDirs = exports.materializePrefix = exports.executableSourceDirs = void 0;
+// The three derived readers. They are part of the port's surface, not helpers:
+// an adapter author reads a layout through them, and they are what replaced the
+// `surfaceDirs` / `intraRefDirs` / `materializeRoot` FIELDS.
+var layout_js_1 = require("./core/layout.js");
+Object.defineProperty(exports, "executableSourceDirs", { enumerable: true, get: function () { return layout_js_1.executableSourceDirs; } });
+Object.defineProperty(exports, "materializePrefix", { enumerable: true, get: function () { return layout_js_1.materializePrefix; } });
+Object.defineProperty(exports, "surfaceDirs", { enumerable: true, get: function () { return layout_js_1.surfaceDirs; } });
+var instruction_chain_js_1 = require("./core/instruction-chain.js");
+Object.defineProperty(exports, "EMPTY_CHAIN", { enumerable: true, get: function () { return instruction_chain_js_1.EMPTY_CHAIN; } });
+var settings_codec_js_1 = require("./core/settings-codec.js");
+Object.defineProperty(exports, "jsonSettingsCodec", { enumerable: true, get: function () { return settings_codec_js_1.jsonSettingsCodec; } });
+Object.defineProperty(exports, "tomlSettingsCodec", { enumerable: true, get: function () { return settings_codec_js_1.tomlSettingsCodec; } });
 /**
  * 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

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

@@ -1,3 +1,33 @@
-import type { HarnessAdapter } from "../../core/adapter.js";
-export declare const claudeCodeAdapter: HarnessAdapter;
+/**
+ * claudeCodeAdapter — the Claude Code `HarnessAdapter`: the five port
+ * implementations bundled, plus a `detect` that recognizes a Claude Code repo
+ * (a `.claude-plugin/` manifest, a `.claude/settings.json`, or a `CLAUDE.md`).
+ * This is the reference adapter a second harness (Codex, Gemini, …) mirrors.
+ */
+import type { DetectSignal, InstallReader } from "../../core/adapter.js";
+export declare const claudeCodeAdapter: {
+    readonly name: "claude-code";
+    readonly harnessTesting: true;
+    readonly shellHooks: true;
+    readonly subagents: true;
+    readonly dialect: import("./dialect.js").HarnessDialect;
+    readonly layout: import("../../adapter.js").PluginLayout;
+    readonly runtime: import("../../adapter.js").HarnessRuntime;
+    readonly hookProtocol: import("../../adapter.js").HookProtocol;
+    readonly modelMock: import("../../adapter.js").ModelMock;
+    readonly harnessTestDriver: () => Promise<import("../../harness-test.js").HarnessTestDriver>;
+    readonly liveDriver: () => Promise<import("../../core/live-driver.js").HarnessLiveDriver>;
+    readonly claims: (path: string) => boolean;
+    readonly detect: (exists: (repoRelative: string) => boolean) => DetectSignal;
+    /**
+     * The two install diagnostics that used to sit behind
+     * `if (adapter.name === "claude-code")` in the CLI, now reached through the
+     * port. Both are genuinely THIS harness's and both would MISLEAD on another
+     * one — the reachability fix line is `claude plugin install`, which a Codex
+     * user cannot run — which is why the gate was right and only its shape wrong.
+     *
+     * Never throws and never scores: each check degrades to "nothing to say".
+     */
+    readonly advisories: (read: InstallReader) => readonly string[];
+};
 //# sourceMappingURL=adapter.d.ts.map

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

@@ -1,14 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeAdapter = void 0;
-/**
- * claudeCodeAdapter — the Claude Code `HarnessAdapter`: the five port
- * implementations bundled, plus a `detect` that recognizes a Claude Code repo
- * (a `.claude-plugin/` manifest, a `.claude/settings.json`, or a `CLAUDE.md`).
- * This is the reference adapter a second harness (Codex, Gemini, …) mirrors.
- */
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
+const dialect_drift_js_1 = require("./dialect-drift.js");
+const skill_reachability_js_1 = require("./skill-reachability.js");
 const dialect_js_1 = require("./dialect.js");
 const layout_js_1 = require("./layout.js");
 const surface_discovery_js_1 = require("../../core/surface-discovery.js");
@@ -19,12 +13,14 @@ exports.claudeCodeAdapter = {
     name: "claude-code",
     // The reference harness: every tier. Mockable transport (Anthropic SSE) and
     // shell hooks (exit 2 / decision JSON) — both pillars, all tiers.
-    capabilities: {
-        referenceVerification: true,
-        harnessTesting: true,
-        shellHooks: true,
-        subagents: true,
-    },
+    //
+    // The flags are FLAT, not nested under `capabilities`, because TypeScript
+    // narrows a union by a discriminant on the object itself and never by
+    // `a.capabilities.x` — nesting them is what made "declares the capability,
+    // ships no port" expressible at all.
+    harnessTesting: true,
+    shellHooks: true,
+    subagents: true,
     dialect: dialect_js_1.claudeCodeDialect,
     layout: layout_js_1.claudeCodeLayout,
     runtime: runtime_js_1.claudeCodeRuntime,
@@ -33,22 +29,47 @@ 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,
+    // The executing tiers' driver, thunked for the same reason: it reaches the
+    // real-model graph, which an adapter READ (the hook runtime) must not pay for.
+    liveDriver: async () => (await import("../../eval.js")).claudeCodeLiveDriver,
     // 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) {
+    // Takes the domain's `exists`, never a root: this adapter cannot enumerate
+    // anything, and it asks only about the three paths its own `claims` covers.
+    detect(exists) {
         // Most specific signal wins: a plugin manifest (3) > repo settings (2) >
         // a bare CLAUDE.md (1, weak — many tools also read it / AGENTS.md).
-        const has = (rel) => (0, node_fs_1.existsSync)((0, node_path_1.join)(root, rel));
-        if (has(layout_js_1.claudeCodeLayout.manifestPath))
-            return 3;
-        if (has(layout_js_1.claudeCodeLayout.settingsPath))
-            return 2;
-        if (has(layout_js_1.claudeCodeLayout.instructionFile))
-            return 1;
-        return 0;
+        if (exists(layout_js_1.claudeCodeLayout.manifestPath))
+            return { specificity: 3, via: "manifest" };
+        if (exists(layout_js_1.claudeCodeLayout.settingsPath))
+            return { specificity: 2, via: "settings" };
+        if (exists(layout_js_1.claudeCodeLayout.instructionFile))
+            return { specificity: 1, via: "instruction-file" };
+        return { specificity: 0, via: "instruction-file" };
+    },
+    /**
+     * The two install diagnostics that used to sit behind
+     * `if (adapter.name === "claude-code")` in the CLI, now reached through the
+     * port. Both are genuinely THIS harness's and both would MISLEAD on another
+     * one — the reachability fix line is `claude plugin install`, which a Codex
+     * user cannot run — which is why the gate was right and only its shape wrong.
+     *
+     * Never throws and never scores: each check degrades to "nothing to say".
+     */
+    advisories(read) {
+        return [
+            // Our hand-maintained tool/hook catalog vs the `@anthropic-ai/claude-code`
+            // actually installed on this machine. A machine read, not a repo read.
+            (0, dialect_drift_js_1.formatDialectDrift)((0, dialect_drift_js_1.checkDialectDrift)()),
+            // Can the agent SEE the skills vigiles ships here? `npm install` drops
+            // them in node_modules, which Claude Code never scans; the plugin install
+            // is what wires them, and until it runs the teaching surface is silently
+            // absent.
+            (0, skill_reachability_js_1.formatSkillReachability)((0, skill_reachability_js_1.checkSkillReachability)(read)),
+        ].filter((line) => line !== null);
     },
 };
 //# sourceMappingURL=adapter.js.map