Skip to content

docs: merge the upsert ADRs, drop replaced and non-ADR records, renumber - #62

Merged
lesnik512 merged 1 commit into
mainfrom
docs/adr-cleanup
Oct 17, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/adr-cleanup

Conversation

@lesnik512

Copy link
Copy Markdown
Member

This PR tidies up docs/adr/ and changes the rule for replaced records.

Rule change

docs/adr/README.md used to keep a replaced ADR in place with superseded_by frontmatter. Now the reasoning that still holds moves into the new record and the old file is deleted, since git history keeps it. With that, every file in the directory is a current decision, so ADRs carry no frontmatter.

Records

Before After Change
0005 upsert via DuplicateKeyError recovery deleted Replaced by the upsert. Its lasting point, that a pre-read can't make the insert safe, moved into the new 0011.
0012 message send is one upsert, 0013 direct chat is one upsert 0011 idempotent creates are one upsert Merged: same statement, same xmax check, same rejected options. This also removes the duplicate 0012.
0009 coverage exclusions deleted Fails "hard to reverse". The rule now sits under Conventions in AGENTS.md.
0006 idempotency scoped per chat 0005 Trimmed the bug history to two sentences.
0007 read-marker integrity 0006 Kept the API behaviour: reject ids from other chats, silent no-op for a lower id. The IS DISTINCT FROM and monotonic details now live in INVARIANT: docstrings on test_system_messages_count_as_unread and test_marking_read_is_monotonic. The reason GREATEST runs inside the UPDATE was already in ChatMembersRepository.mark_read's docstring.
0008, 0010, 0011, 0012 pool pre-ping 0007, 0008, 0009, 0010 Renumbered only. The logout ADR's link to the actor-id ADR moved with it.

Nothing outside docs/adr/ cites an ADR by number. docs/agents/domain.md cites ADR-0001, which keeps its number.

Verification

Run locally: just adr-check, ruff, ty, and the full suite (141 passed, 100% coverage).

ADRs that a later decision replaces are now deleted once their reasoning moves
into the new record.
@lesnik512
lesnik512 merged commit 791ee7b into main Oct 17, 2026
4 checks passed
@lesnik512
lesnik512 deleted the docs/adr-cleanup branch October 17, 2026 08: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