1@README.md
2
3## Notes for agents
4
5**Score a new revision when it lands.** After adding a revision and its `song.js`, run `op-env-run -- node tools/critic/critic.mjs --write --song <theme>/<song>` and commit the frontmatter with the revision. Only unscored revisions are called, unless `--all` is given.
6
7**Never copy the rubric.** It lives in `website/src/jev/critic.mjs`, shared with the REPL. A reworded copy gives numbers that don't compare with the recorded ones. To change a criterion or a step, change the module, bump `RUBRIC`, and rescore everything with `--all`. Check the spread on controls first (three notes, a one-bar loop) before recording: the old yes/no question gave every song 93-96%.
8
9**Record means, not one call.** A recorded score is `meanVerdict` (website/src/jev/critic.mjs) over `--runs` calls, default 3; keep `artRuns` beside every mean so the spread stays visible. Don't record from `--runs 1` except to test the tool: one call is the noise this replaced.
10
11**Edits are surgical.** The script rewrites only `art:`/`artRuns:` lines and the `critic:` block (`setRevisionArt`, `setCritic` in website/src/jev/critic.mjs, tested in `critic.test.mjs`), keeping the frontmatter's quoting and comments (`# overwritten by rev 2`). Don't switch it to a YAML parse-and-dump, which would reformat every spec.
12
13**Never guess an unrecoverable revision.** When git doesn't hold a revision's code, the record is `art: null  # not scored: …`.
14
15**The key stays in the environment.** Run under `op-env-run`. Never capture the key with `op-env-run -- printenv` (1Password masks it as `<concealed by 1Password>`), never print it, and never write it down.