docs(agents): drop the fact-placement convention from AGENTS.md - #188
Merged
Conversation
Where a fact goes, its admission check, the ADR references and the PR-body spec rule all go; doc placement is a domain-modeling convention. The INVARIANT: docstring shape stays.
lesnik512
force-pushed
the
docs/drop-adr-convention-from-agents-md
branch
from
September 7, 2026 05:25
b9ec8ef to
ccb24f8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
AGENTS.md carried a per-repo copy of a doc-placement convention: a four-homes table, an admission check to run "before writing a line anywhere", an ADR row prescribing
NNNN-slug.mdand revisit triggers, a ratchet rule, and an index of the repo's ADRs.Doc placement is a domain-modeling convention. Restating it per repo means 25 copies that can drift from it, in a file loaded on every turn — the failure the removed text itself named: "it is always loaded, so a line that restates a docstring… costs every turn and rots in two places at once."
The local ADR rule was also weaker than the convention it duplicated: no reversibility gate, so any non-obvious rejected alternative qualified. That is how a since-dropped ADR rejecting a gRPC bootstrapper got written — trivially reversible, nothing built, and it would have been filtered before its argument was examined.
Design
AGENTS.mdgoes from 103 lines to 56. Removed:### Where a fact goessection in full — four-homes table, the "before writing a line anywhere" admission check, "prose about mechanism has no home", the ratchet rulegrep -i adr AGENTS.mdnow returns nothing.Kept: Project Overview, Commands, Architecture's file-layout paragraph, Code style, Type checking, one Workflow fact (unscheduled work becomes an issue), and the
INVARIANT:docstring shape.Non-goals
docs/adr/and its nine records are untouched — only the prose that indexed them and prescribed when to write one.Companion change
modern-dienforces theINVARIANT:docstring shape withtests/test_invariant_census.py; that test is being dropped separately. The shape stays documented in AGENTS.md and unenforced by CI, checked at review time — which is what this file now says.Verification
grep -i adr AGENTS.md→ no matches.eof-fixer. Every removed markdown link was relative to a target that still exists, so the lychee gate is unaffected.