paperlint 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+import type { RuleBlock } from "./rules-config.ts";
+/**
+ * The shapes the CLI commands exchange. Before the move to TypeScript this was all `{}` and lived
+ * in someone's head: a typo in a config key read as "field not set", not as an error.
+ */
+/** The contents of the consumer's `rpp.json`. */
+export interface RppConfig {
+    /** 🔴 REQUIRED. The paper director(ies), relative to the config file ITSELF. The field name is
+     * `PAPERS_DIR_FIELD` in lib/paper-config.mjs; code reads it through `papersDirOf()` in cli.ts. */
+    papersDir?: string | string[];
+    /** The command that prints the author list from .bib — each corpus has its own. */
+    authorListCommand?: string;
+    /** Per-paper typography debt: how many findings already exist; the number may only go down. */
+    typographyDebt?: Record<string, Record<string, number>>;
+    /** Frontmatter fields required for review notes, and the permitted values of each. */
+    docFields?: Record<string, {
+        values: string[];
+    }>;
+    /** Ignore review findings older than this date. */
+    reviewSince?: string;
+    /** How many findings a cold read must produce to count as a cold read. */
+    minFindings?: number;
+    /** The word with which review notes introduce the cause. */
+    causeMarker?: string;
+    /** Which files a paper directory must carry; `false` turns the check off entirely. */
+    structure?: StructureConfig | false;
+    /** REMOVED — `paperlint build` compiles the paper itself. Still typed so a leftover key can be named. */
+    buildScripts?: unknown;
+    /** ESLint config blocks appended after rpp's own — PARSED by `parseSettings` in cli.ts. */
+    rules?: readonly RuleBlock[];
+}
+export interface StructureConfig {
+    /** These files are what IDENTIFY a directory as a paper. Detection is generous. */
+    markers?: string[];
+    /** These files must exist. The requirements are strict. */
+    require?: string[];
+    /** At least one from each group. */
+    requireOneOf?: string[][];
+    /** Directories exempted from the check by name. */
+    ignore?: string[];
+}
+/** The parsed command line. */
+export interface Args {
+    cmd: string | null;
+    paths: string[];
+    config: string | null;
+    json: boolean;
+    all: boolean;
+    dryRun: boolean;
+    /** `--check`: `toolchain` reports what is missing and changes nothing. */
+    check: boolean;
+    maxWarnings: number;
+    /** `--yes` / `-y`: take every default, ask nothing. */
+    yes: boolean;
+    /** `--no-hooks`: `init` does not touch `.claude/settings.json`. */
+    noHooks: boolean;
+    /** `--paper <name>`: `init` creates this paper. */
+    paper: string | null;
+    /** `--format tex|md` for `new` and `init --paper`. Validated by the command, not here. */
+    format: string | null;
+    /** `--hooks=<mode>` — parsed only so it can be REFUSED by name rather than read as a path. */
+    hooksMode: string | null;
+    help?: boolean;
+    /** A flag that turned out to have no value. A non-empty field is a REFUSAL, not a default. */
+    missingValue?: string;
+}
+/** A finding about the PRESENCE of a file — what an ESLint rule cannot express. */
+export interface StructureFinding {
+    file: string;
+    message: string;
+}
+/** One line of a build plan: a step, whether it applies to this paper, and why. */
+export interface PlanLine {
+    step: string;
+    applies: boolean;
+    /** A required step that does not apply refuses the build instead of being skipped. */
+    required: boolean;
+    why: string;
+}
+/**
+ * The build outcome for one paper. `no-source` — there is no `paper.tex` to compile — is a
+ * REFUSAL, not a skip: "nothing to build" and "built" must never look alike.
+ */
+export interface BuildResult {
+    dir: string;
+    status: "built" | "failed" | "no-source";
+    plan: PlanLine[];
+    /** `--dry-run`: the plan was printed and nothing ran. */
+    dry?: boolean;
+    /** The step that failed and what to show for it. */
+    failure?: {
+        step: string;
+        lines: string[];
+    };
+    /** What the steps reported on success: pass counts, undefined-reference warnings. */
+    notes?: string[];
+    /** A paper.pdf from an earlier run was on disk and `buildPapers` removed it before building. */
+    staleRemoved?: boolean;
+}
+/** The result of reading the config: either data, or the exit code the caller exits with. */
+export type ConfigRead = {
+    opts: RppConfig;
+    configPath: string | null;
+    code?: undefined;
+} | {
+    code: number;
+    opts?: undefined;
+    configPath?: undefined;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/configuration.md

@@ -0,0 +1,235 @@
+# Configuration reference
+
+One key in your `package.json`, written by `paperlint init`. It holds the facts only your repository can
+supply — nothing in it is guessable by a package that has never seen your corpus.
+
+The README carries the minimal version of this. Everything below is the full surface, moved out on
+2026-09-19.
+
+```json
+{
+  "paperlint": {
+    "papersDir": "papers",
+    "authorListCommand": "node scripts/bib-authors.mjs",
+    "typographyDebt": { "papers/my-paper": { "sectionSign": 12 } },
+    "docFields": { "read": { "values": ["full", "abstract", "none"] } },
+    "reviewSince": "2026-08-23",
+    "minFindings": 3,
+    "causeMarker": "Cause:",
+    "rules": [
+      {
+        "files": ["papers/agenticdev-2026/**"],
+        "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] }
+      }
+    ]
+  }
+}
+```
+
+| key                 | required | what it is                                                                                |
+| ------------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `papersDir`         | **yes**  | the directory your papers live in, relative to the file holding it. One string or a list. |
+| `structure`         | no       | which files every paper directory must contain — see below. `false` turns it off.         |
+| `authorListCommand` | no       | the command `paper/author-list` tells you to run when the check is missing                |
+| `typographyDebt`    | no       | per-paper allowance of existing typography findings, so the count can only go down        |
+| `docFields`         | no       | required front-matter fields in review files, and the values each may hold                |
+| `reviewSince`       | no       | only review files created on or after this date are checked                               |
+| `minFindings`       | no       | a review with fewer findings than this is not required to name causes                     |
+| `causeMarker`       | no       | the phrase a review uses to introduce a cause (default `Cause:`), in any language         |
+| `rules`             | no       | extra ESLint config blocks: turn optional rules on, change a rule's severity — see below  |
+
+The skill scripts read a few more keys of the same object — `ledger`, `scripts`, `timezone`,
+`contactEmail`, `citeChecks`, `triggerCases` — documented with the skills that use them.
+
+**Any other key is an error**, named in the message: `package.json → "paperlint":
+unknown key "typographyDept"`. A misspelt key would otherwise read as "not set", and the setting
+you meant would silently do nothing. The list of known keys is `SETTINGS_KEYS` in
+`lib/paper-config.mjs`.
+
+`papersDir` is required because the scope is the one thing that must not default: a default of `"."`
+turns every run into a green report over the whole checkout. `paperlint init` fills it by measuring —
+and when nothing on disk looks like a papers directory, it writes the documented default and says
+in the same breath that it is a guess.
+
+Until 2026-09-24 this field was called `papers`. The old name is not read as a fallback: `paperlint lint`,
+`paperlint init`, `paperlint doctor`, the ESLint helper and the edit guard all stop with
+`"papers" was renamed to "papersDir" in package.json → "paperlint"`. The two advisory
+hooks stay silent instead. The name is defined once, as `PAPERS_DIR_FIELD` in
+`lib/paper-config.mjs`.
+
+## Why the key lives in `package.json`
+
+Because of a count: the `package.json` key has **five** readers — the three editor hooks, the
+ESLint helper, the skill scripts — and a separate config file had **one**, the CLI. A hook cannot
+import code and cannot walk up a tree looking for a config; it can read a path it is able to name,
+and the one path it can always name is the project's `package.json`.
+
+`paperlint lint` looks for it in the current directory and then upwards, the way eslint and tsc find
+theirs, and prints which file it found. `--config <file>` overrides the search.
+
+⚠️ **`rpp.json` is deprecated and still read.** Earlier versions of `init` created it; `init` no
+longer does, and a run that reads one says so on its first line. The hooks never read it, so
+leaving settings there is how the linter and the guard end up watching different directories —
+`paperlint init` copies the value across for you.
+
+## The `rules` key: turning rules on and off
+
+`rules` is a list of blocks in ESLint's own
+[flat-config shape](https://eslint.org/docs/latest/use/configure/configuration-files), limited to
+the three keys that make sense in JSON — `files`, `ignores` and `rules`. paperlint appends the blocks
+**after** its own configuration, so, as in ESLint, a later block wins: a block can turn on a rule
+that is off by default, or change the severity of one that is on.
+
+```json
+"rules": [
+  {
+    "files": ["papers/agenticdev-2026/**"],
+    "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] }
+  },
+  {
+    "files": ["papers/old-draft/**"],
+    "rules": { "paper/typography": "off" }
+  }
+]
+```
+
+- **`files` and `ignores` are globs relative to the file that holds the settings** — the
+  directory of your `package.json` — exactly as ESLint resolves them relative to its config file,
+  whatever directory you run `paperlint lint` from. A block without `files` applies to every linted file.
+  A pattern ending in `/**` is the usual way to name one paper.
+- **A rule entry** is a severity (`"off"`, `"warn"`, `"error"`, or `0`/`1`/`2`), or a list whose
+  first element is a severity and the rest are the rule's options.
+- **Only rules paperlint ships can be named** — the ones in [`docs/rules.md`](rules.md) and
+  [`docs/optional-rules.md`](optional-rules.md). A rule id paperlint does not ship, a bad severity, a
+  `rules` that is not a list, or a block key other than `files`, `ignores` and `rules` stops the run
+  with a message naming the exact key, before anything is linted.
+- **An optional rule you turned on must reach a paper.** If no linted `paper.tex` gets the rule —
+  usually a `files` glob with a typo — `paperlint lint` fails and says so: a rule that never runs
+  reports exactly like one that passed.
+
+## Required files
+
+A rule runs on a file it was handed. A file that is missing is never handed to anything — so no
+rule can report it, and a paper directory without `PIPELINE-STATUS.md` gets **zero** rules and a
+clean report. `paperlint lint` therefore checks presence itself, before ESLint runs.
+
+Detection is generous and requirements are strict, on purpose. A directory counts as a paper only
+once it already holds one of the marker files, so `research/`, `plans/` and other neighbours in
+the corpus are left alone; an error-level check that fires on a correct tree gets switched off,
+and the real findings leave with it.
+
+```json
+"structure": {
+  "markers":      ["PIPELINE-STATUS.md", "paper.tex", "paper.md", "venue.json"],
+  "require":      ["PIPELINE-STATUS.md"],
+  "requireOneOf": [["paper.tex", "paper.md"]],
+  "ignore":       []
+}
+```
+
+Those are the defaults; you only write the block to change them. `paper.md` is still in them
+because Markdown papers are deprecated but not yet removed
+([#57](https://github.com/zernie/research-paper-pipeline/issues/57)). They were measured against a
+real five-paper corpus rather than chosen — it passes with zero findings, while adding
+`paper.pdf` to `require` produces two findings on papers that are perfectly fine, which is why it
+is not there.
+
+This is the half [ls-lint](https://ls-lint.org/) cannot do. ls-lint judges the **names** of files
+that exist; it has nothing to compare against for a file that does not. Use both: ls-lint for
+"what is there is named right", this for "what must be there is there".
+
+## How `paperlint build` compiles a paper
+
+`paperlint build <paper>` compiles `paper.tex` to `paper.pdf` itself, with TeX Live's `pdflatex` and
+`bibtex` ([`docs/toolchain.md`](toolchain.md)). There is nothing to configure and no script to
+write. It prints its plan first, one line per step, then runs it:
+
+```
+papers/my-paper
+  inputs: TEXINPUTS += <paperlint>/skills/submit-paper/references/venues
+  compile: paper.tex (\documentclass[sigconf,screen]{acmart}, venue agenticdev)
+  measure: pdf.js → _build/paper.facts.json (facts for the lint rules; nothing is judged here)
+  ✓ paper.pdf — 4 pdflatex passes, 1 bibtex run; facts: _build/paper.facts.json, last page 621.5 / 264.8 pt
+```
+
+- **inputs** — paperlint's own venue files (`paper-guards.tex`, `<venue>.tex`) are put on `TEXINPUTS`,
+  so `\input{paper-guards}` in a preamble resolves with no setup. The system tree still resolves
+  after them.
+- **compile** — `pdflatex -interaction=nonstopmode -halt-on-error -file-line-error`, then `bibtex`
+  when the `.aux` names a bibliography, then pdflatex again until the `.aux`, `.toc`, `.out` and
+  `.bbl` stop changing and the log stops asking for a rerun. bibtex runs again only when the cited
+  keys or a `.bib` file changed. After that, one **final** pass defines `\finalpass`, which arms
+  the reference guards in `paper-guards.tex`: an undefined `\ref` or `\cite` fails the build
+  there instead of printing `??`. A document that still changes after five passes fails, naming
+  the file that kept changing.
+- **measure** — after a green compile, the PDF is read with pdf.js and what it measures is written
+  to `_build/paper.facts.json`: the page count, every font the pages draw text with (and whether
+  its program is embedded, and whether it is Type 3), and the heights of the last page's two
+  columns — or why they were not measured (a stub page of a few lines, or a review build with
+  numbered lines). [banal](https://github.com/kohler/hotcrp/blob/master/src/banal) — installed by
+  `paperlint toolchain`, or a project's own `vendor/banal` or `$BANAL` — adds the page size, column count
+  and font sizes, measured from the same pdf.js read (no poppler; see
+  [`toolchain.md`](toolchain.md#page-geometry-banal-without-poppler)); without banal those fields
+  are `null` and the build says so. A PDF pdf.js cannot read fails the build. The file is
+  written by one function, which `skills/render-paper/extract-pdf-facts.mjs` also calls for PDFs
+  paperlint did not build. Keep `_build/` out of git: the facts carry the PDF's SHA-256, and a rule
+  refuses facts about a different PDF than the one on disk.
+
+The build does **not** judge the layout. A balanced last page, a page limit, the fonts a venue
+wants — those are verdicts about the finished PDF, and they belong to lint rules that can be
+turned on per venue, given a severity and suppressed with a reason. paperlint once searched for a
+`\balance` position itself and failed the build when none worked; that was removed on
+2026-09-24.
+
+The class and its options and the venue in `venue.json` are read from the paper and shown in the
+plan; later steps decide from them whether they apply.
+
+**`paper.pdf` is deleted before anything runs**, for every targeted paper — before the TeX Live is
+chosen and before the first step. So no outcome leaves an old PDF looking current: not a failed
+build, not a run that stops because there is no TeX Live with the packages the papers need, not a
+paper with no `paper.tex`. A green `✓ paper.pdf` therefore always means this run wrote it, and a
+pdflatex that exits 0 without writing one (a document with no pages) is a failure:
+
+```
+  ✗ compile: pdflatex exited 0 but wrote no paper.pdf — does the document have any pages?
+```
+
+**On failure** the command names the program that failed, quotes the first error line from the log
+with its `l.NNN` source context, and says the PDF is gone — the same line on every path that ends
+without a new one:
+
+```
+  ✗ compile: pdflatex exited with 1
+      ./paper.tex:6: Undefined control sequence.
+      l.6 Text before, then \undefinedmacro
+                                           {} after.
+      full log: papers/my-paper/paper.log
+      paper.pdf removed — a stale PDF must not pass for this build
+```
+
+**A paper with no `paper.tex` is a FAILURE, not a skip.** "Nothing to build" and "built" must never
+look alike: the corpus this came from once let a paper reach its venue without a single paper job
+having run on it, because a missing build read as nothing to do.
+
+`--dry-run` prints the plan and runs nothing — and deletes nothing, `paper.pdf` included.
+
+⚠️ **A `build.sh` or `repro/build-submission.sh` in the paper directory is IGNORED.** Earlier
+versions ran it; `paperlint build` now says one line — `build.sh is ignored — paperlint builds the paper
+itself` — and builds the paper itself. The `buildScripts` key is ignored the same way.
+Why: [#59](https://github.com/zernie/research-paper-pipeline/issues/59).
+
+## Using the rules from an existing ESLint config
+
+Under the hood `paperlint lint` builds an ESLint flat config and runs it. If your repository already
+lints with ESLint, you can import the rule modules from `paperlint/eslint-rules/`
+and wire them yourself; `bin/rpp.mjs` exports `buildConfig(options, texLanguage)` that returns
+the exact config the CLI uses, so the shortest path is:
+
+```js
+// eslint.config.mjs
+import { buildConfig } from "paperlint/bin/rpp.mjs";
+import { texLanguage } from "paperlint/eslint-rules/latex-language.mjs";
+export default buildConfig({ minFindings: 3 }, texLanguage);
+```
+
+Then point the CI action's `config` input at that file.

package/docs/e2e.md

@@ -0,0 +1,152 @@
+# End-to-end tests
+
+They are `test/e2e/install.mjs` and `test/e2e/build.mjs`. Both are
+part of `npm run check`, so nobody has to remember to call them. `npm run test:e2e` runs just
+these, install first; if the install e2e fails or is skipped, the build e2e does not run.
+
+This page says what they prove, what they deliberately do not, and when a change owes a new one.
+
+## The line between a harness and an end-to-end run
+
+Most of this package is tested by harnesses, described in [`CONTRIBUTING.md`](../CONTRIBUTING.md):
+a rule is handed a file with a defect and must find it, then a clean file and must stay silent.
+That is the right shape for a rule, and it cannot answer a different kind of question.
+
+A harness runs **in this repository's process, against this repository's working tree**. It
+imports the module directly. Every path resolves, every dependency is already installed, and the
+file it reads is the file in `git`. An end-to-end run exists because all three of those are
+assumptions that stop holding the moment somebody else installs the package.
+
+| question                                                                             | answered by                                               |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| does this rule find this defect, and stay quiet otherwise                            | harness                                                   |
+| does the CLI pick the right script, with the right interpreter                       | harness (`src/build.harness.mjs` substitutes `spawnSync`) |
+| does the tarball, installed into a tree that is not this one, contain what it claims | **e2e**                                                   |
+| do the paths written inside a skill resolve where the package actually lands         | **e2e**                                                   |
+| did a PDF come out, and is it typeset in the fonts the venue requires                | **e2e**                                                   |
+
+The third and fourth rows are the ones a harness cannot reach even in principle: the defect only
+exists once the code is somewhere else.
+
+## `test/e2e/install.mjs` — the package, installed
+
+`test/e2e/install.mjs`. It runs `npm pack`, then installs the resulting tarball into a fresh
+temporary tree, **under npm and under pnpm separately**, and drives the installed binary:
+
+- the install itself finishes
+- `paperlint --help` answers with zero
+- `paperlint init` declares the papers directory in `package.json`, and does _not_ leave a second
+  carrier `rpp.json` behind
+- `paperlint init` finishes with zero — its doctor found no discrepancy
+- `paperlint init` wires the hooks into `.claude/settings.json` — the same commands `hooks.json`
+  publishes, once each — and says they need `npm install` in a fresh clone; a second `init`
+  leaves that file byte-identical
+- `paperlint lint` passes the staged corpus
+- `paperlint new demo` scaffolds a paper from the templates that shipped in the tarball, its own lint is
+  clean, and `paperlint lint` stays clean with it in the corpus
+- `hooks.json` arrived and parses, and every hook command named in it resolves to a file
+- every skill arrived, and every script path named inside a skill resolves **in the consumer**
+
+The last two rows are the reason this file exists. A skill is a markdown document with paths in
+it; nothing in this repository's own test run would notice that those paths only work here.
+
+🔴 **Two package managers, not one, and it is not belt-and-braces.** The wiring addresses the
+runtime from the project root, and pnpm does not put transitive dependencies at the root. A layout
+that works under npm can be dead under pnpm with no error anywhere. The same run also launches the
+binary **directly** rather than through `node <path>`: under npm `.bin` holds a symlink, under
+pnpm a shell wrapper, and calling `node bin` measures the caller's habit instead of the package.
+
+## `test/e2e/build.mjs` — a real `pdflatex`
+
+`test/e2e/build.mjs`. It copies `fixtures/build-e2e/` — eight papers, none with a build script paperlint
+would run — into a temporary tree, points a config at it, and runs `paperlint build --all`. paperlint compiles
+each paper itself with the real `pdflatex` and `bibtex`; the artifacts are then measured with
+paperlint's own pdf.js reader from `dist/`, and the fonts are cross-checked against the list of
+programs pdfTeX writes into `paper.log`:
+
+| fixture      | what it is there to prove                                                                                                                                                                                                                                                                        |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `acmart`     | a real `\documentclass{acmart}` source builds, and the PDF carries the class's **own** font families — not one family of the silent substitution                                                                                                                                                 |
+| `fallback`   | the same document with the fonts missing still **builds green**, and is **rejected** by the font check. The failure is in the artifact, not in the exit code                                                                                                                                     |
+| `cite`       | the bibtex path: the PDF shows `[1]`, not `[?]`, and no `??`. Its `build.sh` would leave a trace if run — it must not run, and the run must say it is ignored                                                                                                                                    |
+| `guards`     | `\input{paper-guards}` resolves with no configuration, because paperlint puts its own venues directory on `TEXINPUTS`                                                                                                                                                                            |
+| `unbalanced` | a two-column acmart paper whose last page comes out 621.5 / 264.8 pt builds **green** — the build does not judge the layout and rewrites nothing — while `_build/paper.facts.json` records both heights, and `paperlint lint` with `pdf/last-page-balance` turned on in `rules` reports the page |
+| `broken`     | a failing build names pdflatex and its exit code, quotes the error line and its `l.NNN` context, and deletes the stale `paper.pdf` planted before the run                                                                                                                                        |
+| `no-source`  | a paper with no `paper.tex` is named separately, and the run as a whole is a failure                                                                                                                                                                                                             |
+
+The `fallback` row is the point of the whole file. `acmart.cls` checks for `libertine.sty`,
+`zi4.sty` and `newtxmath.sty`, and failing to find any of them sets `\@ACM@newfontsfalse` and
+typesets the paper in Computer Modern. The build is green, the PDF looks fine, the metrics differ,
+and therefore so does the pagination. A submitted paper went out that way. **An exit code cannot
+see it, so the content of the artifact is what gets measured.**
+
+Before the fixtures, the run proves the refusal with no TeX at all: PATH holds `node` alone, the
+cache directory is empty and `CI` is set, and `paperlint build` must exit 1 with one line naming
+`npx paperlint toolchain` and the venue's packages, print no plan and create no PDF and no cache. It then
+asks `paperlint build --dry-run` which TeX Live the real run will use; under `--strict` (CI) that must be
+paperlint's own cache, because the runner has no other.
+
+## `test/e2e/toolchain.mjs` — real TeX Live, and only it
+
+`paperlint toolchain` into `$RPP_TEXLIVE_DIR` against real CTAN; a second run must say "nothing to do"
+within seconds; `--check` must exit 0; then the `acmart` fixture is built with PATH holding `node`
+only, so no other TeX Live and no PDF tool can stand in, and the PDF must carry Libertine and Biolinum
+and no Computer Modern face. Without `RPP_TEXLIVE_DIR` it is a declared skip: installing ~270 MB
+into a home directory as a side effect of `npm run check` is the unasked install rule 11 forbids.
+`src/toolchain.harness.mjs` covers the installer's logic (mirror fallback, archive check, time
+limit, verification, idempotence) against a fake mirror on disk, without the network.
+
+## Skips are declared, never silent
+
+A clone without TeX Live genuinely cannot run the build e2e; a machine without pnpm cannot run
+half of the install e2e. Each says so and exits **77** — the skip code vigiles' own runner uses —
+not zero, and `npm run check` reports it as `SKIPPED — not run, not passed`. In CI the same absence
+means a broken environment, so `--strict` turns the skip into a failure.
+
+A skipped step and a passed one look identical in a CI interface. That is the class this whole
+package is written against, so it is not allowed to happen inside it either.
+
+## When a change owes an e2e
+
+Not every change does. The trigger is countable — ask whether the change touches something that is
+**only true after installation**:
+
+- a new file or directory that has to arrive on the consumer's disk (a skill, a hook, a template)
+- a path written inside a document rather than resolved by a module loader
+- anything read through `package.json` fields — `bin`, `files`, `exports`
+- a new external program the pipeline shells out to
+- a new artifact the pipeline produces whose **content** can be wrong while the exit code is zero
+
+If none of those apply, a harness beside the changed module is the right test, and an e2e run
+would only make the suite slower without making it stricter.
+
+## What these two do NOT cover
+
+Named here on purpose: a test suite that does not say where it stops is read as covering
+everything.
+
+- **macOS and Windows.** Locally these run on whatever machine you have. In CI `build-e2e` is a
+  matrix over `ubuntu-latest` and `macos-latest`; Windows is not run anywhere, and `paperlint toolchain`
+  refuses it.
+- **The rules, on a real document.** `fixtures/real-markdown-paper/` holds a published article and
+  a recorded baseline of what the rules say about it. That is a **lint** fixture, driven by a
+  harness — it does not go through the installed package. Wiring it into the install corpus is
+  open work, not something already done.
+- **The skills as behaviour.** The install run proves a skill arrived and that its paths resolve.
+  Whether the agent then does the right thing with it is a different measurement, and it belongs
+  to the harness tier of `vigiles`, not here.
+- **Registry publication.** The package is on npm: `research-paper-pipeline@1.0.0` was published
+  on 2026-09-25 by `.github/workflows/release.yml`; from 2.0.0 it is published as `paperlint`, the
+  same way. The
+  e2e still covers the packlist through `npm pack`, which produces the same tarball `npm publish`
+  uploads; the registry round-trip — install from npm, then run — is still not run by any test.
+
+## The corpus
+
+`stageCorpus()` in `test/e2e/install.mjs` writes a small paper by hand — a declared stage, its
+PDF, its byte counts, the cross-check between them — and copies `fixtures/build-e2e/acmart` beside
+it so the LaTeX rules see LaTeX rather than a placeholder.
+
+⚠️ **Every line of that corpus was written by somebody who already knew which rule would read it.**
+It keeps the stage machinery honest and it cannot tell you anything about false positives. That is
+what the real-article fixture is for, and why the two tiers are not substitutes.

package/docs/incidents.md

@@ -0,0 +1,59 @@
+# Incidents — the measurements the rules stand on
+
+`CLAUDE.md` is loaded on every turn, so it carries **the claim and the remedy** and nothing
+else. The measurement that produced a rule lives here, and is read only when someone argues
+with the rule or wants to know how it was found.
+
+Two things never move into this file: a measurement that **is** the rule (rule 5's table of
+claims that fell to one command — without it the rule reads "measure things", which nobody
+obeys), and evidence that already lives in a code comment beside the code it explains. Those
+get a pointer, never a copy.
+
+Entries are append-only and dated. A superseded entry is marked, not deleted.
+
+---
+
+## 2026-09-17 — four fixes proposed and withdrawn in one session (rule 9)
+
+Each was proposed before the defect it claimed to fix had been exhibited, and each fell to a
+single command:
+
+| proposed                                       | what one command showed instead                                                                                             |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| a new `skip` API in the test runner            | the existing classification had never been shown to be wrong                                                                |
+| a `link` subcommand as the single install path | this package is consumed three ways, and a plugin cannot serve two of them                                                  |
+| "one delivery channel instead of two"          | the channels carry different things: eight ESLint imports and a composite action on one side, skills and hooks on the other |
+| "symlinked skills are our own invention"       | the documentation describes them, and third-party repositories install exactly that way                                     |
+
+Two of the four were demolished by an adversarial second pass **before** either was built. A
+third pass over six claims about the plugin channel corrected four of them — including a count
+attributed to the wrong file (110 was one script's occurrences; the prefix has 208 across 190
+lines) and a "nothing is installed" claim that was false in the consumer, where 54 symlinks
+make the path resolve.
+
+Cost of the pattern: the four proposals took more of the session than the work they proposed.
+
+## 2026-09-17 — the install-location class, four silent breakages (rule 10)
+
+One class — _code that knows where it is on disk_ — has broken this repository four times, and
+not one of the four announced itself:
+
+| when             | what was assumed                                                                                                        | how it failed                                                                                                                |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| until 2026-08-15 | `resolve(HERE, "..", "skills")`, correct while the code lived beside the skills                                         | a hash over a missing directory is stable, so every verdict read FRESH forever, with no error                                |
+| 2026-09-12       | the same walk, after the move into a package                                                                            | broke the same way, in the same silent direction                                                                             |
+| 2026-09-12       | the ledger defaults to a file beside its own module                                                                     | inside `node_modules`, which `npm ci` deletes: appending SUCCEEDS, so rows look recorded until the next install removes them |
+| 2026-09-17       | skills name their scripts by an install-specific path — 208 literals across 190 lines, in bodies and in `allowed-tools` | resolves through a symlink for one consumer and does not exist for another                                                   |
+
+The first three are documented in the code they broke, and that is where the detail stays:
+`skills/paper-pipeline/scripts/ledger.mjs` (the three rungs) and
+`skills/paper-pipeline/scripts/consumer.mjs` (`ledgerPath`, three steps).
+
+🔴 The load-bearing observation is not the count. All four repetitions happened **while
+comments explaining the exact hazard sat directly above the code** — which is why rule 10 owes
+a lint rule and not another paragraph.
+
+A fifth instance of the same class was measured the same day and is not yet fixed: the guard
+in `ledgerPath` asks `insideNodeModules(hereDir)`, and a plugin cache is not `node_modules`, so
+a plugin-only consumer without a `package.json` gets its ledger written into the cache — which
+the documentation says changes when the plugin updates.