docs(agents): drop the fact-placement convention from AGENTS.md - #171
Merged
Conversation
Where a fact goes, its admission check and the ADR convention all go; doc placement is a domain-modeling convention. The INVARIANT: docstring shape stays.
Benchmark gate✅ gate passed
Gated (fails the build): |
The remaining docs/adr/ references were citations inside architecture prose, or an index of them. The prose stays; the pointers go.
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.mdcarried 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 prescribingNNNN-slug.mdand revisit triggers, and a ratchet rule.Doc placement is a domain-modeling convention. Restating it in every 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: it had no reversibility gate, so any non-obvious rejected alternative qualified.
Piloted and merged in
lite-bootstrap(#188); this applies the same cut here.Design
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 ruleWorkflow's "the spec for a change is its PR body" rule, the "two things outlive the PR" ADR sentence, "there is no change file and no lane to choose", and "there is no separate truth-home directory"Architecture's "behaviour detail has no prose home… run the admission check" tail, where presentKept:
INVARIANT:docstring shape, with its ADR and lychee clauses trimmedWorkflowfact: unscheduled work becomes a GitHub issuedocs/adr/citations inside architecture prose. Those cite a specific decision at the point it is relevant; they are not the convention being dropped.No replacement pointer is added, by design.
Non-goals
docs/adr/is untouched.Verification
The remaining
docs/adr/mentions in this file, if any, are inline citations to specific decisions, not a rule about when to write one.