[Epic] Refactor for maintainability + parallel-safe swarm: decompose HtmlTransformer, formalize finding contract, modularize matrix

[chubes4]

Why now

HtmlTransformer.php is a ~3k-line god-object (pattern dispatch + menu-toggle suppression + button/style resolution + fallback diagnostics + semantic parity + runtime islands). Every transformer change this session had to edit it, forcing agents to be serialized instead of parallel. Decomposing it is the precondition for the mass pattern-recognition swarm (modular files → parallel agents → no collisions) and just good maintenance.

Safety net

128 parity fixtures + the contract suite make behavior-preserving refactors verifiable: identical green before/after, zero block-output diff. Every refactor slice must prove this.

Workstreams

1. Decompose HtmlTransformer into focused modules — Patterns/ (exists) + a Diagnostics/ layer (fallback / behavior-loss / semantic-parity emission) + a Style/ layer (generalize ButtonStyleResolver into element-agnostic CSS→native-attribute resolution) + nav-chrome / runtime-island units. HtmlTransformer becomes a thin orchestrator. (multi-slice)
2. Formalize the cross-repo finding/diagnostic contract — the finding schema is implicit across blocks-engine (FallbackDiagnostic / RuntimeDependencyParityReport / VisualParity), SSI (loss-classes / report-diagnostics), homeboy-rigs (matrix acceptance). Make it one explicit versioned contract.
3. Modularize fixture-matrix.mjs (homeboy-rigs) — split accreted freshness / acceptance / editor-validation / visual-parity / metrics steps into composable step + collector modules.

Rules

• Behavior-preserving; green parity+contract before and after each slice.
• Refactor on a QUIET base — never race feature/swarm agents on the same files.
• Pure extraction/move per slice; no logic changes smuggled in.