From 6200ebc6e4f2524111a9e6d3db6c868e1251d0f8 Mon Sep 17 00:00:00 2001
From: Vince Buffalo <vsbuffalo@gmail.com>
Date: Fri, 10 Jul 2026 12:47:25 -0700
Subject: [PATCH] docs: sync Golden File Management to the real Makefile
 targets (gh#382)

CLAUDE.md's Golden File Management section documented two commands and a
path that do not exist:

  $ grep -nE '^update-expected' Makefile   -> (no match)
  $ ls -d ir/expected                       -> No such file or directory

`make update-golden` does not write `ir/golden/`; it fans out to
`update-ocaml-golden` (-> ocaml/golden/*.ir.json) plus the six
tests/fixtures/*/ir/ sets (Makefile:251). Forward-trajectory baselines are
captured via CAMDL_CAPTURE_BASELINE=1 into the gate tests, not a
`make update-expected` -> ir/expected/ pipeline (neither exists).

Rewrites the section to the current reality and notes that `ir/golden/` is
a separate frozen committed set whose consolidation is tracked in gh#384.
Doc-only.

Closes #382.
---
 CLAUDE.md | 36 +++++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a25b30a6..dddf3786 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -320,25 +320,39 @@ in `docs/dev/proposals/2026-06-04-camdlc-version-guard.md`.
 
 ## Golden File Management
 
-Golden files in `ir/golden/` are the integration test surface — committed IR
-JSON that both sides must parse and agree on.
+Golden IR files are committed, fully-expanded IR JSON that both languages must
+parse and agree on. `make update-golden` regenerates them from their DSL
+fixtures — it fans out to `update-ocaml-golden` (→ `ocaml/golden/*.ir.json`)
+plus the per-fixture sets under `tests/fixtures/*/ir/` (corner_cases,
+regression, reactive, quantities, contrasts, gradient):
 
 ```bash
-make update-golden    # recompile DSL fixtures → ir/golden/*.ir.json
-make update-expected  # re-simulate golden models → ir/expected/*.tsv
+make update-golden    # recompile every DSL fixture → its committed *.ir.json
 ```
 
-When adding a new model: write DSL in `tests/fixtures/`, run `update-golden`,
-review the JSON, run `update-expected`, review the TSV, commit all three
-together.
+There is no `make update-expected` / `ir/expected/`. Forward-trajectory
+baselines for the corner-case / regression goldens are captured into the gate
+tests (e.g. `gate_corner_case_baseline.rs`) by re-running with
+`CAMDL_CAPTURE_BASELINE=1` — not a separate expected-TSV directory.
+
+`ir/golden/*.ir.json` is a **separate, frozen committed set** — the
+cross-language serde + forward-sim smoke surface (`rust/tests/golden_deser.rs`,
+`sim/tests/golden_simulate.rs`, and ~two dozen other integration tests read it).
+It is **not** regenerated by `update-golden`; folding it into the regenerable
+`ocaml/golden` set is tracked in gh#384.
+
+When adding a new model: write the DSL under the appropriate `tests/fixtures/…`
+(or `ocaml/golden/`) directory, run `make update-golden`, review the emitted
+JSON, re-capture any gate baseline it feeds (`CAMDL_CAPTURE_BASELINE=1`), and
+commit the fixture + golden together.
 
 ### Goldens are an explicit, reviewed, human-loop change — never collateral
 
 A golden or `ir/VERSION` change is a deliberate act, not a side effect. The
-serialized format and content of `ir/golden/`, `ocaml/golden/`, and
-`ir/expected/` are load-bearing (the `ir.json` format is `bf5d13b`'s compact
-serialization — one element per line — chosen for a 4.6×/5× compile+size win on
-national-scale models; see
+serialized format and content of `ir/golden/`, `ocaml/golden/`, and the
+`tests/fixtures/*/ir/` sets are load-bearing (the `ir.json` format is
+`bf5d13b`'s compact serialization — one element per line — chosen for a 4.6×/5×
+compile+size win on national-scale models; see
 `docs/dev/proposals/archive/post-alpha/2026-05-30-compact-ir-serialization.md`).
 
 - **Stage goldens explicitly.** Never `git add -A` / `git commit -a` when golden