Skip to content

docs(adr): compress to 2 records in the domain-modeling format - #31

Merged
lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs
Sep 19, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Rewrites docs/adr/ from 2 records (303 words) to 2 (278 words), one paragraph each, in the shape ADR-FORMAT.md asks for. Both records pass the admission test, so nothing is dropped or merged and the numbering is unchanged; what changes is the shape. The **Decision:** lead and the **Revisit trigger:** trailer are gone from both, and each trigger that was the real boundary of its decision is folded into the prose instead of hanging off the end.

Evaluation

Each record was tested against the admission test: hard to reverse, surprising without context, the result of a real trade-off.

Old Outcome New Reason
0001 pure ASGI middleware kept 0001 A deliberate deviation from the obvious path: a reader who sees raw scope/receive/send handling will ask why not BaseHTTPMiddleware, and the anyio-task and http-only answers are not visible in the code.
0002 child container stays internal kept 0002 A public-surface boundary, and an explicit no: publishing an accessor is a name a major release has to keep working, and the reference-cycle reason for deleting the scope entry is nowhere in the code but the one-line comment.

No merges: 0001 decides the middleware's form, 0002 decides what the package exports. They meet at the ASGI scope dict but are separate trade-offs with separate reversal costs.

Citations

No citation moved, because no record was renumbered. The two that exist still resolve: tests/test_public_surface.py cites docs/adr/0002-child-container-stays-internal.md by full path in its INVARIANT: docstring, and docs/agents/domain.md names ADR-0001 plus both filenames in its file-structure block. The repo-wide sweep finds no reference to an old or dropped number.

Stale claims

None. Every concrete claim was checked against modern_di_starlette/main.py: _DIMiddleware is a plain ASGI callable, starlette_websocket_provider opens at Scope.SESSION, _CONTAINER_SCOPE_KEY is private and deleted in a finally, fetch_di_container(app) is the root-container accessor and has no per-connection counterpart, and @inject binds as a method (covered by tests/test_endpoints.py). The 0002 sentence about class-based endpoints kept its substance but dropped the issue reference, which the code and those tests now carry.

Gates

  • pytest -q tests/test_adr_citations.py: 7 passed.
  • pytest -q: 22 passed. The whole suite is unit-level and in-process via TestClient; no directory needed an external service, so none was skipped.
  • ruff format --check (24 files already formatted) and ruff check --no-fix (all checks passed), run for completeness although no Python changed.
  • eof-fixer . --check: clean.
  • lychee --offline --no-progress over both ADRs, CONTEXT.md and AGENTS.md: 4 unique links, 2 OK, 0 errors, 4 excluded.

Both records pass the admission test, so nothing is dropped or merged and the
numbering is unchanged. Each is now a single paragraph: the "**Decision:**"
lead and the "**Revisit trigger:**" trailer are gone, and each trigger that was
the real boundary of its decision is folded into the prose.
@lesnik512
lesnik512 merged commit bfc0eed into main Sep 19, 2026
8 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:29
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