rulereceipt 0.1.27 → 0.1.28

package/README.md

@@ -54,6 +54,13 @@ Published and live on npm, actively developed.
      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.
+
+     When it gets one wrong, `rulereceipt rules --include <handle>` fixes it
+     permanently. The handle is a hash of the rule's own text, not its
+     position, so the correction survives edits elsewhere in the file. That
+     matters more than making the classifier smarter: imperative verbs are
+     not a closed class and the word list is English-only, so it will keep
+     being wrong — it just needs to be correctable.
 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
@@ -76,6 +83,10 @@ rulereceipt check --llm        # opt-in: grade judgment rules with your own Clau
 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 rules              # show corrections you've made to what counts as a rule
+rulereceipt rules --include <handle>   # "this IS a rule" — check it from now on
+rulereceipt rules --exclude <handle>   # "this isn't" — stop reporting it
+rulereceipt rules --coverage   # which rules a configured hook might actually enforce
 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
@@ -88,6 +99,30 @@ rulereceipt verify <session-file> <hash>   # spot-check a report you received ag
 
 `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.
 
+## Which rules actually have teeth
+
+A rule in a file and a rule with a `PreToolUse` hook behind it look identical
+when you read them, and behave completely differently when they're ignored.
+One fails loudly; the other doesn't fail at all.
+
+```bash
+rulereceipt rules --coverage
+```
+
+This lists your rules against the hooks configured on this machine and in the
+project, and tells you which rules name something a *blocking* hook also
+names. Hooks on events that can't refuse anything — `SessionStart`,
+`PostToolUse` — are counted separately, because they can log or inject
+context but can't make a rule fail.
+
+**It reports a possible backing, never a proof, and says so in its own
+output.** A hook's command is usually a path to a script this tool doesn't
+read, so the only evidence available is the event, the matcher, and literal
+text in the command. Both mistakes are possible: a hook can guard a rule
+while sharing no wording with it, and shared wording doesn't mean the hook
+guards it. Treat the links as somewhere to look, and everything else as prose
+until you've checked.
+
 ## Sharing a report
 
 `rulereceipt check --html` writes one self-contained HTML file. No
@@ -159,11 +194,14 @@ 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.
+**Never writes anything you didn't ask for.** RuleReceipt never modifies
+`.claude/settings.json` and installs no hooks. No automatic hooks, ever, in
+v1 — it runs only when you type the command.
+
+Two commands write, both only when you invoke them: `check --html` writes the
+report to the path you name, and `rules --include/--exclude` records a
+correction in `.rulereceipt/overrides.json`. Plain `rulereceipt check` writes
+nothing and makes no network calls.
 
 **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

package/dist/browser/analyze.js

@@ -3,9 +3,9 @@ import { classifyRules } from "../checks/classify.js";
 /** Measured across 559 real public rules files. Shown for comparison. */
 export const CORPUS = {
     files: 559,
-    parsed: 23704,
-    notRulesPct: 64.5,
-    checkablePct: 42.7,
+    parsed: 21986,
+    notRulesPct: 63.4,
+    checkablePct: 44.2,
 };
 function pct(part, whole) {
     return whole === 0 ? 0 : Math.round((part / whole) * 1000) / 10;

package/dist/checks/doctor.d.ts

@@ -3,6 +3,13 @@ export interface HookEntry {
     event: string;
     command: string;
     flags: string[];
+    /**
+     * The matcher the hook is registered under — which tool it fires on, for
+     * tool-call events. Kept because it is the only machine-readable statement
+     * of what a hook watches; the command itself is usually a script path whose
+     * contents this tool does not read.
+     */
+    matcher?: string;
 }
 export interface DoctorResult {
     filesScanned: string[];

package/dist/checks/doctor.js

@@ -38,10 +38,17 @@ function extractHooksFromSettings(filePath) {
             const hookList = matcher?.hooks;
             if (!Array.isArray(hookList))
                 continue;
+            const matcherName = matcher?.matcher;
             for (const h of hookList) {
                 const command = h?.command;
                 if (typeof command === "string") {
-                    entries.push({ sourceFile: filePath, event, command, flags: flagCommand(command) });
+                    entries.push({
+                        sourceFile: filePath,
+                        event,
+                        command,
+                        flags: flagCommand(command),
+                        matcher: typeof matcherName === "string" ? matcherName : undefined,
+                    });
                 }
             }
         }

package/dist/checks/hookCoverage.d.ts

@@ -0,0 +1,59 @@
+import type { Rule } from "../types.js";
+import type { HookEntry } from "./doctor.js";
+/**
+ * Which of your rules has anything behind it?
+ *
+ * Two people arrived at this question independently within a week. From a
+ * dev.to thread: "does the parser separate a rule that's only a sentence from
+ * the same rule with a hook behind it? In a file they look identical, and
+ * only the hooked one fails loudly when it's ignored." And from
+ * anthropics/claude-code#90542, someone with a hook-heavy setup reporting
+ * 13 out of 13 held where enforcement existed, and 1 failure out of 1
+ * opportunity where the same decision was written as prose.
+ *
+ * The tool could already list hooks (`doctor`) and list rules (`check`).
+ * Nothing joined them, so it could tell you what your hooks were and what
+ * your rules were, and not which rules were load-bearing.
+ *
+ * WHAT THIS CANNOT DO, STATED UP FRONT
+ *
+ * It cannot prove a hook enforces a rule. A hook's command is usually a path
+ * to a script this tool does not read, so the only machine-readable evidence
+ * available is the event it fires on, the matcher it is registered under, and
+ * whatever literal text sits in the command string.
+ *
+ * That means both errors are possible and neither is rare:
+ *   - a hook can enforce a rule while sharing no text with it at all
+ *   - sharing text proves nothing about whether the hook actually guards it
+ *
+ * So this reports a POSSIBLE backing and nothing stronger. It is a starting
+ * point for a person who knows their own setup, in the same spirit as
+ * `--show-skipped`: surface what the tool can see, and let the judgement sit
+ * with whoever can actually make it.
+ */
+export type Backing = "possiblyGuarded" | "noHookFound";
+export interface RuleCoverage {
+    rule: Rule;
+    backing: Backing;
+    /** Hooks sharing a literal token with this rule. Empty when noHookFound. */
+    matchedHooks: HookEntry[];
+    /** The tokens that matched, so the user can see WHY it was linked. */
+    sharedTokens: string[];
+}
+export declare function isBlockingEvent(event: string): boolean;
+export declare function distinctiveTokens(text: string): string[];
+/**
+ * Links rules to hooks by shared literal text.
+ *
+ * Only hooks on blocking events are considered: a rule "backed" by a hook
+ * that cannot refuse anything is not backed in the sense being asked about.
+ */
+export declare function correlate(rules: Rule[], hooks: HookEntry[]): RuleCoverage[];
+export interface CoverageSummary {
+    totalRules: number;
+    possiblyGuarded: number;
+    noHookFound: number;
+    blockingHooks: number;
+    nonBlockingHooks: number;
+}
+export declare function summarise(coverage: RuleCoverage[], hooks: HookEntry[]): CoverageSummary;

package/dist/checks/hookCoverage.js

@@ -0,0 +1,96 @@
+/**
+ * Events that can actually refuse something. A hook on an event that cannot
+ * block may still be useful — logging, injecting context — but it cannot make
+ * a rule fail loudly, which is the question being asked here.
+ *
+ * Taken from the documented hook reference. PostToolUse is deliberately
+ * absent: it runs after the call has already succeeded.
+ */
+const BLOCKING_EVENTS = new Set([
+    "PreToolUse",
+    "UserPromptSubmit",
+    "UserPromptExpansion",
+    "Stop",
+    "SubagentStop",
+    "PostToolBatch",
+    "TeammateIdle",
+    "TaskCreated",
+    "TaskCompleted",
+    "ConfigChange",
+    "WorktreeCreate",
+    "PreModelSwitch",
+]);
+export function isBlockingEvent(event) {
+    return BLOCKING_EVENTS.has(event);
+}
+/**
+ * Distinctive literals a rule names: backtick-quoted spans, and bare tokens
+ * that look like a command, path or flag.
+ *
+ * Short and common tokens are dropped. Linking a rule to a hook because both
+ * contain "the" or "test" would produce confident-looking nonsense, which is
+ * worse than reporting nothing — the same reason a text match in this tool
+ * can never produce a confident failure.
+ */
+const MIN_TOKEN_LENGTH = 4;
+const TOO_COMMON = new Set([
+    "test", "tests", "file", "files", "code", "main", "true", "false", "null",
+    "type", "types", "name", "path", "line", "lines", "data", "when", "then",
+    "with", "this", "that", "from", "into", "must", "should", "never", "always",
+    "bash", "node", "json", "yaml", "text", "user", "call", "tool", "hook",
+]);
+export function distinctiveTokens(text) {
+    const found = new Set();
+    for (const [, span] of text.matchAll(/`([^`]{2,80})`/g)) {
+        const cleaned = span.trim().toLowerCase();
+        if (cleaned.length >= MIN_TOKEN_LENGTH && !TOO_COMMON.has(cleaned))
+            found.add(cleaned);
+    }
+    // Bare tokens shaped like a command, path or flag.
+    for (const [, tok] of text.matchAll(/(?:^|\s)(--?[a-z][\w-]{2,}|[\w.-]*\/[\w./*-]+|[\w-]+\.[a-z]{2,4})\b/gi)) {
+        const cleaned = tok.trim().toLowerCase();
+        if (cleaned.length >= MIN_TOKEN_LENGTH && !TOO_COMMON.has(cleaned))
+            found.add(cleaned);
+    }
+    return [...found];
+}
+/**
+ * Links rules to hooks by shared literal text.
+ *
+ * Only hooks on blocking events are considered: a rule "backed" by a hook
+ * that cannot refuse anything is not backed in the sense being asked about.
+ */
+export function correlate(rules, hooks) {
+    const blocking = hooks.filter((h) => isBlockingEvent(h.event));
+    const hookText = blocking.map((h) => ({
+        hook: h,
+        haystack: `${h.command} ${h.matcher ?? ""}`.toLowerCase(),
+    }));
+    return rules.map((rule) => {
+        const tokens = distinctiveTokens(`${rule.title} ${rule.text ?? ""}`);
+        const matchedHooks = [];
+        const sharedTokens = new Set();
+        for (const { hook, haystack } of hookText) {
+            const hits = tokens.filter((t) => haystack.includes(t));
+            if (hits.length > 0) {
+                matchedHooks.push(hook);
+                hits.forEach((h) => sharedTokens.add(h));
+            }
+        }
+        return {
+            rule,
+            backing: matchedHooks.length > 0 ? "possiblyGuarded" : "noHookFound",
+            matchedHooks,
+            sharedTokens: [...sharedTokens],
+        };
+    });
+}
+export function summarise(coverage, hooks) {
+    return {
+        totalRules: coverage.length,
+        possiblyGuarded: coverage.filter((c) => c.backing === "possiblyGuarded").length,
+        noHookFound: coverage.filter((c) => c.backing === "noHookFound").length,
+        blockingHooks: hooks.filter((h) => isBlockingEvent(h.event)).length,
+        nonBlockingHooks: hooks.filter((h) => !isBlockingEvent(h.event)).length,
+    };
+}

package/dist/cli.js

@@ -9,6 +9,7 @@ import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { readLatestTranscript, readTranscriptFromFile, findLatestSessionFile } from "./parsers/transcriptParser.js";
 import { loadRules } from "./rules.js";
 import { classifyRules } from "./checks/classify.js";
+import { loadOverrides, saveOverride, clearOverride, staleOverrides, ruleFingerprint, OVERRIDES_PATH } from "./overrides.js";
 import { runDeterministicChecks } from "./checks/deterministicChecks.js";
 import { runIfEditThenTestChecks } from "./checks/ifEditThenTest.js";
 import { runGitBranchPolicyChecks } from "./checks/gitBranchPolicy.js";
@@ -25,6 +26,7 @@ import { generateDigest } from "./digest.js";
 import { enableSchedule, disableSchedule, scheduleStatus } from "./schedule.js";
 import { findSplitBrainConflicts } from "./checks/splitBrain.js";
 import { runDoctor } from "./checks/doctor.js";
+import { correlate, summarise } from "./checks/hookCoverage.js";
 import { sendTelemetryPing, isTelemetryEnabled } from "./telemetry.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -178,7 +180,33 @@ async function runCheck(opts) {
             return;
         }
     }
-    const classifications = classifyRules(rules);
+    /**
+     * The classifier's guess is corrected here, before anything is checked.
+     *
+     * It looks for a list of English instruction words and is wrong in both
+     * directions: imperative verbs are not a closed class, and the list cannot
+     * match a rule written in another language. This project's own Rule 5 was
+     * filed as documentation and never checked, because it says "say so
+     * explicitly" and `say` is not on the list.
+     *
+     * A rule the user re-includes becomes a judgment result rather than a
+     * confident verdict. Knowing it IS a rule says nothing about which check
+     * can settle it, and guessing would be exactly the behaviour this tool
+     * exists to avoid — so it reports as needing a person, which is honest and
+     * strictly better than being dropped in silence.
+     */
+    const overrides = loadOverrides(cwd);
+    const classifications = classifyRules(rules).map((c) => {
+        const decision = overrides.get(ruleFingerprint(c.rule))?.decision;
+        if (!decision)
+            return c;
+        if (decision === "notARule")
+            return { kind: "notARule", rule: c.rule };
+        return c.kind === "notARule" ? { kind: "judgment", rule: c.rule } : c;
+    });
+    // An override that stopped matching usually means the rule was reworded.
+    // Saying so beats letting someone assume a correction is still in force.
+    const stale = staleOverrides(overrides, rules);
     const deterministic = classifications.filter((c) => c.kind === "deterministic");
     const ifEditThenTest = classifications.filter((c) => c.kind === "ifEditThenTest");
     const gitBranchPolicy = classifications.filter((c) => c.kind === "gitBranchPolicy");
@@ -249,16 +277,29 @@ async function runCheck(opts) {
             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)}`);
+                // The handle is a content hash, never the rule id: ids are positional
+                // and every edit above a rule renumbers it, so a correction keyed on
+                // one would silently reattach itself to a different rule.
+                //
+                // The source is shown because rules are read from the global file as
+                // well as the project's. Without it, someone editing their project
+                // CLAUDE.md to fix an item that came from ~/.claude/CLAUDE.md gets no
+                // explanation for why nothing changed.
+                const where = rule.source === "global" ? " (global)" : "";
+                console.log(`  [${ruleFingerprint(rule)}]${where} ${label.slice(0, 100)}`);
             }
             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.`);
+                `\nlanguage — can land here. Worth a look; you know your rules, it doesn't.` +
+                `\n\nTo fix one permanently:  rulereceipt rules --include <handle>`);
         }
         else {
             console.log(`Run with --show-skipped to see them.`);
         }
     }
+    if (stale.length > 0) {
+        console.log(`\n(${stale.length} saved correction${stale.length === 1 ? "" : "s"} no longer match any rule in this project — the rule was probably reworded. Run \`rulereceipt rules --list\` to see them.)`);
+    }
     appendHistory(results, sessionFilePath);
     if (share) {
         await shareResults(results);
@@ -336,6 +377,131 @@ program
         process.exitCode = 1;
     });
 });
+/**
+ * Corrections to what the classifier thinks is a rule.
+ *
+ * Writes, deliberately and only from here. `check` never writes anything —
+ * a tool that puts files in someone's project without being asked is one
+ * people stop trusting, and that guarantee is worth more than the
+ * convenience of auto-saving a correction.
+ */
+/**
+ * Which rules have a hook behind them, and — said plainly — which of that is
+ * guesswork.
+ *
+ * A hook's command is normally a path to a script this tool does not read, so
+ * the only evidence available is the event, the matcher, and literal text in
+ * the command string. Both error directions are live: a hook can guard a rule
+ * while sharing no wording with it, and shared wording proves nothing. The
+ * output says so every time, because it reads like an audit and people
+ * believe audits.
+ */
+function runCoverage() {
+    const cwd = process.cwd();
+    const rules = loadRules(cwd);
+    if (rules.length === 0) {
+        console.log("No CLAUDE.md or AGENTS.md found, so there are no rules to check hooks against.");
+        return;
+    }
+    const hooks = runDoctor(cwd).hooks;
+    const coverage = correlate(rules, hooks);
+    const s = summarise(coverage, hooks);
+    console.log(`Rule coverage against configured hooks\n`);
+    console.log(`  ${hooks.length} hook${hooks.length === 1 ? "" : "s"} configured · ${s.blockingHooks} can refuse something · ${s.nonBlockingHooks} cannot`);
+    console.log(`  ${s.possiblyGuarded} of ${s.totalRules} rules name something a blocking hook also names`);
+    console.log(`  ${s.noHookFound} of ${s.totalRules} have no hook this can connect them to\n`);
+    const guarded = coverage.filter((c) => c.backing === "possiblyGuarded");
+    if (guarded.length > 0) {
+        console.log(`Possibly guarded:\n`);
+        for (const c of guarded) {
+            console.log(`  ${c.rule.title.replace(/\s+/g, " ").trim().slice(0, 80)}`);
+            for (const h of c.matchedHooks) {
+                // Relative to the working directory when possible: an absolute path
+                // is noise in a report someone may paste elsewhere, and can leak a
+                // home directory name.
+                const where = h.sourceFile.startsWith(cwd) ? h.sourceFile.slice(cwd.length + 1) : h.sourceFile;
+                console.log(`    ${h.event} hook in ${where}${h.matcher ? ` (matcher: ${h.matcher})` : ""}`);
+            }
+            console.log(`    linked on: ${c.sharedTokens.map((t) => `"${t}"`).join(", ")}`);
+            console.log("");
+        }
+    }
+    // Project rules first. Someone running this inside a project can act on
+    // their own rules; the ones from ~/.claude/CLAUDE.md apply everywhere and
+    // are usually not what they came here to look at. Listing global rules
+    // first buried every project rule behind them.
+    const unbacked = coverage
+        .filter((c) => c.backing === "noHookFound")
+        .sort((a, b) => Number(a.rule.source === "global") - Number(b.rule.source === "global"));
+    if (unbacked.length > 0) {
+        const projectCount = unbacked.filter((c) => c.rule.source !== "global").length;
+        console.log(`No hook found for ${unbacked.length} rule${unbacked.length === 1 ? "" : "s"} (${projectCount} in this project), including:\n`);
+        for (const c of unbacked.slice(0, 10)) {
+            const where = c.rule.source === "global" ? " (global)" : "";
+            console.log(`  ${c.rule.title.replace(/\s+/g, " ").trim().slice(0, 76)}${where}`);
+        }
+        if (unbacked.length > 10)
+            console.log(`  ...and ${unbacked.length - 10} more`);
+        console.log("");
+    }
+    console.log(`This is text overlap, and it is not proof. A hook can guard a rule without`);
+    console.log(`sharing any wording with it, and shared wording does not mean the hook`);
+    console.log(`guards it — the command is usually a script this tool does not read. Treat`);
+    console.log(`the links above as somewhere to look, and the rest as prose until you have`);
+    console.log(`checked otherwise.`);
+    if (s.nonBlockingHooks > 0) {
+        console.log(`\nHooks on events that cannot refuse anything were not counted. They can`);
+        console.log(`log or inject context, but they cannot make a rule fail when it is ignored.`);
+    }
+}
+async function runRules(opts) {
+    if (opts.coverage) {
+        runCoverage();
+        return;
+    }
+    const cwd = process.cwd();
+    const rules = loadRules(cwd);
+    const overrides = loadOverrides(cwd);
+    const findRule = (handle) => rules.find((r) => ruleFingerprint(r) === handle);
+    if (opts.include || opts.exclude) {
+        const handle = (opts.include ?? opts.exclude);
+        const decision = opts.include ? "rule" : "notARule";
+        const rule = findRule(handle);
+        if (!rule) {
+            console.error(`No rule in this project has the handle ${handle}.`);
+            console.error(`Handles come from \`rulereceipt check --show-skipped\`, and change if the rule's wording changes.`);
+            process.exitCode = 1;
+            return;
+        }
+        saveOverride(cwd, { hash: handle, decision, title: rule.title.replace(/\s+/g, " ").trim().slice(0, 200) });
+        const verb = opts.include ? "will now be checked" : "will no longer be checked";
+        console.log(`Saved to ${OVERRIDES_PATH}.`);
+        console.log(`  "${rule.title.replace(/\s+/g, " ").trim().slice(0, 90)}" ${verb}.`);
+        if (opts.include) {
+            console.log(`\nIt will report as needing your judgment. Knowing it is a rule says nothing`);
+            console.log(`about which check can settle it, and guessing is what this tool avoids.`);
+        }
+        return;
+    }
+    if (opts.clear) {
+        console.log(clearOverride(cwd, opts.clear) ? `Removed the correction for ${opts.clear}.` : `No correction stored for ${opts.clear}.`);
+        return;
+    }
+    if (overrides.size === 0) {
+        console.log(`No corrections stored for this project.`);
+        console.log(`\nRun \`rulereceipt check --show-skipped\` to see what the classifier excluded,`);
+        console.log(`then \`rulereceipt rules --include <handle>\` for anything that is really a rule.`);
+        return;
+    }
+    const stale = new Set(staleOverrides(overrides, rules).map((o) => o.hash));
+    console.log(`Corrections in ${OVERRIDES_PATH}:\n`);
+    for (const o of overrides.values()) {
+        const mark = o.decision === "rule" ? "checked" : "ignored";
+        const note = stale.has(o.hash) ? "   (no longer matches any rule — reworded?)" : "";
+        console.log(`  ${o.hash}  ${mark.padEnd(8)} ${o.title.slice(0, 70)}${note}`);
+    }
+    console.log(`\nRemove one with:  rulereceipt rules --clear <handle>`);
+}
 async function runLint(markdown, llm) {
     const cwd = process.cwd();
     const claudeMdPath = join(cwd, "CLAUDE.md");
@@ -416,6 +582,20 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("rules")
+    .description("correct what the classifier treats as a rule. Handles come from `check --show-skipped`.")
+    .option("--include <handle>", "treat this item as a real rule and check it from now on")
+    .option("--exclude <handle>", "treat this item as documentation and stop reporting it")
+    .option("--clear <handle>", "remove a stored correction")
+    .option("--list", "show stored corrections (the default when no other flag is given)")
+    .option("--coverage", "show which rules a configured hook might actually be enforcing, and which are prose only")
+    .action((opts) => {
+    runRules(opts).catch((err) => {
+        console.error("Something went wrong:", err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+    });
+});
 program
     .command("lint")
     .description("Find contradictions between this project's CLAUDE.md and AGENTS.md")

package/dist/overrides.d.ts

@@ -0,0 +1,62 @@
+import type { Rule } from "./types.js";
+/**
+ * User corrections to the tool's guess about what counts as a rule.
+ *
+ * The classifier decides which lines in a rules file are genuine instructions
+ * and which are documentation, using a list of English instruction words. It
+ * is wrong in both directions and cannot stop being wrong: imperative verbs
+ * are not a closed class, and an English word list cannot match a rule
+ * written in another language — measured across 559 public files, non-English
+ * content is dropped at 97.5% against a 63.4% baseline.
+ *
+ * This project's own Rule 5, "No silent scope changes", was filed as
+ * documentation and never checked in any report the tool produced, because
+ * the rule says "say so explicitly" and `say` is not on that list.
+ *
+ * So the classifier does not need to be right. It needs to be CORRECTABLE,
+ * and to stay corrected. `--show-skipped` makes a mistake visible; this makes
+ * the fix permanent. That combination has no coverage gap — it needs no API
+ * key, works in any language and any phrasing, and leaves the judgement with
+ * whoever wrote the rules.
+ */
+export type Decision = "rule" | "notARule";
+export interface Override {
+    /** Content hash of the rule — see ruleFingerprint. */
+    hash: string;
+    decision: Decision;
+    /** Stored for humans reading the file, and to explain a stale entry. */
+    title: string;
+}
+export declare const OVERRIDES_PATH: string;
+/**
+ * Identifies a rule by its CONTENT, never by its id or position.
+ *
+ * Rule ids are positional. Editing a rules file renumbers everything after
+ * the edit, and the same is true of any upstream change: a parser fix on
+ * 2026-09-04 shifted the corpus enough that a seeded sample redrawn at the
+ * same seed returned 92 different rules out of 100. An override keyed on
+ * position would silently reattach a decision to a rule nobody ever judged,
+ * which is the exact failure this feature exists to prevent.
+ *
+ * Whitespace is normalised so reflowing a paragraph doesn't drop the
+ * override, but wording is not: if the rule's words change, it is a different
+ * rule and deserves a fresh look.
+ */
+export declare function ruleFingerprint(rule: Rule): string;
+/** Reads overrides for a project. Absent or unreadable file means none. */
+export declare function loadOverrides(cwd: string): Map<string, Override>;
+/**
+ * Writes an override. Only ever called from an explicit command — `check`
+ * never writes anything, which is a stated guarantee of this tool.
+ */
+export declare function saveOverride(cwd: string, entry: Override): void;
+/** Removes an override, returning whether one was actually there. */
+export declare function clearOverride(cwd: string, hash: string): boolean;
+/**
+ * Overrides recorded against rules that are no longer present.
+ *
+ * Surfaced rather than silently ignored: an override that stopped matching
+ * usually means the rule was reworded, and the user should know their
+ * correction is no longer being applied instead of assuming it still is.
+ */
+export declare function staleOverrides(overrides: Map<string, Override>, rules: Rule[]): Override[];

package/dist/overrides.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const OVERRIDES_PATH = join(".rulereceipt", "overrides.json");
+/**
+ * Identifies a rule by its CONTENT, never by its id or position.
+ *
+ * Rule ids are positional. Editing a rules file renumbers everything after
+ * the edit, and the same is true of any upstream change: a parser fix on
+ * 2026-09-04 shifted the corpus enough that a seeded sample redrawn at the
+ * same seed returned 92 different rules out of 100. An override keyed on
+ * position would silently reattach a decision to a rule nobody ever judged,
+ * which is the exact failure this feature exists to prevent.
+ *
+ * Whitespace is normalised so reflowing a paragraph doesn't drop the
+ * override, but wording is not: if the rule's words change, it is a different
+ * rule and deserves a fresh look.
+ */
+export function ruleFingerprint(rule) {
+    const normalised = `${rule.title}\n${rule.text ?? ""}`.replace(/\s+/g, " ").trim();
+    return createHash("sha256").update(normalised).digest("hex").slice(0, 12);
+}
+/** Reads overrides for a project. Absent or unreadable file means none. */
+export function loadOverrides(cwd) {
+    const path = join(cwd, OVERRIDES_PATH);
+    const map = new Map();
+    if (!existsSync(path))
+        return map;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!Array.isArray(parsed?.overrides))
+            return map;
+        for (const o of parsed.overrides) {
+            if (typeof o?.hash === "string" && (o.decision === "rule" || o.decision === "notARule")) {
+                map.set(o.hash, { hash: o.hash, decision: o.decision, title: String(o.title ?? "") });
+            }
+        }
+    }
+    catch {
+        // A corrupt overrides file must not take the whole check down. The user
+        // loses their corrections for this run, which is visible in the report,
+        // rather than losing the report entirely.
+    }
+    return map;
+}
+/**
+ * Writes an override. Only ever called from an explicit command — `check`
+ * never writes anything, which is a stated guarantee of this tool.
+ */
+export function saveOverride(cwd, entry) {
+    const path = join(cwd, OVERRIDES_PATH);
+    const existing = loadOverrides(cwd);
+    existing.set(entry.hash, entry);
+    const out = {
+        version: 1,
+        overrides: [...existing.values()].sort((a, b) => a.hash.localeCompare(b.hash)),
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(out, null, 2)}\n`);
+}
+/** Removes an override, returning whether one was actually there. */
+export function clearOverride(cwd, hash) {
+    const existing = loadOverrides(cwd);
+    if (!existing.delete(hash))
+        return false;
+    const out = {
+        version: 1,
+        overrides: [...existing.values()].sort((a, b) => a.hash.localeCompare(b.hash)),
+    };
+    const path = join(cwd, OVERRIDES_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(out, null, 2)}\n`);
+    return true;
+}
+/**
+ * Overrides recorded against rules that are no longer present.
+ *
+ * Surfaced rather than silently ignored: an override that stopped matching
+ * usually means the rule was reworded, and the user should know their
+ * correction is no longer being applied instead of assuming it still is.
+ */
+export function staleOverrides(overrides, rules) {
+    const live = new Set(rules.map(ruleFingerprint));
+    return [...overrides.values()].filter((o) => !live.has(o.hash));
+}

package/dist/parsers/claudeMdParser.js

@@ -42,9 +42,45 @@ const PLAIN_HEADER = /^#{1,6}\s+(.+)$/;
 const BULLET_ITEM = /^\s*[-*+]\s+(.+)$/;
 const SETEXT_H1_UNDERLINE = /^=+\s*$/;
 const SETEXT_H2_UNDERLINE = /^-{2,}\s*$/;
+/**
+ * A fenced code block is content, not structure.
+ *
+ * Found by auditing 559 real rules files: 588 rules came out holding an
+ * unclosed fence, meaning the parser had split them mid-block. Markdown
+ * headings and bullets appear inside code samples constantly — a shell
+ * comment starts with `#`, a YAML list item starts with `-` — and treating
+ * those as rule boundaries does three things at once. It truncates the real
+ * rule at the fence, it fabricates rules out of the sample's contents, and
+ * it lifts commands out of a "here is what NOT to do" example into a rule
+ * body, where the structured checks can then read them as though they were
+ * the rule itself.
+ *
+ * Matches both fence styles CommonMark allows, and requires the closing
+ * fence to use the same character as the opening one, so a ``` inside a
+ * ~~~ block does not close it.
+ */
+const FENCE_LINE = /^\s*(`{3,}|~{3,})/;
 function normalizeSetextHeaders(lines) {
     const out = [...lines];
+    // Fence-aware for the same reason as the main pass: a row of dashes inside
+    // a code sample is not a setext underline.
+    let inFence = false;
+    let fenceChar = "";
     for (let i = 0; i < out.length - 1; i++) {
+        const fence = out[i].match(FENCE_LINE);
+        if (fence) {
+            const ch = fence[1][0];
+            if (!inFence) {
+                inFence = true;
+                fenceChar = ch;
+            }
+            else if (ch === fenceChar) {
+                inFence = false;
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
         const title = out[i];
         if (title.trim() === "")
             continue;
@@ -101,6 +137,8 @@ export function parseClaudeMdText(raw, source) {
     let sectionCount = 0;
     let sectionId = "S0"; // "S0" before any header is seen; null while a header is pending its first rule
     let bulletIndex = 0;
+    let inFence = false;
+    let fenceChar = "";
     const flush = () => {
         if (current) {
             current.text = bodyLines.join("\n").trim();
@@ -116,7 +154,40 @@ export function parseClaudeMdText(raw, source) {
         }
         return sectionId;
     };
+    /** Adds a line to whatever rule is open, promoting a pending section if needed. */
+    const appendBody = (line) => {
+        if (currentIsMarkedRule) {
+            bodyLines.push(line);
+        }
+        else if (pendingSectionTitle !== null && line.trim() !== "") {
+            current = { id: `${assignSectionId()}.0`, title: pendingSectionTitle, text: "", source };
+            bodyLines = [line];
+            pendingSectionTitle = null;
+        }
+        else if (current) {
+            bodyLines.push(line);
+        }
+    };
     for (const line of lines) {
+        // Fence state is tracked before any structural match, so nothing inside a
+        // code block is ever read as a heading, a bullet, or a rule marker.
+        const fence = line.match(FENCE_LINE);
+        if (fence) {
+            const ch = fence[1][0];
+            if (!inFence) {
+                inFence = true;
+                fenceChar = ch;
+            }
+            else if (ch === fenceChar) {
+                inFence = false;
+            }
+            appendBody(line);
+            continue;
+        }
+        if (inFence) {
+            appendBody(line);
+            continue;
+        }
         const numbered = line.match(NUMBERED_HEADER);
         if (numbered) {
             flush();
@@ -154,17 +225,7 @@ export function parseClaudeMdText(raw, source) {
             }
             continue;
         }
-        if (currentIsMarkedRule) {
-            bodyLines.push(line);
-        }
-        else if (pendingSectionTitle !== null && line.trim() !== "") {
-            current = { id: `${assignSectionId()}.0`, title: pendingSectionTitle, text: "", source };
-            bodyLines = [line];
-            pendingSectionTitle = null;
-        }
-        else if (current) {
-            bodyLines.push(line);
-        }
+        appendBody(line);
     }
     flush();
     if (rules.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",
@@ -38,7 +38,8 @@
     "test:watch": "vitest",
     "lint": "eslint src tests",
     "prepublishOnly": "npm run build && npm test",
-    "build:checker": "esbuild src/browser/analyze.ts --bundle --format=esm --minify --outfile=landing/checker.js"
+    "build:checker": "esbuild src/browser/analyze.ts --bundle --format=esm --minify --outfile=landing/checker.js",
+    "verify": "npm run lint && npm run typecheck && npm test"
   },
   "engines": {
     "node": ">=18"