rulereceipt 0.1.55 → 0.1.57

package/dist/audit.d.ts

@@ -0,0 +1,28 @@
+import type { Rule } from "./types.js";
+/**
+ * A rules-only health score — how much of a rules file can actually be checked,
+ * with NO session needed.
+ *
+ * The recurring day-one gap: a first `check` with no session is empty, and a
+ * real CLAUDE.md is mostly a handbook — measured across the public corpus, ~38%
+ * of items are rules and ~56% of those need judgment. `audit` answers "is your
+ * rules file enforceable?" on any format (CLAUDE.md, AGENTS.md, Cursor, Copilot,
+ * Windsurf, Gemini) instantly, and points at `rules --advise` for the fixes.
+ *
+ * Buckets, by how classifyRule routes each item:
+ *  - checkable : any structured/deterministic kind — a session can be checked
+ *                against it without a human or an LLM
+ *  - judgment  : needs a person (or `--llm`)
+ *  - skipped   : not a rule (docs, directory maps, glossary rows)
+ */
+export interface RulesAudit {
+    total: number;
+    checkable: number;
+    judgment: number;
+    skipped: number;
+    /** checkable / (checkable + judgment), whole %, 0 when there are no rules. */
+    percentCheckable: number;
+}
+export declare function auditRules(rules: Rule[]): RulesAudit;
+/** A short, readable audit. Never says "compliant" — it measures the file, not a session. */
+export declare function renderAudit(a: RulesAudit, md?: boolean): string;

package/dist/audit.js

@@ -0,0 +1,44 @@
+import { classifyRules } from "./checks/classify.js";
+export function auditRules(rules) {
+    let checkable = 0;
+    let judgment = 0;
+    let skipped = 0;
+    for (const c of classifyRules(rules)) {
+        if (c.kind === "notARule")
+            skipped++;
+        else if (c.kind === "judgment")
+            judgment++;
+        else
+            checkable++;
+    }
+    const decided = checkable + judgment;
+    return {
+        total: checkable + judgment + skipped,
+        checkable,
+        judgment,
+        skipped,
+        percentCheckable: decided > 0 ? Math.round((checkable / decided) * 100) : 0,
+    };
+}
+/** A short, readable audit. Never says "compliant" — it measures the file, not a session. */
+export function renderAudit(a, md = false) {
+    if (a.checkable + a.judgment === 0) {
+        return md
+            ? "**No rules found** in this project's rules files. Is there a `CLAUDE.md`, `AGENTS.md` or similar here?"
+            : "No rules found in this project's rules files.\nIs there a CLAUDE.md / AGENTS.md (or Cursor/Copilot/Windsurf rules) here?";
+    }
+    const H = (s) => (md ? `## ${s}` : s);
+    const out = [];
+    out.push(md ? "# RuleReceipt — rules audit" : "RuleReceipt · rules audit  (no session needed)");
+    out.push("");
+    out.push(`${a.checkable + a.judgment} rules read (plus ${a.skipped} documentation item${a.skipped === 1 ? "" : "s"} not scored).`);
+    out.push("");
+    out.push(H("Can this session be checked against them?"));
+    out.push(`  ${String(a.checkable).padStart(4)}  checkable        — verifiable from a session, no human needed`);
+    out.push(`  ${String(a.judgment).padStart(4)}  need judgment    — a person (or \`--llm\`) decides these`);
+    out.push(`  ${String(a.skipped).padStart(4)}  documentation    — structure/notes, not scored as rules`);
+    out.push("");
+    out.push(`${a.percentCheckable}% of your rules can be checked mechanically.`);
+    out.push("See which can't, and the smallest edit that would fix each:  rulereceipt rules --advise");
+    return out.join("\n");
+}

package/dist/checks/classify.js

@@ -293,6 +293,25 @@ const FILE_PATH_PATTERN = /^[^\s]*(\.(json|ya?ml|toml|md|env|lock|ini|cfg|conf|x
 // 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;
+/**
+ * A backtick literal distinctive enough to check INSIDE written code without
+ * matching ordinary prose. A single token (no whitespace), not a shell flag,
+ * carrying code punctuation (`. - / @ # :`) and at least three alphanumerics —
+ * so `lucide-react`, `#0af`, `@deprecated`, `react-dom` qualify, while plain
+ * words (`TODO`, `name`), shell commands (`git push --force`) and bare flags
+ * do not. Used to route a FORBID rule's token to codeContent: found in
+ * Write/Edit content it is an ACTION (a real FAIL), not a mention. Added
+ * 2026-09-28 to move import/value-style rules out of the UNCLEAR bucket.
+ */
+function isContentToken(literal) {
+    if (/\s/.test(literal))
+        return false;
+    if (literal.startsWith("-"))
+        return false;
+    if (!/[.\-/@#:]/.test(literal))
+        return false;
+    return (literal.match(/[A-Za-z0-9]/g) ?? []).length >= 3;
+}
 // 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
@@ -485,6 +504,14 @@ function polarityWasInferred(rule) {
  */
 const EMOJI_SUBJECT = /\bemojis?\b|\bemoticons?\b/i;
 const EMOJI_FORBID = /\b(no|never|avoid|don't|do not|without|free of|refrain from|must not|shall not|not use|zero)\b/i;
+// A permissive threshold means the rule allows SOME emoji — not a zero-ban the
+// deterministic checker can decide.
+const EMOJI_THRESHOLD = /\b(?:liberal|sparing|minimal|excessive|overus|one or two|a couple|a few|maximum|at most|no more than|too many|limit)\w*/i;
+// A rule scoped only to an artifact the checker can't see (it reads the
+// assistant's chat text, not posts/commits/READMEs) can't be verified from
+// that text — unless it also names the chat/output the checker DOES see.
+const EMOJI_OFFTARGET = /\b(?:posts?|commits?|pull requests?|prs?|readme|docs?|documentation|blog|articles?|captions?|changelog)\b/i;
+const EMOJI_ONTARGET = /\b(?:output|repl(?:y|ies)|response|chat|message|answer|conversation|everywhere|anywhere)\b/i;
 function isEmojiRule(rule) {
     const text = `${rule.title} ${rule.text}`;
     if (!EMOJI_SUBJECT.test(text))
@@ -497,7 +524,17 @@ function isEmojiRule(rule) {
     if (!m || m.index === undefined)
         return false;
     const window = text.slice(Math.max(0, m.index - 60), m.index + 40);
-    return EMOJI_FORBID.test(window);
+    if (!EMOJI_FORBID.test(window))
+        return false;
+    // Real false positive 2026-09-28: "one or two emojis per post is the maximum"
+    // (a THRESHOLD, about POSTS) failed on a ✅ in a chat reply. A permissive
+    // threshold, or a rule scoped only to an artifact this checker can't see,
+    // is not a confident deterministic FAIL — it goes to judgment.
+    if (EMOJI_THRESHOLD.test(text))
+        return false;
+    if (EMOJI_OFFTARGET.test(text) && !EMOJI_ONTARGET.test(text))
+        return false;
+    return true;
 }
 /**
  * A rule that forbids an AI-authorship mark in git commits, PRs or comments.
@@ -668,6 +705,16 @@ export function classifyRule(rule) {
     if (filePath && FILE_MUTATION_INTENT.test(text)) {
         return { kind: "fileLifecycle", rule, filePath, polarity, polarityInferred };
     }
+    // A forbid rule naming a distinctive token (an import, a value) is a real
+    // violation when the agent WRITES it — codeContent checks Write/Edit content
+    // only, so this is an action not a mention. Plain words and shell commands
+    // are excluded by isContentToken; protected files already routed above.
+    if (polarity === "forbid") {
+        const contentTokens = [...patterns].filter(isContentToken);
+        if (contentTokens.length > 0) {
+            return { kind: "codeContent", rule, patterns: contentTokens, polarity, polarityInferred };
+        }
+    }
     return { kind: "deterministic", rule, patterns: [...patterns], polarity, polarityInferred };
 }
 export function classifyRules(rules) {

package/dist/cli.js

@@ -13,6 +13,7 @@ import { adviseRules } from "./checkability.js";
 import { shadowedAgentsMd } from "./shadowedAgents.js";
 import { partitionByAge, futureResult } from "./ruleAge.js";
 import { auditSessions, renderComplianceReport } from "./report/complianceReport.js";
+import { auditRules, renderAudit } from "./audit.js";
 import { classifyRules } from "./checks/classify.js";
 import { loadOverrides, saveOverride, clearOverride, staleOverrides, ruleFingerprint, OVERRIDES_PATH } from "./overrides.js";
 import { runDeterministicChecks } from "./checks/deterministicChecks.js";
@@ -891,6 +892,19 @@ program
     const r = await auditSessions(process.cwd(), Number.isFinite(n) ? n : 25);
     console.log(renderComplianceReport(r, Boolean(opts.markdown)));
 });
+program
+    .command("audit")
+    .description("Score your rules files for checkability — NO session needed. How much can be checked mechanically vs needs a human vs is documentation. Works on CLAUDE.md, AGENTS.md, Cursor, Copilot, Windsurf and Gemini rules.")
+    .option("--markdown", "output as markdown, for a report you can send")
+    .option("--json", "output machine-readable JSON (counts and the checkable %)")
+    .action((opts) => {
+    const a = auditRules(loadRules(process.cwd()));
+    if (opts.json) {
+        console.log(JSON.stringify(a, null, 2));
+        return;
+    }
+    console.log(renderAudit(a, Boolean(opts.markdown)));
+});
 program
     .command("digest")
     .description("A non-technical summary of recent check runs (counts only, no rule text) — for a manager who doesn't have time to read 30 individual reports.")

package/dist/rules.js

@@ -62,8 +62,12 @@ function ruleFilesAtLevel(dir) {
     for (const rel of RULE_DIRS)
         found.push(...markdownFilesIn(join(dir, rel)));
     push("CLAUDE.md");
-    if (!has("CLAUDE.md"))
+    // AGENTS.md (and the singular AGENT.md some tools use) are read only when
+    // there's no CLAUDE.md at this level, mirroring Claude Code's shadow rule.
+    if (!has("CLAUDE.md")) {
         push("AGENTS.md");
+        push("AGENT.md");
+    }
     // .local variants: their precedence relative to the base files is not
     // documented, so both are kept rather than guessing at a shadow rule.
     push("CLAUDE.local.md");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "description": "Checks whether your AI coding agent followed your rules, with evidence. Works with Claude Code (Codex in testing); reads CLAUDE.md, AGENTS.md, Cursor, Copilot and Windsurf rules.",
   "repository": {
     "type": "git",