paperlint 13.0.2 → 13.1.0

package/eslint.config.mjs

@@ -687,7 +687,7 @@ export default [
    * not itself.
    *
    * Measurement on the first run: 15 files with dead imports (`resolve`, `pathToFileURL`) and
-   * orphaned constants — remnants of a move from `mine`, where those names were needed. All
+   * orphaned constants — remnants of a move from the downstream repository this package was extracted from, where those names were needed. All
    * cleaned to zero in the same commit, so the rule opens as a GATE on a clean corpus,
    * not as debt to be silenced.
    *

package/hooks/hooks.harness.ts

@@ -25,6 +25,7 @@
 import { runHook, type HookInput, type HookRunResult } from "vigiles";
 import { checkHookImports } from "vigiles/hook";
 import {
+  existsSync,
   mkdtempSync,
   mkdirSync,
   readdirSync,
@@ -105,6 +106,12 @@ const onEdit = (file_path: string): HookInput => ({
   tool_input: { file_path },
   tool_response: {},
 });
+const onRead = (file_path: string): HookInput => ({
+  hook_event_name: "PostToolUse",
+  tool_name: "Read",
+  tool_input: { file_path },
+  tool_response: {},
+});
 const STOP: HookInput = {
   hook_event_name: "Stop",
   tool_name: "",
@@ -459,33 +466,64 @@ try {
   // ═══════════════════════════════════════════════════════════════════════════
   {
     const dir = fixture({ [PAPERS_DIR_FIELD]: "docs/papers" });
-    const lands = (label: string, p: string) => {
-      const r = at(dir, "paper-skills-nudge", onEdit(p));
+    const shipped = readdirSync(join(ROOT, "skills")).filter((d) =>
+      existsSync(join(ROOT, "skills", d, "SKILL.md")),
+    );
+    const lands = (label: string, input: HookInput) => {
+      const r = at(dir, "paper-skills-nudge", input);
       const ctx = injected(r);
       check(
         `nudge LANDS on ${label} (${String(r.stdout.length)}b stdout)`,
         ctx.length > 0,
       );
-      check(
-        `nudge's text on ${label} is the checklist`,
-        /Pre-submit checklist/.test(ctx),
-      );
       check(`nudge on ${label} exits 0`, r.exitCode === 0);
+      return ctx;
     };
-    const silent = (label: string, p: string) => {
-      const r = at(dir, "paper-skills-nudge", onEdit(p));
+    const silent = (label: string, input: HookInput) => {
+      const r = at(dir, "paper-skills-nudge", input);
       check(
         `nudge SILENT on ${label} (${String(r.stdout.length)}b stdout, ${String(r.stderr.length)}b stderr)`,
         r.stdout.length === 0 && r.stderr.length === 0 && r.exitCode === 0,
       );
     };
-    lands("a relative paper.tex", "docs/papers/alpha/paper.tex");
-    lands("a .tex", "docs/papers/alpha/paper.tex");
+    const first = lands(
+      "a relative paper.tex",
+      onEdit("docs/papers/alpha/paper.tex"),
+    );
+    // The list is read from the package's skills folder, not typed into the hook: every shipped
+    // skill appears, one bullet each, so a new skill reaches the nudge without an edit here.
+    check(
+      `nudge lists every shipped skill (${String(shipped.length)} on disk)`,
+      shipped.every((name) => first.includes(`  • ${name} — `)) &&
+        (first.match(/^  • /gm) ?? []).length >= shipped.length,
+    );
+    check("nudge names the paper it fired for", first.includes('"alpha"'));
+    // Once per paper: the same paper again, in its ABSOLUTE spelling, stays quiet.
+    silent(
+      "the same paper again (absolute path)",
+      onEdit(join(dir, "docs/papers/alpha/notes.md")),
+    );
     // 🔴 THE ABSOLUTE SPELLING. The live harness sends absolute paths; a helper that only builds
     // relative ones let an anchored predecessor pass every test while being dead in production.
-    lands("an ABSOLUTE paper.tex", join(dir, "docs/papers/alpha/paper.tex"));
-    silent("a README under the papers root", "docs/papers/README.md");
-    silent("a file outside the papers root", "README.md");
+    lands(
+      "an ABSOLUTE path in another paper",
+      onEdit(join(dir, "docs/papers/beta/paper.tex")),
+    );
+    // Any file of a paper, not only its source: siblings, claims, data are where decisions start.
+    lands(
+      "a non-.tex file of a paper",
+      onEdit("docs/papers/gamma/siblings/novelty.json"),
+    );
+    // A Read is enough: the skills are worth knowing when the paper is opened, before anything is decided.
+    lands(
+      "a Read of a paper file",
+      onRead(join(dir, "docs/papers/delta/CLAIMS.md")),
+    );
+    silent(
+      "a README directly under the papers root",
+      onEdit("docs/papers/README.md"),
+    );
+    silent("a file outside the papers root", onEdit("README.md"));
     // The advisory's own asymmetry: it goes quiet where the gate refuses.
     {
       const broken = fixture(

package/hooks/paper-skills-nudge.hook.d.mts

@@ -0,0 +1,22 @@
+// Types for the exports `hooks/paper-skills-nudge.test.ts` imports from the hook. The hook ships as
+// plain .mjs (a compiled hook may import nothing but `vigiles/hook`), so without this file TypeScript
+// sees `any` and `tsc -p tsconfig.test.json` fails with TS7016 — the same reason
+// `paper-edit-guard.hook.d.mts` exists.
+
+/** One line per skill from the provider's tab-separated `name<TAB>description` output. */
+export declare const skillLines: (raw: string | undefined) => readonly string[];
+
+/** The paper a path belongs to, from every spelling of the path the event carries; null when none. */
+export declare const paperOf: (
+  paths: readonly (string | undefined)[],
+  root: string,
+) => string | null;
+
+/** The notice text for one paper and its skill lines. */
+export declare const message: (
+  paper: string,
+  lines: readonly string[],
+) => string;
+
+declare const hook: unknown;
+export default hook;

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

@@ -36,6 +36,8 @@ import {
   provide,
   notice,
   nothing,
+  record,
+  state,
 } from "vigiles/hook";
 
 /** The tool's name — the package this hook resolves its scripts through. */
@@ -96,28 +98,78 @@ const papersRoot = (rawConfig) => {
   return root;
 };
 
-/** A paper SOURCE — a `.tex`. Not every note or README. */
-const isPaperSource = (p) => p.endsWith(".tex");
+/**
+ * The shipped skills, one per line as name, a tab, and the description, read from the package's own
+ * skills folder (the consumer's node_modules copy; in this repository, its own folder). The list used
+ * to be typed into this file and drifted: a skill added to the package never reached the nudge.
+ * An empty result (no folder, no skills) leaves the list out and keeps the rest of the message.
+ */
+const READ_SKILLS =
+  `d="\${CLAUDE_PROJECT_DIR:-.}/node_modules/paperlint/skills"; [ -d "$d" ] || d="\${CLAUDE_PROJECT_DIR:-.}/skills"; ` +
+  `for f in "$d"/*/SKILL.md; do [ -f "$f" ] || continue; ` +
+  `awk 'NR==1 && $0!="---" {exit} NR>1 && $0=="---" {exit} ` +
+  `/^name: / {n=substr($0, 7)} /^description: / {d=substr($0, 14)} END {if (n!="") print n "\t" d}' "$f"; done`;
+
+/** One line per skill: its name and the description's first clause, at most 110 characters. */
+export const skillLines = (raw) =>
+  String(raw ?? "")
+    .split("\n")
+    .map((l) => l.split("\t"))
+    .filter(([name]) => /^[a-z0-9-]+$/.test(name))
+    .map(([name, desc = ""]) => {
+      const clause = desc
+        .replace(/^["']|["']$/g, "")
+        .replace(/\\"/g, '"')
+        .split(/ — |\. /)[0];
+      return `  • ${name} — ${clause.length > 110 ? `${clause.slice(0, 107)}...` : clause}`;
+    });
+
+/** A path or root in one spelling: no leading "./", no doubled or trailing separators. */
+const tidy = (p) =>
+  p
+    .replace(/^(\.\/+)+/, "")
+    .replace(/\/{2,}/g, "/")
+    .replace(/\/+$/, "");
+
+/**
+ * The paper a path belongs to: the first folder under the papers root, when the file sits inside one.
+ * A file directly in the root (its README) belongs to no paper and stays silent. The path comes in
+ * every spelling the event has (repo-relative and as sent), and the root in any spelling the config
+ * allows (with a leading dot-slash, doubled slashes, absolute); the first spelling under the root wins.
+ */
+export const paperOf = (paths, root) => {
+  const prefix = `${tidy(root)}/`;
+  const names = paths
+    .filter((p) => typeof p === "string")
+    .map(tidy)
+    .filter((p) => p.startsWith(prefix))
+    .map((p) => p.slice(prefix.length).split("/"))
+    .map((parts) => (parts.length >= 2 ? parts[0] : null));
+  return names.length ? names[0] : null;
+};
+
+/** How long one paper stays nudged. Touching a different paper speaks again at once. */
+const QUIET_FOR = "3h";
 
-const CHECKLIST = `📄 Editing a paper — drive it with the \`paper-pipeline\` skill, don't wing the review.
-  → Update <paper-dir>/PIPELINE-STATUS.md: mark the row for any stage you (re)ran, and read its
-    verdict line to see what's still ☐/◐/⚠ before submit.
-Pre-submit checklist (skills):
-  • verify-citations — every \\cite real; nearest-neighbor delta explicit
-  • study-accepted-papers — the venue's Accept→Strong levers
-  • analyze-sibling-paper — deep-read each close competitor; SAVE colocated in <paper-dir>/siblings/
-  • grade-paper-writing — BLIND ≥3-grader panel (absolute scale) + cold-read stall pass
-  • pc-panel-review / paper-adversarial-review — multi-axis scorecard + the "reads-like-slop" halo
-  • harden-paper — threat-model · ethics · page-fit · de-anon · ACTUALLY RUN the artifact clean
-RULES earned the hard way:
-  • After every aggressive rewrite/thinning pass → claim-preservation DIFF vs the pre-pass baseline
-  • Numbers overwhelming the reader? secondary numbers live in the artifact, not the paper
-  • bib inside \\begin{filecontents*}{refs.bib}? edit it THERE — refs.bib is overwritten on build
-  • Done + claim-clean + page-legal ships. Further churn breaks about as much as it fixes.`;
+export const message = (paper, lines) =>
+  `📄 Working on paper "${paper}". Before deciding a step yourself, check whether a skill owns it ` +
+  "(Skill tool) — a hand-written brief or a winged review is how pipeline stages get skipped.\n" +
+  "  → Update <paper-dir>/PIPELINE-STATUS.md: mark the row for any stage you (re)ran, and read its\n" +
+  "    verdict line to see what's still ☐/◐/⚠ before submit.\n" +
+  (lines.length
+    ? `The paper skills shipped with this package:\n${lines.join("\n")}\n`
+    : "") +
+  "RULES earned the hard way:\n" +
+  "  • After every aggressive rewrite/thinning pass → claim-preservation DIFF vs the pre-pass baseline\n" +
+  "  • Numbers overwhelming the reader? secondary numbers live in the artifact, not the paper\n" +
+  "  • bib inside \\begin{filecontents*}{refs.bib}? edit it THERE — refs.bib is overwritten on build\n" +
+  "  • Done + claim-clean + page-legal ships. Further churn breaks about as much as it fixes.";
 
 export default experimental_defineReact({
   on: "PostToolUse",
-  match: tools("Edit", "Write", "MultiEdit"),
+  // Read too: the moment a paper is opened is when its skills are worth knowing, before anything is
+  // decided — an edit-only trigger fires after the decision.
+  match: tools("Read", "Edit", "Write", "MultiEdit"),
   // 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.
@@ -126,12 +178,22 @@ export default experimental_defineReact({
   // 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("config", READ_CONFIG)],
+  needs: [
+    provide("config", READ_CONFIG),
+    provide("skills", READ_SKILLS),
+    state("paper-skills.shown"),
+  ],
   react: (e) => {
     const root = papersRoot(e.ctx.config);
-    if (root === null) return nothing();
-    return e.path.under([root]) && isPaperSource(e.path.raw)
-      ? notice(CHECKLIST)
-      : nothing();
+    if (root === null || !e.path.under([tidy(root)])) return nothing();
+    const paper = paperOf([e.path.rel, e.path.raw], root);
+    if (paper === null) return nothing();
+    const shown = e.ctx["paper-skills.shown"];
+    // Once per paper: the same paper again within QUIET_FOR stays silent; another paper speaks.
+    if (shown.value === paper && shown.fresherThan(QUIET_FOR)) return nothing();
+    return notice(
+      message(paper, skillLines(e.ctx.skills)),
+      record("paper-skills.shown", paper),
+    );
   },
 });

package/hooks/paper-skills-nudge.test.ts

@@ -1,5 +1,5 @@
 /**
- * paper-skills-nudge on the two declarations the hooks harness does not carry: none at all (the
+ * paper-skills-nudge on the declarations the hooks harness does not carry: none at all (the
  * default `papers/` root applies) and one that does not parse (silence — a nudge never blocks).
  */
 import assert from "node:assert/strict";
@@ -7,6 +7,7 @@ import { join } from "node:path";
 import { test } from "vitest";
 import { hookConsumer, onEdit, runShippedHook } from "../test/hook-consumer.ts";
 import { useTempDir } from "../test/support.ts";
+import { message, paperOf, skillLines } from "./paper-skills-nudge.hook.mjs";
 
 const root = useTempDir("paper-skills-nudge-");
 
@@ -33,12 +34,89 @@ test("a paperlint.json that does not parse: silent, exit 0", () => {
   assert.deepEqual([r.exitCode, r.stdout, r.stderr], [0, "", ""]);
 });
 
-test("an edit to a file of the paper other than its source: silent", () => {
-  const dir = hookConsumer(join(root, "not-a-source"));
+test("a file directly under the papers root belongs to no paper: silent", () => {
+  const dir = hookConsumer(join(root, "root-file"));
   const r = runShippedHook(
     "paper-skills-nudge",
-    onEdit("papers/alpha/notes.txt"),
+    onEdit("papers/README.md"),
     dir,
   );
   assert.deepEqual([r.exitCode, r.stdout, r.stderr], [0, "", ""]);
 });
+
+test("any file of a paper, not only its source: the checklist", () => {
+  const dir = hookConsumer(join(root, "any-file"));
+  const r = runShippedHook(
+    "paper-skills-nudge",
+    onEdit("papers/alpha/notes.txt"),
+    dir,
+  );
+  assert.equal(r.exitCode, 0);
+  assert.match(r.stdout, /Working on paper \\"alpha\\"/);
+});
+
+// ── the pure helpers, on the inputs the shipped run never sends ─────────────────────────────
+
+test("skillLines: a missing provider result is no skills, not a crash", () => {
+  assert.deepEqual(skillLines(undefined), []);
+});
+
+test("skillLines: a line that is not a skill name is dropped; a name without a description stays", () => {
+  assert.deepEqual(skillLines("Not A Name\tx\nbare-name"), [
+    "  • bare-name — ",
+  ]);
+});
+
+test("skillLines: a quoted description is unquoted and cut at its first clause, at most 110 characters", () => {
+  const long = "a".repeat(200);
+  assert.deepEqual(
+    skillLines(`quoted\t"Say \\"hi\\" — then more"\nlong\t${long}`),
+    ['  • quoted — Say "hi"', `  • long — ${"a".repeat(107)}...`],
+  );
+});
+
+test("paperOf: only a file inside a paper folder belongs to a paper", () => {
+  assert.deepEqual(
+    [
+      paperOf([undefined], "papers"),
+      paperOf(["elsewhere/alpha/x.tex"], "papers"),
+      paperOf(["papers/README.md"], "papers"),
+      paperOf(["papers/alpha/x.tex"], "papers/"),
+    ],
+    [null, null, null, "alpha"],
+  );
+});
+
+test("message: with no skills found, the list is left out and the rest stays", () => {
+  const m = message("alpha", []);
+  assert.equal(m.includes("shipped with this package"), false);
+  assert.match(m, /RULES earned the hard way/);
+});
+
+test("paperOf: the root in any spelling the path check accepts — ./, doubled slashes, absolute", () => {
+  assert.deepEqual(
+    [
+      paperOf(["papers/alpha/x.tex"], "./papers"),
+      paperOf(["papers/alpha/x.tex"], ".//papers//"),
+      paperOf(
+        ["papers/alpha/x.tex", "/repo/papers/alpha/x.tex"],
+        "/repo/papers",
+      ),
+      paperOf(["papers/README.md", "/repo/papers/README.md"], "/repo/papers"),
+    ],
+    ["alpha", "alpha", "alpha", null],
+  );
+});
+
+test("a ./-spelled papersDir: the checklist still lands", () => {
+  const dir = hookConsumer(join(root, "dot-slash"), {
+    "paperlint.json": JSON.stringify({ papersDir: "./papers" }),
+  });
+  const r = runShippedHook(
+    "paper-skills-nudge",
+    onEdit("papers/alpha/paper.tex"),
+    dir,
+  );
+  assert.equal(r.exitCode, 0);
+  assert.match(r.stdout, /Working on paper/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "13.0.2",
+  "version": "13.1.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/plugin/hooks/hooks.json

@@ -26,12 +26,17 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Edit|Write|MultiEdit",
+        "matcher": "Read|Edit|Write|MultiEdit",
         "hooks": [
           {
             "type": "command",
             "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/paperlint.mjs\" hook paper-skills-nudge"
-          },
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
           {
             "type": "command",
             "command": "node \"${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/paperlint.mjs\" hook paper-status-gates"

package/presets/aidc.jsonc

@@ -52,10 +52,10 @@
     },
     {
       "what": "camera-ready",
-      "at": "2026-10-31T11:59:59Z",
+      "at": "2026-11-09T11:59:59Z",
       "source": "portal",
       "url": "https://aidc.submit.acsac.org/deadlines",
-      "read": "2026-10-05",
+      "read": "2026-10-29",
     },
   ],
 

package/presets/msr.jsonc

@@ -45,18 +45,25 @@
   // on the abstract and paper days themselves; the portal moved both later on or before 2026-10-19.
   "deadlines": [
     {
-      "what": "submission",
+      "what": "registration",
       "at": "2026-10-21T11:59:59Z",
       "source": "portal",
       "url": "https://msr2027.hotcrp.com/deadlines",
-      "read": "2026-10-19",
+      "read": "2026-10-29",
     },
     {
-      "what": "resubmission",
+      "what": "submission",
       "at": "2026-10-24T11:59:59Z",
       "source": "portal",
       "url": "https://msr2027.hotcrp.com/deadlines",
-      "read": "2026-10-19",
+      "read": "2026-10-29",
+    },
+    {
+      "what": "resubmission",
+      "at": "2026-10-26T11:59:59Z",
+      "source": "portal",
+      "url": "https://msr2027.hotcrp.com/deadlines",
+      "read": "2026-10-29",
     },
   ],
 

package/skills/argument-arc/SKILL.md.spec.ts

@@ -3,7 +3,7 @@
 // Adopted 2026-08-17 as part of the second batch. The body is the previous SKILL.md
 // VERBATIM, so the compiled diff shows only what the compiler adds. No `disallowedTools`
 // fence yet: the field exists on `SkillSpec` as of the branch `claude/skill-disallowed-tools`
-// but is not in a release `mine` installs, so adding it here would not compile.
+// but is not in a release the consumer installs, so adding it here would not compile.
 import { experimental_skill } from "vigiles/spec";
 
 export default experimental_skill({

package/skills/find-venue/SKILL.md.spec.ts

@@ -3,7 +3,7 @@
 // Adopted 2026-08-17 as part of the second batch. The body is the previous SKILL.md
 // VERBATIM, so the compiled diff shows only what the compiler adds. No `disallowedTools`
 // fence yet: the field exists on `SkillSpec` as of the branch `claude/skill-disallowed-tools`
-// but is not in a release `mine` installs, so adding it here would not compile.
+// but is not in a release the consumer installs, so adding it here would not compile.
 import { experimental_skill } from "vigiles/spec";
 
 export default experimental_skill({

package/skills/paper-status/SKILL.md.spec.ts

@@ -3,7 +3,7 @@
 // Adopted 2026-08-17 as part of the second batch. The body is the previous SKILL.md
 // VERBATIM, so the compiled diff shows only what the compiler adds. No `disallowedTools`
 // fence yet: the field exists on `SkillSpec` as of the branch `claude/skill-disallowed-tools`
-// but is not in a release `mine` installs, so adding it here would not compile.
+// but is not in a release the consumer installs, so adding it here would not compile.
 import { experimental_skill } from "vigiles/spec";
 
 export default experimental_skill({

package/skills/render-paper/SKILL.md.spec.ts

@@ -3,7 +3,7 @@
 // Adopted 2026-08-17 as part of the second batch. The body is the previous SKILL.md
 // VERBATIM, so the compiled diff shows only what the compiler adds. No `disallowedTools`
 // fence yet: the field exists on `SkillSpec` as of the branch `claude/skill-disallowed-tools`
-// but is not in a release `mine` installs, so adding it here would not compile.
+// but is not in a release the consumer installs, so adding it here would not compile.
 import { experimental_skill } from "vigiles/spec";
 
 export default experimental_skill({