# Final Validation Evidence Guide

This guide explains how to review and preserve the evidence generated by `node scripts/run-final-validation.mjs` or the Final Validation GitHub workflow.

## Evidence bundle layout

A successful or failed run writes a timestamped bundle:

```text
artifacts/final-validation/<timestamp>/
├── bundle-budget.md
├── bundle-budget.json
├── logs/
│   ├── install.log
│   ├── playwright-install.log
│   ├── lint.log
│   ├── typecheck.log
│   ├── unit.log
│   ├── build.log
│   ├── bundle-budget.log
│   └── e2e.log
├── metadata/
│   ├── environment-initial.json
│   ├── environment-final.json
│   └── package-summary.json
├── reports/
│   ├── dist-inventory.csv
│   ├── playwright-report/
│   ├── test-results/
│   └── coverage/
├── validation-summary.json
└── validation-summary.md
```

The most recent run is copied to:

```text
artifacts/final-validation/latest/
```

Root-level convenience copies are also written:

```text
validation-summary.md
bundle-budget.md
```

These root files are generated artifacts and are intentionally ignored by Git.

## What to inspect first

1. Open `validation-summary.md`.
2. Confirm the top-level result is `✅ passed`.
3. Confirm the commit SHA matches the release candidate.
4. Review every required gate in the Gates table.
5. Open `bundle-budget.md`.
6. Open the Playwright HTML report if it exists.

If the summary says `❌ failed`, use the linked log for the first failing required gate as the starting point.

## Gate-specific review

### Install

Inspect `logs/install.log` for:

- Package resolution failures.
- Peer dependency conflicts.
- Native dependency build failures.
- Network or registry failures.

Because the project does not ship a hand-written lockfile, dependency resolution happens during this step.

### Playwright browser install

Inspect `logs/playwright-install.log` for:

- Missing Linux system packages.
- Browser download failures.
- Permission problems on self-hosted runners.

The GitHub workflow runs with `MECHANICA_PLAYWRIGHT_WITH_DEPS=true` on Ubuntu.

### Lint

Inspect `logs/lint.log` for:

- Unused imports.
- Accessibility lint regressions.
- React hook dependency issues.
- Script or config syntax errors.

Do not bypass lint failures for release. Fix the source issue.

### Typecheck

Inspect `logs/typecheck.log` for:

- Cross-file interface mismatches.
- Missing local exports.
- Incorrect React/Three/Zustand types.
- Test utility type regressions.

Typecheck failures usually indicate a real integration problem and should be fixed before running another full validation.

### Unit tests

Inspect `logs/unit.log` for Vitest failures around:

- URL share-state encoding/decoding.
- Keyboard shortcut behavior.
- Lazy loading preloads.
- Reduced-motion preferences.
- Metadata generation.
- WebGL support detection.
- Error-boundary behavior.

### Production build

Inspect `logs/build.log` for:

- Vite transform failures.
- Missing assets.
- Incorrect dynamic imports.
- CSS/PostCSS/Tailwind compilation failures.
- TypeScript project-reference failures if the build script includes them.

The script removes `dist/` before running the build so the bundle analysis cannot accidentally use stale output.

### Bundle budget

Inspect both:

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

The default strict budgets are intentionally generous enough for a Three.js educational viewer while still catching accidental monolithic bundles and asset regressions.

Release review should confirm:

- Total JavaScript gzip is within budget.
- Largest JavaScript chunk gzip is within budget.
- CSS gzip is within budget.
- Total served build output is within budget.
- At least one code-splitting chunk is present or a maintainer has accepted the warning.

### Playwright e2e tests

Open:

```text
artifacts/final-validation/latest/reports/playwright-report/index.html
```

When a test fails, inspect:

```text
artifacts/final-validation/latest/reports/test-results/
```

Look for traces, screenshots, videos, and console errors. Verify failures are fixed in source rather than hidden by selector broadening or skipped tests.

## Evidence to preserve for release

For a passing release candidate, preserve:

- `validation-summary.md`
- `bundle-budget.md`
- The full `artifacts/final-validation/latest/` directory
- The GitHub Actions artifact, if validation ran in CI
- Any Vercel preview URL used for manual smoke testing

A release issue or pull request should link to the GitHub Actions run and attach or reference the artifact name.

## Red flags

Do not sign off if any of these are present:

- Required gate is skipped.
- Required gate failed but the top-level result was manually edited.
- Bundle strict mode was disabled for the final run.
- Playwright tests ran against a stale or unrelated server.
- Git SHA in metadata does not match the release commit.
- Evidence bundle is missing logs.
- Playwright report contains failed/flaky tests.
- Browser console traces show uncaught runtime errors.
- Bundle report shows a sudden large JavaScript or asset increase without a documented reason.

## Cleanup

Generated evidence can be removed locally with:

```bash
rm -rf artifacts/final-validation validation-summary.md bundle-budget.md playwright-report test-results coverage dist
```

Do not remove the preserved passing CI artifact from the release record.