rulereceipt 0.1.45 → 0.1.47

package/dist/cli.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { readLatestTranscript, readTranscriptFromFile, findLatestSessionFile } from "./parsers/transcriptParser.js";
 import { loadRules } from "./rules.js";
+import { adviseRules } from "./checkability.js";
 import { classifyRules } from "./checks/classify.js";
 import { loadOverrides, saveOverride, clearOverride, staleOverrides, ruleFingerprint, OVERRIDES_PATH } from "./overrides.js";
 import { runDeterministicChecks } from "./checks/deterministicChecks.js";
@@ -20,7 +21,7 @@ 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";
@@ -28,6 +29,11 @@ import { saveEmailConfig, loadEmailConfig, detectSmtpHost, isValidEmail } from "
 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";
@@ -140,7 +146,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) {
@@ -258,12 +264,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),
@@ -288,7 +308,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.)`);
@@ -316,15 +336,21 @@ 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).
-    if (!markdown) {
+    // 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);
@@ -355,7 +381,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;
     }
 }
@@ -373,6 +401,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")
@@ -386,6 +416,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),
@@ -479,11 +511,50 @@ function runCoverage() {
         console.log(`log or inject context, but they cannot make a rule fail when it is ignored.`);
     }
 }
+/**
+ * `rules --advise`: for every rule the classifier can't check mechanically,
+ * one line saying why and the smallest edit that would fix it. The other
+ * half of `--coverage` — that says which rules a hook might guard; this says
+ * which rules can't be checked at all, and how to change that.
+ */
+function runAdvise() {
+    const cwd = process.cwd();
+    const rules = loadRules(cwd);
+    if (rules.length === 0) {
+        console.log("No CLAUDE.md or AGENTS.md found, so there are no rules to advise on.");
+        return;
+    }
+    const advice = adviseRules(rules);
+    const checkable = rules.length - advice.length;
+    console.log(`Rule checkability\n`);
+    console.log(`  ${checkable} of ${rules.length} rule${rules.length === 1 ? "" : "s"} can be checked mechanically as written.`);
+    if (advice.length === 0) {
+        console.log(`\n  Every rule names something a check can bind to. Nothing to fix.`);
+        return;
+    }
+    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 }))
+        .sort((x, y) => Number(x.source === "global") - Number(y.source === "global"))
+        .map((x) => x.a);
+    for (const a of ordered) {
+        const tag = a.kind === "notARule" ? "not a rule?" : "judgment";
+        console.log(`  [${tag}] ${a.ruleTitle.replace(/\s+/g, " ").trim().slice(0, 76)}`);
+        console.log(`    -> ${a.suggestion}\n`);
+    }
+    console.log(`Naming the exact command, file or branch a rule is about — in backticks —`);
+    console.log(`is what turns a "wish list" line into one this tool can hold to account.`);
+}
 async function runRules(opts) {
     if (opts.coverage) {
         runCoverage();
         return;
     }
+    if (opts.advise) {
+        runAdvise();
+        return;
+    }
     const cwd = process.cwd();
     const rules = loadRules(cwd);
     const overrides = loadOverrides(cwd);
@@ -629,6 +700,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) {
@@ -704,6 +780,7 @@ program
     .option("--clear <handle>", "remove a stored correction")
     .option("--list", "show stored corrections (the default when no other flag is given)")
     .option("--coverage", "show which rules a configured hook might actually be enforcing, and which are prose only")
+    .option("--advise", "for each rule that can't be checked mechanically, show why and the smallest edit that would fix it")
     .action((opts) => {
     runRules(opts).catch((err) => {
         console.error("Something went wrong:", err instanceof Error ? err.message : err);
@@ -721,6 +798,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")
@@ -821,4 +910,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/evaluate.js

@@ -6,6 +6,8 @@ import { runCodeContentChecks } from "./checks/codeContent.js";
 import { runFileLifecycleChecks } from "./checks/fileLifecycle.js";
 import { runClaimEvidenceChecks } from "./checks/claimEvidence.js";
 import { runEmojiChecks } from "./checks/emojiOutput.js";
+import { runAttributionChecks } from "./checks/attribution.js";
+import { runApprovalGateChecks } from "./checks/approvalGate.js";
 import { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { loadOverrides, ruleFingerprint, staleOverrides } from "./overrides.js";
 /**
@@ -40,6 +42,8 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
         ...runFileLifecycleChecks(of("fileLifecycle"), events),
         ...runClaimEvidenceChecks(of("claimEvidence"), events),
         ...runEmojiChecks(of("emojiOutput"), events),
+        ...runAttributionChecks(of("attribution"), events),
+        ...runApprovalGateChecks(of("approvalGate"), events),
     ];
     const judgment = of("judgment");
     const judgmentResults = llm

package/dist/guard.js

@@ -3,6 +3,7 @@ import { classifyRules } from "./checks/classify.js";
 import { runCodeContentChecks } from "./checks/codeContent.js";
 import { runFileLifecycleChecks } from "./checks/fileLifecycle.js";
 import { runGitBranchPolicyChecks } from "./checks/gitBranchPolicy.js";
+import { runAttributionChecks } from "./checks/attribution.js";
 import { loadOverrides, ruleFingerprint, ratifiedForbids } from "./overrides.js";
 import { commandRunsLiteral } from "./checks/proposedAction.js";
 function readStdin() {
@@ -48,6 +49,11 @@ function structuredBlocks(cwd, event) {
         ...runCodeContentChecks(of("codeContent"), [event]),
         ...runFileLifecycleChecks(of("fileLifecycle"), [event]),
         ...runGitBranchPolicyChecks(of("gitBranchPolicy"), [event]),
+        // Prevention for the attribution rule: a commit/PR carrying a
+        // `Co-Authored-By: Claude` / "Generated with Claude Code" trailer is
+        // refused before it is made, not just reported after. Reuses the exact
+        // detection the report uses, so the two cannot disagree.
+        ...runAttributionChecks(of("attribution"), [event]),
     ];
     return results
         .filter((r) => r.status === "FAIL")

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;