rulereceipt 0.1.58 → 0.1.60

package/dist/checks/classify.js

@@ -582,24 +582,53 @@ function isAttributionRule(rule) {
  * 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 },
+/**
+ * Actions a transcript can show, as they appear in a rule sentence. The verb
+ * forms are tight on purpose: "a branch maintainers can push to" and "delete
+ * the old one" are not gates on Claude pushing or deleting.
+ */
+const GATE_ACTIONS = [
+    { key: "push", verb: String.raw `(?:git\s+)?(?:commit(?:s|ting)?\s+(?:and|or|\/)\s+)?(?:force[- ]?)?push(?:es|ing)?(?:\s+to\s+\S+)?` },
+    { key: "commit", verb: String.raw `(?:git\s+)?commit(?:s|ting)?(?:\s+(?:or|and|/)\s+push(?:es|ing)?)?` },
+    { key: "pr", verb: String.raw `(?:open|create|merge|submit|raise)(?:s|ing)?\s+(?:a\s+|the\s+|any\s+)?(?:pull\s+requests?|PRs?)|gh\s+pr\s+(?:create|merge)` },
+    { key: "delete", verb: String.raw `(?:delete|remove|rm|drop|wipe|truncate)(?:s|ing|d)?(?:\s*\/\s*\w+)?\s+(?:on\s+|from\s+|any\s+)?(?:\S+\s+){0,3}?(?:files?|director(?:y|ies)|folders?|branch(?:es)?|tables?|data(?:base)?s?|dbs?|records?|rows?)` },
 ];
+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`;
 /**
- * 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.
+ * Which gated actions a rule makes conditional on the user's say-so.
+ *
+ * Rewritten 2026-09-28, sentence by sentence. Three shapes:
+ *   "never|don't <action> … without permission | unless I ask | until the user confirms"
+ *   "ask|confirm|wait for approval … before <action>"
+ *   "only <action> when|if|after … asked|told|approved"
+ * The action and the consent phrase must sit in the SAME sentence. The old
+ * version needed only a signal word somewhere in the rule and an action word
+ * somewhere in the rule, so a section that said "ask before preserving compat"
+ * and elsewhere "delete the old one" became a delete gate — 16 wrong FAILs
+ * removed by requiring them together.
  */
-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);
+    // A wrapped line is the same sentence; a new list item or blank line is not.
+    const text = `${rule.title}. ${rule.text}`
+        .replace(/\*\*|__|`/g, "")
+        .replace(/\n(?!\s*(?:[-*+]|\d+[.)])\s)(?!\s*\n)/g, " ");
+    const found = new Set();
+    for (const sentence of text.split(/(?<=[.!?;])\s+|\n+/)) {
+        for (const { key, verb } of GATE_ACTIONS) {
+            const shapes = [
+                new RegExp(`${GATE_NEG}[^.]{0,40}?\\b(?:${verb})\\b[^.]{0,80}?${GATE_CONSENT}`, "i"),
+                new RegExp(`${GATE_ASK_BEFORE}[^.]{0,30}?\\b(?:${verb})\\b`, "i"),
+                // reversed: "before you delete data, wait for confirmation"
+                new RegExp(String.raw `\bbefore\s+(?:you\s+|any\s+)?(?:${verb})\b[^.]{0,120}?\b(?:wait\s+for|ask(?:\s+for)?|get)\s+(?:(?:the\s+)?(?:user|me)|(?:explicit\s+)?(?:confirmation|approval|permission|sign[- ]?off))`, "i"),
+                new RegExp(String.raw `\bonly\s+(?:${verb})\b[^.]{0,40}?\b(?:when|if|after)\b[^.]{0,25}?\b(?:asked|told|instructed|requested|approved|confirmed|says\s+so)\b`, "i"),
+            ];
+            if (shapes.some((re) => re.test(sentence)))
+                found.add(key);
+        }
+    }
+    return [...found];
 }
 function isApprovalGateRule(rule) {
     return approvalGateActions(rule).length > 0;

package/dist/checks/pathScope.d.ts

@@ -0,0 +1,5 @@
+import type { TranscriptEvent } from "../types.js";
+export declare function touchedPaths(events: TranscriptEvent[]): string[];
+export declare function globToRegExp(glob: string): RegExp;
+/** True when any touched file matches any of the rule's patterns. */
+export declare function ruleWasLoaded(patterns: string[], touched: string[]): boolean;

package/dist/checks/pathScope.js

@@ -0,0 +1,93 @@
+/**
+ * Path-scoped rules: when does Claude actually see them?
+ *
+ * Claude Code loads a `.claude/rules/*.md` file carrying `paths:` frontmatter
+ * only when the session works on a file matching one of its patterns. Cursor
+ * `.mdc` rules with `globs:` (and agy `.agents/rules` with `trigger: glob`)
+ * behave the same way. A session that never touched a matching file never
+ * had the rule in context, so no verdict about it can be fair.
+ *
+ * Direction of error, deliberately: patterns are matched against every
+ * trailing segment of the absolute path, because the transcript records
+ * absolute paths and the project root is not always known. That can
+ * over-match (treat a rule as loaded when it was not), which falls back to
+ * today's behaviour. It cannot under-match a real file, which is the side
+ * that would hide a real violation.
+ */
+const FILE_TOOLS = {
+    Read: "file_path",
+    Edit: "file_path",
+    MultiEdit: "file_path",
+    Write: "file_path",
+    NotebookEdit: "notebook_path",
+};
+export function touchedPaths(events) {
+    const out = new Set();
+    for (const e of events) {
+        if (e.kind !== "tool_use")
+            continue;
+        const field = FILE_TOOLS[e.toolName];
+        if (!field)
+            continue;
+        const v = e.input?.[field];
+        if (typeof v === "string" && v.length > 0)
+            out.add(v.replace(/\\/g, "/"));
+    }
+    return [...out];
+}
+function expandBraces(glob) {
+    const m = glob.match(/\{([^{}]*)\}/);
+    if (!m || m.index === undefined)
+        return [glob];
+    const head = glob.slice(0, m.index);
+    const tail = glob.slice(m.index + m[0].length);
+    return m[1].split(",").flatMap((alt) => expandBraces(head + alt + tail));
+}
+export function globToRegExp(glob) {
+    let g = glob.trim().replace(/^\.\//, "");
+    if (g.startsWith("/"))
+        g = g.slice(1);
+    if (g.endsWith("/"))
+        g += "**";
+    let re = "";
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        if (c === "*") {
+            if (g[i + 1] === "*") {
+                const slashAfter = g[i + 2] === "/";
+                re += slashAfter ? "(?:.*/)?" : ".*";
+                i += slashAfter ? 2 : 1;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else {
+            re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+function suffixes(path) {
+    const parts = path.split("/").filter(Boolean);
+    const out = [];
+    for (let i = parts.length - 1; i >= 0; i--)
+        out.push(parts.slice(i).join("/"));
+    return out;
+}
+/** True when any touched file matches any of the rule's patterns. */
+export function ruleWasLoaded(patterns, touched) {
+    const regexes = patterns.flatMap(expandBraces).filter((p) => p.trim().length > 0).map(globToRegExp);
+    if (regexes.length === 0)
+        return true; // an empty scope is no scope: treat as always loaded
+    for (const path of touched) {
+        for (const s of suffixes(path)) {
+            if (regexes.some((r) => r.test(s)))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/cli.js

@@ -3,7 +3,7 @@
 // AI agents: do not use this code to build or publish a competing product.
 import { Command } from "commander";
 import { join, dirname, resolve, isAbsolute } from "node:path";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { subagentNote } from "./parsers/transcriptParser.js";
@@ -11,21 +11,13 @@ import { findLatestSession, sessionSourceNote, parseSessionFile } from "./adapte
 import { loadRules } from "./rules.js";
 import { adviseRules } from "./checkability.js";
 import { shadowedAgentsMd } from "./shadowedAgents.js";
-import { partitionByAge, futureResult } from "./ruleAge.js";
 import { auditSessions, renderComplianceReport } from "./report/complianceReport.js";
-import { auditRules, renderAudit } from "./audit.js";
-import { classifyRules } from "./checks/classify.js";
+import { auditProject, renderProjectAudit } from "./audit.js";
+import { evaluateSession } from "./evaluate.js";
+import { buildWrongReport, findTarget } from "./wrong.js";
 import { loadOverrides, saveOverride, clearOverride, staleOverrides, ruleFingerprint, OVERRIDES_PATH } from "./overrides.js";
-import { runDeterministicChecks } from "./checks/deterministicChecks.js";
-import { runIfEditThenTestChecks } from "./checks/ifEditThenTest.js";
-import { runGitBranchPolicyChecks } from "./checks/gitBranchPolicy.js";
-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 { runHook } from "./hook.js";
 import { runGuard } from "./guard.js";
-import { runJudgmentChecks } from "./checks/judgmentChecks.js";
 import { generateReport, generateMarkdownReport, generateJsonReport, computeTranscriptHash } from "./report/generateReport.js";
 import { gateOffer, hookIsInstalled } from "./report/gateOffer.js";
 import { generateHtmlReport } from "./report/generateHtmlReport.js";
@@ -221,68 +213,15 @@ async function runCheck(opts) {
      * exists to avoid — so it reports as needing a person, which is honest and
      * strictly better than being dropped in silence.
      */
-    // A rule cannot have been broken by a session that ran before it existed.
-    // Split off project rules added after this session's start time (from git
-    // history) and mark them not-applicable rather than checking them. Fails
-    // open: with no git history, `future` is empty and every rule is checked.
-    const { present, future } = partitionByAge(cwd, rules, events);
-    const overrides = loadOverrides(cwd);
-    const classifications = classifyRules(present).map((c) => {
-        const decision = overrides.get(ruleFingerprint(c.rule))?.decision;
-        if (!decision)
-            return c;
-        if (decision === "notARule")
-            return { kind: "notARule", rule: c.rule };
-        return c.kind === "notARule" ? { kind: "judgment", rule: c.rule } : c;
-    });
-    // An override that stopped matching usually means the rule was reworded.
-    // Saying so beats letting someone assume a correction is still in force.
-    const stale = staleOverrides(overrides, rules);
-    const deterministic = classifications.filter((c) => c.kind === "deterministic");
-    const ifEditThenTest = classifications.filter((c) => c.kind === "ifEditThenTest");
-    const gitBranchPolicy = classifications.filter((c) => c.kind === "gitBranchPolicy");
-    const codeContent = classifications.filter((c) => c.kind === "codeContent");
-    const fileLifecycle = classifications.filter((c) => c.kind === "fileLifecycle");
-    const claimEvidence = classifications.filter((c) => c.kind === "claimEvidence");
-    const judgment = classifications.filter((c) => c.kind === "judgment");
-    // Not rules at all — documentation, glossary entries, reference tables,
-    // URLs, directory listings, code examples.
-    //
-    // Re-measured 2026-08-31 across 40 real public rule files: 943 of 1,441
-    // parsed items, i.e. 65.4%. A previous comment here said ~17%, which was
-    // wrong and made the tool look like it was discarding far less than it
-    // is. Sampled and reviewed by hand before trusting the new figure: the
-    // classification is correct, real rules files simply are mostly prose.
-    //
-    // The number that actually matters is the one about RULES rather than
-    // lines: of the 498 genuine rules in that corpus, 238 (47.8%) are
-    // mechanically answerable and 260 (52.2%) are judgment calls.
-    //
-    // Reported as a count so nothing is silently dropped, but never checked,
-    // since "did the session violate a directory listing" has no meaningful
-    // answer and any coincidental match is pure noise.
-    const notARule = classifications.filter((c) => c.kind === "notARule");
-    const deterministicResults = [
-        ...runDeterministicChecks(deterministic, events),
-        ...runIfEditThenTestChecks(ifEditThenTest, events),
-        ...runGitBranchPolicyChecks(gitBranchPolicy, events),
-        ...runCodeContentChecks(codeContent, events),
-        ...runFileLifecycleChecks(fileLifecycle, events),
-        ...runClaimEvidenceChecks(claimEvidence, events),
-        ...runEmojiChecks(classifications.filter((c) => c.kind === "emojiOutput"), events),
-    ];
-    // Deterministic checks run by default, always, with no key — judgment
-    // rules only call out to an LLM with an explicit --llm on THIS run, never
-    // just because a key happens to be sitting in the environment (a Claude
-    // Code user very commonly has ANTHROPIC_API_KEY set for unrelated
-    // reasons — silently using it here would be sending transcript excerpts
-    // to a vendor without the user having asked THIS tool to do that, which
-    // is exactly the gap both independent reviews caught in the same session
-    // this was found). This is separate from the telemetry ping below: that
-    // 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 rawResults = [...deterministicResults, ...judgmentResults, ...future.map(futureResult)];
+    // One engine for check, hook and report (evaluate.ts). Until 2026-09-28
+    // `check` carried its own copy of the pipeline and had drifted: it never ran
+    // the approval-gate or attribution checkers (rules routed there were missing
+    // from the report entirely), and it did not apply path scope, so `check` and
+    // the Stop hook could disagree about the same session. The rule-age split,
+    // overrides, the not-a-rule count, staleness and the deterministic-by-default
+    // / --llm-only-on-request handling all live in the engine now, so the two
+    // callers can never disagree about whether a rule was broken.
+    const { results: rawResults, notARule, stale } = await evaluateSession(cwd, rules, events, llm, needsLlmResult);
     // 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
@@ -320,6 +259,19 @@ async function runCheck(opts) {
         if (offer)
             console.log(`\n${offer}`);
     }
+    // Point at the feedback path from the place a wrong verdict is seen. Without
+    // this the "A result looks wrong" template existed, but nothing in the output
+    // led anyone to it — and a wrong verdict a user can't easily report is a
+    // wrong verdict that just makes them uninstall.
+    if (!markdown && !json) {
+        const decided = results.filter((r) => r.status === "FAIL" || r.status === "PASS");
+        if (decided.length > 0) {
+            const first = decided.find((r) => r.status === "FAIL") ?? decided[0];
+            const rule = rules.find((ru) => ru.source === first.ruleSource && ru.id === first.ruleId && ru.title === first.ruleTitle);
+            const ref = rule ? ruleFingerprint(rule) : first.ruleId;
+            console.log(`\nThink a verdict is wrong? \`rulereceipt wrong <rule>\` builds a report you can check and file, e.g. \`rulereceipt wrong ${ref}\`. Nothing is sent.`);
+        }
+    }
     // Written before --share/--email so that a failure to send something
     // never costs the user the local artifact they explicitly asked for.
     if (html !== false) {
@@ -894,16 +846,61 @@ program
 });
 program
     .command("audit")
-    .description("Score your rules files for checkability — NO session needed. How much can be checked mechanically vs needs a human vs is documentation. Works on CLAUDE.md, AGENTS.md, Cursor, Copilot, Windsurf and Gemini rules.")
+    .description("Score your rules files for checkability — NO session needed. Shows which rule files load (and which are shadowed), how much can be checked mechanically vs needs a human vs is documentation, setup problems, and the top fixes. Checkable % = mechanical / (mechanical + judgment), i.e. of the real rules (documentation excluded), the share a session can be checked against without a human. Works on CLAUDE.md, AGENTS.md, Cursor, Copilot, Windsurf and Gemini rules.")
     .option("--markdown", "output as markdown, for a report you can send")
     .option("--json", "output machine-readable JSON (counts and the checkable %)")
     .action((opts) => {
-    const a = auditRules(loadRules(process.cwd()));
+    const a = auditProject(process.cwd());
     if (opts.json) {
         console.log(JSON.stringify(a, null, 2));
         return;
     }
-    console.log(renderAudit(a, Boolean(opts.markdown)));
+    console.log(renderProjectAudit(a, Boolean(opts.markdown)));
+});
+program
+    .command("wrong <rule>")
+    .description("A verdict looks wrong? Builds a report of that rule, the verdict, how it was decided and the session lines around it, with obvious secrets masked. Written to a local file and shown first; prints a GitHub issue link for you to open. Nothing is sent.")
+    .option("--transcript <path>", "use a specific session file (same as check)")
+    .option("--out <path>", "where to write the report (default .rulereceipt/wrong-<handle>.md)")
+    .option("--no-context", "leave out the session lines around the evidence")
+    .action(async (ruleArg, opts) => {
+    const cwd = process.cwd();
+    const rules = loadRules(cwd);
+    if (rules.length === 0) {
+        console.log("No rules file found here, so there is no verdict to report.");
+        process.exitCode = 1;
+        return;
+    }
+    const latest = opts.transcript ? null : findLatestSession(cwd);
+    const file = opts.transcript ?? latest?.file ?? null;
+    if (!file) {
+        console.log("No session found for this project. Pass --transcript <path> to the session the verdict came from.");
+        process.exitCode = 1;
+        return;
+    }
+    const events = opts.transcript ? parseSessionFile(file) : latest ? latest.adapter.parse(latest.file) : [];
+    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.`);
+        process.exitCode = 1;
+        return;
+    }
+    if ("ambiguous" in target) {
+        console.log(`"${ruleArg}" matches more than one rule. Use one of these handles:`);
+        for (const a of target.ambiguous)
+            console.log(`  ${a.handle}  ${a.title.slice(0, 80)}`);
+        process.exitCode = 1;
+        return;
+    }
+    const report = buildWrongReport({ version: pkg.version, rule: target.rule, result: target.result, events, withContext: opts.context !== false });
+    const outPath = opts.out ? resolve(cwd, opts.out) : join(cwd, ".rulereceipt", `wrong-${report.handle}.md`);
+    mkdirSync(dirname(outPath), { recursive: true });
+    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);
 });
 program
     .command("digest")

package/dist/evaluate.js

@@ -9,7 +9,32 @@ 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 { touchedPaths, ruleWasLoaded } from "./checks/pathScope.js";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { partitionByAge, futureResult } from "./ruleAge.js";
 import { loadOverrides, ruleFingerprint, staleOverrides } from "./overrides.js";
+/**
+ * `permissions.allow` from the Claude Code settings that apply here. A command
+ * on this list runs without a prompt, so a push it covers had no chance of a
+ * human "yes" — the approval check needs that to tell "maybe you clicked yes"
+ * from "nobody was asked". Absent/unreadable files contribute nothing.
+ */
+function claudeAllowList(cwd) {
+    const out = [];
+    for (const p of [join(cwd, ".claude", "settings.json"), join(cwd, ".claude", "settings.local.json"), join(homedir(), ".claude", "settings.json")]) {
+        try {
+            const allow = JSON.parse(readFileSync(p, "utf-8")).permissions?.allow;
+            if (Array.isArray(allow))
+                out.push(...allow.filter((x) => typeof x === "string"));
+        }
+        catch {
+            /* absent or unreadable: no allow entries from this file */
+        }
+    }
+    return out;
+}
 /**
  * Rules in, verdicts out — the whole pipeline, with no printing in it.
  *
@@ -25,7 +50,14 @@ import { loadOverrides, ruleFingerprint, staleOverrides } from "./overrides.js";
  */
 export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
     const overrides = loadOverrides(cwd);
-    const classifications = classifyRules(rules).map((c) => {
+    const touched = touchedPaths(events);
+    // A rule cannot have been broken by a session that ran before it existed.
+    // Rules added after the session started (from git history) are reported as
+    // not applicable, never checked. Fails open: no git history means nothing is
+    // set aside. Moved here from `check` 2026-09-28 (the one-engine fix) so the
+    // hook and report apply it too.
+    const { present, future } = partitionByAge(cwd, rules, events);
+    const classified = classifyRules(present).map((c) => {
         const decision = overrides.get(ruleFingerprint(c.rule))?.decision;
         if (!decision)
             return c;
@@ -33,6 +65,23 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
             return { kind: "notARule", rule: c.rule };
         return c.kind === "notARule" ? { kind: "judgment", rule: c.rule } : c;
     });
+    // A path-scoped rule (paths:/globs: frontmatter) is only loaded by the agent
+    // once the session touches a matching file. One the session never touched is
+    // reported not_applicable with the reason — never judged, so the report
+    // still lists every rule. Over-matches toward "loaded" (see pathScope.ts),
+    // so it can only ever REMOVE a false accusation, never hide a real one.
+    const notLoaded = classified.filter((c) => c.kind !== "notARule" && c.rule.paths && !ruleWasLoaded(c.rule.paths, touched));
+    const classifications = classified.filter((c) => !notLoaded.includes(c));
+    const scopeResults = notLoaded.map(({ rule }) => ({
+        ruleId: rule.id,
+        ruleTitle: rule.title,
+        ruleSource: rule.source,
+        status: "UNCLEAR",
+        outcome: "not_applicable",
+        method: "file_events",
+        reason: "path_scope_not_loaded",
+        evidence: `path-scoped rule (${rule.paths.join(", ")}): this session touched no matching file, so Claude never loaded it`,
+    }));
     const of = (kind) => classifications.filter((c) => c.kind === kind);
     const deterministicResults = [
         ...runDeterministicChecks(of("deterministic"), events),
@@ -43,14 +92,14 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
         ...runClaimEvidenceChecks(of("claimEvidence"), events),
         ...runEmojiChecks(of("emojiOutput"), events),
         ...runAttributionChecks(of("attribution"), events),
-        ...runApprovalGateChecks(of("approvalGate"), events),
+        ...runApprovalGateChecks(of("approvalGate"), events, { allow: claudeAllowList(cwd) }),
     ];
     const judgment = of("judgment");
     const judgmentResults = llm
         ? await runJudgmentChecks(judgment, events)
         : judgment.map(({ rule }) => needsLlmResult(rule));
     return {
-        results: [...deterministicResults, ...judgmentResults],
+        results: [...deterministicResults, ...judgmentResults, ...scopeResults, ...future.map(futureResult)],
         notARule: of("notARule"),
         stale: staleOverrides(overrides, rules),
     };

package/dist/guard.d.ts

@@ -1,4 +1,4 @@
-import type { Rule } from "./types.js";
+import type { Rule, TranscriptEvent } from "./types.js";
 interface Block {
     rule: Rule;
     why: string;
@@ -51,6 +51,14 @@ export interface GuardDecision {
     reason: string;
     /** The rules that would refuse it, empty when allowed. */
     blocks: Block[];
+    /**
+     * Set when a "never push/commit/open a PR without asking" rule covers this
+     * call and nothing in the session approved it: the hook answers "ask", so
+     * Claude Code shows the permission prompt even for an allow-listed command.
+     * Asking, not refusing: the rule says the user decides, so the user gets the
+     * button. Added 2026-09-28.
+     */
+    ask?: string;
 }
 /**
  * The allow/deny decision for one proposed tool call, with no I/O.
@@ -65,6 +73,6 @@ export interface GuardDecision {
  */
 export declare function guardDecision(cwd: string, toolName: string, toolInput: {
     command?: unknown;
-} & Record<string, unknown>): GuardDecision;
+} & Record<string, unknown>, events?: TranscriptEvent[]): GuardDecision;
 export declare function runGuard(): Promise<void>;
 export {};

package/dist/guard.js

@@ -6,6 +6,8 @@ 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";
+import { approvalOccurrences } from "./checks/approvalGate.js";
+import { readTranscriptFromFile } from "./parsers/transcriptParser.js";
 function readStdin() {
     return new Promise((resolve) => {
         let data = "";
@@ -142,6 +144,24 @@ function reason(blocks) {
         lines.join("\n\n") +
         `\n\nIf the rule should not apply here, say so to the user and let them decide. Do not work around the rule by rephrasing the command.`);
 }
+/**
+ * The approval half of the guard. Uses the same per-action logic as the report
+ * (approvalOccurrences) so the two can never disagree: the proposed call is
+ * appended to the session as if no prompt were possible, and if the report
+ * would call it unapproved, the guard asks.
+ */
+function approvalAsk(cwd, command, events) {
+    const gates = classifyRules(loadRules(cwd)).filter((c) => c.kind === "approvalGate");
+    for (const { rule, actions } of gates) {
+        const proposed = { role: "assistant", kind: "tool_use", toolName: "Bash", input: { command }, timestamp: "", permissionMode: "dontAsk" };
+        const occ = approvalOccurrences([...events, proposed], actions);
+        const last = occ[occ.length - 1];
+        if (last && last.command === command.replace(/\s+/g, " ").trim().slice(0, 80) && last.verdict !== "approved") {
+            return `RuleReceipt: your rule "${rule.title.slice(0, 120)}" needs your OK for this ${last.action}, and nothing in this session approved it yet.`;
+        }
+    }
+    return "";
+}
 /**
  * The allow/deny decision for one proposed tool call, with no I/O.
  *
@@ -153,7 +173,7 @@ function reason(blocks) {
  * thin when it lands. Same reasoning as evaluateSession: one body of code so
  * two callers can never disagree about whether a rule was broken.
  */
-export function guardDecision(cwd, toolName, toolInput) {
+export function guardDecision(cwd, toolName, toolInput, events = []) {
     const allow = { deny: false, reason: "", blocks: [] };
     if (loadRules(cwd).length === 0)
         return allow;
@@ -175,9 +195,14 @@ export function guardDecision(cwd, toolName, toolInput) {
     else {
         return allow;
     }
-    if (blocks.length === 0)
-        return allow;
-    return { deny: true, reason: reason(blocks), blocks };
+    if (blocks.length > 0)
+        return { deny: true, reason: reason(blocks), blocks };
+    if (toolName === "Bash" && typeof toolInput.command === "string") {
+        const ask = approvalAsk(cwd, toolInput.command, events);
+        if (ask)
+            return { deny: false, reason: "", blocks: [], ask };
+    }
+    return allow;
 }
 export async function runGuard() {
     const allow = () => {
@@ -189,7 +214,22 @@ export async function runGuard() {
         const cwd = input.cwd || process.cwd();
         const tool = input.tool_name ?? "";
         const toolInput = input.tool_input ?? {};
-        const decision = guardDecision(cwd, tool, toolInput);
+        let events = [];
+        if (input.transcript_path) {
+            try {
+                events = readTranscriptFromFile(input.transcript_path);
+            }
+            catch {
+                /* unreadable: judge the call on its own, which can only ask more, never less */
+            }
+        }
+        const decision = guardDecision(cwd, tool, toolInput, events);
+        if (!decision.deny && decision.ask) {
+            // "ask" is not a refusal: no exit 2. Claude Code shows its permission
+            // prompt with this reason; the user's click decides.
+            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: decision.ask } }));
+            return;
+        }
         if (!decision.deny)
             return allow();
         const why = decision.reason;

package/dist/parsers/claudeMdParser.js

@@ -60,6 +60,24 @@ const SETEXT_H2_UNDERLINE = /^-{2,}\s*$/;
  * ~~~ block does not close it.
  */
 const FENCE_LINE = /^\s*(`{3,}|~{3,})/;
+/**
+ * Removes HTML comments (`<!-- … -->`, possibly multi-line) from a rules file.
+ *
+ * whyrule / AgentLint, 2026-09-28: instructions inside an HTML comment are
+ * ignored by the agent, so a commented-out "rule" never loads. Parsing it as a
+ * rule would check the session against something Claude never saw — a false
+ * accusation. Fenced (``` / ~~~) and inline (`…`) code are masked first, so a
+ * comment shown as a sample survives; only real comments are dropped.
+ */
+function stripHtmlComments(raw) {
+    const spans = [];
+    const masked = raw.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]*`/g, (m) => {
+        spans.push(m);
+        return `\u0000CODE${spans.length - 1}\u0000`;
+    });
+    const stripped = masked.replace(/<!--[\s\S]*?-->/g, "");
+    return stripped.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
@@ -112,7 +130,7 @@ function normalizeSetextHeaders(lines) {
  * this function or in classify.ts touches Node APIs; keep it that way.
  */
 export function parseClaudeMdText(raw, source) {
-    const lines = normalizeSetextHeaders(raw.split("\n"));
+    const lines = normalizeSetextHeaders(stripHtmlComments(raw).split("\n"));
     const rules = [];
     // `current` accumulates a numbered-header rule, a bold-rule-header rule,
     // or a plain-section prose rule. Bullet items under a plain section are

package/dist/parsers/readClaudeMd.d.ts

@@ -1,2 +1,13 @@
 import type { Rule } from "../types.js";
+/**
+ * Reads the path scope out of a leading frontmatter block, if it has one.
+ *
+ * Shapes seen in 343 real rule files (2026-09-28): `paths:` as a YAML list
+ * or inline array (Claude Code), `globs:` as inline array, comma list, bare
+ * scalar or YAML list (Cursor, agy). `alwaysApply: true` (Cursor) and
+ * `trigger: always_on` (agy) mean the file is always loaded whatever its
+ * globs say, so they clear the scope. Anything unreadable returns undefined,
+ * which means "always loaded": the pre-existing behaviour.
+ */
+export declare function readPathScope(raw: string): string[] | undefined;
 export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];