paperlint 13.0.3 → 13.2.0

package/src/outputs-before-decision-rule.test.ts

@@ -15,8 +15,10 @@ import {
 } from "./adapters/node/index.ts";
 import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
 import type { StudyMode } from "./domain/study-mode.ts";
+import { PLAN_V2 } from "./domain/study-gates.ts";
 import { planText, registryText } from "./domain/study-registry.ts";
 import { outputsBeforeDecisionRules } from "./outputs-before-decision-rule.ts";
+import type { GitOrder } from "./ports/git-history.ts";
 import { commit, initRepo } from "../test/git-repo.ts";
 import { useTempDir } from "../test/support.ts";
 import { ROW, planOf } from "../test/study-tree.ts";
@@ -38,12 +40,18 @@ const T = (h: number): string =>
   `2026-10-16T${String(h).padStart(2, "0")}:00:00+05:00`;
 
 /** The rule's message ids over the paper in `repo`, reached through `file`. */
-const lint = (repo: string, file = "p/PIPELINE-STATUS.md"): string[] => {
+const lint = (
+  repo: string,
+  file = "p/PIPELINE-STATUS.md",
+  git: GitOrder = gitHistory(spawnProcess(), {
+    PATH: String(process.env.PATH),
+  }),
+): string[] => {
   const rule = outputsBeforeDecisionRules({
     files: nodeFiles,
     entries: nodeListEntries,
     codec: studyRegistryCodec,
-    git: gitHistory(spawnProcess(), { PATH: String(process.env.PATH) }),
+    git,
   })["outputs-before-decision"];
   const ids: string[] = [];
   rule
@@ -249,3 +257,108 @@ it("loud on a decision under a linked directory: git records the link, not the f
   // would be read from the link's history. The study is reported instead.
   expect(lint(repo)).toEqual(["decision-linked"]);
 });
+
+// ── a plan v2's gates are fixed before the first output ─────────────────────────────────────────
+
+/** A ready plan v2 of the decide-first study, losing below `below`, its question `question`. */
+const v2 = (below: number, question = "Does the hint help?"): string =>
+  planText({
+    ...planOf({ ...DECIDED, we_lose_if: { result: "share", below } }),
+    question,
+    $schema: PLAN_V2,
+    second_check: [{ step: "fits", min_kappa: 0.6 }],
+    self_test: "none",
+    funnel: ["no linter rule"],
+    recall_audit: "none",
+  });
+const V2_PAPER = { ...PAPER, [`${S}/plan.json`]: v2(0.2) };
+
+/** The decided history: the paper with its plan, then the decision, then an output. */
+const decidedRun = (
+  name: string,
+  first: Readonly<Record<string, string>> = V2_PAPER,
+): string => {
+  const repo = join(root, name);
+  initRepo(repo);
+  commit(repo, first, T(9));
+  commit(repo, { [`${S}/decision.md`]: "exclude run 7\n" }, T(10));
+  commit(repo, { [`${S}/RESULTS.md`]: "41 of 60\n" }, T(11));
+  return repo;
+};
+
+it("loud when a gate of a plan v2 changed after the first output: the threshold cannot follow the result", () => {
+  const repo = decidedRun("gate-moved");
+  commit(repo, { [`${S}/plan.json`]: v2(0.1) }, T(12));
+  expect(lint(repo)).toEqual(["gates-changed"]);
+});
+
+it("loud when the plan v2 entered history only after the first output: its gates were not fixed before it", () => {
+  const repo = decidedRun(
+    "gate-late",
+    Object.fromEntries(
+      Object.entries(V2_PAPER).filter(([k]) => k !== `${S}/plan.json`),
+    ),
+  );
+  commit(repo, { [`${S}/plan.json`]: v2(0.2) }, T(12));
+  expect(lint(repo)).toEqual(["gates-not-fixed"]);
+});
+
+it("silent when the gates stand as they were at the first output, even if other text of the plan changed", () => {
+  const same = decidedRun("gate-same");
+  const reworded = decidedRun("gate-reworded");
+  commit(
+    reworded,
+    { [`${S}/plan.json`]: v2(0.2, "Do the hints help?") },
+    T(12),
+  );
+  const v1 = decidedRun("gate-v1", PAPER);
+  commit(v1, { [`${S}/plan.json`]: planText(planOf(DECIDED)) + "\n" }, T(12));
+  // Guards: an unchanged plan; a non-gate edit; a plan v1, which has no gates to freeze.
+  expect([lint(same), lint(reworded), lint(v1)]).toEqual([[], [], []]);
+});
+
+it("loud when the plan at the first output was a v1 or no plan at all, and says why when git cannot show it", () => {
+  const v1 = decidedRun("gate-was-v1", PAPER);
+  commit(v1, { [`${S}/plan.json`]: v2(0.2) }, T(12));
+  const garbled = decidedRun("gate-was-garbled", {
+    ...V2_PAPER,
+    [`${S}/plan.json`]: "{ not json",
+  });
+  commit(garbled, { [`${S}/plan.json`]: v2(0.2) }, T(12));
+  const real = gitHistory(spawnProcess(), { PATH: String(process.env.PATH) });
+  const blind = {
+    ...real,
+    fileAt: () => ({ kind: "unknown", why: "git show failed" }) as const,
+  };
+  expect([
+    lint(v1),
+    lint(garbled),
+    lint(decidedRun("gate-blind"), undefined, blind),
+  ]).toEqual([["gates-not-fixed"], ["gates-not-fixed"], ["no-history"]]);
+});
+
+it("asks nothing of the gates while no output followed the decision, or no order could be read", () => {
+  const waiting = join(root, "gate-waiting");
+  initRepo(waiting);
+  commit(waiting, V2_PAPER, T(9));
+  commit(waiting, { [`${S}/decision.md`]: "exclude run 7\n" }, T(10));
+  const dir = "repro/P1-S01-outcome/decisions";
+  const unread = join(root, "gate-unread");
+  initRepo(unread);
+  commit(
+    unread,
+    {
+      ...V2_PAPER,
+      [`${S}/plan.json`]: v2(0.2).replace(
+        '"file": "repro/P1-S01-outcome/decision.md"',
+        `"file": "${dir}"`,
+      ),
+      [`p/${dir}/a.md`]: "exclude run 7\n",
+    },
+    T(9),
+  );
+  commit(unread, { [`${S}/RESULTS.md`]: "41 of 60\n" }, T(10));
+  // Guards: a plan v2 whose study has not run yet; one whose history yields no order is reported
+  // for that alone, never for gates it could not compare.
+  expect([lint(waiting), lint(unread)]).toEqual([[], ["decision-not-file"]]);
+});

package/src/outputs-before-decision-rule.ts

@@ -18,11 +18,16 @@ import { filter, map, pipe } from "remeda";
 import { callerPath } from "./caller-path.ts";
 import { decisionEntry, modeStudies, type ModeStudy } from "./study-modes.ts";
 import {
+  firstOutputAfter,
   judgeOrder,
   orderMessage,
   type DecideFirstStudy,
+  type GateHistory,
   type OrderFinding,
+  type PlanThen,
 } from "./domain/decide-first.ts";
+import { gatesOf, type PlanGates } from "./domain/study-gates.ts";
+import type { StudyKind } from "./domain/study-registry.ts";
 import { REPRO_DIR } from "./domain/repro-layout.ts";
 import type { DecideFirst } from "./domain/study-mode.ts";
 import type {
@@ -51,11 +56,11 @@ export const decideFirstStudies = (
   return pipe(
     modeStudies(registryOf(paper, deps), reader, deps.codec),
     filter(isDecidedAndReady),
-    map(({ row, plan, mode }): DecideFirstStudy => {
+    map(({ row, plan, mode, gates }): DecideFirstStudy => {
       const folder = join(paper, REPRO_DIR, row.folder);
       const decision = join(paper, mode.decision.file);
       const on = decisionEntry(reader, mode.decision.file);
-      return {
+      const study: DecideFirstStudy = {
         id: row.id,
         folder: row.folder,
         plan,
@@ -66,10 +71,51 @@ export const decideFirstStudies = (
             ? deps.git.order(callerPath(folder), callerPath(decision))
             : on,
       };
+      return {
+        ...study,
+        gates: gateHistory(study, { now: gates, kind: row.kind, folder }, deps),
+      };
     }),
   );
 };
 
+/**
+ * The gates of a plan v2 now, and the plan at the study's first output after its decision: none for
+ * a plan v1, a history not read, or a study with no such output yet.
+ */
+const gateHistory = (
+  s: DecideFirstStudy,
+  from: {
+    readonly now: PlanGates | null;
+    readonly kind: StudyKind;
+    readonly folder: string;
+  },
+  deps: OrderDeps,
+): GateHistory | undefined => {
+  if (from.now === null || s.facts.kind !== "read") return undefined;
+  const output = firstOutputAfter(s, s.facts.files);
+  if (output === null) return undefined;
+  const at = deps.git.fileAt(callerPath(from.folder), output.commit, s.plan);
+  return { now: from.now, output, then: planThen(at, from.kind, deps) };
+};
+
+/** What the plan held at that commit, by gates. */
+const planThen = (
+  at: ReturnType<OrderDeps["git"]["fileAt"]>,
+  kind: StudyKind,
+  deps: OrderDeps,
+): PlanThen => {
+  if (at.kind === "unknown") return at;
+  if (at.kind === "absent") return { kind: "no-gates", why: "absent" };
+  const parsed = deps.codec.parsePlan(at.text, kind);
+  if (parsed.kind === "unreadable")
+    return { kind: "no-gates", why: "unreadable" };
+  const gates = gatesOf(parsed.plan);
+  return gates === null
+    ? { kind: "no-gates", why: "v1" }
+    : { kind: "gates", gates };
+};
+
 /** Only a ready plan decides: a draft may name no outputs, or an empty decision file. */
 const isDecidedAndReady = (
   s: ModeStudy,
@@ -85,6 +131,8 @@ const PROBLEMS: readonly OrderFinding["problem"][] = [
   "shallow",
   "undecided-output",
   "output-before-decision",
+  "gates-changed",
+  "gates-not-fixed",
 ];
 
 const NAME = "repro/outputs-before-decision";

package/src/ports/git-history.ts

@@ -35,10 +35,22 @@ export interface GitHistory {
   readonly committed: (paper: AbsolutePath, file: AbsolutePath) => Committed;
 }
 
+/** A file as it stood at a commit: its text, not there, or why git could not say. */
+export type FileAt =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "absent" }
+  | { readonly kind: "unknown"; readonly why: string };
+
 export interface GitOrder {
   /** The order of `decision`'s first commit against every file's under `studyDir` (a folder that exists). */
   readonly order: (
     studyDir: AbsolutePath,
     decision: AbsolutePath,
   ) => OrderFacts;
+  /** `path` (relative to `studyDir`) as it stood at `commit`: what a plan's gates were at the first output. */
+  readonly fileAt: (
+    studyDir: AbsolutePath,
+    commit: string,
+    path: string,
+  ) => FileAt;
 }

package/src/ports/study-registry-codec.ts

@@ -8,6 +8,7 @@ import type {
   ParsedRegistry,
   StudyKind,
 } from "../domain/study-registry.ts";
+import type { ParsedResult } from "../domain/study-result.ts";
 
 export interface StudyRegistryCodec {
   /** A `studies.json`'s text: the registry, or the one reason it is not one of this schema. */
@@ -19,4 +20,6 @@ export interface StudyRegistryCodec {
   readonly parsePlan: (text: string, kind: StudyKind) => ParsedPlan;
   /** A plan still named `prereg.json`, loose: the same three outcomes. */
   readonly parseLegacyPlan: (text: string) => ParsedPlan;
+  /** A study's `result.json`: its numbers, or why it is none (src/domain/study-result.ts). */
+  readonly parseResult: (text: string) => ParsedResult;
 }

package/src/rule-cases.test.ts

@@ -19,6 +19,7 @@ import { run, rulePlugins } from "./cli.ts";
 import { sha256Hex } from "./domain/sha256.ts";
 import { lockText, type LockEntry } from "./domain/versions.ts";
 import type { StudyMode } from "./domain/study-mode.ts";
+import { PLAN_V2 } from "./domain/study-gates.ts";
 import {
   planTemplate,
   planText,
@@ -127,6 +128,54 @@ const STUDY_IN_MODE = (
   };
 };
 
+/**
+ * The registered study, done on a ready plan v2 — its claim lost below 0.5, kappa 0.6 on one step, a
+ * self-test, one drop reason — with `result` as its `result.json` (none when null).
+ */
+const DONE_ON_PLAN_V2 = (
+  result: Readonly<Record<string, unknown>> | null,
+): Readonly<Record<string, string>> => {
+  const r: StudyRegistry = {
+    ...REGISTRY,
+    studies: REGISTRY.studies.map((s) => ({
+      ...s,
+      status: "done",
+      result: "0.7 pass",
+      result_file: "README.md",
+      plan: "plan.json",
+    })),
+  };
+  const plan: StudyPlan = {
+    $schema: PLAN_V2,
+    question: "Which step does the work?",
+    population: { source: "tasks", draw: { kind: "all", method: "census" } },
+    arms: [],
+    primary_outcome: "pass rate",
+    author_check: null,
+    mode: {
+      kind: "exploratory",
+      reason: "the rule judges the result, not the order",
+    },
+    second_check: [{ step: "pass", min_kappa: 0.6 }],
+    self_test: { made_by: "selftest.mjs" },
+    funnel: ["timed out"],
+    recall_audit: "none",
+  };
+  const facts: IndexInput = {
+    plans: new Map([["P1-S01-ablation/plan.json", { kind: "ready", plan }]]),
+    history: new Map(),
+  };
+  return {
+    [`${P}/repro/studies.json`]: registryText(r),
+    [`${P}/repro/README.md`]: withIndex("# repro\n", r, facts),
+    [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
+    [`${P}/repro/P1-S01-ablation/plan.json`]: planText(plan),
+    ...(result === null
+      ? {}
+      : { [`${P}/repro/P1-S01-ablation/result.json`]: JSON.stringify(result) }),
+  };
+};
+
 /** `study/declare-sample` is off by default; a paper turns it on in its `paperlint.json`. */
 const DECLARE_SAMPLE_ON: Readonly<Record<string, string>> = {
   [`${P}/paperlint.json`]: JSON.stringify({
@@ -992,6 +1041,31 @@ const CASES: Readonly<Record<string, RuleCases>> = {
       ),
     ),
   },
+  // A done study on a plan v2 whose result.json counts no drop for its declared funnel reason.
+  "repro/study-result": {
+    reports: {
+      tree: paper(
+        tex("x"),
+        DONE_ON_PLAN_V2({
+          kappa: { pass: 0.71 },
+          self_test: { passed: 4, failed: 0 },
+          funnel: {},
+        }),
+      ),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same study, every gate shown in its result.json.
+    silent: paper(
+      tex("x"),
+      DONE_ON_PLAN_V2({
+        kappa: { pass: 0.71 },
+        self_test: { passed: 4, failed: 0 },
+        funnel: { "timed out": 2 },
+      }),
+    ),
+  },
   // A study's plan still named prereg.json: read as its plan, and a warning to rename it.
   "repro/study-plan-name": {
     reports: {

package/src/studies.test.ts

@@ -93,6 +93,9 @@ function studies(
           decisionDeleted: false,
           files: [],
         }),
+        fileAt: () => {
+          throw new Error("new and index never read a file at a commit");
+        },
       },
       log: (l) => log.push(l),
       err: (l) => err.push(l),

package/src/study-modes.ts

@@ -7,6 +7,7 @@
 import { posix } from "node:path";
 import { filter, map, pipe } from "remeda";
 import type { NotAFile } from "./domain/decide-first.ts";
+import { gatesOf, type PlanGates } from "./domain/study-gates.ts";
 import type { StudyMode } from "./domain/study-mode.ts";
 import {
   studiesOf,
@@ -52,6 +53,8 @@ export interface ModeStudy {
   readonly plan: string;
   readonly mode: StudyMode;
   readonly empty: readonly PlanTextField[];
+  /** A plan v2's gates as HEAD holds them; null for a plan v1. */
+  readonly gates: PlanGates | null;
 }
 
 /** What reading the plan of one row gave: its mode study, nothing, or a link on the way to it. */
@@ -81,7 +84,13 @@ export const readModeStudy = (
   const empty = parsed.kind === "draft" ? parsed.empty : [];
   return {
     kind: "mode",
-    study: { row: s, plan, mode: parsed.plan.mode, empty },
+    study: {
+      row: s,
+      plan,
+      mode: parsed.plan.mode,
+      empty,
+      gates: gatesOf(parsed.plan),
+    },
   };
 };
 

package/src/study-registry-rule.ts

@@ -190,6 +190,7 @@ const PROBLEMS: readonly StudyFinding["problem"][] = [
   "unknown-requirement",
   "headline-approval",
   "bad-plan",
+  "plan-version",
   "author-check",
 ];