paperlint 10.0.0 → 10.1.0

package/CONTRIBUTING.md

@@ -132,13 +132,25 @@ site without `npx eslint . --prune-suppressions` fails lint, and #134 burns the
 New code is TypeScript (#78). The last block of [`eslint.config.mjs`](eslint.config.mjs) makes any
 `.js`, `.mjs` or `.cjs` file an error in the directories already converted (`TYPESCRIPT_ONLY`), so
 `npm run lint` fails on one; a directory that still mixes the two is not listed yet, and the change
-that converts it adds it. Code that only this repository runs (tests, `scripts/`, `test/e2e/`) is
+that converts it adds it. Everywhere else, a NEW `.js`, `.mjs` or `.cjs` file fails `local/js-needs-reason`
+unless its top comment says `JavaScript, not TypeScript: evidence|fixture|config-loader — <why>`;
+the files that predate the rule are bulk suppressions in `eslint-suppressions.json`, which only
+shrinks. Code that only this repository runs (tests, `scripts/`, `test/e2e/`) is
 run by `node` directly; code a consumer runs from `node_modules` needs a build first, because Node
 does not strip types there.
 
-`npm run build` is one `tsc` over two projects into one `dist/`: `tsconfig.json` builds `src/` to
-`dist/*.js`, and `tsconfig.pkg.json` builds `lib/` and `eslint-rules/` to `dist/lib/` and
-`dist/eslint-rules/`. Everything else imports those two through the package's subpath imports,
+`npm run build` is `tsc -b`: TypeScript's build mode over the project references in the root
+`tsconfig.json`, which is a solution file and compiles nothing itself. The three projects share
+`tsconfig.base.json`: `tsconfig.pkg.json` builds `lib/` and `eslint-rules/` to `dist/lib/` and
+`dist/eslint-rules/`; `tsconfig.src.json` builds `src/` to `dist/*.js` and references the first,
+whose declarations it reads; `tsconfig.skills.json` compiles a skill's scripts
+(`skills/*/scripts/*.ts`) to a `.js` BESIDE each, gitignored and shipped through `files` (their
+declarations go to `dist/skills/`): a skill names its script as `${CLAUDE_SKILL_DIR}/scripts/<name>.js`,
+and only a path inside the skill's own directory resolves the same through the consumer's
+`.claude/skills/<name>` link and in this checkout. A second `tsc -b` with nothing changed is a no-op;
+it decides that from `dist/.tsbuildinfo/`, so an output deleted by hand is rebuilt only by
+`npx tsc -b --force` (or by deleting `dist/` with it). `tsconfig.test.json` is not part of the build:
+it type-checks every `.ts` without emitting. Everything else imports `lib/` and `eslint-rules/` through the package's subpath imports,
 `#lib/<name>` and `#eslint-rules/<name>` (`"imports"` in `package.json`): the default target is the
 build, which is what an install runs; the `paperlint-source` condition points at the `.ts` instead,
 and `npm test` (so `npm run coverage` and `npm run check` too) and `tsconfig.test.json` set it so

package/dist/eslint-rules/js-needs-reason.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `local/js-needs-reason` — a NEW JavaScript file says, at its top, why it is not TypeScript.
+ *
+ * New code is TypeScript (#78). `TYPESCRIPT_ONLY` in `eslint.config.mjs` holds that for the
+ * directories already converted; everywhere else a new `.mjs` arrived whenever its neighbours were
+ * `.mjs`, which is not a reason. This rule closes the rest: a `.js`, `.mjs` or `.cjs` file that is
+ * not in the grandfathered list must open with a comment naming one of the accepted reasons:
+ *
+ *   // JavaScript, not TypeScript: evidence — <why>       kept byte for byte as it ran
+ *   // JavaScript, not TypeScript: fixture — <why>        checked AS JavaScript by a test
+ *   // JavaScript, not TypeScript: config-loader — <why>  read by a loader that cannot read TS
+ *
+ * "Smaller", "faster" and "the neighbours are .mjs" are not on the list. Code a consumer runs from
+ * `node_modules` is TypeScript too, compiled (`tsconfig.skills.json`, `tsconfig.pkg.json`).
+ *
+ * The rule reports EVERY JavaScript file without a reason; it keeps no list of its own. The files
+ * that existed when it arrived are ESLint bulk suppressions in `eslint-suppressions.json`, which
+ * only shrinks: a suppression that no longer matches fails `eslint .` until
+ * `--prune-suppressions` removes it. Not "added since the base branch": a rule may not run git
+ * (`GIT_IN_A_RULE` in the config — a shallow CI checkout has no base).
+ */
+import type { Program } from "estree";
+import type { RuleContext } from "./rule-context.ts";
+interface Comment {
+    readonly type: string;
+    readonly value: string;
+    readonly range: readonly [number, number];
+}
+/** What this rule reads beyond the shared slice: the comments. */
+type Context = RuleContext & {
+    readonly sourceCode: {
+        getAllComments(): readonly Comment[];
+    };
+};
+declare const _default: {
+    rules: {
+        "js-needs-reason": {
+            meta: {
+                type: "problem";
+                docs: {
+                    description: string;
+                };
+                schema: never[];
+                messages: {
+                    noReason: string;
+                };
+            };
+            create(context: Context): {
+                Program(node: Readonly<Program>): void;
+            };
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=js-needs-reason.d.ts.map

package/dist/eslint-rules/js-needs-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"js-needs-reason.d.ts","sourceRoot":"","sources":["../../eslint-rules/js-needs-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD,UAAU,OAAO;IACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,kEAAkE;AAClE,KAAK,OAAO,GAAG,WAAW,GAAG;IAC3B,QAAQ,CAAC,UAAU,EAAE;QAAE,cAAc,IAAI,SAAS,OAAO,EAAE,CAAA;KAAE,CAAC;CAC/D,CAAC;;;;;;;;;;;;;;4BA2BoB,OAAO;8BAEL,QAAQ,CAAC,OAAO,CAAC;;;;;AApBzC,wBA8BE"}

package/dist/eslint-rules/js-needs-reason.js

@@ -0,0 +1,35 @@
+/** The comment that excuses a JavaScript file, and the reasons it may give. */
+const REASON = /JavaScript, not TypeScript: (?:evidence|fixture|config-loader)\b/;
+/** Does a comment that names an accepted reason come before the first statement? */
+const excused = (comments, codeStart) => comments.some((c) => c.type !== "Shebang" && c.range[0] < codeStart && REASON.test(c.value));
+export default {
+    rules: {
+        "js-needs-reason": {
+            meta: {
+                type: "problem",
+                docs: {
+                    description: "a JavaScript file names why it is not TypeScript at its top",
+                },
+                schema: [],
+                messages: {
+                    noReason: "New code is TypeScript (#78): write this file as .ts, or open it with " +
+                        "`// JavaScript, not TypeScript: evidence|fixture|config-loader — <why>` " +
+                        "(evidence kept exactly as it ran; a fixture checked as JavaScript; a config a loader " +
+                        "that cannot read TypeScript reads).",
+                },
+            },
+            create(context) {
+                return {
+                    Program(node) {
+                        const starts = node.body.map((s) => Number(s.range?.[0]));
+                        const codeStart = Math.min(Infinity, ...starts);
+                        if (excused(context.sourceCode.getAllComments(), codeStart))
+                            return;
+                        context.report({ node, messageId: "noReason" });
+                    },
+                };
+            },
+        },
+    },
+};
+//# sourceMappingURL=js-needs-reason.js.map

package/dist/eslint-rules/js-needs-reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"js-needs-reason.js","sourceRoot":"","sources":["../../eslint-rules/js-needs-reason.ts"],"names":[],"mappings":"AAwBA,+EAA+E;AAC/E,MAAM,MAAM,GACV,kEAAkE,CAAC;AAarE,oFAAoF;AACpF,MAAM,OAAO,GAAG,CAAC,QAA4B,EAAE,SAAiB,EAAW,EAAE,CAC3E,QAAQ,CAAC,IAAI,CACX,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CACzE,CAAC;AAEJ,eAAe;IACb,KAAK,EAAE;QACL,iBAAiB,EAAE;YACjB,IAAI,EAAE;gBACJ,IAAI,EAAE,SAAkB;gBACxB,IAAI,EAAE;oBACJ,WAAW,EACT,6DAA6D;iBAChE;gBACD,MAAM,EAAE,EAAE;gBACV,QAAQ,EAAE;oBACR,QAAQ,EACN,wEAAwE;wBACxE,0EAA0E;wBAC1E,uFAAuF;wBACvF,qCAAqC;iBACxC;aACF;YACD,MAAM,CAAC,OAAgB;gBACrB,OAAO;oBACL,OAAO,CAAC,IAAuB;wBAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,CAAC;wBAChD,IAAI,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,cAAc,EAAE,EAAE,SAAS,CAAC;4BAAE,OAAO;wBACpE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;oBAClD,CAAC;iBACF,CAAC;YACJ,CAAC;SACF;KACF;CACF,CAAC"}

package/dist/package-dirs.d.ts

@@ -1,5 +1,11 @@
 /** The shipped venue presets and `venue-profile.schema.json`. */
 export declare const presetsDir: () => string;
+/**
+ * This checkout's own Claude Code directory, `.claude/` at the package root: the links to the
+ * skills that Claude Code loads while working on this repository. For the harnesses, which run
+ * only here; an install has no such directory.
+ */
+export declare const claudeDir: () => string;
 /** The LaTeX inputs a paper `\input`s by name (`paper-guards`, a venue's numbers). */
 export declare const texInputsDir: () => string;
 /** Where an `\input` in the paper in `paperDir` is looked for, first to last. */

package/dist/package-dirs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-dirs.d.ts","sourceRoot":"","sources":["../src/package-dirs.ts"],"names":[],"mappings":"AAcA,iEAAiE;AACjE,eAAO,MAAM,UAAU,QAAO,MACyB,CAAC;AAExD,sFAAsF;AACtF,eAAO,MAAM,YAAY,QAAO,MAC2B,CAAC;AAE5D,iFAAiF;AACjF,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,KAAG,SAAS,MAAM,EAG/D,CAAC"}
+{"version":3,"file":"package-dirs.d.ts","sourceRoot":"","sources":["../src/package-dirs.ts"],"names":[],"mappings":"AAcA,iEAAiE;AACjE,eAAO,MAAM,UAAU,QAAO,MACyB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAO,MAC0B,CAAC;AAExD,sFAAsF;AACtF,eAAO,MAAM,YAAY,QAAO,MAC2B,CAAC;AAE5D,iFAAiF;AACjF,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,KAAG,SAAS,MAAM,EAG/D,CAAC"}

package/dist/package-dirs.js

@@ -13,6 +13,12 @@
 import { fileURLToPath } from "node:url";
 /** The shipped venue presets and `venue-profile.schema.json`. */
 export const presetsDir = () => fileURLToPath(new URL("../presets", import.meta.url));
+/**
+ * This checkout's own Claude Code directory, `.claude/` at the package root: the links to the
+ * skills that Claude Code loads while working on this repository. For the harnesses, which run
+ * only here; an install has no such directory.
+ */
+export const claudeDir = () => fileURLToPath(new URL("../.claude", import.meta.url));
 /** The LaTeX inputs a paper `\input`s by name (`paper-guards`, a venue's numbers). */
 export const texInputsDir = () => fileURLToPath(new URL("../presets/tex", import.meta.url));
 /** Where an `\input` in the paper in `paperDir` is looked for, first to last. */

package/dist/package-dirs.js.map

@@ -1 +1 @@
-{"version":3,"file":"package-dirs.js","sourceRoot":"","sources":["../src/package-dirs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iEAAiE;AACjE,MAAM,CAAC,MAAM,UAAU,GAAG,GAAW,EAAE,CACrC,aAAa,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAExD,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAW,EAAE,CACvC,aAAa,CAAC,IAAI,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE5D,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAgB,EAAqB,EAAE,CAAC;IACpE,QAAQ;IACR,YAAY,EAAE;CACf,CAAC"}
+{"version":3,"file":"package-dirs.js","sourceRoot":"","sources":["../src/package-dirs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iEAAiE;AACjE,MAAM,CAAC,MAAM,UAAU,GAAG,GAAW,EAAE,CACrC,aAAa,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAW,EAAE,CACpC,aAAa,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAExD,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAW,EAAE,CACvC,aAAa,CAAC,IAAI,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE5D,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAgB,EAAqB,EAAE,CAAC;IACpE,QAAQ;IACR,YAAY,EAAE;CACf,CAAC"}

package/dist/skills/label-agent-runs/scripts/labels-commands.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The subcommands of `labels`, by name. One table, read twice: the dispatcher in `labels.ts`
+ * compares against these, and `SKILL.md.spec.ts` interpolates them into every command it
+ * instructs (a name that is not here is a type error there). So the skill cannot instruct a
+ * subcommand the script does not have.
+ *
+ * A module of its own, with no side effects: the spec imports it at compile time, and importing
+ * `labels.ts` itself would run the command line.
+ */
+export declare const COMMANDS: {
+    readonly validate: "validate";
+    readonly agree: "agree";
+};

package/dist/skills/label-agent-runs/scripts/labels.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/skills/run-agent-grid/scripts/grid-guard-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The subcommands of `grid-guard`, by name. One table, read twice: the dispatcher in
+ * `grid-guard.ts` is keyed by these names (a missing or extra entry is a type error there), and
+ * `SKILL.md.spec.ts` interpolates them into every command it instructs (a name that is not here
+ * is a type error there). So the skill cannot instruct a subcommand the script does not have.
+ *
+ * A module of its own, with no side effects: the spec imports it at compile time, and importing
+ * `grid-guard.ts` itself would run the command line.
+ */
+export declare const COMMANDS: {
+    readonly lock: "lock";
+    readonly release: "release";
+    readonly gate: "gate";
+    readonly overlap: "overlap";
+    readonly envProbe: "env-probe";
+    readonly scanKeys: "scan-keys";
+    readonly precommit: "precommit";
+};
+/** A subcommand's name as typed on the command line. */
+export type CommandName = (typeof COMMANDS)[keyof typeof COMMANDS];

package/dist/skills/run-agent-grid/scripts/grid-guard.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/docs/skills.md

@@ -41,6 +41,8 @@ Where each stage writes, and the check that guards each place: [`layout.md`](lay
 | you get                                                                                    | skill              |
 | ------------------------------------------------------------------------------------------ | ------------------ |
 | a study design with honest statistics, and a reproduction artifact that checks its numbers | `build-benchmark`  |
+| the grid of agent runs executed: gated on an approved registry, locked, resumable, audited | `run-agent-grid`   |
+| the outcome of every agent run labelled: codebook first, hand labels, a blind second rater | `label-agent-runs` |
 | a page you label items on from a phone, and the answers exported into the study folder     | `build-label-page` |
 
 ## 4 · Draft

package/docs/testing.md

@@ -61,6 +61,19 @@ When in doubt between unit and integration: if the function takes a port (`Files
 - **Skills are tested through vigiles**, not a bespoke runner: a home-grown runner here once printed
   byte-identical "clean" verdicts for three skills that had never loaded.
 
+## Paid — a skill's trigger eval, `skills/<name>/<name>.eval.ts`
+
+- **Answers:** does the skill's description fire on its own requests, and stay quiet on a
+  sibling's? A real model reads every installed description, so it costs money and is not CI.
+- **Lives:** beside the skill, one file. It default-exports
+  `defineEval({ measureTriggerRate: { name, skillsDir, prompts, irrelevantPrompts, fired, … } })`
+  from vigiles, with the prompts inline; a sibling's own requests may be imported from the
+  sibling's eval file. `vigiles eval <file>` discovers and runs it; nothing runs at import.
+- **The old shape is frozen:** older skills still read their prompts from the shared table in
+  `lib/skill-trigger-cases.mjs` through `lib/skill-eval-kit.mjs`. `lib/skill-trigger-cases.test.ts`
+  fails on a new row there, and on a skill that is in both places; the table goes away in #218.
+- **Example:** `skills/run-agent-grid/run-agent-grid.eval.ts`.
+
 ## End-to-end — `test/e2e/<area>/*.e2e.ts`
 
 - **Answers:** does the package work once it is somewhere else? The tarball installed into another

package/eslint-rules/js-needs-reason.test.ts

@@ -0,0 +1,141 @@
+/**
+ * `local/js-needs-reason`: both halves on planted files, through ESLint's own `Linter`, then the
+ * real configuration on a planted new file, then an existing file through the repository's bulk
+ * suppressions (`eslint-suppressions.json`), with and without them.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { ESLint, Linter } from "eslint";
+import { test } from "vitest";
+import { z } from "zod";
+import { useTempDir, writeTree } from "../test/support.ts";
+import rules from "./js-needs-reason.ts";
+
+const ROOT = join(import.meta.dirname, "..");
+
+/** The module as ESLint's `Plugin` type: its rules are typed against `rule-context.ts`, not ESLint's. */
+const isPlugin = (p: unknown): p is ESLint.Plugin =>
+  typeof p === "object" && p !== null && "rules" in p;
+const plugin: ESLint.Plugin = isPlugin(rules)
+  ? rules
+  : assert.fail("js-needs-reason.ts does not export a plugin");
+const MESSAGE =
+  "New code is TypeScript (#78): write this file as .ts, or open it with " +
+  "`// JavaScript, not TypeScript: evidence|fixture|config-loader — <why>` " +
+  "(evidence kept exactly as it ran; a fixture checked as JavaScript; a config a loader " +
+  "that cannot read TypeScript reads).";
+
+/** The rule's messages for `code` as the file `rel`. */
+const lint = (rel: string, code: string) =>
+  new Linter({ cwd: ROOT })
+    .verify(
+      code,
+      [
+        {
+          files: ["**/*.{js,mjs,cjs}"],
+          plugins: { local: plugin },
+          rules: {
+            "local/js-needs-reason": "error",
+          },
+        },
+      ],
+      { filename: join(ROOT, rel) },
+    )
+    .map((m) => ({ rule: m.ruleId, line: m.line, message: m.message }));
+const FIRES = [{ rule: "local/js-needs-reason", line: 1, message: MESSAGE }];
+
+test("a new .mjs without a reason fails; .js and .cjs too", () => {
+  assert.deepEqual(lint("scripts/new.mjs", "export const x = 1;\n"), FIRES);
+  assert.deepEqual(lint("scripts/new.js", "export const x = 1;\n"), FIRES);
+  assert.deepEqual(lint("scripts/new.cjs", "module.exports = 1;\n"), FIRES);
+  // An empty file has no statement to come before, and still names no reason.
+  assert.deepEqual(lint("scripts/empty.mjs", ""), FIRES);
+});
+
+test("a new file that names an accepted reason at its top passes", () => {
+  for (const reason of ["evidence", "fixture", "config-loader"])
+    assert.deepEqual(
+      lint(
+        "scripts/new.mjs",
+        `// JavaScript, not TypeScript: ${reason} — why\nexport const x = 1;\n`,
+      ),
+      [],
+    );
+  assert.deepEqual(
+    lint(
+      "bin/new.mjs",
+      "#!/usr/bin/env node\n/**\n * JavaScript, not TypeScript: evidence — kept as it ran.\n */\nexport const x = 1;\n",
+    ),
+    [],
+  );
+});
+
+test("a reason that is not on the list, or that comes after the code, fails", () => {
+  assert.deepEqual(
+    lint(
+      "scripts/new.mjs",
+      "// JavaScript, not TypeScript: smaller — fewer bytes\nexport const x = 1;\n",
+    ),
+    FIRES,
+  );
+  assert.deepEqual(
+    lint(
+      "scripts/new.mjs",
+      "export const x = 1;\n// JavaScript, not TypeScript: fixture — late\n",
+    ),
+    FIRES,
+  );
+});
+
+/** The repository's own `eslint` CLI on one file: exit code and this rule's findings. */
+function cli(
+  file: string,
+  extra: readonly string[] = [],
+): { status: number | null; findings: number } {
+  const r = spawnSync(
+    process.execPath,
+    [
+      join(ROOT, "node_modules", "eslint", "bin", "eslint.js"),
+      "--format",
+      "json",
+      ...extra,
+      file,
+    ],
+    { cwd: ROOT, encoding: "utf8" },
+  );
+  const findings = z
+    .array(
+      z.object({
+        messages: z.array(z.object({ ruleId: z.string().nullable() })),
+      }),
+    )
+    .parse(JSON.parse(r.stdout))
+    .flatMap((f) => f.messages)
+    .filter((m) => m.ruleId === "local/js-needs-reason").length;
+  return { status: r.status, findings };
+}
+const WORK = useTempDir("js-needs-reason-");
+
+test("an existing JavaScript file is suppressed by eslint-suppressions.json, and only by it", () => {
+  const old = join(ROOT, "scripts", "rules-see-files.mjs");
+  assert.deepEqual(cli(old), { status: 0, findings: 0 });
+  const none = writeTree(WORK, { "none.json": "{}\n" });
+  assert.deepEqual(
+    cli(old, ["--suppressions-location", join(none, "none.json")]),
+    { status: 1, findings: 1 },
+  );
+}, 120_000);
+
+test("the repository's configuration runs the rule on a new file", async () => {
+  const eslint = new ESLint({ cwd: ROOT });
+  const found = (
+    await eslint.lintText("export const x = 1;\n", {
+      filePath: join(ROOT, "scripts", "planted-new-file.mjs"),
+    })
+  ).flatMap((r) => r.messages.map((m) => m.ruleId));
+  assert.deepEqual(
+    found.filter((id) => id === "local/js-needs-reason"),
+    ["local/js-needs-reason"],
+  );
+}, 120_000);

package/eslint-rules/js-needs-reason.ts

@@ -0,0 +1,77 @@
+/**
+ * `local/js-needs-reason` — a NEW JavaScript file says, at its top, why it is not TypeScript.
+ *
+ * New code is TypeScript (#78). `TYPESCRIPT_ONLY` in `eslint.config.mjs` holds that for the
+ * directories already converted; everywhere else a new `.mjs` arrived whenever its neighbours were
+ * `.mjs`, which is not a reason. This rule closes the rest: a `.js`, `.mjs` or `.cjs` file that is
+ * not in the grandfathered list must open with a comment naming one of the accepted reasons:
+ *
+ *   // JavaScript, not TypeScript: evidence — <why>       kept byte for byte as it ran
+ *   // JavaScript, not TypeScript: fixture — <why>        checked AS JavaScript by a test
+ *   // JavaScript, not TypeScript: config-loader — <why>  read by a loader that cannot read TS
+ *
+ * "Smaller", "faster" and "the neighbours are .mjs" are not on the list. Code a consumer runs from
+ * `node_modules` is TypeScript too, compiled (`tsconfig.skills.json`, `tsconfig.pkg.json`).
+ *
+ * The rule reports EVERY JavaScript file without a reason; it keeps no list of its own. The files
+ * that existed when it arrived are ESLint bulk suppressions in `eslint-suppressions.json`, which
+ * only shrinks: a suppression that no longer matches fails `eslint .` until
+ * `--prune-suppressions` removes it. Not "added since the base branch": a rule may not run git
+ * (`GIT_IN_A_RULE` in the config — a shallow CI checkout has no base).
+ */
+import type { Program } from "estree";
+import type { RuleContext } from "./rule-context.ts";
+
+/** The comment that excuses a JavaScript file, and the reasons it may give. */
+const REASON =
+  /JavaScript, not TypeScript: (?:evidence|fixture|config-loader)\b/;
+
+interface Comment {
+  readonly type: string;
+  readonly value: string;
+  readonly range: readonly [number, number];
+}
+
+/** What this rule reads beyond the shared slice: the comments. */
+type Context = RuleContext & {
+  readonly sourceCode: { getAllComments(): readonly Comment[] };
+};
+
+/** Does a comment that names an accepted reason come before the first statement? */
+const excused = (comments: readonly Comment[], codeStart: number): boolean =>
+  comments.some(
+    (c) =>
+      c.type !== "Shebang" && c.range[0] < codeStart && REASON.test(c.value),
+  );
+
+export default {
+  rules: {
+    "js-needs-reason": {
+      meta: {
+        type: "problem" as const,
+        docs: {
+          description:
+            "a JavaScript file names why it is not TypeScript at its top",
+        },
+        schema: [],
+        messages: {
+          noReason:
+            "New code is TypeScript (#78): write this file as .ts, or open it with " +
+            "`// JavaScript, not TypeScript: evidence|fixture|config-loader — <why>` " +
+            "(evidence kept exactly as it ran; a fixture checked as JavaScript; a config a loader " +
+            "that cannot read TypeScript reads).",
+        },
+      },
+      create(context: Context) {
+        return {
+          Program(node: Readonly<Program>) {
+            const starts = node.body.map((s) => Number(s.range?.[0]));
+            const codeStart = Math.min(Infinity, ...starts);
+            if (excused(context.sourceCode.getAllComments(), codeStart)) return;
+            context.report({ node, messageId: "noReason" });
+          },
+        };
+      },
+    },
+  },
+};

package/eslint.config.mjs

@@ -14,7 +14,9 @@
 import { texLanguage } from "#eslint-rules/latex-language";
 import texBuild from "#eslint-rules/tex-build";
 import markdown from "@eslint/markdown";
-import localRules from "#eslint-rules/temp-root-realpath";
+import tempRootRules from "#eslint-rules/temp-root-realpath";
+import jsReasonRules from "#eslint-rules/js-needs-reason";
+
 import portRules from "#eslint-rules/install-path-literals";
 import n from "eslint-plugin-n";
 import tseslint from "typescript-eslint";
@@ -30,6 +32,11 @@ import { nodeFiles } from "#src/adapters/node/index";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** This repository's own rules, one plugin: `local/<rule>`. */
+const localRules = {
+  rules: { ...tempRootRules.rules, ...jsReasonRules.rules },
+};
+
 // The complexity set, shared by the TypeScript block and the ratchet below. Every function
 // measured over these limits on 2026-09-24 was either refactored under them (the #59 build code)
 // or pinned at its current maximum in RATCHET.
@@ -541,13 +548,16 @@ export default [
   // them invites the next reader to tidy an unused import — and then the file on disk is no longer
   // the file that produced the number it backs.
   // `dist/` is tsc's OUTPUT (gitignored): its declaration files are generated from `src/`, so
-  // linting them would report every finding twice and blame a file nobody edits.
+  // linting them would report every finding twice and blame a file nobody edits. The same holds for
+  // a skill's compiled scripts (`skills/*/scripts/*.js`, gitignored, from tsconfig.skills.json): the
+  // `.ts` beside each is what is linted.
   {
     ignores: [
       ".tmp-stages-src-*/",
       "fixtures/.tmp-*/",
       "docs/prior-art/repro/",
       "dist/",
+      "skills/*/scripts/*.js",
     ],
   },
   // 🔴 THE PACKAGE'S TYPESCRIPT, and before 2026-09-24 no block matched it — the same silent
@@ -872,6 +882,16 @@ export default [
       ],
     },
   },
+  // A NEW JavaScript file names why it is not TypeScript (#78), anywhere in the repository. The
+  // files that existed when the rule arrived are bulk suppressions in eslint-suppressions.json,
+  // which only shrinks (eslint-rules/js-needs-reason.ts).
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    plugins: { local: localRules },
+    rules: {
+      "local/js-needs-reason": "error",
+    },
+  },
   // LAST, so no block above can replace its `no-restricted-syntax` options for these files (none
   // sets that rule for JavaScript today; being last keeps it that way).
   {