feat(core): add color/contrast-aa rule

[aram-devdocs]

Spec

Closes #68

Summary

• add color/contrast-aa in plumb-core with WCAG 2.1 AA thresholds, large-text classification, relative-luminance contrast math, and composited background resolution from existing computed styles only
• add a golden snapshot fixture plus rule-local unit tests that cover the 24px regular / 18.5px bold boundary and ancestor background resolution
• register the rule and wire its docs through the book index, summary, configuration reference, and MCP explain_rule table

Validation

Confirmed in this environment:

• cargo test -p plumb-core --test golden_color_contrast_aa --features test-fake -- --nocapture
• cargo test -p plumb-core --all-features
• cargo test -p plumb-mcp explain -- --nocapture
• cargo clippy -p plumb-core --all-targets --all-features -- -D warnings
• cargo fmt --all -- --check
• cargo check --workspace --all-features
• git diff --check

Environment blockers:

• cargo test -p plumb-core without --all-features fails in this repo because integration tests call PlumbSnapshot::canned(), which is gated behind plumb-core/test-fake
• cargo xtask pre-release fails here because Python lacks the yaml module required by the runbook validator
• just validate cannot run here because just is not installed

Breaking change?

• No
• Yes — describe the migration path

Anything reviewers should double-check

• a11y.min_contrast_ratio now acts as a stricter global floor on top of WCAG AA defaults; the default behavior remains fixed at 4.5:1 for normal text and 3.0:1 for large text.

[github-actions]

Here is the review from the general-purpose reviewer for the local diff (main...HEAD), which covers three commits adding the color/contrast-aa rule:

---

Plumb Code Review — color/contrast-aa rule

Commits reviewed: 4872ced, 8cc1cde, 0650777
Buckets touched: plumb-core, plumb-format (SARIF snapshot), plumb-mcp (explain table), docs

---

Blockers

None.

---

Warnings

W1 — crates/plumb-core/src/rules/color/contrast_aa.rs ~L102/217
The f32::EPSILON alpha-opaque check is correct in practice (since parse_css_color only returns exactly 1.0_f32 for no-alpha-channel paths), but this is a silent invariant. A one-line comment confirming it would prevent a future reader from widening the tolerance incorrectly.

W2 — crates/plumb-core/src/rules/color/contrast_aa.rs (check fn)
parent_index and nodes_by_dom_order are rebuilt from scratch on every Rule::check() invocation — O(n) per rule per viewport, repeated for every registered rule. This is an architectural limitation of the current Rule trait (no shared-state slot), not a defect in this PR. Acceptable today; worth a tracking issue if profiling shows it.

W3 — crates/plumb-core/tests/golden_color_contrast_aa.rs fixture comments
The comments mapping nth-child(N) → px size are accurate but the dom_order mapping is implicit. On a complex fixture this creates selector-confusion risk for future authors. A short table in the fixture doc comment would help. No functional impact.

---

Architecture compliance

Check	Status
No new unsafe outside plumb-cdp	PASS
No unwrap/expect/panic! in library crates	PASS
No println!/eprintln! outside plumb-cli	PASS
No SystemTime::now/Instant::now in plumb-core	PASS
No HashMap/HashSet in observable output	PASS — IndexMap used throughout
No todo!/unimplemented!/dbg!	PASS
Rule has golden test	PASS — golden_color_contrast_aa.rs + committed snapshot
Rule registered in register_builtin	PASS
docs/src/rules/color-contrast-aa.md present	PASS
MCP RULE_DOCS table updated	PASS
SARIF snapshot updated	PASS — ruleIndex incremented correctly
Layer discipline (plumb-core imports only)	PASS
doc_url slug matches explain.rs	PASS
No AI-vocabulary in docs	PASS
No commented-out code / open-ended TODOs	PASS

---

Correctness

• WCAG 2.1 luminance formula is correct (palette sRGB linearisation → 0.2126R + 0.7152G + 0.0722B).
• Large-text cutoffs are correct: 24.0 px (18 pt) and ≈18.667 px (14 pt bold, using 14 × 96/72).
• Boundary fixture exhaustively covers 18 px / 18.6 px / 19 px at font-weight: 700 — all three snapshot entries are consistent with computed ratios.
• Porter-Duff compositing is correct; background walk stops at the first opaque ancestor.
• Determinism: IndexMap throughout, three-run determinism test present, output sorted by (rule_id, viewport, selector, dom_order).
• At most one violation per node per viewport — satisfied.
• min_contrast_ratio config knob is a floor (ratio.max(...)), not a replacement — confirmed by the config.a11y.min_contrast_ratio = Some(7.0) test case.

---

Verdict: APPROVE