paperlint 7.1.0 → 8.0.0

package/scripts/refresh-deadlines.ts

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+/**
+ * THE SHIPPED PRESETS' DEADLINES, RE-READ FROM THEIR PORTALS — run once a day by
+ * `.github/workflows/deadlines.yml`, which opens or updates one pull request when a value changed.
+ *
+ *   node scripts/refresh-deadlines.ts [--presets <dir>] [--summary <file.md>]
+ *
+ * For every preset in the directory whose `portal` has an adapter (HotCRP today), the portal's public
+ * deadlines page is read and compared with the preset's `deadlines`:
+ *
+ *   a kind the page lists at the instant the preset holds   kept as it is, its `read` day too
+ *   a kind the page lists at another instant                rewritten, `read` = today
+ *   a kind the page lists that the preset does not hold     added, `read` = today
+ *   a kind the preset holds that the page no longer lists   KEPT and noted — a portal may drop a
+ *                                                           passed deadline; the reading stays true
+ *   a reading from the call                                 never touched: it is not the portal's
+ *
+ * Only a changed value rewrites the file, so an unchanged portal produces no diff and no pull
+ * request: a `read` day says when the value was last READ DIFFERENT, not when the job last ran.
+ *
+ * ── IT REPORTS, IT DOES NOT BLOCK ─────────────────────────────────────────────────────────────
+ * A portal that is down, gone or no longer a HotCRP page is a `::warning::` line and a line in the
+ * summary, and the run exits 0 — the venue's outage is not this repository's defect, and the next
+ * day's run reads it again. A preset that does not parse IS this repository's defect: `::error::`,
+ * exit 1. The main CI never runs this script against the network; its tests replay the pages
+ * recorded in `src/adapters/hotcrp/cassette/`.
+ *
+ * The block is found on the JSONC's syntax tree (TypeScript's JSON parser, the one the presets are
+ * read with) and replaced; everything else in the file — its comments above all — is left as it
+ * is, and Prettier formats the result as `npm run fmt` would.
+ */
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { format } from "prettier";
+import ts from "typescript";
+import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { hotcrpDeadlines } from "../src/adapters/hotcrp/index.ts";
+import {
+  DEADLINE_WHATS,
+  type DeadlineWhat,
+  type IsoDate,
+  type PortalDeadlines,
+  type Reading,
+} from "../src/domain/deadline.ts";
+import type { Result } from "../src/domain/result.ts";
+import {
+  supportedPortal,
+  type PortalFailure,
+} from "../src/domain/submission.ts";
+import { messageOf } from "../src/domain/text.ts";
+import { presetsDir } from "../src/package-dirs.ts";
+import { parsePreset } from "../src/tex-requirements.ts";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** Reads the deadlines page of the portal site at `site` (no trailing slash). */
+export type ReadPortal = (
+  site: string,
+) => Promise<Result<PortalDeadlines, PortalFailure>>;
+
+/** What happened to one preset. */
+export type Outcome =
+  | { readonly kind: "skipped"; readonly why: string }
+  | { readonly kind: "broken"; readonly why: string }
+  | { readonly kind: "unreadable"; readonly url: string; readonly why: string }
+  | {
+      readonly kind: "unchanged";
+      readonly url: string;
+      readonly notes: readonly string[];
+    }
+  | {
+      readonly kind: "changed";
+      readonly url: string;
+      readonly text: string;
+      readonly changes: readonly string[];
+      readonly notes: readonly string[];
+    };
+
+/** The preset's readings after the page's answer, what changed, and what is worth a note. */
+export interface Refreshed {
+  readonly readings: readonly Reading[];
+  readonly changes: readonly string[];
+  readonly notes: readonly string[];
+}
+
+/** The page's instants for one kind, earliest first. */
+const pageAts = (page: PortalDeadlines, what: DeadlineWhat): string[] =>
+  page.deadlines
+    .filter((d) => d.what === what)
+    .map((d) => d.at)
+    .toSorted();
+
+/** A kind the page does not list: the preset's reading, if it holds one, is kept and noted. */
+const offThePage = (
+  what: DeadlineWhat,
+  held: Reading | undefined,
+): Refreshed =>
+  held === undefined
+    ? { readings: [], changes: [], notes: [] }
+    : {
+        readings: [held],
+        changes: [],
+        notes: [`${what}: no longer on the page — kept as read ${held.read}`],
+      };
+
+/** One kind: the preset's portal reading against the page's. */
+function oneKind(
+  what: DeadlineWhat,
+  held: Reading | undefined,
+  ats: readonly string[],
+  o: { readonly url: string; readonly today: IsoDate },
+): Refreshed {
+  const notes =
+    ats.length > 1
+      ? [`${what}: the page lists ${ats.join(", ")} — the earliest is recorded`]
+      : [];
+  const at = ats[0];
+  if (at === undefined) return offThePage(what, held);
+  if (held?.at === at) return { readings: [held], changes: [], notes };
+  const fresh: Reading = {
+    what,
+    at,
+    source: "portal",
+    url: o.url,
+    read: o.today,
+  };
+  const change =
+    held === undefined ? `${what}: added ${at}` : `${what}: ${held.at} → ${at}`;
+  return { readings: [fresh], changes: [change], notes };
+}
+
+/**
+ * The preset's readings after the portal answered `page` at `url` on `today`. The call's readings
+ * are kept as they are; the portal's are kept, rewritten or added kind by kind. Pure.
+ */
+export function refreshReadings(
+  current: readonly Reading[],
+  page: PortalDeadlines,
+  url: string,
+  today: IsoDate,
+): Refreshed {
+  const perKind = DEADLINE_WHATS.map((what) => {
+    const portal = oneKind(
+      what,
+      current.find((r) => r.what === what && r.source === "portal"),
+      pageAts(page, what),
+      { url, today },
+    );
+    const call = current.filter((r) => r.what === what && r.source === "call");
+    return { ...portal, readings: [...portal.readings, ...call] };
+  });
+  return {
+    readings: perKind.flatMap((k) => k.readings),
+    changes: perKind.flatMap((k) => k.changes),
+    notes: perKind.flatMap((k) => k.notes),
+  };
+}
+
+/** The top-level property `name` of a JSONC object, on its syntax tree; undefined when absent. */
+function property(
+  file: ts.JsonSourceFile,
+  name: string,
+): ts.PropertyAssignment | undefined {
+  const top = file.statements[0]?.expression;
+  if (top === undefined || !ts.isObjectLiteralExpression(top)) return undefined;
+  return top.properties
+    .filter(ts.isPropertyAssignment)
+    .find((p) => ts.isStringLiteral(p.name) && p.name.text === name);
+}
+
+/**
+ * The preset's text with `deadlines` set to `readings`: the value replaced where the key is, or the
+ * key inserted after `portal`. Formatted as the repository formats a preset.
+ */
+export async function withDeadlines(
+  text: string,
+  file: string,
+  readings: readonly Reading[],
+): Promise<string> {
+  const tree = ts.parseJsonText(file, text);
+  const json = JSON.stringify(readings, null, 2);
+  const held = property(tree, "deadlines");
+  const spliced =
+    held === undefined
+      ? insertAfterPortal(tree, text, json)
+      : text.slice(0, held.initializer.getStart(tree)) +
+        json +
+        text.slice(held.initializer.end);
+  return format(spliced, { filepath: file });
+}
+
+/** `"deadlines": …` after the `portal` property — only a preset with a portal is ever refreshed. */
+function insertAfterPortal(
+  tree: ts.JsonSourceFile,
+  text: string,
+  json: string,
+): string {
+  const portal = property(tree, "portal");
+  if (portal === undefined)
+    throw new Error(`${tree.fileName}: no "portal" to put "deadlines" after`);
+  return `${text.slice(0, portal.end)},\n\n  "deadlines": ${json}${text.slice(portal.end)}`;
+}
+
+/** A failure to read the page, in one line. */
+function failureText(f: PortalFailure): string {
+  switch (f.kind) {
+    case "unreachable":
+      return `unreachable: ${f.detail}`;
+    case "refused":
+      return `HTTP ${String(f.httpStatus)}: ${f.messages.map((m) => m.message).join("; ")}`;
+    case "malformed":
+      return `not the page expected (HTTP ${String(f.httpStatus)}): ${f.detail}`;
+  }
+}
+
+/** One preset: its portal read, its readings compared, its new text when one changed. */
+export async function refreshPreset(o: {
+  readonly file: string;
+  readonly text: string;
+  readonly read: ReadPortal;
+  readonly today: IsoDate;
+}): Promise<Outcome> {
+  const parsed = ((): ReturnType<typeof parsePreset> | string => {
+    try {
+      return parsePreset(o.text, o.file, presetsDir());
+    } catch (e) {
+      return messageOf(e);
+    }
+  })();
+  if (typeof parsed === "string") return { kind: "broken", why: parsed };
+  if (parsed.portal === null) return { kind: "skipped", why: "no portal" };
+  const portal = supportedPortal(parsed.portal);
+  if (!portal.ok) return { kind: "skipped", why: portal.error };
+  const url = `${portal.value.url}/deadlines`;
+  const page = await o.read(portal.value.url);
+  if (!page.ok)
+    return { kind: "unreadable", url, why: failureText(page.error) };
+  const r = refreshReadings(parsed.deadlines ?? [], page.value, url, o.today);
+  if (r.changes.length === 0) return { kind: "unchanged", url, notes: r.notes };
+  const text = await withDeadlines(o.text, o.file, r.readings);
+  return { kind: "changed", url, text, changes: r.changes, notes: r.notes };
+}
+
+/** The lines one preset's outcome contributes: to the log (annotations included) and to the summary. */
+function report(
+  name: string,
+  o: Outcome,
+): { readonly log: readonly string[]; readonly md: readonly string[] } {
+  switch (o.kind) {
+    case "skipped":
+      return { log: [], md: [] };
+    case "broken":
+      return {
+        log: [`::error title=deadlines::${name} does not parse: ${o.why}`],
+        md: [`- 🔴 \`${name}\` does not parse: ${o.why}`],
+      };
+    case "unreadable":
+      return {
+        log: [
+          `::warning title=deadlines::${name}: could not read ${o.url} — ${o.why}`,
+        ],
+        md: [`- ⚠️ \`${name}\`: could not read ${o.url} — ${o.why}`],
+      };
+    case "unchanged":
+      return { log: o.notes.map((n) => `${name}: ${n}`), md: [] };
+    case "changed":
+      return changedReport(name, o);
+  }
+}
+
+/** A changed preset: each change and note, in the log and as a list in the summary. */
+const changedReport = (
+  name: string,
+  o: Extract<Outcome, { kind: "changed" }>,
+): { readonly log: readonly string[]; readonly md: readonly string[] } => {
+  const lines = [...o.changes, ...o.notes];
+  return {
+    log: lines.map((c) => `${name}: ${c}`),
+    md: [`- \`${name}\` (${o.url})`, ...lines.map((c) => `  - ${c}`)],
+  };
+};
+
+export interface MainOptions {
+  readonly presetsDir: string;
+  readonly read: ReadPortal;
+  readonly today: IsoDate;
+  readonly log: (line: string) => void;
+  readonly write: (file: string, text: string) => void;
+  /** Where the pull request's body goes; null: nowhere. */
+  readonly summary: string | null;
+}
+
+/** Every preset of the directory, refreshed — a changed one written back. */
+async function outcomesOf(
+  o: MainOptions,
+): Promise<readonly { readonly name: string; readonly out: Outcome }[]> {
+  const names = readdirSync(o.presetsDir)
+    .filter((f) => f.endsWith(".jsonc"))
+    .toSorted();
+  return Promise.all(
+    names.map(async (name) => {
+      const file = join(o.presetsDir, name);
+      const text = readFileSync(file, "utf8");
+      const out = await refreshPreset({
+        file,
+        text,
+        read: o.read,
+        today: o.today,
+      });
+      if (out.kind === "changed") o.write(file, out.text);
+      return { name, out };
+    }),
+  );
+}
+
+/** Every preset of the directory, refreshed. 0 unless a preset does not parse. */
+export async function main(o: MainOptions): Promise<number> {
+  const outcomes = await outcomesOf(o);
+  const reports = outcomes.map(({ name, out }) => report(name, out));
+  reports
+    .flatMap((r) => r.log)
+    .forEach((l) => {
+      o.log(l);
+    });
+  const count = (k: Outcome["kind"]) =>
+    outcomes.filter((x) => x.out.kind === k).length;
+  const read = count("changed") + count("unchanged");
+  o.log(
+    count("changed") === 0
+      ? `✓ no deadline changed: ${String(read)} preset(s) with a portal read, ${String(count("skipped"))} skipped`
+      : `${String(count("changed"))} preset(s) changed`,
+  );
+  if (o.summary !== null)
+    o.write(
+      o.summary,
+      summaryOf(
+        o.today,
+        reports.flatMap((r) => r.md),
+      ),
+    );
+  return count("broken") > 0 ? 1 : 0;
+}
+
+/** The pull request's body. */
+const summaryOf = (today: IsoDate, lines: readonly string[]): string =>
+  [
+    `The venue presets' deadlines, re-read on ${today} from each preset's portal by \`.github/workflows/deadlines.yml\` (\`scripts/refresh-deadlines.ts\`). A reading whose value changed carries today's \`read\` day; the others keep theirs.`,
+    "",
+    ...lines,
+    "",
+    "Merging releases a patch; papers get the new dates through their normal update of paperlint.",
+    "",
+  ].join("\n");
+
+/** `--presets <dir>` and `--summary <file>` from the command line. */
+export function argsOf(argv: readonly string[]): {
+  readonly presets: string;
+  readonly summary: string | null;
+} {
+  const value = (flag: string): string | null => {
+    const i = argv.indexOf(flag);
+    return i === -1 ? null : (argv[i + 1] ?? null);
+  };
+  return {
+    presets: value("--presets") ?? join(ROOT, "presets"),
+    summary: value("--summary"),
+  };
+}
+
+// `isMain`, not a comparison with `file://${argv[1]}`: that is false through a symlink (consumer.mjs).
+if (isMain(import.meta.url)) {
+  const args = argsOf(process.argv.slice(2));
+  process.exit(
+    await main({
+      presetsDir: args.presets,
+      read: (site) => hotcrpDeadlines({ url: site }).read(),
+      // The clock is read here, at the edge: the day a reading was taken.
+      today: new Date().toISOString().slice(0, 10),
+      log: console.log,
+      write: (file, text) => {
+        writeFileSync(file, text);
+      },
+      summary: args.summary,
+    }),
+  );
+}

package/skills/cold-read-diff/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 allowed-tools: [Bash, Read, Agent]
 ---
 
-<!-- vigiles:sha256:293f0627e6873774 compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:c3a1f2644781eb6f compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
 
 # cold-read-diff — the reader who cannot fake understanding
 
@@ -55,7 +55,7 @@ one, and its confusion is the finding.
 
 ## How to run it
 
-1. **Take the diff.** `git diff -U0 -- <paper.md>` since the last commit, or the `new_string` of the
+1. **Take the diff.** `git diff -U0 -- <paper.tex>` since the last commit, or the `new_string` of the
    edits just applied. Prose only — skip comments, tables, bibliography.
 2. **Spawn TWO agents with no repository context, one per persona, in parallel.** Give each the
    changed paragraphs **as text in the prompt**, not as a file path. A path is an invitation to read
@@ -105,7 +105,7 @@ Two more things the same run proved:
 - **Expand build-time macros first.** The reader saw seven raw `{{placeholders}}` and correctly
   reported that every headline number was missing. That is a true statement about the extract and a
   false one about the paper.
-- **Strip working comments.** He graded `<!-- JUSTIFY … -->` notes as prose because he could not tell
+- **Strip working comments.** He graded `% JUSTIFY …` comment notes as prose because he could not tell
   them apart — and said so, which is itself a finding about the extract.
 
 **So:** take the changed lines, then widen each to its enclosing paragraph, expand macros, drop

package/skills/cold-read-diff/SKILL.md.spec.ts

@@ -60,7 +60,7 @@ one, and its confusion is the finding.
 
 ## How to run it
 
-1. **Take the diff.** \`git diff -U0 -- <paper.md>\` since the last commit, or the \`new_string\` of the
+1. **Take the diff.** \`git diff -U0 -- <paper.tex>\` since the last commit, or the \`new_string\` of the
    edits just applied. Prose only — skip comments, tables, bibliography.
 2. **Spawn TWO agents with no repository context, one per persona, in parallel.** Give each the
    changed paragraphs **as text in the prompt**, not as a file path. A path is an invitation to read
@@ -110,7 +110,7 @@ Two more things the same run proved:
 - **Expand build-time macros first.** The reader saw seven raw \`{{placeholders}}\` and correctly
   reported that every headline number was missing. That is a true statement about the extract and a
   false one about the paper.
-- **Strip working comments.** He graded \`<!-- JUSTIFY … -->\` notes as prose because he could not tell
+- **Strip working comments.** He graded \`% JUSTIFY …\` comment notes as prose because he could not tell
   them apart — and said so, which is itself a finding about the extract.
 
 **So:** take the changed lines, then widen each to its enclosing paragraph, expand macros, drop

package/skills/grade-paper-writing/SKILL.md

@@ -4,7 +4,7 @@ description: Use when asking "does this paper read well?" / "is the writing any
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:03d0377baf71967f compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:6401b9117bbf899f compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
 
 # grade-paper-writing — grade how the paper READS, then fix it sentence by sentence
 
@@ -53,7 +53,7 @@ derived from that gap.
 ### 🔴 Read the BUILT PDF, not the source
 
 **The stall pass reads the typeset pages.** The source is for locating the fix afterwards, never for
-judging the read. This was previously written as "read the `.tex`/`.md`, **or** run `render-paper`",
+judging the read. This was previously written as "read the `.tex`, **or** run `render-paper`",
 and that *or* is why the pass kept missing what the author saw immediately: he reads the PDF.
 
 Things that exist only in the render, every one of which produces a real stall:
@@ -153,7 +153,7 @@ is what happened.
 
 ## How to run it
 
-1. **Read the actual draft** (the `.tex`/`.md`, or run `render-paper` to read the built pages as a reader
+1. **Read the actual draft** (the `.tex`, or run `render-paper` to read the built pages as a reader
    would). Grade the writing as written — never from a summary.
 2. **Run the cold-read stall pass FIRST — the full specification is below, under "The stall pass".**
    It was previously a pointer to a reference section that did not exist, which is why the pass drifted
@@ -215,10 +215,17 @@ is what happened.
 5. **Flag the two prose traps by name:** (a) Attention-style dense contribution-less prose used where the
    audience does NOT already care; (b) hedge-stacking ("may possibly in some cases potentially") — replace
    each pile with one precise scope sentence.
-6. 🔴 **Run `prose-lint.mjs` and treat every FLAG as a finding, not as context.** It is wired into
-   `paper-lint` on paper edits, so its output arrives whether or not this skill was invoked — but the
-   skill is what must ACT on it. Its thresholds are sourced; a FLAG means the text sits above a
-   published human or machine baseline, which is a defect with a number attached, not an opinion.
+6. 🔴 **Run `prose-lint.mjs` on the paper and treat every FLAG as a finding, not as context:**
+
+   ```
+   node ${CLAUDE_SKILL_DIR}/prose-lint.mjs <paper-dir>/paper.tex             # the report
+   node ${CLAUDE_SKILL_DIR}/prose-lint.mjs --headings <paper-dir>/paper.tex  # the headings as a set
+   ```
+
+   It measures the prose a reader sees — includes spliced, no preamble, comments, floats or inline
+   `.bib` — so its rates are the paper's, not the source file's. The skill is what must ACT on it.
+   Its thresholds are sourced; a FLAG means the text sits above a published human or machine
+   baseline, which is a defect with a number attached, not an opinion.
    Two entries in `THRESHOLDS` exist because this skill previously ran five times without either
    firing: the `"not X, but Y"` density had **no threshold at all** and printed as a neutral line
    while standing at 50.8 per 10,000 words against an LLM baseline of 7.8, and the lexicon missed
@@ -227,21 +234,6 @@ is what happened.
    A number printed without a threshold is prose; that is this project's own thesis, and the linter
    was violating it.
 
-6a. 🔴 **`prose-lint.mjs` IS NO LONGER ALONE — seven of its twelve gating metrics moved
-   on 2026-08-26 into ESLint rules, and running only it shows you five twelfths.** A second
-   run is mandatory; without it, step 6 is incomplete:
-
-   ```
-   npx eslint "papers/*/paper.md" "papers/*/draft.md"
-   ```
-
-   From there come: `paper/citation-density` · `paper/unexplained-jargon` ·
-   `paper/multi-claim-sentence` · `paper/conceits` · `paper/hedge-density` ·
-   `paper/discourse-subject` · `paper/undefined-coinage` (file — `eslint-rules/paper-craft.mjs`).
-   Gain from the move — `file:line:col` on each finding: the old report printed the sentence head,
-   and you had to find it in the article by eye. Everything step 6b says about
-   meaning regression applies to them just the same: this is diagnosis, not objective.
-
 6b. 🔴 **A lint fix that costs meaning is a REGRESSION, and no linter can see it.** The metrics above
    are diagnostics, never objectives. Optimising one directly is how a sentence gets worse while the
    number gets better — and the number is exactly what makes it feel like progress.

package/skills/grade-paper-writing/SKILL.md.spec.ts

@@ -59,7 +59,7 @@ derived from that gap.
 ### 🔴 Read the BUILT PDF, not the source
 
 **The stall pass reads the typeset pages.** The source is for locating the fix afterwards, never for
-judging the read. This was previously written as "read the \`.tex\`/\`.md\`, **or** run \`render-paper\`",
+judging the read. This was previously written as "read the \`.tex\`, **or** run \`render-paper\`",
 and that *or* is why the pass kept missing what the author saw immediately: he reads the PDF.
 
 Things that exist only in the render, every one of which produces a real stall:
@@ -159,7 +159,7 @@ is what happened.
 
 ## How to run it
 
-1. **Read the actual draft** (the \`.tex\`/\`.md\`, or run \`render-paper\` to read the built pages as a reader
+1. **Read the actual draft** (the \`.tex\`, or run \`render-paper\` to read the built pages as a reader
    would). Grade the writing as written — never from a summary.
 2. **Run the cold-read stall pass FIRST — the full specification is below, under "The stall pass".**
    It was previously a pointer to a reference section that did not exist, which is why the pass drifted
@@ -221,10 +221,17 @@ is what happened.
 5. **Flag the two prose traps by name:** (a) Attention-style dense contribution-less prose used where the
    audience does NOT already care; (b) hedge-stacking ("may possibly in some cases potentially") — replace
    each pile with one precise scope sentence.
-6. 🔴 **Run \`prose-lint.mjs\` and treat every FLAG as a finding, not as context.** It is wired into
-   \`paper-lint\` on paper edits, so its output arrives whether or not this skill was invoked — but the
-   skill is what must ACT on it. Its thresholds are sourced; a FLAG means the text sits above a
-   published human or machine baseline, which is a defect with a number attached, not an opinion.
+6. 🔴 **Run \`prose-lint.mjs\` on the paper and treat every FLAG as a finding, not as context:**
+
+   \`\`\`
+   node \${CLAUDE_SKILL_DIR}/prose-lint.mjs <paper-dir>/paper.tex             # the report
+   node \${CLAUDE_SKILL_DIR}/prose-lint.mjs --headings <paper-dir>/paper.tex  # the headings as a set
+   \`\`\`
+
+   It measures the prose a reader sees — includes spliced, no preamble, comments, floats or inline
+   \`.bib\` — so its rates are the paper's, not the source file's. The skill is what must ACT on it.
+   Its thresholds are sourced; a FLAG means the text sits above a published human or machine
+   baseline, which is a defect with a number attached, not an opinion.
    Two entries in \`THRESHOLDS\` exist because this skill previously ran five times without either
    firing: the \`"not X, but Y"\` density had **no threshold at all** and printed as a neutral line
    while standing at 50.8 per 10,000 words against an LLM baseline of 7.8, and the lexicon missed
@@ -233,21 +240,6 @@ is what happened.
    A number printed without a threshold is prose; that is this project's own thesis, and the linter
    was violating it.
 
-6a. 🔴 **\`prose-lint.mjs\` IS NO LONGER ALONE — seven of its twelve gating metrics moved
-   on 2026-08-26 into ESLint rules, and running only it shows you five twelfths.** A second
-   run is mandatory; without it, step 6 is incomplete:
-
-   \`\`\`
-   npx eslint "papers/*/paper.md" "papers/*/draft.md"
-   \`\`\`
-
-   From there come: \`paper/citation-density\` · \`paper/unexplained-jargon\` ·
-   \`paper/multi-claim-sentence\` · \`paper/conceits\` · \`paper/hedge-density\` ·
-   \`paper/discourse-subject\` · \`paper/undefined-coinage\` (file — \`eslint-rules/paper-craft.mjs\`).
-   Gain from the move — \`file:line:col\` on each finding: the old report printed the sentence head,
-   and you had to find it in the article by eye. Everything step 6b says about
-   meaning regression applies to them just the same: this is diagnosis, not objective.
-
 6b. 🔴 **A lint fix that costs meaning is a REGRESSION, and no linter can see it.** The metrics above
    are diagnostics, never objectives. Optimising one directly is how a sentence gets worse while the
    number gets better — and the number is exactly what makes it feel like progress.

package/skills/grade-paper-writing/__snapshots__/prose-lint.test.ts.snap

@@ -1,18 +1,25 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`--flags-only: an over-long caption flags and exits 1 1`] = `
-"✍️  prose-lint — paper.md — 2 finding(s):
+"✍️  prose-lint — paper.tex — 2 finding(s):
    figures/fig1.tex: caption sentence of 46 words (warn >40) — "Big. word0 word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 wor…"
    figures/fig1.tex: caption is 106 words (warn >100) — a caption this long is a section under a picture
-   run \`node .claude/skills/grade-paper-writing/prose-lint.mjs <file>\` for the sentences
+   run prose-lint.mjs on the file without --flags-only for the sentences
 "
 `;
 
-exports[`--headings lists every heading from level 2 to 4, in order 1`] = `
+exports[`--headings on a paper.tex lists its section titles, in order 1`] = `
 "
-=== paper.md — every heading, in order ===
+=== paper.tex — every heading, in order ===
   1. Introduction
-  2. Method
+  2. The measurement pitfall
+  3. Method: a cost-aware, correctness-gated harness
+  4. Results
+  5. The advertised savings don't show up
+  6. A ceiling for any output-trimming tool
+  7. Discussion and threats to validity
+  8. Related work
+  9. Conclusion
 
 Read these as a stranger who will read nothing else. Each should name a thing:
 a linter, a configuration, a repository, a rule — not "answers", "kinds", "moves".
@@ -21,28 +28,8 @@ a linter, a configuration, a repository, a rule — not "answers", "kinds", "mov
 "
 `;
 
-exports[`a .tex file is refused with exit 2, and nothing is measured 1`] = `
-"prose-lint reads markdown, not LaTeX: <root>/paper.tex
-There is no .tex stripping here — the word count would include the preamble and the .bib,
-and every metric (they are all fractions of the word count) would be understated by roughly half.
-What to cover prose in .tex with — papers/research/2026-08-26-proza-v-latex-zanyatost.md
+exports[`the report over a rendered page: page numbers, hyphenation and the references are dropped 1`] = `
 "
-`;
-
-exports[`the full report over markdown and rendered text 1`] = `
-"
-=== paper.md — 82 words, 9 sentences ===
-sentence lengths [7,10,8,6,19,6,8,8,6]  mean 8.7  sd 3.9  CV 0.45
-FLAG all metadiscourse/1000w  195.1   (Hyland RA baseline 64.9, warn >90)
-     nominalisations/1000w    12.2
-FLAG "rather than"/instead-of/10,000w  243.9   (warn >25; not epanorthosis, no published baseline)
-FLAG sentences ending on a cross-ref/citation/hedge (wasted stress position): 3
-       > …Clearly the first result matters (Section 3).
-       > …Prior work agrees [1, 2].
-       > … full suite of papers, which suggests the method might hold generally.
-ok   sentences whose main claim is a negation: 22%
-     topic positions (whose story is this?): "in this paper we present" | "it might possibly help, but" | "clearly the first result matters" | "prior work agrees [1, 2]." | "the speedup was 40% on" | "- the first item is" | "- the second item is" | "we believe that rather than" | "instead of prose, the numbers"
-
 === page.txt — 13 words, 3 sentences ===
 sentence lengths [3,6,4]  mean 4.3  sd 1.2  CV 0.29
 ok   all metadiscourse/1000w  0   (Hyland RA baseline 64.9, warn >90)
@@ -55,3 +42,30 @@ ok   sentences whose main claim is a negation: 0%
 (thresholds and their sources are in THRESHOLDS at the top of this file)
 "
 `;
+
+exports[`🔴 a paper.tex is measured on the prose a reader sees — not its preamble, comments or inline .bib 1`] = `
+"
+=== paper.tex — 4181 words, 166 sentences ===
+sentence lengths [16,24,12,44,37,27,45,26,33,25,23,16,19,23,9,75,42,14,11,28,19,4,34,15,32,24,39,38,38,9,15,29,26,42,45,78,23,27,18,44,57,20,23,43,30,42,31,27,46,30,30,29,16,53,33,41,23,7,28,27,30,26,14,48,9,26,11,15,5,24,14,16,11,1,38,48,12,18,31,20,44,15,30,36,57,22,25,13,25,52,14,7,17,13,16,7,21,19,18,10,20,7,23,7,5,21,7,27,29,8,14,7,23,16,11,9,20,36,32,25,37,18,7,13,35,37,35,27,16,15,23,29,26,26,12,9,15,19,24,10,22,30,24,18,34,16,50,22,32,63,36,26,12,37,36,12,17,48,10,35,27,24,22,19,35,32]  mean 25.2  sd 13.6  CV 0.54
+ok   all metadiscourse/1000w  50.2   (Hyland RA baseline 64.9, warn >90)
+     nominalisations/1000w    27.3
+FLAG "rather than"/instead-of/10,000w  28.7   (warn >25; not epanorthosis, no published baseline)
+FLAG sentences ending on a cross-ref/citation/hedge (wasted stress position): 12
+       > … this kind are already woven into how programmers work day to day [1].
+       > …the cost claims of the surrounding tooling are largely taken on trust.
+       > …, none of which describe how a coding agent actually runs (Section 1).
+       > …n class, and rejects any trial that regresses correctness (Section 1).
+       > …und explains why no output-trimming tool can move it much (Section 1).
+       > …eaningful under the conditions its consumers face, or it misleads [1].
+       > …ently no-ops, which invalidated an earlier run until we caught it [1].
+       > …irk of these two tools; it follows from the cost structure (Figure 1).
+       > … flagship's output change ranges from a growth to a cut (Table 1) [1].
+       > … right [1], compressing prompts [1], and caching repeated context [1].
+       > …], and that results from a handful of runs need honest statistics [1].
+       > …g code [1], and models that memorize answers instead of reasoning [1].
+ok   sentences whose main claim is a negation: 37%
+     topic positions (whose story is this?): "a fast-growing ecosystem of plugins," | "the most popular single artifact---a" | "we show that such claims," | "efficiency tools are validated on" | "we introduce a reproducible, cost-aware," | "across 140 runs on two" | "output falls far short of" | "the ceiling is also structural:" | "we argue that trustworthy evaluation" | "ai coding agents and their" | "built on the reasoning-and-acting loops" | "assistants of this kind are" | "an unverified performance claim about" | "while the community has invested" | "we focus on the most" | "the flagship example is a" | "naming the commits matters more" | "two separate claims are bundled" | "the first is that the" | "that one has already been" | "the second claim is the" | "nobody had measured it." | "it fails for a reason" | "this paper is about the" | "rq: when a token-efficiency tool" | "the first half is measured," | "our contribution is not that" | "we identify why the headline" | "we build a cost-aware, correctness-gated" | "we measure two widely used" | "output falls far short of" | "the dollar bill does not" | "the broader point is about" | "a modern agent bills tokens" | "a multi-turn agentic session [1]" | "reading the upstream benchmark code" | "the reported number measures something" | "the fix is to measure" | "the compression literature these tools" | "the harness --- the ecosystem" | "we implement the evaluation as" | "figure 1 shows the whole" | "each tool is delivered as" | "a skill that ships as" | "this step is load-bearing: a" | "we use seven self-contained coding" | "the suite deliberately skews short" | "each task is run with" | "the runs date from july" | "the two tools are the" | "for every run we record" | "on a subscription the \`\`bill''" | "we report dollars---the weighting most" | "each task carries a deterministic" | "these are lightweight structural checks" | "a trial where the skill" | "for each task we report" | "we call an effect significant" | "we also note which effects" | "for the bill we report" | "averages taken over a few" | "this protocol is sized to" | "two things are still required" | "the flagship skill (claim 65%)" | "we sign bill changes so" | "for the flagship, the bill" | "either way the answer is" | "the second tool (claim 63%)" | "it is also not significant." | "its one per-task cell that" | "the intervals are wide: at" | "but they exclude anything near" | "whatever room remains is capped" | "correctness." | "both arms passed the correctness" | "a sharper signal hides in" | "this is a short-session effect" | "this is not a quirk" | "both shares below are measured," | "pooled across all tasks and" | "if output is a fraction" | "even a perfect 65% output" | "the advertised 63--75% and the" | "the flagship's other feature trims" | "output is a small fraction" | "we measure cost: latency and" | "we do not claim \`\`these" | "nor do we dispute the" | "our point is that they" | "we label each by its" | "we run five trials per" | "that is itself part of" | "across tasks the flagship's output" | "the honest quantity is therefore" | "our design refutes the advertised" | "what caps those is the" | "a formal equivalence test (tost---a" | "the harness is not toothless," | "at that scale we read" | "we test one model, and" | "anthropic's tiers all share a" | "the ceiling scales linearly with" | "even if output were priced" | "our tasks top out around" | "this cuts in our favor." | "a longer session re-reads a" | "that pushes the ceiling lower," | "one might object that terser" | "but that downstream saving is" | "so it adds a few" | "the compounded ceiling is --," | "the overhead runs the other" | "an always-loaded tool prompt adds" | "that fixed cost amortizes over" | "the durable long-session prediction is" | "an empirical long-session demonstration is" | "every run in the main" | "the harness decides how many" | "a wordier model would raise" | "the ceiling of section 1" | "a pilot on claude haiku" | "nearly double, and still about" | "both runs ship in the" | "a second harness is reachable" | "the flagship now ships wrappers" | "measuring a second harness therefore" | "wrapper list and the rejected" | "we do not study multi-agent" | "we test two tools, and" | "the harness can a/b any" | "the bias runs in our" | "our per-run bill uses the" | "a user can also invalidate" | "(the first two rewrite the" | "that is, they push cost" | "they lower the ceiling and" | "so our clean-caching tasks, if" | "the correctness gate is a" | "so \`\`zero regressions'' bounds gross" | "a stronger gate that runs" | "still, a gate that never" | "without it, a harness would" | "the efficiency-claim failure is a" | "a community norm of cost-aware," | "execution-based, correctness-gated benchmarks such as" | "we keep their correctness-first discipline" | "several lines of work push" | "we take the same stance---price" | "closest to us, [1] argue" | "we turn that lens on" | "a long line of work" | "capability benchmarks show the same" | "we aim the same critique" | "the industry a/b test cited" | "what we add over such" | "the efficiency-tool market runs on" | "these tools trim what the" | "we measured two of the" | "the numbers are not fabricated;" | "the output you are shown" | "trimming the model's replies to" | "we release the measurements with" | "before you install the next" | "the complete harness of section" | "the measurements are released per" | "individual trial rows are not"
+
+(thresholds and their sources are in THRESHOLDS at the top of this file)
+"
+`;