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/intc.md

@@ -0,0 +1,53 @@
+# INTC Contract
+
+Status: `Draft`
+
+## Purpose
+
+Define interrupt-controller ownership explicitly so interrupt routing, masking,
+and acknowledgement do not become scattered across unrelated subsystem
+contracts.
+
+## Owns
+
+- EE interrupt controller register-visible behavior,
+- interrupt status accumulation,
+- interrupt mask behavior,
+- presentation of interrupt state to the EE,
+- acknowledgement / clear semantics visible through the INTC register block.
+
+## Inputs
+
+- interrupt sources from EE-side timers,
+- DMAC interrupt sources,
+- GIF/GS-visible interrupt sources where applicable,
+- IPU-visible interrupt sources where applicable,
+- any additional EE-side sources that target `INTC_STAT`.
+
+## Outputs
+
+- interrupt-pending state to the EE core,
+- register-visible status/mask values,
+- trace events for assertion, masking, and clearing.
+
+## Questions to lock
+
+- Which interrupt sources are required for the first BIOS-progress milestone?
+- Which sources may be stubbed as permanently inactive in Phase 1?
+- How will interrupt timing be modeled in early bring-up:
+  - functionally-correct first
+  - cycle-shaped from day one
+
+## Allowed early stubs
+
+- register-visible INTC with a reduced source set,
+- synthetic interrupt injection for directed tests,
+- simplified assertion timing so long as ordering is deterministic.
+
+## Required debug visibility
+
+- source assertion,
+- source masking,
+- pending-to-serviced transitions,
+- EE acknowledge/clear events,
+- dropped or unimplemented interrupt attempts.