paperlint 10.1.1 → 10.3.0

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

@@ -0,0 +1,328 @@
+/**
+ * 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. A measurement keeps its extra fields as a
+ * row does; a requirement and an approval are exactly their fields.
+ *
+ * A study's plan (`plan.json`) is parsed here too, strictly: a key of the paper's own goes in `extra`.
+ * Its texts may be empty — the template's are — and the parser says which: a plan comes out ready or
+ * a draft naming its empty texts, so nothing downstream looks at a text again. A plan still named
+ * `prereg.json` has a loose schema of its own.
+ */
+import { z } from "zod";
+import {
+  IN_PAPER,
+  MEASUREMENT_ROLES,
+  PLAN_FIELDS,
+  PLAN_TEXT_FIELDS,
+  PREFIX_PATTERN,
+  STUDY_KINDS,
+  STUDY_STATUSES,
+  type Approval,
+  type AuthorCheck,
+  type Measurement,
+  type ParsedPlan,
+  type ParsedRegistry,
+  type Requirement,
+  type Study,
+  type StudyPlan,
+  type StudyRegistry,
+} 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),
+  measurement: z.string().optional(),
+  plan: z.string().optional(),
+});
+
+const words = z.string().min(1);
+
+const requirement = z.strictObject({
+  id: words,
+  text: words,
+  date: z.iso.date(),
+  source: words,
+});
+
+const approval = z.strictObject({
+  by: words,
+  date: z.iso.date(),
+  quote: words,
+  source: words.optional(),
+});
+
+const measurement = z.looseObject({
+  id: words,
+  title: words,
+  rq: z.string().optional(),
+  role: z.enum(MEASUREMENT_ROLES),
+  approval: approval.optional(),
+  requirements: z.array(z.string()).optional(),
+});
+
+const registry = z.strictObject({
+  prefix: z
+    .string()
+    .regex(PREFIX_PATTERN, "a capital letter, then capitals or digits (P1)"),
+  author: words.optional(),
+  requirements: z.array(requirement).optional(),
+  measurements: z.array(measurement).optional(),
+  studies: z.array(study),
+});
+
+const authorCheck = approval.omit({ source: true });
+
+/** A draw: seeded, its seed part of it, or of all the population, with none. */
+const draw = z.discriminatedUnion("kind", [
+  z.strictObject({
+    kind: z.literal("seeded"),
+    method: z.string(),
+    seed: z.union([z.string(), z.number()]),
+  }),
+  z.strictObject({ kind: z.literal("all"), method: z.string() }),
+]);
+
+/** The values that occur more than once in `values`, each once. */
+const repeated = (values: readonly string[]): readonly string[] => [
+  ...new Set(values.filter((v, i) => values.indexOf(v) !== i)),
+];
+
+/** Arms whose names are unique: a repeated name is an error naming it. */
+const uniquelyNamed = (
+  arms: readonly { readonly name: string }[],
+  ctx: Readonly<z.core.$RefinementCtx>,
+): void => {
+  repeated(arms.map((a) => a.name)).forEach((name) => {
+    ctx.addIssue({
+      code: "custom",
+      message: `more than one arm is named «${name}» — an arm's name is unique`,
+    });
+  });
+};
+
+/** The paper's own keys: none of them a field of the plan, which would say a thing twice. */
+const extra = z.record(z.string(), z.unknown()).superRefine((e, ctx) => {
+  Object.keys(e)
+    .filter((k) => PLAN_FIELDS.some((f) => f === k))
+    .forEach((k) => {
+      ctx.addIssue({
+        code: "custom",
+        path: [k],
+        message: "is a field of the plan itself — set it there, not in extra",
+      });
+    });
+});
+
+/** A plan's shape: closed at every level; the paper's own keys go in `extra`. Null is the one "none". */
+const planShape = z.strictObject({
+  question: z.string(),
+  population: z.strictObject({ source: z.string(), draw }),
+  arms: z.array(z.strictObject({ name: words })).superRefine(uniquelyNamed),
+  primary_outcome: z.string(),
+  author_check: authorCheck.nullable(),
+  extra: extra.optional(),
+});
+
+/**
+ * A plan under its old name, `prereg.json`, written by hand before the plan had a schema: open at
+ * every level, its own top-level keys kept in `extra`. A seed makes the draw seeded, none (or null) a
+ * draw of all; a size, and keys of its own deeper down, are not read; the file is never rewritten.
+ */
+const legacyAsPlan = z
+  .looseObject({
+    question: z.string(),
+    population: z.looseObject({
+      source: z.string(),
+      draw: z.looseObject({
+        method: z.string(),
+        seed: z.union([z.string(), z.number()]).nullable().optional(),
+      }),
+    }),
+    arms: z.array(z.looseObject({ name: words })).superRefine(uniquelyNamed),
+    primary_outcome: z.string(),
+    author_check: authorCheck.nullable().optional(),
+  })
+  .transform((p): StudyPlan => {
+    const {
+      question,
+      population,
+      arms,
+      primary_outcome,
+      author_check,
+      ...rest
+    } = p;
+    const { method, seed } = population.draw;
+    return {
+      question,
+      population: {
+        source: population.source,
+        draw:
+          seed === undefined || seed === null
+            ? { kind: "all", method }
+            : { kind: "seeded", method, seed },
+      },
+      arms: arms.map((a) => ({ name: a.name })),
+      primary_outcome,
+      author_check: author_check ?? null,
+      extra: rest,
+    };
+  });
+
+/** A text that says something: more than white space. */
+const filled = z.string().regex(/\S/u);
+
+/** The texts a plan fills before its study runs; what fails here is what is still empty. */
+const readyTexts = z.object({
+  question: filled,
+  population: z.object({
+    source: filled,
+    draw: z.object({ method: filled }),
+  }),
+  primary_outcome: filled,
+});
+
+/** A plan that parsed: ready, or a draft. */
+type ReadyOrDraft = Exclude<ParsedPlan, { readonly kind: "unreadable" }>;
+
+/**
+ * A parsed plan, ready when every required text is filled, else a draft naming the empty ones. A
+ * draft that carries the author's check is no plan: the author approved one with empty texts.
+ */
+const readyOrDraft = (
+  p: StudyPlan,
+  ctx: Readonly<z.core.$RefinementCtx>,
+): ReadyOrDraft => {
+  const checked = readyTexts.safeParse(p);
+  if (checked.success) return { kind: "ready", plan: p };
+  const paths = checked.error.issues.map((i) => i.path.join("."));
+  const empty = PLAN_TEXT_FIELDS.filter((f) => paths.includes(f));
+  if (p.author_check === null)
+    return { kind: "draft", plan: { ...p, author_check: null }, empty };
+  ctx.addIssue({
+    code: "custom",
+    path: ["author_check"],
+    message: `is set, and the plan leaves ${empty.map((f) => `\`${f}\``).join(", ")} empty — the author approves a complete plan: fill them, or set author_check to null`,
+  });
+  return z.NEVER;
+};
+
+/** A `plan.json`: strict, then ready or draft. */
+const plan = planShape.transform(readyOrDraft);
+
+/** A `prereg.json`: loose, mapped onto the plan, then ready or draft. */
+const legacyPlan = legacyAsPlan.transform(readyOrDraft);
+
+// ── the schemas ARE the domain's types ─────────────────────────────────────────
+// Each schema's output and its hand-written domain type are the same type, both ways, once both are
+// made readonly all the way down: a field added to one and not the other stops the build.
+
+/** `T`, readonly all the way down: zod's outputs are mutable, the domain's are not. */
+type Frozen<T> = T extends readonly (infer U)[]
+  ? readonly Frozen<U>[]
+  : T extends object
+    ? { readonly [K in keyof T]: Frozen<T[K]> }
+    : T;
+
+/**
+ * True when `A` and `B`, both made readonly all the way down, are one type, optional modifiers
+ * included: two generic signatures whose returns are deferred conditionals are related only when
+ * the conditionals are identical. Written out, not through an alias: an alias is compared by the
+ * variance of its parameter, which misses a dropped optional field.
+ */
+type Same<A, B> =
+  (<T>() => T extends Frozen<A> ? readonly [T] : 2) extends <
+    T,
+  >() => T extends Frozen<B> ? readonly [T] : 2
+    ? true
+    : false;
+
+/** Compiles only when every schema's output is its domain type. */
+export type SchemasAreTheDomain = [
+  Same<z.output<typeof registry>, StudyRegistry>,
+  Same<z.output<typeof study>, Study>,
+  Same<z.output<typeof measurement>, Measurement>,
+  Same<z.output<typeof requirement>, Requirement>,
+  Same<z.output<typeof approval>, Approval>,
+  Same<z.output<typeof authorCheck>, AuthorCheck>,
+  Same<z.output<typeof planShape>, StudyPlan>,
+  Same<z.output<typeof legacyAsPlan>, StudyPlan>,
+  Same<z.output<typeof plan>, ReadyOrDraft>,
+  Same<z.output<typeof legacyPlan>, ReadyOrDraft>,
+] extends true[]
+  ? true
+  : never;
+
+/** The proof is used, so the build checks it. */
+export const SCHEMAS_ARE_THE_DOMAIN: SchemasAreTheDomain = true;
+
+/** The JSON `text` holds, or undefined when it is not JSON. */
+function jsonOf(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every reason zod gave, each with the path it is about. */
+const reasons = (
+  issues: readonly {
+    readonly path: readonly PropertyKey[];
+    readonly message: string;
+  }[],
+): string =>
+  issues
+    .map(
+      (i) =>
+        `${i.path.length === 0 ? "(top)" : i.path.join(".")}: ${i.message}`,
+    )
+    .join("; ");
+
+/** 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: reasons(parsed.error.issues) };
+}
+
+/** A plan's text, parsed once at the boundary by `schema`: ready, a draft, or every reason it is neither. */
+const planParser =
+  (schema: Readonly<z.ZodType<ReadyOrDraft>>) =>
+  (text: string): ParsedPlan => {
+    const json = jsonOf(text);
+    if (json === undefined) return { kind: "unreadable", why: "not JSON" };
+    const parsed = schema.safeParse(json);
+    return parsed.success
+      ? parsed.data
+      : { kind: "unreadable", why: reasons(parsed.error.issues) };
+  };
+
+/** A `plan.json`: strict. */
+export const parseStudyPlan = planParser(plan);
+
+/** A plan still named `prereg.json`: loose, read only when a row names it. */
+export const parseLegacyPlan = planParser(legacyPlan);
+
+export const studyRegistryCodec: StudyRegistryCodec = {
+  parse: parseStudyRegistry,
+  parsePlan: parseStudyPlan,
+  parseLegacyPlan,
+};

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,13 @@ 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 and plan.json (a template),
+                                      the row (status designing, today's date, its plan), 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 +263,12 @@ 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, its
+                      plan in its plan.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 +386,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 +473,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 +484,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 +1666,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"),
     );

package/src/domain/repro-layout.ts

@@ -7,15 +7,21 @@
  * where a new run goes. The layout gives each kind of material one place:
  *
  *   repro/
- *   ├── README.md              the index: one line per study
- *   ├── <slug>-YYYY-MM-DD/     one folder per study or spike, with a README.md inside
+ *   ├── README.md              the index: one line per study, generated from studies.json
+ *   ├── studies.json           the study registry: one row per study (src/domain/study-registry.ts)
+ *   ├── <id>-<slug>/           one folder per study or spike, named by its row, with a README.md inside
  *   ├── tools/                 scripts used across the paper (numbers, figures, anonymity check, harnesses)
  *   └── data/                  shared data (tables, caches)
  *
  * plus `.gitignore`. A loose note belongs in its study's folder or in the paper's `research/`.
  *
- * ── THE DATE IN A STUDY'S NAME ────────────────────────────────────────────────────
- * `<slug>-YYYY-MM-DD` is the day the study began. `<slug>-YYYY-MM` is accepted too: a study that ran
+ * ── A STUDY'S NAME ───────────────────────────────────────────────────────────────
+ * `<id>-<slug>` (`P1-S03-baseline`): the id of the study's row in `repro/studies.json` — the paper's
+ * prefix, `-S`, two or more digits — then the slug. Whether the id has a row, and the row this folder,
+ * is `repro/study-registered`'s question; this layout only accepts the shape.
+ *
+ * The older form, `<slug>-YYYY-MM-DD`, stays accepted, so a paper that turned the registry off is not
+ * broken: the date is the day the study began. `<slug>-YYYY-MM` is accepted too: a study that ran
  * over weeks (labelling, a reading of a corpus) has a month as its honest date, and both forms sort
  * by time. The date must be a real one (no month 13, no 30 February). The slug is lowercase letters
  * and digits in words joined by single hyphens.
@@ -32,6 +38,9 @@ import { leaf, renderTree, type TreeNode } from "./layout-tree.ts";
 /** The folder this layout governs, at the paper folder's root. */
 export const REPRO_DIR = "repro";
 
+/** The study registry, at the top of `repro/` (src/domain/study-registry.ts). */
+export const STUDIES_FILE = "studies.json";
+
 /** The index at the top of `repro/`, and the file every study folder holds. */
 export const README = "README.md";
 
@@ -40,7 +49,14 @@ export const REPRO_FILE_NOTES: readonly {
   readonly name: string;
   readonly note: string;
 }[] = [
-  { name: README, note: "the index: one line per study" },
+  {
+    name: README,
+    note: "the index: one line per study, generated from studies.json",
+  },
+  {
+    name: STUDIES_FILE,
+    note: "the study registry: id, title, status and result of each study",
+  },
   { name: ".gitignore", note: "keeps the scripts' byproducts out of git" },
 ];
 export const REPRO_FILES: readonly string[] = REPRO_FILE_NOTES.map(
@@ -64,8 +80,8 @@ export const REPRO_DIRS: readonly string[] = REPRO_DIR_NOTES.map((d) => d.name);
 
 /** The study folder as the layout draws it: the name pattern, and the README.md it must hold. */
 const STUDY_NODE: TreeNode = {
-  name: "<slug>-YYYY-MM-DD/",
-  note: "one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)",
+  name: "<id>-<slug>/",
+  note: "one folder per study or spike, named by its row in studies.json (P1-S03-baseline)",
   children: [
     leaf(README, "required: what it asks, how to run it, what it found"),
   ],
@@ -100,9 +116,20 @@ export const REPRO_BYPRODUCTS: readonly string[] = [
   "Thumbs.db",
 ];
 
-/** A study's name: a slug, then the year, the month, and optionally the day it began. */
+/** A slug: lowercase letters and digits, in words joined by single hyphens. */
+export const STUDY_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+/** A dated study's name: a slug, then the year, the month, and optionally the day it began. */
 const STUDY_NAME = /^([a-z0-9]+(?:-[a-z0-9]+)*)-(\d{4})-(\d{2})(?:-(\d{2}))?$/u;
 
+/** A registered study's name: the id (a prefix, `-S`, two or more digits), then the slug. */
+const REGISTERED_STUDY_NAME =
+  /^[A-Z][A-Z0-9]*-S\d{2,}-[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+/** Whether `name` is a registered study folder's: `<id>-<slug>`, as `P1-S03-baseline`. */
+export const isRegisteredStudyName = (name: string): boolean =>
+  REGISTERED_STUDY_NAME.test(name);
+
 const isLeapYear = (y: number): boolean =>
   (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
 
@@ -110,8 +137,8 @@ const isLeapYear = (y: number): boolean =>
 const daysIn = (y: number, m: number): number =>
   m === 2 ? (isLeapYear(y) ? 29 : 28) : [4, 6, 9, 11].includes(m) ? 30 : 31;
 
-/** Whether `name` is a study folder's: `<slug>-YYYY-MM-DD` or `<slug>-YYYY-MM`, a real date. */
-export function isStudyName(name: string): boolean {
+/** Whether `name` is a dated study folder's: `<slug>-YYYY-MM-DD` or `<slug>-YYYY-MM`, a real date. */
+function isDatedStudyName(name: string): boolean {
   const m = STUDY_NAME.exec(name);
   if (m === null) return false;
   const year = Number(m[2]);
@@ -120,6 +147,10 @@ export function isStudyName(name: string): boolean {
   return month >= 1 && month <= 12 && day >= 1 && day <= daysIn(year, month);
 }
 
+/** Whether `name` is a study folder's: `<id>-<slug>`, or the dated `<slug>-YYYY-MM-DD` / `<slug>-YYYY-MM`. */
+export const isStudyName = (name: string): boolean =>
+  isRegisteredStudyName(name) || isDatedStudyName(name);
+
 /**
  * The study name to suggest for a folder named `name`: its name as a slug, with the date to fill in.
  * A name that becomes a study name once lowercased and hyphenated is suggested as it is.
@@ -129,9 +160,18 @@ export function suggestedStudyName(name: string): string {
     .toLowerCase()
     .replace(/[^a-z0-9]+/gu, "-")
     .replace(/^-+|-+$/gu, "");
-  if (isStudyName(slug)) return slug;
-  const base = slug.replace(/(?:^|-)\d{4}(?:-\d{1,2}){0,2}$/u, "");
-  return `${base === "" ? "<slug>" : base}-YYYY-MM-DD`;
+  if (isDatedStudyName(slug)) return slug;
+  return `${suggestedSlug(name)}-YYYY-MM-DD`;
+}
+
+/** The slug to suggest for a folder named `name`: its name as a slug, any trailing date dropped. */
+export function suggestedSlug(name: string): string {
+  const base = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .replace(/(?:^|-)\d{4}(?:-\d{1,2}){0,2}$/u, "");
+  return base === "" ? "<slug>" : base;
 }
 
 /** The extensions of a script: what a study or the paper's build runs. */
@@ -203,11 +243,11 @@ export const DATA_CURE =
 
 /** Where a note goes. */
 export const NOTE_CURE =
-  "the dated folder of the study it is about (repro/<slug>-YYYY-MM-DD/), or the paper's research/ when it is research or a decision rather than the record of a run";
+  "the folder of the study it is about (repro/<id>-<slug>/), or the paper's research/ when it is research or a decision rather than the record of a run";
 
 /** Where a file of any other kind goes. */
 export const FILE_CURE_BY_KIND =
-  "decide by what it is — a script → repro/tools/; data → repro/data/; a note → the dated folder of its study, or the paper's research/; what one study produced → that study's folder";
+  "decide by what it is — a script → repro/tools/; data → repro/data/; a note → the folder of its study, or the paper's research/; what one study produced → that study's folder";
 
 /** The files paperlint itself once kept at the top of `repro/`, each with where it is read now. */
 export const MOVED_FILES: readonly {
@@ -242,7 +282,7 @@ function fileCure(name: string): string {
 
 /** Where a folder with no study name goes: renamed as a study, or emptied into the shared folders. */
 const folderCure = (name: string): string =>
-  `rename it to \`${suggestedStudyName(name)}\`, 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/${name} | 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/`;
+  `rename it to \`<id>-${suggestedSlug(name)}\` — the next free id in repro/${STUDIES_FILE}, 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, \`${suggestedStudyName(name)}\` is accepted instead, dated by the day it began — its first commit is a fine default (\`git log --reverse --format=%as -- repro/${name} | 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/`;
 
 /** An entry at the top of `repro/`: a file or a folder, and for a folder whether it holds a README.md. */
 export interface ReproEntry {
@@ -280,7 +320,7 @@ function judgeEntry(e: ReproEntry): ReproFinding | null {
     return {
       path,
       problem: "no-readme",
-      cure: `add ${path}${README} — what the study asks, how to run it, what it found — and a line for it in repro/${README}`,
+      cure: `add ${path}${README} — what the study asks, how to run it, what it found — and give the study its row in repro/${STUDIES_FILE}`,
     };
   return null;
 }
@@ -300,7 +340,7 @@ export function judgeRepro(
 export function reproMessage(f: ReproFinding): string {
   const head =
     f.problem === "stray"
-      ? `\`${f.path}\` 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: ${f.cure}.`
+      ? `\`${f.path}\` 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: ${f.cure}.`
       : `\`${f.path}\` is a study folder without a ${README}, and every study in repro/ has one. What to do: ${f.cure}.`;
   return [
     head,