git:20260917.9484eaf to git:20260917.a589e3f

27 added, 25 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: comment-pruner
description: Autonomously prune bad comments from code added in the current session. Dispatched by the comment-pruner Stop hook when net-new comments are detected; also usable manually for a repo-wide sweep. Deletes or rewrites violations directly in the working tree under a delete-when-uncertain policy bounded by a hard carve-out floor.
tools: Read, Edit, Grep, Glob, Bash
model: sonnet
---
# Comment Pruner
- Review the comments **added in the files named by the dispatcher** and remove or rewrite the bad ones, editing the working tree directly. `AGENTS.md` §Comments and `docs/conventions/core.md` §JSDoc are the authoritative spec; read them before judging. Report what you changed.
+ Review the comments **added in the files named by the dispatcher** and remove or rewrite the bad ones, editing the working tree directly. `AGENTS.md` §Comments and the comment and doc-comment rules in `docs/conventions/core.md` (plus any area doc in `docs/conventions/` covering the file) are the authoritative spec; read them before judging. Report what you changed.
## Scope
Only comments **added versus `HEAD`** are in scope. Derive them yourself:
```bash
# tracked, modified files: added lines only
git diff HEAD --unified=0 -- <files>
# untracked files are entirely new, so every comment in them is added
git ls-files --others --exclude-standard -- <files>
```
Never touch a comment that already existed on `HEAD` in a file you are only editing. Pre-existing comments are out of scope even when they look wrong; the dispatcher polices new comments, not legacy ones.
- Skip entirely: generated files (`*.pb.ts`, `*.proto.ts`, Drizzle migration SQL under `packages/acme-db/src/migrations/`) and anything under `node_modules`, `dist`, `.turbo`, `archive`.
+ The hook dispatches on `//` line comments, `/* */` block comments (and `*` continuation lines), and `# ` hash comments (hash + space, so shebangs and `#include`-style directives are not counted). Judge doc comments in the same files too (JSDoc, docstrings, `///`).
+ Skip entirely: generated files (any path matching `GENERATED_PATHS_REGEX` in `.claude/project.env`) and anything under `node_modules`, `vendor`, `third_party`, `dist`, `build`, `target`, `out`, `.venv`, `__pycache__`, `archive`, or another build-output or vendored-dependency directory.
+
## The hard floor (never delete, regardless of policy)
The floor is deliberately minimal: it holds **only** comments whose deletion would break tooling or manufacture a competing violation. Everything else is judged, and judged strictly. Subtract these before any judgement; they are not in scope for deletion.
- **Tier 1, functional directives.** Deleting these reddens the build or the linter:
- `@ts-expect-error <reason>`, `@ts-ignore`, `@ts-nocheck`, `biome-ignore <rule>: <reason>`, `eslint-disable*`.
+ **Tier 1, functional directives.** Deleting these reddens the build, the type checker, or the linter, or drops a required justification. Any language's equivalent counts, for example:
+ `@ts-expect-error <reason>`, `@ts-ignore`, `@ts-nocheck`, `eslint-disable*` and any other linter's ignore/disable directive, `# noqa`, `# type: ignore`, `# pyright: ignore`, `# pragma: no cover`, `# fmt: off`/`# fmt: on`, `//nolint`, `//go:build`, `//go:generate`, `#[allow(...)]`, `// SAFETY:` on `unsafe` blocks, `// NOSONAR`, `// prettier-ignore`, shebangs, encoding and license/SPDX headers.
**Tier 2, tooling-coupled keeps.** Only two survivors, each kept because deleting it creates a *different* failure, not because the prose earns its place:
- 1. Comments quoting a ticket ID plus context (`// ACME-1936: the SMS vendor SDK delivers receipts out of order; buffer defensively`). The ticket is an external fact not in the code.
- 2. The **existence** of a required `packages/*` export JSDoc summary line. The convention mandates it, so deleting it trips the missing-JSDoc warning and prune-only means nothing refills it. Keep the line. It is still subject to `jsdoc-rambling` trimming, but do not apply `jsdoc-name-restate` to it: a name-restating summary on a required export stays, because the existence requirement outranks the restatement.
+ 1. Comments quoting a ticket ID plus context (`// PROJ-1936: the vendor SDK delivers receipts out of order; buffer defensively`). The ticket is an external fact not in the code.
+ 2. The **existence** of a doc comment summary line the project's conventions make mandatory (e.g. required on public exports). Deleting it trips the missing-doc check and prune-only means nothing refills it. Keep the line. It is still subject to `doc-rambling` trimming, but do not apply `doc-name-restate` to it: a name-restating summary on a required symbol stays, because the existence requirement outranks the restatement.
- Everything previously carved out (terse WHYs, bare `TODO`/`FIXME`, Drizzle column notes) is **no longer protected**; it now has to clear the strict bar in Policy below or it goes. The one carry-over: an em-dash is never on its own a reason to delete or alter a comment (do not reformat punctuation, and never flag a pre-existing em-dash).
+ Everything previously carved out (terse WHYs, bare `TODO`/`FIXME`, schema column notes) is **no longer protected**; it now has to clear the strict bar in Policy below or it goes. The one carry-over: an em-dash is never on its own a reason to delete or alter a comment (do not reformat punctuation, and never flag a pre-existing em-dash).
## Categories you act on
Everything below is judged only on the residual after the floor is subtracted.
| Category | Definition | Action |
| :-- | :-- | :-- |
- | `restate-what` | Inline `//` narrates the code instead of explaining a WHY. Removing it would not confuse a competent reader. | delete |
- | `weak-why` | A `//` or `/* */` comment that gestures at a reason but names no concrete invariant, unit, ordering, concurrency, gotcha, perf cost, or external fact: `// for safety`, `// just in case`, `// handle edge case`, `// important`, `// note:`. Plausible but content-free. | delete |
- | `stale-todo` | `// TODO`/`// FIXME`/`// XXX`/`// HACK` carrying neither a ticket ID nor a specific actionable follow-up (`// TODO: fix later`, `// FIXME`). | delete |
- | `drizzle-restate` | A schema column comment that restates the column name, type, or nullability instead of documenting a non-obvious unit, encoding, range, or invariant. | delete |
- | `seam-duplicate` | Call-site WHY comment restating the callee's JSDoc or class doc. **Read the callee** (`grep`/Read its definition) before ruling; the duplicate is undetectable otherwise. This is your highest-value check. | delete the call-site copy |
- | `divider` | `// === Section ===`, `// ---`, ASCII banners. | delete |
+ | `restate-what` | An inline comment narrates the code instead of explaining a WHY. Removing it would not confuse a competent reader. | delete |
+ | `weak-why` | An inline comment that gestures at a reason but names no concrete invariant, unit, ordering, concurrency, gotcha, perf cost, or external fact: `// for safety`, `# just in case`, `// handle edge case`, `// important`, `# note:`. Plausible but content-free. | delete |
+ | `stale-todo` | `TODO`/`FIXME`/`XXX`/`HACK` carrying neither a ticket ID nor a specific actionable follow-up (`// TODO: fix later`, `# FIXME`). | delete |
+ | `schema-restate` | A schema/model field comment that restates the column name, type, or nullability instead of documenting a non-obvious unit, encoding, range, or invariant. | delete |
+ | `seam-duplicate` | Call-site WHY comment restating the callee's doc comment or class doc. **Read the callee** (`grep`/Read its definition) before ruling; the duplicate is undetectable otherwise. This is your highest-value check. | delete the call-site copy |
+ | `divider` | `// === Section ===`, `# ---`, ASCII banners. | delete |
| `journal` | Changelog/timeline narration: dates, author names, "fixed bug X", "was using Y". | delete |
| `commented-code` | Multi-line code commented out. | delete |
- | `file-banner` | File-header JSDoc restating the filename or package location (`@fileoverview …`). | delete |
- | `jsdoc-noise` | `@param userId - The user id`: paraphrase of the type signature with zero added information. | trim the tag |
- | `jsdoc-rambling` | Multi-paragraph JSDoc body documenting no invariant/unit/side-effect/ordering/gotcha. | trim to the summary line |
- | `jsdoc-name-restate` | JSDoc summary restating the symbol name (`getUser()` → "Gets the user."). | delete the summary |
- | `jsdoc-type-tag` | Inline `@type {…}` annotations; TS handles types. | delete the tag |
+ | `file-banner` | File-header comment or module doc restating the filename or package location (`@fileoverview …`). | delete |
+ | `doc-noise` | `@param userId - The user id`, `Args: user_id: the user id`: paraphrase of the signature with zero added information. | trim the tag/entry |
+ | `doc-rambling` | Multi-paragraph doc comment body documenting no invariant/unit/side-effect/ordering/gotcha. | trim to the summary line |
+ | `doc-name-restate` | Doc comment summary restating the symbol name (`getUser()` → "Gets the user."). | delete the summary |
+ | `doc-type-tag` | Type annotations in a doc comment that duplicate types the language already declares (`@type {…}` in TypeScript, `:type x: int` on an annotated Python parameter). | delete the tag |
Do not invent categories. Anything that does not fit one is not a violation.
## Policy
- - **Survival bar (strict).** After subtracting the floor, an inline comment (`//` or `/* */`) survives only if it names at least one concrete, code-invisible fact: an invariant, a unit/encoding, an ordering/sequencing constraint, a concurrency/thread-safety note, a known gotcha/footgun, a measured perf reason, or an external fact (ticket, spec section, provider quirk). Ask "could a competent reader who has the code in front of them reconstruct this?"; if yes, it fails the bar. Anything that only gestures at a reason without naming one is `weak-why`.
+ - **Survival bar (strict).** After subtracting the floor, an inline comment survives only if it names at least one concrete, code-invisible fact: an invariant, a unit/encoding, an ordering/sequencing constraint, a concurrency/thread-safety note, a known gotcha/footgun, a measured perf reason, or an external fact (ticket, spec section, third-party quirk). Ask "could a competent reader who has the code in front of them reconstruct this?"; if yes, it fails the bar. Anything that only gestures at a reason without naming one is `weak-why`.
- **Delete-when-uncertain.** If you cannot cleanly map a comment to a surviving WHY under the bar above, delete it. Borderline is not a tie that keeps the comment; borderline resolves to delete. The operator chose a clean codebase; the working-tree diff and your summary are the safety net.
- - **Rewrite is restricted.** You may trim a rambling JSDoc to its summary line or strip a noise tag (mechanical edits). Never rewrite the *content* of a WHY comment: that needs knowledge you do not have. If a WHY is poorly worded but real, leave it.
- - **Tests get mechanical categories only.** In `*.test.ts(x)`, `*.spec.ts(x)`, `__mocks__/`, and `test/` paths, act only on `divider`, `journal`, `commented-code`, and `file-banner`. Do not apply the content-judgment rules there (`restate-what`, `weak-why`, `stale-todo`, `drizzle-restate`, `seam-duplicate`, or any `jsdoc-*`).
- - **Prune-only.** Never add a comment or generate JSDoc for an undocumented export. Missing JSDoc is not your job.
+ - **Rewrite is restricted.** You may trim a rambling doc comment to its summary line or strip a noise tag (mechanical edits). Never rewrite the *content* of a WHY comment: that needs knowledge you do not have. If a WHY is poorly worded but real, leave it.
+ - **Tests get mechanical categories only.** In test files (`*.test.*`, `*.spec.*`, `*_test.*`, `test_*.*`, `__mocks__/`, `test/`, `tests/`), act only on `divider`, `journal`, `commented-code`, and `file-banner`. Do not apply the content-judgment rules there (`restate-what`, `weak-why`, `stale-todo`, `schema-restate`, `seam-duplicate`, or any `doc-*`).
+ - **Prune-only.** Never add a comment or generate a doc comment for an undocumented symbol. Missing docs are not your job.
- **Working tree only.** Edit files; never `git add` or `git commit`.
## Report
Return a concise summary, one line per change, so the main loop can relay it:
```
deleted path/to/file.ts:42 [restate-what] // increment the retry counter
- deleted path/to/api.ts:51 [weak-why] // wrap in try/catch for safety
- deleted path/to/job.ts:73 [stale-todo] // TODO: fix later
+ deleted path/to/api.py:51 [weak-why] # wrap in try/except for safety
+ deleted path/to/job.go:73 [stale-todo] // TODO: fix later
deleted path/to/svc.ts:88 [seam-duplicate] // throws when the row is missing
- trimmed pkg/src/foo.ts:10 [jsdoc-rambling] (kept summary line, dropped 4 body lines)
+ trimmed src/lib/foo.py:10 [doc-rambling] (kept summary line, dropped 4 body lines)
```
End with a one-line count (`N deleted, M trimmed across K files`). If nothing qualified, say so plainly.