paperlint 3.2.0 → 4.1.0

package/src/venue-rules.ts

@@ -45,8 +45,9 @@ import {
 import type { KindLimits, VenueFormat } from "./tex-requirements.ts";
 import { paperPreset, presetProblemText } from "./presets.ts";
 import type { FlatGeometry } from "./domain/geometry.ts";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { callerPath } from "./caller-path.ts";
 import { sha256Hex } from "./domain/sha256.ts";
+import { fieldOf } from "./domain/record.ts";
 import type { Files } from "./ports/files.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
 
@@ -88,13 +89,12 @@ export type Assessment =
 
 export interface VenueRuleDeps {
   readonly files: Files;
-  /** The package's venues directory (`packageVenuesDir()`): the shipped presets and their schema. */
+  /** The package's presets directory (`presetsDir()`): the shipped presets and their schema. */
   readonly venuesDir: string;
 }
 
-const at = (p: string): AbsolutePath => p as AbsolutePath;
 const text = (files: Files, p: string): string | null => {
-  const b = files.readBytes(at(p));
+  const b = files.readBytes(callerPath(p));
   return b === null ? null : new TextDecoder().decode(b);
 };
 
@@ -138,7 +138,7 @@ function freshFacts(
       : finding("factsBroken", { why: parsed.error.why });
   const f = parsed.value;
   const pdf = files.readBytes(
-    at(isAbsolute(f.pdf) ? f.pdf : join(paperDir, f.pdf)),
+    callerPath(isAbsolute(f.pdf) ? f.pdf : join(paperDir, f.pdf)),
   );
   if (pdf === null) return finding("pdfMissing", { pdf: f.pdf });
   return sha256Hex(pdf) === f.sha ? f : finding("stale", { pdf: f.pdf });
@@ -373,8 +373,7 @@ const JUDGES: Readonly<Record<VenueRuleName, Judge>> = {
           a.facts.geometry,
           a.venue.format,
           a.venue.venue,
-          (options[0] as { dimTol?: number } | undefined)?.dimTol ??
-            DEFAULT_DIM_TOL_IN,
+          dimTolOf(options[0]),
         )
       : [],
   limits: (a) =>
@@ -390,6 +389,12 @@ const JUDGES: Readonly<Record<VenueRuleName, Judge>> = {
 /** How far, in inches, a measured page dimension may be from the preset's. */
 export const DEFAULT_DIM_TOL_IN = 0.05;
 
+/** `geometry`'s `dimTol` option in inches, or the default when the rule was given none. */
+function dimTolOf(options: unknown): number {
+  const tol = fieldOf(options, "dimTol");
+  return typeof tol === "number" ? tol : DEFAULT_DIM_TOL_IN;
+}
+
 type Meta = Pick<VenueRuleModule["meta"], "docs" | "messages"> & {
   readonly type?: "suggestion";
   readonly schema?: readonly object[];
@@ -565,9 +570,14 @@ function rule(name: VenueRuleName, deps: VenueRuleDeps): VenueRuleModule {
 export function venueRules(
   deps: VenueRuleDeps,
 ): Record<VenueRuleName, VenueRuleModule> {
-  const names = Object.keys(META) as VenueRuleName[];
-  return Object.fromEntries(names.map((n) => [n, rule(n, deps)])) as Record<
-    VenueRuleName,
-    VenueRuleModule
-  >;
+  // Every name listed: a record missing one is a compile error.
+  return {
+    fresh: rule("fresh", deps),
+    profile: rule("profile", deps),
+    measured: rule("measured", deps),
+    fonts: rule("fonts", deps),
+    geometry: rule("geometry", deps),
+    limits: rule("limits", deps),
+    "body-size": rule("body-size", deps),
+  };
 }

package/templates/paper/paper.tex

@@ -1,5 +1,6 @@
 % Created by `paperlint new`. A stub: replace all of it. The only thing `paperlint lint` needs is that
-% this file exists; the document class is yours. `paperlint build` compiles it to paper.pdf.
+% this file exists. With `--venue`, the class below is the venue's (`tex/template` checks it);
+% without, it is yours. `paperlint build` compiles it to paper.pdf.
 \documentclass{article}
 \title{Working title for {{name}}}
 \begin{document}

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

@@ -1,67 +0,0 @@
-// announce.mjs — a skill says out loud that it started, and the ledger remembers that it did.
-//
-// vigiles:local-by-design — takes a skill name as an argument and so names none itself, which reads
-// generic; it is not. It writes THIS repo's ledger row format, consumed by `status.mjs`'s gate table
-// and `ledger.mjs`'s verdict vocabulary, both of which are conventions of this knowledge base rather
-// than of any product. Moving it would export a schema nobody else has.
-//
-// WHY. Repository owner's request, 2026-08-07: "lack observability into pipeline status and whether
-// skills are actually being called — let's ensure each skill outputs something when activated".
-//
-// The failure behind that sentence is specific and it has happened three times in this repo. An
-// advisory check CANNOT BE SEEN FAILING: silence is both its error state and its normal state.
-// `paper-skills-nudge.sh` was dead for twelve days and was found only because it writes a throttle
-// stamp whose mtime had frozen. Two inline hooks were dead for their entire existence and nobody
-// noticed at all. And on 2026-08-06 a whole session of paper work ran with no skill invoked once.
-//
-// So: starting is an EVENT, and events get written down. A skill that announces leaves two traces —
-// one the human sees immediately, one the ledger keeps. Their disagreement is itself information:
-//
-//   announced, never recorded  → the skill started and died, or the author abandoned it midway
-//   recorded, never announced  → someone wrote a verdict without running the gate
-//   neither                    → it did not run, whatever any status file claims
-//
-// This is the "no trace means it did not work" rule the project already applies to hooks, made
-// available to skills, which had no equivalent.
-
-import { record, skillHash, inputHash } from "./ledger.mjs";
-import { existsSync } from "node:fs";
-import { resolve, basename } from "node:path";
-import { isMain } from "./consumer.mjs";
-
-export function announce(skill, paperDir) {
-  const dir = resolve(paperDir || ".");
-  const has = existsSync(dir);
-  const input = has ? inputHash(dir) : null;
-
-  const lines = [
-    `▶ ${skill}  —  ${has ? basename(dir) : "no paper dir"}`,
-    `  paper ${input ? input.slice(0, 8) : "(none)"} · skill ${(skillHash(skill) || "????????").slice(0, 8)}`,
-  ];
-  // stderr, not stdout: the skill's own output is the product, and a banner that pollutes a pipe
-  // is a banner someone will remove.
-  console.error(lines.join("\n"));
-
-  // An abstention with reason `started`, not an ERROR row. Before 2026-08-10 this wrote `ERROR`,
-  // which meant "the check errored" — so every announce looked like a crash until its terminal row
-  // landed, and `started` and `crashed` were the same word. Both are abstentions and neither is a
-  // judgement about the paper; the reason is what tells them apart.
-  record({
-    skill,
-    check: skill,
-    paper: dir,
-    kind: "ABSTAINED",
-    reason: "started",
-    note: "no verdict recorded yet",
-  });
-  return { skill, paper: basename(dir), input };
-}
-
-if (isMain(import.meta.url)) {
-  const [skill, paperDir] = process.argv.slice(2);
-  if (!skill) {
-    console.error("usage: announce.mjs <skill-name> [paper-dir]");
-    process.exit(2);
-  }
-  announce(skill, paperDir);
-}

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

@@ -1,102 +0,0 @@
-/**
- * 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.ts";
-
-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/fixtures/clean/PIPELINE-STATUS.md

@@ -1,51 +0,0 @@
-# PIPELINE-STATUS — fixture: nothing to report
-Venue: Fixture Workshop · Deadline: 2027-12-31 · Blind: double · State: drafting
-Updated: 2026-08-03
-
-**Readiness verdict:** Submit-ready — every gate green, artifact reproduces clean, nothing blocking.
-
-This fixture deliberately carries NO paper source file, so `newestSourceDate` is null and the
-staleness comparison has nothing to compare against. That keeps the clean case deterministic
-regardless of when the repo was checked out — the staleness rule is exercised by `dirty/`.
-
-### SETUP
-| id | Work | Skill | Status | Date | Result | Open |
-|----|------|-------|--------|------|--------|------|
-| idea | Validate idea | research-ideate | ☑ | 2026-08-01 | go. judge: opus, judge: author | — |
-| priorwork | Map competitors | map-prior-work | ☑ | 2026-08-01 | 6 siblings. judge: sonnet, judge: author | siblings/ |
-| venue | Pick venue | find-venue | ☑ | 2026-08-01 | fixture. judge: sonnet, judge: author | — |
-| venuebar | Venue bar / levers | study-accepted-papers | ☑ | 2026-08-01 | 34 measured. judge: sonnet, judge: author | — |
-| **access** | 🔴 **Can you physically submit?** | plan-paper-timeline | ☑ | 2026-08-01 | profile ACTIVE since 2026-08-01. judge: author, judge: author | — |
-| schedule | Schedule + calendar | plan-paper-timeline | ☑ | 2026-08-01 | —. judge: author, judge: author | — |
-| **frame** | **Claim stated before the runs** | argument-arc (frame) | ☑ | 2026-07-20 | one paragraph filed | — |
-
-### LOOP
-| id | Work | Skill | Status | Date | Result | Open |
-|----|------|-------|--------|------|--------|------|
-| study | Study + artifact | build-benchmark | ☑ | 2026-08-01 | ran | — |
-| draft | Draft | draft-paper | ☑ | 2026-08-01 | — | — |
-| arc | Argument arc | argument-arc | ☑ | 2026-08-01 | holds. judge: opus, judge: author | — |
-
-### CONTINUOUS
-| id | Trigger | Skill | Status | Date | Result | Open |
-|----|---------|-------|--------|------|--------|------|
-| cites | any cite added/moved | verify-citations | ☑ | 2026-08-02 | clean | — |
-| siblings | a sibling surfaces | analyze-sibling-paper | ☑ | 2026-08-02 | 6 read. judge: opus, judge: author | siblings/ |
-| priordelta | framing moved | map-prior-work (delta) | ☑ | 2026-08-02 | no new | — |
-| render | any source edit | render-paper + page count | ☑ | 2026-08-02 | 8 pages / limit 8 | — |
-
-### GATES
-| id | Gate | Skill | Requires | Status | Date | Result | Open |
-|----|------|-------|----------|--------|------|--------|------|
-| structure | Structure | tighten-paper | render, arc | ☑ | 2026-08-02 | cut plan applied. judge: opus, judge: author | — |
-| writing | Writing craft | grade-paper-writing | draft, arc, structure | ☑ | 2026-08-02 | 44/60. judge: sonnet, judge: author | — |
-| panel | Review decision | pc-panel-review | structure, writing | ☑ | 2026-08-03 | accept; judge: opus, judge: author | — |
-| claims | Claim preservation | Fable diff | draft, writing | ☑ | 2026-08-03 | clean | — |
-| harden | Harden (all axes) | harden-paper | panel, structure, writing, cites, priordelta | ☑ | 2026-08-03 | all axes green ; judge: opus, judge: author | — |
-| submit | Submit | submit-paper | harden, access | ☑ | 2026-08-03 | uploaded | — |
-
-### AFTER
-| id | Work | Skill | Status | Date | Result | Open |
-|----|------|-------|--------|------|--------|------|
-| cameraready | Camera-ready | camera-ready | n/a | — | pre-acceptance | — |
-| extend | Extend | extend-paper | n/a | — | post-acceptance | — |

package/skills/paper-pipeline/scripts/fixtures/dirty/PIPELINE-STATUS.md

@@ -1,52 +0,0 @@
-# PIPELINE-STATUS — fixture: every failure this checker exists for
-Venue: Fixture Workshop · Deadline: 2026-08-06 · Blind: double · State: drafting
-Updated: 2026-01-01
-
-**Readiness verdict:** 88% accept probability, looking good.
-
-The `structure` row is missing `arc` from its Requires cell **on purpose** — that is the planted
-`undeclared-input`, copied from a defect found live on a real paper in August 2026. Every
-other gate cell here is the canonical set from `../../pipeline-edges.mjs`, so exactly one edge is
-undeclared and the finding cannot come from somewhere else.
-
-### SETUP
-| id | Work | Skill | Status | Date | Result | Open |
-|----|------|-------|--------|------|--------|------|
-| idea | Validate idea | research-ideate | ☑ | 2026-01-01 | go | — |
-| priorwork | Map competitors | map-prior-work | ☑ | 2026-01-01 | 6 siblings | siblings/ |
-| venue | Pick venue | find-venue | ☑ | 2026-01-01 | fixture | — |
-| venuebar | Venue bar / levers | study-accepted-papers | ☐ | — | — | — |
-| **access** | 🔴 **Can you physically submit?** | plan-paper-timeline | ☐ | — | profile pending moderation | — |
-| schedule | Schedule + calendar | plan-paper-timeline | ☑ | 2026-01-01 | — | — |
-| **frame** | **Claim stated before the runs** | argument-arc (frame) | ☐ | — | — | — |
-
-### LOOP
-| id | Work | Skill | Status | Date | Result | Open |
-|----|------|-------|--------|------|--------|------|
-| study | Study + artifact | build-benchmark | ☑ | 2026-01-01 | ran | — |
-| draft | Draft | draft-paper | ☑ | 2026-01-01 | — | — |
-| arc | Argument arc | argument-arc | ☐ | — | — | — |
-
-### CONTINUOUS
-| id | Trigger | Skill | Status | Date | Result | Open |
-|----|---------|-------|--------|------|--------|------|
-| cites | any cite added/moved | verify-citations | ☑ | 2026-01-01 | clean | — |
-| siblings | a sibling surfaces | analyze-sibling-paper | ☑ | — | done | siblings/ |
-| priordelta | framing moved | map-prior-work (delta) | ☐ | — | — | — |
-| render | any source edit | render-paper + page count | ☑ | 2026-01-01 | 8 pages / limit 8 | — |
-
-### GATES
-| id | Gate | Skill | Requires | Status | Date | Result | Open |
-|----|------|-------|----------|--------|------|--------|------|
-| structure | Structure | tighten-paper | render | ☑ | 2026-01-01 | cut plan | — |
-| writing | Writing craft | grade-paper-writing | draft, arc, structure | ☐ | — | — | — |
-| panel | Review decision | pc-panel-review | structure, writing | ☑ | 2026-01-01 | borderline | — |
-| claims | Claim preservation | Fable diff | draft, writing | ☐ | — | — | — |
-| harden | Harden (all axes) | harden-paper | panel, structure, writing, cites, priordelta | ☐ | — | — | — |
-| submit | Submit | submit-paper | harden, access | ☐ | — | — | — |
-
-### AFTER
-| id | Work | Skill | Status | Date | Result | Open |
-|----|------|-------|--------|------|--------|------|
-| cameraready | Camera-ready | camera-ready | n/a | — | pre-acceptance | — |
-| extend | Extend | extend-paper | n/a | — | post-acceptance | — |

package/skills/paper-pipeline/scripts/fixtures/dirty/paper.md

@@ -1,6 +0,0 @@
-# Fixture paper source
-
-This file exists only so `newestSourceDate` finds something. Its mtime is whenever the
-repo was checked out, which is always later than the 2026-01-01 dates in the fixture's
-CONTINUOUS rows — so the `stale-continuous` check fires deterministically without the
-test having to touch mtimes.

package/skills/paper-pipeline/scripts/fixtures/scorecard.ts

@@ -1,100 +0,0 @@
-/**
- * A PIPELINE-STATUS.md fixture shared by the pipeline-check harness and its CLI test: the four
- * template sections, every row green and dated `today`, so a test plants exactly one defect.
- */
-export const FAR = "2027-12-31";
-
-/** What a test may replace in one row: any cell, and for a GATES row its `Requires` cell. */
-export interface RowOverride {
-  readonly status?: string;
-  readonly date?: string;
-  readonly skill?: string;
-  readonly result?: string;
-  readonly requires?: string;
-}
-
-/** Per-row overrides by row id, plus the four free-text parts of the file. */
-export interface ScorecardOverrides {
-  readonly verdict?: string;
-  readonly deadline?: string;
-  readonly tail?: string;
-  readonly preamble?: string;
-  readonly [id: string]: RowOverride | string | undefined;
-}
-
-interface Row extends RowOverride {
-  readonly id: string;
-  readonly status: string;
-  readonly date: string;
-}
-
-/** A row's overrides; the free-text keys never name a row, so a string here is none. */
-const cellsOf = (v: RowOverride | string | undefined): RowOverride =>
-  typeof v === "object" ? v : {};
-
-/**
- * A scorecard with the four sections the template requires, all green. `over` replaces individual
- * cells: `{ cites: { date: "2020-01-01" } }`, `{ verdict: "…" }`, `{ deadline: "2026-08-18" }`,
- * `{ tail: "…" }` for anything appended after the last section, `{ preamble: "…" }` for anything
- * inserted BEFORE the first heading (the only way to plant a row under no heading at all).
- */
-export function scorecard(
-  over: ScorecardOverrides = {},
-  today: string = new Date().toISOString().slice(0, 10),
-): string {
-  const r = (id: string, status = "☑", date = today): Row => ({
-    id,
-    status,
-    date,
-    ...cellsOf(over[id]),
-  });
-  const row = (o: Row, ...mid: string[]): string =>
-    `| ${o.id} | work | ${o.skill ?? "skill"} | ${mid.length ? mid.join(" | ") + " | " : ""}${o.status} | ${o.date} | ${o.result ?? "result"} | — |`;
-  // The GATES `Requires` cell, canonical by default so the baseline is silent — `{ structure: {
-  // requires: "render" } }` plants a dropped edge. `harden` deliberately declares four of its five
-  // canonical inputs: the fifth (`priordelta`) has no row in this fixture, and the clean case asserts that the checker stays
-  // quiet about an edge there is nowhere to point at.
-  const req = (id: string, dflt: string): string =>
-    cellsOf(over[id]).requires ?? dflt;
-  const verdict =
-    over.verdict ??
-    "Submit-ready — every gate green, artifact reproduces clean, nothing blocking.";
-  return [
-    "# PIPELINE-STATUS — harness fixture",
-    `Venue: Fixture Workshop · Deadline: ${over.deadline ?? FAR} · Blind: double · State: drafting`,
-    "",
-    `**Readiness verdict:** ${verdict}`,
-    "",
-    over.preamble ?? "",
-    "",
-    "### SETUP",
-    "| id | Work | Skill | Status | Date | Result | Open |",
-    "|----|------|-------|--------|------|--------|------|",
-    row(r("idea")),
-    row(r("access")),
-    row(r("frame")),
-    "",
-    "### LOOP",
-    "| id | Work | Skill | Status | Date | Result | Open |",
-    "|----|------|-------|--------|------|--------|------|",
-    row(r("study")),
-    row(r("draft")),
-    row(r("arc")),
-    "",
-    "### CONTINUOUS",
-    "| id | Trigger | Skill | Status | Date | Result | Open |",
-    "|----|---------|-------|--------|------|--------|------|",
-    row(r("cites")),
-    row(r("render")),
-    "",
-    "### GATES",
-    "| id | Gate | Skill | Requires | Status | Date | Result | Open |",
-    "|----|------|-------|----------|--------|------|--------|------|",
-    row(r("structure"), req("structure", "render, arc")),
-    row(r("writing"), req("writing", "draft, arc, structure")),
-    row(r("panel"), req("panel", "structure, writing")),
-    row(r("harden"), req("harden", "panel, structure, writing, cites")),
-    "",
-    over.tail ?? "",
-  ].join("\n");
-}