Add pruning for PR preview deployments

[CodexRaunak]

Current Behavior

This repository's PR preview deployment workflow publishes previews under pr-preview/pr-<number> on the gh-pages branch, but older preview directories are not pruned after new previews are deployed.

As preview artifacts accumulate, the gh-pages branch can grow large enough that GitHub Pages deployments fail because of oversized build artifacts.

Reference workflows with the desired behavior:

• https://github.com/layer5io/layer5/blob/master/.github/workflows/build-and-preview-site.yml
• https://github.com/layer5io/docs/blob/master/.github/workflows/build-and-preview-docs.yml

Desired Behavior

Add preview pruning behavior to this repository's PR preview deployment workflow and keep it consistent with the naming conventions and workflow structure used in the reference workflows.

Expected behavior:

• Keep only the 6 most recently updated PR previews.
• Add a PREVIEW_RETENTION_LIMIT: 6 workflow env value.
• After deploying a PR preview, check out gh-pages for preview retention maintenance.
• Prune old pr-preview/pr-* directories beyond the retention limit.
• Commit and push the pruning changes back to gh-pages.
• Keep the existing sticky preview comment convention consistent with the current workflow and the reference workflows.
• Add a comment/update for PRs whose previews were pruned so contributors know they can push a new commit to regenerate the preview.
• Keep cleanup-on-close behavior for the closed PR's preview.

Implementation

Use the Layer5 preview workflows as the implementation reference:

• layer5io/layer5: .github/workflows/build-and-preview-site.yml
• layer5io/docs: .github/workflows/build-and-preview-docs.yml

The gh-pages maintenance checkout should stay efficient. Please add sparse checkout behavior like the Layer5 site deployment workflow so the workflow only checks out the pr-preview directory instead of spending unnecessary time checking out the full gh-pages branch:

filter: blob:none
sparse-checkout: |
  pr-preview
path: gh-pages-maintenance

The implementation should stay consistent with the reference workflow names, output names, and comment wording where applicable, so preview deployment behavior remains consistent across Layer5-maintained sites.

Acceptance Tests

• The preview workflow keeps no more than 6 active pr-preview/pr-* directories on gh-pages.
• New PR preview deployments still publish and comment the preview URL.
• Older previews are pruned after a successful preview deployment.
• PRs whose previews are pruned receive an updated sticky comment explaining that the preview was removed and can be regenerated by pushing a new commit.
• Closed PR previews continue to be removed.
• The gh-pages maintenance checkout uses sparse checkout for pr-preview.

Mockups

Not applicable. This is a workflow maintenance enhancement to prevent large preview artifacts from blocking GitHub Pages deployments.