feat: 2.x bridges for the 3.0 breaks — validation UX, ContextProvider deprecation, to-3.x guide

[lesnik512]

What

The 2.x-shippable half of the 3.0-gated trio ruled in the 2026-07-05 UX research (API-1/ERR-2, ERR-5, API-6, DOC-1). Bundle: planning/changes/2026-07-05.04-v3-bridges/.

• ERR-5 — ValidationFailedError now groups errors by kind with indented multi-line sub-errors; CircularDependencyError renders its cycle as a multi-line arrow chain (message text only; .errors/.cycle_path unchanged).
• API-1 bridge — Container(validate=) is tri-state (bool | None = None): unset on a root emits the new UnvalidatedContainerWarning (FutureWarning) pointing at the migration guide; explicit False opts out silently, also after 3.0; children never warn.
• API-6 bridge — direct resolve of an unset ContextProvider emits ContextValueNoneWarning (DeprecationWarning) and still returns None; ContextValueNotSetError ships now, raised in 3.0. Dependent-parameter dispositions untouched.
• DOC-1 — docs/migration/to-3.x.md: all five 3.0 switches with before/after code and an empirically verified readiness recipe (module-scoped filters were tested and dropped — they miss 3 of 5 signals due to stacklevel attribution; the page documents this).
• architecture/ promotions + regenerated troubleshooting outputs ride along.

Notable implementation notes

• The repo-suite warning silence uses a message-based pytest filter: the dotted-class form (ignore::modern_di.exceptions...) imports the package at config time, before coverage tracing starts, collapsing coverage to 89% (bisected + independently reproduced in review). A drift-guard test pins the filter to the live message.
• No behavior flips: validate=None provably does not validate (pinned by test_unset_validate_warns_but_does_not_validate); the flips land in the cut-3.0 bundle.

Before tagging the next 2.x minor (not merge-gating)

1. Audit sibling integration repos for internal bare root Container(...) constructions — they'd surface UnvalidatedContainerWarning to downstream users; coordinate releases passing explicit validate=.
2. Release notes must cover: three new warning/error classes, the changed str() shapes of the two validation errors (downstream pytest.raises(match=...) on old one-line text will break), and that ~46 docs samples still construct bare roots (follow-up docs pass planned: samples adopt validate=True).

Process

Subagent-driven: 6 tasks, fresh implementer + spec/quality reviewer per task, two fix loops (empty-message rendering guard; py3.10 ty regression caught by re-review against the CI-pinned environment), final whole-branch review verdict: ready to merge. Gates: just test-ci 269 passed / 100% coverage, just lint-ci, just docs-build --strict, just check-planning.

🤖 Generated with Claude Code