vigiles 38.2.0 → 39.0.0

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

@@ -42,6 +42,8 @@
  * requires, against which 45 ms is ~13%.
  */
 import { z } from "zod";
+/** The config file; the directory holding it is a project root. */
+export declare const PROJECT_CONFIG_FILE = ".vigilesrc.json";
 /** The rule names, for the "did you mean" on an unknown one. */
 export declare const RULE_NAMES: readonly string[];
 /**
@@ -84,38 +86,30 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         }, 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">>>;
@@ -126,7 +120,7 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         "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">>>;
+        "hand-written-hook": 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">>>;
@@ -170,9 +164,14 @@ 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[]>>>;
+    overrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        files: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<readonly string[], string | string[]>>;
+        rules: z.ZodObject<{
+            [x: string]: z.ZodOptional<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>;
+    }, z.core.$strict>>>;
     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[]>>>;
@@ -253,6 +252,37 @@ export declare const REPLACED_KEYS: ReadonlyArray<{
  * 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[];
 /**
  * Turn a Zod failure into the lines a human acts on — ONE per real problem.
  *

package/dist/core/config-schema.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REPLACED_KEYS = exports.VigilesConfigError = exports.vigilesConfigSchema = exports.RULE_NAMES = void 0;
+exports.FOLDED_RULES = exports.MOVED_TO_OVERRIDES = exports.REPLACED_KEYS = exports.VigilesConfigError = exports.vigilesConfigSchema = exports.RULE_NAMES = exports.PROJECT_CONFIG_FILE = void 0;
 exports.parseVigilesConfig = parseVigilesConfig;
 exports.replacedKeyMessage = replacedKeyMessage;
+exports.movedToOverridesMessages = movedToOverridesMessages;
+exports.foldedRuleMessages = foldedRuleMessages;
 exports.formatConfigIssues = formatConfigIssues;
 /**
  * `.vigilesrc.json`, AS A SCHEMA — the one place the config's shape, its
@@ -50,6 +52,8 @@ exports.formatConfigIssues = formatConfigIssues;
 const zod_1 = require("zod");
 const edit_distance_js_1 = require("./edit-distance.js");
 const presets_js_1 = require("./presets.js");
+/** The config file; the directory holding it is a project root. */
+exports.PROJECT_CONFIG_FILE = ".vigilesrc.json";
 // ---------------------------------------------------------------------------
 // Primitives
 // ---------------------------------------------------------------------------
@@ -114,11 +118,14 @@ const coverageThresholds = zod_1.z
     scripts: zod_1.z.number().optional(),
 })
     .strict();
-/** Discovery options shared by the three `untested-*` rules. */
+/**
+ * Discovery options shared by the `untested-*` rules. `include` is where tests
+ * live — a real option of the rule. Skipping paths is not: that is `overrides`
+ * with the rule off (see {@link MOVED_TO_OVERRIDES}).
+ */
 const testCoverageConfig = zod_1.z
     .object({
     include: stringList.optional(),
-    exclude: stringList.optional(),
     testExtension: zod_1.z.string().optional(),
 })
     .strict();
@@ -177,7 +184,8 @@ const rulesSchema = zod_1.z
     "skill-frontmatter": severitySchema.default("warn"),
     "mcp-tool-resolves": severitySchema.default("warn"),
     "hook-script-exists": severitySchema.default("warn"),
-    "prefer-compiled-hooks": severitySchema.default(false),
+    // OFF: its only cure is a compiled hook, an experimental API (docs/experimental.md).
+    "hand-written-hook": severitySchema.default(false),
     "disallowed-tools-contract": severitySchema.default("warn"),
     "description-overlap": severitySchema.default("warn"),
     "skill-description-budget": severitySchema.default("warn"),
@@ -199,6 +207,35 @@ const rulesSchema = zod_1.z
 /** The rule names, for the "did you mean" on an unknown one. */
 exports.RULE_NAMES = Object.keys(rulesSchema.shape);
 // ---------------------------------------------------------------------------
+// Overrides — per-path severities (`./overrides.ts`)
+// ---------------------------------------------------------------------------
+/**
+ * The rule set as an override may spell it: every rule, a SEVERITY only, no
+ * default. Options stay in `rules` — one place — so `["error", { … }]` here is
+ * refused rather than accepted and never read. Derived from `rulesSchema`'s
+ * keys, so a rule added there is overridable with no second list, and an
+ * unknown name gets the same "did you mean" as in `rules`.
+ */
+const overrideRulesSchema = zod_1.z
+    .object(Object.fromEntries(Object.keys(rulesSchema.shape).map((name) => [
+    name,
+    severitySchema.optional(),
+])))
+    .strict();
+/**
+ * One `overrides` entry. `files` are root-relative globs with top-level
+ * `exclude`'s semantics; an entry with none would apply nowhere, so it is
+ * refused rather than kept as a line that does nothing.
+ */
+const overrideSchema = zod_1.z
+    .object({
+    files: stringList.refine((globs) => globs.length > 0, {
+        message: "needs at least one glob",
+    }),
+    rules: overrideRulesSchema,
+})
+    .strict();
+// ---------------------------------------------------------------------------
 // Harnesses (#240)
 // ---------------------------------------------------------------------------
 /**
@@ -251,11 +288,16 @@ exports.vigilesConfigSchema = zod_1.z
     orphans: zod_1.z
         .object({
         include: stringList.optional(),
-        exclude: stringList.optional(),
     })
         .strict()
         .optional(),
     exclude: stringList.optional(),
+    /**
+     * Per-path rule severities, ESLint's `{ files, rules }` list: a later entry
+     * wins over an earlier one, any entry over `rules`, `rules` over `extends`.
+     * Resolved by `ruleResolver` (`./overrides.ts`).
+     */
+    overrides: zod_1.z.array(overrideSchema).optional(),
     sharedDirs: stringList.optional(),
     harnesses: zod_1.z.record(zod_1.z.string(), harnessDeclarationSchema).optional(),
     audit: zod_1.z.object({ measure: zod_1.z.boolean().optional() }).strict().optional(),
@@ -396,6 +438,83 @@ function replacedKeyMessage(present, names) {
         `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.`);
+}
 // ---------------------------------------------------------------------------
 // Messages — the half a schema library does NOT give you
 // ---------------------------------------------------------------------------
@@ -412,17 +531,7 @@ function replacedKeyMessage(present, names) {
 function knownKeysAt(path) {
     let node = exports.vigilesConfigSchema;
     for (const seg of path) {
-        const def = node._zod
-            ?.def;
-        if (def?.type === "object") {
-            node = def.shape?.[String(seg)];
-        }
-        else if (def?.type === "record") {
-            node = def.valueType;
-        }
-        else {
-            return [];
-        }
+        node = childAt(node, seg);
         if (node === undefined)
             return [];
         node = unwrap(node);
@@ -432,6 +541,20 @@ function knownKeysAt(path) {
         ? Object.keys(def.shape)
         : [];
 }
+/**
+ * One step down a schema node: an object's field `seg`, an array's element, a
+ * record's value. `undefined` where the node has no child to step into.
+ */
+function childAt(node, seg) {
+    const def = node._zod?.def;
+    if (def?.type === "object")
+        return def.shape?.[String(seg)];
+    if (def?.type === "array")
+        return def.element;
+    if (def?.type === "record")
+        return def.valueType;
+    return undefined;
+}
 /** Peel `.optional()` / `.default()` / `.prefault()` wrappers off a schema node. */
 function unwrap(node) {
     let cur = node;

package/dist/core/coverage.d.ts

@@ -54,4 +54,20 @@ export declare function checkCoverage(basePath: string, thresholds: CoverageThre
  * Format coverage report as human-readable text.
  */
 export declare function formatCoverageReport(report: CoverageReport): string;
+/**
+ * What `vigiles lint` says under the linter-rule coverage line when some enabled
+ * rules are undocumented. Empty when nothing is.
+ *
+ * 🔴 IT MUST NOT TELL ANYONE TO WRITE MORE INTO THE INSTRUCTION FILE. This used
+ * to read "Consider adding enforce() rules for frequently-triggered undocumented
+ * rules", which turns a coverage percentage into a to-do list for CLAUDE.md —
+ * the one file whose every line is loaded into every request and every subagent.
+ * An enabled linter rule is already enforced: the agent meets it as a failing
+ * lint with the rule's own message. Documentation only earns its place where the
+ * WHY is not in that message, and then it belongs where it is read on demand.
+ */
+export declare function undocumentedRulesAdvice(totals: Readonly<{
+    enabled: number;
+    documented: number;
+}>): readonly string[];
 //# sourceMappingURL=coverage.d.ts.map

package/dist/core/coverage.js

@@ -16,6 +16,7 @@ exports.computeScriptCoverage = computeScriptCoverage;
 exports.computeLinterRuleCoverage = computeLinterRuleCoverage;
 exports.checkCoverage = checkCoverage;
 exports.formatCoverageReport = formatCoverageReport;
+exports.undocumentedRulesAdvice = undocumentedRulesAdvice;
 const node_fs_1 = require("node:fs");
 const integrity_js_1 = require("./integrity.js");
 const node_path_1 = require("node:path");
@@ -183,4 +184,25 @@ function formatCoverageReport(report) {
     }
     return lines.join("\n");
 }
+/**
+ * What `vigiles lint` says under the linter-rule coverage line when some enabled
+ * rules are undocumented. Empty when nothing is.
+ *
+ * 🔴 IT MUST NOT TELL ANYONE TO WRITE MORE INTO THE INSTRUCTION FILE. This used
+ * to read "Consider adding enforce() rules for frequently-triggered undocumented
+ * rules", which turns a coverage percentage into a to-do list for CLAUDE.md —
+ * the one file whose every line is loaded into every request and every subagent.
+ * An enabled linter rule is already enforced: the agent meets it as a failing
+ * lint with the rule's own message. Documentation only earns its place where the
+ * WHY is not in that message, and then it belongs where it is read on demand.
+ */
+function undocumentedRulesAdvice(totals) {
+    if (totals.documented >= totals.enabled)
+        return [];
+    return [
+        "Undocumented is not unenforced: the linter already enforces these rules, and the agent meets each one as a lint failure.",
+        "Every line added to CLAUDE.md is loaded into every request, so do not document a rule just to raise this number.",
+        "Where the WHY is not obvious from the rule's own message, put it in docs/ (linked, read on demand) or declare the rule with enforce() in the spec, which also verifies it stays enabled.",
+    ];
+}
 //# sourceMappingURL=coverage.js.map

package/dist/core/doc-refs.d.ts

@@ -40,7 +40,8 @@ export interface DocRefReport {
     readonly placeholders: number;
 }
 export interface FindDocRefsOptions {
-    readonly basePath?: string;
+    /** The repo root. Required: no cwd fallback. */
+    readonly basePath: string;
     /** The repo exclude (`ExcludeSet.globIgnore`), or patterns relative to `basePath`. */
     readonly ignore?: GlobIgnore;
 }
@@ -55,7 +56,7 @@ interface ExtractResult {
  * spec.ts. Honors `<!-- vigiles:ignore-file -->` (skip the whole file)
  * and `<!-- vigiles:ignore -->` (skip the next code block).
  */
-export declare function findDocRefs(options?: FindDocRefsOptions): DocRefReport;
+export declare function findDocRefs(options: FindDocRefsOptions): DocRefReport;
 /** Format a DocRefReport as human-readable text. */
 export declare function formatDocRefReport(report: DocRefReport, 
 /**

package/dist/core/doc-refs.js

@@ -238,8 +238,8 @@ function validateRefs(refs, basePath) {
  * spec.ts. Honors `<!-- vigiles:ignore-file -->` (skip the whole file)
  * and `<!-- vigiles:ignore -->` (skip the next code block).
  */
-function findDocRefs(options = {}) {
-    const basePath = options.basePath ?? process.cwd();
+function findDocRefs(options) {
+    const basePath = options.basePath;
     const ignore = (0, glob_ignore_js_1.withIgnored)(DEFAULT_IGNORE, options.ignore);
     const files = (0, glob_1.globSync)("**/*.md", { cwd: basePath, ignore });
     const allRefs = [];

package/dist/core/enforce-marker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two ways a compiled instruction file can state an `enforce()` reference,
+ * spelled in ONE place so the renderer and every reader agree (#351).
+ *
+ * "**Enforced by:**" is the product's promise that a machine holds the rule, so
+ * `compile` writes it only for a reference it VERIFIED: the rule exists in the
+ * linter's catalog and the project's config switches it on. Anything less — the
+ * check was turned off (`verify: false`, `verifyLinters: false`, a per-linter
+ * `false`, catalog-only), the config does not set the rule, or the config could
+ * not be read — renders as "**Claimed (unverified):**". A reader of the compiled
+ * file can then tell the two apart without the compile log.
+ *
+ * Zero imports: `validate.ts`, `rule-routing.ts` and the CLI read these markers
+ * too, and some of them are browser-safe.
+ */
+/** A reference `compile` verified: exists, and the project's config runs it. */
+export declare const ENFORCED_MARKER = "**Enforced by:**";
+/** A reference `compile` did not or could not verify. */
+export declare const CLAIMED_MARKER = "**Claimed (unverified):**";
+/**
+ * Either marker followed by its backticked reference, anywhere in a line.
+ * Group 1 is the marker's label (`Enforced by` / `Claimed (unverified)`),
+ * group 2 the reference.
+ */
+export declare const RULE_MARKER_SOURCE: string;
+/** Is the label captured by {@link RULE_MARKER_SOURCE} the verified one? */
+export declare function isVerifiedLabel(label: string): boolean;
+//# sourceMappingURL=enforce-marker.d.ts.map

package/dist/core/enforce-marker.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * The two ways a compiled instruction file can state an `enforce()` reference,
+ * spelled in ONE place so the renderer and every reader agree (#351).
+ *
+ * "**Enforced by:**" is the product's promise that a machine holds the rule, so
+ * `compile` writes it only for a reference it VERIFIED: the rule exists in the
+ * linter's catalog and the project's config switches it on. Anything less — the
+ * check was turned off (`verify: false`, `verifyLinters: false`, a per-linter
+ * `false`, catalog-only), the config does not set the rule, or the config could
+ * not be read — renders as "**Claimed (unverified):**". A reader of the compiled
+ * file can then tell the two apart without the compile log.
+ *
+ * Zero imports: `validate.ts`, `rule-routing.ts` and the CLI read these markers
+ * too, and some of them are browser-safe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULE_MARKER_SOURCE = exports.CLAIMED_MARKER = exports.ENFORCED_MARKER = void 0;
+exports.isVerifiedLabel = isVerifiedLabel;
+/** A reference `compile` verified: exists, and the project's config runs it. */
+exports.ENFORCED_MARKER = "**Enforced by:**";
+/** A reference `compile` did not or could not verify. */
+exports.CLAIMED_MARKER = "**Claimed (unverified):**";
+/**
+ * Either marker followed by its backticked reference, anywhere in a line.
+ * Group 1 is the marker's label (`Enforced by` / `Claimed (unverified)`),
+ * group 2 the reference.
+ */
+exports.RULE_MARKER_SOURCE = /\*\*(Enforced by|Claimed \(unverified\)):\*\*\s*`([^`]+)`/.source;
+/** Is the label captured by {@link RULE_MARKER_SOURCE} the verified one? */
+function isVerifiedLabel(label) {
+    return label === "Enforced by";
+}
+//# sourceMappingURL=enforce-marker.js.map

package/dist/core/eslint-inventory.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The ONE answer to "which ESLint rules exist in this repo, which are enabled
+ * where, and did the config load" — read from ESLint itself.
+ *
+ * Three callers used to ask ESLint three different ways, and each saw a
+ * different repo: `generate types` probed one representative path per
+ * (directory, extension) (#352), `enforce()` verification probed one path per
+ * config block `files` glob (#351), and the routing catalog asked about
+ * `src/index.ts` alone. The same rule could be enabled for one caller and
+ * absent for another. This module owns the probe; every caller reads the same
+ * {@link EslintInventory}.
+ *
+ * This module is the pure half (the probe's script, its wire schema, and every
+ * question asked of the answer); `eslintInventory` in `linters.ts` runs the
+ * probe beside the other linter subprocesses, cached per project.
+ *
+ * HOW: a child `node -e` process runs in the project's directory, so `eslint`
+ * and the config's own imports resolve from the project exactly as `npx eslint`
+ * would, and nothing of the project's config loads into our process. The child
+ * lists the config's blocks (plugins they register, rules they mention, a probe
+ * path synthesized from each `files` glob), adds one representative path per
+ * (directory, name shape) of the project's files, and asks
+ * `calculateConfigForFile` for each. A rule is `enabled` if any probe has it on,
+ * `disabled` if every probe that sets it has it off.
+ *
+ * LIMITS, named: a block naming one exact file that shares directory and
+ * extension with siblings is reached only if its glob synthesizes that path; a
+ * config in a SUBDIRECTORY (v10 looks configs up per file) is not listed; a
+ * `files` entry given as a function is not probed. A rule that a block mentions
+ * but no probe reached reads `unknown`, never `unconfigured`.
+ */
+import type { ConfigEnabledStatus } from "./linter-adapter.js";
+/** What ESLint's resolved config says about the repo, when it loaded. */
+export interface EslintConfigView {
+    /** ESLint's built-in rule ids. */
+    readonly core: ReadonlySet<string>;
+    /** plugin namespace → its rule names, from the plugin objects ESLint holds. */
+    readonly plugins: ReadonlyMap<string, ReadonlySet<string>>;
+    /** rule id → state, merged over every probe path. */
+    readonly rules: ReadonlyMap<string, "enabled" | "disabled">;
+    /** rule ids some block sets, whether or not a probe reached that block. */
+    readonly mentioned: ReadonlySet<string>;
+    /** every block of the config was listed, so an unmentioned rule is unset. */
+    readonly complete: boolean;
+}
+/**
+ * The inventory. Separate members because each is a different instruction to
+ * the user: no ESLint, no config, a config that throws, a config that loads and
+ * switches nothing on, a config with rules.
+ */
+export type EslintInventory = {
+    readonly kind: "not-installed";
+} | {
+    readonly kind: "no-config";
+} | {
+    readonly kind: "failed";
+    readonly error: string;
+} | {
+    readonly kind: "empty";
+    readonly view: EslintConfigView;
+} | {
+    readonly kind: "loaded";
+    readonly view: EslintConfigView;
+};
+/**
+ * One representative path per distinct (directory, name shape) pair of the
+ * project's files. A flat-config `files` glob selects on the directory and the
+ * name's extension chain, so one file per pair sees every block any file of
+ * that pair could match — without linting a single file.
+ */
+export declare function representativePaths(files: readonly string[]): readonly string[];
+/** The files `representativePaths` picks from: everything but dependencies and git. */
+export declare const PROJECT_FILES_GLOB: {
+    readonly pattern: "**/*";
+    readonly ignore: readonly ["**/node_modules/**", "**/.git/**"];
+};
+export declare const ESLINT_PROBE_SCRIPT: string;
+/**
+ * Turn the child's stdout into an inventory. Pure, so every shape of answer is
+ * testable without spawning ESLint. @internal
+ */
+export declare function parseEslintInventory(stdout: string): EslintInventory;
+/** The view, when the config loaded (with or without enabled rules). */
+export declare function configView(inv: EslintInventory): EslintConfigView | null;
+/** Ids of every rule the config switches on somewhere, sorted. */
+export declare function enabledRuleIds(view: EslintConfigView): readonly string[];
+/** Enabled state of one rule id across every block of the config. */
+export declare function eslintRuleState(inv: EslintInventory, ruleId: string): ConfigEnabledStatus;
+/**
+ * Does the plugin the config REGISTERS under `ruleId`'s namespace define the
+ * rule? null when the config registers no plugin under that namespace (or did
+ * not load). The namespace is everything before the LAST slash — ESLint's own
+ * split, so `@scope/plugin/rule` works.
+ */
+export declare function registeredPluginHasRule(inv: EslintInventory, ruleId: string): boolean | null;
+//# sourceMappingURL=eslint-inventory.d.ts.map