Harden corpus-diagnostics harness: severity-ranked, defect-faithful worklist

[chubes4]

Summary

Hardens the php-transformer corpus-diagnostics harness (added in #327) so its numbers are trustworthy. This closes four known blind spots where the harness either under-reported real defects or inflated the worklist with working behavior. Reporting/detector-only — no transformer conversion logic is touched. All changes stay within php-transformer/src/CorpusDiagnostics/ and its tests.

Clusters now rank by severity tier first, then occurrence count, so the actionable worklist leads with real, editor-visible defects.

Blind spots closed

1. Validity headline no longer lies (RichText invalidity is now the headline)

The structural wp_block_validity proxy reports invalid_blocks=0 even when the editor would flag content invalid, because it does not model RichText stripping class/style off inline <span>/<a> in content. The classed-span detector is promoted to the authoritative editor-invalid-risk signal (richtext_invalid_content_risk, HIGH severity), extended to also cover <a> and core/list-item content, surfaced via a new richtext_invalid_risk_count metric, and the summary stops presenting structural invalid_blocks=0 as "no invalid content."

2. Layout-direction faithfulness

New layout_direction_misrecognition :: columns_from_vertical_flex detector: a core/columns emitted from a display:flex; flex-direction:column source (a vertical stack rendered as horizontal columns) is a misrecognition. Conservative — only inline column-direction flex on container elements with 2+ children, confirmed by a verifier that the fragment actually converts to core/columns. Genuine horizontal flex / grid is never flagged.

3. SVG-loss surfaced as HIGH severity

New svg_content_lost lane routes the transformer's inline-SVG fallback diagnostics and empty/comment-only core/html blocks that carry an SVG remnant into one signal, while keeping the distinction from SVG preserved as core/html with real shape elements (acceptable, not flagged). Previously this hid at rank ~61 under generic asset findings.

4. CSS var() false-positive down-ranked to informational

var() references are materialized downstream by SSI (verified end-to-end), so resolved var density is not a repair gap. Relabeled informational_var_density (severity info) and ranked below all actionable clusters, instead of flooding the top of the worklist with 233 css clusters.

Before / after ranking

Full corpus: 368 documents / 77 fixtures, 54,123 blocks.

Before (count-only ranking):

1. preserve_runtime_island :: runtime_script — 1224
2. native_block_recognition :: <svg> — 696
3. richtext_inline_span_normalization :: core/paragraph — 308
4. preserve_runtime_island :: interactive_form — 206
5. semantic_structure_parity_restoration :: navigation_menu — 95
   6–30. all 25 remaining slots are css_custom_property_materialization :: --* (working behavior)

• materialize_static_asset :: inline_svg (the SVG-loss signal): rank 61
• headline: invalid_blocks=0 (the lie)

After (severity-first ranking) — new actionable top-15:

#	sev	count	files	cluster
1	HIGH	1280	350	richtext_invalid_content_risk :: core/paragraph
2	HIGH	311	38	richtext_invalid_content_risk :: core/list-item
3	HIGH	36	13	richtext_invalid_content_risk :: core/heading
4	HIGH	21	17	layout_direction_misrecognition :: columns_from_vertical_flex
5	HIGH	16	15	svg_content_lost :: inline_svg_dropped
6	MEDIUM	1224	347	preserve_runtime_island :: runtime_script
7	MEDIUM	696	162	native_block_recognition :: <svg> (svg preserved — acceptable)
8	MEDIUM	206	95	preserve_runtime_island :: interactive_form
9	MEDIUM	95	82	semantic_structure_parity_restoration :: navigation_menu
10	MEDIUM	68	25	restore_interactive_behavior :: interactive_control
11	MEDIUM	46	46	semantic_structure_parity_restoration :: semantic_landmark
12	MEDIUM	38	33	typography_parity_restoration :: typography
13	MEDIUM	15	3	preserve_runtime_island :: html_template
14	MEDIUM	15	3	preserve_runtime_island :: runtime_template
15	MEDIUM	14	7	materialize_commerce_products :: commerce_product_grid

The 233 informational_var_density clusters now begin at rank 18 (severity info), out of the actionable worklist. New headline surfaces richtext_invalid_risk=1627, svg_content_lost=16, columns_from_vertical_flex=21, and labels var density as informational.

Tests

• tests/unit/corpus-detectors.php extended for all four cases (classed <span>/<a> in paragraph/list-item = richtext invalid risk; vertical-flex→columns flags layout misrecognition while horizontal flex does not; <svg>→empty/comment core/html flags svg_content_lost while a shape-bearing svg core/html does not; var density is informational, not top-ranked). 23 assertions pass.
• composer test green (canonical + 171 parity fixtures + packaging); php -l clean.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Opus 4.8 via Claude Code
• Used for: Detector/reporting implementation, tests, corpus run analysis, and this PR description. All changes reviewed by the submitter.