evals/README.md

# Golden evals

Purpose: catch silent research-behavior drift - output shape, column names/order, metadata
fields, warning codes - per design doc §16.

- `golden_datasets/` - frozen input corpora (never edit rows in place; add new files).
- `expected_outputs/` - human-approved expected results. **Protected by a PreToolUse hook:**
  Claude Code cannot edit files here. To update after an approved behavior change, regenerate
  manually and review the diff yourself before committing.
- Runner arrives with spec 0005 (engine extraction freezes behavior first). Until then, the
  backend test suite's export-shape tests are the drift guard.

Rule of thumb: if a golden diff surprises you, the code is wrong until proven otherwise.