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>

sim/golden/README.md

@@ -0,0 +1,47 @@
+# sim/golden — Golden-Reference Comparison
+
+Scripts, hooks, and notes for comparing RTL behavior against a software
+golden reference (PS2 emulator).
+
+The project-level reference strategy is locked in
+`docs/decisions/0003-golden-reference.md`.
+
+Current state (2026-04-17):
+
+- **Live-emulator harness is parked.** Two attempts were made:
+  DobieStation (blocked at runtime in the Emulator constructor) and PCSX2
+  (blocked at CMake configuration on missing modern deps including SDL3,
+  plutovg, plutosvg, ryml, Qt 6.10.1). See `third_party/DobieStation/NOTES.md`
+  and `third_party/PCSX2/NOTES.md`.
+- **The generated-golden path is the completed Phase 1 result.** End-to-end
+  validated through `make test_compare`: clean run, deliberate corruption,
+  and malformed input all produce the documented exit codes.
+- Live-emulator comparison is deferred until either a fuller EE front end
+  lands (Wave 3) or a low-friction live source becomes available.
+- `docs/decisions/0003-golden-reference.md` is unchanged — multiple-references
+  is still the strategy; only the phasing moved.
+
+Implementation spec:
+
+- `trace_compare_spec.md` — defines the first compare target, common-envelope
+  shape, diff semantics, exit-code contract, and acceptance criteria.
+
+Current implementation (Phase 1, NOP-sled target):
+
+- `make_nop_golden.py` — generates the NOP-sled golden trace in the common
+  envelope. Options: `--count`, `--reset-vector`, `-o`. Default matches the
+  32-fetch window produced by `tb_ee_fetch_stub`.
+- `trace_compare.py` — filtered order-based diff per spec. Exits 0/1/2/3 for
+  pass / semantic mismatch / usage-or-missing / malformed.
+- `dobiestation_runner/` — headless DobieStation harness. Builds cleanly;
+  runtime blocked at Emulator constructor (see
+  `third_party/DobieStation/NOTES.md`). Fetch tap is instrumented and ready
+  to emit in this same envelope once the runtime block is resolved.
+
+Expected content as this area grows:
+
+- build/run notes for emulator-side tools,
+- patches or instrumentation to emit traces in the chosen format,
+- additional comparison scripts as new event classes come under diff,
+- disagreement policy notes for "spec vs emulator" and later "emulator vs
+  emulator" cases.