paperlint 10.1.0 → 10.2.0

package/skills/build-label-page/SKILL.md

@@ -4,7 +4,7 @@ description: Build a phone labelling page published as a claude.ai Artifact with
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
 ---
 
-<!-- vigiles:sha256:592d7b4f8f27c4ce compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:7a537e71585bd321 compiled from skills/build-label-page/SKILL.md.spec.ts -->
 
 # build-label-page — a page the person labels on a phone, and the labels back in the repo
 
@@ -55,9 +55,12 @@ The full text, each with its reason and its check, is
    you meet in practice?". The labelling page is not that check: items made from easy units each look
    fine on their own.
 2. **Copy the generator into the study and write the items.** The study folder is
-   `<paper-dir>/repro/<slug>-YYYY-MM-DD/` (`gold-labels-2026-10-12`; `repro/allowed-files-only` wants the
-   date, a `README.md` in it saying what the study asks, and a line in `repro/README.md`; where this
-   sits in stage 3, and what checks each place: `docs/layout.md` in the paperlint package).
+   `<paper-dir>/repro/<id>-<slug>/`, made by `npx paperlint studies new <paper-dir> "Gold labels"
+   --kind data` when the labelling is a study of its own (`P1-S04-gold-labels`): the command writes
+   its `README.md` and its row in `repro/studies.json`, and `repro/study-registered` checks both. When
+   the labels are in, update the row (`status`, `result`, `result_file`) and run
+   `npx paperlint studies index <paper-dir>`. Where this sits in stage 3, and what checks each place:
+   `docs/layout.md` in the paperlint package.
    `items.json` follows the header of the generator. Source ids in `items.json` are the study's own;
    the page never shows them.
 

package/skills/build-label-page/SKILL.md.spec.ts

@@ -65,9 +65,12 @@ The full text, each with its reason and its check, is
    you meet in practice?". The labelling page is not that check: items made from easy units each look
    fine on their own.
 2. **Copy the generator into the study and write the items.** The study folder is
-   \`<paper-dir>/repro/<slug>-YYYY-MM-DD/\` (\`gold-labels-2026-10-12\`; \`repro/allowed-files-only\` wants the
-   date, a \`README.md\` in it saying what the study asks, and a line in \`repro/README.md\`; where this
-   sits in stage 3, and what checks each place: \`docs/layout.md\` in the paperlint package).
+   \`<paper-dir>/repro/<id>-<slug>/\`, made by \`npx paperlint studies new <paper-dir> "Gold labels"
+   --kind data\` when the labelling is a study of its own (\`P1-S04-gold-labels\`): the command writes
+   its \`README.md\` and its row in \`repro/studies.json\`, and \`repro/study-registered\` checks both. When
+   the labels are in, update the row (\`status\`, \`result\`, \`result_file\`) and run
+   \`npx paperlint studies index <paper-dir>\`. Where this sits in stage 3, and what checks each place:
+   \`docs/layout.md\` in the paperlint package.
    \`items.json\` follows the header of the generator. Source ids in \`items.json\` are the study's own;
    the page never shows them.
 

package/skills/paper-pipeline/references/artifact-checklist.md

@@ -29,7 +29,8 @@ the 140-run `reproduce.py` (AgenticDev) and the 46-guard `evaluate.py`/`mutate.p
 
 In the paper folder the artifact lives in `repro/`, laid out as `repro/allowed-files-only` requires: the
 scripts the whole paper uses in `repro/tools/`, shared data in `repro/data/`, each study in
-`repro/<slug>-YYYY-MM-DD/` with its `README.md`, and `repro/README.md` as the index. The shipped
+`repro/<id>-<slug>/` with its `README.md` and its row in `repro/studies.json`
+(`repro/study-registered`), and `repro/README.md` as the index generated from it. The shipped
 zip below is built from it; the anonymized copy that was uploaded goes in the paper's `submission/`.
 
 - `reproduce.py` / the harness scripts — self-check, print `RESULT: PASS`, exit non-zero on drift.

package/skills/paper-pipeline/references/pipeline-status-template.md

@@ -39,9 +39,11 @@ one file, so there is one place to read and nothing to keep in step:
 - **No `PLAN.md` beside it.** A plan in a second file drifts from the status it plans against;
   `paper/allowed-files-only` reports a `PLAN.md` at the paper's root. A decision's _history_ (why it was
   taken, what was rejected) is a record, not live state: it goes to `research/` as a dated file.
-- **Each study gets a dated folder in `repro/`.** The `study` stage's runs go in
-  `repro/<slug>-YYYY-MM-DD/` (or `<slug>-YYYY-MM` for one that ran over weeks), with a `README.md`
-  saying what it asks, how to run it and what it found, and a line in `repro/README.md`. Scripts the
+- **Each study gets a registered folder in `repro/`.** The `study` stage's runs go in
+  `repro/<id>-<slug>/`, created by `npx paperlint studies new <paper-dir> "<title>"`, with a `README.md`
+  saying what it asks, how to run it and what it found, and a row in `repro/studies.json` that is
+  updated when the study ends (then `npx paperlint studies index <paper-dir>`); `repro/study-registered`
+  holds it. Scripts the
   whole paper uses go in `repro/tools/`, shared data in `repro/data/`; `repro/allowed-files-only` reports
   anything else at the top of `repro/`.
 - **The scorecard's verdicts live only here.** The dated report `study-accepted-papers` writes under

package/skills/render-paper/check-render.sh

@@ -184,10 +184,19 @@ if [ -f "$BLG" ]; then
     grep -E "^(You're|I'm skipping|Repeated entry|I couldn't open)" "$BLG" | sed 's/^/      /' | head -12
   fi
   # A cited key that never made it into the .bbl is the same failure seen from the other side.
+  # An IEEEtran BST control entry (`@IEEEtranBSTCTL`, activated by `\bstctlcite{key}`) is cited
+  # in the .aux like any key, but IEEEtran reads it as configuration and never prints it as a
+  # \bibitem — so it is not a missing reference. A key is exempt only when IEEEtran itself reports
+  # reading it as a control entry: the .blg line `** IEEEtran BST control entry "key" detected.`,
+  # which every IEEEtran*.bst prints. BibTeX wrote that line after parsing the build's own databases,
+  # so a record in a .bib the build does not read, inside `@comment{…}`, or misspelled exempts
+  # nothing, and every layout BibTeX accepts is recognised without parsing .bib files here.
   if [ -f "$BASE.aux" ] && [ -f "$BASE.bbl" ]; then
     missing=0
+    ctl=$(sed -n 's/^\*\* IEEEtran BST control entry "\(.*\)" detected\.$/\1/p' "$BASE.blg" 2>/dev/null | sort -u)
     while read -r key; do
       [ -z "$key" ] && continue
+      printf '%s\n' "$ctl" | grep -qxF -- "$key" && continue
       grep -qF "{$key}" "$BASE.bbl" || { echo "      cited but NOT in the bibliography: $key"; missing=$((missing+1)); }
     done < <(grep -oE '\\citation\{[^}]*\}' "$BASE.aux" | sed 's/.*{//;s/}//' | tr ',' '\n' | sort -u)
     [ "$missing" -gt 0 ] && { echo "  CITED-BUT-ABSENT references: $missing"; blgerr=$((blgerr+missing)); }

package/skills/render-paper/render-paper.harness.mjs

@@ -295,3 +295,105 @@ await checkSkill("render-paper");
         : ` under ${root}/`),
   );
 }
+
+// ── AN IEEEtran BST CONTROL ENTRY IS NOT A MISSING REFERENCE ─────────────────
+// `\\bstctlcite{key}` cites an `@IEEEtranBSTCTL{key, …}` entry, so the key lands in the .aux like any
+// citation, but IEEEtran reads it as configuration and never prints a \\bibitem for it. The
+// "cited but NOT in the bibliography" check failed a real IEEE paper on exactly that key (an
+// "et al. after six authors" setting). The exemption comes only from IEEEtran's own .blg line
+// `** IEEEtran BST control entry "key" detected.`: BibTeX wrote it after parsing the build's
+// databases, so a record BibTeX never read (a .bib the build does not use, a record inside
+// `@comment{…}`) or a misspelled key exempts nothing, and a genuinely missing key is still reported.
+{
+  const HERE = dirname(fileURLToPath(import.meta.url));
+  const CHECK = join(HERE, "check-render.sh");
+  // `detected` = the keys IEEEtran reported in the .blg as control entries it read.
+  const paper = (citations, detected = ["BSTcontrol"]) => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "bstctl-")));
+    writeFileSync(
+      join(dir, "paper.tex"),
+      "\\documentclass{IEEEtran}\n\\begin{document}\n\\bstctlcite{BSTcontrol}\nText \\cite{real}.\n\\bibliographystyle{IEEEtran}\n\\bibliography{refs}\n\\end{document}\n",
+    );
+    writeFileSync(
+      join(dir, "paper.aux"),
+      citations.map((k) => `\\citation{${k}}`).join("\n") +
+        "\n\\bibstyle{IEEEtran}\n\\bibdata{refs}\n",
+    );
+    writeFileSync(
+      join(dir, "paper.bbl"),
+      "\\begin{thebibliography}{1}\n\\bibitem{real}\nA real reference, 2026.\n\\end{thebibliography}\n",
+    );
+    writeFileSync(
+      join(dir, "paper.blg"),
+      "This is BibTeX, Version 0.99e\nDatabase file #1: refs.bib\n-- IEEEtran.bst version 1.14 (2015/08/26) by Michael Shell.\n" +
+        detected
+          .map((k) => `** IEEEtran BST control entry "${k}" detected.\n`)
+          .join("") +
+        "\nDone.\n",
+    );
+    writeFileSync(
+      join(dir, "paper.log"),
+      "This is pdfTeX\nOutput written on paper.pdf (1 page, 1000 bytes).\n",
+    );
+    const r = spawnSync("bash", [CHECK, dir, "paper"], {
+      encoding: "utf8",
+      env: { ...process.env, NO_COMPILE: "1" },
+    });
+    // The script must run to its verdict: a run that stopped early prints no complaint either, and
+    // "no complaint" is what the exemption case asserts. stderr and the bash version name the cause.
+    assert.match(
+      r.stdout,
+      /^(PASS|FAIL)\b/m,
+      `check-render.sh stopped before its verdict (exit ${r.status}, ${BASH_VERSION}):\n` +
+        `--- stdout\n${r.stdout}--- stderr\n${r.stderr}`,
+    );
+    return r;
+  };
+  const BASH_VERSION = spawnSync("bash", ["--version"], {
+    encoding: "utf8",
+  }).stdout.split("\n")[0];
+
+  const ctlOnly = paper(["BSTcontrol", "real"]);
+  assert.doesNotMatch(
+    ctlOnly.stdout,
+    /CITED-BUT-ABSENT/,
+    `a control key IEEEtran reported reading was flagged as a missing reference:\n${ctlOnly.stdout}`,
+  );
+
+  // A key that starts with "-" is still a key, not a grep option.
+  const dashKey = paper(["-ctl", "real"], ["-ctl"]);
+  assert.doesNotMatch(
+    dashKey.stdout,
+    /CITED-BUT-ABSENT/,
+    `a control key starting with "-" was flagged:\n${dashKey.stdout}`,
+  );
+
+  // A misspelled \\bstctlcite key: IEEEtran detected a different key, so this one is not exempt.
+  const typo = paper(["BSTcontrl", "real"]);
+  assert.match(
+    typo.stdout,
+    /cited but NOT in the bibliography: BSTcontrl/,
+    `a \\bstctlcite key IEEEtran did not report must be flagged:\n${typo.stdout}`,
+  );
+
+  // A record BibTeX never read — in a .bib the build does not use, or inside @comment{…} — leaves
+  // no "detected" line, so the key is not exempt.
+  const unread = paper(["BSTcontrol", "real"], []);
+  assert.match(
+    unread.stdout,
+    /cited but NOT in the bibliography: BSTcontrol/,
+    `a control key IEEEtran never reported reading must be flagged:\n${unread.stdout}`,
+  );
+
+  const withGap = paper(["BSTcontrol", "real", "gone"]);
+  assert.match(
+    withGap.stdout,
+    /cited but NOT in the bibliography: gone/,
+    `a key with no \\bibitem must still be reported:\n${withGap.stdout}`,
+  );
+  assert.doesNotMatch(
+    withGap.stdout,
+    /bibliography: BSTcontrol/,
+    withGap.stdout,
+  );
+}

package/skills/run-agent-grid/SKILL.md

@@ -4,7 +4,7 @@ description: "Run a paid or counted agent experiment grid end to end — units
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Agent]
 ---
 
-<!-- vigiles:sha256:aef4152e680a2ccd compiled from skills/run-agent-grid/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:522a747e8eb6ead4 compiled from skills/run-agent-grid/SKILL.md.spec.ts -->
 
 # run-agent-grid — running a counted agent grid without spoiling it
 
@@ -23,6 +23,13 @@ and a driver loop that calls the guard: [`references/registry-and-ledger.md`](re
 **Exit codes of every guard command:** 0 allowed or clean · 1 refused or a finding · 2 usage ·
 3 (`gate` only) the cell is already counted, skip it.
 
+**The grid's study folder.** A grid is one study of the paper. Its folder is made by
+`npx paperlint studies new <paper-dir> "<title>" --kind measurement` — the next id in
+`repro/studies.json`, the folder `repro/<id>-<slug>/` — and `grid.json`, the runs and the ledger live
+in it. When the grid ends, its row is updated (`status`, `result`, `result_file`, `in_paper`) and
+`npx paperlint studies index <paper-dir>` regenerates the index; `repro/study-registered` fails the
+lint until both are done.
+
 ## The order — each gate is passed before the next phase starts
 
 ### 1. The registry: what may be measured, written as data (catalog 1, 3, 14)

package/skills/run-agent-grid/SKILL.md.spec.ts

@@ -24,6 +24,13 @@ and a driver loop that calls the guard: [\`references/registry-and-ledger.md\`](
 **Exit codes of every guard command:** 0 allowed or clean · 1 refused or a finding · 2 usage ·
 3 (\`${COMMANDS.gate}\` only) the cell is already counted, skip it.
 
+**The grid's study folder.** A grid is one study of the paper. Its folder is made by
+\`npx paperlint studies new <paper-dir> "<title>" --kind measurement\` — the next id in
+\`repro/studies.json\`, the folder \`repro/<id>-<slug>/\` — and \`grid.json\`, the runs and the ledger live
+in it. When the grid ends, its row is updated (\`status\`, \`result\`, \`result_file\`, \`in_paper\`) and
+\`npx paperlint studies index <paper-dir>\` regenerates the index; \`repro/study-registered\` fails the
+lint until both are done.
+
 ## The order — each gate is passed before the next phase starts
 
 ### 1. The registry: what may be measured, written as data (catalog 1, 3, 14)

package/src/adapters/study-registry/index.test.ts

@@ -0,0 +1,144 @@
+/**
+ * The schema of `repro/studies.json`: the text a registry is parsed from, the extra fields a row keeps,
+ * and every way a file can fail to be a registry — refused with the reasons, never read as one.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  registryText,
+  type StudyRegistry,
+} from "../../domain/study-registry.ts";
+import { studyRegistryCodec } from "./index.ts";
+
+const parse = studyRegistryCodec.parse;
+
+const ROW = {
+  id: "P1-S01",
+  folder: "P1-S01-baseline",
+  title: "Baseline pass rate",
+  question: "How often does the agent pass?",
+  kind: "measurement",
+  status: "done",
+  date: "2026-10-15",
+  result: "41 of 60 pass",
+  result_file: "results.tsv",
+  superseded_by: "P1-S02",
+  in_paper: "yes",
+} as const;
+
+const text = (v: unknown): string => JSON.stringify(v);
+const withRow = (row: Readonly<Record<string, unknown>>): string =>
+  text({ prefix: "P1", studies: [row] });
+
+describe("parsing a studies.json", () => {
+  it("a registry parses to itself, and what registryText writes parses back", () => {
+    const registry: StudyRegistry = { prefix: "P1", studies: [ROW] };
+    expect(parse(text(registry))).toEqual({ ok: true, registry });
+    expect(parse(registryText(registry))).toEqual({ ok: true, registry });
+  });
+
+  it("the optional fields may be absent", () => {
+    const { result, result_file, superseded_by, ...row } = ROW;
+    expect([result, result_file, superseded_by]).toHaveLength(3);
+    expect(parse(withRow(row))).toEqual({
+      ok: true,
+      registry: { prefix: "P1", studies: [row] },
+    });
+  });
+
+  it("🔴 a row's extra fields are kept, whatever they hold", () => {
+    const row = {
+      ...ROW,
+      role: "counted",
+      frame: { population: 4210 },
+      rules_under_test: ["a", "b"],
+      author_check: null,
+    };
+    expect(parse(withRow(row))).toEqual({
+      ok: true,
+      registry: { prefix: "P1", studies: [row] },
+    });
+  });
+
+  it("an empty registry parses", () => {
+    expect(parse(text({ prefix: "AB2", studies: [] }))).toEqual({
+      ok: true,
+      registry: { prefix: "AB2", studies: [] },
+    });
+  });
+});
+
+describe("refusing what is not a registry", () => {
+  it("text that is not JSON", () => {
+    expect(parse("{ prefix: P1")).toEqual({ ok: false, why: "not JSON" });
+  });
+
+  it.each([
+    [
+      "no prefix",
+      { studies: [] },
+      "prefix: Invalid input: expected string, received undefined",
+    ],
+    [
+      "a prefix of another shape",
+      { prefix: "p1", studies: [] },
+      "prefix: a capital letter, then capitals or digits (P1)",
+    ],
+    [
+      "an unknown top-level key",
+      { prefix: "P1", studies: [], studys: [] },
+      '(top): Unrecognized key: "studys"',
+    ],
+    [
+      "studies not a list",
+      { prefix: "P1", studies: {} },
+      "studies: Invalid input: expected array, received object",
+    ],
+  ])("%s", (_why, v, why) => {
+    expect(parse(text(v))).toEqual({ ok: false, why });
+  });
+});
+
+describe("refusing a row that is not a study", () => {
+  it.each([
+    [
+      "kind",
+      "benchmark",
+      'studies.0.kind: Invalid option: expected one of "measurement"|"spike"|"tooling"|"data"|"artifact"|"salvage"',
+    ],
+    [
+      "status",
+      "finished",
+      'studies.0.status: Invalid option: expected one of "designing"|"running"|"done"|"stopped"|"superseded"|"dropped"',
+    ],
+    [
+      "in_paper",
+      "maybe",
+      'studies.0.in_paper: Invalid option: expected one of "yes"|"no"|"registry"',
+    ],
+    ["date", "15.10.2026", "studies.0.date: Invalid ISO date"],
+    [
+      "title",
+      "",
+      "studies.0.title: Too small: expected string to have >=1 characters",
+    ],
+    [
+      "result",
+      41,
+      "studies.0.result: Invalid input: expected string, received number",
+    ],
+  ])("a row whose %s is %j", (field, value, why) => {
+    expect(parse(withRow({ ...ROW, [field]: value }))).toEqual({
+      ok: false,
+      why,
+    });
+  });
+
+  it("every reason, joined", () => {
+    const { question, ...row } = ROW;
+    expect(question).toBeDefined();
+    expect(parse(text({ prefix: 1, studies: [row] }))).toEqual({
+      ok: false,
+      why: "prefix: Invalid input: expected string, received number; studies.0.question: Invalid input: expected string, received undefined",
+    });
+  });
+});

package/src/adapters/study-registry/index.ts

@@ -0,0 +1,70 @@
+/**
+ * The schema of `repro/studies.json` — the one place its shape is checked (docs/design/study-registry.md).
+ * The text is parsed once, here, into the domain's `StudyRegistry`; whatever reads a registry after it
+ * never re-validates.
+ *
+ * A row is a loose object: a paper merges its own measurement metadata into its rows (`role`, `frame`,
+ * `rules_under_test`, `outcome` …), and those fields are kept as they are. The top level is strict, so
+ * a misspelt key is an error rather than a key nobody reads.
+ */
+import { z } from "zod";
+import {
+  IN_PAPER,
+  PREFIX_PATTERN,
+  STUDY_KINDS,
+  STUDY_STATUSES,
+  type ParsedRegistry,
+} from "../../domain/study-registry.ts";
+import type { StudyRegistryCodec } from "../../ports/study-registry-codec.ts";
+
+const study = z.looseObject({
+  id: z.string(),
+  folder: z.string(),
+  title: z.string().min(1),
+  question: z.string(),
+  kind: z.enum(STUDY_KINDS),
+  status: z.enum(STUDY_STATUSES),
+  date: z.iso.date(),
+  result: z.string().optional(),
+  result_file: z.string().optional(),
+  superseded_by: z.string().optional(),
+  in_paper: z.enum(IN_PAPER),
+});
+
+const registry = z.strictObject({
+  prefix: z
+    .string()
+    .regex(PREFIX_PATTERN, "a capital letter, then capitals or digits (P1)"),
+  studies: z.array(study),
+});
+
+/** The JSON `text` holds, or undefined when it is not JSON. */
+function jsonOf(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/** A `studies.json`'s text, parsed once at the boundary: the registry, or every reason it is not one. */
+export function parseStudyRegistry(text: string): ParsedRegistry {
+  const json = jsonOf(text);
+  if (json === undefined) return { ok: false, why: "not JSON" };
+  const parsed = registry.safeParse(json);
+  return parsed.success
+    ? { ok: true, registry: parsed.data }
+    : {
+        ok: false,
+        why: parsed.error.issues
+          .map(
+            (i) =>
+              `${i.path.length === 0 ? "(top)" : i.path.join(".")}: ${i.message}`,
+          )
+          .join("; "),
+      };
+}
+
+export const studyRegistryCodec: StudyRegistryCodec = {
+  parse: parseStudyRegistry,
+};

package/src/cli.ts

@@ -185,6 +185,12 @@ import {
   REPRO_LAYOUT_RULE_LEVELS,
   reproLayoutRules,
 } from "./repro-layout-rule.ts";
+import {
+  STUDY_REGISTRY_RULE_LEVELS,
+  studyRegistryRules,
+} from "./study-registry-rule.ts";
+import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
+import { runStudies } from "./studies.ts";
 import typography from "#eslint-rules/paper-typography";
 import texBuild from "#eslint-rules/tex-build";
 import reviewFrontmatter from "#eslint-rules/review-frontmatter";
@@ -230,6 +236,12 @@ const USAGE = `paperlint — machine-checkable gates for a paper kept in git
                                       send the PDF (default: the paper's own), an abstract, or
                                       "submitted". A DRY RUN unless --save: the portal checks the
                                       change and keeps nothing
+  npx paperlint studies new <paper-dir> "<title>" [--kind <kind>]
+                                      register a study: the next id in repro/studies.json, the folder
+                                      repro/<id>-<slug>/ with its README.md, the row (status designing,
+                                      today's date), and the index in repro/README.md regenerated
+  npx paperlint studies index <paper-dir>
+                                      regenerate the index in repro/README.md from repro/studies.json
   npx paperlint hook <name>           run an editor hook (.claude/settings.json calls this)
   npx paperlint --help
 
@@ -250,6 +262,11 @@ new:
                       "realm" can be the work's own). Without it such a name is refused: a rejected
                       paper moves to another venue and keeps its folder
 
+studies:
+  --kind <kind>       new: measurement (the default), spike, tooling, data, artifact or salvage.
+                      A study's status, result and in_paper are edited in repro/studies.json;
+                      the rule repro/study-registered checks them (docs/rules/repro/study-registered.md)
+
 submission:
   The venue preset declares the portal — "portal": { "kind": "hotcrp", "url": "<site>" } — and the
   paper's paperlint.json its submission there — "submission": { "id": <number> }. The token comes
@@ -367,6 +384,27 @@ const FRAGMENT_RULES = {
 /** What the two layout rules read with: the disk and its directory listings. */
 const LAYOUT_RULE_DEPS = { files: nodeFiles, listDir: nodeListDir };
 
+/** What `repro/study-registered` and `paperlint studies` read with: the layout's, and the registry's parser. */
+const STUDY_RULE_DEPS = { ...LAYOUT_RULE_DEPS, codec: studyRegistryCodec };
+
+/** The `repro` plugin's rules, on every `PIPELINE-STATUS.md`: the layout of `repro/`, and its study registry. */
+const REPRO_RULES = {
+  ...reproLayoutRules(LAYOUT_RULE_DEPS),
+  ...studyRegistryRules(STUDY_RULE_DEPS),
+};
+const REPRO_RULE_LEVELS = {
+  ...REPRO_LAYOUT_RULE_LEVELS,
+  ...STUDY_REGISTRY_RULE_LEVELS,
+};
+
+/** Today in this machine's time zone, `YYYY-MM-DD`: the date `paperlint studies new` registers a study on. */
+const today = (now = new Date()): string =>
+  [
+    String(now.getFullYear()),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0"),
+  ].join("-");
+
 /** What the talk rules read with: the disk, the shipped presets, and the three media readers. */
 const TALK_RULE_DEPS = {
   files: nodeFiles,
@@ -433,7 +471,7 @@ export function buildConfig(
             ...folderLayoutRules(LAYOUT_RULE_DEPS),
           },
         },
-        repro: { rules: reproLayoutRules(LAYOUT_RULE_DEPS) },
+        repro: { rules: REPRO_RULES },
         // Registered, on for no paper: `"study/declare-sample": "error"` in paperlint.json turns it on.
         study: { rules: preregCoverage.rules },
         cycle: { rules: CYCLE_STATUS_RULES },
@@ -444,7 +482,7 @@ export function buildConfig(
         "paper/source": "error",
         ...FOLDER_VENUE_RULE_LEVELS,
         ...FOLDER_LAYOUT_RULE_LEVELS,
-        ...REPRO_LAYOUT_RULE_LEVELS,
+        ...REPRO_RULE_LEVELS,
         ...CYCLE_RULE_LEVELS,
       },
     },
@@ -1626,6 +1664,17 @@ const SIMPLE: Readonly<
       banal: hostBanalInstaller(),
       tex: toolchainTex(cwd),
     }),
+  studies: (a, { log, err, cwd }) =>
+    runStudies(
+      {
+        sub: a.paths[0],
+        paperDir: a.paths[1],
+        title: a.paths[2],
+        extra: a.paths.slice(3),
+        kind: a.kind,
+      },
+      { ...STUDY_RULE_DEPS, cwd, today: today(), log, err },
+    ),
   submission: (a, { log, err, cwd }) =>
     runSubmission(
       {

package/src/domain/paper-layout.test.ts

@@ -257,7 +257,7 @@ describe("strayMessage — stands alone for a reader with no context", () => {
       ),
     ).toEqual([]);
     expect(lines).toContain(
-      "│   └── <slug>-YYYY-MM-DD/         ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)",
+      "│   └── <id>-<slug>/               ← one folder per study or spike, named by its row in studies.json (P1-S03-baseline)",
     );
     expect(lines.at(-1)).toMatch(/^└── extra\/ +← anything; never judged$/);
   });

package/src/domain/repro-layout.test.ts

@@ -38,6 +38,9 @@ describe("isStudyName", () => {
     "leap-2024-02-29",
     "leap-2000-02-29",
     "april-2026-04-30",
+    "P1-S01-baseline",
+    "P12-S100-a1-b2",
+    "AB-S07-x",
   ])("%s is a study's name", (name) => {
     expect(isStudyName(name)).toBe(true);
   });
@@ -56,6 +59,11 @@ describe("isStudyName", () => {
     ["29 February 1900", "x-1900-02-29"],
     ["32 October", "x-2026-10-32"],
     ["a two-digit year", "x-26-10-12"],
+    ["an id with one digit", "P1-S1-baseline"],
+    ["an id and no slug", "P1-S01"],
+    ["a lowercase id", "p1-s01-baseline"],
+    ["a capital in the slug", "P1-S01-Baseline"],
+    ["an id with no S", "P1-01-baseline"],
   ])("not with %s: %s", (_why, name) => {
     expect(isStudyName(name)).toBe(false);
   });
@@ -158,7 +166,7 @@ describe("judgeRepro — reports a folder, one finding each", () => {
       {
         path: "repro/Old_Baseline/",
         problem: "stray",
-        cure: "rename it to `old-baseline-YYYY-MM-DD`, one folder per study or spike, named for what it is and the date it began — the date of its first commit is a fine default (`git log --reverse --format=%as -- repro/Old_Baseline | head -1`, run in the paper folder) — and give it a README.md; if it holds scripts or data shared across the paper instead, move them into repro/tools/ or repro/data/",
+        cure: "rename it to `<id>-old-baseline` — the next free id in repro/studies.json, then what it is — give it its row there and a README.md (`npx paperlint studies new` makes all three for a new study); in a paper with repro/study-registered off, `old-baseline-YYYY-MM-DD` is accepted instead, dated by the day it began — its first commit is a fine default (`git log --reverse --format=%as -- repro/Old_Baseline | head -1`, run in the paper folder); if it holds scripts or data shared across the paper instead, move them into repro/tools/ or repro/data/",
       },
     ]);
   });
@@ -168,7 +176,7 @@ describe("judgeRepro — reports a folder, one finding each", () => {
       {
         path: "repro/ablation-2026-10-12/",
         problem: "no-readme",
-        cure: "add repro/ablation-2026-10-12/README.md — what the study asks, how to run it, what it found — and a line for it in repro/README.md",
+        cure: "add repro/ablation-2026-10-12/README.md — what the study asks, how to run it, what it found — and give the study its row in repro/studies.json",
       },
     ]);
   });
@@ -194,15 +202,16 @@ describe("reproMessage — stands alone", () => {
       }),
     ).toBe(
       [
-        `\`repro/run.py\` is loose at the top of the paper's repro/ folder, which holds only an index, the shared tools and data, and one dated folder per study. Where it goes: ${SCRIPT_CURE}.`,
+        `\`repro/run.py\` is loose at the top of the paper's repro/ folder, which holds only an index, the study registry, the shared tools and data, and one folder per study. Where it goes: ${SCRIPT_CURE}.`,
         "What repro/ holds (what interpreters and package managers leave there, like __pycache__/ and node_modules/, is never reported):",
         "repro/",
-        "├── README.md           ← the index: one line per study",
-        "├── .gitignore          ← keeps the scripts' byproducts out of git",
-        "├── tools/              ← scripts used across the paper (numbers, figures, anonymity check, harnesses)",
-        "├── data/               ← shared data (tables, caches)",
-        "└── <slug>-YYYY-MM-DD/  ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)",
-        "    └── README.md       ← required: what it asks, how to run it, what it found",
+        "├── README.md      ← the index: one line per study, generated from studies.json",
+        "├── studies.json   ← the study registry: id, title, status and result of each study",
+        "├── .gitignore     ← keeps the scripts' byproducts out of git",
+        "├── tools/         ← scripts used across the paper (numbers, figures, anonymity check, harnesses)",
+        "├── data/          ← shared data (tables, caches)",
+        "└── <id>-<slug>/   ← one folder per study or spike, named by its row in studies.json (P1-S03-baseline)",
+        "    └── README.md  ← required: what it asks, how to run it, what it found",
         "Rule repro/allowed-files-only: https://github.com/zernie/paperlint/blob/main/docs/rules/repro/allowed-files-only.md",
       ].join("\n"),
     );