rulereceipt 0.1.39 → 0.1.41

package/README.md

@@ -184,7 +184,7 @@ survives that by saying UNCLEAR. A gate cannot — so you mark it:
 rulereceipt rules --forbid <handle> --literal "git push --force"
 ```
 
-Handles come from `rulereceipt check --show-skipped`. The mark is stored
+Handles come from `rulereceipt rules --handles`. The mark is stored
 against the rule's content hash, and the guard blocks on that literal and no
 other. Three things it deliberately will not do:
 
@@ -201,6 +201,32 @@ Of 99 forbidding rules in the corpus that name a command-shaped literal, only
 marked automatically, which is the point.
 
 
+### Reproducing the published numbers
+
+Every figure in the [postmortem](https://rulereceipt.dev/postmortem) and in the
+issue threads is measured over 559 public rules files. The list of those files
+is committed as `rule_file_corpus.md`; the files themselves are not, because
+they belong to other projects.
+
+```bash
+bash scripts/fetch-corpus.sh 600      # the default is 60
+npx tsx scripts/corpus-report.ts      # where real rules route: 63.2% not instructions
+npx tsx scripts/false-accusation-rate.ts   # reports carrying a false accusation
+npx tsx scripts/verb-gate.ts          # which gate admits each rule
+npx tsx scripts/guard-replay.ts corpus 3   # what the PreToolUse guard would refuse
+```
+
+The list holds 563 URLs and yields 559 files — four have moved or been deleted
+upstream since it was drawn on 2026-08-30. That gap is expected and will grow;
+if your count differs from 559, that is why, and the routing percentages move
+by a rounding error rather than meaningfully.
+
+Two of these print a sha256 for every session they read. That is deliberate:
+"the largest sessions on this machine" is a selection rule, not a pin, and the
+largest include the session doing the measuring. Two runs of identical code
+four days apart returned 14,033 and 9,605 tool calls. Numbers are comparable
+only when those hashes match.
+
 ## Which rules actually have teeth
 
 A rule in a file and a rule with a `PreToolUse` hook behind it look identical

package/dist/checks/classify.d.ts

@@ -17,6 +17,11 @@ export interface IfEditThenTestClassification {
     kind: "ifEditThenTest";
     rule: Rule;
 }
+export interface EmojiClassification {
+    kind: "emojiOutput";
+    rule: Rule;
+    polarity: "forbid";
+}
 export interface JudgmentClassification {
     kind: "judgment";
     rule: Rule;
@@ -106,7 +111,7 @@ export interface ClaimEvidenceClassification {
     kind: "claimEvidence";
     rule: Rule;
 }
-export type Classification = ClaimEvidenceClassification | DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | JudgmentClassification;
+export type Classification = ClaimEvidenceClassification | DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | EmojiClassification | JudgmentClassification;
 export declare const DIRECTIVE_LANGUAGE: RegExp;
 /**
  * Imperative instruction — a bare command verb starting a clause ("Use
@@ -137,12 +142,5 @@ 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;
-/**
- * A rule is only treated as deterministic when it names a specific,
- * literal, checkable token (a CLI flag, a command, an exact string) in
- * backticks — e.g. "never use `git push --force`". Everything else
- * defaults to judgment, per the spec: never silently skip a rule by
- * guessing it's safe to pattern-match.
- */
 export declare function classifyRule(rule: Rule): Classification;
 export declare function classifyRules(rules: Rule[]): Classification[];

package/dist/checks/classify.js

@@ -463,6 +463,36 @@ function polarityWasInferred(rule) {
  * defaults to judgment, per the spec: never silently skip a rule by
  * guessing it's safe to pattern-match.
  */
+/**
+ * A rule forbidding emoji in output.
+ *
+ * Checkable, and it was not being checked: every phrasing routed to
+ * judgment, including one naming an emoji in backticks, because an emoji
+ * literal carries no alphanumerics and is rejected as unusable. Raised by
+ * anthropics/claude-code#94219.
+ *
+ * Both halves are required. The subject must be emoji, and the rule must
+ * FORBID them — "Use these emoji consistently across all chat output" is a
+ * real corpus rule and prescribes the opposite. A rule that merely mentions
+ * emoji in passing ("the identity file holds its name, vibe and emoji") is
+ * not about output at all.
+ */
+const EMOJI_SUBJECT = /\bemojis?\b|\bemoticons?\b/i;
+const EMOJI_FORBID = /\b(no|never|avoid|don't|do not|without|free of|refrain from|must not|shall not|not use|zero)\b/i;
+function isEmojiRule(rule) {
+    const text = `${rule.title} ${rule.text}`;
+    if (!EMOJI_SUBJECT.test(text))
+        return false;
+    if (!EMOJI_FORBID.test(text))
+        return false;
+    // The prohibition has to be near the subject, not merely present in the
+    // same section — the same adjacency argument as claim-evidence.
+    const m = text.match(EMOJI_SUBJECT);
+    if (!m || m.index === undefined)
+        return false;
+    const window = text.slice(Math.max(0, m.index - 60), m.index + 40);
+    return EMOJI_FORBID.test(window);
+}
 export function classifyRule(rule) {
     // Checked first: if this isn't a rule at all, no check of any kind
     // should run against it — not a keyword match, not an LLM call.
@@ -476,6 +506,11 @@ export function classifyRule(rule) {
         return { kind: "claimEvidence", rule };
     }
     // (length guard applied inside isClaimEvidenceRule)
+    // Checked before the backtick test: an emoji literal is rejected as an
+    // unusable pattern, so these would otherwise fall through to judgment.
+    if (isEmojiRule(rule)) {
+        return { kind: "emojiOutput", rule, polarity: "forbid" };
+    }
     const patterns = new Set();
     for (const match of rule.text.matchAll(BACKTICK_TOKEN)) {
         const token = match[1].trim();

package/dist/checks/emojiOutput.d.ts

@@ -0,0 +1,20 @@
+import type { EmojiClassification } from "./classify.js";
+import type { CheckResult, TranscriptEvent } from "../types.js";
+/**
+ * Did the assistant emit an emoji, against a rule forbidding it?
+ *
+ * One of the very few OUTPUT rules that can be answered mechanically. Most
+ * of what a rules file forbids leaves no event to inspect; this one lands in
+ * assistant text, which both the transcript and the Stop hook can read.
+ *
+ * Raised by anthropics/claude-code#94219: instructions said "avoid emojis
+ * unless the user explicitly asks", the model sent one, then appended a
+ * parenthetical retracting it rather than removing it. The retraction is why
+ * this reads the text rather than trusting the session's own account of
+ * itself — the apology and the emoji were in the same message.
+ *
+ * Only ASSISTANT text counts. A user who sends an emoji has not broken the
+ * assistant's rule, and an earlier version of this check that scanned every
+ * event would have reported one.
+ */
+export declare function runEmojiChecks(classifications: EmojiClassification[], events: TranscriptEvent[]): CheckResult[];

package/dist/checks/emojiOutput.js

@@ -0,0 +1,70 @@
+import { violation } from "../types.js";
+/**
+ * Emoji, as distinct from "any character a keyboard cannot type".
+ *
+ * Deliberately narrow. Accented Latin, CJK, mathematical symbols, arrows,
+ * dashes, degree signs and the check mark are NOT emoji, and a rule banning
+ * emoji must not fire on "café", "日本語", "±3°C" or "2×3". Those are
+ * ordinary text to the people who write them, and treating them as a
+ * violation would make this checker useless outside English.
+ *
+ * Covered: the pictographic blocks, the emoticon block, transport and map
+ * symbols, supplemental symbols, flags, and the dingbats that are actually
+ * rendered as emoji. Variation-selector-16 is included because it is what
+ * turns an otherwise plain glyph into its emoji presentation.
+ */
+const EMOJI = /[\u{1F300}-\u{1F5FF}\u{1F600}-\u{1F64F}\u{1F680}-\u{1F6FF}\u{1F900}-\u{1FAFF}\u{1F1E6}-\u{1F1FF}\u{2600}-\u{26FF}\u{FE0F}]/u;
+/** Every distinct emoji in a string, in order of first appearance. */
+function emojiIn(text) {
+    const found = [];
+    for (const ch of text) {
+        if (EMOJI.test(ch) && ch !== "️" && !found.includes(ch))
+            found.push(ch);
+    }
+    return found;
+}
+/**
+ * Did the assistant emit an emoji, against a rule forbidding it?
+ *
+ * One of the very few OUTPUT rules that can be answered mechanically. Most
+ * of what a rules file forbids leaves no event to inspect; this one lands in
+ * assistant text, which both the transcript and the Stop hook can read.
+ *
+ * Raised by anthropics/claude-code#94219: instructions said "avoid emojis
+ * unless the user explicitly asks", the model sent one, then appended a
+ * parenthetical retracting it rather than removing it. The retraction is why
+ * this reads the text rather than trusting the session's own account of
+ * itself — the apology and the emoji were in the same message.
+ *
+ * Only ASSISTANT text counts. A user who sends an emoji has not broken the
+ * assistant's rule, and an earlier version of this check that scanned every
+ * event would have reported one.
+ */
+export function runEmojiChecks(classifications, events) {
+    let first = null;
+    for (const event of events) {
+        if (event.kind !== "text" || event.role !== "assistant")
+            continue;
+        const found = emojiIn(event.text);
+        if (found.length === 0)
+            continue;
+        first = { emoji: found, text: event.text };
+        break;
+    }
+    return classifications.map(({ rule, polarity }) => {
+        if (first) {
+            const at = first.text.indexOf(first.emoji[0]);
+            const excerpt = first.text.slice(Math.max(0, at - 40), at + 40).replace(/\s+/g, " ").trim();
+            return violation(rule, polarity, `the assistant's reply contained ${first.emoji.slice(0, 4).join(" ")} — "…${excerpt}…"`, { method: "emoji_output" });
+        }
+        return {
+            ruleId: rule.id,
+            ruleTitle: rule.title,
+            ruleSource: rule.source,
+            status: "PASS",
+            outcome: "pass",
+            evidence: "no emoji appears in anything the assistant said this session",
+            ceiling: "a scan of the assistant's recorded text — it cannot see anything said outside this transcript",
+        };
+    });
+}

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 { runEmojiChecks } from "./checks/emojiOutput.js";
 import { runHook } from "./hook.js";
 import { runGuard } from "./guard.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
@@ -241,6 +242,7 @@ async function runCheck(opts) {
         ...runCodeContentChecks(codeContent, events),
         ...runFileLifecycleChecks(fileLifecycle, events),
         ...runClaimEvidenceChecks(claimEvidence, events),
+        ...runEmojiChecks(classifications.filter((c) => c.kind === "emojiOutput"), events),
     ];
     // Deterministic checks run by default, always, with no key — judgment
     // rules only call out to an LLM with an explicit --llm on THIS run, never
@@ -535,6 +537,33 @@ async function runRules(opts) {
         console.log(`your judgment onto words you never read.`);
         return;
     }
+    /**
+     * Every rule with its handle.
+     *
+     * --forbid needs a handle, and before this the only place handles were
+     * printed was `check --show-skipped`, which lists the items the classifier
+     * DISCARDED. A rule that is actually being checked had no handle anywhere,
+     * so the marking feature shipped in 0.1.39 could not be reached for any
+     * rule a user would want to mark. Found by trying to use it.
+     */
+    if (opts.handles) {
+        if (rules.length === 0) {
+            console.log("No CLAUDE.md or AGENTS.md rules found in this project.");
+            return;
+        }
+        console.log(`${rules.length} rule${rules.length === 1 ? "" : "s"} in this project:\n`);
+        for (const r of rules) {
+            const h = ruleFingerprint(r);
+            const marked = overrides.get(h)?.forbids;
+            console.log(`  ${h}  ${r.title.replace(/\s+/g, " ").trim().slice(0, 72)}`);
+            if (marked?.length)
+                console.log(`                blocks on: ${marked.map((f) => `\`${f}\``).join(", ")}`);
+        }
+        console.log(`\nMark which clause of a rule is the prohibition:`);
+        console.log(`  rulereceipt rules --forbid <handle> --literal "<the banned command>"`);
+        console.log(`Only a marked clause can ever refuse a command, and only via \`rulereceipt guard\`.`);
+        return;
+    }
     if (opts.clear) {
         console.log(clearOverride(cwd, opts.clear) ? `Removed the correction for ${opts.clear}.` : `No correction stored for ${opts.clear}.`);
         return;
@@ -651,6 +680,7 @@ program
     .description("correct what the classifier treats as a rule. Handles come from `check --show-skipped`.")
     .option("--include <handle>", "treat this item as a real rule and check it from now on")
     .option("--exclude <handle>", "treat this item as documentation and stop reporting it")
+    .option("--handles", "list every rule with its handle, for use with --forbid")
     .option("--forbid <handle>", "mark which clause of this rule is the prohibition, so the guard may block on it")
     .option("--literal <text>", "the exact banned command, used with --forbid; must appear in the rule")
     .option("--clear <handle>", "remove a stored correction")

package/dist/evaluate.js

@@ -5,6 +5,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 { runEmojiChecks } from "./checks/emojiOutput.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { loadOverrides, ruleFingerprint, staleOverrides } from "./overrides.js";
 /**
@@ -38,6 +39,7 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
         ...runCodeContentChecks(of("codeContent"), events),
         ...runFileLifecycleChecks(of("fileLifecycle"), events),
         ...runClaimEvidenceChecks(of("claimEvidence"), events),
+        ...runEmojiChecks(of("emojiOutput"), events),
     ];
     const judgment = of("judgment");
     const judgmentResults = llm

package/dist/guard.js

@@ -80,13 +80,22 @@ function structuredBlocks(cwd, event) {
 function ratifiedLiteralBlocks(cwd, command) {
     const overrides = loadOverrides(cwd);
     const blocks = [];
-    for (const c of forbidRules(cwd)) {
-        if (c.kind !== "deterministic")
+    // Read from the RULES, not from the classification. A human mark
+    // supersedes the classifier, including its refusal to classify — and that
+    // refusal is the common case here. "Never use `git push --force`; prefer
+    // `git push --force-with-lease`" goes to judgment via hasMixedPolarity,
+    // for a correct reason: literal matching cannot tell which half owns which
+    // token. A rule naming both the ban and the alternative is the canonical
+    // reason to have someone say which is which, so gating the mark behind the
+    // classifier made the feature unavailable in exactly the case that
+    // motivated it. Shipped that way in 0.1.39 and caught by running it.
+    for (const rule of loadRules(cwd)) {
+        if (overrides.get(ruleFingerprint(rule))?.decision === "notARule")
             continue;
-        for (const literal of ratifiedForbids(overrides, c.rule)) {
+        for (const literal of ratifiedForbids(overrides, rule)) {
             if (!commandRunsLiteral(command, literal))
                 continue;
-            blocks.push({ rule: c.rule, why: `the command about to run does \`${literal}\`, which this rule forbids (marked by you, not inferred)` });
+            blocks.push({ rule, why: `the command about to run does \`${literal}\`, which this rule forbids (marked by you, not inferred)` });
             break;
         }
     }
@@ -200,13 +209,29 @@ export async function runGuard() {
         }
         if (blocks.length === 0)
             return allow();
+        const why = reason(blocks);
         process.stdout.write(JSON.stringify({
             hookSpecificOutput: {
                 hookEventName: "PreToolUse",
                 permissionDecision: "deny",
-                permissionDecisionReason: reason(blocks),
+                permissionDecisionReason: why,
             },
         }));
+        // The same reason on stderr, deliberately duplicated.
+        //
+        // Two refusal paths exist and they carry the message differently.
+        // anthropics/claude-code#91574, measured by yurukusa on 2.1.278: a
+        // top-level {"permissionDecision":"deny"} body is invoked and IGNORED;
+        // the nested hookSpecificOutput form refuses; and stderr with exit 2
+        // refuses. Nobody has measured the nested body together with exit 2,
+        // which is what this emits.
+        //
+        // On the exit-2 path the documented channel back to the model is
+        // stderr, and stdout JSON is not promised to be read. Writing only the
+        // JSON risks a refusal with no reason attached — the block lands and
+        // the model is told nothing, which is the one failure a gate cannot
+        // afford. Printing both costs a duplicate line at worst.
+        process.stderr.write(`${why}\n`);
         // Exit 2 is what actually blocks the call; the JSON carries the reason.
         process.exitCode = 2;
     }

package/dist/types.d.ts

@@ -64,7 +64,7 @@ export type CheckOutcome = "pass" | "fail"
 /** How a verdict was reached. A verdict with no method is a verdict with no standing. */
 export type CheckMethod = "text_scan" | "file_events" | "git_events" | "code_content" | "edit_test_pairing" | "claim_vs_evidence" | "model_judgment"
 /** Nothing ran. */
- | "none";
+ | "none" | "emoji_output";
 export interface CheckResult {
     ruleId: string;
     ruleTitle: string;

package/package.json

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