rulereceipt 0.1.38 → 0.1.40

package/README.md

@@ -168,16 +168,37 @@ Read the limit before wiring it in, because it is most of the story. It
 enforces rules naming a **file** or a **branch** — "never modify `.env`",
 "never commit to `main`" — and nothing else.
 
-It does **not** block banned commands. That was the point of building it, and
-it did not survive measurement: replaying 16,336 real tool calls against every
-forbidding rule in a 559-file corpus, blocking on command literals refused
-62.8% of them. Narrowing twice reached 2.5%, and the residue was still wrong
-in a way no matcher fixes — one rule refused `npm run build` 112 times,
-because it forbids running Playwright unprompted and *recommends*
-`npm run build`, which is its only command-shaped literal.
+It does **not** block a banned command unless you have said which command is
+banned. That was the point of building it, and the automatic version did not
+survive measurement: replaying 16,336 real tool calls against every forbidding
+rule in a 559-file corpus, blocking on command literals refused 62.8% of them.
+Narrowing twice reached 2.5%, and the residue was still wrong in a way no
+matcher fixes — one rule refused `npm run build` 112 times, because it forbids
+running Playwright unprompted and *recommends* `npm run build`, which is its
+only command-shaped literal.
 
 Nothing in a rules file marks which backtick is the prohibition. A report
-survives that by saying UNCLEAR. A gate cannot.
+survives that by saying UNCLEAR. A gate cannot — so you mark it:
+
+```bash
+rulereceipt rules --forbid <handle> --literal "git push --force"
+```
+
+Handles come from `rulereceipt rules --handles`. The mark is stored
+against the rule's content hash, and the guard blocks on that literal and no
+other. Three things it deliberately will not do:
+
+- An **unmarked** rule cannot block, at any confidence, ever. There is no
+  fallback to "probably the first literal" — that fallback is the bug.
+- **Rewording the rule drops the mark.** It would otherwise carry your
+  judgment onto words you never read.
+- A mark naming a literal the rule no longer contains is **ignored**. A gate
+  refusing a command for a reason written nowhere is the worst failure a gate
+  has.
+
+Of 99 forbidding rules in the corpus that name a command-shaped literal, only
+43 have a prohibition that actually introduces one. The rest could never be
+marked automatically, which is the point.
 
 
 ## Which rules actually have teeth

package/dist/checks/classify.d.ts

@@ -107,6 +107,36 @@ export interface ClaimEvidenceClassification {
     rule: Rule;
 }
 export type Classification = ClaimEvidenceClassification | DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | JudgmentClassification;
+export declare const DIRECTIVE_LANGUAGE: RegExp;
+/**
+ * Imperative instruction — a bare command verb starting a clause ("Use
+ * `gh pr merge`", "Run the tests first", "Keep functions small"). This is
+ * the other way a real rule is written when it doesn't use a modal.
+ *
+ * Anchored to a clause start (line start, or after sentence/bullet
+ * punctuation) on purpose: the same verbs appear mid-sentence in pure
+ * documentation ("the CLI can run migrations"), where they describe a
+ * capability rather than instruct the agent.
+ */
+export declare const IMPERATIVE_INSTRUCTION: RegExp;
+/**
+ * A title that OPENS with an instruction is a rule, whatever it goes on
+ * to mention. "Never repeat the 2026-08-28 incident" is a directive that
+ * happens to name an incident; "Real incident (2026-08-28): ..." is a
+ * report that happens to contain the word never further along.
+ */
+export declare const TITLE_OPENS_WITH_DIRECTIVE: RegExp;
+export declare function isEventRecord(rule: Rule): boolean;
+/**
+ * A heading that labels a command, with the command as its whole body:
+ * "Build release APK" over `.\gradlew assembleRelease`. The title reads as
+ * an imperative, but nothing here constrains the agent — it is a how-to, and
+ * there is no compliance to check.
+ *
+ * Guarded by TITLE_OPENS_WITH_DIRECTIVE so a genuine prohibition whose body
+ * is the forbidden command ("Never run: `rm -rf /`") is still a rule.
+ */
+export declare function isCommandDocumentation(rule: Rule): boolean;
 /**
  * A rule is only treated as deterministic when it names a specific,
  * literal, checkable token (a CLI flag, a command, an exact string) in

package/dist/checks/classify.js

@@ -1,7 +1,7 @@
 // Normative language — the thing that makes a line a rule rather than a
 // description. Deliberately broad on modals AND imperative verbs, because
 // a wrongly-excluded rule is a silent miss.
-const DIRECTIVE_LANGUAGE = /\b(never|always|must|should|shall|do not|don't|dont|cannot|can't|required?|requires|ensure|avoid|prefer|forbidden|prohibited|only|make sure|be sure|need|needs|needed|need to|has to|have to|expected to|responsible for)\b/i;
+export const DIRECTIVE_LANGUAGE = /\b(never|always|must|should|shall|do not|don't|dont|cannot|can't|required?|requires|ensure|avoid|prefer|forbidden|prohibited|only|make sure|be sure|need|needs|needed|need to|has to|have to|expected to|responsible for)\b/i;
 /**
  * Imperative instruction — a bare command verb starting a clause ("Use
  * `gh pr merge`", "Run the tests first", "Keep functions small"). This is
@@ -12,7 +12,7 @@ const DIRECTIVE_LANGUAGE = /\b(never|always|must|should|shall|do not|don't|dont|
  * documentation ("the CLI can run migrations"), where they describe a
  * capability rather than instruct the agent.
  */
-const IMPERATIVE_INSTRUCTION = /(?:^|[.;:!?]\s+|^\s*[-*+]\s*|\n\s*[-*+]\s*)(use|run|keep|write|add|remove|delete|check|verify|test|commit|document|update|create|follow|apply|include|exclude|handle|validate|escape|sanitize|log|report|raise|throw|return|call|invoke|split|group|sort|name|place|put|store|read|load|save|close|open|start|stop|restart|install|build|deploy|review|refactor|rename|move|copy|merge|rebase|squash|tag|branch|push|pull|fetch|clone|stage|stash|lead|state|explain|describe|list|show|surface|flag|mark|label|note|treat|assume|confirm|ask|wait|stick|limit|cap|batch|cache|mock|stub|assert|expect|measure|quantify|label)\b/i;
+export const IMPERATIVE_INSTRUCTION = /(?:^|[.;:!?]\s+|^\s*[-*+]\s*|\n\s*[-*+]\s*)(use|run|keep|write|add|remove|delete|check|verify|test|commit|document|update|create|follow|apply|include|exclude|handle|validate|escape|sanitize|log|report|raise|throw|return|call|invoke|split|group|sort|name|place|put|store|read|load|save|close|open|start|stop|restart|install|build|deploy|review|refactor|rename|move|copy|merge|rebase|squash|tag|branch|push|pull|fetch|clone|stage|stash|lead|state|explain|describe|list|show|surface|flag|mark|label|note|treat|assume|confirm|ask|wait|stick|limit|cap|batch|cache|mock|stub|assert|expect|measure|quantify|label)\b/i;
 /**
  * Deliberately inverted: tests for the presence of a DIRECTIVE, never for
  * the shape of documentation.
@@ -60,8 +60,8 @@ const EVENT_RECORD_TITLE = /\b(incident|post-?mortem|retro(spective)?|outage|wha
  * happens to name an incident; "Real incident (2026-08-28): ..." is a
  * report that happens to contain the word never further along.
  */
-const TITLE_OPENS_WITH_DIRECTIVE = /^\s*[-*+\d.\s]*(never|always|must|do not|don'?t|dont|avoid|ensure|prefer|only|make sure|be sure|no)\b/i;
-function isEventRecord(rule) {
+export const TITLE_OPENS_WITH_DIRECTIVE = /^\s*[-*+\d.\s]*(never|always|must|do not|don'?t|dont|avoid|ensure|prefer|only|make sure|be sure|no)\b/i;
+export function isEventRecord(rule) {
     if (TITLE_OPENS_WITH_DIRECTIVE.test(rule.title))
         return false;
     if (IMPERATIVE_INSTRUCTION.test(rule.title))
@@ -126,7 +126,7 @@ function looksLikeBareCommand(text) {
  * Guarded by TITLE_OPENS_WITH_DIRECTIVE so a genuine prohibition whose body
  * is the forbidden command ("Never run: `rm -rf /`") is still a rule.
  */
-function isCommandDocumentation(rule) {
+export function isCommandDocumentation(rule) {
     if (TITLE_OPENS_WITH_DIRECTIVE.test(rule.title))
         return false;
     if (FLAG_DOCUMENTATION.test(rule.text) || FLAG_DOCUMENTATION.test(rule.title))

package/dist/cli.js

@@ -488,6 +488,80 @@ async function runRules(opts) {
         }
         return;
     }
+    /**
+     * Marking WHICH clause of a rule is the prohibition.
+     *
+     * The one thing a rules file never says. Blocking on every backtick in a
+     * forbidding rule refused 62.8% of 16,336 real tool calls, and the worst
+     * survivor after two narrowings refused `npm run build` 112 times against
+     * a rule that recommends it. So the guard blocks on nothing here until a
+     * person names the clause, and this is where they name it.
+     */
+    if (opts.forbid) {
+        const rule = findRule(opts.forbid);
+        if (!rule) {
+            console.error(`No rule in this project has the handle ${opts.forbid}.`);
+            console.error(`Handles come from \`rulereceipt check --show-skipped\`, and change if the rule's wording changes.`);
+            process.exitCode = 1;
+            return;
+        }
+        const literal = opts.literal?.trim();
+        if (!literal) {
+            console.error(`--forbid needs --literal "<the exact command this rule bans>".`);
+            console.error(`Copy it from the rule itself; it has to appear in the rule's text.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (!`${rule.title}\n${rule.text ?? ""}`.includes(literal)) {
+            console.error(`That rule does not contain "${literal}".`);
+            console.error(`The mark has to name something the rule actually says, or a gate would`);
+            console.error(`refuse a command for a reason written nowhere.`);
+            process.exitCode = 1;
+            return;
+        }
+        const prior = overrides.get(opts.forbid)?.forbids ?? [];
+        const forbids = [...new Set([...prior, literal])];
+        saveOverride(cwd, {
+            hash: opts.forbid,
+            decision: overrides.get(opts.forbid)?.decision ?? "rule",
+            title: rule.title.replace(/\s+/g, " ").trim().slice(0, 200),
+            forbids,
+        });
+        console.log(`Saved to ${OVERRIDES_PATH}.`);
+        console.log(`  "${rule.title.replace(/\s+/g, " ").trim().slice(0, 90)}"`);
+        console.log(`  now blocks on: ${forbids.map((f) => `\`${f}\``).join(", ")}`);
+        console.log(`\nThis only takes effect if you run \`rulereceipt guard\` as a PreToolUse hook.`);
+        console.log(`Rewording the rule drops the mark, on purpose — it would otherwise carry`);
+        console.log(`your judgment onto words you never read.`);
+        return;
+    }
+    /**
+     * Every rule with its handle.
+     *
+     * --forbid needs a handle, and before this the only place handles were
+     * printed was `check --show-skipped`, which lists the items the classifier
+     * DISCARDED. A rule that is actually being checked had no handle anywhere,
+     * so the marking feature shipped in 0.1.39 could not be reached for any
+     * rule a user would want to mark. Found by trying to use it.
+     */
+    if (opts.handles) {
+        if (rules.length === 0) {
+            console.log("No CLAUDE.md or AGENTS.md rules found in this project.");
+            return;
+        }
+        console.log(`${rules.length} rule${rules.length === 1 ? "" : "s"} in this project:\n`);
+        for (const r of rules) {
+            const h = ruleFingerprint(r);
+            const marked = overrides.get(h)?.forbids;
+            console.log(`  ${h}  ${r.title.replace(/\s+/g, " ").trim().slice(0, 72)}`);
+            if (marked?.length)
+                console.log(`                blocks on: ${marked.map((f) => `\`${f}\``).join(", ")}`);
+        }
+        console.log(`\nMark which clause of a rule is the prohibition:`);
+        console.log(`  rulereceipt rules --forbid <handle> --literal "<the banned command>"`);
+        console.log(`Only a marked clause can ever refuse a command, and only via \`rulereceipt guard\`.`);
+        return;
+    }
     if (opts.clear) {
         console.log(clearOverride(cwd, opts.clear) ? `Removed the correction for ${opts.clear}.` : `No correction stored for ${opts.clear}.`);
         return;
@@ -604,6 +678,9 @@ program
     .description("correct what the classifier treats as a rule. Handles come from `check --show-skipped`.")
     .option("--include <handle>", "treat this item as a real rule and check it from now on")
     .option("--exclude <handle>", "treat this item as documentation and stop reporting it")
+    .option("--handles", "list every rule with its handle, for use with --forbid")
+    .option("--forbid <handle>", "mark which clause of this rule is the prohibition, so the guard may block on it")
+    .option("--literal <text>", "the exact banned command, used with --forbid; must appear in the rule")
     .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")

package/dist/guard.js

@@ -3,7 +3,8 @@ 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 { loadOverrides, ruleFingerprint } from "./overrides.js";
+import { loadOverrides, ruleFingerprint, ratifiedForbids } from "./overrides.js";
+import { commandRunsLiteral } from "./checks/proposedAction.js";
 function readStdin() {
     return new Promise((resolve) => {
         let data = "";
@@ -56,7 +57,52 @@ function structuredBlocks(cwd, event) {
     }));
 }
 /**
- * Literal command bans do NOT block. Measured, then cut.
+ * A command ban blocks only where a person marked the clause.
+ *
+ * The unratified version was measured before shipping and cut: blocking on a
+ * rule's command literals refused 62.8% of 16,336 real tool calls. Two
+ * narrowings reached 2.49% and the residue had no matcher fix — a rule
+ * titled "Feature Validation" refused `npm run build` 112 times, because it
+ * forbids running Playwright unprompted and RECOMMENDS the build command,
+ * which is its only command-shaped literal. Another refused plain
+ * `git status`, its backticks holding both the ban and the alternative.
+ *
+ * Nothing in a rules file marks which backtick is the prohibition. So this
+ * path reads only what someone declared, and yields nothing otherwise. The
+ * declaration is keyed on the rule's content hash and re-checked against the
+ * rule's current text, so a reworded rule loses its mark rather than
+ * carrying a judgement onto words nobody read.
+ *
+ * The important property is what happens by default: an unmarked rule cannot
+ * block, at any confidence, ever. That is the whole difference between this
+ * and the version that refused two thirds of everything.
+ */
+function ratifiedLiteralBlocks(cwd, command) {
+    const overrides = loadOverrides(cwd);
+    const blocks = [];
+    // Read from the RULES, not from the classification. A human mark
+    // supersedes the classifier, including its refusal to classify — and that
+    // refusal is the common case here. "Never use `git push --force`; prefer
+    // `git push --force-with-lease`" goes to judgment via hasMixedPolarity,
+    // for a correct reason: literal matching cannot tell which half owns which
+    // token. A rule naming both the ban and the alternative is the canonical
+    // reason to have someone say which is which, so gating the mark behind the
+    // classifier made the feature unavailable in exactly the case that
+    // motivated it. Shipped that way in 0.1.39 and caught by running it.
+    for (const rule of loadRules(cwd)) {
+        if (overrides.get(ruleFingerprint(rule))?.decision === "notARule")
+            continue;
+        for (const literal of ratifiedForbids(overrides, rule)) {
+            if (!commandRunsLiteral(command, literal))
+                continue;
+            blocks.push({ rule, why: `the command about to run does \`${literal}\`, which this rule forbids (marked by you, not inferred)` });
+            break;
+        }
+    }
+    return blocks;
+}
+/**
+ * Literal command bans do NOT block unless ratified. Measured, then cut.
  *
  * This was the point of the feature and it does not survive its own
  * measurement. Replaying 16,336 real tool calls against every forbidding
@@ -149,7 +195,7 @@ export async function runGuard() {
                 role: "assistant", kind: "tool_use", toolName: "Bash",
                 input: { command: toolInput.command }, timestamp: "",
             };
-            blocks = structuredBlocks(cwd, event);
+            blocks = [...structuredBlocks(cwd, event), ...ratifiedLiteralBlocks(cwd, toolInput.command)];
         }
         else if (tool === "Write" || tool === "Edit" || tool === "NotebookEdit") {
             const event = {

package/dist/overrides.d.ts

@@ -26,6 +26,21 @@ export interface Override {
     decision: Decision;
     /** Stored for humans reading the file, and to explain a stale entry. */
     title: string;
+    /**
+     * The literal(s) a person has marked as the PROHIBITION in this rule.
+     *
+     * A rules file does not say which of its backticks is the thing being
+     * banned. Measured: blocking on all of them refused 62.8% of 16,336 real
+     * tool calls, and the residue after two narrowings still refused
+     * `npm run build` 112 times, because the rule that named it forbids
+     * running Playwright and RECOMMENDS the build command. No matcher fixes
+     * that — the information is not in the text.
+     *
+     * So it is declared, once, and only what is declared can block. Absent
+     * means absent: there is deliberately no fallback to "probably the first
+     * literal", because that fallback is the bug.
+     */
+    forbids?: string[];
 }
 export declare const OVERRIDES_PATH: string;
 /**
@@ -60,3 +75,21 @@ export declare function clearOverride(cwd: string, hash: string): boolean;
  * correction is no longer being applied instead of assuming it still is.
  */
 export declare function staleOverrides(overrides: Map<string, Override>, rules: Rule[]): Override[];
+/**
+ * The prohibition literals a person has declared for this rule, or none.
+ *
+ * Two conditions, both required, and both are refusals to infer:
+ *
+ * 1. The mark is keyed on the rule's CONTENT hash, so rewording the rule
+ *    drops it rather than reattaching a judgement to text nobody read. Same
+ *    reasoning as ruleFingerprint, one field down.
+ *
+ * 2. The literal must still appear in the rule. A mark that survives a
+ *    partial edit and names something the rule no longer mentions would
+ *    block on a phrase with nothing behind it — a gate refusing a command
+ *    for a reason that is no longer written anywhere, which is the worst
+ *    failure available to a gate.
+ *
+ * Returns [] for anything unratified. There is no fallback on purpose.
+ */
+export declare function ratifiedForbids(overrides: Map<string, Override>, rule: Rule): string[];

package/dist/overrides.js

@@ -32,7 +32,15 @@ export function loadOverrides(cwd) {
             return map;
         for (const o of parsed.overrides) {
             if (typeof o?.hash === "string" && (o.decision === "rule" || o.decision === "notARule")) {
-                map.set(o.hash, { hash: o.hash, decision: o.decision, title: String(o.title ?? "") });
+                const forbids = Array.isArray(o.forbids)
+                    ? o.forbids.filter((x) => typeof x === "string" && x.trim().length > 0)
+                    : undefined;
+                map.set(o.hash, {
+                    hash: o.hash,
+                    decision: o.decision,
+                    title: String(o.title ?? ""),
+                    ...(forbids && forbids.length > 0 ? { forbids } : {}),
+                });
             }
         }
     }
@@ -83,3 +91,27 @@ export function staleOverrides(overrides, rules) {
     const live = new Set(rules.map(ruleFingerprint));
     return [...overrides.values()].filter((o) => !live.has(o.hash));
 }
+/**
+ * The prohibition literals a person has declared for this rule, or none.
+ *
+ * Two conditions, both required, and both are refusals to infer:
+ *
+ * 1. The mark is keyed on the rule's CONTENT hash, so rewording the rule
+ *    drops it rather than reattaching a judgement to text nobody read. Same
+ *    reasoning as ruleFingerprint, one field down.
+ *
+ * 2. The literal must still appear in the rule. A mark that survives a
+ *    partial edit and names something the rule no longer mentions would
+ *    block on a phrase with nothing behind it — a gate refusing a command
+ *    for a reason that is no longer written anywhere, which is the worst
+ *    failure available to a gate.
+ *
+ * Returns [] for anything unratified. There is no fallback on purpose.
+ */
+export function ratifiedForbids(overrides, rule) {
+    const entry = overrides.get(ruleFingerprint(rule));
+    if (!entry?.forbids)
+        return [];
+    const body = `${rule.title}\n${rule.text ?? ""}`;
+    return entry.forbids.filter((literal) => body.includes(literal));
+}

package/package.json

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