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>

rtl/debug/README.md

@@ -0,0 +1,44 @@
+# rtl/debug
+
+Trace taps, observability modules, and first-class debug infrastructure.
+
+This directory is intentionally first-class per the debug/validation strategy
+in `docs/contracts/validation.md`. Nothing here is ornamental; stubs and real
+blocks alike depend on it.
+
+## Wave 1 contents
+
+- `trace_pkg.sv` — shared types (`subsys_e`, `event_e`) and string renderers
+  used by all trace producers and `trace_sink_stub`.
+- `trace_sink_stub.sv` — simulation-only text trace writer. One instance per
+  output file; each Wave 1 stub wires its event port to its own sink. See
+  `docs/decisions/0000-trace-format.md` for format rationale.
+
+## Usage pattern for Wave 1 testbenches
+
+```systemverilog
+trace_sink_stub #(
+    .FILENAME  ("ee.trace"),
+    .SINK_LABEL("ee_fetch")
+) u_trace_ee (
+    .clk      (clk),
+    .rst_n    (rst_n),
+    .ev_valid (dut_ev_valid),
+    .ev_subsys(dut_ev_subsys),
+    .ev_event (dut_ev_event),
+    .ev_arg0  (dut_ev_arg0),
+    .ev_arg1  (dut_ev_arg1),
+    .ev_arg2  (dut_ev_arg2),
+    .ev_arg3  (dut_ev_arg3),
+    .ev_flags (dut_ev_flags)
+);
+```
+
+## Notes
+
+- Cycle counter is internal to the sink and advances on `clk` while `rst_n`
+  is high. Cross-clock correlation is a later-wave concern.
+- `ev_flags == 0` renders as `-` in the trace line; any non-zero value is
+  printed as an 8-hex-digit field.
+- Event/subsystem codes are globally unique in Wave 1 (not per-subsystem).
+  Revisit if the namespace gets crowded.