rulereceipt 0.1.65 → 0.1.67

package/README.md

@@ -431,6 +431,12 @@ npx tsx src/cli.ts demo
 
 ## Trust, privacy and licensing
 
+**Verify it yourself.** `npx rulereceipt selftest` runs a set of bundled
+golden fixtures on your machine and reports how many verdicts are correct, with
+**zero network calls** — watch it with `lsof` or Little Snitch if you like. The
+same fixtures are the project's regression suite, so "all correct" is a promise
+the build enforces, not a claim.
+
 **What it can't see, it says so.** [KNOWN-GAPS.md](KNOWN-GAPS.md) lists
 exactly where the evidence runs out — commands in another terminal, clicks on
 the permission prompt, `rm`/delete not bound to a rule's subject, edited

package/dist/audit.d.ts

@@ -27,6 +27,7 @@ export interface RulesAudit {
     topFixes: {
         title: string;
         suggestion: string;
+        handle?: string;
     }[];
 }
 export declare function auditRules(rules: Rule[]): RulesAudit;
@@ -39,7 +40,7 @@ export declare function renderAudit(a: RulesAudit, md?: boolean): string;
  * cannot know without a transcript.
  */
 export interface Diagnostic {
-    id: "no-rules-file" | "empty-or-pointer" | "zero-rules" | "docs-heavy" | "shadowed-file" | "size-warn" | "template-text" | "broken-import";
+    id: "no-rules-file" | "empty-or-pointer" | "zero-rules" | "docs-heavy" | "shadowed-file" | "size-warn" | "template-text" | "broken-import" | "hook-config" | "dead-globs";
     severity: "info" | "warn";
     message: string;
 }

package/dist/audit.js

@@ -1,8 +1,39 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { classifyRules } from "./checks/classify.js";
 import { adviseRules } from "./checkability.js";
+import { ruleWasLoaded } from "./checks/pathScope.js";
 import { describeRuleSources, loadRules } from "./rules.js";
+/** Files in the repo, for checking whether a path-scoped rule matches anything. */
+function repoFiles(cwd, cap = 4000) {
+    const out = [];
+    const skip = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage", ".rulereceipt", ".vercel", ".turbo", "vendor"]);
+    const walk = (dir) => {
+        if (out.length >= cap)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (out.length >= cap)
+                return;
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!skip.has(e.name))
+                    walk(full);
+            }
+            else {
+                out.push(full);
+            }
+        }
+    };
+    walk(cwd);
+    return out;
+}
 export function auditRules(rules) {
     let checkable = 0;
     let judgment = 0;
@@ -19,7 +50,7 @@ export function auditRules(rules) {
     const topFixes = adviseRules(rules)
         .filter((a) => a.actionable)
         .slice(0, 5)
-        .map((a) => ({ title: a.ruleTitle, suggestion: a.suggestion }));
+        .map((a) => ({ title: a.ruleTitle, suggestion: a.suggestion, handle: a.handle }));
     return {
         total: checkable + judgment + skipped,
         checkable,
@@ -60,6 +91,30 @@ export function renderAudit(a, md = false) {
     out.push("Full advice, rule by rule:  rulereceipt rules --advise");
     return out.join("\n");
 }
+/** Hook events Claude Code recognises. A hook under any other name never fires. */
+const KNOWN_HOOK_EVENTS = new Set([
+    "PreToolUse", "PostToolUse", "Stop", "SubagentStop", "UserPromptSubmit",
+    "SessionStart", "SessionEnd", "Notification", "PreCompact", "PostCompact",
+    "PermissionRequest", "PermissionDenied", "InstructionsLoaded",
+]);
+/** Hook event names in the project/user settings that Claude Code won't recognise. */
+function unknownHookEvents(cwd) {
+    const bad = new Set();
+    for (const p of [join(cwd, ".claude", "settings.json"), join(cwd, ".claude", "settings.local.json")]) {
+        try {
+            const hooks = JSON.parse(readFileSync(p, "utf-8")).hooks;
+            if (hooks && typeof hooks === "object") {
+                for (const name of Object.keys(hooks))
+                    if (!KNOWN_HOOK_EVENTS.has(name))
+                        bad.add(name);
+            }
+        }
+        catch {
+            /* absent or unreadable */
+        }
+    }
+    return [...bad];
+}
 /**
  * Claude Code reads a bounded prefix of a rules file; past it the rest is
  * silently dropped, so a rule below the cut never loads. The figure is a
@@ -104,7 +159,7 @@ function isPointerFile(path) {
         return false;
     }
 }
-function buildDiagnostics(cwd, graph, a) {
+function buildDiagnostics(cwd, graph, a, rules) {
     const diags = [];
     const loaded = graph.filter((g) => g.status === "loaded");
     const shadowed = graph.filter((g) => g.status === "shadowed");
@@ -187,6 +242,29 @@ function buildDiagnostics(cwd, graph, a) {
             });
         }
     }
+    // A path-scoped rule whose globs match no file in the repo never loads.
+    const scoped = rules.filter((r) => r.paths && r.paths.length > 0);
+    if (scoped.length > 0) {
+        const files = repoFiles(cwd);
+        for (const r of scoped) {
+            if (!ruleWasLoaded(r.paths, files)) {
+                diags.push({
+                    id: "dead-globs",
+                    severity: "warn",
+                    message: `"${r.title.replace(/\s+/g, " ").trim().slice(0, 50)}" is scoped to ${r.paths.join(", ")}, which matches no file in this repo — so it never loads and governs nothing. Fix the glob.`,
+                });
+            }
+        }
+    }
+    // A hook wired under a misspelled/unknown event name never fires — silently.
+    const badHooks = unknownHookEvents(cwd);
+    if (badHooks.length > 0) {
+        diags.push({
+            id: "hook-config",
+            severity: "warn",
+            message: `.claude/settings.json has hook${badHooks.length === 1 ? "" : "s"} under ${badHooks.map((h) => `"${h}"`).join(", ")}, which ${badHooks.length === 1 ? "is not a" : "are not"} Claude Code hook event${badHooks.length === 1 ? "" : "s"} — ${badHooks.length === 1 ? "it never fires" : "they never fire"}. Check the spelling (e.g. PreToolUse, PostToolUse, Stop).`,
+        });
+    }
     // A handbook, not a policy: mostly documentation, little to enforce.
     if (a.total >= 8 && a.skipped / a.total > 0.7) {
         diags.push({
@@ -206,7 +284,7 @@ export function auditProject(cwd) {
     const rules = loadRules(cwd);
     const base = auditRules(rules);
     const loadGraph = describeRuleSources(cwd);
-    const diagnostics = buildDiagnostics(cwd, loadGraph, base);
+    const diagnostics = buildDiagnostics(cwd, loadGraph, base, rules);
     const memoryRules = rules.filter((r) => r.id.startsWith("memory:")).length;
     return { ...base, loadGraph, diagnostics, memoryRules };
 }
@@ -251,7 +329,7 @@ export function renderProjectAudit(pa, md = false) {
     if (pa.topFixes.length > 0) {
         out.push(H("Top fixes to unlock more checks"));
         for (const f of pa.topFixes) {
-            out.push(`  • ${f.title.replace(/\s+/g, " ").trim().slice(0, 60)}`);
+            out.push(`  • ${f.title.replace(/\s+/g, " ").trim().slice(0, 60)}${f.handle ? `  [${f.handle}]` : ""}`);
             out.push(`      ${f.suggestion}`);
         }
         out.push("");

package/dist/browser/analyze.d.ts

@@ -44,3 +44,4 @@ export declare const CORPUS: {
 };
 export declare function analyze(text: string): AnalysisResult;
 export { evaluateBrowserSession, checkSessionInBrowser, type BrowserSessionSummary } from "./evaluateBrowser.js";
+export { shareText, shareLinks, cardSvg, type CardData } from "../card.js";

package/dist/browser/analyze.js

@@ -50,3 +50,8 @@ export function analyze(text) {
 // Client-side SESSION check for the browser demo: drop a session .jsonl +
 // paste rules, get per-rule verdicts, nothing uploaded. Same checkers as the CLI.
 export { evaluateBrowserSession, checkSessionInBrowser } from "./evaluateBrowser.js";
+// Share the browser result: caption (counts only), compose links, and a
+// self-contained SVG card. card.ts is pure string work — no Node, no network —
+// so it can run in the page without breaking the "nothing leaves this page"
+// promise. Counts only, never rule text or the session.
+export { shareText, shareLinks, cardSvg } from "../card.js";

package/dist/card.js

@@ -12,9 +12,16 @@
 const SITE = "rulereceipt.dev";
 /** The share caption. Counts only, unless showRules adds the broken rule names. */
 export function shareText(d, showRules = false) {
-    const base = d.broken > 0
-        ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in ${d.days} days (${d.sessions} session${d.sessions === 1 ? "" : "s"}) — now it can't.`
-        : `RuleReceipt checked ${d.sessions} of my agent session${d.sessions === 1 ? "" : "s"} over ${d.days} days against my written rules: ${d.broken} broken.`;
+    // A single dropped session (the browser demo) has no "over N days" span, so
+    // it gets a "this session" caption rather than the history-mode one.
+    const single = d.sessions === 1;
+    const base = single
+        ? d.broken > 0
+            ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in this session — now it can't.`
+            : `RuleReceipt checked one of my agent's sessions against my written rules: ${d.broken} broken.`
+        : d.broken > 0
+            ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in ${d.days} days (${d.sessions} sessions) — now it can't.`
+            : `RuleReceipt checked ${d.sessions} of my agent sessions over ${d.days} days against my written rules: ${d.broken} broken.`;
     const tail = `Checked with RuleReceipt — runs locally, nothing uploaded. ${SITE}`;
     if (showRules && d.broken > 0 && d.brokenTitles && d.brokenTitles.length > 0) {
         const list = d.brokenTitles.slice(0, 3).map((t) => `“${t.replace(/\s+/g, " ").trim().slice(0, 50)}”`).join(", ");
@@ -41,7 +48,9 @@ function esc(s) {
 /** A self-contained SVG card. Counts only — never rule text, paths or code. */
 export function cardSvg(d) {
     const headline = d.broken > 0 ? `${d.who} broke your rules ${d.broken}×` : `0 rules broken`;
-    const sub = `${d.sessions} session${d.sessions === 1 ? "" : "s"} · last ${d.days} days`;
+    const sub = d.days > 0
+        ? `${d.sessions} session${d.sessions === 1 ? "" : "s"} · last ${d.days} days`
+        : `${d.sessions} session${d.sessions === 1 ? "" : "s"}`;
     const stats = `${d.followed} followed · ${d.judgment} need judgment`;
     return `<svg xmlns="http://www.w3.org/2000/svg" width="800" height="418" viewBox="0 0 800 418" role="img" aria-label="RuleReceipt summary">
   <rect width="800" height="418" fill="#0b0d10"/>

package/dist/checkability.d.ts

@@ -30,6 +30,8 @@ export interface RuleAdvice {
      * actionable ones as the top fixes.
      */
     actionable?: boolean;
+    /** Stable content-hash handle for `rules --include/--exclude`. */
+    handle?: string;
 }
 /**
  * Advice for one rule, or null when the rule is already mechanically checked.

package/dist/checkability.js

@@ -1,4 +1,5 @@
 import { classifyRule } from "./checks/classify.js";
+import { ruleFingerprint } from "./overrides.js";
 /** A concrete action the rule is plausibly about, so we can name what to quote. */
 const CONCRETE_SUBJECT = /\b(?:push(?:es|ed|ing)?|commit(?:s|ted|ting)?|merge[ds]?|rebase|delet\w*|remov\w*|\brm\b|drop|truncate|deploy\w*|migrat\w*|branch|tag|force[- ]?push|test|lint|build|install|env|secret|token|password|key|\.env|database|table|file|path|directory|endpoint|api)\b/i;
 /** A rule that is qualitative by nature — no literal makes it mechanical. */
@@ -65,5 +66,14 @@ export function adviseRule(rule) {
 }
 /** Advice for every rule that isn't already mechanically checked. */
 export function adviseRules(rules) {
-    return rules.map(adviseRule).filter((a) => a !== null);
+    const out = [];
+    for (const rule of rules) {
+        const a = adviseRule(rule);
+        // Attach the stable content-hash handle so `audit`'s top fixes can be acted
+        // on with `rules --include/--exclude <handle>` (ids are positional and
+        // renumber; the handle survives edits above the rule).
+        if (a)
+            out.push({ ...a, handle: ruleFingerprint(rule) });
+    }
+    return out;
 }

package/dist/checks/approvalGate.js

@@ -1,5 +1,5 @@
 import { violation } from "../types.js";
-import { withoutHeredocs } from "./shellCommand.js";
+import { withoutHeredocs, withoutQuotedMentions } from "./shellCommand.js";
 const IN_COMMAND = {
     push: /\bgit\s+(?:\S+\s+){0,4}?push(?![\w-])/,
     commit: /\bgit\s+(?:\S+\s+){0,4}?commit(?![\w-])/,
@@ -29,7 +29,10 @@ function commandOf(e) {
     const c = e.input?.command;
     // A heredoc that WRITES "git push" into a file is not a push. Strip heredoc
     // bodies so only the commands actually invoked are inspected.
-    return typeof c === "string" ? withoutHeredocs(c) : "";
+    // Strip heredoc bodies (a heredoc that WRITES "git push" is not a push) and
+    // blank quoted/commented mentions (`echo "git push"`, `# git push`), so only
+    // a command actually being run is matched.
+    return typeof c === "string" ? withoutQuotedMentions(withoutHeredocs(c)) : "";
 }
 /** The result for the call at `i`: matched by id when present, else the next result. */
 function resultOf(events, i) {

package/dist/checks/doctor.d.ts

@@ -11,11 +11,25 @@ export interface HookEntry {
      */
     matcher?: string;
 }
+/**
+ * A hook command registered more than once on the same event within a single
+ * settings file — so it fires that many times per event. Cross-file repetition
+ * (a global and a project settings file both registering it) is legitimate
+ * layering and is NOT reported: only a genuinely redundant in-file duplicate is,
+ * to avoid a false "you have a problem" on a normal setup.
+ */
+export interface DuplicateHook {
+    sourceFile: string;
+    event: string;
+    command: string;
+    count: number;
+}
 export interface DoctorResult {
     filesScanned: string[];
     filesFound: string[];
     hooks: HookEntry[];
     newSinceLastRun: HookEntry[];
+    duplicates: DuplicateHook[];
 }
 /**
  * Lists every Claude Code hook and VS Code folderOpen task this machine

package/dist/checks/doctor.js

@@ -140,5 +140,22 @@ export function runDoctor(cwd) {
     const previousKeys = new Set(previous.map((h) => `${h.sourceFile}|${h.event}|${h.command}`));
     const newSinceLastRun = hooks.filter((h) => !previousKeys.has(`${h.sourceFile}|${h.event}|${h.command}`));
     saveSnapshot(cwd, hooks);
-    return { filesScanned, filesFound, hooks, newSinceLastRun };
+    return { filesScanned, filesFound, hooks, newSinceLastRun, duplicates: findDuplicates(hooks) };
+}
+/**
+ * Same command on the same event within ONE file, counted. Keyed by
+ * file+event+command so the global-plus-project case never registers as a
+ * duplicate — that is intended layering, not a misconfiguration.
+ */
+function findDuplicates(hooks) {
+    const counts = new Map();
+    for (const h of hooks) {
+        const key = `${h.sourceFile}|${h.event}|${h.command}`;
+        const existing = counts.get(key);
+        if (existing)
+            existing.count += 1;
+        else
+            counts.set(key, { sourceFile: h.sourceFile, event: h.event, command: h.command, count: 1 });
+    }
+    return [...counts.values()].filter((d) => d.count > 1);
 }

package/dist/checks/shellCommand.d.ts

@@ -44,3 +44,15 @@ export declare function leadingCommand(segment: string): string;
  * false-matched on commit-message text — findings 2026-09-26).
  */
 export declare function withoutCommitMessage(command: string): string;
+/**
+ * Blanks out quoted-string CONTENTS and drops #-comments, so a command MENTION
+ * inside a quote or a comment is not read as the command running.
+ *
+ * Found 2026-09-28: `echo "git push"` and `cat notes.md # git push` were both
+ * flagged as an unapproved push, because the matcher saw "git push" anywhere in
+ * the string. Blanking quote contents keeps the real verb visible (`git commit
+ * -m "msg"` still reads as a commit) while removing the mention. Use this only
+ * where a MENTION must not count as an action; checks that need the quoted text
+ * (attribution's commit-message trailer) must not use it.
+ */
+export declare function withoutQuotedMentions(command: string): string;

package/dist/checks/shellCommand.js

@@ -104,3 +104,19 @@ export function leadingCommand(segment) {
 export function withoutCommitMessage(command) {
     return command.replace(/(-m|--message)(=|\s+)(['"])(?:\\.|(?!\3)[\s\S])*\3/g, "$1 <message>");
 }
+/**
+ * Blanks out quoted-string CONTENTS and drops #-comments, so a command MENTION
+ * inside a quote or a comment is not read as the command running.
+ *
+ * Found 2026-09-28: `echo "git push"` and `cat notes.md # git push` were both
+ * flagged as an unapproved push, because the matcher saw "git push" anywhere in
+ * the string. Blanking quote contents keeps the real verb visible (`git commit
+ * -m "msg"` still reads as a commit) while removing the mention. Use this only
+ * where a MENTION must not count as an action; checks that need the quoted text
+ * (attribution's commit-message trailer) must not use it.
+ */
+export function withoutQuotedMentions(command) {
+    const noQuotes = command.replace(/'[^']*'/g, "''").replace(/"[^"]*"/g, '""');
+    // A `#` that begins a word (start or after whitespace) starts a comment.
+    return noQuotes.replace(/(^|\s)#[^\n]*/g, "$1");
+}

package/dist/cli.js

@@ -18,6 +18,8 @@ import { buildWrongReport, findTarget } from "./wrong.js";
 import { detectSelfEditedRuleFiles } from "./checks/selfEditedRules.js";
 import { scanHistory, renderHistory } from "./historyReport.js";
 import { observeSessions, renderNoRules, draftRulesFromHistory } from "./sessionObserve.js";
+import { listSessionRows, renderSessionList } from "./listSessions.js";
+import { runSelfTestChecks, renderSelfTest } from "./selftest.js";
 import { planProtect, applyProtect, undoProtect } from "./protect.js";
 import { cardSvg, renderCardShare } from "./card.js";
 import { createInterface } from "node:readline";
@@ -411,7 +413,13 @@ program
     .option("--require-session", "fail (exit 1) if no session is found, or the session is empty, instead of reporting a pass for a check that never actually ran. Use this anywhere automated.")
     .option("--show-skipped", "list the items that were treated as documentation and not checked. Worth running once on any rules file: the classifier is a heuristic over English verbs, so a rule it does not recognise is otherwise dropped without you seeing it.")
     .option("--transcript <path>", "manual override: check this exact .jsonl session file instead of auto-detecting one. Useful if your Claude Code session lives somewhere non-standard that auto-detection doesn't cover.")
+    .option("--list-sessions", "list recent sessions for this project (tool, time, first prompt) so you can pick one for --transcript, instead of checking.")
     .action((opts) => {
+    if (opts.listSessions) {
+        const cwd = process.cwd();
+        console.log(renderSessionList(listSessionRows(cwd), cwd));
+        return;
+    }
     runCheck({
         markdown: Boolean(opts.markdown),
         json: Boolean(opts.json),
@@ -742,6 +750,14 @@ function runDoctorCommand() {
     if (result.newSinceLastRun.length > 0) {
         console.log(`${result.newSinceLastRun.length} of these are new since the last time doctor ran here.`);
     }
+    if (result.duplicates.length > 0) {
+        console.log("");
+        console.log(`⚠ ${result.duplicates.length} duplicate hook${result.duplicates.length === 1 ? "" : "s"} — the same command is registered more than once on one event, so it runs that many times:`);
+        for (const d of result.duplicates) {
+            console.log(`  ${d.event} — ${d.command}  (×${d.count})`);
+            console.log(`     in ${d.sourceFile} — remove the extra copy so it fires once.`);
+        }
+    }
 }
 program
     .command("hook")
@@ -831,6 +847,15 @@ program
         shadowedAgents: shadowedAgentsMd(cwd).map((s) => s.agents),
     }));
 });
+program
+    .command("selftest")
+    .description("Run bundled golden fixtures on your machine and report how many verdicts are correct — proof the checkers work, with zero network calls (watch it with lsof if you like). Exits non-zero if any is wrong.")
+    .action(() => {
+    const r = runSelfTestChecks();
+    console.log(renderSelfTest(r));
+    if (r.failures.length > 0)
+        process.exitCode = 1;
+});
 program
     .command("demo")
     .description("See a sample report — no setup, no API key needed")

package/dist/evaluate.d.ts

@@ -20,3 +20,4 @@ export interface Evaluation {
  * a transcript comes from, and a hook is handed one it must not second-guess.
  */
 export declare function evaluateSession(cwd: string, rules: Rule[], events: TranscriptEvent[], llm: boolean, needsLlmResult: (rule: Rule) => CheckResult): Promise<Evaluation>;
+export declare function attachSourceLocation(results: CheckResult[], rules: Rule[]): CheckResult[];

package/dist/evaluate.js

@@ -98,9 +98,35 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
     const judgmentResults = llm
         ? await runJudgmentChecks(judgment, events)
         : judgment.map(({ rule }) => needsLlmResult(rule));
+    const results = [...deterministicResults, ...judgmentResults, ...scopeResults, ...future.map(futureResult)];
     return {
-        results: [...deterministicResults, ...judgmentResults, ...scopeResults, ...future.map(futureResult)],
+        results: attachSourceLocation(results, rules),
         notARule: of("notARule"),
         stale: staleOverrides(overrides, rules),
     };
 }
+/**
+ * Copies each rule's source file/line onto its verdict — but ONLY when the
+ * (source, id, title) triple maps to exactly one loaded rule. Rule ids are
+ * positional and two files can legitimately reuse "1" or "S1.1", so a blind
+ * id-match could point a report at the wrong line. A wrong "CLAUDE.md:42" is
+ * worse than none, so an ambiguous or unlocated rule simply carries no line.
+ */
+function locationKey(source, id, title) {
+    return `${source}\u0000${id}\u0000${title}`;
+}
+export function attachSourceLocation(results, rules) {
+    const byKey = new Map();
+    for (const rule of rules) {
+        if (rule.sourcePath === undefined)
+            continue;
+        const key = locationKey(rule.source, rule.id, rule.title);
+        byKey.set(key, byKey.has(key) ? null : rule); // second hit => ambiguous => null
+    }
+    return results.map((r) => {
+        const rule = byKey.get(locationKey(r.ruleSource, r.ruleId, r.ruleTitle));
+        if (!rule)
+            return r;
+        return { ...r, sourcePath: rule.sourcePath, sourceLine: rule.sourceLine };
+    });
+}

package/dist/guard.js

@@ -168,8 +168,26 @@ function ratifiedLiteralBlocks(cwd, command) {
  * rules may block — not a cleverer guess. That is a design question for
  * whoever asks for it, not a default.
  */
+/**
+ * What to do instead — every refusal names a concrete next step, so the model
+ * corrects rather than just retrying (Failproof's "corrective context" idea,
+ * built our own way). Inferred from the rule and the reason; falls back to
+ * "ask the user", which is always safe.
+ */
+function suggest(b) {
+    const t = `${b.rule.title} ${b.why}`.toLowerCase();
+    if (/co-?authored|generated with|attribution|trailer/.test(t))
+        return "Instead: make the commit without the AI trailer (no `Co-Authored-By` / `Generated with` line).";
+    if (/\bpush\b|\bbranch\b|\bmain\b|\bmaster\b/.test(t))
+        return "Instead: work on a feature branch (`git switch -c <name>`) and open a PR, or ask the user before pushing.";
+    if (/\.env|secret|credential|\btoken\b|\bkey\b|password/.test(t))
+        return "Instead: leave that file as it is; if it genuinely must change, ask the user first.";
+    if (/delet|remov|\bdrop\b|truncat|wipe|\brm\b/.test(t))
+        return "Instead: don't delete it; if it should be removed, confirm with the user first.";
+    return "Instead: ask the user before doing this, or explain why the rule shouldn't apply and let them decide.";
+}
 function reason(blocks) {
-    const lines = blocks.map((b) => `  • Rule ${b.rule.id} — ${b.rule.title}\n    ${b.why}`);
+    const lines = blocks.map((b) => `  • Rule ${b.rule.id} — ${b.rule.title}\n    ${b.why}\n    ${suggest(b)}`);
     const n = blocks.length;
     return (`RuleReceipt blocked this: it breaks ${n === 1 ? "a rule" : `${n} rules`} in CLAUDE.md.\n\n` +
         lines.join("\n\n") +

package/dist/listSessions.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `rulereceipt check --list-sessions` — a readable list of recent sessions so
+ * `--transcript <path>` is easy to pick. Without this, choosing a session means
+ * staring at a directory of UUID filenames. Each row shows the tool, how long
+ * ago, the first thing the user said (truncated and redacted), and the path to
+ * pass to `--transcript`.
+ */
+export interface SessionRow {
+    file: string;
+    tool: string;
+    mtimeMs: number;
+    firstPrompt: string;
+}
+export declare function listSessionRows(cwd: string, limit?: number, sessions?: {
+    adapter: import("./adapters/index.js").SessionAdapter;
+    file: string;
+}[]): SessionRow[];
+export declare function renderSessionList(rows: SessionRow[], cwd: string, now?: number): string;

package/dist/listSessions.js

@@ -0,0 +1,60 @@
+import { statSync } from "node:fs";
+import { relative } from "node:path";
+import { listAllSessions } from "./adapters/index.js";
+import { redact } from "./wrong.js";
+function firstUserText(events) {
+    for (const e of events) {
+        if (e.kind === "text" && e.role === "user" && e.text.trim())
+            return e.text.trim();
+    }
+    return "";
+}
+const toolLabel = (t) => (t === "claude-code" ? "Claude Code" : t === "codex" ? "Codex" : t);
+export function listSessionRows(cwd, limit = 15, sessions = listAllSessions(cwd)) {
+    const rows = [];
+    for (const { adapter, file } of sessions.slice(0, limit)) {
+        let mtimeMs;
+        try {
+            mtimeMs = statSync(file).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        let prompt = "";
+        try {
+            prompt = firstUserText(adapter.parse(file));
+        }
+        catch {
+            /* unreadable session: still list it, just without a prompt */
+        }
+        rows.push({ file, tool: adapter.tool, mtimeMs, firstPrompt: redact(prompt).replace(/\s+/g, " ").trim().slice(0, 70) });
+    }
+    return rows;
+}
+function ago(ms, now = Date.now()) {
+    const s = Math.max(0, Math.round((now - ms) / 1000));
+    if (s < 90)
+        return `${s}s ago`;
+    const m = Math.round(s / 60);
+    if (m < 90)
+        return `${m}m ago`;
+    const h = Math.round(m / 60);
+    if (h < 36)
+        return `${h}h ago`;
+    return `${Math.round(h / 24)}d ago`;
+}
+export function renderSessionList(rows, cwd, now = Date.now()) {
+    if (rows.length === 0) {
+        return "No coding-agent sessions found for this project. Run Claude Code (or Codex) here first.";
+    }
+    const out = [];
+    out.push(`Recent sessions for this project (newest first). Check one with:  rulereceipt check --transcript <path>`);
+    out.push("");
+    rows.forEach((r, i) => {
+        const rel = relative(cwd, r.file);
+        const path = rel && !rel.startsWith("..") ? rel : r.file;
+        out.push(`  ${String(i + 1).padStart(2)}. ${toolLabel(r.tool).padEnd(11)} ${ago(r.mtimeMs, now).padEnd(8)} ${r.firstPrompt || "(no user message)"}`);
+        out.push(`      ${path}`);
+    });
+    return out.join("\n");
+}

package/dist/parsers/claudeMdParser.js

@@ -75,7 +75,12 @@ function stripHtmlComments(raw) {
         spans.push(m);
         return `\u0000CODE${spans.length - 1}\u0000`;
     });
-    const stripped = masked.replace(/<!--[\s\S]*?-->/g, "");
+    // A removed comment is replaced by the SAME number of newlines it spanned,
+    // not by nothing. Rule source lines are tracked by line index (2026-09-29),
+    // so a multi-line comment that collapsed to nothing would shift every rule
+    // below it and make the reported "CLAUDE.md:42" wrong. Blank lines left in a
+    // rule body are trimmed at its edges and harmless within it.
+    const stripped = masked.replace(/<!--[\s\S]*?-->/g, (m) => "\n".repeat((m.match(/\n/g) ?? []).length));
     return stripped.replace(/\u0000CODE(\d+)\u0000/g, (_, i) => spans[Number(i)]);
 }
 function normalizeSetextHeaders(lines) {
@@ -152,6 +157,8 @@ export function parseClaudeMdText(raw, source) {
     let currentIsMarkedRule = false; // true for numbered/bold rules: bullets in their body stay as body text
     let bodyLines = [];
     let pendingSectionTitle = null;
+    let pendingSectionLine = 0; // 1-based line of the plain header awaiting its prose rule
+    let lineNo = 0; // 1-based index of the line currently being read
     let sectionCount = 0;
     let sectionId = "S0"; // "S0" before any header is seen; null while a header is pending its first rule
     let bulletIndex = 0;
@@ -178,7 +185,7 @@ export function parseClaudeMdText(raw, source) {
             bodyLines.push(line);
         }
         else if (pendingSectionTitle !== null && line.trim() !== "") {
-            current = { id: `${assignSectionId()}.0`, title: pendingSectionTitle, text: "", source };
+            current = { id: `${assignSectionId()}.0`, title: pendingSectionTitle, text: "", source, sourceLine: pendingSectionLine };
             bodyLines = [line];
             pendingSectionTitle = null;
         }
@@ -187,6 +194,7 @@ export function parseClaudeMdText(raw, source) {
         }
     };
     for (const line of lines) {
+        lineNo += 1;
         // Fence state is tracked before any structural match, so nothing inside a
         // code block is ever read as a heading, a bullet, or a rule marker.
         const fence = line.match(FENCE_LINE);
@@ -210,7 +218,7 @@ export function parseClaudeMdText(raw, source) {
         if (numbered) {
             flush();
             pendingSectionTitle = null;
-            current = { id: numbered[1], title: numbered[2].trim(), text: "", source };
+            current = { id: numbered[1], title: numbered[2].trim(), text: "", source, sourceLine: lineNo };
             currentIsMarkedRule = true;
             continue;
         }
@@ -218,7 +226,7 @@ export function parseClaudeMdText(raw, source) {
         if (bold) {
             flush();
             pendingSectionTitle = null;
-            current = { id: bold[1], title: bold[2].trim(), text: "", source };
+            current = { id: bold[1], title: bold[2].trim(), text: "", source, sourceLine: lineNo };
             currentIsMarkedRule = true;
             continue;
         }
@@ -228,6 +236,7 @@ export function parseClaudeMdText(raw, source) {
             sectionId = null;
             bulletIndex = 0;
             pendingSectionTitle = plain[1].trim();
+            pendingSectionLine = lineNo;
             currentIsMarkedRule = false;
             continue;
         }
@@ -239,7 +248,7 @@ export function parseClaudeMdText(raw, source) {
             else {
                 bulletIndex += 1;
                 const text = bullet[1].trim();
-                rules.push({ id: `${assignSectionId()}.${bulletIndex}`, title: text, text, source });
+                rules.push({ id: `${assignSectionId()}.${bulletIndex}`, title: text, text, source, sourceLine: lineNo });
             }
             continue;
         }
@@ -253,13 +262,27 @@ export function parseClaudeMdText(raw, source) {
     // headers, no bullets, no bold-rule markers) is split one rule per
     // blank-line-separated paragraph, so a genuinely unstructured file
     // still yields checkable rules instead of silently returning nothing.
-    const paragraphs = raw
-        .split(/\n\s*\n/)
-        .map((p) => p.trim())
-        .filter((p) => p.length > 0);
-    return paragraphs.map((p, i) => {
+    // Track the line each paragraph starts on so the fallback rules carry a
+    // source line too. Split on the raw text and walk cumulative line counts.
+    const chunks = raw.split(/\n\s*\n/);
+    const out = [];
+    let lineCursor = 1;
+    let n = 0;
+    for (const chunk of chunks) {
+        const startLine = lineCursor;
+        lineCursor += (chunk.match(/\n/g) ?? []).length; // lines consumed by this chunk
+        // account for the blank separator the split removed (one newline minimum)
+        lineCursor += 1;
+        const p = chunk.trim();
+        if (p.length === 0)
+            continue;
+        n += 1;
         const firstLine = p.split("\n")[0].trim();
         const title = firstLine.length > 100 ? `${firstLine.slice(0, 100).trim()}…` : firstLine;
-        return { id: String(i + 1), title, text: p, source };
-    });
+        // Best-effort line for the freeform fallback: any leading blank lines in the
+        // chunk push the real first line down.
+        const leadBlank = (chunk.match(/^(?:[ \t]*\n)*/)?.[0].match(/\n/g) ?? []).length;
+        out.push({ id: String(n), title, text: p, source, sourceLine: startLine + leadBlank });
+    }
+    return out;
 }

package/dist/parsers/readClaudeMd.js

@@ -81,6 +81,24 @@ export function readPathScope(raw) {
     }
     return undefined;
 }
+/**
+ * How many leading lines `stripFrontmatter` removes, so a source line computed
+ * on the stripped text can be mapped back to the real file line. Zero when
+ * there is no frontmatter block.
+ */
+function frontmatterLineOffset(raw) {
+    if (!/^---\r?\n/.test(raw))
+        return 0;
+    const end = raw.indexOf("\n---", 3);
+    if (end === -1)
+        return 0;
+    const after = raw.indexOf("\n", end + 1);
+    if (after === -1)
+        return 0;
+    // stripFrontmatter returns raw.slice(after + 1): everything up to and
+    // including that newline is gone. Count the newlines removed.
+    return (raw.slice(0, after + 1).match(/\n/g) ?? []).length;
+}
 export function parseClaudeMd(filePath, source) {
     let raw;
     try {
@@ -89,7 +107,13 @@ export function parseClaudeMd(filePath, source) {
     catch {
         return [];
     }
+    const offset = frontmatterLineOffset(raw);
     const rules = parseClaudeMdText(stripFrontmatter(raw), source);
     const paths = readPathScope(raw);
-    return paths ? rules.map((r) => ({ ...r, paths })) : rules;
+    return rules.map((r) => ({
+        ...r,
+        sourcePath: filePath,
+        sourceLine: r.sourceLine === undefined ? undefined : r.sourceLine + offset,
+        ...(paths ? { paths } : {}),
+    }));
 }

package/dist/report/generateReport.js

@@ -1,5 +1,20 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+/**
+ * Where a rule lives, for the report — "~/proj/CLAUDE.md:42", or just the path
+ * when the parser could not place a line, or "" when the rule's location was
+ * ambiguous and deliberately omitted (see attachSourceLocation). The home dir
+ * is compressed to ~ so the line stays readable; the JSON report keeps the full
+ * absolute path.
+ */
+function locationOf(r) {
+    if (!r.sourcePath)
+        return "";
+    const home = homedir();
+    const path = r.sourcePath.startsWith(home) ? `~${r.sourcePath.slice(home.length)}` : r.sourcePath;
+    return r.sourceLine ? `${path}:${r.sourceLine}` : path;
+}
 const MARK = { PASS: "✓", FAIL: "✕", UNCLEAR: "?" };
 /**
  * A CLAUDE.md rule title, or evidence text pulled from session content, is
@@ -196,6 +211,9 @@ export function generateReport(results, meta) {
             lines.push("");
             for (const r of inBucket) {
                 lines.push(`  ${ruleLabel(r, clean)}`);
+                const loc = locationOf(r);
+                if (loc)
+                    lines.push(`    ↳ ${loc}`);
                 // An entry that does not share the hoisted text still says its own
                 // piece — that difference is the only per-rule information there is.
                 if (r.evidence && r.evidence !== shared)
@@ -207,6 +225,9 @@ export function generateReport(results, meta) {
         }
         for (const r of inBucket) {
             lines.push(`${MARK[r.status]} ${r.status.padEnd(7)} ${ruleLabel(r, clean)}`);
+            const loc = locationOf(r);
+            if (loc)
+                lines.push(`  ↳ ${loc}`);
             if (r.evidence)
                 lines.push(`  evidence: ${r.evidence}`);
             // What this method was ALLOWED to conclude, travelling with the
@@ -259,7 +280,9 @@ export function generateMarkdownReport(results, meta) {
     lines.push("|---|---|---|");
     for (const r of clean) {
         const evidence = escapeMarkdownCell(r.evidence || "");
-        lines.push(`| ${MARK[r.status]} ${r.status} | ${escapeMarkdownCell(ruleLabel(r, clean))} | ${evidence} |`);
+        const loc = locationOf(r);
+        const label = loc ? `${ruleLabel(r, clean)}<br>\`${loc}\`` : ruleLabel(r, clean);
+        lines.push(`| ${MARK[r.status]} ${r.status} | ${escapeMarkdownCell(label)} | ${evidence} |`);
     }
     lines.push("");
     const hash = computeTranscriptHash(meta.sessionFilePath);
@@ -302,6 +325,10 @@ export function generateJsonReport(results, meta, toolVersion, editedRuleFiles =
             ruleId: r.ruleId,
             ruleTitle: r.ruleTitle,
             ruleSource: r.ruleSource,
+            // Absolute path + 1-based line of the rule's heading, when unambiguous
+            // (see attachSourceLocation). A consumer can jump straight to the rule.
+            sourcePath: r.sourcePath ?? null,
+            sourceLine: r.sourceLine ?? null,
             status: r.status,
             outcome: r.outcome ?? null,
             method: r.method ?? null,

package/dist/selftest.d.ts

@@ -0,0 +1,11 @@
+export interface SelfTestResult {
+    total: number;
+    passed: number;
+    failures: {
+        name: string;
+        detail: string;
+    }[];
+}
+export declare function runSelfTestChecks(): SelfTestResult;
+/** The human-facing selftest output. */
+export declare function renderSelfTest(r: SelfTestResult): string;

package/dist/selftest.js

@@ -0,0 +1,85 @@
+import { checkSessionInBrowser } from "./browser/evaluateBrowser.js";
+function sessionOf(lines) {
+    return lines.map((l) => JSON.stringify(l)).join("\n");
+}
+const asst = (content) => ({ type: "assistant", timestamp: "t", message: { role: "assistant", content } });
+const user = (content, permissionMode) => ({ type: "user", timestamp: "t", permissionMode, message: { role: "user", content } });
+const bash = (command, id = "x") => ({ type: "tool_use", id, name: "Bash", input: { command } });
+const edit = (file_path) => ({ type: "tool_use", id: "e", name: "Edit", input: { file_path, old_string: "a", new_string: "b" } });
+const GOLDENS = [
+    {
+        name: "push with no approval in a no-prompt mode is Broken",
+        rules: "## 1. Never push without asking\nNever push without explicit user instruction.\n",
+        session: sessionOf([user("fix the page", "bypassPermissions"), asst([bash("git push origin main", "a")])]),
+        expect: [{ title: /never push/i, want: "FAIL" }],
+    },
+    {
+        name: "push the user asked for is Followed",
+        rules: "## 1. Never push without asking\nNever push without explicit user instruction.\n",
+        session: sessionOf([user("fix it and push it", "bypassPermissions"), asst([bash("git push origin main", "a")])]),
+        expect: [{ title: /never push/i, want: "PASS" }],
+    },
+    {
+        name: "push in default mode is Can't-tell (a prompt may have been approved)",
+        rules: "## 1. Never push without asking\nNever push without explicit user instruction.\n",
+        session: sessionOf([user("fix the page", "default"), asst([bash("git push origin main", "a")])]),
+        expect: [{ title: /never push/i, want: "not-fail" }],
+    },
+    {
+        name: "console.log written into a file is Broken",
+        rules: "## 1. No debug logging\nNever leave a `console.log(` call in committed code.\n",
+        session: sessionOf([asst([{ type: "tool_use", id: "w", name: "Write", input: { file_path: "app.ts", content: "console.log(1)" } }])]),
+        expect: [{ title: /debug logging/i, want: "FAIL" }],
+    },
+    {
+        name: "editing .env is Broken",
+        rules: "## 1. Never edit `.env`\nNever edit `.env`.\n",
+        session: sessionOf([asst([edit(".env")])]),
+        expect: [{ title: /never edit/i, want: "FAIL" }],
+    },
+    {
+        name: "a Co-Authored-By trailer is Broken",
+        rules: "## 1. No AI attribution\nNever add a `Co-Authored-By: Claude` trailer to git commits.\n",
+        session: sessionOf([asst([bash("git commit -m 'x\n\nCo-Authored-By: Claude <noreply@anthropic.com>'", "c")])]),
+        expect: [{ title: /attribution/i, want: "FAIL" }],
+    },
+    {
+        name: "a temp-dir rm is NOT Broken against a 'never wipe databases' rule",
+        rules: "## 1. Never wipe databases\nBefore any delete on the database, wait for explicit confirmation.\n",
+        session: sessionOf([asst([bash("rm -rf /tmp/scratch-xyz", "r")])]),
+        expect: [{ title: /wipe databases/i, want: "not-fail" }],
+    },
+    {
+        name: "a judgment rule is Can't-tell, never Broken",
+        rules: "## 1. Keep changes small\nAlways keep changes small and focused.\n",
+        session: sessionOf([asst([bash("git commit -m x", "c")])]),
+        expect: [{ title: /keep changes small/i, want: "UNCLEAR" }],
+    },
+];
+export function runSelfTestChecks() {
+    const failures = [];
+    let total = 0;
+    for (const g of GOLDENS) {
+        const results = checkSessionInBrowser(g.rules, g.session).results;
+        for (const e of g.expect) {
+            total++;
+            const r = results.find((x) => e.title.test(x.ruleTitle));
+            const got = r?.status ?? "MISSING";
+            const ok = e.want === "not-fail" ? got !== "FAIL" && got !== "MISSING" : got === e.want;
+            if (!ok)
+                failures.push({ name: g.name, detail: `expected ${e.want}, got ${got}` });
+        }
+    }
+    return { total, passed: total - failures.length, failures };
+}
+/** The human-facing selftest output. */
+export function renderSelfTest(r) {
+    if (r.failures.length === 0) {
+        return (`rulereceipt selftest\n\n` +
+            `  ${r.total} checks, all correct.\n` +
+            `  0 network calls — this ran entirely on your machine (watch it with lsof / Little Snitch if you like).\n\n` +
+            `The same checkers ran here as on your real sessions. If any of these were ever wrong, this would say so.`);
+    }
+    const lines = r.failures.map((f) => `  ✗ ${f.name} — ${f.detail}`);
+    return `rulereceipt selftest\n\n  ${r.passed}/${r.total} correct, ${r.failures.length} WRONG:\n` + lines.join("\n") + `\n\nThis is a bug — please report it with the version (rulereceipt --version).`;
+}

package/dist/types.d.ts

@@ -11,6 +11,15 @@ export interface Rule {
      * against a rule it was never shown. Absent = always loaded.
      */
     paths?: string[];
+    /**
+     * Absolute path of the rules file this rule was read from, and the 1-based
+     * line where its heading/marker sits. Added 2026-09-29 so a report can say
+     * exactly where a rule lives ("CLAUDE.md:42 — Never push to main"): a verdict
+     * you can walk to the source of is a verdict you can trust. Optional — memory
+     * rules and the freeform-paragraph fallback carry a path but may omit a line.
+     */
+    sourcePath?: string;
+    sourceLine?: number;
 }
 export interface TranscriptTextEvent {
     role: "user" | "assistant";
@@ -149,6 +158,14 @@ export interface CheckResult {
      * anthropics/claude-code#90542.
      */
     polarityInferred?: boolean;
+    /**
+     * Where the checked rule lives — the rules file's absolute path and the
+     * 1-based line of its heading. Copied from the rule in `evaluateSession`,
+     * and ONLY when the (source, id, title) triple maps to exactly one loaded
+     * rule, so a report never points at the wrong line. Absent otherwise.
+     */
+    sourcePath?: string;
+    sourceLine?: number;
 }
 /**
  * A FAIL may only be constructed from a forbidding rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "Checks whether your AI coding agent followed your rules, with evidence. Works with Claude Code (Codex in testing); reads CLAUDE.md, AGENTS.md, Cursor, Copilot and Windsurf rules.",
   "repository": {
     "type": "git",