paperlint 2.0.1 → 3.0.0

package/hooks/paper-edit-guard.hook.mjs

@@ -43,13 +43,13 @@
  * this cannot — there is only one file.
  *
  * ── WHERE THE CONSUMER'S PAPERS ARE ─────────────────────────────────────────
- * One declaration, `"paperlint": { "papersDir": "…" }`, read the way a hook is able to
- * read anything at all: `needs: [provide("pkg", "cat \"${CLAUDE_PROJECT_DIR:-.}/package.json\"")]`.
+ * One declaration, `{ "papersDir": "…" }` in the root `paperlint.json` (optional; default
+ * `papers`), read the way a hook is able to read anything at all: a `provide` that cats the file.
  * The alternatives were measured and killed in `eslint-rules/papers.mjs` — an env var cannot be
  * read from a hook at all (no imports), and a symlinked root makes ESLint report zero files.
  *
  * 🔴 THE PATH IS ANCHORED, AND THAT IS NOT DECORATION. vigiles runs a provider "via execSync in
- * the hook's cwd", so a bare `cat package.json` resolves against whatever directory the hook
+ * the hook's cwd", so a bare `cat paperlint.json` resolves against whatever directory the hook
  * PROCESS happens to have — which is set by the consumer's wiring, a string this hook cannot
  * see and does not control. With the wiring this package documents (`cd "$CLAUDE_PROJECT_DIR"
  * && node …`) the bare read is correct; without it, any tool cwd outside the project root makes
@@ -63,8 +63,8 @@
  * when the variable is absent, so this is strictly wider than what it replaces.
  *
  * 🔴 AN UNREADABLE DECLARATION DENIES, IT DOES NOT DEFAULT. Measured 2026-09-12: when the
- * provider's command fails — no `package.json`, or one with conflict markers in it — `e.ctx.pkg`
- * arrives as the EMPTY STRING and the runtime says nothing. A `try { JSON.parse } catch { use the
+ * provider's command fails — an unreadable file, or one with conflict markers in it — `e.ctx.config`
+ * arrives as the EMPTY STRING (or text that is not JSON) and the runtime says nothing. A `try { JSON.parse } catch { use the
  * default }` therefore turns a broken declaration into a silently permissive gate: the prefix
  * quietly becomes `papers`, nothing under the real root matches, and every Bash write to a paper
  * is allowed by a gate that still looks installed and green. So parse failure is a `deny` that
@@ -107,19 +107,29 @@ import {
   deny,
 } from "vigiles/hook";
 
-/** The key every carrier of this package reads its consumer-specific settings from. */
+/** The tool's name — the package this hook resolves its scripts through. */
 export const CONFIG_KEY = "paperlint";
-/** The key's name before 2.0.0 — still read, a copy of `lib/paper-config.mjs`. */
-export const LEGACY_CONFIG_KEY = "research-paper-pipeline";
+/** The settings file at the project root. Optional: absent means every default. */
+export const CONFIG_FILE = "paperlint.json";
 /** The default. A consumer that declares nothing is assumed to keep papers in `papers/`. */
 export const DEFAULT_PAPERS_ROOT = "papers";
 /**
- * The field under CONFIG_KEY that names the papers directory, and its old name. A copy of the
+ * The field of the root `paperlint.json` that names the papers directory. These are copies of the
  * constants in `lib/paper-config.mjs` (a hook may import nothing but `vigiles/hook`);
  * `lib/paper-config.harness.mjs` checks that the copies match.
  */
 export const PAPERS_DIR_FIELD = "papersDir";
-export const OLD_PAPERS_DIR_FIELD = "papers";
+
+/**
+ * The provider: the root `paperlint.json`, or `{}` when the project has none — so an ABSENT file
+ * (every default) and an UNREADABLE one (the empty string the runtime gives a failed provider)
+ * stay two different inputs.
+ *
+ * 🔴 THE PATH IS ANCHORED TO THE PROJECT ROOT. vigiles runs a provider "via execSync in the hook's
+ * cwd", which is the consumer's wiring — a string this hook cannot see. A bare relative path reads
+ * from whatever directory the Bash tool last moved to.
+ */
+const READ_CONFIG = `f="\${CLAUDE_PROJECT_DIR:-.}/${CONFIG_FILE}"; if [ -e "$f" ]; then cat "$f"; else echo '{}'; fi`;
 
 /**
  * The declared papers root, or a `deny` explaining why there is not one.
@@ -140,51 +150,30 @@ export const OLD_PAPERS_DIR_FIELD = "papers";
  * doesn't restrict exporting outward, and the reverse direction, CLI → hook, is free.
  * Returns the root string, or a rejection object: the caller tells them apart by `typeof`.
  */
-export const papersRoot = (rawPkg) => {
-  let pkg;
+export const papersRoot = (rawConfig) => {
+  let config;
   try {
-    pkg = JSON.parse(rawPkg);
+    config = JSON.parse(rawConfig);
   } catch {
     return deny(
-      `${CONFIG_KEY}: this gate could not read the consumer's package.json, so it does not know ` +
+      `${CONFIG_KEY}: this gate could not read the project's ${CONFIG_FILE}, so it does not know ` +
         `where papers live and is refusing rather than guessing.\n` +
         `The declaration it needs is:\n` +
-        `  "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": "path/to/papers" }\n` +
-        `(no key at all is fine too — the default is "${DEFAULT_PAPERS_ROOT}").\n` +
-        `If package.json is mid-merge or otherwise broken, fix it with Edit or Write: file ` +
+        `  { "${PAPERS_DIR_FIELD}": "path/to/papers" }\n` +
+        `(no file at all is fine too — the default is "${DEFAULT_PAPERS_ROOT}").\n` +
+        `If ${CONFIG_FILE} is mid-merge or otherwise broken, fix it with Edit or Write: file ` +
         `tools do not pass through this gate, so that path out is always open.\n` +
         `This refuses rather than falling back on purpose. A gate whose prefix quietly became ` +
         `the default would allow every Bash write to the real papers root while still looking ` +
         `installed and green.`,
     );
   }
-  // The settings sit under CONFIG_KEY, or under its old name. Both, with different contents, is
-  // refused: the gate cannot know which one the author means.
-  const current = pkg?.[CONFIG_KEY];
-  const legacy = pkg?.[LEGACY_CONFIG_KEY];
-  if (
-    current !== undefined &&
-    legacy !== undefined &&
-    JSON.stringify(current) !== JSON.stringify(legacy)
-  )
-    return deny(
-      `package.json has both "${CONFIG_KEY}" and "${LEGACY_CONFIG_KEY}", and they differ. ` +
-        `Keep "${CONFIG_KEY}" and delete "${LEGACY_CONFIG_KEY}" (its old name). ` +
-        `Fix it with Edit or Write: file tools do not pass through this gate.`,
-    );
-  const settings = current ?? legacy;
-  // The old field name is refused, not read as a fallback: this gate would otherwise guard the
-  // default directory while the consumer believes it guards the one they declared.
-  if (settings && Object.hasOwn(settings, OLD_PAPERS_DIR_FIELD))
-    return deny(
-      `"${OLD_PAPERS_DIR_FIELD}" was renamed to "${PAPERS_DIR_FIELD}" in package.json → "${CONFIG_KEY}"`,
-    );
-  const declared = settings?.[PAPERS_DIR_FIELD];
+  const declared = config?.[PAPERS_DIR_FIELD];
   const root = declared === undefined ? DEFAULT_PAPERS_ROOT : declared;
   if (typeof root !== "string" || root.length === 0)
     return deny(
       `${CONFIG_KEY}: "${PAPERS_DIR_FIELD}" must be a non-empty string, got ${JSON.stringify(root)}.\n` +
-        `Fix it in the consumer's package.json. This gate refuses while the value is unusable: ` +
+        `Fix it in the project's ${CONFIG_FILE}. This gate refuses while the value is unusable: ` +
         `an empty prefix matches nothing, so the gate would pass every paper write in silence.`,
     );
   // One trailing slash at most, whatever the consumer typed: `"papersDir": "docs/papers/"` reaches
@@ -425,9 +414,9 @@ const namesPaperSource = (raw, prefixes) =>
 export default experimental_defineHook({
   on: "PreToolUse",
   match: tools("Bash"),
-  needs: [provide("pkg", 'cat "${CLAUDE_PROJECT_DIR:-.}/package.json"')],
+  needs: [provide("config", READ_CONFIG)],
   decide: (e) => {
-    const root = papersRoot(e.ctx.pkg);
+    const root = papersRoot(e.ctx.config);
     // A `deny` object rather than a string means the root could not be established. Returning it
     // unchanged is deliberate: there is no root to continue with, so there is nothing to decide.
     if (typeof root !== "string") return root;

package/hooks/paper-skills-nudge.hook.mjs

@@ -38,19 +38,29 @@ import {
   nothing,
 } from "vigiles/hook";
 
-/** The key every carrier of this package reads its consumer-specific settings from. */
+/** The tool's name — the package this hook resolves its scripts through. */
 export const CONFIG_KEY = "paperlint";
-/** The key's name before 2.0.0 — still read, a copy of `lib/paper-config.mjs`. */
-export const LEGACY_CONFIG_KEY = "research-paper-pipeline";
+/** The settings file at the project root. Optional: absent means every default. */
+export const CONFIG_FILE = "paperlint.json";
 /** The default. A consumer that declares nothing is assumed to keep papers in `papers/`. */
 export const DEFAULT_PAPERS_ROOT = "papers";
 /**
- * The field under CONFIG_KEY that names the papers directory, and its old name. A copy of the
+ * The field of the root `paperlint.json` that names the papers directory. These are copies of the
  * constants in `lib/paper-config.mjs` (a hook may import nothing but `vigiles/hook`);
  * `lib/paper-config.harness.mjs` checks that the copies match.
  */
 export const PAPERS_DIR_FIELD = "papersDir";
-export const OLD_PAPERS_DIR_FIELD = "papers";
+
+/**
+ * The provider: the root `paperlint.json`, or `{}` when the project has none — so an ABSENT file
+ * (every default) and an UNREADABLE one (the empty string the runtime gives a failed provider)
+ * stay two different inputs.
+ *
+ * 🔴 THE PATH IS ANCHORED TO THE PROJECT ROOT. vigiles runs a provider "via execSync in the hook's
+ * cwd", which is the consumer's wiring — a string this hook cannot see. A bare relative path reads
+ * from whatever directory the Bash tool last moved to.
+ */
+const READ_CONFIG = `f="\${CLAUDE_PROJECT_DIR:-.}/${CONFIG_FILE}"; if [ -e "$f" ]; then cat "$f"; else echo '{}'; fi`;
 
 /**
  * The declared papers root, or `null` when it is unusable.
@@ -74,14 +84,10 @@ export const OLD_PAPERS_DIR_FIELD = "papers";
  * 🔴 `declared === undefined`, NOT `declared ?? DEFAULT` — `"papersDir": null` is a keystroke, not
  * an absence. Same distinction as every other carrier in this package.
  */
-const papersRoot = (rawPkg) => {
+const papersRoot = (rawConfig) => {
   let declared;
   try {
-    const pkg = JSON.parse(rawPkg);
-    const settings = pkg?.[CONFIG_KEY] ?? pkg?.[LEGACY_CONFIG_KEY];
-    // Old field name: stay silent rather than fall back to the default directory.
-    if (settings && Object.hasOwn(settings, OLD_PAPERS_DIR_FIELD)) return null;
-    declared = settings?.[PAPERS_DIR_FIELD];
+    declared = JSON.parse(rawConfig)?.[PAPERS_DIR_FIELD];
   } catch {
     return null;
   }
@@ -113,21 +119,17 @@ RULES earned the hard way:
 export default experimental_defineReact({
   on: "PostToolUse",
   match: tools("Edit", "Write", "MultiEdit"),
-  // 🔴 THE PATH IS ANCHORED TO THE PROJECT ROOT, and that is not decoration. vigiles runs the
-  // provider "via execSync in the hook's cwd", and the hook process's cwd is the consumer's
-  // own wiring — a string this hook cannot see. A bare `cat package.json` therefore reads from
-  // whatever directory the Bash tool last moved to, and a `cd` into a subdirectory with no
-  // manifest breaks the read.
+  // The provider is anchored to the project root (`READ_CONFIG`, above).
   //
   // ⚠️ THE FAILURE HERE IS SILENT, which makes it more dangerous than its neighbor's.
   // `paper-edit-guard` on PreToolUse DENIES loudly and visibly when the declaration is
   // unreadable. This hook on PostToolUse just returns `nothing()`, i.e. simply stops firing:
-  // the `cat` chain fails → empty string → `JSON.parse("")` throws → `papersRoot` returns null
+  // the `cat` fails → empty string → `JSON.parse("")` throws → `papersRoot` returns null
   // → silence. And silence is exactly what a nudge's success state looks like, so a dead hook
   // is indistinguishable from a working one.
-  needs: [provide("pkg", 'cat "${CLAUDE_PROJECT_DIR:-.}/package.json"')],
+  needs: [provide("config", READ_CONFIG)],
   react: (e) => {
-    const root = papersRoot(e.ctx.pkg);
+    const root = papersRoot(e.ctx.config);
     if (root === null) return nothing();
     return e.path.under([root]) && isPaperSource(e.path.raw)
       ? notice(CHECKLIST)

package/hooks/paper-status-gates.hook.mjs

@@ -63,19 +63,29 @@ import {
   nothing,
 } from "vigiles/hook";
 
-/** The key every carrier of this package reads its consumer-specific settings from. */
+/** The tool's name — the package this hook resolves its scripts through. */
 export const CONFIG_KEY = "paperlint";
-/** The key's name before 2.0.0 — still read, a copy of `lib/paper-config.mjs`. */
-export const LEGACY_CONFIG_KEY = "research-paper-pipeline";
+/** The settings file at the project root. Optional: absent means every default. */
+export const CONFIG_FILE = "paperlint.json";
 /** The default. A consumer that declares nothing is assumed to keep papers in `papers/`. */
 export const DEFAULT_PAPERS_ROOT = "papers";
 /**
- * The field under CONFIG_KEY that names the papers directory, and its old name. A copy of the
+ * The field of the root `paperlint.json` that names the papers directory. These are copies of the
  * constants in `lib/paper-config.mjs` (a hook may import nothing but `vigiles/hook`);
  * `lib/paper-config.harness.mjs` checks that the copies match.
  */
 export const PAPERS_DIR_FIELD = "papersDir";
-export const OLD_PAPERS_DIR_FIELD = "papers";
+
+/**
+ * The provider: the root `paperlint.json`, or `{}` when the project has none — so an ABSENT file
+ * (every default) and an UNREADABLE one (the empty string the runtime gives a failed provider)
+ * stay two different inputs.
+ *
+ * 🔴 THE PATH IS ANCHORED TO THE PROJECT ROOT. vigiles runs a provider "via execSync in the hook's
+ * cwd", which is the consumer's wiring — a string this hook cannot see. A bare relative path reads
+ * from whatever directory the Bash tool last moved to.
+ */
+const READ_CONFIG = `f="\${CLAUDE_PROJECT_DIR:-.}/${CONFIG_FILE}"; if [ -e "$f" ]; then cat "$f"; else echo '{}'; fi`;
 
 /**
  * The declared papers root, or `null` when it is unusable.
@@ -88,14 +98,10 @@ export const OLD_PAPERS_DIR_FIELD = "papers";
  * 🔴 `declared === undefined`, NOT `declared ?? DEFAULT` — `"papersDir": null` is a keystroke, not
  * an absence.
  */
-const papersRoot = (rawPkg) => {
+const papersRoot = (rawConfig) => {
   let declared;
   try {
-    const pkg = JSON.parse(rawPkg);
-    const settings = pkg?.[CONFIG_KEY] ?? pkg?.[LEGACY_CONFIG_KEY];
-    // Old field name: stay silent rather than fall back to the default directory.
-    if (settings && Object.hasOwn(settings, OLD_PAPERS_DIR_FIELD)) return null;
-    declared = settings?.[PAPERS_DIR_FIELD];
+    declared = JSON.parse(rawConfig)?.[PAPERS_DIR_FIELD];
   } catch {
     return null;
   }
@@ -133,21 +139,17 @@ const surface = (dir) =>
 export default experimental_defineReact({
   on: "PostToolUse",
   match: tools("Edit", "Write", "MultiEdit"),
-  // 🔴 THE PATH IS ANCHORED TO THE PROJECT ROOT, and that is not decoration. vigiles runs the
-  // provider "via execSync in the hook's cwd", and the hook process's cwd is the consumer's
-  // own wiring — a string this hook cannot see. A bare `cat package.json` therefore reads from
-  // whatever directory the Bash tool last moved to, and a `cd` into a subdirectory with no
-  // manifest breaks the read.
+  // The provider is anchored to the project root (`READ_CONFIG`, above).
   //
   // ⚠️ THE FAILURE HERE IS SILENT, which makes it more dangerous than its neighbor's.
   // `paper-edit-guard` on PreToolUse DENIES loudly and visibly when the declaration is
   // unreadable. This hook on PostToolUse just returns `nothing()`, i.e. simply stops firing:
-  // the `cat` chain fails → empty string → `JSON.parse("")` throws → `papersRoot` returns null
+  // the `cat` fails → empty string → `JSON.parse("")` throws → `papersRoot` returns null
   // → silence. And silence is exactly what a nudge's success state looks like, so a dead hook
   // is indistinguishable from a working one.
-  needs: [provide("pkg", 'cat "${CLAUDE_PROJECT_DIR:-.}/package.json"')],
+  needs: [provide("config", READ_CONFIG)],
   react: (e) => {
-    const root = papersRoot(e.ctx.pkg);
+    const root = papersRoot(e.ctx.config);
     if (root === null) return nothing();
     const m = paperSourceRe(root).exec(e.path.raw.replace(/^\.\//, ""));
     if (m === null) return nothing();

package/hooks/paper-status-gates.sh

@@ -27,33 +27,28 @@ case "$pdir_name" in
   *[!A-Za-z0-9._-]* | "" | . | ..) exit 0 ;;
 esac
 
-# ── WHERE THE CONSUMER'S THINGS ARE — TWO CARRIERS, READ, NOT ASSUMED ────────
-# This file used to hard-code both of these paths, which made it a tool with exactly one possible
-# user. Both now come from the one declaration every other carrier of this package reads:
+# ── WHERE THE CONSUMER'S THINGS ARE — READ, NOT ASSUMED ─────────────────────
+# Both paths come from the one declaration every other carrier of this package reads, the
+# project's root paperlint.json (optional — absent means every default):
 #
-#   "paperlint": { "papersDir": "docs/papers", "scripts": "tools/pipeline" }
+#   { "papersDir": "docs/papers", "scripts": "tools/pipeline" }
 #
-# (The key's name before 2.0.0, "research-paper-pipeline", is still read.)
-#
-# ⚠️ `node -p` RATHER THAN grep/sed ON package.json. A JSON value is not a line of text: it can
+# ⚠️ `node -p` RATHER THAN grep/sed ON THE FILE. A JSON value is not a line of text: it can
 # be quoted, escaped, or spread across lines, and a pattern that gets it right today gets it
 # wrong on the first reformat — silently, by producing a root that matches nothing. Node is
 # already a hard dependency of the checker this script runs, so there is no new requirement.
 ROOT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 read_key() { # $1 = key, $2 = default
-  node -p "((p) => p['paperlint'] ?? p['research-paper-pipeline'] ?? {})(require('$ROOT_DIR/package.json'))['$1'] ?? '$2'" \
+  node -p "((c) => c['$1'] ?? '$2')((() => { try { return require('$ROOT_DIR/paperlint.json') } catch { return {} } })())" \
     2>/dev/null || echo "$2"
 }
-# The field used to be called "papers". Every other reader refuses the old name; this script only
-# gives advice, so it stays silent instead of falling back to the default directory.
-[ -z "$(read_key papers '')" ] || exit 0
 papers_root="$(read_key papersDir papers)"
 scripts_root="$(read_key scripts .claude/skills/paper-pipeline/scripts)"
 
 # 🔴 AN UNUSABLE ROOT EXITS, IT DOES NOT BUILD A PATH FROM IT. `node -p` prints `undefined` for a
 # key whose value is literally `null` (`?? ` only catches null/undefined AFTER the object lookup,
-# and a `null` value reaches the default — but a malformed package.json makes the whole command
-# fail and the `|| echo` hands back the default). Either way, an empty or nonsense value would
+# and a `null` value reaches the default — but a malformed paperlint.json reads as {} and
+# hands back the default). Either way, an empty or nonsense value would
 # produce `/<paper>/PIPELINE-STATUS.md` rooted at the filesystem, which does not exist, and this
 # script would exit 0 looking like a paper with nothing to report. Named rather than risked.
 case "$papers_root" in

package/lib/paper-config.d.mts

@@ -5,30 +5,27 @@
 // The field names are typed as `string`, not as their values, so that the value is written
 // once, in paper-config.mjs.
 
+/** The tool's name — its settings file is named after it. */
 export declare const CONFIG_KEY: string;
-export declare const LEGACY_CONFIG_KEY: string;
-export declare const LEGACY_KEY_MESSAGE: string;
+/** `paperlint.json`: the settings file, at the project root and in each paper. */
+export declare const CONFIG_FILE: string;
+/** The files that make a directory a paper. */
+export declare const PAPER_MARKERS: readonly string[];
 
-/** Where a parsed package.json keeps the settings: the new key, else the old one. */
-export declare function declaredSettings(pkg: unknown): {
-  readonly settings: unknown;
-  readonly legacy: boolean;
-  readonly conflict: string | null;
-};
+/** The project root, walking up from `startDir` (see the module). */
+export declare function findProjectRoot(
+  startDir: string,
+  isFile?: (path: string) => boolean,
+): string;
 
-/** The settings object alone — undefined when absent or on a conflict. */
+/** The root `paperlint.json` of `root` — undefined when absent, unparsable or not an object. */
 export declare function settingsOf(
-  pkg: unknown,
+  root: string,
 ): Readonly<Record<string, unknown>> | undefined;
 export declare const DEFAULT_PAPERS_ROOT: string;
 export declare const PAPERS_DIR_FIELD: string;
-export declare const OLD_PAPERS_DIR_FIELD: string;
 
-/** The error text for settings that still use the old field name, or `null` when they do not. */
-export declare function renamedFieldMessage(
-  settings: unknown,
-  where?: string,
-): string | null;
-
-/** Every key the settings object may hold, mapped to who reads it. */
+/** Every key a `paperlint.json` may hold, at either level, mapped to who reads it. */
 export declare const SETTINGS_KEYS: Readonly<Record<string, string>>;
+/** The keys refused in a paper's `paperlint.json`. */
+export declare const ROOT_ONLY_KEYS: readonly string[];

package/lib/paper-config.harness.mjs

@@ -62,8 +62,7 @@ const loaded = await Promise.all(
       key: mod.CONFIG_KEY,
       def: mod.DEFAULT_PAPERS_ROOT,
       field: mod.PAPERS_DIR_FIELD,
-      old: mod.OLD_PAPERS_DIR_FIELD,
-      legacyKey: mod.LEGACY_CONFIG_KEY,
+      file: mod.CONFIG_FILE,
     };
   }),
 );
@@ -98,30 +97,34 @@ const loaded = await Promise.all(
     `all carriers agree on DEFAULT_PAPERS_ROOT (${[...defs].join(" / ")})`,
     defs.size === 1,
   );
-  // The papers-directory field name, and its old name. Only the source and the three hooks
+  // The papers-directory field name. Only the source and the three hooks
   // (which cannot import it) declare these; the value itself is pinned nowhere but the source,
   // so a rename stays a one-line change there plus the hook copies this checks.
   const fields = new Set(
     loaded.map((c) => c.field).filter((v) => v !== undefined),
   );
-  const olds = new Set(loaded.map((c) => c.old).filter((v) => v !== undefined));
   check(
     `all carriers agree on PAPERS_DIR_FIELD (${[...fields].join(" / ")})`,
     fields.size === 1,
   );
+  const files = new Set(
+    loaded.map((c) => c.file).filter((v) => v !== undefined),
+  );
   check(
-    `all carriers agree on OLD_PAPERS_DIR_FIELD (${[...olds].join(" / ")})`,
-    olds.size === 1,
+    `all carriers agree on CONFIG_FILE (${[...files].join(" / ")})`,
+    files.size === 1,
   );
   check(
-    "every hook declares both field names — a hook without them would read an undefined field",
+    "every hook declares the file name — its provider reads that file",
     loaded
       .filter((c) => c.rel.endsWith(".hook.mjs"))
-      .every((c) => typeof c.field === "string" && typeof c.old === "string"),
+      .every((c) => typeof c.file === "string"),
   );
   check(
-    "the new and the old field names differ",
-    loaded[0].field !== loaded[0].old,
+    "every hook declares the field name — a hook without it would read an undefined field",
+    loaded
+      .filter((c) => c.rel.endsWith(".hook.mjs"))
+      .every((c) => typeof c.field === "string"),
   );
   check(
     "and no carrier is silent about both at once — such an entry is dead weight on the list",
@@ -135,23 +138,6 @@ const loaded = await Promise.all(
     loaded[0].key ===
       JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).name,
   );
-  // The old key is still read — by the source and by each hook, which keep their own copy.
-  const legacyKeys = new Set(
-    loaded.map((c) => c.legacyKey).filter((v) => v !== undefined),
-  );
-  const { LEGACY_PACKAGE_NAME } = await import(
-    pathToFileURL(join(ROOT, "skills/paper-pipeline/scripts/consumer.mjs")).href
-  );
-  check(
-    `all carriers agree on LEGACY_CONFIG_KEY, the package's old name (${[...legacyKeys].join(" / ")})`,
-    legacyKeys.size === 1 && legacyKeys.has(LEGACY_PACKAGE_NAME),
-  );
-  check(
-    "and every hook carries it — a hook without it would ignore settings under the old key",
-    loaded
-      .filter((c) => c.rel.endsWith(".hook.mjs"))
-      .every((c) => c.legacyKey !== undefined),
-  );
 }
 
 // ── III. THE HOOKS DUPLICATE, AND THAT IS CHECKED SEPARATELY ───────────────────────────────
@@ -186,7 +172,7 @@ const loaded = await Promise.all(
     "repro",
   ]);
   const declares =
-    /^(?:export )?const (?:CONFIG_KEY|DEFAULT_PAPERS_ROOT|PAPERS_DIR_FIELD|OLD_PAPERS_DIR_FIELD)\s*=/m;
+    /^(?:export )?const (?:CONFIG_KEY|CONFIG_FILE|DEFAULT_PAPERS_ROOT|PAPERS_DIR_FIELD)\s*=/m;
   const found = [];
   const walk = (dir) => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
@@ -218,19 +204,16 @@ const loaded = await Promise.all(
 // The settings object has readers all over the package, each reading its own keys, and the CLI
 // refuses any key not in SETTINGS_KEYS. So the list must hold every key some reader reads — or a
 // consumer's valid key is refused — and nothing no one reads. The readers are FOUND, by the AST:
-// every `[CONFIG_KEY]?.<key>` (or the literal package name in the brackets), plus every field of
+// every `settingsOf(root)?.<key>` (and the older `[CONFIG_KEY]?.<key>` shape), plus every field of
 // `PaperlintConfig`, the CLI's typed view of the same object.
 {
   const { SETTINGS_KEYS } = await import(join(HERE, "paper-config.mjs"));
   const ts = (await import("typescript")).default;
   const readKeys = new Set();
   const isConfigKey = (e) =>
-    (ts.isIdentifier(e) &&
-      (e.text === "CONFIG_KEY" || e.text === "LEGACY_CONFIG_KEY")) ||
-    (ts.isStringLiteral(e) &&
-      (e.text === "paperlint" || e.text === "research-paper-pipeline"));
-  // A read is `pkg[CONFIG_KEY]?.<key>` or `settingsOf(pkg)?.<key>` — the helper that also reads
-  // the old key.
+    (ts.isIdentifier(e) && e.text === "CONFIG_KEY") ||
+    (ts.isStringLiteral(e) && e.text === "paperlint");
+  // A read is `settingsOf(root)?.<key>` (or `x[CONFIG_KEY]?.<key>`).
   const isSettings = (e) =>
     (ts.isElementAccessExpression(e) && isConfigKey(e.argumentExpression)) ||
     (ts.isCallExpression(e) &&