Initial commit: retroDE_ps2 — first-of-its-kind PS2 GS FPGA core (DE25-Nano / Agilex 5)

RTL (GS rasterizer, EE core stub, platform bridge, LPDDR4B path), sim regression
(272 TBs), docs, and tooling. Copyrighted PS2 content (BIOS, game code, GS dumps,
and all dump-derived textures/traces) is excluded via .gitignore and stays local.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/contracts/validation.md

@@ -0,0 +1,66 @@
+# Validation Contract
+
+Status: `Draft`
+
+## Purpose
+
+Define how subsystem correctness is judged before and during implementation.
+
+## Principles
+
+- Traces are first-class outputs.
+- Small directed tests beat giant software workloads early.
+- Every major subsystem should have a "stub-valid" test mode before a "real"
+  implementation exists.
+- At least one software golden reference should be selected before large RTL
+  effort begins.
+
+## Proposed validation ladder
+
+### Level 0: structural
+
+- modules elaborate,
+- resets are deterministic,
+- key registers can be written/read in simulation,
+- traces are emitted.
+
+### Level 1: directed block tests
+
+- memory map tests,
+- DMAC register tests,
+- GIF packet intake tests,
+- SIF mailbox tests,
+- VIF packet decode tests.
+
+### Level 2: subsystem behavior tests
+
+- BIOS fetch trace agreement,
+- GS stub/test-pattern agreement,
+- simple DMA-to-endpoint transfers,
+- IOP boot-progress markers.
+
+### Level 3: software-facing tests
+
+- tiny EE code payloads,
+- tiny IOP payloads,
+- `gsKit`-style graphics tests,
+- minimal inter-processor coordination tests.
+
+### Level 4: comparative reference
+
+- compare selected traces against a golden emulator/reference,
+- resolve disagreements against authoritative docs where available.
+
+## Artifacts to maintain
+
+- `sim/vectors/`: deterministic stimulus inputs
+- `sim/traces/`: captured reference traces
+- `sim/golden/`: scripts/notes for emulator-side comparison
+- `software/tests/`: minimal payloads for EE/IOP/graphics/audio/device paths
+
+## Required early decisions
+
+- primary golden reference,
+- trace format,
+- first three block-level regression tests,
+- policy for "spec disagrees with emulator" cases.