vigiles 29.1.0 → 30.0.0

package/dist/core/adapter.d.ts

@@ -18,27 +18,29 @@ import type { HarnessRuntime } from "./runtime.js";
 import type { HookProtocol } from "./hook-protocol.js";
 import type { ModelMock } from "./model-mock.js";
 import type { HarnessTestDriver } from "./harness-driver.js";
+import type { HarnessLiveDriver } from "./live-driver.js";
 /**
  * Which vigiles pillars/tiers a harness can drive — the capability matrix made
- * executable (see `docs/harnesses.md`). Not every harness reaches every tier:
- * a closed, un-mockable one (Cursor, Devin, Amp, Amazon Q) can only ever do
- * pillar 1, and a harness whose hooks are in-process code modules (OpenCode)
- * has no shell-hook tier. Declaring this lets the conformance kit relax the
- * port requirements for what an adapter says it can't do (instead of forcing a
- * fake `runtime`/`modelMock`/`hookProtocol`), and lets the pillar-2 runners
- * refuse — rather than mysteriously hang on — an adapter that can't be mocked.
+ * executable (see `docs/harnesses.md`).
+ *
+ * 🔴 KEPT AS A TYPE, NOT AS A FIELD. The flags used to sit in a nested
+ * `capabilities` object on the adapter, and that nesting is precisely what made
+ * the illegal state below expressible: TypeScript narrows a union by a
+ * discriminant on the object ITSELF, never by `a.capabilities.x`, so no shape
+ * of this interface could have tied `harnessTesting: true` to the presence of a
+ * driver. The flags are now discriminants on `HarnessAdapter` directly; this
+ * interface remains as the documented projection of them.
+ *
+ * `referenceVerification` is gone. It was `true` on every adapter and its type
+ * was the literal `true` — a field that can hold one value carries no
+ * information, and the conformance check for it could not fail.
  */
 export interface AdapterCapabilities {
-    /**
-     * Pillar 1 — reference verification (dialect + layout). Always `true`: every
-     * harness with an instruction-file format can have its references verified.
-     */
-    readonly referenceVerification: true;
     /**
      * Pillar 2 — deterministic harness tests + evals: the binary can be spawned
-     * and pointed at a mock model. Requires `runtime` + `modelMock`. `false` for
-     * closed harnesses that route through a fixed backend (no BYOM): Cursor,
-     * Devin, Amp, Amazon Q — they are pillar-1-only adapters.
+     * and pointed at a mock model. Requires `runtime` + `modelMock` +
+     * `harnessTestDriver`. `false` for closed harnesses that route through a fixed
+     * backend (no BYOM): Cursor, Devin, Amp, Amazon Q — pillar-1-only adapters.
      */
     readonly harnessTesting: boolean;
     /**
@@ -56,65 +58,63 @@ export interface AdapterCapabilities {
      * is `false` those rules report **n/a** rather than running. `false` for Codex,
      * whose `[agents]` TOML is a concurrency table, not a tool-contract file — a
      * wholly different concept that deliberately shares the word.
+     *
+     * No port sits behind it, so it stays a plain flag on the base rather than
+     * becoming a discriminant of a union with nothing in its arms.
      */
     readonly subagents: boolean;
 }
-export interface HarnessAdapter {
+/**
+ * How, and how strongly, a repo looks like this harness.
+ *
+ * `via` exists so the REGISTRY can break a tie without naming a harness. The
+ * one false "both" tie is at the weak instruction-file level, where two
+ * adapters match on mirrored root files; `via: "instruction-file"` is what
+ * makes that case recognisable from the outside, and it used to be recognised
+ * by comparing a winner's `name` against a literal in the registry.
+ */
+export interface DetectSignal {
+    /** 0 = not this harness; higher = a more specific match. The registry picks
+     *  the highest scorer, so a strong signal (a plugin manifest) beats a weak
+     *  one (a shared `AGENTS.md`) regardless of registration order. */
+    readonly specificity: number;
+    /** WHICH kind of marker produced the score. */
+    readonly via: "manifest" | "settings" | "instruction-file";
+}
+/**
+ * The fields EVERY adapter has, whatever it can drive. The capability-gated
+ * ports are deliberately NOT here — see the unions below.
+ */
+interface AdapterBase {
     /** Stable identifier, e.g. "claude-code". The CLI/registry key. */
     readonly name: string;
-    /** What this harness can drive — gates which ports below are required. */
-    readonly capabilities: AdapterCapabilities;
     /** Format axis: tool catalog, hook events, instruction targets, plugin-root token. */
     readonly dialect: HarnessDialect;
     /** Layout axis: where the instruction file / skills / agents / hooks live on disk. */
     readonly layout: PluginLayout;
-    /** Transport axis: the agent binary to spawn + the mock-model env. Present iff
-     *  `capabilities.harnessTesting`. */
-    readonly runtime?: HarnessRuntime;
-    /** Transport axis: how a hook signals a block/deny. Present iff
-     *  `capabilities.shellHooks`. */
-    readonly hookProtocol?: HookProtocol;
-    /** Transport axis: the mock model's wire format + endpoints. Present iff
-     *  `capabilities.harnessTesting`. */
-    readonly modelMock?: ModelMock;
-    /**
-     * Pillar-2 deterministic-runner driver: how `runHarnessTest` builds this
-     * harness's argv, starts its scripted mock, and parses its stdout. Present iff
-     * `capabilities.harnessTesting` (it composes the runtime + modelMock into the
-     * one seam the runner dispatches through). Carried on the bundle so the runner
-     * never imports a sibling adapter to find it.
-     */
+    /** See {@link AdapterCapabilities.subagents}. */
+    readonly subagents: boolean;
     /**
-     * 🔴 A THUNK, NOT THE DRIVER, and the indirection is the whole point. A driver
-     * lives in `harness-test.ts`, which imports the conformance suite, which
-     * imports the compiler, which imports the cross-language symbol index, which
-     * loads a NATIVE binary. Holding the driver eagerly meant every consumer of an
-     * adapter paid for all of it — including the hook runtime, which reads only
-     * `dialect` and `hookProtocol` and never runs a harness test at all.
+     * How strongly, and by WHAT, a repo looks like it targets this harness — the
+     * CLI uses it to auto-detect which adapter to use (the library selects by
+     * import).
      *
-     * Measured 2026-09-19, `require("./adapter-registry.js")`:
+     * 🔴 IT TAKES A PREDICATE, NOT A ROOT, and that is the same rule `claims`
+     * follows one docblock down. `detect(root: string)` handed every adapter a
+     * directory and `node:fs`: an adapter could enumerate anything under it, so
+     * registering an adapter COULD change what vigiles reads in someone's
+     * repository — the exact inversion `claims` exists to prevent, sitting
+     * unnoticed beside it. With `exists` injected, an adapter can ask about a
+     * path and nothing else, and the domain decides what asking means. It also
+     * removes `node:fs` from the adapter bundles.
      *
-     *     eager:  107 modules, 7 ast-grep, 1 native .node
-     *
-     * ...on a path whose actual work takes about a millisecond. Calling the thunk
-     * is what loads the driver, so the test tier pays and the runtime does not.
-     *
-     * ASYNC because a dynamic `import()` is the only form that defers in BOTH
-     * environments this code runs in: the CJS `dist/` build (where TypeScript
-     * lowers it to a deferred `require`) and vitest loading the TS sources
-     * directly, where a synchronous `require` of a sibling `.ts` does not resolve
-     * at all — measured, not assumed.
-     */
-    readonly harnessTestDriver?: () => Promise<HarnessTestDriver>;
-    /**
-     * How strongly a repo at `root` looks like it targets this harness — the CLI
-     * uses it to auto-detect which adapter to use (the library selects by import).
-     * Returns a **specificity score**: 0 = not this harness; higher = a more
-     * specific match. The registry picks the highest scorer, so a strong signal
-     * (a `.claude-plugin/` manifest) beats a weak one (a bare `CLAUDE.md`, or an
-     * `AGENTS.md` that many harnesses share) regardless of registration order.
+     * The property a test asserts (`adapter-properties.test.ts`): `detect` may
+     * only ask about paths its own `claims` returns true for. An adapter that
+     * wanted to detect by a marker it does not read would be refused by that,
+     * which is the intended trade — a detector that reads what it does not claim
+     * is how a grade starts covering files nobody declared.
      */
-    detect(root: string): number;
+    detect(exists: (repoRelative: string) => boolean): DetectSignal;
     /**
      * Is this repo-relative path one THIS harness reads — "is it mine?"
      *
@@ -138,5 +138,157 @@ export interface HarnessAdapter {
      * Override it only for a location the `PluginLayout` fields cannot express.
      */
     claims(path: string): boolean;
+    /**
+     * Diagnostics about THIS harness's INSTALL on this machine that bear on how
+     * far the report can be trusted — never scored, printed as-is, one string per
+     * line. `[]` is the honest answer for a harness with nothing to say.
+     *
+     * 🔴 REQUIRED, NOT A CAPABILITY FLAG. A `localAdvisories: boolean` would be a
+     * flag with nothing behind it — the argument {@link AdapterCapabilities.subagents}
+     * already makes from the other side — because an empty array says exactly what
+     * `false` would say, and cannot fall out of step with the method the way a
+     * flag beside a port can.
+     *
+     * WHAT IT REPLACES: `if (adapter.name === "claude-code") { …two Claude Code
+     * install checks… }` in the CLI. Those checks are real and they are genuinely
+     * this harness's (one reads the installed vendor package, the other the
+     * plugin install), and run against another harness's repo they would print a
+     * fix line for a CLI that repo does not use. So the gate was right and its
+     * SHAPE was wrong: the consumer now prints uniformly and the knowledge sits
+     * with the adapter that has it.
+     *
+     * 🔴 IT TAKES A READER, NOT A ROOT — the same bound as `detect(exists)` one
+     * docblock up, for the same reason: handed a root, an adapter could enumerate
+     * anything in the repository, and registering an adapter would change what
+     * vigiles reads. {@link InstallReader.repo} answers only for paths this
+     * adapter `claims`, which `adapter-properties.test.ts` asserts.
+     */
+    advisories(read: InstallReader): readonly string[];
 }
+/**
+ * What {@link AdapterBase.advisories} may read.
+ *
+ * Built by the DOMAIN and handed in, so the adapter holds no filesystem. The two
+ * plain FACTS are here rather than as reads because the shipped checks need them
+ * from files NO adapter claims (`package.json`, and vigiles's own package inside
+ * `node_modules`) — an unclaimed read is exactly what the bound forbids, so the
+ * domain reads them once and passes the answer.
+ */
+export interface InstallReader {
+    /**
+     * A repo file's contents, or null when it is missing, unreadable, or NOT a
+     * path this adapter claims. A refusal and an absence are deliberately the same
+     * answer: an adapter must not be able to probe for the existence of files
+     * outside its own surface.
+     */
+    readonly repo: (repoRelative: string) => string | null;
+    /**
+     * A file under the user's HOME, or null. This is a read of the MACHINE, never
+     * of the repository — the plugin-install record lives there — and everything
+     * it feeds is advisory-only.
+     */
+    readonly home: (homeRelative: string) => string | null;
+    /** Does this repo take a dependency on vigiles? (From `package.json`, unclaimed.) */
+    readonly repoDependsOnVigiles: boolean;
+    /** Skill names vigiles ships inside its own installed package, if it is installed. */
+    readonly vendoredSkillNames: readonly string[];
+}
+/**
+ * Pillar 2's three ports, present IFF `harnessTesting` — as a union, so
+ * declaring the capability without the ports is a COMPILE error.
+ *
+ * 🔴 THE STATE THIS REMOVES WAS SHIPPING. `opencodeAdapter` declared
+ * `harnessTesting: true` and carried no `harnessTestDriver`; the runner threw
+ * at `harness-test.ts:782` — at RUN time, after a driver was asked for — and
+ * the conformance kit did not catch it, because it checked `runtime` and
+ * `modelMock` and not the thunk. Adding a third check would have been the
+ * third place to remember. The union needs no check at all: the shape is
+ * unwritable.
+ *
+ * The `?: never` arms matter as much as the `true` arm. Without them a
+ * `false` adapter could still carry a driver, which is the same defect
+ * pointing the other way — a port nothing will ever call, read by a reader as
+ * capability that is not there.
+ */
+type TestingPorts = {
+    readonly harnessTesting: true;
+    /** Transport axis: the agent binary to spawn + the mock-model env. */
+    readonly runtime: HarnessRuntime;
+    /** Transport axis: the mock model's wire format + endpoints. */
+    readonly modelMock: ModelMock;
+    /**
+     * Pillar-2 deterministic-runner driver: how `runHarnessTest` builds this
+     * harness's argv, starts its scripted mock, and parses its stdout.
+     *
+     * 🔴 A THUNK, NOT THE DRIVER, and the indirection is the whole point. A
+     * driver lives in `harness-test.ts`, which imports the conformance suite,
+     * which imports the compiler, which imports the cross-language symbol
+     * index, which loads a NATIVE binary. Holding the driver eagerly meant
+     * every consumer of an adapter paid for all of it — including the hook
+     * runtime, which reads only `dialect` and `hookProtocol` and never runs a
+     * harness test at all.
+     *
+     * Measured 2026-09-19, `require("./adapter-registry.js")`:
+     *
+     *     eager:  107 modules, 7 ast-grep, 1 native .node
+     *
+     * ...on a path whose actual work takes about a millisecond. Calling the
+     * thunk is what loads the driver, so the test tier pays and the runtime
+     * does not.
+     *
+     * ASYNC because a dynamic `import()` is the only form that defers in BOTH
+     * environments this code runs in: the CJS `dist/` build (where TypeScript
+     * lowers it to a deferred `require`) and vitest loading the TS sources
+     * directly, where a synchronous `require` of a sibling `.ts` does not
+     * resolve at all — measured, not assumed.
+     */
+    readonly harnessTestDriver: () => Promise<HarnessTestDriver>;
+    /**
+     * The EXECUTING tiers' driver: how vigiles drives this harness against a
+     * REAL model on the user's own credentials — which eval transport, how
+     * firing shows in the trace, whether a model is reachable and on whose
+     * bill, and whether the probe may stub the skill bodies. See
+     * {@link HarnessLiveDriver}.
+     *
+     * A THUNK, for the same measured load-cost reason as the line above: the
+     * eval transport reaches the whole real-model graph, and an adapter is
+     * read by the hook runtime, which never runs a model at all.
+     *
+     * 🔴 IN THIS ARM RATHER THAN BEHIND A FLAG OF ITS OWN. Every
+     * implementation that can go live can also be mocked, and this
+     * capability's own docblock already claims both tiers. A `liveEval:
+     * boolean` beside it would be `true` exactly when `harnessTesting` is —
+     * a second copy of one fact, which is the state this union exists to
+     * make unwritable. The `?: never` below is the other half: a `false`
+     * adapter cannot carry a live driver nothing will ever call.
+     */
+    readonly liveDriver: () => Promise<HarnessLiveDriver>;
+} | {
+    readonly harnessTesting: false;
+    readonly runtime?: never;
+    readonly modelMock?: never;
+    readonly harnessTestDriver?: never;
+    readonly liveDriver?: never;
+};
+/** The shell-hook port, present IFF `shellHooks`. Same construction, same reason. */
+type ShellHookPorts = {
+    readonly shellHooks: true;
+    /** Transport axis: how a hook signals a block/deny. */
+    readonly hookProtocol: HookProtocol;
+} | {
+    readonly shellHooks: false;
+    readonly hookProtocol?: never;
+};
+/**
+ * A harness, as one addable unit: the ports it implements plus the flags that
+ * say which ones those are.
+ *
+ * ⚠️ THE COST, NAMED SO NOBODY IS SURPRISED BY IT: a wrong adapter literal
+ * produces a TypeScript error against an INTERSECTION OF UNIONS, which reads
+ * badly — it will list both arms of each union rather than say "you declared
+ * harnessTesting and gave me no driver". That is why the conformance kit keeps
+ * its per-flag messages: the TYPE is the gate, the KIT is the explanation.
+ */
+export type HarnessAdapter = AdapterBase & TestingPorts & ShellHookPorts;
+export {};
 //# sourceMappingURL=adapter.d.ts.map

package/dist/core/compile.d.ts

@@ -160,8 +160,8 @@ export interface CompileSkillResult {
 export declare function compileSkill(spec: SkillSpec, options?: {
     basePath?: string;
     specFile?: string;
-    /** The harness dialect — selects the SKILL.md frontmatter profile. Omitting
-     *  it defaults to the Claude Code profile, so existing callers are unchanged. */
+    /** The harness dialect — supplies `skillFrontmatterKeys`. Omitting it emits
+     *  every key the compiler can render, so existing callers are unchanged. */
     dialect?: HarnessDialect;
 }): CompileSkillResult;
 export interface CompileAgentResult {

package/dist/core/compile.js

@@ -38,10 +38,16 @@ const skill_normalize_js_1 = require("./skill-normalize.js");
 const linters_js_1 = require("./linters.js");
 const tool_contract_js_1 = require("./tool-contract.js");
 const effects_js_1 = require("./effects.js");
+const dialect_js_1 = require("./dialect.js");
 // vigiles's default compile target when a spec names none and no dialect is
 // injected — a product convention (vigiles emits CLAUDE.md by default), not a
 // harness dialect. When a dialect IS injected its instructionTargets win.
-const DEFAULT_TARGET = "CLAUDE.md";
+//
+// DERIVED, not restated: this is the head of the one recognized-filenames list,
+// and `instructionTargets` already contracts that `[0]` is the default target.
+// Writing the literal here made "what vigiles recognizes" and "what vigiles
+// emits" two facts that could disagree while both looking right.
+const DEFAULT_TARGET = dialect_js_1.DEFAULT_INSTRUCTION_TARGETS[0];
 // ---------------------------------------------------------------------------
 // Hash utilities
 // ---------------------------------------------------------------------------
@@ -781,46 +787,54 @@ function yamlScalar(value) {
     // A JSON string IS a YAML double-quoted scalar, escaping included.
     return JSON.stringify(value);
 }
-function renderSkillFrontmatter(spec, 
-// Downstream of the SkillFrontmatterProfile alias (src/core/dialect.ts).
-// eslint-disable-next-line local/no-harness-names -- goes away with that alias
-profile = "claude-code") {
-    const fm = [
-        "---",
-        `name: ${yamlScalar(spec.name)}`,
-        `description: ${yamlScalar(spec.description)}`,
-    ];
-    // The CC-only keys below are inert in a minimal (Codex/OpenCode) SKILL.md, so
-    // they're omitted entirely under that profile.
-    // Downstream of the SkillFrontmatterProfile alias (src/core/dialect.ts).
-    // eslint-disable-next-line local/no-harness-names -- goes away with that alias
-    if (profile === "claude-code") {
-        if (spec.disableModelInvocation !== undefined) {
-            fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
-        }
-        if (spec.context !== undefined)
-            fm.push(`context: ${spec.context}`);
-        const argHint = spec.inputs && spec.inputs.length > 0
-            ? renderArgumentHint(spec.inputs)
-            : spec.argumentHint;
-        if (argHint)
-            fm.push(`argument-hint: ${yamlScalar(argHint)}`);
-        if (spec.tools && spec.tools.length > 0) {
-            // A Claude Code SKILL declares its tool contract under `allowed-tools`
-            // (NOT `tools:` — that's the SUBAGENT key), as a real YAML sequence. Flow
-            // style keeps it one line while parsing as a list, not a single comma
-            // scalar. Previously this emitted `tools: a, b` — the wrong key AND an
-            // ambiguous scalar, so the restriction was lost on the CC round-trip. (#107)
-            fm.push(`allowed-tools: [${spec.tools.join(", ")}]`);
-        }
-        if (spec.disallowedTools && spec.disallowedTools.length > 0) {
-            // 🔴 `disallowed-tools`, HYPHENATED — that is a skill's fence. A subagent's
-            // key is `disallowedTools:` (camelCase) and a different reader parses it, so
-            // writing the agent spelling here emits a key nothing looks at: inert, and
-            // inert in the direction that reads as protection. Same class as the #107
-            // defect two lines up, where `tools:` on a skill silently lost the contract.
-            fm.push(`disallowed-tools: [${spec.disallowedTools.join(", ")}]`);
-        }
+/**
+ * Render a SKILL.md frontmatter block, emitting a key iff `keys` holds it.
+ *
+ * 🔴 ONE CODE PATH, NOT A PROFILE BRANCH. This used to take a
+ * `SkillFrontmatterProfile` (`"claude-code" | "minimal"`) and wrap five `push`
+ * calls in `if (profile === "claude-code")`. The branch was never about a
+ * harness: it was about which keys the reader on the other end parses, which is
+ * exactly what a key set says. A harness that reads four of the seven now gets
+ * four, instead of falling into whichever of two buckets someone picked for it.
+ */
+function renderSkillFrontmatter(spec, keys = dialect_js_1.RENDERABLE_SKILL_FRONTMATTER_KEYS) {
+    const emits = (key) => keys.includes(key);
+    const fm = ["---"];
+    if (emits("name"))
+        fm.push(`name: ${yamlScalar(spec.name)}`);
+    if (emits("description")) {
+        fm.push(`description: ${yamlScalar(spec.description)}`);
+    }
+    if (emits("disable-model-invocation") &&
+        spec.disableModelInvocation !== undefined) {
+        fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
+    }
+    if (emits("context") && spec.context !== undefined) {
+        fm.push(`context: ${spec.context}`);
+    }
+    const argHint = spec.inputs && spec.inputs.length > 0
+        ? renderArgumentHint(spec.inputs)
+        : spec.argumentHint;
+    if (emits("argument-hint") && argHint) {
+        fm.push(`argument-hint: ${yamlScalar(argHint)}`);
+    }
+    if (emits("allowed-tools") && spec.tools && spec.tools.length > 0) {
+        // A Claude Code SKILL declares its tool contract under `allowed-tools`
+        // (NOT `tools:` — that's the SUBAGENT key), as a real YAML sequence. Flow
+        // style keeps it one line while parsing as a list, not a single comma
+        // scalar. Previously this emitted `tools: a, b` — the wrong key AND an
+        // ambiguous scalar, so the restriction was lost on the CC round-trip. (#107)
+        fm.push(`allowed-tools: [${spec.tools.join(", ")}]`);
+    }
+    if (emits("disallowed-tools") &&
+        spec.disallowedTools &&
+        spec.disallowedTools.length > 0) {
+        // 🔴 `disallowed-tools`, HYPHENATED — that is a skill's fence. A subagent's
+        // key is `disallowedTools:` (camelCase) and a different reader parses it, so
+        // writing the agent spelling here emits a key nothing looks at: inert, and
+        // inert in the direction that reads as protection. Same class as the #107
+        // defect two lines up, where `tools:` on a skill silently lost the contract.
+        fm.push(`disallowed-tools: [${spec.disallowedTools.join(", ")}]`);
     }
     fm.push("---");
     return fm.join("\n");
@@ -899,10 +913,7 @@ function compileSkill(spec, options = {}) {
     spec = (0, skill_normalize_js_1.foldLegacyPostcondition)(spec);
     const basePath = options.basePath ?? process.cwd();
     const specFile = options.specFile ?? "SKILL.md.spec.ts";
-    const profile = 
-    // Downstream of the SkillFrontmatterProfile alias (src/core/dialect.ts).
-    // eslint-disable-next-line local/no-harness-names -- goes away with that alias
-    options.dialect?.skillFrontmatter ?? "claude-code";
+    const frontmatterKeys = options.dialect?.skillFrontmatterKeys ?? dialect_js_1.RENDERABLE_SKILL_FRONTMATTER_KEYS;
     const errors = [];
     // Verify spec file naming
     if (!specFile.endsWith(".spec.ts")) {
@@ -971,7 +982,7 @@ function compileSkill(spec, options = {}) {
     // compilation (so adoption always compiles), just nudge toward file().
     const warnings = checkInlineCode(sections, spec.maxInlineCodeLines ?? DEFAULT_MAX_INLINE_CODE_LINES);
     const marker = purityMarker(spec.purity);
-    const content = renderSkillFrontmatter(spec, profile) +
+    const content = renderSkillFrontmatter(spec, frontmatterKeys) +
         // ONE newline, not two: `placeIntegrityHeader` puts the stamp AFTER the
         // frontmatter and supplies its own blank line on each side, so a second one
         // here becomes two blank lines in the artifact — which `prettier --check`

package/dist/core/compose.d.ts

@@ -59,9 +59,11 @@ export declare function detectSyncTools(root: string): DetectedSyncTool[];
 /**
  * Detect whether `CLAUDE.md` and `AGENTS.md` at `root` are ONE artifact, not two
  * — a symlink in either direction (`ln -s CLAUDE.md AGENTS.md`) or byte-identical
- * content (a sync tool keeping them in lockstep). Claude Code reads CLAUDE.md
- * only ([anthropics/claude-code#34235]); users bridge to the AGENTS.md tools this
- * way (see `research/sync-tool-compatibility.md` requirement 7). When mirrored,
+ * content (a sync tool keeping them in lockstep). The idiom predates Claude Code
+ * reading `AGENTS.md` natively ([anthropics/claude-code#34235], reversed in
+ * v2.1.277) and outlives it, because a repo with BOTH files loads only the
+ * `CLAUDE.md` — so the mirror is still how one text reaches both toolchains (see
+ * `research/sync-tool-compatibility.md` requirement 7). When mirrored,
  * vigiles must treat them as the same file — hash + `require-instructions-spec` run once on the
  * real one, and the mirror is never flagged as a second, spec-less instruction
  * file. Returns null when one is absent, or both exist but genuinely differ.

package/dist/core/compose.js

@@ -72,9 +72,11 @@ function targetName(target) {
 /**
  * Detect whether `CLAUDE.md` and `AGENTS.md` at `root` are ONE artifact, not two
  * — a symlink in either direction (`ln -s CLAUDE.md AGENTS.md`) or byte-identical
- * content (a sync tool keeping them in lockstep). Claude Code reads CLAUDE.md
- * only ([anthropics/claude-code#34235]); users bridge to the AGENTS.md tools this
- * way (see `research/sync-tool-compatibility.md` requirement 7). When mirrored,
+ * content (a sync tool keeping them in lockstep). The idiom predates Claude Code
+ * reading `AGENTS.md` natively ([anthropics/claude-code#34235], reversed in
+ * v2.1.277) and outlives it, because a repo with BOTH files loads only the
+ * `CLAUDE.md` — so the mirror is still how one text reaches both toolchains (see
+ * `research/sync-tool-compatibility.md` requirement 7). When mirrored,
  * vigiles must treat them as the same file — hash + `require-instructions-spec` run once on the
  * real one, and the mirror is never flagged as a second, spec-less instruction
  * file. Returns null when one is absent, or both exist but genuinely differ.

package/dist/core/config-schema.d.ts

@@ -196,8 +196,20 @@ export declare const REPLACED_KEYS: ReadonlyArray<{
     readonly was: string;
     readonly now: string;
 }>;
-/** The message a config written in the replaced shape gets. */
-export declare function replacedKeyMessage(present: ReadonlyArray<(typeof REPLACED_KEYS)[number]>): string;
+/**
+ * The message a config written in the replaced shape gets.
+ *
+ * `names` are the harnesses the user's OWN config named under the removed
+ * `harness` key, so the worked example below shows THEIR migration.
+ *
+ * 🔴 IT USED TO BE A FIXED EXAMPLE — `{ "harnesses": { "claude-code": …,
+ * "codex": {} } }`, two names typed into the core. Its own comment called that
+ * debt and predicted the failure: "with a third adapter this sample goes
+ * stale". Reading the names from the config being migrated is better than
+ * reading them from the registry would have been, and it is available here:
+ * it shows the reader their own keys instead of somebody else's.
+ */
+export declare function replacedKeyMessage(present: ReadonlyArray<(typeof REPLACED_KEYS)[number]>, names: readonly string[]): string;
 /**
  * Turn a Zod failure into the lines a human acts on — ONE per real problem.
  *

package/dist/core/config-schema.js

@@ -298,15 +298,28 @@ exports.REPLACED_KEYS = [
         now: '"roots" INSIDE the harness that reads them',
     },
 ];
-/** The message a config written in the replaced shape gets. */
-function replacedKeyMessage(present) {
+/**
+ * The message a config written in the replaced shape gets.
+ *
+ * `names` are the harnesses the user's OWN config named under the removed
+ * `harness` key, so the worked example below shows THEIR migration.
+ *
+ * 🔴 IT USED TO BE A FIXED EXAMPLE — `{ "harnesses": { "claude-code": …,
+ * "codex": {} } }`, two names typed into the core. Its own comment called that
+ * debt and predicted the failure: "with a third adapter this sample goes
+ * stale". Reading the names from the config being migrated is better than
+ * reading them from the registry would have been, and it is available here:
+ * it shows the reader their own keys instead of somebody else's.
+ */
+function replacedKeyMessage(present, names) {
+    // Empty when the config used only `surfaceRoots`, or named no harness — a
+    // placeholder the reader will obviously replace, never an invented name.
+    const example = (names.length > 0 ? names : ["<harness>"])
+        .map((n, i) => `"${n}": ${i === 0 ? '{ "roots": [".ai"] }' : "{}"}`)
+        .join(", ");
     return (`.vigilesrc.json: ${present.map((k) => `"${k.key}"`).join(" and ")} ` +
         `${present.length === 1 ? "was" : "were"} replaced by one nested key, "harnesses".\n` +
-        // A worked EXAMPLE config in a diagnostic, and real debt: with a third
-        // adapter this sample goes stale, so it wants rendering from the adapter
-        // registry rather than two names typed out here.
-        // eslint-disable-next-line local/no-harness-names -- example config text
-        `  Write:  { "harnesses": { "claude-code": { "roots": [".ai"] }, "codex": {} } }\n` +
+        `  Write:  { "harnesses": { ${example} } }\n` +
         present.map((k) => `  - ${k.was}  →  ${k.now}`).join("\n") +
         `\n  The old harness ARRAY's order silently decided what got read: one order graded the ` +
         `skills and read no instruction file, the other read the instruction file and found no ` +