fix(eval): restore SEC_UNIT_TERMS_REF override with fail-fast on missing path

[sroussey]

Finding

PR #211 (this branch's parent) silently removed the SEC_UNIT_TERMS_REF env override from src/eval/embarcUnitTermsReference.ts when the module was refactored to use resolveAsset() and fileURLToPath. The pre-#211 resolveReferencePath() began with:

const envPath = process.env.SEC_UNIT_TERMS_REF;
return resolveAsset([
  ...(envPath ? [envPath] : []),
  join(import.meta.dir, "mock_data/embarc-spac-unit-terms.csv"),
  ...
]);

That override is the seam downstream packages depend on — the published @workglow/sec tarball does not ship mock_data/, so embarc-data (and any future consumer of loadEmbarcUnitTermsReference()) points SEC_UNIT_TERMS_REF at its own vendored copy of the CSV. Without it, loadEmbarcUnitTermsReference() throws at any consumer that doesn't have the source-tree layout on disk.

Fix

1. Restore the override. Re-add the process.env.SEC_UNIT_TERMS_REF check in resolveReferencePath().
2. Strengthen the semantics. When the env var is set, honor it strictly: a missing file throws a clear error naming the env var and the path, rather than silently falling through to the package-relative default. A typo in a downstream caller's env cannot masquerade as "fixture missing, using default" anymore — this is the improvement over pre-test(config,vitest): harden test isolation and complete vitest migration #211 behavior.
3. Restore & update the explanatory docstring above the resolver.
4. Add existsSync to the node:fs import for the file-exists check.
5. Export _resetEmbarcUnitTermsCacheForTesting() so tests can force reload without vi.resetModules().
6. Tests (src/eval/embarcUnitTermsReference.test.ts): a new describe("SEC_UNIT_TERMS_REF override") block with three cases, wrapping process.env.SEC_UNIT_TERMS_REF in beforeEach/afterEach restore and calling the reset helper:
   • env set + file exists → loader returns the row from the override CSV;
   • env set + file missing → loader throws matching /SEC_UNIT_TERMS_REF.*does not exist/;
   • env unset → committed fixture still loads (> 1200 rows, mirroring the existing baseline test).
7. Docs: added a SEC_UNIT_TERMS_REF bullet next to SEC_S1_MOCK_DIR in CLAUDE.md.

Verification

• bun x vitest run src/eval/embarcUnitTermsReference.test.ts → 10 passed (7 existing + 3 new).
• bun x tsc --noEmit -p tsconfig.json → clean.

Only src/eval/embarcUnitTermsReference.ts, its test file, and the CLAUDE.md bullet are touched. No unrelated changes; no version bump.

Stacking

This PR stacks on top of #211 (base = claude/beautiful-archimedes-o87xem). Merge #211 first; this PR should then rebase cleanly onto main.

---

Generated by Claude Code