rulereceipt 0.1.84 → 0.1.85

package/dist/breakContext.d.ts

@@ -30,6 +30,13 @@ export interface BreakContext {
     rulesInContext: boolean;
     /** Did a compaction occur before the break? */
     compactionBefore: boolean;
+    /**
+     * Did the transcript show ANY context-injection machinery (a system-reminder,
+     * a claudeMd/instructions attachment, a compaction)? When false, the log is
+     * too thin to tell whether the rules file was loaded — so "rules not in
+     * context" would be a guess, and the caller must treat it as can't-tell.
+     */
+    contextObserved: boolean;
     /**
      * The rules file was in context earlier, but its last appearance was BEFORE
      * the last compaction and it was not re-injected after — so the summary may

package/dist/breakContext.js

@@ -27,6 +27,11 @@
 // and the structural claudeMd attachment (escaped or not inside a JSONL line).
 const RULES_INJECTION = /Contents of [^\n"]*(?:CLAUDE|AGENTS|GEMINI|AGENT)[^\n"]*\.md \(project instructions|project instructions, checked into|\\?"(?:claudeMd|type\\?":\\?"claudeMd)\\?"|\\?"type\\?":\s*\\?"claudeMd/;
 const COMPACTION = /"isCompactSummary"\s*:\s*true/;
+// Evidence that THIS transcript records context-injection at all: a
+// system-reminder block, a claudeMd / instructions / attachment line, a
+// rules-file block, or a compaction. If none of this appears, the log is too
+// thin to conclude the rules file was absent (vs simply not recorded).
+const CONTEXT_MACHINERY = /<system-reminder>|\\?"claudeMd\\?"|"type"\s*:\s*"(?:instructions|attachment|system)"|project instructions|Contents of [^\n"]*\.md|"isCompactSummary"\s*:\s*true/i;
 /** Longest-first distinctive fragments of the evidence to find the break line by. */
 function needles(evidence) {
     const quoted = [...evidence.matchAll(/"([^"]{6,})"/g)].map((m) => m[1]);
@@ -78,8 +83,9 @@ export function breakContext(transcriptText, evidence) {
             }
         }
     }
+    const contextObserved = lines.some((l) => CONTEXT_MACHINERY.test(l));
     if (breakIdx === -1)
-        return { located: false, rulesInContext: false, compactionBefore: false, rulesStaleAfterCompaction: false };
+        return { located: false, rulesInContext: false, compactionBefore: false, rulesStaleAfterCompaction: false, contextObserved };
     let lastRulesIdx = -1;
     let lastCompactionIdx = -1;
     let precedingUser;
@@ -101,6 +107,7 @@ export function breakContext(transcriptText, evidence) {
         rulesInContext,
         compactionBefore,
         rulesStaleAfterCompaction: rulesInContext && compactionBefore && lastRulesIdx < lastCompactionIdx,
+        contextObserved,
     };
 }
 /** The lines the report prints under a break, or [] when nothing is worth adding. */
@@ -110,20 +117,18 @@ export function renderBreakContext(ctx) {
     const out = ["     why it broke:"];
     if (ctx.precedingUser)
         out.push(`       just before, you said: "${ctx.precedingUser}"`);
-    if (!ctx.rulesInContext) {
-        out.push("       your rules file was NOT in context at this point — not the agent ignoring a");
-        out.push("       rule it never saw. Claude Code can load CLAUDE.md only when a Read touches its");
-        out.push("       directory, so a shell-heavy session can miss it. Fix: a SessionStart (and");
-        out.push("       post-compaction) hook that injects your rules every session.");
-    }
-    else if (ctx.rulesStaleAfterCompaction) {
-        out.push("       your rules file was in context earlier but NOT after the last compaction — the");
-        out.push("       summary may have dropped it. Fix: a post-compaction hook that re-injects your rules.");
-    }
-    else {
+    // This renders only for a break that was NOT downgraded to "Rule not visible"
+    // (see visibility.ts). So either the rules file WAS in context, or the log is
+    // too thin to tell — never the confident not-visible case, which shows its own
+    // fix in the "Rule not visible" section.
+    if (ctx.rulesInContext) {
         out.push("       your rules file was in context before this.");
         if (ctx.compactionBefore)
-            out.push("       (a compaction happened earlier in this session; context before it was summarised.)");
+            out.push("       (a compaction happened earlier in this session; it was re-injected after.)");
+    }
+    else {
+        out.push("       couldn't tell whether your rules file was in context here — the session log");
+        out.push("       doesn't record it. If it wasn't, this isn't the agent ignoring a rule it never saw.");
     }
     return out;
 }

package/dist/cli.js

@@ -31,6 +31,7 @@ import { runHook } from "./hook.js";
 import { runGuard } from "./guard.js";
 import { generateReport, generateMarkdownReport, generateJsonReport, computeTranscriptHash } from "./report/generateReport.js";
 import { buildTeamExport, parseExport, mergeTeamExports, renderTeamHtml } from "./teamExport.js";
+import { applyVisibility } from "./visibility.js";
 import { gateOffer, hookIsInstalled } from "./report/gateOffer.js";
 import { generateHtmlReport } from "./report/generateHtmlReport.js";
 import { verifySessionHash } from "./verifyHash.js";
@@ -268,7 +269,21 @@ async function runCheck(opts) {
     // back to its stable handle so the mark survives edits that renumber ids.
     const projectConfig = loadProjectConfig(cwd);
     const handleFor = handleMap(rules);
-    const results = visibleResults(rawResults, projectConfig, handleFor);
+    // The raw session text — for A4 "why it broke" context AND for the
+    // visibility pass (#4). Best-effort: if it can't be read, visibility is left
+    // undetermined (a would-be break stays Broken) and no A4 context is shown.
+    let transcriptText;
+    try {
+        if (sessionFilePath)
+            transcriptText = readFileSync(sessionFilePath, "utf-8");
+    }
+    catch {
+        /* unreadable: never a crash */
+    }
+    // "Rule not visible" (#4): downgrade a FAIL whose rule was never in the
+    // agent's context at the break. Applied HERE, before anything counts a break,
+    // so the report, the exit code and the export all agree.
+    const results = applyVisibility(visibleResults(rawResults, projectConfig, handleFor), transcriptText);
     const blockingFails = blockingFailures(results, projectConfig, handleFor);
     const warnedFails = warningFailures(results, projectConfig, handleFor);
     const meta = { sessionFilePath, ruleCount: results.length };
@@ -303,16 +318,6 @@ async function runCheck(opts) {
         : "";
     // Kept in human/markdown form for --email and any other reader below, even
     // when stdout is JSON — a manager gets a readable report, not raw JSON.
-    // The raw session text, for A4 "why it broke" context under each Broken verdict.
-    // Best-effort: if it can't be read, the report simply omits the context.
-    let transcriptText;
-    try {
-        if (sessionFilePath)
-            transcriptText = readFileSync(sessionFilePath, "utf-8");
-    }
-    catch {
-        /* unreadable: no A4 context, never a crash */
-    }
     const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta, transcriptText);
     if (json) {
         console.log(generateJsonReport(results, meta, pkg.version, editedRuleFiles));

package/dist/historyReport.d.ts

@@ -37,6 +37,8 @@ export interface HistorySummary {
     followedRules: number;
     /** Rules that need a human's judgment (never mechanically decided). */
     judgmentRules: number;
+    /** Rules whose only would-be breaks happened while the rule wasn't in context. */
+    notVisibleRules: number;
     elapsedMs: number;
 }
 /**

package/dist/historyReport.js

@@ -1,6 +1,7 @@
-import { statSync } from "node:fs";
+import { statSync, readFileSync } from "node:fs";
 import { listAllSessions } from "./adapters/index.js";
 import { evaluateSession } from "./evaluate.js";
+import { applyVisibility } from "./visibility.js";
 /**
  * One-line clip that ends on a whole word with an ellipsis, never mid-sentence.
  * Found by a real test 2026-09-29: a break quote was cut as "...so no prompt was".
@@ -64,15 +65,25 @@ export async function scanHistory(cwd, rules, days = 30, now = Date.now(), sessi
         // today" for it is wrong (found by a real test, 2026-09-29). Falls back to
         // the mtime only when the transcript carries no usable timestamp.
         const sessionMs = lastEventMs(events) ?? ms;
-        const { results } = await evaluateSession(cwd, rules, events, false, needsLlmResult);
+        const { results: rawResults } = await evaluateSession(cwd, rules, events, false, needsLlmResult);
+        // "Rule not visible" (#4): a FAIL whose rule wasn't in context is not a break
+        // here either, so the headline count stays honest across sessions.
+        let rawText;
+        try {
+            rawText = readFileSync(file, "utf-8");
+        }
+        catch { /* keep undefined */ }
+        const results = applyVisibility(rawResults, rawText);
         for (const r of results) {
             const k = key(r);
             let a = rules_.get(k);
             if (!a) {
-                a = { title: r.ruleTitle, source: r.ruleSource, id: r.ruleId, breaks: [], passed: false, judgment: false };
+                a = { title: r.ruleTitle, source: r.ruleSource, id: r.ruleId, breaks: [], passed: false, judgment: false, notVisible: false };
                 rules_.set(k, a);
             }
-            if (r.status === "FAIL")
+            if (r.status === "FAIL" && r.notVisible)
+                a.notVisible = true;
+            else if (r.status === "FAIL")
                 a.breaks.push({ ms: sessionMs, quote: r.evidence });
             else if (r.status === "PASS")
                 a.passed = true;
@@ -83,11 +94,16 @@ export async function scanHistory(cwd, rules, days = 30, now = Date.now(), sessi
     const breaks = [];
     let followedRules = 0;
     let judgmentRules = 0;
+    let notVisibleRules = 0;
     for (const a of rules_.values()) {
         if (a.breaks.length > 0) {
             const last = a.breaks.reduce((m, b) => (b.ms > m.ms ? b : m), a.breaks[0]);
             breaks.push({ ruleId: a.id, ruleTitle: a.title, ruleSource: a.source, count: a.breaks.length, lastMs: last.ms, quote: a.breaks[0].quote });
         }
+        else if (a.notVisible) {
+            // Would-be break(s), but the rule was never in context — not a violation.
+            notVisibleRules++;
+        }
         else if (a.passed) {
             followedRules++;
         }
@@ -104,6 +120,7 @@ export async function scanHistory(cwd, rules, days = 30, now = Date.now(), sessi
         totalBrokenCount: breaks.reduce((n, b) => n + b.count, 0),
         followedRules,
         judgmentRules,
+        notVisibleRules,
         elapsedMs: Date.now() - started,
     };
 }
@@ -146,6 +163,9 @@ export function renderHistory(s, projectName, now = Date.now()) {
     }
     out.push("");
     out.push(`  ${s.followedRules} rule${s.followedRules === 1 ? "" : "s"} followed every time · ${s.judgmentRules} need${s.judgmentRules === 1 ? "s" : ""} your judgment`);
+    if (s.notVisibleRules > 0) {
+        out.push(`  ${s.notVisibleRules} rule${s.notVisibleRules === 1 ? " was" : "s were"} not in context when the agent acted — NOT counted as broken. Start sessions from the project root, or add a SessionStart hook that injects your rules.`);
+    }
     out.push("");
     out.push(`checked ${s.sessionsScanned} session${s.sessionsScanned === 1 ? "" : "s"} in ${secs}s`);
     out.push("");

package/dist/projectConfig.js

@@ -85,9 +85,10 @@ export function handleMap(rules) {
 }
 /** FAILs at `error` mode — these fail the build. (`off` never reaches here.) */
 export function blockingFailures(results, config, handleFor) {
-    return results.filter((r) => r.status === "FAIL" && modeForResult(r, config, handleFor) === "error");
+    // `notVisible` FAILs are "Rule not visible", not Broken — they never fail the build.
+    return results.filter((r) => r.status === "FAIL" && !r.notVisible && modeForResult(r, config, handleFor) === "error");
 }
 /** FAILs at `warn` mode — shown, but they do not fail the build. */
 export function warningFailures(results, config, handleFor) {
-    return results.filter((r) => r.status === "FAIL" && modeForResult(r, config, handleFor) === "warn");
+    return results.filter((r) => r.status === "FAIL" && !r.notVisible && modeForResult(r, config, handleFor) === "warn");
 }

package/dist/report/generateReport.js

@@ -78,6 +78,8 @@ function ruleLabel(r, results) {
 function summaryLine(results) {
     const n = (b) => results.filter((r) => bucketOf(r) === b).length;
     const parts = [`${n("PASS")} followed`, `${n("FAIL")} not followed`];
+    if (n("RULE_NOT_VISIBLE") > 0)
+        parts.push(`${n("RULE_NOT_VISIBLE")} rule not visible`);
     if (n("UNCLEAR_EVIDENCE") > 0)
         parts.push(`${n("UNCLEAR_EVIDENCE")} couldn't tell`);
     if (n("NOT_RUN") > 0)
@@ -104,6 +106,10 @@ function summaryLine(results) {
  * fallback while the rest are migrated.
  */
 function bucketOf(result) {
+    // A would-be Broken whose rule wasn't in context is "Rule not visible", never
+    // Broken — decided before anything else so it can't be counted as a violation.
+    if (result.notVisible)
+        return "RULE_NOT_VISIBLE";
     switch (result.outcome) {
         case "fail":
             return "FAIL";
@@ -133,6 +139,7 @@ function bucketOf(result) {
  */
 const BUCKET_LABEL = {
     FAIL: "Not followed",
+    RULE_NOT_VISIBLE: "Rule not visible (not a violation)",
     UNCLEAR_EVIDENCE: "Couldn't tell",
     NOT_RUN: "Not run",
     PASS: "Followed",
@@ -147,6 +154,7 @@ const BUCKET_LABEL = {
  */
 const BUCKET_ORDER = [
     "FAIL",
+    "RULE_NOT_VISIBLE",
     "UNCLEAR_EVIDENCE",
     "NOT_RUN",
     "PASS",
@@ -242,10 +250,14 @@ export function generateReport(results, meta, transcriptText) {
             // versions as a PASS on a session that ran `git push -f`.
             if (r.ceiling)
                 lines.push(`  this means: ${r.ceiling}`);
-            // A4: why it broke — the context around a proven break, read from the raw
-            // transcript. Honest by construction: if the rules file was never in
-            // context before the break, it says so rather than implying it was ignored.
-            if (r.status === "FAIL" && transcriptText && r.evidence) {
+            // "Rule not visible": not a violation. Say plainly why, and the fix.
+            if (r.notVisible) {
+                lines.push(`  not a violation: the agent never had this rule in context at that moment.`);
+                lines.push(`  fix: ${r.notVisible.fix}`);
+            }
+            // A4: why it broke — the context around a PROVEN break (one that WAS
+            // visible). Skipped for a not-visible result, which shows its own fix above.
+            if (r.status === "FAIL" && !r.notVisible && transcriptText && r.evidence) {
                 for (const l of renderBreakContext(breakContext(transcriptText, r.evidence)))
                     lines.push(l);
             }
@@ -331,13 +343,16 @@ export function generateJsonReport(results, meta, toolVersion, editedRuleFiles =
         summary: {
             total: clean.length,
             pass: count("PASS"),
-            fail: count("FAIL"),
+            // A "rule not visible" FAIL is never counted as broken — same everywhere.
+            fail: clean.filter((r) => r.status === "FAIL" && !r.notVisible).length,
             unclear: count("UNCLEAR"),
+            ruleNotVisible: clean.filter((r) => Boolean(r.notVisible)).length,
         },
         results: clean.map((r) => ({
             ruleId: r.ruleId,
             ruleTitle: r.ruleTitle,
             ruleSource: r.ruleSource,
+            ...(r.notVisible ? { notVisible: r.notVisible } : {}),
             // Absolute path + 1-based line of the rule's heading, when unambiguous
             // (see attachSourceLocation). A consumer can jump straight to the rule.
             sourcePath: r.sourcePath ?? null,

package/dist/teamExport.d.ts

@@ -35,12 +35,14 @@ export interface TeamExport {
         fail: number;
         unclear: number;
     };
-    /** One entry per rule: the verdict and the quoted evidence, nothing else. */
+    /** One entry per rule: the verdict and the quoted evidence. `notVisible` marks
+     * a would-be break the rule wasn't in context for — never counted as broken. */
     rules: {
         title: string;
         source: string;
         status: CheckResult["status"];
         evidence: string;
+        notVisible?: boolean;
     }[];
 }
 export declare function buildTeamExport(results: CheckResult[], project: string, dev: string, version: string, now?: Date): TeamExport;

package/dist/teamExport.js

@@ -20,6 +20,8 @@ import { redact } from "./wrong.js";
 export const EXPORT_SCHEMA = 1;
 export function buildTeamExport(results, project, dev, version, now = new Date()) {
     const count = (s) => results.filter((r) => r.status === s).length;
+    // A "rule not visible" FAIL is never counted as broken — same rule as the report.
+    const fail = results.filter((r) => r.status === "FAIL" && !r.notVisible).length;
     return {
         tool: "rulereceipt",
         kind: "export",
@@ -28,10 +30,10 @@ export function buildTeamExport(results, project, dev, version, now = new Date()
         dev: dev.trim() || "unknown",
         project,
         date: now.toISOString().slice(0, 10),
-        summary: { total: results.length, pass: count("PASS"), fail: count("FAIL"), unclear: count("UNCLEAR") },
+        summary: { total: results.length, pass: count("PASS"), fail, unclear: count("UNCLEAR") },
         // Evidence is masked before it leaves: an export is shared, so obvious
         // secrets, the home path and emails are redacted (same patterns as `wrong`).
-        rules: results.map((r) => ({ title: redact(r.ruleTitle), source: r.ruleSource, status: r.status, evidence: redact(r.evidence) })),
+        rules: results.map((r) => ({ title: redact(r.ruleTitle), source: r.ruleSource, status: r.status, evidence: redact(r.evidence), ...(r.notVisible ? { notVisible: true } : {}) })),
     };
 }
 /** A tolerant parse of one export file's text; null if it is not a valid export. */
@@ -59,8 +61,8 @@ export function mergeTeamExports(exports) {
     let totalBroken = 0;
     for (const e of exports) {
         for (const r of e.rules) {
-            if (r.status !== "FAIL")
-                continue;
+            if (r.status !== "FAIL" || r.notVisible)
+                continue; // a not-visible break is not broken
             totalBroken++;
             const cur = byRule.get(r.title) ?? { count: 0, devs: new Set() };
             cur.count++;

package/dist/types.d.ts

@@ -129,6 +129,19 @@ export interface CheckResult {
      * when a recorded run CONTRADICTED a claim.
      */
     unverifiedClaim?: boolean;
+    /**
+     * Set when a would-be Broken verdict is downgraded to "Rule not visible":
+     * the session's working directory and history show the rule was never in the
+     * agent's context at the moment of the break (not loaded from this cwd, or
+     * dropped by a compaction and not re-injected). This is NOT a violation — the
+     * agent can't follow a rule it never saw — so it is never counted as Broken,
+     * never fails the build, and carries the fix. See visibility.ts. `reason`
+     * distinguishes "never in context" from "lost after a compaction".
+     */
+    notVisible?: {
+        reason: "not-in-context" | "stale-after-compaction";
+        fix: string;
+    };
     /**
      * The outcome in the five-value vocabulary. Optional while the checkers
      * are migrated one at a time; `status` remains the fallback.

package/dist/visibility.d.ts

@@ -0,0 +1,13 @@
+import type { CheckResult } from "./types.js";
+/** How a would-be break relates to the rule's visibility, from the raw transcript. */
+export declare function classifyVisibility(transcriptText: string, evidence: string): {
+    reason: "not-in-context" | "stale-after-compaction";
+    fix: string;
+} | null;
+/**
+ * Attach `notVisible` to any FAIL whose rule wasn't in context at the break.
+ * Returns a new array (inputs untouched). A no-op without transcript text, and
+ * for non-FAIL results. Called everywhere a verdict is counted so Broken means
+ * the same thing in the report, the exit code, history and the team export.
+ */
+export declare function applyVisibility(results: CheckResult[], transcriptText: string | undefined): CheckResult[];

package/dist/visibility.js

@@ -0,0 +1,51 @@
+import { breakContext } from "./breakContext.js";
+/**
+ * "Rule not visible" (dogfood/#4). Before a Broken verdict stands, ask whether
+ * the rule was even IN THE AGENT'S CONTEXT at the moment of the break. A rule
+ * the agent never saw cannot have been "broken" by it — Claude Code loads
+ * CLAUDE.md only when the session starts from (or a Read touches) its directory,
+ * and a compaction can drop it. Counting those as Broken is a false accusation.
+ *
+ * So a FAIL is downgraded to `notVisible` when, read from the raw transcript:
+ *   - the rules file never entered context before the break  -> "not-in-context"
+ *   - it was present but not re-injected after the last compaction -> "stale-after-compaction"
+ * and left as Broken when it WAS visible. When the break can't be located in the
+ * transcript we do NOT guess — it stays Broken (the forbidden action is real and
+ * quoted); the caller may add a "can't tell if the rule was visible" caveat.
+ *
+ * This runs wherever a verdict is finalized (check, history, export) so every
+ * surface agrees. It changes nothing without the raw transcript text.
+ */
+const FIX_NOT_IN_CONTEXT = "The rules file was never in context here. Start the session from the project root so CLAUDE.md loads at the start, or add a SessionStart hook that injects your rules every session.";
+const FIX_STALE = "The rules file was in context earlier but not after the last compaction. Add a post-compaction hook (SessionStart:compact) that re-injects your rules.";
+/** How a would-be break relates to the rule's visibility, from the raw transcript. */
+export function classifyVisibility(transcriptText, evidence) {
+    const ctx = breakContext(transcriptText, evidence);
+    if (!ctx.located)
+        return null; // can't find the break -> don't guess; stays Broken
+    // Only downgrade when we can POSITIVELY tell the rule wasn't there: the
+    // transcript shows context-injection machinery (system-reminders, attachments,
+    // a compaction) yet no rules file before the break. A thin log with no such
+    // machinery is can't-tell, NOT "not visible" — stays Broken.
+    if (!ctx.rulesInContext)
+        return ctx.contextObserved ? { reason: "not-in-context", fix: FIX_NOT_IN_CONTEXT } : null;
+    if (ctx.rulesStaleAfterCompaction)
+        return { reason: "stale-after-compaction", fix: FIX_STALE };
+    return null; // visible before the break -> a real Broken
+}
+/**
+ * Attach `notVisible` to any FAIL whose rule wasn't in context at the break.
+ * Returns a new array (inputs untouched). A no-op without transcript text, and
+ * for non-FAIL results. Called everywhere a verdict is counted so Broken means
+ * the same thing in the report, the exit code, history and the team export.
+ */
+export function applyVisibility(results, transcriptText) {
+    if (!transcriptText)
+        return results;
+    return results.map((r) => {
+        if (r.status !== "FAIL" || r.notVisible || !r.evidence)
+            return r;
+        const v = classifyVisibility(transcriptText, r.evidence);
+        return v ? { ...r, notVisible: v } : r;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.84",
+  "version": "0.1.85",
   "description": "Checks whether your AI coding agent followed your rules, with evidence. Works with Claude Code (Codex in testing); reads CLAUDE.md, AGENTS.md, Cursor, Copilot and Windsurf rules.",
   "repository": {
     "type": "git",