# Final Validation Sign-off Template

This template is for the final human release sign-off after a clean checkout or CI runner executes the production validation flow. Do not treat the application as release-ready until the evidence below is filled from an actual run and the referenced artifacts are preserved.

## Required Commands

Run from a clean checkout using the dependency versions resolved by the package manager:

```bash
npm ci
node scripts/run-final-validation.mjs
node scripts/collect-validation-evidence.mjs
node scripts/verify-validation-evidence.mjs --dir <collected-evidence-dir> --require-pass-markers
```

If `collect-validation-evidence.mjs` writes a timestamped directory, use that directory for `<collected-evidence-dir>`. If validation is executed through GitHub Actions, download the final-validation artifact bundle and run the verifier against the extracted folder.

## Environment Record

| Field | Value recorded from the validation run |
| --- | --- |
| Commit SHA |  |
| Branch / tag |  |
| Runner type | Local clean checkout / GitHub Actions / other |
| Operating system |  |
| Node.js version |  |
| npm version |  |
| Browser engines used by Playwright | Chromium / Firefox / WebKit versions |
| Validation started at |  |
| Validation completed at |  |
| Evidence bundle path or artifact URL |  |

## Automated Gate Summary

Record each gate exactly as reported in `validation-summary.md` and the per-gate logs.

| Gate | Evidence file or log | Result | Notes |
| --- | --- | --- | --- |
| Dependency install |  |  |  |
| TypeScript strict check |  |  |  |
| ESLint |  |  |  |
| Prettier / formatting check |  |  |  |
| Unit tests |  |  |  |
| Production build |  |  |  |
| Bundle budget |  |  |  |
| Playwright desktop regression |  |  |  |
| Playwright tablet regression |  |  |  |
| Playwright mobile regression |  |  |  |
| Clean-checkout validation wrapper |  |  |  |
| Evidence verifier | `validation-evidence-verification.md` |  |  |

## Bundle Budget Review

Copy the headline values from `bundle-budget.md` or the bundle-budget log.

| Metric | Reported value | Budget | Result |
| --- | ---: | ---: | --- |
| Initial JavaScript |  |  |  |
| Initial CSS |  |  |  |
| Largest async chunk |  |  |  |
| Total production assets |  |  |  |
| Gzip / compressed total, if reported |  |  |  |

Confirm that lazy-loaded route and viewer chunks are present and that no unexpected monolithic application bundle was introduced.

## Playwright Evidence Review

| Item | Location | Reviewed |
| --- | --- | --- |
| HTML report |  |  |
| Trace archive(s), if generated |  |  |
| Screenshots / videos for failures or retries |  |  |
| Mobile viewport run |  |  |
| Reduced-motion run |  |  |
| Keyboard-navigation run |  |  |
| Share-link round trip run |  |  |

Any Playwright retry, flaky test, unexpected browser console error, page error, network failure, or visual regression must be investigated before sign-off.

## Manual Production-Hardening Checks

These checks complement automated regression coverage.

| Check | Expected result | Result / evidence |
| --- | --- | --- |
| Catalogue search/filter/sort remains keyboard reachable | Focus order is logical and visible; controls have accessible names. |  |
| Viewer keyboard shortcuts do not trap focus | Canvas, sidebars, drawers, and help overlay can be entered and exited with keyboard only. |  |
| Reduced-motion preference is honored | Animations and transitions are minimized when OS or in-app reduced motion is enabled. |  |
| Share link copies and restores state | Machine slug, camera, explode distance, display modes, selected/hidden/transparent parts restore from URL. |  |
| WebGL unsupported path is usable | Fallback explains the issue and lets the user continue browsing the catalogue. |  |
| Mobile layout remains usable at 375–430 px widths | Side panels, toolbar, drawer, and bottom status bar do not overlap core controls. |  |
| Social/meta strategy is intact | Base Open Graph/Twitter tags exist and machine-specific client-side meta updates work after navigation. |  |
| Production build has no white flash | Dark theme background is visible through loading and route transitions. |  |
| Error boundary recovery works | Recoverable viewer/page errors show the production fallback and reset path. |  |

## Evidence Preservation Checklist

The final evidence bundle must contain:

- `validation-summary.md`
- `bundle-budget.md` or equivalent bundle-budget output
- Per-gate logs for install, typecheck, lint, tests, build, e2e, and bundle budget
- Playwright HTML report or blob report
- Playwright traces, screenshots, or videos when retries/failures occur
- `validation-evidence-verification.md`
- `validation-evidence-sha256.json`

Store the bundle with the release record so future maintainers can reproduce the exact validation state.

## Sign-off Decision

| Decision field | Value |
| --- | --- |
| Release approved? | Yes / No |
| Blocking issues remaining? |  |
| Non-blocking follow-up issues filed? |  |
| Approver name |  |
| Approval timestamp |  |

A release can be approved only when all required automated gates pass, no bundle budget regression is accepted without an explicit documented waiver, all blocking browser regressions are fixed, and the evidence bundle is preserved.