rulereceipt 0.1.24 → 0.1.26

package/README.md

@@ -93,38 +93,6 @@ 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
@@ -160,7 +128,6 @@ 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/browser/analyze.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Entry point for the in-browser checker on the site.
+ *
+ * The privacy claim on that page — "your file never leaves this page" — is
+ * only true because everything reachable from here is pure string work.
+ * parseClaudeMdText and classifyRules touch no Node API, no network, and
+ * no storage. If anything in this dependency chain ever gains an import
+ * that does, the page's claim becomes false and must change with it.
+ *
+ * Deliberately returns counts and a small sample, never the file: nothing
+ * here should make it easy to accidentally send the text somewhere.
+ */
+export interface Breakdown {
+    kind: string;
+    count: number;
+}
+export interface AnalysisResult {
+    /** Everything the parser pulled out of the file, rules and non-rules alike. */
+    parsed: number;
+    /** Items carrying no instruction — documentation, tables, listings. */
+    notRules: number;
+    /** Items that are genuinely directives. */
+    realRules: number;
+    /** Real rules a check can answer by looking at what ran. */
+    checkable: number;
+    /** Real rules that need a person. */
+    judgment: number;
+    /** Share of the whole file that isn't an instruction, 0-100. */
+    notRulesPct: number;
+    /** Share of REAL rules that are mechanically answerable, 0-100. */
+    checkablePct: number;
+    byKind: Breakdown[];
+    /** A few non-rule titles, so the number is inspectable rather than asserted. */
+    notRuleSamples: string[];
+    /** A few judgment-call titles, same reason. */
+    judgmentSamples: string[];
+}
+/** Measured across 559 real public rules files. Shown for comparison. */
+export declare const CORPUS: {
+    files: number;
+    parsed: number;
+    notRulesPct: number;
+    checkablePct: number;
+};
+export declare function analyze(text: string): AnalysisResult;

package/dist/browser/analyze.js

@@ -0,0 +1,49 @@
+import { parseClaudeMdText } from "../parsers/claudeMdParser.js";
+import { classifyRules } from "../checks/classify.js";
+/** Measured across 559 real public rules files. Shown for comparison. */
+export const CORPUS = {
+    files: 559,
+    parsed: 23704,
+    notRulesPct: 62.9,
+    checkablePct: 43.5,
+};
+function pct(part, whole) {
+    return whole === 0 ? 0 : Math.round((part / whole) * 1000) / 10;
+}
+export function analyze(text) {
+    const rules = parseClaudeMdText(text, "project");
+    const classified = classifyRules(rules);
+    const counts = new Map();
+    const notRuleSamples = [];
+    const judgmentSamples = [];
+    for (const c of classified) {
+        counts.set(c.kind, (counts.get(c.kind) ?? 0) + 1);
+        const title = c.rule.title.trim();
+        if (!title)
+            continue;
+        if (c.kind === "notARule" && notRuleSamples.length < 4)
+            notRuleSamples.push(title);
+        if (c.kind === "judgment" && judgmentSamples.length < 4)
+            judgmentSamples.push(title);
+    }
+    const parsed = classified.length;
+    const notRules = counts.get("notARule") ?? 0;
+    const judgment = counts.get("judgment") ?? 0;
+    const realRules = parsed - notRules;
+    const checkable = realRules - judgment;
+    const byKind = [...counts.entries()]
+        .map(([kind, count]) => ({ kind, count }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        parsed,
+        notRules,
+        realRules,
+        checkable,
+        judgment,
+        notRulesPct: pct(notRules, parsed),
+        checkablePct: pct(checkable, realRules),
+        byKind,
+        notRuleSamples,
+        judgmentSamples,
+    };
+}

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { join, dirname, resolve, isAbsolute } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { parseClaudeMd } from "./parsers/claudeMdParser.js";
+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";
@@ -26,7 +26,6 @@ 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";
@@ -221,22 +220,7 @@ 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 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 results = [...deterministicResults, ...judgmentResults];
     const meta = { sessionFilePath, ruleCount: results.length };
     const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta);
     console.log(reportText);
@@ -278,9 +262,6 @@ 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/parsers/claudeMdParser.d.ts

@@ -1,2 +1,11 @@
 import type { Rule } from "../types.js";
-export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];
+/**
+ * The actual parser, taking text rather than a path.
+ *
+ * Split out from parseClaudeMd so the parsing logic carries no filesystem
+ * dependency and can run anywhere a string can — including a browser, for
+ * the client-side checker on the site. That checker's privacy claim
+ * ("your file never leaves the page") is only true because nothing in
+ * this function or in classify.ts touches Node APIs; keep it that way.
+ */
+export declare function parseClaudeMdText(raw: string, source: "global" | "project"): Rule[];

package/dist/parsers/claudeMdParser.js

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 /**
  * Real CLAUDE.md/AGENTS.md files use several different conventions for
  * organizing rules. Verified against real files and templates: Anthropic's
@@ -67,14 +66,16 @@ function normalizeSetextHeaders(lines) {
     }
     return out;
 }
-export function parseClaudeMd(filePath, source) {
-    let raw;
-    try {
-        raw = readFileSync(filePath, "utf-8");
-    }
-    catch {
-        return [];
-    }
+/**
+ * The actual parser, taking text rather than a path.
+ *
+ * Split out from parseClaudeMd so the parsing logic carries no filesystem
+ * dependency and can run anywhere a string can — including a browser, for
+ * the client-side checker on the site. That checker's privacy claim
+ * ("your file never leaves the page") is only true because nothing in
+ * this function or in classify.ts touches Node APIs; keep it that way.
+ */
+export function parseClaudeMdText(raw, source) {
     const lines = normalizeSetextHeaders(raw.split("\n"));
     const rules = [];
     // `current` accumulates a numbered-header rule, a bold-rule-header rule,

package/dist/parsers/readClaudeMd.d.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types.js";
+/**
+ * The filesystem half of rules-file parsing, deliberately kept in its own
+ * module.
+ *
+ * claudeMdParser.ts must stay free of Node imports so it can be bundled
+ * for the browser — the in-page checker on the site claims the pasted file
+ * never leaves the page, and that is only true while nothing reachable
+ * from the parser can perform I/O. Keeping the one readFileSync here
+ * means a bundler cannot pull `node:fs` in behind it, and a future import
+ * that breaks the guarantee has to be added here, visibly, rather than
+ * appearing by accident in the parser.
+ */
+/**
+ * Reads a rules file from disk. Thin wrapper: an unreadable file is an
+ * empty rule list, never a throw, because a missing global CLAUDE.md is a
+ * normal state rather than an error.
+ */
+export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];

package/dist/parsers/readClaudeMd.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { parseClaudeMdText } from "./claudeMdParser.js";
+/**
+ * The filesystem half of rules-file parsing, deliberately kept in its own
+ * module.
+ *
+ * claudeMdParser.ts must stay free of Node imports so it can be bundled
+ * for the browser — the in-page checker on the site claims the pasted file
+ * never leaves the page, and that is only true while nothing reachable
+ * from the parser can perform I/O. Keeping the one readFileSync here
+ * means a bundler cannot pull `node:fs` in behind it, and a future import
+ * that breaks the guarantee has to be added here, visibly, rather than
+ * appearing by accident in the parser.
+ */
+/**
+ * Reads a rules file from disk. Thin wrapper: an unreadable file is an
+ * empty rule list, never a throw, because a missing global CLAUDE.md is a
+ * normal state rather than an error.
+ */
+export function parseClaudeMd(filePath, source) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    return parseClaudeMdText(raw, source);
+}

package/dist/report/generateHtmlReport.js

@@ -103,13 +103,6 @@ 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) {
@@ -209,9 +202,6 @@ 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; }
@@ -242,7 +232,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${results.filter((r) => r.overriddenReason).length > 0 ? ` · ${results.filter((r) => r.overriddenReason).length} developer-overridden` : ""}</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</span>
   </div>
 
   <table class="facts">

package/dist/report/generateReport.js

@@ -64,21 +64,11 @@ 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) {
@@ -90,15 +80,6 @@ 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/rules.d.ts

@@ -5,5 +5,15 @@ import type { Rule } from "./types.js";
  * global CLAUDE.md under its own home dir (e.g. ~/.claude-office/CLAUDE.md).
  * Real gap found 2026-08-30, same root cause as the transcript-lookup fix
  * in transcriptParser.ts: hardcoding one home-dir name misses any variant.
+ *
+ * Also reads ~/.claude/rules/*.md, the documented location for personal
+ * rules that apply across every project.
+ *
+ * NOT covered, and stated rather than left silent: machine-wide managed
+ * enterprise policy files (/Library/Application Support/ClaudeCode,
+ * /etc/claude-code, C:\Program Files\ClaudeCode). Those are deployed by
+ * IT, exist on no development machine this can be tested against, and
+ * guessing at their location would be the kind of unverified assumption
+ * this project has already been bitten by twice.
  */
 export declare function loadRules(cwd: string): Rule[];

package/dist/rules.js

@@ -1,9 +1,62 @@
 import { homedir } from "node:os";
 import { dirname, join, parse } from "node:path";
-import { existsSync } from "node:fs";
-import { parseClaudeMd } from "./parsers/claudeMdParser.js";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { findClaudeHomeDirNames } from "./parsers/transcriptParser.js";
-const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md"];
+/**
+ * Every place Claude Code actually reads a rule from, at one directory
+ * level. Order mirrors the documented load order, broadest first.
+ *
+ * Real gap found 2026-09-02: only the two bare filenames were read. A
+ * project with four rules files reported "1 rules checked · all passed" —
+ * three files invisible, with nothing saying so. A clean report on rules
+ * the tool never opened is the most misleading result this can produce,
+ * worse than no report, because it looks like evidence.
+ */
+const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", "AGENTS.local.md"];
+const RULE_SUBDIR_FILES = [join(".claude", "CLAUDE.md"), join(".claude", "AGENTS.md")];
+const RULE_DIRS = [join(".claude", "rules")];
+/**
+ * Lists the markdown files in a rules directory, if it exists.
+ *
+ * Sorted so the same project always produces the same rule order — rule
+ * ids are positional, and an unstable order would renumber rules between
+ * runs on different machines, making two reports of the same session
+ * impossible to compare. Non-markdown files are skipped: a rules
+ * directory legitimately holds README fragments and notes.
+ */
+function markdownFilesIn(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        if (!statSync(dir).isDirectory())
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.toLowerCase().endsWith(".md"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/** Every rules file at one directory level, in documented load order. */
+function ruleFilesAtLevel(dir) {
+    const found = [];
+    for (const rel of RULE_SUBDIR_FILES) {
+        const p = join(dir, rel);
+        if (existsSync(p))
+            found.push(p);
+    }
+    for (const rel of RULE_DIRS)
+        found.push(...markdownFilesIn(join(dir, rel)));
+    for (const name of RULE_FILE_NAMES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            found.push(p);
+    }
+    return found;
+}
 /**
  * Walks from the working directory up toward the repository root,
  * collecting rules files at every level.
@@ -25,11 +78,7 @@ function findProjectRuleFiles(cwd) {
     const home = homedir();
     let dir = cwd;
     for (;;) {
-        for (const name of RULE_FILE_NAMES) {
-            const p = join(dir, name);
-            if (existsSync(p))
-                found.push(p);
-        }
+        found.push(...ruleFilesAtLevel(dir));
         // stop AT the repo root (inclusive) — its rules do apply
         if (existsSync(join(dir, ".git")))
             break;
@@ -48,9 +97,26 @@ function findProjectRuleFiles(cwd) {
  * global CLAUDE.md under its own home dir (e.g. ~/.claude-office/CLAUDE.md).
  * Real gap found 2026-08-30, same root cause as the transcript-lookup fix
  * in transcriptParser.ts: hardcoding one home-dir name misses any variant.
+ *
+ * Also reads ~/.claude/rules/*.md, the documented location for personal
+ * rules that apply across every project.
+ *
+ * NOT covered, and stated rather than left silent: machine-wide managed
+ * enterprise policy files (/Library/Application Support/ClaudeCode,
+ * /etc/claude-code, C:\Program Files\ClaudeCode). Those are deployed by
+ * IT, exist on no development machine this can be tested against, and
+ * guessing at their location would be the kind of unverified assumption
+ * this project has already been bitten by twice.
  */
 export function loadRules(cwd) {
-    const rules = findClaudeHomeDirNames().flatMap((dirName) => parseClaudeMd(join(homedir(), dirName, "CLAUDE.md"), "global"));
+    const rules = [];
+    for (const dirName of findClaudeHomeDirNames()) {
+        const base = join(homedir(), dirName);
+        rules.push(...parseClaudeMd(join(base, "CLAUDE.md"), "global"));
+        for (const file of markdownFilesIn(join(base, "rules"))) {
+            rules.push(...parseClaudeMd(file, "global"));
+        }
+    }
     for (const path of findProjectRuleFiles(cwd)) {
         rules.push(...parseClaudeMd(path, "project"));
     }

package/dist/types.d.ts

@@ -32,15 +32,6 @@ 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.24",
+  "version": "0.1.26",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",

package/dist/overrides.d.ts

@@ -1,82 +0,0 @@
-/**
- * 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

@@ -1,134 +0,0 @@
-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 };
-}