@avi2dg/checks 0.69.0 → 0.70.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.70.0
+
+Released 2026-11-07.
+
+### Features
+
+- **docs:** require root AGENTS.md and CLAUDE.md with package.json [#58](https://github.com/avi2d/checks/pull/58)
+
 ## 0.69.0
 
 Released 2026-11-06.

package/docs/gates/checks-docs.md

@@ -17,6 +17,7 @@ It fails when a living doc or an agent file names a path, link or command that d
 It fails when an agent file holds more than 3,000 characters or a `## Maintaining this file` section, whatever the range touches, as [Agent files](#agent-files) says.
 It fails when an entry in an agent file names no tracked path, link or `bun run` command, whatever the range touches.
 It fails when a range edits a README that is over 6,000 characters or holds a table cell over 300, as [README ceilings](#readme-ceilings) says.
+It fails when a range edits a doc file and a repository with a `package.json` is missing `AGENTS.md` or `CLAUDE.md` at its root, as [Root agent files](#root-agent-files) says.
 It fails when a living doc or an agent file names a code span the range removed from every file outside the docs, on any line.
 [Paths, links and commands](#paths-links-and-commands) says how each reference resolves.
 The package ships one template per kind under `dist/templates/`, and a repository starts a new doc file by copying one:
@@ -206,6 +207,21 @@ No line in a complete same-named generated block counts toward either ceiling, f
 A README fails only in a range that edits it.
 A README the range leaves alone is listed as advisory, so the first change that edits an oversize README shrinks it.
 
+## Root agent files
+
+A repository with a `package.json` keeps `AGENTS.md` and `CLAUDE.md` at its root, since Claude Code reads `CLAUDE.md` and every other agent reads `AGENTS.md`.
+The failure names the missing file and the template to copy:
+
+- `AGENTS.md` starts from `dist/templates/agents.md`, and [Agent files](#agent-files) holds its shape.
+- `CLAUDE.md` is `dist/templates/claude.md` word for word, the import that points Claude Code at `AGENTS.md`.
+  A symlink to `AGENTS.md` or any other text fails that template once a range touches the file.
+
+A `package.json` anywhere in the repository asks for both files.
+A repository with no `package.json` needs neither.
+A missing file fails only in a range that adds, changes, renames or deletes a doc file, an ADR or the changelog included.
+Markdown the gate does not judge, such as a changeset entry or a pull request template, does not end the advisory period.
+Any other range lists the missing file as advisory, so the first change that edits a doc file adds both files.
+
 ## What it reads
 
 It reads each Markdown file at the head commit, and uses its path or front matter to choose its kind.
@@ -217,6 +233,8 @@ It reads the repository's own name and its direct dependencies from the root `pa
 It reads the versions the root `package.json` and `.bun-version` pin at the head commit.
 It reads each agent file at the head commit for the ceiling, its sections and its entries, whatever the range touches.
 It reads the root `README.md` and each `README.md` beside a tracked `package.json` at the head commit for the README ceilings.
+It reads whether any `package.json` and the root `AGENTS.md` and `CLAUDE.md` are tracked at the head commit for the root agent files.
+When a root agent file is missing, it reads a deleted or renamed Markdown file at the base commit to find its front matter kind.
 A name that an installed direct dependency still holds counts as present.
 From the working tree it reads the ignore files git reads, `node_modules/.bin`, and the directory of each direct dependency under `node_modules`.
 
@@ -234,14 +252,15 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 | Code | When |
 | --- | --- |
-| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules and copies no pinned version, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, every README the range edits holds to the README ceilings, and no code span a living doc or an agent file names vanished from every file outside the docs |
-| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule or copies a pinned version, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, a README the range edits is over a README ceiling, or the range removes a name a living doc or an agent file still carries |
+| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules and copies no pinned version, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, every README the range edits holds to the README ceilings, a range that edits a doc file leaves `AGENTS.md` and `CLAUDE.md` at the root of a repository with a `package.json`, and no code span a living doc or an agent file names vanished from every file outside the docs |
+| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule or copies a pinned version, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, a README the range edits is over a README ceiling, a range that edits a doc file leaves either `AGENTS.md` or `CLAUDE.md` missing from the root in a repository with a `package.json`, or the range removes a name a living doc or an agent file still carries |
 | 2 | a `package.json` does not decode, a ref does not resolve, or `grep` cannot read an installed direct dependency |
 
 ## Sample output
 
 ```
-docs: 7 violation(s):
+docs: 8 violation(s):
+  CLAUDE.md: is missing from the repository root, which a repository with a `package.json` keeps. Copy `node_modules/@avi2dg/checks/dist/templates/claude.md` to `CLAUDE.md` word for word, so Claude Code reads `AGENTS.md`
   README.md:1: lacks `## Before you begin`
   README.md:12: carries `;`, a semicolon. Use two sentences
   README.md:13: carries `1.3.5`, a version .bun-version pins. Name .bun-version instead, or let a build write the line between generated markers
@@ -265,6 +284,7 @@ docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files
 A repository adopts the templates as its files change, and the prose rules as its lines change, because an untouched file or line never fails those checks.
 It reshapes its agent files when it adopts the gate, because [Agent files](#agent-files) judges each one whatever the range touches.
 It shrinks an oversize README in the first change that edits it, because [README ceilings](#readme-ceilings) judges only a README the range edits.
+It adds `AGENTS.md` and `CLAUDE.md` at its root in the first change that edits a doc file, because [Root agent files](#root-agent-files) judges only such a range.
 A name the range removes fails wherever a doc still carries it, because the removal is what turned the line stale.
 
 ## Related topics

package/docs/how-to/set-up-a-repository.md

@@ -65,6 +65,20 @@ To give each tool the config it reads:
    export default defineConfig({ orphans: ["^src/bin[.]ts$"] });
    ```
 
+## Write the agent files
+
+To give each agent the file it reads:
+
+1. Copy the agent templates to the repository root:
+
+   ```sh
+   cp node_modules/@avi2dg/checks/dist/templates/agents.md AGENTS.md
+   cp node_modules/@avi2dg/checks/dist/templates/claude.md CLAUDE.md
+   ```
+
+1. Fill `AGENTS.md` with what an agent cannot infer from the code.
+1. Keep `CLAUDE.md` word for word, so Claude Code reads `AGENTS.md`.
+
 ## Run the checks on every pull request
 
 To run the gates in CI:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",

package/src/docs/doc-agents.ts

@@ -1,5 +1,5 @@
 import { Parser, type NodeType } from "commonmark";
-import { commandNames, type Snapshot } from "./doc-references.ts";
+import { commandNames, PACKAGE_MANIFEST, type Snapshot } from "./doc-references.ts";
 import { handWritten } from "./doc-versions.ts";
 import { AGENT_NAMES, scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
 
@@ -8,7 +8,6 @@ export const README_CEILING = 6000;
 export const CELL_CEILING = 300;
 
 const README = "README.md";
-const MANIFEST = "package.json";
 const SECOND_LEVEL = /^\s{0,3}##(?:\s+|$)(.*?)(?:\s+#+)?\s*$/;
 const SETEXT_SECOND = /^\s{0,3}-+\s*$/;
 const CELL_SEPARATOR = /(?<!\\)\|/;
@@ -37,7 +36,31 @@ export function ceilingFinding(text: string): AgentFinding | undefined {
 
 export function isCeiledReadme(repositoryPath: string, files: ReadonlySet<string>): boolean {
   if (repositoryPath === README) return true;
-  return repositoryPath.endsWith(`/${README}`) && files.has(`${repositoryPath.slice(0, -README.length)}${MANIFEST}`);
+  return repositoryPath.endsWith(`/${README}`) && files.has(`${repositoryPath.slice(0, -README.length)}${PACKAGE_MANIFEST}`);
+}
+
+const KIT_TEMPLATES = "node_modules/@avi2dg/checks/dist/templates";
+
+const ROOT_AGENT_FILES = [
+  { path: "AGENTS.md", fix: `Copy \`${KIT_TEMPLATES}/agents.md\` to \`AGENTS.md\` and fill it with what an agent cannot infer from the code` },
+  { path: "CLAUDE.md", fix: `Copy \`${KIT_TEMPLATES}/claude.md\` to \`CLAUDE.md\` word for word, so Claude Code reads \`AGENTS.md\`` },
+] as const;
+
+export type RootAgentFinding = {
+  readonly path: (typeof ROOT_AGENT_FILES)[number]["path"];
+  readonly message: string;
+};
+
+export function hasManifest(files: ReadonlySet<string>): boolean {
+  return [...files].some((file) => file === PACKAGE_MANIFEST || file.endsWith(`/${PACKAGE_MANIFEST}`));
+}
+
+export function missingAgentFiles(files: ReadonlySet<string>): readonly RootAgentFinding[] {
+  if (!hasManifest(files)) return [];
+  return ROOT_AGENT_FILES.filter(({ path }) => !files.has(path)).map(({ path, fix }) => ({
+    path,
+    message: `is missing from the repository root, which a repository with a \`package.json\` keeps. ${fix}`,
+  }));
 }
 
 type Part = { readonly title: string; readonly lines: readonly MarkdownLine[] };

package/src/docs/docs.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env bun
 import { Console, Effect } from "effect";
-import { ceilingFinding, entryFindings, isAgentFile, isCeiledReadme, maintainingFinding, readmeFindings } from "./doc-agents.ts";
-import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
+import { ceilingFinding, entryFindings, hasManifest, isAgentFile, isCeiledReadme, maintainingFinding, missingAgentFiles, readmeFindings, type RootAgentFinding } from "./doc-agents.ts";
+import { rootsOf, snapshotOf, type Snapshot, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, recordsOf, speaksToConsumers, type Placement, type Records } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
 import { pinsAt, versionFindings } from "./doc-versions.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
-import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
+import { changedLines, changedPaths, git, pathsAt, pathsOf, rangeEnds, refArgs, type Change } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { proseFindings, readerOf } from "./prose-matchers.ts";
 import { longSentences } from "./sentence-length.ts";
@@ -23,9 +23,11 @@ type Judged = {
   readonly named: number;
   readonly agents: number;
   readonly readmes: number;
+  readonly hasManifest: boolean;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
   readonly readmeAdvisory: readonly Finding[];
+  readonly agentFileAdvisory: readonly Finding[];
   readonly sentenceAdvisory: readonly Finding[];
   readonly brokenBefore: readonly Finding[];
 };
@@ -45,6 +47,27 @@ const NAME = "docs";
 const USAGE = "usage: docs.ts <ref> | <base-ref> <head-ref>";
 const MARKDOWN = [":(glob)**/*.md"];
 
+function agentFileFindings(path: string, text: string, tracked: Snapshot): readonly Finding[] {
+  const shaped = [ceilingFinding(text), maintainingFinding(text)].flatMap((finding) => (finding === undefined ? [] : [finding]));
+  return [...shaped, ...entryFindings(path, text, tracked)].map((finding) => ({ path, ...finding }));
+}
+
+const rangeEditsDocs = Effect.fn("rangeEditsDocs")(function* (root: string, base: string, changes: readonly Change[], text: (path: string) => string) {
+  const paths = changes.flatMap((change) => pathsOf(change));
+  if (paths.some((path) => placementOf(path, text(path)).type !== "unjudged" || readerOf(path) !== undefined)) return true;
+  const gone = [...new Set(changes.flatMap((change) => (change.kind === "deleted" ? [change.path] : change.kind === "renamed" ? [change.from] : [])))].filter(
+    (path) => readerOf(path) === undefined && placementOf(path).type === "unjudged",
+  );
+  if (gone.length === 0) return false;
+  const before = yield* readTexts(root, base, gone);
+  return gone.some((path) => placementOf(path, before.get(path) ?? "").type !== "unjudged");
+});
+
+function rootAgentFindings(absent: readonly RootAgentFinding[], editsDocs: boolean): { readonly failing: readonly Finding[]; readonly advisory: readonly Finding[] } {
+  const listed = absent.map((finding) => ({ ...finding, line: undefined }));
+  return editsDocs ? { failing: listed, advisory: [] } : { failing: [], advisory: listed };
+}
+
 function templateFindings(path: string, text: string, placement: Placement, records: Records): readonly Finding[] {
   const misplaced = placementProblem(placement);
   if (misplaced !== undefined) return [{ path, line: undefined, message: misplaced }];
@@ -114,9 +137,6 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const versions = edited.flatMap(({ path }) =>
     versionFindings(text(path), pins, changed.get(path)).map(({ line, message }) => ({ path, line, message })),
   );
-  const sentenceAdvisory = edited
-    .flatMap(({ path }) => longSentences(text(path), changed.get(path)).map(({ line, message }) => ({ path, line, message })))
-    .toSorted(inPathOrder);
   const judging = (path: string): Judging => ({ commands: !speaksToConsumers(text(path)) });
   // A directory the range deletes still belongs to this repository, so a path under it is stale rather than another repository's.
   const roots = rootsOf(yield* pathsAt(base, [], root));
@@ -125,12 +145,11 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const vanished = yield* vanishedNames(root, base, head, referenced, references.failed);
   const agents = proseDocs.filter(({ path }) => isAgentFile(path));
   const tracked = snapshotOf(yield* pathsAt(head, [], root), new Map(), new Map());
-  const shapes = agents.flatMap(({ path }) =>
-    [ceilingFinding(text(path)), maintainingFinding(text(path))].flatMap((finding) => (finding === undefined ? [] : [{ path, ...finding }])),
-  );
-  const entries = agents.flatMap(({ path }) => entryFindings(path, text(path), tracked).map((finding) => ({ path, ...finding })));
+  const shapes = agents.flatMap(({ path }) => agentFileFindings(path, text(path), tracked));
   const readmes = proseDocs.filter(({ path }) => isCeiledReadme(path, tracked.files));
   const oversize = readmes.flatMap(({ path }) => readmeFindings(text(path)).map((finding) => ({ path, ...finding })));
+  const absent = missingAgentFiles(tracked.files);
+  const rootAgents = rootAgentFindings(absent, absent.length === 0 ? false : yield* rangeEditsDocs(root, base, changes, text));
   const advisory = new Map<string, number>();
   for (const { path } of templated.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
   return {
@@ -139,6 +158,7 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
     named: referenced.size,
     agents: agents.length,
     readmes: readmes.filter(({ path }) => touched.has(path)).length,
+    hasManifest: hasManifest(tracked.files),
     findings: [
       ...templated.filter((finding) => touched.has(finding.path)),
       ...prose,
@@ -146,12 +166,15 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
       ...references.failing,
       ...vanished,
       ...shapes,
-      ...entries,
       ...oversize.filter((finding) => touched.has(finding.path)),
+      ...rootAgents.failing,
     ].toSorted(inPathOrder),
     advisory,
     readmeAdvisory: oversize.filter((finding) => !touched.has(finding.path)).toSorted(inPathOrder),
-    sentenceAdvisory,
+    agentFileAdvisory: rootAgents.advisory,
+    sentenceAdvisory: edited
+      .flatMap(({ path }) => longSentences(text(path), changed.get(path)).map(({ line, message }) => ({ path, line, message })))
+      .toSorted(inPathOrder),
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
 });
@@ -160,7 +183,24 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, named, agents, readmes, findings, advisory, readmeAdvisory, sentenceAdvisory, brokenBefore }: Judged): string {
+export function report({
+  held,
+  edited,
+  named,
+  agents,
+  readmes,
+  hasManifest: manifestHeld,
+  findings,
+  advisory,
+  readmeAdvisory,
+  agentFileAdvisory,
+  sentenceAdvisory,
+  brokenBefore,
+}: Judged): string {
+  const rootAgentFiles =
+    manifestHeld && agentFileAdvisory.length === 0
+      ? [`${NAME}: the repository root holds the AGENTS.md and CLAUDE.md a repository with a \`package.json\` keeps`]
+      : [];
   const verdict =
     findings.length === 0
       ? [
@@ -170,6 +210,7 @@ export function report({ held, edited, named, agents, readmes, findings, advisor
           `${NAME}: the range breaks no path, link or command the ${named} living doc(s) or agent file(s) name`,
           `${NAME}: the ${agents} agent file(s) hold to the ceiling, and every entry names a tracked path, a link or a command`,
           `${NAME}: the ${readmes} README(s) the range edits hold to the 6,000-character ceiling and the 300-character table cell ceiling`,
+          ...rootAgentFiles,
         ]
       : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
   const unconformed =
@@ -183,6 +224,13 @@ export function report({ held, edited, named, agents, readmes, findings, advisor
     readmeAdvisory.length === 0
       ? []
       : [`${NAME}: advisory, ${readmeAdvisory.length} README ceiling finding(s) in README(s) the range leaves alone:`, ...readmeAdvisory.map(describe)];
+  const missing =
+    agentFileAdvisory.length === 0
+      ? []
+      : [
+          `${NAME}: advisory, ${agentFileAdvisory.length} agent file(s) missing from the repository root, which the first range that edits a doc adds:`,
+          ...agentFileAdvisory.map(describe),
+        ];
   const sentences =
     sentenceAdvisory.length === 0
       ? []
@@ -197,7 +245,7 @@ export function report({ held, edited, named, agents, readmes, findings, advisor
           `${NAME}: advisory, ${brokenBefore.length} path(s), link(s) or command(s) the living docs or agent files name were broken before the range:`,
           ...brokenBefore.map(describe),
         ];
-  return [...verdict, ...unconformed, ...oversize, ...sentences, ...broken].join("\n");
+  return [...verdict, ...unconformed, ...oversize, ...missing, ...sentences, ...broken].join("\n");
 }
 
 const docs = Effect.gen(function* () {