paperlint 7.2.0 → 9.0.0

package/skills/paper-pipeline/scripts/extract-ref-facts.test.mjs

@@ -1,6 +1,6 @@
 /**
- * extract-ref-facts.mjs beyond its harness: the edges of each reader (markdown list, .bib, CrossRef,
- * arXiv, cache) and the command itself — sources, flags, the network loop (with `fetch` stubbed in
+ * extract-ref-facts.mjs beyond its harness: the edges of each reader (.bib, CrossRef, arXiv,
+ * cache) and the command itself — sources, flags, the network loop (with `fetch` stubbed in
  * the child process), and the refusals.
  */
 import assert from "node:assert/strict";
@@ -9,18 +9,18 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
 import { runNode, useTempDir, writeTree } from "../../../test/support.ts";
+import { plantedOnDisk, recordOnDisk } from "../../../test/recorded-fixture.ts";
+import { bibliographyUnreadWhy } from "#src/paper-sources";
 import {
+  bibliographyFrom,
   buildFacts,
   extractIds,
   loadCache,
   loadEntries,
-  parseBib,
-  parseMarkdownRefs,
   primaryOf,
   readArxiv,
   readCrossref,
   recordFrom,
-  resolveSource,
 } from "./extract-ref-facts.mjs";
 
 const SCRIPT = join(
@@ -29,72 +29,13 @@ const SCRIPT = join(
 );
 const root = useTempDir("extract-ref-facts-");
 
-test("markdown: the list ends at the file's end or a second References heading; lines continue an entry", () => {
-  assert.deepEqual(parseMarkdownRefs("# P\n\n## References"), []);
-  const refs = parseMarkdownRefs(
-    [
-      "## References",
-      "",
-      "1. A. Author, B. Author. *A Title.* Venue,",
-      "   continued 2021.",
-      "2. *Untitled Authors.* 2019 note",
-      "3. C. Writer 2018. *Late Year.* Venue",
-      "4. No title here at all",
-      "",
-      "## References",
-      "5. Never read. *X.* 2000",
-    ].join("\n"),
-  );
-  assert.deepEqual(
-    refs.map(({ n, line, authors, title, year, venue_text }) => ({
-      n,
-      line,
-      authors,
-      title,
-      year,
-      venue_text,
-    })),
-    [
-      {
-        n: 1,
-        line: 3,
-        authors: ["A. Author", "B. Author"],
-        title: "A Title",
-        year: "2021",
-        venue_text: "Venue, continued 2021.",
-      },
-      {
-        n: 2,
-        line: 5,
-        authors: [],
-        title: "Untitled Authors",
-        year: "2019",
-        venue_text: "2019 note",
-      },
-      {
-        n: 3,
-        line: 6,
-        authors: ["C. Writer 2018"],
-        title: "Late Year",
-        year: "2018",
-        venue_text: "Venue",
-      },
-      {
-        n: 4,
-        line: 7,
-        authors: [],
-        title: null,
-        year: null,
-        venue_text: "No title here at all",
-      },
-    ],
-  );
-});
-
-test(".bib: a key the text spells with spaces has no line; a missing title or year is null, not empty", async () => {
-  const [entry] = await parseBib(
-    "@misc{ spaced ,\n  note={see arXiv:2101.00001}\n}\n",
+test(".bib: an entry's line is where its `@` stands; a missing title or year is null, not empty", () => {
+  const bib = join(root, "lines.bib");
+  writeFileSync(
+    bib,
+    "% a comment\n\n@misc{ spaced ,\n  note={see arXiv:2101.00001}\n}\n",
   );
+  const [entry] = loadEntries(bibliographyFrom(bib).texts[0]);
   assert.deepEqual(
     {
       line: entry.line,
@@ -104,7 +45,7 @@ test(".bib: a key the text spells with spaces has no line; a missing title or ye
       raw: entry.raw,
     },
     {
-      line: 0,
+      line: 3,
       title: null,
       year: null,
       authors: [],
@@ -113,52 +54,6 @@ test(".bib: a key the text spells with spaces has no line; a missing title or ye
   );
 });
 
-test(".bib from a parser that returns no fields, or list and number fields: joined and printed, not dropped", async () => {
-  const load = async () => ({
-    parse: () => ({
-      entries: [
-        { key: "bare" },
-        {
-          key: "odd",
-          fields: {
-            title: ["Split", "Title"],
-            year: 2021,
-            note: null,
-            author: [{ firstName: "Ada", lastName: "Lovelace" }],
-          },
-        },
-      ],
-    }),
-  });
-  const [bare, odd] = await parseBib("@misc{bare,}\n@misc{odd,}\n", { load });
-  assert.deepEqual(
-    [
-      bare,
-      { title: odd.title, year: odd.year, authors: odd.authors, raw: odd.raw },
-    ],
-    [
-      {
-        n: 1,
-        line: 1,
-        key: "bare",
-        raw: "",
-        authors: [],
-        truncated: false,
-        title: null,
-        year: null,
-        venue_text: "",
-        doi_field: null,
-      },
-      {
-        title: "Split Title",
-        year: "2021",
-        authors: ["Ada Lovelace"],
-        raw: "Ada Lovelace Split Title 2021",
-      },
-    ],
-  );
-});
-
 test("identifiers: a declared DOI field comes first; an entry without text fields has none", () => {
   const ids = extractIds({
     doi_field: "10.1111/field",
@@ -244,19 +139,22 @@ test("cache: no path and a corrupt file both read as empty", () => {
   assert.deepEqual([loadCache(undefined), loadCache(corrupt)], [{}, {}]);
 });
 
-test("sources: a file names itself; a .bib is read as BibTeX; facts without a cache say so", async () => {
+test("sources: a .bib named is read as itself, as BibTeX; facts without a cache say so", async () => {
   const bib = join(root, "one.bib");
   writeFileSync(bib, "@misc{k, title={T}, year={2020}}\n");
-  assert.equal(resolveSource(bib), bib);
-  const entries = await loadEntries(bib);
+  const found = bibliographyFrom(bib);
+  assert.deepEqual([found.ok, found.texts.map((t) => t.path)], [true, [bib]]);
+  const entries = loadEntries(found.texts[0]);
   const facts = buildFacts({
-    source: bib,
-    text: "",
+    texts: found.texts,
     entries,
     cache: {},
     cachePath: null,
   });
-  assert.deepEqual([facts.source_kind, facts.cache], ["bibtex", null]);
+  assert.deepEqual(
+    [facts.source_kind, facts.cache, facts.sources],
+    ["bibtex", null, [bib]],
+  );
 });
 
 // ── the command ─────────────────────────────────────────────────────────────
@@ -268,24 +166,59 @@ const CROSSREF_OK = JSON.stringify({
     issued: { "date-parts": [[2020]] },
   },
 });
+/** A paper.tex declaring `\bibliography{refs}`, with `preamble` before its document. */
+const declaring = (preamble = "") =>
+  `\\documentclass{article}\n${preamble}\\begin{document}x\\bibliography{refs}\\end{document}\n`;
 writeTree(root, {
-  "paper/paper.md":
-    "## References\n\n1. A. A. *Found.* doi:10.1234/ok\n2. B. B. *Lost.* doi:10.1234/down\n",
-  "empty/paper.md": "# Nothing cited\n",
+  "paper/paper.tex": declaring(),
+  "paper/refs.bib":
+    "@misc{a, author={A. A}, title={Found}, note={doi:10.1234/ok}}\n" +
+    "@misc{b, author={B. B}, title={Lost}, note={doi:10.1234/down}}\n",
+  "empty/paper.tex": declaring(),
+  "empty/refs.bib": "% nothing cited\n",
+  "notes/notes.txt": "A. A. Found. doi:10.1234/ok\n",
   // `fetch` in the child: 10.1234/down fails at the transport, anything else is a CrossRef hit.
   "fetch.mjs":
     `globalThis.fetch = async (url) => {\n` +
     `  if (url.includes("down")) throw new Error("network down");\n` +
     `  return { status: 200, text: async () => ${JSON.stringify(CROSSREF_OK)} };\n` +
     `};\n`,
-  // The optional .bib parser, uninstalled — and broken in some other way.
-  "no-parser.mjs":
-    "import { register } from 'node:module';\n" +
-    "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '@retorquere/bibtex-parser') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
-  "bad-parser.mjs":
-    "import { register } from 'node:module';\n" +
-    "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '@retorquere/bibtex-parser') throw Object.assign(new Error('broken install'), { code: 'EACCES' }); return next(s, c); }\"));\n",
+  "bib/paper.tex": declaring(),
+  "switched/paper.tex":
+    "\\documentclass{article}\\newif\\ifanon\\begin{document}x\\ifanon\\bibliography{anon}\\else\\bibliography{refs}\\fi\\end{document}\n",
+  "switched/anon.bib": "@misc{anon1, title={A}, note={doi:10.1234/a}}\n",
+  "switched/refs.bib": "@misc{refs1, title={R}, note={doi:10.1234/r}}\n",
   "bib/refs.bib": "@misc{k, title={T}, note={doi:10.1234/ok}}\n",
+  // The bibliography is embedded in paper.tex; the refs.bib beside it is what TeX wrote from the block.
+  "inline/paper.tex": declaring(
+    "\\begin{filecontents*}[overwrite]{refs.bib}\n" +
+      "@misc{a, author={A. A}, title={Found}, note={doi:10.1234/ok}}\n" +
+      "@misc{b, author={B. B}, title={Lost}, note={doi:10.1234/down}}\n" +
+      "\\end{filecontents*}\n",
+  ),
+  "inline/refs.bib":
+    "@misc{a, author={A. A}, title={Found}, note={doi:10.1234/ok}}\n" +
+    "@misc{b, author={B. B}, title={Lost}, note={doi:10.1234/down}}\n",
+  // A paper that was never built has no record: nothing says which bibliography TeX reads.
+  "unbuilt/paper.tex": declaring(),
+  "unbuilt/refs.bib": "@misc{k, title={T}, note={doi:10.1234/ok}}\n",
+});
+/** What a build records for a paper whose bibliography is the file `db` the author keeps. */
+const keeps = (db = "refs.bib") => ({
+  inputs: [
+    ["paper.tex", "body"],
+    [db, "preamble"],
+  ],
+  databases: [db],
+});
+for (const dir of ["paper", "empty", "bib"])
+  recordOnDisk(join(root, dir), keeps());
+// bibtex opened refs.bib only: the switch took its `\else`.
+recordOnDisk(join(root, "switched"), keeps());
+recordOnDisk(join(root, "inline"), {
+  inputs: [["paper.tex", "body"]],
+  written: ["refs.bib"],
+  databases: ["refs.bib"],
 });
 const cli = (args, { cwd = root, nodeArgs = [] } = {}) =>
   runNode(SCRIPT, args, {
@@ -309,7 +242,7 @@ test("online: hits are fetched and cached, a transport failure is named and stay
     {
       status: 0,
       stdout:
-        "📚 paper.md → paper/_build/refs.facts.json (2 entries, 2 identifiers, 1 resolved, +1 fetched)\n",
+        "📚 refs.bib → paper/_build/refs.facts.json (2 entries, 2 identifiers, 1 resolved, +1 fetched)\n",
       stderr: "   … doi:10.1234/down: network down\n",
       cached: ["doi:10.1234/ok"],
     },
@@ -321,7 +254,7 @@ test("online again: cached keys are not refetched; --quiet hides the failure; --
   assert.deepEqual(again, {
     status: 0,
     stdout:
-      "📚 paper.md → paper/_build/refs.facts.json (2 entries, 2 identifiers, 1 resolved, all from cache)\n",
+      "📚 refs.bib → paper/_build/refs.facts.json (2 entries, 2 identifiers, 1 resolved, all from cache)\n",
     stderr: "",
   });
   const refresh = cli(["paper", "--refresh", "--quiet"], { nodeArgs: FETCH });
@@ -330,7 +263,7 @@ test("online again: cached keys are not refetched; --quiet hides the failure; --
 
 test("the paper file itself as the target, with --cache, --out and --offline", () => {
   const r = cli([
-    join(root, "paper/paper.md"),
+    join(root, "paper/refs.bib"),
     "--offline",
     `--cache=${join(root, "paper/repro/refs-cache.json")}`,
     `--out=${join(root, "out/facts.json")}`,
@@ -338,7 +271,7 @@ test("the paper file itself as the target, with --cache, --out and --offline", (
   assert.deepEqual(r, {
     status: 0,
     stdout:
-      "📚 paper.md → out/facts.json (2 entries, 2 identifiers, 1 resolved, offline)\n",
+      "📚 refs.bib → out/facts.json (2 entries, 2 identifiers, 1 resolved, offline)\n",
     stderr: "",
   });
 });
@@ -348,33 +281,113 @@ test("no target: the current directory", () => {
   assert.equal(r.status, 0, r.stderr);
 });
 
-test("refusals: nowhere to read from, and zero entries (not written as a clean bibliography)", () => {
-  assert.deepEqual(cli([join(root, "nope"), "--offline"]), {
+test("refusals: no bibliography to read (in bibliographyAt's words), and zero entries (not written as a clean bibliography)", () => {
+  // The path → bibliography vocabulary is tested once, beside bibliographyAt (src/paper-sources.ts).
+  // Here: that the command speaks it, and stops.
+  const notes = join(root, "notes/notes.txt");
+  assert.deepEqual(cli([notes, "--offline"]), {
     status: 1,
     stdout: "",
-    stderr: `🛑 no paper.md, draft.md, refs.bib, build/custom.bib under ${join(root, "nope")} — nowhere to take a bibliography from.\n`,
+    stderr: `🛑 ${bibliographyUnreadWhy({ kind: "not-bib-or-tex", path: notes })}.\n`,
   });
   assert.deepEqual(cli(["empty", "--offline"]), {
     status: 1,
     stdout: "",
     stderr:
-      "🛑 parsed 0 entries out of empty/paper.md. Silence here would look like a clean bibliography.\n",
+      "🛑 parsed 0 entries out of empty/refs.bib. Silence here would look like a clean bibliography.\n",
   });
 });
 
-test(".bib without its optional parser: the error names the install; any other failure is not masked", () => {
-  const missing = cli(["bib", "--offline"], {
-    nodeArgs: ["--import", join(root, "no-parser.mjs")],
+test("🔴 a paper directory whose paper.tex embeds its .bib: the entries are read from the block that wrote it, where the author edits them", () => {
+  const r = cli(["inline", "--offline"]);
+  // Guards: only materialized .bib files were looked for, so a paper with its bibliography in
+  // `filecontents` was refused before a build and read from a stale refs.bib after an edit.
+  assert.deepEqual(r, {
+    status: 0,
+    stdout:
+      "📚 paper.tex → inline/_build/refs.facts.json (2 entries, 2 identifiers, 0 resolved, offline)\n",
+    stderr: "",
   });
-  assert.equal(missing.status, 1);
-  assert.match(
-    missing.stderr,
-    /parsing \.bib requires @retorquere\/bibtex-parser[\s\S]*Install: {2}npm i -D @retorquere\/bibtex-parser/,
+  const facts = JSON.parse(
+    readFileSync(join(root, "inline/_build/refs.facts.json"), "utf8"),
+  );
+  // Each entry's line is its line in paper.tex, where the author edits it.
+  assert.deepEqual(
+    facts.entries.map((e) => [e.file, e.key, e.line]),
+    [
+      ["inline/paper.tex", "a", 3],
+      ["inline/paper.tex", "b", 4],
+    ],
   );
-  const broken = cli(["bib", "--offline"], {
-    nodeArgs: ["--import", join(root, "bad-parser.mjs")],
+});
+
+test("a bibliography behind a switch: the database bibtex opened is read, not every candidate", () => {
+  assert.deepEqual(cli(["switched", "--offline"]), {
+    status: 0,
+    stdout:
+      "📚 refs.bib → switched/_build/refs.facts.json (1 entries, 1 identifiers, 0 resolved, offline)\n",
+    stderr: "",
   });
-  assert.equal(broken.status, 1);
-  assert.match(broken.stderr, /broken install/);
-  assert.doesNotMatch(broken.stderr, /npm i -D/);
+});
+
+test("🔴 a paper that was not built is refused — run `npx paperlint build` first — never read from its source", () => {
+  assert.deepEqual(cli(["unbuilt", "--offline"]), {
+    status: 1,
+    stdout: "",
+    stderr: `🛑 ${join(root, "unbuilt")} has not been built — run \`npx paperlint build\` first, which records the databases bibtex reads.\n`,
+  });
+});
+
+test("an embedded entry's line is its line in paper.tex", () => {
+  const block = "@misc{ spaced ,\n  note={arXiv:2101.00001}\n}\n";
+  writeTree(root, {
+    "spaced/paper.tex": declaring(
+      `\\begin{filecontents*}{refs.bib}\n${block}\\end{filecontents*}\n`,
+    ),
+    "spaced/refs.bib": block,
+  });
+  recordOnDisk(join(root, "spaced"), {
+    inputs: [["paper.tex", "body"]],
+    written: ["refs.bib"],
+    databases: ["refs.bib"],
+  });
+  const found = bibliographyFrom(join(root, "spaced", "paper.tex"));
+  assert.deepEqual(
+    loadEntries(found.texts[0]).map((e) => e.line),
+    [3],
+  );
+});
+
+// ── the planted papers of fixtures/paper-sources, laid out as a build leaves them ─────
+
+test.each([
+  // [paper, the file read, the keys read] — tex-truth.json beside each paper is TeX's own answer: the
+  // databases bibtex opened. A `.bib` TeX wrote from a block is read from the block (paper.tex).
+  ["v1-stale", "refs.bib", ["stale2020"]],
+  ["v2-overwrite", "paper.tex", ["inline2024"]],
+  ["v3-declared", "paper.bib", ["declared2023"]],
+  ["v4-commented", "refs.bib", ["stale2020"]],
+  // What bibtex reads beyond these — a malformed entry, or one behind `%` or inside `@comment{…}` —
+  // the build's post-build check names (src/references.ts).
+  ["v5-percent-entry", "paper.tex", ["inline2024"]],
+  ["v6-unclosed", "refs.bib", ["a1", "a3"]],
+  ["v13-percent-text", "refs.bib", ["ok1"]],
+  ["v8-jobname", "paper.tex", ["jkey"]],
+])("%s: the bibliography bibtex opened", (paper, file, keys) => {
+  const dir = join(root, "planted", paper);
+  plantedOnDisk(dir, paper);
+  const out = join(root, "planted", `${paper}.json`);
+  const r = cli([
+    dir,
+    "--offline",
+    `--out=${out}`,
+    `--cache=${join(root, "planted", "cache.json")}`,
+  ]);
+  assert.deepEqual([r.status, r.stderr], [0, ""]);
+  assert.match(r.stdout, new RegExp(`^📚 ${file} → `));
+  const facts = JSON.parse(readFileSync(out, "utf8"));
+  assert.deepEqual(
+    facts.entries.map((e) => e.key),
+    keys,
+  );
 });

package/skills/paper-pipeline/scripts/generated-code.harness.mjs

@@ -68,7 +68,7 @@ function run(dir, flagsOnly = true) {
 function fixture({ scripts = {}, allow = null, bundle = {}, at = "repro" }) {
   const d = join(tmp, `f${++n}`);
   mkdirSync(d, { recursive: true });
-  writeFileSync(join(d, "paper.md"), "## 1. x\n\nprose\n");
+  writeFileSync(join(d, "paper.tex"), "\\section{x}\nprose\n");
   if (at === null) return d;
   mkdirSync(join(d, at), { recursive: true });
   for (const [p, src] of Object.entries(scripts)) {
@@ -142,13 +142,13 @@ function fixture({ scripts = {}, allow = null, bundle = {}, at = "repro" }) {
     fixture({
       scripts: {
         "wc.py":
-          'text = open("/home/example/papers/paper.md").read()\nprint(len(text.split()))\n',
+          'text = open("/home/example/papers/paper.tex").read()\nprint(len(text.split()))\n',
       },
     }),
   );
   assert.match(
     r.out,
-    /ABS_PATH\s+repro\/wc\.py — hard-codes 1 absolute path\(s\), e\.g\. `\/home\/example\/papers\/paper\.md`/,
+    /ABS_PATH\s+repro\/wc\.py — hard-codes 1 absolute path\(s\), e\.g\. `\/home\/example\/papers\/paper\.tex`/,
     "a script that only runs on its author's laptop shipped in the reproduction directory unremarked:\n" +
       r.out,
   );

package/skills/paper-status/SKILL.md

@@ -4,7 +4,7 @@ description: Answer "what's the status of the paper?" in one pass — MEASURE wh
 allowed-tools: [Bash, Read, Grep, Glob]
 ---
 
-<!-- vigiles:sha256:cdf5e1fcefdb916d compiled from skills/paper-status/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:c90bd362b565fa22 compiled from skills/paper-status/SKILL.md.spec.ts -->
 
 # paper-status — state, measured before it is narrated
 
@@ -65,7 +65,7 @@ git log --oneline @{u}..HEAD                # unpushed commits
 A gate is stale if the paper changed after the gate ran. Check it mechanically, not by recall:
 
 ```bash
-git log -1 --format=%cd --date=short -- paper.md          # when the text last moved
+git log -1 --format=%cd --date=short -- paper.tex         # when the text last moved
 ls -la reviews/ | tail -20                                # when each gate last reported
 ```
 

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

@@ -71,7 +71,7 @@ git log --oneline @{u}..HEAD                # unpushed commits
 A gate is stale if the paper changed after the gate ran. Check it mechanically, not by recall:
 
 \`\`\`bash
-git log -1 --format=%cd --date=short -- paper.md          # when the text last moved
+git log -1 --format=%cd --date=short -- paper.tex         # when the text last moved
 ls -la reviews/ | tail -20                                # when each gate last reported
 \`\`\`
 

package/skills/render-paper/SKILL.md

@@ -4,7 +4,7 @@ description: Compile a LaTeX paper (ACM/IEEE/arXiv) to PDF and render its pages
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, SendUserFile]
 ---
 
-<!-- vigiles:sha256:5e2ee8850c098375 compiled from skills/render-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:ff8dca1e1be3977e compiled from skills/render-paper/SKILL.md.spec.ts -->
 
 # render-paper — .tex → PDF → readable page PNGs
 
@@ -15,7 +15,7 @@ first try.
 ## 🔴 This is a COMMAND, not a stage
 
 You run it twenty times a day. It has no position in the pipeline and nothing waits its turn to reach
-it: **any `.tex` / `paper.md` edit is the trigger** — render, then eyeball pages 1–2 before believing
+it: **any `.tex` edit is the trigger** — render, then eyeball pages 1–2 before believing
 anything you say about the paper. Scorecard row **`render`** (in the CONTINUOUS section of
 `paper-pipeline`) records the last render and its page count; that page count is the hard input the
 `tighten-paper` structure gate is blocked on, which is the only sense in which anything "comes after"

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

@@ -21,7 +21,7 @@ first try.
 ## 🔴 This is a COMMAND, not a stage
 
 You run it twenty times a day. It has no position in the pipeline and nothing waits its turn to reach
-it: **any \`.tex\` / \`paper.md\` edit is the trigger** — render, then eyeball pages 1–2 before believing
+it: **any \`.tex\` edit is the trigger** — render, then eyeball pages 1–2 before believing
 anything you say about the paper. Scorecard row **\`render\`** (in the CONTINUOUS section of
 \`paper-pipeline\`) records the last render and its page count; that page count is the hard input the
 \`tighten-paper\` structure gate is blocked on, which is the only sense in which anything "comes after"

package/skills/render-paper/extract-pdf-facts.mjs

@@ -56,8 +56,8 @@ const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 /**
  * Accept either a path to a PDF or a PAPER DIRECTORY — and in the second case find the artifact on
  * its own: the path the paper declares in the `pdf` field of `paperlint.json`, else `paper.pdf` beside
- * it. A paper written in markdown and built by its own script into `build/acl_latex.pdf` would
- * otherwise be skipped silently. The facts ALWAYS go into `<paper directory>/_build/`, not next to
+ * it. A paper built by its own script into `build/acl_latex.pdf` would otherwise be skipped
+ * silently. The facts ALWAYS go into `<paper directory>/_build/`, not next to
  * the PDF, where neither a rule's glob nor a human looks.
  */
 export function resolveTarget(arg) {

package/skills/tighten-paper/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when a paper \"feels long / bloated / overly complex / hard to
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent]
 ---
 
-<!-- vigiles:sha256:fd00cde33ea4b81c compiled from skills/tighten-paper/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:c57d6da372b28acf compiled from skills/tighten-paper/SKILL.md.spec.ts -->
 
 # tighten-paper — the developmental edit
 
@@ -34,31 +34,12 @@ counter, is not this skill; it is the damage this skill exists to undo.
 If you are invoked while the author is still adding material, say so and decline the pass. The right
 answer is "not yet", not a smaller cut.
 
-## 🏗 START WITH THE MECHANICAL LEG — run `structure.mjs` (added 2026-08-05)
+## 🏗 START WITH THE SHAPE — weigh every section before judging it
 
-```
-node .claude/skills/tighten-paper/structure.mjs <paper.md>              # whole paper
-node .claude/skills/tighten-paper/structure.mjs <paper.md> --section=3  # one section
-```
-
-🔴 **THE SCRIPT NO LONGER FINDS ANYTHING — it is an INVENTORY (2026-08-26).** All sixteen of its
-checks moved into ESLint rules (`eslint-rules/paper-structure.mjs`). The findings you used to read
-here now come from:
-
-```
-npx eslint --no-config-lookup --config eslint.config.mjs <paper.md>
-```
-
-⚠️ Do NOT pass `--flags-only`. It is kept only because two harnesses assert on its silence, and it
-prints nothing and exits 0 whatever the paper looks like. Measured 26.08 on `the reference paper`:
-`--flags-only` printed 0 lines while ESLint on the same bytes reported **6 structural findings**
-(subsection-size ×2 · section-lead · free-section-size ×2 · block-ungraded). A mode that cannot
-speak is not a check, and reading its silence as "clean" is the defect this pipeline is named for.
-
-What the inventory prints, and why it stays a script: the outline **in order** — every heading, its
-own words, its total with subsections, its share of the body, and the `carries:`/`score:`/`verdict:`
-note the section wrote about itself, printed beside its weight. That comparison is the whole point
-and a linter cannot make it: a finding has nowhere to put a table.
+Write the outline out **in order**: every heading, its own words before its first subsection, its
+total with subsections, its share of the body — and beside each, the `carries:`/`score:`/`verdict:`
+note the section wrote about itself. That comparison, a section's weight printed next to what it
+claims about itself, is the whole point.
 
 🔴 **Why this exists, and why word counts alone mislead.** Asked whether a paper short-changed its
 contribution, per-section word counts said no — the contribution had 38% more words than related
@@ -67,7 +48,7 @@ owned **0, 28 and 38** words before their first subsection. Nothing in the toolc
 question, because every metric was per-sentence or per-document and none was per-section. The author's
 word for the result was a "salad" — a jumbled mix — and he was right while the numbers said fine.
 
-**What the script does NOT decide, and you must:** the ORDER, the NAMES, and whether a section earns
+**What the count does NOT decide, and you must:** the ORDER, the NAMES, and whether a section earns
 its place. Those are judgement, and pretending otherwise would be the failure this whole pipeline
 exists to prevent.
 
@@ -188,18 +169,24 @@ called it "fat for no reason" after a pass that cut almost nothing and left it 1
 
 A verdict that lives in a chat log is gone by the next session, and the next session then re-derives
 it or ignores it. **Every section and subsection gets a one-line verdict comment immediately above its
-heading**, in the paper source, stamped with the date and the skill that produced it:
-
-```
-<!-- TIGHTEN 2026-08-06 · score 8/10 · verdict: KEEP · 190w
-     carries: tools get close but none resolves a NAMED rule against a committed config
-     because: it is the only place the tool-ecosystem gap is closed; a reviewer who skips it
-              asks "hasn't this been done" and gets no answer -->
-<!-- TIGHTEN 2026-08-06 · score 5/10 · verdict: SHORTEN -89w · 210w
-     carries: why a linter for the rules file cannot work
-     because: the point lands in two sentences; the rest re-establishes what §2 already did -->
-<!-- TIGHTEN 2026-08-06 · score 2/10 · verdict: MOVE→artifact · 45w
-     carries: nothing the reader must hold to judge the contribution -->
+heading**, in `paper.tex`, as LaTeX `%` comments, stamped with the date and the skill that
+produced it:
+
+```latex
+% TIGHTEN 2026-08-06 · score 8/10 · verdict: KEEP · 190w
+%   carries: tools get close but none resolves a NAMED rule against a committed config
+%   because: it is the only place the tool-ecosystem gap is closed; a reviewer who skips it
+%            asks "hasn't this been done" and gets no answer
+\section{Related tools}
+
+% TIGHTEN 2026-08-06 · score 5/10 · verdict: SHORTEN -89w · 210w
+%   carries: why a linter for the rules file cannot work
+%   because: the point lands in two sentences; the rest re-establishes what §2 already did
+\subsection{Why not a linter}
+
+% TIGHTEN 2026-08-06 · score 2/10 · verdict: MOVE→artifact · 45w
+%   carries: nothing the reader must hold to judge the contribution
+\subsection{Implementation notes}
 ```
 
 🔴 **Before assigning any `MOVE→` verdict, read `paper-pipeline/references/body-vs-appendix.md`.**
@@ -224,7 +211,7 @@ written and **not one ever concluded "cut me"**. Author, 2026-08-06, reading the
 value on every page and compared nothing.
 
 The pairing is the mechanism: **a low score beside a KEEP verdict is a visible contradiction**, and
-`structure.mjs` reports it. Prose cannot contradict itself; a number can.
+the outline above puts the two side by side. Prose cannot contradict itself; a number can.
 
 **Calibration, so the scale does not drift to "everything is an 8":**
 - **9–10** — remove it and a reviewer cannot assess the contribution. The claim, its evidence, its price.
@@ -279,10 +266,10 @@ Rules for these comments:
   unpriced prose accumulates, because nothing there costs a page.
 - **Stale beats absent, but not by much.** A comment whose date precedes the last substantive edit to
   its section is stale; re-grade it rather than trusting it.
-- **A verdict nobody executed is a note, not a decision.** `structure.mjs` reports blocks still
-  carrying a non-KEEP verdict — a paper full of unexecuted CUTs is worse than one never graded,
+- **A verdict nobody executed is a note, not a decision.** List the blocks still carrying a
+  non-KEEP verdict — a paper full of unexecuted CUTs is worse than one never graded,
   because it reads as decided.
-- They are working notes: stripped before typesetting, like every other `<!-- -->` block.
+- They are working notes: a `%` comment never reaches the PDF.
 - The chat summary still gets written — but it is the *derivative*, and the paper is the record.
 
 ## 🧱 Enforce subsections — a section without them is a wall