AGENTS.md: cut history from comments rather than labelling it in place

[willhea]

Changes three lines in Comments and rationale so the section's lead agrees with the bullets under it.

The problem

The lead currently says:

History and rejected alternatives are not deleted — they are labelled

Read as a default, that is permission to keep them, and the result is source that narrates its own debugging. Concretely, from a recent branch:

"""Only genuine acquisition code may bypass the bill rules (gap G2).

... Measured before any ceiling existed -- adding ``src/deltatrack/similarity.py``
to ``_DOWNLOAD_TIER_FILES`` and planting a real committed-fixture path in that
module left this module at 29 passed and the whole non-browser suite green.

Membership is enumerated, not bounded by prefix. A ``tools/``/``tests/`` prefix
bound was tried first and is not enough: ... with this module still at 30 passed.
...
"""

Twenty-seven lines, of which about six describe the invariant. The rest is a transcript of how it was found: pass counts, a rejected design, a corpus measurement, and justification for a test that no longer exists.

Nothing there violates the "label it" rule — it is all accurate. It is just material that belongs to the change rather than to the file.

The change

The default becomes cut, with labelling kept for the narrow case it was written for.

• Lead: history and rejected alternatives are cut, not carried — the PR and the issue already hold them, they outlive the session that produced them, and neither can silently contradict the code the way a comment can. Label what genuinely must stay.
• Label anything that is not current → Prefer removing what is not current; label what survives, naming the four things that most often should go (mutation counts, rejected designs, debugging measurements, explanations of deleted code).
• One new bullet for the judgement call: write what would still be true if the bug had never happened. An invariant, an unusual flag, a non-obvious exit code and the sibling that owns the other half of a check all pass that test; how the defect was found does not.

Why this is a correction, not a new rule

The bullets already said it, which is what makes the lead worth fixing rather than extending:

• "The measurement, the rejected design and the argument belong in the issue."
• "A number describing current state needs a gate or a repro." — a corpus count in a docstring has neither.
• "Past about six lines, ask whether it is a decision."

The lead was the one sentence pointing the other way, so it is the one that got followed.

No new section, and nothing about audits or reports — Research artifacts are working material already covers those, including the retention bar and the instruction not to write a closure document.

Verification

test_docs_consistency, test_adr_index, test_build_validation	43 passed
full non-browser suite	3821 passed, rc=0
diff	1 file, 3 lines

Adoption

Deliberately not a repo-wide rewrite. The existing verbose docstrings stay until something else edits them; new and touched code follows the terser style, which means the two will coexist for a while. #720 and #721 already do it this way.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NwVE7osYo39KaUe7CEitFJ

[willhea]

Closing: not needed. AGENTS.md already requires this — "the tail points, it does not narrate" sends the measurement and the rejected design to the issue, numbers need a gate or a repro, and anything past about six lines should be a decision record. The verbose docstrings that prompted this broke those rules rather than exposing a gap in them. The fix is to follow the file, which #720 and #721 now do.