# Verification Matrix

Run from the repository root. Stop and fix the first failure before continuing.

## Environment

```bash
godot --version
flatpak run org.blender.Blender --version | head -3
git status --short
```

Expected: Godot 4.7.2; Blender 5.2 LTS flatpak; clean or intentionally scoped
working tree. Blender's flatpak cwd is `/app/blender`; all paths passed to
Blender must be absolute.

## Asset checks

| Check | Command | Expected |
| --- | --- | --- |
| Contract audit | `python3 tools/blender_assets.py audit` | exit 0, no `BAD` assets |
| Gear fit | `python3 tools/blender_assets.py fit` | exit 0; review head band/clothing/back clearances |
| Texture/texel density | `python3 tools/blender_assets.py texels` | authored 40–400 px/m; fabric ≥250 px/m |
| NPC base | `python3 tools/npc_pipeline.py audit` | exit 0, contract bones/slots/maps |
| Proportions | `python3 tools/npc_proportions.py report` | all eight inside the stylized guide |
| Single incoming GLB | `flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- inspect --file "$PWD/path.glb" --category <cat> --json` | contract result and measurements |
| Part GLB (local) | `flatpak run org.blender.Blender --background --python "$PWD/tools/npc_parts.py" -- inspect --file "$PWD/tmp/npc-parts/<variant>/<part>.glb"` | measurements; a part GLB is not a shipped asset |
| Prop audit | `python3 tools/model_pipeline.py audit` | exit 0 when generated props changed |
| Texture audit | `python3 tools/asset_pipeline.py audit assets/textures/ai/game_ready` | exit 0 when textures changed |

## Build/bake

```bash
# one library asset
flatpak run org.blender.Blender --background \
  --python "$PWD/tools/blender_assets.py" -- build --only npc_guard

# bake AO for the same asset
flatpak run org.blender.Blender --background \
  --python "$PWD/tools/bake_ao.py" -- --only npc_guard

# NPC base material maps/base
python3 tools/npc_pipeline.py prepare
flatpak run org.blender.Blender --background \
  --python "$PWD/tools/npc_pipeline.py" -- build
python3 tools/npc_pipeline.py audit
```

Only run `prepare` when AI fabric inputs changed. Do not run a full library
rebuild just to hide a small diff; build the affected asset and its AO map.

## Import and tests

```bash
godot --headless --path . --import
godot --headless --path . --script res://src/test/test_runner.gd
python3 -m unittest discover -s tools/tests -t tools -p 'test_*.py'
python3 tools/check_docs.py
```

Expected: Godot suite passes; Python tooling suite passes; docs check OK. The
project uses its own headless runner, not GUT.

## Capture gates

```bash
# neutral studio baseline: 48 frames (8 characters x 6 views)
godot --path . --script res://src/test/capture_npc_baseline.gd \
  -- --out=res://tmp/npc-baseline-after

# final-context: 96 frames (8 models x 3 distances x 2 venues x day/night)
godot --path . --script res://src/test/capture_npc_review.gd \
  -- --out=res://tmp/npc-review-after

# optional hand close-up: 8 frames
godot --path . --script res://src/test/capture_npc_baseline.gd \
  -- --out=res://tmp/npc-hands --view=hand
```

Raw frames stay under `tmp/` and are never committed. Compare with:

```bash
python3 tools/npc_baseline.py compare \
  --before tmp/npc-baseline --after tmp/npc-baseline-after \
  --out docs/blender_previews/sheet_npc_baseline_compare-<topic>.jpg
```

Do not replace the committed baseline sheet until the change is accepted.

## Budget/performance

```bash
godot --headless --path . --script res://src/test/smoke_npc_budget.gd
```

Expected report: 24 avatars / 168 meshes / 131,616 triangles (current baseline)
inside the 50 ms budget. Record the actual frame time; do not copy an old number
without measuring.

## Visual review criteria

The part pipeline (`tools/npc_parts.py`) builds/extracts head/face/hand parts under
`tmp/npc-parts/<variant>/`; these are local working files and are **not shipped**. Only the
assembled character GLBs, AO/maps, the manifest and the review sheets are committed. An
assembled GLB still goes through `blender_assets.py inspect`/`audit`/`fit` before any part is
accepted. The `npc_base.blend` fallback is frozen: never save prototype detail into it.

For each changed variant, inspect at least:

- 2 m portrait: eyes, mouth, ears, neck/shoulder, hair/headgear clearance.
- 4.2 m conversation: hands, gear contact, clothing silhouette.
- 8 m crowd: readable silhouette and LOD/impostor swap.
- Day and night/LATE final-context frames.
- Front, three-quarter and profile for a shape change.

Accepted stylized limits are in `docs/assets/3d-model-review.md` and
`docs/design/known-limitations.md`. Do not turn an accepted limit into an unreviewed
contract change.

## Final diff review

```bash
git diff --check
git status --short
git diff --stat
```

Check that only intended `.glb`, AO/maps, manifest, tests and docs changed. If a
`.blend`, raw capture, generated AI input or temporary sheet is staged, stop and
remove it. Commit one coherent asset family per commit.