rulereceipt 0.1.56 → 0.1.58

package/README.md

@@ -76,6 +76,7 @@ Published and live on npm, actively developed.
 ## Usage
 
 ```bash
+rulereceipt audit              # score your rules file for checkability — NO session needed
 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

package/dist/audit.d.ts

@@ -0,0 +1,33 @@
+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;
+    /** The highest-leverage rewrites — a concrete rule missing only its literal. */
+    topFixes: {
+        title: string;
+        suggestion: string;
+    }[];
+}
+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,59 @@
+import { classifyRules } from "./checks/classify.js";
+import { adviseRules } from "./checkability.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;
+    const topFixes = adviseRules(rules)
+        .filter((a) => a.actionable)
+        .slice(0, 5)
+        .map((a) => ({ title: a.ruleTitle, suggestion: a.suggestion }));
+    return {
+        total: checkable + judgment + skipped,
+        checkable,
+        judgment,
+        skipped,
+        percentCheckable: decided > 0 ? Math.round((checkable / decided) * 100) : 0,
+        topFixes,
+    };
+}
+/** 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("");
+    if (a.topFixes.length > 0) {
+        out.push(H("Top fixes to unlock more checks"));
+        for (const f of a.topFixes) {
+            out.push(`  • ${f.title.replace(/\s+/g, " ").trim().slice(0, 60)}`);
+            out.push(`      ${f.suggestion}`);
+        }
+        out.push("");
+    }
+    out.push("Full advice, rule by rule:  rulereceipt rules --advise");
+    return out.join("\n");
+}

package/dist/checkability.d.ts

@@ -22,6 +22,14 @@ export interface RuleAdvice {
     kind: "judgment" | "notARule";
     /** One line: what is missing and the smallest edit that fixes it. */
     suggestion: string;
+    /**
+     * True when there is a concrete, high-leverage rewrite (name the command/
+     * file/branch in backticks) that would turn this into a real check — as
+     * opposed to a genuine judgment call or plain documentation, where the
+     * honest answer is "no edit makes it mechanical." `audit` surfaces the
+     * actionable ones as the top fixes.
+     */
+    actionable?: boolean;
 }
 /**
  * Advice for one rule, or null when the rule is already mechanically checked.

package/dist/checkability.js

@@ -53,6 +53,7 @@ export function adviseRule(rule) {
         return {
             ruleTitle: rule.title,
             kind,
+            actionable: true, // a concrete, high-leverage rewrite: just add the literal
             suggestion: `mentions ${subject} but names no exact term to match. Put the concrete command, file or branch in backticks (e.g. ${exampleFor(subject)}) and it becomes a mechanical check.`,
         };
     }

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.58",
   "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",