paperlint 2.0.0

package/docs/prior-art/blocking-vs-advisory.md

@@ -0,0 +1,83 @@
+# Who decides to fail the run — the rule, or the runner?
+
+**Question this file answers:** when a check finds something, what decides whether the build
+goes red: a property of the check, or a decision of whatever invoked it?
+
+**Verdict:** in every tool examined, severity is **data attached to the finding or the rule**,
+and the decision to fail is made by the **runner**. No tool examined lets a check decide, in its
+own body, that the process must stop.
+
+---
+
+## Danger JS — the closest analogue, because it lints the PROCESS
+
+Danger exists to check facts about a change rather than about code: did you update the
+changelog, is this PR too large, does it touch a file that requires a second reviewer. That is
+the same family as "a paper declares a submitted stage but no frozen PDF is on disk".
+
+Its levels are not a severity field — they are **four separate functions**:
+
+| function     | effect                       |
+| ------------ | ---------------------------- |
+| `fail()`     | declares a CI-blocking error |
+| `warn()`     | reports, does not block      |
+| `message()`  | adds a row to the table      |
+| `markdown()` | free-form output             |
+
+So the author of a check chooses the level **at the call site**, and the level is structural
+rather than a string somebody parses later.
+
+Source: <https://danger.systems/js/reference.html>
+
+## reviewdog — non-blocking by default, failing is the runner's flag
+
+reviewdog ingests diagnostics from any linter and posts them as review comments.
+
+> By default Reviewdog will return 0 as exit code once all actions done (linter report
+> analyzed, comments posted and so on). Once `fail-on-error` flag passed — Reviewdog will
+> return 1 as exit code if at least one violation was found/reported.
+
+The important part is **where the flag lives**: on the invocation, not on the rule. The same
+rule set is advisory in one pipeline and blocking in another without editing a rule.
+
+A recurring complaint is worth recording because it is a design warning, not a bug report:
+when `--fail-on-error` is enabled, reviewdog fails on **any** result regardless of the
+diagnostic level — people did not want an `info` diagnostic to turn the build red. In other
+words: a single global "fail on anything" switch is too coarse once levels exist at all.
+
+Sources: <https://github.com/reviewdog/reviewdog> ·
+<https://github.com/reviewdog/reviewdog/issues/856>
+
+## ESLint — severity is a value in the config, keyed by rule id
+
+The model this package already consumes. `off` / `warn` / `error` sit in the config against a
+rule **identifier**; the rule body never decides. `error` is what makes the process exit
+non-zero. The severity of a rule can be changed without touching the rule.
+
+## Clippy — four levels, per lint, overridable
+
+`allow` / `warn` / `deny` / `forbid`, set per lint and overridable on the command line
+(`-D warnings` being the familiar CI incantation). Again: the lint declares a default, the
+invoker decides.
+
+---
+
+## What this means for this package
+
+1. **A finding must be a record, not a rendered string.** `{ rule, severity, where, message }`.
+   Anything that reads severity out of the message text — an emoji, a prefix, a keyword — is
+   the same defect as parsing prose for a fact: it works until someone rewrites the sentence.
+
+2. **The blocking decision belongs to the entry point.** `rpp lint` in CI may exit non-zero on
+   `error`; an editor hook running the same rules should not block at all. Same rules, two
+   policies, no rule edited.
+
+3. **A single "fail on anything" switch is not enough** once more than one level exists — the
+   reviewdog complaint above is exactly that lesson, reported by its users.
+
+4. **Default to not blocking.** This is also the house position for a separate, measured
+   reason: a gate that fails on taste gets routed around, and once people route around a gate
+   they stop reading the binary findings it also carried.
+
+See also: [`nondeterministic-checks.md`](nondeterministic-checks.md) — a check whose verdict can
+change without the file changing is a check that must not block, whatever its severity.

package/docs/prior-art/content-delivery.md

@@ -0,0 +1,124 @@
+# How tools ship installable CONTENT, not just code
+
+**Question this file answers:** this package carries 26 skills (2.9 MB of markdown an agent
+reads) alongside its rules and its CLI. How do comparable tools deliver content that is neither
+code nor configuration — styles, extensions, presets — and what do they refuse to do?
+
+**Verdict:** the tools that do this well **declare the content in the config and fetch it with
+an explicit command**. None of them silently bundle a large content tree into the tool itself,
+and none of them rely on the user's file layout matching a path the content hard-codes.
+
+---
+
+## Vale — the closest analogue, because its content IS the product
+
+Vale is a prose linter whose rules are not compiled in: a _style_ is a folder of YAML rules, and
+published styles (Google, Microsoft, Red Hat) are installed rather than vendored.
+
+The declaration lives in `.vale.ini`:
+
+```ini
+StylesPath = styles
+MinAlertLevel = suggestion
+
+Packages = Google, write-good
+
+[*.md]
+BasedOnStyles = Vale, Google
+```
+
+and one command fetches what the config asked for:
+
+```console
+$ vale sync
+```
+
+Three properties worth stealing:
+
+- **The config names the content; the command fetches it.** There is no step where the user
+  copies a folder, and no step where the tool guesses.
+- **`StylesPath` is declared by the consumer**, so the content does not need to know where it
+  will land.
+- **A style is versioned and shareable independently of the binary.** Updating a style is not a
+  release of Vale.
+
+Sources: <https://vale.sh/> · <https://github.com/vale-cli/vale>
+
+## Quarto — extensions as a first-class verb pair
+
+Quarto is the closest _domain_ analogue (scientific publishing: `render`, `preview`, `check`,
+`publish`, `create`). For content it uses two verbs:
+
+- `quarto add <extension>` — install an extension into the project
+- `quarto use <template>` — start from a template that an extension provides
+
+Project configuration lives in one place, `_quarto.yml`. The extension mechanism covers
+filters, output formats and templates — that is, all three of "transform my document",
+"produce this venue's format" and "start me from this skeleton" go through the same door.
+
+Source: <https://quarto.org/docs/reference/>
+
+## ESLint — shareable configs as ordinary packages
+
+The pattern this package already lives inside. A shareable config is a normal npm package that
+the consumer installs and names in their config; nothing is copied into the consumer's tree and
+no path inside the config assumes where the consumer put it. Resolution is the module system's
+job, which is precisely why it survives pnpm, yarn and npm layouts.
+
+## pre-commit — hooks declared, fetched, pinned
+
+```yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.4.2
+    hooks:
+      - id: black
+```
+
+The consumer declares a repository, a **revision**, and which hooks to enable; the tool clones
+and caches it. The lesson is the `rev:` field — content delivered from elsewhere is **pinned**,
+so an upstream change cannot alter today's run.
+
+---
+
+## What this means for this package
+
+The measured problem this file exists for: the plugin channel carries **zero skills**.
+`marketplace.json` points at `plugin/`, which contains `plugin.json` (with no `skills` key) and
+`hooks/hooks.json` — while `README.md` claims the install brings "all 24 skills". Separately,
+**113 literal paths** of the form `.claude/skills/paper-pipeline/scripts/<x>.mjs` are written
+inside the skills' own prose.
+
+Read against the four tools above, those are one problem, not two:
+
+1. **The content hard-codes where it expects to live.** No tool above does this. Vale's styles
+   do not know `StylesPath`; an ESLint shareable config does not know the consumer's directory.
+   A path inside the content is a bet on one installation channel, and there are two.
+
+2. **There is no declared-and-fetched step.** Today the content arrives by being _inside_ the
+   package (npm) or by not arriving at all (plugin). Neither is `vale sync`: a line in the
+   config plus one command.
+
+3. **Nothing pins the content** the way `pre-commit`'s `rev:` does.
+
+➕ **Correction, 2026-09-19.** Point 1 above stands; the framing around it does not. The
+`README.md` sentence this note quoted — "that installs all 24 skills" — has been fixed, and the
+plugin carrying no skills turns out to be **deliberate and forced**, not an oversight: a plugin
+fetched from npm gets no `node_modules`, so a plugin that shipped the skills would ship scripts it
+could not run. The npm door delivers the skills; the plugin door delivers the hook wiring. What
+remains a real problem is the paths written inside the skills.
+
+Three directions follow, and they are genuinely different bets rather than one idea:
+
+- **One channel.** Skills ship only through npm; the plugin carries hooks and says so. Cheapest;
+  gives up the plugin's discovery story.
+- **Content is fetched, not bundled.** `rpp` declares which skill pack a project wants and a
+  command materialises it into a path the consumer declared. Closest to Vale; costs a fetcher
+  and a cache.
+- **Content is addressed, never pathed.** Skills stop naming filesystem locations and call the
+  CLI instead (`rpp <verb>`), so the same prose works in both channels. Attacks the root cause;
+  costs a pass over 113 sites and a rule that keeps them from coming back.
+
+See also: [`multi-mode-tools.md`](multi-mode-tools.md) for how these verbs sit beside `lint` and
+`build`, and `CONTRIBUTING.md` § "Why not one of the existing academic skill suites" — that
+section answers a different question (should this exist), not this one (what shape it takes).

package/docs/prior-art/multi-mode-tools.md

@@ -0,0 +1,106 @@
+# When one tool is a linter AND a builder AND an extension host
+
+**Question this file answers:** this package is four things at once — a linter over papers, a
+build front-end, a host for agent hooks, and a carrier of 26 skills. Tools that carry a
+comparable mix exist. How do they keep the command surface small, and where do they draw the
+line between a verb and a flag?
+
+**Verdict:** the tools that feel small do not have fewer capabilities — they have **fewer
+NOUNS**. Capability is reached by a verb over a project that the config already describes; what
+would be a second noun becomes a flag or disappears into the config. The tools that feel large
+are the ones where the user must name, on the command line, a thing the project already knows.
+
+---
+
+## Biome — the "one tool, one config, one command" position, stated by its authors
+
+> Biome unifies functionalities that have previously been separate tools. Building upon a shared
+> base allows it to provide a cohesive experience for processing code, displaying errors,
+> parallelize work, caching, and configuration.
+
+The user-facing consequence is a single default verb:
+
+```console
+$ biome check .          # format + lint + organize imports
+$ biome check --write .  # and fix what is fixable
+```
+
+Formatting and linting remain available separately, but the advertised path is one command.
+Note what this costs: `check` is doing three jobs, so its _output_ has to be legible enough to
+tell them apart. Merging verbs pushes the burden onto the report.
+
+Sources: <https://biomejs.dev/> · <https://github.com/biomejs/biome>
+
+## Quarto — the domain analogue, and its verbs are all about the PROJECT
+
+```console
+$ quarto render          # produce outputs
+$ quarto preview         # live preview
+$ quarto check           # validate the installation and its dependencies
+$ quarto create          # start a project or document
+$ quarto publish         # deploy
+$ quarto add <ext>       # install an extension
+$ quarto use <template>  # start from an extension's template
+```
+
+Two things to steal, and one to notice:
+
+- **`check` means "is my toolchain sane", not "is my document good".** That is a different
+  meaning from `biome check` and from this package's current `doctor`. Whichever meaning is
+  chosen, only one can be in play.
+- **Extensions get their own verb pair** (`add` / `use`) rather than being wired by hand.
+- Configuration lives in one file, `_quarto.yml`, and the verbs above almost never take a path —
+  the project says what it contains.
+
+Source: <https://quarto.org/docs/reference/>
+
+## What the small-surface tools have in common
+
+| tool   | verbs a user types weekly   | where the nouns went                  |
+| ------ | --------------------------- | ------------------------------------- |
+| Biome  | `check` (and `--write`)     | config declares includes/excludes     |
+| Quarto | `render`, `preview`         | `_quarto.yml` declares the project    |
+| Vale   | `vale <paths>`, `vale sync` | `.vale.ini` declares styles and scope |
+
+And the recurring shape: **one verb for the routine loop, one verb for "make my environment
+match the declaration", and everything else rare.** Vale's `sync`, Quarto's `add`, and a
+hypothetical `rpp install` are the same slot.
+
+## This package today, measured 2026-09-19
+
+```
+npx rpp init [dir]              set the project up
+npx rpp lint [paths…]           run every rule over your papers
+npx rpp build <paper> | --all   build a paper with its own build script
+npx rpp doctor                  say what is actually wired — and what only LOOKS wired
+npx rpp hook <name>             run an editor hook (the plugin wiring calls this)
+```
+
+Read against the table above:
+
+- `lint` takes `[paths…]` **and** the config declares `papers`. Two ways to say the same thing;
+  the help text already has to explain which wins.
+- `build` takes `<paper>` or `--all` — a noun the project could supply, exactly the shape the
+  small-surface tools removed.
+- `hook <name>` is **not a user verb at all**: it exists because the plugin wiring calls it.
+  Nobody types it. It is an entry point wearing a command's clothes.
+- `doctor` and a possible `check` would collide in meaning unless one of them is renamed — see
+  the Quarto note above.
+
+So the honest count of verbs a researcher types is **two** (`lint`, `build`), one is setup
+(`init`), one is diagnostics (`doctor`), and one is machine-facing (`hook`). That is not a large
+surface — but it is presented as five equals, which makes it read larger than it is.
+
+---
+
+## Open questions this file does not settle
+
+- Whether `lint` and `build` should merge into one routine verb the way `biome check` did, and
+  what that costs the report.
+- Whether the machine-facing entry point should be hidden from `--help` entirely, or moved
+  behind a subcommand namespace.
+- What `check` should mean here if it is introduced — toolchain sanity (Quarto) or the routine
+  pass (Biome). Both are taken; picking either forfeits the other.
+
+See also: [`content-delivery.md`](content-delivery.md) for the `add` / `sync` slot, and
+[`blocking-vs-advisory.md`](blocking-vs-advisory.md) for what each verb should exit with.

package/docs/prior-art/nondeterministic-checks.md

@@ -0,0 +1,99 @@
+# Checks whose verdict can change without the file changing
+
+**Question this file answers:** a linter is normally a pure function of a file's bytes. Some
+useful checks are not — they read the clock, compare modification times, or need a before/after
+pair. Do real tools ship such checks, and how do they contain the damage?
+
+**Verdict:** yes, they exist and they are respectable — but the tools that ship them
+(a) make the non-deterministic condition **opt-in**, (b) **suppress it** in the context where it
+would block someone who cannot fix it, and (c) **prefer a condition over recorded data** to a
+condition over the clock wherever both are possible. Two of the three shapes below dissolve
+entirely once the fact is recorded rather than inferred.
+
+---
+
+## Shape 1: the clock — `unicorn/expiring-todo-comments`
+
+The canonical time-dependent lint rule. A comment carries an expiry and starts being reported
+once it passes:
+
+```js
+// TODO [2018-05-01]: Do this thing
+```
+
+Two defaults are the whole lesson:
+
+- **`checkDates` defaults to `false`.** The date condition — the only non-deterministic one —
+  ships switched off.
+- **`checkDatesOnPullRequests` also defaults to `false`.** Even with dates enabled, the rule
+  does not fire on pull requests, so the person blocked is the maintainer who wrote the TODO,
+  not a contributor who merely touched the file.
+
+And the shape of the rest of the rule is the real argument. Of its six conditions, **five are
+over declared data** and only one is over the clock:
+
+| condition                   | example                     | deterministic?             |
+| --------------------------- | --------------------------- | -------------------------- |
+| package version             | `[>1]`                      | yes — reads `package.json` |
+| engine version              | `[engine:node@>8]`          | yes                        |
+| dependency present / absent | `[+package]` · `[-package]` | yes                        |
+| dependency version          | `[package@>1]`              | yes                        |
+| peer dependency version     | `[peer:eslint@>9]`          | yes                        |
+| **expiry date**             | `[2018-05-01]`              | **no**                     |
+
+There is a standing issue titled "failing the lint on a date may be inconvenient", which is the
+community arriving at the same discomfort from the other direction.
+
+Sources:
+<https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/expiring-todo-comments.md>
+· <https://github.com/sindresorhus/eslint-plugin-unicorn/issues/1541>
+
+## Shape 2: the before/after pair — Semgrep `--baseline-commit`
+
+A check that wants to see what a change _did_ seems to need an event. It does not.
+
+> A diff-aware scan runs on your code before and after some "baseline" and only reports findings
+> that are newly introduced in the commits after that baseline.
+
+The same deterministic analysis is run on two revisions and the results are subtracted. Nothing
+in the rule knows about events; the _runner_ supplies two inputs.
+
+The cost is that the second input comes from git history, which brings its own constraint: a CI
+checkout that fetches one commit cannot produce a baseline. That is a property of the pipeline,
+not of the rule, and it has to be arranged deliberately.
+
+Sources: <https://semgrep.dev/docs/semgrep-ci/findings-ci> · <https://semgrep.dev/docs/cli-reference>
+
+## Shape 3: modification times — and this one is not a lint at all
+
+Comparing the mtime of a built artefact against the mtime of its source is what a **build
+system** does (`make`, `ninja`). It is non-deterministic in the way that matters here: a fresh
+clone gives every file the same checkout timestamp, so the verdict changes without any content
+changing.
+
+The fix is not to accept the non-determinism but to **record the fact**: store a content hash of
+the source alongside the artefact, and the question "is this build stale?" becomes
+`sha256(source) !== recorded`, which is pure, file-only, and expressible as an ordinary rule.
+
+---
+
+## What this means for this package
+
+1. **Prefer a recorded fact to an inferred one.** Wherever a check currently reasons about
+   _when_ something happened, ask whether the paper can simply declare _what_ it was built from.
+   A stage that records `source_sha256` turns two separate staleness checks into byte
+   comparisons.
+
+2. **A hash of CONTENT, not a git object.** A commit id is a pointer that history rewriting,
+   garbage collection and shallow clones can all invalidate; the bytes cannot. If the check is
+   about the file, the recorded fact must be about the file.
+
+3. **If a check must stay non-deterministic, it must not block, and it should be opt-in.**
+   That is what `checkDates: false` encodes, and the reasoning transfers unchanged.
+
+4. **A diff-shaped check has two legitimate homes** — a runner that supplies two revisions
+   (Semgrep's model), or an editor/agent hook, which is handed the before and after of a single
+   edit for free and needs no git at all. The second is not a workaround for a missing
+   mechanism; it is using the event source that exists.
+
+See also: [`blocking-vs-advisory.md`](blocking-vs-advisory.md).