# Handoff Notes

## Quick status
- Pipeline: question-first by default (JSONL chunks), deterministic chunk IDs, cache-backed (questions/gens/verifications/rewards).
- Generator parsing/logging: preserves provider `.thinking` plus parsed thought/answer/confidence/evidence/limitations; verbose logs show both parsed and raw (pretty-printed if JSON). Gold stores all of these fields.
- Verifier: expects distributor prompt output; accepts `SCORE` as number or `PASS/FAIL` (even noisy `PROMPT = PASS`); raw transcript logged in verbose.
- Scripts: `gold_preview.mjs` (shows thought/thinking/raw), `cache_report.mjs`, `regenerate_gold_from_cache.mjs`, `purge_mock_gold.mjs`.
- Tests: passing in writable env (read-only sandboxes block Vitest temp/cache writes).

## Running
- Default verbose CLI: `npm run pipeline -- --limit N --verbose`.
- Question-first mode: `PIPELINE_SEED_MODE=question-first npm run pipeline -- --limit N --verbose`.
- Random walk over chunks: `PIPELINE_RANDOM_WALK=1` (or `PIPELINE_CHUNK_ORDER=random`) + optional `--chunk-limit`.
- Question cap per chunk: `QUESTION_MAX_PER_CHUNK` (e.g., 3).
- Preview gold: `node scripts/gold_preview.mjs --max-answer 2000 --limit 5`.
- Regenerate gold from cache: `node scripts/regenerate_gold_from_cache.mjs`.
- Purge mock Q1? gold: `node scripts/purge_mock_gold.mjs`.

## What to watch
- Cache/gold should stay out of git; regenerate gold via cache script.
- Question provider must be reachable; otherwise question-first will spin through chunks with errors.
- Verifier prompt locked; parsing tolerates PASS/FAIL tokens and logs raw output.
- Generator prompt locked; parsing handles `.thinking` and Qwen-style answer blocks; thought/answer stay separate for verifier/reward.

## Files of note
- `src/generator/generator_core.mjs`: parses provider responses; carries `.thinking`, thought, answer, confidence, evidence, limitations.
- `src/pipeline/step.mjs`: verbose logging of thought, thinking, answer, raw.
- `prompts/*`: locked prompts (do not edit generator/verifier without intent).
- `data/cache/*.jsonl`: intermediate cache (questions/gens/verifications/rewards); use `PIPELINE_CACHE_DIR` to redirect.
- `gold/pipeline_gold.jsonl`: output; rebuild via cache if needed.

## Caveats
- Read-only environments will fail `npm test` due to /tmp and `.vite` writes; run tests where writes are allowed.
- Long generator outputs can bloat verifier context; consider truncation or smaller verifier model if needed.