rulereceipt 0.1.73 → 0.1.75

package/README.md

@@ -332,12 +332,25 @@ npx rulereceipt wrong <rule-handle>
 
 Builds a report of that rule, the verdict, how it was decided and the
 session lines around it, with obvious secrets, your home path and email
-addresses masked. It is saved to `.rulereceipt/wrong-<handle>.md` and
-printed so you can read and edit it, along with a link to a pre-filled
-GitHub issue that you open yourself. Nothing is sent. `check` prints the
-command after every report that has a decided verdict, and the HTML report
-has a "Verdict wrong?" link on each one that carries only the version and
-the verdict, never the rule or the evidence.
+addresses masked (GitHub/Slack/Stripe tokens, JWTs, passwords in URLs,
+private-key blocks and `.env`-style `KEY=value` lines too — but masking
+catches common formats only, so read it before sending). It is saved to
+`.rulereceipt/wrong-<handle>.md` and printed so you can read and edit it.
+
+Nothing is ever sent automatically. After showing the report you get three
+choices:
+
+```bash
+rulereceipt wrong <rule> --submit   # open a PUBLIC GitHub issue (asks y/N first; needs gh)
+rulereceipt wrong <rule> --email    # a mailto: to hello@rulereceipt.dev, private
+rulereceipt wrong <rule>            # just print the report + a pre-filled issue link
+```
+
+`--submit` shows the full report, then asks before creating anything — the
+default answer is No, and `--yes` does not skip that question. If `gh` isn't
+installed or logged in, or you're not at a terminal, it never sends: it
+prints the pre-filled link for you to open yourself. You can pass a rule by
+the short handle or by the id shown in the report (e.g. `S1.2`).
 
 Every accuracy fix in this project has come from a report like this.
 
@@ -498,8 +511,26 @@ so you can verify the published package was built from this repository at
 a specific commit. No publishing token exists to be stolen. Check it
 yourself with `npm audit signatures` after installing.
 
-**Licence.** Source-available software — see [LICENSE](./LICENSE) and
-[NOTICE.md](./NOTICE.md) before reusing this code.
+**Licence.** Source-available, not OSI open source: the code is public and
+you can read, run and modify it for yourself, but reuse is limited — see
+[LICENSE](./LICENSE) and [NOTICE.md](./NOTICE.md) before reusing it.
+
+**Windows.** Not tested yet. RuleReceipt is developed and tested on macOS
+and Linux. It may work on Windows, but nothing there is verified — treat it
+as unsupported until this note changes.
+
+## Uninstalling
+
+Easy to remove, no leftovers:
+
+```bash
+rulereceipt protect --undo     # restores .claude/settings.json byte-for-byte
+npm uninstall -g rulereceipt   # or: npm rm rulereceipt in a project
+rm -rf .rulereceipt/           # the local reports/receipts folder, if you want it gone
+```
+
+`protect --undo` is only needed if you ran `protect`. Nothing else is
+installed anywhere on your system.
 
 ## Contact
 

package/dist/checks/approvalGate.d.ts

@@ -46,6 +46,8 @@ export interface ApprovalOptions {
     allow?: string[];
     /** When set, a `push` action is only gated if it targets this branch (or its target is unknown). */
     scopedBranch?: string;
+    /** The current git branch (guard only), so a bare `git push` from a feature branch is not gated by a "push to main" rule. */
+    currentBranch?: string;
 }
 interface Occurrence {
     action: Action;

package/dist/checks/approvalGate.js

@@ -75,7 +75,7 @@ export function approvalScopedBranch(rule) {
  * push to a DIFFERENT branch returns false, so a feature-branch push is not
  * gated by a rule that names main.
  */
-function pushTargetsBranch(command, branch) {
+function pushTargetsBranch(command, branch, currentBranch) {
     const m = command.match(/\bgit\s+(?:\S+\s+){0,4}?push\b(.*)/i);
     if (!m)
         return true;
@@ -88,7 +88,13 @@ function pushTargetsBranch(command, branch) {
         const b = tokens[tokens.length - 1];
         return b === branch || b.endsWith(`/${branch}`);
     }
-    return true; // bare `git push` / `git push origin` — unknown target, gate to be safe
+    // Bare `git push` / `git push origin` — the target is the CURRENT branch. When
+    // the guard can tell us that branch, gate only if it is the scoped branch (a
+    // bare push from a feature branch is not a push to main). When it is unknown
+    // (the check path, or git unavailable), gate to be safe.
+    if (currentBranch)
+        return currentBranch === branch || currentBranch.endsWith(`/${branch}`);
+    return true;
 }
 /** The result for the call at `i`: matched by id when present, else the next result. */
 function resultOf(events, i) {
@@ -128,7 +134,7 @@ export function approvalOccurrences(events, actions, opts = {}) {
                 continue;
             // A branch-scoped push rule ("push to main") does not gate a push to a
             // different branch — only main (or a bare push whose target is unknown).
-            if (action === "push" && opts.scopedBranch && !pushTargetsBranch(command, opts.scopedBranch))
+            if (action === "push" && opts.scopedBranch && !pushTargetsBranch(command, opts.scopedBranch, opts.currentBranch))
                 continue;
             const res = resultOf(events, i);
             if (res && res.kind === "tool_result" && res.isError)

package/dist/checks/claimEvidence.js

@@ -200,6 +200,10 @@ function outcomeFromOutput(output) {
         return false;
     return null;
 }
+/** A test command carrying a leading env-var assignment is a variant of the default run. */
+function isVariantRun(command) {
+    return /(?:^|&&|;|\|\||\bthen\b|\bdo\b|\s)\s*[A-Z][A-Z0-9_]+=\S+\s+\S/.test(command);
+}
 /**
  * A command short enough to read in a report.
  *
@@ -322,6 +326,7 @@ export function runClaimEvidenceChecks(classifications, events) {
                     failed: stated !== null ? stated : event.isError,
                     outcomeReadable: oneRun && (stated !== null || trustExitCode),
                     output: event.content.slice(0, 200),
+                    variant: isVariantRun(pendingRun),
                 };
                 pendingRuns.delete(resultId);
                 unknownSinceRed = null; // a recognised run supersedes anything before it
@@ -378,6 +383,12 @@ export function runClaimEvidenceChecks(classifications, events) {
                 if (uncertain === null)
                     uncertain = { claim: sentence.trim(), script: unknownSinceRed };
             }
+            else if (lastRun.failed && lastRun.variant) {
+                // A deliberately-different variant run (env-var prefix) failing does not
+                // contradict a claim about the DEFAULT suite — the honest case where
+                // "npm test" passes and "DISABLE_LOCKS=1 npm test" is reported failing in
+                // the same breath. Not a contradiction; leave it can't-tell.
+            }
             else if (lastRun.failed && contradiction === null) {
                 contradiction = { claim: sentence.trim(), run: lastRun };
             }

package/dist/checks/classify.js

@@ -626,7 +626,12 @@ const GATE_ACTIONS = [
 ];
 const GATE_NEG = String.raw `\b(?:never|don'?t|do\s+not|must\s+not|mustn'?t|should\s+not|shouldn'?t|no)\b`;
 const GATE_CONSENT = String.raw `\b(?:without\s+(?:(?:the\s+)?(?:user'?s?|my|your|an?)\s+)?(?:explicit(?:ly)?\s+|express\s+|prior\s+)?(?:(?:the\s+)?user'?s?\s+|my\s+)?(?:permission|approval|consent|confirmation|instruction|request|sign[- ]?off|go[- ]?ahead|asking|being\s+(?:asked|told|instructed))|unless\s+(?:(?:the\s+)?user|i|you\s+are|explicitly)\s*(?:explicitly\s+)?(?:asks?|asked|requests?|requested|says?|tells?|told|instructs?|instructed|approves?|approved|confirms?)|until\s+(?:the\s+)?user\s+(?:confirms|approves|says|asks))\b`;
-const GATE_ASK_BEFORE = String.raw `\b(?:ask|check\s+with\s+(?:me|the\s+user)|confirm|get\s+(?:approval|permission|sign[- ]?off)|wait\s+for\s+(?:(?:the\s+)?(?:user|me)|approval|confirmation|explicit|sign[- ]?off))\b(?:\s+\w+){0,4}?\s+(?:before|prior\s+to)\b`;
+// "confirm" alone means VERIFY, not "ask the user" — found on unseen data
+// 2026-09-29: a file note "`extension-report.py` … confirm before committing"
+// became a blanket commit-approval gate. So a bare "confirm"/"check" no longer
+// counts; it must be "confirm/check WITH me/the user". "ask", "get approval" and
+// "wait for approval" before the action still count.
+const GATE_ASK_BEFORE = String.raw `\b(?:ask|(?:check|confirm)\s+with\s+(?:me|the\s+user|us)|get\s+(?:approval|permission|sign[- ]?off)|wait\s+for\s+(?:(?:the\s+)?(?:user|me)|approval|confirmation|explicit|sign[- ]?off))\b(?:\s+\w+){0,4}?\s+(?:before|prior\s+to)\b`;
 /**
  * Which gated actions a rule makes conditional on the user's say-so.
  *

package/dist/checks/codeContent.js

@@ -45,7 +45,21 @@ function editedContentFromEvent(event) {
  * open paren or a call — so requiring a boundary after it would reject the
  * arguments.
  */
+/**
+ * The token sits inside a natural-language sentence (a lowercase word + space
+ * right before it, and a space + lowercase word right after) — a MENTION, not
+ * code. Found on unseen data 2026-09-29: "Avoid `try-catch` in hot paths" FAILed
+ * (and the guard blocked a Write) because "try-catch" appears in the prose
+ * "...use a try-catch block...". A real import (`from "lucide-react"`) is not
+ * sandwiched in prose (it is bounded by quotes), so it still matches.
+ */
+function isProseSandwich(content, at, pattern) {
+    const before = content.slice(Math.max(0, at - 12), at);
+    const after = content.slice(at + pattern.length, at + pattern.length + 12);
+    return /[a-z]\s$/.test(before) && /^\s[a-z]/.test(after);
+}
 function containsCall(content, pattern) {
+    const isCall = pattern.endsWith("(");
     const leadsWithIdentifier = /^[A-Za-z0-9_$]/.test(pattern);
     if (!leadsWithIdentifier) {
         // A CALL like `.forEach(` legitimately follows an object (`arr.forEach()`),
@@ -79,8 +93,14 @@ function containsCall(content, pattern) {
         // continuation — `analytics.track(` is a real call to `track(`. So `.` is
         // NOT in the disqualifying class (fixed 2026-09-26); `_` still is, so
         // `_metar_fetch(` does not match `fetch(`.
-        if (!/[A-Za-z0-9_$]/.test(before))
+        if (!/[A-Za-z0-9_$]/.test(before)) {
+            // A non-call token embedded in a prose sentence is a mention, not code.
+            if (!isCall && isProseSandwich(content, at, pattern)) {
+                from = at + 1;
+                continue;
+            }
             return true;
+        }
         from = at + 1;
     }
 }

package/dist/cli.js

@@ -14,9 +14,12 @@ import { shadowedAgentsMd } from "./shadowedAgents.js";
 import { auditSessions, renderComplianceReport } from "./report/complianceReport.js";
 import { auditProject, renderProjectAudit } from "./audit.js";
 import { evaluateSession } from "./evaluate.js";
-import { buildWrongReport, findTarget } from "./wrong.js";
+import { buildWrongReport, findTarget, reportedLabel } from "./wrong.js";
+import { ghReady, issueTitle, issueCreateArgs, buildMailto, mailtoSubject } from "./wrongSubmit.js";
+import { spawnSync } from "node:child_process";
 import { detectSelfEditedRuleFiles } from "./checks/selfEditedRules.js";
 import { scanHistory, renderHistory } from "./historyReport.js";
+import { explainRule, renderWhy } from "./why.js";
 import { observeSessions, renderNoRules, draftRulesFromHistory } from "./sessionObserve.js";
 import { listSessionRows, renderSessionList } from "./listSessions.js";
 import { runSelfTestChecks, renderSelfTest } from "./selftest.js";
@@ -949,12 +952,36 @@ program
     }
     console.log(renderProjectAudit(a, Boolean(opts.markdown)));
 });
+program
+    .command("why <rule...>")
+    .description("Everything the tool knows about ONE rule, in one place: where it lives (file:line), whether the agent actually loads it, whether a command or path it names exists, whether it's mechanically checkable (and if not, one suggested rewrite), and how it did over the last 30 days. Fuzzy-matches the rule text; if several match, lists them. Read-only — no verdict is created, nothing is sent.")
+    .option("--json", "output machine-readable JSON (the same fields)")
+    .action(async (ruleWords, opts) => {
+    const cwd = process.cwd();
+    const query = ruleWords.join(" ").trim();
+    const rules = loadRules(cwd);
+    if (rules.length === 0) {
+        console.log("No rules file found here, so there is nothing to explain. Run `rulereceipt init` to add one.");
+        process.exitCode = 1;
+        return;
+    }
+    const result = await explainRule(cwd, query);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(renderWhy(result));
+    if (result.matches === 0 || result.candidates)
+        process.exitCode = 1;
+});
 program
     .command("wrong <rule>")
     .description("A verdict looks wrong? Builds a report of that rule, the verdict, how it was decided and the session lines around it, with obvious secrets masked. Written to a local file and shown first; prints a GitHub issue link for you to open. Nothing is sent.")
     .option("--transcript <path>", "use a specific session file (same as check)")
     .option("--out <path>", "where to write the report (default .rulereceipt/wrong-<handle>.md)")
     .option("--no-context", "leave out the session lines around the evidence")
+    .option("--submit", "after showing the report, offer to open a PUBLIC GitHub issue (asks first; needs gh)")
+    .option("--email", "print a mailto: to send the report privately to the maintainer")
     .action(async (ruleArg, opts) => {
     const cwd = process.cwd();
     const rules = loadRules(cwd);
@@ -974,7 +1001,13 @@ program
     const { results } = await evaluateSession(cwd, rules, events, false, needsLlmResult);
     const target = findTarget(ruleArg, rules, results);
     if (!target) {
-        console.log(`No checked rule matches "${ruleArg}". Use the handle from \`rulereceipt check --json\` or the rule id shown in the report.`);
+        console.log(`No checked rule matches "${ruleArg}".`);
+        const valid = results.map((r) => `  ${r.ruleId}  ${r.ruleTitle.replace(/\s+/g, " ").slice(0, 70)}`);
+        if (valid.length > 0) {
+            console.log("Valid ids from the latest session (use one of these, or the handle from `rulereceipt check --json`):");
+            for (const line of valid.slice(0, 40))
+                console.log(line);
+        }
         process.exitCode = 1;
         return;
     }
@@ -991,8 +1024,51 @@ program
     writeFileSync(outPath, report.markdown);
     console.log(report.markdown);
     console.log(`\nSaved to ${outPath}. Nothing was sent.`);
-    console.log("Read it, edit anything private, then open this link to file it (the form is pre-filled; add what you expected):");
-    console.log(report.issueUrl);
+    const reported = reportedLabel(target.result);
+    if (opts.submit) {
+        // PUBLIC issue. Preview was just printed; --yes does NOT bypass this ask.
+        if (!ghReady()) {
+            console.log("\ngh (GitHub CLI) is not installed or not logged in — nothing was sent.");
+            console.log("Install/login with `gh auth login`, or open this pre-filled link yourself:");
+            console.log(report.issueUrl);
+            return;
+        }
+        const ok = await confirmYesNo("\nThis creates a PUBLIC issue on github.com/rulereceipt/rulereceipt from your GitHub account. Anyone can read it. Send it? (y/N) ");
+        if (!ok) {
+            console.log("Not sent. The report is saved locally; you can open the link above anytime.");
+            return;
+        }
+        const title = issueTitle(reported, target.rule.title);
+        let res = spawnSync("gh", issueCreateArgs(title, report.markdown, true), { encoding: "utf-8" });
+        if (res.status !== 0) {
+            // The wrong-verdict label may not exist yet: retry without it.
+            res = spawnSync("gh", issueCreateArgs(title, report.markdown, false), { encoding: "utf-8" });
+        }
+        if (res.status === 0) {
+            const url = (res.stdout || "").trim();
+            console.log(`\nOpened: ${url || "issue created"}`);
+        }
+        else {
+            console.log("\nCould not create the issue automatically — nothing was sent. Open this link instead:");
+            console.log(report.issueUrl);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (opts.email) {
+        const { url, trimmed } = buildMailto(mailtoSubject(target.rule.title), report.markdown);
+        console.log("\nSend privately to the maintainer:");
+        console.log(url);
+        console.log(`\nIf your mail app doesn't open, email hello@rulereceipt.dev and attach: ${outPath}`);
+        if (trimmed)
+            console.log("(The report was long, so the email body is trimmed — attach the saved file above.)");
+        return;
+    }
+    // No flag: show the three ways to send, plus the pre-filled link.
+    console.log(`\nRead it first, then:`);
+    console.log(`  Send publicly:   rulereceipt wrong ${ruleArg} --submit`);
+    console.log(`  Send privately:  rulereceipt wrong ${ruleArg} --email`);
+    console.log(`  Or open:         ${report.issueUrl}`);
 });
 program
     .command("digest")

package/dist/guard.js

@@ -8,6 +8,23 @@ import { loadOverrides, ruleFingerprint, ratifiedForbids } from "./overrides.js"
 import { commandRunsLiteral } from "./checks/proposedAction.js";
 import { approvalOccurrences, allowListed, approvalCommandShort, approvalScopedBranch } from "./checks/approvalGate.js";
 import { readTranscriptFromFile } from "./parsers/transcriptParser.js";
+import { execFileSync } from "node:child_process";
+/**
+ * The current git branch in `cwd`, or undefined if it can't be determined —
+ * so a bare `git push` from a feature branch is not gated by a "push to main"
+ * rule. Fails open (never throws, never blocks) if git is unavailable.
+ */
+function gitCurrentBranch(cwd) {
+    try {
+        // `symbolic-ref --short HEAD` gives the branch name even on an unborn branch
+        // (no commits yet); `rev-parse --abbrev-ref` returns "HEAD" there.
+        const b = execFileSync("git", ["symbolic-ref", "--short", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 1000 }).trim();
+        return b && b !== "HEAD" ? b : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -204,7 +221,7 @@ function unapprovedGate(cwd, command, events) {
     const gates = classifyRules(loadRules(cwd)).filter((c) => c.kind === "approvalGate");
     for (const { rule, actions } of gates) {
         const proposed = { role: "assistant", kind: "tool_use", toolName: "Bash", input: { command }, timestamp: "", permissionMode: "dontAsk" };
-        const occ = approvalOccurrences([...events, proposed], actions, { scopedBranch: approvalScopedBranch(rule) });
+        const occ = approvalOccurrences([...events, proposed], actions, { scopedBranch: approvalScopedBranch(rule), currentBranch: gitCurrentBranch(cwd) });
         const last = occ[occ.length - 1];
         // Compare against the SAME canonical short the occurrence uses (mention
         // segments dropped, `sh -c` unwrapped) — a raw-string compare missed a

package/dist/historyReport.js

@@ -1,6 +1,18 @@
 import { statSync } from "node:fs";
 import { listAllSessions } from "./adapters/index.js";
 import { evaluateSession } from "./evaluate.js";
+/**
+ * One-line clip that ends on a whole word with an ellipsis, never mid-sentence.
+ * Found by a real test 2026-09-29: a break quote was cut as "...so no prompt was".
+ */
+function clip(s, n) {
+    const one = s.replace(/\s+/g, " ").trim();
+    if (one.length <= n)
+        return one;
+    const cut = one.slice(0, n);
+    const lastSpace = cut.lastIndexOf(" ");
+    return `${(lastSpace > n * 0.6 ? cut.slice(0, lastSpace) : cut).replace(/[\s,;:.—-]+$/, "")}…`;
+}
 function needsLlmResult(rule) {
     return { ruleId: rule.id, ruleTitle: rule.title, ruleSource: rule.source, status: "UNCLEAR", needsHuman: true, evidence: "" };
 }
@@ -125,11 +137,11 @@ export function renderHistory(s, projectName, now = Date.now()) {
         out.push(`${who} broke your rules ${s.totalBrokenCount} time${s.totalBrokenCount === 1 ? "" : "s"}.`);
         out.push("");
         for (const b of s.breaks.slice(0, 10)) {
-            const title = b.ruleTitle.replace(/\s+/g, " ").trim().slice(0, 60);
+            const title = clip(b.ruleTitle, 60);
             const when = relDate(b.lastMs, now);
             out.push(`  x  ${title}    ${b.count} time${b.count === 1 ? "" : "s"}   last: ${when}`);
             if (b.quote)
-                out.push(`       ${b.quote.replace(/\s+/g, " ").trim().slice(0, 100)}`);
+                out.push(`       ${clip(b.quote, 100)}`);
         }
     }
     out.push("");

package/dist/parsers/claudeMdParser.d.ts

@@ -8,4 +8,4 @@ import type { Rule } from "../types.js";
  * ("your file never leaves the page") is only true because nothing in
  * this function or in classify.ts touches Node APIs; keep it that way.
  */
-export declare function parseClaudeMdText(raw: string, source: "global" | "project"): Rule[];
+export declare function parseClaudeMdText(rawInput: string, source: "global" | "project"): Rule[];

package/dist/parsers/claudeMdParser.js

@@ -83,6 +83,25 @@ function stripHtmlComments(raw) {
     const stripped = masked.replace(/<!--[\s\S]*?-->/g, (m) => "\n".repeat((m.match(/\n/g) ?? []).length));
     return stripped.replace(/\u0000CODE(\d+)\u0000/g, (_, i) => spans[Number(i)]);
 }
+/**
+ * A whole-line `@import` directive (`@AGENTS.md`, `@docs/rules.md`) is how Claude
+ * Code pulls in another file — it is NOT itself a rule. Blank those lines (keeping
+ * the line, so source lines below stay right) so a CLAUDE.md whose body is just
+ * `@AGENTS.md` does not report the import as a phantom one-line rule. Imports
+ * inside code spans/fences are left untouched (they are examples, not directives).
+ */
+function stripImportDirectiveLines(raw) {
+    const spans = [];
+    const masked = raw.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]*`/g, (m) => {
+        spans.push(m);
+        return `\u0000CODE${spans.length - 1}\u0000`;
+    });
+    const blanked = masked
+        .split("\n")
+        .map((line) => (/^\s*@[^\s]+\s*$/.test(line) ? "" : line))
+        .join("\n");
+    return blanked.replace(/\u0000CODE(\d+)\u0000/g, (_, i) => spans[Number(i)]);
+}
 function normalizeSetextHeaders(lines) {
     const out = [...lines];
     // Fence-aware for the same reason as the main pass: a row of dashes inside
@@ -134,7 +153,10 @@ function normalizeSetextHeaders(lines) {
  * ("your file never leaves the page") is only true because nothing in
  * this function or in classify.ts touches Node APIs; keep it that way.
  */
-export function parseClaudeMdText(raw, source) {
+export function parseClaudeMdText(rawInput, source) {
+    // Whole-line @import directives are file references, not rules — drop them
+    // before anything counts or classifies them.
+    const raw = stripImportDirectiveLines(rawInput);
     const lines = normalizeSetextHeaders(stripHtmlComments(raw).split("\n"));
     const rules = [];
     // `current` accumulates a numbered-header rule, a bold-rule-header rule,

package/dist/parsers/imports.d.ts

@@ -0,0 +1,9 @@
+/** Blank out fenced code blocks and inline code spans so @tokens inside them are ignored. */
+export declare function stripCodeForImports(md: string): string;
+/** The @import paths a file names, resolved to absolute paths (existence not yet checked). */
+export declare function importTargets(filePath: string, content: string): string[];
+/**
+ * Absolute paths of every file transitively @imported by `filePath`, in a stable
+ * order, each confirmed to exist as a real file. `filePath` itself is excluded.
+ */
+export declare function resolveImports(filePath: string): string[];

package/dist/parsers/imports.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Claude Code's @import feature: a rules file can pull in another file with an
+ * `@path` reference, and the agent reads the imported file's rules as if they
+ * were inline. The canonical case is a CLAUDE.md whose entire body is
+ * `@AGENTS.md` (the pattern Anthropic's own docs suggest) — the AGENTS.md IS
+ * loaded, not shadowed. Missing this made the tool state something untrue ("AGENTS.md
+ * present but not loaded") and silently skip every imported rule (found by
+ * independent test on 0.1.74, 2026-09-29).
+ *
+ * Faithful to how Claude Code resolves them, per its docs:
+ *  - relative paths resolve against the importing file's directory; `~` is home;
+ *  - imports inside code spans (`...`) and fenced code blocks (``` ```) do NOT count;
+ *  - a bounded hop depth (5) guards against import cycles.
+ * An @token that resolves to something that is not a real file is ignored, which
+ * is what keeps an email address (`name@host`) or an @mention from being treated
+ * as an import.
+ */
+const MAX_DEPTH = 5;
+/** Blank out fenced code blocks and inline code spans so @tokens inside them are ignored. */
+export function stripCodeForImports(md) {
+    const lines = md.split(/\r?\n/);
+    let inFence = false;
+    const out = [];
+    for (const line of lines) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            out.push("");
+            continue;
+        }
+        if (inFence) {
+            out.push("");
+            continue;
+        }
+        out.push(line.replace(/`[^`]*`/g, " "));
+    }
+    return out.join("\n");
+}
+function realOr(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The @import paths a file names, resolved to absolute paths (existence not yet checked). */
+export function importTargets(filePath, content) {
+    const base = dirname(filePath);
+    const stripped = stripCodeForImports(content);
+    const targets = [];
+    // An import is `@` at line start or after whitespace, then a path with no spaces.
+    const re = /(?:^|\s)@(\S+)/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        let p = m[1].replace(/[).,;:'"]+$/, ""); // trailing prose punctuation is not part of the path
+        if (p.length === 0)
+            continue;
+        if (p === "~" || p.startsWith("~/"))
+            p = resolve(homedir(), p.slice(2));
+        else if (!isAbsolute(p))
+            p = resolve(base, p);
+        targets.push(p);
+    }
+    return targets;
+}
+/**
+ * Absolute paths of every file transitively @imported by `filePath`, in a stable
+ * order, each confirmed to exist as a real file. `filePath` itself is excluded.
+ */
+export function resolveImports(filePath) {
+    const found = [];
+    const seen = new Set([realOr(filePath)]);
+    const walk = (fp, depth) => {
+        if (depth >= MAX_DEPTH)
+            return;
+        let content;
+        try {
+            content = readFileSync(fp, "utf-8");
+        }
+        catch {
+            return;
+        }
+        for (const target of importTargets(fp, content)) {
+            const real = realOr(target);
+            if (seen.has(real))
+                continue;
+            seen.add(real);
+            if (!existsSync(target) || !isFile(target))
+                continue;
+            found.push(target);
+            walk(target, depth + 1);
+        }
+    };
+    walk(filePath, 0);
+    return found;
+}

package/dist/parsers/transcriptParser.d.ts

@@ -5,7 +5,16 @@ 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. */
+/**
+ * Every session file that belongs to this project, newest first.
+ *
+ * A folder matches when the real cwd stored in its sessions is THIS directory
+ * (encoding-independent — handles dots, underscores, spaces, symlinks), or when
+ * this directory is a project root and the session's cwd is inside it (a
+ * monorepo subfolder like packages/api, so the root check sees that work too).
+ * Encoding candidates are only a fallback for folders whose stored cwd can't be
+ * read.
+ */
 export declare function listAllSessionFiles(cwd: string): string[];
 export declare function findLatestSessionFile(cwd: string): string | null;
 export { parseLine } from "./transcriptLine.js";

package/dist/parsers/transcriptParser.js

@@ -1,6 +1,6 @@
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, statSync, realpathSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname, basename } from "node:path";
+import { join, dirname, basename, sep } from "node:path";
 import { parseTranscriptText } from "./transcriptLine.js";
 /**
  * Claude Code stores each session as a JSONL file at:
@@ -32,8 +32,80 @@ import { parseTranscriptText } from "./transcriptLine.js";
  * generalizes to variants never seen on this machine, at the cost of one
  * extra readdir() of the home directory per check — negligible.
  */
-function encodeProjectPath(cwd) {
-    return cwd.replace(/\//g, "-");
+/**
+ * Claude Code names the per-project directory by mangling the cwd, but the exact
+ * rule is not stable or documented across versions: at minimum "/" becomes "-",
+ * and observed builds also turn "." "_" and space (every non-alphanumeric) into
+ * "-". Guessing the encoding is therefore fragile — a project at
+ * /Users/john.doe/my.app, my_project or "My Work" would silently find zero
+ * sessions (found by independent test on 0.1.74, 2026-09-29; the whole first
+ * screen — check, history, list-sessions, card — showed "No sessions found").
+ *
+ * So encoding is only a FAST-PATH hint. The source of truth is the `cwd` field
+ * every Claude session line carries: this reads the real cwd out of each folder
+ * and matches on it (realpath-compared, so symlinks and dotted paths just work),
+ * which also survives any future encoding change Claude Code makes.
+ */
+function encodeCandidates(cwd) {
+    const slashOnly = cwd.replace(/\//g, "-");
+    const allNonAlnum = cwd.replace(/[^A-Za-z0-9]/g, "-");
+    return [...new Set([slashOnly, allNonAlnum])];
+}
+function realpathOr(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** The cwd a session folder belongs to, read from the first line that carries it. */
+function sessionCwdOf(sessionFile) {
+    let text;
+    try {
+        text = readFileSync(sessionFile, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    // The cwd is on every line; scan only until the first hit (usually line 1).
+    let from = 0;
+    for (let i = 0; i < 200; i++) {
+        const nl = text.indexOf("\n", from);
+        const line = text.slice(from, nl === -1 ? undefined : nl);
+        if (line.includes('"cwd"')) {
+            try {
+                const cwd = JSON.parse(line).cwd;
+                if (typeof cwd === "string" && cwd.length > 0)
+                    return cwd;
+            }
+            catch {
+                /* partial/garbled line: keep scanning */
+            }
+        }
+        if (nl === -1)
+            break;
+        from = nl + 1;
+    }
+    return null;
+}
+/** A cwd looks like a real project root, so descendant (monorepo) sessions are safe to pull in. */
+function looksLikeProjectRoot(cwd) {
+    return [".git", "CLAUDE.md", "AGENTS.md", "GEMINI.md", ".claude", ".cursor", ".github/copilot-instructions.md"].some((marker) => existsSync(join(cwd, marker)));
+}
+/** Absolute paths of every Claude-Code-style home to search, including CLAUDE_CONFIG_DIR. */
+function claudeHomeDirs() {
+    const dirs = new Set();
+    for (const name of findClaudeHomeDirNames())
+        dirs.add(join(homedir(), name));
+    const cfg = process.env.CLAUDE_CONFIG_DIR;
+    if (cfg)
+        for (const part of cfg.split(",")) {
+            const p = part.trim();
+            if (p)
+                dirs.add(p);
+        }
+    return [...dirs];
 }
 function listSessionFiles(projectDir) {
     let entries;
@@ -70,12 +142,61 @@ export function findClaudeHomeDirNames() {
         return [];
     }
 }
-/** Every session file for this project, newest first. */
+/**
+ * Every session file that belongs to this project, newest first.
+ *
+ * A folder matches when the real cwd stored in its sessions is THIS directory
+ * (encoding-independent — handles dots, underscores, spaces, symlinks), or when
+ * this directory is a project root and the session's cwd is inside it (a
+ * monorepo subfolder like packages/api, so the root check sees that work too).
+ * Encoding candidates are only a fallback for folders whose stored cwd can't be
+ * read.
+ */
 export function listAllSessionFiles(cwd) {
-    const encoded = encodeProjectPath(cwd);
-    const sessionFiles = findClaudeHomeDirNames().flatMap((dirName) => listSessionFiles(join(homedir(), dirName, "projects", encoded)));
-    sessionFiles.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
-    return sessionFiles;
+    const target = realpathOr(cwd);
+    const candidates = new Set(encodeCandidates(cwd));
+    const allowDescendants = looksLikeProjectRoot(cwd);
+    const files = [];
+    const seen = new Set();
+    for (const home of claudeHomeDirs()) {
+        const projectsDir = join(home, "projects");
+        let folders;
+        try {
+            folders = readdirSync(projectsDir);
+        }
+        catch {
+            continue;
+        }
+        for (const folder of folders) {
+            const dir = join(projectsDir, folder);
+            const folderFiles = listSessionFiles(dir);
+            if (folderFiles.length === 0)
+                continue;
+            const storedCwd = sessionCwdOf(folderFiles[0]);
+            let matches = false;
+            if (storedCwd) {
+                const real = realpathOr(storedCwd);
+                if (real === target)
+                    matches = true;
+                else if (allowDescendants && real.startsWith(target + sep))
+                    matches = true;
+            }
+            else {
+                // No readable cwd (older/garbled file): fall back to the name encoding.
+                matches = candidates.has(folder);
+            }
+            if (!matches)
+                continue;
+            for (const f of folderFiles) {
+                if (!seen.has(f)) {
+                    seen.add(f);
+                    files.push(f);
+                }
+            }
+        }
+    }
+    files.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    return files;
 }
 export function findLatestSessionFile(cwd) {
     const all = listAllSessionFiles(cwd);

package/dist/rules.js

@@ -4,6 +4,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { findClaudeHomeDirNames } from "./parsers/transcriptParser.js";
 import { loadMemoryRules } from "./parsers/readMemory.js";
+import { resolveImports } from "./parsers/imports.js";
 /**
  * Every place Claude Code actually reads a rule from, at one directory
  * level. Order mirrors the documented load order, broadest first.
@@ -135,6 +136,42 @@ function ruleSourcesAtLevel(dir) {
     }
     // Gemini CLI: single rules file (its AGENTS.md equivalent).
     loaded("GEMINI.md", "Gemini");
+    return applyImports(out);
+}
+/**
+ * Claude Code follows @imports: a loaded rules file that says `@AGENTS.md` (or
+ * `@docs/rules.md`) makes that file part of what the agent reads. So an imported
+ * file is NOT shadowed, and its rules ARE checked. This reconciles `out` with
+ * that: any file imported by a loaded file is promoted to loaded (a shadowed
+ * AGENTS.md a CLAUDE.md imports flips to loaded), and any imported file not
+ * already listed is added as a loaded source. Without imports, `out` is
+ * unchanged, so existing projects keep their exact rule order and ids.
+ */
+function applyImports(out) {
+    const imported = new Set();
+    for (const src of out) {
+        if (src.status !== "loaded")
+            continue;
+        for (const target of resolveImports(src.path))
+            imported.add(resolve(target));
+    }
+    if (imported.size === 0)
+        return out;
+    const present = new Set(out.map((s) => resolve(s.path)));
+    for (const src of out) {
+        if (src.status === "shadowed" && imported.has(resolve(src.path))) {
+            src.status = "loaded";
+            src.note = "imported by a loaded CLAUDE.md (@import), so the agent does read it";
+        }
+    }
+    // Imported files that were not otherwise candidates at this level (e.g. a
+    // @docs/rules.md), in a stable order so rule ids stay deterministic.
+    for (const path of [...imported].sort()) {
+        if (present.has(path))
+            continue;
+        present.add(path);
+        out.push({ path, status: "loaded", format: "imported (@import)" });
+    }
     return out;
 }
 /** Every rules file at one directory level that the agent actually loads. */

package/dist/shadowedAgents.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname, parse } from "node:path";
+import { join, dirname, parse, resolve } from "node:path";
+import { resolveImports } from "./parsers/imports.js";
 /** Directory-level pairs where a CLAUDE.md shadows an AGENTS.md. */
 const SHADOW_PAIRS = [
     { claude: "CLAUDE.md", agents: "AGENTS.md" },
@@ -24,7 +25,11 @@ export function shadowedAgentsMd(cwd) {
             const claudePath = join(dir, claude);
             const agentsPath = join(dir, agents);
             if (existsSync(claudePath) && existsSync(agentsPath)) {
-                found.push({ agents: agentsPath, shadowedBy: claudePath });
+                // If the CLAUDE.md @imports the AGENTS.md, the agent DOES read it — it
+                // is not shadowed, and warning that it is would itself be untrue.
+                const importedByClaude = resolveImports(claudePath).some((p) => resolve(p) === resolve(agentsPath));
+                if (!importedByClaude)
+                    found.push({ agents: agentsPath, shadowedBy: claudePath });
             }
         }
         if (existsSync(join(dir, ".git")))

package/dist/why.d.ts

@@ -0,0 +1,34 @@
+import type { Rule } from "./types.js";
+export interface WhyRule {
+    id: string;
+    title: string;
+    source: "global" | "project";
+    location: string;
+    loaded: boolean;
+    loadNote?: string;
+    pathScoped?: string;
+    checkable: boolean;
+    kind: string;
+    suggestion?: string;
+    named?: {
+        kind: "command" | "file";
+        name: string;
+        exists: boolean;
+    };
+    brokenCount: number;
+    brokenDates: string[];
+    sessionsScanned: number;
+}
+export interface WhyResult {
+    query: string;
+    matches: number;
+    rule?: WhyRule;
+    candidates?: {
+        title: string;
+        location: string;
+    }[];
+}
+/** Fuzzy-match a rule by the query appearing in its title/body, or the query being the title. */
+export declare function findRules(rules: Rule[], query: string): Rule[];
+export declare function explainRule(cwd: string, query: string): Promise<WhyResult>;
+export declare function renderWhy(r: WhyResult): string;

package/dist/why.js

@@ -0,0 +1,153 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { homedir } from "node:os";
+import { loadRules, describeRuleSources } from "./rules.js";
+import { classifyRule } from "./checks/classify.js";
+import { adviseRule } from "./checkability.js";
+import { scanHistory } from "./historyReport.js";
+/**
+ * `rulereceipt why "<rule text>"` — everything the tool already knows about ONE
+ * rule, in one place: where it lives, whether the agent even loads it, whether a
+ * command/path it names exists, whether it is mechanically checkable (and if
+ * not, the smallest edit that would make it), and how it has done in the last 30
+ * days. It answers the exact question people ask — "why isn't THIS rule
+ * working?" — and it invents nothing: every line is combined from data the
+ * engine already produces. Read-only; no verdict is created here.
+ */
+const CHECKABLE_KINDS = new Set([
+    "gitBranchPolicy", "fileLifecycle", "codeContent", "approvalGate",
+    "claimEvidence", "deterministic", "attribution", "emojiOutput", "ifEditThenTest",
+]);
+/** Fuzzy-match a rule by the query appearing in its title/body, or the query being the title. */
+export function findRules(rules, query) {
+    // Normalize both sides to lowercase words separated by single spaces, so
+    // punctuation the user won't type (commas, backticks, dashes) doesn't block a
+    // match: "clean elegant maintainable" finds "clean, elegant, maintainable".
+    const clean = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    const q = clean(query);
+    if (q.length === 0)
+        return [];
+    const exact = rules.filter((r) => clean(r.title) === q);
+    if (exact.length > 0)
+        return exact;
+    return rules.filter((r) => {
+        const hay = clean(`${r.title} ${r.text}`);
+        if (hay.includes(q))
+            return true;
+        // Reverse direction (query IS roughly the title) only for a title long
+        // enough to be distinctive — otherwise a 1-char heading like "A" matches
+        // any query that happens to contain that letter.
+        const title = clean(r.title);
+        return title.length >= 6 && q.includes(title);
+    });
+}
+/** A `npm run <script>` or a backtick file path the rule names, and whether it exists. */
+function namedCommandOrPath(rule, cwd) {
+    const text = `${rule.title} ${rule.text}`;
+    const script = text.match(/\b(?:npm|pnpm|yarn)\s+run\s+([\w:-]+)/);
+    if (script) {
+        let exists = false;
+        try {
+            const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8"));
+            exists = Boolean(pkg.scripts && script[1] in pkg.scripts);
+        }
+        catch {
+            /* no package.json: report not found */
+        }
+        return { kind: "command", name: `${script[1]}`, exists };
+    }
+    const path = text.match(/`([^`\s]+\.[a-z0-9]{1,6})`/i);
+    if (path && !path[1].includes("://")) {
+        const p = isAbsolute(path[1]) ? path[1] : join(cwd, path[1]);
+        return { kind: "file", name: path[1], exists: existsSync(p) };
+    }
+    return undefined;
+}
+export async function explainRule(cwd, query) {
+    const rules = loadRules(cwd);
+    const matches = findRules(rules, query);
+    if (matches.length === 0)
+        return { query, matches: 0 };
+    if (matches.length > 1) {
+        return {
+            query,
+            matches: matches.length,
+            candidates: matches.slice(0, 12).map((r) => ({ title: r.title, location: locationOf(r) })),
+        };
+    }
+    const rule = matches[0];
+    const graph = describeRuleSources(cwd);
+    const src = rule.sourcePath ? graph.find((e) => e.path === rule.sourcePath) : undefined;
+    const cls = classifyRule(rule);
+    const checkable = CHECKABLE_KINDS.has(cls.kind);
+    const advice = checkable ? null : adviseRule(rule);
+    let brokenCount = 0;
+    let brokenDates = [];
+    let sessionsScanned = 0;
+    try {
+        const hist = await scanHistory(cwd, rules, 30);
+        sessionsScanned = hist.sessionsScanned;
+        const b = hist.breaks.find((x) => x.ruleId === rule.id && x.ruleTitle === rule.title);
+        if (b) {
+            brokenCount = b.count;
+            brokenDates = [new Date(b.lastMs).toISOString().slice(0, 10)];
+        }
+    }
+    catch {
+        /* history is best-effort; a rule can still be explained without it */
+    }
+    return {
+        query,
+        matches: 1,
+        rule: {
+            id: rule.id,
+            title: rule.title,
+            source: rule.source,
+            location: locationOf(rule),
+            loaded: src ? src.status === "loaded" : true,
+            loadNote: src?.note,
+            pathScoped: rule.paths ? rule.paths.join(", ") : undefined,
+            checkable,
+            kind: cls.kind,
+            suggestion: advice?.suggestion,
+            named: namedCommandOrPath(rule, cwd),
+            brokenCount,
+            brokenDates,
+            sessionsScanned,
+        },
+    };
+}
+function locationOf(rule) {
+    if (!rule.sourcePath)
+        return "unknown";
+    const home = homedir();
+    const p = rule.sourcePath.startsWith(home) ? `~${rule.sourcePath.slice(home.length)}` : rule.sourcePath;
+    return rule.sourceLine ? `${p}:${rule.sourceLine}` : p;
+}
+export function renderWhy(r) {
+    if (r.matches === 0)
+        return `No rule matched "${r.query}". Try a distinctive phrase from the rule, or run \`rulereceipt audit\` to list what loads.`;
+    if (r.candidates) {
+        const lines = r.candidates.map((c) => `  • ${c.title}   (${c.location})`);
+        return `"${r.query}" matched ${r.matches} rules — narrow it down:\n${lines.join("\n")}`;
+    }
+    const w = r.rule;
+    const out = [];
+    out.push(`Rule ${w.id} — ${w.title}`);
+    out.push(`  at ${w.location}  (${w.source})`);
+    out.push("");
+    out.push(w.loaded ? `  ✓ loaded — the agent reads this file` : `  ✗ NOT loaded — ${w.loadNote ?? "the agent never sees this file"}`);
+    if (w.pathScoped)
+        out.push(`  • path-scoped: only loads when the session touches ${w.pathScoped}`);
+    if (w.named)
+        out.push(w.named.exists ? `  ✓ names a ${w.named.kind} that exists: ${w.named.name}` : `  ✗ names a ${w.named.kind} that does NOT exist here: ${w.named.name}`);
+    out.push(w.checkable
+        ? `  ✓ mechanically checkable (${w.kind}) — a session is judged against it with quoted evidence`
+        : `  • needs your judgment${w.suggestion ? ` — ${w.suggestion}` : ` — no command or file to check it by; a human decides`}`);
+    out.push("");
+    if (w.brokenCount > 0)
+        out.push(`  last 30 days: broken ${w.brokenCount}× (last: ${w.brokenDates[0]}) across ${w.sessionsScanned} session${w.sessionsScanned === 1 ? "" : "s"}`);
+    else
+        out.push(`  last 30 days: no proven break across ${w.sessionsScanned} session${w.sessionsScanned === 1 ? "" : "s"}`);
+    return out.join("\n");
+}

package/dist/wrong.js

@@ -27,12 +27,25 @@ export function reportedLabel(r) {
     return "Couldn't tell";
 }
 const SECRET_PATTERNS = [
+    // Private key blocks and passwords inside URLs go FIRST — before the email
+    // rule, which would otherwise partially rewrite a user:pass@host authority.
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "<redacted-private-key>"],
+    [/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s:/@]+:)[^\s:/@]+(@)/g, "$1<redacted>$2"],
     [/\bsk-[A-Za-z0-9_-]{16,}/g, "<redacted-key>"],
     [/\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{16,}/g, "<redacted-token>"],
     [/\bxox[abprs]-[A-Za-z0-9-]{10,}/g, "<redacted-token>"],
+    // Stripe secret/publishable/restricted/webhook keys.
+    [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}/g, "<redacted-stripe-key>"],
+    [/\bwhsec_[A-Za-z0-9]{16,}/g, "<redacted-stripe-secret>"],
     [/\bAKIA[0-9A-Z]{16}\b/g, "<redacted-aws-key>"],
-    [/\b(?:Bearer|token|apikey|api_key|password|passwd|secret)(\s*[:=]\s*|\s+)["']?[^\s"']{6,}/gi, "$1<redacted>"],
-    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "<redacted-private-key>"],
+    // JSON Web Tokens: header.payload.signature, each base64url.
+    [/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, "<redacted-jwt>"],
+    // The value excludes a leading "<" so this never re-clobbers a more specific
+    // placeholder an earlier rule already inserted (e.g. "token <redacted-jwt>").
+    [/\b(?:Bearer|token|apikey|api_key|password|passwd|secret)(\s*[:=]\s*|\s+)["']?(?!<redacted)[^\s"']{6,}/gi, "$1<redacted>"],
+    // .env-style KEY=value: an UPPERCASE_KEY assigned a non-trivial value. A short
+    // value (DISABLE_LOCKS=1) is left alone so ordinary flags are not mangled.
+    [/\b([A-Z][A-Z0-9_]{2,})=(["']?)[^\s"']{8,}\2/g, "$1=<redacted>"],
     [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, "<email>"],
 ];
 /** Masks the things most likely to be private. Not a guarantee — the user is told to read it. */
@@ -91,6 +104,7 @@ export function buildWrongReport(input) {
         "",
         "> Read this before sharing. Obvious secrets, your home path and email addresses were masked,",
         "> but rule text and session lines are quoted as they are. Edit anything private.",
+        "> Masking catches common formats only. Read before sending.",
         "",
         `**Rule handle:** \`${handle}\`  (id ${result.ruleId}, ${result.ruleSource})`,
         "",

package/dist/wrongSubmit.d.ts

@@ -0,0 +1,24 @@
+import { type SpawnSyncReturns } from "node:child_process";
+/**
+ * The two ways to send a wrong-verdict report, kept as pure, testable pieces so
+ * the command wiring in cli.ts stays thin. Nothing here sends on its own: it
+ * builds the exact `gh issue create` argv and the exact mailto: URL, and the
+ * caller only runs them AFTER an explicit yes (see cli.ts). `--yes` never skips
+ * that preview+confirm — the report is public, so the default answer is No.
+ */
+export declare const SUPPORT_EMAIL = "hello@rulereceipt.dev";
+export declare const REPO = "rulereceipt/rulereceipt";
+export declare const ISSUE_LABEL = "wrong-verdict";
+type Runner = (cmd: string, args: string[]) => SpawnSyncReturns<Buffer>;
+/** True only if `gh` is installed AND logged in. No issue is offered otherwise. */
+export declare function ghReady(run?: Runner): boolean;
+export declare function issueTitle(reported: string, ruleTitle: string): string;
+/** argv for `gh issue create`. The label is included only when withLabel. */
+export declare function issueCreateArgs(title: string, body: string, withLabel: boolean): string[];
+export declare const MAILTO_MAX = 1800;
+export declare function mailtoSubject(ruleTitle: string): string;
+export declare function buildMailto(subject: string, body: string): {
+    url: string;
+    trimmed: boolean;
+};
+export {};

package/dist/wrongSubmit.js

@@ -0,0 +1,50 @@
+import { spawnSync } from "node:child_process";
+/**
+ * The two ways to send a wrong-verdict report, kept as pure, testable pieces so
+ * the command wiring in cli.ts stays thin. Nothing here sends on its own: it
+ * builds the exact `gh issue create` argv and the exact mailto: URL, and the
+ * caller only runs them AFTER an explicit yes (see cli.ts). `--yes` never skips
+ * that preview+confirm — the report is public, so the default answer is No.
+ */
+export const SUPPORT_EMAIL = "hello@rulereceipt.dev";
+export const REPO = "rulereceipt/rulereceipt";
+export const ISSUE_LABEL = "wrong-verdict";
+const defaultRun = (cmd, args) => spawnSync(cmd, args, { stdio: "ignore" });
+/** True only if `gh` is installed AND logged in. No issue is offered otherwise. */
+export function ghReady(run = defaultRun) {
+    try {
+        if (run("gh", ["--version"]).status !== 0)
+            return false;
+        return run("gh", ["auth", "status"]).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function issueTitle(reported, ruleTitle) {
+    const t = ruleTitle.replace(/\s+/g, " ").trim().slice(0, 60);
+    return `Wrong verdict: ${reported} on ${t}`;
+}
+/** argv for `gh issue create`. The label is included only when withLabel. */
+export function issueCreateArgs(title, body, withLabel) {
+    const args = ["issue", "create", "--repo", REPO, "--title", title, "--body", body];
+    if (withLabel)
+        args.push("--label", ISSUE_LABEL);
+    return args;
+}
+// A conservative cap so the mailto: fits what mail clients accept; a longer body
+// is trimmed and the user is told to attach the saved .md file instead.
+export const MAILTO_MAX = 1800;
+export function mailtoSubject(ruleTitle) {
+    return `RuleReceipt wrong verdict: ${ruleTitle.replace(/\s+/g, " ").trim().slice(0, 80)}`;
+}
+export function buildMailto(subject, body) {
+    let b = body;
+    let trimmed = false;
+    if (b.length > MAILTO_MAX) {
+        b = b.slice(0, MAILTO_MAX) + "\n\n[Report trimmed to fit email — attach the saved .md file instead.]";
+        trimmed = true;
+    }
+    const url = `mailto:${SUPPORT_EMAIL}?subject=${encodeURIComponent(subject)}&body=${encodeURIComponent(b)}`;
+    return { url, trimmed };
+}

package/package.json

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