Skip to content

docs(agents): drop the fact-placement convention from AGENTS.md - #188

Merged
lesnik512 merged 1 commit into
mainfrom
docs/drop-adr-convention-from-agents-md
Sep 7, 2026
Merged

docs(agents): drop the fact-placement convention from AGENTS.md#188
lesnik512 merged 1 commit into
mainfrom
docs/drop-adr-convention-from-agents-md

Conversation

@lesnik512

@lesnik512 lesnik512 commented Sep 7, 2026

Copy link
Copy Markdown
Member

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.md and 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.md goes from 103 lines to 56. Removed:

  • the ### Where a fact goes section in full — four-homes table, the "before writing a line anywhere" admission check, "prose about mechanism has no home", the ratchet rule
  • Architecture's "why four shapes are load-bearing" list and its five ADR links, plus the "Behaviour detail has no prose home… run the admission check" tail
  • Workflow's "the spec for a change is its PR body" rule, "there is no change file and no lane to choose", and "there is no separate truth-home directory"

grep -i adr AGENTS.md now 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

  • No ADR is changed, removed or renumbered. docs/adr/ and its nine records are untouched — only the prose that indexed them and prescribed when to write one.
  • No test is changed here.
  • No replacement pointer to the convention is added, by design.
  • This is the pilot for the same edit across 24 other repos; those are separate PRs and none is open.

Companion change

modern-di enforces the INVARIANT: docstring shape with tests/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.
  • No dangling cross-reference: the only pointer to Where a fact goes was the Architecture tail, removed in the same change.
  • Trailing newline preserved for eof-fixer. Every removed markdown link was relative to a target that still exists, so the lychee gate is unaffected.

@lesnik512 lesnik512 changed the title docs(agents): drop the ADR convention from AGENTS.md docs(agents): drop the fact-placement convention from AGENTS.md Sep 7, 2026
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
lesnik512 force-pushed the docs/drop-adr-convention-from-agents-md branch from b9ec8ef to ccb24f8 Compare September 7, 2026 05:25
@lesnik512
lesnik512 merged commit 63da333 into main Sep 7, 2026
12 checks passed
@lesnik512
lesnik512 deleted the docs/drop-adr-convention-from-agents-md branch September 7, 2026 05:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant