Skip to content

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

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 3 records (~740 words) to 2 (~300 words), one paragraph each, in the shape ADR-FORMAT.md asks for. Survivors are renumbered 0001-0002 in their original order and every citation moves with them.

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 dialog support is a submodule kept 0001 Packaging and public-API boundary, genuinely costly to undo, and the rejected alternative (a separate modern-di-aiogram-dialog distribution, matching every other integration) is the obvious one.
0002 per-update context stays a literal dropped - The context dict is internal to _DiMiddleware; routing it through integrations.bind is a three-line, zero-risk change, so the decision is not hard to reverse, and the alternative was rejected on length rather than on a constraint. No survivor relies on a rule it states, so nothing needed folding.
0003 no auto_inject for dialogs kept, renumbered 0002 A user who sets auto_inject=True and finds dialog getters untouched will ask why; the answer is the structural constraint 0001 protects, so it is a real scope decision with a real alternative.

No merges: 0001 answers where dialog support lives, 0002 answers how far the sweep reaches. They share a constraint but not a question.

Citations moved

The only ADR citation in the repo is docs/agents/domain.md, which names ADR-0001 as its worked example of flagging a conflict; 0001 keeps its number, so the reference is unchanged. The file-structure block in the same file listed 0002-per-update-context-stays-a-literal.md and now lists 0002-no-auto-inject-for-dialogs.md. No Python, TOML or workflow file cites an ADR. The repo-wide sweep after editing finds no old or dropped number.

Stale claims corrected

  • 0003 described the sweep as rewriting "the callback on every HandlerObject it finds". _inject_router skips the update observer and skips any callback integrations.is_injected already marks; 0002 now says so.
  • 0003's "Dishka, the comparable integration, draws the line in the same place" was dropped rather than restated: it is a claim about another project that nothing in this repo verifies.
  • Dropped 0002 claimed modern-di's kit "records aiogram as the documented Layer-1 outlier". The installed modern_di 3.4.0 integrations.py module docstring describes Layer 1 and Layer 2 but names no framework, and aiogram appears nowhere in that package. The record also dated the kit to modern-di 2.28 while this package now pins modern-di>=3,<4. Both go away with the record.
  • 0001 said a separate distribution would have to re-export "this package's marker and private child-container key". dialog.py imports FromDI and the private helper _fetch_child_container, not the key constant; 0001 now says "its private container lookup".

Gates

Gate Result
pytest -q tests/test_adr_citations.py 7 passed
pytest -q (full suite) 27 passed; no directory needs external services, so none was skipped
ruff format --check 25 files already formatted
ruff check --no-fix all checks passed
eof-fixer . --check clean
lychee --offline --no-progress over both ADRs, docs/agents/domain.md, CONTEXT.md, AGENTS.md 3 OK, 0 errors, 3 excluded

No Python changed, so the two Python gates only confirm the tree is still clean.

Drop 0002 (per-update context stays a literal): the context dict is internal
and swapping it for two `bind` calls costs nothing, so the record fails the
hard-to-reverse and real-trade-off halves of the admission test.

Renumber 0003 (no auto_inject for dialogs) to 0002, keeping the original
relative order. No merges. Both survivors become one paragraph each, and the
`_inject_router` description is corrected to what the code does now.
@lesnik512
lesnik512 merged commit ddf0643 into main Sep 19, 2026
8 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:27
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