paperlint 3.1.0 → 3.1.1

package/skills/paper-pipeline/scripts/population-map.selftest.mjs

@@ -1,122 +0,0 @@
-#!/usr/bin/env node
-/**
- * population-map.selftest.mjs — planted defects, both directions.
- *
- * This repository has been burned three times by checkers and hooks that were green and dead, and
- * the rule that came out of it is that a checker which has never failed is not a checker.
- *
- * 🔴 SHRUNK 2026-08-26 TOGETHER WITH THE CHECKER ITSELF. Nine of the thirteen cases checked
- * `untied` and `undeclared` — both findings moved into ESLint rules (`paper/population-untied`,
- * `paper/population-undeclared`), and their cases moved there too, into
- * `eslint-rules/paper-registry.harness.mjs`, where they sit next to a run against a REAL paper.
- * What is left here are the two findings that speak about the registry itself: `stale` and `badref`.
- *
- * 🔴 ONE CASE WAS DELETED, NOT MOVED, and that is worth remembering. It looked like this:
- *
- *     check('189 does not match inside 1,189',
- *           !sentences('x 1,189 y').some((s) => /(?<![\d,.])189(?!\d|[,.]\d)/.test(s)));
- *
- * that is, it ran a HAND-COPIED COPY of the checker's regex over a string and asserted about a
- * literal inside the test itself. A mutation of the body of `printed()` does not touch such a test
- * by construction — which is exactly what the `eslint-rules/paper-registry.mutations.mjs` battery
- * showed, where that mutation SURVIVED the first run. The property is now pinned by a fixture that
- * checks BEHAVIOUR, not the agreement of two copies of a regex.
- */
-import { findings, bodyOf } from "./population-map.mjs";
-
-const doc = (bodyLines) =>
-  `## Abstract\n\n${bodyLines}\n\n## References\n\n[1] x.\n`;
-let pass = 0,
-  fail = 0;
-const check = (name, cond) => {
-  if (cond) {
-    pass++;
-  } else {
-    fail++;
-    console.log(`  FAIL  ${name}`);
-  }
-};
-const kinds = (md, reg) =>
-  findings(md, reg).map((f) => `${f.kind}:${f.row?.print ?? f.print}`);
-
-const REG = [
-  "id\tprinted\trelation\trelated_to\tgloss",
-  "broad\t1,921\troot\t\tthe corpus",
-  "sub\t1,836\tsubset\tbroad\tthose it could read",
-].join("\n");
-
-// 1. Everything the registry declares is printed -> silence. The direction that matters more:
-//    a checker firing on a paper that already obeys gets muted the same week, and a muted checker
-//    is indistinguishable from an absent one.
-check(
-  "a registry that matches the body is silent",
-  kinds(
-    doc(
-      "The resolver ran over all 1,921 repositories, and read 1,836 of them.",
-    ),
-    REG,
-  ).length === 0,
-);
-
-// 2. A registry row for a quantity the paper no longer prints. The registry shrinks when the
-//    paper does; a row nobody removed is a claim nobody can check.
-check(
-  "stale registry row fires",
-  kinds(doc("The resolver ran over all 1,921 repositories."), REG).includes(
-    "stale:1,836",
-  ),
-);
-
-// 3. ...but a row explicitly marked `retired` is exempt — that is what the marker is FOR.
-//    Without this the only way to keep a set declared after cutting it from the paper would be
-//    to delete the row, which loses the record.
-check(
-  "a retired row does not fire",
-  !kinds(
-    doc("The resolver ran over all 1,921 repositories."),
-    REG + "\ngold\t7,310\tretired\t\ta public gold set",
-  ).includes("stale:7,310"),
-);
-
-// 4. A relation pointing at an id that does not exist. Purely a defect of the TSV: the row claims
-//    a parent that is not a row. This is why the check stayed a script — there is nothing in the
-//    paper to point a finding at.
-check(
-  "dangling related_to fires",
-  findings(
-    doc("We read 1,836 repositories."),
-    "id\tprinted\trelation\trelated_to\tgloss\nsub\t1,836\tsubset\tnosuch\tx",
-  ).some((f) => f.kind === "badref"),
-);
-
-// 5. `badref` is reached only for a quantity the body actually prints: a row whose number is
-//    absent is `stale`, and reporting both about one row would double-count it.
-check(
-  "a row that is absent is stale, not badref",
-  kinds(
-    doc("Nothing numeric here."),
-    "id\tprinted\trelation\trelated_to\tgloss\nsub\t1,836\tsubset\tnosuch\tx",
-  ).join() === "stale:1,836",
-);
-
-// 6. `printed()` boundaries, tested through BEHAVIOUR: 189 must not count as printed inside 1,189.
-//    Without the guard the row would be considered present and `stale` would go quiet — a silent
-//    loss, which is the failure mode this file exists to prevent. (The deleted case asserted the
-//    same property against a hand-copied regex, and a mutation of the real one survived it.)
-check(
-  '189 is not "printed" inside 1,189',
-  kinds(
-    doc("A follow-up read covered 1,189 records."),
-    "id\tprinted\trelation\trelated_to\tgloss\nbroad\t1,921\troot\t\tthe corpus\nspread\t189\tsubset\tbroad\tenumerable",
-  ).includes("stale:189"),
-);
-
-// 7. bodyOf must stop at the bibliography. Appendices sit after it and are not under the page
-//    limit, so a number printed only there does not reach the reader who stops at References.
-check(
-  "bodyOf stops at References",
-  !bodyOf(doc("nothing here")).includes("[1] x."),
-);
-
-console.log(`population-map selftest: ${pass} passed, ${fail} failed`);
-process.exit(fail ? 1 : 0);

package/skills/paper-pipeline/scripts/provenance.mutations.mjs

@@ -1,59 +0,0 @@
-/**
- * provenance.mutations.mjs — plant each defect `provenance.harness.mjs` claims to catch, and require it to die.
- *
- * Run: `node skills/paper-pipeline/scripts/provenance.mutations.mjs` (~1 min; it rewrites the source and
- * restores it, so it is not part of the plain test run).
- *
- * WHY IT EXISTS. A harness whose success state is silence cannot be observed working: «it passed»
- * and «it cannot fail» produce identical output. This battery is the difference. It was written on
- * 2026-09-12, when the mechanism moved into this package and `scripts/run-mutations.mjs` reported
- * this harness as one nothing could kill — a gap that had been open for as long as the harness had
- * existed, invisible because nothing asked the question.
- *
- * Every replacement below differs from the text it replaces (the driver refuses a no-op, which
- * would leave a green harness proving nothing), every case names the assertion that must fire, and
- * the driver verifies the patch actually landed before believing a result.
- */
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { runMutations } from "../../../lib/mutation-driver.mjs";
-import { consumerRoot } from "./consumer.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const SRC = join(HERE, "check-provenance.mjs");
-const HARNESS = join(HERE, "provenance.harness.mjs");
-
-const MUTATIONS = [
-  [
-    "the scope gate is inverted",
-    [
-      [
-        SRC,
-        "if (!provenanceScope(dir).covered) return [];",
-        "if (provenanceScope(dir).covered) return [];",
-      ],
-    ],
-    "coverage measurement must always print",
-    "the in-scope/out-of-scope distinction: covered papers stop being checked and the report still prints",
-  ],
-  [
-    "the numbers gate is removed",
-    [[SRC, "return [...checkNumbersGate(dir)];", "return [];"]],
-    "coverage measurement must always print",
-    "the only finding this checker can make — it becomes a script that always says clean",
-  ],
-];
-
-process.exit(
-  runMutations({
-    root: consumerRoot(),
-    runner: "vigiles",
-    cases: MUTATIONS.map(([name, edits, expect, disables]) => ({
-      name,
-      disables,
-      edits,
-      harness: HARNESS,
-      expect,
-    })),
-  }),
-);

package/skills/paper-pipeline/scripts/round-diff.mutations.mjs

@@ -1,276 +0,0 @@
-/**
- * round-diff.mutations.mjs — proof that every check in `round-diff.mjs` is watched FAILING.
- * Run: `node .claude/skills/paper-pipeline/scripts/round-diff.mutations.mjs`  (~40 s; not in CI, it rewrites the source)
- *
- * This is not a test. It is the evidence behind the claim that the tests test something.
- *
- * WHY IT EXISTS. The house rule is «a checker that has never failed once is not considered working», and
- * it has been broken repeatedly here: three hooks dead on arrival, a statistics script that printed
- * "All recomputed values match paper.md" without opening paper.md. A green harness proves the
- * CHECKER fires on planted defects. It does not prove the HARNESS would notice if a check were
- * DELETED — an assertion can be vacuous, and a vacuous assertion is indistinguishable from a real
- * one in a passing run. Two were found in this repository in one week:
- *
- *   - one where removing a check left the test green because a LATER BRANCH produced the same
- *     finding KIND. The harness asserts on messages as well as kinds for that reason, and this file
- *     is what proves the message assertions are load-bearing;
- *   - one where the mutation DID NOT MUTATE — the `find` string was absent or matched twice, the
- *     rewrite was a no-op, and the run reported a killed mutant. Hence the arity check below:
- *     anything other than exactly one occurrence is reported as NOT FOUND / AMBIGUOUS and never
- *     as a pass.
- *
- * WHAT IT DOES. For each check: neuter exactly that check in the source, run the harness, and
- * require the harness to go RED **at the named assertion**. Restore. A mutation the harness survives
- * is a check nobody is watching, and it is reported as SURVIVED.
- *
- * The source is restored in a `finally`, and the run refuses to start on a dirty working tree, so an
- * interrupted run cannot leave a neutered checker behind.
- */
-import { runMutations } from "../../../lib/mutation-driver.mjs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { consumerRoot } from "./consumer.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const ROOT = consumerRoot();
-const SRC = join(HERE, "round-diff.mjs");
-const HARNESS = join(HERE, "round-diff.harness.mjs");
-
-/**
- * [name, what it disables, exact source substring, replacement, harness assertion expected to fire]
- *
- * `false && add(...)` is the standard neuter for a finding: it keeps the statement, the control flow
- * and any `return` beside it, and removes only the report. Guards and thresholds are neutered at the
- * condition instead, because for those the question is whether the THRESHOLD is watched, not whether
- * the push is.
- */
-const MUTATIONS = [
-  // ── the findings ──
-  [
-    "no-round-ledger",
-    "reporting a paper with no round manifests",
-    "if (!since && manifests.length === 0) {",
-    "if (false) {",
-    "must say so rather than pass",
-  ],
-  [
-    "two-open-rounds",
-    "reporting two manifests with no `closed:`",
-    "if (open.length > 1) {",
-    "if (false) {",
-    "silently pick one base",
-  ],
-  [
-    "no-open-round",
-    "reporting edits made with every round closed",
-    "if (dirty) {",
-    "if (false) {",
-    "authorised by nothing",
-  ],
-  [
-    "unresolvable-base",
-    "reporting a base revision that does not resolve",
-    'add(\n      "unresolvable-base",\n      `cannot read paper.md at',
-    "a round whose base does not resolve is a round with no gate",
-  ],
-  [
-    "ratchet/push",
-    "reporting growth past the declared budget",
-    "if (grew > budget) {",
-    "if (false) {",
-    "growth past the declared budget is the finding this gate exists for",
-  ],
-  // 🔴 Killed by the CLEAN CASE, not by the block that names the budget, and that is the honest
-  // record. Any mutation that makes the gate noisier trips block 1 before it reaches its own block,
-  // because block 1's fixture is a legal round and block 1 demands total silence. Block 1 is
-  // therefore the strongest assertion in the harness, and the three rows marked this way are its
-  // proof — see the note under the table at the bottom of this file.
-  [
-    "ratchet/budget",
-    "honouring the declared budget (every round is charged against 0)",
-    "const budget = num(active?.budget, 0);",
-    "const budget = 0;",
-    "a round that changed only its declared section, inside budget",
-  ],
-  [
-    "ratchet-cumulative",
-    "the compounding check across all rounds",
-    "if (cum > total) {",
-    "if (false) {",
-    "compounding to +66 must be caught",
-  ],
-  [
-    "hedge/push",
-    "reporting hedge density growth",
-    "if (dh > hb + 1e-9) {",
-    "if (false) {",
-    "hedges deposited by a review round, inside the word budget, must still be caught",
-  ],
-  [
-    "hedge/budget",
-    "honouring the declared hedge budget",
-    'const hb = num(active?.["hedge-budget"], 0);',
-    "const hb = 0;",
-    "declared its hedge budget in advance has paid for it",
-  ],
-  [
-    "overbroad-scope",
-    "reporting a `touches:` list that covers the paper",
-    "if (all.length && covered.length * 2 > all.length) {",
-    "if (false) {",
-    "declaring most of the document defeats the declaration",
-  ],
-  [
-    "undeclared/changed",
-    "reporting a changed section nobody declared",
-    'add(\n        "undeclared-section",\n        `"${s.heading}" ${how}',
-    'false && add(\n        "undeclared-section",\n        `"${s.heading}" ${how}',
-    "a change to Limitations under a manifest declaring only §3",
-  ],
-  [
-    "undeclared/removed",
-    "reporting a REMOVED section nobody declared",
-    'add(\n        "undeclared-section",\n        `"${h}" was removed',
-    'false && add(\n        "undeclared-section",\n        `"${h}" was removed',
-    "a REMOVED section must be caught",
-  ],
-  [
-    "cite/push",
-    "reporting a citation added mid-round",
-    'add(\n        "unauthorised-citation",',
-    'false && add(\n        "unauthorised-citation",',
-    "a cite added mid-round is ARIS's `new_cite`",
-  ],
-  [
-    "cite/allows",
-    "honouring `allows: new-citation`",
-    'if (!allows.has("new-citation")) {',
-    "if (true) {",
-    "a declared `new-citation` is authorised",
-  ],
-  [
-    "cite/bibitem",
-    "scanning the References list (prose markers only)",
-    "/gm)].map((m) => m[1]),\n    );",
-    "/gm)].map(() => null),\n    ).filter(Boolean);",
-    "a bibliography entry with NO inline marker",
-  ],
-  [
-    "number/push",
-    "reporting a numeric literal added mid-round",
-    'add(\n        "unauthorised-number",',
-    'false && add(\n        "unauthorised-number",',
-    "a figure that appears during a revision round",
-  ],
-  [
-    "number/allows",
-    "honouring `allows: new-number`",
-    'if (!allows.has("new-number")) {',
-    "if (true) {",
-    "a declared `new-number` is authorised",
-  ],
-  // Also killed by block 1 rather than by block 11b — the clean fixture's body already carries
-  // numbers, so a gate that stops filtering out numbers already present fires on a legal round.
-  [
-    "number/novelty",
-    "the rule that a number already in the paper is free to restate",
-    "const added = [...numbers(now)].filter((n) => !wasNums.has(n));",
-    "const added = [...numbers(now)];",
-    "a round that changed only its declared section, inside budget",
-  ],
-  [
-    "number/direction",
-    "comparing against the BASE (the 'already present' set becomes the current one)",
-    "const wasNums = numbers(base);",
-    "const wasNums = numbers(now);",
-    "a figure that appears during a revision round has no provenance row",
-  ],
-  [
-    "unknown-op",
-    "reporting an `allows:` entry this gate does not implement",
-    'add(\n        "unknown-op",',
-    'false && add(\n        "unknown-op",',
-    "must be reported. ARIS carries `new_theorem_env`",
-  ],
-  [
-    "manifest/base",
-    "rejecting a manifest with no `base:`",
-    "if (!out.base)\n    return {\n      error:",
-    "if (false)\n    return {\n      error:",
-    "a manifest with no base must be reported, not skipped",
-  ],
-  [
-    "manifest/touches",
-    "rejecting a manifest with no `touches:`",
-    "if (!Array.isArray(out.touches) || out.touches.length === 0) {",
-    "if (false) {",
-    "authorises nothing and must say so",
-  ],
-
-  // ── the shared machinery every finding above is computed from ──
-  [
-    "covers/nesting",
-    "number-prefix nesting in `touches:` (4 no longer covers 4.1)",
-    'num.startsWith(e + ".")',
-    "false",
-    "must cover §2.1",
-  ],
-  [
-    "covers/text",
-    "the substring rule for NON-numeric entries (`Appendix` covers nothing)",
-    "return h.includes(e);",
-    "return false;",
-    "moving a passage into an appendix must not read as growth",
-  ],
-  [
-    "split/appendix",
-    "the body↔appendix boundary (everything counts as body)",
-    "const i = secs.findIndex((s) => /^references\\b/i.test(s.heading));",
-    "const i = -1;",
-    "the appendix delta is still reported as a fact",
-  ],
-  [
-    "census/appendix",
-    "keeping appendix words out of the body count",
-    "    bodyWords: bw,",
-    '    bodyWords: bw + words(appendix.map((s) => s.text).join("\\n")),',
-    "appendix growth under a zero body budget must be free",
-  ],
-  [
-    "strip/comments",
-    "stripping HTML comments before every measurement",
-    'const stripComments = (s) => s.replace(/<!--[\\s\\S]*?-->/g, " ");',
-    "const stripComments = (s) => s;",
-    "rewriting a section's own TIGHTEN note must change nothing",
-  ],
-  [
-    "since/mode",
-    "`--since` running without a manifest",
-    'const since =\n    (args.find((a) => a.startsWith("--since=")) ?? "").split("=")[1] ||\n    undefined;',
-    "const since = undefined;",
-    "`--since` must still measure",
-  ],
-];
-
-// Two case shapes, and BOTH are preserved: the long `[name, disables, find, replace, expect]` and
-// the `false &&` shorthand `[name, disables, find, expect]`, where the replacement is the find with
-// `false && ` in front. The shorthand is the standard neuter for a finding — it keeps the statement,
-// the control flow and any `return` beside it, and removes only the report — so it earns its place
-// as data, and expanding it here keeps the engine ignorant of what a "finding" is.
-process.exit(
-  runMutations({
-    root: ROOT,
-    cases: MUTATIONS.map((m) => {
-      const [name, disables, find] = m;
-      const [replace, expect] =
-        m.length === 4 ? [`false && ${find}`, m[3]] : [m[3], m[4]];
-      return {
-        name,
-        disables,
-        edits: [[SRC, find, replace]],
-        harness: HARNESS,
-        expect,
-      };
-    }),
-  }),
-);

package/skills/plan-paper-timeline/plan-paper-timeline.effects.mutations.mjs

@@ -1,65 +0,0 @@
-/**
- * plan-paper-timeline.effects.mutations.mjs — the non-vacuity proof for the EFFECTS harness.
- *
- * Run: `node skills/plan-paper-timeline/plan-paper-timeline.effects.mutations.mjs` (slow: each
- * case spawns the real `claude` CLI against a scripted mock model).
- *
- * ── WHY THIS ONE IS EASY TO GET WRONG ───────────────────────────────────────
- * The effects harness spends most of its length proving that a run HAPPENED — the skill
- * activated, its body reached the model, a control tool answered. Those are preconditions, and a
- * harness made of preconditions passes for reasons that have nothing to do with the thing under
- * test. The two cases below plant defects in the two claims that are actually about §3.
- *
- * ── CASE 1: the zone in the prescription stops being the documented default ─
- * §3's example must carry `DEFAULT_TIMEZONE`, because the zone is the `timezone` CARRIER — it
- * belongs to the author, not to the pipeline. A REAL zone in the example is the silent defect:
- * it is valid, the calendar API accepts it, the harness's schema check passes, and every author
- * who copies the example schedules their deadlines in somebody else's day. `Asia/Tokyo` is
- * chosen precisely because it is well-formed; a malformed zone would be caught by the other
- * assertion and would prove the wrong half.
- *
- * ── CASE 2: the instruction to substitute disappears ────────────────────────
- * With the example showing a default and the "read the carrier" line deleted, the default
- * silently BECOMES the prescription — every anchor lands in UTC and nothing anywhere says so.
- * Removing the line leaves a file that still reads sensibly, which is why a human diff is not
- * enough and this case exists.
- */
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { runMutations } from "../../lib/mutation-driver.mjs";
-import { consumerRoot } from "../paper-pipeline/scripts/consumer.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const SKILL = join(HERE, "SKILL.md");
-const HARNESS = join(HERE, "plan-paper-timeline.effects.harness.mjs");
-
-process.exit(
-  runMutations({
-    root: consumerRoot(),
-    runner: "vigiles",
-    cases: [
-      {
-        name: "§3's example carries a real zone instead of the default",
-        disables:
-          "the rule that the prescription shows DEFAULT_TIMEZONE — a real zone reads as the zone to use",
-        edits: [[SKILL, '"timeZone": "UTC"', '"timeZone": "Asia/Tokyo"']],
-        harness: HARNESS,
-        expect: "must show the documented default",
-      },
-      {
-        name: "§3 stops telling the model to read the `timezone` carrier",
-        disables:
-          "the substitution instruction — without it the default stops being an example and becomes the prescription",
-        edits: [
-          [
-            SKILL,
-            "require('./paperlint.json')?.timezone } catch {} })() ?? 'UTC'",
-            "require('./paperlint.json')?.papersDir } catch {} })() ?? 'papers'",
-          ],
-        ],
-        harness: HARNESS,
-        expect: "tells the model to READ the `timezone` carrier",
-      },
-    ],
-  }),
-);