Verification
Forge Universe uses layered checks: unit tests on core math, Playwright oracles on built HTML, and PDCA phase gates for the PoC rollout.
Unit tests
node --test tools/universe/tests/*.test.mjs
Covers scene validation, pose transforms, Platonic edge uniformity, sphere rings, axis-panel projection, and rigid-body sim (tools/universe/tests/sim.test.mjs — gravity, ground bounce, sphere pairs, reset, pose sync).
Oracle verifier
python3 generator/build-site.py
node tools/universe-verifier/verify-oracles.mjs
Oracles live in docs/design/universe/oracles/{HASH}.json. Each scenario specifies:
| Field | Purpose |
|---|---|
root_selector |
e.g. [data-ks-hash="Us3"] |
threshold |
Pass ratio (1.0 = all checks green) |
prefers_reduced_motion |
Emulate reduced motion when true |
PoC oracles: Up2, Us3, Uhx, Ups, Udr, Usb, Uca, Ucr.
Ucr (construction realistic)
| Scenario | Action | Expect |
|---|---|---|
ucr-dom-present |
(none) | [data-ks-hash="Ucr"] present |
ucr-status-loaded |
(none) | #status.fu-status inside Ucr root |
Fixture: docs/design/universe/oracles/Ucr.json · Page: /demos/construction-realistic.html.
Uca (construction assets)
| Scenario | Action | Expect |
|---|---|---|
uca-dom-present |
(none) | [data-ks-hash="Uca"] present |
uca-status-loaded |
(none) | #status.fu-status inside Uca root |
Fixture: docs/design/universe/oracles/Uca.json · Page: /demos/construction-assets.html.
Usb (sim bounce)
| Scenario | Action | Expect |
|---|---|---|
usb-dom-present |
(none) | [data-ks-hash="Usb"] present |
usb-play-toggle |
Click [data-action="play-sim"] |
Root has data-playing="true" |
Fixture: docs/design/universe/oracles/Usb.json · Page: /demos/sim-bounce.html.
Phase gate
./scripts/universe-poc-pdca/check-phase-gate.sh S08
Validates repo layout, built pages, and verifier prerequisites per PDCA sequence in docs/prompts/universe-poc-pdca/.
Design contracts
Component contracts in docs/design/catalog/components/ document expected hashes and surfaces per visual element. Registry: docs/design/catalog/visual-registry.yaml.
Local parity before deploy
python3 generator/build-site.py
node --test tools/universe/tests/*.test.mjs
node tools/universe-verifier/verify-oracles.mjs
From workspace root, deploy with:
./deploy-websites.sh --only forge-universe