rulereceipt 0.1.23 → 0.1.24

package/README.md

@@ -93,6 +93,38 @@ on a session it never found.
 For most people the honest answer is simpler: run `rulereceipt check --html`
 locally and attach the report to the PR.
 
+## Correcting a misclassification
+
+If the tool treats something in your rules file as a rule when it isn't,
+create `.rulereceipt.json` in your project:
+
+```json
+{
+  "overrides": [
+    { "rule": "12", "reason": "changelog entry, not a rule", "date": "2026-08-31" }
+  ]
+}
+```
+
+Commit it. An override should be visible in code review, not just in the
+report.
+
+**An override cannot hide a violation, by design.** The check still runs,
+keeps its real result, and the override only adds a label. So the report
+shows the rule, its true result, your reason, and a line saying what the
+result would have been without the override. The headline count includes
+overridden failures, and the exit code still fails on them — otherwise CI
+would be the loophole.
+
+The worst an override can do is draw a labelled box around a real
+violation and sign it with your reason. That leaves a reader better
+informed than a plain failure would, not worse.
+
+A reason is required; an override without one is refused rather than
+applied quietly. If a rule id exists in both your global and project
+rules files, write `"project:12"` or `"global:12"` — a bare id that
+matches both is refused rather than silently disabling both.
+
 ## Sharing a report
 
 `rulereceipt check --html` writes one self-contained HTML file. No
@@ -128,6 +160,7 @@ rulereceipt check --html       # write a shareable single-file HTML report you c
 rulereceipt check --html report.html       # ...to a specific path
 rulereceipt check --require-session        # fail if there's no session, instead of passing silently
 rulereceipt check --exit-zero              # report failures without failing the build
+# .rulereceipt.json          # mark a misclassified item as not-a-rule (see below)
 rulereceipt check --llm        # opt-in: grade judgment rules with your own Claude key
 rulereceipt check --share      # opt-in: send anonymous pass/fail/unclear counts
 rulereceipt check --telemetry  # opt-in: send one random per-machine ID

package/dist/cli.js

@@ -26,6 +26,7 @@ import { enableSchedule, disableSchedule, scheduleStatus } from "./schedule.js";
 import { findSplitBrainConflicts } from "./checks/splitBrain.js";
 import { runDoctor } from "./checks/doctor.js";
 import { sendTelemetryPing, isTelemetryEnabled } from "./telemetry.js";
+import { loadOverrides, resolveOverrides } from "./overrides.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 const SHARE_ENDPOINT = "https://rulereceipt.dev/api/share";
@@ -220,7 +221,22 @@ async function runCheck(opts) {
     // sends only a random install ID, never rule text or transcript content,
     // regardless of --llm.
     const judgmentResults = llm ? await runJudgmentChecks(judgment, events) : judgment.map(({ rule }) => needsLlmResult(rule));
-    const results = [...deterministicResults, ...judgmentResults];
+    const computed = [...deterministicResults, ...judgmentResults];
+    // Applied AFTER every check has run, and it only attaches a label.
+    // Nothing is skipped and no status is changed: an override that could
+    // suppress a check would let anyone delete their own violations, which
+    // is precisely what this design refuses to allow. See src/overrides.ts.
+    // Resolved against the rules actually present, and scoped by source: a
+    // global and a project rules file can both define "Rule 1", and a bare
+    // id would otherwise silently disable both.
+    const { bySourceAndId: overrides, problems: overrideProblems } = resolveOverrides(loadOverrides(cwd), computed.map((r) => ({ ruleId: r.ruleId, ruleSource: r.ruleSource })));
+    const results = computed.map((r) => {
+        const o = overrides.get(`${r.ruleSource}:${r.ruleId}`);
+        return o ? { ...r, overriddenReason: o.reason, overriddenDate: o.date } : r;
+    });
+    for (const problem of overrideProblems) {
+        console.log(`\n(${problem})`);
+    }
     const meta = { sessionFilePath, ruleCount: results.length };
     const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta);
     console.log(reportText);
@@ -262,6 +278,9 @@ async function runCheck(opts) {
     // rules in a real CLAUDE.md need judgment, so without --llm they
     // legitimately report UNCLEAR. Gating on those would make every build
     // red on day one and the check would be deleted within a week.
+    // Deliberately reads .status, which an override never changes. If an
+    // overridden failure exited 0, CI would become the loophole this whole
+    // design exists to close: mark the rule, get a green build, done.
     if (!exitZero && results.some((r) => r.status === "FAIL")) {
         process.exitCode = 1;
     }

package/dist/overrides.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Per-project overrides: a way to say "this item in my rules file isn't
+ * actually a rule for my project" without waiting for an upstream release.
+ *
+ * THE SECURITY PROPERTY THAT MAKES THIS SAFE
+ *
+ * An override never changes whether a check runs, and never changes its
+ * result. The check executes exactly as it would have, keeps its real
+ * status, and the override only changes how the result is PRESENTED.
+ *
+ * That distinction is the whole design. The obvious version of this
+ * feature — "let the user mark a rule as not-a-rule, and skip it" — is
+ * not safe, and restricting the direction of the override does not make
+ * it safe:
+ *
+ *     Rule:  "Never commit directly to main"
+ *     Agent: commits directly to main            -> FAIL
+ *     User:  marks it "not a rule"               -> not checked
+ *     Report: the violation is gone
+ *
+ * Nobody had to claim a pass. They deleted the question instead. So this
+ * implementation refuses to delete questions. The worst an override can
+ * do is draw a labelled box around a real violation and sign it with a
+ * reason and a date — which leaves a reader BETTER informed than a plain
+ * failure would, not worse.
+ *
+ * Consequences enforced elsewhere, and deliberately not weakened:
+ *   - the exit code still fails on an overridden violation (cli.ts), or
+ *     CI becomes the loophole this whole design exists to close;
+ *   - the report's headline verdict counts overridden failures, or the
+ *     one line everyone reads would be the one line that lies.
+ *
+ * A reason is mandatory. An override without one is refused, not applied
+ * silently: it costs a sentence to write, and it is the part a reviewer
+ * actually reads.
+ *
+ * AMBIGUOUS IDS FAIL CLOSED. A global CLAUDE.md and a project one can
+ * legitimately both contain a "Rule 1" — the report already disambiguates
+ * those on collision. An override written as `"rule": "1"` when two rules
+ * share that id would silently disable BOTH, including one the user never
+ * meant to touch. Found while testing this feature against a real machine
+ * that has a global rules file. So a bare id is applied only when it is
+ * unambiguous; when it is not, the override is refused and the user is
+ * told to write `"project:1"` or `"global:1"` instead.
+ */
+export declare const OVERRIDES_FILE = ".rulereceipt.json";
+export interface RuleOverride {
+    /** Rule id as it appears in the report, e.g. "12" or "S7.0". */
+    rule: string;
+    /** Why this isn't a rule for this project. Required — never optional. */
+    reason: string;
+    /** Optional ISO date, shown in the report so a reader can judge staleness. */
+    date?: string;
+}
+export interface LoadedOverrides {
+    /** Keyed by the raw id as written by the user ("1" or "project:1"). */
+    byRuleId: Map<string, RuleOverride>;
+    /** Problems worth telling the user about — malformed entries, missing reasons. */
+    problems: string[];
+}
+/** A rule as the report identifies it, used to resolve an override target. */
+export interface OverrideTarget {
+    ruleId: string;
+    ruleSource: "global" | "project";
+}
+/**
+ * Resolves override entries against the rules actually present, and
+ * refuses anything ambiguous rather than guessing which rule was meant.
+ * Returns a lookup keyed by `${source}:${id}`, plus any new problems.
+ */
+export declare function resolveOverrides(loaded: LoadedOverrides, targets: OverrideTarget[]): {
+    bySourceAndId: Map<string, RuleOverride>;
+    problems: string[];
+};
+/**
+ * Reads and validates the override file. Never throws: a broken override
+ * file must not take down a check that would otherwise have worked, and
+ * an unreadable file means "no overrides", never "override everything".
+ * Every rejection is reported rather than swallowed, so a user whose
+ * override isn't working finds out why.
+ */
+export declare function loadOverrides(cwd: string): LoadedOverrides;

package/dist/overrides.js

@@ -0,0 +1,134 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Per-project overrides: a way to say "this item in my rules file isn't
+ * actually a rule for my project" without waiting for an upstream release.
+ *
+ * THE SECURITY PROPERTY THAT MAKES THIS SAFE
+ *
+ * An override never changes whether a check runs, and never changes its
+ * result. The check executes exactly as it would have, keeps its real
+ * status, and the override only changes how the result is PRESENTED.
+ *
+ * That distinction is the whole design. The obvious version of this
+ * feature — "let the user mark a rule as not-a-rule, and skip it" — is
+ * not safe, and restricting the direction of the override does not make
+ * it safe:
+ *
+ *     Rule:  "Never commit directly to main"
+ *     Agent: commits directly to main            -> FAIL
+ *     User:  marks it "not a rule"               -> not checked
+ *     Report: the violation is gone
+ *
+ * Nobody had to claim a pass. They deleted the question instead. So this
+ * implementation refuses to delete questions. The worst an override can
+ * do is draw a labelled box around a real violation and sign it with a
+ * reason and a date — which leaves a reader BETTER informed than a plain
+ * failure would, not worse.
+ *
+ * Consequences enforced elsewhere, and deliberately not weakened:
+ *   - the exit code still fails on an overridden violation (cli.ts), or
+ *     CI becomes the loophole this whole design exists to close;
+ *   - the report's headline verdict counts overridden failures, or the
+ *     one line everyone reads would be the one line that lies.
+ *
+ * A reason is mandatory. An override without one is refused, not applied
+ * silently: it costs a sentence to write, and it is the part a reviewer
+ * actually reads.
+ *
+ * AMBIGUOUS IDS FAIL CLOSED. A global CLAUDE.md and a project one can
+ * legitimately both contain a "Rule 1" — the report already disambiguates
+ * those on collision. An override written as `"rule": "1"` when two rules
+ * share that id would silently disable BOTH, including one the user never
+ * meant to touch. Found while testing this feature against a real machine
+ * that has a global rules file. So a bare id is applied only when it is
+ * unambiguous; when it is not, the override is refused and the user is
+ * told to write `"project:1"` or `"global:1"` instead.
+ */
+export const OVERRIDES_FILE = ".rulereceipt.json";
+/**
+ * Resolves override entries against the rules actually present, and
+ * refuses anything ambiguous rather than guessing which rule was meant.
+ * Returns a lookup keyed by `${source}:${id}`, plus any new problems.
+ */
+export function resolveOverrides(loaded, targets) {
+    const bySourceAndId = new Map();
+    const problems = [...loaded.problems];
+    for (const [written, entry] of loaded.byRuleId) {
+        const scoped = /^(global|project):(.+)$/i.exec(written);
+        if (scoped) {
+            const source = scoped[1].toLowerCase();
+            const id = scoped[2].trim();
+            const hit = targets.find((t) => t.ruleId === id && t.ruleSource === source);
+            if (!hit) {
+                problems.push(`${OVERRIDES_FILE}: no ${source} rule with id "${id}" was found, so that override did nothing.`);
+                continue;
+            }
+            bySourceAndId.set(`${source}:${id}`, entry);
+            continue;
+        }
+        const matches = targets.filter((t) => t.ruleId === written);
+        if (matches.length === 0) {
+            problems.push(`${OVERRIDES_FILE}: no rule with id "${written}" was found, so that override did nothing.`);
+            continue;
+        }
+        const sources = new Set(matches.map((m) => m.ruleSource));
+        if (sources.size > 1) {
+            problems.push(`${OVERRIDES_FILE}: rule id "${written}" exists in BOTH your global and project rules, so the override was NOT applied — it would have silently disabled both. Write "project:${written}" or "global:${written}" instead.`);
+            continue;
+        }
+        bySourceAndId.set(`${[...sources][0]}:${written}`, entry);
+    }
+    return { bySourceAndId, problems };
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.trim().length > 0;
+}
+/**
+ * Reads and validates the override file. Never throws: a broken override
+ * file must not take down a check that would otherwise have worked, and
+ * an unreadable file means "no overrides", never "override everything".
+ * Every rejection is reported rather than swallowed, so a user whose
+ * override isn't working finds out why.
+ */
+export function loadOverrides(cwd) {
+    const byRuleId = new Map();
+    const problems = [];
+    const path = join(cwd, OVERRIDES_FILE);
+    if (!existsSync(path))
+        return { byRuleId, problems };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        problems.push(`${OVERRIDES_FILE} isn't valid JSON, so no overrides were applied: ${err instanceof Error ? err.message : String(err)}`);
+        return { byRuleId, problems };
+    }
+    const raw = parsed?.overrides;
+    if (raw === undefined)
+        return { byRuleId, problems };
+    if (!Array.isArray(raw)) {
+        problems.push(`${OVERRIDES_FILE}: "overrides" must be an array, so no overrides were applied.`);
+        return { byRuleId, problems };
+    }
+    for (const [i, entry] of raw.entries()) {
+        const e = entry;
+        if (!isNonEmptyString(e?.rule)) {
+            problems.push(`${OVERRIDES_FILE} entry ${i + 1}: missing a "rule" id, so it was ignored.`);
+            continue;
+        }
+        // Fails closed, on purpose. An override with no stated reason is the
+        // exact shape of one added to make a number go away.
+        if (!isNonEmptyString(e?.reason)) {
+            problems.push(`${OVERRIDES_FILE} entry for rule ${e.rule}: no "reason" given, so it was NOT applied. Every override needs a reason a reviewer can read.`);
+            continue;
+        }
+        byRuleId.set(e.rule.trim(), {
+            rule: e.rule.trim(),
+            reason: e.reason.trim(),
+            date: isNonEmptyString(e.date) ? e.date.trim() : undefined,
+        });
+    }
+    return { byRuleId, problems };
+}

package/dist/report/generateHtmlReport.js

@@ -103,6 +103,13 @@ function renderResultRow(result, all) {
           </div>
           <h3 class="result__title">${clean(result.ruleTitle)}</h3>
           ${result.evidence ? `<p class="result__evidence">${clean(result.evidence)}</p>` : ""}
+          ${result.overriddenReason
+        ? `<div class="override">
+            <strong>Marked by the developer as &ldquo;not a rule for this project&rdquo;${result.overriddenDate ? ` on ${clean(result.overriddenDate)}` : ""}.</strong>
+            Reason given: ${clean(result.overriddenReason)}
+            <span class="override__truth">Without this override, the result is: <strong>${clean(BUCKET_LABEL[bucketOf({ ...result, overriddenReason: undefined })])}</strong></span>
+          </div>`
+        : ""}
         </article>`;
 }
 function renderSection(bucket, results, all) {
@@ -202,6 +209,9 @@ export function generateHtmlReport(results, meta) {
   .result--judgment { border-left-color: #6b6f76; }
   .badge--judgment { background: #f2f3f5; color: #4a4e55; }
   .section__note { font-size: 13px; color: var(--muted); margin: -4px 0 12px; }
+  .override { margin-top: 10px; padding: 10px 12px; border-radius: 6px; background: var(--unclear-bg); border: 1px solid var(--unclear-line); font-size: 13.5px; color: var(--ink-soft); }
+  .override strong { color: var(--ink); }
+  .override__truth { display: block; margin-top: 6px; }
   .result__id { font-size: 12px; color: var(--muted); }
   .result__title { font-size: 15px; margin: 0 0 6px; font-weight: 600; }
   .result__evidence { margin: 0; font-size: 14px; color: var(--muted); white-space: pre-wrap; }
@@ -232,7 +242,7 @@ export function generateHtmlReport(results, meta) {
 
   <div class="verdict verdict--${v.cls}">
     <strong>${clean(v.text)}</strong>
-    <span>${countBy(results, "PASS")} followed · ${countBy(results, "FAIL")} not followed · ${results.filter((r) => bucketOf(r) === "UNCLEAR_EVIDENCE").length} couldn&#39;t tell · ${results.filter((r) => bucketOf(r) === "UNCLEAR_JUDGMENT").length} need your judgment</span>
+    <span>${countBy(results, "PASS")} followed · ${countBy(results, "FAIL")} not followed · ${results.filter((r) => bucketOf(r) === "UNCLEAR_EVIDENCE").length} couldn&#39;t tell · ${results.filter((r) => bucketOf(r) === "UNCLEAR_JUDGMENT").length} need your judgment${results.filter((r) => r.overriddenReason).length > 0 ? ` · ${results.filter((r) => r.overriddenReason).length} developer-overridden` : ""}</span>
   </div>
 
   <table class="facts">

package/dist/report/generateReport.js

@@ -64,11 +64,21 @@ function summaryLine(results) {
     const fail = results.filter((r) => r.status === "FAIL").length;
     const needsHuman = results.filter((r) => r.status === "UNCLEAR" && r.needsHuman).length;
     const couldntTell = results.filter((r) => r.status === "UNCLEAR" && !r.needsHuman).length;
+    const overriddenFails = results.filter((r) => r.status === "FAIL" && r.overriddenReason).length;
+    const overridden = results.filter((r) => r.overriddenReason).length;
     const parts = [`${pass} followed`, `${fail} not followed`];
     if (couldntTell > 0)
         parts.push(`${couldntTell} couldn't tell`);
     if (needsHuman > 0)
         parts.push(`${needsHuman} need your judgment`);
+    // Named in the one line everyone reads. A headline that quietly folded
+    // overridden failures into a clean total would be the single most
+    // misleading thing this tool could print.
+    if (overridden > 0) {
+        parts.push(overriddenFails > 0
+            ? `${overridden} user-overridden (${overriddenFails} still not followed)`
+            : `${overridden} user-overridden`);
+    }
     return parts.join(" · ");
 }
 export function generateReport(results, meta) {
@@ -80,6 +90,15 @@ export function generateReport(results, meta) {
         lines.push(`${MARK[r.status]} ${r.status.padEnd(7)} ${ruleLabel(r, clean)}`);
         if (r.evidence)
             lines.push(`  evidence: ${r.evidence}`);
+        // The true status is printed above, unchanged. This line adds the
+        // override on top of it rather than replacing it — a reader must be
+        // able to see what the result would have been without the override.
+        if (r.overriddenReason) {
+            lines.push(`  USER-OVERRIDDEN as "not a rule for this project"${r.overriddenDate ? ` on ${r.overriddenDate}` : ""} — reason: ${r.overriddenReason}`);
+            if (r.status === "FAIL") {
+                lines.push("  NOTE: this rule was NOT FOLLOWED. The override does not change that.");
+            }
+        }
     }
     lines.push("─".repeat(40));
     lines.push(summaryLine(clean));

package/dist/types.d.ts

@@ -32,6 +32,15 @@ export interface CheckResult {
     ruleSource: "global" | "project";
     status: CheckStatus;
     evidence: string;
+    /**
+     * Set when the user marked this rule as "not a rule for my project" in
+     * .rulereceipt.json. The status above is STILL the real, computed
+     * result — an override changes presentation only, never the answer.
+     * See src/overrides.ts for why that distinction is the whole design.
+     */
+    overriddenReason?: string;
+    /** Optional date from the override entry, so a reader can judge staleness. */
+    overriddenDate?: string;
     /**
      * True when this rule was never mechanically answerable — a judgment
      * call like "surface bad news first", which has no command to inspect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",