# Final Validation Runbook

This runbook is the release gate for the production-hardening milestone. Do not mark the milestone complete until a clean checkout or CI runner produces a passing `validation-summary.md` and the passing evidence bundle has been preserved.

## Required environment

- Current Node.js LTS. The GitHub workflow uses `actions/setup-node@v4` with `node-version: lts/*`.
- npm, supplied with Node.
- Git, so the evidence bundle can record the commit SHA and working-tree status.
- Network access for `npm install` and Playwright browser downloads.
- Linux CI runners should allow Playwright to install system browser dependencies. The provided workflow runs `playwright install --with-deps` through the validation script.

No lockfile is hand-authored in this repository. The final validation run intentionally uses `npm install`, which may generate a lockfile locally for reproducibility evidence.

## One-command local validation

From a clean checkout:

```bash
git clone <repository-url> mechanica
cd mechanica
node scripts/run-final-validation.mjs
```

The script performs the full release gate:

1. Removes stale generated outputs (`dist`, Playwright reports, coverage, previous root summaries).
2. Runs `npm install`.
3. Installs Playwright browsers using the locally installed Playwright CLI.
4. Runs ESLint.
5. Runs TypeScript typechecking.
6. Runs Vitest.
7. Runs the production build.
8. Analyzes the built Vite output against bundle budgets.
9. Runs Playwright browser regression tests.
10. Writes a summary and evidence bundle.

## CI validation

Use the included workflow:

```text
.github/workflows/final-validation.yml
```

It can be run from the GitHub Actions UI via `workflow_dispatch`, and it also runs on `main` pushes and pull requests targeting `main`.

The workflow uploads an artifact named:

```text
mechanica-final-validation-<run_id>-<run_attempt>
```

Download that artifact before sign-off.

## Generated evidence

After a run, inspect:

```text
validation-summary.md
bundle-budget.md
artifacts/final-validation/latest/
```

The timestamped run directory is also preserved under:

```text
artifacts/final-validation/<timestamp>/
```

Important subdirectories:

```text
logs/                         per-gate stdout/stderr
metadata/                     environment, package, git metadata
reports/playwright-report/    HTML report when Playwright ran
reports/test-results/         traces, screenshots, and videos when configured
reports/coverage/             Vitest coverage when configured
reports/dist-inventory.csv    production build file inventory
```

## Passing criteria

A release candidate passes only when all of these are true:

- `validation-summary.md` says `Result: ✅ passed`.
- Every required gate in the Gates table says `✅ pass`.
- `bundle-budget.md` has no strict-mode budget breaches.
- Playwright report has no failed, flaky, or unexpectedly skipped critical tests.
- Any captured trace, screenshot, or video artifacts are consistent with the expected dark premium UI and do not show WebGL/runtime crashes.
- The production build output is from the same commit SHA being released.

## Failure loop

If any gate fails:

1. Open `validation-summary.md`.
2. Read the failing gate’s linked log under `artifacts/final-validation/latest/logs/`.
3. For Playwright failures, open `reports/playwright-report/index.html` and inspect traces under `reports/test-results/`.
4. Fix the actual source issue. Do not weaken tests or budgets to hide a regression.
5. Re-run `node scripts/run-final-validation.mjs` from a clean checkout or re-run the GitHub workflow.
6. Preserve the first fully passing evidence bundle.

## Useful environment overrides

Use overrides only for diagnosis unless the release manager explicitly approves them.

| Variable | Default | Purpose |
| --- | --- | --- |
| `MECHANICA_VALIDATION_ARTIFACT_DIR` | `artifacts/final-validation` | Custom evidence output directory. |
| `MECHANICA_SKIP_PLAYWRIGHT_INSTALL` | `false` | Skip browser installation when browsers are already provisioned. E2E tests still run. |
| `MECHANICA_PLAYWRIGHT_WITH_DEPS` | `true` on Linux | Include Playwright system dependencies during browser install. |
| `MECHANICA_BUNDLE_BUDGET_STRICT` | `true` | Fail validation when bundle budgets are exceeded. |
| `MECHANICA_BUNDLE_MAX_TOTAL_JS_GZIP_KIB` | `1800` | Total JavaScript gzip budget. |
| `MECHANICA_BUNDLE_MAX_LARGEST_JS_GZIP_KIB` | `1200` | Largest JavaScript chunk gzip budget. |
| `MECHANICA_BUNDLE_MAX_TOTAL_CSS_GZIP_KIB` | `250` | Total CSS gzip budget. |
| `MECHANICA_BUNDLE_MAX_HTML_GZIP_KIB` | `80` | HTML gzip budget. |
| `MECHANICA_BUNDLE_MAX_TOTAL_BUILD_MIB` | `30` | Total served build output budget. |

## Sign-off template

```md
Final validation commit: <git-sha>
Validation run: <GitHub Actions URL or local run timestamp>
Summary: validation-summary.md shows Result: ✅ passed
Bundle budget: bundle-budget.md shows no strict-mode breaches
Playwright report reviewed: yes/no
Known release caveats: <none or link>
Approver: <name/date>
```