rulereceipt 0.1.20 → 0.1.21

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.)",
     };
 }
@@ -174,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),

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);

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