rulereceipt 0.1.10 → 0.1.18

package/README.md

@@ -23,29 +23,38 @@ only (`rulereceipt check`). No automatic hooks, ever, in v1.
 
 ## Status
 
-Published and live on npm. Core CLI is built and tested (100 tests
-passing).
+Published and live on npm, actively developed.
 
 ## How it works
 
 1. Reads your CLAUDE.md / AGENTS.md and extracts individual rules —
-   from the current project directory and `~/.claude/CLAUDE.md`.
-2. Reads your most recent Claude Code session transcript (stored locally
-   at `~/.claude/projects/...`).
-3. Splits rules into two kinds:
-   - **Deterministic** — checkable by plain pattern matching (a rule
-     naming a specific literal in backticks, e.g. "never use
-     `git push --force`"). No AI call, no cost, no data exposure.
-   - **Judgment** — needs actual understanding (e.g. "surface bad news
-     first"). Checked via one batched API call using *your own* Claude
-     API key. If no key is set, these rules report UNCLEAR with an
-     explanation — never a silent guess at PASS.
+   from the current project directory and your global rules file.
+2. Reads your most recent Claude Code session transcript, wherever Claude
+   Code stored it — including hosted or enterprise variants that use a
+   different directory.
+3. Routes each rule to the narrowest check that can actually answer it:
+   - **Structured checks** read what the session really did — an actual
+     git command's branch argument, actual file edits, actual file
+     operations. These are the only checks that report a confident FAIL,
+     because they can tell an action from a mention.
+   - **Literal checks** look for a specific string named in the rule.
+     Absence is real evidence, so a clean session PASSes. A match reports
+     UNCLEAR with the text quoted, because a text match alone cannot
+     distinguish doing the forbidden thing from grepping for it, quoting
+     it, or naming it in a commit message.
+   - **Judgment** rules need real understanding (e.g. "surface bad news
+     first"). With `--llm` each is graded individually using *your own*
+     Claude key; without it they report UNCLEAR rather than guessing.
+   - Lines containing no instruction at all — directory listings,
+     reference tables, examples — aren't rules, and are reported as such
+     instead of being checked.
 4. Prints a report — terminal table by default, or `--markdown` for
    pasting into a PR or Slack message — showing what passed, what
    failed, and a quoted line of evidence for each. Every report includes
    a SHA-256 hash of the session file it checked, so anyone with that
-   file can independently confirm the report matches a real, unaltered
-   session.
+   file can confirm the report describes that exact file. (It proves the
+   report matches the file, not that the file is an unmodified record —
+   see SECURITY.md.)
 
 ## Try it with zero setup
 
@@ -61,7 +70,14 @@ report so you can see the output shape immediately.
 ```bash
 rulereceipt check              # check the latest session in this project
 rulereceipt check --markdown   # same, formatted for pasting into a PR/Slack
-rulereceipt check --share      # opt-in: also send anonymous pass/fail/unclear counts
+rulereceipt check --llm        # opt-in: grade judgment rules with your own Claude key
+rulereceipt check --share      # opt-in: send anonymous pass/fail/unclear counts
+rulereceipt check --telemetry  # opt-in: send one random per-machine ID
+rulereceipt check --transcript <path>      # check a specific session file
+rulereceipt doctor             # list hooks/auto-run tasks configured on this machine
+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)
 rulereceipt demo               # sample output, no setup needed
 rulereceipt demo --markdown
 rulereceipt --version          # print the installed version

package/dist/checks/classify.d.ts

@@ -19,7 +19,75 @@ export interface JudgmentClassification {
     kind: "judgment";
     rule: Rule;
 }
-export type Classification = DeterministicClassification | IfEditThenTestClassification | JudgmentClassification;
+/**
+ * First real structured-check primitive (2026-08-30), replacing keyword
+ * search for one whole rule category: git branch policy. A rule naming a
+ * branch (e.g. "never touch the `demo` branch") was previously checked by
+ * searching for the word "demo" ANYWHERE in the transcript — matching a
+ * repo name, a directory, a sentence, anything. This routes instead to a
+ * real parser (gitBranchPolicy.ts) that reads actual git command
+ * arguments and checks the literal branch name, not a substring search.
+ */
+export interface GitBranchPolicyClassification {
+    kind: "gitBranchPolicy";
+    rule: Rule;
+    branchName: string;
+    polarity: DeterministicPolarity;
+}
+/**
+ * Second structured-check primitive (2026-08-30): code content, for rules
+ * naming an actual code construct — a function/method call like `print(`
+ * or `analytics.track(` — rather than a CLI command. Real false-positive
+ * this fixes: even after excluding tool_result (see deterministicChecks.ts),
+ * a rule like "no `print(` statements" still matched when the agent's OWN
+ * Bash command merely MENTIONED the pattern as an argument (e.g. grepping
+ * for it), because generic deterministic matching scans the whole
+ * stringified tool_use input, commands included. This routes instead to
+ * codeContent.ts, which only looks at the actual content of real file
+ * edits (Write/Edit/NotebookEdit) — never a Bash command string, never
+ * prose, never a search argument.
+ */
+export interface CodeContentClassification {
+    kind: "codeContent";
+    rule: Rule;
+    patterns: string[];
+    polarity: DeterministicPolarity;
+}
+/**
+ * Third structured-check primitive (2026-08-30): file lifecycle, for
+ * rules protecting a specific file ("never modify `.claude/settings.json`",
+ * "don't delete `config.yaml`"). Real false-positive this fixes: the path
+ * was flagged as touched when the agent merely READ it (`cat
+ * .claude/settings.json` to verify its contents) — reading a protected
+ * file is not modifying it. Routes to fileLifecycle.ts, which only counts
+ * real mutations: Write/Edit on that path, or a Bash rm/mv/truncate-style
+ * command targeting it.
+ */
+export interface FileLifecycleClassification {
+    kind: "fileLifecycle";
+    rule: Rule;
+    filePath: string;
+    polarity: DeterministicPolarity;
+}
+/**
+ * Not every line in a real CLAUDE.md is a rule. Measured against 40 real
+ * public rule files (1,441 parsed items, 2026-08-30): only ~20% contained
+ * any directive language at all. The other ~80% is documentation —
+ * directory listings ("`forge/llm/` - Multi-provider LLM integrations"),
+ * import examples, model-name tables, glob-syntax references. 521 of those
+ * were getting a literal keyword check run against them, which is the
+ * single largest source of false positives: checking whether a session
+ * "violated" a directory listing is meaningless, and any coincidental
+ * match is noise reported as a finding.
+ *
+ * These are reported as N/A and excluded from pass/fail entirely — not
+ * sent to the LLM either, since there's no rule to judge.
+ */
+export interface NotARuleClassification {
+    kind: "notARule";
+    rule: Rule;
+}
+export type Classification = DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | JudgmentClassification;
 /**
  * A rule is only treated as deterministic when it names a specific,
  * literal, checkable token (a CLI flag, a command, an exact string) in

package/dist/checks/classify.js

@@ -1,16 +1,81 @@
+// Normative language — the thing that makes a line a rule rather than a
+// description. Deliberately broad on modals AND imperative verbs, because
+// a wrongly-excluded rule is a silent miss.
+const DIRECTIVE_LANGUAGE = /\b(never|always|must|should|shall|do not|don't|dont|cannot|can't|required?|requires|ensure|avoid|prefer|forbidden|prohibited|only|make sure|be sure|need|needs|needed|need to|has to|have to|expected to|responsible for)\b/i;
+/**
+ * Imperative instruction — a bare command verb starting a clause ("Use
+ * `gh pr merge`", "Run the tests first", "Keep functions small"). This is
+ * the other way a real rule is written when it doesn't use a modal.
+ *
+ * Anchored to a clause start (line start, or after sentence/bullet
+ * punctuation) on purpose: the same verbs appear mid-sentence in pure
+ * documentation ("the CLI can run migrations"), where they describe a
+ * capability rather than instruct the agent.
+ */
+const IMPERATIVE_INSTRUCTION = /(?:^|[.;:!?]\s+|^\s*[-*+]\s*|\n\s*[-*+]\s*)(use|run|keep|write|add|remove|delete|check|verify|test|commit|document|update|create|follow|apply|include|exclude|handle|validate|escape|sanitize|log|report|raise|throw|return|call|invoke|split|group|sort|name|place|put|store|read|load|save|close|open|start|stop|restart|install|build|deploy|review|refactor|rename|move|copy|merge|rebase|squash|tag|branch|push|pull|fetch|clone|stage|stash|lead|state|explain|describe|list|show|surface|flag|mark|label|note|treat|assume|confirm|ask|wait|stick|limit|cap|batch|cache|mock|stub|assert|expect|measure|quantify|label)\b/i;
+/**
+ * Deliberately inverted: tests for the presence of a DIRECTIVE, never for
+ * the shape of documentation.
+ *
+ * The first version of this enumerated documentation shapes (backtick
+ * glossary, bold-term definition, arrow mapping, label rows, "Reference:"
+ * prefixes). That approach cannot work: every new rules-file convention is
+ * a new shape, so the list grows forever and is always one format behind —
+ * measurably so, since `notARule` coverage fell from 17.4% on a 40-file
+ * sample to 7.1% on a 658-file one purely because the bigger corpus used
+ * shapes the list didn't have yet.
+ *
+ * "Does this contain an instruction" is a bounded question about English —
+ * modal verbs plus the closed class of imperative command verbs — and it
+ * doesn't change when someone invents a new markdown convention. A line
+ * with no instruction in it has nothing to check compliance against,
+ * whatever its punctuation.
+ */
+function isNotARule(rule) {
+    const combined = `${rule.title} ${rule.text}`;
+    if (DIRECTIVE_LANGUAGE.test(combined))
+        return false;
+    // Title and text are tested SEPARATELY: the imperative pattern is
+    // anchored to a clause start, and concatenating them pushes the text's
+    // opening verb into mid-string where the anchor can never match. That
+    // bug silently classified real rules ("Use `npm` for this project")
+    // as non-rules — caught by an existing test, not by inspection.
+    return !IMPERATIVE_INSTRUCTION.test(rule.title) && !IMPERATIVE_INSTRUCTION.test(rule.text);
+}
+const BRANCH_WORD = /\bbranch\b/i;
+// 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 = /\(/;
+// 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,
+// while a command that happens to contain a slash ("`git push --force`")
+// does. Checked AFTER the code-construct test, so "foo(" never lands here.
+const FILE_PATH_PATTERN = /^[^\s]*(\.(json|ya?ml|toml|md|env|lock|ini|cfg|conf|xml|txt|js|ts|py|rb|go|rs|sh)$|\/)/i;
+// Only route to fileLifecycle when the rule is actually about touching the
+// file, not merely mentioning one (e.g. "read `config.yaml` before
+// starting" names a path but isn't a protection rule).
+const FILE_MUTATION_INTENT = /\b(modif|chang|edit|delet|remov|overwrit|touch|writ|creat|rename|mov)\w*\b/i;
 // Catches rules like "add tests for every change" or "every new function
 // needs a test" - no literal backtick token to pattern-match, so without
 // this they'd fall all the way through to judgment (an LLM call) even
 // though they're actually structurally checkable: did a production file
 // get edited without a corresponding test file also being touched.
-// Deliberately requires BOTH signals together, not just the word "test"
-// alone (which would also match purely descriptive rules like "write
-// good tests" that aren't actually an edit-implies-test requirement).
-const TEST_WORD = /\btest/i;
-const REQUIRE_TEST_SIGNAL = /\b(always|must|required|require|ensure|need to|every)\b/i;
+//
+// Real false-positive found 2026-08-30 on an actual session: the earlier
+// version of this heuristic (bare "test" word + any require-signal word,
+// independently anywhere in the text) misclassified "Tests must be able
+// to fail" - a rule about test QUALITY (a test must be demonstrated to
+// fail on bad input before it counts) - as an edit-implies-test rule,
+// producing nonsense like "you edited .env but no test file was touched"
+// for a rule that was never about that at all. Fixed by requiring a
+// specific phrase shape - a create/add/need verb close to the word
+// "test" - not just independent word presence anywhere in the text.
+const EDIT_IMPLIES_TEST_PHRASE = /\b(needs?\s+(a\s+)?(corresponding\s+)?test|add(?:ing|ed)?\s+tests?|write\s+tests?|include\s+tests?|corresponding\s+test|test\s+coverage\s+for)\b/i;
 function isEditImpliesTestRule(rule) {
     const text = `${rule.title} ${rule.text}`;
-    return TEST_WORD.test(text) && REQUIRE_TEST_SIGNAL.test(text);
+    return EDIT_IMPLIES_TEST_PHRASE.test(text);
 }
 const BACKTICK_TOKEN = /`([^`]+)`/g;
 // Keyword signal near the rule text that this is a mandatory action, not a
@@ -21,6 +86,44 @@ const BACKTICK_TOKEN = /`([^`]+)`/g;
 // only an additive one for rules that clearly ask for a required action.
 const REQUIRE_SIGNAL = /\b(always|must|required|require|ensure|need to)\b/i;
 const FORBID_SIGNAL = /\b(never|don't|do not|forbidden|banned|must not)\b/i;
+/**
+ * A rule can prohibit one thing AND prescribe another in the same breath:
+ * "NEVER squash when merging PRs. Use `gh pr merge --merge --admin`".
+ * Literal pattern matching cannot handle this — it extracts `--merge` from
+ * the PRESCRIBED command, then applies the rule's forbid polarity to it,
+ * so doing exactly what the rule demands gets reported as violating it.
+ * Real false positive found 2026-08-30 on a real rules file.
+ *
+ * There's no honest way to split which literal belongs to which half by
+ * pattern alone, so a mixed-polarity rule goes to judgment instead of
+ * being guessed at. Better an "needs --llm" than a confident wrong FAIL.
+ */
+// Prescriptive language beyond the modal verbs in REQUIRE_SIGNAL. A rule
+// often prescribes with a bare imperative ("Use `gh pr merge --merge`")
+// rather than "you must use" — and it's exactly those imperative clauses
+// whose literals get misattributed to the prohibiting half.
+const PRESCRIPTIVE_VERB = /\b(use|run|prefer|apply|follow|call|invoke|stick to)\b/i;
+function hasMixedPolarity(rule) {
+    const text = `${rule.title} ${rule.text}`;
+    if (!FORBID_SIGNAL.test(text))
+        return false;
+    // The prescription must live in a DIFFERENT clause than the prohibition.
+    // "Never run `git push --force`" is one clause: "run" belongs to the
+    // forbidden action, and treating that as mixed polarity would send the
+    // most basic literal rule there is to the LLM. "NEVER squash when
+    // merging PRs. Use `gh pr merge --merge`" is two clauses, and only the
+    // second one's literals would be misattributed.
+    //
+    // Code spans are masked before splitting. Real bug caught by the
+    // end-to-end violation tests: "Never leave a `console.log(` call in
+    // committed code" was split on the period INSIDE the code span, leaving
+    // a fragment ("log(` call in committed code") with no forbid word but a
+    // prescriptive one, so a plain prohibition was misread as mixed
+    // polarity and sent to judgment instead of being checked.
+    const masked = text.replace(/`[^`]*`/g, (m) => "`" + "x".repeat(Math.max(m.length - 2, 0)) + "`");
+    const clauses = masked.split(/[.;\n]|(?:\s+-\s+)/).filter((c) => c.trim().length > 0);
+    return clauses.some((clause) => !FORBID_SIGNAL.test(clause) && (REQUIRE_SIGNAL.test(clause) || PRESCRIPTIVE_VERB.test(clause)));
+}
 function detectPolarity(rule) {
     const text = `${rule.title} ${rule.text}`;
     // An explicit forbid word anywhere wins over a require word — "you must
@@ -39,6 +142,11 @@ function detectPolarity(rule) {
  * guessing it's safe to pattern-match.
  */
 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.
+    if (isNotARule(rule)) {
+        return { kind: "notARule", rule };
+    }
     const patterns = new Set();
     for (const match of rule.text.matchAll(BACKTICK_TOKEN)) {
         const token = match[1].trim();
@@ -50,12 +158,32 @@ export function classifyRule(rule) {
         if (token.length > 0)
             patterns.add(token);
     }
+    // A rule that both forbids and prescribes can't be checked by literal
+    // matching without misattributing one half's tokens to the other.
+    if (patterns.size > 0 && hasMixedPolarity(rule)) {
+        return { kind: "judgment", rule };
+    }
     if (patterns.size === 0) {
         if (isEditImpliesTestRule(rule)) {
             return { kind: "ifEditThenTest", rule };
         }
         return { kind: "judgment", rule };
     }
+    const text = `${rule.title} ${rule.text}`;
+    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;
+        return { kind: "gitBranchPolicy", rule, branchName, polarity: detectPolarity(rule) };
+    }
+    if ([...patterns].some((p) => CODE_CONSTRUCT_PATTERN.test(p))) {
+        return { kind: "codeContent", rule, patterns: [...patterns], polarity: detectPolarity(rule) };
+    }
+    const filePath = [...patterns].find((p) => FILE_PATH_PATTERN.test(p));
+    if (filePath && FILE_MUTATION_INTENT.test(text)) {
+        return { kind: "fileLifecycle", rule, filePath, polarity: detectPolarity(rule) };
+    }
     return { kind: "deterministic", rule, patterns: [...patterns], polarity: detectPolarity(rule) };
 }
 export function classifyRules(rules) {

package/dist/checks/codeContent.d.ts

@@ -0,0 +1,3 @@
+import type { TranscriptEvent, CheckResult } from "../types.js";
+import type { CodeContentClassification } from "./classify.js";
+export declare function runCodeContentChecks(classifications: CodeContentClassification[], events: TranscriptEvent[]): CheckResult[];

package/dist/checks/codeContent.js

@@ -0,0 +1,89 @@
+/**
+ * Second structured-check primitive: only scans the actual content of
+ * real file edits for a code-construct pattern (e.g. `print(`,
+ * `analytics.track(`) — never a Bash command string, never prose, never
+ * tool_result. Real false-positive this fixes (found 2026-08-30, on the
+ * same real session as the git-branch bug): even after excluding
+ * tool_result from the generic deterministic check, a rule like "no
+ * `print(` statements" still matched because the agent's own Bash
+ * command MENTIONED the pattern as a search argument (e.g. `grep -rn
+ * "print(" src/`) — no print statement was ever written into a file.
+ *
+ * Known, stated limitation: `content`/`new_string` are the confirmed
+ * real field names for Write/Edit tool_use input; NotebookEdit's field
+ * name is included as best-effort (not independently confirmed against a
+ * real NotebookEdit transcript event before shipping this) — a session
+ * that only writes matching code via NotebookEdit could under-report,
+ * which fails toward UNCLEAR/PASS, not a fabricated FAIL.
+ */
+function editedContentFromEvent(event) {
+    if (event.kind !== "tool_use")
+        return null;
+    const input = event.input;
+    if (event.toolName === "Write" && typeof input?.content === "string")
+        return input.content;
+    if (event.toolName === "Edit" && typeof input?.new_string === "string")
+        return input.new_string;
+    if (event.toolName === "NotebookEdit" && typeof input?.new_source === "string")
+        return input.new_source;
+    return null;
+}
+export function runCodeContentChecks(classifications, events) {
+    const editedContents = [];
+    for (const event of events) {
+        const content = editedContentFromEvent(event);
+        if (content)
+            editedContents.push(content);
+    }
+    return classifications.map(({ rule, patterns, polarity }) => {
+        let foundPattern;
+        let foundContent;
+        for (const content of editedContents) {
+            for (const pattern of patterns) {
+                if (content.includes(pattern)) {
+                    foundPattern = pattern;
+                    foundContent = content;
+                    break;
+                }
+            }
+            if (foundPattern)
+                break;
+        }
+        if (polarity === "forbid") {
+            if (foundPattern && foundContent) {
+                return {
+                    ruleId: rule.id,
+                    ruleTitle: rule.title,
+                    ruleSource: rule.source,
+                    status: "FAIL",
+                    evidence: `found "${foundPattern}" actually written into a file: ${foundContent.slice(0, 160)}`,
+                };
+            }
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                evidence: `no file edit actually contained ${patterns.map((p) => `"${p}"`).join(" or ")} this session`,
+            };
+        }
+        // require: absence is UNCLEAR, not a fabricated FAIL — same reasoning
+        // as deterministicChecks.ts's require-polarity handling
+        if (foundPattern && foundContent) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                evidence: `found required "${foundPattern}" actually written into a file: ${foundContent.slice(0, 160)}`,
+            };
+        }
+        return {
+            ruleId: rule.id,
+            ruleTitle: rule.title,
+            ruleSource: rule.source,
+            status: "UNCLEAR",
+            evidence: `no file edit contained the required ${patterns.map((p) => `"${p}"`).join(" or ")} this session — can't tell if the rule didn't apply, or applied and was skipped`,
+        };
+    });
+}

package/dist/checks/deterministicChecks.js

@@ -70,12 +70,25 @@ export function runDeterministicChecks(classifications, events) {
             if (polarity === "forbid") {
                 if (foundEvent && foundPattern) {
                     const haystack = eventSearchText(foundEvent);
+                    // Deliberately UNCLEAR, never FAIL. A bare literal match proves
+                    // the string appeared somewhere; it cannot prove the agent DID
+                    // the forbidden thing. The same match is produced by grepping
+                    // for the pattern, quoting it in an explanation, or naming it in
+                    // a commit message — all compliant. Every false positive found
+                    // on 2026-08-30 was this exact confusion, and no amount of
+                    // pattern tuning fixes it, because the information needed to
+                    // tell action from mention is not in the string.
+                    //
+                    // Confident FAILs come only from the structured primitives
+                    // (gitBranchPolicy, codeContent, fileLifecycle), which read what
+                    // the agent actually executed or wrote. This path reports the
+                    // evidence and says plainly that it can't confirm a violation.
                     return {
                         ruleId: rule.id,
                         ruleTitle: rule.title,
                         ruleSource: rule.source,
-                        status: "FAIL",
-                        evidence: `found banned pattern "${foundPattern}" in a ${foundEvent.kind === "tool_use" ? foundEvent.toolName + " call" : foundEvent.kind}: ${haystack.slice(0, 160)}`,
+                        status: "UNCLEAR",
+                        evidence: `"${foundPattern}" appears in a ${foundEvent.kind === "tool_use" ? foundEvent.toolName + " call" : foundEvent.kind}, but a text match alone can't tell an actual violation from a mention (a search for it, a quote, an explanation) — needs a human look: ${haystack.slice(0, 160)}`,
                     };
                 }
                 return {

package/dist/checks/fileLifecycle.d.ts

@@ -0,0 +1,3 @@
+import type { TranscriptEvent, CheckResult } from "../types.js";
+import type { FileLifecycleClassification } from "./classify.js";
+export declare function runFileLifecycleChecks(classifications: FileLifecycleClassification[], events: TranscriptEvent[]): CheckResult[];

package/dist/checks/fileLifecycle.js

@@ -0,0 +1,119 @@
+/**
+ * Third structured-check primitive: only counts real MUTATIONS of a
+ * protected file, never reads of it. Real false-positive this fixes
+ * (found 2026-08-30 on a real session): a rule protecting
+ * `.claude/settings.json` reported it as touched because the agent ran
+ * `cat .claude/settings.json` to VERIFY its contents — reading a
+ * protected file to confirm it's intact is the opposite of violating the
+ * rule, and flagging it punishes exactly the behavior the rule wants.
+ *
+ * Counts as a mutation:
+ *  - Write / Edit / NotebookEdit tool_use whose file_path is the file
+ *  - A Bash command using a destructive/overwriting operator on the path
+ *    (rm, mv onto it, truncation via `>`, sed -i, tee)
+ *
+ * Explicitly NOT a mutation: cat, less, head, tail, grep, Read, ls, or
+ * the path merely appearing in prose or in another command's arguments.
+ *
+ * Known, stated limitation: Bash detection is regex over the command
+ * string, not a shell parser. A sufficiently exotic invocation (an
+ * unusual redirect form, a path built from a variable, a mutation inside
+ * a script file that is itself invoked) will be missed — that's a false
+ * NEGATIVE (reports PASS/UNCLEAR), the safe direction. This must never
+ * fabricate a FAIL from a command that only read the file.
+ */
+const WRITE_LIKE_TOOLS = new Set(["Write", "Edit", "NotebookEdit"]);
+function escapeRegex(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * A path is "the same file" if the command references it exactly, or
+ * references a path ending in it (so a rule naming
+ * `.claude/settings.json` still matches an absolute
+ * `/home/x/.claude/settings.json`). Deliberately anchored at a path
+ * boundary so `settings.json` does not match `other-settings.json`.
+ */
+function pathPattern(filePath) {
+    return `(?:^|[\\s'"=/])${escapeRegex(filePath.replace(/^\.\//, ""))}(?=$|[\\s'";)])`;
+}
+function mutatesPathInBash(command, filePath) {
+    const p = pathPattern(filePath);
+    const mutations = [
+        // rm / rmdir / unlink targeting the path
+        new RegExp(`\\b(?:rm|rmdir|unlink)\\b[^|;&]*${p}`),
+        // mv / cp writing ONTO the path (path appears as the final argument)
+        new RegExp(`\\b(?:mv|cp)\\b[^|;&]*${p}\\s*(?:$|[;&|])`),
+        // truncation or append redirect onto the path
+        new RegExp(`>>?\\s*['"]?${escapeRegex(filePath.replace(/^\.\//, ""))}`),
+        // in-place edits
+        new RegExp(`\\bsed\\b[^|;&]*-i[^|;&]*${p}`),
+        new RegExp(`\\btee\\b[^|;&]*${p}`),
+        new RegExp(`\\btruncate\\b[^|;&]*${p}`),
+    ];
+    return mutations.some((re) => re.test(command));
+}
+function findMutation(events, filePath) {
+    const normalized = filePath.replace(/^\.\//, "");
+    for (const event of events) {
+        if (event.kind !== "tool_use")
+            continue;
+        if (WRITE_LIKE_TOOLS.has(event.toolName)) {
+            const input = event.input;
+            if (typeof input?.file_path === "string") {
+                const actual = input.file_path.replace(/^\.\//, "");
+                if (actual === normalized || actual.endsWith(`/${normalized}`)) {
+                    return `${event.toolName} on ${input.file_path}`;
+                }
+            }
+            continue;
+        }
+        if (event.toolName === "Bash") {
+            const input = event.input;
+            if (typeof input?.command === "string" && mutatesPathInBash(input.command, filePath)) {
+                return input.command;
+            }
+        }
+    }
+    return null;
+}
+export function runFileLifecycleChecks(classifications, events) {
+    return classifications.map(({ rule, filePath, polarity }) => {
+        const mutation = findMutation(events, filePath);
+        if (polarity === "forbid") {
+            if (mutation) {
+                return {
+                    ruleId: rule.id,
+                    ruleTitle: rule.title,
+                    ruleSource: rule.source,
+                    status: "FAIL",
+                    evidence: `"${filePath}" was actually modified: ${mutation.slice(0, 160)}`,
+                };
+            }
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                evidence: `"${filePath}" was never written to, deleted, or moved this session (reading it does not count)`,
+            };
+        }
+        // require: absence is UNCLEAR, not a fabricated FAIL — same reasoning
+        // as deterministicChecks.ts's require-polarity handling
+        if (mutation) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                evidence: `"${filePath}" was updated as required: ${mutation.slice(0, 160)}`,
+            };
+        }
+        return {
+            ruleId: rule.id,
+            ruleTitle: rule.title,
+            ruleSource: rule.source,
+            status: "UNCLEAR",
+            evidence: `"${filePath}" was never modified this session — can't tell if the rule didn't apply, or applied and was skipped`,
+        };
+    });
+}

package/dist/checks/gitBranchPolicy.d.ts

@@ -0,0 +1,3 @@
+import type { TranscriptEvent, CheckResult } from "../types.js";
+import type { GitBranchPolicyClassification } from "./classify.js";
+export declare function runGitBranchPolicyChecks(classifications: GitBranchPolicyClassification[], events: TranscriptEvent[]): CheckResult[];

package/dist/checks/gitBranchPolicy.js

@@ -0,0 +1,131 @@
+/**
+ * First real structured-check primitive: parses actual git command
+ * arguments instead of searching prose for a branch name as a substring.
+ * Real bug this fixes (found 2026-08-30): a rule like "never touch the
+ * `demo` branch" previously matched the word "demo" appearing ANYWHERE —
+ * a repo name ("acme demo repo"), a directory, an unrelated sentence.
+ * This only matches an actual git command whose branch ARGUMENT is
+ * exactly the named branch.
+ *
+ * Known, stated limitation: covers the common real invocations
+ * (checkout, switch, branch create/delete/rename, push to a branch) via
+ * regex on the command string, not a real git-command-line parser. Things
+ * this does NOT reliably cover: `git checkout <ref>` when <ref> could be
+ * a file path rather than a branch (ambiguous without actually running
+ * git), refspecs with `+`/wildcards, `git rebase --onto <branch>`, and
+ * any git GUI/porcelain wrapper that doesn't literally run `git` in Bash.
+ * Failing to detect a real violation here is a false negative (UNCLEAR),
+ * which is the safe direction — this must never fabricate a FAIL from a
+ * command that didn't actually target the named branch.
+ */
+// Split from a single "checkout or switch" pattern: `checkout -b`/`switch
+// -c` CREATE a new branch with that exact name — nobody accidentally
+// creates a branch named exactly the protected name while trying to sync
+// something else, so this is an immediate hit, same as GIT_BRANCH_CREATE.
+// A bare `checkout`/`switch` (no -b/-c) only SWITCHES to an existing
+// branch, which is routine (syncing before branching off) and only
+// becomes a real violation if a commit follows it — see
+// findCheckoutCommitViolation.
+const GIT_CHECKOUT_CREATE = /\bgit\s+(?:checkout\s+-[bB]|switch\s+-c)\s+([^\s-][^\s]*)/;
+const GIT_CHECKOUT_SWITCH_ONLY = /\bgit\s+(?:checkout|switch)\s+(?:--\s+)?([^\s-][^\s]*)/;
+const GIT_BRANCH_CREATE = /\bgit\s+branch\s+(?:-[a-zA-Z]+\s+)?([^\s-][^\s]*)/;
+const GIT_PUSH = /\bgit\s+push\s+(?:\S+\s+)?(?:\+)?(?:[^\s:]+:)?([^\s:]+)\s*$/;
+const GIT_COMMIT = /\bgit\s+commit\b/;
+function extractGitBranchTargets(command) {
+    const targets = [];
+    for (const regex of [GIT_CHECKOUT_CREATE, GIT_CHECKOUT_SWITCH_ONLY, GIT_BRANCH_CREATE, GIT_PUSH]) {
+        const match = command.match(regex);
+        if (match)
+            targets.push(match[1]);
+    }
+    return targets;
+}
+function commandFromEvent(event) {
+    if (event.kind !== "tool_use" || event.toolName !== "Bash")
+        return null;
+    const input = event.input;
+    return typeof input?.command === "string" ? input.command : null;
+}
+/**
+ * Real gap found 2026-08-30, one publish after the first version of this
+ * file shipped: the original version treated ANY checkout of the named
+ * branch as a violation — but "git checkout sprint && git pull origin
+ * sprint" (sync, then branch off) is normal, compliant workflow, not a
+ * violation of "never work on the sprint branch." The actual violation is
+ * COMMITTING while that branch is checked out, not merely visiting it.
+ * Simulates the current checked-out branch across the session in
+ * chronological order, and only counts a checkout-based hit when a real
+ * `git commit` happens while that branch is current. Push/branch-create
+ * targeting the named branch stay immediate hits regardless — pushing
+ * straight to a protected branch, or creating/renaming/deleting it, is
+ * the violation itself, not something that needs a following commit.
+ */
+function findCheckoutCommitViolation(commands, branchName) {
+    let currentBranch = null;
+    for (const command of commands) {
+        const checkoutMatch = command.match(GIT_CHECKOUT_CREATE) ?? command.match(GIT_CHECKOUT_SWITCH_ONLY);
+        if (checkoutMatch) {
+            currentBranch = checkoutMatch[1];
+            continue;
+        }
+        if (currentBranch === branchName && GIT_COMMIT.test(command)) {
+            return command;
+        }
+    }
+    return null;
+}
+export function runGitBranchPolicyChecks(classifications, events) {
+    const commands = [];
+    const allTargets = [];
+    for (const event of events) {
+        const command = commandFromEvent(event);
+        if (!command)
+            continue;
+        commands.push(command);
+        for (const branch of extractGitBranchTargets(command)) {
+            allTargets.push({ branch, command });
+        }
+    }
+    return classifications.map(({ rule, branchName, polarity }) => {
+        const pushOrCreateHit = allTargets.find((t) => t.branch === branchName &&
+            (GIT_PUSH.test(t.command) || GIT_BRANCH_CREATE.test(t.command) || GIT_CHECKOUT_CREATE.test(t.command)));
+        const commitViolationCommand = findCheckoutCommitViolation(commands, branchName);
+        const hit = pushOrCreateHit ?? (commitViolationCommand ? { branch: branchName, command: commitViolationCommand } : undefined);
+        if (polarity === "forbid") {
+            if (hit) {
+                return {
+                    ruleId: rule.id,
+                    ruleTitle: rule.title,
+                    ruleSource: rule.source,
+                    status: "FAIL",
+                    evidence: `a git command actually targeted the "${branchName}" branch: ${hit.command}`,
+                };
+            }
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                evidence: `no git command targeted the "${branchName}" branch this session`,
+            };
+        }
+        // require: absence is UNCLEAR, not a fabricated FAIL — same reasoning
+        // as deterministicChecks.ts's require-polarity handling
+        if (hit) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                evidence: `a git command targeted the required "${branchName}" branch: ${hit.command}`,
+            };
+        }
+        return {
+            ruleId: rule.id,
+            ruleTitle: rule.title,
+            ruleSource: rule.source,
+            status: "UNCLEAR",
+            evidence: `no git command targeting the "${branchName}" branch appeared this session — can't tell if the rule didn't apply, or applied and was skipped`,
+        };
+    });
+}

package/dist/cli.js

@@ -11,6 +11,9 @@ import { loadRules } from "./rules.js";
 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 { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { generateReport, generateMarkdownReport } from "./report/generateReport.js";
 import { verifySessionHash } from "./verifyHash.js";
@@ -72,13 +75,23 @@ async function emailResults(reportText) {
         console.log(`\n(--email failed to send: ${result.error} — report above is unaffected)`);
     }
 }
+/**
+ * A rule that genuinely requires judgment ("surface bad news first",
+ * "write readable code") has no mechanical answer. Reporting that as a
+ * deficiency of the tool ("run with --llm") frames the honest answer as a
+ * missing feature; it isn't. Deciding a subjective rule was followed is a
+ * human call, and saying so plainly is the product working correctly.
+ *
+ * --llm is offered as what it is — a second opinion from a model, still
+ * not a substitute for the reader's judgment.
+ */
 function needsLlmResult(rule) {
     return {
         ruleId: rule.id,
         ruleTitle: rule.title,
         ruleSource: rule.source,
         status: "UNCLEAR",
-        evidence: "this rule needs judgment, not just pattern matching — run with --llm to grade it (opt-in: sends this rule's text and transcript excerpts to your own configured Anthropic key)",
+        evidence: "NEEDS HUMAN REVIEW — this rule is a judgment call, not something that can be settled by looking at what commands ran. Read the session and decide for yourself. (`--llm` will give you a model's opinion on it, using your own Anthropic key — an opinion, not a verdict.)",
     };
 }
 async function runCheck(markdown, share, email, emailAlways, llm, telemetry, transcriptOverride) {
@@ -105,10 +118,22 @@ async function runCheck(markdown, share, email, emailAlways, llm, telemetry, tra
     const classifications = classifyRules(rules);
     const deterministic = classifications.filter((c) => c.kind === "deterministic");
     const ifEditThenTest = classifications.filter((c) => c.kind === "ifEditThenTest");
+    const gitBranchPolicy = classifications.filter((c) => c.kind === "gitBranchPolicy");
+    const codeContent = classifications.filter((c) => c.kind === "codeContent");
+    const fileLifecycle = classifications.filter((c) => c.kind === "fileLifecycle");
     const judgment = classifications.filter((c) => c.kind === "judgment");
+    // Not rules at all — documentation, glossary entries, reference tables.
+    // Measured on 40 real public rule files: ~17% of parsed items. Reported
+    // as a count so nothing is silently dropped, but never checked, since
+    // "did the session violate a directory listing" has no meaningful answer
+    // and any coincidental match is pure noise.
+    const notARule = classifications.filter((c) => c.kind === "notARule");
     const deterministicResults = [
         ...runDeterministicChecks(deterministic, events),
         ...runIfEditThenTestChecks(ifEditThenTest, events),
+        ...runGitBranchPolicyChecks(gitBranchPolicy, events),
+        ...runCodeContentChecks(codeContent, events),
+        ...runFileLifecycleChecks(fileLifecycle, 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
@@ -122,9 +147,12 @@ async function runCheck(markdown, share, email, emailAlways, llm, telemetry, tra
     // regardless of --llm.
     const judgmentResults = llm ? await runJudgmentChecks(judgment, events) : judgment.map(({ rule }) => needsLlmResult(rule));
     const results = [...deterministicResults, ...judgmentResults];
-    const meta = { sessionFilePath, ruleCount: rules.length };
+    const meta = { sessionFilePath, ruleCount: results.length };
     const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta);
     console.log(reportText);
+    if (notARule.length > 0) {
+        console.log(`\n(${notARule.length} item${notARule.length === 1 ? "" : "s"} in your rules file ${notARule.length === 1 ? "is" : "are"} documentation, not a rule — directory listings, reference tables, examples. Not checked, because there's nothing to check.)`);
+    }
     appendHistory(results, sessionFilePath);
     if (share) {
         await shareResults(results);

package/dist/rules.js

@@ -1,7 +1,47 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, parse } from "node:path";
+import { existsSync } from "node:fs";
 import { parseClaudeMd } from "./parsers/claudeMdParser.js";
 import { findClaudeHomeDirNames } from "./parsers/transcriptParser.js";
+const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md"];
+/**
+ * Walks from the working directory up toward the repository root,
+ * collecting rules files at every level.
+ *
+ * Real gap: rules were only read from the exact directory the command ran
+ * in. Claude Code itself applies a rules file to everything beneath it, so
+ * in a monorepo the root CLAUDE.md governs `packages/api/` — but running
+ * the check inside that package silently missed it, reporting on a subset
+ * of the rules that actually applied and never saying so.
+ *
+ * Stops at the repository root (a directory containing `.git`) so an
+ * unrelated rules file further up the filesystem — in a parent workspace,
+ * or the home directory — is never pulled into an unrelated project.
+ * Global rules are handled separately, deliberately, below.
+ */
+function findProjectRuleFiles(cwd) {
+    const found = [];
+    const { root } = parse(cwd);
+    const home = homedir();
+    let dir = cwd;
+    for (;;) {
+        for (const name of RULE_FILE_NAMES) {
+            const p = join(dir, name);
+            if (existsSync(p))
+                found.push(p);
+        }
+        // stop AT the repo root (inclusive) — its rules do apply
+        if (existsSync(join(dir, ".git")))
+            break;
+        if (dir === root || dir === home)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return found;
+}
 /**
  * Global rules come from every .claude*-prefixed home dir found, not just
  * ~/.claude — a hosted/enterprise Claude Code variant can keep its own
@@ -11,9 +51,8 @@ import { findClaudeHomeDirNames } from "./parsers/transcriptParser.js";
  */
 export function loadRules(cwd) {
     const rules = findClaudeHomeDirNames().flatMap((dirName) => parseClaudeMd(join(homedir(), dirName, "CLAUDE.md"), "global"));
-    for (const name of ["CLAUDE.md", "AGENTS.md"]) {
-        const projectPath = join(cwd, name);
-        rules.push(...parseClaudeMd(projectPath, "project"));
+    for (const path of findProjectRuleFiles(cwd)) {
+        rules.push(...parseClaudeMd(path, "project"));
     }
     return rules;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.10",
+  "version": "0.1.18",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "eslint src tests"
+    "lint": "eslint src tests",
+    "prepublishOnly": "npm run build && npm test"
   },
   "engines": {
     "node": ">=18"
@@ -36,6 +37,6 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.67.0",
-    "vitest": "^2.1.0"
+    "vitest": "^4.1.11"
   }
 }