paperlint 2.1.0 → 3.0.0

package/lib/paper-config.mjs

@@ -20,95 +20,87 @@
  * COVERAGE.
  */
 
-/** The key in the consumer's `package.json` this package's settings are read from. */
-export const CONFIG_KEY = "paperlint";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 
 /**
- * The key's name before 2.0.0, when the package was `research-paper-pipeline`. Still READ, with a
- * deprecation line from the CLI and `doctor`; `init` renames it. Both keys at once with different
- * contents is refused: there is no way to know which one the author means.
+ * The tool's name. Its settings file is named after it (`CONFIG_FILE`), its messages start with it,
+ * and the hooks resolve their scripts through it. It equals the package name, and
+ * `lib/paper-config.harness.mjs` checks that.
  */
-export const LEGACY_CONFIG_KEY = "research-paper-pipeline";
+export const CONFIG_KEY = "paperlint";
 
 /**
- * THE THREE LEVELS OF SETTINGS, each named after the tool:
+ * THE SETTINGS FILE, ONE NAME AT TWO LEVELS, ONE SCHEMA (`SETTINGS_KEYS`):
  *
- *   package.json → "paperlint"     the project: where the papers are, what every paper gets
- *   <paper>/paperlint.json         one paper: the venue preset it extends, its kind, its own rules
- *   a venue preset                 one venue: its format, TeX packages and rules — shipped with
- *                                  paperlint (`paperlint:<name>`) or the project's own (`./x.jsonc`)
+ *   paperlint.json                 optional, at the project root: where the papers are, the
+ *                                  project's rules, and defaults for every paper
+ *   <papersDir>/<paper>/paperlint.json   one paper: its venue preset, its kind, its own rules
  *
- * The per-paper file was `venue.json` before 2.1.0. It is NOT read any more — a fallback would keep
- * it working forever — and `paperlint init` moves it.
+ * A paper's file merges over the root's: its `extends`, `kind` and `pdf` win, and its `rules` are
+ * applied after the root's. A venue preset (`paperlint:<name>`, or the project's own `./x.jsonc`)
+ * is the third level, below both.
  */
-export const PAPER_SETTINGS_FILE = "paperlint.json";
-export const LEGACY_PAPER_SETTINGS_FILE = "venue.json";
+export const CONFIG_FILE = "paperlint.json";
 
 /**
- * Every key `paperlint.json` may hold. Any other key is REFUSED with its name: a typo would
- * otherwise read as "not set". `$comment` is JSON Schema's own keyword for a comment, the one way
- * to leave a note in a JSON file; paperlint ignores its value.
+ * The files that make a directory a PAPER. A `paperlint.json` beside one of them is that paper's,
+ * never the project's — so walking up from inside a paper does not stop at the paper's own file.
  */
-export const PAPER_SETTINGS_KEYS = Object.freeze({
-  extends:
-    "the venue preset: paperlint:<name> or ./path.jsonc — the pdf/ venue rules, paperlint build",
-  kind: "the kind of paper, whose page limit applies — pdf/limits",
-  pdf: "where the built PDF is, relative to the paper, when it is not paper.pdf — the facts",
-  rules: "rule overrides for this paper alone — paperlint lint",
-  $comment: "a note for humans; ignored",
-});
-
-/** What a leftover pre-2.1.0 file is told. */
-export const LEGACY_PAPER_SETTINGS_MESSAGE = `${LEGACY_PAPER_SETTINGS_FILE} is no longer read: it was renamed ${PAPER_SETTINGS_FILE} in paperlint 2.1.0. \`npx paperlint init\` moves it.`;
+export const PAPER_MARKERS = Object.freeze([
+  "paper.tex",
+  "paper.md",
+  "draft.md",
+  "PIPELINE-STATUS.md",
+]);
 
 /**
- * Where a parsed `package.json` keeps this package's settings — the new key, else the old one.
+ * The project root: the nearest directory, walking up from `startDir`, that holds a root
+ * `paperlint.json` (one not beside a paper's files); else the nearest directory holding a
+ * `package.json`; else `startDir` itself. The same walk eslint, prettier and tsc use for theirs.
  *
- * @returns `settings` (undefined when neither key is there, or on a conflict), `legacy` (read
- *   from the old key), `conflict` (the message when both keys are there and differ, else null).
+ * @param isFile  whether a path exists — `existsSync` by default; `src/` passes its Files port.
  */
-export function declaredSettings(pkg) {
-  const has = (k) =>
-    pkg !== null && typeof pkg === "object" && Object.hasOwn(pkg, k);
-  const current = has(CONFIG_KEY);
-  const legacy = has(LEGACY_CONFIG_KEY);
-  if (
-    current &&
-    legacy &&
-    JSON.stringify(pkg[CONFIG_KEY]) !== JSON.stringify(pkg[LEGACY_CONFIG_KEY])
-  )
-    return {
-      settings: undefined,
-      legacy: false,
-      conflict:
-        `package.json has both "${CONFIG_KEY}" and "${LEGACY_CONFIG_KEY}", and they differ. ` +
-        `Keep "${CONFIG_KEY}" and delete "${LEGACY_CONFIG_KEY}" (its old name).`,
-    };
-  if (current)
-    return { settings: pkg[CONFIG_KEY], legacy: false, conflict: null };
-  if (legacy)
-    return { settings: pkg[LEGACY_CONFIG_KEY], legacy: true, conflict: null };
-  return { settings: undefined, legacy: false, conflict: null };
+export function findProjectRoot(startDir, isFile = existsSync) {
+  const start = resolve(startDir);
+  const isPaper = (d) => PAPER_MARKERS.some((m) => isFile(join(d, m)));
+  const walk = (found) => {
+    for (let d = start; ; d = dirname(d)) {
+      if (found(d)) return d;
+      if (dirname(d) === d) return null;
+    }
+  };
+  return (
+    walk((d) => isFile(join(d, CONFIG_FILE)) && !isPaper(d)) ??
+    walk((d) => isFile(join(d, "package.json"))) ??
+    start
+  );
 }
 
+const isObject = (v) =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+
 /**
- * The settings object alone, for readers that only need a value: the new key, else the old one,
- * and nothing on a conflict (the CLI, `doctor` and the edit guard report the conflict).
+ * The project's settings: the object in `<root>/paperlint.json`, or undefined when there is no
+ * such file, or it does not parse, or it is not an object. For readers that only need one key and
+ * fall back to its default; `paperlint lint` parses the file strictly and names what is wrong.
  */
-export function settingsOf(pkg) {
-  const d = declaredSettings(pkg);
-  return d.conflict === null ? d.settings : undefined;
+export function settingsOf(root) {
+  let v;
+  try {
+    v = JSON.parse(readFileSync(join(root, CONFIG_FILE), "utf8"));
+  } catch {
+    return undefined;
+  }
+  return isObject(v) ? v : undefined;
 }
 
-/** The deprecation line for settings read from the old key. */
-export const LEGACY_KEY_MESSAGE = `"${LEGACY_CONFIG_KEY}" in package.json is the old name of this package's key — rename it to "${CONFIG_KEY}". \`npx paperlint init\` does it for you.`;
-
-/** Default: a consumer that declares nothing is assumed to keep papers in `papers/`. */
+/** The default papers directory, used when the root `paperlint.json` declares none (or there is none). */
 export const DEFAULT_PAPERS_ROOT = "papers";
 
 /**
- * The field under CONFIG_KEY that names the papers directory:
- * `"paperlint": { "papersDir": "papers" }`.
+ * The field that names the papers directory: `{ "papersDir": "papers" }` in the root
+ * `paperlint.json`. Optional; absent means `DEFAULT_PAPERS_ROOT`.
  *
  * This is the one place the name is spelled. Code reads the field as
  * `settings[PAPERS_DIR_FIELD]`, never by a literal, so renaming it again is a one-line change
@@ -118,51 +110,24 @@ export const DEFAULT_PAPERS_ROOT = "papers";
 export const PAPERS_DIR_FIELD = "papersDir";
 
 /**
- * The field's old name. A config that still has it is REFUSED with `renamedFieldMessage()`,
- * even if it also has the new one: the package is unpublished, so there is nobody to migrate
- * quietly, and reading the old name as a fallback would leave it working forever.
- */
-export const OLD_PAPERS_DIR_FIELD = "papers";
-
-/**
- * The error text for a config that still uses the old field name, or `null` when it does not.
- *
- * @param settings  the object under CONFIG_KEY
- * @param where     where that object lives, as the reader should see it in the message
- */
-export function renamedFieldMessage(
-  settings,
-  where = `package.json → "${CONFIG_KEY}"`,
-) {
-  if (settings === null || typeof settings !== "object") return null;
-  if (!Object.hasOwn(settings, OLD_PAPERS_DIR_FIELD)) return null;
-  return `"${OLD_PAPERS_DIR_FIELD}" was renamed to "${PAPERS_DIR_FIELD}" in ${where}`;
-}
-
-/**
- * Every key the settings object may hold, with who reads it. A key not listed here is REFUSED
- * with its name (`paperlint lint`, `paperlint build`, `paperlint new`, `paperlint doctor` all read through the same
- * parser), because a typo in a key otherwise reads as "not set" — the defect `src/types.ts` names
- * in its first line.
+ * Every key a `paperlint.json` may hold — the root's and a paper's, ONE schema — with who reads it.
+ * A key not listed here is REFUSED with its name, because a typo in a key otherwise reads as "not
+ * set". The keys in `ROOT_ONLY_KEYS` describe the whole project and are refused in a paper's file.
  *
- * 🔴 ONE LIST, AND IT IS CHECKED AGAINST THE READERS, NOT TRUSTED. The settings object has readers
- * all over the package (the CLI, the skill scripts, the trigger-case loader), each reading its own
- * keys. `lib/paper-config.harness.mjs` walks the package's source, finds every
- * `[CONFIG_KEY]?.<key>` read and every field of `PaperlintConfig`, and requires each to be here — so a
- * new reader that forgets this list turns the harness red before a consumer's config does.
+ * 🔴 ONE LIST, AND IT IS CHECKED AGAINST THE READERS, NOT TRUSTED. `lib/paper-config.harness.mjs`
+ * walks the package's source, finds every `settingsOf(…)?.<key>` read and every field of
+ * `PaperlintConfig`, and requires each to be here — so a new reader that forgets this list turns
+ * the harness red before a consumer's config does.
  */
 export const SETTINGS_KEYS = Object.freeze({
-  papersDir: "the papers directory (required) — every command, the hooks",
+  papersDir: `the papers directory, default "papers" — every command, the hooks`,
   structure: "which files a paper directory must hold — paperlint lint",
-  authorListCommand: "paper/author-list — paperlint lint",
-  typographyDebt: "paper/typography — paperlint lint",
-  docFields: "doc/fields — paperlint lint",
-  reviewSince: "review/findings-cause — paperlint lint",
-  minFindings: "review/findings-cause — paperlint lint",
-  causeMarker: "review/findings-cause — paperlint lint",
   rules:
-    "extra ESLint config blocks, appended after paperlint's own — paperlint lint",
-  buildScripts: "REMOVED; still named so paperlint build can say it is ignored",
+    "rule overrides: { id: severity } for every paper in scope, or ESLint blocks (files, ignores, rules) — paperlint lint",
+  extends:
+    "the venue preset: paperlint:<name> or ./path.jsonc — the pdf/ venue rules, paperlint build",
+  kind: "the kind of paper, whose page limit applies — pdf/limits",
+  pdf: "where the built PDF is, relative to the paper, when it is not paper.pdf — the facts",
   ledger: "the run ledger — skills/paper-pipeline/scripts/consumer.mjs",
   scripts: "how skill prose names the scripts — consumer.mjs",
   timezone: "dates in the ledger — consumer.mjs",
@@ -170,4 +135,17 @@ export const SETTINGS_KEYS = Object.freeze({
   citeChecks: "the consumer's citation checkers — run-mechanical.mjs",
   triggerCases:
     "the consumer's own skill trigger cases — lib/skill-trigger-cases.mjs",
+  $comment: "a note for humans (JSON Schema's own comment keyword); ignored",
 });
+
+/** The keys that only mean something for the whole project: refused in a paper's `paperlint.json`. */
+export const ROOT_ONLY_KEYS = Object.freeze([
+  "papersDir",
+  "structure",
+  "ledger",
+  "scripts",
+  "timezone",
+  "contactEmail",
+  "citeChecks",
+  "triggerCases",
+]);

package/lib/paper-config.mutations.mjs

@@ -117,8 +117,8 @@ process.exit(
         edits: [
           [
             DOCTOR,
-            'import {\n  papersRoot,\n  CONFIG_KEY,\n  DEFAULT_PAPERS_ROOT,\n  PAPERS_DIR_FIELD,\n  OLD_PAPERS_DIR_FIELD,\n} from "../hooks/paper-edit-guard.hook.mjs";',
-            'import {\n  papersRoot,\n  DEFAULT_PAPERS_ROOT,\n  PAPERS_DIR_FIELD,\n  OLD_PAPERS_DIR_FIELD,\n} from "../hooks/paper-edit-guard.hook.mjs";\nconst CONFIG_KEY = "research-paper-pipeline";',
+            'import {\n  papersRoot,\n  DEFAULT_PAPERS_ROOT,\n  PAPERS_DIR_FIELD,\n  CONFIG_FILE,\n} from "../hooks/paper-edit-guard.hook.mjs";',
+            'import {\n  papersRoot,\n  DEFAULT_PAPERS_ROOT,\n  PAPERS_DIR_FIELD,\n} from "../hooks/paper-edit-guard.hook.mjs";\nconst CONFIG_FILE = "paperlint.json";',
           ],
         ],
       },

package/lib/skill-checks.mjs

@@ -70,7 +70,7 @@ import {
 //
 // The value now comes from the package, as the fourth carrier beside `papersRoot()` (where the
 // papers are), `ledgerPath()` (where the journal is) and `citeChecks` (where the consumer's own
-// citation checkers are). One declaration in `package.json`, default
+// citation checkers are). One declaration in `paperlint.json`, default
 // `.claude/skills/paper-pipeline/scripts`, and the resolver REFUSES a root that is not on disk
 // or that resolves inside `node_modules`.
 //

package/lib/skill-trigger-cases.harness.mjs

@@ -53,9 +53,12 @@ function loadAt(root) {
   }).trim();
 }
 
-function fixture(pkgJson, casesFile) {
+/** A consumer: a package.json, the root paperlint.json `settings` (none when null), a cases file. */
+function fixture(settings, casesFile) {
   const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-cases-")));
-  writeFileSync(join(root, "package.json"), JSON.stringify(pkgJson));
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "c" }));
+  if (settings)
+    writeFileSync(join(root, "paperlint.json"), JSON.stringify(settings));
   if (casesFile) {
     mkdirSync(join(root, ".claude", "lib"), { recursive: true });
     writeFileSync(
@@ -114,7 +117,7 @@ soft("I. irrelevantFor still yields a full set for a one-collider case", () => {
 soft(
   "II. undeclared and absent is SILENT — a consumer with no skills of its own",
   () => {
-    const out = loadAt(fixture({ name: "plain-consumer" }, null));
+    const out = loadAt(fixture(null, null));
     assert.match(out, /^OK \d+$/, `expected a clean load, got: ${out}`);
     assert.equal(
       Number(out.slice(3)),
@@ -125,7 +128,7 @@ soft(
 );
 
 soft("II. the DEFAULT path is picked up without any declaration", () => {
-  const out = loadAt(fixture({ name: "defaulting-consumer" }, LOCAL_ONE));
+  const out = loadAt(fixture(null, LOCAL_ONE));
   assert.equal(
     out,
     `OK ${CASES.length + 1}`,
@@ -137,9 +140,7 @@ soft("II. the DEFAULT path is picked up without any declaration", () => {
 // is the same one `scriptsRoot()` draws: a path someone typed is a keystroke away from being wrong,
 // and substituting silence for it hides the typo behind a working run.
 soft("II. declared and missing THROWS, naming the declaration", () => {
-  const out = loadAt(
-    fixture({ paperlint: { triggerCases: "nope.mjs" } }, null),
-  );
+  const out = loadAt(fixture({ triggerCases: "nope.mjs" }, null));
   assert.match(out, /^THROW /, `a typoed declaration loaded quietly: ${out}`);
   assert.match(
     out,
@@ -150,7 +151,7 @@ soft("II. declared and missing THROWS, naming the declaration", () => {
 
 soft("II. a consumer may not redefine a case this package owns", () => {
   const clash = `export const CASES = [{ skill: "${CASES[0].skill}", why: "x", prompts: ["a","b","c","d"], collides: [] }];\n`;
-  const out = loadAt(fixture({ name: "clashing-consumer" }, clash));
+  const out = loadAt(fixture(null, clash));
   assert.match(out, /^THROW /, `a shadowing case was accepted: ${out}`);
   assert.match(
     out,

package/lib/skill-trigger-cases.mjs

@@ -334,8 +334,8 @@ const PACKAGE_CASES = [
 // out of the code and into a declaration. This is the fifth of those carriers and reads the same
 // key from the same file.
 //
-//     // <consumer>/package.json
-//     "paperlint": { "triggerCases": ".claude/lib/skill-trigger-cases.local.mjs" }
+//     // <consumer>/paperlint.json
+//     { "triggerCases": ".claude/lib/skill-trigger-cases.local.mjs" }
 //
 // The module it names must export `CASES` in the shape documented at the top of this file.
 //
@@ -347,8 +347,7 @@ const PACKAGE_CASES = [
 // ⚠️ A CONSUMER MAY NOT REDEFINE A PACKAGE CASE. Two tables answering "what should fire on this
 // prompt" is two truths; the override would live in the consumer and the original would keep
 // looking authoritative here. Throws, naming the skill.
-import { readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
   CONFIG_KEY,
@@ -360,14 +359,7 @@ const DEFAULT_LOCAL_CASES = ".claude/lib/skill-trigger-cases.local.mjs";
 
 async function consumerCases() {
   const root = consumerRoot();
-  let declared;
-  try {
-    declared = settingsOf(
-      JSON.parse(readFileSync(join(root, "package.json"), "utf8")),
-    )?.triggerCases;
-  } catch {
-    declared = undefined;
-  }
+  const declared = settingsOf(root)?.triggerCases;
   const rel = declared === undefined ? DEFAULT_LOCAL_CASES : declared;
   if (typeof rel !== "string" || rel.length === 0)
     throw new TypeError(
@@ -382,9 +374,9 @@ async function consumerCases() {
     throw new Error(
       `${CONFIG_KEY}: could not load the consumer's trigger cases from ${abs}` +
         (declared === undefined
-          ? ` (the default location; declare another in package.json under ` +
-            `"${CONFIG_KEY}": { "triggerCases": … } if the file lives elsewhere).`
-          : ` — it is declared in package.json as "triggerCases": ${JSON.stringify(declared)}.`) +
+          ? ` (the default location; declare another in paperlint.json as ` +
+            `{ "triggerCases": … } if the file lives elsewhere).`
+          : ` — it is declared in paperlint.json as "triggerCases": ${JSON.stringify(declared)}.`) +
         `
 A missing case set does not shrink the measurement, it CHANGES it: ` +
         `\`irrelevantFor()\` builds the false-positive set out of a case's colliders, so an ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",

package/scripts/eslint-report-guard.mjs

@@ -26,7 +26,7 @@ import { readFileSync } from "node:fs";
 export function guard(
   reportPath,
   eslintRc,
-  { paths = ".", config = "eslint.config.mjs" } = {},
+  { paths = ".", config = "paperlint.json" } = {},
 ) {
   const lines = [];
   let res;

package/scripts/harness-api.frozen.json

@@ -3,15 +3,12 @@
   "why": "A *.harness.* file tests the agent surface and imports runHook, runHarnessTest or runEval from vigiles. Plain unit tests are *.test.ts, run by vitest. These are the harness files that existed on main on 2026-09-25 and import none of the three. The list only shrinks: rename a file to *.test.ts (issue #77), or make it a real harness, then delete its entry. Checked by scripts/harness-api.test.ts, part of npm test.",
   "harnesses": [
     "action.harness.mjs",
-    "eslint-rules/doc-fields.harness.mjs",
     "eslint-rules/install-path-literals.harness.mjs",
     "eslint-rules/latex-language.harness.mjs",
     "eslint-rules/paper-research-question.harness.mjs",
     "eslint-rules/paper-stages.harness.mjs",
-    "eslint-rules/paper-typography.harness.mjs",
     "eslint-rules/papers.harness.mjs",
     "eslint-rules/pdf-last-page-balance.harness.mjs",
-    "eslint-rules/review-findings-cause.harness.mjs",
     "eslint-rules/temp-root-realpath.harness.mjs",
     "eslint-rules/tex-build.harness.mjs",
     "fixtures/real-markdown-paper/real-markdown-paper.harness.mjs",

package/scripts/mutation-batteries.frozen.json

@@ -5,9 +5,6 @@
     "action.mutations.mjs": {
       "cases": 6
     },
-    "eslint-rules/doc-fields.mutations.mjs": {
-      "cases": 6
-    },
     "eslint-rules/install-path-literals.mutations.mjs": {
       "cases": 3
     },
@@ -18,17 +15,11 @@
       "cases": 6
     },
     "eslint-rules/paper-stages.mutations.mjs": {
-      "cases": 9
-    },
-    "eslint-rules/paper-typography.mutations.mjs": {
-      "cases": 6
+      "cases": 4
     },
     "eslint-rules/papers.mutations.mjs": {
       "cases": 10
     },
-    "eslint-rules/review-findings-cause.mutations.mjs": {
-      "cases": 4
-    },
     "eslint-rules/temp-root-realpath.mutations.mjs": {
       "cases": 5
     },
@@ -36,7 +27,7 @@
       "cases": 21
     },
     "fixtures/real-markdown-paper/real-markdown-paper.mutations.mjs": {
-      "cases": 4
+      "cases": 3
     },
     "hooks/hooks.mutations.mjs": {
       "cases": 23
@@ -96,13 +87,13 @@
       "cases": 11
     },
     "src/cli.mutations.mjs": {
-      "cases": 26
+      "cases": 25
     },
     "src/doctor.mutations.mjs": {
       "cases": 10
     },
     "src/hooks-settings.mutations.mjs": {
-      "cases": 7
+      "cases": 6
     },
     "src/link-skills.mutations.mjs": {
       "cases": 6

package/skills/analyze-sibling-paper/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [WebSearch, WebFetch, Read, Write, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:19d00fe70002d3fa compiled from skills/analyze-sibling-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:f528cbe9e892d6d0 compiled from skills/analyze-sibling-paper/SKILL.md.spec.ts -->
 
 # analyze-sibling-paper — settle "isn't this just X?" before a reviewer does
 
@@ -44,9 +44,9 @@ far below the cost of a "novelty concern" reject.
    abstract → intro → method → claims (as much as is accessible). An abstract hides exactly the overlap
    that matters. Try the fetch routes in order — `arxiv.org/abs/<id>` for metadata, `arxiv.org/html/<id>v1`,
    `ar5iv.labs.arxiv.org/html/<id>`, then the PDF — and **a 403/404 on one route is not "inaccessible"**;
-   switch channel before concluding. **Record what you actually read** in the card as a
-   `**Read:**` line naming the sections you covered and the ones you could not — an abstract-only
-   verdict is PROVISIONAL and must say so in that same line.
+   switch channel before concluding. **Record what you actually read** in the card's frontmatter as
+   `read: full | abstract | none`, and name in a `**Read:**` line the sections you covered and the
+   ones you could not — an abstract-only verdict is PROVISIONAL and must say so.
    🔴 **Verify the abstract's numbers against the body.** They disagree more often than you would expect,
    and a disagreement is itself a finding worth recording.
 
@@ -87,17 +87,21 @@ far below the cost of a "novelty concern" reject.
 
 ## Required shape of the saved card — two sections are machine-checked
 
-The card is not free-form. Two of its parts are checked by `.claude/hooks/paper-lint.mjs`
-(`checkSiblingCards`) and a card missing either is reported as an unfinished analysis:
+The card is not free-form:
 
-- **`**Read:**`** — one line naming what of the full text you actually read and what you could
-  not. This exists because "I read the paper" is the single easiest thing to skip while producing a
-  card that looks complete.
+- **`read:` in the frontmatter** — `full`, `abstract` or `none`: how much of the full text you
+  actually read. `paperlint lint` checks it (`sibling/frontmatter`, a warning on a card without it).
+  It exists because "I read the paper" is the single easiest thing to skip while producing a card that
+  looks complete. The `**Read:**` line under it names which sections.
 - **`## Sibling's References`** — their bibliography mined and diffed against yours (step 2), with the
   MUST CITE / SHOULD CONSIDER / NOT RELEVANT verdicts.
 
-Enforced only for cards dated on or after 2026-07-29; older cards get one summary nudge instead of
-burying every other finding. Frontmatter needs `title`, `created`, `tags` like any note.
+```yaml
+---
+title: "Smith et al. 2025 — <title>"
+read: abstract # full | abstract | none
+---
+```
 
 ## Save + surface — COLOCATED with the paper (mandatory — do not leave it in context)
 Each paper's competitive landscape lives **with that paper**, not in a shared research folder: write the
@@ -136,7 +140,7 @@ would have overwritten one another.
 
 ## Rules
 - **Read the paper, not the abstract.** An abstract-only "delta" is not a verdict — and the card must
-  say, in its `**Read:**` line, which parts you actually read.
+  say so: `read: abstract` in its frontmatter, and which parts in its `**Read:**` line.
 - **Mine their references.** A sibling analysis that never opened the sibling's bibliography is half done;
   the scoop you missed is more likely to be in their reference list than in their results.
 - **Classify by contribution type** before judging overlap — it's the difference between a shared concept and a collision.

package/skills/analyze-sibling-paper/SKILL.md.spec.ts

@@ -59,9 +59,9 @@ far below the cost of a "novelty concern" reject.
    abstract → intro → method → claims (as much as is accessible). An abstract hides exactly the overlap
    that matters. Try the fetch routes in order — \`arxiv.org/abs/<id>\` for metadata, \`arxiv.org/html/<id>v1\`,
    \`ar5iv.labs.arxiv.org/html/<id>\`, then the PDF — and **a 403/404 on one route is not "inaccessible"**;
-   switch channel before concluding. **Record what you actually read** in the card as a
-   \`**Read:**\` line naming the sections you covered and the ones you could not — an abstract-only
-   verdict is PROVISIONAL and must say so in that same line.
+   switch channel before concluding. **Record what you actually read** in the card's frontmatter as
+   \`read: full | abstract | none\`, and name in a \`**Read:**\` line the sections you covered and the
+   ones you could not — an abstract-only verdict is PROVISIONAL and must say so.
    🔴 **Verify the abstract's numbers against the body.** They disagree more often than you would expect,
    and a disagreement is itself a finding worth recording.
 
@@ -102,17 +102,21 @@ far below the cost of a "novelty concern" reject.
 
 ## Required shape of the saved card — two sections are machine-checked
 
-The card is not free-form. Two of its parts are checked by \`.claude/hooks/paper-lint.mjs\`
-(\`checkSiblingCards\`) and a card missing either is reported as an unfinished analysis:
+The card is not free-form:
 
-- **\`**Read:**\`** — one line naming what of the full text you actually read and what you could
-  not. This exists because "I read the paper" is the single easiest thing to skip while producing a
-  card that looks complete.
+- **\`read:\` in the frontmatter** — \`full\`, \`abstract\` or \`none\`: how much of the full text you
+  actually read. \`paperlint lint\` checks it (\`sibling/frontmatter\`, a warning on a card without it).
+  It exists because "I read the paper" is the single easiest thing to skip while producing a card that
+  looks complete. The \`**Read:**\` line under it names which sections.
 - **\`## Sibling's References\`** — their bibliography mined and diffed against yours (step 2), with the
   MUST CITE / SHOULD CONSIDER / NOT RELEVANT verdicts.
 
-Enforced only for cards dated on or after 2026-07-29; older cards get one summary nudge instead of
-burying every other finding. Frontmatter needs \`title\`, \`created\`, \`tags\` like any note.
+\`\`\`yaml
+---
+title: "Smith et al. 2025 — <title>"
+read: abstract # full | abstract | none
+---
+\`\`\`
 
 ## Save + surface — COLOCATED with the paper (mandatory — do not leave it in context)
 Each paper's competitive landscape lives **with that paper**, not in a shared research folder: write the
@@ -151,7 +155,7 @@ would have overwritten one another.
 
 ## Rules
 - **Read the paper, not the abstract.** An abstract-only "delta" is not a verdict — and the card must
-  say, in its \`**Read:**\` line, which parts you actually read.
+  say so: \`read: abstract\` in its frontmatter, and which parts in its \`**Read:**\` line.
 - **Mine their references.** A sibling analysis that never opened the sibling's bibliography is half done;
   the scoop you missed is more likely to be in their reference list than in their results.
 - **Classify by contribution type** before judging overlap — it's the difference between a shared concept and a collision.

package/skills/cold-read-diff/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [Bash, Read, Agent]
 ---
 
-<!-- vigiles:sha256:f3c36e3e56bbd3cd compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:596fbd7e2eb85252 compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
 
 # cold-read-diff — the reader who cannot fake understanding
 
@@ -101,6 +101,25 @@ Two more things the same run proved:
 comments, and hand the reader continuous prose. The findings that survive that are worth the run; the
 ones that do not are noise, and noise is how this check gets muted.
 
+## The report's frontmatter — the findings, as records
+
+The report opens with YAML frontmatter that lists what it found, one record per finding.
+`paperlint lint` validates it (`review/frontmatter`): an **open** finding must name the
+pipeline `cause` that let it through — fix that, and the text edit falls out of running the
+fixed tool.
+
+```yaml
+---
+findings:
+  - id: 1
+    status: open            # open | fixed | wontfix
+    cause: missing-skill    # skill-defect | missing-skill | hook | rule — required when open
+    title: "§3 opens on a term the reader has not met"
+  - id: 2
+    status: fixed
+---
+```
+
 ## Record the verdict
 
 🔴 LAST step, once the deliverable exists:

package/skills/cold-read-diff/SKILL.md.spec.ts

@@ -106,6 +106,25 @@ Two more things the same run proved:
 comments, and hand the reader continuous prose. The findings that survive that are worth the run; the
 ones that do not are noise, and noise is how this check gets muted.
 
+## The report's frontmatter — the findings, as records
+
+The report opens with YAML frontmatter that lists what it found, one record per finding.
+\`paperlint lint\` validates it (\`review/frontmatter\`): an **open** finding must name the
+pipeline \`cause\` that let it through — fix that, and the text edit falls out of running the
+fixed tool.
+
+\`\`\`yaml
+---
+findings:
+  - id: 1
+    status: open            # open | fixed | wontfix
+    cause: missing-skill    # skill-defect | missing-skill | hook | rule — required when open
+    title: "§3 opens on a term the reader has not met"
+  - id: 2
+    status: fixed
+---
+\`\`\`
+
 ## Record the verdict
 
 🔴 LAST step, once the deliverable exists: