# Core Machine Catalogue Quality Gates

Milestone 5 now has an explicit audit layer for preventing regressions in the Phase 1 machine catalogue. The original catalogue validator checks structural coverage; the deeper audit checks whether each entry still has enough educational and integration depth to be useful in the 3D explorer.

## Run locally

```bash
node scripts/validate-core-machine-catalogue.mjs
node scripts/audit-core-machine-catalogue-depth.mjs
```

Useful report modes:

```bash
node scripts/audit-core-machine-catalogue-depth.mjs --format=markdown --output=docs/generated/core-machine-audit.md
node scripts/audit-core-machine-catalogue-depth.mjs --format=json --output=tmp/core-machine-audit.json
node scripts/audit-core-machine-catalogue-depth.mjs --strict-warnings
```

## What the depth audit enforces

Blocking errors are raised when a machine is missing core delivery requirements:

- the Phase 1 catalogue count is not 28;
- machine IDs are duplicated or not URL-safe;
- title, category, difficulty, or substantial description data is absent;
- engineering facts are too sparse;
- the component hierarchy is too shallow or lacks component descriptions;
- saved camera presets, labels/hotspots, or exploded-view metadata are missing;
- procedural blueprints, dossiers, animations, or the central registry do not visibly cover the machine;
- related-machine IDs point to entries that do not exist.

Warnings identify issues that are not release-blocking but should be cleaned up before asset polish: thin related-machine coverage, fewer preferred camera presets, missing catalogue thumbnail strategy, duplicate component IDs, or unclear GLB/GLTF replacement language.

## CI coverage

`.github/workflows/core-machine-catalogue-audit.yml` runs both validators on pull requests and pushes that touch catalogue, dossier, blueprint, animation, or catalogue documentation files. The depth audit fails CI on errors and can be made stricter locally with `--strict-warnings`.

## Intentional limits

The audit is static: it parses TypeScript source with the compiler API instead of importing React or Three.js runtime modules. That makes it reliable in CI and good at catching catalogue regressions, but it does not replace visual QA for procedural geometry proportions, animation timing, material aesthetics, or final GLB asset swaps.