| name | ref-model |
| description | Builds Phase 2 golden C reference model with bitexact conformance and bandwidth estimation. Use for 'build reference model', 'C ref model', 'golden model'. |
| user-invocable | true |
| argument-hint | [algorithm-name | --update] |
| allowed-tools | Bash, Read, Write, Edit, Task, Grep, Glob |
Build a golden C functional reference model (Phase 2) that validates algorithm correctness and estimates external memory bandwidth. Outputs: `refc/*.c`, `refc/include/*.h`, `conformance_report.json`, `bandwidth_report.json`, and `reviews/phase-2-architecture/ref-model-feature-coverage.md`.
<Use_When>
- Phase 1 artifacts are complete and a reference model does not yet exist.
- Reference model needs updating after a spec change.
- A conformance baseline is needed before RTL verification can begin.
- Bandwidth or datapath-width exploration is required.
- An independent quality gate is needed before declaring the model a verification oracle.
</Use_When>
<Do_Not_Use_When>
- Reference model already exists and
conformance_report.json is current — avoid regenerating.
- Only a quick algorithm question is needed → use
domain-consult instead.
</Do_Not_Use_When>
<Why_This_Exists>
Writing the reference model before RTL forces algorithm understanding and exposes spec ambiguities before silicon commitment. Bitexact match against JM/HM is the industry-standard acceptance criterion. The model doubles as a bandwidth analysis tool by routing all external memory traffic through ext_mem_read/ext_mem_write, enabling memory-bandwidth estimation without RTL.
</Why_This_Exists>
Prerequisites
docs/phase-1-research/iron-requirements.json present with REQ-F-* items.- JM 19.0 (H.264) or HM 16.20 (H.265) installed and on
PATH.
If missing: WARNING — proceed with available artifacts; feature coverage step will note absent requirements file.
| Path | Role |
|------|------|
| `templates/Makefile` | Build + test + bandwidth targets (`build`, `test`, `bandwidth`, `sanitize`). |
| `templates/ref_model_main.c` | Scaffold with `ext_mem_read/write` stubs and `PARALLEL_LANES` define. |
| `templates/ref_model_header.h` | Struct typedefs: `input_t`, `output_t`, `context_t`, `ext_mem_stats_t`. |
| `templates/dpi_wrapper.h` | DPI-C export declarations for SV testbench linkage. |
| `scripts/run_ref_model.py` | Build-and-run wrapper: locates `refc/`, builds via Makefile (direct `cc -std=c11` fallback), runs the model with `--input`/`--output`/`--args` pass-through, writes a JSON run report. |
| `references/ref-model-conventions.md` | C11/DPI-C rules, output schemas, anti-patterns. |
| `examples/sat_add/` | Worked example: self-testing saturating-adder ref model + committed `expected_run_report.json` (regeneration-checked in CI). |
<Responsibility_Boundary>
- Scripts handle build, bitexact comparison, and bandwidth measurement via
Makefile targets.
- LLM handles algorithm implementation, feature-coverage mapping, and spec-gap escalation.
- Contract surface:
ext_mem_read/write abstraction layer + REQ-F-* coverage table.
</Responsibility_Boundary>
1. Spawn domain expert for algorithm pseudocode and edge-case table (see Tool_Usage).
2. Spawn `ref-model-dev` to implement `refc/*.c` — pure C11, no clock/reset, I/O as function args, internal state as arrays/struct members, external memory via `ext_mem_read/write`, `PARALLEL_LANES` parameterizable, no C++ features.
3. Build: `cd refc && make build` (must compile with `-Wall -Wextra -Werror`).
4. Test: `cd refc && make test` — bitexact comparison against JM/HM; fix mismatches and iterate.
For a single build+run cycle with a machine-readable result, use
`python3 {plugin_root}/skills/ref-model/scripts/run_ref_model.py --refc-dir refc --report refc_run_report.json`
(`{plugin_root}` resolved from `.rat/state/spawn-context.json`) — exit 0 = model ran clean, 1 = build/run failure (report written), 2 = environment error.
5. Bandwidth: `cd refc && make bandwidth` — captures `ext_mem_stats_t`; write `bandwidth_report.json`.
6. Feature coverage: read `iron-requirements.json`, map every `REQ-F-*` to a real code path (structural check — not just bitexact coverage); save `reviews/phase-2-architecture/ref-model-feature-coverage.md`. Escalate any unmapped feature to the user before proceeding.
7. Spawn `ref-model-reviewer` for algorithm fidelity, numeric precision, and UB/memory-safety review.
8. Write `conformance_report.json` with JM/HM version and per-vector pass/fail.
9. Sanitize: `cd refc && make sanitize` (`-fsanitize=address,undefined`) — must pass clean.
Apply steps 1-9 to every algorithm unit requested — do not stop after the first.
<Tool_Usage>
Task(subagent_type="rtl-agent-team:vcodec-syntax-entropy-expert",
prompt="Provide algorithm pseudocode and edge case table for CABAC entropy coding per H.264 spec §9.3.")
Task(subagent_type="rtl-agent-team:ref-model-dev",
prompt="Implement C functional reference model at refc/. Must be bitexact vs JM. "
"No clock/reset — pure functional. I/O as function args. Internal memory as arrays/struct. "
"External memory via ext_mem_read/write. PARALLEL_LANES parameterizable. "
"C11, DPI-C compatible (no C++ features). Use templates/ scaffolding.")
Task(subagent_type="rtl-agent-team:ref-model-reviewer",
prompt="Review refc/ model quality. Check algorithm fidelity, fixed-point/bit-width correctness, "
"build warnings, UB risks, and I/O format compatibility. "
"Save report to reviews/phase-2-architecture/ref-model-review.md with PASS/FAIL verdict.")
</Tool_Usage>
New CABAC entropy coder; Phase 1 complete; JM 19.0 available.
refc/cabac_encoder.c compiled clean; 500 ITU-T vectors pass bitexact vs JM 19.0; bandwidth_report.json shows 2.3 MB/frame reads; all REQ-F-* mapped; ref-model-reviewer issues PASS.
Spec change adds intra 8×8 prediction; existing ref model misses REQ-F-042.
ref-model-dev adds intra_predict_8x8(); feature-coverage.md updated; re-run confirms bitexact match; conformance_report.json refreshed.
Datapath width exploration: choose between PARALLEL_LANES=4 and PARALLEL_LANES=8.
bandwidth_report.json generated for both configs; estimated_read_cycles compared; architect selects PARALLEL_LANES=4 based on memory bandwidth budget.
<Escalation_And_Stop_Conditions>
- Bitexact mismatch persists after 3 fix iterations → report failing vectors with diff to user.
- JM/HM not available → halt; instruct user to install before proceeding.
- Feature coverage < 100% and user declines to implement missing feature → record ADR with impact estimate; proceed only with explicit approval.
- External memory bandwidth exceeds technology limits → escalate to arch-designer for block restructuring.
</Escalation_And_Stop_Conditions>
Output
refc/*.c, refc/include/*.h — C11 functional reference model.conformance_report.json — per-vector bitexact results with JM/HM version.bandwidth_report.json — external memory access statistics per block.reviews/phase-2-architecture/ref-model-feature-coverage.md — REQ-F-* mapping table.reviews/phase-2-architecture/ref-model-review.md — reviewer verdict.
<Final_Checklist>
