ai(rules[AGENTS]) add AI slop prevention standards

tony · tony · commit 2e46eb52daa3 · 2026-05-23T14:16:59.000-05:00
why: AI-assisted contributions need clear signals to reduce noise
and preserve technical context beyond simple narrative bleed.
what:
- Expand narrative bleed rules into full AI Slop Prevention rubric
- Add specific prohibitions for AI signatures and prose inflation
- Include safety guardrails to preserve load-bearing context
diff --git a/AGENTS.md b/AGENTS.md
@@ -534,59 +534,89 @@ When stuck in debugging loops:
 3. **Document the issue** comprehensively for a fresh approach
 4. Format for portability (using quadruple backticks)
 
-## Shipped vs. Branch-Internal Narrative
+## 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.
+
+### Preservation & Context
+
+**When unsure, leave the text in place and ask.** Subjective cleanup
+must never be a reason to remove load-bearing rationale.
+
+- **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.
+
+### The Published-Release Test
 
 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:
+refactors, attempts-then-reverts. When deciding what counts as
+branch-internal, use trunk or the parent branch as the baseline — not
+intermediate states inside the current branch. 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**
+If the answer is **no**, it is branch-internal narrative. Move it to
+the commit message and describe only the final 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.
+- Comments explaining *why the current code looks this way*
+  (invariants, platform quirks) that make sense to a reader who never
+  saw the previous version.
 
 ### Cleanup in Hindsight
 
-When applying this rule retroactively from inside a feature branch,
+When applying these rules 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.
+- **In-branch commits:** 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.
+- **Trunk/Parent commits:** Default to leaving them alone. Act only on
+  explicit user instruction. If the user opts in, fold the cleanup
+  into a single commit at branch tip; do not rewrite shared history.
+- **Scope guard:** If cleaning prior slop would touch a colleague's
+  work or expand the branch beyond its stated goal, stay in lane:
+  protect the current goal and leave prior slop alone.
+
