rulereceipt 0.1.26 → 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.js

@@ -4,8 +4,8 @@ import { classifyRules } from "../checks/classify.js";
 export const CORPUS = {
     files: 559,
     parsed: 23704,
-    notRulesPct: 62.9,
-    checkablePct: 43.5,
+    notRulesPct: 64.5,
+    checkablePct: 42.7,
 };
 function pct(part, whole) {
     return whole === 0 ? 0 : Math.round((part / whole) * 1000) / 10;

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

@@ -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/package.json

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