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/decisions/0000-trace-format.md

@@ -0,0 +1,64 @@
+# Decision 0000: Trace Format
+
+Status: `Locked`
+
+## Context
+
+Trace format is a required Phase 0 decision because every subsystem contract
+already depends on debug visibility, and those traces are much more useful if
+they share a known structure.
+
+The project needs one format that is:
+
+- simple enough to emit from early RTL stubs,
+- simple enough to generate from emulator-side instrumentation,
+- human-readable during bring-up,
+- structured enough for automated diffs later.
+
+## Options considered
+
+1. One shared tabular text format for everything.
+2. Subsystem-specific text formats with no shared envelope.
+3. Binary trace format from day one.
+4. Common text envelope plus subsystem-specific payload fields.
+
+## Decision
+
+Adopt a `common text envelope plus subsystem-specific payload fields` format for
+Phase 0 and Phase 1.
+
+The common envelope should include:
+
+- cycle or monotonic timestamp,
+- subsystem id,
+- event type,
+- schema/version id,
+- payload fields encoded as self-describing key/value pairs or a stable
+  column layout documented per subsystem.
+
+Golden-reference traces should be normalized into the same envelope before
+comparison. The trace files under `sim/traces/` remain text during early bring-up.
+
+Binary traces are deferred unless text traces become a demonstrated bottleneck.
+
+## Consequences
+
+- Early traces stay readable in code review and terminal workflows.
+- RTL stubs can emit useful traces before any heavy tooling exists.
+- Emulator-side tooling has a clear normalization target.
+- Different subsystems may still define different payload fields, but they must
+  fit inside the same outer structure.
+- If performance later requires binary traces, the project can add them behind
+  the same logical schema rather than reinventing the event model.
+
+## Inputs to use when locking
+
+- `docs/contracts/validation.md`
+- per-subsystem "required debug visibility" sections in `docs/contracts/`
+- `sim/traces/README.md`
+
+## Follow-up
+
+- The stub-module plan should name the initial envelope fields explicitly.
+- Subsystem contracts may later gain a short "trace payload schema" section once
+  the first stubs are specified.