rulereceipt 0.1.51 → 0.1.53

package/dist/checks/classify.js

@@ -567,6 +567,13 @@ export function approvalGateActions(rule) {
 function isApprovalGateRule(rule) {
     return approvalGateActions(rule).length > 0;
 }
+/**
+ * A subordinating condition that scopes when a prohibition applies. A literal
+ * matcher cannot read it, so a forbid carrying one is routed to judgment
+ * rather than flagged on every occurrence. Kept to clear scoping words so a
+ * flat prohibition that merely contains "if" in passing is not swept in.
+ */
+const CONDITIONAL_SCOPE = /\b(?:when(?:ever)?|unless|except\s+when|only\s+(?:if|when)|as\s+long\s+as|provided\s+that|in\s+cases?\s+where)\b|\bif\s+(?:you|the|it|they|we|a|an|on|in|running|building|committing|pushing|deploying)\b/i;
 export function classifyRule(rule) {
     // Checked first: if this isn't a rule at all, no check of any kind
     // should run against it — not a keyword match, not an LLM call.
@@ -634,6 +641,19 @@ export function classifyRule(rule) {
     if (BRANCH_WORD.test(text) && branchName !== undefined) {
         return { kind: "gitBranchPolicy", rule, branchName, polarity, polarityInferred };
     }
+    // A forbid scoped by a condition the literal checkers cannot evaluate.
+    //
+    // Raised by etoryoki on anthropics/claude-code#2544: "Never run `terraform
+    // apply` when you're on main" read as "never run it" flags every correct run
+    // elsewhere. A deterministic literal match sees only the command, not the
+    // "when/unless/if" that scopes it, so it accuses every occurrence. Routing
+    // these to judgment lets the condition actually be weighed — the same choice
+    // etoryoki made ("treat conditional or hedged sentences as not checkable
+    // instead of guessing"). Placed AFTER the branch check on purpose:
+    // gitBranchPolicy evaluates its own branch condition and must keep those.
+    if (polarity === "forbid" && CONDITIONAL_SCOPE.test(text)) {
+        return { kind: "judgment", rule };
+    }
     // Route on ANY code-shaped literal, but check ONLY the code-shaped ones.
     // This used to pass every literal through once one of them looked like
     // code, so a rule mentioning `foo(` and `name` searched written files for

package/dist/cli.js

@@ -11,6 +11,7 @@ import { loadRules } from "./rules.js";
 import { adviseRules } from "./checkability.js";
 import { shadowedAgentsMd } from "./shadowedAgents.js";
 import { partitionByAge, futureResult } from "./ruleAge.js";
+import { auditSessions, renderComplianceReport } from "./report/complianceReport.js";
 import { classifyRules } from "./checks/classify.js";
 import { loadOverrides, saveOverride, clearOverride, staleOverrides, ruleFingerprint, OVERRIDES_PATH } from "./overrides.js";
 import { runDeterministicChecks } from "./checks/deterministicChecks.js";
@@ -865,6 +866,16 @@ const PERIOD_MS = {
     weekly: 7 * 24 * 60 * 60 * 1000,
     monthly: 30 * 24 * 60 * 60 * 1000,
 };
+program
+    .command("report")
+    .description("Compliance report across your recent sessions (not just the latest): which policy rules were broken, where, with evidence. Deterministic, local, no network. The org-wide version runs via the Claude Compliance API for Enterprise orgs.")
+    .option("--last <n>", "how many recent sessions to audit", "25")
+    .option("--markdown", "output as markdown, for a report you can send")
+    .action(async (opts) => {
+    const n = Number.parseInt(String(opts.last), 10);
+    const r = await auditSessions(process.cwd(), Number.isFinite(n) ? n : 25);
+    console.log(renderComplianceReport(r, Boolean(opts.markdown)));
+});
 program
     .command("digest")
     .description("A non-technical summary of recent check runs (counts only, no rule text) — for a manager who doesn't have time to read 30 individual reports.")

package/dist/parsers/transcriptParser.d.ts

@@ -5,6 +5,8 @@ import type { TranscriptEvent } from "../types.js";
  * variant could keep its own global rules file under its own home dir.
  */
 export declare function findClaudeHomeDirNames(): string[];
+/** Every session file for this project, newest first. */
+export declare function listAllSessionFiles(cwd: string): string[];
 export declare function findLatestSessionFile(cwd: string): string | null;
 export declare function parseLine(line: string): TranscriptEvent[];
 /**

package/dist/parsers/transcriptParser.js

@@ -69,13 +69,16 @@ export function findClaudeHomeDirNames() {
         return [];
     }
 }
-export function findLatestSessionFile(cwd) {
+/** Every session file for this project, newest first. */
+export function listAllSessionFiles(cwd) {
     const encoded = encodeProjectPath(cwd);
     const sessionFiles = findClaudeHomeDirNames().flatMap((dirName) => listSessionFiles(join(homedir(), dirName, "projects", encoded)));
-    if (sessionFiles.length === 0)
-        return null;
     sessionFiles.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
-    return sessionFiles[0];
+    return sessionFiles;
+}
+export function findLatestSessionFile(cwd) {
+    const all = listAllSessionFiles(cwd);
+    return all.length > 0 ? all[0] : null;
 }
 function extractToolResultText(content) {
     if (typeof content === "string")

package/dist/report/complianceReport.d.ts

@@ -0,0 +1,35 @@
+import type { CheckResult } from "../types.js";
+/**
+ * A compliance report over MANY sessions, not one.
+ *
+ * The free `check` reads a single latest session — one dev, one run. The
+ * enterprise question is different: "across every agent session in this org
+ * this month, which policy rules were broken, and where's the evidence?"
+ * This aggregates per-session results into that org-style summary. It runs on
+ * whatever sessions are reachable locally today; the same aggregation feeds
+ * the Compliance API (org-wide sessions) once an enterprise grants a key.
+ *
+ * Deterministic by default — no LLM, no network — so it can run over hundreds
+ * of sessions fast. Judgment rules are surfaced as "needs review", never
+ * guessed at, same honesty as everywhere else.
+ */
+export interface SessionAudit {
+    session: string;
+    when: string;
+    events: number;
+    violations: CheckResult[];
+}
+export interface ComplianceReport {
+    sessionsChecked: number;
+    sessionsWithViolations: number;
+    totalViolations: number;
+    ruleCount: number;
+    byRule: {
+        title: string;
+        count: number;
+    }[];
+    sessions: SessionAudit[];
+}
+export declare function auditSessions(cwd: string, limit: number): Promise<ComplianceReport>;
+/** A readable / pasteable compliance report. Markdown when `md` is set. */
+export declare function renderComplianceReport(r: ComplianceReport, md?: boolean): string;

package/dist/report/complianceReport.js

@@ -0,0 +1,76 @@
+import { basename } from "node:path";
+import { loadRules } from "../rules.js";
+import { evaluateSession } from "../evaluate.js";
+import { readTranscriptFromFile, listAllSessionFiles } from "../parsers/transcriptParser.js";
+function needsReview(rule) {
+    return {
+        ruleId: rule.id, ruleTitle: rule.title, ruleSource: rule.source,
+        status: "UNCLEAR", outcome: "not_run", method: "none", needsHuman: true,
+        evidence: "judgment rule — not graded without --llm",
+    };
+}
+export async function auditSessions(cwd, limit) {
+    const rules = loadRules(cwd);
+    const files = listAllSessionFiles(cwd).slice(0, Math.max(1, limit));
+    const sessions = [];
+    const byRule = new Map();
+    let totalViolations = 0;
+    for (const file of files) {
+        const events = readTranscriptFromFile(file);
+        if (events.length === 0)
+            continue;
+        const { results } = await evaluateSession(cwd, rules, events, false, needsReview);
+        const violations = results.filter((r) => r.status === "FAIL");
+        for (const v of violations)
+            byRule.set(v.ruleTitle, (byRule.get(v.ruleTitle) ?? 0) + 1);
+        totalViolations += violations.length;
+        const first = events.find((e) => e.timestamp)?.timestamp ?? "";
+        sessions.push({ session: basename(file).replace(/\.jsonl$/, ""), when: first.slice(0, 10), events: events.length, violations });
+    }
+    return {
+        sessionsChecked: sessions.length,
+        sessionsWithViolations: sessions.filter((s) => s.violations.length > 0).length,
+        totalViolations,
+        ruleCount: rules.length,
+        byRule: [...byRule.entries()].map(([title, count]) => ({ title, count })).sort((a, b) => b.count - a.count),
+        sessions,
+    };
+}
+/** A readable / pasteable compliance report. Markdown when `md` is set. */
+export function renderComplianceReport(r, md = false) {
+    const H = (s) => (md ? `## ${s}` : s);
+    const out = [];
+    out.push(md ? "# RuleReceipt — Compliance Report" : "RuleReceipt · Compliance Report");
+    out.push("");
+    out.push(`Checked ${r.sessionsChecked} session${r.sessionsChecked === 1 ? "" : "s"} against ${r.ruleCount} rules (project + global).`);
+    out.push("");
+    out.push(`${r.sessionsWithViolations} of ${r.sessionsChecked} sessions had at least one policy violation.`);
+    out.push(`${r.totalViolations} total violation${r.totalViolations === 1 ? "" : "s"} across ${r.byRule.length} distinct rule${r.byRule.length === 1 ? "" : "s"}.`);
+    out.push("");
+    if (r.byRule.length > 0) {
+        out.push(H("Most-violated rules"));
+        for (const { title, count } of r.byRule.slice(0, 10)) {
+            out.push(`  ${String(count).padStart(3)}×  ${title.replace(/\s+/g, " ").trim().slice(0, 70)}`);
+        }
+        out.push("");
+    }
+    const flagged = r.sessions.filter((s) => s.violations.length > 0);
+    if (flagged.length > 0) {
+        out.push(H("Sessions with violations"));
+        for (const s of flagged) {
+            out.push(`  ${s.session.slice(0, 12)}  ${s.when}  — ${s.violations.length} violation${s.violations.length === 1 ? "" : "s"}`);
+            for (const v of s.violations.slice(0, 5)) {
+                out.push(`    ✕ ${v.ruleTitle.replace(/\s+/g, " ").trim().slice(0, 66)}`);
+                out.push(`      ${v.evidence.replace(/\s+/g, " ").trim().slice(0, 90)}`);
+            }
+        }
+        out.push("");
+    }
+    else {
+        out.push("No mechanical policy violations found in the sessions checked.");
+        out.push("");
+    }
+    out.push("Deterministic checks only. Judgment rules are not graded here (run per-session with --llm).");
+    out.push("Local sessions today; the same report runs org-wide via the Claude Compliance API for Enterprise orgs.");
+    return out.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",