vigiles 38.2.0 → 39.1.0

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

@@ -0,0 +1,69 @@
+/**
+ * The configs that USED TO WORK — keys and rules whose shape changed, and the
+ * sentence each one gets instead of the schema's "unknown key".
+ *
+ * Read BEFORE the schema (`./validate.ts` `loadConfig`): the reader of these
+ * messages is someone whose config was valid in an earlier release, so
+ * `.strict()`'s "Unrecognized key" would be true and useless — they need the
+ * new spelling. Kept apart from `./config-schema.ts`, which describes the
+ * config as it is today; this file describes how it got here.
+ */
+/**
+ * The two keys `harnesses` replaced, and the sentence each one gets (#240).
+ *
+ * They are listed here rather than left to `.strict()`'s "Unrecognized key"
+ * because the reader of that message is someone whose config USED to work: they
+ * need the new spelling, not the news that the old one is unknown. `.strict()`
+ * would tell them the truth in the least useful possible way.
+ */
+export declare const REPLACED_KEYS: ReadonlyArray<{
+    readonly key: string;
+    readonly was: string;
+    readonly now: 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;
+/**
+ * The per-rule `exclude` options that became `overrides`, and the rules an
+ * equivalent override turns off. `untested-*` shared ONE merged option set, so
+ * an `exclude` on any of them skipped those paths for all four.
+ */
+export declare const MOVED_TO_OVERRIDES: ReadonlyArray<{
+    /** Where the option sat: a rule name, or the `orphans` block. */
+    readonly owner: string;
+    /** The rules the equivalent override turns off. */
+    readonly rules: readonly string[];
+}>;
+/**
+ * The message an old config with a per-rule `exclude` gets — the user's OWN
+ * globs, written as the `overrides` entry that does what the option did.
+ *
+ * Read BEFORE the schema, like {@link REPLACED_KEYS}: the reader's config used
+ * to work, so "unknown key exclude" would be true and useless.
+ */
+export declare function movedToOverridesMessages(raw: unknown): readonly string[];
+/** Rules whose findings another rule now reports, and what changed. */
+export declare const FOLDED_RULES: ReadonlyArray<{
+    readonly rule: string;
+    readonly into: string;
+    readonly what: string;
+}>;
+/**
+ * The message a config naming a folded rule gets — in `rules` or in an
+ * `overrides` entry. Read BEFORE the schema, like {@link REPLACED_KEYS}: the
+ * reader's config used to work, so "unknown key" would be true and useless.
+ */
+export declare function foldedRuleMessages(raw: unknown): readonly string[];
+//# sourceMappingURL=config-migrations.d.ts.map

package/dist/core/config-migrations.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * The configs that USED TO WORK — keys and rules whose shape changed, and the
+ * sentence each one gets instead of the schema's "unknown key".
+ *
+ * Read BEFORE the schema (`./validate.ts` `loadConfig`): the reader of these
+ * messages is someone whose config was valid in an earlier release, so
+ * `.strict()`'s "Unrecognized key" would be true and useless — they need the
+ * new spelling. Kept apart from `./config-schema.ts`, which describes the
+ * config as it is today; this file describes how it got here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOLDED_RULES = exports.MOVED_TO_OVERRIDES = exports.REPLACED_KEYS = void 0;
+exports.replacedKeyMessage = replacedKeyMessage;
+exports.movedToOverridesMessages = movedToOverridesMessages;
+exports.foldedRuleMessages = foldedRuleMessages;
+/**
+ * The two keys `harnesses` replaced, and the sentence each one gets (#240).
+ *
+ * They are listed here rather than left to `.strict()`'s "Unrecognized key"
+ * because the reader of that message is someone whose config USED to work: they
+ * need the new spelling, not the news that the old one is unknown. `.strict()`
+ * would tell them the truth in the least useful possible way.
+ */
+exports.REPLACED_KEYS = [
+    {
+        key: "harness",
+        // The literal OLD config text this migration notice quotes back at the user:
+        // a historical artefact, not a fact about a harness, so there is no port to
+        // read it off. This is the one exemption here that is not debt.
+        // eslint-disable-next-line local/no-harness-names -- quoted legacy config
+        was: '"harness": ["claude-code", "codex"]',
+        now: "a KEY per harness",
+    },
+    {
+        key: "surfaceRoots",
+        was: '"surfaceRoots": [".ai"]',
+        now: '"roots" INSIDE the harness that reads them',
+    },
+];
+/**
+ * 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` +
+        `  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 ` +
+        `skills. Scoping each root under the harness that reads it removes the order.`);
+}
+/**
+ * The per-rule `exclude` options that became `overrides`, and the rules an
+ * equivalent override turns off. `untested-*` shared ONE merged option set, so
+ * an `exclude` on any of them skipped those paths for all four.
+ */
+exports.MOVED_TO_OVERRIDES = [
+    ...[
+        "untested-skill",
+        "untested-subagent",
+        "untested-hook",
+        "untested-output-style",
+    ].map((owner, _i, all) => ({ owner, rules: all })),
+    { owner: "orphans", rules: ["orphan-docs"] },
+];
+/** A plain JSON object, narrowed without a cast. */
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** The `exclude` an old config wrote under `owner`, as a glob list, if any. */
+function movedExclude(raw, owner) {
+    if (!isRecord(raw))
+        return null;
+    const value = isRecord(raw.rules) ? raw.rules[owner] : undefined;
+    const tuple = Array.isArray(value) ? value : [];
+    const holder = owner === "orphans" ? raw.orphans : tuple[1];
+    if (!isRecord(holder) || holder.exclude === undefined)
+        return null;
+    const globs = [holder.exclude].flat();
+    return globs.filter((g) => typeof g === "string");
+}
+/**
+ * The message an old config with a per-rule `exclude` gets — the user's OWN
+ * globs, written as the `overrides` entry that does what the option did.
+ *
+ * Read BEFORE the schema, like {@link REPLACED_KEYS}: the reader's config used
+ * to work, so "unknown key exclude" would be true and useless.
+ */
+function movedToOverridesMessages(raw) {
+    return exports.MOVED_TO_OVERRIDES.flatMap(({ owner, rules }) => {
+        const globs = movedExclude(raw, owner);
+        if (globs === null)
+            return [];
+        const files = globs.map((g) => JSON.stringify(g)).join(", ");
+        const off = rules.map((r) => `"${r}": "off"`).join(", ");
+        return [
+            `.vigilesrc.json: "exclude" inside "${owner}" moved to "overrides" — skipping paths is not a rule option any more; an override turns the rule off for them.\n` +
+                `  Write:  "overrides": [{ "files": [${files}], "rules": { ${off} } }]\n` +
+                `  and remove "exclude" from "${owner}". Paths top-level "exclude" removes are not read at all; an override only changes what a rule reports.`,
+        ];
+    });
+}
+/** Rules whose findings another rule now reports, and what changed. */
+exports.FOLDED_RULES = [
+    {
+        rule: "prefer-compiled-hooks",
+        into: "hand-written-hook",
+        what: "every hook line vigiles did not write is now one hand-written-hook finding that names it",
+    },
+];
+/**
+ * The message a config naming a folded rule gets — in `rules` or in an
+ * `overrides` entry. Read BEFORE the schema, like {@link REPLACED_KEYS}: the
+ * reader's config used to work, so "unknown key" would be true and useless.
+ */
+function foldedRuleMessages(raw) {
+    if (!isRecord(raw))
+        return [];
+    const overrides = Array.isArray(raw.overrides)
+        ? raw.overrides
+        : [];
+    const ruleBlocks = [
+        raw.rules,
+        ...overrides.map((o) => (isRecord(o) ? o.rules : undefined)),
+    ];
+    return exports.FOLDED_RULES.filter(({ rule }) => ruleBlocks.some((b) => isRecord(b) && rule in b)).map(({ rule, into, what }) => `.vigilesrc.json: rule "${rule}" was folded into "${into}": ${what}.\n` +
+        `  Remove "${rule}"; set "${into}" to change how those findings report.`);
+}
+//# sourceMappingURL=config-migrations.js.map

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

@@ -17,17 +17,19 @@
  * happening inside the tool, so the shape is now DECLARED and anything outside
  * it is named out loud.
  *
- * THE TYPE IS DERIVED FROM THIS, not written beside it: `VigilesConfig` is
- * `z.infer<typeof vigilesConfigSchema>` (see `./types.ts`), so a field cannot
- * exist in the type and not in the validator, which is how `surfaceRoots` ended
- * up documented in `docs/cli.md` for a week after it stopped being read.
+ * THE TYPE IS DERIVED FROM THIS, not written beside it: `VigilesConfigOf` is
+ * the static keys' `z.output` plus the rule set's own entries (see `./types.ts`),
+ * so a field cannot exist in the type and not in the validator, which is how
+ * `surfaceRoots` ended up documented in `docs/cli.md` for a week after it
+ * stopped being read.
  *
- * DEFAULTS LIVE HERE TOO, and that is what makes the derivation exact. Every key
+ * THE RULES ARE A PARAMETER. The `rules` object, its defaults and the presets
+ * `extends` accepts are BUILT from the rule set a composition root hands to
+ * {@link configFor} — each rule declares its id, default and options schema in
+ * its own module (`src/rules/`), and this file names none of them. Every key
  * the loaded config is guaranteed to carry (`rules`, `files`, `ruleMarkers`)
- * carries a Zod `.default(...)`, and Zod's inferred OUTPUT type for a defaulted
- * field is non-optional — so `z.infer` reproduces the old
- * `rules: Required<RulesConfig>` exactly, rather than approximating it. Parsing
- * `{}` yields byte-for-byte the old `DEFAULT_CONFIG`.
+ * carries a Zod `.default(...)`, so parsing `{}` yields every rule at its
+ * shipped default (`src/rules/index.test.ts` pins that snapshot).
  *
  * ⚠️ ZOD COSTS ~45 ms TO IMPORT (measured, Zod 4.6.5), AND IT IS IMPORTED
  * NORMALLY — `src/core/validate.ts` has a top-level `import`, not a deferred
@@ -42,10 +44,23 @@
  * requires, against which 45 ms is ~13%.
  */
 import { z } from "zod";
-/** The rule names, for the "did you mean" on an unknown one. */
-export declare const RULE_NAMES: readonly string[];
+import { type RuleGroups, type RuleSpec } from "./rule.js";
+import type { RuleSeverity, RuleWithOptions } from "./types.js";
+/** The config file; the directory holding it is a project root. */
+export declare const PROJECT_CONFIG_FILE = ".vigilesrc.json";
 /**
- * ONE harness's entry in {@link vigilesConfigSchema}'s `harnesses`.
+ * A string, or a string ARRAY — coerced to an array.
+ *
+ * The bare-string case is the natural first-value mistake and it used to spread
+ * a string's CHARACTERS as globs: `"exclude": "bench"` became
+ * `["b","e","n","c","h"]`, which is a no-op at best and garbage `orphan` matches
+ * (`.`, `/`, `README.md`) at worst. Accepting it as a one-element array is what
+ * `asStringArray` did; the difference is that anything that is neither is now a
+ * schema error instead of a `console.warn` nobody reads.
+ */
+export declare const stringList: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>;
+/**
+ * ONE harness's entry in the config's `harnesses`.
  *
  * `.strict()` is load-bearing here specifically: the whole reason this key
  * exists is that a declaration which reaches nothing used to be silent, and
@@ -56,106 +71,21 @@ declare const harnessDeclarationSchema: z.ZodObject<{
 }, z.core.$strict>;
 /** The harness keys' value shape, exported so `types.ts` can derive the type. */
 export type HarnessDeclarationShape = z.infer<typeof harnessDeclarationSchema>;
+/** What counts as a rule in markdown, by default: both constructs. */
+export declare const DEFAULT_RULE_MARKERS: readonly ["headings", "checkboxes"];
 /**
- * The whole of `.vigilesrc.json`.
- *
- * `.strict()` at the top level is the check that did not exist: an unrecognized
- * key is now a named error with a suggestion, where it used to be spread into
- * the config object and never read.
+ * The keys of `.vigilesrc.json` that do not depend on the rule set, in the
+ * order the "Known: …" list prints them (it is capped, so the keys people
+ * misspell most come first). `rules`, `overrides` and `extends` are built from
+ * the rule set by {@link configFor} and slotted in around these.
  */
-export declare const vigilesConfigSchema: z.ZodObject<{
+declare const configKeys: {
+    /** Which markdown constructs count as a rule — headings, checkboxes, or both. */
     ruleMarkers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         headings: "headings";
         checkboxes: "checkboxes";
     }>>>;
-    rules: z.ZodPrefault<z.ZodObject<{
-        "spec-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "orphan-docs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "duplicate-rules": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "require-instructions-spec": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "require-skill-spec": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        integrity: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        coverage: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
-            linterRules: z.ZodOptional<z.ZodNumber>;
-            scripts: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
-            linterRules: z.ZodOptional<z.ZodNumber>;
-            scripts: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>], null>]>>;
-        "untested-skill": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>]>>;
-        "untested-subagent": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>]>>;
-        "untested-hook": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>]>>;
-        "untested-output-style": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
-            include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-            testExtension: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], null>]>>;
-        "unmarked-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "subagent-tool-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "hook-events": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "subagent-frontmatter": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "mcp-config": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "skill-frontmatter": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "mcp-tool-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "hook-script-exists": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "prefer-compiled-hooks": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "disallowed-tools-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "description-overlap": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "skill-description-budget": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "compile-budget": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
-            maxEntryChars: z.ZodOptional<z.ZodNumber>;
-            maxSectionChars: z.ZodOptional<z.ZodNumber>;
-            maxRulesChars: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
-            maxEntryChars: z.ZodOptional<z.ZodNumber>;
-            maxSectionChars: z.ZodOptional<z.ZodNumber>;
-            maxRulesChars: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>], null>]>>;
-        "frontmatter-valid": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "mcp-hook-target-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "lethal-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "skill-resource-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "skill-missing-fence": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "plugin-dir-layout": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "delegation-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "hook-block-ineffective": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "hook-matcher": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "doc-refs": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-        "instruction-weight": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
-            max: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
-            max: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>], null>]>>;
-        "deprecated-key-files": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
-    }, z.core.$strict>>;
+    /** The instruction files to validate. */
     files: z.ZodDefault<z.ZodArray<z.ZodString>>;
     maxRules: z.ZodOptional<z.ZodNumber>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -170,9 +100,11 @@ export declare const vigilesConfigSchema: z.ZodObject<{
     }>>;
     orphans: z.ZodOptional<z.ZodObject<{
         include: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
-        exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
     }, z.core.$strict>>;
     exclude: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
+};
+/** The keys after `overrides`; `extends` and `$schema` close the shape. */
+declare const configTailKeys: {
     sharedDirs: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
     harnesses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         roots: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>>;
@@ -184,27 +116,136 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         apiVersion: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     nudge: z.ZodOptional<z.ZodLiteral<"dismissed">>;
-    extends: z.ZodOptional<z.ZodEnum<{
-        "vigiles:recommended": "vigiles:recommended";
-    }>>;
-    $schema: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
+};
 /**
- * Parse a raw `.vigilesrc.json` value — THE one entry point every reader uses.
+ * The editor's pointer at the published JSON Schema. Accepted, never read.
+ *
+ * 🔴 IT IS DECLARED HERE RATHER THAN EXCUSED IN THE UNKNOWN-KEY WALKER, and
+ * the reason is that the walker is only half the surface. `dist/vigilesrc.
+ * schema.json` is generated FROM this schema by
+ * `scripts/build-config-schema.mjs`, with `additionalProperties: false`, so
+ * a key missing here is refused TWICE: once by the CLI, and once by the
+ * editor being pointed at the schema. Measured before this key existed, on
+ * `{"$schema": <the schema's own $id>, "harnesses": {"claude-code": {}}}`:
  *
- * 🔴 THE PRESET IS MERGED INTO THE RAW INPUT, BEFORE THE SCHEMA, for one reason:
- * after parsing, every rule carries a value (the schema fills each default), so
- * "the user wrote `hook-events: warn`" and "nobody wrote it" are the same
- * output, and an explicit downgrade could not win over the preset. Before
- * parsing, the user's own `rules` keys are exactly what they wrote. So the
- * preset's severities go UNDER them, and the schema then normalizes and
- * validates the result as if the user had typed both.
+ * ```
+ * $ vigiles audit . --no-interactive
+ * ✗ .vigilesrc.json: unknown key "$schema" in (top level). Known: …
+ * (exit 2)
+ * $ # and the same document against dist/vigilesrc.schema.json:
+ * additionalProperties: should NOT have additional properties ($schema)
+ * ```
+ *
+ * It is LAST in the shape on purpose: `knownKeysAt` reads the schema to build
+ * the "Known: …" candidate list, which is capped, so a key nobody misspells
+ * belongs past the cap rather than at the head of the suggestion.
+ */
+declare const schemaPointer: z.ZodOptional<z.ZodString>;
+/** The keys that do not depend on the rule set, as one object type. */
+type StaticConfig = z.output<z.ZodObject<typeof configKeys & typeof configTailKeys & {
+    readonly $schema: typeof schemaPointer;
+}>>;
+/** One rule's entry in `rules`: a severity, or `[severity, options]`. */
+export type RuleEntry = RuleWithOptions<unknown>;
+/** The `rules` of a config, keyed by rule id. */
+export type RulesConfig<Id extends string = string> = {
+    readonly [K in Id]: RuleEntry;
+};
+/** The config entry a rule takes: with its options' type when it has options. */
+type EntryOf<S> = S extends {
+    readonly options: infer O extends z.ZodType;
+} ? RuleWithOptions<z.output<O>> : RuleSeverity;
+/**
+ * The PRECISE `rules` of a rule set — each id with its own options type. The
+ * composition root instantiates it over `RULES`; generic code takes
+ * {@link RulesConfig} and never names an id (the `local/no-rule-ids` fence).
+ */
+export type RulesConfigOf<R extends readonly RuleSpec[]> = {
+    readonly [S in R[number] as S["id"]]: EntryOf<S>;
+};
+/**
+ * The whole parsed config: the static keys as the schema defines them, plus
+ * the rule set's `rules` and `overrides`. Exported from here and re-exported
+ * (type-only) by `./types.ts`; a key cannot be in the type and absent from the
+ * validator.
+ */
+export type VigilesConfigOf<Rules> = StaticConfig & {
+    rules: Rules;
+    overrides?: readonly {
+        readonly files: readonly string[];
+        readonly rules: {
+            readonly [K in keyof Rules]?: RuleSeverity;
+        };
+    }[];
+    extends?: string | readonly string[];
+};
+/** A parse of a raw config: the config, or the issues that refused it. */
+export type ConfigParse<C> = {
+    readonly success: true;
+    readonly data: C;
+} | {
+    readonly success: false;
+    readonly error: {
+        readonly issues: readonly ConfigIssue[];
+    };
+};
+/**
+ * `.vigilesrc.json` for one rule set — the schema, its presets and its
+ * defaults, BUILT from the rules a composition root hands in. `C` is the parsed
+ * config's type: precise (`VigilesConfigOf<RulesConfigOf<typeof RULES>>`) at
+ * the root, string-keyed in generic code.
+ */
+export interface ConfigSet<C> {
+    /** The whole schema — for the JSON Schema build and the error messages. */
+    readonly schema: z.ZodType;
+    /** Every rule id the schema accepts, in the set's order. */
+    readonly ruleNames: readonly string[];
+    /** The preset names `extends` and `--preset=` accept, from the groups. */
+    readonly presetNames: readonly string[];
+    /**
+     * Parse a raw `.vigilesrc.json` value — THE one entry point every reader uses.
+     *
+     * 🔴 THE PRESET IS MERGED INTO THE RAW INPUT, BEFORE THE SCHEMA: after
+     * parsing, every rule carries a value (the schema fills each default), so
+     * "the user wrote `hook-events: warn`" and "nobody wrote it" are the same
+     * output, and an explicit downgrade could not win over the preset. Before
+     * parsing, the user's own `rules` keys are exactly what they wrote, so the
+     * preset's severities go UNDER them. Only a recognized preset with an object
+     * (or absent) `rules` is expanded; anything else is passed through for the
+     * schema to refuse with its own message.
+     *
+     * `extraPresets` — `audit`/`lint --preset=<name>` for one run — go after the
+     * file's own presets (so they win over them) and never over its explicit
+     * `rules`. They are not written into the parsed `extends`: that key stays
+     * what the FILE says.
+     */
+    parse(raw: unknown, extraPresets?: readonly string[]): ConfigParse<C>;
+}
+/**
+ * Build `.vigilesrc.json` for a rule set: each rule's key with its default and,
+ * for a rule with `options`, the `[severity, options]` form; `overrides` over
+ * the same ids; `extends` over the groups' preset names.
  *
- * Only a recognized preset with an object (or absent) `rules` is expanded;
- * anything else is passed through untouched for the schema to refuse with its
- * own message, so a typo in `extends` is reported, never silently ignored.
+ * The one place Zod cannot carry the type: an object built from
+ * `Object.fromEntries` has string keys, so the parse result is narrowed to the
+ * set's precise type by `complete`, which checks at run time that every id is
+ * present — never by an assertion.
  */
-export declare function parseVigilesConfig(raw: unknown): Readonly<ReturnType<typeof vigilesConfigSchema.safeParse>>;
+export declare function configFor<const R extends readonly RuleSpec[]>(rules: R, groups: RuleGroups): ConfigSet<VigilesConfigOf<RulesConfigOf<R>>>;
+/**
+ * Parse the values of `--preset=` (each may be a comma list) into preset
+ * names, through the SAME enum `extends` validates with, so the config file
+ * and the command line refuse an unknown name with the same message. The
+ * `vigiles:` prefix is optional on the command line: `--preset=experimental`
+ * and `--preset=vigiles:experimental` are the same preset.
+ */
+export declare function parsePresetFlags(known: readonly string[], values: readonly string[]): {
+    readonly ok: true;
+    readonly presets: readonly string[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
 /**
  * A `.vigilesrc.json` that cannot be honoured as written.
  *
@@ -218,41 +259,6 @@ export declare function parseVigilesConfig(raw: unknown): Readonly<ReturnType<ty
 export declare class VigilesConfigError extends Error {
     readonly name = "VigilesConfigError";
 }
-/**
- * The whole config, AS THE SCHEMA DEFINES IT — `VigilesConfig` is this.
- *
- * Exported from here and re-exported (type-only, so no runtime cycle) by
- * `./types.ts`, which every consumer already imports. The derivation is the
- * point: a key cannot be in the type and absent from the validator.
- */
-export type VigilesConfigShape = z.infer<typeof vigilesConfigSchema>;
-/**
- * The two keys `harnesses` replaced, and the sentence each one gets (#240).
- *
- * They are listed here rather than left to `.strict()`'s "Unrecognized key"
- * because the reader of that message is someone whose config USED to work: they
- * need the new spelling, not the news that the old one is unknown. `.strict()`
- * would tell them the truth in the least useful possible way.
- */
-export declare const REPLACED_KEYS: ReadonlyArray<{
-    readonly key: string;
-    readonly was: string;
-    readonly now: 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.
  *
@@ -277,7 +283,7 @@ export declare function replacedKeyMessage(present: ReadonlyArray<(typeof REPLAC
  * the key accepts, and an unknown key carries the candidate list plus a
  * distance-bounded "did you mean".
  */
-export declare function formatConfigIssues(issues: readonly ConfigIssue[]): string[];
+export declare function formatConfigIssues(schema: Readonly<z.ZodType>, issues: readonly ConfigIssue[]): string[];
 /**
  * The shape of a Zod issue this formatter reads — structural, not imported.
  *