AGENTS.md · diff

git:20260814.a16c92e to git:20260816.fd1d93b

82 added, 2 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.

# AGENTS.md — claude-code-riper-5
## Git Commit Standards
Format commit messages as:
```
Scope(type[detail]): concise description
why: Explanation of necessity or impact.
what:
- Specific technical changes made
- Focused on a single topic
```
Keep the subject ≤50 chars (excluding any trailing `(#NN)` PR ref); wrap
body lines at ≤72 chars. Separate the `why:` and `what:` blocks with a
blank line.
Common commit types:
- **feat**: New features or enhancements
- **fix**: Bug fixes
- **refactor**: Code restructuring without functional change
- **docs**: Documentation updates
- **chore**: Maintenance (dependencies, tooling, config)
- **test**: Test-related updates
- **style**: Code style and formatting
- **ai(rules[AGENTS])**: AI rule updates
- **ai(claude[rules])**: Claude Code rules (CLAUDE.md)
- **ai(claude[command])**: Claude Code command changes
## Documentation Standards
### Code Blocks
Code blocks are paste-and-run units: pasting one block runs exactly one
intended action. Doctests and other executed examples are exempt — the test
suite runs them, nobody pastes them.
- **One command per block.** Multiple steps may share a block only when
explicitly chained with `&&`, `;`, or `\` continuations — the chain is
then one logical command.
- **Explanations go in prose above the block**, never as `#` comments inside it.
- **Command menus are per-command blocks with prose lead-ins**, not tables.
- **Shell commands use the `console` tag with a `$ ` prefix.** This separates
interactive commands from scripts and enables prompt-aware copy.
- **Split long commands with `\`** — one flag or flag+value pair per indented
continuation line, positional arguments last.
Good:
Show the last ten commits as a graph:
```console
$ git log \
--max-count=10 \
--graph \
--oneline
```
Bad:
```console
# Show the last ten commits as a graph
$ git log --max-count=10 --graph --oneline
```
+ ## Comments earn their maintenance cost
+
+ A comment ships only if it passes all three gates. Fail any: delete or rewrite.
+ Borderline: delete — borderline means the information is reconstructible, which
+ is what makes deletion cheap.
+
+ **Loss.** Three years from now, would losing this cost a maintainer real time
+ rediscovering intent, an invariant, a constraint, or a failure mode the code and
+ tests do not already make obvious?
+
+ **Elite.** Would SQLite, Redis, the Go standard library, or CPython write this
+ comment, at this length? Those projects state the constraint and stop. They do
+ not argue with an imagined objector.
+
+ **Upkeep.** Will it stay true without maintenance? A comment that hand-syncs a
+ value the code owns — a count, an offset, a line reference, a duplicated
+ constant — is false the first time that value moves.
+
+ ### Ceiling
+
+ One or two lines. A comment reaching four is either carrying several facts, in
+ which case split it, or arguing, in which case cut it to the fact.
+
+ Rationale, alternatives weighed, and the story of how the code got here belong
+ in the commit message: timestamped, attached to the exact diff, and free to
+ maintain.
+
+ A comment often holds both a constraint and the deliberation that found it. Keep
+ the constraint, cut the deliberation. "Runs at most once per second" survives;
+ "this is the right trade for now" does not.
+
+ ### Keep
+
+ - Why over how: upstream quirks, protocol and compatibility constraints,
+ performance tradeoffs still part of the contract.
+ - Invariants, preconditions, ordering, lifetime, and concurrency requirements
+ that types and tests cannot express.
+ - Code that looks wrong but is not, so a later cleanup does not reintroduce the
+ bug.
+ - A high-level sketch of an algorithm whose local operations do not reveal the
+ whole.
+
+ ### Delete
+
+ - Narration of the next lines; code translated into English.
+ - Restated names, types, defaults, or control flow.
+ - Values duplicated from the code and hand-synced.
+ - Justification, hedging, or apology for a choice.
+ - Speculation about future requirements.
+ - History version control already holds, including commented-out code.
+ - Ticket and issue numbers. They say nothing to a reader without tracker access,
+ and they rot when the tracker moves. Unfinished work goes in the tracker, not
+ the source.
+ - Transient observations — "currently", "for now", "the latest release" —
+ that go stale with no nearby edit.
+
+ ### The upkeep gate in practice
+
+ It reaches values that track our own code. It does not reach frozen external
+ facts.
+
+ Bad (Delete):
+
+ ```python
+ # There are 321 tests to complete for servers.
+ ```
+
+ Good (Keep):
+
+ ```python
+ # CPython < 3.11 has no ExceptionGroup, so this branch stays.
+ ```
+
+ ### Documentation exception
+
+ Doctests, minimal usage examples, and param, return, and raises lines on public
+ API are exempt from the loss gate — they serve the caller, not the maintainer.
+ They are exempt from nothing else. Ceiling: a good man page entry.
+
## AI Slop Prevention
Treat AI slop as **review-hostile noise**, not as proof that text or
code is wrong. The goal is to maximize information density by removing
artifacts that make the repository harder to trust or navigate.
### The Anti-Slop Rubric
Before committing, audit all AI-assisted changes for these noise
patterns:
- **AI Signatures:** Remove "Generated by", footers, conversational
filler ("Certainly!", "Here is..."), unexplained emojis (🤖, ✨), and
AI-tool metadata.
- **Brittle References:** Avoid hard-coded line numbers, fragile
file/test counts, dated "as of" claims, bare SHAs, and local
absolute paths unless they are strict evidentiary artifacts (e.g.,
benchmark logs).
- **Diff Narration:** Do not restate what moved, was renamed, or was
removed in artifacts the downstream reader holds: code, docstrings,
README, CHANGES, PR descriptions, or release notes. The diff and
commit message already carry this history.
- **Branch-Internal Narrative:** Do not mention intermediate branch
states, abandoned approaches, or "no longer" behavior unless users
of a published release actually experienced the old state (**The
Published-Release Test**).
- **Low-Value Scaffolding:** Remove ownerless TODOs (`TODO: revisit`),
unused future-proofing, debug artifacts, and defensive wrappers that
do not protect a currently reachable failure mode.
- **Prose Inflation:** Replace generic AI "tells" like *comprehensive,
robust, seamless, production-ready, leverage, delve, tapestry,* and
*best practices* with concrete descriptions of behavior,
constraints, or trade-offs.
- **Coded Labels:** Write rules, options, and findings as plain
imperatives. Don't tag them with codes like `[R1]`, `A1`, or
`Option B` in artifacts a human reads — the reader shouldn't have to
decode an index. Internal agent bookkeeping may use ids; shipped text
may not.
### Durable Source Links
Link to a pinned revision, never to trunk. A pinned permalink is not a
brittle reference; an unlinked SHA dropped into prose is. `blob/master/…`
links rot silently — the file moves, lines shift, and the anchor lands
on unrelated code while still resolving.
- Prefer a release tag (`blob/v1.4.0/…`). Most durable, and it tells
the reader which released version the claim held for.
- Otherwise use a 7-char commit ref (`blob/9a29b1a/…`) reachable from
trunk. Use when there is no tag or the claim is about unreleased
code. Never a PR-head SHA — it can be rebased or garbage-collected.
- Reserve `blob/master/…` for living documents meant to always show the
latest state, such as a contributing guide.
- Line anchors (`#L120-L145`) are only safe on a pinned ref.
### Preservation & Context
- **When unsure, leave the text in place and ask.** Subjective cleanup
- must never be a reason to remove load-bearing rationale.
+ Subjective cleanup must never remove load-bearing rationale. Adjudicate
+ comments with the comment policy above; borderline cases are deleted, not
+ kept.
- **Preserve the "Why":** You MUST NOT delete comments that document
invariants, protocol constraints, platform quirks, security
boundaries, and upstream workarounds.
- **Evidence is Immune:** Preserve exact counts, dates, and SHAs when
they serve as evidence in benchmark results, release notes, stack
traces, or lockfiles.
- **Behavior Over Inventory:** A useful description explains what
changed for the *system or user*; it does not provide an inventory
of files or functions the diff already shows.
### Change Discipline
- Make the smallest coherent change that solves the verified problem;
keep unrelated cleanup out of it.
- Reuse an existing file, component, helper, API, or test before adding
a new one. Modify in place when the change fits the file's
responsibility.
- Keep new APIs private until a caller outside the module needs them.
- Add a file only for a durable boundary — a distinct responsibility,
independent reuse, or splitting an oversized high-touch module — not
for a single-use helper or a one-line re-export.
### Keep Instructions Lean
Treat this file like code and prune it.
- Delete a line whose removal would not cause a mistake.
- Move multi-step procedures into skills, path-specific rules into
nested AGENTS.md files, and hard limits into hooks or CI.
- Keep only non-obvious, broadly applicable defaults here. Anything a
reader can infer from the code, a manifest, or a linter does not
belong.
## Shipped vs. Branch-Internal Narrative
Long-running branches accumulate tactical decisions — renames,
refactors, attempts-then-reverts, intermediate states. Commit messages
and the diff hold *what changed* and *why*. Do not restate either in
artifacts the downstream reader holds: code, docstrings, README,
CHANGES, PR descriptions, release notes, migration guides.
When deciding what counts as branch-internal, use trunk or the parent
branch as the baseline — not intermediate states inside the current
branch.
**The Published-Release Test**
Before adding rename history, "previously" / "formerly" / "no longer
X" phrasing, "removed" / "moved" / "refactored" / "fixed" diff
paraphrases, or `### Fixes` entries to a user-facing surface, ask:
> Did users of the most recently published release ever experience
> this old name, old behavior, or bug?
If the answer is no, it is branch-internal narrative. Move it to the
commit message and describe only the current state in the artifact.
**Keep in shipped artifacts**
- Deprecations and migration guides for symbols that actually shipped.
- `### Fixes` entries for bugs that affected users of a published
release.
- Comments explaining *why the current code looks this way* —
invariants, platform quirks, upstream bug workarounds — that make
sense to a reader who never saw the previous version.
**Default**: when in doubt, keep the artifact clean and put the story
in the commit.
### Cleanup in Hindsight
When applying this rule retroactively from inside a feature branch,
first establish scope by diffing against the parent branch (or trunk)
to identify which commits this branch actually introduced. Then:
- **Commits introduced in this branch** — prompt the user with two
options: `fixup!` commits with `git rebase --autosquash` to address
each causal commit at its source, or a single cleanup commit at
branch tip. User chooses.
- **Commits already in trunk or a parent branch** — default to
leaving them alone. Do not raise them as cleanup candidates; act
only on explicit user instruction. If the user opts in, fold the
cleanup into a single commit at branch tip and do not rewrite trunk
or parent-branch history.
- **Scope guard** — if cleaning in-branch bleed would touch a
colleague's in-flight work or expand the branch beyond its stated
goal, default to staying in lane: protect the project's current
goal, leave prior bleed alone, and don't introduce new bleed in the
current change.