docs: chromium exact-pin to version range ADR (refs #117 #118 #126)

[aram-devdocs]

Summary

Phase 1 remediation follow-up for PR #126 (issues #117 / #118). PR #126 merged before the Claude review thread reached approval; this PR captures the durable rationale that should have shipped alongside the code change.

ADR 0002 covers:

• Why the original exact-pin Chromium gate became a MIN_SUPPORTED_CHROMIUM_MAJOR..=MAX_SUPPORTED_CHROMIUM_MAJOR range, and what each bound represents.
• The contract for moving the upper bound: re-run cargo test -p plumb-cdp --features e2e-chromium against the candidate major (including the byte-identical determinism check) and land the constant bump in the same PR as the verification work.
• The new fail-loud behavior of the e2e-chromium test suite — ChromiumNotFound and UnsupportedChromium propagate by default; PLUMB_E2E_CHROMIUM_SKIP=1 is the explicit opt-in for hosts without Chromium.
• The current range 131..=150 and how subsequent ADRs are required when widening crosses a Chromium release that changes DOMSnapshot output.

The book index (docs/src/adr.md) is updated to link the new ADR.

Why this is an ADR (not just a docs note)

crates/plumb-cdp/CLAUDE.md records the invariant: "Widening or shifting the range needs an ADR." This ADR exists so a future contributor reading the constants in plumb-cdp/src/lib.rs finds the rationale and the validation procedure in one place.

Test plan

• mdbook build (CI Docs job) succeeds with the new entry.
• cargo doc --workspace --no-deps (CI Docs job) succeeds — no rustdoc-link change.
• bash scripts/check-agents-md.sh — passes locally; AGENTS.md scope contract unchanged.
• Conventional Commits — docs(adr): … first line, scope under 72 chars.
• No source code touched — cargo fmt, cargo clippy, and cargo test jobs run unchanged.

Refs #117, #118, #126.

🤖 Generated with Claude Code

[github-actions]

This PR adds only two Markdown files. Items 1–4 (determinism, layering, error handling, test coverage) are not applicable — there are no code changes. The review focuses on documentation accuracy and convention adherence.

---

Documentation review

Technical accuracy — all symbols verified against the codebase:

ADR claim	Code location	Result
MIN_SUPPORTED_CHROMIUM_MAJOR = 131	crates/plumb-cdp/src/lib.rs:62	✓
MAX_SUPPORTED_CHROMIUM_MAJOR = 150	lib.rs:67	✓
validate_chromium_product_major fn name	lib.rs:536	✓
CdpError::UnsupportedChromium { min_supported, max_supported, found }	lib.rs:151-159	✓ exact field names
chromium_driver_snapshot_is_byte_identical	tests/driver_contract.rs:206	✓
PLUMB_E2E_CHROMIUM_SKIP env var	driver_contract.rs:85	✓
chromium_install_hint	lib.rs:448	✓
crates/plumb-cdp/CLAUDE.md invariant clause	exists, matches	✓
docs/src/install-chromium.md range reference	exists, correct	✓

AI-writing check (docs/CLAUDE.md mandatory humanizer list): No flagged phrases found in either file. Prose is direct and specific.

RFC 2119 usage: MUST used correctly in the version-range contract (§2 checklist). No lowercase ambiguity for normative statements.

docs/src/SUMMARY.md: ADRs link to GitHub, not mdBook pages — consistent with ADR 0001. No SUMMARY.md entry needed.

---

Punch list

docs/adr/0002-chromium-version-range.md, §3 (wording imprecision — non-blocker):
"the workspace test job no longer activates the e2e-chromium feature, so out-of-range hosts do not silently pass" — the conclusion doesn't follow. If the feature isn't activated, those tests don't run at all; "do not silently pass" conflates no-run with a passing test. Better: "so missing or out-of-range Chromium has no effect on the CI pass/fail signal." Also, no longer implies CI previously activated it; the current ci.yml has no record of that. Consider dropping no longer unless PR #126 explicitly removed it.

docs/adr/0002-chromium-version-range.md, Supersedes field (convention drift — non-blocker):
The Supersedes field references a code change (plumb-cdp's exact-pin gate), not a prior ADR. ADR 0001 omits this field entirely when there's nothing to supersede. Standard practice: remove the field or write "N/A — no prior ADR for Chromium version gating." Using it to point at code conflates ADR lineage with implementation history.

Historical claim in §4 (unverifiable from codebase):
"the e2e suite was confirmed against a host with Chrome 139 in that window (PR #126 test plan)" — this is the author's assertion; no code artifact corroborates it. Acceptable for an ADR, but the author should stand behind it.

---

Verdict: APPROVE