test: cover the CSS Module class-name resolution contract (tests/css-modules.test.mjs)

[hivecommons-hive]

Test Improvement

Adds tests/css-modules.test.mjs, covering the CSS Module class-name
resolution contract across the JS/CSS boundary in src/.

A CSS Module exports only the class names its stylesheet declares, so
styles.notDeclared is plain undefined property access: React renders the
element with no class attribute, docusaurus build stays green, and the
element silently loses its styling. src/ has 9 stylesheet importers and ~129
class references behind that invariant, and no existing test reads a
*.module.css — tests/validate-button-contrast.test.mjs reads only the
global src/css/custom.css.

Six assertions, in both directions:

• every import x from '*.module.css' specifier resolves to a stylesheet on disk
• every referenced class (styles.foo, styles['foo']) is declared by its stylesheet
• every declared class has a reader (skipped per-stylesheet when a file uses a computed styles[key] lookup, where the referenced set is not statically knowable)
• every composes: target resolves to a declared class
• plus two guards asserting each exemption below still describes live drift

Implementation notes: class names are read from selector preludes only, so
url(./x.png) in a declaration is not mistaken for a class, and the minified
}.note,.source { form this repo actually ships in
MetricsDashboard/styles.module.css is parsed correctly. Import statements are
stripped before the reference scan, since the specifier './styles.module.css'
otherwise reads as a styles.module reference.

Verification. npm run test:unit is green at 61 tests (55 existing + 6
new); npx prettier --check tests/css-modules.test.mjs is clean. The
assertions were mutation-tested rather than assumed: injecting an undeclared
styles.bogusMissing reference and an orphan .bogusOrphan rule fails the
forward and reverse assertions with a precise message, and declaring
.iconLink fails the staleness guard with "remove it from KNOWN_UNDECLARED".

Related Issue

Refs #319 — partial by lane constraint, not by choice. #319 asks for two
things, and this PR lands only the second box:

• Remove the two dead references in src/theme/Footer/ — still open.
  This is a production-code change (src/theme/Footer/index.js and its
  styles.module.css), which the quality lane may not PR. It needs a human
  or a production-lane agent.
• Add the contract test — this PR.

Because the production half cannot land here, the two live drifts #319
documents are pinned in explicit exemption lists instead of being fixed:

• KNOWN_UNDECLARED: src/theme/Footer/styles.module.css#iconLink
• KNOWN_ORPHANS: src/theme/Footer/styles.module.css#orgText

Both are confirmed present on main at 00b44df. This keeps the contract
enforced for all 9 importers and stops the drift spreading, while leaving the
6-line deletion to the first box. The exemptions are not permanent
carve-outs: the two staleness guards fail the moment either drift is fixed,
demanding the entry's removal, so landing box 1 tightens this test rather than
leaving a stale exemption behind. #319 stays open until then.

Disjointness: this PR touches only the new tests/css-modules.test.mjs. #347
(tests/css-variables.test.mjs) covers var(--x) custom-property resolution —
different names, different namespace; #343 covers JSX link/image hygiene; #317
covers custom.css → static/fonts/, a global stylesheet not scanned here;
#229 covers filterArchitectures; #268 covers useFocusTrap. No open PR reads
CSS Module class names or touches src/theme/Footer/**.

---

Filed by quality agent (hold-gated mode). Human review required.

— hive: agent=quality backend=copilot model=claude-opus-5

[hivecommons-hive]

Important

Held for human review by the hive's ACMM level gate.

This PR was opened by the "quality" agent while Hive policy required a human checkpoint for that agent. Non-outreach agents are held at ACMM L3–L5; the outreach agent is always held because it publishes project-facing communication.

Hive will automatically remove the hold label once current policy no longer requires a level hold for "quality". If this is an outreach PR, a human must review it and remove the label.