Skip to content

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

Merged
lesnik512 merged 2 commits into
mainfrom
docs/drop-fact-placement-convention
Sep 7, 2026
Merged

docs(agents): drop the fact-placement convention from AGENTS.md#171
lesnik512 merged 2 commits into
mainfrom
docs/drop-fact-placement-convention

Conversation

@lesnik512

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, 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:

  • 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
  • Workflow'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 present

Kept:

  • the INVARIANT: docstring shape, with its ADR and lychee clauses trimmed
  • one Workflow fact: unscheduled work becomes a GitHub issue
  • every other section, unchanged
  • inline docs/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

  • No ADR is changed, removed or renumbered. docs/adr/ is untouched.
  • No code or test changes.

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.

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.
@github-actions

github-actions Bot commented Sep 7, 2026

Copy link
Copy Markdown

Benchmark gate

✅ gate passed

scenario msg/s delete/msg WALrec/msg WALB/msg fpi upd del dead_tup
consumer/w1/b10 889 1.000 6.80 918 242 5000 5000 10000
consumer/w1/b100 874 1.000 6.84 920 243 5000 5000 10000
consumer/w2/b10 1036 1.000 6.79 959 242 5000 5000 10000
consumer/w2/b100 1264 1.000 6.78 994 263 5000 5000 10000
consumer/w4/b10 955 1.000 6.67 921 243 5000 5000 10000
consumer/w4/b100 1450 1.000 6.86 1035 243 5000 5000 10000
consumer/w1/b100/tfbs100 5183 0.010 6.07 1116 243 5000 5000 10000
producer/w1/b100 2154 0.000 3.04 584 0 0 0 0

Gated (fails the build): delete_calls + tuple counters (upd/del/ins) + the producer's insert_calls, exact; select_calls within +2; wal_records within a 10% band. msg/s, WAL bytes and total calls are informational (timing/FPI noise).

The remaining docs/adr/ references were citations inside architecture prose,
or an index of them. The prose stays; the pointers go.
@lesnik512
lesnik512 merged commit 68a5b6b into main Sep 7, 2026
9 checks passed
@lesnik512
lesnik512 deleted the docs/drop-fact-placement-convention branch September 7, 2026 05:50
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