rulereceipt 0.1.25 → 0.1.27

package/README.md

@@ -9,29 +9,18 @@
 Checks whether a Claude Code session actually followed the rules in your
 CLAUDE.md / AGENTS.md — with evidence, not just a vibe.
 
-Every release from 0.1.19 on is built and published by GitHub Actions and
-signed with [npm provenance](https://docs.npmjs.com/generating-provenance-statements),
-so you can verify the published package was built from this repository at
-a specific commit. No publishing token exists to be stolen. Check it
-yourself with `npm audit signatures` after installing.
+Runs entirely on your machine. Plain `rulereceipt check` makes zero network
+calls — [Trust, privacy and licensing](#trust-privacy-and-licensing) has the
+full detail, including the three off-by-default opt-ins.
 
-Licensed source-available software — see [LICENSE](./LICENSE) and
-[NOTICE.md](./NOTICE.md) before reusing this code.
+## See it in 10 seconds
 
-Runs entirely on your machine. Your code, rules, and session content never
-leave your computer, ever. Plain `rulereceipt check` makes zero network
-calls. `--llm`, `--share`, and `--telemetry` are all separate, off-by-default
-opt-ins: `--llm` calls the Claude API using your own Anthropic key for rules
-that need judgment; `--share` sends aggregate pass/fail/unclear counts;
-`--telemetry` sends one random per-machine ID so real distinct-install
-counts are knowable, nothing else. None of them fire unless you explicitly
-pass the flag, and `DO_NOT_TRACK=1` / `RULERECEIPT_NO_TELEMETRY=1` forces
-telemetry off even if you do.
-
-**Security note:** RuleReceipt never modifies `.claude/settings.json` and
-installs no hooks without explicit action. It only ever reads your
-CLAUDE.md/AGENTS.md and session transcripts — read-only, manual invocation
-only (`rulereceipt check`). No automatic hooks, ever, in v1.
+```bash
+npx rulereceipt demo
+```
+
+No install, no config, no API key, no real session needed — prints a sample
+report so you can see the output shape immediately.
 
 ## Status
 
@@ -59,7 +48,12 @@ Published and live on npm, actively developed.
      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.
+     instead of being checked. This step is a heuristic over English
+     instruction words, so it can be wrong in both directions: run
+     `rulereceipt check --show-skipped` once on your rules file to see
+     exactly what it excluded. A rule phrased unusually, or written in
+     another language, can land there — and a rule dropped silently is
+     worse than one reported wrongly.
 4. Prints a report — terminal table by default, `--markdown` for pasting
    into a PR or Slack message, or `--html` for a shareable single file —
    showing what passed, what failed, and a quoted line of evidence for
@@ -68,30 +62,31 @@ Published and live on npm, actively developed.
    that exact file. (It proves the report matches the file, not that the
    file is an unmodified record — see SECURITY.md.)
 
-## Exit codes
-
-`check` exits **1** when a rule was actually broken, and **0** otherwise,
-so CI can gate on it. Rules that need human judgment report UNCLEAR and
-never affect the exit code — most rules in a real CLAUDE.md need judgment,
-and gating on those would make every build red on day one.
-
-`--exit-zero` prints the report without failing the build. `--require-session`
-does the opposite and is the one to use anywhere automated: it fails when
-there is no session, or an empty one, instead of reporting a pass for a
-check that never actually ran.
-
-### A limit worth knowing before you wire this into CI
+## Usage
 
-Claude Code writes its session transcript to the machine the agent ran on
-— your laptop. A CI runner is a fresh machine that has never seen it, so a
-CI job cannot check a session that happened on your laptop unless you
-deliberately make that transcript available to the job. See
-[templates/rulereceipt-ci.yml](./templates/rulereceipt-ci.yml), which
-explains the options and, if you use it, fails loudly rather than passing
-on a session it never found.
+```bash
+rulereceipt check              # check the latest session in this project
+rulereceipt check --markdown   # same, formatted for pasting into a PR/Slack
+rulereceipt check --html       # write a shareable single-file HTML report you can send
+rulereceipt check --html report.html       # ...to a specific path
+rulereceipt check --show-skipped           # list what was treated as documentation and not checked
+rulereceipt check --require-session        # fail if there's no session, instead of passing silently
+rulereceipt check --exit-zero              # report failures without failing the build
+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
+rulereceipt verify <session-file> <hash>   # spot-check a report you received against the real session file
+```
 
-For most people the honest answer is simpler: run `rulereceipt check --html`
-locally and attach the report to the PR.
+`verify` isn't a routine check — trust your team day to day, same as any status update. It's there for the rare case it actually matters (a dispute, an incident review): give it the session file and the hash printed in the report, and it confirms whether they really match.
 
 ## Sharing a report
 
@@ -110,39 +105,30 @@ 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.
 
-## Try it with zero setup
+## Exit codes
 
-```bash
-rulereceipt demo
-```
+`check` exits **1** when a rule was actually broken, and **0** otherwise,
+so CI can gate on it. Rules that need human judgment report UNCLEAR and
+never affect the exit code — most rules in a real CLAUDE.md need judgment,
+and gating on those would make every build red on day one.
 
-No install config, no API key, no real session needed — prints a sample
-report so you can see the output shape immediately.
+`--exit-zero` prints the report without failing the build. `--require-session`
+does the opposite and is the one to use anywhere automated: it fails when
+there is no session, or an empty one, instead of reporting a pass for a
+check that never actually ran.
 
-## Usage
+### A limit worth knowing before you wire this into CI
 
-```bash
-rulereceipt check              # check the latest session in this project
-rulereceipt check --markdown   # same, formatted for pasting into a PR/Slack
-rulereceipt check --html       # write a shareable single-file HTML report you can send
-rulereceipt check --html report.html       # ...to a specific path
-rulereceipt check --require-session        # fail if there's no session, instead of passing silently
-rulereceipt check --exit-zero              # report failures without failing the build
-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
-rulereceipt verify <session-file> <hash>   # spot-check a report you received against the real session file
-```
+Claude Code writes its session transcript to the machine the agent ran on
+— your laptop. A CI runner is a fresh machine that has never seen it, so a
+CI job cannot check a session that happened on your laptop unless you
+deliberately make that transcript available to the job. See
+[templates/rulereceipt-ci.yml](./templates/rulereceipt-ci.yml), which
+explains the options and, if you use it, fails loudly rather than passing
+on a session it never found.
 
-`verify` isn't a routine check — trust your team day to day, same as any status update. It's there for the rare case it actually matters (a dispute, an incident review): give it the session file and the hash printed in the report, and it confirms whether they really match.
+For most people the honest answer is simpler: run `rulereceipt check --html`
+locally and attach the report to the PR.
 
 ## Install
 
@@ -161,6 +147,34 @@ npm test
 npx tsx src/cli.ts demo
 ```
 
+## Trust, privacy and licensing
+
+**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
+separate, off-by-default opt-ins: `--llm` calls the Claude API using your
+own Anthropic key for rules that need judgment; `--share` sends aggregate
+pass/fail/unclear counts; `--telemetry` sends one random per-machine ID so
+real distinct-install counts are knowable, nothing else. None of them fire
+unless you explicitly pass the flag, and `DO_NOT_TRACK=1` /
+`RULERECEIPT_NO_TELEMETRY=1` forces telemetry off even if you do.
+
+**Read-only, and no hooks.** RuleReceipt never modifies
+`.claude/settings.json` and installs no hooks without explicit action. It
+only ever reads your CLAUDE.md/AGENTS.md and session transcripts —
+read-only, manual invocation only (`rulereceipt check`). No automatic
+hooks, ever, in v1.
+
+**You can verify the package came from this source.** Every release from
+0.1.19 on is built and published by GitHub Actions and signed with
+[npm provenance](https://docs.npmjs.com/generating-provenance-statements),
+so you can verify the published package was built from this repository at
+a specific commit. No publishing token exists to be stolen. Check it
+yourself with `npm audit signatures` after installing.
+
+**Licence.** Source-available software — see [LICENSE](./LICENSE) and
+[NOTICE.md](./NOTICE.md) before reusing this code.
+
 ## Contact
 
 Questions, bugs, or anything else — hello@rulereceipt.dev.

package/dist/browser/analyze.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Entry point for the in-browser checker on the site.
+ *
+ * The privacy claim on that page — "your file never leaves this page" — is
+ * only true because everything reachable from here is pure string work.
+ * parseClaudeMdText and classifyRules touch no Node API, no network, and
+ * no storage. If anything in this dependency chain ever gains an import
+ * that does, the page's claim becomes false and must change with it.
+ *
+ * Deliberately returns counts and a small sample, never the file: nothing
+ * here should make it easy to accidentally send the text somewhere.
+ */
+export interface Breakdown {
+    kind: string;
+    count: number;
+}
+export interface AnalysisResult {
+    /** Everything the parser pulled out of the file, rules and non-rules alike. */
+    parsed: number;
+    /** Items carrying no instruction — documentation, tables, listings. */
+    notRules: number;
+    /** Items that are genuinely directives. */
+    realRules: number;
+    /** Real rules a check can answer by looking at what ran. */
+    checkable: number;
+    /** Real rules that need a person. */
+    judgment: number;
+    /** Share of the whole file that isn't an instruction, 0-100. */
+    notRulesPct: number;
+    /** Share of REAL rules that are mechanically answerable, 0-100. */
+    checkablePct: number;
+    byKind: Breakdown[];
+    /** A few non-rule titles, so the number is inspectable rather than asserted. */
+    notRuleSamples: string[];
+    /** A few judgment-call titles, same reason. */
+    judgmentSamples: string[];
+}
+/** Measured across 559 real public rules files. Shown for comparison. */
+export declare const CORPUS: {
+    files: number;
+    parsed: number;
+    notRulesPct: number;
+    checkablePct: number;
+};
+export declare function analyze(text: string): AnalysisResult;

package/dist/browser/analyze.js

@@ -0,0 +1,49 @@
+import { parseClaudeMdText } from "../parsers/claudeMdParser.js";
+import { classifyRules } from "../checks/classify.js";
+/** Measured across 559 real public rules files. Shown for comparison. */
+export const CORPUS = {
+    files: 559,
+    parsed: 23704,
+    notRulesPct: 64.5,
+    checkablePct: 42.7,
+};
+function pct(part, whole) {
+    return whole === 0 ? 0 : Math.round((part / whole) * 1000) / 10;
+}
+export function analyze(text) {
+    const rules = parseClaudeMdText(text, "project");
+    const classified = classifyRules(rules);
+    const counts = new Map();
+    const notRuleSamples = [];
+    const judgmentSamples = [];
+    for (const c of classified) {
+        counts.set(c.kind, (counts.get(c.kind) ?? 0) + 1);
+        const title = c.rule.title.trim();
+        if (!title)
+            continue;
+        if (c.kind === "notARule" && notRuleSamples.length < 4)
+            notRuleSamples.push(title);
+        if (c.kind === "judgment" && judgmentSamples.length < 4)
+            judgmentSamples.push(title);
+    }
+    const parsed = classified.length;
+    const notRules = counts.get("notARule") ?? 0;
+    const judgment = counts.get("judgment") ?? 0;
+    const realRules = parsed - notRules;
+    const checkable = realRules - judgment;
+    const byKind = [...counts.entries()]
+        .map(([kind, count]) => ({ kind, count }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        parsed,
+        notRules,
+        realRules,
+        checkable,
+        judgment,
+        notRulesPct: pct(notRules, parsed),
+        checkablePct: pct(checkable, realRules),
+        byKind,
+        notRuleSamples,
+        judgmentSamples,
+    };
+}

package/dist/checks/classify.js

@@ -68,12 +68,82 @@ function isEventRecord(rule) {
         return false;
     return EVENT_RECORD_TITLE.test(rule.title);
 }
+/**
+ * A line whose SUBJECT is a command-line option, i.e. the documentation of
+ * a flag rather than an instruction to the agent. "`--file=<path>, -f`: Use
+ * alternative tasks.json file" describes what the flag does; the imperative
+ * belongs to the flag, not to the reader.
+ *
+ * This is why the directive test alone cannot separate these: command
+ * documentation is written with the same verbs as a command, because it is
+ * describing a command. The distinguishing property is grammatical — what
+ * the sentence is ABOUT — and it is announced by the line beginning with an
+ * option token and a separator.
+ *
+ * Deliberately narrow. It requires the option token to be the first thing on
+ * the line and to be followed by a colon, so a rule that merely mentions a
+ * flag ("Always pass `--frozen-lockfile` when installing") is untouched.
+ */
+const FLAG_DOCUMENTATION = /^\s*`?\s*-{1,2}[A-Za-z0-9][\w-]*(?:=[^\s,`]*)?(?:\s*,\s*`?\s*-{1,2}[\w-]+`?(?:=[^\s,`]*)?)*\s*`?\s*:/;
+/**
+ * English prose almost always contains at least one function word. A shell
+ * invocation contains none, and contains at least one token carrying a path
+ * separator, a flag prefix, an internal dot, or an assignment.
+ *
+ * Both conditions are required. "Use modular architecture" has no function
+ * word either, but no command-shaped token, so it stays a rule. "Run `npm
+ * test` before every push" has command-shaped tokens but also has function
+ * words, so it stays a rule too.
+ *
+ * This is a property of the language, not of the file format — the same
+ * reasoning as DIRECTIVE_LANGUAGE above, which is why it is expressed as a
+ * test on the text rather than as a list of documentation conventions.
+ */
+const FUNCTION_WORD = /\b(a|an|the|is|are|was|were|be|being|been|to|of|in|on|for|with|when|if|that|this|these|those|and|or|but|not|no|do|does|you|your|it|its|as|at|by|from|before|after|until|unless|any|every|all|each|must|should|never|always|only|via|per|than|then|so|such|into|onto|over|under|about)\b/i;
+const COMMAND_SHAPED_TOKEN = /(?:^|\s)(?:\S*[/\\]\S*|-{1,2}[A-Za-z]\S*|\S+\.\S+|\S+=\S+)/;
+function looksLikeBareCommand(text) {
+    const withoutCode = text
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`[^`]*`/g, " ")
+        .trim();
+    // If stripping code leaves nothing, the body WAS only code.
+    const body = withoutCode.length > 0 ? withoutCode : text.replace(/[`\n]+/g, " ").trim();
+    if (!body)
+        return false;
+    // Long enough to be prose, whatever it contains.
+    if (body.split(/\s+/).length > 12)
+        return false;
+    if (FUNCTION_WORD.test(body))
+        return false;
+    return COMMAND_SHAPED_TOKEN.test(body);
+}
+/**
+ * A heading that labels a command, with the command as its whole body:
+ * "Build release APK" over `.\gradlew assembleRelease`. The title reads as
+ * an imperative, but nothing here constrains the agent — it is a how-to, and
+ * there is no compliance to check.
+ *
+ * Guarded by TITLE_OPENS_WITH_DIRECTIVE so a genuine prohibition whose body
+ * is the forbidden command ("Never run: `rm -rf /`") is still a rule.
+ */
+function isCommandDocumentation(rule) {
+    if (TITLE_OPENS_WITH_DIRECTIVE.test(rule.title))
+        return false;
+    if (FLAG_DOCUMENTATION.test(rule.text) || FLAG_DOCUMENTATION.test(rule.title))
+        return true;
+    return looksLikeBareCommand(rule.text);
+}
 function isNotARule(rule) {
     // Checked before the directive test on purpose: an incident note that
     // ends with its lesson contains a real directive, and would otherwise
     // be enforced as though the history itself were the rule.
     if (isEventRecord(rule))
         return true;
+    // Same reason as above: command documentation carries real imperatives
+    // ("Use alternative tasks.json file"), so the directive test below would
+    // otherwise accept it as a rule to check compliance against.
+    if (isCommandDocumentation(rule))
+        return true;
     const combined = `${rule.title} ${rule.text}`;
     if (DIRECTIVE_LANGUAGE.test(combined))
         return false;

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { join, dirname, resolve, isAbsolute } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { parseClaudeMd } from "./parsers/claudeMdParser.js";
+import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { readLatestTranscript, readTranscriptFromFile, findLatestSessionFile } from "./parsers/transcriptParser.js";
 import { loadRules } from "./rules.js";
 import { classifyRules } from "./checks/classify.js";
@@ -132,7 +132,7 @@ function writeHtmlReport(results, meta, cwd, target) {
     }
 }
 async function runCheck(opts) {
-    const { markdown, share, email, emailAlways, llm, telemetry, html, exitZero, requireSession, transcriptOverride } = opts;
+    const { markdown, share, email, emailAlways, llm, telemetry, html, exitZero, requireSession, showSkipped, transcriptOverride } = opts;
     const cwd = process.cwd();
     const rules = loadRules(cwd);
     if (rules.length === 0) {
@@ -229,8 +229,35 @@ async function runCheck(opts) {
     if (html !== false) {
         writeHtmlReport(results, { sessionFilePath, ruleCount: results.length }, cwd, html);
     }
+    // A count alone is not enough. The classifier is a heuristic over English
+    // verbs: measured across 559 public rules files it drops non-English
+    // content at 97.5% against a 64.5% baseline, and any imperative verb
+    // outside its list is invisible to it. Neither gap closes by extending the
+    // list — imperative verbs are not a closed class, and the list is
+    // English-only by construction.
+    //
+    // What does close is the silence. "12 items were documentation" reads as
+    // reassurance; it is the one place this tool still guesses without saying
+    // so, and a rule dropped here never appears in the report at all. Listing
+    // them needs no key, works in any language, and lets the person who wrote
+    // the rule be the one who decides.
     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.)`);
+        const n = notARule.length;
+        const plural = n === 1 ? "" : "s";
+        console.log(`\n(${n} item${plural} in your rules file ${n === 1 ? "was" : "were"} treated as documentation and not checked — directory listings, reference tables, examples.)`);
+        if (showSkipped) {
+            console.log(`\nSkipped as documentation:\n`);
+            for (const { rule } of notARule) {
+                const label = rule.title.replace(/\s+/g, " ").trim();
+                console.log(`  [${rule.id}] ${label.slice(0, 110)}`);
+            }
+            console.log(`\nIf any of those is actually a rule, the classifier was wrong. It looks for` +
+                `\nEnglish instruction words, so a rule written another way — or in another` +
+                `\nlanguage — can land here. Worth a look; you know your rules, it doesn't.`);
+        }
+        else {
+            console.log(`Run with --show-skipped to see them.`);
+        }
     }
     appendHistory(results, sessionFilePath);
     if (share) {
@@ -288,6 +315,7 @@ program
     .option("--html [path]", `write a shareable single-file HTML report you can email, attach to a ticket, or print to PDF. Defaults to ./${DEFAULT_HTML_REPORT_NAME}. Written locally — nothing is uploaded.`)
     .option("--exit-zero", "always exit 0, even when a rule was broken. Without this, `check` exits 1 on any FAIL so CI can gate on it (rules needing human judgment report UNCLEAR and never affect the exit code).")
     .option("--require-session", "fail (exit 1) if no session is found, or the session is empty, instead of reporting a pass for a check that never actually ran. Use this anywhere automated.")
+    .option("--show-skipped", "list the items that were treated as documentation and not checked. Worth running once on any rules file: the classifier is a heuristic over English verbs, so a rule it does not recognise is otherwise dropped without you seeing it.")
     .option("--transcript <path>", "manual override: check this exact .jsonl session file instead of auto-detecting one. Useful if your Claude Code session lives somewhere non-standard that auto-detection doesn't cover.")
     .action((opts) => {
     runCheck({
@@ -301,6 +329,7 @@ program
         html: opts.html ?? false,
         exitZero: Boolean(opts.exitZero),
         requireSession: Boolean(opts.requireSession),
+        showSkipped: Boolean(opts.showSkipped),
         transcriptOverride: opts.transcript,
     }).catch((err) => {
         console.error("Something went wrong:", err instanceof Error ? err.message : err);

package/dist/parsers/claudeMdParser.d.ts

@@ -1,2 +1,11 @@
 import type { Rule } from "../types.js";
-export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];
+/**
+ * The actual parser, taking text rather than a path.
+ *
+ * Split out from parseClaudeMd so the parsing logic carries no filesystem
+ * dependency and can run anywhere a string can — including a browser, for
+ * the client-side checker on the site. That checker's privacy claim
+ * ("your file never leaves the page") is only true because nothing in
+ * this function or in classify.ts touches Node APIs; keep it that way.
+ */
+export declare function parseClaudeMdText(raw: string, source: "global" | "project"): Rule[];

package/dist/parsers/claudeMdParser.js

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 /**
  * Real CLAUDE.md/AGENTS.md files use several different conventions for
  * organizing rules. Verified against real files and templates: Anthropic's
@@ -67,14 +66,16 @@ function normalizeSetextHeaders(lines) {
     }
     return out;
 }
-export function parseClaudeMd(filePath, source) {
-    let raw;
-    try {
-        raw = readFileSync(filePath, "utf-8");
-    }
-    catch {
-        return [];
-    }
+/**
+ * The actual parser, taking text rather than a path.
+ *
+ * Split out from parseClaudeMd so the parsing logic carries no filesystem
+ * dependency and can run anywhere a string can — including a browser, for
+ * the client-side checker on the site. That checker's privacy claim
+ * ("your file never leaves the page") is only true because nothing in
+ * this function or in classify.ts touches Node APIs; keep it that way.
+ */
+export function parseClaudeMdText(raw, source) {
     const lines = normalizeSetextHeaders(raw.split("\n"));
     const rules = [];
     // `current` accumulates a numbered-header rule, a bold-rule-header rule,

package/dist/parsers/readClaudeMd.d.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types.js";
+/**
+ * The filesystem half of rules-file parsing, deliberately kept in its own
+ * module.
+ *
+ * claudeMdParser.ts must stay free of Node imports so it can be bundled
+ * for the browser — the in-page checker on the site claims the pasted file
+ * never leaves the page, and that is only true while nothing reachable
+ * from the parser can perform I/O. Keeping the one readFileSync here
+ * means a bundler cannot pull `node:fs` in behind it, and a future import
+ * that breaks the guarantee has to be added here, visibly, rather than
+ * appearing by accident in the parser.
+ */
+/**
+ * Reads a rules file from disk. Thin wrapper: an unreadable file is an
+ * empty rule list, never a throw, because a missing global CLAUDE.md is a
+ * normal state rather than an error.
+ */
+export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];

package/dist/parsers/readClaudeMd.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { parseClaudeMdText } from "./claudeMdParser.js";
+/**
+ * The filesystem half of rules-file parsing, deliberately kept in its own
+ * module.
+ *
+ * claudeMdParser.ts must stay free of Node imports so it can be bundled
+ * for the browser — the in-page checker on the site claims the pasted file
+ * never leaves the page, and that is only true while nothing reachable
+ * from the parser can perform I/O. Keeping the one readFileSync here
+ * means a bundler cannot pull `node:fs` in behind it, and a future import
+ * that breaks the guarantee has to be added here, visibly, rather than
+ * appearing by accident in the parser.
+ */
+/**
+ * Reads a rules file from disk. Thin wrapper: an unreadable file is an
+ * empty rule list, never a throw, because a missing global CLAUDE.md is a
+ * normal state rather than an error.
+ */
+export function parseClaudeMd(filePath, source) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    return parseClaudeMdText(raw, source);
+}

package/dist/rules.d.ts

@@ -5,5 +5,15 @@ import type { Rule } from "./types.js";
  * global CLAUDE.md under its own home dir (e.g. ~/.claude-office/CLAUDE.md).
  * Real gap found 2026-08-30, same root cause as the transcript-lookup fix
  * in transcriptParser.ts: hardcoding one home-dir name misses any variant.
+ *
+ * Also reads ~/.claude/rules/*.md, the documented location for personal
+ * rules that apply across every project.
+ *
+ * NOT covered, and stated rather than left silent: machine-wide managed
+ * enterprise policy files (/Library/Application Support/ClaudeCode,
+ * /etc/claude-code, C:\Program Files\ClaudeCode). Those are deployed by
+ * IT, exist on no development machine this can be tested against, and
+ * guessing at their location would be the kind of unverified assumption
+ * this project has already been bitten by twice.
  */
 export declare function loadRules(cwd: string): Rule[];

package/dist/rules.js

@@ -1,9 +1,62 @@
 import { homedir } from "node:os";
 import { dirname, join, parse } from "node:path";
-import { existsSync } from "node:fs";
-import { parseClaudeMd } from "./parsers/claudeMdParser.js";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { findClaudeHomeDirNames } from "./parsers/transcriptParser.js";
-const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md"];
+/**
+ * Every place Claude Code actually reads a rule from, at one directory
+ * level. Order mirrors the documented load order, broadest first.
+ *
+ * Real gap found 2026-09-02: only the two bare filenames were read. A
+ * project with four rules files reported "1 rules checked · all passed" —
+ * three files invisible, with nothing saying so. A clean report on rules
+ * the tool never opened is the most misleading result this can produce,
+ * worse than no report, because it looks like evidence.
+ */
+const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", "AGENTS.local.md"];
+const RULE_SUBDIR_FILES = [join(".claude", "CLAUDE.md"), join(".claude", "AGENTS.md")];
+const RULE_DIRS = [join(".claude", "rules")];
+/**
+ * Lists the markdown files in a rules directory, if it exists.
+ *
+ * Sorted so the same project always produces the same rule order — rule
+ * ids are positional, and an unstable order would renumber rules between
+ * runs on different machines, making two reports of the same session
+ * impossible to compare. Non-markdown files are skipped: a rules
+ * directory legitimately holds README fragments and notes.
+ */
+function markdownFilesIn(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        if (!statSync(dir).isDirectory())
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.toLowerCase().endsWith(".md"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/** Every rules file at one directory level, in documented load order. */
+function ruleFilesAtLevel(dir) {
+    const found = [];
+    for (const rel of RULE_SUBDIR_FILES) {
+        const p = join(dir, rel);
+        if (existsSync(p))
+            found.push(p);
+    }
+    for (const rel of RULE_DIRS)
+        found.push(...markdownFilesIn(join(dir, rel)));
+    for (const name of RULE_FILE_NAMES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            found.push(p);
+    }
+    return found;
+}
 /**
  * Walks from the working directory up toward the repository root,
  * collecting rules files at every level.
@@ -25,11 +78,7 @@ function findProjectRuleFiles(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);
-        }
+        found.push(...ruleFilesAtLevel(dir));
         // stop AT the repo root (inclusive) — its rules do apply
         if (existsSync(join(dir, ".git")))
             break;
@@ -48,9 +97,26 @@ function findProjectRuleFiles(cwd) {
  * global CLAUDE.md under its own home dir (e.g. ~/.claude-office/CLAUDE.md).
  * Real gap found 2026-08-30, same root cause as the transcript-lookup fix
  * in transcriptParser.ts: hardcoding one home-dir name misses any variant.
+ *
+ * Also reads ~/.claude/rules/*.md, the documented location for personal
+ * rules that apply across every project.
+ *
+ * NOT covered, and stated rather than left silent: machine-wide managed
+ * enterprise policy files (/Library/Application Support/ClaudeCode,
+ * /etc/claude-code, C:\Program Files\ClaudeCode). Those are deployed by
+ * IT, exist on no development machine this can be tested against, and
+ * guessing at their location would be the kind of unverified assumption
+ * this project has already been bitten by twice.
  */
 export function loadRules(cwd) {
-    const rules = findClaudeHomeDirNames().flatMap((dirName) => parseClaudeMd(join(homedir(), dirName, "CLAUDE.md"), "global"));
+    const rules = [];
+    for (const dirName of findClaudeHomeDirNames()) {
+        const base = join(homedir(), dirName);
+        rules.push(...parseClaudeMd(join(base, "CLAUDE.md"), "global"));
+        for (const file of markdownFilesIn(join(base, "rules"))) {
+            rules.push(...parseClaudeMd(file, "global"));
+        }
+    }
     for (const path of findProjectRuleFiles(cwd)) {
         rules.push(...parseClaudeMd(path, "project"));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",
@@ -37,7 +37,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src tests",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "build:checker": "esbuild src/browser/analyze.ts --bundle --format=esm --minify --outfile=landing/checker.js"
   },
   "engines": {
     "node": ">=18"