paperlint 13.0.3 → 13.2.0

package/src/adapters/git/index.ts

@@ -7,11 +7,13 @@
  *   order       whether the clone is shallow; the decision file's first commit; every file's first
  *               commit under the study's folder (`git log --reverse --name-only`); and for each, whether
  *               any commit that touched the decision is its strict ancestor (`git rev-list -- <decision>`)
+ *   fileAt      a file under the study's folder as it stood at a commit (`git ls-tree`, then `git show`)
  */
 import type { AbsolutePath } from "../../domain/paths.ts";
 import type {
   CommitAt,
   Committed,
+  FileAt,
   FirstCommit,
   GitHistory,
   GitOrder,
@@ -110,9 +112,26 @@ export function gitHistory(
         : { kind: "changed", commit };
     },
     order: (studyDir, decision) => orderIn(git, studyDir, decision),
+    fileAt: (studyDir, commit, path) => fileAtIn(git, studyDir, commit, path),
   };
 }
 
+/** `path` (relative to `studyDir`) at `commit`: `ls-tree` says whether it is there, `show` gives its text. */
+const fileAtIn = (
+  git: Git,
+  studyDir: AbsolutePath,
+  commit: string,
+  path: string,
+): FileAt => {
+  const listed = git(studyDir, ["ls-tree", "--name-only", commit, "--", path]);
+  if ("why" in listed) return { kind: "unknown", why: listed.why };
+  if (listed.out.trim() === "") return { kind: "absent" };
+  const shown = git(studyDir, ["show", `${commit}:./${path}`]);
+  return "why" in shown
+    ? { kind: "unknown", why: shown.why }
+    : { kind: "text", text: shown.out };
+};
+
 type Git = ReturnType<typeof gitIn>;
 
 /** Whether `file` is in HEAD's tree (`git ls-tree`, which takes an absolute path in the worktree). */

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

@@ -0,0 +1,181 @@
+/**
+ * The schema of a plan v2's gates (src/domain/study-gates.ts). Both halves: a plan v2 with every gate
+ * parses to itself, ready, and a plan v1 stays as it was; every gate missing, misplaced or malformed
+ * is refused with its reason; a gate still null keeps the plan a draft naming it.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, it } from "vitest";
+import { PLAN_V2 } from "../../domain/study-gates.ts";
+import type { DecideFirst } from "../../domain/study-mode.ts";
+import { planText, type StudyPlan } from "../../domain/study-registry.ts";
+import { planV2JsonSchema, studyRegistryCodec } from "./index.ts";
+
+const DECIDED: DecideFirst = {
+  kind: "decide_before_run",
+  outputs: ["result.json"],
+  decision: { file: "repro/P1-S01-x/decision.md", note: "the draw" },
+};
+
+const V1: StudyPlan = {
+  question: "Do the readings disagree?",
+  population: {
+    source: "repositories, 2026-10-31",
+    draw: { kind: "seeded", method: "one rule per repository", seed: 7 },
+  },
+  arms: [],
+  primary_outcome: "share of rules whose readings disagree",
+  author_check: null,
+  mode: DECIDED,
+};
+
+const V2: StudyPlan = {
+  ...V1,
+  $schema: PLAN_V2,
+  mode: { ...DECIDED, we_lose_if: { result: "share_upper95", below: 0.2 } },
+  second_check: [
+    { step: "lint-checkable", min_kappa: 0.6 },
+    { step: "admissible", min_kappa: 0.6 },
+  ],
+  self_test: { made_by: "scripts/selftest.mjs" },
+  funnel: ["no linter rule", "clone failed"],
+  recall_audit: { n_files: 50, min_recall: 0.6 },
+};
+
+const parse = (p: unknown) =>
+  studyRegistryCodec.parsePlan(JSON.stringify(p), "measurement");
+const why = (p: unknown): string => {
+  const r = parse(p);
+  return r.kind === "unreadable" ? r.why : r.kind;
+};
+const empty = (p: unknown) => {
+  const r = parse(p);
+  return r.kind === "draft" ? r.empty : r.kind;
+};
+
+it("a plan v2 with every gate parses to itself, ready; a plan v1 stays ready", () => {
+  // Guards: the v2 fields round-trip through the text planText writes, and v1 is unchanged.
+  expect(
+    [V1, V2].map((p) =>
+      studyRegistryCodec.parsePlan(planText(p), "measurement"),
+    ),
+  ).toEqual([
+    { kind: "ready", plan: V1 },
+    { kind: "ready", plan: V2 },
+  ]);
+});
+
+it('"none" is a gate decided: a census with nothing labelled, tested or dropped is ready', () => {
+  const p = {
+    ...V2,
+    mode: { ...DECIDED, we_lose_if: { result: "rate", above: 0.1 } },
+    second_check: "none",
+    self_test: "none",
+    funnel: "none",
+    recall_audit: "none",
+  };
+  // Guards: "not this study" has one spelling, and it is a decision, not a gap.
+  expect(parse(p)).toEqual({ kind: "ready", plan: p });
+});
+
+it("every gate still null keeps the plan a draft naming it", () => {
+  const p = {
+    ...V2,
+    mode: { ...DECIDED, we_lose_if: null },
+    second_check: null,
+    self_test: null,
+    funnel: null,
+    recall_audit: null,
+  };
+  // Guards: null is "not decided yet" — the study may not run on it.
+  expect(empty(p)).toEqual([
+    "mode.we_lose_if",
+    "second_check",
+    "self_test",
+    "funnel",
+    "recall_audit",
+  ]);
+});
+
+it("a plan v2 that leaves a gate out is no plan, the gate named", () => {
+  const noFunnel = { ...V2, funnel: undefined };
+  const modeWithout = DECIDED;
+  // Guards: a forgotten gate cannot be written — only "none" or null say "not this one".
+  expect(why(noFunnel)).toMatch(/^funnel: is missing, and a plan v2/u);
+  expect(why({ ...V2, recall_audit: undefined })).toMatch(
+    /^recall_audit: is missing, and a plan v2/u,
+  );
+  expect(why({ ...V2, mode: modeWithout })).toMatch(
+    /^mode\.we_lose_if: is missing/u,
+  );
+});
+
+it("a plan without $schema that carries a gate is refused: nobody would read it", () => {
+  // Guards: a v1 plan cannot half-declare the gates.
+  expect(why({ ...V1, funnel: "none" })).toBe(
+    `funnel: is a field of a plan v2 — add "$schema": "${PLAN_V2}"`,
+  );
+  expect(why({ ...V1, recall_audit: "none" })).toBe(
+    `recall_audit: is a field of a plan v2 — add "$schema": "${PLAN_V2}"`,
+  );
+});
+
+it("an exploratory mode cannot carry we_lose_if, and an exploratory plan v2 needs none", () => {
+  const exploratory = { kind: "exploratory", reason: "a first look" };
+  // Guards: no claim, no falsifier — the shape refuses one.
+  expect(why({ ...V2, mode: { ...exploratory, we_lose_if: null } })).toContain(
+    "we_lose_if",
+  );
+  expect(parse({ ...V2, mode: exploratory }).kind).toBe("ready");
+});
+
+it("each malformed gate is refused", () => {
+  const bad: readonly unknown[] = [
+    { ...V2, $schema: "https://example.com/plan.json" },
+    {
+      ...V2,
+      mode: { ...DECIDED, we_lose_if: { result: "x", below: 1, above: 2 } },
+    },
+    { ...V2, mode: { ...DECIDED, we_lose_if: { result: "x" } } },
+    { ...V2, second_check: [] },
+    { ...V2, second_check: [{ step: "a", min_kappa: 0 }] },
+    { ...V2, second_check: [{ step: "a", min_kappa: 1.2 }] },
+    {
+      ...V2,
+      second_check: [
+        { step: "a", min_kappa: 0.6 },
+        { step: "a", min_kappa: 0.7 },
+      ],
+    },
+    { ...V2, self_test: "n/a" },
+    { ...V2, self_test: { made_by: "../outside.mjs" } },
+    { ...V2, self_test: { must_catch: "bad.js" } },
+    { ...V2, funnel: [] },
+    { ...V2, funnel: ["clone failed", "clone failed"] },
+    { ...V2, recall_audit: "n/a" },
+    { ...V2, recall_audit: { n_files: 0, min_recall: 0.6 } },
+    { ...V2, recall_audit: { n_files: 2.5, min_recall: 0.6 } },
+    { ...V2, recall_audit: { n_files: 50, min_recall: 0 } },
+    { ...V2, recall_audit: { n_files: 50, min_recall: 1.2 } },
+    { ...V2, recall_audit: { n_files: 50 } },
+  ];
+  // Guards: each of these is refused — none parses to a plan.
+  expect(bad.map((p) => parse(p).kind)).toEqual(bad.map(() => "unreadable"));
+  expect(why(bad[6])).toContain("the step «a» is listed more than once");
+  expect(why(bad[11])).toContain("the reason «clone failed»");
+});
+
+it("the shipped schemas/plan.v2.schema.json is the one the parser generates", () => {
+  const shipped: unknown = JSON.parse(
+    readFileSync(
+      join(
+        dirname(fileURLToPath(import.meta.url)),
+        "../../../schemas/plan.v2.schema.json",
+      ),
+      "utf8",
+    ),
+  );
+  // Guards: an editor's suggestions for a plan v2 never drift from what the parser accepts.
+  expect(shipped).toEqual(planV2JsonSchema());
+});

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

@@ -44,6 +44,21 @@ import {
   type Decision,
   type StudyMode,
 } from "../../domain/study-mode.ts";
+import {
+  NONE,
+  PLAN_V2,
+  type Funnel,
+  type KappaStep,
+  type RecallAudit,
+  type SecondCheck,
+  type SelfTest,
+  type WeLoseIf,
+} from "../../domain/study-gates.ts";
+import {
+  CLAIM_LOST,
+  type ParsedResult,
+  type StudyResult,
+} from "../../domain/study-result.ts";
 import type { StudyRegistryCodec } from "../../ports/study-registry-codec.ts";
 
 const study = z.looseObject({
@@ -190,12 +205,81 @@ const decisionShape = z.strictObject({ file: inPaper, note: z.string() });
 /** The output globs: each once; none yet in a draft. */
 const outputs = z.array(inFolder).superRefine(once("the output"));
 
+// ── a plan v2's gates (src/domain/study-gates.ts) ───────────────────────────────────
+
+/** A threshold: a finite number. */
+const threshold = z.number().refine(Number.isFinite, "is not a finite number");
+
+/** When the claim loses: below a threshold or above one, exactly one of the two. */
+const weLoseIf = z.union([
+  z.strictObject({ result: words, below: threshold }),
+  z.strictObject({ result: words, above: threshold }),
+]);
+
+/** The literal that says "this study has none of it". */
+const none = z.literal(NONE);
+
+const kappaStep = z.strictObject({
+  step: words,
+  min_kappa: z
+    .number()
+    .gt(0, "is a kappa above 0")
+    .lte(1, "is a kappa of at most 1"),
+});
+
+/** The steps judged by two raters, each named once; or none. */
+const secondCheck = z.union([
+  none,
+  z
+    .array(kappaStep)
+    .min(1, 'lists no step — write "none" when nothing is labelled')
+    .superRefine((steps, ctx) => {
+      once("the step")(
+        steps.map((t) => t.step),
+        ctx,
+      );
+    }),
+]);
+
+/** A path inside the study's folder: a file or a folder. */
+const inStudyFolder = z
+  .string()
+  .min(1)
+  .refine(staysInside, "is not a path inside the study's folder");
+
+const selfTest = z.union([
+  none,
+  z.strictObject({ made_by: inStudyFolder }),
+  z.strictObject({ must_catch: inStudyFolder, must_pass: inStudyFolder }),
+]);
+
+const funnel = z.union([
+  none,
+  z
+    .array(words)
+    .min(1, 'lists no reason — write "none" when no unit is dropped')
+    .superRefine(once("the reason")),
+]);
+
+/** The audit of the extractor: files a person reads in full, and the least recall in (0, 1]. */
+const recallAudit = z.union([
+  none,
+  z.strictObject({
+    n_files: z.number().int().positive("is at least 1 file"),
+    min_recall: z
+      .number()
+      .gt(0, "is a recall above 0")
+      .lte(1, "is a recall of at most 1"),
+  }),
+]);
+
 /** How the outcomes are kept from the decisions: exactly one mode, by its `kind`. */
 const mode = z.discriminatedUnion("kind", [
   z.strictObject({
     kind: z.literal("decide_before_run"),
     outputs,
     decision: decisionShape,
+    we_lose_if: weLoseIf.nullable().optional(),
   }),
   z.strictObject({ kind: z.literal("exploratory"), reason: z.string() }),
 ]);
@@ -209,8 +293,68 @@ const planShape = z.strictObject({
   author_check: authorCheck.nullable(),
   extra: extra.optional(),
   mode: mode.optional(),
+  $schema: z.literal(PLAN_V2).optional(),
+  second_check: secondCheck.nullable().optional(),
+  self_test: selfTest.nullable().optional(),
+  funnel: funnel.nullable().optional(),
+  recall_audit: recallAudit.nullable().optional(),
 });
 
+/**
+ * The JSON Schema of a plan v2, generated from the parser's own shape: what an editor offers for a
+ * `plan.json` whose `$schema` names it. Shipped as `schemas/plan.v2.schema.json`; a test holds the
+ * file to this. The rules, not the schema, decide: a gate left out of a decide-first mode, or a
+ * draft, is theirs to report.
+ */
+export const planV2JsonSchema = (): unknown =>
+  z.toJSONSchema(
+    planShape.extend({
+      $schema: z.literal(PLAN_V2),
+      second_check: secondCheck.nullable(),
+      self_test: selfTest.nullable(),
+      funnel: funnel.nullable(),
+      recall_audit: recallAudit.nullable(),
+    }),
+    { io: "input", unrepresentable: "any" },
+  );
+
+/** The gates a plan v2 declares at its top, each present (null while undecided). */
+const V2_GATES = [
+  "second_check",
+  "self_test",
+  "funnel",
+  "recall_audit",
+] as const;
+
+/**
+ * A plan v2 declares every gate, and a decide-first mode its `we_lose_if`; a plan v1 declares none
+ * of them: a gate in a plan that does not say it is v2 would be read by nobody.
+ */
+const gatesOfItsVersion = (
+  p: Readonly<z.output<typeof planShape>>,
+  ctx: Readonly<z.core.$RefinementCtx>,
+): void => {
+  const v2 = p.$schema !== undefined;
+  const decided = p.mode?.kind === "decide_before_run" ? p.mode : undefined;
+  const gates = [
+    ...V2_GATES.map((g) => ({ path: [g], value: p[g] })),
+    ...(decided === undefined
+      ? []
+      : [{ path: ["mode", "we_lose_if"], value: decided.we_lose_if }]),
+  ];
+  gates
+    .filter((g) => (g.value === undefined) === v2)
+    .forEach((g) => {
+      ctx.addIssue({
+        code: "custom",
+        path: g.path,
+        message: v2
+          ? 'is missing, and a plan v2 declares it — "none" when the study has none of it, null until decided'
+          : `is a field of a plan v2 — add "$schema": "${PLAN_V2}"`,
+      });
+    });
+};
+
 /**
  * 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
@@ -291,6 +435,60 @@ const modeEmpties = (
   );
 };
 
+/** A count: a whole number, 0 or more. */
+const count = z.number().int().nonnegative();
+
+/**
+ * A study's `result.json` (src/domain/study-result.ts): open — the study's own numbers by any name —
+ * with the four parts the gates read, each of a fixed shape when present.
+ */
+const studyResult = z.looseObject({
+  claim: z.literal(CLAIM_LOST).optional(),
+  // Cohen's kappa lies in -1..1: a percentage (75) or a count is refused here, not compared with a bar.
+  kappa: z
+    .record(
+      z.string(),
+      z
+        .number()
+        .gte(-1, "is a kappa of at least -1")
+        .lte(1, "is a kappa of at most 1"),
+    )
+    .optional(),
+  self_test: z.strictObject({ passed: count, failed: count }).optional(),
+  funnel: z.record(z.string(), count).optional(),
+  // The counts of the audit, not a share: the files are checked against the plan, the recall computed.
+  recall_audit: z
+    .strictObject({
+      files: count,
+      units_in_files: z
+        .number()
+        .int()
+        .positive(
+          "is at least 1 unit — an audit that found none measures no recall",
+        ),
+      extracted: count,
+    })
+    .refine(
+      (c) => c.extracted <= c.units_in_files,
+      "counts more units extracted than the person found in the files",
+    )
+    .optional(),
+});
+
+/** A plan v2's gates still null, by their field: decided is anything but null. */
+const gateEmpties = (p: StudyPlan): readonly PlanTextField[] =>
+  PLAN_TEXT_FIELDS.filter(
+    (f) =>
+      (f === "mode.we_lose_if" &&
+        p.mode?.kind === "decide_before_run" &&
+        p.mode.we_lose_if === null) ||
+      ((f === "second_check" ||
+        f === "self_test" ||
+        f === "funnel" ||
+        f === "recall_audit") &&
+        p[f] === null),
+  );
+
 /** A plan that parsed: ready, or a draft. */
 type ReadyOrDraft = Exclude<ParsedPlan, { readonly kind: "unreadable" }>;
 
@@ -308,6 +506,7 @@ const readyOrDraft =
     const empty = [
       ...PLAN_TEXT_FIELDS.filter((f) => paths.includes(f)),
       ...modeEmpties(p, kind),
+      ...gateEmpties(p),
     ];
     if (empty.length === 0) return { kind: "ready", plan: p };
     if (p.author_check === null)
@@ -321,7 +520,8 @@ const readyOrDraft =
   };
 
 /** A `plan.json` of a study of `kind`: strict, then ready or draft — a measurement's ready only with its mode. */
-const planFor = (kind: StudyKind) => planShape.transform(readyOrDraft(kind));
+const planFor = (kind: StudyKind) =>
+  planShape.superRefine(gatesOfItsVersion).transform(readyOrDraft(kind));
 
 /**
  * A `prereg.json`: loose, mapped onto the plan, then ready or draft. Written before modes existed, it
@@ -368,6 +568,13 @@ export type SchemasAreTheDomain = [
   Same<z.output<typeof legacyPlan>, ReadyOrDraft>,
   Same<z.output<typeof mode>, StudyMode>,
   Same<z.output<typeof decisionShape>, Decision>,
+  Same<z.output<typeof weLoseIf>, WeLoseIf>,
+  Same<z.output<typeof kappaStep>, KappaStep>,
+  Same<z.output<typeof secondCheck>, SecondCheck>,
+  Same<z.output<typeof selfTest>, SelfTest>,
+  Same<z.output<typeof funnel>, Funnel>,
+  Same<z.output<typeof recallAudit>, RecallAudit>,
+  Same<z.output<typeof studyResult>, StudyResult>,
 ] extends true[]
   ? true
   : never;
@@ -427,8 +634,19 @@ export const parseStudyPlan = (text: string, kind: StudyKind): ParsedPlan =>
 /** A plan still named `prereg.json`: loose, read only when a row names it. */
 export const parseLegacyPlan = planParser(legacyPlan);
 
+/** A study's `result.json` text, parsed once at the boundary: the result, or every reason it is none. */
+export function parseStudyResult(text: string): ParsedResult {
+  const json = jsonOf(text);
+  if (json === undefined) return { kind: "unreadable", why: "not JSON" };
+  const parsed = studyResult.safeParse(json);
+  return parsed.success
+    ? { kind: "read", result: parsed.data }
+    : { kind: "unreadable", why: reasons(parsed.error.issues) };
+}
+
 export const studyRegistryCodec: StudyRegistryCodec = {
   parse: parseStudyRegistry,
   parsePlan: parseStudyPlan,
   parseLegacyPlan,
+  parseResult: parseStudyResult,
 };

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

@@ -76,6 +76,7 @@ it("the template of a measurement is a draft decided before its run, its decisio
     kind: "decide_before_run",
     outputs: [],
     decision: { file: "repro/P1-S02-x/decision.md", note: "" },
+    we_lose_if: null,
   });
   expect(empty(planText(t))).toEqual([
     "question",
@@ -84,6 +85,11 @@ it("the template of a measurement is a draft decided before its run, its decisio
     "primary_outcome",
     "mode.outputs",
     "mode.decision.note",
+    "mode.we_lose_if",
+    "second_check",
+    "self_test",
+    "funnel",
+    "recall_audit",
   ]);
   expect(planTemplate("spike", "P1-S03-y").mode).toBeUndefined();
 });

package/src/cli.ts

@@ -215,6 +215,7 @@ import {
   outputsBeforeDecisionRules,
 } from "./outputs-before-decision-rule.ts";
 import { runStudies } from "./studies.ts";
+import { RESULT_RULE_LEVELS, studyResultRules } from "./study-result-rule.ts";
 import typography from "#eslint-rules/paper-typography";
 import texBuild from "#eslint-rules/tex-build";
 import reviewFrontmatter from "#eslint-rules/review-frontmatter";
@@ -490,11 +491,13 @@ const REPRO_RULES = {
   ...reproLayoutRules(LAYOUT_RULE_DEPS),
   ...studyRegistryRules(STUDY_RULE_DEPS),
   ...outputsBeforeDecisionRules({ ...STUDY_RULE_DEPS, git: GIT }),
+  ...studyResultRules(STUDY_RULE_DEPS),
 };
 const REPRO_RULE_LEVELS = {
   ...REPRO_LAYOUT_RULE_LEVELS,
   ...STUDY_REGISTRY_RULE_LEVELS,
   ...ORDER_RULE_LEVELS,
+  ...RESULT_RULE_LEVELS,
 };
 
 /** Today in this machine's time zone, `YYYY-MM-DD`: the date `paperlint studies new` registers a study on. */

package/src/domain/decide-first.test.ts

@@ -5,11 +5,14 @@
  */
 import { expect, it } from "vitest";
 import {
+  firstOutputAfter,
   judgeOrder,
   orderMessage,
   type DecideFirstStudy,
   type OrderFinding,
+  type PlanThen,
 } from "./decide-first.ts";
+import type { PlanGates } from "./study-gates.ts";
 
 const D = { commit: "d".repeat(40), date: "2026-10-16T10:00:00+05:00" };
 const A = { commit: "a".repeat(40), date: "2026-10-16T11:00:00+05:00" };
@@ -289,3 +292,131 @@ it("each finding's message: what is wrong, what to do, the rule's page", () => {
       PAGE,
   ]);
 });
+
+// ── a plan v2's gates against the plan at the first output ──────────────────────────────────────
+
+const GATES: PlanGates = {
+  we_lose_if: { result: "share", below: 0.2 },
+  second_check: [{ step: "fits", min_kappa: 0.6 }],
+  self_test: "none",
+  funnel: ["no linter rule"],
+  recall_audit: "none",
+};
+const OUT = { path: "RESULTS.md", ...A, order: "after" as const };
+const withGates = (
+  then: PlanThen,
+  now: PlanGates = GATES,
+): DecideFirstStudy => ({
+  ...STUDY,
+  gates: { now, output: OUT, then },
+});
+
+it("the first output after the decision is the one the gates are held to; none while none followed it", () => {
+  // Guards: the study's own files and outputs not after the decision are not it.
+  expect([
+    firstOutputAfter(
+      STUDY,
+      STUDY.facts.kind === "read" ? STUDY.facts.files : [],
+    ),
+    firstOutputAfter(STUDY, [{ path: "RESULTS.md", ...D, order: "same" }]),
+  ]).toEqual([OUT, null]);
+});
+
+it("gates as they stood at the first output are silent; each one changed since is a finding", () => {
+  const moved: PlanGates = {
+    ...GATES,
+    we_lose_if: { result: "share", below: 0.1 },
+    funnel: ["no linter rule", "clone failed"],
+    recall_audit: { n_files: 50, min_recall: 0.5 },
+  };
+  const at = {
+    id: "P1-S01",
+    folder: "P1-S01-x",
+    plan: "plan.json",
+    output: OUT,
+  };
+  // Guards: deep equality, not identity; one finding per changed gate, in the gates' order.
+  expect([
+    judgeOrder(withGates({ kind: "gates", gates: structuredClone(GATES) })),
+    judgeOrder(withGates({ kind: "gates", gates: GATES }, moved)),
+  ]).toEqual([
+    [],
+    [
+      {
+        problem: "gates-changed",
+        ...at,
+        gate: "we_lose_if",
+        then: { result: "share", below: 0.2 },
+        now: { result: "share", below: 0.1 },
+      },
+      {
+        problem: "gates-changed",
+        ...at,
+        gate: "funnel",
+        then: ["no linter rule"],
+        now: ["no linter rule", "clone failed"],
+      },
+      {
+        problem: "gates-changed",
+        ...at,
+        gate: "recall_audit",
+        then: "none",
+        now: { n_files: 50, min_recall: 0.5 },
+      },
+    ],
+  ]);
+});
+
+it("no gates at the first output is a finding with its reason; a history git cannot read is said", () => {
+  const at = {
+    id: "P1-S01",
+    folder: "P1-S01-x",
+    plan: "plan.json",
+    output: OUT,
+  };
+  expect([
+    judgeOrder(withGates({ kind: "no-gates", why: "absent" })),
+    judgeOrder(withGates({ kind: "unknown", why: "fatal: x" })),
+  ]).toEqual([
+    [{ problem: "gates-not-fixed", ...at, why: "absent" }],
+    [{ problem: "no-history", id: "P1-S01", why: "fatal: x" }],
+  ]);
+});
+
+it("the gates' messages: which gate, then and now, the output's commit, and what to do", () => {
+  const at = {
+    id: "P1-S01",
+    folder: "P1-S01-x",
+    plan: "plan.json",
+    output: OUT,
+  };
+  const when = `\`RESULTS.md\`, entered history in ${"a".repeat(12)} (${A.date})`;
+  const fix =
+    "What to do: run the study again now that the plan v2 is committed; if the outputs must stand, declare the study `exploratory` with the reason.";
+  // Guards: the whole text for each finding and each reason.
+  expect(
+    [
+      {
+        problem: "gates-changed" as const,
+        ...at,
+        gate: "we_lose_if" as const,
+        then: { result: "share", below: 0.2 },
+        now: { result: "share", below: 0.1 },
+      },
+      ...(["absent", "v1", "unreadable"] as const).map((why) => ({
+        problem: "gates-not-fixed" as const,
+        ...at,
+        why,
+      })),
+    ].map(orderMessage),
+  ).toEqual([
+    `The gate \`we_lose_if\` in the plan of \`P1-S01\`, \`repro/P1-S01-x/plan.json\`, was {"result":"share","below":0.2} when its first output, ${when}, and is {"result":"share","below":0.1} now. A gate is fixed before the run: moved after a result exists, it can only follow the result. What to do: put the gate back as it was; if it was wrong, say so in the paper and run the study again under the corrected plan — never edit the history to make it pass.` +
+      PAGE,
+    `The plan of \`P1-S01\`, \`repro/P1-S01-x/plan.json\`, was not in history yet when its first output, ${when}: its gates were not fixed before the run. ${fix}` +
+      PAGE,
+    `The plan of \`P1-S01\`, \`repro/P1-S01-x/plan.json\`, was a plan v1, which declares no gates, when its first output, ${when}: its gates were not fixed before the run. ${fix}` +
+      PAGE,
+    `The plan of \`P1-S01\`, \`repro/P1-S01-x/plan.json\`, was no plan paperlint could read when its first output, ${when}: its gates were not fixed before the run. ${fix}` +
+      PAGE,
+  ]);
+});