paperlint 2.0.0

package/.github/dependabot.yml

@@ -0,0 +1,72 @@
+# Dependency updates by bot, not by hand.
+#
+# WHY A BOT AT ALL, not runtime version checks: an update IS AN ACTION,
+# and the bot creates a pull request you can press. A terminal line
+# saying "something newer exists" is not an action; it gets forgotten in a day. The local gate
+# `npm ls vigiles` in the consumer solves a DIFFERENT problem — "installed does not match manifest" —
+# and knows nothing about freshness against the registry: measurement 2026-09-16 — manifest `^27.1.4`
+# with 27.1.6 and 27.2.0 in the registry gives RC=0, the range is satisfied.
+#
+# WHY THIS IS ALLOWED HERE, though the bot is off in a neighboring repository: that one is
+# PRIVATE, and its runs ate the shared Actions quota. This one is
+# public, free-tier minutes are free, so that objection does not apply here. If it becomes private,
+# the rule changes with it.
+#
+# 🔴 WHAT THIS FILE DOES NOT GOVERN, and we have tripped on this: it controls only
+# version updates. SECURITY updates are a separate mechanism and a separate
+# REPOSITORY SETTING (Settings → Advanced Security), their frequency and
+# grouping cannot be changed from here. If single PRs for indirect
+# dependencies start appearing — look for the lever there, not in this file.
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    # MONTHLY. It used to be daily so that new vigiles releases arrived fast, but we bump
+    # vigiles by hand in the same pass that merges a vigiles PR, so the bot was only ever
+    # catching up with what we had already done. Once a month is the pace someone reads.
+    #
+    # 🔴 SCHEDULE IS NOT THE ONLY DELAY, and the second one is easy to miss: version
+    # updates have a COOLDOWN, defaulting to 3 days — "a new version is not
+    # considered for a version update until 3 days after its release". It is NOT
+    # removed deliberately: three days is protection against a just-revoked release, and
+    # we learn about our own versions before the bot anyway (vigiles is our package, bumped
+    # in the same pass where we merge PRs). Net window ~3-4 days.
+    #
+    # ⚠️ Publishing to the registry does not wake the bot — it runs on schedule only.
+    # For immediate check: Insights -> Dependency graph -> Dependabot -> Check for updates.
+    schedule:
+      interval: "monthly"
+      time: "06:00"
+      timezone: "Asia/Almaty"
+    # 🔴 OUR OWN PACKAGE IS EXEMPT FROM COOLDOWN, answering a specific objection:
+    # we can release multiple vigiles versions in a day, and a three-day
+    # default wait would mean the bot offers yesterday's.
+    # The wait exists as protection against a just-revoked release — for
+    # SOMEONE ELSE'S package that is sound; for our own, it is pointless: we will revoke it ourselves.
+    cooldown:
+      default-days: 3
+      exclude: ["vigiles"]
+
+    # One PR for the whole dev tree instead of a PR per package. Without this, the first
+    # week yields four separate CI runs and four reviews for one piece of work.
+    groups:
+      dev-dependencies:
+        patterns: ["*"]
+    open-pull-requests-limit: 2
+    commit-message:
+      prefix: "deps"
+    labels: ["dependencies"]
+
+  # Versions of GitHub Actions themselves go stale silently and are only noticed when
+  # the runner drops a warning about old Node.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      actions:
+        patterns: ["*"]
+    open-pull-requests-limit: 1
+    commit-message:
+      prefix: "ci"
+    labels: ["dependencies"]

package/.github/workflows/ci.yml

@@ -0,0 +1,297 @@
+# CI for paperlint — ONE job, every gate, bonds set BY MEASUREMENT.
+#
+# ── WHY ONE JOB ─────────────────────────────────────────────────────────────
+# Parallelism does not save billable minutes, it ADDS them: every job pays for its own
+# setup + checkout + install (~20-30 s). Splitting is worth it for signal isolation on a big
+# matrix; here the whole suite is 84 seconds, so a second job would cost more than it isolates.
+#
+# ⛽ THIS REPOSITORY IS PUBLIC, so its minutes are FREE — they do not touch the account's
+# 3000/month quota (verified against the API 2026-09-12: `"private": false`). The header said
+# PRIVATE until then, which was true when written and is the reason the gates were measured
+# rather than guessed. Keep measuring them anyway: the bond exists to stop a HANG, and a hang
+# costs wall-clock and a red check whether or not anyone is billed.
+#
+# ── THE MEASUREMENT THE BONDS COME FROM (local, 2026-09-12) ─────────────────
+#   npm test (12 harnesses)              11 s
+#   npm run lint (eslint over fixtures)   1 s
+#   rules-see-files.mjs                   1 s
+#   vigiles lint                          3 s   ← added 2026-09-12 with the first ten skills
+#   run-mutations.mjs (12 batteries)    242 s   ← 130 mutations, the expensive and load-bearing part
+#   ───────────────────────────────────────────
+#   total work                          ~255 s, plus checkout + install
+#
+# 🔴 THE PREVIOUS NUMBERS ARE KEPT NOWHERE BUT THIS SENTENCE, ON PURPOSE: they said ~84 s total
+# with `timeout-minutes: 8`, i.e. a ~2.7× bond. The pipeline's checkers arrived on 2026-09-12 and
+# tripled every count — 4 harnesses became 12, 45 mutations became 130 — which would have left an
+# 8-minute bond at ~1.3× of a ~6-minute run. A bond that tight fails on a slow runner and reads
+# as a broken suite rather than as a bond. Re-measure when the counts move again; do not cite the
+# table above without re-running it.
+#
+# Expect ~6 minutes warm. `timeout-minutes: 20` is ~3.3×, and `npm ci` carries its OWN bond
+# because a job-level bond cannot tell "the registry hung" from "the suite is slow" and so hands
+# a hang the whole job.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  # 🔴 `types:` FULLY ENUMERATED, INCLUDING DEFAULTS. As soon as this key is declared, the defaults
+  # (`opened`, `synchronize`, `reopened`) DISAPPEAR; forgetting them would disable CI on PR pushes,
+  # and the only way to notice would be by the absence of a run, i.e., silence.
+  # `ready_for_review` is not a default either, and without it the draft gate below would work only
+  # halfway: marking a draft ready is none of the defaults, so the PR would reach the merge button
+  # with zero checks. macOS is a cell of the build-e2e matrix below.
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+# A newer push supersedes an older one on the same ref. Note this does NOT make the cancelled
+# run free — cancellation arrives after the expensive steps have already run and been billed —
+# it only stops the tail. (Until 2026-09-23 the key also split on `labeled` events, because a
+# label click used to cancel the code run; with no `labeled` trigger that split has nothing to do.)
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    # 🔴 A DRAFT PULL REQUEST PAYS NOTHING (same gate as vigiles and the knowledge base). Written as
+    # `event_name != 'pull_request' || draft == false`, not `draft == false` alone: on a push to main
+    # there is no pull_request object, and a bare `.draft` would be missing and kill every check there.
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          # The floor: engines.node is >=22.13, so the gates run on 22. build-e2e runs 24.
+          node-version: 22
+          cache: npm
+
+      # 🔴 ITS OWN BOND. This is the only step that talks to the network, and a hung registry is
+      # indistinguishable from a slow suite at the job level. Measured in the consumer repo:
+      # a `npm ci` without its own bond once held a job for five minutes on a slow mirror.
+      - name: npm ci
+        run: npm ci
+        timeout-minutes: 5
+
+      # Harnesses. `--min=1` is inside the script: it refuses a run where NOTHING matched.
+      #
+      # 🔴 WHAT IT DOES NOT DO, contrary to what was written here before 17.09: it does NOT protect
+      # against a directory in the argument. Measurement: `npx vigiles test . --min=1` → `0 passed, 1 skipped`,
+      # **RC=0** — the directory exists, discovery treats it as a file, and it counts toward the
+      # minimum. The prior version called `--min=1` "load-bearing" precisely against this case,
+      # i.e., claimed a protection that does not exist. Protection against this case comes from `--no-skip` below.
+      # 🔴 THE `claude` CLI IS A TEST DEPENDENCY HERE, and its absence was NOT harmless.
+      # `plan-paper-timeline.effects.harness.mjs` spawns the real agent binary; without it the
+      # harness SKIPS, the skip exits 0 through `vigiles test`, and the mutation driver interprets
+      # that as "the mutation survived". Measured 2026-09-15 on run 34966606186: two survivors in CI,
+      # zero locally, the difference being this binary and nothing about the code.
+      #
+      # The driver now REFUSES a battery whose harness skips (lib/mutation-driver.mjs), so the
+      # wrong diagnosis is gone either way. This step is the other half: it restores the evidence
+      # instead of settling for an honest "no evidence". No API key — the tier drives a scripted
+      # stand-in, which is why it costs seconds and $0.
+      # 🔴 DELIBERATELY UNPINNED, and since issue #7 that is finally honest. The tier exists to
+      # notice upstream moving, so a pin would defeat it — but until the version was OBSERVED
+      # rather than probed for, an unpinned install meant the assertions characterized whatever
+      # shipped that morning while the docblock named 2.1.227 (measured drift: 2.1.273). The run
+      # now prints both numbers, so the log says which version the green belongs to.
+      - name: the agent binary the effects tier observes
+        run: npm i -g @anthropic-ai/claude-code
+        timeout-minutes: 3
+
+      # 🔴 `--no-skip` HERE, AND PRECISELY AFTER THE INSTALL ABOVE. Measurement 17.09: without it,
+      # skip is green, and `skip` status is applied not only to author-declared `skip()`, but also to a file
+      # that failed to LOAD. In other words, one flag closes both doors at once.
+      #
+      # ⚠️ The step order was incorrect and made the install above nearly pointless: `npm test`
+      # ran BEFORE it, so the effects tier in this job was always skipped, and the binary
+      # reached only the mutation batteries. The comment about "its absence was NOT harmless"
+      # described exactly this harm yet did not protect against it itself.
+      #
+      # ⚠️ And the flag belongs IN THE STEP, not in `package.json`: the macOS cell of build-e2e runs the same `npm test`
+      # WITHOUT installing the binary, where skips are legitimate, and a global flag would falsely color it.
+      - name: npm test
+        run: npm test -- --no-skip
+
+      # The rules themselves, over this repository's own fixtures. Two of the four fixtures are
+      # DEFECTIVE ON PURPOSE, so a healthy checkout reports warnings here and still exits 0 —
+      # the pass/fail signal for rule behaviour lives in `npm test`, not in the warning count.
+      - name: npm run lint
+        run: npm run lint
+
+      # Prettier defaults, the same config as vigiles; `.prettierignore` names what it must not
+      # reflow (compiled SKILL.md, fixture data, raw runs) and why.
+      - name: npm run fmt:check
+        run: npm run fmt:check
+
+      # 🔴 THE ONLY GATE THAT LOOKS AT THE SKILLS THEMSELVES — it existed as a package.json
+      # script (`lint:skills`, removed 2026-09-24) long before it was WIRED HERE. That cost
+      # nothing while the package shipped rules only; the first skill arrived 2026-09-12 and made it the one check
+      # covering frontmatter, `allowed-tools` contracts, dangling pointers and name collisions.
+      # `npm run lint` above is ESLint over .tex/.md fixtures and never opens a SKILL.md.
+      #
+      # A PLAIN GATE, NOT `continue-on-error` — and that is a measurement, not a preference. In
+      # the consumer repository this command CANNOT exit 0: a repo-wide "Markdown code block refs"
+      # pass walks prose that quotes OTHER projects' commands, so it is pinned under
+      # `continue-on-error` there and gates nothing. Measured here on a clean tree 2026-09-12:
+      # **28 findings, 0 error, exit 0, 3 seconds**. Nothing to hide, so nothing is hidden.
+      #
+      # ⚠️ Warnings are expected and do not fail the run (description budgets, missing
+      # `disallowed-tools:` fences). What fails it is severity `error` — a malformed frontmatter
+      # or a pointer to a file that does not exist. Bond is 3 × the measured 3 s, floored at the
+      # 1-minute granularity GitHub bills in.
+      #
+      # README.md is linted too, by name (see the same gate in scripts/check.mjs). Its
+      # `vigiles:symbol` marks name the functions behind `paperlint init` and `paperlint new`; if one is
+      # renamed or removed, this step fails and names README.md.
+      - name: vigiles lint (skills + README.md)
+        run: npx vigiles lint . README.md
+        timeout-minutes: 2
+
+      # 🔴 THE GREEN-ZERO GUARD. A rule whose glob matches no file is never invoked, and a run
+      # with no findings is byte-identical to a run that examined everything and passed. This
+      # asks ESLint for the effective config of every linted file and names any rule that saw
+      # none. In the source corpus it once found NINETEEN blind rules on a green run.
+      - name: every rule sees a file
+        run: node scripts/rules-see-files.mjs
+
+      # Hand-written mutation batteries are being removed (#52): the frozen list may only
+      # shrink — no new battery, no new case in an existing one.
+      - name: mutation batteries are frozen
+        run: node scripts/mutation-batteries-frozen.mjs
+
+      # The legacy exemptions from src/'s layer rules (#76) may only shrink: counted from ESLint's
+      # own suppressedMessages, so a new `-- legacy …` directive anywhere fails here.
+      - name: legacy layer exemptions are frozen
+        run: node scripts/layer-legacy-frozen.mjs
+
+      # The batteries that remain still run until #52 replaces or removes them. The runner
+      # DISCOVERS batteries rather than listing them and errors on finding zero — see
+      # scripts/run-mutations.mjs for why (the hand list it replaced had gone stale, silently).
+      - name: mutation batteries
+        run: node scripts/run-mutations.mjs
+
+      # pnpm is INSTALLED here rather than hoped for. The runner image may or may not carry it,
+      # and the npm/pnpm difference is the entire reason the install e2e exists — so leaving it
+      # to the image means the half that matters most is covered by luck. `corepack` ships with
+      # Node, so this costs a second and no network round-trip to a third-party action.
+      - name: enable pnpm
+        run: corepack enable pnpm
+        timeout-minutes: 2
+
+      # Called directly with --strict, the same as the build e2e below. --strict: a manager that does not launch is a declared skip on a
+      # contributor's clone and a FAILURE here, because in CI it means a broken environment.
+      - name: install e2e (--strict)
+        run: node test/e2e/install.mjs --strict
+        timeout-minutes: 10
+
+  # ── BUILDING THE PAPER WITH REAL pdflatex, ON LINUX AND macOS ──────────────────────────────────
+  #
+  # 🔴 ONE JOB, TWO OPERATING SYSTEMS. TeX Live comes from `paperlint toolchain` — the same command a user
+  # runs — so the job tests the install path users get, not a CI-only script. It used to be a bash
+  # installer here and a separate macOS workflow (platform.yml) there; both are gone. macOS matters
+  # twice: install-tl-unx has to work on it, and issue #9 (`/var` is a symlink to `/private/var`)
+  # exists only there, so the macOS cell also runs `npm test` and the temp-dir probe.
+  #
+  # 🔴 WHY A SEPARATE JOB, NOT A STEP IN `gates`. Its only dependency is TeX Live, and it alone costs
+  # minutes: ~270 MB, ~3 min cold (measured 2026-09-24 with `paperlint toolchain`). A separate job runs in
+  # parallel and caches itself.
+  #
+  # 🔴 WHY ON EVERY PUSH. It catches silent font substitution — a class that HAS ALREADY shipped a
+  # paper typeset in the wrong font. This repository is public, so the macOS minutes are free.
+  #
+  # `--strict`: absence of TeX locally is a legitimate skip; here it is an environment failure.
+  build-e2e:
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          # The latest LTS; the gates job covers the 22 floor, so no job runs twice.
+          node-version: 24
+          cache: npm
+
+      - name: npm ci
+        run: npm ci
+        timeout-minutes: 8
+
+      # Issue #9's distinction: prints BOTH spellings of the temp root. If they match, this machine
+      # is not the platform the macOS cell exists for, and green below says nothing about it.
+      - name: two spellings of one directory — does this machine see them
+        if: runner.os == 'macOS'
+        run: |
+          node -e '
+            const { mkdtempSync, realpathSync } = require("node:fs");
+            const { tmpdir } = require("node:os");
+            const { join } = require("node:path");
+            const d = mkdtempSync(join(tmpdir(), "probe-"));
+            console.log("as typed :", d);
+            console.log("realpath :", realpathSync(d));
+            console.log(d === realpathSync(d) ? "MATCH — issue #9 traps do not exist on this machine"
+                                              : "DIVERGE — this is the platform this job exists for");
+          '
+
+      # Issue #9: `npm test` was red ONLY on macOS. Only `npm test`, not the mutation batteries:
+      # they would verify on macOS exactly what the gates job verifies on Linux.
+      - name: npm test (macOS)
+        if: runner.os == 'macOS'
+        run: npm test
+        timeout-minutes: 10
+
+      # The cache key is what the install depends on: the runner and the declared packages (every
+      # venue profile, the base set included). NOT the TeX Live year, and not the calendar year that
+      # used to stand in for it: the calendar says nothing about CTAN's release, and a restored tree
+      # from an older year is safe — `paperlint toolchain` verifies every declared file on it, leaves it
+      # alone when it is complete, and when a newly declared package makes tlmgr refuse it across
+      # releases, installs the new year beside it (src/toolchain.ts, `newRelease`).
+      # No `restore-keys`, deliberately: a partial restore would carry the old year's tree into the
+      # new entry, and the old tree is never deleted, so the cache would grow by a whole TeX Live.
+      - name: where TeX Live is cached
+        run: echo "RPP_TEXLIVE_DIR=$HOME/.cache/rpp-texlive" >> "$GITHUB_ENV"
+
+      - name: TeX Live from cache
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/rpp-texlive
+          key: texlive-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('skills/submit-paper/references/venues/*.jsonc') }}
+
+      # The same command a user runs. On a cache hit it verifies and says "nothing to do"; on a miss
+      # it installs from an empty directory and verifies every declared file with kpsewhich.
+      # `node bin/rpp.mjs`, not `npx paperlint`: inside this repository npx would look the name up on npm.
+      # It also downloads banal, the Perl script HotCRP runs to measure page geometry (~90 KB, pinned
+      # commit, sha256-checked, then run once on a test page). paperlint keeps banal and no longer needs
+      # poppler: paperlint now writes the XML banal reads, which poppler's pdftohtml used to write.
+      # Both runner images ship perl. The download is too small to be worth an Actions cache.
+      - name: paperlint toolchain
+        run: node bin/rpp.mjs toolchain
+        timeout-minutes: 15
+
+      # Proves banal works without poppler. This runner has no poppler, and the test also limits
+      # PATH to perl. paperlint turns each fixture PDF into XML with pdf.js, banal measures it, and the
+      # result must equal the numbers banal gave on the same PDFs through poppler's pdftohtml
+      # (recorded once, hardcoded in the test). Runs in seconds, hence the short timeout.
+      - name: banal e2e (--strict)
+        run: node test/e2e/banal.mjs --strict
+        timeout-minutes: 3
+
+      # Called directly with --strict (see the install e2e step in the `gates` job).
+      - name: build e2e (--strict)
+        run: node test/e2e/build.mjs --strict
+        timeout-minutes: 10
+
+      - name: toolchain e2e (--strict)
+        run: node test/e2e/toolchain.mjs --strict
+        timeout-minutes: 10

package/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,70 @@
+# MERGE THE UPDATE UPON A GREEN RUN.
+#
+# 🔴 WHY NOT `gh pr merge --auto`, even though the owner enabled "Allow auto-merge" and branch protection.
+# Standard auto-merge waits for precisely the checks declared REQUIRED in the branch protection. That
+# is a setting in the interface, invisible from here, and it can drift from `ci.yml` on any job rename —
+# and it WILL drift silently, because the PR will simply merge faster.
+# Measurement 2026-09-16 showed exactly this cost: before protection, `main` had `"protected": false`, and
+# `--auto` would have merged the PR IMMEDIATELY, looking like "merge on green" while doing the opposite.
+#
+# This workflow fires FROM THE COMPLETION EVENT of `ci` and reads its `conclusion`. The same reasoning
+# as all checks in this repository: we ask for the THING (run verdict), not its shadow (a setting
+# that promises the verdict will be considered).
+#
+# ⚠️ Branch protection is not redundant — it closes a DIFFERENT hole: a person or bot merging
+# a PR outside CI manually. Two mechanisms, two concerns.
+#
+# 🔴 WHY WE MERGE ANY BUMP, INCLUDING MAJOR, not just patch/minor.
+# Semver is a PUBLISHER'S CLAIM about their release; `ci` is a MEASUREMENT on our corpus (full harness suite,
+# mutations, gates for "rules see their files" and "rules don't touch git"). A major bump that breaks us
+# reds the run and does not merge; a minor one that breaks us does the same.
+# A version-number filter adds a manual step where measurement already exists, and would miss
+# exactly the class for which version filters are typically used.
+#
+# ⚠️ WHAT THIS DOES NOT GIVE, stated plainly: green `ci` means "our harnesses detected no difference,"
+# not "no difference exists." Uncovered behavior passes silently — as vigiles schema 19 → 27 passed
+# through a hook reading an empty field for eight releases in a row.
+name: dependabot auto-merge
+
+on:
+  workflow_run:
+    workflows: ["ci"]
+    types: [completed]
+
+# Merge and delete branch — nothing else this workflow needs.
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  merge:
+    # Three conditions, each blocking a case: the run was for a PR (not a push to main) ·
+    # the run is GREEN · the author is a bot, not a person. Remove any one and meaning changes.
+    if: >
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.actor.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: merge the PR that just turned green
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          # 🔴 The number comes FROM THE EVENT, not from a search by branch name. A search would find the PR
+          # but would not prove the green run belongs to it.
+          PR: ${{ github.event.workflow_run.pull_requests[0].number }}
+          # 🔴 The commit the green run TESTED. Without it, a push landing between the run and this job
+          # would merge an untested head: `gh pr merge` merges whatever the PR points at NOW.
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          set -euo pipefail
+          # An empty number is NOT "nothing to do": fork PRs come with an empty array, and
+          # silent exit would look like a successful merge. Fail with a reason.
+          if [ -z "${PR}" ]; then
+            echo "::error::ci run did not yield a PR number (fork?) — nothing merged, resolve manually"
+            exit 1
+          fi
+          gh pr merge "${PR}" --repo "${REPO}" --squash --delete-branch --match-head-commit "${HEAD_SHA}"
+          echo "merged PR #${PR} on green ci run ${RUN_ID}"

package/.github/workflows/pr-title.yml

@@ -0,0 +1,59 @@
+# The PR title becomes the squash commit on main, and that commit is what semantic-release reads
+# (release.yml). A title without a conventional prefix means a merged fix releases nothing, with
+# every check green. Copied from zernie/vigiles.
+name: PR Title
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    # Measured 5 s in vigiles.
+    timeout-minutes: 5
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            chore
+            refactor
+            test
+            perf
+            ci
+            build
+          requireScope: false
+          subjectPattern: ^.+$
+          subjectPatternError: "PR title must not be empty after the type prefix."
+
+      # For a PR with exactly ONE commit, GitHub's squash merge takes the COMMIT's subject as the
+      # squash title, not the PR's. So a PR can pass the check above and still land a commit with
+      # no conventional prefix, and semantic-release then cuts no version. Measured in vigiles
+      # (#163, 2026-08-19): a `feat!:` PR title, check green, a plain commit on main, no release.
+      - name: The squash title, for a single-commit PR
+        if: github.event.pull_request.commits == 1
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          subject=$(gh api "repos/$REPO/pulls/$PR/commits" --jq '.[0].commit.message' | head -1)
+          echo "commit subject: $subject"
+          if ! printf '%s' "$subject" | grep -qE '^(feat|fix|docs|chore|refactor|test|perf|ci|build)(\([^)]+\))?!?: .+'; then
+            echo "::error::This PR has ONE commit, so GitHub's squash default will use the COMMIT subject"
+            echo "::error::as the squash title — not the PR title, which already passed the check above."
+            echo "::error::That subject is: $subject"
+            echo "::error::Fix either side: amend the commit to carry the same conventional prefix, or"
+            echo "::error::set the squash title explicitly when merging. Otherwise semantic-release sees"
+            echo "::error::no releasable change and publishes nothing, with every check green."
+            exit 1
+          fi

package/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+# Release: every push to main runs semantic-release, which reads the commits since the last tag,
+# and — only when one of them is `feat:`, `fix:` or breaking — bumps the version, publishes the
+# package to npm as `paperlint`, tags `vX.Y.Z` and writes a GitHub release.
+# Copied from zernie/vigiles, whose release setup this mirrors.
+#
+# The squash title of a merged PR IS the commit this reads, so a PR titled without a
+# conventional prefix releases nothing, silently. pr-title.yml guards that.
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Not measured yet; npm ci + tsc + publish. Bounded generously, but bounded: an unbounded
+    # job that hangs runs to GitHub's six-hour ceiling instead of failing.
+    timeout-minutes: 20
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # semantic-release walks the history back to the last release tag.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          # semantic-release 25 refuses to start below Node ^22.14.0.
+          node-version: "22"
+          cache: npm
+
+      # `npm ci` runs `prepare` (tsc), so dist/ exists before publishing; `npm publish` runs it
+      # again. dist/ is not committed.
+      - name: npm ci
+        run: npm ci
+        timeout-minutes: 5
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        # `--no-install`: run the version pinned in package.json, never fetch one. The preset is
+        # pinned with it (conventional-changelog-conventionalcommits 9.3.1): preset 10 renders only
+        # through conventional-changelog-writer 9, which @semantic-release/release-notes-generator
+        # 14 does not load, and vigiles shipped empty release notes for five weeks that way
+        # (zernie/vigiles#282). scripts/release-config.test.ts renders the notes with the installed
+        # toolchain.
+        run: npx --no-install semantic-release