rulereceipt 0.1.44 → 0.1.46

package/README.md

@@ -309,6 +309,52 @@ on a session it never found.
 For most people the honest answer is simpler: run `rulereceipt check --html`
 locally and attach the report to the PR.
 
+### The GitHub Action and the receipt flow
+
+The concrete way to gate in CI: produce a **receipt** where the session
+lives, verify it where it doesn't.
+
+Locally (the session is on your machine), produce and commit a receipt:
+
+```bash
+rulereceipt check --json > .rulereceipt/receipt.json   # commit this file
+```
+
+In CI (no session), verify the committed receipt with the Action:
+
+```yaml
+- uses: rulereceipt/rulereceipt@main   # pin to a release tag once one is cut
+  with:
+    receipt: .rulereceipt/receipt.json
+    max-age-days: "7"                  # optional: reject a stale receipt
+    # anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}  # optional: also fail on CLAUDE.md↔AGENTS.md contradictions
+```
+
+The build **fails** unless the receipt is a real, current, passing
+RuleReceipt receipt. The Action also prints a session-independent audit of
+your CLAUDE.md (`rules --coverage`), and — only if you pass an API key —
+fails on a CLAUDE.md-vs-AGENTS.md contradiction.
+
+Or run the pieces directly:
+
+```bash
+rulereceipt verify-receipt .rulereceipt/receipt.json --max-age-days 7
+```
+
+**Honest trust boundary:** with no session, CI trusts the receipt you
+committed. But if the session *is* available — agentic CI, or you upload the
+transcript — pass it and CI re-derives instead of trusting:
+
+```bash
+rulereceipt verify-receipt .rulereceipt/receipt.json --session path/to/session.jsonl
+```
+
+That re-hashes the session and **rejects a receipt that doesn't match it**
+(forged, tampered, or the wrong session) — no trust required. For the
+no-session case, trust remains until signed/attested receipts land; a
+self-signed receipt would not help (the author holds the key), so the honest
+closure is session re-verification where the session exists.
+
 ## Install
 
 ```bash

package/dist/badge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A shields.io "endpoint" badge, derived from a receipt.
+ *
+ * The user commits the receipt (from `check --json`), runs `rulereceipt badge
+ * <receipt>` to emit this JSON, commits that too, and references it:
+ *   ![rules](https://img.shields.io/endpoint?url=<raw-url-to-the-json>)
+ *
+ * Honest by construction: the badge only ever says what the receipt says.
+ * "passing" means no rule FAILED — UNCLEAR (needs judgment / no key) is not a
+ * failure, same as everywhere else in the tool.
+ */
+export interface Badge {
+    schemaVersion: 1;
+    label: string;
+    message: string;
+    color: string;
+}
+export declare function buildBadge(summary: {
+    pass: number;
+    fail: number;
+    unclear: number;
+}): Badge;

package/dist/badge.js

@@ -0,0 +1,22 @@
+/**
+ * A shields.io "endpoint" badge, derived from a receipt.
+ *
+ * The user commits the receipt (from `check --json`), runs `rulereceipt badge
+ * <receipt>` to emit this JSON, commits that too, and references it:
+ *   ![rules](https://img.shields.io/endpoint?url=<raw-url-to-the-json>)
+ *
+ * Honest by construction: the badge only ever says what the receipt says.
+ * "passing" means no rule FAILED — UNCLEAR (needs judgment / no key) is not a
+ * failure, same as everywhere else in the tool.
+ */
+export function buildBadge(summary) {
+    if (summary.fail > 0) {
+        return { schemaVersion: 1, label: "rules", message: `${summary.fail} failing`, color: "red" };
+    }
+    if (summary.pass > 0) {
+        return { schemaVersion: 1, label: "rules", message: "passing", color: "brightgreen" };
+    }
+    // Nothing failed and nothing deterministically passed — only judgment rules
+    // with nothing to grade. Not green (that would overstate), not red.
+    return { schemaVersion: 1, label: "rules", message: "unclear", color: "lightgrey" };
+}

package/dist/cli.js

@@ -20,13 +20,19 @@ import { runEmojiChecks } from "./checks/emojiOutput.js";
 import { runHook } from "./hook.js";
 import { runGuard } from "./guard.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
-import { generateReport, generateMarkdownReport } from "./report/generateReport.js";
+import { generateReport, generateMarkdownReport, generateJsonReport, computeTranscriptHash } from "./report/generateReport.js";
 import { gateOffer, hookIsInstalled } from "./report/gateOffer.js";
 import { generateHtmlReport } from "./report/generateHtmlReport.js";
 import { verifySessionHash } from "./verifyHash.js";
 import { saveEmailConfig, loadEmailConfig, detectSmtpHost, isValidEmail } from "./emailConfig.js";
 import { sendReportEmail } from "./sendReport.js";
 import { appendHistory, readHistorySince } from "./history.js";
+import { maybeShowWhatsNew } from "./whatsNew.js";
+import { verifyReceipt, parseReceipt } from "./receipt.js";
+import { buildBadge } from "./badge.js";
+import { buildInitGuidance } from "./init.js";
+import { loadProjectConfig, handleMap, blockingFailures, warningFailures, PROJECT_CONFIG_PATH } from "./projectConfig.js";
+import { maybeCheckUpdates, isUpdateCheckEnabled } from "./updateCheck.js";
 import { generateDigest } from "./digest.js";
 import { enableSchedule, disableSchedule, scheduleStatus } from "./schedule.js";
 import { findSplitBrainConflicts } from "./checks/splitBrain.js";
@@ -139,7 +145,7 @@ function writeHtmlReport(results, meta, cwd, target) {
     }
 }
 async function runCheck(opts) {
-    const { markdown, share, email, emailAlways, llm, telemetry, html, exitZero, requireSession, showSkipped, transcriptOverride } = opts;
+    const { markdown, json, checkUpdates, share, email, emailAlways, llm, telemetry, html, exitZero, requireSession, showSkipped, transcriptOverride } = opts;
     const cwd = process.cwd();
     const rules = loadRules(cwd);
     if (rules.length === 0) {
@@ -257,12 +263,26 @@ async function runCheck(opts) {
     // regardless of --llm.
     const judgmentResults = llm ? await runJudgmentChecks(judgment, events) : judgment.map(({ rule }) => needsLlmResult(rule));
     const results = [...deterministicResults, ...judgmentResults];
+    // Severity: rules a team marked as warnings in .rulereceipt/config.json are
+    // still reported but do not fail the build. handleFor maps a result back to
+    // its stable handle so the mark survives edits that renumber rule ids.
+    const projectConfig = loadProjectConfig(cwd);
+    const handleFor = handleMap(rules);
+    const blockingFails = blockingFailures(results, projectConfig, handleFor);
+    const warnedFails = warningFailures(results, projectConfig, handleFor);
     const meta = { sessionFilePath, ruleCount: results.length };
+    // 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);
-    console.log(reportText);
+    if (json) {
+        console.log(generateJsonReport(results, meta, pkg.version));
+    }
+    else {
+        console.log(reportText);
+    }
     // Shown only to someone who has just read their own broken rules, and only
     // if they have not already wired it up. See report/gateOffer.ts.
-    if (!markdown) {
+    if (!markdown && !json) {
         const offer = gateOffer({
             failures: results.filter((r) => r.status === "FAIL").length,
             hookInstalled: hookIsInstalled(cwd),
@@ -287,7 +307,7 @@ async function runCheck(opts) {
     // so, and a rule dropped here never appears in the report at all. Listing
     // them needs no key, works in any language, and lets the person who wrote
     // the rule be the one who decides.
-    if (notARule.length > 0) {
+    if (!json && notARule.length > 0) {
         const n = notARule.length;
         const plural = n === 1 ? "" : "s";
         console.log(`\n(${n} item${plural} in your rules file ${n === 1 ? "was" : "were"} treated as documentation and not checked — directory listings, reference tables, examples.)`);
@@ -315,10 +335,22 @@ async function runCheck(opts) {
             console.log(`Run with --show-skipped to see them.`);
         }
     }
-    if (stale.length > 0) {
+    if (!json && stale.length > 0) {
         console.log(`\n(${stale.length} saved correction${stale.length === 1 ? "" : "s"} no longer match any rule in this project — the rule was probably reworded. Run \`rulereceipt rules --list\` to see them.)`);
     }
+    if (!json && !markdown && warnedFails.length > 0) {
+        console.log(`\n(${warnedFails.length} failing rule${warnedFails.length === 1 ? "" : "s"} ${warnedFails.length === 1 ? "is" : "are"} set to warning in ${PROJECT_CONFIG_PATH} and did not fail the build.)`);
+    }
     appendHistory(results, sessionFilePath);
+    // A once-per-update footer so a returning user sees the tool improved and
+    // comes back. Offline (notes ship in the package), fails open, and never
+    // on --markdown (that output is meant to be pasted into a PR/Slack) or
+    // --json (that output must be a single parseable object, nothing else).
+    if (!markdown && !json) {
+        maybeShowWhatsNew(pkg.version);
+        // Opt-in only; makes no network call unless enabled. Fails open.
+        await maybeCheckUpdates(pkg.version, isUpdateCheckEnabled(checkUpdates));
+    }
     if (share) {
         await shareResults(results);
     }
@@ -348,7 +380,9 @@ async function runCheck(opts) {
     // rules in a real CLAUDE.md need judgment, so without --llm they
     // legitimately report UNCLEAR. Gating on those would make every build
     // red on day one and the check would be deleted within a week.
-    if (!exitZero && results.some((r) => r.status === "FAIL")) {
+    // Gate on BLOCKING failures only — a rule marked warning in the project
+    // config is reported but does not fail the build.
+    if (!exitZero && blockingFails.length > 0) {
         process.exitCode = 1;
     }
 }
@@ -366,6 +400,8 @@ program
     .command("check", { isDefault: true })
     .description("Check the current project's latest Claude Code session against CLAUDE.md/AGENTS.md")
     .option("--markdown", "output as markdown, for pasting into a PR or Slack")
+    .option("--json", "output a machine-readable JSON report instead of text — for CI, a GitHub Action, or any other consumer. Suppresses all human-only output; exit code is unchanged.")
+    .option("--check-updates", "opt-in: check npm for a newer rulereceipt and print a one-line nudge if there is one (at most once a day). Off by default; RULERECEIPT_CHECK_UPDATES=1 also enables it.")
     .option("--share", "opt-in: send anonymous pass/fail/unclear counts only (no rule text, no file paths, no session content). Off by default — no network call happens without this flag.")
     .option("--email", "opt-in: send this report directly from your own email (configured via `rulereceipt config`) to your configured manager email — but only when something actually failed. A manager doesn't need an email for every clean run. RuleReceipt's servers are never involved — sends straight from your machine via your own SMTP credentials.")
     .option("--email-always", "used with --email: send every time, even when nothing failed")
@@ -379,6 +415,8 @@ program
     .action((opts) => {
     runCheck({
         markdown: Boolean(opts.markdown),
+        json: Boolean(opts.json),
+        checkUpdates: Boolean(opts.checkUpdates),
         share: Boolean(opts.share),
         email: Boolean(opts.email),
         emailAlways: Boolean(opts.emailAlways),
@@ -622,6 +660,11 @@ async function runLint(markdown, llm) {
         console.log("No contradictions found between CLAUDE.md and AGENTS.md.");
         return;
     }
+    // A contradiction between the two rule files is a real defect, not just
+    // information: it means the agent is being given conflicting instructions.
+    // Exit non-zero so CI (and the GitHub Action) can gate on it, the same way
+    // `check` exits 1 on a FAIL.
+    process.exitCode = 1;
     if (markdown) {
         const lines = ["## CLAUDE.md vs AGENTS.md — contradictions found", ""];
         for (const c of result.conflicts) {
@@ -714,6 +757,18 @@ program
         process.exitCode = 1;
     });
 });
+program
+    .command("init")
+    .description("Guided setup: shows what's configured and the exact next steps. Read-only — writes nothing.")
+    .action(() => {
+    const cwd = process.cwd();
+    console.log(buildInitGuidance({
+        hasClaudeMd: existsSync(join(cwd, "CLAUDE.md")),
+        hasAgentsMd: existsSync(join(cwd, "AGENTS.md")),
+        hookInstalled: hookIsInstalled(cwd),
+        hasApiKey: Boolean(process.env.ANTHROPIC_API_KEY),
+    }));
+});
 program
     .command("demo")
     .description("See a sample report — no setup, no API key needed")
@@ -814,4 +869,64 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("verify-receipt <path>")
+    .description("CI gate: verify a receipt (produced locally with `check --json` and committed) — that it is a real, current, passing RuleReceipt receipt. No session needed. Exits non-zero if invalid, stale, or anything FAILED.")
+    .option("--max-age-days <n>", "reject a receipt older than N days (freshness gate)")
+    .option("--session <path>", "if the session transcript is available (agentic CI, or you uploaded it), re-hash it and confirm the receipt was produced from THAT session. This is the only check that needs no trust — a mismatch is rejected.")
+    .action((path, opts) => {
+    let text;
+    try {
+        text = readFileSync(path, "utf-8");
+    }
+    catch {
+        console.error(`Could not read receipt file: ${path}`);
+        process.exitCode = 1;
+        return;
+    }
+    const maxAgeDays = opts.maxAgeDays !== undefined ? Number(opts.maxAgeDays) : undefined;
+    if (maxAgeDays !== undefined && !Number.isFinite(maxAgeDays)) {
+        console.error(`--max-age-days must be a number, got: ${opts.maxAgeDays}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Only pass sessionHash when a session was actually requested; null (path
+    // given but unreadable) is a rejection inside verifyReceipt.
+    const sessionHash = opts.session !== undefined ? computeTranscriptHash(opts.session) : undefined;
+    const res = verifyReceipt(text, { maxAgeDays, sessionHash });
+    if (res.ok && res.receipt) {
+        const r = res.receipt;
+        const trust = res.sessionVerified
+            ? "re-verified against the session (no trust needed)"
+            : "trusted (no session provided to re-verify against)";
+        console.log(`✓ receipt OK — rulereceipt v${r.version}, ${r.summary.pass} passed / ${r.summary.fail} failed / ${r.summary.unclear} unclear, generated ${r.generatedAt}\n  ${trust}`);
+    }
+    else {
+        console.error("✕ receipt rejected:");
+        for (const p of res.problems)
+            console.error(`  - ${p}`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("badge <receiptPath>")
+    .description("Emit a shields.io endpoint JSON from a receipt (from `check --json`), for a README badge. Commit the output and reference it: ![rules](https://img.shields.io/endpoint?url=<raw-url>)")
+    .action((receiptPath) => {
+    let text;
+    try {
+        text = readFileSync(receiptPath, "utf-8");
+    }
+    catch {
+        console.error(`Could not read receipt file: ${receiptPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    const parsed = parseReceipt(text);
+    if (parsed.error || !parsed.receipt) {
+        console.error(`Not a valid receipt: ${parsed.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(JSON.stringify(buildBadge(parsed.receipt.summary), null, 2));
+});
 program.parse();

package/dist/init.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `rulereceipt init` — a guided setup that tells you exactly where you are and
+ * what to do next. Read-only on purpose: RuleReceipt audits OTHER tools for
+ * silently writing to .claude/settings.json, so it will not do that itself.
+ * It shows you the snippet to paste; you paste it.
+ */
+export interface InitState {
+    hasClaudeMd: boolean;
+    hasAgentsMd: boolean;
+    hookInstalled: boolean;
+    hasApiKey: boolean;
+}
+/** The PreToolUse guard hook, as it goes into .claude/settings.json. */
+export declare const GUARD_HOOK_SNIPPET = "{\n  \"hooks\": {\n    \"PreToolUse\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"rulereceipt guard\" } ] }\n    ]\n  }\n}";
+export declare function buildInitGuidance(state: InitState): string;

package/dist/init.js

@@ -0,0 +1,55 @@
+/**
+ * `rulereceipt init` — a guided setup that tells you exactly where you are and
+ * what to do next. Read-only on purpose: RuleReceipt audits OTHER tools for
+ * silently writing to .claude/settings.json, so it will not do that itself.
+ * It shows you the snippet to paste; you paste it.
+ */
+/** The PreToolUse guard hook, as it goes into .claude/settings.json. */
+export const GUARD_HOOK_SNIPPET = `{
+  "hooks": {
+    "PreToolUse": [
+      { "hooks": [ { "type": "command", "command": "rulereceipt guard" } ] }
+    ]
+  }
+}`;
+function line(done, label) {
+    return `  ${done ? "✓" : "✗"} ${label}`;
+}
+export function buildInitGuidance(state) {
+    const out = [];
+    out.push("RuleReceipt setup");
+    out.push("");
+    out.push("Where you are:");
+    out.push(line(state.hasClaudeMd || state.hasAgentsMd, "a rules file (CLAUDE.md or AGENTS.md) in this directory"));
+    out.push(line(state.hookInstalled, "a RuleReceipt hook wired into Claude Code (enforcement)"));
+    out.push(line(state.hasApiKey, "ANTHROPIC_API_KEY set (for rules that need judgment)"));
+    out.push("");
+    const steps = [];
+    if (!state.hasClaudeMd && !state.hasAgentsMd) {
+        steps.push("Write a CLAUDE.md in this directory with your rules, one per line or per heading.\n" +
+            '   Even a few lines work — e.g. "Never commit to main" and "Run the tests before committing".');
+    }
+    if (!state.hookInstalled) {
+        steps.push("Turn on enforcement (optional but recommended). Add this to .claude/settings.json,\n" +
+            "   then start a NEW Claude Code session so the hook loads:\n\n" +
+            GUARD_HOOK_SNIPPET.split("\n").map((l) => `     ${l}`).join("\n") +
+            "\n\n   It refuses a command that breaks a file/branch rule before it runs, and fails\n" +
+            "   open on any error. Needs `npm i -g rulereceipt` (or use `npx rulereceipt guard`).");
+    }
+    if (!state.hasApiKey) {
+        steps.push("Set ANTHROPIC_API_KEY (the same key Claude Code uses) if you want rules that need\n" +
+            "   judgment graded. Without it those report UNCLEAR — deterministic checks run regardless,\n" +
+            "   and nothing is ever sent without the --llm flag.");
+    }
+    if (steps.length === 0) {
+        out.push("You're set up. Run:  rulereceipt check");
+    }
+    else {
+        out.push("Next steps:");
+        steps.forEach((s, i) => out.push(`${i + 1}. ${s}`));
+    }
+    out.push("");
+    out.push("See it right now with no setup:  rulereceipt demo");
+    out.push("Check your last real session:    rulereceipt check");
+    return out.join("\n");
+}

package/dist/projectConfig.d.ts

@@ -0,0 +1,25 @@
+import type { CheckResult, Rule } from "./types.js";
+/**
+ * A committed, team-shared config at .rulereceipt/config.json.
+ *
+ * Today it holds one thing: rule handles to treat as WARNINGS — a broken
+ * "warning" rule is still reported, but it does not fail the build. This is
+ * the honest version of "severity": a team marks the must-not-break rules as
+ * errors (the default) and the nice-to-have ones as warnings, so CI gates on
+ * what actually matters instead of going red on day one.
+ *
+ * Handles, not rule ids: an id is positional and renumbers when the file is
+ * edited above it; a handle is a content hash, so it survives edits. Get one
+ * from `rulereceipt rules --list`.
+ */
+export interface ProjectConfig {
+    warn: string[];
+}
+export declare const PROJECT_CONFIG_PATH: string;
+export declare function loadProjectConfig(cwd: string): ProjectConfig;
+/** A lookup from a result back to its stable rule handle, built from the loaded rules. */
+export declare function handleMap(rules: Rule[]): (r: CheckResult) => string;
+/** FAILs that are NOT configured as warnings — these fail the build. */
+export declare function blockingFailures(results: CheckResult[], config: ProjectConfig, handleFor: (r: CheckResult) => string): CheckResult[];
+/** FAILs that ARE configured as warnings — shown, but they do not fail the build. */
+export declare function warningFailures(results: CheckResult[], config: ProjectConfig, handleFor: (r: CheckResult) => string): CheckResult[];

package/dist/projectConfig.js

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ruleFingerprint } from "./overrides.js";
+export const PROJECT_CONFIG_PATH = join(".rulereceipt", "config.json");
+export function loadProjectConfig(cwd) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(cwd, PROJECT_CONFIG_PATH), "utf-8"));
+        const warn = parsed?.warn;
+        return { warn: Array.isArray(warn) ? warn.filter((x) => typeof x === "string") : [] };
+    }
+    catch {
+        // Missing or malformed config means no severities configured, never an
+        // error — same fail-open discipline as the rest of the tool.
+        return { warn: [] };
+    }
+}
+/** A lookup from a result back to its stable rule handle, built from the loaded rules. */
+export function handleMap(rules) {
+    const m = new Map();
+    for (const rule of rules)
+        m.set(`${rule.source}:${rule.id}`, ruleFingerprint(rule));
+    return (r) => m.get(`${r.ruleSource}:${r.ruleId}`) ?? "";
+}
+/** FAILs that are NOT configured as warnings — these fail the build. */
+export function blockingFailures(results, config, handleFor) {
+    return results.filter((r) => r.status === "FAIL" && !config.warn.includes(handleFor(r)));
+}
+/** FAILs that ARE configured as warnings — shown, but they do not fail the build. */
+export function warningFailures(results, config, handleFor) {
+    return results.filter((r) => r.status === "FAIL" && config.warn.includes(handleFor(r)));
+}

package/dist/receipt.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The CI side of RuleReceipt.
+ *
+ * The check itself needs the local Claude Code session transcript, which a CI
+ * runner does not have. So CI does not re-run the check — it verifies a
+ * RECEIPT the developer produced locally with `check --json` and committed:
+ * that it is a real RuleReceipt receipt, a schema this tool understands, not
+ * stale, and that nothing FAILED.
+ *
+ * Honest trust boundary: the receipt commits to the session via its sha256,
+ * but CI has no session to re-hash, so CI is trusting the committed receipt.
+ * A signed/attested receipt closes that gap and is the documented next step;
+ * until then, "verify-receipt" means "this receipt is well-formed, current,
+ * and passing", not "CI independently re-derived it from the session".
+ */
+export interface Receipt {
+    tool: string;
+    schema: number;
+    version: string;
+    generatedAt: string;
+    session: {
+        path: string | null;
+        sha256: string | null;
+    };
+    summary: {
+        total: number;
+        pass: number;
+        fail: number;
+        unclear: number;
+    };
+    results: unknown[];
+}
+/** The receipt schema this tool understands. Bumped in generateJsonReport on any breaking shape change. */
+export declare const KNOWN_SCHEMA = 1;
+export interface VerifyReceiptOptions {
+    /** Reject a receipt whose generatedAt is older than this many days. */
+    maxAgeDays?: number;
+    /**
+     * The sha256 of the actual session file, if it is available to the verifier
+     * (agentic CI, or a developer who uploaded the transcript). When set, the
+     * receipt is re-verified against it: a mismatch is rejected. This is the
+     * only path that closes the trust boundary — CI re-derives instead of
+     * trusting. `null` means "a session was named but could not be read".
+     * `undefined` means "no session provided" (the normal, trust-the-receipt case).
+     */
+    sessionHash?: string | null;
+}
+export interface VerifyResult {
+    ok: boolean;
+    problems: string[];
+    receipt?: Receipt;
+    /** True only when a session was provided AND its hash matched the receipt — i.e. CI re-derived, not trusted. */
+    sessionVerified?: boolean;
+}
+/**
+ * Structural validation only — is this a RuleReceipt receipt at all, with the
+ * fields the verifier relies on. Returns a typed receipt or a reason.
+ */
+export declare function parseReceipt(text: string): {
+    receipt?: Receipt;
+    error?: string;
+};
+/**
+ * The CI gate. ok=false with a reason list means fail the build. UNCLEAR
+ * never fails on its own — same rule as `check`'s exit code: a rule that
+ * needs human judgment is not a violation.
+ */
+export declare function verifyReceipt(text: string, opts?: VerifyReceiptOptions): VerifyResult;

package/dist/receipt.js

@@ -0,0 +1,91 @@
+/**
+ * The CI side of RuleReceipt.
+ *
+ * The check itself needs the local Claude Code session transcript, which a CI
+ * runner does not have. So CI does not re-run the check — it verifies a
+ * RECEIPT the developer produced locally with `check --json` and committed:
+ * that it is a real RuleReceipt receipt, a schema this tool understands, not
+ * stale, and that nothing FAILED.
+ *
+ * Honest trust boundary: the receipt commits to the session via its sha256,
+ * but CI has no session to re-hash, so CI is trusting the committed receipt.
+ * A signed/attested receipt closes that gap and is the documented next step;
+ * until then, "verify-receipt" means "this receipt is well-formed, current,
+ * and passing", not "CI independently re-derived it from the session".
+ */
+/** The receipt schema this tool understands. Bumped in generateJsonReport on any breaking shape change. */
+export const KNOWN_SCHEMA = 1;
+/**
+ * Structural validation only — is this a RuleReceipt receipt at all, with the
+ * fields the verifier relies on. Returns a typed receipt or a reason.
+ */
+export function parseReceipt(text) {
+    let obj;
+    try {
+        obj = JSON.parse(text);
+    }
+    catch (e) {
+        return { error: `not valid JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (obj === null || typeof obj !== "object")
+        return { error: "receipt is not a JSON object" };
+    const o = obj;
+    if (o.tool !== "rulereceipt")
+        return { error: `not a rulereceipt receipt (tool=${JSON.stringify(o.tool)})` };
+    if (typeof o.schema !== "number")
+        return { error: "receipt has no numeric 'schema'" };
+    if (typeof o.generatedAt !== "string")
+        return { error: "receipt has no 'generatedAt' timestamp" };
+    const s = o.summary;
+    if (!s || typeof s.fail !== "number" || typeof s.pass !== "number" || typeof s.unclear !== "number") {
+        return { error: "receipt has no valid 'summary' counts" };
+    }
+    return { receipt: o };
+}
+/**
+ * The CI gate. ok=false with a reason list means fail the build. UNCLEAR
+ * never fails on its own — same rule as `check`'s exit code: a rule that
+ * needs human judgment is not a violation.
+ */
+export function verifyReceipt(text, opts = {}) {
+    const parsed = parseReceipt(text);
+    if (parsed.error)
+        return { ok: false, problems: [parsed.error] };
+    const r = parsed.receipt;
+    const problems = [];
+    if (r.schema > KNOWN_SCHEMA) {
+        problems.push(`receipt schema ${r.schema} is newer than this tool understands (${KNOWN_SCHEMA}) — upgrade rulereceipt`);
+    }
+    if (r.summary.fail > 0) {
+        problems.push(`${r.summary.fail} rule${r.summary.fail === 1 ? "" : "s"} FAILED in this receipt`);
+    }
+    if (opts.maxAgeDays !== undefined) {
+        const ms = Date.now() - new Date(r.generatedAt).getTime();
+        const days = ms / 86_400_000;
+        if (!Number.isFinite(days)) {
+            problems.push(`receipt generatedAt is not a valid date: ${r.generatedAt}`);
+        }
+        else if (days > opts.maxAgeDays) {
+            problems.push(`receipt is ${Math.floor(days)} days old, older than the ${opts.maxAgeDays}-day limit`);
+        }
+    }
+    // Session re-verification: the only check that does not require trust. When
+    // the actual session is available, re-derive its hash and confirm the
+    // receipt was produced from THAT session — a mismatch means forged or wrong.
+    let sessionVerified;
+    if (opts.sessionHash !== undefined) {
+        if (opts.sessionHash === null) {
+            problems.push("a session file was named but could not be read");
+        }
+        else if (r.session.sha256 === null) {
+            problems.push("receipt has no session hash (demo data?), so it cannot be re-verified against a session");
+        }
+        else if (opts.sessionHash !== r.session.sha256) {
+            problems.push("receipt does NOT match the provided session (sha256 mismatch) — forged, tampered, or the wrong session");
+        }
+        else {
+            sessionVerified = true;
+        }
+    }
+    return { ok: problems.length === 0, problems, receipt: r, sessionVerified };
+}

package/dist/report/generateReport.d.ts

@@ -13,3 +13,15 @@ export interface ReportMeta {
 export declare function computeTranscriptHash(sessionFilePath: string | null): string | null;
 export declare function generateReport(results: CheckResult[], meta: ReportMeta): string;
 export declare function generateMarkdownReport(results: CheckResult[], meta: ReportMeta): string;
+/**
+ * Machine-readable output for CI, a GitHub Action, or any other consumer.
+ *
+ * `schema` is versioned deliberately: this is a contract other tools will
+ * parse, so a breaking shape change must bump it rather than silently move
+ * fields under callers. The full (untruncated) sha256 is included so a
+ * consumer can `rulereceipt verify` the session independently — the human
+ * reports only show a prefix. Rule text and evidence are sanitized the same
+ * way as every other output: a hostile CLAUDE.md does not get to smuggle
+ * control characters through the JSON either.
+ */
+export declare function generateJsonReport(results: CheckResult[], meta: ReportMeta, toolVersion: string): string;

package/dist/report/generateReport.js

@@ -266,3 +266,45 @@ export function generateMarkdownReport(results, meta) {
     lines.push(hash ? `\`verify: sha256:${hash.slice(0, 16)}...\` · checked ${new Date().toISOString()}` : `demo data · checked ${new Date().toISOString()}`);
     return lines.join("\n");
 }
+/**
+ * Machine-readable output for CI, a GitHub Action, or any other consumer.
+ *
+ * `schema` is versioned deliberately: this is a contract other tools will
+ * parse, so a breaking shape change must bump it rather than silently move
+ * fields under callers. The full (untruncated) sha256 is included so a
+ * consumer can `rulereceipt verify` the session independently — the human
+ * reports only show a prefix. Rule text and evidence are sanitized the same
+ * way as every other output: a hostile CLAUDE.md does not get to smuggle
+ * control characters through the JSON either.
+ */
+export function generateJsonReport(results, meta, toolVersion) {
+    const clean = results.map(sanitize);
+    const count = (s) => clean.filter((r) => r.status === s).length;
+    const report = {
+        tool: "rulereceipt",
+        schema: 1,
+        version: toolVersion,
+        generatedAt: new Date().toISOString(),
+        session: {
+            path: meta.sessionFilePath,
+            sha256: computeTranscriptHash(meta.sessionFilePath),
+        },
+        summary: {
+            total: clean.length,
+            pass: count("PASS"),
+            fail: count("FAIL"),
+            unclear: count("UNCLEAR"),
+        },
+        results: clean.map((r) => ({
+            ruleId: r.ruleId,
+            ruleTitle: r.ruleTitle,
+            ruleSource: r.ruleSource,
+            status: r.status,
+            outcome: r.outcome ?? null,
+            method: r.method ?? null,
+            needsHuman: r.needsHuman ?? false,
+            evidence: r.evidence,
+        })),
+    };
+    return JSON.stringify(report, null, 2);
+}

package/dist/updateCheck.d.ts

@@ -0,0 +1,11 @@
+export declare function isUpdateCheckEnabled(flag: boolean): boolean;
+/** True if enough time has passed since the last check (or there was none). */
+export declare function shouldCheckNow(now: number, lastCheck: number | null, intervalMs?: number): boolean;
+/** The nudge, or null if the current version is already latest (or newer). */
+export declare function renderUpdateNudge(current: string, latest: string): string | null;
+/**
+ * Orchestration: only when enabled, only when due, fetch the latest version
+ * and nudge if newer. Records the check time even on failure so a flaky
+ * network does not turn into a ping on every single run.
+ */
+export declare function maybeCheckUpdates(current: string, enabled: boolean, log?: (s: string) => void): Promise<void>;

package/dist/updateCheck.js

@@ -0,0 +1,92 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { compareVersions } from "./whatsNew.js";
+/**
+ * The online complement to the offline "what's new" footer: tell someone on
+ * an old global install that a newer version exists.
+ *
+ * OPT-IN, never by default. RuleReceipt's whole promise is that it makes no
+ * network call you did not ask for — telemetry is opt-in for the same reason,
+ * and an auditing tool that quietly phones a registry is the hypocrisy it
+ * exists to catch. Enabled only by --check-updates or RULERECEIPT_CHECK_UPDATES=1,
+ * cached so it pings at most once a day, and fails open on any error.
+ */
+const REGISTRY = "https://registry.npmjs.org/rulereceipt/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+function stampPath() {
+    return join(homedir(), ".rulereceipt", "last-update-check");
+}
+export function isUpdateCheckEnabled(flag) {
+    if (flag)
+        return true;
+    const env = process.env.RULERECEIPT_CHECK_UPDATES;
+    return env === "1" || env === "true";
+}
+/** True if enough time has passed since the last check (or there was none). */
+export function shouldCheckNow(now, lastCheck, intervalMs = CHECK_INTERVAL_MS) {
+    if (lastCheck === null)
+        return true;
+    return now - lastCheck >= intervalMs;
+}
+function readLastCheck() {
+    try {
+        const n = parseInt(readFileSync(stampPath(), "utf-8").trim(), 10);
+        return Number.isFinite(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLastCheck(now) {
+    try {
+        const dir = join(homedir(), ".rulereceipt");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(stampPath(), String(now), "utf-8");
+    }
+    catch {
+        // best-effort
+    }
+}
+/** The nudge, or null if the current version is already latest (or newer). */
+export function renderUpdateNudge(current, latest) {
+    if (compareVersions(latest, current) <= 0)
+        return null;
+    return `\nA newer rulereceipt is available: v${latest} (you have v${current}). Update with: npx rulereceipt@latest`;
+}
+async function fetchLatestVersion() {
+    try {
+        const res = await fetch(REGISTRY, { signal: AbortSignal.timeout(2000) });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Orchestration: only when enabled, only when due, fetch the latest version
+ * and nudge if newer. Records the check time even on failure so a flaky
+ * network does not turn into a ping on every single run.
+ */
+export async function maybeCheckUpdates(current, enabled, log = console.log) {
+    try {
+        if (!enabled)
+            return;
+        if (!shouldCheckNow(Date.now(), readLastCheck()))
+            return;
+        writeLastCheck(Date.now());
+        const latest = await fetchLatestVersion();
+        if (!latest)
+            return;
+        const nudge = renderUpdateNudge(current, latest);
+        if (nudge)
+            log(nudge);
+    }
+    catch {
+        // never let an update check affect the run
+    }
+}

package/dist/whatsNew.d.ts

@@ -0,0 +1,41 @@
+export interface Release {
+    version: string;
+    highlights: string[];
+}
+/**
+ * User-facing release highlights, newest first.
+ *
+ * This is NOT the internal CHANGELOG (developer/business-facing, never
+ * shipped). It is the short, plain "here is what got better" note a user
+ * sees once, the first time they run a new version. Add ONE entry at the
+ * top on each release: what changed, in a sentence, honest, no marketing.
+ *
+ * The whole point: someone who bounced off an early version sees the tool
+ * is improving and comes back. So keep it truthful — a highlight that
+ * overstates is the exact failure this tool exists to catch.
+ */
+export declare const RELEASES: Release[];
+export declare function readLastSeen(): string | null;
+export declare function writeLastSeen(version: string): void;
+/**
+ * Numeric dotted-version compare: <0 if a<b, 0 if equal, >0 if a>b.
+ * Numeric per segment, so 0.1.9 < 0.1.10 (not lexical). Junk gives 0, which
+ * makes the caller show nothing rather than guess.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Releases strictly newer than lastSeen and no newer than current, newest
+ * first. A null lastSeen (first run ever) yields nothing on purpose: a
+ * first-timer should see their report, not a changelog.
+ */
+export declare function highlightsBetween(lastSeen: string | null, current: string, releases?: Release[]): Release[];
+export declare function renderWhatsNew(releases: Release[], current: string): string;
+/**
+ * Prints the "what's new" note once per new version, then records the
+ * current version so it never repeats for that version.
+ *
+ * Fails open, always: any error here must never affect the report the user
+ * actually ran for, and there is no network call — the notes ship inside
+ * the package, so the tool stays true to "nothing leaves your machine".
+ */
+export declare function maybeShowWhatsNew(current: string, log?: (s: string) => void): void;

package/dist/whatsNew.js

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * User-facing release highlights, newest first.
+ *
+ * This is NOT the internal CHANGELOG (developer/business-facing, never
+ * shipped). It is the short, plain "here is what got better" note a user
+ * sees once, the first time they run a new version. Add ONE entry at the
+ * top on each release: what changed, in a sentence, honest, no marketing.
+ *
+ * The whole point: someone who bounced off an early version sees the tool
+ * is improving and comes back. So keep it truthful — a highlight that
+ * overstates is the exact failure this tool exists to catch.
+ */
+export const RELEASES = [
+    {
+        version: "0.1.46",
+        highlights: [
+            "Run RuleReceipt in CI: `--json` output, `verify-receipt`, and a GitHub Action (uses: rulereceipt/rulereceipt).",
+            "`rulereceipt init` for guided setup, and per-rule warnings via .rulereceipt/config.json so CI gates on what matters.",
+            "A README status badge (`rulereceipt badge`), and opt-in `--check-updates`.",
+        ],
+    },
+    { version: "0.1.45", highlights: ["The tool now shows what's improved since you last ran it, like this note."] },
+    { version: "0.1.44", highlights: ["The report now offers to install enforcement, but only when a rule was actually broken."] },
+    { version: "0.1.43", highlights: ["New check: a claim to have read or verified something, with nothing in the session behind it."] },
+    { version: "0.1.41", highlights: ["Emoji rules are checked properly now (Unicode properties, not a hand-written list)."] },
+    { version: "0.1.39", highlights: ["You can mark which clause in a rule is the actual prohibition, so only that blocks."] },
+    { version: "0.1.36", highlights: ["Enforcement arrives: the tool can act on a broken rule with a hook, not just report it."] },
+];
+function stateDir() {
+    return join(homedir(), ".rulereceipt");
+}
+function lastSeenPath() {
+    return join(stateDir(), "last-seen-version");
+}
+export function readLastSeen() {
+    try {
+        const v = readFileSync(lastSeenPath(), "utf-8").trim();
+        return v.length > 0 ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeLastSeen(version) {
+    try {
+        const dir = stateDir();
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(lastSeenPath(), version, "utf-8");
+    }
+    catch {
+        // best-effort; a run that cannot persist this just shows the note again
+    }
+}
+/**
+ * Numeric dotted-version compare: <0 if a<b, 0 if equal, >0 if a>b.
+ * Numeric per segment, so 0.1.9 < 0.1.10 (not lexical). Junk gives 0, which
+ * makes the caller show nothing rather than guess.
+ */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10));
+    const pb = b.split(".").map((n) => parseInt(n, 10));
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (Number.isNaN(x) || Number.isNaN(y))
+            return 0;
+        if (x !== y)
+            return x - y;
+    }
+    return 0;
+}
+/**
+ * Releases strictly newer than lastSeen and no newer than current, newest
+ * first. A null lastSeen (first run ever) yields nothing on purpose: a
+ * first-timer should see their report, not a changelog.
+ */
+export function highlightsBetween(lastSeen, current, releases = RELEASES) {
+    if (!lastSeen)
+        return [];
+    return releases.filter((r) => compareVersions(r.version, lastSeen) > 0 && compareVersions(r.version, current) <= 0);
+}
+export function renderWhatsNew(releases, current) {
+    const lines = [];
+    lines.push(`\n✨ What's new since you last ran rulereceipt (you're on v${current}):`);
+    for (const r of releases) {
+        for (const h of r.highlights) {
+            lines.push(`  • v${r.version}  ${h}`);
+        }
+    }
+    lines.push(`\nThis note shows once per update. To stay current: npx rulereceipt@latest`);
+    return lines.join("\n");
+}
+/**
+ * Prints the "what's new" note once per new version, then records the
+ * current version so it never repeats for that version.
+ *
+ * Fails open, always: any error here must never affect the report the user
+ * actually ran for, and there is no network call — the notes ship inside
+ * the package, so the tool stays true to "nothing leaves your machine".
+ */
+export function maybeShowWhatsNew(current, log = console.log) {
+    try {
+        const lastSeen = readLastSeen();
+        const news = highlightsBetween(lastSeen, current, RELEASES);
+        if (news.length > 0)
+            log(renderWhatsNew(news, current));
+        // Record current even on the first run and even when nothing showed, so
+        // the next update is measured from here.
+        if (lastSeen !== current)
+            writeLastSeen(current);
+    }
+    catch {
+        // never let a footer break the run
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",
@@ -57,6 +57,6 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.68.0",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   }
 }