rulereceipt 0.1.35 → 0.1.37

package/README.md

@@ -88,6 +88,7 @@ rulereceipt rules --include <handle>   # "this IS a rule" — check it from now
 rulereceipt rules --exclude <handle>   # "this isn't" — stop reporting it
 rulereceipt rules --coverage   # which rules a configured hook might actually enforce
 rulereceipt doctor             # list hooks/auto-run tasks configured on this machine
+rulereceipt hook               # run AS a Claude Code Stop hook — block Claude finishing on a broken rule
 rulereceipt lint               # find contradictions between CLAUDE.md and AGENTS.md
 rulereceipt digest             # summarise recent checks; --email to send it
 rulereceipt config             # set up email sending (stays on your machine)
@@ -99,6 +100,49 @@ rulereceipt verify <session-file> <hash>   # spot-check a report you received ag
 
 `verify` isn't a routine check — trust your team day to day, same as any status update. It's there for the rare case it actually matters (a dispute, an incident review): give it the session file and the hash printed in the report, and it confirms whether they really match.
 
+## Blocking, not just reporting
+
+`rulereceipt check` tells you afterwards. `rulereceipt hook` refuses to let the
+session end.
+
+Add this to `.claude/settings.json` — you add it, we never do:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "npx rulereceipt hook" } ] }
+    ]
+  }
+}
+```
+
+When Claude tries to finish, it reads the session that just happened. If a rule
+was broken it hands Claude the rule, the evidence, and instructions to keep
+working, so the session cannot end on a claim that isn't backed.
+
+The one it is actually for: *"Done — all tests pass"* when the last run of
+`npm test` returned two failures. It checks the claim against what ran, which
+is the part a model cannot talk its way around.
+
+Three properties worth knowing before you wire it in:
+
+- **It only blocks on things it can prove.** Never a judgment rule, never an
+  LLM opinion, never "couldn't tell". Only a matched literal or a claim
+  contradicted by a recorded tool result. Run against twelve real sessions it
+  blocked none of them.
+- **It cannot loop.** Claude Code sets `stop_hook_active` when a session is
+  already continuing because of a block; the hook returns immediately in that
+  case. One interruption per stop.
+- **It fails open.** Unreadable transcript, missing rules file, a bug in us —
+  it allows the stop and writes a line to stderr. Failing closed would mean our
+  bug locks you out of finishing your own session. That is a deliberate
+  weakening, and it is why `check` in CI stays the backstop.
+
+It runs when Claude stops, so it catches a finished session, not a command
+mid-flight. For that, use a `PreToolUse` hook of your own — `rulereceipt
+doctor` will show you what you already have.
+
 ## Which rules actually have teeth
 
 A rule in a file and a rule with a `PreToolUse` hook behind it look identical

package/dist/checks/claimEvidence.js

@@ -1,4 +1,4 @@
-import { TEST_COMMAND } from "./testCommands.js";
+import { TEST_COMMAND, withoutHeredocs, countTestRuns } from "./testCommands.js";
 /**
  * Did the session claim something worked, when the log says it didn't?
  *
@@ -200,7 +200,7 @@ export function runClaimEvidenceChecks(classifications, events) {
     for (const event of events) {
         const command = commandOf(event);
         if (command !== null) {
-            pendingRun = TEST_COMMAND.test(command) ? command : null;
+            pendingRun = TEST_COMMAND.test(withoutHeredocs(command)) ? command : null;
             for (const action of ACTION_CLAIMS) {
                 if (action.command.test(command))
                     commandsSeen.add(action.label);
@@ -222,10 +222,15 @@ export function runClaimEvidenceChecks(classifications, events) {
                 // words survive a pipe, the exit status does not.
                 const stated = outcomeFromOutput(event.content);
                 const trustExitCode = !PIPED.test(pendingRun);
+                // Two suite invocations in one command means neither the exit code
+                // nor the printed summary belongs to a single run, so nothing about
+                // this command can contradict a claim. Checked before both, because
+                // reading the output is what defeated the pipe guard here.
+                const oneRun = countTestRuns(pendingRun) <= 1;
                 lastRun = {
                     command: pendingRun,
                     failed: stated !== null ? stated : event.isError,
-                    outcomeReadable: stated !== null || trustExitCode,
+                    outcomeReadable: oneRun && (stated !== null || trustExitCode),
                     output: event.content.slice(0, 200),
                 };
                 pendingRun = null;

package/dist/checks/classify.js

@@ -200,19 +200,83 @@ const PRE_ACTION_GATE = /\b(?:repeat[- ]back|restate\s+what|wait\s+for\s+(?:conf
  * failures on its own.
  */
 const MAX_RULE_BODY_FOR_CLAIM = 1500;
+/**
+ * The claim shape: a reporting verb NEXT TO a done-word.
+ *
+ * "Do not claim tests passed", "before declaring work complete", "before
+ * telling user publishing is complete" — the two halves sit within a few
+ * words of each other, in one sentence, because that adjacency IS the
+ * thing being forbidden: announcing a finish you have not verified.
+ *
+ * Testing the two words independently across a whole section is what kept
+ * mis-routing. A 944-character rule about writing Slack updates contained a
+ * reporting verb in one paragraph, an evidence noun in another, and the
+ * done-word inside the compound "Slack-ready" — three unrelated matches,
+ * one confident verdict about whether a test command was piped. That was
+ * patched twice with blocklist entries (PRE_ACTION_GATE) before the
+ * independence was recognised as the fault itself.
+ *
+ * Thirty characters, measured rather than picked: it is the smallest
+ * window that keeps every genuine claim rule in the corpus and the widest
+ * that admits none of the scattered ones. `[^.\n]` confines the match to a
+ * single sentence, which is what stops a match spanning a paragraph break.
+ * Across 559 public rules files this narrows claim-evidence from 38 rules
+ * to 8, and all 8 read as the same instruction in different words.
+ */
+const CLAIM_SHAPE = new RegExp(`(?:${REPORTING_VERB.source})[^.\n]{0,30}?(?:${DONE_WORD.source})` +
+    `|(?:${DONE_WORD.source})[^.\n]{0,30}?(?:${REPORTING_VERB.source})`, "i");
 function isClaimEvidenceRule(rule) {
     if (rule.text.length > MAX_RULE_BODY_FOR_CLAIM)
         return false;
     const text = `${rule.title} ${rule.text}`;
+    // Kept as a second line of defence even though CLAIM_SHAPE now excludes
+    // every case it was added for. It is cheap, it is tested, and the rules
+    // it names are ones this checker must never answer.
     if (PRE_ACTION_GATE.test(text))
         return false;
-    return REPORTING_VERB.test(text) && EVIDENCE_NOUN.test(text) && DONE_WORD.test(text);
+    return CLAIM_SHAPE.test(text) && EVIDENCE_NOUN.test(text);
 }
 const BRANCH_WORD = /\bbranch\b/i;
+/**
+ * A literal that could actually be a git branch name.
+ *
+ * git's refname rules, reduced to what a CLAUDE.md really writes: no
+ * whitespace, no shell punctuation, no `..`, no leading dash, not ending
+ * `.lock`. Everything this excludes was being accepted as a branch name and
+ * then searched for in the session's git commands.
+ *
+ * Rejecting a template is the point of the character class rather than an
+ * accident of it: `{`, `<` and `$` are how a rules file writes a PATTERN
+ * for branch names ("squad/{issue-number}-{kebab-case-slug}"), and a
+ * pattern is not a branch. Checking whether the session used a branch
+ * literally called that has no meaningful answer.
+ */
+const BRANCH_NAME_PATTERN = /^[A-Za-z0-9._/-]{1,100}$/;
+function isBranchName(literal) {
+    if (!BRANCH_NAME_PATTERN.test(literal))
+        return false;
+    if (literal.startsWith("-") || literal.startsWith("/"))
+        return false;
+    if (literal.includes("..") || literal.endsWith(".lock") || literal.endsWith("/"))
+        return false;
+    return true;
+}
 // A function/method-call shape ("print(", "analytics.track(") is a strong,
 // simple signal that a backtick literal names actual CODE, not a CLI
 // command or flag ("git push --force", "npm test" never look like this).
-const CODE_CONSTRUCT_PATTERN = /\(/;
+//
+// It must be a CALL, not merely a parenthesis. The test used to be /\(/,
+// which is true of a great deal of ordinary prose: measured 2026-09-15
+// across 559 rules files, 74 of 1,086 literals reaching content matching
+// (6.8%) were not code — "(e.g.", "(soft)", a markdown link fragment, three
+// whole blocks of accounting formulae. "(in the" produced a real false
+// accusation, reported as having been "actually written into a file", which
+// is true of any file containing that phrase.
+//
+// An identifier immediately before the paren, optionally dotted or scoped,
+// so "console.log(", "std::cout(" and "obj->run(" all qualify and a bare
+// parenthesis does not.
+const CODE_CONSTRUCT_PATTERN = /[A-Za-z_$][A-Za-z0-9_$]*(?:\s*(?:\.|::|->)\s*[A-Za-z_$][A-Za-z0-9_$]*)*\s*\(/;
 // A file-path shape: a known config/source extension, or a path with a
 // directory separator. Deliberately requires no spaces — a real path
 // literal ("`.claude/settings.json`", "`config.yaml`") never has one,
@@ -441,11 +505,12 @@ export function classifyRule(rule) {
         return { kind: "judgment", rule };
     }
     const polarityInferred = polarityWasInferred(rule);
-    if (BRANCH_WORD.test(text)) {
-        // first backtick literal is treated as the branch name — real rules
-        // this targets name exactly one branch ("the `demo` branch", "never
-        // push to `main`"), not a set of them
-        const [branchName] = patterns;
+    // The first literal that could BE a branch, not simply the first literal.
+    // Real rules here name exactly one branch ("the `demo` branch", "never
+    // push to the `main` branch"), and a rule that mentions branches while
+    // naming a command belongs to whichever checker handles that command.
+    const branchName = [...patterns].find(isBranchName);
+    if (BRANCH_WORD.test(text) && branchName !== undefined) {
         return { kind: "gitBranchPolicy", rule, branchName, polarity, polarityInferred };
     }
     // Route on ANY code-shaped literal, but check ONLY the code-shaped ones.

package/dist/checks/codeContent.js

@@ -29,6 +29,37 @@ function editedContentFromEvent(event) {
         return input.new_source;
     return null;
 }
+/**
+ * Whether the content contains this literal AS A CALL, not merely as a
+ * substring of a longer identifier.
+ *
+ * Found 2026-09-15 by checking a corpus FAIL rather than assuming it was
+ * legitimate: a rule forbidding `fetch()` matched a file containing
+ * `_metar_fetch()`. The literal was present verbatim, and entirely the wrong
+ * function. The same bare-substring test makes `main()` match `domain()` and
+ * `run()` match `rerun()`, and short generic call names are exactly what
+ * these rules tend to name.
+ *
+ * Only the LEADING boundary is checked. The trailing side is already pinned
+ * by the pattern itself — every literal reaching this checker ends in an
+ * open paren or a call — so requiring a boundary after it would reject the
+ * arguments.
+ */
+function containsCall(content, pattern) {
+    const leadsWithIdentifier = /^[A-Za-z0-9_$]/.test(pattern);
+    if (!leadsWithIdentifier)
+        return content.includes(pattern);
+    let from = 0;
+    for (;;) {
+        const at = content.indexOf(pattern, from);
+        if (at === -1)
+            return false;
+        const before = at === 0 ? "" : content[at - 1];
+        if (!/[A-Za-z0-9_$.]/.test(before))
+            return true;
+        from = at + 1;
+    }
+}
 export function runCodeContentChecks(classifications, events) {
     const editedContents = [];
     for (const event of events) {
@@ -41,7 +72,7 @@ export function runCodeContentChecks(classifications, events) {
         let foundContent;
         for (const content of editedContents) {
             for (const pattern of patterns) {
-                if (content.includes(pattern)) {
+                if (containsCall(content, pattern)) {
                     foundPattern = pattern;
                     foundContent = content;
                     break;

package/dist/checks/fileLifecycle.js

@@ -1,5 +1,6 @@
 import { violation } from "../types.js";
 import { isProjectPath } from "./projectPaths.js";
+import { withoutHeredocs } from "./shellCommand.js";
 /**
  * Third structured-check primitive: only counts real MUTATIONS of a
  * protected file, never reads of it. Real false-positive this fixes
@@ -43,7 +44,17 @@ function pathPattern(filePath) {
  * it mutates after that is a scratch file, not the project's.
  */
 const CD_INTO_TEMP = /\bcd\s+["']?(?:\/private)?\/(?:tmp|var\/folders)\b|\bcd\s+["']?[^\s"'&|;]*\/(?:scratchpad|node_modules)\b/;
-function mutatesPathInBash(command, filePath) {
+/**
+ * A path named only inside a heredoc body was not touched by the command
+ * that contains it.
+ *
+ * Real case, 2026-09-15: a command editing landing/index.html through a
+ * Python heredoc was reported as modifying `.claude/`, because the HTML it
+ * inserts tells readers to put a hook in `.claude/settings.json`. Writing a
+ * path into a file is not mutating that path.
+ */
+function mutatesPathInBash(rawCommand, filePath) {
+    const command = withoutHeredocs(rawCommand);
     const p = pathPattern(filePath);
     const mutations = [
         // rm / rmdir / unlink targeting the path

package/dist/checks/shellCommand.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Facts about shell command text that more than one checker needs.
+ *
+ * Created 2026-09-15. The heredoc guard below lived in testCommands.ts, was
+ * used only by the test-command matcher, and the file-mutation checker never
+ * saw it — so the same class of false accusation was fixed in one reader and
+ * left standing in the other. Anything that reasons about what a shell
+ * command DID, rather than what it says, belongs here.
+ */
+/**
+ * Removes heredoc bodies from a shell command.
+ *
+ * A command that WRITES a test command is not a command that RUNS one.
+ * Found 2026-09-14 on a real session: two false failures whose "last test
+ * run" was a shell variable assignment. The actual match came from a
+ * heredoc further down, writing a demo fixture whose body contains the
+ * string `npm test`. The literal was being generated, never executed — and
+ * the tool then read its own report output as the failing result.
+ *
+ * Handles both quoted and bare delimiters, and leaves everything after the
+ * closing delimiter intact, because a real test run often follows the
+ * heredoc that set the fixture up.
+ */
+export declare function withoutHeredocs(command: string): string;

package/dist/checks/shellCommand.js

@@ -0,0 +1,43 @@
+/**
+ * Facts about shell command text that more than one checker needs.
+ *
+ * Created 2026-09-15. The heredoc guard below lived in testCommands.ts, was
+ * used only by the test-command matcher, and the file-mutation checker never
+ * saw it — so the same class of false accusation was fixed in one reader and
+ * left standing in the other. Anything that reasons about what a shell
+ * command DID, rather than what it says, belongs here.
+ */
+/**
+ * Removes heredoc bodies from a shell command.
+ *
+ * A command that WRITES a test command is not a command that RUNS one.
+ * Found 2026-09-14 on a real session: two false failures whose "last test
+ * run" was a shell variable assignment. The actual match came from a
+ * heredoc further down, writing a demo fixture whose body contains the
+ * string `npm test`. The literal was being generated, never executed — and
+ * the tool then read its own report output as the failing result.
+ *
+ * Handles both quoted and bare delimiters, and leaves everything after the
+ * closing delimiter intact, because a real test run often follows the
+ * heredoc that set the fixture up.
+ */
+export function withoutHeredocs(command) {
+    const lines = command.split("\n");
+    const out = [];
+    let closing = null;
+    for (const line of lines) {
+        if (closing !== null) {
+            if (line.trim() === closing)
+                closing = null;
+            continue;
+        }
+        const open = line.match(/<<-?\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))/);
+        if (open) {
+            closing = open[1] ?? open[2] ?? open[3];
+            out.push(line.slice(0, open.index));
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}

package/dist/checks/testCommands.d.ts

@@ -19,5 +19,24 @@ import type { TranscriptEvent } from "../types.js";
  * wrong.
  */
 export declare const TEST_COMMAND: RegExp;
+/**
+ * How many times a single shell command invokes a test suite.
+ *
+ * A command that runs the suite twice has no single outcome to attribute.
+ * Real case, 2026-09-14: one command ran a typecheck, then the suite (37
+ * passed), then re-ran one file with locking deliberately disabled to
+ * demonstrate those tests can fail. The session said "Everything passes:",
+ * which was true; the checker read "2 failed" out of the third section and
+ * called it a lie.
+ *
+ * Deliberate red runs cannot be recognised - "is this failure intended" is
+ * not in the text. What IS in the text is that the suite ran more than
+ * once, and that is enough: the outcome is unattributable for the same
+ * reason a pipe makes an exit code unattributable. Heredoc bodies are
+ * stripped first, so a command that merely writes a test command twice
+ * still counts zero.
+ */
+export declare function countTestRuns(command: string): number;
 /** The first test command run in this session, or null if none ran. */
 export declare function findTestRun(events: TranscriptEvent[]): string | null;
+export { withoutHeredocs } from "./shellCommand.js";

package/dist/checks/testCommands.js

@@ -1,3 +1,4 @@
+import { withoutHeredocs } from "./shellCommand.js";
 /**
  * Commands that run a project's test suite.
  *
@@ -18,6 +19,27 @@
  * wrong.
  */
 export const TEST_COMMAND = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|verify|check|ci)\b|\bnpx\s+(?:vitest|jest|mocha|ava)\b|\b(?:vitest|jest|mocha|pytest|phpunit|rspec|tox)\b|\bcargo\s+test\b|\bgo\s+test\b|\bmvn\s+(?:test|verify)\b|\bgradle\s+test\b|\bdotnet\s+test\b|\bpython\s+-m\s+(?:pytest|unittest)\b/i;
+/**
+ * How many times a single shell command invokes a test suite.
+ *
+ * A command that runs the suite twice has no single outcome to attribute.
+ * Real case, 2026-09-14: one command ran a typecheck, then the suite (37
+ * passed), then re-ran one file with locking deliberately disabled to
+ * demonstrate those tests can fail. The session said "Everything passes:",
+ * which was true; the checker read "2 failed" out of the third section and
+ * called it a lie.
+ *
+ * Deliberate red runs cannot be recognised - "is this failure intended" is
+ * not in the text. What IS in the text is that the suite ran more than
+ * once, and that is enough: the outcome is unattributable for the same
+ * reason a pipe makes an exit code unattributable. Heredoc bodies are
+ * stripped first, so a command that merely writes a test command twice
+ * still counts zero.
+ */
+export function countTestRuns(command) {
+    const global = new RegExp(TEST_COMMAND.source, "gi");
+    return (withoutHeredocs(command).match(global) ?? []).length;
+}
 /** The first test command run in this session, or null if none ran. */
 export function findTestRun(events) {
     for (const event of events) {
@@ -25,8 +47,9 @@ export function findTestRun(events) {
             continue;
         const input = event.input;
         const command = input && typeof input.command === "string" ? input.command : "";
-        if (command && TEST_COMMAND.test(command))
+        if (command && TEST_COMMAND.test(withoutHeredocs(command)))
             return command;
     }
     return null;
 }
+export { withoutHeredocs } from "./shellCommand.js";

package/dist/cli.js

@@ -16,6 +16,7 @@ import { runGitBranchPolicyChecks } from "./checks/gitBranchPolicy.js";
 import { runCodeContentChecks } from "./checks/codeContent.js";
 import { runFileLifecycleChecks } from "./checks/fileLifecycle.js";
 import { runClaimEvidenceChecks } from "./checks/claimEvidence.js";
+import { runHook } from "./hook.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { generateReport, generateMarkdownReport } from "./report/generateReport.js";
 import { generateHtmlReport } from "./report/generateHtmlReport.js";
@@ -573,6 +574,12 @@ function runDoctorCommand() {
         console.log(`${result.newSinceLastRun.length} of these are new since the last time doctor ran here.`);
     }
 }
+program
+    .command("hook")
+    .description("run as a Claude Code Stop hook - blocks Claude from finishing on a broken rule (payload on stdin)")
+    .action(async () => {
+    await runHook(needsLlmResult);
+});
 program
     .command("doctor")
     .description("List every Claude Code hook and VS Code auto-task on this machine/project, flag anything suspicious")

package/dist/evaluate.d.ts

@@ -0,0 +1,22 @@
+import { type Classification } from "./checks/classify.js";
+import { staleOverrides } from "./overrides.js";
+import type { CheckResult, Rule, TranscriptEvent } from "./types.js";
+export interface Evaluation {
+    results: CheckResult[];
+    notARule: Classification[];
+    stale: ReturnType<typeof staleOverrides>;
+}
+/**
+ * Rules in, verdicts out — the whole pipeline, with no printing in it.
+ *
+ * Extracted 2026-09-14 when a second caller appeared. `check` renders a
+ * report for a person; `hook` returns a decision to Claude Code. Those two
+ * must never be able to disagree about whether a rule was broken, and the
+ * only way to guarantee that is one body of code. The same reasoning is
+ * written at the top of testCommands.ts, about two checkers sharing one
+ * definition; this is that argument one level up.
+ *
+ * Deliberately takes `events` rather than a path: the caller decides where
+ * 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>;

package/dist/evaluate.js

@@ -0,0 +1,51 @@
+import { classifyRules } from "./checks/classify.js";
+import { runDeterministicChecks } from "./checks/deterministicChecks.js";
+import { runIfEditThenTestChecks } from "./checks/ifEditThenTest.js";
+import { runGitBranchPolicyChecks } from "./checks/gitBranchPolicy.js";
+import { runCodeContentChecks } from "./checks/codeContent.js";
+import { runFileLifecycleChecks } from "./checks/fileLifecycle.js";
+import { runClaimEvidenceChecks } from "./checks/claimEvidence.js";
+import { runJudgmentChecks } from "./checks/judgmentChecks.js";
+import { loadOverrides, ruleFingerprint, staleOverrides } from "./overrides.js";
+/**
+ * Rules in, verdicts out — the whole pipeline, with no printing in it.
+ *
+ * Extracted 2026-09-14 when a second caller appeared. `check` renders a
+ * report for a person; `hook` returns a decision to Claude Code. Those two
+ * must never be able to disagree about whether a rule was broken, and the
+ * only way to guarantee that is one body of code. The same reasoning is
+ * written at the top of testCommands.ts, about two checkers sharing one
+ * definition; this is that argument one level up.
+ *
+ * Deliberately takes `events` rather than a path: the caller decides where
+ * a transcript comes from, and a hook is handed one it must not second-guess.
+ */
+export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
+    const overrides = loadOverrides(cwd);
+    const classifications = classifyRules(rules).map((c) => {
+        const decision = overrides.get(ruleFingerprint(c.rule))?.decision;
+        if (!decision)
+            return c;
+        if (decision === "notARule")
+            return { kind: "notARule", rule: c.rule };
+        return c.kind === "notARule" ? { kind: "judgment", rule: c.rule } : c;
+    });
+    const of = (kind) => classifications.filter((c) => c.kind === kind);
+    const deterministicResults = [
+        ...runDeterministicChecks(of("deterministic"), events),
+        ...runIfEditThenTestChecks(of("ifEditThenTest"), events),
+        ...runGitBranchPolicyChecks(of("gitBranchPolicy"), events),
+        ...runCodeContentChecks(of("codeContent"), events),
+        ...runFileLifecycleChecks(of("fileLifecycle"), events),
+        ...runClaimEvidenceChecks(of("claimEvidence"), events),
+    ];
+    const judgment = of("judgment");
+    const judgmentResults = llm
+        ? await runJudgmentChecks(judgment, events)
+        : judgment.map(({ rule }) => needsLlmResult(rule));
+    return {
+        results: [...deterministicResults, ...judgmentResults],
+        notARule: of("notARule"),
+        stale: staleOverrides(overrides, rules),
+    };
+}

package/dist/hook.d.ts

@@ -0,0 +1,35 @@
+import type { CheckResult, Rule } from "./types.js";
+/**
+ * A Stop hook that refuses to let a session end on a broken rule.
+ *
+ * The gap this closes was named by a reader of anthropics/claude-code#90542
+ * on 2026-09-14, from a lab that measured it: a receiving agent auto-ACKed
+ * 107 dispatched orders and did none of them, and 69 of 664 records marked
+ * complete were plans rather than completions. Their conclusion — "rules
+ * that live only in context are advisory by construction; rules that live
+ * in a gate are not" — applies to this tool as it stood, which read the
+ * transcript afterwards and told you what had already happened.
+ *
+ * Three safety properties, in the order they matter:
+ *
+ * 1. FAIL only. Never UNCLEAR, never NOT_RUN, never a judgment rule, and
+ *    never the LLM path — a model opinion is an opinion, and blocking on
+ *    one would let a wrong guess hold a session hostage. This gate fires
+ *    only on the deterministic checkers, where the finding is a matched
+ *    literal and can be read back.
+ *
+ * 2. It cannot loop. Claude Code sets `stop_hook_active` when the session
+ *    is already continuing because of a previous block. Blocking again
+ *    there is how a Stop hook wedges a session permanently, so this returns
+ *    immediately in that case: it gets exactly one interruption per stop.
+ *
+ * 3. It fails OPEN. Any error — unreadable transcript, no rules file,
+ *    malformed payload — allows the stop and writes a line to stderr.
+ *    Failing closed is the right default for money-touching code; here it
+ *    would mean a bug in this tool leaves someone unable to end a session
+ *    in their own editor, and they would rip the hook out that day. The
+ *    cost of the two failures is not symmetric, so the default is not
+ *    symmetric either. It is a deliberate weakening, and it is the reason
+ *    `check` in CI stays the backstop rather than this.
+ */
+export declare function runHook(needsLlmResult: (rule: Rule) => CheckResult): Promise<void>;

package/dist/hook.js

@@ -0,0 +1,100 @@
+import { loadRules } from "./rules.js";
+import { readTranscriptFromFile } from "./parsers/transcriptParser.js";
+import { evaluateSession } from "./evaluate.js";
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        if (process.stdin.isTTY)
+            return resolve("");
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => (data += c));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(""));
+    });
+}
+/**
+ * What Claude is told when it tries to finish on a broken rule.
+ *
+ * Addressed to the model, not to the person: it is the model that has to
+ * act on this, and a message written for a human reader ("see the report
+ * above") gives it nothing to do. Names the rule, states what was found,
+ * and stops — no instruction to "fix it", because the rule already said
+ * what to do and repeating it invites the model to argue with the wording
+ * instead of going and running the thing.
+ */
+function blockReason(failures) {
+    const lines = failures.map((f) => `  • Rule ${f.ruleId} — ${f.ruleTitle}\n    ${f.evidence}`);
+    const n = failures.length;
+    return (`RuleReceipt: ${n} rule${n === 1 ? "" : "s"} in CLAUDE.md ${n === 1 ? "was" : "were"} not followed in this session.\n\n` +
+        lines.join("\n\n") +
+        `\n\nDo not report this work as finished until the above is resolved or you have said plainly, to the user, that it is still open and why.`);
+}
+/**
+ * A Stop hook that refuses to let a session end on a broken rule.
+ *
+ * The gap this closes was named by a reader of anthropics/claude-code#90542
+ * on 2026-09-14, from a lab that measured it: a receiving agent auto-ACKed
+ * 107 dispatched orders and did none of them, and 69 of 664 records marked
+ * complete were plans rather than completions. Their conclusion — "rules
+ * that live only in context are advisory by construction; rules that live
+ * in a gate are not" — applies to this tool as it stood, which read the
+ * transcript afterwards and told you what had already happened.
+ *
+ * Three safety properties, in the order they matter:
+ *
+ * 1. FAIL only. Never UNCLEAR, never NOT_RUN, never a judgment rule, and
+ *    never the LLM path — a model opinion is an opinion, and blocking on
+ *    one would let a wrong guess hold a session hostage. This gate fires
+ *    only on the deterministic checkers, where the finding is a matched
+ *    literal and can be read back.
+ *
+ * 2. It cannot loop. Claude Code sets `stop_hook_active` when the session
+ *    is already continuing because of a previous block. Blocking again
+ *    there is how a Stop hook wedges a session permanently, so this returns
+ *    immediately in that case: it gets exactly one interruption per stop.
+ *
+ * 3. It fails OPEN. Any error — unreadable transcript, no rules file,
+ *    malformed payload — allows the stop and writes a line to stderr.
+ *    Failing closed is the right default for money-touching code; here it
+ *    would mean a bug in this tool leaves someone unable to end a session
+ *    in their own editor, and they would rip the hook out that day. The
+ *    cost of the two failures is not symmetric, so the default is not
+ *    symmetric either. It is a deliberate weakening, and it is the reason
+ *    `check` in CI stays the backstop rather than this.
+ */
+export async function runHook(needsLlmResult) {
+    const emit = (out) => {
+        process.stdout.write(JSON.stringify(out));
+    };
+    try {
+        const raw = await readStdin();
+        const input = raw ? JSON.parse(raw) : {};
+        // Property 2: one interruption per stop.
+        if (input.stop_hook_active)
+            return void emit({});
+        const cwd = input.cwd || process.cwd();
+        if (!input.transcript_path)
+            return void emit({});
+        const rules = loadRules(cwd);
+        if (rules.length === 0)
+            return void emit({});
+        const events = readTranscriptFromFile(input.transcript_path);
+        // An empty transcript produces no failures, which would read as a pass.
+        // Nothing to gate on, so allow — and say nothing, because a hook that
+        // warns on every empty read is a hook people mute.
+        if (events.length === 0)
+            return void emit({});
+        // Property 1: deterministic only. `llm: false` is not a default here,
+        // it is part of the contract.
+        const { results } = await evaluateSession(cwd, rules, events, false, needsLlmResult);
+        const failures = results.filter((r) => r.status === "FAIL" && r.outcome !== "not_run");
+        if (failures.length === 0)
+            return void emit({});
+        return void emit({ decision: "block", reason: blockReason(failures) });
+    }
+    catch (err) {
+        // Property 3: fail open, but never silently.
+        process.stderr.write(`rulereceipt hook: allowing stop, check did not complete (${err instanceof Error ? err.message : String(err)})\n`);
+        return void emit({});
+    }
+}

package/dist/report/generateReport.js

@@ -154,10 +154,27 @@ const BUCKET_ORDER = [
 function sharedEvidence(rs) {
     if (rs.length < 2)
         return null;
-    const first = rs[0].evidence;
-    if (!first)
-        return null;
-    return rs.every((r) => r.evidence === first) ? first : null;
+    // The MAJORITY text, not a unanimous one. Requiring every entry to match
+    // meant a single rule with its own message reinstated the wall for all the
+    // others — shipped in 0.1.35 and visible at once: fourteen judgment rules,
+    // twelve repeating the same 300-character paragraph, because two carried
+    // claim-evidence text. Whether it happened depended on what was in the
+    // transcript that minute, so it passed locally and broke for the reader.
+    const counts = new Map();
+    for (const r of rs) {
+        if (!r.evidence)
+            continue;
+        counts.set(r.evidence, (counts.get(r.evidence) ?? 0) + 1);
+    }
+    let best = null;
+    let bestN = 1;
+    for (const [text, n] of counts) {
+        if (n > bestN) {
+            best = text;
+            bestN = n;
+        }
+    }
+    return best;
 }
 export function generateReport(results, meta) {
     const clean = results.map(sanitize);
@@ -177,8 +194,15 @@ export function generateReport(results, meta) {
         if (shared) {
             lines.push(`  ${shared}`);
             lines.push("");
-            for (const r of inBucket)
+            for (const r of inBucket) {
                 lines.push(`  ${ruleLabel(r, clean)}`);
+                // 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)
+                    lines.push(`    ${r.evidence}`);
+                if (r.ceiling)
+                    lines.push(`    this means: ${r.ceiling}`);
+            }
             continue;
         }
         for (const r of inBucket) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",