paperlint 2.0.0

package/lib/trigger-ledger.mjs

@@ -0,0 +1,215 @@
+/**
+ * trigger-ledger.mjs — "this description was measured, here is when and with what result".
+ *
+ * WHY. Trigger evals cost money and are therefore not in CI ("Not CI. Run it deliberately" —
+ * that is what every `*.eval.mjs` says). The consequence, measured 2026-08-28: recall is a
+ * quantity obtained ONCE, not one that is maintained. Let anyone reword a `description`
+ * tomorrow — nobody will ever catch the firing regression, because there is nothing and
+ * nobody to catch it with.
+ *
+ * 🔴 WHY THE READY-MADE `skillHash()` WAS NOT TAKEN. It hashes the WHOLE skill directory
+ * (`.md`, `.mjs`, `.sh`, `.py`, `.ts`). EXACTLY ONE FIELD affects the model's choice of a
+ * skill — `description`: the eval kit sets `stubSkillBodies: true` with the comment
+ * "selection is decided by frontmatter; don't run the body". Had we taken the whole
+ * directory, the gate would redden at a typo in the body and at every new harness, that is,
+ * almost always. A check that is red for no reason lives one day, gets silenced, and the hole
+ * comes back, this time unnoticed. So the field is what gets hashed.
+ *
+ * ⚠️ WHAT THIS LEDGER DOES NOT KNOW. It does not know that a description got BETTER or WORSE
+ * — only that it is DIFFERENT. The verdict still comes from the paid run; all that is
+ * recorded here is that the run relates to this text and not to some earlier one.
+ *
+ * vigiles:local-by-design — the generic version ("coverage must cover the eval tier, not only
+ * the harness") belongs to the product: `.vigiles/coverage.json` is written by the CLI from a
+ * completed run, while `*.eval.mjs` are started as `node <file>` past the CLI, so there are
+ * ZERO evals there against 50 harness records (measured 2026-08-28). What stays here is ours:
+ * WHICH of our descriptions were measured and with what number.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  consumerRoot,
+  installedSkills,
+} from "../skills/paper-pipeline/scripts/consumer.mjs";
+
+// The CONSUMER's root, not this file's grandparent — see the same note in `skill-corpus.mjs`.
+// The ledger itself (`.claude/skill-trigger-runs.json`) is the consumer's DATA and stays there;
+// only the code that reads and writes it lives here.
+export const ROOT = consumerRoot();
+export const LEDGER = join(ROOT, ".claude", "skill-trigger-runs.json");
+const SKILLS = join(ROOT, ".claude", "skills");
+
+// THE DEBT BASELINE WAS DELETED 2026-08-28. A ratchet with 24 names "never measured once"
+// stood here — and it was a way of not doing the work. The corpus owner: "a ratchet again, fuck…
+// let's just fix it properly". All 24 were run (~40 min of machine time, $0 metered —
+// subscription), the debt is paid off, the check became an ordinary gate. Its meaning changed
+// with that: it was "the debt does not grow", it became "a measurement must relate to the
+// current description". The same transition as the markdown-regex debt, and for the same
+// reason — paying it off is cheaper than servicing it.
+
+/** The exact text of `description:` from the frontmatter. Empty string if the field is absent. */
+export function descriptionOf(skill) {
+  const p = join(SKILLS, skill, "SKILL.md");
+  if (!existsSync(p)) return "";
+  const src = readFileSync(p, "utf8");
+  const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return "";
+  // description may be multi-line, up to the next top-level key
+  const m = fm[1].match(
+    /^description:[ \t]*([\s\S]*?)(?=\r?\n[a-zA-Z_-]+:|$)/m,
+  );
+  return m ? m[1].trim() : "";
+}
+
+export const hashOf = (s) =>
+  createHash("sha256").update(s).digest("hex").slice(0, 16);
+
+/**
+ * A hash of the WHOLE set of descriptions — "against whom it was measured".
+ *
+ * 🔴 Why a second mark (the corpus owner's question, 2026-08-28). A trigger eval measures the
+ * model's CHOICE out of all installed descriptions — the kit says exactly that: "whole-harness by
+ * construction… an isolated measurement OVERSTATES recall and UNDERSTATES false positives". So my
+ * recall can go stale from an edit to a NEIGHBOUR'S DESCRIPTION: it starts winning my prompts
+ * while my own description does not change by a single character. A hash of my own field is not
+ * enough for that.
+ *
+ * ⚠️ But hashing the corpus STRICTLY is not allowed either: one edit to any description would
+ * void every record at once, and the check would again be always-red. Hence the different
+ * loudness:
+ * my own description changed → THE MEASUREMENT IS INVALID (an error);
+ * the set of competitors changed → the measurement WEAKENED (a note in the ledger, no shouting).
+ */
+export function corpusHash() {
+  const names = installedSkills(SKILLS);
+  return hashOf(
+    names.map((n) => n + "\u0000" + descriptionOf(n)).join("\u0001"),
+  );
+}
+
+export const readLedger = () =>
+  existsSync(LEDGER)
+    ? JSON.parse(readFileSync(LEDGER, "utf8"))
+    : { v: 1, runs: {} };
+
+/** Record a measurement that happened. Called by the kit AFTER the run, not before. */
+export function recordRun(skill, { recall, precision, model, trials }) {
+  const l = readLedger();
+  l.runs[skill] = {
+    description_sha: hashOf(descriptionOf(skill)),
+    corpus_sha: corpusHash(),
+    measured_at: new Date().toISOString().slice(0, 10),
+    recall,
+    precision,
+    model,
+    trials,
+  };
+  writeFileSync(LEDGER, JSON.stringify(l, null, 2) + "\n");
+  return l.runs[skill];
+}
+
+/**
+ * Skills that HAVE an `*.eval.mjs` but whose measurement does not relate to the current
+ * description. Returns [{skill, reason}]. `reason` — 'never' or 'changed'.
+ */
+export function staleSkills(skillsWithEval) {
+  const l = readLedger();
+  const out = [];
+  for (const s of skillsWithEval) {
+    const rec = l.runs[s];
+    if (!rec) {
+      out.push({ skill: s, reason: "never" });
+      continue;
+    }
+    if (rec.description_sha !== hashOf(descriptionOf(s))) {
+      out.push({ skill: s, reason: "changed", measured_at: rec.measured_at });
+      continue;
+    }
+    // The skill's own description is the same but the competitors differ — the measurement
+    // weakened, it did not die.
+    if (rec.corpus_sha && rec.corpus_sha !== corpusHash())
+      out.push({
+        skill: s,
+        reason: "corpus",
+        measured_at: rec.measured_at,
+        soft: true,
+      });
+  }
+  return out;
+}
+
+// ── CLI: `node .claude/lib/trigger-ledger.mjs --check` ────────────────────────────
+// Cheap: no model, no network — only reading frontmatter and comparing hashes.
+// That is exactly why this can be kept in CI, unlike the evals themselves.
+if (process.argv[1] && process.argv[1].endsWith("trigger-ledger.mjs")) {
+  const withEval = installedSkills(SKILLS).filter((d) =>
+    existsSync(join(SKILLS, d, `${d}.eval.mjs`)),
+  );
+  // A RATCHET, not a gate. Measured 2026-08-28 on a clean tree: 24 findings "never measured
+  // once" — for the paper skills firing had been measured earlier, just not into this ledger,
+  // which is five minutes old. A check with 24 red lines on its first day does not get read, it
+  // gets silenced: that is exactly how the markdown-regex debt already died in this repo, and
+  // there it was turned into a ratchet.
+  //
+  // So: "the description changed after the measurement" — LOUD ALWAYS, that is the very
+  // regression all of this was started for. "Never measured once" — loud only for skills that
+  // are not in the debt baseline, that is, for NEW ones. The debt does not grow silently, but it
+  // does not shout on every run either.
+  const all = staleSkills(withEval);
+  const soft = all.filter((x) => x.soft);
+  const stale = all.filter((x) => !x.soft);
+  // ONE line, not one line per skill. Measured 2026-08-28: an edit to ONE description changes
+  // the corpus hash as a whole, and per-line output produced 27 notes at once. Twenty-seven
+  // informational lines per edit is noise, and noise gets silenced; and then the hard half stops
+  // being read along with it.
+  // Three names + a counter, not only a counter and not 27 lines. A bare counter cannot be
+  // checked and gives nothing to start a re-measurement from; one line per skill is 27 lines of
+  // noise per edit (measured 2026-08-28). The assertion "the note is addressed" in the harness
+  // requires exactly the names — and it was RED from 2026-08-28 to 2026-08-31, because the code
+  // printed only the counter: the harness was written, declared working, and not run.
+  if (soft.length) {
+    const names = soft
+      .slice(0, 3)
+      .map((x) => x.skill)
+      .join(", ");
+    console.log(
+      `ℹ️ the set of competing descriptions changed after the last measurement — ` +
+        `for ${soft.length} skill(s) recall may have shifted without their own description being ` +
+        `touched (${names}${soft.length > 3 ? ` and ${soft.length - 3} more` : ""}). ` +
+        `Not an error: re-measure when convenient.`,
+    );
+  }
+  // 🔴 THE DENOMINATOR IS MANDATORY. The line "✓ current for 27" reads as "27 skills are fine",
+  // whereas the true statement is "27 of 50 fall under this check at all": a skill without its
+  // own .eval.mjs is inexpressible for this gate, there is nothing to re-measure for it.
+  // Measured 2026-08-31: 50 skills on disk, 27 with an eval, 23 without. That day I changed the
+  // description of telegram-channel-audit (no eval), the gate printed green, and that looked
+  // like "the change was verified". A counter that does not name what it ignores lies — the
+  // CLAUDE.md rule §"A counter that counts what it IGNORES".
+  const total = installedSkills(SKILLS).length;
+  const noEval = total - withEval.length;
+  if (!stale.length) {
+    console.log(
+      `✓ trigger measurements are current for ${withEval.length} skill(s) of ${total}` +
+        (noEval
+          ? ` — the other ${noEval} have NO .eval.mjs of their own, they are outside this ` +
+            `check by construction (nothing to measure, not "fine")`
+          : ""),
+    );
+    process.exit(0);
+  }
+  for (const s of stale) {
+    console.error(
+      s.reason === "never"
+        ? `✗ ${s.skill}: ${s.skill}.eval.mjs exists, but a firing measurement NEVER happened`
+        : `✗ ${s.skill}: description changed after the ${s.measured_at} measurement — recall relates to the former text`,
+    );
+  }
+  console.error(
+    `\nRun it: node .claude/skills/<skill>/<skill>.eval.mjs` +
+      `\nThis is the paid tier (a real model), so CI does not run it — it only requires that a run ` +
+      `exists and relates to the current description.`,
+  );
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "paperlint",
+  "version": "2.0.0",
+  "description": "Machine-checkable gates for a research paper kept in git: ESLint rules over .tex/.md paper sources, plus the skills and hooks that drive each stage.",
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "node scripts/exclusive.mjs vitest run && node scripts/exclusive.mjs vigiles test --min=1",
+    "lint": "node scripts/exclusive.mjs eslint .",
+    "check": "node scripts/check.mjs",
+    "test:e2e": "node scripts/exclusive.mjs node test/e2e/install.mjs && node scripts/exclusive.mjs node test/e2e/build.mjs",
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check ."
+  },
+  "dependencies": {
+    "@eslint/markdown": "^8.0.3",
+    "@eslint/plugin-kit": "^0.7.2",
+    "@unified-latex/unified-latex-util-parse": "^1.8.4",
+    "ajv": "^6.12.6",
+    "eslint": "^10.9.1",
+    "js-yaml": "^4.1.0",
+    "markdown-it": "^14.3.0",
+    "ts-essentials": "^10.2.1",
+    "typescript": "^5.9.3",
+    "unpdf": "^1.8.1",
+    "vigiles": "^31.0.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@retorquere/bibtex-parser": "^10.0.1",
+    "@semantic-release/commit-analyzer": "13.0.1",
+    "@semantic-release/release-notes-generator": "14.1.1",
+    "@types/node": "^26.6.1",
+    "conventional-changelog-conventionalcommits": "9.3.1",
+    "eslint-plugin-boundaries": "^7.2.0",
+    "eslint-plugin-n": "^18.3.0",
+    "prettier": "^3.8.1",
+    "semantic-release": "25.0.9",
+    "typescript-eslint": "^8.70.1",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "@retorquere/bibtex-parser": "^10.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@retorquere/bibtex-parser": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zernie/research-paper-pipeline.git"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "latex",
+    "tex",
+    "research",
+    "paper",
+    "academic",
+    "linter",
+    "claude-code"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "bin": {
+    "paperlint": "bin/rpp.mjs"
+  },
+  "files": [
+    ".github",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
+    "action.harness.mjs",
+    "action.mutations.mjs",
+    "action.yml",
+    "bin",
+    "dist",
+    "docs",
+    "eslint-rules",
+    "eslint.config.mjs",
+    "fixtures",
+    "!fixtures/real-markdown-paper",
+    "fixtures/real-markdown-paper/baseline.*",
+    "hooks",
+    "lib",
+    "plugin",
+    "scripts",
+    "skills",
+    "src",
+    "templates",
+    "tsconfig.json"
+  ]
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "research-paper-pipeline",
+  "version": "0.1.0",
+  "description": "Wiring for the research-paper-pipeline hooks. The code itself comes from the npm package installed in the consumer's project — this plugin carries no code and no dependencies on purpose.",
+  "author": { "name": "zernie" },
+  "repository": "https://github.com/zernie/research-paper-pipeline",
+  "keywords": ["latex", "academic-writing", "eslint", "linting", "ci"]
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/rpp.mjs\" hook paper-edit-guard"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/rpp.mjs\" hook paper-skills-nudge"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/rpp.mjs\" hook paper-status-gates"
+          }
+        ]
+      }
+    ]
+  }
+}

package/scripts/check.harness.mjs

@@ -0,0 +1,177 @@
+/**
+ * Both halves for `npm run check` — and the half that matters is not "does it run the gates",
+ * it is "does its list still describe the CI it claims to mirror".
+ *
+ * 🔴 A HANDWRITTEN LIST OF GATES IS A FOSSIL THE DAY AFTER IT IS WRITTEN. That is measured, not
+ * feared: on 2026-09-19 eleven scripts existed with no aggregate, a subset was run from memory,
+ * and a suite-breaking change was pushed. Writing the subset down in a doc would have produced
+ * the same outcome one release later — the list would simply have been wrong instead of absent.
+ *
+ * So the assertions below do not check that `check.mjs` contains the right strings. They pull
+ * the job names OUT OF `.github/workflows/ci.yml` and require every one to be accounted for.
+ * Add a job to CI and this goes red the same day, naming the job nobody covered.
+ *
+ * ⚠️ Assertions at the TOP LEVEL: `vigiles test` imports the file and counts "did not throw"
+ * as a pass.
+ */
+import assert from "node:assert/strict";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { load } from "js-yaml";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = dirname(HERE);
+
+const { GATES, NOT_COVERED, outcome, SKIP_EXIT, commandOf } =
+  await import("./check.mjs");
+
+let n = 0;
+const check = (label, cond) => {
+  n++;
+  assert.ok(cond, label);
+};
+
+// ── the workflow is the ORACLE, not a copy of it ───────────────────────────────────────────
+// A declared skip is a THIRD outcome. Folding it into "pass" printed "all gates passed" on a
+// machine where the e2e never ran (Codex review on #45); folding it into "fail" would make the
+// command red for anyone without pnpm or TeX, and it would be ignored.
+check("exit 0 is a pass", outcome(0) === "pass");
+check(
+  `exit ${SKIP_EXIT} is a skip — neither a pass nor a failure`,
+  outcome(SKIP_EXIT) === "skip",
+);
+check("the skip code is the one vigiles' runner uses (77)", SKIP_EXIT === 77);
+check(
+  "any other nonzero exit is a failure",
+  outcome(1) === "fail" && outcome(2) === "fail",
+);
+check(
+  "a process killed by a signal (status null) is a failure, not a skip",
+  outcome(null) === "fail",
+);
+
+// Every workflow, not just ci.yml: a harness reading one file would stop seeing a job added to
+// another without a sound. (macOS lived in platform.yml from 2026-09-23 to 2026-09-24; it is now
+// a cell of ci.yml's build-e2e matrix.)
+const WF_DIR = join(ROOT, ".github", "workflows");
+const workflows = Object.fromEntries(
+  readdirSync(WF_DIR)
+    .filter((f) => f.endsWith(".yml"))
+    .map((f) => [f, load(readFileSync(join(WF_DIR, f), "utf-8"))]),
+);
+const ciJobs = Object.values(workflows).flatMap((wf) =>
+  Object.keys(wf.jobs ?? {}),
+);
+check(
+  "the workflows parse and declare jobs — without this every assertion below is vacuous",
+  ciJobs.length > 0 && "ci.yml" in workflows,
+);
+
+// ── macOS: a cell of the TeX job, on every push ─────────────────────────────────────────
+// install-tl-unx must work there, and issue #9 appears there alone. The trigger used to be a
+// separate once-per-PR workflow; the repository is public, so the minutes are free.
+const prTypes = (wf) => wf.on?.pull_request?.types ?? [];
+const buildOs =
+  workflows["ci.yml"]?.jobs?.["build-e2e"]?.strategy?.matrix?.os ?? [];
+check(
+  "build-e2e runs on Linux AND macOS — one job, two operating systems",
+  buildOs.includes("ubuntu-latest") && buildOs.includes("macos-latest"),
+  JSON.stringify(buildOs),
+);
+check(
+  "no workflow listens to `labeled` — a label trigger re-fires on every push and can pass by skipping",
+  Object.values(workflows).every((wf) => !prTypes(wf).includes("labeled")),
+);
+check(
+  "ci.yml listens to ready_for_review — otherwise marking a draft ready runs NOTHING",
+  prTypes(workflows["ci.yml"]).includes("ready_for_review"),
+);
+
+// ── HALF ONE: every CI job is accounted for ────────────────────────────────────────────────
+const covered = new Set(GATES.map((g) => g.job).filter(Boolean));
+for (const job of ciJobs) {
+  check(
+    `CI job «${job}» is either reproduced by a gate or named in NOT_COVERED with a reason — ` +
+      `an unexplained gap is indistinguishable from an oversight`,
+    covered.has(job) || typeof NOT_COVERED[job] === "string",
+  );
+}
+
+// ── HALF TWO: the list names nothing that does not exist ───────────────────────────────────
+// A dead job name is worse than a missing one: it reads as coverage and delivers nothing.
+for (const g of GATES) {
+  if (g.job === null) continue;
+  check(
+    `gate «${g.name}» names a job that really exists in a workflow (${g.job})`,
+    ciJobs.includes(g.job),
+  );
+}
+for (const job of Object.keys(NOT_COVERED)) {
+  check(
+    `NOT_COVERED names a job that really exists in a workflow (${job})`,
+    ciJobs.includes(job),
+  );
+}
+
+// ── HALF THREE: every gate is runnable ─────────────────────────────────────────────────────
+// A gate whose script or file was renamed fails at the moment someone runs it — which is
+// exactly the moment they are trusting it. Catch it here instead.
+const scripts =
+  JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8")).scripts ?? {};
+for (const g of GATES) {
+  check(
+    `gate «${g.name}» says how to run it in exactly one way (script or run)`,
+    Boolean(g.script) !== Array.isArray(g.run),
+  );
+  if (g.script) {
+    check(
+      `gate «${g.name}» maps to a script that exists (npm run ${g.script})`,
+      typeof scripts[g.script] === "string",
+    );
+    continue;
+  }
+  // A `run` gate names files and programs directly. Every file it names must be on disk, and
+  // every program other than `node` must be installed in node_modules/.bin.
+  const argv = commandOf(g);
+  const files = argv.filter((a) => /\.m?js$/.test(a));
+  const programs = argv.filter(
+    (a, i) => i === 0 || argv[i - 1] === "scripts/exclusive.mjs",
+  );
+  // Guards: a gate runs SOMETHING — a script of ours, or an installed program such as `tsc`.
+  check(
+    `gate «${g.name}» runs files that exist (${files.join(", ")})`,
+    (files.length > 0 || programs.some((p) => p !== "node")) &&
+      files.every((f) => existsSync(join(ROOT, f))),
+  );
+  check(
+    `gate «${g.name}» runs programs that are installed (${programs.join(", ")})`,
+    programs.every(
+      (p) => p === "node" || existsSync(join(ROOT, "node_modules", ".bin", p)),
+    ),
+  );
+}
+check(
+  "`check` itself is wired as a script, or nobody can run any of this",
+  typeof scripts.check === "string",
+);
+
+// ── HALF FOUR: a local-only gate must say WHY ──────────────────────────────────────────────
+// Without this, `job: null` becomes the quiet way to drop something out of CI.
+for (const g of GATES.filter((g) => g.job === null)) {
+  check(
+    `local-only gate «${g.name}» carries a reason`,
+    typeof g.reason === "string" && g.reason.length > 20,
+  );
+}
+
+// ── and the tail is not optional ───────────────────────────────────────────────────────────
+check(
+  "NOT_COVERED is non-empty — if it ever is, either CI shrank or someone silenced the tail",
+  Object.keys(NOT_COVERED).length > 0,
+);
+
+console.log(
+  `✓ ${String(n)} assertions passed — npm run check: ${GATES.length} gates, ` +
+    `${ciJobs.length} CI job(s) all accounted for`,
+);