chore: adopt the modern-di convention; drop planning/ and architecture/

[lesnik512]

Why

Two documentation trees carried the cost of every change and neither paid it back.

architecture/ was 12 capability pages, 612 lines, restating what faststream_outbox/ already
says. The promotion rule — "update the matching capability file in the same PR" — asked did you
update the page? and never should this paragraph exist?, so pages only ever grew.

planning/ was 63 files: 34 change files, 13 curated release notes, 6 closed audit reports, 5
decision records, 5 templates, and a validator wired into lint-ci. Of that, only some of the
decision records and one deferred item were still load-bearing. Every audit was fully closed (PRs
#61–#95). The change files duplicated what the PRs they described already recorded.

CONTEXT.md did not exist, though docs/agents/domain.md had been pointing at it as "not yet
created" for months, so the glossary rule it stated was unenforceable.

Design

Adopt the convention modern-di arrived at over PRs #424–#450.

The spec for a change is its PR body. .github/PULL_REQUEST_TEMPLATE.md carries why / design /
non-goals / verification and is reviewed with the diff. No change file, no lane. A trivial PR
deletes the template and ships a conventional-commit title.

Two things outlive the PR, one home each: a rejected alternative becomes an ADR in docs/adr/
(NNNN-slug.md, with a revisit trigger); unscheduled work becomes a GitHub issue. CLAUDE.md now
opens with the admission check that decides where a fact goes at all — derivable from the package →
don't write it; enforceable → a test; a user needs it → docs/; otherwise it does not get written.

Mechanism moves into the tests that already pinned it. The invariants turned out to be
executable already: 32 existing tests now carry an INVARIANT: docstring — the claim on line 1,
what breaks it in the second paragraph — spanning all 11 capabilities the old CLAUDE.md table
listed. This was marking, not writing. tests/test_invariant_census.py guards the shape: an
INVARIANT: docstring without a "what breaks it" paragraph fails.

One test is genuinely new. Engine ownership — "the caller owns the AsyncEngine; the broker never
disposes it" — was asserted in CLAUDE.md and pinned by nothing, and every other test constructs a
dedicated engine, so a broker that disposed it would have passed the whole suite.

The ADR corpus is two records, not five. The migration first carried all five planning/decisions/
forward; review cut it back. The doc-code-fence record declined a CI feature that was never built.
The conn-union record's contract already lives in AbstractOutboxClient's docstring, which is
where a contract belongs. The two free-threading records were one decision split in two, and the
second largely restated docs/introduction/installation.md — they merge into one holding only the
declined options. What survives is the metrics-recorder record (trimmed) and free-threading.

The BrokerUsecase-invariance rationale that planning/lint-suppressions.md carried is now a
one-line comment at each of the four suppression sites, plus a separate note on the two
invalid-method-override suppressions, which are a deliberate signature divergence rather than the
same variance rule.

CONTEXT.md is written: 16 terms, each listed only because there is a synonym to reject.

Curated release notes go with the planning tree. release.yml drops the mandatory-notes gate and
falls back to GitHub's generated notes, rendered from the squashed PR titles since the previous tag
— which is what makes the conventional-commit title on a trivial PR carry its weight.

Non-goals

• Not changing any runtime behaviour. The only faststream_outbox/ edits are five comments at
  existing suppression sites; no logic moves.
• Not adopting modern-di's docs_slug / docs/troubleshooting/ scheme. That rests on exceptions
  owning every message, which this package does not do.
• Not renaming CLAUDE.md to AGENTS.md. Worth doing, but org-wide rather than here alone —
  tracked separately.
• Not moving the PR template to the org .github repo. That repo is still on convention 2.0.0,
  so inheriting its template would contradict this one. Tracked separately.
• Not fixing the OutboxRouter routers gap. It was the only genuinely open item in
  planning/deferred.md and is now OutboxRouter does not forward routers to the inner broker #158 — it needs a design call on lifespan-start ordering and
  AsyncAPI composition, not a kwarg passthrough.

Verification

just test → 612 passed, 100.00% coverage (the gate). just lint-ci clean — ruff format,
ruff check --no-fix, ty. just docs-build clean under --strict, with docs/adr/ built so its
outgoing links are validated and not_in_nav keeping it out of the site menu.

A repo-wide sweep for planning/, architecture/, check-planning, just index, deferred.md,
and lint-suppressions returns one hit: the sentence in docs/agents/domain.md that says neither
directory exists any more. mkdocs --strict passing after the deletion is the completeness proof
for the docs side — those references resolve while the directories exist and only break once they
are gone.

[github-actions]

Benchmark gate

✅ gate passed

scenario	msg/s	delete/msg	WALrec/msg	WALB/msg	fpi	upd	del	dead_tup
consumer/w1/b10	918	1.000	6.79	918	242	5000	5000	10000
consumer/w1/b100	923	1.000	6.82	921	243	5000	5000	10000
consumer/w2/b10	1026	1.000	6.80	968	242	5000	5000	10000
consumer/w2/b100	1252	1.000	6.78	997	263	5000	5000	10000
consumer/w4/b10	919	1.000	6.74	947	243	5000	5000	10000
consumer/w4/b100	1419	1.000	6.87	1036	243	5000	5000	10000
consumer/w1/b100/tfbs100	4842	0.010	6.07	1116	243	5000	5000	10000
producer/w1/b100	2112	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/select_calls, exact; wal_records within a 10% band. msg/s, WAL bytes and total calls are informational (timing/FPI noise).