rulereceipt 0.1.83 → 0.1.85

package/NOTICE.md

@@ -32,3 +32,4 @@ we did not copy the code):
   from **Pilan-AI/mnemo** (MIT). Our reader is `src/adapters/copilot.ts`.
 - **Gemini CLI** session format (`~/.gemini/tmp/<hash>/chats/*.{jsonl,json}`, legacy `~/.gemini/sessions/*.json`): documented by **yigitkonur/cli-continues** (MIT, pinned `e486cd2`; from mnemo MIT). Our reader is `src/adapters/gemini.ts`.
 - **Cursor** agent-transcripts (`~/.cursor/projects/<slug>/agent-transcripts/**/*.jsonl`, Anthropic-API shaped): documented by **yigitkonur/cli-continues** (MIT, pinned `e486cd2`). Our reader `src/adapters/cursor.ts`. (Old `state.vscdb` SQLite path deferred.)
+- **OpenCode** JSON file store (`$XDG_DATA_HOME/opencode/storage/{session,message,part}/*.json`): documented by **yigitkonur/cli-continues** (MIT, pinned `e486cd2`). Our reader `src/adapters/opencode.ts`. (opencode.db SQLite path deferred.)

package/dist/adapters/index.d.ts

@@ -46,6 +46,8 @@ export declare const ADAPTERS: SessionAdapter[];
 export declare const geminiCliAdapter: SessionAdapter;
 /** Cursor — EXPERIMENTAL. Current agent-transcripts (JSONL, Anthropic-shaped); old SQLite deferred. */
 export declare const cursorAdapter: SessionAdapter;
+/** OpenCode — EXPERIMENTAL. JSON file store (3-dir join); opencode.db SQLite deferred. */
+export declare const openCodeAdapter: SessionAdapter;
 /** Experimental adapters: reader exists, awaiting real+planted+clean fixtures. */
 export declare const EXPERIMENTAL_ADAPTERS: SessionAdapter[];
 /**

package/dist/adapters/index.js

@@ -5,6 +5,7 @@ import { listCodexSessions, parseCodexTranscript } from "./codex.js";
 import { listCopilotSessions, parseCopilotTranscript, copilotFormatIsKnown } from "./copilot.js";
 import { listGeminiSessions, parseGeminiTranscript, geminiFormatIsKnown } from "./gemini.js";
 import { listCursorSessions, parseCursorTranscript, cursorFormatIsKnown } from "./cursor.js";
+import { listOpenCodeSessions, parseOpenCodeTranscript, openCodeFormatIsKnown } from "./opencode.js";
 /**
  * Claude Code — the original and reference adapter. Delegates to the existing
  * transcriptParser so its behaviour (including subagent transcripts) is
@@ -54,8 +55,15 @@ export const cursorAdapter = {
     parse: (sessionFile) => parseCursorTranscript(sessionFile),
     experimental: true,
 };
+/** OpenCode — EXPERIMENTAL. JSON file store (3-dir join); opencode.db SQLite deferred. */
+export const openCodeAdapter = {
+    tool: "opencode",
+    listSessions: (cwd) => listOpenCodeSessions(cwd),
+    parse: (sessionFile) => parseOpenCodeTranscript(sessionFile),
+    experimental: true,
+};
 /** Experimental adapters: reader exists, awaiting real+planted+clean fixtures. */
-export const EXPERIMENTAL_ADAPTERS = [copilotCliAdapter, geminiCliAdapter, cursorAdapter];
+export const EXPERIMENTAL_ADAPTERS = [copilotCliAdapter, geminiCliAdapter, cursorAdapter, openCodeAdapter];
 /**
  * Tools deliberately NOT read yet, with the honest reason. Kept as data (not
  * silence) so the tool — and its docs — can state exactly where the line is
@@ -63,7 +71,6 @@ export const EXPERIMENTAL_ADAPTERS = [copilotCliAdapter, geminiCliAdapter, curso
  */
 export const UNSUPPORTED_TOOLS = [
     { tool: "aider", reason: "history is a Markdown transcript (.aider.chat.history.md), not structured events — needs a prose parser, not a field mapping" },
-    { tool: "opencode", reason: "stores sessions in a SQLite DB (opencode.db) — needs a WASM sqlite reader; planned next" },
     { tool: "windsurf", reason: "IDE-embedded; history in undocumented internal state, same as old Cursor" },
 ];
 /**
@@ -160,6 +167,10 @@ export function parseSessionFile(file) {
     // `message` wrapper and no `type`. Gated the same way.
     if (cursorFormatIsKnown(file))
         return parseCursorTranscript(file);
+    // OpenCode: a single session JSON (`id` starting `ses_`); the message/part
+    // dirs are resolved relative to this file.
+    if (openCodeFormatIsKnown(file))
+        return parseOpenCodeTranscript(file);
     return readTranscriptFromFile(file);
 }
 /**

package/dist/adapters/opencode.d.ts

@@ -0,0 +1,7 @@
+import type { TranscriptEvent } from "../types.js";
+/** OpenCode session files for this cwd, newest first. */
+export declare function listOpenCodeSessions(cwd: string): string[];
+/** True when the file is an OpenCode session JSON (id starting `ses_`). */
+export declare function openCodeFormatIsKnown(sessionFile: string): boolean;
+/** Parse one OpenCode session (by its ses_*.json) into neutral events. Tolerant. */
+export declare function parseOpenCodeTranscript(sessionFile: string): TranscriptEvent[];

package/dist/adapters/opencode.js

@@ -0,0 +1,179 @@
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+/**
+ * OpenCode adapter — EXPERIMENTAL (no real-session fixtures yet).
+ *
+ * Reads the JSON file store (NOT the newer `opencode.db` SQLite, which is
+ * deferred — see REUSE.md). Format documented by yigitkonur/cli-continues (MIT,
+ * src/parsers/opencode.ts, pinned e486cd22a592d89d890cff056624647fbe9cbe80).
+ * Credit: NOTICE.md / REUSE.md.
+ *
+ * Store (under `$XDG_DATA_HOME/opencode/storage` or `~/.local/share/opencode/
+ * storage`): a 3-directory join
+ *   session/<proj>/ses_*.json   → { id, projectID, directory, time:{updated} }
+ *   message/<sessionId>/msg_*.json → { id, role }
+ *   part/<messageId>/prt_*.json    → { type:'text'|'tool'|…, text?, tool?, callID?,
+ *                                      state:{ input, status, output, error } }
+ * cwd = session.directory, else project/<projectID>.json `.worktree`.
+ *   text part  -> text (role of its message)
+ *   tool part  -> tool_use (shell -> canonical Bash) + a tool_result from its state.
+ *
+ * The message/part dirs are resolved RELATIVE to the session file, so
+ * `--transcript <…/session/<proj>/ses_X.json>` works wherever the store lives.
+ *
+ * RESILIENCE: only the fields above; unknown part types / bad files skipped,
+ * never guessed; `openCodeFormatIsKnown` gates use.
+ */
+function realpathOr(p) { try {
+    return realpathSync(p);
+}
+catch {
+    return p;
+} }
+function str(v) { return typeof v === "string" && v.length > 0 ? v : undefined; }
+function rec(v) { return v && typeof v === "object" && !Array.isArray(v) ? v : {}; }
+function storageDir() {
+    const xdg = process.env.XDG_DATA_HOME?.trim();
+    const base = xdg && xdg.length > 0 ? join(xdg, "opencode") : join(homedir(), ".local", "share", "opencode");
+    return join(base, "storage");
+}
+function readJson(file) {
+    try {
+        const o = JSON.parse(readFileSync(file, "utf-8"));
+        return rec(o);
+    }
+    catch {
+        return null;
+    }
+}
+/** storage root for a given session file (…/storage/session/<proj>/ses_X.json). */
+function storageRootOf(sessionFile) {
+    return join(dirname(sessionFile), "..", "..");
+}
+/** cwd of a session JSON: its `directory`, else project/<projectID>.json .worktree. */
+function sessionCwd(sessionFile, s) {
+    const dir = str(s.directory);
+    if (dir)
+        return dir;
+    const pid = str(s.projectID);
+    if (pid) {
+        const proj = readJson(join(storageRootOf(sessionFile), "project", `${pid}.json`));
+        if (proj)
+            return str(proj.worktree) ?? null;
+    }
+    return null;
+}
+function listSessionJsonFiles(storage) {
+    const sessionBase = join(storage, "session");
+    const out = [];
+    let projs = [];
+    try {
+        projs = readdirSync(sessionBase);
+    }
+    catch {
+        return out;
+    }
+    for (const p of projs) {
+        const d = join(sessionBase, p);
+        let names = [];
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            continue;
+        }
+        for (const n of names)
+            if (n.startsWith("ses_") && n.endsWith(".json"))
+                out.push(join(d, n));
+    }
+    return out;
+}
+/** OpenCode session files for this cwd, newest first. */
+export function listOpenCodeSessions(cwd) {
+    const storage = storageDir();
+    if (!existsSync(storage))
+        return [];
+    const target = realpathOr(cwd);
+    const hits = [];
+    for (const file of listSessionJsonFiles(storage)) {
+        const s = readJson(file);
+        if (!s)
+            continue;
+        const c = sessionCwd(file, s);
+        if (c && realpathOr(c) !== target)
+            continue;
+        try {
+            hits.push({ file, mtimeMs: statSync(file).mtimeMs });
+        }
+        catch { /* skip */ }
+    }
+    return hits.sort((a, b) => b.mtimeMs - a.mtimeMs).map((h) => h.file);
+}
+function sortedJson(dir) {
+    try {
+        return readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function toToolUse(name, input, id, ts) {
+    const command = str(input.command) ?? str(input.cmd);
+    const filePath = str(input.file_path) ?? str(input.path) ?? str(input.filePath);
+    const lower = name.toLowerCase();
+    if (command && (/(shell|bash|terminal|exec|run|command)/.test(lower) || !filePath)) {
+        return { role: "assistant", kind: "tool_use", toolName: "Bash", toolUseId: id, input: { command }, timestamp: ts };
+    }
+    if (filePath && /(write|create|edit|replace|patch|insert|modif|apply)/.test(lower)) {
+        return { role: "assistant", kind: "tool_use", toolName: /(edit|replace|patch|apply)/.test(lower) ? "Edit" : "Write", toolUseId: id, input: { file_path: filePath, ...input }, timestamp: ts };
+    }
+    if (filePath && /(read|view|open|cat|show)/.test(lower)) {
+        return { role: "assistant", kind: "tool_use", toolName: "Read", toolUseId: id, input: { file_path: filePath }, timestamp: ts };
+    }
+    return { role: "assistant", kind: "tool_use", toolName: name, toolUseId: id, input, timestamp: ts };
+}
+/** True when the file is an OpenCode session JSON (id starting `ses_`). */
+export function openCodeFormatIsKnown(sessionFile) {
+    const s = readJson(sessionFile);
+    return Boolean(s && str(s.id)?.startsWith("ses_"));
+}
+/** Parse one OpenCode session (by its ses_*.json) into neutral events. Tolerant. */
+export function parseOpenCodeTranscript(sessionFile) {
+    const s = readJson(sessionFile);
+    const sessionId = s ? str(s.id) : undefined;
+    if (!s || !sessionId)
+        return [];
+    const root = storageRootOf(sessionFile);
+    const messageDir = join(root, "message", sessionId);
+    const out = [];
+    for (const msgFile of sortedJson(messageDir)) {
+        const m = readJson(join(messageDir, msgFile));
+        if (!m)
+            continue;
+        const role = m.role === "assistant" ? "assistant" : m.role === "user" ? "user" : undefined;
+        const msgId = str(m.id);
+        if (!role || !msgId)
+            continue;
+        const partDir = join(root, "part", msgId);
+        for (const prtFile of sortedJson(partDir)) {
+            const part = readJson(join(partDir, prtFile));
+            if (!part)
+                continue;
+            if (part.type === "text" && str(part.text)) {
+                out.push({ role, kind: "text", text: part.text, timestamp: "" });
+            }
+            else if (part.type === "tool" && role === "assistant") {
+                const name = str(part.tool);
+                if (!name)
+                    continue;
+                const state = rec(part.state);
+                const id = str(part.callID);
+                out.push(toToolUse(name, rec(state.input), id, ""));
+                const content = str(state.output) ?? str(state.error) ?? "";
+                out.push({ role: "user", kind: "tool_result", toolUseId: id, content: content.slice(0, 2000), isError: state.status === "error", timestamp: "" });
+            }
+        }
+    }
+    return out;
+}

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.83",
+  "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",