rulereceipt 0.1.46 → 0.1.48

package/dist/checkability.d.ts

@@ -0,0 +1,31 @@
+import type { Rule } from "./types.js";
+/**
+ * Why a rule can't be checked mechanically, and what to change so it can.
+ *
+ * The other half of hookCoverage. `hookCoverage` answers "which rules have a
+ * hook behind them"; this answers "which rules can't be checked at all, and
+ * how to fix that." Both come from the same complaint — a CLAUDE.md full of
+ * rules that read fine to a human and mean nothing to a checker
+ * (anthropics/claude-code#2544, and the whole "wish list, not a contract"
+ * genre).
+ *
+ * It never rewrites the rule. It says, in one line, what is missing and the
+ * smallest edit that would make the rule land in a real check — usually
+ * naming the concrete command, file or branch the rule is about, in
+ * backticks. Some rules are genuine judgment calls ("surface bad news
+ * first") and the honest advice is that no edit makes them mechanical; those
+ * are for the LLM judge, and this says so rather than pretending otherwise.
+ */
+export interface RuleAdvice {
+    ruleTitle: string;
+    /** The classifier's verdict: "judgment" or "notARule". */
+    kind: "judgment" | "notARule";
+    /** One line: what is missing and the smallest edit that fixes it. */
+    suggestion: string;
+}
+/**
+ * Advice for one rule, or null when the rule is already mechanically checked.
+ */
+export declare function adviseRule(rule: Rule): RuleAdvice | null;
+/** Advice for every rule that isn't already mechanically checked. */
+export declare function adviseRules(rules: Rule[]): RuleAdvice[];

package/dist/checkability.js

@@ -0,0 +1,68 @@
+import { classifyRule } from "./checks/classify.js";
+/** A concrete action the rule is plausibly about, so we can name what to quote. */
+const CONCRETE_SUBJECT = /\b(?:push(?:es|ed|ing)?|commit(?:s|ted|ting)?|merge[ds]?|rebase|delet\w*|remov\w*|\brm\b|drop|truncate|deploy\w*|migrat\w*|branch|tag|force[- ]?push|test|lint|build|install|env|secret|token|password|key|\.env|database|table|file|path|directory|endpoint|api)\b/i;
+/** A rule that is qualitative by nature — no literal makes it mechanical. */
+const QUALITATIVE = /\b(?:concise|verbose|clear|clean|readable|tone|polite|honest|thorough|surface\s+bad\s+news|be\s+kind|professional|idiomatic|maintainable|simple|elegant|good\s+judg\w*|reasonable|appropriate|well[- ]?(?:written|structured|named))\b/i;
+function hasBacktickLiteral(rule) {
+    return /`[^`]{2,}`/.test(`${rule.title} ${rule.text}`);
+}
+/** A believable backtick example for the kind of subject the rule named. */
+function exampleFor(subject) {
+    if (/push|commit|merge|rebase|branch|tag|force/.test(subject))
+        return "`git push`, `main`";
+    if (/deploy|migrat/.test(subject))
+        return "`vercel --prod`, `npm run deploy`";
+    if (/test|lint|build|install/.test(subject))
+        return "`npm test`, `npm run build`";
+    if (/\.env|secret|token|password|key/.test(subject))
+        return "`.env`, `.env.production`";
+    if (/database|table/.test(subject))
+        return "`data/app.db`, `DROP TABLE`";
+    if (/file|path|directory|endpoint|api/.test(subject))
+        return "`data/x.db`, `src/config.ts`";
+    if (/rm|delet|remov|drop|truncate/.test(subject))
+        return "`rm`, `data/x.db`";
+    return "`git push`, `data/x.db`";
+}
+/**
+ * Advice for one rule, or null when the rule is already mechanically checked.
+ */
+export function adviseRule(rule) {
+    const kind = classifyRule(rule).kind;
+    if (kind !== "judgment" && kind !== "notARule")
+        return null;
+    const text = `${rule.title} ${rule.text}`;
+    if (kind === "notARule") {
+        return {
+            ruleTitle: rule.title,
+            kind,
+            suggestion: "reads as documentation or an incident note, not a rule to check. If it IS a rule, phrase it as a direct imperative (\"Never …\", \"Always …\") so a check can bind to it.",
+        };
+    }
+    // kind === "judgment"
+    if (QUALITATIVE.test(text) && !CONCRETE_SUBJECT.test(text)) {
+        return {
+            ruleTitle: rule.title,
+            kind,
+            suggestion: "a genuine judgment call — no edit makes it mechanical. It can only be graded with the LLM judge (`check --llm`); that is expected, not a defect.",
+        };
+    }
+    if (CONCRETE_SUBJECT.test(text) && !hasBacktickLiteral(rule)) {
+        const m = text.match(CONCRETE_SUBJECT);
+        const subject = m ? m[0].toLowerCase() : "the action";
+        return {
+            ruleTitle: rule.title,
+            kind,
+            suggestion: `mentions ${subject} but names no exact term to match. Put the concrete command, file or branch in backticks (e.g. ${exampleFor(subject)}) and it becomes a mechanical check.`,
+        };
+    }
+    return {
+        ruleTitle: rule.title,
+        kind,
+        suggestion: "has no concrete term a check can bind to. Name the exact command, file, branch or flag it is about in backticks, or leave it for the LLM judge (`check --llm`).",
+    };
+}
+/** Advice for every rule that isn't already mechanically checked. */
+export function adviseRules(rules) {
+    return rules.map(adviseRule).filter((a) => a !== null);
+}

package/dist/checks/approvalGate.d.ts

@@ -0,0 +1,3 @@
+import type { ApprovalGateClassification } from "./classify.js";
+import type { CheckResult, TranscriptEvent } from "../types.js";
+export declare function runApprovalGateChecks(classifications: ApprovalGateClassification[], events: TranscriptEvent[]): CheckResult[];

package/dist/checks/approvalGate.js

@@ -0,0 +1,105 @@
+import { violation } from "../types.js";
+import { withoutHeredocs } from "./shellCommand.js";
+/**
+ * Did the assistant ASK before doing a thing a rule says needs approval?
+ *
+ * From anthropics/claude-code#95494 ("committed without permission", scope
+ * rewritten and fake results presented) and #92505. A whole cluster of rules
+ * reads "ask/repeat-back/wait for approval BEFORE you delete | push | commit".
+ *
+ * The honest, mechanical half is narrow and stated as such: the rule is
+ * satisfied by ASKING, so this checks whether the assistant sought approval
+ * in its recorded text before the action. It does NOT judge whether a reply
+ * actually granted approval — the "it read my frustration as a yes" case
+ * (#92505) is a judgment call and stays with the model, not this check.
+ *
+ * Bias is deliberately toward NOT accusing: any approval-seeking assistant
+ * turn before the action clears the rule. A FAIL means the action ran and
+ * nothing before it asked — the clean case, e.g. a bare `git commit` with no
+ * "shall I / ok to / before I" anywhere ahead of it.
+ */
+/** Command shapes for each gated action. Kept conservative to avoid accusing. */
+// `git\s+…\s+push/commit` allows config flags between the two (`git -c x=y
+// push`), which a literal `git push` missed — found by an evasion probe
+// 2026-09-22. Up to four intervening tokens; the verb must not be followed by
+// a word char so `commit-graph` / `push-option` are not matched.
+const ACTION_IN_COMMAND = {
+    push: /\bgit\s+(?:\S+\s+){0,4}?push(?![\w-])/,
+    commit: /\bgit\s+(?:\S+\s+){0,4}?commit(?![\w-])/,
+    delete: /\brm\s+-?\w|\bgit\b[^\n]*\s-D\b|\bdrop\s+table\b|\bdelete\s+from\b|\btruncate\b/i,
+};
+/**
+ * The assistant seeking sign-off. Read generously on purpose: a broad match
+ * here means fewer false accusations, at the cost of occasionally missing a
+ * real one — the safe direction for a tool whose whole point is not crying
+ * wolf.
+ */
+const APPROVAL_SEEK = /\b(?:shall i|should i|may i|can i|do you want|would you like|let me know|before i (?:proceed|do|run|delete|push|commit|go|continue)|your (?:approval|go[- ]?ahead|sign[- ]?off|confirmation)|please confirm|is (?:it|this) ok|ok(?:ay)? to|go ahead\?)\b/i;
+function commandOf(event) {
+    if (event.kind !== "tool_use" || event.toolName !== "Bash")
+        return "";
+    const input = event.input;
+    const raw = input && typeof input.command === "string" ? input.command : "";
+    // A heredoc that WRITES "git push" into a file is not a push. Strip
+    // heredoc bodies so only the commands actually invoked are inspected.
+    return withoutHeredocs(raw);
+}
+/**
+ * The first event index at which one of the gated actions runs, and the
+ * command that ran it — or null if none did.
+ */
+function firstAction(events, actions) {
+    const regexes = actions.map((a) => ACTION_IN_COMMAND[a]).filter(Boolean);
+    for (let i = 0; i < events.length; i++) {
+        const command = commandOf(events[i]);
+        if (!command)
+            continue;
+        if (regexes.some((re) => re.test(command)))
+            return { index: i, command };
+    }
+    return null;
+}
+/** Did any assistant text before `index` seek approval? */
+function askedBefore(events, index) {
+    for (let i = 0; i < index; i++) {
+        const e = events[i];
+        if (e.kind !== "text" || e.role !== "assistant")
+            continue;
+        if (APPROVAL_SEEK.test(e.text))
+            return true;
+    }
+    return false;
+}
+export function runApprovalGateChecks(classifications, events) {
+    return classifications.map(({ rule, actions, polarity }) => {
+        const action = firstAction(events, actions);
+        if (!action) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "UNCLEAR",
+                outcome: "not_applicable",
+                method: "approval_gate",
+                evidence: `no ${actions.join("/")} action ran this session, so the gate never applied`,
+            };
+        }
+        if (askedBefore(events, action.index)) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                outcome: "pass",
+                method: "approval_gate",
+                evidence: "the assistant sought approval before the action",
+                ceiling: "confirms the assistant ASKED; it does not judge whether the reply granted approval, and cannot see an approval given through the permission UI",
+            };
+        }
+        const excerpt = action.command.replace(/\s+/g, " ").trim().slice(0, 70);
+        return violation(rule, polarity, `the assistant ran "${excerpt}" with no approval sought beforehand`, {
+            method: "approval_gate",
+            ceiling: "flags an action taken with no approval-seeking text before it; it cannot see an approval given through the permission UI, so this is the clean no-ask case only",
+        });
+    });
+}

package/dist/checks/attribution.d.ts

@@ -0,0 +1,3 @@
+import type { AttributionClassification } from "./classify.js";
+import type { CheckResult, TranscriptEvent } from "../types.js";
+export declare function runAttributionChecks(classifications: AttributionClassification[], events: TranscriptEvent[]): CheckResult[];

package/dist/checks/attribution.js

@@ -0,0 +1,105 @@
+import { violation } from "../types.js";
+import { withoutHeredocs } from "./shellCommand.js";
+/**
+ * Did the session add an AI-attribution trailer to a commit, PR or comment,
+ * against a rule forbidding it?
+ *
+ * Raised by anthropics/claude-code#83813, #92169, #82690 and #4287: a user
+ * writes "no Co-Authored-By, no 'Generated with Claude Code'" into their
+ * rules file, and the trailer lands on the commit anyway. It is one of the
+ * most-filed rule-following complaints, and it is mechanically checkable —
+ * the trailer is literal text that sits in the git command the assistant
+ * ran.
+ *
+ * Scope is deliberately narrow, for the same reason emojiOutput reads only
+ * assistant text: a rule that FORBIDS attribution necessarily quotes the
+ * exact trailer it forbids ("never add `Co-Authored-By: Claude`"), and this
+ * repo's own CLAUDE.md does exactly that. Scanning rule text, user text, or
+ * a plain `cat` of a file would fire on the prohibition itself. So this
+ * looks at one thing only: the text of a git-writing command the ASSISTANT
+ * issued — `git commit`, `gh pr create`, a PR or issue comment — and asks
+ * whether the forbidden trailer is inside it.
+ *
+ * The ceiling that travels with the verdict is the honest limit: a trailer
+ * the harness appends OUTSIDE the recorded command text (the #83813
+ * mechanism, where the platform adds it) is not visible in the transcript,
+ * so a PASS means "not in any command recorded here", never "no attribution
+ * reached the commit".
+ */
+/** Commands that write to git history or to GitHub on the author's behalf. */
+// `git\s+…\s+commit` allows config flags between the two — `git -c
+// user.name=x commit`, `git --no-pager commit` — which a literal `git commit`
+// missed (found by an evasion probe, 2026-09-22). Up to four intervening
+// tokens, and `commit` not followed by a word char so `commit-graph` is not
+// a commit. Same shape for the push detector in approvalGate.
+const GIT_WRITE = /\bgit\s+(?:\S+\s+){0,4}?commit(?![\w-])|\bgit\s+.*--amend\b|\bgh\s+pr\s+(?:create|edit|review|comment)\b|\bgh\s+issue\s+(?:create|comment)\b|\bgh\s+api\b[^\n]*\bcomments?\b/i;
+/**
+ * The forbidden trailers, as literal spellings. Each is an AI-authorship
+ * mark, not merely the word "Claude" (a commit may legitimately say "fix the
+ * Claude Code parser"): the co-author trailer, the generated-with line with
+ * or without its robot, and the anthropic noreply address used as an author.
+ */
+const ATTRIBUTION_TRAILER = /co-?authored-by:\s*[^\n]*(?:claude|anthropic)|generated with\s*\[?\s*claude code|🤖\s*generated with|<?noreply@anthropic\.com>?/i;
+function commandText(event) {
+    const input = event.input;
+    return input && typeof input.command === "string" ? input.command : "";
+}
+/** The first git-writing command in the session that carries a trailer. */
+function firstOffendingCommand(events) {
+    let sawGitWrite = false;
+    for (const event of events) {
+        if (event.kind !== "tool_use" || event.toolName !== "Bash")
+            continue;
+        const command = commandText(event);
+        // Prove git is actually INVOKED, not merely quoted: a `cat <<EOF … git
+        // commit … Co-Authored-By … EOF` writes a file that contains the example,
+        // it does not commit. Strip heredoc bodies before testing the invocation,
+        // but match the trailer against the FULL command so a real heredoc that
+        // FEEDS the commit message is still caught.
+        if (!GIT_WRITE.test(withoutHeredocs(command)))
+            continue;
+        sawGitWrite = true;
+        if (ATTRIBUTION_TRAILER.test(command))
+            return command;
+    }
+    return sawGitWrite ? "" : null;
+}
+export function runAttributionChecks(classifications, events) {
+    const offending = firstOffendingCommand(events);
+    return classifications.map(({ rule, polarity }) => {
+        if (typeof offending === "string" && offending.length > 0) {
+            const m = offending.match(ATTRIBUTION_TRAILER);
+            const at = m?.index ?? 0;
+            const excerpt = offending
+                .slice(Math.max(0, at - 30), at + 50)
+                .replace(/\s+/g, " ")
+                .trim();
+            return violation(rule, polarity, `a git/PR command carried an AI-attribution trailer — "…${excerpt}…"`, {
+                method: "attribution_scan",
+                ceiling: "reads the text of git/PR commands recorded in the transcript; a trailer the harness appends outside the recorded command is not visible here",
+            });
+        }
+        if (offending === null) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                outcome: "not_applicable",
+                method: "attribution_scan",
+                evidence: "no commit, PR or comment was created this session, so there was nothing to attribute",
+                ceiling: "a scan of the git/PR commands recorded in this transcript",
+            };
+        }
+        return {
+            ruleId: rule.id,
+            ruleTitle: rule.title,
+            ruleSource: rule.source,
+            status: "PASS",
+            outcome: "pass",
+            method: "attribution_scan",
+            evidence: "the git/PR commands this session ran carried no AI-attribution trailer",
+            ceiling: "reads the text of git/PR commands recorded in the transcript; a trailer the harness appends outside the recorded command is not visible here",
+        };
+    });
+}

package/dist/checks/classify.d.ts

@@ -22,6 +22,18 @@ export interface EmojiClassification {
     rule: Rule;
     polarity: "forbid";
 }
+export interface AttributionClassification {
+    kind: "attribution";
+    rule: Rule;
+    polarity: "forbid";
+}
+export interface ApprovalGateClassification {
+    kind: "approvalGate";
+    rule: Rule;
+    /** The gated actions this rule names, e.g. ["push", "delete"]. */
+    actions: string[];
+    polarity: "forbid";
+}
 export interface JudgmentClassification {
     kind: "judgment";
     rule: Rule;
@@ -111,7 +123,7 @@ export interface ClaimEvidenceClassification {
     kind: "claimEvidence";
     rule: Rule;
 }
-export type Classification = ClaimEvidenceClassification | DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | EmojiClassification | JudgmentClassification;
+export type Classification = ClaimEvidenceClassification | DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | EmojiClassification | AttributionClassification | ApprovalGateClassification | JudgmentClassification;
 export declare const DIRECTIVE_LANGUAGE: RegExp;
 /**
  * Imperative instruction — a bare command verb starting a clause ("Use
@@ -142,5 +154,6 @@ export declare function isEventRecord(rule: Rule): boolean;
  * is the forbidden command ("Never run: `rm -rf /`") is still a rule.
  */
 export declare function isCommandDocumentation(rule: Rule): boolean;
+export declare function approvalGateActions(rule: Rule): string[];
 export declare function classifyRule(rule: Rule): Classification;
 export declare function classifyRules(rules: Rule[]): Classification[];

package/dist/checks/classify.js

@@ -152,6 +152,12 @@ function isNotARule(rule) {
     const combined = `${rule.title} ${rule.text}`;
     if (DIRECTIVE_LANGUAGE.test(combined))
         return false;
+    // A gate over a concrete action ("before you delete data, wait for
+    // confirmation") is a rule, even when its imperative sits after a comma
+    // where IMPERATIVE_INSTRUCTION's clause-start anchor cannot see it. Placed
+    // after the event-record and command-doc filters so those still win.
+    if (isApprovalGateRule(rule))
+        return false;
     // Title and text are tested SEPARATELY: the imperative pattern is
     // anchored to a clause start, and concatenating them pushes the text's
     // opening verb into mid-string where the anchor can never match. That
@@ -493,6 +499,74 @@ function isEmojiRule(rule) {
     const window = text.slice(Math.max(0, m.index - 60), m.index + 40);
     return EMOJI_FORBID.test(window);
 }
+/**
+ * A rule that forbids an AI-authorship mark in git commits, PRs or comments.
+ *
+ * Same shape as the emoji test: a subject (an attribution mark) and a
+ * prohibition next to it, plus a git/GitHub context so a general rule about
+ * crediting sources does not route here. Placed before the backtick pass
+ * because the rule quotes the exact trailer it forbids (`Co-Authored-By:
+ * Claude`), which would otherwise be extracted as a literal and searched for
+ * across written files — flagging the prohibition itself.
+ *
+ * From anthropics/claude-code#83813, #92169, #82690, #4287, one of the most-
+ * filed rule-following complaints. This repo's own CLAUDE.md carries this
+ * rule, so the check is dogfooded on every session here.
+ */
+const ATTRIBUTION_SUBJECT = /co-?authored-by|generated with\s*\[?\s*claude|\bai\b[^.\n]{0,20}(?:trace|attribution|authorship)|\battribution\b/i;
+const ATTRIBUTION_CONTEXT = /\b(?:commit|git|pull request|\bpr\b|github|co-?author)\b/i;
+const ATTRIBUTION_FORBID = /\b(?:no|never|don't|do not|without|must not|shall not|not add|zero|forbid)\b/i;
+function isAttributionRule(rule) {
+    const text = `${rule.title} ${rule.text}`;
+    if (!ATTRIBUTION_SUBJECT.test(text))
+        return false;
+    if (!ATTRIBUTION_CONTEXT.test(text))
+        return false;
+    if (!ATTRIBUTION_FORBID.test(text))
+        return false;
+    const m = text.match(ATTRIBUTION_SUBJECT);
+    if (!m || m.index === undefined)
+        return false;
+    const window = text.slice(Math.max(0, m.index - 60), m.index + 60);
+    return ATTRIBUTION_FORBID.test(window);
+}
+/**
+ * A rule that says the agent must ASK before a concrete, detectable action.
+ *
+ * "Wait for approval before you delete", "repeat-back before destructive
+ * actions", "ask first before you push". These already trip PRE_ACTION_GATE
+ * (which deflects them away from claimEvidence); routing them here lets the
+ * ONE mechanically-honest half be answered without the LLM: did the assistant
+ * seek approval before it did the thing.
+ *
+ * Only routes when the rule names an action this can actually find in a
+ * transcript — push, commit, delete/rm/drop/truncate. A gate over something
+ * vague ("ask before big changes") has no detectable action and stays a
+ * judgment call. The subtle half — whether a reply actually GRANTED approval,
+ * the #92505 "read my frustration as a yes" case — is not claimed here.
+ */
+const APPROVAL_GATE_ACTIONS = [
+    { key: "push", inRule: /\bpush(?:es|ed|ing)?\b/i },
+    { key: "commit", inRule: /\bcommit(?:s|ted|ting)?\b/i },
+    { key: "delete", inRule: /\b(?:delet\w*|remov\w*|wip(?:e|ed|ing)?|truncat\w*|drop)\b|\brm\b/i },
+];
+/**
+ * The rule must actually ask for sign-off, not merely order two things in
+ * time. "Run `npm test` before committing" gates a commit temporally but
+ * seeks no approval — it is a require-an-action rule, not this. Requiring an
+ * approval-seeking phrase (not the bare "before <action>" clause) is what
+ * keeps those out.
+ */
+const APPROVAL_SIGNAL = /\b(?:repeat[- ]back|restate\s+what|wait\s+for\s+(?:confirmation|approval|explicit|sign[- ]?off)|ask\s+(?:first|before|for\s+(?:permission|approval|confirmation|sign[- ]?off))|get\s+(?:approval|sign[- ]?off|permission)|(?:explicit\s+)?(?:approval|confirmation|sign[- ]?off|permission)\s+(?:is\s+)?(?:required|needed|first)|confirm\s+(?:first|before))\b/i;
+export function approvalGateActions(rule) {
+    const text = `${rule.title} ${rule.text}`;
+    if (!APPROVAL_SIGNAL.test(text))
+        return [];
+    return APPROVAL_GATE_ACTIONS.filter((a) => a.inRule.test(text)).map((a) => a.key);
+}
+function isApprovalGateRule(rule) {
+    return approvalGateActions(rule).length > 0;
+}
 export function classifyRule(rule) {
     // Checked first: if this isn't a rule at all, no check of any kind
     // should run against it — not a keyword match, not an LLM call.
@@ -511,6 +585,18 @@ export function classifyRule(rule) {
     if (isEmojiRule(rule)) {
         return { kind: "emojiOutput", rule, polarity: "forbid" };
     }
+    // Checked before the backtick test: the rule quotes the exact trailer it
+    // forbids, which would otherwise be extracted as a literal and searched
+    // for across written files, flagging the prohibition itself.
+    if (isAttributionRule(rule)) {
+        return { kind: "attribution", rule, polarity: "forbid" };
+    }
+    // Checked before the backtick pass: these carry action verbs, not literals,
+    // and would otherwise fall through to judgment. Only the ones naming a
+    // detectable action route here; the rest stay judgment.
+    if (isApprovalGateRule(rule)) {
+        return { kind: "approvalGate", rule, actions: approvalGateActions(rule), polarity: "forbid" };
+    }
     const patterns = new Set();
     for (const match of rule.text.matchAll(BACKTICK_TOKEN)) {
         const token = match[1].trim();

package/dist/cli.js

@@ -8,6 +8,8 @@ import { fileURLToPath } from "node:url";
 import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { readLatestTranscript, readTranscriptFromFile, findLatestSessionFile } from "./parsers/transcriptParser.js";
 import { loadRules } from "./rules.js";
+import { adviseRules } from "./checkability.js";
+import { 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";
@@ -510,11 +512,50 @@ function runCoverage() {
         console.log(`log or inject context, but they cannot make a rule fail when it is ignored.`);
     }
 }
+/**
+ * `rules --advise`: for every rule the classifier can't check mechanically,
+ * one line saying why and the smallest edit that would fix it. The other
+ * half of `--coverage` — that says which rules a hook might guard; this says
+ * which rules can't be checked at all, and how to change that.
+ */
+function runAdvise() {
+    const cwd = process.cwd();
+    const rules = loadRules(cwd);
+    if (rules.length === 0) {
+        console.log("No CLAUDE.md or AGENTS.md found, so there are no rules to advise on.");
+        return;
+    }
+    const advice = adviseRules(rules);
+    const checkable = rules.length - advice.length;
+    console.log(`Rule checkability\n`);
+    console.log(`  ${checkable} of ${rules.length} rule${rules.length === 1 ? "" : "s"} can be checked mechanically as written.`);
+    if (advice.length === 0) {
+        console.log(`\n  Every rule names something a check can bind to. Nothing to fix.`);
+        return;
+    }
+    console.log(`  ${advice.length} cannot yet — here is what each one needs:\n`);
+    // Project rules first: those are the ones the reader can act on today.
+    const ordered = advice
+        .map((a, i) => ({ a, source: rules.find((r) => r.title === a.ruleTitle)?.source }))
+        .sort((x, y) => Number(x.source === "global") - Number(y.source === "global"))
+        .map((x) => x.a);
+    for (const a of ordered) {
+        const tag = a.kind === "notARule" ? "not a rule?" : "judgment";
+        console.log(`  [${tag}] ${a.ruleTitle.replace(/\s+/g, " ").trim().slice(0, 76)}`);
+        console.log(`    -> ${a.suggestion}\n`);
+    }
+    console.log(`Naming the exact command, file or branch a rule is about — in backticks —`);
+    console.log(`is what turns a "wish list" line into one this tool can hold to account.`);
+}
 async function runRules(opts) {
     if (opts.coverage) {
         runCoverage();
         return;
     }
+    if (opts.advise) {
+        runAdvise();
+        return;
+    }
     const cwd = process.cwd();
     const rules = loadRules(cwd);
     const overrides = loadOverrides(cwd);
@@ -740,6 +781,7 @@ program
     .option("--clear <handle>", "remove a stored correction")
     .option("--list", "show stored corrections (the default when no other flag is given)")
     .option("--coverage", "show which rules a configured hook might actually be enforcing, and which are prose only")
+    .option("--advise", "for each rule that can't be checked mechanically, show why and the smallest edit that would fix it")
     .action((opts) => {
     runRules(opts).catch((err) => {
         console.error("Something went wrong:", err instanceof Error ? err.message : err);
@@ -767,6 +809,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/evaluate.js

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

package/dist/guard.js

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

package/dist/init.d.ts

@@ -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/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/dist/types.d.ts

@@ -64,7 +64,7 @@ export type CheckOutcome = "pass" | "fail"
 /** How a verdict was reached. A verdict with no method is a verdict with no standing. */
 export type CheckMethod = "text_scan" | "file_events" | "git_events" | "code_content" | "edit_test_pairing" | "claim_vs_evidence" | "model_judgment"
 /** Nothing ran. */
- | "none" | "emoji_output";
+ | "none" | "emoji_output" | "attribution_scan" | "approval_gate";
 export interface CheckResult {
     ruleId: string;
     ruleTitle: string;

package/package.json

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