paperlint 3.0.0 → 3.1.1

package/skills/grade-paper-writing/prose-lint.mjs

@@ -45,8 +45,7 @@
  * from the neighbouring `CLAUDE.md` exactly as `pdf/profile` reads a venue profile, and the address
  * of the finding is the `## Abstract` line in the paper itself. Parity was taken BEFORE the deletion
  * on `compile-rules-2026/paper.md`: 306 words against a ceiling of 305, one finding in both places,
- * the same four numbers. The test and eight mutations are in
- * `eslint-rules/paper-craft.{harness,mutations}.mjs`.
+ * the same four numbers. The test is `eslint-rules/paper-craft.harness.mjs`.
  *
  * WHAT IS LEFT AND WHY — TWO. The paragraph below was written when there were three, and is kept as
  * a record: they read a SECOND ENTITY on the filesystem, while an ESLint rule sees one linted file:
@@ -313,11 +312,9 @@ const NOMINAL = /\b\w{4,}(tion|sion|ment|ance|ence|ity|ness)s?\b/gi;
 
 // JARGON — moved into `eslint-rules/paper-craft.mjs` (the `unexplained-jargon` rule, 2026-08-26).
 
+/** Matches of every pattern in the lexicon `pats`, summed. Every caller passes a lexicon array. */
 const count = (t, pats) =>
-  (Array.isArray(pats) ? pats : [pats]).reduce(
-    (n, p) => n + (t.match(p) || []).length,
-    0,
-  );
+  pats.reduce((n, p) => n + (t.match(p) || []).length, 0);
 // 🔴 Next to this lived `listHits(t, pats)` — the same walk, but returning THE MATCHES THEMSELVES
 // rather than their count. Nobody called it (`no-unused-vars`, 2026-08-28), and that is not a
 // trifle: the paragraph below explains that a metric was ignored precisely because it could not NAME
@@ -368,14 +365,17 @@ function splitSentences(t) {
 }
 const words = (t) => (t.match(/[A-Za-z0-9%.'’-]+/g) || []).length;
 
-function analyse(text) {
+/**
+ * The metrics of `text`, whose sentences the caller split and found non-empty — the same array is
+ * passed in rather than split again, so the check the caller made is the one the division relies on.
+ */
+function analyse(text, sents) {
   const W = words(text),
     per1k = (n) => +((n / W) * 1000).toFixed(1);
-  const sents = splitSentences(text);
   const lens = sents.map(words);
-  const mean = lens.reduce((a, b) => a + b, 0) / (lens.length || 1);
+  const mean = lens.reduce((a, b) => a + b, 0) / lens.length;
   const sd = Math.sqrt(
-    lens.reduce((a, b) => a + (b - mean) ** 2, 0) / (lens.length || 1),
+    lens.reduce((a, b) => a + (b - mean) ** 2, 0) / lens.length,
   );
 
   const cats = {
@@ -652,7 +652,21 @@ for (const f of args.filter((a) => !a.startsWith("--"))) {
   const raw = fs.readFileSync(f, "utf8");
   const isPdfText = f.endsWith(".txt");
   const prep = isPdfText ? pdfTextOnly : bodyOnly;
-  const r = analyse(prep(raw));
+  // 🔴 NOTHING LEFT IS NOT "CLEAN". A body that strips to no words used to be analysed anyway: every
+  // metric is a fraction of the word count, so the report printed NaN, FLAGged three metrics and
+  // exited 0. Refused like `.tex` above — no number is better than a meaningless one.
+  // A body of headings only has words but no sentence (headings are struck out before splitting),
+  // and a zero sentence count divides just the same, so the test is on sentences.
+  const text = prep(raw);
+  const sentences = splitSentences(text);
+  if (sentences.length === 0) {
+    console.error(
+      `prose-lint: ${f} has no prose to measure — after the frontmatter, comments, code ` +
+        "blocks, tables and the reference section are stripped, no word is left.",
+    );
+    process.exit(2);
+  }
+  const r = analyse(text, sentences);
   if (flagsOnly) {
     const lines = [];
     // Citation density in a paragraph and a pile-up of jargon in a sentence moved on 2026-08-26 into
@@ -678,7 +692,12 @@ for (const f of args.filter((a) => !a.startsWith("--"))) {
     // `hedge-density`, `discourse-subject`, `undefined-coinage`.
     if (lines.length) {
       flagged += lines.length;
-      console.error(`✍️  prose-lint — ${f.split("/").pop()}:`);
+      // The header STATES the count. run-mechanical.mjs prefers a stated "— N finding(s)" over
+      // counting output lines, and without it recorded header + findings + footer: one flagged
+      // caption became three findings in the ledger.
+      console.error(
+        `✍️  prose-lint — ${f.split("/").pop()} — ${lines.length} finding(s):`,
+      );
       lines.forEach((l) => console.error(l));
       console.error(
         "   run `node .claude/skills/grade-paper-writing/prose-lint.mjs <file>` for the sentences",

package/skills/grade-paper-writing/prose-lint.test.mjs

@@ -0,0 +1,153 @@
+/**
+ * prose-lint.mjs as a process — the way the skill and `run-mechanical.mjs` run it. Every mode, on
+ * fixtures written here, with the WHOLE output compared: the report is the product, so a changed
+ * number or a dropped line is a changed result.
+ */
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../test/support.mjs";
+
+const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "prose-lint.mjs");
+const root = useTempDir("prose-lint-");
+
+const LONG_CAPTION_SENTENCE = Array.from(
+  { length: 45 },
+  (_, i) => `word${i}`,
+).join(" ");
+const PAPER = `---
+title: A title the linter must not read as a sentence
+---
+# The paper
+
+<!-- TIGHTEN: a working note, not prose -->
+
+## Introduction
+
+In this paper we present a linter. It might possibly help, but this is not a proof. Clearly the
+first result matters (Section 3). Prior work agrees [1, 2]. The speedup was 40% on average across the
+full suite of papers, which suggests the method might hold generally.
+
+- The first item is short.
+- The second item is not long either.
+
+\`\`\`
+# a heading inside a code block is code
+\`\`\`
+
+| a | table |
+|---|---|
+| is | data |
+
+### Method
+
+We believe that rather than guessing, we measure. Instead of prose, the numbers speak.
+
+## References
+
+[1] A reference that is not prose.
+`;
+
+writeTree(root, {
+  "p/paper.md": PAPER,
+  "p/figures/fig1.tex": `\\begin{figure}\\caption{\\textbf{Big.} ${LONG_CAPTION_SENTENCE}. ${"More words here. ".repeat(20)}}\\end{figure}`,
+  // Empty once LaTeX commands and braces are stripped: skipped, not counted as a zero-word caption.
+  "p/figures/fig2.tex": "\\caption{\\centering}",
+  // A lone "#": no word at all, and no sentence either.
+  "p/figures/fig4.tex": "\\caption{{#}}",
+  "p/figures/notes.txt": "not a figure",
+  // Reads as a markdown heading once LaTeX is stripped ("# Big"), so it splits into NO sentence:
+  // the caption scan must not flag it and must not crash.
+  "p/figures/fig3.tex": "\\caption{{#} Big}",
+  "clean/paper.md": "## Intro\n\nShort and plain. Nothing else.\n",
+  "page.txt":
+    "A rendered page. It was hyphen-\nated across a line.\n\n12\n\fNext page text here.\nReferences\n[1] cut here.\n",
+  "paper.tex": "\\documentclass{article}",
+});
+
+test("no arguments: the usage line, exit 0", () => {
+  assert.deepEqual(runNode(SCRIPT), {
+    status: 0,
+    stdout: "",
+    stderr: "usage: node prose-lint.mjs <file.md|file.txt> [more files]\n",
+  });
+});
+
+test("a .tex file is refused with exit 2, and nothing is measured", () => {
+  const r = runNode(SCRIPT, [join(root, "paper.tex")]);
+  assert.deepEqual(
+    { status: r.status, stdout: r.stdout },
+    { status: 2, stdout: "" },
+  );
+  expect(r.stderr.replaceAll(root, "<root>")).toMatchSnapshot();
+});
+
+test("the full report over markdown and rendered text", () => {
+  const r = runNode(SCRIPT, [
+    join(root, "p", "paper.md"),
+    join(root, "page.txt"),
+  ]);
+  assert.deepEqual(
+    { status: r.status, stderr: r.stderr },
+    { status: 0, stderr: "" },
+  );
+  expect(r.stdout).toMatchSnapshot();
+});
+
+test("--headings lists every heading from level 2 to 4, in order", () => {
+  const r = runNode(SCRIPT, ["--headings", join(root, "p", "paper.md")]);
+  assert.deepEqual(
+    { status: r.status, stderr: r.stderr },
+    { status: 0, stderr: "" },
+  );
+  expect(r.stdout).toMatchSnapshot();
+});
+
+test("--flags-only: an over-long caption flags and exits 1", () => {
+  const r = runNode(SCRIPT, ["--flags-only", join(root, "p", "paper.md")]);
+  assert.deepEqual(
+    { status: r.status, stdout: r.stdout },
+    { status: 1, stdout: "" },
+  );
+  expect(r.stderr).toMatchSnapshot();
+});
+
+test("--flags-only: a paper with no figures directory is clean, exit 0 and silent", () => {
+  assert.deepEqual(
+    runNode(SCRIPT, ["--flags-only", join(root, "clean", "paper.md")]),
+    {
+      status: 0,
+      stdout: "",
+      stderr: "",
+    },
+  );
+});
+
+test("a file with no prose left to measure is refused with exit 2, not reported as NaN", () => {
+  writeTree(root, {
+    "empty/paper.md":
+      "---\ntitle: only frontmatter\n---\n<!-- and a note -->\n",
+  });
+  const file = join(root, "empty", "paper.md");
+  assert.deepEqual(runNode(SCRIPT, [file]), {
+    status: 2,
+    stdout: "",
+    stderr:
+      `prose-lint: ${file} has no prose to measure — after the frontmatter, comments, code ` +
+      "blocks, tables and the reference section are stripped, no word is left.\n",
+  });
+});
+
+test("a body of headings only has no sentence to measure, and is refused the same way", () => {
+  writeTree(root, { "headings/paper.md": "## Intro\n\n### Method\n" });
+  const file = join(root, "headings", "paper.md");
+  assert.deepEqual(runNode(SCRIPT, [file]), {
+    status: 2,
+    stdout: "",
+    stderr:
+      `prose-lint: ${file} has no prose to measure — after the frontmatter, comments, code ` +
+      "blocks, tables and the reference section are stripped, no word is left.\n",
+  });
+});

package/skills/paper-pipeline/grade-paper-writing-ablation.eval.mjs

@@ -752,9 +752,9 @@ function buildArm(a) {
   // WRITING is the opposite case, and a parser is the wrong tool: `yaml.dump` would
   // reformat the whole block, so the fixture would differ from the real file in ways
   // the ablation is not measuring. The line is READ OUT of the file instead of
-  // assumed — the idiom skills.mutations.mjs already uses — and a missing line is an
-  // error rather than a silent no-op, because a mutation that does not apply scores
-  // as a pass over a fixture nobody changed.
+  // assumed, and a missing line is an error rather than a silent no-op, because an
+  // edit that fails to apply would otherwise score as a pass over a fixture nobody
+  // changed.
   const setLine = (text, key, value) => {
     const line = new RegExp(`^${key}:.*\\n`, "m").exec(text); // kb-lint:markdown-regex-ok — editing a LINE, not parsing
     if (!line)

package/skills/paper-pipeline/scripts/README.md

@@ -10,7 +10,7 @@ each mechanical gate and check the gate says no (see **Harnesses**, added 2026-0
 > here, and **their tests, which until that day lay in another top-level directory**. That is,
 > colocation was missing precisely where we preach it: checker in the skill, its harness — outside.
 >
-> What remained without an owner (shared library of 24 skills, `markdown.mjs`, mutations engine) —
+> What remained without an owner (shared library of 24 skills, `markdown.mjs`) —
 > in [`.claude/lib/`](../../../lib/README.md), also there the breakdown of four forms of reference, from which
 > path-based search sees only one.
 
@@ -153,7 +153,7 @@ finished. Neither row present means it did not run, whatever any status file cla
 - `EXPECTED_GATES` in `status.mjs` is the table. A check that records rows and is absent there
   writes rows nobody sees. Add a new skill AND its mechanical checks; `unlistedGates()` catches the
   omission after the fact, and `pipeline-corpus.harness.mjs` catches it before.
-- `ledger.selftest.mjs` and every harness redirect `PIPELINE_LEDGER` to a temp file **before**
+- `ledger.test.mjs` and every harness redirect `PIPELINE_LEDGER` to a temp file **before**
   importing `ledger.mjs`. Save-and-restore is not isolation; it lost that race on its first day.
 
 ## Harnesses (2026-08-07)
@@ -184,133 +184,14 @@ These two are the only ones aimed at the **skills** rather than the scripts they
 is what `vigiles audit`'s `Tested` metric actually counts — "34 surfaces with no vigiles test/eval"
 was never about `structure.mjs`. It also fails differently: a script with a bad path crashes, a
 **skill** with a bad path is read by a model that quietly does something adjacent and reports success.
-Its non-vacuity proof is a separate file, `skills.mutations.mjs` — 21 planted defects, one per
-assertion class, each on a throwaway copy of `.claude/`, plus a control asserting the clean corpus
-produces _only_ the four known-red YAML findings so no case can pass on noise. Run it by hand after
-touching the harness (`node .claude/skills/paper-pipeline/scripts/skills.mutations.mjs`, ~3 s); CI runs it too.
-
-> **2026-09-24 — hand-written mutation batteries are deprecated (#52).** Do not write a new
-> `*.mutations.mjs` or add cases to an existing one; say what an assertion guards in a comment
-> directly above it. `npm run check` enforces this through `scripts/mutation-batteries.frozen.json`,
-> which may only shrink. The history below is kept as a record, not as an instruction.
-
-Nine harnesses now carry a mutations file of their own — `delivered-pdf.mutations.mjs` (25 rows), `bound-numbers.mutations.mjs` (12 rows),
-`round-diff.mutations.mjs` (28 rows), `ledger.mutations.mjs` (28 rows, covering the 2026-08-10
-refactor across both `gates.harness.mjs` and `skill-checks.mjs`), `artifact-coverage.mutations.mjs`
-(22 rows), `generated-code.mutations.mjs` (22 rows), `textidote.mutations.mjs` (20 rows) and
-`uncited-refs.mutations.mjs` (8 rows). They are run by
-hand, not in CI, because each one rewrites a source file dozens of times and takes minutes.
-
-> **2026-08-26 — `verify-refs.mjs` moved to the engine and deleted from here** (along with its harness and
-> mutations). Bibliography measurement now `extract-ref-facts.mjs` in the same folder, judgment — twelve
-> rules `refs/*` in `eslint-rules/ref-facts.mjs`, mutations — `eslint-rules/ref-facts.mutations.mjs`
-> (21 rows). Analysis — `the author's private research notes`.
-
-**2026-08-14 — the engine was split out into `mutation-driver.mjs`; the tables stayed.** Each file
-now holds only its cases (which defect, which bytes, which message — data about ITS checker) and
-calls `runMutations()`. The reason is not line count: the ten copies of the driver had DRIFTED, and
-the protections lived in whichever file happened to earn them. Counted against the committed
-versions — the no-op guard (a replacement equal to the original leaves a green harness proving
-nothing) was in **4 of 10**; the retry-once on a non-kill was in **1 of 10**; the strict rule that a
-mutation must be killed by its OWN named assertion, not merely by _something_ going red, was in
-**1 of 10**. All ten now have all three. Two dead-path defects were closed on the way: six `ledger`
-cases named `skills.harness.mjs`, deleted by the 2026-08-11 colocation, and `vigiles test` on a path
-matching nothing exits 0 — so those six reported SURVIVED on every run since (they now go red at
-their own assertions, verified by running them). And the end-of-run "restore failed" line had been
-firing on `gates.harness.mjs`, which is red **on purpose** — the driver now baselines the harnesses
-before touching anything, so that claim means what it says. `skills.mutations.mjs` deliberately
-stays outside the engine: it mutates a COPY of `.claude/`, which is right for cases whose subject
-IS the skill corpus, and it is the only one CI runs. **The
-first run of a mutations file has never yet been clean, and that is the argument for writing one.**
-`delivered-pdf`'s first run left five survivors and three wrong-case hits, and unpicking them found
-three fixtures that tested nothing they claimed to (a window assertion satisfied by ordering, a
-digit-width guard the counter never reached), two mutations that did not mutate, and **one dead rule
-in the checker itself** — a table of sixteen Unicode space separators whose removal changed no
-verdict, because Python's `\s` already matched every one of them. It was deleted rather than tested.
-
-The two 2026-08-10 files kept the streak, and both findings were about the TEST rather than the
-checker. `uncited-refs`'s heading-offset row SURVIVED, which said either that the offset was dead
-code or that nothing watched it; reading `checkcites.lua` settled it — line 359 prints `=> <name>`
-for an auxiliary file it could not resolve and then CARRIES ON into the report, and LaTeX writes
-`\@input{sub.aux}` for every `\include`, so without the offset a partial build makes the wrapper
-report `nope.aux` as an uncited bibliography entry. A fabricated finding, in a report somebody
-would act on. `textidote`'s run reported `key/rule` as a WRONG-CASE kill three times running, and
-each fix exposed the next layer: the key assertions sat after the delta block (so a key defect was
-named by the delta's message), then a finding's rule was being read back out of the key (so a key
-defect was named by the PARSER's message), then the two warnings in the fixture were in the order
-that hides a collapsing key. **And the third fix silently deleted two assertion blocks** — a
-scripted reorder dropped the delta and case blocks, the harness stayed green, and the only signal
-was the next mutation run reporting `key/case` as SURVIVED. Deleting assertions can never turn a
-harness red; nothing but a mutation run can see it.
-
-The two 2026-08-10 arrivals kept the streak, and one of them found a defect in the CHECKER rather
-than in a test. `generated-code`'s first run left **three survivors**:
-
-- **A quiet case that was quiet for the wrong reason.** The fixture proving `--seed` in an argparse
-  call is recognised drew with `rnd.sample(...)` off a local `random.Random(...)`, which the
-  draw pattern does not recognise as a draw at all. So the case passed because _nothing was
-  detected_, not because the seed was — neutering the seed rule changed no verdict. This is the
-  same shape as `delivered-pdf`'s window assertion satisfied by ordering, and it is invisible on
-  inspection: the fixture reads like a correct script, because it is one.
-- **🔴 A dead flag in the checker.** The absolute-path rule is written case-sensitive on purpose —
-  without it an Express route `/users/export` matches `/Users/`. But the matcher was built with
-  `new RegExp(ABS.source + …, 'g')`, which takes the source and **throws the flags away**. Adding
-  an `i` to the pattern therefore changed nothing, i.e. a mutation that did not mutate, i.e. the
-  property the harness asserted lived nowhere the harness could reach. Fixed by threading
-  `ABS.flags` through, which makes the flag load-bearing for the first time.
-- **A mutation that could not change the answer.** Loosening the READ side of the in-place rule
-  alone can never produce a finding, because the WRITE side still demands a quoted literal and no
-  operand can pair. That row now spans both arrays, and says so.
-
-`artifact-coverage`'s 22 rows all killed on the first run, but four killed at a DIFFERENT assertion
-than named, and two of those were the expectation string matching a fragment of prose that appears
-in more than one message (`"that is the"`) — the `no-witness` defect from `ledger.mutations.mjs`,
-committed again three days later. Two rows legitimately kill at an earlier case that asserts the
-same property, and each says which, so a future reader does not read it as off-target. One harness
-case was also restructured because two rows were landing on a shared assertion: a case that tests
-an EXCLUSION should not assert the finding count, or a mutation of the header lands there and hides
-which property actually broke.
-
-The reverse leg's own first run on the live paper found a third defect, this time in the port:
-matching a directory name with `includes()` acquitted a fixture directory called `a-2026-01-01` on
-the strength of the letter "a" appearing in the prose. Substring matching in a cherry-picking
-detector fails in the dangerous direction — it invents evidence that a result was mentioned — and
-it is now whole-token with a minimum length.
-
-`round-diff`'s first run was six rows wrong out of twenty-six, and one of those was a hole in the
-checker rather than in the test: disabling the number-prefix rule in `covers()` changed **no**
-verdict, because a substring fallback had been silently doing its work — which also meant
-`touches: ["2"]` covered "Section 12" and every heading containing a 2, so a one-character
-declaration authorised most of the paper while `overbroad-scope` stayed quiet because the _list_ was
-short. Two more rows were the test's own fault in the two documented ways: a `find` string written
-in its already-mutated form (a mutation that did not mutate), and a fixture that MOVED text between
-body and appendix — which keeps the total constant and therefore cannot test the boundary at all.
-
-`ledger.mutations.mjs` kept the streak: five survivors and two wrong-case kills on its first run,
-and **every one was a defect in the assertion rather than in the checker.** Two matched a bare word
-(`no-witness`, `input-missing`) that the CLI's usage block prints unconditionally, so the refusal
-message could have said anything at all. The dead-report-path case asserted only a non-zero exit —
-which the next line's `ENOENT` supplies once the check is deleted. The status view's reason
-assertion matched the explanatory PARAGRAPH rather than the check's own row, so the reason could
-have been stripped from every row and the test stayed green. And the legacy fixture recorded `PASS`
-with `findings: 0`, which made "a retired acquittal carries nothing forward" true by accident —
-real `PASS` rows carry counts (`sweep-design-space`, 8). One mutation also turned out to be
-**inexpressible finely**: disabling only the no-report-path arm makes the next line `resolve()` a
-null and throw, so the run goes red for a reason unrelated to the check. That row disables the whole
-evidence contract instead and relies on assertion order, which is written down in the row's note.
-
-The `--blocking` flag was found the same way and is worth naming separately, because it is not a
-test defect: it shipped **documented in the usage text and in all 22 SKILL.md files while nothing in
-the CLI parsed it**. Every skill instructing `--blocking` for its desk-reject case would have
-recorded an ordinary advisory finding. That is the repository's oldest failure — a documented
-mechanism nothing implements, the same shape as three hooks dead on arrival and a nudge dead for
-twelve days — arriving _inside_ the refactor written to end it. Block 14 of `gates.harness.mjs` now
-asserts every advertised flag from outside the process, in both directions.
-
-⚠️ A mutations file refuses to start on a dirty working tree, because it rewrites the source it is
-proving. Commit first. (`ledger.mutations.mjs` touches `status.mjs` and `run-mechanical.mjs`, which
-another session may be editing; running it against a copy of `.claude/` with `CLAUDE_PROJECT_DIR`
-pointed at the copy works and is how it was last verified.)
+Its non-vacuity proof is `lib/skill-checks.test.mjs` — a copy of the shipped skills with defects
+planted on the copy, checked against both `checkSkill` (pipeline skills) and `checkProseSkill`
+(skills without the pipeline). Run it with `npx vitest run lib/skill-checks.test.mjs`; CI runs it
+too.
+
+> **2026-09-26 — hand-written per-checker mutation batteries are REMOVED (#52).** Do not write a
+> `*.mutations.mjs`; see a new test fail before the fix and assert whole values instead (the
+> repository's CLAUDE.md, § Testing).
 
 Five rules, each learned by getting it wrong here:
 
@@ -321,10 +202,10 @@ Five rules, each learned by getting it wrong here:
    importing `ledger.mjs`. Save-and-restore is not isolation; it loses the race on the first crash.
 3. **Run them by explicit path.** `npx vigiles test` with no arguments finds **nothing** here: its
    glob does not descend into dot-directories. Every harness is therefore named explicitly in
-   `.github/workflows/paper-gates.yml` (`hooks` job) — one not named there does not run, and its
+   the `hooks` job of `.github/workflows/ci.yml` — one not named there does not run, and its
    silence looks exactly like having nothing to say. Add the line in the same commit as the file.
-4. **Prove non-vacuity by MUTATION, never by reading.** An assertion you cannot see fail is an
-   assertion you have not tested. `skill-checks.mjs` (then `skills.harness.mjs`) shipped its first draft with a record-block
+4. **Prove non-vacuity by SEEING IT FAIL, never by reading.** An assertion you cannot see fail is
+   an assertion you have not tested. `skill-checks.mjs` (then `skills.harness.mjs`) shipped its first draft with a record-block
    slicer matching `^#` against an already-sliced string; `^` hit offset 0, every block came back as
    the single character `#`, one assertion then fired on all 21 skills while its neighbour checked
    nothing at all. Both were invisible on inspection and obvious on the first planted defect.

package/skills/paper-pipeline/scripts/announce.test.mjs

@@ -0,0 +1,102 @@
+/**
+ * announce.mjs — the first line of every wired skill's `## Run me` block: a banner on stderr naming
+ * the paper and skill versions, and a `started` abstention in the ledger. Run as the skills run it,
+ * against a temp consumer and a temp ledger.
+ */
+import assert from "node:assert/strict";
+import { cpSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, "announce.mjs");
+const root = useTempDir("announce-");
+const consumer = join(root, "consumer");
+const LEDGER = join(root, "runs.jsonl");
+writeTree(root, { "consumer/papers/p/paper.md": "# P\n\ntext\n" });
+cpSync(
+  join(HERE, "..", "..", "cold-read-diff"),
+  join(consumer, ".claude", "skills", "cold-read-diff"),
+  {
+    recursive: true,
+    verbatimSymlinks: true,
+  },
+);
+const env = { CLAUDE_PROJECT_DIR: consumer, PIPELINE_LEDGER: LEDGER };
+process.env.CLAUDE_PROJECT_DIR = consumer;
+process.env.PIPELINE_LEDGER = LEDGER;
+const { inputHash, skillHash } = await import("./ledger.mjs");
+
+const rows = () =>
+  readFileSync(LEDGER, "utf8")
+    .trim()
+    .split("\n")
+    .map((l) => JSON.parse(l))
+    .map(({ skill, check, paper, kind, reason, note }) => ({
+      skill,
+      check,
+      paper,
+      kind,
+      reason,
+      note,
+    }));
+afterEach(() => rmSync(LEDGER, { force: true }));
+
+test("no skill name: the usage line, exit 2, nothing recorded", () => {
+  assert.deepEqual(runNode(SCRIPT, [], { env }), {
+    status: 2,
+    stdout: "",
+    stderr: "usage: announce.mjs <skill-name> [paper-dir]\n",
+  });
+});
+
+test("a skill on a paper: the banner names both versions, and a `started` row is recorded", () => {
+  const paper = join(consumer, "papers", "p");
+  const r = runNode(SCRIPT, ["cold-read-diff", paper], { env });
+  assert.deepEqual(
+    { ...r, rows: rows() },
+    {
+      status: 0,
+      stdout: "",
+      stderr:
+        "▶ cold-read-diff  —  p\n" +
+        `  paper ${inputHash(paper).slice(0, 8)} · skill ${skillHash("cold-read-diff").slice(0, 8)}\n`,
+      rows: [
+        {
+          skill: "cold-read-diff",
+          check: "cold-read-diff",
+          paper: "p",
+          kind: "ABSTAINED",
+          reason: "started",
+          note: "no verdict recorded yet",
+        },
+      ],
+    },
+  );
+});
+
+test("no paper directory and an unknown skill still announce, with placeholders", () => {
+  const r = runNode(SCRIPT, ["no-such-skill", join(root, "nowhere")], { env });
+  assert.deepEqual(
+    { status: r.status, stderr: r.stderr, kind: rows()[0].kind },
+    {
+      status: 0,
+      stderr:
+        "▶ no-such-skill  —  no paper dir\n  paper (none) · skill ????????\n",
+      kind: "ABSTAINED",
+    },
+  );
+});
+
+test("no paper argument means the current directory", () => {
+  const r = runNode(SCRIPT, ["cold-read-diff"], {
+    env,
+    cwd: join(consumer, "papers", "p"),
+  });
+  assert.deepEqual(
+    { status: r.status, firstLine: r.stderr.split("\n")[0] },
+    { status: 0, firstLine: "▶ cold-read-diff  —  p" },
+  );
+});

package/skills/paper-pipeline/scripts/artifact-coverage.test.mjs

@@ -0,0 +1,86 @@
+/**
+ * artifact-coverage.mjs on the inputs its harness does not build: no argument, no markdown paper,
+ * a free-section heading on the paper's very first line, a numbered section without subsections,
+ * an index naming the same path twice / a glob / a URL / a repro path, no repro/ at all, a
+ * grandfather row without a reason, and a plain file among the repro/ entries.
+ */
+import assert from "node:assert/strict";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+
+const SCRIPT = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "artifact-coverage.mjs",
+);
+const root = useTempDir("artifact-coverage-");
+const run = (...args) => runNode(SCRIPT, args);
+
+test("no argument prints the usage; a paper with no markdown source is a named skip", () => {
+  assert.deepEqual(run(), {
+    status: 0,
+    stdout: "",
+    stderr: "usage: node artifact-coverage.mjs <paper-dir> [--flags-only]\n",
+  });
+  const tex = writeTree(join(root, "tex"), { "paper.tex": "x" });
+  const r = run(tex);
+  assert.equal(r.status, 0);
+  assert.match(
+    r.stderr,
+    /artifact coverage SKIPPED for .* — no paper\.md\/draft\.md/,
+  );
+});
+
+test("a section without subsections is checked against its own number; the index's odd paths are passed over", () => {
+  const dir = writeTree(join(root, "odd"), {
+    "paper.md": "## 3. Results\n\nWe measured **42 %** of runs.\n",
+    "artifact/README.md": [
+      "Section 7 only.",
+      "`data/rows.tsv` and again `data/rows.tsv`",
+      "`runs/*/out.json`",
+      "`https://example.org/x.json`",
+      "`repro/work/tmp.json`",
+    ].join("\n"),
+  });
+  const r = run(dir);
+  assert.match(
+    r.stdout,
+    /§3 reports 1 bolded figure\(s\) and is named NOWHERE/,
+  );
+  assert.match(
+    r.stdout,
+    /the index names `data\/rows\.tsv` and `data` is not in the bundle/,
+  );
+  assert.equal(r.stdout.match(/rows\.tsv/g)?.length, 1);
+  assert.doesNotMatch(r.stdout, /out\.json|example\.org|tmp\.json/);
+  assert.match(
+    r.stdout,
+    /reverse check \(results on disk nobody reports\): SKIPPED — no repro\/ directory/,
+  );
+});
+
+test("a free-section heading on the first line does not end the body at offset 0", () => {
+  const dir = writeTree(join(root, "first-line"), {
+    "paper.md": "## Limitations\n\nNone.\n\n## 2. Method\n\nIt took **9 s**.\n",
+    "artifact/README.md": "nothing\n",
+  });
+  assert.match(run(dir).stdout, /§2 reports 1 bolded figure\(s\)/);
+});
+
+test("repro/: a plain file is not a candidate, a dot-directory is swallowed and named; a grandfather row with no reason says so", () => {
+  const dir = writeTree(join(root, "grandfathered"), {
+    "paper.md": "## 1. Intro\n\nText.\n",
+    "artifact/README.md": "§1\n",
+    "repro/notes.txt": "a file, not an analysis",
+    "repro/.cache/RESULTS.md": "a dot-directory, swallowed before counting",
+    "repro/old-run/RESULTS.md": "done\n",
+    "repro/unreported-grandfathered.txt": "old-run\n",
+  });
+  const out = run(dir).stdout;
+  assert.match(out, / {7}old-run {2}→ {2}\(NO REASON GIVEN\)/);
+  assert.match(
+    out,
+    /• 1 before they were counted — dot-directories and build\/dependency trees[^\n]*\n {7}\.cache/,
+  );
+});

package/skills/paper-pipeline/scripts/consumer.d.mts

@@ -23,7 +23,14 @@ export interface DanglingSkillLink {
  * `SKILL.md`, symlinks followed. Throws an error with `code: "DANGLING_SKILL_LINK"` and a
  * `dangling: DanglingSkillLink[]` property when any entry is a link that does not resolve.
  */
-export declare function installedSkills(dir: string): string[];
+/** The four filesystem calls `installedSkills` makes — a test passes a fake. */
+export interface SkillsFs {
+  readdirSync(dir: string): string[];
+  statSync(path: string): { isDirectory(): boolean };
+  existsSync(path: string): boolean;
+  readlinkSync(path: string): string;
+}
+export declare function installedSkills(dir: string, fs?: SkillsFs): string[];
 
 /** The directory of venue TeX files this package ships; `paperlint build` prepends it to TEXINPUTS. */
 export declare function packageVenuesDir(): string;

package/skills/paper-pipeline/scripts/consumer.harness.mjs

@@ -298,9 +298,9 @@ assert.equal(
 
   // 🔴 RELATIVE, AND `/`-SEPARATED, ASSERTED BEFORE THE EQUALITIES BELOW — and the order is a
   // finding, not a preference. `assert` aborts at the first failure, so with this line placed
-  // after them a resolver that returned an absolute path died on "must be returned as written":
-  // the mutation run reported RED-but-a-DIFFERENT-case, i.e. this assertion was never reached and
-  // nothing showed it can fail. The narrow property goes first; the equalities then cover the rest.
+  // after them a resolver that returned an absolute path died on "must be returned as written" —
+  // a RED result, but for a different case than this one, i.e. this assertion was never reached
+  // and nothing showed it can fail. The narrow property goes first; the equalities then cover the rest.
   // The value is compared against text a human typed inside a SKILL.md, so an absolute path makes
   // every `startsWith` false — not an error, an empty loop body.
   assert.equal(