rulereceipt 0.1.70 → 0.1.72

package/dist/card.js

@@ -14,13 +14,16 @@ const SITE = "rulereceipt.dev";
 export function shareText(d, showRules = false) {
     // 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.
+    // Never claim "now it can't" — that is only true if `protect` is installed,
+    // and even then a determined command can slip a guard (found by a real test,
+    // 2026-09-29). The card states the FACT it can prove: what the session did.
     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.`
+            ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in this session — with the receipt to prove it.`
             : `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.`
+            ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in ${d.days} days (${d.sessions} sessions) — with the receipt to prove it.`
             : `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) {

package/dist/checks/approvalGate.js

@@ -1,5 +1,5 @@
 import { violation } from "../types.js";
-import { withoutHeredocs, withoutQuotedMentions } from "./shellCommand.js";
+import { withoutHeredocs, withoutQuotedMentions, unwrapShellWrappers } from "./shellCommand.js";
 const IN_COMMAND = {
     push: /\bgit\s+(?:\S+\s+){0,4}?push(?![\w-])/,
     commit: /\bgit\s+(?:\S+\s+){0,4}?commit(?![\w-])/,
@@ -32,7 +32,9 @@ function commandOf(e) {
     // 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)) : "";
+    // Unwrap `sh -c '…'` BEFORE blanking quotes, so a push hidden in a wrapper is
+    // exposed as a real command rather than blanked as a quoted mention (#2).
+    return typeof c === "string" ? withoutQuotedMentions(unwrapShellWrappers(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/ifEditThenTest.js

@@ -97,12 +97,20 @@ export function runIfEditThenTestChecks(classifications, events) {
             };
         }
         if (testPaths.length === 0) {
+            // Shadow, 2026-09-29: "every change needs a test" is a REQUIRE rule, and
+            // an edit with no test touched or run is not PROOF the rule was broken —
+            // the test may not have been needed, or may have run in another terminal.
+            // The product's guarantee is that "Broken" means a forbidden action
+            // actually happened, or a claim was contradicted by the session; this is
+            // neither, so it reports "can't tell", never a fabricated FAIL. Promote to
+            // Broken only after 30+ real cases are hand-checked at 0 wrong.
             return {
                 ruleId: rule.id,
                 ruleTitle: rule.title,
                 ruleSource: rule.source,
-                status: "FAIL",
-                evidence: `edited ${prodPaths.slice(0, 3).join(", ")}${prodPaths.length > 3 ? ", ..." : ""} but no matching test file was touched`,
+                status: "UNCLEAR",
+                method: "edit_test_pairing",
+                evidence: `edited ${prodPaths.slice(0, 3).join(", ")}${prodPaths.length > 3 ? ", ..." : ""}, and no test file was touched or run this session — can't tell whether this change needed a test`,
             };
         }
         return {

package/dist/checks/judgmentChecks.js

@@ -261,7 +261,24 @@ export async function runJudgmentChecks(classifications, events) {
                     : "the situation this rule governs never arose in this session",
             };
         }
-        if (status === "PASS" || status === "FAIL" || status === "UNCLEAR") {
+        if (status === "FAIL") {
+            // An AI opinion is NEVER a verdict — the product's guarantee is that
+            // "Broken" comes only from a forbidden action that happened or a claim
+            // contradicted by the session, never a model's guess. A model "FAIL" is
+            // surfaced as a clearly-labelled opinion needing a human, so it can never
+            // be counted as Broken in the report, history, card, digest or badge.
+            const evidence = (parsed.evidence ?? "").trim();
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "UNCLEAR",
+                needsHuman: true,
+                method: "model_judgment",
+                evidence: `AI opinion (not a verdict — a human should decide): this looks broken. ${evidence}${transcript.truncated ? ` ${TRUNCATION_NOTE}` : ""}`.trim(),
+            };
+        }
+        if (status === "PASS" || status === "UNCLEAR") {
             const evidence = parsed.evidence ?? "";
             return {
                 ruleId: rule.id,

package/dist/checks/shellCommand.d.ts

@@ -31,6 +31,7 @@ export declare function withoutHeredocs(command: string): string;
  * runs (proposedAction, attribution).
  */
 export declare function segments(command: string): string[];
+export declare function unwrapShellWrappers(command: string): string;
 /** The executable a segment invokes, with env assignments and `sudo` skipped. */
 export declare function leadingCommand(segment: string): string;
 /**

package/dist/checks/shellCommand.js

@@ -78,11 +78,35 @@ function isHeredocOpener(before, afterDelim) {
  * runs (proposedAction, attribution).
  */
 export function segments(command) {
-    return withoutHeredocs(command)
+    return unwrapShellWrappers(withoutHeredocs(command))
         .split(/\n|&&|\|\||[;|]/)
         .map((s) => s.trim())
         .filter((s) => s.length > 0);
 }
+/**
+ * Hoists the script out of a shell wrapper — `sh -c '<script>'`, `bash -lc
+ * "<script>"`, `zsh -c ...`, `dash -c ...`, `eval '<script>'` — so the command
+ * it actually runs is seen by every checker instead of hiding in a quoted arg.
+ *
+ * Found by a real test 2026-09-29: `sh -c 'git push origin main'` slipped past
+ * the guard AND the report, because the push sat inside a quote that
+ * withoutQuotedMentions blanks. Unwrapping first exposes the inner command as
+ * its own segment. Only a shell/eval wrapper is unwrapped — `echo "git push"`
+ * is not a wrapper and stays a mention. Bounded loop handles one nested level;
+ * deeper nesting is rare and fails toward not-unwrapped (a miss, not a false
+ * accusation).
+ */
+const SHELL_WRAPPER = /\b(?:sh|bash|zsh|dash|eval)\b(?:\s+-[A-Za-z]+)*\s+(['"])([\s\S]*?)\1/;
+export function unwrapShellWrappers(command) {
+    let out = command;
+    for (let i = 0; i < 4; i++) {
+        const m = out.match(SHELL_WRAPPER);
+        if (!m || m.index === undefined)
+            break;
+        out = out.slice(0, m.index) + ` ; ${m[2]} ; ` + out.slice(m.index + m[0].length);
+    }
+    return out;
+}
 /** The executable a segment invokes, with env assignments and `sudo` skipped. */
 export function leadingCommand(segment) {
     const words = segment.split(/\s+/).filter(Boolean);

package/dist/cli.js

@@ -20,7 +20,7 @@ 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 { planProtect, applyProtect, undoProtect, PROTECT_HOOK_SNIPPET } from "./protect.js";
 import { cardSvg, renderCardShare } from "./card.js";
 import { createInterface } from "node:readline";
 import { loadOverrides, saveOverride, clearOverride, staleOverrides, ruleFingerprint, OVERRIDES_PATH } from "./overrides.js";
@@ -76,10 +76,20 @@ async function shareResults(results) {
         console.log("\n(--share failed to send, non-fatal, report above is unaffected)");
     }
 }
+// Sample output. A FAIL is only ever shown here for a STRUCTURED rule with a
+// quoted command — never a judgment rule — because that is the tool's actual
+// promise, and the demo is the first thing people run. (A judgment rule shown
+// Broken here was found by a real test 2026-09-29 and was exactly the kind of
+// over-claim this product exists to catch.)
 const DEMO_RESULTS = [
-    { ruleId: "7", ruleTitle: "Tests must be able to fail", ruleSource: "global", status: "PASS", evidence: "sabotage-and-revert shown before the green run" },
-    { ruleId: "4", ruleTitle: "Surface bad news first", ruleSource: "global", status: "FAIL", evidence: "reply led with passing tests, the one broken test was mentioned last" },
-    { ruleId: "11", ruleTitle: "Fails closed on error", ruleSource: "global", status: "UNCLEAR", evidence: "no error occurred this session, nothing to verify against" },
+    { ruleId: "1", ruleTitle: "Never push to `main`", ruleSource: "project", status: "FAIL", outcome: "fail", method: "git_events",
+        evidence: 'a git command actually targeted the "main" branch: git push origin main' },
+    { ruleId: "2", ruleTitle: "Evidence or it didn't happen", ruleSource: "global", status: "FAIL", outcome: "fail", method: "claim_vs_evidence",
+        evidence: 'the session stated "All tests pass ✅" but the last test run before it, `npm test`, reported "1 failed"' },
+    { ruleId: "3", ruleTitle: "Never edit `.env`", ruleSource: "project", status: "PASS", outcome: "pass", method: "file_events",
+        evidence: "no write, edit, or delete of `.env` this session" },
+    { ruleId: "4", ruleTitle: "Surface bad news first", ruleSource: "global", status: "UNCLEAR", needsHuman: true,
+        evidence: "" },
 ];
 async function emailResults(reportText) {
     const config = loadEmailConfig();
@@ -1114,6 +1124,14 @@ program
         return;
     }
     const plan = planProtect(cwd);
+    if (plan.parseError) {
+        console.log(`Your ${plan.settingsPath} is not valid JSON (a comment, a trailing comma, or a syntax error).`);
+        console.log("protect will NOT touch it — rewriting it could delete your own settings (deny rules, model, other hooks).");
+        console.log("\nFix the JSON, then re-run  rulereceipt protect  — or add these two hooks by hand:\n");
+        console.log(PROTECT_HOOK_SNIPPET.split("\n").map((l) => `    ${l}`).join("\n"));
+        process.exitCode = 1;
+        return;
+    }
     if (plan.alreadyProtected) {
         console.log(`Already protected — the RuleReceipt hooks are in ${plan.settingsPath}. Nothing to add.`);
         return;

package/dist/historyReport.js

@@ -103,7 +103,7 @@ export function renderHistory(s, projectName, now = Date.now()) {
         return out.join("\n");
     }
     if (s.breaks.length === 0) {
-        out.push("No rules were broken in these sessions. Nothing to flag.");
+        out.push("No proven breaks found in these sessions (a structured check with quoted evidence). Rules needing judgment are shown per-session, not counted here.");
     }
     else {
         const who = s.tools.length === 1 && s.tools[0] === "claude-code" ? "Claude" : "the agent";

package/dist/protect.d.ts

@@ -9,7 +9,17 @@ export interface ProtectPlan {
     toAdd: string[];
     /** True when both hooks are already present — nothing to do. */
     alreadyProtected: boolean;
+    /**
+     * True when the settings file exists but is not parseable JSON (a comment, a
+     * trailing comma, or genuinely broken). protect MUST NOT rewrite it — doing so
+     * would delete the user's own settings (deny rules, model, other hooks). The
+     * caller shows the hooks to add by hand and changes nothing. Found by a real
+     * test, 2026-09-29: a JSONC file lost its `permissions.deny` rule.
+     */
+    parseError: boolean;
 }
+/** The two hook lines to add by hand, for the parse-error path. */
+export declare const PROTECT_HOOK_SNIPPET = "\"hooks\": {\n  \"PreToolUse\": [{ \"hooks\": [{ \"type\": \"command\", \"command\": \"rulereceipt guard\" }] }],\n  \"Stop\": [{ \"hooks\": [{ \"type\": \"command\", \"command\": \"rulereceipt hook\" }] }]\n}";
 export declare function planProtect(cwd: string): ProtectPlan;
 export declare function applyProtect(cwd: string, plan: ProtectPlan): void;
 export interface UndoResult {

package/dist/protect.js

@@ -39,22 +39,29 @@ function atomicWrite(path, content) {
     writeFileSync(tmp, content);
     renameSync(tmp, path);
 }
+/** The two hook lines to add by hand, for the parse-error path. */
+export const PROTECT_HOOK_SNIPPET = `"hooks": {
+  "PreToolUse": [{ "hooks": [{ "type": "command", "command": "${GUARD_CMD}" }] }],
+  "Stop": [{ "hooks": [{ "type": "command", "command": "${HOOK_CMD}" }] }]
+}`;
 export function planProtect(cwd) {
     const settingsPath = settingsPathFor(cwd);
     const existed = existsSync(settingsPath);
     let original = null;
     let settings = {};
     if (existed) {
+        original = readFileSync(settingsPath, "utf-8");
         try {
-            original = readFileSync(settingsPath, "utf-8");
             const parsed = JSON.parse(original);
             if (parsed && typeof parsed === "object")
                 settings = parsed;
         }
         catch {
-            // Malformed JSON: we keep the ORIGINAL bytes (for a faithful undo) but
-            // build the new file from an empty object rather than guessing at a merge.
-            settings = {};
+            // Malformed/JSONC (comment, trailing comma, or broken): REFUSE. Rewriting
+            // it would silently delete the user's own settings — deny rules, model,
+            // other hooks. Return a plan that changes NOTHING and flags the parse
+            // error so the caller can tell the user and show the lines to add by hand.
+            return { settingsPath, existed, original, next: original, toAdd: [], alreadyProtected: false, parseError: true };
         }
     }
     const toAdd = [];
@@ -73,9 +80,14 @@ export function planProtect(cwd) {
         next: `${JSON.stringify(settings, null, 2)}\n`,
         toAdd,
         alreadyProtected: toAdd.length === 0,
+        parseError: false,
     };
 }
 export function applyProtect(cwd, plan) {
+    // Never write over a file we could not parse — that is the data-loss bug this
+    // guards against. The CLI stops before here, but this makes it impossible.
+    if (plan.parseError)
+        throw new Error("refusing to write: the settings file is not valid JSON");
     // Record exactly what to restore (the original bytes, or that there was no
     // file) BEFORE touching anything, so --undo is byte-for-byte.
     atomicWrite(backupPathFor(cwd), `${JSON.stringify({ settingsPath: plan.settingsPath, existed: plan.existed, original: plan.original }, null, 2)}\n`);

package/dist/report/gateOffer.js

@@ -52,7 +52,6 @@ export function gateOffer(state) {
         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.`);
+    return (`This report is after the fact. To refuse a session that ends on a broken rule, run\n` +
+        `\`rulereceipt protect\` — it adds the Stop hook and the guard for you (with a preview and undo).`);
 }

package/dist/selftest.js

@@ -78,7 +78,7 @@ export function renderSelfTest(r) {
         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.`);
+            `The same checkers ran here as on your real sessions. These are a sample of hand-checked cases across the checkers — a regression in any of them shows up here (it is not exhaustive proof).`);
     }
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.70",
+  "version": "0.1.72",
   "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",