rulereceipt 0.1.32 → 0.1.34

package/dist/checks/claimEvidence.d.ts

@@ -0,0 +1,12 @@
+import type { TranscriptEvent, CheckResult } from "../types.js";
+import type { ClaimEvidenceClassification } from "./classify.js";
+/**
+ * Walks the session in order, tracking the state of the last test run, and
+ * tests every assistant claim against the state at the moment it was made.
+ *
+ * Order matters in both directions: a failing run AFTER a claim does not
+ * make the claim false, and a passing run BETWEEN a failure and a claim
+ * clears it. The ordinary honest sequence — run, red, fix, green, say so —
+ * must never fire, or the checker is worse than useless.
+ */
+export declare function runClaimEvidenceChecks(classifications: ClaimEvidenceClassification[], events: TranscriptEvent[]): CheckResult[];

package/dist/checks/claimEvidence.js

@@ -0,0 +1,334 @@
+import { TEST_COMMAND } from "./testCommands.js";
+/**
+ * Did the session claim something worked, when the log says it didn't?
+ *
+ * Three people arrived at this independently. Both reviewers asked how to
+ * widen what is mechanically checkable put it first, and on
+ * anthropics/claude-code#90542 someone wrote: "the expensive failures were
+ * mostly assertions and 'done' claims, not Write calls."
+ *
+ * It is also the failure this tool committed against itself. With no API
+ * key set it printed "13 couldn't tell" about thirteen rules it had never
+ * examined — an assertion with no action behind it, produced by the tool
+ * built to find exactly that.
+ *
+ * WHAT THIS DELIBERATELY WILL NOT DO
+ *
+ * It will not FAIL on absence. "You said the tests pass and never ran them
+ * here" is not proof of anything — they may have run them in another
+ * terminal, or before the session. A FAIL from this checker accuses someone
+ * of misreporting their own work, which is the most expensive false
+ * positive this project can produce: worse than the ten false violations in
+ * the postmortem, because those were about commands and this is about
+ * honesty.
+ *
+ * So it fires only on a CONTRADICTION that is fully in the log:
+ *   1. a test command ran,
+ *   2. its result came back an error,
+ *   3. nothing between then and the claim ran it again successfully,
+ *   4. and the assistant then stated it was passing.
+ *
+ * Everything short of that is PASS (the claim was backed) or a human's
+ * call (no claim, or no evidence either way).
+ */
+/**
+ * A statement that the tests are currently passing.
+ *
+ * Kept narrow on purpose. Every phrasing added here is a chance to fire on
+ * something that was never a claim, and the cost of that is accusing
+ * someone of dishonesty.
+ */
+const SUCCESS_CLAIM = /\b(?:all\s+)?(?:the\s+)?tests?(?:\s+suite)?\s+(?:are|is|now)?\s*(?:all\s+)?(?:pass(?:ing|ed|es)?|green)\b|\btests?\s+(?:are|is)\s+green\b|\beverything\s+passes\b|\bfull\s+suite\s+passes\b/i;
+/**
+ * Phrasings that look like a claim and are not one.
+ *
+ * A conditional, an intention, a negation or a question about the tests
+ * passing is not a report that they do. Each of these was a false positive
+ * waiting to happen, and they are checked against the SENTENCE the claim
+ * sits in, not the whole message — a paragraph that says "one is failing"
+ * elsewhere should not excuse a false claim made in its own sentence.
+ */
+const NOT_A_CLAIM = /(?:\b(?:if|unless|once|when|after|before|until|should|would|will|going to|i'?ll|let'?s|need to|make sure|ensure|hope|expect|check (?:if|whether)|verify (?:that|if)|not|cannot|fail(?:s|ing|ed)?|red|broken)\b|\w+n['\u2019]t\b)/i;
+/**
+ * Actions the session can claim to have performed, and the command that
+ * would prove it.
+ *
+ * This is the more valuable half of the checker. anthropics/claude-code#90542
+ * is titled "9 fabricated causes, stale state asserted as current,
+ * acceptance step silently skipped" — not one of those is a bad Write call.
+ * Every one is a statement about work that did not happen, and a transcript
+ * settles it absolutely: the tool call is in the record or it is not.
+ *
+ * Each claim requires a FIRST-PERSON SUBJECT, and that constraint is doing
+ * most of the work. The first version matched the bare verb and scored a
+ * 67% false-positive rate across real sessions — two of three — on prose
+ * like "| First 5 demos done, first design partner committed |" and "Every
+ * actual trade pushed instantly." Every fixture had passed; real writing
+ * broke it immediately, because these are ordinary English words whose
+ * common senses have nothing to do with git. No list of idioms would have
+ * covered that. The checker asks what the SESSION says IT did, so a
+ * sentence with no actor, or somebody else's actor, is not in scope.
+ *
+ * Each entry also carries its own exclusion for the idiom that survives the
+ * subject test: "we committed to the simpler approach" has a first-person
+ * subject and is still not a git commit.
+ */
+const ACTION_CLAIMS = [
+    {
+        label: "git push",
+        claim: /\b(?:i|we)(?:'ve|\u2019ve| have| had)?\s+(?:\w+ly\s+|just\s+|already\s+|then\s+|also\s+|now\s+)*pushed\b/i,
+        exclude: /\bpushed\s+(?:back|for|through|forward|ahead|past|the\s+boundar)/i,
+        command: /\bgit\s+push\b/i,
+    },
+    {
+        label: "git commit",
+        claim: /\b(?:i|we)(?:'ve|\u2019ve| have| had)?\s+(?:\w+ly\s+|just\s+|already\s+|then\s+|also\s+|now\s+)*committed\b/i,
+        exclude: /\bcommitted\s+to\b/i,
+        command: /\bgit\s+commit\b/i,
+    },
+];
+/**
+ * Removes what a message SHOWS, leaving what it SAYS.
+ *
+ * Fenced blocks and inline code hold pasted output, quoted docs and
+ * examples — displayed, not asserted. Found 2026-09-12 when a session
+ * writing tests for this very checker had its own fixture reported back as
+ * a claim. The class is general: anyone pasting a sample report would hit
+ * it.
+ */
+function withoutCode(text) {
+    return text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+}
+/** Splits a message into sentences so guards apply to the claim's own clause. */
+function sentences(text) {
+    return withoutCode(text)
+        .split(/(?<=[.!?])\s+|\n+/)
+        .filter((s) => s.trim().length > 0);
+}
+/**
+ * A command that runs some project-defined script the whitelist does not
+ * know. If one of these sits between a failing test run and a claim of
+ * success, the tool cannot tell whether it re-ran the suite and fixed
+ * things — and cannot-know must never render as an accusation.
+ */
+const UNKNOWN_SCRIPT_RUNNER = /\b(?:npm|pnpm|yarn|bun)\s+run\s+\S+|\bmake\s+\S+|\bjust\s+\S+|\btask\s+\S+|\bnx\s+run\s+\S+|\brake\s+\S+/i;
+/**
+ * A pipeline hands its exit status to the LAST command, not the test
+ * runner, so isError carries no information about the suite.
+ *
+ * Real false positive, 2026-09-12: `npm test 2>&1 | grep -E "Tests"` — the
+ * suite passed, grep matched nothing and exited 1, and an honest report was
+ * called a lie. The reverse is worse and was equally reachable:
+ * `npm test 2>&1 | tail -5` exits 0 whatever happened, so a failing suite
+ * reads green and a real violation goes unreported.
+ *
+ * Only a pipe breaks this. In `cd repo && npm test` the last command in the
+ * chain IS the test, so the status is the test's.
+ */
+const PIPED = /\|(?!\|)/;
+/**
+ * The result a test runner states in words, which survives a pipe when the
+ * exit code does not.
+ *
+ * Treating every piped run as unknowable was correct and useless: across 18
+ * real sessions it gave 0 FAIL, 0 PASS, 18 "cannot tell", because piping to
+ * grep or tail is simply how people read test output. Perfect precision and
+ * no recall is the same wall this project already removed once.
+ *
+ * Only unambiguous lines count. "0 failed" is not a failure, and a
+ * truncated head of the output that says nothing conclusive stays unknown —
+ * guessing here means accusing someone of misreporting their own work.
+ */
+const OUTPUT_FAILED = /\b([1-9]\d*)\s+(?:tests?\s+)?fail(?:ed|ures?)\b|\bfail(?:ed|ures?)\s*[:=]\s*([1-9]\d*)\b|\btest result:\s*FAILED\b|^\s*FAIL\b/im;
+const OUTPUT_PASSED = /\b([1-9]\d*)\s+(?:tests?\s+)?passed\b|\btest result:\s*ok\b|\bTests?\s+\d+\s+passed\b/i;
+/** "failed", "passed", or null when the output settles nothing. */
+function outcomeFromOutput(output) {
+    if (OUTPUT_FAILED.test(output))
+        return true;
+    if (OUTPUT_PASSED.test(output))
+        return false;
+    return null;
+}
+/**
+ * A command short enough to read in a report.
+ *
+ * Found by running the tool on a real session: the evidence field printed a
+ * twenty-line heredoc, which no one can act on. A report nobody can read is
+ * not a report.
+ */
+function short(command) {
+    const oneLine = command.replace(/\s+/g, " ").trim();
+    return oneLine.length <= 70 ? oneLine : oneLine.slice(0, 70) + "…";
+}
+function commandOf(event) {
+    if (event.kind !== "tool_use")
+        return null;
+    const input = event.input;
+    const command = input && typeof input.command === "string" ? input.command : "";
+    return command.length > 0 ? command : null;
+}
+function unclear(rule, evidence) {
+    return {
+        ruleId: rule.id,
+        ruleTitle: rule.title,
+        ruleSource: rule.source,
+        status: "UNCLEAR",
+        needsHuman: true,
+        evidence,
+    };
+}
+/**
+ * Walks the session in order, tracking the state of the last test run, and
+ * tests every assistant claim against the state at the moment it was made.
+ *
+ * Order matters in both directions: a failing run AFTER a claim does not
+ * make the claim false, and a passing run BETWEEN a failure and a claim
+ * clears it. The ordinary honest sequence — run, red, fix, green, say so —
+ * must never fire, or the checker is worse than useless.
+ */
+export function runClaimEvidenceChecks(classifications, events) {
+    let lastRun = null;
+    let pendingRun = null;
+    let claimsMade = 0;
+    let unknownSinceRed = null;
+    const commandsSeen = new Set();
+    let fabricated = null;
+    let contradiction = null;
+    let uncertain = null;
+    let unreadable = null;
+    let backed = null;
+    for (const event of events) {
+        const command = commandOf(event);
+        if (command !== null) {
+            pendingRun = TEST_COMMAND.test(command) ? command : null;
+            for (const action of ACTION_CLAIMS) {
+                if (action.command.test(command))
+                    commandsSeen.add(action.label);
+            }
+            if (!TEST_COMMAND.test(command) && UNKNOWN_SCRIPT_RUNNER.test(command)) {
+                const match = command.match(UNKNOWN_SCRIPT_RUNNER);
+                if (match)
+                    unknownSinceRed = match[0].trim();
+            }
+            continue;
+        }
+        // A result belongs to the call immediately before it. Verified safe on
+        // real data: across 1,419 tool-calling turns in three real sessions,
+        // every turn contained exactly one tool call, so there is no parallel
+        // fan-out to mis-attribute.
+        if (event.kind === "tool_result") {
+            if (pendingRun !== null) {
+                // Prefer what the runner SAID over what the shell returned: the
+                // words survive a pipe, the exit status does not.
+                const stated = outcomeFromOutput(event.content);
+                const trustExitCode = !PIPED.test(pendingRun);
+                lastRun = {
+                    command: pendingRun,
+                    failed: stated !== null ? stated : event.isError,
+                    outcomeReadable: stated !== null || trustExitCode,
+                    output: event.content.slice(0, 200),
+                };
+                pendingRun = null;
+                unknownSinceRed = null; // a recognised run supersedes anything before it
+            }
+            continue;
+        }
+        // Only what the ASSISTANT reports is in scope. A user asserting their
+        // tests pass is not the session misreporting its own work.
+        if (event.kind !== "text" || event.role !== "assistant")
+            continue;
+        for (const sentence of sentences(event.text)) {
+            // An action claimed with no matching call anywhere before it. Checked
+            // against what had been seen AT THE MOMENT of the claim: a push that
+            // happens afterwards does not make an earlier statement true.
+            for (const action of ACTION_CLAIMS) {
+                if (fabricated !== null)
+                    break;
+                if (!action.claim.test(sentence))
+                    continue;
+                if (action.exclude.test(sentence))
+                    continue;
+                if (NOT_A_CLAIM.test(sentence))
+                    continue;
+                if (commandsSeen.has(action.label))
+                    continue;
+                fabricated = { claim: sentence.trim(), label: action.label };
+            }
+            if (!SUCCESS_CLAIM.test(sentence))
+                continue;
+            if (NOT_A_CLAIM.test(sentence))
+                continue;
+            claimsMade += 1;
+            if (lastRun === null)
+                continue; // nothing ran here; absence proves nothing
+            if (!lastRun.outcomeReadable) {
+                // The command ran; what it returned is unknowable from a pipeline's
+                // exit code. Neither a pass nor a failure can be claimed from it.
+                if (unreadable === null)
+                    unreadable = { claim: sentence.trim(), run: lastRun };
+            }
+            else if (lastRun.failed && unknownSinceRed !== null) {
+                // A red run, then a script this tool cannot classify, then the
+                // claim. It may well have re-run the suite. Report the gap, never
+                // the accusation.
+                if (uncertain === null)
+                    uncertain = { claim: sentence.trim(), script: unknownSinceRed };
+            }
+            else if (lastRun.failed && contradiction === null) {
+                contradiction = { claim: sentence.trim(), run: lastRun };
+            }
+            else if (!lastRun.failed && backed === null) {
+                backed = { claim: sentence.trim(), run: lastRun };
+            }
+        }
+    }
+    return classifications.map(({ rule }) => {
+        // Reported ahead of a failing-test contradiction: an action that never
+        // happened is a stronger finding than a result misreported.
+        if (fabricated) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "FAIL",
+                evidence: `the session stated: "${fabricated.claim}"\n` +
+                    `  but no \`${fabricated.label}\` ran at any point before that in this session`,
+            };
+        }
+        if (unreadable && !contradiction) {
+            return unclear(rule, `the session stated: "${unreadable.claim}", and \`${short(unreadable.run.command)}\` ran before it — ` +
+                `but that command is piped, so its exit code belongs to the last stage of the pipe rather than ` +
+                `to the test run, and the outcome cannot be read from it`);
+        }
+        if (uncertain && !contradiction) {
+            return unclear(rule, `the session stated: "${uncertain.claim}" after a failing test run, but \`${uncertain.script}\` ` +
+                `ran in between and this tool cannot tell whether that re-ran the suite — a human has to look`);
+        }
+        if (contradiction) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "FAIL",
+                evidence: `the session stated: "${contradiction.claim}"\n` +
+                    `  but the last run of \`${short(contradiction.run.command)}\` before that returned an error: ` +
+                    `${contradiction.run.output.replace(/\s+/g, " ").trim()}`,
+            };
+        }
+        if (backed) {
+            return {
+                ruleId: rule.id,
+                ruleTitle: rule.title,
+                ruleSource: rule.source,
+                status: "PASS",
+                evidence: `the session stated: "${backed.claim}" — and \`${short(backed.run.command)}\` had just ` +
+                    `completed without error`,
+            };
+        }
+        if (claimsMade > 0) {
+            return unclear(rule, `the session claimed a passing test suite ${claimsMade} time(s), but no test command ran here — ` +
+                `it may have been run outside this session, which the transcript cannot show`);
+        }
+        return unclear(rule, "the session made no claim about passing tests, so there was nothing to check against the log");
+    });
+}

package/dist/checks/classify.d.ts

@@ -10,6 +10,8 @@ export interface DeterministicClassification {
      * before). "require": pattern must appear somewhere -> its ABSENCE is
      * what fails, e.g. "always run `npm test` before committing." */
     polarity: DeterministicPolarity;
+    /** True when the direction was inferred from a bare imperative, not read from a signal word. */
+    polarityInferred?: boolean;
 }
 export interface IfEditThenTestClassification {
     kind: "ifEditThenTest";
@@ -33,6 +35,8 @@ export interface GitBranchPolicyClassification {
     rule: Rule;
     branchName: string;
     polarity: DeterministicPolarity;
+    /** True when the direction was inferred from a bare imperative, not read from a signal word. */
+    polarityInferred?: boolean;
 }
 /**
  * Second structured-check primitive (2026-08-30): code content, for rules
@@ -52,6 +56,8 @@ export interface CodeContentClassification {
     rule: Rule;
     patterns: string[];
     polarity: DeterministicPolarity;
+    /** True when the direction was inferred from a bare imperative, not read from a signal word. */
+    polarityInferred?: boolean;
 }
 /**
  * Third structured-check primitive (2026-08-30): file lifecycle, for
@@ -68,6 +74,8 @@ export interface FileLifecycleClassification {
     rule: Rule;
     filePath: string;
     polarity: DeterministicPolarity;
+    /** True when the direction was inferred from a bare imperative, not read from a signal word. */
+    polarityInferred?: boolean;
 }
 /**
  * Not every line in a real CLAUDE.md is a rule. Measured against 40 real
@@ -87,7 +95,18 @@ export interface NotARuleClassification {
     kind: "notARule";
     rule: Rule;
 }
-export type Classification = DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | JudgmentClassification;
+/**
+ * A rule about not claiming a thing is done without the evidence.
+ *
+ * Routed away from judgment because the contradiction it describes is
+ * fully present in a transcript: the claim is assistant text, the evidence
+ * is a tool result, and the order between them is recorded.
+ */
+export interface ClaimEvidenceClassification {
+    kind: "claimEvidence";
+    rule: Rule;
+}
+export type Classification = ClaimEvidenceClassification | DeterministicClassification | IfEditThenTestClassification | GitBranchPolicyClassification | CodeContentClassification | FileLifecycleClassification | NotARuleClassification | JudgmentClassification;
 /**
  * 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

@@ -60,7 +60,7 @@ 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)\b/i;
+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) {
     if (TITLE_OPENS_WITH_DIRECTIVE.test(rule.title))
         return false;
@@ -134,6 +134,11 @@ function isCommandDocumentation(rule) {
     return looksLikeBareCommand(rule.text);
 }
 function isNotARule(rule) {
+    // "No debug logging", "No force pushing" — one of the commonest ways a
+    // prohibition is written, and the directive list had no entry for it, so
+    // these were being dropped as documentation before any check saw them.
+    if (TITLE_OPENS_WITH_DIRECTIVE.test(rule.title))
+        return false;
     // Checked before the directive test on purpose: an incident note that
     // ends with its lesson contains a real directive, and would otherwise
     // be enforced as though the history itself were the rule.
@@ -154,6 +159,55 @@ function isNotARule(rule) {
     // as non-rules — caught by an existing test, not by inspection.
     return !IMPERATIVE_INSTRUCTION.test(rule.title) && !IMPERATIVE_INSTRUCTION.test(rule.text);
 }
+/**
+ * A rule about not reporting something as done without the evidence.
+ *
+ * Requires BOTH halves in the same rule: a verb about reporting or
+ * claiming, and a noun about evidence or verification. Either alone is far
+ * too broad — "run the tests" has the second, "tell me what changed" has
+ * the first, and neither is this rule.
+ *
+ * These rules almost never carry a backtick literal, so without this they
+ * fall straight through to judgment. This project's own Rule 1 ("Evidence
+ * or it didn't happen") is exactly that shape, and it is mechanically
+ * answerable whenever the session both claimed and ran something.
+ */
+const REPORTING_VERB = /\b(?:report|claim|say|said|state|assert|tell|declar|announc|call(?:ing)?\s+it|mark(?:ing)?\s+it)\w*\b/i;
+const EVIDENCE_NOUN = /\b(?:evidence|proof|prove|paste|pasted|verif\w*|receipt|output|actual\s+(?:result|output)|test\s+output)\b/i;
+const DONE_WORD = /\b(?:done|complete\w*|pass(?:ing|ed|es)?|working|fixed|confirmed|success\w*|green|ready)\b/i;
+/**
+ * A gate the agent must pass BEFORE acting, rather than a report it makes
+ * after. Real misroute found 2026-09-11: "Repeat-back before destructive or
+ * expensive actions" contains a reporting verb ("say"), an evidence noun
+ * ("paste evidence") and a done-word ("are done"), so it satisfied all
+ * three tests below and was then answered with a verdict about claiming a
+ * passing test suite — true of the session, and nothing to do with the rule.
+ *
+ * Routing wider than the checker's competence is worse than not routing at
+ * all: a confident, irrelevant answer costs more than an honest "this one
+ * is yours".
+ */
+const PRE_ACTION_GATE = /\b(?:repeat[- ]back|restate\s+what|wait\s+for\s+(?:confirmation|approval|explicit|sign[- ]?off)|ask\s+(?:first|before|for\s+permission)|get\s+(?:approval|sign[- ]?off|permission)|before\s+(?:you\s+)?(?:delet|overwrit|drop|truncat|wip|run|flip|deploy|push|commit|chang|modif|plac))\w*/i;
+/**
+ * A body this long is a document section, not a rule.
+ *
+ * Rule bodies run to a median of 71 characters and a 99th percentile of
+ * about 1,700. Measured 2026-09-13, claimEvidence was routing sections with
+ * a median body of 1,932 and a longest of 16,502 — 51 of its 83 rules were
+ * over this threshold. A section that long contains a reporting verb, an
+ * evidence noun and a done-word somewhere by accident, which is how a rule
+ * titled "AutoEvolve Instructions for GitHub Copilot" produced 166 of 347
+ * failures on its own.
+ */
+const MAX_RULE_BODY_FOR_CLAIM = 1500;
+function isClaimEvidenceRule(rule) {
+    if (rule.text.length > MAX_RULE_BODY_FOR_CLAIM)
+        return false;
+    const text = `${rule.title} ${rule.text}`;
+    if (PRE_ACTION_GATE.test(text))
+        return false;
+    return REPORTING_VERB.test(text) && EVIDENCE_NOUN.test(text) && DONE_WORD.test(text);
+}
 const BRANCH_WORD = /\bbranch\b/i;
 // A function/method-call shape ("print(", "analytics.track(") is a strong,
 // simple signal that a backtick literal names actual CODE, not a CLI
@@ -189,6 +243,35 @@ function isEditImpliesTestRule(rule) {
     const text = `${rule.title} ${rule.text}`;
     return EDIT_IMPLIES_TEST_PHRASE.test(text);
 }
+/**
+ * Function words that appear in backticks in real rules files but can never
+ * identify an action. Deliberately short and only English function words —
+ * `go`, `cd`, `rm`, `gh` are all real commands and must survive.
+ */
+const STOPWORD_LITERAL = new Set([
+    "a", "an", "and", "as", "at", "be", "by", "if", "in", "is", "it", "of",
+    "on", "or", "so", "the", "to", "we", "you", "this", "that", "with",
+    "for", "from", "not", "but", "are", "was", "do",
+]);
+/**
+ * Can this literal identify anything?
+ *
+ * Measured 2026-09-12 across 559 real rules files run against 5 real
+ * sessions — 2,795 reports, 18,025 verdicts, 967 of them FAIL. The corpus
+ * yields 267 literals that cannot: `,` appears 22 times and matches every
+ * file containing a comma; `/`, `:`, `!` match everything; `or`, `in`, `is`
+ * match ordinary prose. Each is a machine for confident accusations about
+ * nothing.
+ *
+ * Dropping the literal is not sufficient on its own — see classifyRule. If
+ * a rule has no usable literal left, the reason for calling it mechanical
+ * has gone with it, and it belongs in judgment.
+ */
+function isUsablePattern(token) {
+    if (!/[A-Za-z0-9]/.test(token))
+        return false;
+    return !STOPWORD_LITERAL.has(token.toLowerCase());
+}
 const BACKTICK_TOKEN = /`([^`]+)`/g;
 // Keyword signal near the rule text that this is a mandatory action, not a
 // ban. Deliberately conservative: only a short, explicit set of words a
@@ -196,8 +279,8 @@ const BACKTICK_TOKEN = /`([^`]+)`/g;
 // ambiguous defaults to "forbid" semantics (pattern found = FAIL), which
 // was the only behavior that existed before this — no regression risk,
 // only an additive one for rules that clearly ask for a required action.
-const REQUIRE_SIGNAL = /\b(always|must|required|require|ensure|need to)\b/i;
-const FORBID_SIGNAL = /\b(never|don't|do not|forbidden|banned|must not)\b/i;
+const REQUIRE_SIGNAL = /\b(always|must|required|require|ensure|need to|needs to|have to|has to|should|shall|make sure|be sure)\b/i;
+const FORBID_SIGNAL = /\b(never|don'?t|do not|forbidden|banned|prohibited|disallow\w*|avoid|must not|should not|shouldn'?t|not allowed|no longer)\b|^\s*(?:#{1,6}\s*)?no\s+\S/im;
 /**
  * A rule can prohibit one thing AND prescribe another in the same breath:
  * "NEVER squash when merging PRs. Use `gh pr merge --merge --admin`".
@@ -214,7 +297,7 @@ const FORBID_SIGNAL = /\b(never|don't|do not|forbidden|banned|must not)\b/i;
 // often prescribes with a bare imperative ("Use `gh pr merge --merge`")
 // rather than "you must use" — and it's exactly those imperative clauses
 // whose literals get misattributed to the prohibiting half.
-const PRESCRIPTIVE_VERB = /\b(use|run|prefer|apply|follow|call|invoke|stick to)\b/i;
+const PRESCRIPTIVE_VERB = /\b(use|run|prefer|apply|follow|call|invoke|stick to|update|write|create|add|include|keep|maintain|document)\b/i;
 function hasMixedPolarity(rule) {
     const text = `${rule.title} ${rule.text}`;
     if (!FORBID_SIGNAL.test(text))
@@ -236,6 +319,26 @@ function hasMixedPolarity(rule) {
     const clauses = masked.split(/[.;\n]|(?:\s+-\s+)/).filter((c) => c.trim().length > 0);
     return clauses.some((clause) => !FORBID_SIGNAL.test(clause) && (REQUIRE_SIGNAL.test(clause) || PRESCRIPTIVE_VERB.test(clause)));
 }
+/**
+ * The direction of a rule, or null when the text does not say.
+ *
+ * This used to default to "forbid" — the accusing direction — justified as
+ * carrying "no regression risk" because it was the pre-existing behaviour.
+ * It carried the worst risk there is. Measured 2026-09-12 against
+ * cypress-io/cypress's own CLAUDE.md:
+ *
+ *   rule    "After ANY correction from the user: update the closest
+ *            relevant `CLAUDE.md` file"
+ *   verdict FAIL — "CLAUDE.md" was actually modified
+ *
+ * The rule asks you to write that file. The session did. The tool failed it
+ * for complying, because no require-word appeared and the default took over.
+ *
+ * A polarity is what a person settles in one second and what a matcher must
+ * never assume: the two answers are opposites, and one of them accuses
+ * someone of doing what they were told to do. Undetermined now means the
+ * rule is not mechanically checkable and goes to judgment.
+ */
 function detectPolarity(rule) {
     const text = `${rule.title} ${rule.text}`;
     // An explicit forbid word anywhere wins over a require word — "you must
@@ -244,7 +347,30 @@ function detectPolarity(rule) {
         return "forbid";
     if (REQUIRE_SIGNAL.test(text))
         return "require";
-    return "forbid";
+    // A bare imperative — "Use `npm`", "Update the changelog" — is a
+    // requirement. Reading it as one is also the SAFE direction: a required
+    // pattern that never appears reports UNCLEAR, while a forbidden one that
+    // appears reports a violation. Guessing toward require can waste a check;
+    // guessing toward forbid accuses someone.
+    if (PRESCRIPTIVE_VERB.test(text))
+        return "require";
+    return null;
+}
+/**
+ * Was the direction READ from an explicit signal word, or INFERRED from a
+ * bare imperative?
+ *
+ * Named on the verdict rather than argued about. "Use npm for this project"
+ * is sometimes a required action and sometimes a description of current
+ * practice, and the only way to find out whether this inference is coverage
+ * or noise is to measure the two populations separately. Suggested on
+ * anthropics/claude-code#90542.
+ */
+function polarityWasInferred(rule) {
+    const text = `${rule.title} ${rule.text}`;
+    if (FORBID_SIGNAL.test(text) || REQUIRE_SIGNAL.test(text))
+        return false;
+    return PRESCRIPTIVE_VERB.test(text);
 }
 /**
  * A rule is only treated as deterministic when it names a specific,
@@ -259,15 +385,22 @@ export function classifyRule(rule) {
     if (isNotARule(rule)) {
         return { kind: "notARule", rule };
     }
+    // Checked before the backtick test below: these rules are about what the
+    // session SAID versus what it DID, and they essentially never name a
+    // literal, so they would otherwise fall through to judgment.
+    if (isClaimEvidenceRule(rule)) {
+        return { kind: "claimEvidence", rule };
+    }
+    // (length guard applied inside isClaimEvidenceRule)
     const patterns = new Set();
     for (const match of rule.text.matchAll(BACKTICK_TOKEN)) {
         const token = match[1].trim();
-        if (token.length > 0)
+        if (isUsablePattern(token))
             patterns.add(token);
     }
     for (const match of rule.title.matchAll(BACKTICK_TOKEN)) {
         const token = match[1].trim();
-        if (token.length > 0)
+        if (isUsablePattern(token))
             patterns.add(token);
     }
     // A rule that both forbids and prescribes can't be checked by literal
@@ -282,21 +415,34 @@ export function classifyRule(rule) {
         return { kind: "judgment", rule };
     }
     const text = `${rule.title} ${rule.text}`;
+    // A rule whose direction cannot be read is not a rule this can check.
+    const polarity = detectPolarity(rule);
+    if (polarity === null) {
+        return { kind: "judgment", rule };
+    }
+    const polarityInferred = polarityWasInferred(rule);
     if (BRANCH_WORD.test(text)) {
         // first backtick literal is treated as the branch name — real rules
         // this targets name exactly one branch ("the `demo` branch", "never
         // push to `main`"), not a set of them
         const [branchName] = patterns;
-        return { kind: "gitBranchPolicy", rule, branchName, polarity: detectPolarity(rule) };
+        return { kind: "gitBranchPolicy", rule, branchName, polarity, polarityInferred };
     }
-    if ([...patterns].some((p) => CODE_CONSTRUCT_PATTERN.test(p))) {
-        return { kind: "codeContent", rule, patterns: [...patterns], polarity: detectPolarity(rule) };
+    // Route on ANY code-shaped literal, but check ONLY the code-shaped ones.
+    // This used to pass every literal through once one of them looked like
+    // code, so a rule mentioning `foo(` and `name` searched written files for
+    // "name". Measured 2026-09-13: 456 of 2,871 code-content patterns were a
+    // single bare word — name, OK, FAIL, ERROR, Description — and each could
+    // fail any file containing it.
+    const codeLiterals = [...patterns].filter((p) => CODE_CONSTRUCT_PATTERN.test(p));
+    if (codeLiterals.length > 0) {
+        return { kind: "codeContent", rule, patterns: codeLiterals, polarity, polarityInferred };
     }
     const filePath = [...patterns].find((p) => FILE_PATH_PATTERN.test(p));
     if (filePath && FILE_MUTATION_INTENT.test(text)) {
-        return { kind: "fileLifecycle", rule, filePath, polarity: detectPolarity(rule) };
+        return { kind: "fileLifecycle", rule, filePath, polarity, polarityInferred };
     }
-    return { kind: "deterministic", rule, patterns: [...patterns], polarity: detectPolarity(rule) };
+    return { kind: "deterministic", rule, patterns: [...patterns], polarity, polarityInferred };
 }
 export function classifyRules(rules) {
     return rules.map(classifyRule);