# Final Build Hygiene Self-Audit

This audit summarizes the release-readiness checks added for the full-stack integration milestone. It is written for maintainers preparing the public demo branch.

## Scope verified by delivered files

| Area | Delivered evidence |
| --- | --- |
| End-to-end app path | Integrated API, web app, shared package, API client, and Playwright demo test. |
| Core gameplay | Collection, trivia, prediction, badge, challenge, and leaderboard flows are represented in app code and tests. |
| Backend integration | API routes, store, gamification engine, server entry, and integration tests. |
| Frontend integration | React app, API client, loading/error/empty states, responsive styles, and component tests. |
| QA package | Unit/integration tests, e2e test, HTTP smoke script, accessibility static check, QA plan, manual scenarios, and acceptance matrix. |
| Release package | Demo script, deployment guide, Docker demo, runbook, release checklist, crowdfunding update copy, support triage, analytics plan, and video shot list. |
| Automation | GitHub Actions CI workflow and static release preflight script. |

## Dependency hygiene

- New scripts in this final pass use only Node.js built-in modules.
- No new npm runtime package was introduced in this pass.
- The CI workflow installs dependencies with `npm install` so it works whether or not a maintainer has generated a lockfile.
- No lockfile is hand-authored in this deliverable.
- Node.js 22 is used for CI and Docker because it is a current stable runtime and includes the built-in `fetch` used by container health checks.

Maintainers should generate dependency resolution on a clean machine with:

```bash
npm install
```

If the project team chooses to commit a lockfile later, it should be the file generated by npm from the manifests.

## Cross-file consistency checks

The new `scripts/qa/release-preflight.mjs` statically checks that:

- Required files exist.
- Workspace manifests parse as JSON.
- Relative TypeScript/JavaScript imports resolve to delivered files.
- Bare package imports are declared in a visible manifest or are local workspace packages.
- Environment samples do not contain obvious secret-shaped values.
- Merge-conflict markers are absent.
- The QA and release documentation package is present.

Run it with:

```bash
node scripts/qa/release-preflight.mjs
```

For a stricter publishing gate that also blocks advisory wording findings:

```bash
node scripts/qa/release-preflight.mjs --strict
```

## Recommended final verification sequence

From a clean checkout:

```bash
npm install
node scripts/qa/release-preflight.mjs
npm run typecheck --if-present
npm --workspaces run typecheck --if-present
npm test --if-present
npm --workspaces run test --if-present
npm run build --if-present
npm --workspaces run build --if-present
npx playwright install --with-deps chromium
npm run e2e --if-present
```

Then verify the Docker demo path:

```bash
docker compose -f docker-compose.demo.yml up --build
```

Open:

```text
http://localhost:4173
```

Run the API smoke check in another terminal:

```bash
API_BASE_URL=http://localhost:4000 node scripts/qa/http-smoke.mjs
```

## Public demo acceptance criteria

Before posting the crowdfunding update, confirm:

1. The app loads from a clean session.
2. A fan can collect an item.
3. A fan can answer trivia and receive clear feedback.
4. A fan can submit a prediction.
5. A badge or challenge unlock appears after qualifying actions.
6. Leaderboard points or rank reflect the fan's progress.
7. Duplicate or invalid actions show friendly errors.
8. Loading and empty states are visible and understandable.
9. Keyboard navigation reaches primary controls.
10. Mobile layout remains usable at narrow widths.
11. Release checklist, deployment guide, and demo script are reviewed.

## Known operational boundaries

These are not blockers for the funded demo milestone, but they should be addressed before a large public launch:

- Add durable persistence for real fan accounts.
- Add authentication and abuse prevention.
- Add production analytics using the event plan.
- Add centralized logging and alerting.
- Add content moderation and licensing review for official marks, fixtures, teams, and stadium assets.
- Add rate limits for prediction, trivia, and leaderboard endpoints.
- Add a real data reset/migration strategy for post-World Cup passport variants.