# Final Validation Evidence Bundle

This document explains how to preserve the final clean-checkout validation evidence for the Mechanica production-hardening milestone. The evidence bundle is the release record that proves TypeScript, linting, unit tests, browser regressions, build output, bundle budgets, and deployment-readiness checks were actually executed on a clean machine.

## When to collect evidence

Collect evidence only after running one of the final validation paths:

```sh
node scripts/run-final-validation.mjs
```

or the `final-validation` GitHub Actions workflow.

If any validation gate fails, do not collect a “passing” release bundle. Fix the underlying issue, rerun validation from a clean checkout or clean CI runner, and collect a new bundle after the required gates pass.

## Local clean-checkout flow

From a fresh clone:

```sh
npm ci
node scripts/run-final-validation.mjs
node scripts/collect-validation-evidence.mjs
```

The collector writes a timestamped directory under:

```text
validation-evidence/
```

Each bundle contains:

- `README.md` — how to review the bundle.
- `executive-summary.md` — required-artifact status and excerpts from the validation and bundle-budget reports.
- `manifest.json` — machine-readable metadata, copied files, skipped files, git state, and CI metadata if available.
- `MANIFEST.sha256` — checksums for every file in the bundle except the checksum file itself.
- `artifacts/` — copied validation outputs preserving checkout-relative paths.

## Required artifacts

A release evidence bundle is incomplete unless it contains at least:

1. `validation-summary.md`
2. `bundle-budget.md`

The collector fails by default if either file is missing. For failure triage, an incomplete bundle can be written with:

```sh
node scripts/collect-validation-evidence.mjs --allow-incomplete
```

Do not treat an incomplete bundle as release evidence.

## Including additional paths

If a validation command or CI runner writes reports outside the default discovery locations, include them explicitly:

```sh
node scripts/collect-validation-evidence.mjs \
  --include path/to/per-gate-logs \
  --include path/to/playwright-report \
  --include path/to/bundle-budget.md
```

Explicit include paths are resolved relative to the checkout root and must stay inside the `--source` directory.

## Custom source and output directories

To collect from a downloaded CI artifact directory or a non-current checkout:

```sh
node scripts/collect-validation-evidence.mjs \
  --source /path/to/mechanica-clean-checkout \
  --out /path/to/evidence-output
```

To make a stable bundle name for a release candidate:

```sh
node scripts/collect-validation-evidence.mjs --label rc-2026-06-14
```

## Large files

By default, a single file larger than 300 MiB is skipped and listed in `manifest.json` plus `executive-summary.md`. This avoids accidentally publishing oversized traces or build outputs. If a large Playwright trace is essential to the evidence record, rerun with:

```sh
node scripts/collect-validation-evidence.mjs --include-large
```

or raise the threshold:

```sh
node scripts/collect-validation-evidence.mjs --max-file-mb 750
```

## Integrity verification

From inside a generated evidence bundle:

```sh
shasum -a 256 -c MANIFEST.sha256
```

The verification must report every file as `OK`. If checksums fail, discard the bundle and collect it again from the original validation output.

## Review checklist for release owner

Before accepting a bundle as passing evidence:

- Confirm `executive-summary.md` reports both required artifacts as found.
- Read the full `validation-summary.md`; every required gate must pass.
- Inspect per-gate logs for warnings that should block release, even if the command exited successfully.
- Open Playwright HTML reports and traces; verify desktop, mobile, keyboard, reduced-motion, and sharing scenarios.
- Confirm `bundle-budget.md` is within the documented performance budget.
- Confirm `manifest.json` shows the expected git commit and no unexpected dirty working-tree files.
- Confirm `MANIFEST.sha256` verifies successfully.
- Store the evidence bundle as a CI artifact, release artifact, or internal handoff record rather than committing bulky reports to the source tree.

## GitHub Actions flow

When using the final-validation workflow:

1. Trigger the workflow on the target commit.
2. Wait for all jobs to finish.
3. Download the workflow artifacts.
4. Inspect the same required reports and Playwright traces.
5. If the workflow already includes an evidence bundle, verify `MANIFEST.sha256`.
6. If artifacts were downloaded into a clean checkout and no bundle exists, run the collector with explicit `--include` paths for the downloaded reports.

Example:

```sh
node scripts/collect-validation-evidence.mjs \
  --include downloaded-artifacts/validation-summary.md \
  --include downloaded-artifacts/bundle-budget.md \
  --include downloaded-artifacts/playwright-report \
  --include downloaded-artifacts/per-gate-logs
```

## Failure handling

If validation fails:

1. Preserve a triage bundle if it helps debugging:

   ```sh
   node scripts/collect-validation-evidence.mjs --allow-incomplete --label failing-triage
   ```

2. Fix the root cause in source code, tests, configuration, or budgets.
3. Recreate dependencies from scratch with `npm ci`.
4. Rerun final validation.
5. Collect a new passing bundle.
6. Keep only the passing bundle as release evidence.

## Maintenance notes

The collector intentionally uses only Node.js standard-library APIs. If `scripts/run-final-validation.mjs` changes output paths in the future, update either:

- the collector’s candidate directory/file lists, or
- the release runbook command to pass explicit `--include` paths.

The collector packages and fingerprints validation outputs; it does not replace human review of the reports.