1@README.md
2
3## Notes for agents
4
5**The questions are yours to refine, without asking.** Standing permission from the
6owner (2026-10-02). When a verdict is wrong or noisy, fix `judge.rs` and say what
7changed. Two rules for doing it: define every term in the option or level it belongs
8to, as concrete acts, never a bare adjective ("destructive" stopped a harmless note in
9another repository); and add a question to the same request rather than overloading
10one, deriving the verdict from the typed answers in code where a test can pin it. A
11request mixes Choice, Score and Noul questions freely; its limit is size, not count
12(Jev's docs, read 2026-10-02: 64k tokens for the state plus all questions, 32k for the
13state plus the longest question, and at most 255 options per Choice).
14
15**Jev judges words unless told what runs.** A command that only writes, prints or
16posts `rm -rf ~/` as text was stopped as if it ran it. `WHAT_RUNS` in `judge.rs` is in
17every command question for that reason; keep it in any new question about a command.
18
19**Only one confident act stops a command, never a sum.** Summing the consequential
20acts' probabilities turned an unsure answer (top act 36%) into a stop. Unsure is
21`Pass`.
22
23**An option's label is what Jev answers with.** `Act::label` and `ENDINGS`' first
24fields are sent as the Choice's labels and matched back (`Act::from_label`, the
25`"stopped-early"` lookup in `stop`); renaming one without the other silently zeroes
26its probability. `every_act_has_its_own_label` guards the acts only.
27
28**`MODEL` is pinned (`jev-1.13.0` in `serve.rs`).** The thresholds were set against
29that model's answers; moving the pin means re-reading `decisions.jsonl` under the new
30one before trusting them.
31
32**Never remove the `stop_hook_active` check.** It is what keeps one refusal of a
33turn's end from becoming a loop of refusals.
34
35**The decision log is evidence, not a guard.** `DecisionLog::append` reports a failed
36write and the decision stands; do not make a full disk block a command.
37
38**Outcomes are logged only for judged tool calls.** `Session.judged` holds their ids
39until `PostToolUse`, `PostToolUseFailure` or `PermissionDenied` removes them; an
40outcome record for an unjudged call would join to nothing.
41
42**A configured memory command is the only source once set.** `Headroom` never falls
43back to `MemAvailable` when the command fails (`a_configured_command_is_the_only_source`).