[github-actions] Validate published reports HTML with proof-html

[coisa]

Summary

The reports workflow already verifies that published main and preview URLs respond after deployment, but it does not yet validate the rendered HTML itself. We should add proof-html validation for both the production reports site and pull-request previews so broken links, malformed markup, and publication regressions are caught closer to deploy time.

Current Behavior

• reports.yml deploys the main site and PR previews to GitHub Pages.
• The workflow performs post-deploy health checks against the published URLs.
• Those checks confirm availability, but they do not validate the published HTML documents and link graph.

Expected Behavior

After a successful deploy, the workflow SHOULD run https://github.com/anishathalye/proof-html against the published site contents for both main and preview deployments. Validation failures SHOULD fail the workflow clearly, while temporary transport or GitHub Pages propagation issues SHOULD remain handled by the existing deployment verification steps.

Scope

Investigate and implement proof-html validation for:

• the main published reports site
• pull-request preview reports sites
• any workflow summaries or docs updates needed to explain the new validation step

Acceptance Criteria

• reports.yml validates published main-site HTML with proof-html after deployment verification succeeds.
• reports.yml validates pull-request preview HTML with proof-html after preview verification succeeds.
• The validation target and invocation are deterministic and compatible with GitHub Actions.
• Validation failures surface clearly in logs and fail the workflow.
• Existing deploy health checks remain in place for propagation and availability verification.
• README or docs are updated if maintainers need to understand the new validation behavior.

Non-Goals

• Replacing the existing availability and deployment health checks.
• Validating unpublished local build artifacts instead of the published GitHub Pages output.
• Adding automatic retries for genuine HTML validation failures.

[coisa]

We investigated this by opening PR #235 and running against the published reports preview after the existing GitHub Pages health check. The experiment showed that this is not a good default for DevTools right now: the validation takes too long for the generated reports surface and reports many issues inside generated assets produced by upstream tools rather than by our RST/documentation source.

Because DevTools only directly controls the source documentation and workflow orchestration, not all generated HTML/assets emitted by phpDocumentor, coverage tooling, PhpMetrics, and related generators, making a blocking reports workflow would create noisy failures without a clear maintainable remediation path.

Decision: close this issue as not planned for now. The reports workflow should keep the existing published URL health checks. If we revisit HTML validation later, it should probably target narrower source-controlled documentation output or a curated allow-list rather than the full generated reports tree.

One unrelated but valuable CI finding from PR #235 will be split into a separate follow-up for the previous wiki pointer required-check work: workflow-dispatched test runs need to mirror required contexts as commit statuses so branch protection recognizes bot-authored wiki pointer commits.

[coisa]

Closing as not planned after the PR #235 experiment showed is too slow and too noisy for the full generated reports output.

[coisa]

Correction/context after closing #178:

We investigated this by opening PR #235 and running proof-html against the published reports preview after the existing GitHub Pages health check. The experiment showed that this is not a good default for DevTools right now: the validation takes too long for the generated reports surface and reports many issues inside generated assets produced by upstream tools rather than by our RST/documentation source.

Because DevTools only directly controls the source documentation and workflow orchestration, not all generated HTML/assets emitted by phpDocumentor, coverage tooling, PhpMetrics, and related generators, making proof-html a blocking reports workflow would create noisy failures without a clear maintainable remediation path.

Decision: keep #178 closed as not planned for now. The reports workflow should keep the existing published URL health checks. If we revisit HTML validation later, it should probably target narrower source-controlled documentation output or a curated allow-list rather than the full generated reports tree.

One unrelated but valuable CI finding from PR #235 will be split into a separate follow-up for the previous wiki pointer required-check work: workflow-dispatched test runs need to mirror required Run Tests contexts as commit statuses so branch protection recognizes bot-authored wiki pointer commits.