paperlint 9.0.0 → 9.0.1

package/CONTRIBUTING.md

@@ -79,7 +79,7 @@ Most of the package's rules run on users' papers and are described for users in
 files.
 
 One rule checks one requirement, and a rule that judges a venue requirement is validated on real
-accepted papers built to PDF — both in [`CLAUDE.md`](CLAUDE.md#the-ten-rules-that-decide-what-may-live-here--and-what-may-not-be-written), rule 3.
+accepted papers built to PDF — both in [`eslint-rules/CLAUDE.md`](eslint-rules/CLAUDE.md).
 
 A new rule ships with its page, `docs/rules/<group>/<rule>.md`, in these sections: What it
 catches · Why · Examples (failing / passing) · Options / preset fields · What it does not check ·
@@ -93,7 +93,7 @@ length, markers, hedges — drives papers toward clipped, unsignposted prose tha
 blog post, so a new one also has a floor, or measures the distance to accepted papers of the target
 venue, with its threshold measured by the same counter on those papers. What the parse tree can
 count is a rule; what needs reading (register, genre) is a skill criterion. The five principles are
-in [`CLAUDE.md`](CLAUDE.md#writing-checks--what-keeps-them-from-pushing-papers-toward-a-blog-post).
+in [`eslint-rules/CLAUDE.md`](eslint-rules/CLAUDE.md#a-rule-that-judges-prose).
 
 ## Maintainer docs
 

package/dist/CLAUDE.md.spec.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vigiles/spec").ClaudeSpec;
+export default _default;
+//# sourceMappingURL=CLAUDE.md.spec.d.ts.map

package/dist/CLAUDE.md.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLAUDE.md.spec.d.ts","sourceRoot":"","sources":["../src/CLAUDE.md.spec.ts"],"names":[],"mappings":";AAGA,wBAoEG"}

package/dist/CLAUDE.md.spec.js

@@ -0,0 +1,62 @@
+// Compiled to src/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+import { enforce, file, instructionFile, prose } from "vigiles/spec";
+export default instructionFile({
+    sections: {
+        "`src/`": prose `The package's TypeScript: the CLI, the build, the toolchain installer, and the measuring that feeds
+the facts file. Loaded when working under \`src/\`; the repository-wide rules are in the root
+\`CLAUDE.md\`.`,
+        "The two layer axes": prose `**\`src/\` is hexagonal on two axes, and the linter enforces both** (\`eslint.config.mjs\`; fixtures in
+\`test/fixtures/layers/\`, run by ${file("test/eslint-layers.test.ts")}; issue #76).
+
+**Axis A — knowledge. Core means the DOMAIN, not "no I/O".** A file belongs to an adapter when it
+exists because of one external program or format: _if banal / pdf.js / TeX Live / ESLint / Claude
+Code disappeared tomorrow, which files would change? Those are its adapter, wherever they sit
+today._ The domain is what would not change if every one of them were swapped. Purity is not the
+test — a parser for banal's JSON is pure and is still banal's.
+
+| element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
+| --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| \`domain\`  | \`src/domain/\`          | values and decisions in the paper's vocabulary                                                                                                                     | \`domain\`; \`ts-essentials\`, \`node:path\`, \`node:crypto\`                                                                   |
+| \`port\`    | \`src/ports/\`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | \`domain\`, \`port\`; the same three externals                                                                              |
+| \`app\`     | \`src/*.ts\`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | \`domain\`, \`port\`, \`app\`, the package's \`.mjs\`; Node's \`util\`/\`url\`/\`module\`                                             |
+| \`adapter\` | \`src/adapters/<tool>/\` | everything that knows \`<tool>\` exists, pure parsers included; used through its \`index.ts\`                                                                          | \`domain\`, \`port\`, its own folder, its tool's packages, the package's \`.mjs\`. **Never** \`app\`, **never** another adapter |
+| \`root\`    | \`src/cli.ts\`           | reads \`process.*\`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
+
+Folders are ELEMENTS of \`eslint-plugin-boundaries\`, single files are CATEGORIES (\`root\`, \`app\`,
+\`test\`, \`io\`): v7 matches element patterns as folders. Everyone — tests included — reaches an
+adapter through its \`index.ts\`; the files inside one adapter import each other freely.
+
+**Axis B — purity.** An effect (disk, process, network, env, clock, TTY) may be written only in
+\`src/adapters/<tool>/<x>.io.ts\` and \`src/cli.ts\`. Every other file, adapters' parsers included,
+takes a port. Test: _can a call here fail for a reason not in its arguments?_ Imports are checked
+through the \`io\` file category in \`boundaries/dependencies\`; the \`process\` and \`fetch\` globals by
+\`no-restricted-globals\`.
+
+**The legacy app files are held by a ratchet, not exempted.** A site that still breaks either axis
+carries \`// eslint-disable-next-line <rule> -- legacy <I/O|layer>, moves behind a port in #76\`.
+Unused directives are errors (\`reportUnusedDisableDirectives\`), so a fixed site must drop its
+comment; the per-file counts are frozen in \`scripts/layer-legacy.frozen.json\` and checked by
+${file("scripts/layer-legacy-frozen.ts")} (\`npm run check\`, CI), which counts ESLint's own
+\`suppressedMessages\` and fails when a file's count grows, a file not in the list carries one, or
+anything under \`src/domain/\`, \`src/ports/\` or \`src/adapters/\` does. A NEW module that needs the
+world is a new \`*.io.ts\` in the adapter of the program it talks to — never a new directive.
+
+Parse at the boundary, into types that cannot hold an invalid state (a banal path that exists only
+after its sha256 and probe passed; a \`Ready\` only an installer mints; an outcome as a discriminated
+union, not a string); the inside never re-validates.
+
+⚠️ **Two settings are load-bearing.** \`boundaries/root-path\`: without it the plugin matches paths
+against \`process.cwd()\`, so lint started from any other directory classifies nothing and passes.
+\`checkAllOrigins: true\`: without it no \`module:\` policy is evaluated, so axis B and the library bans
+report nothing — dropping it turns the fixtures \`src/domain/reads-disk.ts\` and
+\`src/adapters/one/disk.ts\` clean (measured).`,
+        "Readers and commands": prose `\`@retorquere/bibtex-parser\` is the one \`.bib\` reader, behind ${file("src/ports/bib-reader.ts")}.
+Rejected on 2026-09-27, so not proposed again: a separate \`paperlint refs\` command; the slowness it
+would have moved was a cache thrown away after every build (${file("docs/references.md")}).`,
+    },
+    rules: {
+        layers: enforce("eslint/boundaries/dependencies", "Both axes: what a layer may import, and where an effect may be written.", { render: "id" }),
+        "effect-globals": enforce("eslint/no-restricted-globals", "The process and fetch globals only where an effect may be written.", { render: "id" }),
+    },
+});
+//# sourceMappingURL=CLAUDE.md.spec.js.map

package/dist/CLAUDE.md.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLAUDE.md.spec.js","sourceRoot":"","sources":["../src/CLAUDE.md.spec.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErE,eAAe,eAAe,CAAC;IAC7B,QAAQ,EAAE;QACR,QAAQ,EAAE,KAAK,CAAA;;eAEJ;QAEX,oBAAoB,EAAE,KAAK,CAAA;oCACK,IAAI,CAAC,4BAA4B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BpE,IAAI,CAAC,gCAAgC,CAAC;;;;;;;;;;;;;+CAaO;QAE3C,sBAAsB,EAAE,KAAK,CAAA,oEAAoE,IAAI,CAAC,yBAAyB,CAAC;;8DAEtE,IAAI,CAAC,oBAAoB,CAAC,IAAI;KACzF;IACD,KAAK,EAAE;QACL,MAAM,EAAE,OAAO,CACb,gCAAgC,EAChC,yEAAyE,EACzE,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB;QACD,gBAAgB,EAAE,OAAO,CACvB,8BAA8B,EAC9B,oEAAoE,EACpE,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB;KACF;CACF,CAAC,CAAC"}

package/dist/build.js

@@ -34,7 +34,7 @@
  * The decision of the LaTeX loop is `latex-loop.ts`, reading the log is `latex-log.ts`; both are
  * pure. This file is the shell: it runs processes through the injected `run` (the existing port —
  * `spawnSync` by default) and reads the files a pass left behind. Where paperlint's own files live is
- * answered by `package-dirs.ts`, the one module allowed to know it (rule 10).
+ * answered by `package-dirs.ts`, the one module allowed to know it (root CLAUDE.md).
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";

package/dist/eslint-rules/CLAUDE.md.spec.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vigiles/spec").ClaudeSpec;
+export default _default;
+//# sourceMappingURL=CLAUDE.md.spec.d.ts.map

package/dist/eslint-rules/CLAUDE.md.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLAUDE.md.spec.d.ts","sourceRoot":"","sources":["../../eslint-rules/CLAUDE.md.spec.ts"],"names":[],"mappings":";AAMA,wBAoCG"}

package/dist/eslint-rules/CLAUDE.md.spec.js

@@ -0,0 +1,39 @@
+// Compiled to eslint-rules/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+//
+// The requirements below are held by tests and scripts, not by an ESLint rule `enforce()` could
+// name, so they are prose with verified file references rather than `enforce()` rules.
+import { file, guidance, instructionFile, prose } from "vigiles/spec";
+export default instructionFile({
+    sections: {
+        "`eslint-rules/`": prose `The rules this package ships. Loaded when working under \`eslint-rules/\`; the rules for every change
+are in the root \`CLAUDE.md\`. Each requirement below names what holds it; the reasoning lives in
+that file's header.`,
+        "What a new rule ships with, and what holds it": prose `| requirement | held by |
+| --- | --- |
+| **Both halves** (root \`CLAUDE.md\`), for every registered rule | ${file("src/rule-cases.test.ts")} fails on a registered rule with no cases |
+| **One rule, one requirement**: two checks with different reasons to switch them off are two rules | review |
+| **A venue requirement is validated on real accepted papers** of that venue, built to PDF, with the ground truth established independently | review; the papers are in ${file("fixtures/accepted-papers/README.md")} |
+| **Its page**, \`docs/rules/<group>/<rule>.md\`, and \`meta.docs.url\` pointing at it | ${file("src/rule-docs.test.ts")}; its \`AWAITING_PAGE\` list only shrinks |
+| **Loud on an empty input set**: a rule that matched no files must not report like one that passed | ${file("scripts/rules-see-files.mjs")}, per rule and not per glob, in \`npm run check\` |
+
+The page's sections: What it catches · Why · Examples (failing / passing) · Options / preset fields ·
+What it does not check · How to fix. Its row in ${file("docs/rules.md")} is one line linking there.`,
+        "A rule that judges prose": prose `A rule, or a skill criterion, that judges a paper's prose is held to five principles. Without them
+the checks push every paper toward a blog post.
+
+1. **Two-sided**: a floor as well as a ceiling, or the distance to accepted papers of the target
+   venue. A set of ceilings alone converges on clipped, unsignposted prose.
+2. **Rules count, skills judge.** Countable on the parse tree → a lint rule; needs reading (register,
+   genre, whether a claim changed strength) → a skill criterion.
+3. **The model reader is the venue's reviewer**, including one who skims the abstract, the
+   introduction and the conclusion.
+4. **Thresholds are calibrated, not borrowed**: set with the same counter on the accepted papers,
+   never taken from a figure measured by a different counter.
+5. **A rewrite is accepted on what reviewers see**: the combined count of every surface form of a
+   tic, plus a check that no claim was softened or strengthened.`,
+    },
+    rules: {
+        "lint-rule-over-script": guidance("A check over a syntax tree is a lint rule, not a script. It fires in the editor on save, gets the AST for free, and has a suppression syntax people already know. A script is for corpus-wide questions — index connectivity, ratios across many files. When the work has to run a program, a script may do the work and write facts to a JSON file, and a rule judges that file: the verdict still lands in the engine."),
+    },
+});
+//# sourceMappingURL=CLAUDE.md.spec.js.map

package/dist/eslint-rules/CLAUDE.md.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLAUDE.md.spec.js","sourceRoot":"","sources":["../../eslint-rules/CLAUDE.md.spec.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,EAAE;AACF,gGAAgG;AAChG,uFAAuF;AACvF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAEtE,eAAe,eAAe,CAAC;IAC7B,QAAQ,EAAE;QACR,iBAAiB,EAAE,KAAK,CAAA;;oBAER;QAEhB,+CAA+C,EAAE,KAAK,CAAA;;sEAEY,IAAI,CAAC,wBAAwB,CAAC;;0KAEsE,IAAI,CAAC,oCAAoC,CAAC;2FACzH,IAAI,CAAC,uBAAuB,CAAC;wGAChB,IAAI,CAAC,6BAA6B,CAAC;;;kDAGzF,IAAI,CAAC,eAAe,CAAC,6BAA6B;QAEhG,0BAA0B,EAAE,KAAK,CAAA;;;;;;;;;;;;iEAY4B;KAC9D;IACD,KAAK,EAAE;QACL,uBAAuB,EAAE,QAAQ,CAC/B,0ZAA0Z,CAC3Z;KACF;CACF,CAAC,CAAC"}

package/dist/eslint-rules/install-path-literals.d.ts

@@ -1,5 +1,5 @@
 /**
- * Rule 10's mechanical half: nothing outside the port may name a file by WHERE IT IS
+ * The install-location rule's mechanical half (root CLAUDE.md): nothing outside the port may name a file by WHERE IT IS
  * INSTALLED.
  *
  * The class this exists for has broken this repository five times, silently every time, and

package/dist/eslint-rules/install-path-literals.js

@@ -1,5 +1,5 @@
 /**
- * Rule 10's mechanical half: nothing outside the port may name a file by WHERE IT IS
+ * The install-location rule's mechanical half (root CLAUDE.md): nothing outside the port may name a file by WHERE IT IS
  * INSTALLED.
  *
  * The class this exists for has broken this repository five times, silently every time, and
@@ -43,7 +43,7 @@ function channelPrefixIn(s) {
 const PORT = "skills/paper-pipeline/scripts/consumer.mjs";
 const MESSAGES = {
     installPath: "This names a file by where it is INSTALLED ('{{prefix}}'), so it resolves in one " +
-        "delivery channel and does not exist in another. Rule 10: every answer to *where* comes " +
+        "delivery channel and does not exist in another. Every answer to *where* comes " +
         `from the port, ${PORT}. In a skill, use the substitution the harness performs ` +
         "(CLAUDE_SKILL_DIR / CLAUDE_PLUGIN_ROOT); in a module, ask the port.",
 };
@@ -52,7 +52,7 @@ const mdInstallPath = {
     meta: {
         type: "problem",
         docs: {
-            description: "a skill must not name its scripts by an install-specific path — rule 10, the port owns where",
+            description: "a skill must not name its scripts by an install-specific path — the port owns where",
         },
         schema: [],
         messages: MESSAGES,
@@ -73,7 +73,7 @@ const jsInstallPath = {
     meta: {
         type: "problem",
         docs: {
-            description: "a shipped module must not carry an install-specific path literal — rule 10, the port owns where",
+            description: "a shipped module must not carry an install-specific path literal — the port owns where",
         },
         schema: [],
         messages: MESSAGES,

package/dist/eslint-rules/install-path-literals.js.map

@@ -1 +1 @@
-{"version":3,"file":"install-path-literals.js","sourceRoot":"","sources":["../../eslint-rules/install-path-literals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,uEAAuE;AACvE,MAAM,gBAAgB,GAAG;IACvB,iBAAiB,EAAE,qDAAqD;IACxE,eAAe,EAAE,aAAa;IAC9B,kBAAkB,EAAE,mBAAmB;IACvC,gBAAgB,EAAE,wCAAwC;CAC3D,CAAC;AAEF,+FAA+F;AAC/F,SAAS,eAAe,CAAC,CAAU;IACjC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,gBAAgB;QAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,4FAA4F;AAC5F,2FAA2F;AAC3F,0FAA0F;AAC1F,MAAM,IAAI,GAAG,4CAA4C,CAAC;AAE1D,MAAM,QAAQ,GAAqC;IACjD,WAAW,EACT,mFAAmF;QACnF,yFAAyF;QACzF,kBAAkB,IAAI,0DAA0D;QAChF,qEAAqE;CACxE,CAAC;AAEF,oFAAoF;AACpF,MAAM,aAAa,GAAG;IACpB,IAAI,EAAE;QACJ,IAAI,EAAE,SAAkB;QACxB,IAAI,EAAE;YACJ,WAAW,EACT,8FAA8F;SACjG;QACD,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,QAAQ;KACnB;IACD,MAAM,CAAC,OAAoB;QACzB,MAAM,KAAK,GAAG,CAAC,IAAkC,EAAE,EAAE;YACnD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,MAAM;gBACR,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC,CAAC;QACF,yFAAyF;QACzF,iDAAiD;QACjD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACtE,CAAC;CACF,CAAC;AAEF,kDAAkD;AAClD,MAAM,aAAa,GAAG;IACpB,IAAI,EAAE;QACJ,IAAI,EAAE,SAAkB;QACxB,IAAI,EAAE;YACJ,WAAW,EACT,iGAAiG;SACpG;QACD,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,QAAQ;KACnB;IACD,MAAM,CAAC,OAAoB;QACzB,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,MAAc,EAAE,EAAE;YAC9C,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QACvE,CAAC,CAAC;QACF,OAAO;YACL,OAAO,CAAC,IAAiC;gBACvC,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC3C,IAAI,MAAM;oBAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACnC,CAAC;YACD,mFAAmF;YACnF,oFAAoF;YACpF,eAAe,CAAC,IAKf;gBACC,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBACtE,IAAI,MAAM;oBAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACnC,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe;IACb,KAAK,EAAE,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,aAAa,EAAE;CAC9E,CAAC;AACF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"install-path-literals.js","sourceRoot":"","sources":["../../eslint-rules/install-path-literals.ts"],"names":[],"mappings":"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"}

package/dist/eslint-rules/pdf-last-page-balance.js

@@ -11,7 +11,7 @@
  *   { "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] } }
  *
  * (That is a line comment's worth of JSON in a block comment only because it has no asterisk
- * followed by a slash; see rule 8 of CLAUDE.md before editing it.)
+ * followed by a slash; see the block-comment rule in the root CLAUDE.md before editing it.)
  *
  * ── WHAT IT READS: THE FACTS THE BUILD WROTE, NOT THE PDF ───────────────────────
  * `paperlint build` measures the PDF with pdf.js and writes `<paper>/_build/paper.facts.json`. This rule

package/dist/lib/agent-cli-version.js

@@ -54,7 +54,7 @@ export function observeAgentCli({ spawnSync, program = "claude", characterized =
     const version = VERSION_IN.exec(raw)?.[1] ?? "";
     // ⚠️ EXIT 0 AND NOTHING ON STDOUT IS NOT A CLEAN OBSERVATION — it is exactly what the discarded
     // probe looked like, and reporting `characterized against ""` would be the same lie in a new
-    // place. This is rule 4 of CLAUDE.md applied to the check that enforces it.
+    // place. This is the green zero of scripts/rules-see-files.mjs, applied to the check that enforces it.
     if (version === "")
         throw new Error(`\`${program} --version\` exited 0 but printed no version on stdout (got ${JSON.stringify(raw)}` +
             `${probe.stderr ? `, stderr ${JSON.stringify(probe.stderr.trim().slice(0, 200))}` : ""}). ` +

package/dist/lib/agent-cli-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-cli-version.js","sourceRoot":"","sources":["../../lib/agent-cli-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C,+DAA+D;AAC/D,MAAM,UAAU,GAAG,qBAAqB,CAAC;AA6BzC,MAAM,UAAU,eAAe,CAAC,EAC9B,SAAS,EACT,OAAO,GAAG,QAAQ,EAClB,aAAa,GAAG,iBAAiB,GAKlC;IACC,2FAA2F;IAC3F,2FAA2F;IAC3F,oDAAoD;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACpB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,GAAG,EAAE,EAAE;YACP,OAAO,EAAE,EAAE;YACX,aAAa;YACb,OAAO,EAAE,KAAK;YACd,IAAI,EAAE,SAAS,OAAO,oDAAoD;SAC3E,CAAC;IAEJ,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEhD,gGAAgG;IAChG,6FAA6F;IAC7F,4EAA4E;IAC5E,IAAI,OAAO,KAAK,EAAE;QAChB,MAAM,IAAI,KAAK,CACb,KAAK,OAAO,+DAA+D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;YAC9F,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK;YAC3F,8FAA8F;YAC9F,kEAAkE,CACrE,CAAC;IAEJ,MAAM,OAAO,GAAG,OAAO,KAAK,aAAa,CAAC;IAC1C,OAAO;QACL,OAAO,EAAE,IAAI;QACb,GAAG;QACH,OAAO;QACP,aAAa;QACb,OAAO;QACP,IAAI,EAAE,OAAO;YACX,CAAC,CAAC,cAAc,OAAO,MAAM,OAAO,oDAAoD;gBACtF,GAAG,aAAa,8EAA8E;gBAC9F,uEAAuE;YACzE,CAAC,CAAC,cAAc,OAAO,MAAM,OAAO,6DAA6D;KACpG,CAAC;AACJ,CAAC"}
+{"version":3,"file":"agent-cli-version.js","sourceRoot":"","sources":["../../lib/agent-cli-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C,+DAA+D;AAC/D,MAAM,UAAU,GAAG,qBAAqB,CAAC;AA6BzC,MAAM,UAAU,eAAe,CAAC,EAC9B,SAAS,EACT,OAAO,GAAG,QAAQ,EAClB,aAAa,GAAG,iBAAiB,GAKlC;IACC,2FAA2F;IAC3F,2FAA2F;IAC3F,oDAAoD;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACpB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,GAAG,EAAE,EAAE;YACP,OAAO,EAAE,EAAE;YACX,aAAa;YACb,OAAO,EAAE,KAAK;YACd,IAAI,EAAE,SAAS,OAAO,oDAAoD;SAC3E,CAAC;IAEJ,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEhD,gGAAgG;IAChG,6FAA6F;IAC7F,uGAAuG;IACvG,IAAI,OAAO,KAAK,EAAE;QAChB,MAAM,IAAI,KAAK,CACb,KAAK,OAAO,+DAA+D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;YAC9F,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK;YAC3F,8FAA8F;YAC9F,kEAAkE,CACrE,CAAC;IAEJ,MAAM,OAAO,GAAG,OAAO,KAAK,aAAa,CAAC;IAC1C,OAAO;QACL,OAAO,EAAE,IAAI;QACb,GAAG;QACH,OAAO;QACP,aAAa;QACb,OAAO;QACP,IAAI,EAAE,OAAO;YACX,CAAC,CAAC,cAAc,OAAO,MAAM,OAAO,oDAAoD;gBACtF,GAAG,aAAa,8EAA8E;gBAC9F,uEAAuE;YACzE,CAAC,CAAC,cAAc,OAAO,MAAM,OAAO,6DAA6D;KACpG,CAAC;AACJ,CAAC"}

package/dist/tex-requirements.js

@@ -17,7 +17,7 @@
  * of every violation, it is never read as "no packages".
  *
  * Where the profiles live is answered by `presetsDir()` in `package-dirs.ts` — the one module
- * allowed to know where this package's data is installed (rule 10).
+ * allowed to know where this package's data is installed (root CLAUDE.md).
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { readFileSync, readdirSync } from "node:fs";

package/dist/toolchain.js

@@ -3,7 +3,7 @@
  * declare, into paperlint's own cache, and banal (the page-geometry script HotCRP runs) at its pinned
  * commit (`adapters/banal/`). `paperlint build` offers the TeX Live install on a terminal.
  *
- * 🔴 WHY paperlint INSTALLS TeX AT ALL (rule 11). "Install TeX Live yourself" was a manual step with a
+ * 🔴 WHY paperlint INSTALLS TeX AT ALL (root CLAUDE.md: installing must be smooth). "Install TeX Live yourself" was a manual step with a
  * trap in it: the distribution packages cost 2.1 GB, and a smaller hand-picked set silently typeset
  * acmart papers in Computer Modern. The engine decision (2026-09-24) is TeX Live's pdflatex,
  * installed the way Playwright installs browsers: one command, a cache directory, idempotent.

package/docs/e2e.md

@@ -137,7 +137,7 @@ be paperlint's own cache, because the runner has no other.
 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 `PAPERLINT_TEXLIVE_DIR` its tests are skipped: installing ~270 MB
-into a home directory as a side effect of `npm run check` is the unasked install rule 11 forbids.
+into a home directory as a side effect of `npm run check` is the unasked install the root `CLAUDE.md` 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.
 

package/docs/incidents.md

@@ -4,7 +4,7 @@
 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
+Two things never move into this file: a measurement that **is** the rule (the root `CLAUDE.md`'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.
@@ -13,7 +13,7 @@ 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)
+## 2026-09-17 — four fixes proposed and withdrawn in one session (measure the defect first)
 
 Each was proposed before the defect it claimed to fix had been exhibited, and each fell to a
 single command:
@@ -33,7 +33,7 @@ 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)
+## 2026-09-17 — the install-location class, four silent breakages (where paperlint is installed)
 
 One class — _code that knows where it is on disk_ — has broken this repository four times, and
 not one of the four announced itself:
@@ -50,8 +50,8 @@ The first three are documented in the code they broke, and that is where the det
 `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.
+comments explaining the exact hazard sat directly above the code** — which is why that rule got
+a lint rule (`eslint-rules/install-path-literals.ts`) 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

package/eslint-rules/CLAUDE.md

@@ -0,0 +1,44 @@
+<!-- vigiles:sha256:5231f736e3b1a263 compiled from eslint-rules/CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## `eslint-rules/`
+
+The rules this package ships. Loaded when working under `eslint-rules/`; the rules for every change
+are in the root `CLAUDE.md`. Each requirement below names what holds it; the reasoning lives in
+that file's header.
+
+## What a new rule ships with, and what holds it
+
+| requirement | held by |
+| --- | --- |
+| **Both halves** (root `CLAUDE.md`), for every registered rule | `src/rule-cases.test.ts` fails on a registered rule with no cases |
+| **One rule, one requirement**: two checks with different reasons to switch them off are two rules | review |
+| **A venue requirement is validated on real accepted papers** of that venue, built to PDF, with the ground truth established independently | review; the papers are in `fixtures/accepted-papers/README.md` |
+| **Its page**, `docs/rules/<group>/<rule>.md`, and `meta.docs.url` pointing at it | `src/rule-docs.test.ts`; its `AWAITING_PAGE` list only shrinks |
+| **Loud on an empty input set**: a rule that matched no files must not report like one that passed | `scripts/rules-see-files.mjs`, per rule and not per glob, in `npm run check` |
+
+The page's sections: What it catches · Why · Examples (failing / passing) · Options / preset fields ·
+What it does not check · How to fix. Its row in `docs/rules.md` is one line linking there.
+
+## A rule that judges prose
+
+A rule, or a skill criterion, that judges a paper's prose is held to five principles. Without them
+the checks push every paper toward a blog post.
+
+1. **Two-sided**: a floor as well as a ceiling, or the distance to accepted papers of the target
+   venue. A set of ceilings alone converges on clipped, unsignposted prose.
+2. **Rules count, skills judge.** Countable on the parse tree → a lint rule; needs reading (register,
+   genre, whether a claim changed strength) → a skill criterion.
+3. **The model reader is the venue's reviewer**, including one who skims the abstract, the
+   introduction and the conclusion.
+4. **Thresholds are calibrated, not borrowed**: set with the same counter on the accepted papers,
+   never taken from a figure measured by a different counter.
+5. **A rewrite is accepted on what reviewers see**: the combined count of every surface form of a
+   tic, plus a check that no claim was softened or strengthened.
+
+## Rules
+
+### Lint Rule Over Script
+
+**Guidance only** — A check over a syntax tree is a lint rule, not a script. It fires in the editor on save, gets the AST for free, and has a suppression syntax people already know. A script is for corpus-wide questions — index connectivity, ratios across many files. When the work has to run a program, a script may do the work and write facts to a JSON file, and a rule judges that file: the verdict still lands in the engine.

package/eslint-rules/CLAUDE.md.spec.ts

@@ -0,0 +1,43 @@
+// Compiled to eslint-rules/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+//
+// The requirements below are held by tests and scripts, not by an ESLint rule `enforce()` could
+// name, so they are prose with verified file references rather than `enforce()` rules.
+import { file, guidance, instructionFile, prose } from "vigiles/spec";
+
+export default instructionFile({
+  sections: {
+    "`eslint-rules/`": prose`The rules this package ships. Loaded when working under \`eslint-rules/\`; the rules for every change
+are in the root \`CLAUDE.md\`. Each requirement below names what holds it; the reasoning lives in
+that file's header.`,
+
+    "What a new rule ships with, and what holds it": prose`| requirement | held by |
+| --- | --- |
+| **Both halves** (root \`CLAUDE.md\`), for every registered rule | ${file("src/rule-cases.test.ts")} fails on a registered rule with no cases |
+| **One rule, one requirement**: two checks with different reasons to switch them off are two rules | review |
+| **A venue requirement is validated on real accepted papers** of that venue, built to PDF, with the ground truth established independently | review; the papers are in ${file("fixtures/accepted-papers/README.md")} |
+| **Its page**, \`docs/rules/<group>/<rule>.md\`, and \`meta.docs.url\` pointing at it | ${file("src/rule-docs.test.ts")}; its \`AWAITING_PAGE\` list only shrinks |
+| **Loud on an empty input set**: a rule that matched no files must not report like one that passed | ${file("scripts/rules-see-files.mjs")}, per rule and not per glob, in \`npm run check\` |
+
+The page's sections: What it catches · Why · Examples (failing / passing) · Options / preset fields ·
+What it does not check · How to fix. Its row in ${file("docs/rules.md")} is one line linking there.`,
+
+    "A rule that judges prose": prose`A rule, or a skill criterion, that judges a paper's prose is held to five principles. Without them
+the checks push every paper toward a blog post.
+
+1. **Two-sided**: a floor as well as a ceiling, or the distance to accepted papers of the target
+   venue. A set of ceilings alone converges on clipped, unsignposted prose.
+2. **Rules count, skills judge.** Countable on the parse tree → a lint rule; needs reading (register,
+   genre, whether a claim changed strength) → a skill criterion.
+3. **The model reader is the venue's reviewer**, including one who skims the abstract, the
+   introduction and the conclusion.
+4. **Thresholds are calibrated, not borrowed**: set with the same counter on the accepted papers,
+   never taken from a figure measured by a different counter.
+5. **A rewrite is accepted on what reviewers see**: the combined count of every surface form of a
+   tic, plus a check that no claim was softened or strengthened.`,
+  },
+  rules: {
+    "lint-rule-over-script": guidance(
+      "A check over a syntax tree is a lint rule, not a script. It fires in the editor on save, gets the AST for free, and has a suppression syntax people already know. A script is for corpus-wide questions — index connectivity, ratios across many files. When the work has to run a program, a script may do the work and write facts to a JSON file, and a rule judges that file: the verdict still lands in the engine.",
+    ),
+  },
+});

package/eslint-rules/install-path-literals.harness.mjs

@@ -19,7 +19,7 @@ import markdown from "@eslint/markdown";
 import { recordCheck } from "vigiles";
 import port, { PORT } from "./install-path-literals.ts";
 
-// Resolved from THIS file, never from the caller's cwd — rule 6, and the mistake this very
+// Resolved from THIS file, never from the caller's cwd (root CLAUDE.md), and the mistake this very
 // class of bug is about.
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(HERE, "..");

package/eslint-rules/install-path-literals.ts

@@ -1,5 +1,5 @@
 /**
- * Rule 10's mechanical half: nothing outside the port may name a file by WHERE IT IS
+ * The install-location rule's mechanical half (root CLAUDE.md): nothing outside the port may name a file by WHERE IT IS
  * INSTALLED.
  *
  * The class this exists for has broken this repository five times, silently every time, and
@@ -47,7 +47,7 @@ const PORT = "skills/paper-pipeline/scripts/consumer.mjs";
 const MESSAGES: Readonly<Record<string, string>> = {
   installPath:
     "This names a file by where it is INSTALLED ('{{prefix}}'), so it resolves in one " +
-    "delivery channel and does not exist in another. Rule 10: every answer to *where* comes " +
+    "delivery channel and does not exist in another. Every answer to *where* comes " +
     `from the port, ${PORT}. In a skill, use the substitution the harness performs ` +
     "(CLAUDE_SKILL_DIR / CLAUDE_PLUGIN_ROOT); in a module, ask the port.",
 };
@@ -58,7 +58,7 @@ const mdInstallPath = {
     type: "problem" as const,
     docs: {
       description:
-        "a skill must not name its scripts by an install-specific path — rule 10, the port owns where",
+        "a skill must not name its scripts by an install-specific path — the port owns where",
     },
     schema: [],
     messages: MESSAGES,
@@ -81,7 +81,7 @@ const jsInstallPath = {
     type: "problem" as const,
     docs: {
       description:
-        "a shipped module must not carry an install-specific path literal — rule 10, the port owns where",
+        "a shipped module must not carry an install-specific path literal — the port owns where",
     },
     schema: [],
     messages: MESSAGES,

package/eslint-rules/pdf-last-page-balance.ts

@@ -11,7 +11,7 @@
  *   { "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] } }
  *
  * (That is a line comment's worth of JSON in a block comment only because it has no asterisk
- * followed by a slash; see rule 8 of CLAUDE.md before editing it.)
+ * followed by a slash; see the block-comment rule in the root CLAUDE.md before editing it.)
  *
  * ── WHAT IT READS: THE FACTS THE BUILD WROTE, NOT THE PDF ───────────────────────
  * `paperlint build` measures the PDF with pdf.js and writes `<paper>/_build/paper.facts.json`. This rule

package/eslint.config.mjs

@@ -250,6 +250,9 @@ const ROOT = { file: { categories: "root" } };
  */
 export const layerBoundaries = (root) => ({
   files: ["src/**/*.ts"],
+  // The source of src/CLAUDE.md sits beside it because `vigiles compile` requires that; it is an
+  // instruction file, not a layer of the package.
+  ignores: ["src/CLAUDE.md.spec.ts"],
   plugins: { boundaries },
   settings: {
     "boundaries/root-path": root,
@@ -681,7 +684,7 @@ export default [
     languageOptions: { ecmaVersion: 2024, sourceType: "module" },
     plugins: { local: localRules, port: portRules },
     rules: {
-      // Rule 10's mechanical half, code side. `warn` and not `error`, unlike its neighbour
+      // The install-location rule's mechanical half (root CLAUDE.md), code side. `warn` and not `error`, unlike its neighbour
       // above: this one does NOT open on a clean corpus. Two shipped modules print a command
       // for a human that names an install-specific path, and neither is fixable by the
       // answer the skills get — a printed command has to be resolved through the port at
@@ -741,7 +744,7 @@ export default [
     rules: { "n/no-missing-import": "error" },
   },
   /**
-   * Rule 10's mechanical half, prose side — and this is where the debt actually is: 76
+   * The install-location rule's mechanical half (root CLAUDE.md), prose side — and this is where the debt actually is: 76
    * findings across 29 skills on a healthy checkout, every one of them a command that
    * resolves in one delivery channel and is absent in another.
    *
@@ -789,7 +792,7 @@ export default [
     // ⚠️ `npx eslint .` therefore reports six warnings on a healthy checkout: the four defect
     // fixtures are DEFECTIVE ON PURPOSE, and that is what makes the fire half of every harness
     // real. Do not silence them by adding an ignore — a rule that lints only clean inputs is
-    // one whose firing path nothing exercises, which is rule 4 wearing a different hat. The
+    // one whose firing path nothing exercises, which is the green zero of scripts/rules-see-files.mjs wearing a different hat. The
     // pass/fail signal lives in `npm test`, not in the warning count of `npm run lint`.
   },
   {

package/hooks/CLAUDE.md

@@ -0,0 +1,34 @@
+<!-- vigiles:sha256:0407b53b2036133e compiled from hooks/CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## `hooks/`
+
+The hooks this package ships into a consumer's Claude Code session. Loaded when working under
+`hooks/`. Every shipped hook is run in both halves, firing and silent, by `hooks/hooks.harness.ts`.
+
+A bug here does not break this repository; it breaks somebody else's whole session. The Bash gate
+fails closed, so a hook that cannot read its config denies every command, including the one that
+would undo it.
+
+## Rules
+
+### Ship Hook Mjs Never Hook Ts
+
+**Guidance only** — A `.ts` hook inside `node_modules` fails to load and blocks every Bash command. Rejected, so not proposed again: a `.hook.ts` twin compiled to the `.mjs` (a twin drifts from its build, and nothing would notice), and a thin `.hook.ts` in the consumer importing the logic from here (`vigiles compile` refuses the import, so the hook can never be re-stamped, and the runtime fails closed on the stale stamp). [Measurements](https://github.com/zernie/paperlint/blob/b4a3dc3a81d436186f41db2d69b65fd93f1af3b6/CLAUDE.md#L272-L357).
+
+### No Sibling Imports
+
+**Guidance only** — A shipped hook cannot import a sibling module. The papers-root resolver is repeated in each hook, and `hooks.harness.ts` compares the copies.
+
+### No Import Shaped Text
+
+**Guidance only** — `checkHookImports` (run by `hooks.harness.ts`) is a text regex. Describe a forbidden import in words; never write one, not even in a comment.
+
+### One Wiring File
+
+**Guidance only** — The wiring is `plugin/hooks/hooks.json`. `paperlint init` merges it into the consumer's `.claude/settings.json`; there is no second copy.
+
+### Vigiles Moves With The Consumer
+
+**Guidance only** — `vigiles` moves with the consumer's pin, in one pass. A major mismatch makes `PreToolUse` refuse every command. `npm ls vigiles` compares what is installed with the manifest, not with the registry; Dependabot (`.github/dependabot.yml`) carries the registry half.

package/hooks/CLAUDE.md.spec.ts

@@ -0,0 +1,30 @@
+// Compiled to hooks/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+import { file, guidance, instructionFile, prose } from "vigiles/spec";
+
+export default instructionFile({
+  sections: {
+    "`hooks/`": prose`The hooks this package ships into a consumer's Claude Code session. Loaded when working under
+\`hooks/\`. Every shipped hook is run in both halves, firing and silent, by ${file("hooks/hooks.harness.ts")}.
+
+A bug here does not break this repository; it breaks somebody else's whole session. The Bash gate
+fails closed, so a hook that cannot read its config denies every command, including the one that
+would undo it.`,
+  },
+  rules: {
+    "ship-hook-mjs-never-hook-ts": guidance(
+      "A `.ts` hook inside `node_modules` fails to load and blocks every Bash command. Rejected, so not proposed again: a `.hook.ts` twin compiled to the `.mjs` (a twin drifts from its build, and nothing would notice), and a thin `.hook.ts` in the consumer importing the logic from here (`vigiles compile` refuses the import, so the hook can never be re-stamped, and the runtime fails closed on the stale stamp). [Measurements](https://github.com/zernie/paperlint/blob/b4a3dc3a81d436186f41db2d69b65fd93f1af3b6/CLAUDE.md#L272-L357).",
+    ),
+    "no-sibling-imports": guidance(
+      "A shipped hook cannot import a sibling module. The papers-root resolver is repeated in each hook, and `hooks.harness.ts` compares the copies.",
+    ),
+    "no-import-shaped-text": guidance(
+      "`checkHookImports` (run by `hooks.harness.ts`) is a text regex. Describe a forbidden import in words; never write one, not even in a comment.",
+    ),
+    "one-wiring-file": guidance(
+      "The wiring is `plugin/hooks/hooks.json`. `paperlint init` merges it into the consumer's `.claude/settings.json`; there is no second copy.",
+    ),
+    "vigiles-moves-with-the-consumer": guidance(
+      "`vigiles` moves with the consumer's pin, in one pass. A major mismatch makes `PreToolUse` refuse every command. `npm ls vigiles` compares what is installed with the manifest, not with the registry; Dependabot (`.github/dependabot.yml`) carries the registry half.",
+    ),
+  },
+});

package/lib/agent-cli-version.ts

@@ -95,7 +95,7 @@ export function observeAgentCli({
 
   // ⚠️ EXIT 0 AND NOTHING ON STDOUT IS NOT A CLEAN OBSERVATION — it is exactly what the discarded
   // probe looked like, and reporting `characterized against ""` would be the same lie in a new
-  // place. This is rule 4 of CLAUDE.md applied to the check that enforces it.
+  // place. This is the green zero of scripts/rules-see-files.mjs, applied to the check that enforces it.
   if (version === "")
     throw new Error(
       `\`${program} --version\` exited 0 but printed no version on stdout (got ${JSON.stringify(raw)}` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "9.0.0",
+  "version": "9.0.1",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "ts-essentials": "^10.2.1",
     "typescript": "^6.0.3",
     "unpdf": "^1.8.1",
-    "vigiles": "^32.1.0",
+    "vigiles": "^38.2.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {