rulereceipt 0.1.47 → 0.1.49

package/README.md

@@ -393,6 +393,28 @@ report to the path you name, and `rules --include/--exclude` records a
 correction in `.rulereceipt/overrides.json`. Plain `rulereceipt check` writes
 nothing and makes no network calls.
 
+**Severity, per rule.** A committed, team-shared `.rulereceipt/config.json`
+sets how hard each rule bites in CI, by its stable handle (from `rulereceipt
+rules --list`):
+
+```json
+{
+  "rules": {
+    "a1b2c3": "off",     // hidden from the report, never gates
+    "d4e5f6": "warn",    // shown, but does not fail the build
+    "97h8i9": "error"    // shown, FAILS the build — the default for a checkable rule
+  }
+}
+```
+
+No config means today's behaviour: every checkable FAIL is an `error`. This is
+the one place severity lives — a team marks the must-not-break rules `error`
+and the nice-to-haves `warn`, so CI gates on what matters instead of going red
+on day one. (Refusing a command *before* it runs is separate, and stays with
+the guard's `rules --forbid` clause-mark — a config that could block on any
+rule would refuse far too much.) The older `{"warn": ["a1b2c3"]}` list still
+works and means the same as `"warn"` above.
+
 **You can verify the package came from this source.** Every release from
 0.1.19 on is built and published by GitHub Actions and signed with
 [npm provenance](https://docs.npmjs.com/generating-provenance-statements),

package/dist/cli.js

@@ -9,6 +9,7 @@ import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { readLatestTranscript, readTranscriptFromFile, findLatestSessionFile } from "./parsers/transcriptParser.js";
 import { loadRules } from "./rules.js";
 import { adviseRules } from "./checkability.js";
+import { shadowedAgentsMd } from "./shadowedAgents.js";
 import { classifyRules } from "./checks/classify.js";
 import { loadOverrides, saveOverride, clearOverride, staleOverrides, ruleFingerprint, OVERRIDES_PATH } from "./overrides.js";
 import { runDeterministicChecks } from "./checks/deterministicChecks.js";
@@ -32,7 +33,7 @@ import { maybeShowWhatsNew } from "./whatsNew.js";
 import { verifyReceipt, parseReceipt } from "./receipt.js";
 import { buildBadge } from "./badge.js";
 import { buildInitGuidance } from "./init.js";
-import { loadProjectConfig, handleMap, blockingFailures, warningFailures, PROJECT_CONFIG_PATH } from "./projectConfig.js";
+import { loadProjectConfig, handleMap, blockingFailures, warningFailures, visibleResults, PROJECT_CONFIG_PATH } from "./projectConfig.js";
 import { maybeCheckUpdates, isUpdateCheckEnabled } from "./updateCheck.js";
 import { generateDigest } from "./digest.js";
 import { enableSchedule, disableSchedule, scheduleStatus } from "./schedule.js";
@@ -263,12 +264,14 @@ async function runCheck(opts) {
     // sends only a random install ID, never rule text or transcript content,
     // regardless of --llm.
     const judgmentResults = llm ? await runJudgmentChecks(judgment, events) : judgment.map(({ rule }) => needsLlmResult(rule));
-    const results = [...deterministicResults, ...judgmentResults];
-    // Severity: rules a team marked as warnings in .rulereceipt/config.json are
-    // still reported but do not fail the build. handleFor maps a result back to
-    // its stable handle so the mark survives edits that renumber rule ids.
+    const rawResults = [...deterministicResults, ...judgmentResults];
+    // Severity ladder from .rulereceipt/config.json (per rule handle): `off`
+    // rules are hidden entirely, `warn` rules are shown but do not fail the
+    // build, everything else is `error` (the default). handleFor maps a result
+    // back to its stable handle so the mark survives edits that renumber ids.
     const projectConfig = loadProjectConfig(cwd);
     const handleFor = handleMap(rules);
+    const results = visibleResults(rawResults, projectConfig, handleFor);
     const blockingFails = blockingFailures(results, projectConfig, handleFor);
     const warnedFails = warningFailures(results, projectConfig, handleFor);
     const meta = { sessionFilePath, ruleCount: results.length };
@@ -808,6 +811,7 @@ program
         hasAgentsMd: existsSync(join(cwd, "AGENTS.md")),
         hookInstalled: hookIsInstalled(cwd),
         hasApiKey: Boolean(process.env.ANTHROPIC_API_KEY),
+        shadowedAgents: shadowedAgentsMd(cwd).map((s) => s.agents),
     }));
 });
 program

package/dist/init.d.ts

@@ -9,6 +9,8 @@ export interface InitState {
     hasAgentsMd: boolean;
     hookInstalled: boolean;
     hasApiKey: boolean;
+    /** AGENTS.md files a CLAUDE.md shadows, so Claude Code never loads them. */
+    shadowedAgents?: string[];
 }
 /** The PreToolUse guard hook, as it goes into .claude/settings.json. */
 export declare const GUARD_HOOK_SNIPPET = "{\n  \"hooks\": {\n    \"PreToolUse\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"rulereceipt guard\" } ] }\n    ]\n  }\n}";

package/dist/init.js

@@ -41,6 +41,16 @@ export function buildInitGuidance(state) {
             "   judgment graded. Without it those report UNCLEAR — deterministic checks run regardless,\n" +
             "   and nothing is ever sent without the --llm flag.");
     }
+    const shadowed = state.shadowedAgents ?? [];
+    if (shadowed.length > 0) {
+        out.push("Warning — rules Claude Code never reads:");
+        for (const path of shadowed) {
+            out.push(`  ${path} sits next to a CLAUDE.md, so Claude Code ignores it.`);
+        }
+        out.push("  Since 2026-09, AGENTS.md is only read when there is NO CLAUDE.md at that");
+        out.push("  level. Move these rules into the CLAUDE.md, or they govern nothing.");
+        out.push("");
+    }
     if (steps.length === 0) {
         out.push("You're set up. Run:  rulereceipt check");
     }

package/dist/parsers/transcriptParser.d.ts

@@ -14,4 +14,26 @@ export declare function parseLine(line: string): TranscriptEvent[];
  * not a failure.
  */
 export declare function readTranscriptFromFile(filePath: string): TranscriptEvent[];
+/**
+ * Subagent transcripts for a session.
+ *
+ * Claude Code writes each subagent (a Task/background agent, up to 20 at once
+ * and 3 deep as of mid-2026) to its own JSONL under a directory named after
+ * the PARENT session id — verified against real files 2026-09-23:
+ *   projects/<enc>/<sessionId>/subagents/agent-*.jsonl
+ * and each subagent line's own `sessionId` equals that parent id. So for a
+ * picked session file `<sessionId>.jsonl`, the subagents sit in a sibling
+ * directory named by its basename.
+ *
+ * These were invisible before: the reader took only the newest top-level
+ * file, so a rule broken by a subagent — the exact shape of the risk as
+ * Claude Code pushes toward fleets of unattended agents — was never checked.
+ *
+ * The events are appended to the main stream. Scan checks (git/file/
+ * attribution/emoji) simply gain more to inspect; claim-vs-evidence pairs on
+ * globally-unique tool ids so it cannot cross-match; the approval gate can at
+ * worst treat a main-session "ask" as covering a subagent action, which is a
+ * false negative — the safe direction for a tool that must not over-accuse.
+ */
+export declare function findSubagentFiles(sessionFile: string): string[];
 export declare function readLatestTranscript(cwd: string): TranscriptEvent[];

package/dist/parsers/transcriptParser.js

@@ -1,6 +1,6 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, dirname, basename } from "node:path";
 /**
  * Claude Code stores each session as a JSONL file at:
  *   ~/.claude/projects/<cwd with every "/" replaced by "-">/<sessionId>.jsonl
@@ -171,9 +171,39 @@ export function readTranscriptFromFile(filePath) {
     }
     return events;
 }
+/**
+ * Subagent transcripts for a session.
+ *
+ * Claude Code writes each subagent (a Task/background agent, up to 20 at once
+ * and 3 deep as of mid-2026) to its own JSONL under a directory named after
+ * the PARENT session id — verified against real files 2026-09-23:
+ *   projects/<enc>/<sessionId>/subagents/agent-*.jsonl
+ * and each subagent line's own `sessionId` equals that parent id. So for a
+ * picked session file `<sessionId>.jsonl`, the subagents sit in a sibling
+ * directory named by its basename.
+ *
+ * These were invisible before: the reader took only the newest top-level
+ * file, so a rule broken by a subagent — the exact shape of the risk as
+ * Claude Code pushes toward fleets of unattended agents — was never checked.
+ *
+ * The events are appended to the main stream. Scan checks (git/file/
+ * attribution/emoji) simply gain more to inspect; claim-vs-evidence pairs on
+ * globally-unique tool ids so it cannot cross-match; the approval gate can at
+ * worst treat a main-session "ask" as covering a subagent action, which is a
+ * false negative — the safe direction for a tool that must not over-accuse.
+ */
+export function findSubagentFiles(sessionFile) {
+    const sessionId = basename(sessionFile).replace(/\.jsonl$/, "");
+    const subagentDir = join(dirname(sessionFile), sessionId, "subagents");
+    return listSessionFiles(subagentDir);
+}
 export function readLatestTranscript(cwd) {
     const filePath = findLatestSessionFile(cwd);
     if (!filePath)
         return [];
-    return readTranscriptFromFile(filePath);
+    const events = readTranscriptFromFile(filePath);
+    for (const sub of findSubagentFiles(filePath)) {
+        events.push(...readTranscriptFromFile(sub));
+    }
+    return events;
 }

package/dist/projectConfig.d.ts

@@ -2,24 +2,49 @@ import type { CheckResult, Rule } from "./types.js";
 /**
  * A committed, team-shared config at .rulereceipt/config.json.
  *
- * Today it holds one thing: rule handles to treat as WARNINGS — a broken
- * "warning" rule is still reported, but it does not fail the build. This is
- * the honest version of "severity": a team marks the must-not-break rules as
- * errors (the default) and the nice-to-have ones as warnings, so CI gates on
- * what actually matters instead of going red on day one.
+ * ONE place for "how hard should this rule bite", a ladder per rule handle:
+ *
+ *   off    hidden from the report, never gates CI
+ *   warn   shown, does not fail the build
+ *   error  shown, FAILS the build (the default for a checkable rule)
+ *
+ * This is the honest version of "severity": a team marks must-not-break rules
+ * as errors (the default) and nice-to-haves as warnings, and silences the
+ * irrelevant ones, so CI gates on what actually matters instead of going red
+ * on day one. It replaces three scattered mechanisms — the old `warn` list,
+ * `rules --exclude` (now `off`), and the plain default — with one field.
+ *
+ * Pre-run BLOCKING is deliberately NOT a mode here: refusing a command before
+ * it runs still goes through the guard's clause-mark (`rules --forbid`),
+ * because a config that could block on any rule would refuse the 62.8% of
+ * commands the measured guard already showed it must not. This file governs
+ * the report and the CI gate; the guard governs refusal.
  *
  * Handles, not rule ids: an id is positional and renumbers when the file is
  * edited above it; a handle is a content hash, so it survives edits. Get one
  * from `rulereceipt rules --list`.
+ *
+ * Backward compatible: the old top-level `warn: [handle, ...]` list still
+ * works and means the same as `rules: { <handle>: "warn" }`.
  */
+export type RuleMode = "off" | "warn" | "error";
 export interface ProjectConfig {
     warn: string[];
+    rules: Record<string, RuleMode>;
 }
 export declare const PROJECT_CONFIG_PATH: string;
 export declare function loadProjectConfig(cwd: string): ProjectConfig;
+/**
+ * The mode for one result. `rules` wins over the legacy `warn` list; anything
+ * unlisted is `error`, so the default is unchanged and no config means today's
+ * behaviour exactly.
+ */
+export declare function modeForResult(result: CheckResult, config: ProjectConfig, handleFor: (r: CheckResult) => string): RuleMode;
+/** Results the report should show — everything except rules set to `off`. */
+export declare function visibleResults(results: CheckResult[], config: ProjectConfig, handleFor: (r: CheckResult) => string): CheckResult[];
 /** A lookup from a result back to its stable rule handle, built from the loaded rules. */
 export declare function handleMap(rules: Rule[]): (r: CheckResult) => string;
-/** FAILs that are NOT configured as warnings — these fail the build. */
+/** FAILs at `error` mode — these fail the build. (`off` never reaches here.) */
 export declare function blockingFailures(results: CheckResult[], config: ProjectConfig, handleFor: (r: CheckResult) => string): CheckResult[];
-/** FAILs that ARE configured as warnings — shown, but they do not fail the build. */
+/** FAILs at `warn` mode — shown, but they do not fail the build. */
 export declare function warningFailures(results: CheckResult[], config: ProjectConfig, handleFor: (r: CheckResult) => string): CheckResult[];

package/dist/projectConfig.js

@@ -1,19 +1,44 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ruleFingerprint } from "./overrides.js";
+const VALID_MODES = ["off", "warn", "error"];
 export const PROJECT_CONFIG_PATH = join(".rulereceipt", "config.json");
 export function loadProjectConfig(cwd) {
     try {
         const parsed = JSON.parse(readFileSync(join(cwd, PROJECT_CONFIG_PATH), "utf-8"));
-        const warn = parsed?.warn;
-        return { warn: Array.isArray(warn) ? warn.filter((x) => typeof x === "string") : [] };
+        const warn = Array.isArray(parsed?.warn) ? parsed.warn.filter((x) => typeof x === "string") : [];
+        const rules = {};
+        if (parsed?.rules && typeof parsed.rules === "object" && !Array.isArray(parsed.rules)) {
+            for (const [handle, mode] of Object.entries(parsed.rules)) {
+                if (typeof mode === "string" && VALID_MODES.includes(mode))
+                    rules[handle] = mode;
+            }
+        }
+        return { warn, rules };
     }
     catch {
         // Missing or malformed config means no severities configured, never an
         // error — same fail-open discipline as the rest of the tool.
-        return { warn: [] };
+        return { warn: [], rules: {} };
     }
 }
+/**
+ * The mode for one result. `rules` wins over the legacy `warn` list; anything
+ * unlisted is `error`, so the default is unchanged and no config means today's
+ * behaviour exactly.
+ */
+export function modeForResult(result, config, handleFor) {
+    const handle = handleFor(result);
+    if (config.rules[handle])
+        return config.rules[handle];
+    if (config.warn.includes(handle))
+        return "warn";
+    return "error";
+}
+/** Results the report should show — everything except rules set to `off`. */
+export function visibleResults(results, config, handleFor) {
+    return results.filter((r) => modeForResult(r, config, handleFor) !== "off");
+}
 /** A lookup from a result back to its stable rule handle, built from the loaded rules. */
 export function handleMap(rules) {
     const m = new Map();
@@ -21,11 +46,11 @@ export function handleMap(rules) {
         m.set(`${rule.source}:${rule.id}`, ruleFingerprint(rule));
     return (r) => m.get(`${r.ruleSource}:${r.ruleId}`) ?? "";
 }
-/** FAILs that are NOT configured as warnings — these fail the build. */
+/** FAILs at `error` mode — these fail the build. (`off` never reaches here.) */
 export function blockingFailures(results, config, handleFor) {
-    return results.filter((r) => r.status === "FAIL" && !config.warn.includes(handleFor(r)));
+    return results.filter((r) => r.status === "FAIL" && modeForResult(r, config, handleFor) === "error");
 }
-/** FAILs that ARE configured as warnings — shown, but they do not fail the build. */
+/** FAILs at `warn` mode — shown, but they do not fail the build. */
 export function warningFailures(results, config, handleFor) {
-    return results.filter((r) => r.status === "FAIL" && config.warn.includes(handleFor(r)));
+    return results.filter((r) => r.status === "FAIL" && modeForResult(r, config, handleFor) === "warn");
 }

package/dist/rules.js

@@ -13,8 +13,6 @@ import { findClaudeHomeDirNames } from "./parsers/transcriptParser.js";
  * the tool never opened is the most misleading result this can produce,
  * worse than no report, because it looks like evidence.
  */
-const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", "AGENTS.local.md"];
-const RULE_SUBDIR_FILES = [join(".claude", "CLAUDE.md"), join(".claude", "AGENTS.md")];
 const RULE_DIRS = [join(".claude", "rules")];
 /**
  * Lists the markdown files in a rules directory, if it exists.
@@ -43,18 +41,30 @@ function markdownFilesIn(dir) {
 /** Every rules file at one directory level, in documented load order. */
 function ruleFilesAtLevel(dir) {
     const found = [];
-    for (const rel of RULE_SUBDIR_FILES) {
+    const push = (rel) => {
         const p = join(dir, rel);
         if (existsSync(p))
             found.push(p);
-    }
+    };
+    const has = (rel) => existsSync(join(dir, rel));
+    // 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)));
-    for (const name of RULE_FILE_NAMES) {
-        const p = join(dir, name);
-        if (existsSync(p))
-            found.push(p);
-    }
+    push("CLAUDE.md");
+    if (!has("CLAUDE.md"))
+        push("AGENTS.md");
+    // .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");
     return found;
 }
 /**

package/dist/shadowedAgents.d.ts

@@ -0,0 +1,34 @@
+/**
+ * An AGENTS.md that Claude Code never loads because a CLAUDE.md sits beside it.
+ *
+ * As of 2026-09-19, Claude Code reads AGENTS.md at a directory level ONLY when
+ * that level has no CLAUDE.md; if both exist, the AGENTS.md is silently
+ * ignored (InfoWorld / Enterprise DNA, 2026-09). So a rule a user carefully
+ * wrote into AGENTS.md next to a CLAUDE.md governs nothing — Claude never saw
+ * it.
+ *
+ * This matters to RuleReceipt in TWO ways:
+ *   1. A warning the user needs: "these rules are dead, move them into
+ *      CLAUDE.md." That is what this surfaces.
+ *   2. A false-accusation risk in the tool itself: loadRules currently reads
+ *      BOTH files, so it could report the session for breaking a shadowed
+ *      AGENTS.md rule Claude never loaded. That deeper loading fix is tracked
+ *      separately; this detector is the first, safe, additive step.
+ *
+ * Detection mirrors Claude Code's own precedence per directory level: a
+ * CLAUDE.md shadows an AGENTS.md at the same level, and the same for the
+ * `.claude/` subdirectory pair.
+ */
+export interface ShadowedAgents {
+    /** The AGENTS.md that is being ignored. */
+    agents: string;
+    /** The CLAUDE.md at the same level that shadows it. */
+    shadowedBy: string;
+}
+/**
+ * Walks from cwd up to the repository root (inclusive), the same span
+ * loadRules reads project rules over, and returns every AGENTS.md shadowed by
+ * a CLAUDE.md. Global (home-dir) files are out of scope: that is a different
+ * precedence and a different fix.
+ */
+export declare function shadowedAgentsMd(cwd: string): ShadowedAgents[];

package/dist/shadowedAgents.js

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, parse } from "node:path";
+/** Directory-level pairs where a CLAUDE.md shadows an AGENTS.md. */
+const SHADOW_PAIRS = [
+    { claude: "CLAUDE.md", agents: "AGENTS.md" },
+    { claude: join(".claude", "CLAUDE.md"), agents: join(".claude", "AGENTS.md") },
+];
+/**
+ * Walks from cwd up to the repository root (inclusive), the same span
+ * loadRules reads project rules over, and returns every AGENTS.md shadowed by
+ * a CLAUDE.md. Global (home-dir) files are out of scope: that is a different
+ * precedence and a different fix.
+ */
+export function shadowedAgentsMd(cwd) {
+    const found = [];
+    const { root } = parse(cwd);
+    const home = homedir();
+    let dir = cwd;
+    for (;;) {
+        if (dir === home && dir !== cwd)
+            break;
+        for (const { claude, agents } of SHADOW_PAIRS) {
+            const claudePath = join(dir, claude);
+            const agentsPath = join(dir, agents);
+            if (existsSync(claudePath) && existsSync(agentsPath)) {
+                found.push({ agents: agentsPath, shadowedBy: claudePath });
+            }
+        }
+        if (existsSync(join(dir, ".git")))
+            break;
+        if (dir === root)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return found;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",