heeded 0.1.0 → 0.1.1

package/README.md

@@ -12,16 +12,16 @@ $ npx heeded
   3 files · 41 rules · 12 checked · 29 need a judge
 
   CLAUDE.md
-    ✗ never git add -A    kept 95% of 214            broken 9×    last 2 days ago
+    ✗ :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
-    ✓ never force-push    kept 100% of 61
-    ○ use pnpm, not npm   never applied              ~40 tokens every session
-    · failing test first  kept 80% of 20 judged      broken 4×    last 3 days ago
+    ✓ :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
-    ✗ answer in italian   kept 96% of 3,812          broken 152×  last today
+    ✗ :3   answer in italian   kept 96% of 3,812          broken 152×  last today
         after compaction kept 69% of 410
-    ○ ask before deploys  never applied in 8 judged  ~30 tokens every session
+    ○ :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%
@@ -44,6 +44,8 @@ $ npx heeded
 - `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
@@ -51,6 +53,34 @@ $ npx heeded
 
 ## 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
@@ -58,7 +88,7 @@ npx heeded --all     # judge every case waiting, not one run's 150k tokens
 npx heeded --json    # everything, as json
 ```
 
-needs node 22 or later and claude code, signed in: heeded calls your own `claude` to read rules and to judge.
+to type `heeded` instead of `npx heeded`, install it: `npm install -g heeded`.
 
 ## how it works
 
@@ -78,23 +108,13 @@ needs node 22 or later and claude code, signed in: heeded calls your own `claude
    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: kept, broken with the evidence, never applied; by context depth and after
-   compaction.
-
-steps 2 and 4 cost tokens. heeded shows the estimate and asks once, 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]
-```
-
-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.
+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.
 
-run it again whenever you like: every run reads the transcripts again, for free, and asks only when something new
-costs tokens (sessions since, a section edited). what was read or judged is cached and never paid for twice; with
-nothing new, the report ends `up to date`.
+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:
 
@@ -104,11 +124,11 @@ $ npx heeded rules
   ~/repos/app · 1 file · 5 rules
 
   CLAUDE.md
-    ✓ never git add -A           Bash command  when (^|\s)git\s+add(\s|$)  broken \s(-A|--all)\b
-    ✓ answer in italian          language it
-    · commit only when asked     judged on Bash command  when (^|\s)git\s+commit(\s|$)
-    · say what you changed       judged on replies
-    ! never kill the dev server  failed its examples: keeps "pkill -f vite-test"
+    ✓ :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

package/dist/check.js

@@ -455,6 +455,8 @@ export function counter(rulesOf, verdictOf = () => null) {
                     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 } : {}),

package/dist/cli.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
 // The heeded command: arguments, the two commands, the question before spending, exit codes.
-import { readFileSync, realpathSync } from 'node:fs';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs } from 'node:util';
 import { counter } from './check.js';
 import { read } from './claude-code.js';
 import { BUDGET, estimate as judgingEstimate, JUDGE_MODEL, judge, select, verdicts } from './judge.js';
 import { approx, json, rules, text } from './report.js';
-import { estimate, extract, MODEL, remember, rulesOf } from './rules.js';
+import { redact } from './redact.js';
+import { estimate, extract, lineOf, MODEL, remember, rulesOf } from './rules.js';
 const HELP = `heeded — did your coding agent follow its instructions?
 
 usage
@@ -25,12 +26,22 @@ reads CLAUDE_CONFIG_DIR, else ~/.claude. caches rules and verdicts in XDG_CACHE_
 `;
 /** One pass over the folder's transcripts with the rules and verdicts cached so far: the report, the sections to read,
  * the cases waiting for the judge, and what the most the rules may still take would cost. */
-async function scan(configDir, folder, cacheDir) {
+async function scan(configDir, folder, cacheDir, home) {
     const count = counter(rulesOf(cacheDir), verdicts(cacheDir));
     const { unrecognized } = await read(configDir, folder, count.on);
     for (const v of count.readVersions())
         remember(cacheDir, v.identity, v.section.hash, v.at);
     const data = count.result();
+    // Where each rule is written now, what the user opens to rewrite or remove it.
+    // Claude Code reads the user's own file from ~/.claude whatever the config dir.
+    const content = onDisk(folder, [configDir, join(home, '.claude')]);
+    for (const rule of data.rules) {
+        for (const file of rule.files) {
+            const line = lineOf(content(file), rule.quote, rule.heading);
+            if (line)
+                rule.lines[file] = line;
+        }
+    }
     const waiting = count.waiting();
     // A tool rule lists 40 of its candidates: the others cost what those listed cost on average.
     const listed = [...waiting.tool, ...waiting.judgment].flat();
@@ -38,6 +49,30 @@ async function scan(configDir, folder, cacheDir) {
     return { report: { folder, configDir, unrecognized, ...data, toJudgeTokens: Math.round(each * data.toJudge) },
         pending: count.pending(), waiting, mostTokens: Math.round(each * data.atMost) };
 }
+/** Instruction files as they are on disk now, secrets redacted as in what their rules were read from (a redaction
+ * keeps every line); empty for a file gone. Read only in the folder, the folders above it and the agent's own: where
+ * the user already gave access, so no privacy prompt for another folder. And only a regular file under 1 MB: a path
+ * from a transcript may name a pipe, which would never end. */
+function onDisk(folder, own) {
+    const read = new Map();
+    const allowed = (file) => [folder, ...own].some((dir) => file.startsWith(`${dir}/`))
+        || `${folder}/`.startsWith(dirname(file).replace(/\/?$/, '/'));
+    return (file) => {
+        if (!read.has(file)) {
+            let text = '';
+            try {
+                const stat = allowed(file) ? statSync(file) : null;
+                if (stat?.isFile() && stat.size < 1_000_000)
+                    text = redact(readFileSync(file, 'utf8'));
+            }
+            catch {
+                // gone, or not readable: no line
+            }
+            read.set(file, text);
+        }
+        return read.get(file);
+    };
+}
 const thousands = (n) => n.toLocaleString('en-US');
 const plural = (n, word) => `${thousands(n)} ${word}${n === 1 ? '' : 's'}`;
 const clock = (ms) => `${Math.floor(ms / 60_000)}:${String(Math.floor(ms / 1000) % 60).padStart(2, '0')}`;
@@ -79,6 +114,8 @@ export async function main(argv, io) {
         return usage(`unknown command ${command}`);
     if (rest.length)
         return usage(`unexpected ${rest.join(' ')}`);
+    if (command === 'rules' && args.values.all)
+        return usage('--all judges cases, and heeded rules never judges');
     if (args.values.help) {
         io.out(HELP);
         return 0;
@@ -101,7 +138,7 @@ async function run(command, asJson, all, io) {
     const home = io.env.HOME || homedir();
     const configDir = io.env.CLAUDE_CONFIG_DIR || join(home, '.claude');
     const cacheDir = io.env.XDG_CACHE_HOME || join(home, '.cache');
-    let { report, pending, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir);
+    let { report, pending, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir, home);
     let code = 0;
     const failed = (errors) => {
         for (const e of errors)
@@ -120,9 +157,15 @@ async function run(command, asJson, all, io) {
             io.err(`read ${plural(found.read, 'section')} · ${thousands(found.tokens)} tokens\n`);
         failed(found.errors);
         if (found.read)
-            ({ report, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir));
+            ({ report, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir, home));
         return found.read > 0;
     };
+    /** Asks about the new sections alone, and reads them on yes. */
+    const askToRead = async (then) => {
+        io.err(`${plural(distinct.length, 'rule section')} to read${then} · claude ${MODEL}`
+            + ` · ${approx(estimate(distinct).tokens)} tokens\n`);
+        return await yes() && await readSections();
+    };
     /** Judges the cases a round picks, then counts again; with `all`, again while cases wait and the last round judged
      * some. One line for every round. */
     const judgeCases = async () => {
@@ -138,7 +181,7 @@ async function run(command, asJson, all, io) {
             tokens += done.tokens;
             errors.push(...done.errors);
             if (done.judged)
-                ({ report, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir));
+                ({ report, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir, home));
             if (!all || !done.judged)
                 break;
         }
@@ -148,7 +191,12 @@ async function run(command, asJson, all, io) {
     };
     // Reading sections and judging cases spend the user's quota: only when asked on a terminal, after what the run may
     // spend. Every call costs ~4k tokens: an estimate is never under a thousand.
-    if (io.terminal && (distinct.length || report.toJudge > 0)) {
+    if (io.terminal && command === 'rules') {
+        // The rules and how each is checked: no verdict changes them, only new sections do.
+        if (distinct.length)
+            await askToRead('');
+    }
+    else if (io.terminal && (distinct.length || report.toJudge > 0)) {
         if (!all) {
             // One question. The cases of the rules about to be read aren't known yet: with sections to read, it shows the
             // ceiling.
@@ -170,12 +218,7 @@ async function run(command, asJson, all, io) {
         }
         else {
             // Every case: what judging them costs is known once the new sections are read, so the reading is asked first.
-            let reading = true;
-            if (distinct.length) {
-                io.err(`${plural(distinct.length, 'rule section')} to read first · claude ${MODEL}`
-                    + ` · ${approx(estimate(distinct).tokens)} tokens\n`);
-                reading = await yes() && await readSections();
-            }
+            const reading = !distinct.length || await askToRead(' first');
             if (reading && report.toJudge > 0) {
                 const more = report.atMost > report.toJudge;
                 io.err(`${plural(report.toJudge, 'case')} to judge${more ? ', more if their rules apply' : ''}`

package/dist/report.js

@@ -30,6 +30,16 @@ const inOrder = (r) => {
 };
 /** The file a rule is listed under: of the files it is written in, the first listed. */
 const under = (order, x) => order.find((f) => x.files.includes(f));
+/** Each rule's line in the file it is listed under, as `:12`, padded to the widest: where the user goes to rewrite or
+ * remove it. No column when no rule has one (its file gone, or edited since and its words with it). */
+const lineCells = (order, rules) => {
+    const line = (x) => {
+        const n = x.lines[under(order, x) ?? ''];
+        return n ? `:${n}` : '';
+    };
+    const width = Math.max(0, ...rules.map((x) => line(x).length));
+    return new Map(rules.map((x) => [x, width ? `${line(x).padEnd(width)}  ` : '']));
+};
 /** A file as the user finds it: by its path in the folder, or from home. */
 const where = (r, path, home) => (path.startsWith(`${r.folder}/`) ? path.slice(r.folder.length + 1) : tilde(path, home));
 /** Floored, so never 100% with a violation; and never 0% with a case kept. */
@@ -86,7 +96,9 @@ export function text(r, o) {
                 : [`kept ${kept(x.applied, x.broken)} of ${thousands(x.applied)}${x.status === 'judgment' ? ' judged' : ''}`,
                     ...(x.broken ? [`broken ${thousands(x.broken)}×`, `last ${ago(x.evidence[0].at, o.now)}`] : [])]),
         ...(x.status !== 'judgment' && x.toJudge ? [`${thousands(x.toJudge)} to confirm`] : [])]);
-    const laid = (width) => columns(rows.map(([name, ...rest]) => [cut(name, width).padEnd(width), ...rest]));
+    const at = lineCells(order, shown);
+    const laid = (width) => columns(rows.map(([name, ...rest]) => [cut(name, width).padEnd(width), ...rest]))
+        .map((l, i) => `${at.get(shown[i])}${l}`);
     let width = Math.max(...rows.map((row) => row[0].length));
     while (width > 10 && Math.max(...laid(width).map((l) => l.length + 6)) > o.columns)
         width--;
@@ -157,6 +169,7 @@ export function rules(r, o) {
     const width = Math.max(...r.rules.map((x) => x.name.length));
     const lines = ['', `  ${tilde(r.folder, o.home)} · ${plural(r.files.length, 'file')} · ${plural(r.rules.length, 'rule')}`, ''];
     const order = inOrder(r);
+    const at = lineCells(order, r.rules);
     for (const file of order) {
         const mine = r.rules.filter((x) => under(order, x) === file);
         if (mine.length)
@@ -164,7 +177,7 @@ export function rules(r, o) {
         for (const x of mine) {
             const mark = x.status === 'judgment' ? paint(o.color, 2, 22, '·') : x.status === 'demoted' ? paint(o.color, 33, 39, '!')
                 : paint(o.color, 32, 39, '✓');
-            lines.push(`    ${mark} ${x.name.padEnd(width + 2)}${how(x)}`);
+            lines.push(`    ${mark} ${at.get(x)}${x.name.padEnd(width + 2)}${how(x)}`);
         }
     }
     if (r.notRead || r.toReread)

package/dist/rules.js

@@ -46,6 +46,31 @@ export function sections(content) {
     return out;
 }
 const collapse = (text) => text.replace(/\s+/g, ' ').trim();
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const WORD = /[\p{L}\p{N}_]/u;
+/** The line a rule's words start on in a file's text, however they are spaced and wrapped there: under its section's
+ * headings (` › ` between them), as whole words, so the same words earlier (an intro, another section) aren't taken
+ * for it. Null when the text no longer holds them. What the user opens to rewrite or remove the rule. */
+export function lineOf(content, quote, heading) {
+    const words = quote.split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return null;
+    // Down the section's headings, as far as the file still has them: from the line of the last one found.
+    let from = 0;
+    let next = 0;
+    for (const title of heading ? heading.split(' › ') : []) {
+        const at = new RegExp(`^#{1,6}[ \\t]+${escape(title)}[ \\t]*\\r?$`, 'mu').exec(content.slice(next));
+        if (!at)
+            break;
+        from = next + at.index;
+        next = from + at[0].length;
+    }
+    const [first, last] = [[...words[0]][0], [...words.at(-1)].at(-1)];
+    const whole = new RegExp(`${WORD.test(first) ? '(?<![\\p{L}\\p{N}_])' : ''}${words.map(escape).join('\\s+')}`
+        + `${WORD.test(last) ? '(?![\\p{L}\\p{N}_])' : ''}`, 'u');
+    const at = whole.exec(content.slice(from))?.index;
+    return at === undefined ? null : content.slice(0, from + at).split('\n').length;
+}
 /**
  * A rule as the extraction returned it, checked here: its quote must be in its section as the model read it (secrets
  * redacted), word for word (spacing aside), or the rule is dropped; a check that can't be trusted is demoted, with the
@@ -56,7 +81,8 @@ export function verify(raw, section) {
     if (typeof r?.quote !== 'string' || !collapse(redact(section.text)).includes(collapse(r.quote)))
         return null;
     const id = createHash('sha256').update(collapse(r.quote).toLowerCase()).digest('hex').slice(0, 8);
-    const name = [...String(r.name).replace(/[\p{Cc}\s]+/gu, ' ').trim()].slice(0, 40).join('').trimEnd();
+    const chars = [...String(r.name).replace(/[\p{Cc}\s]+/gu, ' ').trim()];
+    const name = chars.length > 40 ? `${chars.slice(0, 39).join('').trimEnd()}…` : chars.join('');
     const own = /^#{1,6}[ \t]+(.+)$/.exec(section.text.split('\n')[0])?.[1].trim();
     const heading = [...section.path, ...(own ? [own] : [])].join(' › ');
     // What the section says around the rule: from 500 characters before its words to 1,000 after.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heeded",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "did your coding agent follow its instructions?",
   "license": "MIT",
   "author": "Francesco Musso",