Skip to content

docs(adr): compress to 3 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 4 records (1,106 words) to 3 (452 words), one paragraph each, in the shape the domain-modeling ADR format asks for. Survivors are renumbered 0001-0003 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. A record that fails it on its own but states a rule a survivor relies on was folded into that survivor as a sentence.

Old Outcome New Why
0001 no connection provider for a task kept 0001 A boundary decision: no other integration declines to seed a context, and the alternatives (bind=True everywhere, the thread-local current task) were real.
0002 no functools.wraps on the inject wrapper dropped, folded into 0002 - On its own it is a one-line "do not clean this up" note, already carried by a code comment: cheap to reverse and no genuine alternative. Its rule, __wrapped__ would point inspect.signature back at the un-rewritten signature, is now the last sentence of the variadics record it was already declared "related" to.
0003 reject variadics alongside FromDI kept, merged with 0002 0002 Same boundary: the visible signature plus by-name binding is one mechanism, and both records are guards on it. Keeps the two rejected alternatives (forward positionally, special-case args/kwargs).
0004 setup_di connects both worker signal pairs kept 0003 Four connections for two operations is the definition of surprising, and the 3.0.1 regression is the evidence that neither pair alone works.

The three **Revisit trigger:** blocks were dropped as sections. None of them was the real boundary of its decision: each restated "revisit when the constraint that forced this stops holding".

Citations

Only two existed, and both are Markdown:

  • docs/agents/domain.md file-structure example listed 0002-no-functools-wraps-on-the-inject-wrapper.md, now 0002-reject-variadics-alongside-fromdi.md.
  • Old 0002's **Related:** [ADR-0003](0003-reject-variadics-alongside-fromdi.md) link disappears with the record it lived in.

docs/agents/domain.md's ADR-0001 mention is unchanged: 0001 keeps its number, slug and subject. No Python, TOML or YAML file cites an ADR. The repo-wide sweep finds no reference to an old or dropped number.

Stale claims

None. Every concrete claim was checked against the current code:

  • _ROOT_CONTAINER_KEY, the no-context build_child_container(scope=Scope.REQUEST), the by-name call func(**bound.arguments, **resolved), the early return func for a task with no FromDI parameter, the four weak=False signal connections and the hand-copied __name__/__qualname__/__doc__/__module__ plus __signature__ all match modern_di_celery/main.py.
  • The 3.0.1 claim in old 0004 is accurate: ba2eeb7 ("open root container for non-forking worker pools") is exactly the commit that added the worker_init/worker_shutdown pair.
  • The modern-di-typer cross-reference in 0001 is real (modern-di-typer docs/adr/0002-no-connection-binding-for-a-cli.md).

One wording change rather than a correction: old 0001 described only the @inject route. The DITask base class also injects, by wrapping self.run, and it likewise builds the child with no context, so the record now states the rule without leaning on decorator ordering alone.

Gates

Gate Result
pytest -q tests/test_adr_citations.py 7 passed
pytest -q (full suite) 24 passed
ruff format --check 23 files already formatted
ruff check --no-fix all checks passed
eof-fixer . --check clean
lychee --offline --no-progress over the touched Markdown plus CONTEXT.md and AGENTS.md 4 links, 2 OK, 0 errors, 2 excluded

No Python was touched, so the lint gates are informational. Nothing was skipped: this repo's suite needs no external services, and ty check was not part of the requested gate list.

Rewrite docs/adr/ from 4 records (1106 words) to 3 (452 words), one paragraph each.

- dropped 0002 (no functools.wraps on the inject wrapper): fails the admission test on
  its own, its rule is folded into the surviving variadics record as one sentence
- 0003 reject variadics alongside FromDI -> 0002
- 0004 connect both worker signal pairs -> 0003
@lesnik512
lesnik512 merged commit 90dd95e 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