rulereceipt 0.1.56 → 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/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.56",
+  "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",