feat: init mlkem project with Verilator test framework

- sync_rtl/common/: skid_buffer, pipeline_reg, defines (valid/ready)
- sync_rtl/mod_add/: modular adder example with Verilator C++ TB
- test_framework/: Python-driven Verilator compile/sim/compare pipeline
- test_framework/modules/mod_add/: 50-vector test plan, full鏈路 PASS
- .trellis/spec/: RTL and test_framework conventions documented

.trellis/spec/test_framework/structure.md

@@ -0,0 +1,66 @@
+# Test Framework Structure
+
+## Directory Layout
+
+```
+test_framework/
+├── run_all.py              # CLI entry: --module, --case, --list, --quick
+├── config.json              # Verilator path, clock period, timeouts
+├── lib/
+│   ├── test_runner.py      # Discovery, compile, run, compare pipeline
+│   ├── sim_controller.py   # Verilator compiles/run wrapper
+│   ├── vector_gen.py       # Base class for vector generators
+│   ├── result_checker.py   # Hex-file comparison
+│   └── reporter.py         # Terminal + HTML output
+├── modules/
+│   └── <module>/
+│       ├── test_plan.json  # Module test definition
+│       ├── gen_vectors.py  # Vector generator (subclass of VectorGenerator)
+│       └── vectors/        # Generated hex files (auto-cleaned)
+└── reports/
+    ├── latest/
+    └── history/
+```
+
+## test_plan.json Schema
+
+```json
+{
+  "module": "<name>",
+  "rtl_top": "sync_rtl/<path>/<top>.v",
+  "rtl_deps": ["sync_rtl/common/<dep>.v"],
+  "tb_cpp": "sync_rtl/<path>/TB/tb_<top>.cpp",
+  "simulator": "verilator",
+  "timeout_s": 30,
+  "cases": [{
+    "id": "<case_id>",
+    "description": "<what this tests>",
+    "params": {},
+    "num_vectors": 50,
+    "tolerance": "bit_exact"
+  }]
+}
+```
+
+- `rtl_top`: top module basename (without .v) is used as Verilator `--top-module`
+- `rtl_deps`: listed before `rtl_top` in Verilator command line
+- `tolerance`: "bit_exact" uses result_checker.py; otherwise delegates to gen_vectors.compare_results()
+
+## Vector Generator Contract
+
+Each module's `gen_vectors.py` must:
+1. Subclass `VectorGenerator` from `test_framework.lib.vector_gen`
+2. Implement `generate_one(params) -> dict` returning `{"input": {...}, "expected": {...}}`
+3. Override `write_hex_file(vectors, filepath)` for input format
+4. Override `write_expected_file(vectors, filepath)` for expected format
+
+The framework auto-discovers the generator class by scanning for subclasses of VectorGenerator.
+
+## Adding a New Module
+
+1. Create `test_framework/modules/<name>/test_plan.json`
+2. Create `test_framework/modules/<name>/gen_vectors.py`
+3. Create `sync_rtl/<name>/<name>_sync.v` (RTL)
+4. Create `sync_rtl/<name>/TB/tb_<name>.cpp` (Verilator C++ TB)
+5. Run `python3 test_framework/run_all.py --list` to verify discovery
+6. Run `python3 test_framework/run_all.py --module <name>` to test