feat(agents): make the no-inline-comments rule enforceable by every tool (#254)

* feat(agents): reject an inline comment where it is written

AGENTS.md has forbidden inline comments since it was written, and the rule
was still being broken — including by the agent that wrote several of the
comments now in packages/core. Nothing loaded the file and nothing checked
the rule, so it was advice that arrived only if someone thought to look.

CLAUDE.md is a symlink to AGENTS.md. Claude Code loads CLAUDE.md by name;
a symlink means the two cannot drift.

.claude/settings.json registers a PostToolUse hook that runs after every
file write. It counts the comments in the file just written, counts the
ones in the same file at HEAD, and rejects the write if the set grew,
naming each comment added. Comparing against HEAD rather than a checked-in
baseline keeps it quiet on the 1,700 comment lines already in the tree
while refusing every new one, with no list to maintain.

.gitignore ignored .claude wholesale, so no per-repository configuration
could travel between sessions. It now ignores the contents and tracks
settings.json and hooks/ — git cannot re-include a file whose parent
directory is excluded, hence `.claude/*` rather than `.claude/`.

The rule in AGENTS.md now names its exceptions, because the ambiguity is
what made it easy to break: /** */ counts as much as //, but suppressions,
compiler-read type annotations, and the prose in the six files a generated
reference is built from do not. Deleting the latter deletes a page.

scripts/comment-scan.test.ts is why the scanner can be trusted. One that
reads https:// inside a string as a comment would block honest work; one
that misses a comment after a regular expression would wave through what it
exists to catch. Both directions are covered.

This is deliberately not a CI gate. The rule is about how the codebase is
written, so the enforcement sits where the writing happens.

* feat(agents): enforce the comment rule for every tool, not only Claude Code

The PostToolUse hook added in the previous commit only fires in Claude Code.
Codex, another agent, or a person committing by hand met no resistance at
all, so the rule held for exactly one of the tools that write this code.

AGENTS.md now says what it is: the contract for every agent and for people.
Codex reads AGENTS.md by name and Claude Code reads CLAUDE.md, which is a
symlink to it, so both load one text rather than two that drift.

.githooks/pre-commit refuses a commit that adds a comment, whoever staged it.
core.hooksPath is pointed at .githooks by a prepare script, so pnpm install
arms it once. `git commit --no-verify` is the way past, which leaves a
deliberate choice behind rather than an accident.

pnpm comments:check is the same check as a command, comparing the working
tree against HEAD and naming every comment the change adds. AGENTS.md asks
for it before finishing, so an agent that reads instructions and one that
does not are both covered.

All three layers share scripts/comment-scan.mjs, and none of them are in
pnpm verify or CI — the rule is about how the code is written, so it is
enforced where writing and committing happen.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jouwdan

.claude/hooks/no-inline-comments.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+import { relative, resolve } from 'node:path'
+
+import { commentLines } from '../../scripts/comment-scan.mjs'
+
+const ROOT = resolve(new URL('../..', import.meta.url).pathname)
+const SOURCE = /\.(?:ts|tsx|mts|cts|mjs|cjs|js|jsx)$/
+const EXCLUDED = /^templates\/|\.d\.ts$/
+const DOC_SOURCES = new Set([
+  'packages/theme-kit/src/slots.ts',
+  'packages/theme-kit/src/api.ts',
+  'packages/theme-kit/src/view-models.ts',
+  'packages/plugin-kit/src/hooks.ts',
+  'packages/plugin-kit/src/payloads.ts',
+  'packages/plugin-kit/src/regions.ts',
+])
+
+async function read(stream) {
+  const chunks = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+let event
+try {
+  event = JSON.parse(await read(process.stdin))
+} catch {
+  process.exit(0)
+}
+
+const edited = event?.tool_input?.file_path
+if (typeof edited !== 'string') process.exit(0)
+
+const rel = relative(ROOT, resolve(edited))
+if (rel.startsWith('..') || !SOURCE.test(rel) || EXCLUDED.test(rel) || DOC_SOURCES.has(rel)) {
+  process.exit(0)
+}
+
+let source
+try {
+  source = await readFile(resolve(ROOT, rel), 'utf8')
+} catch {
+  process.exit(0)
+}
+
+const now = commentLines(source)
+if (now.size === 0) process.exit(0)
+
+const head = spawnSync('git', ['show', `HEAD:${rel}`], {
+  cwd: ROOT,
+  encoding: 'utf8',
+  maxBuffer: 32 * 1024 * 1024,
+})
+const before = head.status === 0 ? new Set(commentLines(head.stdout).values()) : new Set()
+
+const added = [...now.entries()].filter(([, text]) => !before.has(text))
+if (added.length === 0) process.exit(0)
+
+const listed = added
+  .slice(0, 5)
+  .map(([line, text]) => `    ${rel}:${line}  ${text.slice(0, 80)}`)
+  .join('\n')
+
+const more = added.length > 5 ? `\n    …and ${added.length - 5} more` : ''
+
+console.error(
+  `AGENTS.md: no inline code comments. This change adds ${added.length} to ${rel}:\n\n` +
+    `${listed}${more}\n\n` +
+    'Remove them. If one explains something a reader needs, that explanation belongs in ' +
+    'the relevant document under docs/, changed in the same commit — never in the code. ' +
+    'Suppressions (biome-ignore, @ts-expect-error), type annotations (@type, @satisfies) ' +
+    'and the JSDoc a generated reference is built from are not counted, so these are real ' +
+    'comments. See docs/contributing/development.md, "No inline comments".',
+)
+process.exit(2)

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/no-inline-comments.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

.githooks/pre-commit

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Rejects a commit that adds an inline code comment. AGENTS.md carries the rule;
+# docs/contributing/development.md, "No inline comments", explains this hook.
+# Bypass for a commit that genuinely needs one with `git commit --no-verify`.
+exec node scripts/comment-check.mjs --staged

.gitignore

@@ -55,4 +55,12 @@ test-results/
 # Common ignores
 node_modules
 .DS_Store
-.claude/
+
+# Claude Code's per-repository directory. `.claude/*` rather than `.claude/`,
+# because git cannot re-include a file whose parent directory is excluded — and
+# settings.json and hooks/ are the guardrails every session in this repository
+# loads, so they have to be tracked. Worktrees and personal overrides are not.
+.claude/*
+!.claude/settings.json
+!.claude/hooks/
+.claude/settings.local.json

AGENTS.md

@@ -1,5 +1,12 @@
 # Agent Guide
 
+**This file is the contract for every coding agent working in this repository
+— Claude Code, Codex, or anything else — and for people.** Codex reads
+`AGENTS.md` by name; `CLAUDE.md` is a symlink to this file so Claude Code
+loads the same text rather than a copy that drifts. The rules below are not
+advisory: the ones that can be checked are checked, by a git `pre-commit`
+hook that runs whatever produced the change.
+
 Meith: community forum software. A pnpm workspace — the board (`apps/community`),
 meith.dev (`apps/web`), the worker and the operator CLI in `apps/`; domain
 packages in `packages/`; `themes/`, `plugins/`, `examples/`. The deployment
@@ -10,7 +17,17 @@ interface lives in `docker/`. Documentation lives in `docs/` and nowhere else 
 
 - **No inline code comments.** If something needs explaining, the explanation
   belongs in the relevant document under `docs/`, updated in the same change —
-  never in the code.
+  never in the code. This covers `/** */` as well as `//`: a JSDoc block that
+  explains, justifies or gives context is an inline comment. Four things are
+  not, and are the only exceptions: a `biome-ignore` suppression, a
+  `@ts-expect-error`, a type annotation the compiler reads (`@type`,
+  `@satisfies`, `/// <reference>`), and the prose in the six files a generated
+  reference is built from — `packages/theme-kit/src/{slots,api,view-models}.ts`
+  and `packages/plugin-kit/src/{hooks,payloads,regions}.ts`, where the comment
+  *is* the published document. Run `pnpm comments:check` before you finish: it
+  lists every comment your change added, and it is the same check the git
+  `pre-commit` hook runs, so a commit carrying one is refused whoever or
+  whatever wrote it. `docs/contributing/development.md` explains both.
 - **Update the docs with every change.** Behavior described in `docs/` changes
   in the same commit that changes the behavior. A new document is registered in
   `apps/web/content/docs.manifest.json` and linked from `docs/README.md`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docs/contributing/development.md

@@ -521,6 +521,72 @@ but not symmetrically.**
 CI's other jobs build the image, drive a browser, and run the migrations
 against real Postgres.
 
+## No inline comments
+
+`AGENTS.md` carries the rule: an explanation belongs in the document under
+`docs/` that covers the behaviour, changed in the same commit, never in the
+code. The reason is that a comment is invisible to everyone who is not
+already reading that function — an operator, a theme author, somebody
+deciding whether the software does what they need — and it rots without
+anything noticing, because nothing checks a comment against the code beside
+it. A paragraph in `docs/` is read by all of them and is checked: the links
+gate holds its anchors, the index gate holds its registration, and the
+generated references fail when the contract they describe moves.
+
+The rule covers `/** */` as much as `//`. A JSDoc block that explains why a
+function does what it does is an inline comment with a decorative syntax.
+
+Four kinds of comment are not, and are the only exceptions:
+
+- **`biome-ignore` suppressions**, which the linter reads, and which the rule
+  above this section requires to carry a reason.
+- **`@ts-expect-error`**, which the compiler reads.
+- **Type annotations the compiler reads** — `@type`, `@satisfies`,
+  `/// <reference>` — mostly in `.mjs` files that have no other way to say it.
+- **The prose in the six files a generated reference is built from**:
+  `packages/theme-kit/src/slots.ts`, `api.ts` and `view-models.ts`, which
+  `pnpm theme:docs` publishes as
+  [the theme slot reference](../reference/theme-slots.md); and
+  `packages/plugin-kit/src/hooks.ts`, `payloads.ts` and `regions.ts`, which
+  `pnpm plugin:docs` publishes as
+  [the plugin hook reference](../reference/plugin-hooks.md). There the comment
+  *is* the published document, and deleting it deletes a page.
+
+### How it is enforced
+
+Three layers, none of them CI, in the order they catch something.
+
+**`pnpm comments:check`** lists every comment your change adds, comparing the
+working tree against `HEAD`. Run it before you finish. Comparing against
+`HEAD` rather than a checked-in list of allowed comments is what lets all
+three layers stay quiet about the comments already in the tree while refusing
+every new one, with nothing to maintain.
+
+**The git `pre-commit` hook** — `.githooks/pre-commit` — runs the same check
+over the staged tree and refuses the commit. `core.hooksPath` is set to
+`.githooks` by the `prepare` script, so `pnpm install` arms it once and it
+applies to every commit made in the repository afterwards, by any agent and by
+any person. This is the layer that does not care what wrote the code:
+`git commit --no-verify` is the deliberate way past it, and it leaves a
+visible choice behind rather than an accident.
+
+**A `PostToolUse` hook**, `.claude/hooks/no-inline-comments.mjs`, registered in
+`.claude/settings.json`, runs after every file write a Claude Code session
+makes and rejects the write, naming each comment added. It is the fastest
+feedback of the three because it fires before the code is even staged, but it
+only covers that one tool — which is why it is not the layer the rule rests
+on.
+
+`scripts/comment-scan.mjs` does the scanning for all three, and
+`scripts/comment-scan.test.ts` is why it can be trusted: a scanner that reads
+`https://` inside a string as a comment, or misses one after a regular
+expression, would either block honest work or wave through the thing it exists
+to catch. Both directions are covered there.
+
+Nothing in `pnpm verify` or CI checks for comments. That is deliberate: the
+rule is about how the codebase is written, so the enforcement sits where the
+writing and the committing happen, not on the branch.
+
 ## Formatting and lint
 
 One tool does both: [Biome](https://biomejs.dev/), configured in `biome.json`

package.json

@@ -62,7 +62,9 @@
     "board:eject:smoke": "tsx scripts/board-eject-smoke.mts",
     "perf": "tsx packages/testkit/src/load/run.ts",
     "perf:docs": "node scripts/perf-docs.mjs",
-    "perf:docs:check": "node scripts/perf-docs.mjs --check"
+    "perf:docs:check": "node scripts/perf-docs.mjs --check",
+    "prepare": "git rev-parse --is-inside-work-tree >/dev/null 2>&1 && git config core.hooksPath .githooks || true",
+    "comments:check": "node scripts/comment-check.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.8",

scripts/comment-check.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { commentLines } from './comment-scan.mjs'
+import { ROOT } from './repo-files.mjs'
+
+const SOURCE = /\.(?:ts|tsx|mts|cts|mjs|cjs|js|jsx)$/
+const EXCLUDED = /^templates\/|\.d\.ts$/
+
+const DOC_SOURCES = new Map([
+  ['packages/theme-kit/src/slots.ts', 'pnpm theme:docs'],
+  ['packages/theme-kit/src/api.ts', 'pnpm theme:docs'],
+  ['packages/theme-kit/src/view-models.ts', 'pnpm theme:docs'],
+  ['packages/plugin-kit/src/hooks.ts', 'pnpm plugin:docs'],
+  ['packages/plugin-kit/src/payloads.ts', 'pnpm plugin:docs'],
+  ['packages/plugin-kit/src/regions.ts', 'pnpm plugin:docs'],
+])
+
+const STAGED = process.argv.includes('--staged')
+
+function git(args, options = {}) {
+  return spawnSync('git', args, {
+    cwd: ROOT,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    ...options,
+  })
+}
+
+const listing = STAGED
+  ? git(['diff', '--cached', '--name-only', '--diff-filter=ACMR', '-z'])
+  : git(['diff', 'HEAD', '--name-only', '--diff-filter=ACMR', '-z'])
+
+if (listing.status !== 0) {
+  console.error('✗ inline comments: could not list changed files')
+  process.exit(1)
+}
+
+const changed = listing.stdout
+  .split('\0')
+  .filter((rel) => rel !== '' && SOURCE.test(rel) && !EXCLUDED.test(rel) && !DOC_SOURCES.has(rel))
+
+if (changed.length === 0) {
+  console.log('✓ inline comments: no source file changed')
+  process.exit(0)
+}
+
+async function after(rel) {
+  if (!STAGED) return readFile(join(ROOT, rel), 'utf8').catch(() => null)
+  const staged = git(['show', `:${rel}`])
+  return staged.status === 0 ? staged.stdout : null
+}
+
+const problems = []
+
+for (const rel of changed) {
+  const source = await after(rel)
+  if (source === null) continue
+
+  const now = commentLines(source)
+  if (now.size === 0) continue
+
+  const head = git(['show', `HEAD:${rel}`])
+  const before = head.status === 0 ? new Set(commentLines(head.stdout).values()) : new Set()
+
+  const added = [...now.entries()].filter(([, text]) => !before.has(text))
+  if (added.length === 0) continue
+
+  problems.push({ rel, added })
+}
+
+if (problems.length === 0) {
+  console.log(`✓ inline comments: ${changed.length} changed source file(s), no comment added`)
+  process.exit(0)
+}
+
+const total = problems.reduce((sum, { added }) => sum + added.length, 0)
+console.error(`✗ inline comments: ${total} added across ${problems.length} file(s)\n`)
+
+for (const { rel, added } of problems) {
+  for (const [line, text] of added.slice(0, 5)) {
+    console.error(`    ${rel}:${line}  ${text.slice(0, 80)}`)
+  }
+  if (added.length > 5) console.error(`    …and ${added.length - 5} more in ${rel}`)
+}
+
+console.error(
+  '\n  AGENTS.md: no inline code comments. An explanation belongs in the relevant\n' +
+    '  document under docs/, changed in the same commit — never in the code.\n\n' +
+    '  Suppressions (biome-ignore, @ts-expect-error), compiler-read type annotations\n' +
+    '  (@type, @satisfies) and the prose in the six files a generated reference is\n' +
+    '  built from are not counted, so these are real comments.\n\n' +
+    '  docs/contributing/development.md, "No inline comments", has the whole rule.\n',
+)
+process.exit(1)