rulereceipt 0.1.59 → 0.1.61

package/README.md

@@ -289,6 +289,23 @@ independently confirm it describes the session it claims to.
 Nothing is uploaded. The file is written to your working directory and
 goes wherever you choose to send it.
 
+## A verdict looks wrong?
+
+```bash
+npx rulereceipt wrong <rule-handle>
+```
+
+Builds a report of that rule, the verdict, how it was decided and the
+session lines around it, with obvious secrets, your home path and email
+addresses masked. It is saved to `.rulereceipt/wrong-<handle>.md` and
+printed so you can read and edit it, along with a link to a pre-filled
+GitHub issue that you open yourself. Nothing is sent. `check` prints the
+command after every report that has a decided verdict, and the HTML report
+has a "Verdict wrong?" link on each one that carries only the version and
+the verdict, never the rule or the evidence.
+
+Every accuracy fix in this project has come from a report like this.
+
 ## Exit codes
 
 `check` exits **1** when a rule was actually broken, and **0** otherwise,
@@ -379,6 +396,13 @@ npx tsx src/cli.ts demo
 
 ## Trust, privacy and licensing
 
+**What it can't see, it says so.** [KNOWN-GAPS.md](KNOWN-GAPS.md) lists
+exactly where the evidence runs out — commands in another terminal, clicks on
+the permission prompt, `rm`/delete not bound to a rule's subject, edited
+transcripts, IDE sessions without logs. When RuleReceipt hits one of those it
+reports "Can't tell", never a guess. Gaps we know about are safer than gaps we
+don't.
+
 **Nothing leaves your machine unless you ask.** Your code, rules, and
 session content never leave your computer, ever. Plain `rulereceipt check`
 makes zero network calls. `--llm`, `--share`, and `--telemetry` are all

package/dist/audit.d.ts

@@ -1,3 +1,4 @@
+import { type LoadGraphEntry } from "./rules.js";
 import type { Rule } from "./types.js";
 /**
  * A rules-only health score — how much of a rules file can actually be checked,
@@ -31,3 +32,31 @@ export interface RulesAudit {
 export declare function auditRules(rules: Rule[]): RulesAudit;
 /** A short, readable audit. Never says "compliant" — it measures the file, not a session. */
 export declare function renderAudit(a: RulesAudit, md?: boolean): string;
+/**
+ * A file-level problem the audit can name WITHOUT a session: things that stop a
+ * rules file from ever reaching the agent as a useful rule. Deliberately about
+ * load / shape / checkability only — never "the model ignored you," which this
+ * cannot know without a transcript.
+ */
+export interface Diagnostic {
+    id: "no-rules-file" | "empty-or-pointer" | "zero-rules" | "docs-heavy" | "shadowed-file" | "size-warn" | "template-text" | "broken-import";
+    severity: "info" | "warn";
+    message: string;
+}
+/** The full doorstep audit for a project: counts + load graph + diagnostics. */
+export interface ProjectAudit extends RulesAudit {
+    /** Every candidate rules file the walk saw, loaded or shadowed. */
+    loadGraph: LoadGraphEntry[];
+    /** File-level problems worth surfacing before any session. */
+    diagnostics: Diagnostic[];
+    /** How many rules came from Claude Code memory (not a file, so not in loadGraph). */
+    memoryRules: number;
+}
+/**
+ * The doorstep audit: what loaded, what's checkable, what to fix — no session.
+ * `check` proves what a real session did; this answers the day-one questions a
+ * cold `npx rulereceipt audit` should, before any transcript exists.
+ */
+export declare function auditProject(cwd: string): ProjectAudit;
+/** The doorstep render: load graph → summary → diagnostics → top fixes. */
+export declare function renderProjectAudit(pa: ProjectAudit, md?: boolean): string;

package/dist/audit.js

@@ -1,5 +1,8 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { classifyRules } from "./checks/classify.js";
 import { adviseRules } from "./checkability.js";
+import { describeRuleSources, loadRules } from "./rules.js";
 export function auditRules(rules) {
     let checkable = 0;
     let judgment = 0;
@@ -57,3 +60,203 @@ export function renderAudit(a, md = false) {
     out.push("Full advice, rule by rule:  rulereceipt rules --advise");
     return out.join("\n");
 }
+/**
+ * Claude Code reads a bounded prefix of a rules file; past it the rest is
+ * silently dropped, so a rule below the cut never loads. The figure is a
+ * conservative approximation (character count, not bytes, so non-English files
+ * aren't over-counted) and is WARN-only — never a FAIL. TODO: pin to the exact
+ * current documented limit before leaning on the number in marketing.
+ */
+const SIZE_WARN_CHARS = 40000;
+/** Placeholder text left in from a template — the rule was never actually written. */
+const TEMPLATE_TEXT = /\[your\s+[^\]]+\]|<your\s+[^>]+>|\[project[_ ]name\]|\[TODO\]|^\s*(?:TODO|FIXME)\s*:/im;
+/** Fenced and inline code, masked before scanning for imports/placeholders. */
+function stripCode(text) {
+    return text.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]*`/g, " ");
+}
+/**
+ * `@path` imports the agent follows. Conservative on purpose: only an `@` at a
+ * word start (so an email's `@` never counts), and only when the target looks
+ * like a file — has a rules-file extension, or starts with `./ ../ /`. That
+ * excludes npm scopes like `@types/node` (no extension, no `./`), which are the
+ * classic false positive. Resolved relative to the importing file.
+ */
+const IMPORT_LINE = /(?:^|[\s(])@((?:\.{0,2}\/)?[\w./-]+\.(?:md|markdown|mdc|txt)|(?:\.{1,2}\/|\/)[\w./-]+)/g;
+function brokenImports(filePath, text) {
+    const dir = dirname(filePath);
+    const broken = [];
+    for (const m of stripCode(text).matchAll(IMPORT_LINE)) {
+        const target = m[1];
+        const abs = isAbsolute(target) ? target : resolve(dir, target);
+        if (!existsSync(abs))
+            broken.push(target);
+    }
+    return broken;
+}
+/** Content that is a pointer to another file, not rules of its own ("see AGENTS.md"). */
+const POINTER = /^\s*(?:#[^\n]*\n)?\s*(?:see|refer\s+to|read|follow|use|check)\b[^\n]{0,80}?\.(?:md|markdown|txt|mdc)\b/i;
+function isPointerFile(path) {
+    try {
+        const text = readFileSync(path, "utf-8").trim();
+        return text.length > 0 && text.length < 220 && POINTER.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+function buildDiagnostics(cwd, graph, a) {
+    const diags = [];
+    const loaded = graph.filter((g) => g.status === "loaded");
+    const shadowed = graph.filter((g) => g.status === "shadowed");
+    const short = (p) => {
+        const r = relative(cwd, p);
+        return r && !r.startsWith("..") ? r : p;
+    };
+    // Nothing to check against at all.
+    if (loaded.length === 0 && a.total === 0) {
+        diags.push({
+            id: "no-rules-file",
+            severity: "warn",
+            message: "No rules file found. Add a CLAUDE.md or AGENTS.md at the repo root (or .cursor/rules, copilot-instructions.md, .windsurfrules, GEMINI.md) with the rules you want checked.",
+        });
+        return diags;
+    }
+    // A shadowed file is present but the agent ignores it — the single most
+    // confusing "why isn't my rule firing?" case, so it leads.
+    for (const s of shadowed) {
+        const ignored = s.ruleCount > 0 ? ` — ${s.ruleCount} rule${s.ruleCount === 1 ? "" : "s"} not applied` : "";
+        diags.push({
+            id: "shadowed-file",
+            severity: "warn",
+            message: `${short(s.path)} is present but not loaded (${s.note})${ignored}.`,
+        });
+    }
+    // Loaded files that carry no rules of their own: empty, or just a pointer to
+    // another file. A pointer parses to a rule or two ("See AGENTS.md"), so it is
+    // caught by content, not only by a zero count.
+    for (const l of loaded) {
+        if (l.ruleCount === 0) {
+            diags.push({ id: "empty-or-pointer", severity: "warn", message: `${short(l.path)} is loaded but has no rules in it yet.` });
+        }
+        else if (l.ruleCount <= 2 && isPointerFile(l.path)) {
+            diags.push({
+                id: "empty-or-pointer",
+                severity: "warn",
+                message: `${short(l.path)} only points to another file — put the actual rules where the agent will read them, or use an @import the agent follows.`,
+            });
+        }
+    }
+    // Files exist and load, but nothing parsed as a rule anywhere.
+    if (loaded.length > 0 && a.total === 0) {
+        diags.push({
+            id: "zero-rules",
+            severity: "warn",
+            message: "Rules files were loaded but none parsed into a rule. Use headings, numbered items, or `-` bullets so each rule stands on its own.",
+        });
+    }
+    // Content-level problems on each loaded file: silent truncation, leftover
+    // template text, and imports that resolve to nothing. Read once per file.
+    for (const l of loaded) {
+        let text = "";
+        try {
+            text = readFileSync(l.path, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (text.length > SIZE_WARN_CHARS) {
+            diags.push({
+                id: "size-warn",
+                severity: "warn",
+                message: `${short(l.path)} is ${text.length.toLocaleString()} characters — large rules files can be silently truncated, so rules near the end may never load. Split it or trim.`,
+            });
+        }
+        if (TEMPLATE_TEXT.test(text)) {
+            diags.push({
+                id: "template-text",
+                severity: "warn",
+                message: `${short(l.path)} still has template placeholder text (e.g. "[your project name]", "TODO:") — fill it in or remove it so it reads as a real rule.`,
+            });
+        }
+        const broken = brokenImports(l.path, text);
+        if (broken.length > 0) {
+            diags.push({
+                id: "broken-import",
+                severity: "warn",
+                message: `${short(l.path)} imports ${broken.slice(0, 3).map((b) => `@${b}`).join(", ")}${broken.length > 3 ? ` (+${broken.length - 3} more)` : ""} — the file doesn't exist, so nothing loads from it.`,
+            });
+        }
+    }
+    // A handbook, not a policy: mostly documentation, little to enforce.
+    if (a.total >= 8 && a.skipped / a.total > 0.7) {
+        diags.push({
+            id: "docs-heavy",
+            severity: "info",
+            message: `${a.skipped} of ${a.total} items are documentation, not rules. That's fine — but for the lines you want enforced, phrase them as Never/Always and put the command, file or branch in \`backticks\`.`,
+        });
+    }
+    return diags;
+}
+/**
+ * The doorstep audit: what loaded, what's checkable, what to fix — no session.
+ * `check` proves what a real session did; this answers the day-one questions a
+ * cold `npx rulereceipt audit` should, before any transcript exists.
+ */
+export function auditProject(cwd) {
+    const rules = loadRules(cwd);
+    const base = auditRules(rules);
+    const loadGraph = describeRuleSources(cwd);
+    const diagnostics = buildDiagnostics(cwd, loadGraph, base);
+    const memoryRules = rules.filter((r) => r.id.startsWith("memory:")).length;
+    return { ...base, loadGraph, diagnostics, memoryRules };
+}
+/** The doorstep render: load graph → summary → diagnostics → top fixes. */
+export function renderProjectAudit(pa, md = false) {
+    const H = (s) => (md ? `## ${s}` : s);
+    const out = [];
+    out.push(md ? "# RuleReceipt — rules audit" : "RuleReceipt · rules audit  (no session needed)");
+    out.push("");
+    const loaded = pa.loadGraph.filter((g) => g.status === "loaded");
+    const shadowed = pa.loadGraph.filter((g) => g.status === "shadowed");
+    out.push(H("Rules files found"));
+    if (pa.loadGraph.length === 0) {
+        out.push("  (none — no CLAUDE.md / AGENTS.md / Cursor / Copilot / Windsurf / Gemini rules on the path)");
+    }
+    else {
+        for (const g of loaded) {
+            out.push(`  loaded    ${g.format} · ${g.ruleCount} rule${g.ruleCount === 1 ? "" : "s"}  (${g.path})`);
+        }
+        for (const g of shadowed) {
+            out.push(`  ignored   ${g.format} · ${g.note}  (${g.path})`);
+        }
+        if (pa.memoryRules > 0)
+            out.push(`  loaded    Claude memory · ${pa.memoryRules} rule${pa.memoryRules === 1 ? "" : "s"}`);
+    }
+    out.push("");
+    if (pa.checkable + pa.judgment > 0) {
+        out.push(H("Can this session be checked against them?"));
+        out.push(`  ${String(pa.checkable).padStart(4)}  checkable        — verifiable from a session, no human needed`);
+        out.push(`  ${String(pa.judgment).padStart(4)}  need judgment    — a person (or \`--llm\`) decides these`);
+        out.push(`  ${String(pa.skipped).padStart(4)}  documentation    — structure/notes, not scored as rules`);
+        out.push("");
+        out.push(`${pa.percentCheckable}% of your rules can be checked mechanically.`);
+        out.push("");
+    }
+    if (pa.diagnostics.length > 0) {
+        out.push(H("What to fix in the setup"));
+        for (const d of pa.diagnostics)
+            out.push(`  ${d.severity === "warn" ? "!" : "·"} ${d.message}`);
+        out.push("");
+    }
+    if (pa.topFixes.length > 0) {
+        out.push(H("Top fixes to unlock more checks"));
+        for (const f of pa.topFixes) {
+            out.push(`  • ${f.title.replace(/\s+/g, " ").trim().slice(0, 60)}`);
+            out.push(`      ${f.suggestion}`);
+        }
+        out.push("");
+    }
+    out.push("Full advice, rule by rule:  rulereceipt rules --advise");
+    out.push("After you run your agent here:  rulereceipt check   (rule-by-rule proof from the session)");
+    return out.join("\n");
+}

package/dist/checks/approvalGate.d.ts

@@ -1,3 +1,44 @@
 import type { ApprovalGateClassification } from "./classify.js";
 import type { CheckResult, TranscriptEvent } from "../types.js";
-export declare function runApprovalGateChecks(classifications: ApprovalGateClassification[], events: TranscriptEvent[]): CheckResult[];
+/**
+ * "Never push / commit / open a PR / delete without asking me" — checked per
+ * action, not per session.
+ *
+ * Rewritten 2026-09-28. The first version looked only at the FIRST gated action
+ * and cleared the rule if any "shall I…?" appeared anywhere earlier. That
+ * passes exactly the case filed most often (anthropics/claude-code #86742,
+ * #58079, #67060): one approved push, then a second, unrelated push with no new
+ * consent. It also passed "asked, then pushed without waiting".
+ *
+ * For EACH gated action that actually went through, look at the window since
+ * the previous action of the same kind:
+ *   - the user asked for it, or said yes to an ask  -> approved
+ *   - the tool call was rejected in the prompt        -> not an action (skip)
+ *   - otherwise, could a permission prompt have shown?
+ *       yes (default / acceptEdits / plan, or mode unknown) -> UNCLEAR: the
+ *           "Yes" button leaves no trace in the transcript, so a FAIL here
+ *           could accuse someone who WAS asked and agreed
+ *       no  (bypassPermissions / dontAsk / auto, or the project's allow list
+ *           covers the command) -> FAIL: nobody was asked
+ *
+ * Asking is not approval. Claude can say "shall I push?" and push before any
+ * reply; the user has to actually say yes. This is the whole reason a bare
+ * "no ask found" cannot be a FAIL: the approval may have happened in the
+ * permission UI, which the transcript never records.
+ */
+type Action = "push" | "commit" | "pr" | "delete";
+/** `Bash(git push:*)`, `Bash(git:*)`, `Bash` style allow entries. */
+export declare function allowListed(command: string, allow: string[]): boolean;
+export interface ApprovalOptions {
+    /** `permissions.allow` entries from the project's and user's Claude Code settings. */
+    allow?: string[];
+}
+interface Occurrence {
+    action: Action;
+    command: string;
+    verdict: "approved" | "unclear" | "unapproved";
+    why: string;
+}
+export declare function approvalOccurrences(events: TranscriptEvent[], actions: Action[], opts?: ApprovalOptions): Occurrence[];
+export declare function runApprovalGateChecks(classifications: ApprovalGateClassification[], events: TranscriptEvent[], opts?: ApprovalOptions): CheckResult[];
+export {};

package/dist/checks/approvalGate.js

@@ -1,105 +1,149 @@
 import { violation } from "../types.js";
 import { withoutHeredocs } from "./shellCommand.js";
-/**
- * Did the assistant ASK before doing a thing a rule says needs approval?
- *
- * From anthropics/claude-code#95494 ("committed without permission", scope
- * rewritten and fake results presented) and #92505. A whole cluster of rules
- * reads "ask/repeat-back/wait for approval BEFORE you delete | push | commit".
- *
- * The honest, mechanical half is narrow and stated as such: the rule is
- * satisfied by ASKING, so this checks whether the assistant sought approval
- * in its recorded text before the action. It does NOT judge whether a reply
- * actually granted approval — the "it read my frustration as a yes" case
- * (#92505) is a judgment call and stays with the model, not this check.
- *
- * Bias is deliberately toward NOT accusing: any approval-seeking assistant
- * turn before the action clears the rule. A FAIL means the action ran and
- * nothing before it asked — the clean case, e.g. a bare `git commit` with no
- * "shall I / ok to / before I" anywhere ahead of it.
- */
-/** Command shapes for each gated action. Kept conservative to avoid accusing. */
-// `git\s+…\s+push/commit` allows config flags between the two (`git -c x=y
-// push`), which a literal `git push` missed — found by an evasion probe
-// 2026-09-22. Up to four intervening tokens; the verb must not be followed by
-// a word char so `commit-graph` / `push-option` are not matched.
-const ACTION_IN_COMMAND = {
+const IN_COMMAND = {
     push: /\bgit\s+(?:\S+\s+){0,4}?push(?![\w-])/,
     commit: /\bgit\s+(?:\S+\s+){0,4}?commit(?![\w-])/,
-    delete: /\brm\s+-?\w|\bgit\b[^\n]*\s-D\b|\bdrop\s+table\b|\bdelete\s+from\b|\btruncate\b/i,
+    pr: /\bgh\s+pr\s+(?:create|merge)\b/,
+    delete: /(?:^|[;&|]\s*|\s)rm\s+-?\w|\bgit\b[^\n]*\s-D\b|\bdrop\s+table\b|\bdelete\s+from\b|\btruncate\s+table\b/i,
 };
-/**
- * The assistant seeking sign-off. Read generously on purpose: a broad match
- * here means fewer false accusations, at the cost of occasionally missing a
- * real one — the safe direction for a tool whose whole point is not crying
- * wolf.
- */
-const APPROVAL_SEEK = /\b(?:shall i|should i|may i|can i|do you want|would you like|let me know|before i (?:proceed|do|run|delete|push|commit|go|continue)|your (?:approval|go[- ]?ahead|sign[- ]?off|confirmation)|please confirm|is (?:it|this) ok|ok(?:ay)? to|go ahead\?)\b/i;
-function commandOf(event) {
-    if (event.kind !== "tool_use" || event.toolName !== "Bash")
+const IN_USER_TEXT = {
+    push: /\bpush/i,
+    commit: /\bcommit/i,
+    pr: /\b(?:pr|pull\s+request)\b/i,
+    delete: /\b(?:delete|remove|rm|drop|clean\s*up|wipe|get\s+rid)\b/i,
+};
+/** "don't push yet", "no commits", "hold off on the PR": not a yes. */
+function negated(text, verb) {
+    const m = text.match(verb);
+    if (!m || m.index === undefined)
+        return false;
+    const before = text.slice(Math.max(0, m.index - 30), m.index);
+    return /\b(?:don'?t|do\s+not|no|never|not\s+yet|without|hold\s+off(?:\s+on)?|wait(?:\s+before)?|stop)\b[\s\w]{0,12}$/i.test(before);
+}
+const ASK = /\b(?:shall i|should i|may i|can i|do you want|would you like|want me to|ok(?:ay)? to|is (?:it|this) ok|please confirm|ready to (?:push|commit)|let me know (?:if|when|whether))\b/i;
+const YES = /^\s*(?:y|yes|yep|yeah|yup|sure|ok(?:ay)?|go(?:\s+ahead)?|do\s+it|please\s+do|proceed|lgtm|ship\s+it|sounds\s+good|approved|confirmed|go\s+for\s+it)\b/i;
+const NO_PROMPT_MODES = new Set(["bypassPermissions", "dontAsk", "auto"]);
+function commandOf(e) {
+    if (e.kind !== "tool_use" || e.toolName !== "Bash")
         return "";
-    const input = event.input;
-    const raw = input && typeof input.command === "string" ? input.command : "";
-    // A heredoc that WRITES "git push" into a file is not a push. Strip
-    // heredoc bodies so only the commands actually invoked are inspected.
-    return withoutHeredocs(raw);
+    const c = e.input?.command;
+    // A heredoc that WRITES "git push" into a file is not a push. Strip heredoc
+    // bodies so only the commands actually invoked are inspected.
+    return typeof c === "string" ? withoutHeredocs(c) : "";
 }
-/**
- * The first event index at which one of the gated actions runs, and the
- * command that ran it — or null if none did.
- */
-function firstAction(events, actions) {
-    const regexes = actions.map((a) => ACTION_IN_COMMAND[a]).filter(Boolean);
-    for (let i = 0; i < events.length; i++) {
-        const command = commandOf(events[i]);
-        if (!command)
+/** The result for the call at `i`: matched by id when present, else the next result. */
+function resultOf(events, i) {
+    const call = events[i];
+    const id = call.kind === "tool_use" ? call.toolUseId : undefined;
+    for (let j = i + 1; j < events.length; j++) {
+        const e = events[j];
+        if (e.kind !== "tool_result")
             continue;
-        if (regexes.some((re) => re.test(command)))
-            return { index: i, command };
+        if (!id || !e.toolUseId || e.toolUseId === id)
+            return e;
     }
-    return null;
+    return undefined;
 }
-/** Did any assistant text before `index` seek approval? */
-function askedBefore(events, index) {
-    for (let i = 0; i < index; i++) {
-        const e = events[i];
-        if (e.kind !== "text" || e.role !== "assistant")
-            continue;
-        if (APPROVAL_SEEK.test(e.text))
+/** `Bash(git push:*)`, `Bash(git:*)`, `Bash` style allow entries. */
+export function allowListed(command, allow) {
+    const c = command.trim();
+    return allow.some((entry) => {
+        const m = entry.match(/^Bash(?:\((.*)\))?$/);
+        if (!m)
+            return false;
+        if (m[1] === undefined || m[1] === "*" || m[1] === ":*")
             return true;
+        const pat = m[1].replace(/:\*$/, "").replace(/\s*\*$/, "");
+        return c === pat || c.startsWith(pat + " ") || (m[1].endsWith("*") && c.startsWith(pat));
+    });
+}
+export function approvalOccurrences(events, actions, opts = {}) {
+    const out = [];
+    const lastIndex = {};
+    for (let i = 0; i < events.length; i++) {
+        const command = commandOf(events[i]);
+        if (!command)
+            continue;
+        for (const action of actions) {
+            if (!IN_COMMAND[action].test(command))
+                continue;
+            const res = resultOf(events, i);
+            if (res && res.kind === "tool_result" && res.isError)
+                continue; // rejected in the prompt, or it never went through
+            const from = (lastIndex[action] ?? -1) + 1;
+            lastIndex[action] = i;
+            const window = events.slice(from, i);
+            let approved = false;
+            let asked = false;
+            for (const e of window) {
+                if (e.kind !== "text")
+                    continue;
+                if (e.role === "assistant" && ASK.test(e.text))
+                    asked = true;
+                if (e.role !== "user")
+                    continue;
+                if (IN_USER_TEXT[action].test(e.text) && !negated(e.text, IN_USER_TEXT[action]))
+                    approved = true;
+                else if (asked && YES.test(e.text))
+                    approved = true;
+            }
+            const short = command.replace(/\s+/g, " ").trim().slice(0, 80);
+            if (approved) {
+                out.push({ action, command: short, verdict: "approved", why: "the user asked for it or said yes since the last one" });
+                continue;
+            }
+            const call = events[i];
+            const mode = call.kind === "tool_use" ? call.permissionMode : undefined;
+            const listed = allowListed(command, opts.allow ?? []);
+            const noPrompt = (mode && NO_PROMPT_MODES.has(mode)) || listed;
+            if (action === "delete") {
+                // `rm` / `drop` / `delete` are far too common and generic to bind
+                // confidently to a specific rule's subject: a test-cleanup `rm -rf
+                // /tmp/x` is not "wiping the production database", but the command
+                // matcher can't tell them apart. So a delete gate NEVER produces a
+                // FAIL — it reports UNCLEAR, and the guard still asks before the call.
+                // Found 2026-09-28: a "Never wipe data storage databases" rule FAILed
+                // on an unrelated temp-dir `rm -rf` once the one-engine fix made
+                // approval-gate rules visible in `check`. push/commit/pr are specific
+                // git/gh operations and keep the FAIL path.
+                out.push({ action, command: short, verdict: "unclear", why: "a delete/rm command ran; a transcript can't tell whether it hit the data this rule protects, or whether it was approved" });
+            }
+            else if (noPrompt) {
+                out.push({ action, command: short, verdict: "unapproved", why: listed ? "the command is on the allow list, so no prompt was shown" : `permission mode was ${mode}, so no prompt was shown` });
+            }
+            else {
+                out.push({ action, command: short, verdict: "unclear", why: asked ? "Claude asked but ran it before any reply in the chat" : "nothing in the chat approved it" });
+            }
+        }
     }
-    return false;
+    return out;
 }
-export function runApprovalGateChecks(classifications, events) {
+export function runApprovalGateChecks(classifications, events, opts = {}) {
     return classifications.map(({ rule, actions, polarity }) => {
-        const action = firstAction(events, actions);
-        if (!action) {
-            return {
-                ruleId: rule.id,
-                ruleTitle: rule.title,
-                ruleSource: rule.source,
-                status: "UNCLEAR",
-                outcome: "not_applicable",
+        const occ = approvalOccurrences(events, actions, opts);
+        const base = { ruleId: rule.id, ruleTitle: rule.title, ruleSource: rule.source, method: "approval_gate" };
+        if (occ.length === 0) {
+            return { ...base, status: "UNCLEAR", outcome: "not_applicable", evidence: `no ${actions.join("/")} went through this session, so the rule never applied` };
+        }
+        const bad = occ.find((o) => o.verdict === "unapproved");
+        if (bad) {
+            const n = occ.filter((o) => o.verdict === "unapproved").length;
+            return violation(rule, polarity, `ran "${bad.command}" with no approval: ${bad.why}${n > 1 ? ` (${n} times this session)` : ""}`, {
                 method: "approval_gate",
-                evidence: `no ${actions.join("/")} action ran this session, so the gate never applied`,
-            };
+                ceiling: "per action: approval is a user message asking for it or a yes after Claude asked, since the previous action of the same kind",
+            });
         }
-        if (askedBefore(events, action.index)) {
+        const unsure = occ.find((o) => o.verdict === "unclear");
+        if (unsure) {
             return {
-                ruleId: rule.id,
-                ruleTitle: rule.title,
-                ruleSource: rule.source,
-                status: "PASS",
-                outcome: "pass",
-                method: "approval_gate",
-                evidence: "the assistant sought approval before the action",
-                ceiling: "confirms the assistant ASKED; it does not judge whether the reply granted approval, and cannot see an approval given through the permission UI",
+                ...base,
+                status: "UNCLEAR",
+                outcome: "inconclusive",
+                reason: "approval_not_visible",
+                ceiling: "a click on the permission prompt leaves no trace in the transcript",
+                evidence: `ran "${unsure.command}": ${unsure.why}. Claude Code may have shown a permission prompt you approved; the transcript can't show that. Turn on the rulereceipt guard to force a prompt next time.`,
             };
         }
-        const excerpt = action.command.replace(/\s+/g, " ").trim().slice(0, 70);
-        return violation(rule, polarity, `the assistant ran "${excerpt}" with no approval sought beforehand`, {
-            method: "approval_gate",
-            ceiling: "flags an action taken with no approval-seeking text before it; it cannot see an approval given through the permission UI, so this is the clean no-ask case only",
-        });
+        return { ...base, status: "PASS", outcome: "pass", evidence: `${occ.length} ${actions.join("/")} action(s), each asked for or approved in the chat first` };
     });
 }

package/dist/checks/classify.d.ts

@@ -154,6 +154,19 @@ export declare function isEventRecord(rule: Rule): boolean;
  * is the forbidden command ("Never run: `rm -rf /`") is still a rule.
  */
 export declare function isCommandDocumentation(rule: Rule): boolean;
+/**
+ * Which gated actions a rule makes conditional on the user's say-so.
+ *
+ * Rewritten 2026-09-28, sentence by sentence. Three shapes:
+ *   "never|don't <action> … without permission | unless I ask | until the user confirms"
+ *   "ask|confirm|wait for approval … before <action>"
+ *   "only <action> when|if|after … asked|told|approved"
+ * The action and the consent phrase must sit in the SAME sentence. The old
+ * version needed only a signal word somewhere in the rule and an action word
+ * somewhere in the rule, so a section that said "ask before preserving compat"
+ * and elsewhere "delete the old one" became a delete gate — 16 wrong FAILs
+ * removed by requiring them together.
+ */
 export declare function approvalGateActions(rule: Rule): string[];
 export declare function classifyRule(rule: Rule): Classification;
 export declare function classifyRules(rules: Rule[]): Classification[];