rulereceipt 0.1.76 → 0.1.78

package/README.md

@@ -17,7 +17,7 @@ npx rulereceipt
 Runs entirely on your machine. Plain `rulereceipt check` makes zero network
 calls — [Trust, privacy and licensing](#trust-privacy-and-licensing) has the full
 detail, including the three off-by-default opt-ins. Works with Claude Code today
-(OpenAI Codex CLI in testing); reads rules from CLAUDE.md, AGENTS.md, Cursor
+(OpenAI Codex CLI supported); reads rules from CLAUDE.md, AGENTS.md, Cursor
 (`.cursor/rules`), GitHub Copilot, Windsurf, Gemini (`GEMINI.md`), Google's
 `.agents/rules`, and Claude Code memory. [Accuracy](https://rulereceipt.dev/accuracy)
 · [Known gaps](KNOWN-GAPS.md) · Source-available, not OSI — see [LICENSE](LICENSE).
@@ -77,7 +77,7 @@ Published and live on npm, actively developed.
    current project directory and your global rules file.
 2. Reads your most recent agent session transcript — Claude Code today
    (including hosted/enterprise variants under a different directory), and
-   OpenAI Codex CLI (in testing); newest session across tools wins.
+   OpenAI Codex CLI (supported); newest session across tools wins.
 3. Routes each rule to the narrowest check that can actually answer it:
    - **Structured checks** read what the session really did — an actual
      git command's branch argument, actual file edits, actual file

package/dist/breakContext.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A4 — "why it broke" context for a single proven break.
+ *
+ * The report says WHICH rule broke and quotes the line. This adds the three
+ * things a person asks next, read straight from the raw transcript (the parsed
+ * event stream drops attachment/system/compaction lines, so this works on the
+ * file text `check` already has):
+ *
+ *   1. the user's own message just before the break,
+ *   2. whether the rules file (CLAUDE.md/AGENTS.md/GEMINI.md) was in context
+ *      BEFORE the break at all,
+ *   3. whether a compaction happened earlier in the session.
+ *
+ * The point of (2) is honesty, not accusation. Claude Code can load CLAUDE.md
+ * only when a Read touches its directory, so a shell-heavy session may never
+ * have the rule in context. When that is the case the report must say "the rules
+ * file was not in context here", NOT imply the agent ignored a rule it never saw
+ * — and it points at the fix (a SessionStart / post-compaction hook that injects
+ * the rules). Nothing here changes a verdict; it only explains one.
+ *
+ * If the break line cannot be located in the transcript (evidence with no
+ * quotable fragment), `located` is false and the caller shows nothing rather
+ * than guessing.
+ */
+export interface BreakContext {
+    located: boolean;
+    /** The user's own typed message just before the break, clipped; undefined if none. */
+    precedingUser?: string;
+    /** Did a rules file appear in the transcript before the break? */
+    rulesInContext: boolean;
+    /** Did a compaction occur before the break? */
+    compactionBefore: 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
+     * have dropped it. (The real session ef53e676: CLAUDE.md present before a
+     * compaction, never came back.)
+     */
+    rulesStaleAfterCompaction: boolean;
+}
+/**
+ * Context for the break whose evidence is `evidence`, read from the raw JSONL
+ * `transcriptText`. Line-based: the break line is the LAST line carrying a
+ * distinctive fragment of the evidence (so a later, unrelated mention does not
+ * win), and the three facts are computed over the lines before it.
+ */
+export declare function breakContext(transcriptText: string, evidence: string): BreakContext;
+/** The lines the report prints under a break, or [] when nothing is worth adding. */
+export declare function renderBreakContext(ctx: BreakContext): string[];

package/dist/breakContext.js

@@ -0,0 +1,129 @@
+/**
+ * A4 — "why it broke" context for a single proven break.
+ *
+ * The report says WHICH rule broke and quotes the line. This adds the three
+ * things a person asks next, read straight from the raw transcript (the parsed
+ * event stream drops attachment/system/compaction lines, so this works on the
+ * file text `check` already has):
+ *
+ *   1. the user's own message just before the break,
+ *   2. whether the rules file (CLAUDE.md/AGENTS.md/GEMINI.md) was in context
+ *      BEFORE the break at all,
+ *   3. whether a compaction happened earlier in the session.
+ *
+ * The point of (2) is honesty, not accusation. Claude Code can load CLAUDE.md
+ * only when a Read touches its directory, so a shell-heavy session may never
+ * have the rule in context. When that is the case the report must say "the rules
+ * file was not in context here", NOT imply the agent ignored a rule it never saw
+ * — and it points at the fix (a SessionStart / post-compaction hook that injects
+ * the rules). Nothing here changes a verdict; it only explains one.
+ *
+ * If the break line cannot be located in the transcript (evidence with no
+ * quotable fragment), `located` is false and the caller shows nothing rather
+ * than guessing.
+ */
+// A rules file being injected into context. Covers the literal injected header
+// ("Contents of .../CLAUDE.md (project instructions"), the "checked into" variant,
+// 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/;
+/** 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]);
+    const after = evidence.split(/:\s/).slice(1).join(": ");
+    return [...quoted, after]
+        .map((s) => s.replace(/\s+/g, " ").trim().slice(0, 80))
+        .filter((s) => s.length >= 6)
+        .sort((a, b) => b.length - a.length);
+}
+/** The human's own message on a user line (string content), or null. */
+function userTyped(line) {
+    try {
+        const o = JSON.parse(line);
+        if (o.type !== "user")
+            return null;
+        const c = o.message?.content;
+        if (typeof c === "string" && c.trim().length > 0)
+            return c.trim();
+    }
+    catch {
+        /* partial line */
+    }
+    return null;
+}
+function clip(s, n = 140) {
+    const one = s.replace(/\s+/g, " ").trim();
+    if (one.length <= n)
+        return one;
+    const cut = one.slice(0, n);
+    const sp = cut.lastIndexOf(" ");
+    return `${sp > n * 0.6 ? cut.slice(0, sp) : cut}…`;
+}
+/**
+ * Context for the break whose evidence is `evidence`, read from the raw JSONL
+ * `transcriptText`. Line-based: the break line is the LAST line carrying a
+ * distinctive fragment of the evidence (so a later, unrelated mention does not
+ * win), and the three facts are computed over the lines before it.
+ */
+export function breakContext(transcriptText, evidence) {
+    const lines = transcriptText.split(/\r?\n/);
+    const ns = needles(evidence);
+    let breakIdx = -1;
+    if (ns.length > 0) {
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const flat = lines[i].replace(/\s+/g, " ");
+            if (ns.some((n) => flat.includes(n))) {
+                breakIdx = i;
+                break;
+            }
+        }
+    }
+    if (breakIdx === -1)
+        return { located: false, rulesInContext: false, compactionBefore: false, rulesStaleAfterCompaction: false };
+    let lastRulesIdx = -1;
+    let lastCompactionIdx = -1;
+    let precedingUser;
+    for (let i = 0; i < breakIdx; i++) {
+        const line = lines[i];
+        if (RULES_INJECTION.test(line))
+            lastRulesIdx = i;
+        if (COMPACTION.test(line))
+            lastCompactionIdx = i;
+        const u = userTyped(line);
+        if (u)
+            precedingUser = clip(u);
+    }
+    const rulesInContext = lastRulesIdx !== -1;
+    const compactionBefore = lastCompactionIdx !== -1;
+    return {
+        located: true,
+        precedingUser,
+        rulesInContext,
+        compactionBefore,
+        rulesStaleAfterCompaction: rulesInContext && compactionBefore && lastRulesIdx < lastCompactionIdx,
+    };
+}
+/** The lines the report prints under a break, or [] when nothing is worth adding. */
+export function renderBreakContext(ctx) {
+    if (!ctx.located)
+        return [];
+    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 {
+        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.)");
+    }
+    return out;
+}

package/dist/checks/gitBranchPolicy.js

@@ -158,7 +158,14 @@ export function runGitBranchPolicyChecks(classifications, events) {
             allTargets.push({ branch: hit.branch, command, kind: hit.kind });
         }
     }
-    const anyGitCommand = events.some((e) => e.kind === "tool_use" && /\bgit\s/.test(JSON.stringify(e.input ?? "")));
+    // "Did a git command actually run?" — tested on the real command segments, not
+    // JSON.stringify(input). Two bugs that caused: (1) a newline before `git`
+    // becomes the two chars `\n` once stringified, so `\bgit` lost its word
+    // boundary and a `git push` on the line after a heredoc was missed entirely
+    // (check AND guard reported "didn't apply"); (2) a mere mention in a quote or
+    // heredoc body counted as a git command. leadingCommand over heredoc-stripped
+    // segments answers the real question: a git invocation in an executable segment.
+    const anyGitCommand = commands.some((c) => segments(c).some((seg) => leadingCommand(seg) === "git"));
     return classifications.map(({ rule, branchName, polarity, polarityInferred }) => {
         // No git command ran, so a git rule never had a situation to govern.
         // Calling that "followed" is how an empty session produced 2,770 green

package/dist/cli.js

@@ -282,7 +282,17 @@ 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.
-    const reportText = markdown ? generateMarkdownReport(results, meta) : generateReport(results, meta);
+    // 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));
     }
@@ -572,7 +582,7 @@ function runAdvise() {
     console.log(`  ${advice.length} cannot yet — here is what each one needs:\n`);
     // Project rules first: those are the ones the reader can act on today.
     const ordered = advice
-        .map((a, i) => ({ a, source: rules.find((r) => r.title === a.ruleTitle)?.source }))
+        .map((a) => ({ a, source: rules.find((r) => r.title === a.ruleTitle)?.source }))
         .sort((x, y) => Number(x.source === "global") - Number(y.source === "global"))
         .map((x) => x.a);
     for (const a of ordered) {

package/dist/report/generateReport.d.ts

@@ -11,7 +11,12 @@ export interface ReportMeta {
  * is a valid state (e.g. running against demo data).
  */
 export declare function computeTranscriptHash(sessionFilePath: string | null): string | null;
-export declare function generateReport(results: CheckResult[], meta: ReportMeta): string;
+/**
+ * `transcriptText` is the raw session JSONL. When present, each Broken verdict
+ * gets A4 "why it broke" context (the user message before it, whether the rules
+ * file was in context, whether a compaction preceded it) read straight from it.
+ */
+export declare function generateReport(results: CheckResult[], meta: ReportMeta, transcriptText?: string): string;
 export declare function generateMarkdownReport(results: CheckResult[], meta: ReportMeta): string;
 /**
  * Machine-readable output for CI, a GitHub Action, or any other consumer.

package/dist/report/generateReport.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { breakContext, renderBreakContext } from "../breakContext.js";
 /**
  * Where a rule lives, for the report — "~/proj/CLAUDE.md:42", or just the path
  * when the parser could not place a line, or "" when the rule's location was
@@ -191,7 +192,12 @@ function sharedEvidence(rs) {
     }
     return best;
 }
-export function generateReport(results, meta) {
+/**
+ * `transcriptText` is the raw session JSONL. When present, each Broken verdict
+ * gets A4 "why it broke" context (the user message before it, whether the rules
+ * file was in context, whether a compaction preceded it) read straight from it.
+ */
+export function generateReport(results, meta, transcriptText) {
     const clean = results.map(sanitize);
     const lines = [];
     lines.push(`RuleReceipt · ${meta.ruleCount} rules checked`);
@@ -236,6 +242,13 @@ export function generateReport(results, meta) {
             // 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) {
+                for (const l of renderBreakContext(breakContext(transcriptText, r.evidence)))
+                    lines.push(l);
+            }
         }
     }
     lines.push("");

package/dist/rules.js

@@ -75,20 +75,31 @@ function ruleSourcesAtLevel(dir) {
         for (const f of markdownFilesIn(join(dir, rel)))
             out.push({ path: f, status: "loaded", format: ".claude/rules" });
     }
-    if (has("CLAUDE.md")) {
+    // AGENTS.md / AGENT.md load ONLY when this level has no Claude file at all.
+    // As of Claude Code 2.1.277 (default "Project instructions" = claude-md-or-
+    // agents-md), AGENTS.md is read only when none of CLAUDE.md / CLAUDE.local.md
+    // (nor .claude/CLAUDE.md, handled above) exists — so CLAUDE.local.md ALSO
+    // shadows AGENTS.md, not just CLAUDE.md. Checking a shadowed AGENTS.md would be
+    // a false accusation (it never reaches the agent).
+    // KNOWN LIMIT: the 2.1.277 rule is "no Claude file in cwd OR ABOVE"; this
+    // shadows at the SAME level only. A parent CLAUDE.md shadowing a child
+    // AGENTS.md across levels is not yet modelled (see KNOWN-GAPS).
+    const hasClaudeMd = has("CLAUDE.md");
+    const hasClaudeLocal = has("CLAUDE.local.md");
+    if (hasClaudeMd)
         loaded("CLAUDE.md", "Claude (CLAUDE.md)");
-        // AGENTS.md (and the singular AGENT.md some tools use) are ignored when
-        // there's a CLAUDE.md at this level, mirroring Claude Code's shadow rule.
-        shadowed("AGENTS.md", "AGENTS.md", "a CLAUDE.md at the same level wins");
-        shadowed("AGENT.md", "AGENT.md", "a CLAUDE.md at the same level wins");
+    // .local always loads alongside the base CLAUDE.md when present.
+    if (hasClaudeLocal)
+        loaded("CLAUDE.local.md", "Claude (CLAUDE.local.md)");
+    if (hasClaudeMd || hasClaudeLocal) {
+        const winner = hasClaudeMd ? "CLAUDE.md" : "CLAUDE.local.md";
+        shadowed("AGENTS.md", "AGENTS.md", `a ${winner} at the same level wins`);
+        shadowed("AGENT.md", "AGENT.md", `a ${winner} at the same level wins`);
     }
     else {
         loaded("AGENTS.md", "AGENTS.md");
         loaded("AGENT.md", "AGENT.md");
     }
-    // .local variants: precedence relative to the base files is not documented,
-    // so both are kept rather than guessing at a shadow rule.
-    loaded("CLAUDE.local.md", "Claude (CLAUDE.local.md)");
     loaded("AGENTS.local.md", "AGENTS (AGENTS.local.md)");
     // Non-Claude rule-file conventions (added 2026-09-26 for multi-tool
     // support), read IN ADDITION to Claude's files when present. The engine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.76",
+  "version": "0.1.78",
   "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",