rulereceipt 0.1.74 → 0.1.76

package/README.md

@@ -6,15 +6,21 @@
 [![npm](https://img.shields.io/npm/v/rulereceipt)](https://www.npmjs.com/package/rulereceipt)
 [![provenance](https://img.shields.io/badge/npm-provenance%20signed-blue)](https://www.npmjs.com/package/rulereceipt#provenance)
 
-Checks whether your AI coding agent actually followed your rules — with
-evidence, not just a vibe. Works with Claude Code today (OpenAI Codex CLI
-support is built and in testing), and reads rules from CLAUDE.md, AGENTS.md,
-Cursor (`.cursor/rules`), GitHub Copilot, Windsurf, Gemini (`GEMINI.md`),
-Google's `.agents/rules`, and Claude Code memory.
+**Check if your AI coding agent followed the rules in your CLAUDE.md, with the exact line as proof.**
+
+[![RuleReceipt checking an agent session against your rules — three rules broken, each with the quoted line](https://raw.githubusercontent.com/rulereceipt/rulereceipt/main/docs/screenshot.png)](https://rulereceipt.dev)
+
+```bash
+npx rulereceipt
+```
 
 Runs entirely on your machine. Plain `rulereceipt check` makes zero network
-calls — [Trust, privacy and licensing](#trust-privacy-and-licensing) has the
-full detail, including the three off-by-default opt-ins.
+calls — [Trust, privacy and licensing](#trust-privacy-and-licensing) has the full
+detail, including the three off-by-default opt-ins. Works with Claude Code today
+(OpenAI Codex CLI in testing); reads rules from CLAUDE.md, AGENTS.md, Cursor
+(`.cursor/rules`), GitHub Copilot, Windsurf, Gemini (`GEMINI.md`), Google's
+`.agents/rules`, and Claude Code memory. [Accuracy](https://rulereceipt.dev/accuracy)
+· [Known gaps](KNOWN-GAPS.md) · Source-available, not OSI — see [LICENSE](LICENSE).
 
 ## See it in 10 seconds
 
@@ -332,12 +338,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 +517,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/blockHint.d.ts

@@ -0,0 +1,49 @@
+import type { Classification } from "./checks/classify.js";
+/**
+ * `why` answers "why isn't THIS rule working?". For a rule that names a
+ * concrete action, the honest follow-up is "then how do I actually stop it?".
+ * This computes that answer — and it is deliberately pinned to what the tool
+ * really does, because an overstated "add this and you're safe" is exactly the
+ * failure RuleReceipt exists to catch.
+ *
+ * Two facts, kept separate because they are not the same promise:
+ *
+ *  - `guardCovers`: RuleReceipt's own PreToolUse guard refuses this exact rule
+ *    before the action runs. True only for the kinds guardDecision/structuredBlocks
+ *    actually handle (a branch, a file, forbidden file content, an AI-authorship
+ *    trailer) and for an approval gate (which it answers "ask", or "deny" in a
+ *    no-prompt mode). It is NOT a general command blocker — that was measured and
+ *    cut (see guard.ts), so nothing here claims it.
+ *
+ *  - `native`: a Claude Code `permissions` entry the user can add by hand with no
+ *    extra tool. Only emitted where a permission rule can genuinely express the
+ *    thing, and always with the honest caveat: a permission rule matches the
+ *    command text or the file path, so it cannot scope to a branch, cannot read a
+ *    commit message, and cannot see file content. Where it can't express the rule,
+ *    `nativeImpossibleReason` says so instead of inventing a rule that wouldn't fire.
+ *
+ * `preventable: false` is the honest answer for the rest: a claim-evidence rule,
+ * an emoji rule, an edit-implies-test rule, a plain literal rule — these are judged
+ * AFTER the run, not blockable before an action. The caller points at `check` and
+ * the Stop hook instead.
+ */
+export interface BlockHint {
+    /** Can an action be refused BEFORE it runs (guard or a native deny/ask)? */
+    preventable: boolean;
+    /** Does RuleReceipt's own guard (`rulereceipt protect`) check this exact rule pre-flight? */
+    guardCovers: boolean;
+    /** A native Claude Code permissions entry, where one can genuinely express the rule. */
+    native?: {
+        kind: "deny" | "ask";
+        entries: string[];
+        note: string;
+    };
+    /** When preventable but a native permission rule cannot express it, why. */
+    nativeImpossibleReason?: string;
+}
+/**
+ * The block advice for one classified rule, or undefined when there is nothing
+ * useful to say (a judgment rule or a non-rule — the "needs your judgment" line
+ * already covers those).
+ */
+export declare function blockHintFor(cls: Classification): BlockHint | undefined;

package/dist/blockHint.js

@@ -0,0 +1,87 @@
+/** Map an approval-gate action to the Claude Code permission pattern that matches it. */
+function askEntryFor(action) {
+    switch (action) {
+        case "push": return "Bash(git push:*)";
+        case "commit": return "Bash(git commit:*)";
+        case "pr": return "Bash(gh pr:*)";
+        case "delete": return "Bash(rm:*)";
+        default: return undefined;
+    }
+}
+/**
+ * The block advice for one classified rule, or undefined when there is nothing
+ * useful to say (a judgment rule or a non-rule — the "needs your judgment" line
+ * already covers those).
+ */
+export function blockHintFor(cls) {
+    switch (cls.kind) {
+        case "gitBranchPolicy": {
+            if (cls.polarity !== "forbid")
+                return { preventable: false, guardCovers: false };
+            return {
+                preventable: true,
+                guardCovers: true,
+                native: {
+                    kind: "deny",
+                    entries: ["Bash(git push:*)"],
+                    note: `a permission rule matches the command text, so this denies EVERY push — it can't ` +
+                        `scope to the \`${cls.branchName}\` branch. The guard below checks the actual target branch.`,
+                },
+            };
+        }
+        case "fileLifecycle": {
+            if (cls.polarity !== "forbid")
+                return { preventable: false, guardCovers: false };
+            return {
+                preventable: true,
+                guardCovers: true,
+                native: {
+                    kind: "deny",
+                    entries: [`Edit(${cls.filePath})`, `Write(${cls.filePath})`],
+                    note: `covers Edit/Write of that path; a Bash \`rm\`/\`mv\` targeting it is NOT matched by ` +
+                        `these — the guard below covers those too.`,
+                },
+            };
+        }
+        case "approvalGate": {
+            const entries = cls.actions.map(askEntryFor).filter((e) => e !== undefined);
+            if (entries.length === 0)
+                return { preventable: true, guardCovers: true, nativeImpossibleReason: "the action it gates isn't one a permission rule can match" };
+            return {
+                preventable: true,
+                guardCovers: true,
+                native: {
+                    kind: "ask",
+                    entries,
+                    note: `an "ask" is skipped in no-prompt modes (bypassPermissions / auto), so the action would ` +
+                        `run there without a prompt. The guard below denies it in those modes instead.`,
+                },
+            };
+        }
+        case "attribution":
+            return {
+                preventable: true,
+                guardCovers: true,
+                nativeImpossibleReason: "a permission rule can't read a commit message, so it can't catch an AI-authorship trailer",
+            };
+        case "codeContent": {
+            if (cls.polarity !== "forbid")
+                return { preventable: false, guardCovers: false };
+            return {
+                preventable: true,
+                guardCovers: true,
+                nativeImpossibleReason: "a permission rule matches the command or path, not the content written into a file",
+            };
+        }
+        case "claimEvidence":
+        case "ifEditThenTest":
+        case "emojiOutput":
+        case "deterministic":
+            // Checkable, but only after the run — there is no single action to refuse
+            // beforehand. The caller points at `check` and the Stop hook.
+            return { preventable: false, guardCovers: false };
+        default:
+            // judgment, notARule — nothing mechanical to block or check.
+            return undefined;
+    }
+}

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, explainAll, renderAllWhy, whyList, renderWhyList } from "./why.js";
 import { observeSessions, renderNoRules, draftRulesFromHistory } from "./sessionObserve.js";
 import { listSessionRows, renderSessionList } from "./listSessions.js";
 import { runSelfTestChecks, renderSelfTest } from "./selftest.js";
@@ -928,7 +931,7 @@ const PERIOD_MS = {
 };
 program
     .command("report")
-    .description("Compliance report across your recent sessions (not just the latest): which policy rules were broken, where, with evidence. Deterministic, local, no network. The org-wide version runs via the Claude Compliance API for Enterprise orgs.")
+    .description("Compliance report across your recent sessions (not just the latest): which policy rules were broken, where, with evidence. Deterministic, local, no network. An org-wide version (multi-repo, trends, a manager digest) is coming in the team version.")
     .option("--last <n>", "how many recent sessions to audit", "25")
     .option("--markdown", "output as markdown, for a report you can send")
     .action(async (opts) => {
@@ -949,12 +952,49 @@ 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. With no argument, lists every rule with its id so you can pick one; with --all, shows every rule (problems first). Read-only — no verdict is created, nothing is sent.")
+    .option("--all", "show every rule, problems first (not loaded, missing command, broken recently), then the rest")
+    .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;
+    }
+    // --all: every rule, problems first.
+    if (opts.all) {
+        const all = await explainAll(cwd);
+        console.log(opts.json ? JSON.stringify(all, null, 2) : renderAllWhy(all));
+        return;
+    }
+    // No argument: list the rules with ids so the reader can pick one.
+    if (query.length === 0) {
+        const list = whyList(cwd);
+        console.log(opts.json ? JSON.stringify(list, null, 2) : renderWhyList(list));
+        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.")
+    .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. Then --submit opens a public GitHub issue (asks first; needs gh) or --email sends it privately to the maintainer; with no flag it just prints the report and a pre-filled link. Nothing is sent without your say-so.")
     .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 +1014,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 +1037,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/historyReport.js

@@ -150,6 +150,8 @@ export function renderHistory(s, projectName, now = Date.now()) {
     out.push(`checked ${s.sessionsScanned} session${s.sessionsScanned === 1 ? "" : "s"} in ${secs}s`);
     out.push("");
     out.push("See one session in full:  rulereceipt check");
+    out.push("Make Claude ask first:     rulereceipt protect");
+    out.push("Share the result:          rulereceipt card");
     out.push("Think a verdict is wrong?  rulereceipt wrong <rule>");
     return out.join("\n");
 }

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";