paperlint 2.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,159 @@
+# Contributing
+
+Everything a user needs is in [`README.md`](README.md). This file is for people changing the
+package.
+
+🔴 **These sections used to live in the README.** They were moved here on 2026-09-17, because a
+directory listing and a testing methodology are not what someone reads to decide whether to try
+the tool. Nothing was dropped — if you are looking for a fact that used to be on the front page,
+it is below.
+
+## How this is tested
+
+Every rule ships with a **harness**: a test that runs the rule twice. Once on a file with a defect
+planted in it, where the rule must find it. Once on a clean file, where the rule must say nothing.
+
+The second run is the one people skip, and it is the one that matters. A rule that is broken and
+finds nothing passes the first kind of test by accident — from outside, "there is nothing wrong
+here" and "this check never ran" look exactly the same.
+
+Older rules also have a **battery** (`*.mutations.mjs`): it deletes one thing the rule depends on
+and then demands the harness go red, at the specific assertion that thing belongs to. **These
+hand-written batteries are deprecated and being removed (#52).** Do not write a new one and do
+not add cases to an existing one; instead, say what an assertion guards in a comment directly
+above it (`// Guards: …`). `npm run check` fails on a new or grown battery — the frozen list in
+`scripts/mutation-batteries.frozen.json` may only shrink. Whether a real mutation-testing tool
+replaces them is decided in #52.
+
+A harness runs in this tree, against this working copy. That is the wrong shape for a defect that
+only exists once somebody else has installed the package — a path written inside a skill, a file
+that never made it into the tarball, a PDF whose content is wrong while the exit code is zero.
+Those are covered by the end-to-end runs, and [`docs/e2e.md`](docs/e2e.md) says which question
+belongs to which tier, and **when a change owes a new e2e rather than a harness**.
+
+It caught a real one on the way in: `js-yaml` 5 stopped parsing an unquoted date as a `Date`.
+Every harness stayed green under both majors, and only the battery noticed that the rule's
+date coercion had become dead code.
+
+## Running the checks: one command
+
+```sh
+npm run check
+```
+
+That is the whole instruction. It runs every gate in order — build, lint, every harness, every
+mutation battery, the install e2e under npm and pnpm, and a real `pdflatex` build — and ends
+
+by printing **which CI jobs it does not reproduce, and why**.
+
+🔴 **There is no `--fast` flag, and that is the point.** On 2026-09-19 a rule change was pushed
+that broke the suite: the gates were run afterwards and were green, but `npm test` and
+`test:install` were not among them, because there were eleven separate scripts and the only way
+to run them all was from memory. A subset flag re-creates exactly that — the cheap half gets run
+and reported as "the gates". If a step genuinely cannot run here, it says so out loud rather than
+being skipped quietly: an e2e that finds no TeX or no pnpm exits 77 _having stated_ why, and
+`npm run check` lists it as skipped instead of counting it as passed.
+
+Each gate's command is listed in `scripts/check.mjs`; run one of them directly while iterating on
+one rule. They are not what you run before pushing.
+
+**The list of gates cannot quietly fall behind CI.** `scripts/check.harness.mjs` pulls the job
+names out of `.github/workflows/ci.yml` and requires each to be either reproduced by a gate or
+named with a reason for why it cannot be. Add a job and it goes red the same day, naming the job
+nobody covered — verified by adding a `windows` job and watching it fail.
+
+## Layout
+
+```
+eslint-rules/   the rules, each with its .harness.mjs beside it (older ones also a .mutations.mjs)
+lib/            shared readers — markdown, skill corpus, the mutation driver
+hooks/          three hooks for vigiles — the code
+plugin/         the Claude Code plugin: wiring for those hooks, no code, no package.json
+skills/         24 stage skills
+scripts/        this repo's own gates
+action.yml      the CI composite action
+fixtures/       inputs the harnesses lint
+docs/           evidence that would otherwise bloat CLAUDE.md:
+                  prior-art/  how comparable tools are shaped, and why this one is shaped so
+                  incidents.md  what broke, measured
+                  install.md  the install contract
+                  e2e.md  the end-to-end runs, and when a change owes one
+```
+
+Most of the package's rules run on users' papers and are described for users in
+[`docs/rules.md`](docs/rules.md); the rest lint this package's own source and never see a user's
+files.
+
+## Maintainer docs
+
+The README links only what a user needs. These are for people changing the package:
+
+- [`docs/prior-art/`](docs/prior-art/README.md) — how comparable tools are shaped, with the URLs
+  that were checked
+- [`docs/install.md`](docs/install.md) — installation: what `npm i` and `paperlint init` set up, what
+  `init` writes, supported package managers, troubleshooting, and why it is shaped this way
+- [`docs/e2e.md`](docs/e2e.md) — the end-to-end runs: what each proves, what they do not cover,
+  and when a change owes one
+- [`docs/incidents.md`](docs/incidents.md) — what broke, measured
+- [`docs/package-shape-options.md`](docs/package-shape-options.md) — the options for the
+  package's shape, and the ranking
+
+## Working on this package
+
+```bash
+npm install
+npm test                 # every harness, the tests' type-check, every *.test.ts (Node >= 22.18)
+node scripts/run-mutations.mjs   # run the remaining batteries (deprecated, #52 — do not add to them)
+```
+
+None of these are needed to USE the tool — they are here because the gates are part of the
+argument, not decoration.
+
+## Releases
+
+Every push to `main` runs semantic-release (`.github/workflows/release.yml`). The squash commit —
+that is, the PR title — decides what ships:
+
+| title                                                         | release |
+| ------------------------------------------------------------- | ------- |
+| `feat: …`                                                     | minor   |
+| `fix: …`, `perf: …`                                           | patch   |
+| any type with `!` (`fix!: …`), or a `BREAKING CHANGE:` footer | major   |
+| `docs:`, `chore:`, `ci:`, `test:`, `refactor:` …              | none    |
+
+`pr-title.yml` fails a PR whose title is not a conventional commit, and for a PR with one commit
+it checks that commit's subject too, because GitHub squashes to it. npm, the git tag `vX.Y.Z` and
+the GitHub Release always carry the same version. Never run `npm publish` by hand.
+
+## Why not one of the existing academic skill suites
+
+The nearest neighbour, [`Imbad0202/academic-research-skills`](https://github.com/Imbad0202/academic-research-skills),
+is a serious project with its own linters, a CI threshold gate and a write guard. "Just prompts"
+is wrong about it.
+
+The difference is **what a check is allowed to read.** Its integrity gate thresholds a numeric
+score that the audited model writes about itself. Here, nothing a rule reads is authored by the
+thing being checked: `paper/stages` compares a declared byte count against `statSync`, and
+`paper/source` does the same for the frozen `.tex`. It also reads the paper's LaTeX source, which
+that suite does not — it checks process artefacts.
+
+Licensing differs too: that suite is CC BY-NC 4.0, this is MIT.
+
+## Words this page uses
+
+- **stage** — a point a paper reached and cannot un-reach: `submitted`, `camera-ready`, `arxiv`.
+- **scorecard** — `PIPELINE-STATUS.md`, the file above. One per paper.
+- **frozen** — a copy of the exact PDF or `.tex` that was sent, kept in `versions/`. Bytes, not a
+  commit reference: squash and `gc` destroy commit references, and did.
+- **harness** — the test beside a rule. **battery** — a set of edits that try to break a harness
+  (deprecated, being removed in #52).
+
+## Also in the box
+
+**The skills** are markdown, one directory each, and they name the scripts
+they run. Point your agent at `skills/` and ask it for a stage by name. The stages that need taste
+stay taste and say so — `paper-adversarial-review` does not pretend to be a checker.
+
+**The 3 hooks** run on [vigiles](https://github.com/zernie/vigiles), a runner that executes checks
+inside an agent's edit loop. It is an ordinary dependency of this package, so it installs with it —
+and it is most of what the install weighs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 research-paper-pipeline contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# paperlint
+
+[![npm version](https://img.shields.io/npm/v/paperlint)](https://www.npmjs.com/package/paperlint)
+![Node version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fzernie%2Fresearch-paper-pipeline%2Fmain%2Fpackage.json&query=%24.engines.node&label=node)
+
+A checker for a research paper you keep in a git repository. You record what happened to the paper
+— "submitted on 22 July, as this PDF" — and `paperlint` checks that the files match: the PDF you say you
+sent is still there and unchanged, its LaTeX source was kept beside it, and the paper itself avoids
+a few mistakes reviewers flag. It runs on your machine and in CI, like a linter.
+
+It is for researchers and engineers who write papers in LaTeX inside git and submit them to
+conferences or journals. Claude Code users also get optional skills and hooks.
+
+## Install and set up
+
+<!-- `vigiles:symbol src/init.ts#init` — `npm run check` fails if this function is renamed or removed. -->
+
+```sh
+npm i -D paperlint
+npx paperlint init
+```
+
+Node 22.13 or newer. Install first: `paperlint init` links the skills and hooks to the copy in
+your project's `node_modules`, so run without the install it has nothing to link to.
+
+`paperlint init` finds your papers directory and records it in `package.json`, offers a CI workflow and a
+first paper, and sets up the optional Claude Code skills and hooks. It installs no software. It
+asks questions only when you run it in a terminal; an agent, CI or `--yes` gets the defaults, and
+each default it takes is printed. It ends by running `paperlint doctor`, which checks the setup.
+Exactly what it writes: [`docs/install.md`](docs/install.md#what-rpp-init-writes).
+
+## What you get
+
+| command                       | what it does                                                                                       |
+| ----------------------------- | -------------------------------------------------------------------------------------------------- |
+| `npx paperlint init`          | sets the project up (see above)                                                                    |
+| `npx paperlint new my-paper`  | creates a paper folder from a template; never overwrites a file                                    |
+| `npx paperlint lint`          | runs every check over your papers; `npx paperlint lint papers/my-paper` checks one                 |
+| `npx paperlint build <paper>` | compiles `paper.tex` to `paper.pdf` with pdflatex and bibtex; `--all` builds every paper           |
+| `npx paperlint toolchain`     | installs TeX Live with the LaTeX packages your venues need; `--check` only reports what is missing |
+| `npx paperlint doctor`        | checks the setup and exits non-zero if something is miswired                                       |
+| `npx paperlint --help`        | every command and flag                                                                             |
+
+A venue is the conference or journal you submit to. TeX Live is the standard LaTeX distribution;
+`paperlint build` offers to install it the first time it needs it.
+
+## Your first paper in five minutes
+
+### Starting a paper
+
+<!-- `vigiles:symbol src/new-paper.ts#newPaper` — `npm run check` fails if this function is renamed or removed. -->
+
+After `npx paperlint init`:
+
+```sh
+npx paperlint new my-paper
+```
+
+```
+  ✓ created papers/my-paper
+      + PIPELINE-STATUS.md  (from the package template)
+      + paper.tex  (from the package template)
+
+config: package.json
+✓ 2 file(s) checked, no findings
+```
+
+You now have one folder per paper:
+
+```
+papers/
+  my-paper/
+    paper.tex                 the paper, in LaTeX
+    PIPELINE-STATUS.md        the paper's record: its research question and the stages it reached
+    reviews/*.md              review notes (optional)
+    versions/                 the exact PDF and source you sent at each stage, never edited
+```
+
+A **stage** is a point the paper has reached, such as `submitted` or `camera-ready` (the final
+version for the proceedings). The name may use `a-z`, `0-9`, `.`, `_` and `-`. On a folder that
+already exists, `paperlint new` adds only the missing files. To use your own templates, put files with
+the same names in `papers/.template/`; `{{name}}` in them becomes the paper's name.
+
+Write the paper, then check and build it:
+
+```sh
+npx paperlint lint                     # check every paper
+npx paperlint build papers/my-paper    # writes papers/my-paper/paper.pdf
+```
+
+`paperlint build` runs pdflatex and bibtex until the references settle. There is no build script to
+write; a `build.sh` in the paper folder is ignored.
+
+When you submit, copy the PDF and `paper.tex` into `versions/` and record the stage in the front
+matter of `PIPELINE-STATUS.md`, with the file sizes in bytes:
+
+```yaml
+stages:
+  - stage: submitted
+    date: 2026-07-22
+    venue: A Venue 2026
+    pdf: versions/2026-07-22-submitted.pdf
+    bytes: 305412
+    source: versions/2026-07-22-submitted.tex
+    sourceBytes: 57210
+```
+
+From then on `paperlint lint` fails if that PDF goes missing or changes size. A frozen PDF should never
+change, so a size that no longer matches means the file was replaced after you recorded it
+([`docs/rules.md`](docs/rules.md#the-scorecards-bytes-and-sourcebytes)).
+
+### What a finding looks like
+
+On a paper folder made by hand, with only `paper.tex`:
+
+```
+config: package.json
+papers/my-paper
+  error  missing `PIPELINE-STATUS.md` — `paper/stages`, `paper/source` and `paper/author-list` read this file, so nothing `my-paper` declares about its stages, sources or authors is checked
+…/my-papers/papers/my-paper/paper.tex
+  1:1  warning  1 × `§` instead of «Section» (reviewer B). Paying the debt down is silent; growth is reported                                                 paper/typography
+  1:1  warning  1 × a decimal without a leading zero, `.05` instead of `0.05` (IEEE / ISO 80000-1 style). Paying the debt down is silent; growth is reported  paper/typography
+
+✖ 2 problems (0 errors, 2 warnings)
+```
+
+Each finding gives the file, line and column, the level, what is wrong, and the check that found
+it. The first line is an error about the folder: without `PIPELINE-STATUS.md`, the three checks
+that read it have nothing to check; `npx paperlint new my-paper` adds the file and leaves `paper.tex`
+alone. The two warnings count typography slips against an allowance you can set per paper: going over
+it is reported, fixing some is not ("paying the debt down is silent").
+
+`paperlint lint` exits `1` when any check reports an error (as here, even though the summary line counts
+only the warnings in files), or when it checked no files at all (usually a wrong path). Warnings
+never fail the run unless you pass `--max-warnings <n>`. `--json` prints the findings as JSON.
+
+## Run it in CI
+
+`paperlint init` offers to write this GitHub Actions workflow step for you. By hand:
+
+```yaml
+- uses: zernie/research-paper-pipeline@v2.0.0
+  with:
+    paths: papers
+```
+
+Use the tag of the version you installed (`npm ls paperlint`): every npm release has
+a git tag of the same version, so the step runs the same code as your package. It runs
+`paperlint lint`. `paths` is required, and the step fails if it checked zero files, so a typo in the path
+shows up red. Optional inputs: `config`, `max-warnings` (default `-1`, no limit), `texcount` (default
+`true`), `working-directory`.
+
+## What the checks catch
+
+| check                          | level   | catches                                                                                                    |
+| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
+| `paper/stages`                 | error   | a stage's PDF is missing, or it is not the same file any more (its size changed)                           |
+| `paper/source`                 | error   | a stage has no frozen source file next to its PDF                                                          |
+| `paper/author-list`            | warning | a stage is declared, but `PIPELINE-STATUS.md` does not record that the author list was checked             |
+| `paper/research-question`      | warning | the research question is missing from `PIPELINE-STATUS.md`, or the paper does not contain that sentence    |
+| `paper/typography`             | warning | more `§`, `.05`-style decimals, mixed `Fig.`/`Figure`, or references without a DOI or URL than you allowed |
+| `tex/future-promise`           | warning | a camera-ready still says your code "will be released"                                                     |
+| `tex/acm-frontmatter-override` | error   | an ACM paper overrides the template's title-page commands, so parts of page 1 go missing                   |
+| `review/findings-cause`        | error   | a review note lists several findings and names no cause for any of them                                    |
+| `doc/fields`                   | warning | a review note's front matter is missing a field you require (off unless configured)                        |
+
+Errors fail the run; warnings only print. What each check reads: [`docs/rules.md`](docs/rules.md).
+Checks that only some venues need are off until you turn them on:
+[`docs/optional-rules.md`](docs/optional-rules.md).
+
+## Configuration
+
+`paperlint init` writes the one required setting into `package.json`:
+
+```json
+{
+  "paperlint": {
+    "papersDir": "papers"
+  }
+}
+```
+
+`papersDir` has no default, so the tool never checks a folder you did not choose: without it,
+`paperlint lint` stops and says so, unless you pass a path. An unknown key is an error. The optional
+settings, and how to use the checks inside your own ESLint setup, are in
+[`docs/configuration.md`](docs/configuration.md). TeX Live, its install location and the external
+programs the skills use are in [`docs/toolchain.md`](docs/toolchain.md).
+
+## Claude Code (optional)
+
+`paperlint lint` needs only Node. If you use Claude Code, `paperlint init` also sets up two things:
+
+**Skills** — one per stage of writing a paper, from checking the idea through drafting, review,
+submission and camera-ready. They are linked into `.claude/skills/`. Start with `/paper-pipeline`;
+it routes to the rest. Some call Java or Python 3, which you install yourself.
+
+**Hooks** — written into `.claude/settings.json`. Commit that file so every clone gets them; a
+fresh clone needs `npm install` before they run.
+
+| hook                 | blocks? | what it does                                                     |
+| -------------------- | ------- | ---------------------------------------------------------------- |
+| `paper-edit-guard`   | yes     | stops a shell command from writing to a paper file               |
+| `paper-skills-nudge` | no      | after a paper edit, shows the agent the pre-submission checklist |
+| `paper-status-gates` | no      | after a paper edit, lists the stages that have not run yet       |
+
+**Know this about `paper-edit-guard`:** if the `paperlint` key in `package.json`
+cannot be read (the file is missing, or has merge-conflict markers), it blocks **every** shell
+command in Claude Code, not only paper ones, until the key is readable again. Fix `package.json`
+with a normal file edit — those are not blocked.
+
+## What it does not do
+
+- **It does not install software behind your back.** `paperlint init` installs nothing; TeX Live comes
+  only from `paperlint toolchain` or when you answer yes in `paperlint build`. On Windows, install TeX Live
+  yourself.
+- **It does not guess what to check.** There is no default papers directory.
+- **It does not overwrite your files.** `paperlint new` and `paperlint init` only add what is missing.
+- **It does not run your build script.** `paperlint build` compiles the paper itself.
+- **It does not write or grade the paper.** `paperlint lint` checks records and a few mechanical
+  mistakes; judging the writing is what the optional skills are for.
+- **New papers are LaTeX.** Markdown papers (`paper.md`) are still read but deprecated
+  ([#57](https://github.com/zernie/research-paper-pipeline/issues/57)).
+- **No Yarn Plug'n'Play.** npm and pnpm are supported
+  ([`docs/install.md`](docs/install.md#package-managers)).
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md): how the package is tested, the one command that runs
+every check, and how releases work: the pull-request title decides the version (`feat:` is a
+minor release, `fix:` a patch).
+
+## License
+
+MIT.
+
+**banal is not part of this package.** banal, the page-geometry script from
+[HotCRP](https://github.com/kohler/hotcrp) (Geoffrey M. Voelker, Eddie Kohler), is licensed
+GPL-2.0-or-later. paperlint does not contain, copy or modify it: `paperlint toolchain` downloads it from HotCRP
+at a pinned commit, checks its sha256, and paperlint runs it as a separate program (`perl banal …`),
+reading its JSON output. Details: [`docs/toolchain.md`](docs/toolchain.md#page-geometry-banal-without-poppler).