rulereceipt 0.1.75 → 0.1.77

package/README.md

@@ -6,15 +6,21 @@
 [![npm](https://img.shields.io/npm/v/rulereceipt)](https://www.npmjs.com/package/rulereceipt)
 [![provenance](https://img.shields.io/badge/npm-provenance%20signed-blue)](https://www.npmjs.com/package/rulereceipt#provenance)
 
-Checks whether your AI coding agent actually followed your rules — with
-evidence, not just a vibe. Works with Claude Code today (OpenAI Codex CLI
-support is built and in testing), and reads rules from CLAUDE.md, AGENTS.md,
-Cursor (`.cursor/rules`), GitHub Copilot, Windsurf, Gemini (`GEMINI.md`),
-Google's `.agents/rules`, and Claude Code memory.
+**Check if your AI coding agent followed the rules in your CLAUDE.md, with the exact line as proof.**
+
+[![RuleReceipt checking an agent session against your rules — three rules broken, each with the quoted line](https://raw.githubusercontent.com/rulereceipt/rulereceipt/main/docs/screenshot.png)](https://rulereceipt.dev)
+
+```bash
+npx rulereceipt
+```
 
 Runs entirely on your machine. Plain `rulereceipt check` makes zero network
-calls — [Trust, privacy and licensing](#trust-privacy-and-licensing) has the
-full detail, including the three off-by-default opt-ins.
+calls — [Trust, privacy and licensing](#trust-privacy-and-licensing) has the full
+detail, including the three off-by-default opt-ins. Works with Claude Code today
+(OpenAI Codex CLI in testing); reads rules from CLAUDE.md, AGENTS.md, Cursor
+(`.cursor/rules`), GitHub Copilot, Windsurf, Gemini (`GEMINI.md`), Google's
+`.agents/rules`, and Claude Code memory. [Accuracy](https://rulereceipt.dev/accuracy)
+· [Known gaps](KNOWN-GAPS.md) · Source-available, not OSI — see [LICENSE](LICENSE).
 
 ## See it in 10 seconds
 

package/dist/blockHint.d.ts

@@ -0,0 +1,49 @@
+import type { Classification } from "./checks/classify.js";
+/**
+ * `why` answers "why isn't THIS rule working?". For a rule that names a
+ * concrete action, the honest follow-up is "then how do I actually stop it?".
+ * This computes that answer — and it is deliberately pinned to what the tool
+ * really does, because an overstated "add this and you're safe" is exactly the
+ * failure RuleReceipt exists to catch.
+ *
+ * Two facts, kept separate because they are not the same promise:
+ *
+ *  - `guardCovers`: RuleReceipt's own PreToolUse guard refuses this exact rule
+ *    before the action runs. True only for the kinds guardDecision/structuredBlocks
+ *    actually handle (a branch, a file, forbidden file content, an AI-authorship
+ *    trailer) and for an approval gate (which it answers "ask", or "deny" in a
+ *    no-prompt mode). It is NOT a general command blocker — that was measured and
+ *    cut (see guard.ts), so nothing here claims it.
+ *
+ *  - `native`: a Claude Code `permissions` entry the user can add by hand with no
+ *    extra tool. Only emitted where a permission rule can genuinely express the
+ *    thing, and always with the honest caveat: a permission rule matches the
+ *    command text or the file path, so it cannot scope to a branch, cannot read a
+ *    commit message, and cannot see file content. Where it can't express the rule,
+ *    `nativeImpossibleReason` says so instead of inventing a rule that wouldn't fire.
+ *
+ * `preventable: false` is the honest answer for the rest: a claim-evidence rule,
+ * an emoji rule, an edit-implies-test rule, a plain literal rule — these are judged
+ * AFTER the run, not blockable before an action. The caller points at `check` and
+ * the Stop hook instead.
+ */
+export interface BlockHint {
+    /** Can an action be refused BEFORE it runs (guard or a native deny/ask)? */
+    preventable: boolean;
+    /** Does RuleReceipt's own guard (`rulereceipt protect`) check this exact rule pre-flight? */
+    guardCovers: boolean;
+    /** A native Claude Code permissions entry, where one can genuinely express the rule. */
+    native?: {
+        kind: "deny" | "ask";
+        entries: string[];
+        note: string;
+    };
+    /** When preventable but a native permission rule cannot express it, why. */
+    nativeImpossibleReason?: string;
+}
+/**
+ * The block advice for one classified rule, or undefined when there is nothing
+ * useful to say (a judgment rule or a non-rule — the "needs your judgment" line
+ * already covers those).
+ */
+export declare function blockHintFor(cls: Classification): BlockHint | undefined;

package/dist/blockHint.js

@@ -0,0 +1,87 @@
+/** Map an approval-gate action to the Claude Code permission pattern that matches it. */
+function askEntryFor(action) {
+    switch (action) {
+        case "push": return "Bash(git push:*)";
+        case "commit": return "Bash(git commit:*)";
+        case "pr": return "Bash(gh pr:*)";
+        case "delete": return "Bash(rm:*)";
+        default: return undefined;
+    }
+}
+/**
+ * The block advice for one classified rule, or undefined when there is nothing
+ * useful to say (a judgment rule or a non-rule — the "needs your judgment" line
+ * already covers those).
+ */
+export function blockHintFor(cls) {
+    switch (cls.kind) {
+        case "gitBranchPolicy": {
+            if (cls.polarity !== "forbid")
+                return { preventable: false, guardCovers: false };
+            return {
+                preventable: true,
+                guardCovers: true,
+                native: {
+                    kind: "deny",
+                    entries: ["Bash(git push:*)"],
+                    note: `a permission rule matches the command text, so this denies EVERY push — it can't ` +
+                        `scope to the \`${cls.branchName}\` branch. The guard below checks the actual target branch.`,
+                },
+            };
+        }
+        case "fileLifecycle": {
+            if (cls.polarity !== "forbid")
+                return { preventable: false, guardCovers: false };
+            return {
+                preventable: true,
+                guardCovers: true,
+                native: {
+                    kind: "deny",
+                    entries: [`Edit(${cls.filePath})`, `Write(${cls.filePath})`],
+                    note: `covers Edit/Write of that path; a Bash \`rm\`/\`mv\` targeting it is NOT matched by ` +
+                        `these — the guard below covers those too.`,
+                },
+            };
+        }
+        case "approvalGate": {
+            const entries = cls.actions.map(askEntryFor).filter((e) => e !== undefined);
+            if (entries.length === 0)
+                return { preventable: true, guardCovers: true, nativeImpossibleReason: "the action it gates isn't one a permission rule can match" };
+            return {
+                preventable: true,
+                guardCovers: true,
+                native: {
+                    kind: "ask",
+                    entries,
+                    note: `an "ask" is skipped in no-prompt modes (bypassPermissions / auto), so the action would ` +
+                        `run there without a prompt. The guard below denies it in those modes instead.`,
+                },
+            };
+        }
+        case "attribution":
+            return {
+                preventable: true,
+                guardCovers: true,
+                nativeImpossibleReason: "a permission rule can't read a commit message, so it can't catch an AI-authorship trailer",
+            };
+        case "codeContent": {
+            if (cls.polarity !== "forbid")
+                return { preventable: false, guardCovers: false };
+            return {
+                preventable: true,
+                guardCovers: true,
+                nativeImpossibleReason: "a permission rule matches the command or path, not the content written into a file",
+            };
+        }
+        case "claimEvidence":
+        case "ifEditThenTest":
+        case "emojiOutput":
+        case "deterministic":
+            // Checkable, but only after the run — there is no single action to refuse
+            // beforehand. The caller points at `check` and the Stop hook.
+            return { preventable: false, guardCovers: false };
+        default:
+            // judgment, notARule — nothing mechanical to block or check.
+            return undefined;
+    }
+}

package/dist/breakContext.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A4 — "why it broke" context for a single proven break.
+ *
+ * The report says WHICH rule broke and quotes the line. This adds the three
+ * things a person asks next, read straight from the raw transcript (the parsed
+ * event stream drops attachment/system/compaction lines, so this works on the
+ * file text `check` already has):
+ *
+ *   1. the user's own message just before the break,
+ *   2. whether the rules file (CLAUDE.md/AGENTS.md/GEMINI.md) was in context
+ *      BEFORE the break at all,
+ *   3. whether a compaction happened earlier in the session.
+ *
+ * The point of (2) is honesty, not accusation. Claude Code can load CLAUDE.md
+ * only when a Read touches its directory, so a shell-heavy session may never
+ * have the rule in context. When that is the case the report must say "the rules
+ * file was not in context here", NOT imply the agent ignored a rule it never saw
+ * — and it points at the fix (a SessionStart / post-compaction hook that injects
+ * the rules). Nothing here changes a verdict; it only explains one.
+ *
+ * If the break line cannot be located in the transcript (evidence with no
+ * quotable fragment), `located` is false and the caller shows nothing rather
+ * than guessing.
+ */
+export interface BreakContext {
+    located: boolean;
+    /** The user's own typed message just before the break, clipped; undefined if none. */
+    precedingUser?: string;
+    /** Did a rules file appear in the transcript before the break? */
+    rulesInContext: boolean;
+    /** Did a compaction occur before the break? */
+    compactionBefore: boolean;
+    /**
+     * The rules file was in context earlier, but its last appearance was BEFORE
+     * the last compaction and it was not re-injected after — so the summary may
+     * have dropped it. (The real session ef53e676: CLAUDE.md present before a
+     * compaction, never came back.)
+     */
+    rulesStaleAfterCompaction: boolean;
+}
+/**
+ * Context for the break whose evidence is `evidence`, read from the raw JSONL
+ * `transcriptText`. Line-based: the break line is the LAST line carrying a
+ * distinctive fragment of the evidence (so a later, unrelated mention does not
+ * win), and the three facts are computed over the lines before it.
+ */
+export declare function breakContext(transcriptText: string, evidence: string): BreakContext;
+/** The lines the report prints under a break, or [] when nothing is worth adding. */
+export declare function renderBreakContext(ctx: BreakContext): string[];

package/dist/breakContext.js

@@ -0,0 +1,129 @@
+/**
+ * A4 — "why it broke" context for a single proven break.
+ *
+ * The report says WHICH rule broke and quotes the line. This adds the three
+ * things a person asks next, read straight from the raw transcript (the parsed
+ * event stream drops attachment/system/compaction lines, so this works on the
+ * file text `check` already has):
+ *
+ *   1. the user's own message just before the break,
+ *   2. whether the rules file (CLAUDE.md/AGENTS.md/GEMINI.md) was in context
+ *      BEFORE the break at all,
+ *   3. whether a compaction happened earlier in the session.
+ *
+ * The point of (2) is honesty, not accusation. Claude Code can load CLAUDE.md
+ * only when a Read touches its directory, so a shell-heavy session may never
+ * have the rule in context. When that is the case the report must say "the rules
+ * file was not in context here", NOT imply the agent ignored a rule it never saw
+ * — and it points at the fix (a SessionStart / post-compaction hook that injects
+ * the rules). Nothing here changes a verdict; it only explains one.
+ *
+ * If the break line cannot be located in the transcript (evidence with no
+ * quotable fragment), `located` is false and the caller shows nothing rather
+ * than guessing.
+ */
+// A rules file being injected into context. Covers the literal injected header
+// ("Contents of .../CLAUDE.md (project instructions"), the "checked into" variant,
+// and the structural claudeMd attachment (escaped or not inside a JSONL line).
+const RULES_INJECTION = /Contents of [^\n"]*(?:CLAUDE|AGENTS|GEMINI|AGENT)[^\n"]*\.md \(project instructions|project instructions, checked into|\\?"(?:claudeMd|type\\?":\\?"claudeMd)\\?"|\\?"type\\?":\s*\\?"claudeMd/;
+const COMPACTION = /"isCompactSummary"\s*:\s*true/;
+/** Longest-first distinctive fragments of the evidence to find the break line by. */
+function needles(evidence) {
+    const quoted = [...evidence.matchAll(/"([^"]{6,})"/g)].map((m) => m[1]);
+    const after = evidence.split(/:\s/).slice(1).join(": ");
+    return [...quoted, after]
+        .map((s) => s.replace(/\s+/g, " ").trim().slice(0, 80))
+        .filter((s) => s.length >= 6)
+        .sort((a, b) => b.length - a.length);
+}
+/** The human's own message on a user line (string content), or null. */
+function userTyped(line) {
+    try {
+        const o = JSON.parse(line);
+        if (o.type !== "user")
+            return null;
+        const c = o.message?.content;
+        if (typeof c === "string" && c.trim().length > 0)
+            return c.trim();
+    }
+    catch {
+        /* partial line */
+    }
+    return null;
+}
+function clip(s, n = 140) {
+    const one = s.replace(/\s+/g, " ").trim();
+    if (one.length <= n)
+        return one;
+    const cut = one.slice(0, n);
+    const sp = cut.lastIndexOf(" ");
+    return `${sp > n * 0.6 ? cut.slice(0, sp) : cut}…`;
+}
+/**
+ * Context for the break whose evidence is `evidence`, read from the raw JSONL
+ * `transcriptText`. Line-based: the break line is the LAST line carrying a
+ * distinctive fragment of the evidence (so a later, unrelated mention does not
+ * win), and the three facts are computed over the lines before it.
+ */
+export function breakContext(transcriptText, evidence) {
+    const lines = transcriptText.split(/\r?\n/);
+    const ns = needles(evidence);
+    let breakIdx = -1;
+    if (ns.length > 0) {
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const flat = lines[i].replace(/\s+/g, " ");
+            if (ns.some((n) => flat.includes(n))) {
+                breakIdx = i;
+                break;
+            }
+        }
+    }
+    if (breakIdx === -1)
+        return { located: false, rulesInContext: false, compactionBefore: false, rulesStaleAfterCompaction: false };
+    let lastRulesIdx = -1;
+    let lastCompactionIdx = -1;
+    let precedingUser;
+    for (let i = 0; i < breakIdx; i++) {
+        const line = lines[i];
+        if (RULES_INJECTION.test(line))
+            lastRulesIdx = i;
+        if (COMPACTION.test(line))
+            lastCompactionIdx = i;
+        const u = userTyped(line);
+        if (u)
+            precedingUser = clip(u);
+    }
+    const rulesInContext = lastRulesIdx !== -1;
+    const compactionBefore = lastCompactionIdx !== -1;
+    return {
+        located: true,
+        precedingUser,
+        rulesInContext,
+        compactionBefore,
+        rulesStaleAfterCompaction: rulesInContext && compactionBefore && lastRulesIdx < lastCompactionIdx,
+    };
+}
+/** The lines the report prints under a break, or [] when nothing is worth adding. */
+export function renderBreakContext(ctx) {
+    if (!ctx.located)
+        return [];
+    const out = ["     why it broke:"];
+    if (ctx.precedingUser)
+        out.push(`       just before, you said: "${ctx.precedingUser}"`);
+    if (!ctx.rulesInContext) {
+        out.push("       your rules file was NOT in context at this point — not the agent ignoring a");
+        out.push("       rule it never saw. Claude Code can load CLAUDE.md only when a Read touches its");
+        out.push("       directory, so a shell-heavy session can miss it. Fix: a SessionStart (and");
+        out.push("       post-compaction) hook that injects your rules every session.");
+    }
+    else if (ctx.rulesStaleAfterCompaction) {
+        out.push("       your rules file was in context earlier but NOT after the last compaction — the");
+        out.push("       summary may have dropped it. Fix: a post-compaction hook that re-injects your rules.");
+    }
+    else {
+        out.push("       your rules file was in context before this.");
+        if (ctx.compactionBefore)
+            out.push("       (a compaction happened earlier in this session; context before it was summarised.)");
+    }
+    return out;
+}

package/dist/cli.js

@@ -19,7 +19,7 @@ import { ghReady, issueTitle, issueCreateArgs, buildMailto, mailtoSubject } from
 import { spawnSync } from "node:child_process";
 import { detectSelfEditedRuleFiles } from "./checks/selfEditedRules.js";
 import { scanHistory, renderHistory } from "./historyReport.js";
-import { explainRule, renderWhy } from "./why.js";
+import { explainRule, renderWhy, explainAll, renderAllWhy, whyList, renderWhyList } from "./why.js";
 import { observeSessions, renderNoRules, draftRulesFromHistory } from "./sessionObserve.js";
 import { listSessionRows, renderSessionList } from "./listSessions.js";
 import { runSelfTestChecks, renderSelfTest } from "./selftest.js";
@@ -282,7 +282,17 @@ async function runCheck(opts) {
         : "";
     // Kept in human/markdown form for --email and any other reader below, even
     // when stdout is JSON — a manager gets a readable report, not raw JSON.
-    const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta);
+    // The raw session text, for A4 "why it broke" context under each Broken verdict.
+    // Best-effort: if it can't be read, the report simply omits the context.
+    let transcriptText;
+    try {
+        if (sessionFilePath)
+            transcriptText = readFileSync(sessionFilePath, "utf-8");
+    }
+    catch {
+        /* unreadable: no A4 context, never a crash */
+    }
+    const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta, transcriptText);
     if (json) {
         console.log(generateJsonReport(results, meta, pkg.version, editedRuleFiles));
     }
@@ -572,7 +582,7 @@ function runAdvise() {
     console.log(`  ${advice.length} cannot yet — here is what each one needs:\n`);
     // Project rules first: those are the ones the reader can act on today.
     const ordered = advice
-        .map((a, i) => ({ a, source: rules.find((r) => r.title === a.ruleTitle)?.source }))
+        .map((a) => ({ a, source: rules.find((r) => r.title === a.ruleTitle)?.source }))
         .sort((x, y) => Number(x.source === "global") - Number(y.source === "global"))
         .map((x) => x.a);
     for (const a of ordered) {
@@ -931,7 +941,7 @@ const PERIOD_MS = {
 };
 program
     .command("report")
-    .description("Compliance report across your recent sessions (not just the latest): which policy rules were broken, where, with evidence. Deterministic, local, no network. The org-wide version runs via the Claude Compliance API for Enterprise orgs.")
+    .description("Compliance report across your recent sessions (not just the latest): which policy rules were broken, where, with evidence. Deterministic, local, no network. An org-wide version (multi-repo, trends, a manager digest) is coming in the team version.")
     .option("--last <n>", "how many recent sessions to audit", "25")
     .option("--markdown", "output as markdown, for a report you can send")
     .action(async (opts) => {
@@ -953,18 +963,31 @@ program
     console.log(renderProjectAudit(a, Boolean(opts.markdown)));
 });
 program
-    .command("why <rule...>")
-    .description("Everything the tool knows about ONE rule, in one place: where it lives (file:line), whether the agent actually loads it, whether a command or path it names exists, whether it's mechanically checkable (and if not, one suggested rewrite), and how it did over the last 30 days. Fuzzy-matches the rule text; if several match, lists them. Read-only — no verdict is created, nothing is sent.")
+    .command("why [rule...]")
+    .description("Everything the tool knows about ONE rule, in one place: where it lives (file:line), whether the agent actually loads it, whether a command or path it names exists, whether it's mechanically checkable (and if not, one suggested rewrite), and how it did over the last 30 days. With no argument, lists every rule with its id so you can pick one; with --all, shows every rule (problems first). Read-only — no verdict is created, nothing is sent.")
+    .option("--all", "show every rule, problems first (not loaded, missing command, broken recently), then the rest")
     .option("--json", "output machine-readable JSON (the same fields)")
     .action(async (ruleWords, opts) => {
     const cwd = process.cwd();
-    const query = ruleWords.join(" ").trim();
+    const query = (ruleWords ?? []).join(" ").trim();
     const rules = loadRules(cwd);
     if (rules.length === 0) {
         console.log("No rules file found here, so there is nothing to explain. Run `rulereceipt init` to add one.");
         process.exitCode = 1;
         return;
     }
+    // --all: every rule, problems first.
+    if (opts.all) {
+        const all = await explainAll(cwd);
+        console.log(opts.json ? JSON.stringify(all, null, 2) : renderAllWhy(all));
+        return;
+    }
+    // No argument: list the rules with ids so the reader can pick one.
+    if (query.length === 0) {
+        const list = whyList(cwd);
+        console.log(opts.json ? JSON.stringify(list, null, 2) : renderWhyList(list));
+        return;
+    }
     const result = await explainRule(cwd, query);
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -976,7 +999,7 @@ program
 });
 program
     .command("wrong <rule>")
-    .description("A verdict looks wrong? Builds a report of that rule, the verdict, how it was decided and the session lines around it, with obvious secrets masked. Written to a local file and shown first; prints a GitHub issue link for you to open. Nothing is sent.")
+    .description("A verdict looks wrong? Builds a report of that rule, the verdict, how it was decided and the session lines around it, with obvious secrets masked. Written to a local file and shown first. Then --submit opens a public GitHub issue (asks first; needs gh) or --email sends it privately to the maintainer; with no flag it just prints the report and a pre-filled link. Nothing is sent without your say-so.")
     .option("--transcript <path>", "use a specific session file (same as check)")
     .option("--out <path>", "where to write the report (default .rulereceipt/wrong-<handle>.md)")
     .option("--no-context", "leave out the session lines around the evidence")

package/dist/historyReport.js

@@ -150,6 +150,8 @@ export function renderHistory(s, projectName, now = Date.now()) {
     out.push(`checked ${s.sessionsScanned} session${s.sessionsScanned === 1 ? "" : "s"} in ${secs}s`);
     out.push("");
     out.push("See one session in full:  rulereceipt check");
+    out.push("Make Claude ask first:     rulereceipt protect");
+    out.push("Share the result:          rulereceipt card");
     out.push("Think a verdict is wrong?  rulereceipt wrong <rule>");
     return out.join("\n");
 }

package/dist/report/generateReport.d.ts

@@ -11,7 +11,12 @@ export interface ReportMeta {
  * is a valid state (e.g. running against demo data).
  */
 export declare function computeTranscriptHash(sessionFilePath: string | null): string | null;
-export declare function generateReport(results: CheckResult[], meta: ReportMeta): string;
+/**
+ * `transcriptText` is the raw session JSONL. When present, each Broken verdict
+ * gets A4 "why it broke" context (the user message before it, whether the rules
+ * file was in context, whether a compaction preceded it) read straight from it.
+ */
+export declare function generateReport(results: CheckResult[], meta: ReportMeta, transcriptText?: string): string;
 export declare function generateMarkdownReport(results: CheckResult[], meta: ReportMeta): string;
 /**
  * Machine-readable output for CI, a GitHub Action, or any other consumer.

package/dist/report/generateReport.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { breakContext, renderBreakContext } from "../breakContext.js";
 /**
  * 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
@@ -191,7 +192,12 @@ function sharedEvidence(rs) {
     }
     return best;
 }
-export function generateReport(results, meta) {
+/**
+ * `transcriptText` is the raw session JSONL. When present, each Broken verdict
+ * gets A4 "why it broke" context (the user message before it, whether the rules
+ * file was in context, whether a compaction preceded it) read straight from it.
+ */
+export function generateReport(results, meta, transcriptText) {
     const clean = results.map(sanitize);
     const lines = [];
     lines.push(`RuleReceipt · ${meta.ruleCount} rules checked`);
@@ -236,6 +242,13 @@ export function generateReport(results, meta) {
             // versions as a PASS on a session that ran `git push -f`.
             if (r.ceiling)
                 lines.push(`  this means: ${r.ceiling}`);
+            // A4: why it broke — the context around a proven break, read from the raw
+            // transcript. Honest by construction: if the rules file was never in
+            // context before the break, it says so rather than implying it was ignored.
+            if (r.status === "FAIL" && transcriptText && r.evidence) {
+                for (const l of renderBreakContext(breakContext(transcriptText, r.evidence)))
+                    lines.push(l);
+            }
         }
     }
     lines.push("");

package/dist/rules.js

@@ -75,20 +75,31 @@ function ruleSourcesAtLevel(dir) {
         for (const f of markdownFilesIn(join(dir, rel)))
             out.push({ path: f, status: "loaded", format: ".claude/rules" });
     }
-    if (has("CLAUDE.md")) {
+    // AGENTS.md / AGENT.md load ONLY when this level has no Claude file at all.
+    // As of Claude Code 2.1.277 (default "Project instructions" = claude-md-or-
+    // agents-md), AGENTS.md is read only when none of CLAUDE.md / CLAUDE.local.md
+    // (nor .claude/CLAUDE.md, handled above) exists — so CLAUDE.local.md ALSO
+    // shadows AGENTS.md, not just CLAUDE.md. Checking a shadowed AGENTS.md would be
+    // a false accusation (it never reaches the agent).
+    // KNOWN LIMIT: the 2.1.277 rule is "no Claude file in cwd OR ABOVE"; this
+    // shadows at the SAME level only. A parent CLAUDE.md shadowing a child
+    // AGENTS.md across levels is not yet modelled (see KNOWN-GAPS).
+    const hasClaudeMd = has("CLAUDE.md");
+    const hasClaudeLocal = has("CLAUDE.local.md");
+    if (hasClaudeMd)
         loaded("CLAUDE.md", "Claude (CLAUDE.md)");
-        // AGENTS.md (and the singular AGENT.md some tools use) are ignored when
-        // there's a CLAUDE.md at this level, mirroring Claude Code's shadow rule.
-        shadowed("AGENTS.md", "AGENTS.md", "a CLAUDE.md at the same level wins");
-        shadowed("AGENT.md", "AGENT.md", "a CLAUDE.md at the same level wins");
+    // .local always loads alongside the base CLAUDE.md when present.
+    if (hasClaudeLocal)
+        loaded("CLAUDE.local.md", "Claude (CLAUDE.local.md)");
+    if (hasClaudeMd || hasClaudeLocal) {
+        const winner = hasClaudeMd ? "CLAUDE.md" : "CLAUDE.local.md";
+        shadowed("AGENTS.md", "AGENTS.md", `a ${winner} at the same level wins`);
+        shadowed("AGENT.md", "AGENT.md", `a ${winner} at the same level wins`);
     }
     else {
         loaded("AGENTS.md", "AGENTS.md");
         loaded("AGENT.md", "AGENT.md");
     }
-    // .local variants: precedence relative to the base files is not documented,
-    // so both are kept rather than guessing at a shadow rule.
-    loaded("CLAUDE.local.md", "Claude (CLAUDE.local.md)");
     loaded("AGENTS.local.md", "AGENTS (AGENTS.local.md)");
     // Non-Claude rule-file conventions (added 2026-09-26 for multi-tool
     // support), read IN ADDITION to Claude's files when present. The engine

package/dist/why.d.ts

@@ -1,3 +1,4 @@
+import { type BlockHint } from "./blockHint.js";
 import type { Rule } from "./types.js";
 export interface WhyRule {
     id: string;
@@ -15,6 +16,8 @@ export interface WhyRule {
         name: string;
         exists: boolean;
     };
+    /** How (and whether) this rule can actually be blocked/checked — see blockHint.ts. */
+    block?: BlockHint;
     brokenCount: number;
     brokenDates: string[];
     sessionsScanned: number;
@@ -31,4 +34,28 @@ export interface WhyResult {
 /** Fuzzy-match a rule by the query appearing in its title/body, or the query being the title. */
 export declare function findRules(rules: Rule[], query: string): Rule[];
 export declare function explainRule(cwd: string, query: string): Promise<WhyResult>;
+export interface WhyAll {
+    rules: WhyRule[];
+    sessionsScanned: number;
+}
+/**
+ * `why --all` — the same facts for every loaded rule, problems first (not loaded, then a
+ * named command/file missing, then broken recently, then judgment-only, then the rest).
+ * Read-only, facts only, no verdicts. Order within a rank is the rule's own order.
+ */
+export declare function explainAll(cwd: string): Promise<WhyAll>;
+/** The no-argument help: how to use `why`, plus every rule with its id, so people can pick. */
+export declare function whyList(cwd: string): {
+    id: string;
+    title: string;
+    location: string;
+}[];
 export declare function renderWhy(r: WhyResult): string;
+/** No-argument output: how to use `why`, then every rule with its id so you can pick one. */
+export declare function renderWhyList(list: {
+    id: string;
+    title: string;
+    location: string;
+}[]): string;
+/** One short line per rule for `why --all`, problems first. */
+export declare function renderAllWhy(all: WhyAll): string;

package/dist/why.js

@@ -5,6 +5,7 @@ import { loadRules, describeRuleSources } from "./rules.js";
 import { classifyRule } from "./checks/classify.js";
 import { adviseRule } from "./checkability.js";
 import { scanHistory } from "./historyReport.js";
+import { blockHintFor } from "./blockHint.js";
 /**
  * `rulereceipt why "<rule text>"` — everything the tool already knows about ONE
  * rule, in one place: where it lives, whether the agent even loads it, whether a
@@ -63,6 +64,43 @@ function namedCommandOrPath(rule, cwd) {
     }
     return undefined;
 }
+async function historyLookup(cwd, rules) {
+    try {
+        const hist = await scanHistory(cwd, rules, 30);
+        const byRule = new Map();
+        for (const b of hist.breaks)
+            byRule.set(`${b.ruleId}\u0000${b.ruleTitle}`, { count: b.count, lastMs: b.lastMs });
+        return { sessionsScanned: hist.sessionsScanned, byRule };
+    }
+    catch {
+        return { sessionsScanned: 0, byRule: new Map() };
+    }
+}
+/** Build the WhyRule facts for one rule, reusing an already-computed load graph and history. */
+function ruleFacts(cwd, rule, graph, hist) {
+    const src = rule.sourcePath ? graph.find((e) => e.path === rule.sourcePath) : undefined;
+    const cls = classifyRule(rule);
+    const checkable = CHECKABLE_KINDS.has(cls.kind);
+    const advice = checkable ? null : adviseRule(rule);
+    const b = hist.byRule.get(`${rule.id}\u0000${rule.title}`);
+    return {
+        id: rule.id,
+        title: rule.title,
+        source: rule.source,
+        location: locationOf(rule),
+        loaded: src ? src.status === "loaded" : true,
+        loadNote: src?.note,
+        pathScoped: rule.paths ? rule.paths.join(", ") : undefined,
+        checkable,
+        kind: cls.kind,
+        suggestion: advice?.suggestion,
+        named: namedCommandOrPath(rule, cwd),
+        block: blockHintFor(cls),
+        brokenCount: b?.count ?? 0,
+        brokenDates: b ? [new Date(b.lastMs).toISOString().slice(0, 10)] : [],
+        sessionsScanned: hist.sessionsScanned,
+    };
+}
 export async function explainRule(cwd, query) {
     const rules = loadRules(cwd);
     const matches = findRules(rules, query);
@@ -75,47 +113,41 @@ export async function explainRule(cwd, query) {
             candidates: matches.slice(0, 12).map((r) => ({ title: r.title, location: locationOf(r) })),
         };
     }
-    const rule = matches[0];
     const graph = describeRuleSources(cwd);
-    const src = rule.sourcePath ? graph.find((e) => e.path === rule.sourcePath) : undefined;
-    const cls = classifyRule(rule);
-    const checkable = CHECKABLE_KINDS.has(cls.kind);
-    const advice = checkable ? null : adviseRule(rule);
-    let brokenCount = 0;
-    let brokenDates = [];
-    let sessionsScanned = 0;
-    try {
-        const hist = await scanHistory(cwd, rules, 30);
-        sessionsScanned = hist.sessionsScanned;
-        const b = hist.breaks.find((x) => x.ruleId === rule.id && x.ruleTitle === rule.title);
-        if (b) {
-            brokenCount = b.count;
-            brokenDates = [new Date(b.lastMs).toISOString().slice(0, 10)];
-        }
-    }
-    catch {
-        /* history is best-effort; a rule can still be explained without it */
-    }
-    return {
-        query,
-        matches: 1,
-        rule: {
-            id: rule.id,
-            title: rule.title,
-            source: rule.source,
-            location: locationOf(rule),
-            loaded: src ? src.status === "loaded" : true,
-            loadNote: src?.note,
-            pathScoped: rule.paths ? rule.paths.join(", ") : undefined,
-            checkable,
-            kind: cls.kind,
-            suggestion: advice?.suggestion,
-            named: namedCommandOrPath(rule, cwd),
-            brokenCount,
-            brokenDates,
-            sessionsScanned,
-        },
-    };
+    const hist = await historyLookup(cwd, rules);
+    return { query, matches: 1, rule: ruleFacts(cwd, matches[0], graph, hist) };
+}
+/** A "problem" rank so `why --all` can put the ones that need attention first. */
+function problemRank(w) {
+    if (!w.loaded)
+        return 0; // the agent never sees it
+    if (w.named && !w.named.exists)
+        return 1; // names a command/file that does not exist
+    if (w.brokenCount > 0)
+        return 2; // broken recently
+    if (!w.checkable)
+        return 3; // needs judgment
+    return 4; // fine
+}
+/**
+ * `why --all` — the same facts for every loaded rule, problems first (not loaded, then a
+ * named command/file missing, then broken recently, then judgment-only, then the rest).
+ * Read-only, facts only, no verdicts. Order within a rank is the rule's own order.
+ */
+export async function explainAll(cwd) {
+    const rules = loadRules(cwd);
+    const graph = describeRuleSources(cwd);
+    const hist = await historyLookup(cwd, rules);
+    const facts = rules.map((r) => ruleFacts(cwd, r, graph, hist));
+    const ranked = facts
+        .map((w, i) => ({ w, i }))
+        .sort((a, b) => problemRank(a.w) - problemRank(b.w) || a.i - b.i)
+        .map((x) => x.w);
+    return { rules: ranked, sessionsScanned: hist.sessionsScanned };
+}
+/** The no-argument help: how to use `why`, plus every rule with its id, so people can pick. */
+export function whyList(cwd) {
+    return loadRules(cwd).map((r) => ({ id: r.id, title: r.title, location: locationOf(r) }));
 }
 function locationOf(rule) {
     if (!rule.sourcePath)
@@ -144,6 +176,7 @@ export function renderWhy(r) {
     out.push(w.checkable
         ? `  ✓ mechanically checkable (${w.kind}) — a session is judged against it with quoted evidence`
         : `  • needs your judgment${w.suggestion ? ` — ${w.suggestion}` : ` — no command or file to check it by; a human decides`}`);
+    renderBlockHint(w.block, out);
     out.push("");
     if (w.brokenCount > 0)
         out.push(`  last 30 days: broken ${w.brokenCount}× (last: ${w.brokenDates[0]}) across ${w.sessionsScanned} session${w.sessionsScanned === 1 ? "" : "s"}`);
@@ -151,3 +184,72 @@ export function renderWhy(r) {
         out.push(`  last 30 days: no proven break across ${w.sessionsScanned} session${w.sessionsScanned === 1 ? "" : "s"}`);
     return out.join("\n");
 }
+/**
+ * How to actually enforce this rule, appended to the single-rule view. Prints
+ * only what the tool truly does: a native Claude Code permissions rule where one
+ * can genuinely express it (with its honest limitation), RuleReceipt's own guard
+ * where it covers the rule pre-flight, and — for rules judged only after the run —
+ * the after-the-fact path. Nothing here claims a block the guard doesn't make.
+ */
+function renderBlockHint(block, out) {
+    if (!block)
+        return;
+    out.push("");
+    if (block.preventable) {
+        out.push("  To stop this before it runs:");
+        if (block.native) {
+            const entries = block.native.entries.map((e) => `"${e}"`).join(", ");
+            out.push(`    • Claude Code settings (.claude/settings.json), no extra tool:`);
+            out.push(`        { "permissions": { "${block.native.kind}": [${entries}] } }`);
+            out.push(`      ${block.native.note}`);
+        }
+        else if (block.nativeImpossibleReason) {
+            out.push(`    • A Claude Code permission rule can't express this — ${block.nativeImpossibleReason}.`);
+        }
+        if (block.guardCovers) {
+            out.push(`    • RuleReceipt's own guard checks this exact rule: run \`rulereceipt protect\``);
+            out.push(`      (adds a PreToolUse deny hook + a Stop hook, shown before it writes anything).`);
+        }
+    }
+    else {
+        out.push("  Can't be blocked before an action — this rule is judged after the run.");
+        out.push("  Run `rulereceipt check` after a session; `rulereceipt protect` also adds a Stop");
+        out.push("  hook that won't let a session end on a broken rule.");
+    }
+}
+/** No-argument output: how to use `why`, then every rule with its id so you can pick one. */
+export function renderWhyList(list) {
+    if (list.length === 0)
+        return "No rules file found here. Run `rulereceipt init` to add one, then `rulereceipt why \"<rule>\"`.";
+    const out = ['Explain one rule:  rulereceipt why "<some words from the rule>"', "Or all of them:    rulereceipt why --all", "", "Rules found:"];
+    for (const r of list)
+        out.push(`  ${r.id.padEnd(6)}  ${r.title.replace(/\s+/g, " ").slice(0, 72)}`);
+    return out.join("\n");
+}
+/** One short line per rule for `why --all`, problems first. */
+export function renderAllWhy(all) {
+    if (all.rules.length === 0)
+        return "No rules file found here. Run `rulereceipt init` to add one.";
+    const out = [];
+    for (const w of all.rules) {
+        let mark = "  ✓";
+        let note = w.checkable ? `checkable (${w.kind})` : "needs your judgment";
+        if (!w.loaded) {
+            mark = "  ✗";
+            note = `NOT loaded — ${w.loadNote ?? "the agent never sees this file"}`;
+        }
+        else if (w.named && !w.named.exists) {
+            mark = "  ✗";
+            note = `names a ${w.named.kind} that does not exist: ${w.named.name}`;
+        }
+        else if (w.brokenCount > 0) {
+            mark = "  ✗";
+            note = `broken ${w.brokenCount}× (last: ${w.brokenDates[0]})`;
+        }
+        out.push(`${mark} ${w.id.padEnd(6)} ${w.title.replace(/\s+/g, " ").slice(0, 60)}`);
+        out.push(`         ${note}`);
+    }
+    out.push("");
+    out.push(`across ${all.sessionsScanned} session${all.sessionsScanned === 1 ? "" : "s"} · run \`rulereceipt why "<rule>"\` for one rule in full`);
+    return out.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "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",
@@ -43,6 +43,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src tests",
+    "license:check": "node scripts/license-gate.mjs",
     "prepublishOnly": "npm run build && npm test",
     "build:checker": "esbuild src/browser/analyze.ts --bundle --format=esm --minify --outfile=landing/checker.js",
     "verify": "npm run lint && npm run typecheck && npm test"