heeded 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Musso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# heeded
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+did your coding agent follow its instructions?
+
+you write rules for your agent in `CLAUDE.md` and hope they stick. heeded reads the transcripts claude code keeps on
+disk and tells you which rules were kept, which were broken, when and where.
+
+```text
+$ npx heeded
+
+  ~/repos/app · 76 sessions, 412 subagents · oct 11 – nov 10
+  3 files · 41 rules · 12 checked · 29 need a judge
+
+  CLAUDE.md
+    ✗ :12  never git add -A    kept 95% of 214            broken 9×    last 2 days ago
+        nov 8   19df6c20  git add -A && git commit -m "fix: …"
+        nov 2   8c0e8fab  git add -A
+    ✓ :14  never force-push    kept 100% of 61
+    ○ :21  use pnpm, not npm   never applied              ~40 tokens every session
+    · :30  failing test first  kept 80% of 20 judged      broken 4×    last 3 days ago
+  ~/.claude/CLAUDE.md
+    ✗ :3   answer in italian   kept 96% of 3,812          broken 152×  last today
+        after compaction kept 69% of 410
+    ○ :17  ask before deploys  never applied in 8 judged  ~30 tokens every session
+
+  kept by context depth   0–100k   100–200k   200–400k   400k+
+                             98%        97%        91%     84%
+
+  6 rules no call or reply shows: heeded rules
+  up to date: new sessions and changes to instruction files are read on the next run
+```
+
+<sub>a sketch: the numbers are invented.</sub>
+
+| mark | the rule |
+| --- | --- |
+| `✗` | was broken: every case confirmed by the judge, listed with its date, session and call |
+| `✓` | was kept every time it applied |
+| `?` | has candidates only: a pattern flagged them, the judge hasn't looked yet |
+| `○` | never applied in these sessions: it sits in every session's context all the same |
+| `·` | needs a judge, no pattern can decide it: a sample of its cases was judged |
+
+- `kept 95% of 214`: the rule applied 214 times and was kept in 95% of them.
+- `after compaction`: the same rule, counted only after claude code compacted the context.
+- each rule is under the file it is written in: the folder's files first, then the others (`~/.claude/CLAUDE.md` is
+  loaded in every project, so a rule there can be never applied here and needed elsewhere).
+- `:12`: the line the rule starts on in that file, as the file is now. no number: its words aren't in the file any
+  more.
+- `kept by context depth`: every rule together, by how full the context was at the time.
+- `never applied in 8 judged`: none of the 8 cases the judge read was about the rule.
+- `rules no call or reply shows`: rules about how to work ("plan before coding"), which no single call or reply can
+  show; `heeded rules` lists them.
+
+## use
+
+needs node 22 or later and claude code, signed in: heeded calls your own `claude` to read rules and to judge.
+
+1. **run it in a project** you've worked on with claude code:
+
+   ```sh
+   cd ~/code/my-app
+   npx heeded
+   ```
+
+2. **say yes, or not yet.** reading the rules and judging cost tokens from your claude account, so heeded shows the
+   estimate and asks before spending anything:
+
+   ```text
+   11 rule sections to read, then cases to judge · claude sonnet and haiku · up to ~175k tokens
+   go ahead? [y/N]
+   ```
+
+   `y` reads the rules, judges a first round of cases and prints the report. enter spends nothing: the report shows
+   what is already cached, on a first run the sessions found and the sections still to read.
+
+3. **act on the report.** each rule is under its file, with its line (`:12`). a rule broken often may need
+   rewriting, or saying why it matters. a rule never applied costs its tokens in every session: move it to the project
+   it's for, or remove it. `heeded rules` shows how each rule is checked, and the ones no call or reply can show.
+
+4. **run it again** whenever you like: after more sessions, or after editing an instruction file. every run reads the
+   transcripts again, for free, and asks only when something new costs tokens. what was read or judged is cached and
+   never paid for twice; with nothing new, the report ends `up to date`.
+
+```sh
+npx heeded           # the report, for the claude code sessions run in this folder
+npx heeded rules     # the rules found, and how each one is checked
+npx heeded --all     # judge every case waiting, not one run's 150k tokens
+npx heeded --json    # everything, as json
+```
+
+to type `heeded` instead of `npx heeded`, install it: `npm install -g heeded`.
+
+## how it works
+
+1. **find the sessions.** the transcripts of the sessions run in this folder and its worktrees, subagents included,
+   under `~/.claude/projects/`.
+2. **read the rules.** claude code writes into each transcript the instruction files it loaded, word for word. heeded
+   splits them into sections and asks `claude` (sonnet) for each section's rules, each with a check:
+   - a pattern over a tool call, like `git add -A` in a bash command;
+   - the language replies must be in;
+   - otherwise, the calls or replies the rule is about, left to the judge.
+
+   a check that fails its own examples is set aside. a section is read once, then cached.
+3. **check every call.** one pass over the transcripts: each call and reply against the rules in effect at that point.
+   a shell command is read the way a shell reads it, so `echo "rm -rf"` isn't running `rm`.
+4. **judge.** a pattern finds candidates, not violations. each candidate, and a sample of the cases no pattern can
+   decide, goes to `claude` (haiku) with an excerpt of its session: your prompt, what the agent did since, the call
+   itself. it answers broken, kept, or doesn't apply. only your words grant a permission; an agent's never do. each
+   verdict is cached. a rule the judge decides is tried on 8 of its cases first: if none is about it, it stops there;
+   if some are, it goes on to 20 cases that applied, or 40 judged. up to 3 calls run at once.
+5. **report.** each rule under its file, at its line in the file as it is now: kept, broken with the evidence, never
+   applied; by context depth and after compaction.
+
+steps 2 and 4 cost tokens: heeded asks once, before spending anything. a run judges within 150k tokens and nothing is
+paid for twice, so coverage grows run after run. `heeded --all` goes to the end instead: its question shows what waits
+now and the most it can reach, then it judges round after round until nothing waits. off a terminal (ci, a script) it
+never spends.
+
+`heeded rules` shows what each rule became:
+
+```text
+$ npx heeded rules
+
+  ~/repos/app · 1 file · 5 rules
+
+  CLAUDE.md
+    ✓ :8   never git add -A           Bash command  when (^|\s)git\s+add(\s|$)  broken \s(-A|--all)\b
+    ✓ :12  answer in italian          language it
+    · :15  commit only when asked     judged on Bash command  when (^|\s)git\s+commit(\s|$)
+    · :19  say what you changed       judged on replies
+    ! :23  never kill the dev server  failed its examples: keeps "pkill -f vite-test"
+```
+
+`✓` a pattern decides it: `when` picks the calls it applies to, `broken` the ones that break it. `·` the judge
+decides, on the calls or replies shown. `!` its check was set aside, and why.
+
+## privacy
+
+local and read-only: heeded never changes your transcripts, instruction files or settings, and writes only to its own
+cache (`~/.cache/heeded`, or under `$XDG_CACHE_HOME`). two things leave your machine, through your own `claude`: the
+text of instruction sections not read before, and the excerpts the judge reads. both have secrets redacted first, and
+what is written to files like `.env` is never sent. no telemetry.
+
+`CLAUDE_CONFIG_DIR` points heeded at another claude code folder (default `~/.claude`).
+
+## license
+
+[mit](LICENSE)

package/dist/check.js

@@ -0,0 +1,495 @@
+import { excerpts } from './judge.js';
+import { redact } from './redact.js';
+import { commands } from './shell.js';
+/** The most common words of each language a reply can be detected in. */
+const STOPWORDS = {
+    en: `the be to of and a in that have i it for not on with he as you do at this but his by from they we say her she or an
+    will my one all would there their what so up out if about who get which go me when make can like no just him know
+    take into your some could them see other than then now only its also how our well way even because any these us is
+    are was were been has had does did should here where why very`,
+    it: `il lo la i gli le un uno una di da in con su per tra fra a e o ma che non come anche se più è sono era sia del della
+    dei degli delle al alla allo ai agli alle dal dalla nel nella nei sul sulla questo questa questi quello quella ci si mi
+    ti ne cosa perché quando dove tutto molto ancora già poi solo ho hai ha abbiamo hanno essere fare può adesso quindi ora`,
+    es: `el la los las un una unos unas de del a al en con por para que y o pero no sí es son era fue ser está están estar
+    como más muy también ya este esta estos estas ese esa eso lo le les se me te nos su sus mi tu cuando donde porque hay
+    hacer puede todo nada algo bien entre sobre sin hasta desde ahora así luego aquí pues`,
+    fr: `le la les un une des de du à au aux en dans par pour sur avec sans que qui et ou mais ne pas plus est sont était
+    être avoir ai as ont ce cette ces cet il elle ils elles je tu nous vous on se me te lui leur son sa ses mon ma mes
+    comme aussi très bien tout tous faire peut fait donc alors si quand où vais`,
+    de: `der die das den dem des ein eine einen einem einer und oder aber nicht ist sind war waren sein haben hat habe ich du
+    er sie es wir ihr mit von zu zum zur auf für bei aus nach über unter vor auch noch nur schon sehr wie wenn dass weil
+    was wer wo hier dann jetzt kann muss soll mehr kein keine diese dieser dieses man sich im deshalb`,
+    pt: `o a os as um uma uns umas de do da dos das em no na nos nas por para com sem que e ou mas não sim é são era foi ser
+    estar está estão ter tem como mais muito também já este esta isso esse essa ele ela eles elas eu você nós se me te
+    lhe seu sua quando onde porque há fazer pode tudo nada bem entre sobre até então agora vou depois ainda aqui pelo pela
+    ao aos num numa`,
+};
+/** The languages a reply can be detected in. */
+export const LANGUAGES = Object.keys(STOPWORDS);
+/** Each stopword's language; a word shared by two languages (`de`, `que`, `a`) tells none apart, so it is left out. */
+const WORDS = new Map();
+for (const [code, words] of Object.entries(STOPWORDS)) {
+    for (const w of words.split(/\s+/))
+        WORDS.set(w, WORDS.has(w) && WORDS.get(w) !== code ? null : code);
+}
+/**
+ * The language a reply is written in, or null when it can't be told: under 20 words once code, quoted blocks (someone
+ * else's words), URLs and paths are removed, or no clear winner (at least 5 stopwords, twice the runner-up's).
+ */
+export function language(text) {
+    const prose = text.replace(/(```|~~~)[\s\S]*?(\1|$)/g, ' ').replace(/^[ \t]*>.*$/gm, ' ').replace(/`[^`\n]*`/g, ' ')
+        .replace(/\S*[/\\]\S*/g, ' ');
+    const words = prose.toLowerCase().match(/\p{L}+/gu) ?? [];
+    if (words.length < 20)
+        return null;
+    const hits = new Map();
+    for (const w of words) {
+        const code = WORDS.get(w);
+        if (code)
+            hits.set(code, (hits.get(code) ?? 0) + 1);
+    }
+    const [first, second] = [...hits].sort((a, b) => b[1] - a[1]);
+    return first && first[1] >= 5 && first[1] >= 2 * (second?.[1] ?? 0) ? first[0] : null;
+}
+/**
+ * Whether a pattern repeats a group that holds a quantifier or an alternation, at any depth — `(a+)+`, `((a+))+`,
+ * `(a|a)+` — the shapes that can take exponential time on a long value. Character classes are read as one atom.
+ */
+function exponential(source) {
+    const open = []; // per open group: whether it holds a quantifier or an alternation
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        if (c === '\\')
+            i++;
+        else if (c === '[') {
+            for (i++; i < source.length && source[i] !== ']'; i++)
+                if (source[i] === '\\')
+                    i++;
+        }
+        else if (c === '(')
+            open.push(false);
+        else if (c === ')') {
+            const holds = open.pop() ?? false;
+            const repeated = /[*+{]/.test(source[i + 1] ?? '');
+            if (holds && repeated)
+                return true;
+            if (open.length && (holds || repeated))
+                open[open.length - 1] = true;
+        }
+        else if (/[*+{|]/.test(c) && open.length)
+            open[open.length - 1] = true;
+    }
+    return false;
+}
+/**
+ * The check's patterns as regular expressions, or why they can't be used. Never `g` or `y` (they keep state between
+ * calls) nor `u` (model-written patterns often escape characters it rejects); `i` only when the check asks.
+ */
+export function compile(check) {
+    const flags = check.ignoreCase ? 'i' : '';
+    const compiled = { field: check.field, when: {}, broken: {} };
+    for (const part of ['when', 'broken']) {
+        for (const key of ['tool', 'value', 'data']) {
+            const source = check[part]?.[key];
+            if (source === undefined)
+                continue;
+            if (exponential(source))
+                return `regex may take exponential time: ${source}`;
+            try {
+                compiled[part][key] = new RegExp(source, flags);
+            }
+            catch {
+                return `regex doesn't compile: ${source}`;
+            }
+        }
+    }
+    return compiled;
+}
+// The last command line read: every rule in effect looks at the same call in turn.
+let last;
+/** What a check's field shows: one view per simple command of a shell `command`, else the value whole; none when the
+ * check has no field or the call's field isn't a string. */
+function views(field, input) {
+    const value = field === undefined ? undefined : input[field];
+    if (typeof value !== 'string')
+        return [];
+    if (field !== 'command')
+        return [{ does: value, carries: '', text: value }];
+    if (last?.line !== value)
+        last = { line: value, views: commands(value) };
+    return last.views;
+}
+/** Each view is matched on its first 4,096 characters: model-written patterns over a huge command or file stay cheap. */
+const hits = (p, v) => (!p.value || p.value.test(v.does.slice(0, 4096)))
+    && (!p.data || p.data.test(v.carries.slice(0, 4096)));
+const needs = (p) => p.value !== undefined || p.data !== undefined;
+/** Whether one of a call's views matches the patterns; a loop, not a closure: it runs for every rule on every call. */
+function found(p, all) {
+    if (!needs(p))
+        return true;
+    for (const v of all)
+        if (hits(p, v))
+            return true;
+    return false;
+}
+/**
+ * Whether the rule applies to a call and, when it does, the view that broke it: the call applies when its tool
+ * matches and one view matches `when`; it is broken when, besides, that same view matches `broken`.
+ */
+function assess(c, tool, input) {
+    if (c.when.tool && !c.when.tool.test(tool))
+        return { verdict: 'none' };
+    const all = views(c.field, input);
+    const applying = needs(c.when) ? all.filter((v) => hits(c.when, v)) : all;
+    if (needs(c.when) && !applying.length)
+        return { verdict: 'none' };
+    if (c.broken.tool && !c.broken.tool.test(tool))
+        return { verdict: 'kept' };
+    if (!needs(c.broken))
+        return { verdict: 'broken' };
+    const by = applying.find((v) => hits(c.broken, v));
+    return by ? { verdict: 'broken', by } : { verdict: 'kept' };
+}
+export function verdict(c, tool, input) {
+    return assess(c, tool, input).verdict;
+}
+/** Whether a call is one the check is about, whatever would break it: asked on every call, so it allocates nothing. */
+export function applies(c, tool, input) {
+    return (!c.when.tool || c.when.tool.test(tool)) && found(c.when, views(c.field, input));
+}
+/**
+ * What broke the rule, as written: the simple command (followed by what it carries, when the check reads that and the
+ * command as written doesn't show it: a heredoc's body), the field's value, or the tool when the check has no field.
+ */
+export function culprit(c, tool, input) {
+    const by = assess(c, tool, input).by;
+    if (by)
+        return (c.when.data || c.broken.data) && !by.text.includes(by.carries) ? `${by.text} ${by.carries}` : by.text;
+    const value = c.field === undefined ? undefined : input[c.field];
+    return typeof value === 'string' ? value : tool;
+}
+/** Context depth buckets, in tokens: where the context window fills up. */
+const DEPTHS = [0, 100_000, 200_000, 400_000];
+const buckets = (counts) => counts.map((c, i) => ({ from: DEPTHS[i], to: DEPTHS[i + 1] ?? null, ...c }));
+const zero = () => ({ applied: 0, broken: 0 });
+const add = (c, broken) => {
+    c.applied++;
+    if (broken)
+        c.broken++;
+};
+/** The cases a rule keeps waiting, at most: a run judges far fewer. */
+const WAITING = 40;
+/** A judgment rule's sample: its first 8 cases, and if none of them applies, no more: a rule that doesn't concern the
+ * folder (a global rule about a tool it never uses) stops costing. Once one applies, judged until 20 of its cases are
+ * decided, or 40 judged in all. */
+const PROBE = 8;
+const DECIDED = 20;
+const JUDGED = 40;
+const allowed = (t) => (t.rule.kind !== 'judgment' ? Infinity
+    : Math.max(0, t.all.applied ? Math.min(JUDGED - t.judged, DECIDED - t.all.applied) : PROBE - t.judged));
+/** Whether a rule's sample may ever take another case. Unlike `allowed`, never true again once false: a sample stopped
+ * after 8 cases that didn't apply opens again when a later case applies. */
+const open = (t) => t.rule.kind !== 'judgment' || Math.min(JUDGED - t.judged, DECIDED - t.all.applied) > 0;
+/** The most a rule may still take: a judgment rule whose sample hasn't ended, every case up to 40 judged. */
+const most = (t) => (t.rule.kind !== 'judgment' ? t.unjudged : allowed(t) ? Math.min(t.unjudged, JUDGED - t.judged) : 0);
+/** A rule's cases waiting: latest first (ties by key), an excerpt once (two events can read alike), at most 40. */
+function trim(list) {
+    list.sort((a, b) => (a.at !== b.at ? (a.at > b.at ? -1 : 1) : a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const keys = new Set();
+    let n = 0;
+    for (const x of list) {
+        if (n === WAITING || keys.has(x.key))
+            continue;
+        keys.add(x.key);
+        list[n++] = x;
+    }
+    list.length = n;
+}
+/** Into a rule's cases waiting, trimmed now and then rather than kept in order: rules × events is the hot loop. */
+function wait(list, x) {
+    list.push(x);
+    if (list.length > 2 * WAITING)
+        trim(list);
+}
+/** A violation in one line, secrets redacted: what in the call broke the rule, a reply's language and first words. */
+function evidence(e, c, detected) {
+    if (e.kind === 'reply') {
+        const words = redact(e.text).split(/[\p{Cc}\s]+/u).filter(Boolean);
+        return `${detected}: "${words.slice(0, 8).join(' ')}${words.length > 8 ? ' …' : ''}"`;
+    }
+    const line = redact(culprit(c, e.tool, e.input)).replace(/[\p{Cc}\s]+/gu, ' ').trim();
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}
+/**
+ * Counts, over a stream of events, how often each rule applied and how often it was broken. Each transcript starts with
+ * no file in effect; the rules in effect are those of the files its `instructions` events recorded. A call a tool
+ * rule's patterns say broke it is a candidate, and a call or reply a judgment rule is about is a case of it: either
+ * counts by the judge's verdict, and waits for one until then.
+ */
+export function counter(rulesOf, verdictOf = () => null) {
+    const tallies = new Map();
+    let inEffect = new Map();
+    let checked = []; // the tool and language rules in effect
+    let finders = [];
+    let replying = [];
+    // Resumed and forked sessions copy history into new files: an event counts once. Only events a rule applied to are
+    // remembered.
+    const seen = new Set();
+    let session = '';
+    let agent = null;
+    // Every version of every section seen, with the last time it was in effect during a call or reply; and those of the
+    // files in effect now.
+    const versions = new Map();
+    let current = [];
+    const files = new Set();
+    let sessions = 0;
+    let subagents = 0;
+    let active = false;
+    let from = null;
+    let to = null;
+    const excerpt = excerpts();
+    function refresh() {
+        const ids = new Set();
+        const groups = new Map();
+        const whens = new Map();
+        checked = [];
+        replying = [];
+        current = [];
+        for (const file of inEffect.values()) {
+            const found = rulesOf(file);
+            if (!found)
+                continue;
+            files.add(file.path);
+            for (const v of found.versions) {
+                const key = `${v.identity}\0${v.section.hash}`;
+                let seen = versions.get(key);
+                if (!seen)
+                    versions.set(key, (seen = { ...v, at: '' }));
+                current.push(seen);
+            }
+            for (const rule of found.rules) {
+                let t = tallies.get(rule.id);
+                if (!t) {
+                    // verify demoted every tool rule, and gave no cases to every judgment rule, whose check doesn't compile
+                    const compiled = (rule.kind === 'tool' && !rule.demoted)
+                        || (rule.kind === 'judgment' && !rule.noCases && rule.check?.reply !== true)
+                        ? compile(rule.check) : null;
+                    t = { rule, files: new Set(), all: zero(), after: zero(), depth: DEPTHS.map(zero), evidence: [], compiled, judged: 0,
+                        unjudged: 0, waiting: [] };
+                    tallies.set(rule.id, t);
+                }
+                t.files.add(file.path);
+                // A quote read two ways (two versions of a section) is one rule: it is counted as it was first read, which its
+                // tally's check was compiled from.
+                const { demoted, noCases, kind, check } = t.rule;
+                if (!ids.has(rule.id) && !demoted && !noCases) {
+                    ids.add(rule.id);
+                    if (kind !== 'judgment')
+                        checked.push(t);
+                    else if (check?.reply === true)
+                        replying.push(t);
+                    else {
+                        const { field, when, ignoreCase } = check;
+                        const key = JSON.stringify([field, when?.tool, ignoreCase === true]);
+                        let group = groups.get(key);
+                        if (!group)
+                            groups.set(key, (group = { field, tool: t.compiled.when.tool, whens: [] }));
+                        const same = JSON.stringify([key, when?.value, when?.data]);
+                        const w = whens.get(same);
+                        if (w)
+                            w.tallies.push(t);
+                        else
+                            group.whens.push(whens.set(same, { when: t.compiled.when, tallies: [t] }).get(same));
+                    }
+                }
+            }
+        }
+        finders = [...groups.values()];
+    }
+    /** Of each section, the version in effect latest. */
+    function latest() {
+        const last = new Map();
+        for (const v of versions.values()) {
+            const l = last.get(v.identity);
+            if (!l || v.at > l.at || (v.at === l.at && v.read))
+                last.set(v.identity, v);
+        }
+        return [...last.values()];
+    }
+    /**
+     * The sections to read: of each section, the version in effect latest when it wasn't read, unless a version of it
+     * read already was in effect as late. The others take that version's rules meanwhile.
+     */
+    function unread() {
+        return latest().filter((v) => !v.read && (v.readAt === null || v.at > v.readAt));
+    }
+    function pending() {
+        return unread().map(({ section, identity, at }) => ({ section, identity, at }));
+    }
+    /** The versions read, with when they were last in effect: what the cache remembers moves forward with them. */
+    function readVersions() {
+        return latest().filter((v) => v.read && v.at).map(({ section, identity, at }) => ({ section, identity, at }));
+    }
+    /** One more case a rule applied to; a violation's evidence, as `text` says it. */
+    function record(t, e, broken, text, quote) {
+        add(t.all, broken);
+        if (e.compactions > 0)
+            add(t.after, broken);
+        add(t.depth[DEPTHS.findLastIndex((d) => e.depth >= d)], broken);
+        if (broken)
+            t.evidence.push({ at: e.at, session, agent, text: text(), ...(quote ? { quote } : {}) });
+    }
+    /** A case the judge decides, a tool rule's candidate or a judgment rule's case: counted by its verdict, or waiting. */
+    function decide(t, e) {
+        seen.add(e.id);
+        const x = excerpt.of(e); // its text is built only when read
+        const v = verdictOf(t.rule.id, x.key);
+        if (!v) {
+            t.unjudged++;
+            // A rule whose sample is full takes no more cases; one stopped by its first 8 still does, as it may open again.
+            if (open(t))
+                wait(t.waiting, x);
+            return;
+        }
+        t.judged++;
+        if (v.verdict === 'none')
+            return;
+        // A judgment rule's evidence is its case's own line; a tool rule's, what in the call broke it.
+        const own = () => {
+            const line = x.text.slice(x.text.lastIndexOf('\n') + 1);
+            return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+        };
+        record(t, e, v.verdict === 'broken', t.rule.kind === 'judgment' ? own : () => evidence(e, t.compiled, null), v.quote);
+    }
+    function count(e) {
+        // A session or subagent counts once it did something: a transcript with no call or reply isn't one.
+        if (!active) {
+            active = true;
+            if (agent)
+                subagents++;
+            else
+                sessions++;
+        }
+        if (!from || e.at < from)
+            from = e.at;
+        if (!to || e.at > to)
+            to = e.at;
+        let detected;
+        for (const t of checked) {
+            let v = 'none';
+            if (e.kind === 'call' && t.compiled)
+                v = verdict(t.compiled, e.tool, e.input);
+            else if (e.kind === 'reply' && t.rule.kind === 'language') {
+                detected ??= language(e.text);
+                if (detected)
+                    v = detected === t.rule.check?.language ? 'kept' : 'broken';
+            }
+            if (v === 'none')
+                continue;
+            seen.add(e.id);
+            // A tool rule's patterns find candidates: whether one broke the rule is the judge's to say.
+            if (v === 'broken' && t.compiled)
+                decide(t, e);
+            else
+                record(t, e, v === 'broken', () => evidence(e, null, detected ?? null));
+        }
+        if (e.kind === 'reply')
+            for (const t of replying)
+                decide(t, e);
+        // The agent's own files (its memory) are no case of the user's rules about their project.
+        else if (!e.own) {
+            for (const f of finders) {
+                if (f.tool && !f.tool.test(e.tool))
+                    continue;
+                const all = views(f.field, e.input);
+                for (const w of f.whens)
+                    if (found(w.when, all))
+                        for (const t of w.tallies)
+                            decide(t, e);
+            }
+        }
+    }
+    return {
+        on(e) {
+            if (e.kind === 'transcript') {
+                ({ session, agent } = e);
+                active = false;
+                inEffect = new Map();
+                checked = [];
+                finders = [];
+                replying = [];
+                current = [];
+            }
+            else if (e.kind === 'instructions') {
+                if (e.replace)
+                    inEffect = new Map();
+                for (const file of e.files)
+                    inEffect.set(file.path, file);
+                refresh();
+            }
+            else if (e.kind === 'call' || e.kind === 'reply') {
+                for (const c of current)
+                    if (e.at > c.at)
+                        c.at = e.at;
+                if (!seen.has(e.id))
+                    count(e);
+            }
+            // Copies are counted once, but their events still lead to the ones after them.
+            excerpt.push(e);
+        },
+        /** Per rule, its latest cases without a verdict: for a judgment rule, only as many as its sample still takes. */
+        waiting() {
+            const of = (kind) => [...tallies.values()].filter((t) => t.rule.kind === kind).map((t) => {
+                trim(t.waiting);
+                return t.waiting.slice(0, allowed(t)).map((x) => ({ id: `${t.rule.id}-${x.key}`, rule: t.rule, excerpt: x.text, at: x.at }));
+            }).filter((l) => l.length);
+            return { tool: of('tool'), judgment: of('judgment') };
+        },
+        pending,
+        readVersions,
+        result() {
+            const rules = [...tallies.values()].map((t) => {
+                const { rule, files, all, after, depth, evidence, judged, unjudged } = t;
+                return {
+                    id: rule.id,
+                    name: rule.name,
+                    quote: rule.quote,
+                    files: [...files],
+                    heading: rule.heading,
+                    lines: {},
+                    status: rule.kind === 'judgment' ? 'judgment' : rule.demoted ? 'demoted'
+                        : all.broken ? 'broken' : all.applied ? 'kept' : unjudged ? 'to-confirm' : 'never-applied',
+                    ...(rule.demoted || rule.noCases ? { reason: rule.demoted ?? rule.noCases } : {}),
+                    ...(rule.check ? { check: rule.check } : {}),
+                    applied: all.applied,
+                    broken: all.broken,
+                    judged,
+                    toJudge: Math.min(allowed(t), unjudged),
+                    afterCompaction: after,
+                    byDepth: buckets(depth),
+                    tokens: Math.ceil(rule.quote.length / 4),
+                    evidence: evidence.toReversed().sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0)),
+                };
+            });
+            // Broken rules first, the least kept leading; then kept, to confirm, never applied, judgment, demoted.
+            const rank = ['broken', 'kept', 'to-confirm', 'never-applied', 'judgment', 'demoted'];
+            const keptShare = (r) => (r.applied ? (r.applied - r.broken) / r.applied : 0);
+            rules.sort((a, b) => rank.indexOf(a.status) - rank.indexOf(b.status) || keptShare(a) - keptShare(b)
+                || b.applied - a.applied);
+            const sum = DEPTHS.map(zero);
+            for (const t of tallies.values()) {
+                t.depth.forEach((c, i) => {
+                    sum[i].applied += c.applied;
+                    sum[i].broken += c.broken;
+                });
+            }
+            // Sections by their text: a worktree's copy of a file is one section to read. A text with rules from before under
+            // one of its paths is one to read again, not also one never read.
+            const reread = new Set(unread().filter((v) => v.before).map((v) => v.section.hash));
+            const never = new Set(unread().filter((v) => !reread.has(v.section.hash)).map((v) => v.section.hash));
+            return { from, to, sessions, subagents, files: [...files], notRead: never.size, toReread: reread.size,
+                toJudge: rules.reduce((n, r) => n + r.toJudge, 0), atMost: [...tallies.values()].reduce((n, t) => n + most(t), 0),
+                rules, byDepth: buckets(sum) };
+        },
+    };
+}