rulereceipt 0.1.42 → 0.1.44

package/README.md

@@ -101,6 +101,22 @@ 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.
 
+### Claims of having read something
+
+A session that writes `PAGES READ: 1-20`, `STATUS: READ IN FULL` or "confirmed
+at source" while never opening a file is asserting provenance it does not
+have. Reported by a user in anthropics/claude-code#92505, where those headers
+went into tracked files and commit messages for material the model had never
+read.
+
+The check is narrow on purpose. It fires only when **nothing at all** was read
+in the session — no `Read`, no `Grep`, no `cat`. That much a transcript can
+prove, and it contradicts any claim of reading. It cannot tell you *which*
+document was read when reads did happen, so a session that read the wrong
+thing is still beyond it, and the report says so rather than guessing.
+
+"I will read the filing next" is a plan, not a claim, and does not fire.
+
 ## Blocking, not just reporting
 
 `rulereceipt check` tells you afterwards. `rulereceipt hook` refuses to let the

package/dist/checks/claimEvidence.js

@@ -86,7 +86,46 @@ const ACTION_CLAIMS = [
         exclude: /\bcommitted\s+to\b/i,
         command: /\bgit\s+commit\b/i,
     },
+    {
+        /**
+         * A claim to have READ a source, when nothing was read at all.
+         *
+         * From anthropics/claude-code#92505: "PAGES READ: 1-20", "STATUS: READ
+         * IN FULL", "confirmed at source" — emitted for material never opened,
+         * then written into tracked files and commit messages. The reporter's
+         * framing is the one that matters: the apparatus that certifies work was
+         * produced decoupled from the work, and a plainly-worded guess would
+         * have been safer, because a guess reads as a guess.
+         *
+         * Two claim shapes, because a provenance header has no "I" in it. The
+         * first-person form is gated like the others; the header form is matched
+         * literally, since "PAGES READ:" and "READ IN FULL" do not occur by
+         * accident.
+         *
+         * exclude carries the future tense. "I will read the filing next" is a
+         * plan, and a plan is not a claim.
+         *
+         * Ceiling: this fires only when NOTHING was read. The transcript can
+         * show that, and it contradicts any claim of reading. It cannot show
+         * WHICH document was read when reads did happen, so a session that read
+         * something else entirely is still beyond it.
+         */
+        label: "read of a source",
+        claim: /\b(?:i|we)(?:'ve|’ve| have| had)?\s+(?:\w+ly\s+|just\s+|already\s+|then\s+|also\s+|now\s+)*read\b|^\s*(?:pages?\s+read|status)\s*:\s*(?:[\d\s,-]+|read\s+in\s+full)|\bread\s+in\s+full\b|\bconfirmed\s+at\s+source\b/im,
+        exclude: /\b(?:will|going\s+to|need\s+to|should|next|plan\s+to|about\s+to|let\s+me|i'?ll|we'?ll)\s+(?:\w+\s+){0,3}read\b/i,
+        command: /\b(?:cat|head|tail|less|more|bat|nl|strings|pdftotext|xxd|od)\b/i,
+    },
 ];
+/**
+ * Tools that read a file, as distinct from shell commands that do.
+ *
+ * ACTION_CLAIMS matches Bash command text, which is the whole surface for
+ * push and commit. Reading is not: most reads go through Read, Grep, Glob
+ * or WebFetch and never touch a shell. Without these, a session that read
+ * twenty files through the proper tool would be reported as having read
+ * nothing.
+ */
+const READING_TOOLS = new Set(["Read", "Grep", "Glob", "NotebookRead", "WebFetch", "Fetch"]);
 /**
  * Removes what a message SHOWS, leaving what it SAYS.
  *
@@ -202,6 +241,11 @@ export function runClaimEvidenceChecks(classifications, events) {
     let unreadable = null;
     let backed = null;
     for (const event of events) {
+        // A read through Read/Grep/Glob never reaches the shell, so it has to be
+        // recorded here rather than by matching command text.
+        if (event.kind === "tool_use" && READING_TOOLS.has(event.toolName ?? "")) {
+            commandsSeen.add("read of a source");
+        }
         const command = commandOf(event);
         if (command !== null) {
             const id = event.kind === "tool_use" ? (event.toolUseId ?? null) : null;

package/dist/cli.js

@@ -21,6 +21,7 @@ import { runHook } from "./hook.js";
 import { runGuard } from "./guard.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { generateReport, generateMarkdownReport } from "./report/generateReport.js";
+import { gateOffer, hookIsInstalled } from "./report/gateOffer.js";
 import { generateHtmlReport } from "./report/generateHtmlReport.js";
 import { verifySessionHash } from "./verifyHash.js";
 import { saveEmailConfig, loadEmailConfig, detectSmtpHost, isValidEmail } from "./emailConfig.js";
@@ -259,6 +260,16 @@ async function runCheck(opts) {
     const meta = { sessionFilePath, ruleCount: results.length };
     const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta);
     console.log(reportText);
+    // Shown only to someone who has just read their own broken rules, and only
+    // if they have not already wired it up. See report/gateOffer.ts.
+    if (!markdown) {
+        const offer = gateOffer({
+            failures: results.filter((r) => r.status === "FAIL").length,
+            hookInstalled: hookIsInstalled(cwd),
+        });
+        if (offer)
+            console.log(`\n${offer}`);
+    }
     // Written before --share/--email so that a failure to send something
     // never costs the user the local artifact they explicitly asked for.
     if (html !== false) {

package/dist/report/gateOffer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Is a RuleReceipt hook already wired into this project or this machine?
+ *
+ * Read-only, and deliberately forgiving: an unreadable or malformed settings
+ * file means "assume not installed" rather than an error. A missing settings
+ * file is the normal case, not a problem.
+ */
+export declare function hookIsInstalled(cwd: string): boolean;
+/**
+ * The line offering enforcement, or null when it should not be shown.
+ *
+ * The site describes the Stop hook to someone deciding whether to adopt the
+ * tool at all. This speaks to someone who has already run it and is looking
+ * at rules that were broken — which is the moment the offer is a consequence
+ * of what they just read rather than an advertisement.
+ *
+ * Three conditions, and each is a way of not nagging:
+ *
+ *   - Only when something actually failed. On a clean report there is
+ *     nothing to enforce and the line would be a pitch.
+ *   - Never when the hook is already installed. Telling someone to do what
+ *     they have already done is how a tool gets muted.
+ *   - One line, no config block. A terminal report is not documentation, and
+ *     pasting JSON into it would bury the findings it sits under.
+ */
+export declare function gateOffer(state: {
+    failures: number;
+    hookInstalled: boolean;
+}): string | null;

package/dist/report/gateOffer.js

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Is a RuleReceipt hook already wired into this project or this machine?
+ *
+ * Read-only, and deliberately forgiving: an unreadable or malformed settings
+ * file means "assume not installed" rather than an error. A missing settings
+ * file is the normal case, not a problem.
+ */
+export function hookIsInstalled(cwd) {
+    const candidates = [
+        join(cwd, ".claude", "settings.json"),
+        join(cwd, ".claude", "settings.local.json"),
+        join(homedir(), ".claude", "settings.json"),
+    ];
+    for (const path of candidates) {
+        if (!existsSync(path))
+            continue;
+        try {
+            // Matched as text rather than by walking the hook schema: the shape of
+            // that config has changed before, and a rename of one field should not
+            // make this start nagging someone who already installed it.
+            if (/rulereceipt\s+(hook|guard)/.test(readFileSync(path, "utf-8")))
+                return true;
+        }
+        catch {
+            // unreadable settings file — treat as not installed
+        }
+    }
+    return false;
+}
+/**
+ * The line offering enforcement, or null when it should not be shown.
+ *
+ * The site describes the Stop hook to someone deciding whether to adopt the
+ * tool at all. This speaks to someone who has already run it and is looking
+ * at rules that were broken — which is the moment the offer is a consequence
+ * of what they just read rather than an advertisement.
+ *
+ * Three conditions, and each is a way of not nagging:
+ *
+ *   - Only when something actually failed. On a clean report there is
+ *     nothing to enforce and the line would be a pitch.
+ *   - Never when the hook is already installed. Telling someone to do what
+ *     they have already done is how a tool gets muted.
+ *   - One line, no config block. A terminal report is not documentation, and
+ *     pasting JSON into it would bury the findings it sits under.
+ */
+export function gateOffer(state) {
+    if (state.failures === 0)
+        return null;
+    if (state.hookInstalled)
+        return null;
+    const n = state.failures;
+    return (`This report is after the fact. \`rulereceipt hook\` runs as a Claude Code Stop hook and\n` +
+        `refuses to let a session end on ${n === 1 ? "a broken rule" : "a broken rule"} — see the README for the four lines to add.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",
@@ -46,9 +46,9 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.32.0",
-    "commander": "^15.0.0",
-    "nodemailer": "^9.1.1"
+    "@anthropic-ai/sdk": "~0.126.0",
+    "commander": "~15.0.0",
+    "nodemailer": "~10.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",