rulereceipt 0.1.59 → 0.1.60

package/dist/rules.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
-import { existsSync, readdirSync, statSync } from "node:fs";
+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";
@@ -41,65 +41,105 @@ function markdownFilesIn(dir, exts = [".md"]) {
         return [];
     }
 }
-/** Every rules file at one directory level, in documented load order. */
-function ruleFilesAtLevel(dir) {
-    const found = [];
-    const push = (rel) => {
-        const p = join(dir, rel);
-        if (existsSync(p))
-            found.push(p);
-    };
+/**
+ * Every candidate rules file at one directory level, in documented load order,
+ * each tagged loaded or shadowed. This is the single source of truth for both
+ * what gets checked (`ruleFilesAtLevel`, the loaded subset) and the load graph
+ * (`describeRuleSources`) — so the report can never claim a file was loaded
+ * that the checker skipped, or vice versa.
+ */
+function ruleSourcesAtLevel(dir) {
+    const out = [];
     const has = (rel) => existsSync(join(dir, rel));
+    const loaded = (rel, format) => {
+        if (has(rel))
+            out.push({ path: join(dir, rel), status: "loaded", format });
+    };
+    const shadowed = (rel, format, note) => {
+        if (has(rel))
+            out.push({ path: join(dir, rel), status: "shadowed", format, note });
+    };
     // CLAUDE.md shadows AGENTS.md at the same level: as of 2026-09-19 Claude
     // Code loads AGENTS.md ONLY when that level has no CLAUDE.md, and silently
-    // ignores it otherwise. Reading a shadowed AGENTS.md here would check the
-    // session against rules Claude never loaded — a false accusation. `init`
-    // separately WARNS about the shadowed file (see shadowedAgents.ts) so the
-    // rules are not lost silently. Mirrored for the `.claude/` subdir pair.
-    push(join(".claude", "CLAUDE.md"));
-    if (!has(join(".claude", "CLAUDE.md")))
-        push(join(".claude", "AGENTS.md"));
-    for (const rel of RULE_DIRS)
-        found.push(...markdownFilesIn(join(dir, rel)));
-    push("CLAUDE.md");
-    // AGENTS.md (and the singular AGENT.md some tools use) are read only when
-    // there's no CLAUDE.md at this level, mirroring Claude Code's shadow rule.
-    if (!has("CLAUDE.md")) {
-        push("AGENTS.md");
-        push("AGENT.md");
+    // ignores it otherwise. `init` separately WARNS about the shadowed file (see
+    // shadowedAgents.ts). Mirrored for the `.claude/` subdir pair.
+    if (has(join(".claude", "CLAUDE.md"))) {
+        loaded(join(".claude", "CLAUDE.md"), "Claude (.claude/CLAUDE.md)");
+        shadowed(join(".claude", "AGENTS.md"), "AGENTS (.claude/AGENTS.md)", "a CLAUDE.md at the same level wins");
+    }
+    else {
+        loaded(join(".claude", "AGENTS.md"), "AGENTS (.claude/AGENTS.md)");
+    }
+    for (const rel of RULE_DIRS) {
+        for (const f of markdownFilesIn(join(dir, rel)))
+            out.push({ path: f, status: "loaded", format: ".claude/rules" });
     }
-    // .local variants: their precedence relative to the base files is not
-    // documented, so both are kept rather than guessing at a shadow rule.
-    push("CLAUDE.local.md");
-    push("AGENTS.local.md");
+    if (has("CLAUDE.md")) {
+        loaded("CLAUDE.md", "Claude (CLAUDE.md)");
+        // AGENTS.md (and the singular AGENT.md some tools use) are ignored when
+        // there's a CLAUDE.md at this level, mirroring Claude Code's shadow rule.
+        shadowed("AGENTS.md", "AGENTS.md", "a CLAUDE.md at the same level wins");
+        shadowed("AGENT.md", "AGENT.md", "a CLAUDE.md at the same level wins");
+    }
+    else {
+        loaded("AGENTS.md", "AGENTS.md");
+        loaded("AGENT.md", "AGENT.md");
+    }
+    // .local variants: precedence relative to the base files is not documented,
+    // so both are kept rather than guessing at a shadow rule.
+    loaded("CLAUDE.local.md", "Claude (CLAUDE.local.md)");
+    loaded("AGENTS.local.md", "AGENTS (AGENTS.local.md)");
     // Non-Claude rule-file conventions (added 2026-09-26 for multi-tool
-    // support). Each is a plain text/markdown file needing no special access,
-    // read IN ADDITION to Claude's files when present — a rule the project
-    // wrote is a rule to check, and silently ignoring one is the "clean report
-    // on rules never opened" failure this module already guards against. The
-    // engine (classify.ts) is agent-neutral, so it does not matter which tool a
-    // rule was authored for. Precedence is FIXED and documented so rule ids stay
+    // support), read IN ADDITION to Claude's files when present. The engine
+    // (classify.ts) is agent-neutral. Precedence is FIXED so rule ids stay
     // deterministic: Claude family (above), then Cursor, Copilot, Windsurf.
     //
     // Cursor: the modern `.cursor/rules/*.mdc|.md` directory SHADOWS the legacy
-    // single `.cursorrules` file — Cursor itself deprecated `.cursorrules` in
-    // favour of the directory, so reading both would double-count. Same
-    // shadow shape as CLAUDE.md over AGENTS.md above.
+    // single `.cursorrules` file — Cursor deprecated `.cursorrules` in favour of
+    // the directory, so reading both would double-count.
     const cursorRules = markdownFilesIn(join(dir, ".cursor", "rules"), [".mdc", ".md"]);
-    if (cursorRules.length > 0)
-        found.push(...cursorRules);
-    else
-        push(".cursorrules");
+    if (cursorRules.length > 0) {
+        for (const f of cursorRules)
+            out.push({ path: f, status: "loaded", format: "Cursor (.cursor/rules)" });
+        shadowed(".cursorrules", "Cursor (.cursorrules)", "the .cursor/rules/ directory supersedes the legacy file");
+    }
+    else {
+        loaded(".cursorrules", "Cursor (.cursorrules)");
+    }
     // GitHub Copilot: repo-level custom instructions.
-    push(join(".github", "copilot-instructions.md"));
+    loaded(join(".github", "copilot-instructions.md"), "Copilot");
     // Windsurf (Codeium): single rules file.
-    push(".windsurfrules");
-    // Google's newer agent convention (agy) / "agents rules": .agents/rules/*.md,
-    // each with a `trigger:` frontmatter block (stripped by the reader).
-    found.push(...markdownFilesIn(join(dir, ".agents", "rules"), [".md"]));
+    loaded(".windsurfrules", "Windsurf");
+    // Google's newer agent convention / "agents rules": .agents/rules/*.md, each
+    // with a `trigger:` frontmatter block. The trigger decides whether the agent
+    // auto-loads the file, so it decides whether we may check against it:
+    //   - always_on / glob (or no trigger)  → loaded, checked
+    //   - manual / model_decision           → not auto-loaded → shadowed
+    // README fragments in the directory are notes, not rules, so they are skipped
+    // entirely (not even reported — they were never a candidate rule).
+    for (const file of markdownFilesIn(join(dir, ".agents", "rules"), [".md"])) {
+        if (/(^|[/\\])readme\.md$/i.test(file))
+            continue;
+        let head = "";
+        try {
+            head = readFileSync(file, "utf-8").slice(0, 600);
+        }
+        catch {
+            continue;
+        }
+        if (/^---[\s\S]*?^\s*trigger:\s*(?:manual|model_decision)\b/m.test(head)) {
+            out.push({ path: file, status: "shadowed", format: ".agents/rules", note: "trigger is manual/model_decision — the agent does not auto-load it" });
+            continue;
+        }
+        out.push({ path: file, status: "loaded", format: ".agents/rules" });
+    }
     // Gemini CLI: single rules file (its AGENTS.md equivalent).
-    push("GEMINI.md");
-    return found;
+    loaded("GEMINI.md", "Gemini");
+    return out;
+}
+/** Every rules file at one directory level that the agent actually loads. */
+function ruleFilesAtLevel(dir) {
+    return ruleSourcesAtLevel(dir).filter((s) => s.status === "loaded").map((s) => s.path);
 }
 /**
  * Walks from the working directory up toward the repository root,
@@ -116,8 +156,8 @@ function ruleFilesAtLevel(dir) {
  * or the home directory — is never pulled into an unrelated project.
  * Global rules are handled separately, deliberately, below.
  */
-function findProjectRuleFiles(cwd) {
-    const found = [];
+function projectLevels(cwd) {
+    const levels = [];
     const { root } = parse(cwd);
     const home = homedir();
     let dir = cwd;
@@ -131,7 +171,7 @@ function findProjectRuleFiles(cwd) {
         // it; loadRules dedupes that against the global pass.
         if (dir === home && dir !== cwd)
             break;
-        found.push(...ruleFilesAtLevel(dir));
+        levels.push(dir);
         // stop AT the repo root (inclusive) — its rules do apply
         if (existsSync(join(dir, ".git")))
             break;
@@ -142,7 +182,10 @@ function findProjectRuleFiles(cwd) {
             break;
         dir = parent;
     }
-    return found;
+    return levels;
+}
+function findProjectRuleFiles(cwd) {
+    return projectLevels(cwd).flatMap((dir) => ruleFilesAtLevel(dir));
 }
 /**
  * Global rules come from every .claude*-prefixed home dir found, not just
@@ -189,3 +232,46 @@ export function loadRules(cwd) {
     rules.push(...loadMemoryRules(cwd));
     return rules;
 }
+/**
+ * The load graph: every candidate rules file the discovery walk sees, in the
+ * same order and with the same dedup as `loadRules`, tagged loaded or shadowed
+ * and counted. This is what `audit` prints so "why isn't my rule firing?" has
+ * an honest, file-level answer — built on the SAME `ruleSourcesAtLevel` the
+ * checker's own discovery uses, so the graph can never claim a file was loaded
+ * that the checker skipped.
+ *
+ * Memory rules are deliberately NOT listed here: this graph is about files on
+ * disk a user can point at, and memory is summarised separately by the caller.
+ */
+export function describeRuleSources(cwd) {
+    const entries = [];
+    const seen = new Set();
+    const add = (src, scope) => {
+        const key = resolve(src.path);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        let ruleCount = 0;
+        try {
+            ruleCount = parseClaudeMd(src.path, scope).length;
+        }
+        catch {
+            /* unreadable: reported with count 0 rather than dropped */
+        }
+        entries.push({ path: src.path, scope, status: src.status, format: src.format, note: src.note, ruleCount });
+    };
+    // Globals first, so a file reachable both ways keeps its "global" label —
+    // mirrors loadRules' dedup order exactly.
+    for (const dirName of findClaudeHomeDirNames()) {
+        const base = join(homedir(), dirName);
+        if (existsSync(join(base, "CLAUDE.md")))
+            add({ path: join(base, "CLAUDE.md"), status: "loaded", format: "Claude (global CLAUDE.md)" }, "global");
+        for (const file of markdownFilesIn(join(base, "rules")))
+            add({ path: file, status: "loaded", format: "Claude (global rules)" }, "global");
+    }
+    for (const dir of projectLevels(cwd)) {
+        for (const src of ruleSourcesAtLevel(dir))
+            add(src, "project");
+    }
+    return entries;
+}

package/dist/types.d.ts

@@ -35,6 +35,14 @@ export interface TranscriptToolUseEvent {
      * the test run that a completion claim depended on.
      */
     toolUseId?: string;
+    /**
+     * The Claude Code permission mode in force when this call was made, when the
+     * transcript records one (`permissionMode` on user turns). Added 2026-09-28
+     * for the approval check: in `default`/`acceptEdits`/`plan` a shell command
+     * may have been approved in the permission prompt, which leaves no trace in
+     * the transcript; in `bypassPermissions`/`dontAsk`/`auto` no person was asked.
+     */
+    permissionMode?: string;
 }
 export interface TranscriptToolResultEvent {
     role: "user";

package/dist/wrong.d.ts

@@ -0,0 +1,57 @@
+import type { CheckResult, Rule, TranscriptEvent } from "./types.js";
+/**
+ * `rulereceipt wrong <rule>` — turn "this verdict is wrong" into a report
+ * someone can actually file, without sending anything anywhere.
+ *
+ * Added 2026-09-28. The "A result looks wrong" issue template already asked the
+ * right questions, but nothing in the tool pointed to it, and filling it meant
+ * copying the rule, the verdict and the evidence by hand. A user who sees a
+ * wrong verdict and has to do that mostly uninstalls instead, and the project
+ * loses the one kind of report every accuracy fix has come from.
+ *
+ * Privacy: nothing is sent. The report is written to a local file and shown
+ * first; the issue link is printed for the user to open themselves. Obvious
+ * secrets, the home directory and email addresses are masked before either is
+ * produced, and the user is told to read it before sharing.
+ */
+export declare const ISSUE_BASE = "https://github.com/rulereceipt/rulereceipt/issues/new";
+/** The dropdown options of .github/ISSUE_TEMPLATE/wrong-result.yml, verbatim. */
+export declare function reportedLabel(r: CheckResult): string;
+/** Masks the things most likely to be private. Not a guarantee — the user is told to read it. */
+export declare function redact(text: string, home?: string): string;
+/**
+ * A few events around the one the evidence quotes, so the reader can see what
+ * happened just before and after. Found by the longest quoted fragment of the
+ * evidence; if nothing matches, no excerpt (never a guessed one).
+ */
+export declare function excerptAround(events: TranscriptEvent[], evidence: string, radius?: number): string[];
+export interface WrongReportInput {
+    version: string;
+    rule: Rule;
+    result: CheckResult;
+    events: TranscriptEvent[];
+    withContext?: boolean;
+    home?: string;
+}
+export interface WrongReport {
+    handle: string;
+    markdown: string;
+    issueUrl: string;
+}
+export declare function buildWrongReport(input: WrongReportInput): WrongReport;
+/**
+ * The link for a shared report (HTML). No rule text and no evidence in it: that
+ * report is often sent to someone else, and a link should not leak what the
+ * page deliberately shows only to its reader.
+ */
+export declare function minimalIssueUrl(result: CheckResult, version: string): string;
+/** Finds the result a user means: by 12-char handle, or by id when that id is unique. */
+export declare function findTarget(query: string, rules: Rule[], results: CheckResult[]): {
+    rule: Rule;
+    result: CheckResult;
+} | {
+    ambiguous: Array<{
+        handle: string;
+        title: string;
+    }>;
+} | null;

package/dist/wrong.js

@@ -0,0 +1,156 @@
+import { homedir } from "node:os";
+import { ruleFingerprint } from "./overrides.js";
+/**
+ * `rulereceipt wrong <rule>` — turn "this verdict is wrong" into a report
+ * someone can actually file, without sending anything anywhere.
+ *
+ * Added 2026-09-28. The "A result looks wrong" issue template already asked the
+ * right questions, but nothing in the tool pointed to it, and filling it meant
+ * copying the rule, the verdict and the evidence by hand. A user who sees a
+ * wrong verdict and has to do that mostly uninstalls instead, and the project
+ * loses the one kind of report every accuracy fix has come from.
+ *
+ * Privacy: nothing is sent. The report is written to a local file and shown
+ * first; the issue link is printed for the user to open themselves. Obvious
+ * secrets, the home directory and email addresses are masked before either is
+ * produced, and the user is told to read it before sharing.
+ */
+export const ISSUE_BASE = "https://github.com/rulereceipt/rulereceipt/issues/new";
+/** The dropdown options of .github/ISSUE_TEMPLATE/wrong-result.yml, verbatim. */
+export function reportedLabel(r) {
+    if (r.status === "FAIL")
+        return "Not followed";
+    if (r.status === "PASS")
+        return "Followed";
+    if (r.needsHuman || r.outcome === "not_run")
+        return "Needs your judgment";
+    return "Couldn't tell";
+}
+const SECRET_PATTERNS = [
+    [/\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>"],
+    [/\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>"],
+    [/\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. */
+export function redact(text, home = homedir()) {
+    let out = text;
+    if (home && home.length > 1)
+        out = out.split(home).join("~");
+    for (const [re, rep] of SECRET_PATTERNS)
+        out = out.replace(re, rep);
+    return out;
+}
+function eventLine(e) {
+    if (e.kind === "text")
+        return `${e.role}: ${e.text}`;
+    if (e.kind === "tool_use") {
+        const input = e.input;
+        const main = input?.command ?? input?.file_path ?? input?.notebook_path ?? JSON.stringify(input ?? {});
+        return `assistant ran ${e.toolName}: ${String(main)}`;
+    }
+    return `tool result${e.isError ? " (error)" : ""}: ${e.content}`;
+}
+/**
+ * A few events around the one the evidence quotes, so the reader can see what
+ * happened just before and after. Found by the longest quoted fragment of the
+ * evidence; if nothing matches, no excerpt (never a guessed one).
+ */
+export function excerptAround(events, evidence, radius = 2) {
+    const quoted = [...evidence.matchAll(/"([^"]{6,})"/g)].map((m) => m[1]);
+    const after = evidence.split(/:\s/).slice(1).join(": ");
+    const needles = [...quoted, after].map((s) => s.trim().slice(0, 60)).filter((s) => s.length >= 6).sort((a, b) => b.length - a.length);
+    if (needles.length === 0)
+        return [];
+    // Evidence strings collapse whitespace; the session keeps newlines. Compare both the same way.
+    const flat = (t) => t.replace(/\s+/g, " ");
+    const idx = events.findIndex((e) => needles.some((n) => flat(eventLine(e)).includes(flat(n))));
+    if (idx === -1)
+        return [];
+    return events.slice(Math.max(0, idx - radius), idx + radius + 1).map((e) => eventLine(e).replace(/\s+/g, " ").slice(0, 240));
+}
+const MAX_URL = 7500;
+export function buildWrongReport(input) {
+    const { version, rule, result, events } = input;
+    const r = (s) => redact(s, input.home);
+    const handle = ruleFingerprint(rule);
+    const ruleText = r(rule.text && rule.text !== rule.title ? `${rule.title}\n${rule.text}` : rule.title);
+    const reported = reportedLabel(result);
+    const excerpt = input.withContext === false ? [] : excerptAround(events, result.evidence).map(r);
+    const how = [
+        result.method ? `method: ${result.method}` : "",
+        result.outcome ? `outcome: ${result.outcome}` : "",
+        result.reason ? `reason: ${result.reason}` : "",
+        result.ceiling ? `limits: ${r(result.ceiling)}` : "",
+    ].filter(Boolean);
+    const markdown = [
+        `# Wrong verdict report (rulereceipt ${version})`,
+        "",
+        "> 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.",
+        "",
+        `**Rule handle:** \`${handle}\`  (id ${result.ruleId}, ${result.ruleSource})`,
+        "",
+        "## The rule",
+        "```",
+        ruleText,
+        "```",
+        "",
+        `## What RuleReceipt reported: ${reported}`,
+        "",
+        "```",
+        r(result.evidence),
+        "```",
+        ...(how.length ? ["", ...how.map((h) => `- ${h}`)] : []),
+        ...(excerpt.length ? ["", "## Session lines around it", "```", ...excerpt, "```"] : []),
+        "",
+        "## What you expected instead",
+        "",
+        "_(write it here)_",
+        "",
+    ].join("\n");
+    const params = new URLSearchParams({
+        template: "wrong-result.yml",
+        title: `Wrong verdict: ${reported} on "${r(rule.title).slice(0, 60)}"`,
+        rule: ruleText,
+        reported,
+        evidence: r(result.evidence),
+        version,
+    });
+    let issueUrl = `${ISSUE_BASE}?${params.toString()}`;
+    if (issueUrl.length > MAX_URL) {
+        params.set("rule", ruleText.slice(0, 1500));
+        params.set("evidence", r(result.evidence).slice(0, 1500));
+        issueUrl = `${ISSUE_BASE}?${params.toString()}`;
+    }
+    return { handle, markdown, issueUrl };
+}
+/**
+ * The link for a shared report (HTML). No rule text and no evidence in it: that
+ * report is often sent to someone else, and a link should not leak what the
+ * page deliberately shows only to its reader.
+ */
+export function minimalIssueUrl(result, version) {
+    const params = new URLSearchParams({ template: "wrong-result.yml", reported: reportedLabel(result), version });
+    return `${ISSUE_BASE}?${params.toString()}`;
+}
+/** Finds the result a user means: by 12-char handle, or by id when that id is unique. */
+export function findTarget(query, rules, results) {
+    const pairs = results
+        .map((result) => ({ result, rule: rules.find((ru) => ru.source === result.ruleSource && ru.id === result.ruleId && ru.title === result.ruleTitle) }))
+        .filter((p) => Boolean(p.rule));
+    const q = query.trim();
+    const byHandle = pairs.filter((p) => ruleFingerprint(p.rule) === q || (q.length >= 6 && ruleFingerprint(p.rule).startsWith(q)));
+    if (byHandle.length === 1)
+        return byHandle[0];
+    const byId = pairs.filter((p) => p.result.ruleId === q);
+    if (byId.length === 1)
+        return byId[0];
+    const many = byHandle.length > 1 ? byHandle : byId;
+    if (many.length > 1)
+        return { ambiguous: many.map((p) => ({ handle: ruleFingerprint(p.rule), title: p.rule.title })) };
+    return null;
+}

package/package.json

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