@@ -296,59 +296,89 @@ These rules apply when authoring entries in `CHANGES`, which is rendered as the
296296- Repository: https://github.com/vcs-python/g
297297- Shared tooling (gp-libs): https://gp-libs.git-pull.com/
298298
299- ## Shipped vs. Branch-Internal Narrative
299+ ## AI Slop Prevention
300+
301+ Treat AI slop as ** review-hostile noise** , not as proof that text or
302+ code is wrong. The goal is to maximize information density by removing
303+ artifacts that make the repository harder to trust or navigate.
304+
305+ ### The Anti-Slop Rubric
306+
307+ Before committing, audit all AI-assisted changes for these noise
308+ patterns:
309+
310+ - ** AI Signatures:** Remove "Generated by", footers, conversational
311+ filler ("Certainly!", "Here is..."), unexplained emojis (🤖, ✨), and
312+ AI-tool metadata.
313+ - ** Brittle References:** Avoid hard-coded line numbers, fragile
314+ file/test counts, dated "as of" claims, bare SHAs, and local
315+ absolute paths unless they are strict evidentiary artifacts (e.g.,
316+ benchmark logs).
317+ - ** Diff Narration:** Do not restate what moved, was renamed, or was
318+ removed in artifacts the downstream reader holds: code, docstrings,
319+ README, CHANGES, PR descriptions, or release notes. The diff and
320+ commit message already carry this history.
321+ - ** Branch-Internal Narrative:** Do not mention intermediate branch
322+ states, abandoned approaches, or "no longer" behavior unless users
323+ of a published release actually experienced the old state (** The
324+ Published-Release Test** ).
325+ - ** Low-Value Scaffolding:** Remove ownerless TODOs (` TODO: revisit ` ),
326+ unused future-proofing, debug artifacts, and defensive wrappers that
327+ do not protect a currently reachable failure mode.
328+ - ** Prose Inflation:** Replace generic AI "tells" like * comprehensive,
329+ robust, seamless, production-ready, leverage, delve, tapestry,* and
330+ * best practices* with concrete descriptions of behavior,
331+ constraints, or trade-offs.
332+
333+ ### Preservation & Context
334+
335+ ** When unsure, leave the text in place and ask.** Subjective cleanup
336+ must never be a reason to remove load-bearing rationale.
337+
338+ - ** Preserve the "Why":** You MUST NOT delete comments that document
339+ invariants, protocol constraints, platform quirks, security
340+ boundaries, and upstream workarounds.
341+ - ** Evidence is Immune:** Preserve exact counts, dates, and SHAs when
342+ they serve as evidence in benchmark results, release notes, stack
343+ traces, or lockfiles.
344+ - ** Behavior Over Inventory:** A useful description explains what
345+ changed for the * system or user* ; it does not provide an inventory
346+ of files or functions the diff already shows.
347+
348+ ### The Published-Release Test
300349
301350Long-running branches accumulate tactical decisions — renames,
302- refactors, attempts-then-reverts, intermediate states. Commit messages
303- and the diff hold * what changed* and * why* . Do not restate either in
304- artifacts the downstream reader holds: code, docstrings, README,
305- CHANGES, PR descriptions, release notes, migration guides.
306-
307- When deciding what counts as branch-internal, use trunk or the parent
308- branch as the baseline — not intermediate states inside the current
309- branch.
310-
311- ** The Published-Release Test**
312-
313- Before adding rename history, "previously" / "formerly" / "no longer
314- X" phrasing, "removed" / "moved" / "refactored" / "fixed" diff
315- paraphrases, or ` ### Fixes ` entries to a user-facing surface, ask:
351+ refactors, attempts-then-reverts. When deciding what counts as
352+ branch-internal, use trunk or the parent branch as the baseline — not
353+ intermediate states inside the current branch. Ask:
316354
317355> Did users of the most recently published release ever experience
318356> this old name, old behavior, or bug?
319357
320- If the answer is no, it is branch-internal narrative. Move it to the
321- commit message and describe only the current state in the artifact.
322-
323- ** Keep in shipped artifacts**
358+ If the answer is ** no** , it is branch-internal narrative. Move it to
359+ the commit message and describe only the final state in the artifact.
324360
361+ ** Keep in shipped artifacts:**
325362- Deprecations and migration guides for symbols that actually shipped.
326363- ` ### Fixes ` entries for bugs that affected users of a published
327364 release.
328- - Comments explaining * why the current code looks this way* —
329- invariants, platform quirks, upstream bug workarounds — that make
330- sense to a reader who never saw the previous version.
331-
332- ** Default** : when in doubt, keep the artifact clean and put the story
333- in the commit.
365+ - Comments explaining * why the current code looks this way*
366+ (invariants, platform quirks) that make sense to a reader who never
367+ saw the previous version.
334368
335369### Cleanup in Hindsight
336370
337- When applying this rule retroactively from inside a feature branch,
371+ When applying these rules retroactively from inside a feature branch,
338372first establish scope by diffing against the parent branch (or trunk)
339373to identify which commits this branch actually introduced. Then:
340374
341- - ** Commits introduced in this branch** — prompt the user with two
342- options: ` fixup! ` commits with ` git rebase --autosquash ` to address
343- each causal commit at its source, or a single cleanup commit at
344- branch tip. User chooses.
345- - ** Commits already in trunk or a parent branch** — default to
346- leaving them alone. Do not raise them as cleanup candidates; act
347- only on explicit user instruction. If the user opts in, fold the
348- cleanup into a single commit at branch tip and do not rewrite trunk
349- or parent-branch history.
350- - ** Scope guard** — if cleaning in-branch bleed would touch a
351- colleague's in-flight work or expand the branch beyond its stated
352- goal, default to staying in lane: protect the project's current
353- goal, leave prior bleed alone, and don't introduce new bleed in the
354- current change.
375+ - ** In-branch commits:** Prompt the user with two options: ` fixup! `
376+ commits with ` git rebase --autosquash ` to address each causal commit
377+ at its source, or a single cleanup commit at branch tip.
378+ - ** Trunk/Parent commits:** Default to leaving them alone. Act only on
379+ explicit user instruction. If the user opts in, fold the cleanup
380+ into a single commit at branch tip; do not rewrite shared history.
381+ - ** Scope guard:** If cleaning prior slop would touch a colleague's
382+ work or expand the branch beyond its stated goal, stay in lane:
383+ protect the current goal and leave prior slop alone.
384+
0 commit comments