rulereceipt 0.1.19 → 0.1.21

package/README.md

@@ -1,8 +1,20 @@
 # RuleReceipt
 
+[![CI](https://github.com/rulereceipt/rulereceipt/actions/workflows/ci.yml/badge.svg)](https://github.com/rulereceipt/rulereceipt/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/rulereceipt/rulereceipt/actions/workflows/codeql.yml/badge.svg)](https://github.com/rulereceipt/rulereceipt/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/rulereceipt/rulereceipt/badge)](https://scorecard.dev/viewer/?uri=github.com/rulereceipt/rulereceipt)
+[![npm](https://img.shields.io/npm/v/rulereceipt)](https://www.npmjs.com/package/rulereceipt)
+[![provenance](https://img.shields.io/badge/npm-provenance%20signed-blue)](https://www.npmjs.com/package/rulereceipt#provenance)
+
 Checks whether a Claude Code session actually followed the rules in your
 CLAUDE.md / AGENTS.md — with evidence, not just a vibe.
 
+Every release from 0.1.19 on is built and published by GitHub Actions and
+signed with [npm provenance](https://docs.npmjs.com/generating-provenance-statements),
+so you can verify the published package was built from this repository at
+a specific commit. No publishing token exists to be stolen. Check it
+yourself with `npm audit signatures` after installing.
+
 Licensed source-available software — see [LICENSE](./LICENSE) and
 [NOTICE.md](./NOTICE.md) before reusing this code.
 
@@ -56,6 +68,31 @@ Published and live on npm, actively developed.
    that exact file. (It proves the report matches the file, not that the
    file is an unmodified record — see SECURITY.md.)
 
+## Exit codes
+
+`check` exits **1** when a rule was actually broken, and **0** otherwise,
+so CI can gate on it. Rules that need human judgment report UNCLEAR and
+never affect the exit code — most rules in a real CLAUDE.md need judgment,
+and gating on those would make every build red on day one.
+
+`--exit-zero` prints the report without failing the build. `--require-session`
+does the opposite and is the one to use anywhere automated: it fails when
+there is no session, or an empty one, instead of reporting a pass for a
+check that never actually ran.
+
+### A limit worth knowing before you wire this into CI
+
+Claude Code writes its session transcript to the machine the agent ran on
+— your laptop. A CI runner is a fresh machine that has never seen it, so a
+CI job cannot check a session that happened on your laptop unless you
+deliberately make that transcript available to the job. See
+[templates/rulereceipt-ci.yml](./templates/rulereceipt-ci.yml), which
+explains the options and, if you use it, fails loudly rather than passing
+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.
+
 ## Sharing a report
 
 `rulereceipt check --html` writes one self-contained HTML file. No
@@ -89,6 +126,8 @@ rulereceipt check              # check the latest session in this project
 rulereceipt check --markdown   # same, formatted for pasting into a PR/Slack
 rulereceipt check --html       # write a shareable single-file HTML report you can send
 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 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

@@ -92,6 +92,7 @@ function needsLlmResult(rule) {
         ruleTitle: rule.title,
         ruleSource: rule.source,
         status: "UNCLEAR",
+        needsHuman: true,
         evidence: "NEEDS HUMAN REVIEW — this rule is a judgment call, not something that can be settled by looking at what commands ran. Read the session and decide for yourself. (`--llm` will give you a model's opinion on it, using your own Anthropic key — an opinion, not a verdict.)",
     };
 }
@@ -121,7 +122,7 @@ function writeHtmlReport(results, meta, cwd, target) {
     }
 }
 async function runCheck(opts) {
-    const { markdown, share, email, emailAlways, llm, telemetry, html, transcriptOverride } = opts;
+    const { markdown, share, email, emailAlways, llm, telemetry, html, exitZero, requireSession, transcriptOverride } = opts;
     const cwd = process.cwd();
     const rules = loadRules(cwd);
     if (rules.length === 0) {
@@ -139,9 +140,34 @@ async function runCheck(opts) {
         console.log("No Claude Code session found for this project yet.\n" +
             "Run Claude Code here at least once, then try `rulereceipt check` again — " +
             "or pass --transcript <path-to-.jsonl> directly if your session lives somewhere non-standard.");
+        // Exiting 0 here is right for a person running this locally for the
+        // first time — nothing is wrong, there is simply nothing yet. It is
+        // dangerous anywhere automated, where a silent 0 reads as "checked,
+        // all clear" when nothing was checked at all. --require-session makes
+        // that case fail loudly. See the note in templates/rulereceipt-ci.yml.
+        if (requireSession) {
+            console.error("\n--require-session was set and no session was found, so nothing could be checked. " +
+                "Failing rather than reporting a pass for a check that never ran.");
+            process.exitCode = 1;
+        }
         return;
     }
     const events = transcriptOverride ? readTranscriptFromFile(sessionFilePath) : readLatestTranscript(cwd);
+    // A session file with nothing in it produces a report full of PASSes,
+    // because no forbidden action appears in an empty session. That is
+    // technically true and badly misleading: "we found no proof of
+    // wrongdoing" gets printed as "you're fine." Same shape as the rule this
+    // tool already enforces on itself — an absence of evidence is not
+    // evidence. Say so out loud, and fail where a machine is reading it.
+    if (events.length === 0) {
+        console.log("\n⚠ This session file contains no recorded activity, so there was nothing to check against.\n" +
+            "  Every result below reflects an empty session, not a clean one.");
+        if (requireSession) {
+            console.error("\n--require-session was set and the session was empty. Failing rather than reporting a pass for a check that had no evidence.");
+            process.exitCode = 1;
+            return;
+        }
+    }
     const classifications = classifyRules(rules);
     const deterministic = classifications.filter((c) => c.kind === "deterministic");
     const ifEditThenTest = classifications.filter((c) => c.kind === "ifEditThenTest");
@@ -149,11 +175,22 @@ async function runCheck(opts) {
     const codeContent = classifications.filter((c) => c.kind === "codeContent");
     const fileLifecycle = classifications.filter((c) => c.kind === "fileLifecycle");
     const judgment = classifications.filter((c) => c.kind === "judgment");
-    // Not rules at all — documentation, glossary entries, reference tables.
-    // Measured on 40 real public rule files: ~17% of parsed items. Reported
-    // as a count so nothing is silently dropped, but never checked, since
-    // "did the session violate a directory listing" has no meaningful answer
-    // and any coincidental match is pure noise.
+    // Not rules at all — documentation, glossary entries, reference tables,
+    // URLs, directory listings, code examples.
+    //
+    // Re-measured 2026-08-31 across 40 real public rule files: 943 of 1,441
+    // parsed items, i.e. 65.4%. A previous comment here said ~17%, which was
+    // wrong and made the tool look like it was discarding far less than it
+    // is. Sampled and reviewed by hand before trusting the new figure: the
+    // classification is correct, real rules files simply are mostly prose.
+    //
+    // The number that actually matters is the one about RULES rather than
+    // lines: of the 498 genuine rules in that corpus, 238 (47.8%) are
+    // mechanically answerable and 260 (52.2%) are judgment calls.
+    //
+    // Reported as a count so nothing is silently dropped, but never checked,
+    // since "did the session violate a directory listing" has no meaningful
+    // answer and any coincidental match is pure noise.
     const notARule = classifications.filter((c) => c.kind === "notARule");
     const deterministicResults = [
         ...runDeterministicChecks(deterministic, events),
@@ -201,6 +238,23 @@ async function runCheck(opts) {
     if (isTelemetryEnabled(telemetry)) {
         await sendTelemetryPing();
     }
+    // Exit non-zero when a rule was actually broken, so CI can gate on it.
+    //
+    // This was a real shipped falsehood (found 2026-08-31):
+    // templates/rulereceipt-ci.yml told people to copy a workflow and said
+    // "rulereceipt already exits non-zero on FAIL, this just wires that
+    // into CI" — while `check` always exited 0. Anyone who used that
+    // template had a job that passed even as the agent broke their rules,
+    // which is worse than having no check at all, because it reads as
+    // evidence that nothing went wrong.
+    //
+    // Only FAIL counts. UNCLEAR must not, and that isn't a softening: most
+    // 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.
+    if (!exitZero && results.some((r) => r.status === "FAIL")) {
+        process.exitCode = 1;
+    }
 }
 function runDemo(markdown) {
     const meta = { sessionFilePath: null, ruleCount: DEMO_RESULTS.length };
@@ -222,6 +276,8 @@ program
     .option("--llm", "opt-in: grade rules that need judgment (not just pattern matching) using your own Anthropic key. Without this flag, those rules report UNCLEAR and nothing is sent anywhere — deterministic checks always run with no key regardless.")
     .option("--telemetry", "opt-in: send an anonymous install-count ping (a random per-machine ID, never rule text or results) so real distinct-install counts are knowable. Off by default. DO_NOT_TRACK=1 or RULERECEIPT_NO_TELEMETRY=1 overrides this flag back off.")
     .option("--html [path]", `write a shareable single-file HTML report you can email, attach to a ticket, or print to PDF. Defaults to ./${DEFAULT_HTML_REPORT_NAME}. Written locally — nothing is uploaded.`)
+    .option("--exit-zero", "always exit 0, even when a rule was broken. Without this, `check` exits 1 on any FAIL so CI can gate on it (rules needing human judgment report UNCLEAR and never affect the exit code).")
+    .option("--require-session", "fail (exit 1) if no session is found, or the session is empty, instead of reporting a pass for a check that never actually ran. Use this anywhere automated.")
     .option("--transcript <path>", "manual override: check this exact .jsonl session file instead of auto-detecting one. Useful if your Claude Code session lives somewhere non-standard that auto-detection doesn't cover.")
     .action((opts) => {
     runCheck({
@@ -233,6 +289,8 @@ program
         telemetry: Boolean(opts.telemetry),
         // commander gives `true` for a bare --html and the string for --html <path>
         html: opts.html ?? false,
+        exitZero: Boolean(opts.exitZero),
+        requireSession: Boolean(opts.requireSession),
         transcriptOverride: opts.transcript,
     }).catch((err) => {
         console.error("Something went wrong:", err instanceof Error ? err.message : err);

package/dist/report/generateHtmlReport.js

@@ -25,17 +25,32 @@ function stripControlChars(value) {
 function clean(value) {
     return escapeHtml(stripControlChars(value));
 }
-const STATUS_LABEL = {
+function bucketOf(result) {
+    if (result.status === "FAIL")
+        return "FAIL";
+    if (result.status === "PASS")
+        return "PASS";
+    return result.needsHuman ? "UNCLEAR_JUDGMENT" : "UNCLEAR_EVIDENCE";
+}
+const BUCKET_LABEL = {
     FAIL: "Not followed",
+    UNCLEAR_EVIDENCE: "Couldn't tell",
+    UNCLEAR_JUDGMENT: "Needs your judgment",
     PASS: "Followed",
-    UNCLEAR: "Needs review",
+};
+const BUCKET_CLASS = {
+    FAIL: "fail",
+    UNCLEAR_EVIDENCE: "unclear",
+    UNCLEAR_JUDGMENT: "judgment",
+    PASS: "pass",
 };
 /**
  * Failures first, deliberately. A report that opens with a wall of passes
  * and buries one failure at the bottom is a report designed to be skimmed
- * past — the opposite of what an audit document is for.
+ * past — the opposite of what an audit document is for. Judgment calls
+ * sit last: they're expected, and they're the longest section.
  */
-const STATUS_ORDER = ["FAIL", "UNCLEAR", "PASS"];
+const BUCKET_ORDER = ["FAIL", "UNCLEAR_EVIDENCE", "PASS", "UNCLEAR_JUDGMENT"];
 function ruleLabel(result, all) {
     const collides = all.filter((other) => other.ruleId === result.ruleId).length > 1;
     return collides
@@ -46,24 +61,29 @@ function countBy(results, status) {
     return results.filter((r) => r.status === status).length;
 }
 function renderResultRow(result, all) {
-    const cls = result.status.toLowerCase();
+    const bucket = bucketOf(result);
+    const cls = BUCKET_CLASS[bucket];
     return `
         <article class="result result--${cls}">
           <div class="result__head">
-            <span class="badge badge--${cls}">${clean(STATUS_LABEL[result.status])}</span>
+            <span class="badge badge--${cls}">${clean(BUCKET_LABEL[bucket])}</span>
             <span class="result__id">${clean(ruleLabel(result, all))}</span>
           </div>
           <h3 class="result__title">${clean(result.ruleTitle)}</h3>
           ${result.evidence ? `<p class="result__evidence">${clean(result.evidence)}</p>` : ""}
         </article>`;
 }
-function renderSection(status, results, all) {
-    const inSection = results.filter((r) => r.status === status);
+function renderSection(bucket, results, all) {
+    const inSection = results.filter((r) => bucketOf(r) === bucket);
     if (inSection.length === 0)
         return "";
+    const note = bucket === "UNCLEAR_JUDGMENT"
+        ? `<p class="section__note">These were never questions a tool could settle — they need someone to read the session and decide. That is expected, not a gap in the check.</p>`
+        : "";
     return `
       <section class="section">
-        <h2 class="section__title">${clean(STATUS_LABEL[status])} <span class="section__count">${inSection.length}</span></h2>
+        <h2 class="section__title">${clean(BUCKET_LABEL[bucket])} <span class="section__count">${inSection.length}</span></h2>
+        ${note}
         ${inSection.map((r) => renderResultRow(r, all)).join("")}
       </section>`;
 }
@@ -75,12 +95,22 @@ function renderSection(status, results, all) {
  */
 function verdict(results) {
     const fail = countBy(results, "FAIL");
-    const unclear = countBy(results, "UNCLEAR");
+    const couldntTell = results.filter((r) => bucketOf(r) === "UNCLEAR_EVIDENCE").length;
+    const needsHuman = results.filter((r) => bucketOf(r) === "UNCLEAR_JUDGMENT").length;
     if (fail > 0) {
         return { text: `${fail} rule${fail === 1 ? "" : "s"} not followed`, cls: "fail" };
     }
-    if (unclear > 0) {
-        return { text: `No rule violations found · ${unclear} need human review`, cls: "unclear" };
+    if (couldntTell > 0) {
+        return { text: `No rule violations found · ${couldntTell} couldn't be determined`, cls: "unclear" };
+    }
+    // Judgment rules still appear in the headline. They must not be styled
+    // as a problem — they aren't one — but they must not be omitted either.
+    // "No rule violations found" on its own, when half the rules were never
+    // evaluated mechanically, reads as full coverage. Naming the count is
+    // what keeps the headline from overclaiming, and it is the property the
+    // "does not claim a clean result" test exists to hold.
+    if (needsHuman > 0) {
+        return { text: `No rule violations found · ${needsHuman} still need human review`, cls: "judgment" };
     }
     return { text: "No rule violations found", cls: "pass" };
 }
@@ -117,6 +147,7 @@ export function generateHtmlReport(results, meta) {
   .verdict--fail { background: var(--fail-bg); border-color: #f0c4c6; }
   .verdict--pass { background: var(--pass-bg); border-color: #bfe3cd; }
   .verdict--unclear { background: var(--unclear-bg); border-color: #ecdcb0; }
+  .verdict--judgment { background: var(--panel); border-color: var(--line); }
   .verdict strong { display: block; font-size: 19px; margin-bottom: 2px; }
   .verdict span { color: var(--muted); font-size: 14px; }
   .facts { width: 100%; border-collapse: collapse; margin-bottom: 32px; font-size: 14px; }
@@ -136,6 +167,9 @@ export function generateHtmlReport(results, meta) {
   .badge--fail { background: var(--fail-bg); color: var(--fail); }
   .badge--pass { background: var(--pass-bg); color: var(--pass); }
   .badge--unclear { background: var(--unclear-bg); color: var(--unclear); }
+  .result--judgment { border-left-color: #6b6f76; }
+  .badge--judgment { background: #f2f3f5; color: #4a4e55; }
+  .section__note { font-size: 13px; color: var(--muted); margin: -4px 0 12px; }
   .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; }
@@ -166,7 +200,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 · ${countBy(results, "UNCLEAR")} need review · ${results.length} rules checked</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">
@@ -177,14 +211,15 @@ export function generateHtmlReport(results, meta) {
     <tr><th>Tool version</th><td><code>rulereceipt ${clean(meta.toolVersion)}</code></td></tr>
   </table>
 
-${STATUS_ORDER.map((s) => renderSection(s, results, results)).join("")}
+${BUCKET_ORDER.map((b) => renderSection(b, results, results)).join("")}
 
   <div class="note">
     <h2>How to read this report</h2>
     <ul>
       <li><strong>Followed</strong> — a specific action in the session satisfies the rule, or the forbidden action never occurred.</li>
       <li><strong>Not followed</strong> — a real action in the session contradicts the rule. The evidence quotes it.</li>
-      <li><strong>Needs review</strong> — this rule can't be settled by looking at what commands ran. It is not a pass and not a failure; a person has to read the session and decide.</li>
+      <li><strong>Couldn&#39;t tell</strong> — the check ran and the evidence was ambiguous. A genuine gap.</li>
+      <li><strong>Needs your judgment</strong> — this rule never had a mechanical answer ("surface bad news first"). Not a pass, not a failure, and not a shortcoming of the check: it is the part that was always a person&#39;s call.</li>
     </ul>
     <h2>What this report does not establish</h2>
     <ul>

package/dist/report/generateReport.js

@@ -44,11 +44,32 @@ function ruleLabel(r, results) {
     const collides = results.filter((other) => other.ruleId === r.ruleId).length > 1;
     return collides ? `Rule ${r.ruleId} (${r.ruleSource}) — ${r.ruleTitle}` : `Rule ${r.ruleId} — ${r.ruleTitle}`;
 }
+/**
+ * Separates the two very different things that were both being reported
+ * as "unclear":
+ *
+ *   - couldn't tell  — the tool looked and the evidence was ambiguous.
+ *   - needs you      — a judgment call that never had a mechanical
+ *                      answer ("surface bad news first").
+ *
+ * Collapsing them made the tool look like it failed on most rules. It
+ * doesn't: across 40 real rules files, 52.2% of the actual rules people
+ * write are judgment calls. Those aren't the tool falling short, they're
+ * the half of the work that was always a human's. Naming that honestly is
+ * the difference between a report that reads as broken and one that reads
+ * as a division of labour.
+ */
 function summaryLine(results) {
     const pass = results.filter((r) => r.status === "PASS").length;
     const fail = results.filter((r) => r.status === "FAIL").length;
-    const unclear = results.filter((r) => r.status === "UNCLEAR").length;
-    return `${pass} pass · ${fail} fail · ${unclear} unclear`;
+    const needsHuman = results.filter((r) => r.status === "UNCLEAR" && r.needsHuman).length;
+    const couldntTell = results.filter((r) => r.status === "UNCLEAR" && !r.needsHuman).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`);
+    return parts.join(" · ");
 }
 export function generateReport(results, meta) {
     const clean = results.map(sanitize);
@@ -67,6 +88,31 @@ export function generateReport(results, meta) {
     lines.push(`checked: ${new Date().toISOString()}`);
     return lines.join("\n");
 }
+/**
+ * Makes a value safe to place inside a markdown table cell.
+ *
+ * The previous version escaped only `|`, which broke a real table three
+ * separate ways (first found by CodeQL js/incomplete-sanitization, the
+ * other two while fixing it):
+ *
+ * 1. Backslash was not escaped, so evidence containing a literal `\|`
+ *    became `\\|` — rendering as a backslash followed by a live column
+ *    separator, splitting the row. Backslash must be escaped FIRST, or
+ *    it re-escapes the pipes added afterwards.
+ * 2. The rule TITLE was not escaped at all, so any rule whose title
+ *    contains a pipe broke the table. Titles come from a user's
+ *    CLAUDE.md, and pipes appear naturally in shell examples.
+ * 3. Newlines were not handled. stripControlChars deliberately keeps
+ *    `\n` so multi-line evidence stays readable in the terminal, but a
+ *    newline inside a table cell ends the row and destroys everything
+ *    below it. Rendered as a literal <br> instead.
+ */
+function escapeMarkdownCell(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/\|/g, "\\|")
+        .replace(/\r?\n/g, "<br>");
+}
 export function generateMarkdownReport(results, meta) {
     const clean = results.map(sanitize);
     const lines = [];
@@ -75,8 +121,8 @@ export function generateMarkdownReport(results, meta) {
     lines.push("| Status | Rule | Evidence |");
     lines.push("|---|---|---|");
     for (const r of clean) {
-        const evidence = (r.evidence || "").replace(/\|/g, "\\|");
-        lines.push(`| ${MARK[r.status]} ${r.status} | ${ruleLabel(r, clean)} | ${evidence} |`);
+        const evidence = escapeMarkdownCell(r.evidence || "");
+        lines.push(`| ${MARK[r.status]} ${r.status} | ${escapeMarkdownCell(ruleLabel(r, clean))} | ${evidence} |`);
     }
     lines.push("");
     const hash = computeTranscriptHash(meta.sessionFilePath);

package/dist/telemetry.d.ts

@@ -15,5 +15,15 @@ export declare function isTelemetryEnabled(telemetryFlag: boolean): boolean;
  * session content, or even pass/fail counts (that's what opt-in --share is
  * for). A send failure must never affect the `check` command's own exit
  * code or output; this is best-effort and silent on failure.
+ *
+ * CodeQL flags this as js/file-access-to-http ("outbound network request
+ * depends on file data"), which is technically accurate and not a real
+ * issue: the file it reads is ~/.rulereceipt/telemetry-id, whose entire
+ * contents are a random UUID this tool generated and wrote itself. No
+ * user content, no path, and nothing derived from the session ever
+ * reaches this request. Reviewed and dismissed deliberately rather than
+ * left open — a permanently red alert list is one nobody reads. If the
+ * payload here ever grows beyond `{ id }`, that decision is void and
+ * this needs re-reviewing.
  */
 export declare function sendTelemetryPing(): Promise<void>;

package/dist/telemetry.js

@@ -61,6 +61,16 @@ export function isTelemetryEnabled(telemetryFlag) {
  * session content, or even pass/fail counts (that's what opt-in --share is
  * for). A send failure must never affect the `check` command's own exit
  * code or output; this is best-effort and silent on failure.
+ *
+ * CodeQL flags this as js/file-access-to-http ("outbound network request
+ * depends on file data"), which is technically accurate and not a real
+ * issue: the file it reads is ~/.rulereceipt/telemetry-id, whose entire
+ * contents are a random UUID this tool generated and wrote itself. No
+ * user content, no path, and nothing derived from the session ever
+ * reaches this request. Reviewed and dismissed deliberately rather than
+ * left open — a permanently red alert list is one nobody reads. If the
+ * payload here ever grows beyond `{ id }`, that decision is void and
+ * this needs re-reviewing.
  */
 export async function sendTelemetryPing() {
     const id = getOrCreateTelemetryId();

package/dist/types.d.ts

@@ -32,4 +32,20 @@ export interface CheckResult {
     ruleSource: "global" | "project";
     status: CheckStatus;
     evidence: string;
+    /**
+     * True when this rule was never mechanically answerable — a judgment
+     * call like "surface bad news first", which has no command to inspect.
+     *
+     * Exists because collapsing these into a single UNCLEAR count made the
+     * tool look broken. Measured across 40 real rules files: of the actual
+     * rules people write, 47.8% are mechanically answerable and 52.2% are
+     * judgment calls. Reporting "1 pass · 0 fail · 14 unclear" reads as
+     * fourteen failures, when most of those were a human's call from the
+     * start and the tool is working exactly as intended.
+     *
+     * "I could not determine this" and "this was always yours to decide"
+     * are different statements, and a tool about honest reporting should
+     * not blur them.
+     */
+    needsHuman?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",
@@ -45,16 +45,16 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.32.0",
-    "commander": "^12.1.0",
-    "nodemailer": "^9.0.5"
+    "commander": "^15.0.0",
+    "nodemailer": "^9.0.6"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.4.0",
     "@types/nodemailer": "^8.0.1",
-    "eslint": "^9.0.0",
+    "eslint": "^10.9.1",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
-    "typescript-eslint": "^8.67.0",
+    "typescript-eslint": "^8.68.0",
     "vitest": "^4.1.11"
   }
 }