rulereceipt 0.1.57 → 0.1.59

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

@@ -22,6 +22,11 @@ export interface RulesAudit {
     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. */

package/dist/audit.js

@@ -1,4 +1,5 @@
 import { classifyRules } from "./checks/classify.js";
+import { adviseRules } from "./checkability.js";
 export function auditRules(rules) {
     let checkable = 0;
     let judgment = 0;
@@ -12,12 +13,17 @@ export function auditRules(rules) {
             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. */
@@ -39,6 +45,15 @@ export function renderAudit(a, md = false) {
     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");
+    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/checks/pathScope.d.ts

@@ -0,0 +1,5 @@
+import type { TranscriptEvent } from "../types.js";
+export declare function touchedPaths(events: TranscriptEvent[]): string[];
+export declare function globToRegExp(glob: string): RegExp;
+/** True when any touched file matches any of the rule's patterns. */
+export declare function ruleWasLoaded(patterns: string[], touched: string[]): boolean;

package/dist/checks/pathScope.js

@@ -0,0 +1,93 @@
+/**
+ * Path-scoped rules: when does Claude actually see them?
+ *
+ * Claude Code loads a `.claude/rules/*.md` file carrying `paths:` frontmatter
+ * only when the session works on a file matching one of its patterns. Cursor
+ * `.mdc` rules with `globs:` (and agy `.agents/rules` with `trigger: glob`)
+ * behave the same way. A session that never touched a matching file never
+ * had the rule in context, so no verdict about it can be fair.
+ *
+ * Direction of error, deliberately: patterns are matched against every
+ * trailing segment of the absolute path, because the transcript records
+ * absolute paths and the project root is not always known. That can
+ * over-match (treat a rule as loaded when it was not), which falls back to
+ * today's behaviour. It cannot under-match a real file, which is the side
+ * that would hide a real violation.
+ */
+const FILE_TOOLS = {
+    Read: "file_path",
+    Edit: "file_path",
+    MultiEdit: "file_path",
+    Write: "file_path",
+    NotebookEdit: "notebook_path",
+};
+export function touchedPaths(events) {
+    const out = new Set();
+    for (const e of events) {
+        if (e.kind !== "tool_use")
+            continue;
+        const field = FILE_TOOLS[e.toolName];
+        if (!field)
+            continue;
+        const v = e.input?.[field];
+        if (typeof v === "string" && v.length > 0)
+            out.add(v.replace(/\\/g, "/"));
+    }
+    return [...out];
+}
+function expandBraces(glob) {
+    const m = glob.match(/\{([^{}]*)\}/);
+    if (!m || m.index === undefined)
+        return [glob];
+    const head = glob.slice(0, m.index);
+    const tail = glob.slice(m.index + m[0].length);
+    return m[1].split(",").flatMap((alt) => expandBraces(head + alt + tail));
+}
+export function globToRegExp(glob) {
+    let g = glob.trim().replace(/^\.\//, "");
+    if (g.startsWith("/"))
+        g = g.slice(1);
+    if (g.endsWith("/"))
+        g += "**";
+    let re = "";
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        if (c === "*") {
+            if (g[i + 1] === "*") {
+                const slashAfter = g[i + 2] === "/";
+                re += slashAfter ? "(?:.*/)?" : ".*";
+                i += slashAfter ? 2 : 1;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else {
+            re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+function suffixes(path) {
+    const parts = path.split("/").filter(Boolean);
+    const out = [];
+    for (let i = parts.length - 1; i >= 0; i--)
+        out.push(parts.slice(i).join("/"));
+    return out;
+}
+/** True when any touched file matches any of the rule's patterns. */
+export function ruleWasLoaded(patterns, touched) {
+    const regexes = patterns.flatMap(expandBraces).filter((p) => p.trim().length > 0).map(globToRegExp);
+    if (regexes.length === 0)
+        return true; // an empty scope is no scope: treat as always loaded
+    for (const path of touched) {
+        for (const s of suffixes(path)) {
+            if (regexes.some((r) => r.test(s)))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/evaluate.js

@@ -9,6 +9,7 @@ import { runEmojiChecks } from "./checks/emojiOutput.js";
 import { runAttributionChecks } from "./checks/attribution.js";
 import { runApprovalGateChecks } from "./checks/approvalGate.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
+import { touchedPaths, ruleWasLoaded } from "./checks/pathScope.js";
 import { loadOverrides, ruleFingerprint, staleOverrides } from "./overrides.js";
 /**
  * Rules in, verdicts out — the whole pipeline, with no printing in it.
@@ -25,7 +26,8 @@ import { loadOverrides, ruleFingerprint, staleOverrides } from "./overrides.js";
  */
 export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
     const overrides = loadOverrides(cwd);
-    const classifications = classifyRules(rules).map((c) => {
+    const touched = touchedPaths(events);
+    const classified = classifyRules(rules).map((c) => {
         const decision = overrides.get(ruleFingerprint(c.rule))?.decision;
         if (!decision)
             return c;
@@ -33,6 +35,23 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
             return { kind: "notARule", rule: c.rule };
         return c.kind === "notARule" ? { kind: "judgment", rule: c.rule } : c;
     });
+    // A path-scoped rule (paths:/globs: frontmatter) is only loaded by the agent
+    // once the session touches a matching file. One the session never touched is
+    // reported not_applicable with the reason — never judged, so the report
+    // still lists every rule. Over-matches toward "loaded" (see pathScope.ts),
+    // so it can only ever REMOVE a false accusation, never hide a real one.
+    const notLoaded = classified.filter((c) => c.kind !== "notARule" && c.rule.paths && !ruleWasLoaded(c.rule.paths, touched));
+    const classifications = classified.filter((c) => !notLoaded.includes(c));
+    const scopeResults = notLoaded.map(({ rule }) => ({
+        ruleId: rule.id,
+        ruleTitle: rule.title,
+        ruleSource: rule.source,
+        status: "UNCLEAR",
+        outcome: "not_applicable",
+        method: "file_events",
+        reason: "path_scope_not_loaded",
+        evidence: `path-scoped rule (${rule.paths.join(", ")}): this session touched no matching file, so Claude never loaded it`,
+    }));
     const of = (kind) => classifications.filter((c) => c.kind === kind);
     const deterministicResults = [
         ...runDeterministicChecks(of("deterministic"), events),
@@ -50,7 +69,7 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
         ? await runJudgmentChecks(judgment, events)
         : judgment.map(({ rule }) => needsLlmResult(rule));
     return {
-        results: [...deterministicResults, ...judgmentResults],
+        results: [...deterministicResults, ...judgmentResults, ...scopeResults],
         notARule: of("notARule"),
         stale: staleOverrides(overrides, rules),
     };

package/dist/parsers/readClaudeMd.d.ts

@@ -1,2 +1,13 @@
 import type { Rule } from "../types.js";
+/**
+ * Reads the path scope out of a leading frontmatter block, if it has one.
+ *
+ * Shapes seen in 343 real rule files (2026-09-28): `paths:` as a YAML list
+ * or inline array (Claude Code), `globs:` as inline array, comma list, bare
+ * scalar or YAML list (Cursor, agy). `alwaysApply: true` (Cursor) and
+ * `trigger: always_on` (agy) mean the file is always loaded whatever its
+ * globs say, so they clear the scope. Anything unreadable returns undefined,
+ * which means "always loaded": the pre-existing behaviour.
+ */
+export declare function readPathScope(raw: string): string[] | undefined;
 export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];

package/dist/parsers/readClaudeMd.js

@@ -36,6 +36,51 @@ function stripFrontmatter(raw) {
     const after = raw.indexOf("\n", end + 1);
     return after === -1 ? "" : raw.slice(after + 1);
 }
+/**
+ * Reads the path scope out of a leading frontmatter block, if it has one.
+ *
+ * Shapes seen in 343 real rule files (2026-09-28): `paths:` as a YAML list
+ * or inline array (Claude Code), `globs:` as inline array, comma list, bare
+ * scalar or YAML list (Cursor, agy). `alwaysApply: true` (Cursor) and
+ * `trigger: always_on` (agy) mean the file is always loaded whatever its
+ * globs say, so they clear the scope. Anything unreadable returns undefined,
+ * which means "always loaded": the pre-existing behaviour.
+ */
+export function readPathScope(raw) {
+    if (!/^---\r?\n/.test(raw))
+        return undefined;
+    const end = raw.indexOf("\n---", 3);
+    if (end === -1)
+        return undefined;
+    const lines = raw.slice(raw.indexOf("\n") + 1, end).split(/\r?\n/);
+    if (lines.some((l) => /^alwaysApply:\s*true\b/i.test(l) || /^trigger:\s*always_on\b/i.test(l)))
+        return undefined;
+    const unquote = (v) => v.trim().replace(/^["']|["']$/g, "").trim();
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(paths|globs):\s*(.*)$/);
+        if (!m)
+            continue;
+        const value = m[2].trim();
+        let items = [];
+        if (value.startsWith("[")) {
+            items = value.replace(/^\[|\]$/g, "").split(",").map(unquote);
+        }
+        else if (value.length > 0) {
+            items = value.split(",").map(unquote);
+        }
+        else {
+            for (let j = i + 1; j < lines.length && /^\s*-\s+/.test(lines[j]); j++) {
+                items.push(unquote(lines[j].replace(/^\s*-\s+/, "")));
+            }
+        }
+        items = items.filter((x) => x.length > 0);
+        // `**/*` or `*` scopes to everything: same as no scope.
+        if (items.length === 0 || items.some((x) => x === "**/*" || x === "**" || x === "*"))
+            return undefined;
+        return items;
+    }
+    return undefined;
+}
 export function parseClaudeMd(filePath, source) {
     let raw;
     try {
@@ -44,5 +89,7 @@ export function parseClaudeMd(filePath, source) {
     catch {
         return [];
     }
-    return parseClaudeMdText(stripFrontmatter(raw), source);
+    const rules = parseClaudeMdText(stripFrontmatter(raw), source);
+    const paths = readPathScope(raw);
+    return paths ? rules.map((r) => ({ ...r, paths })) : rules;
 }

package/dist/types.d.ts

@@ -3,6 +3,14 @@ export interface Rule {
     title: string;
     text: string;
     source: "global" | "project";
+    /**
+     * Path scope from the rules file's frontmatter (`paths:` in Claude Code
+     * `.claude/rules/*.md`, `globs:` in Cursor `.mdc` / agy `.agents/rules`).
+     * Claude Code only loads a path-scoped rule once the session touches a
+     * matching file, so judging it in a session that never did checks Claude
+     * against a rule it was never shown. Absent = always loaded.
+     */
+    paths?: string[];
 }
 export interface TranscriptTextEvent {
     role: "user" | "assistant";

package/package.json

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