Add safe PR previews for reports Pages deployments

[coisa]

Problem

The reports workflow publishes generated documentation and coverage only after changes reach main. Reviewers cannot inspect the generated reports for a pull request before merging, even though the wiki workflow now provides a PR-scoped preview before publishing to the canonical wiki branch.

Proposal

Add a PR preview path to .github/workflows/reports.yml while keeping the existing GitHub Pages artifact and actions/deploy-pages publishing model for the canonical main deployment.

The preview implementation MUST NOT replace or corrupt the currently published production Pages site. A normal Pages deployment replaces the complete Pages artifact, so PR previews must either use GitHub Pages preview-deployment support when available or fall back to a non-published PR artifact instead of deploying PR output over the production site.

Goals

• Generate reports for pull requests so maintainers can inspect documentation and coverage before merge.
• Preserve the existing upload-pages-artifact and deploy-pages model for main deployments.
• Avoid overwriting the production Pages site with PR-specific output.
• Expose a clear preview URL or artifact reference in the workflow output.

Expected Behavior

• Pushes to main continue to build public/, upload it as a Pages artifact, and deploy it to the canonical GitHub Pages environment.
• Pull request updates generate the same reports from the PR branch.
• If GitHub Pages preview deployment is supported for this repository, PR report output is deployed as a preview deployment without replacing the canonical Pages site.
• If preview deployment is not supported, PR report output remains available as an Actions artifact and the workflow does not call deploy-pages for the PR.

Implementation Strategy

• Extend reports.yml to run on pull request preview events.
• Keep the current main deployment path intact.
• Split report generation from deployment so PR and main behavior can diverge safely.
• Add explicit conditions around deploy-pages so production Pages deployment only happens from main, and PR preview deployment only uses the safe preview path.
• Update the packaged workflow stub in resources/github-actions/reports.yml so consumer repositories receive the same event model.

Requirements

• The workflow must continue to use actions/upload-pages-artifact and actions/deploy-pages for Pages deployments.
• PR preview logic must not deploy PR output as the production Pages site.
• The generated PR artifact must include docs and coverage produced by the existing reports command.
• The implementation must be safe for repeated pushes to the same PR.

Non-goals

• Replacing GitHub Pages with a gh-pages branch deployment model.
• Introducing a third-party Pages deployment action.
• Changing report generation commands or report content.
• Redesigning coverage or documentation output paths.

Acceptance Criteria

Functional Criteria

• reports.yml runs report generation for pull request updates.
• main pushes continue to deploy the canonical Pages site through actions/upload-pages-artifact and actions/deploy-pages.
• PR runs never deploy their artifact as the production Pages site.
• When Pages preview deployment is available, PR runs deploy through actions/deploy-pages preview mode.
• When Pages preview deployment is not available, PR runs still upload a downloadable report artifact and fail-safe without replacing production Pages.
• resources/github-actions/reports.yml mirrors the event triggers needed by consumer repositories.

Regression Criteria

• Existing manual workflow_dispatch behavior remains available.
• Existing generated reports remain under public/ for canonical deployments.
• Workflow conditions are explicit enough to prevent accidental production deployment from PR refs.

Architectural / Isolation Criteria

• The change is limited to the reports workflow and packaged reports workflow stub unless a small helper script is needed for clarity.
• The workflow remains deterministic for repeated PR pushes.
• No source PHP behavior changes are introduced by this issue.