claude-dev-env 1.80.0 → 1.81.0

package/audit-rubrics/category_rubrics/category-a-api-contracts.md

@@ -10,6 +10,7 @@
 - A PowerShell cmdlet is invoked with a parameter that belongs to a different parameter set.
 - A new gate-time validator omits the `all_changed_lines` parameter that peer span-based validators accept, so the dispatcher cannot plumb diff scope through and the check silently over- or under-blocks.
 - A new span-based check applies its result cap before honoring `defer_scope_to_caller=True`, while peer checks return all violations in that mode and let the caller cap; this leaves the new sibling stale against the established pattern.
+- A call passes `PollingIntervals.resume_check` (a poll interval — how often to re-check) into a `progress_check_timeout` parameter (a timeout — how long to wait). The value's role does not match the parameter's role, so the call type-checks while the behavior is wrong.
 
 **Companion reference:** see `../source-material-section-types.md` for guidance on how to chunk the artifact under audit.
 
@@ -23,7 +24,7 @@ The decomposition that worked best for PR #394 (a Python+PowerShell scheduled-ta
 
 | ID | Axis name | Concrete checks |
 |---|---|---|
-| A1 | Python function signatures vs internal call sites | Parameter count, names, defaults, kw-only barriers; every internal call binds correctly. Is the symbol `async def`? Confirm the exact access path a caller uses: free function vs instance method reached through an object attribute vs import path. A keyword-only parameter with no default is required; omitting it raises `TypeError`. |
+| A1 | Python function signatures vs internal call sites | Parameter count, names, defaults, kw-only barriers; every internal call binds correctly. Is the symbol `async def`? Confirm the exact access path a caller uses: free function vs instance method reached through an object attribute vs import path. A keyword-only parameter with no default is required; omitting it raises `TypeError`. When a call passes a config value as an argument, confirm the value's documented role matches the parameter's role — a poll interval is not a timeout, and a timeout is not a budget. |
 | A2 | Python return-type annotation vs every code path | Each function's return annotation is satisfied by every path: explicit `return X`, fall-through, exception-handler exit. The full failure contract is the return value AND every exception raised — trace the body and the docstring `Raises:` for each `raise`, including custom errors. A `-> bool` function that also raises is not fully described by "returns bool". |
 | A3 | argparse parser → Namespace contract | Every `add_argument(...)` produces the exact dest name accessed downstream; `type=` matches downstream usage; switches produce bools. |
 | A4 | Stdlib callback contracts | `os.walk(onerror=...)` callback shape; `os.path.getctime` / `os.rmdir` argument and exception contracts; `time.sleep` argument types. Catch-site precision: for any claim that code "catches X", confirm the exact catch site and scope — an `except` around only a rollback inside `finally` does not catch the same error raised in the `with` body. |

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -30,7 +30,19 @@
 | J11 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (test files exempt). |
 | J12 | Hardcoded user paths | String literals naming a specific user's home directory (`C:/Users/jon/...`, `/Users/alice/...`, `/home/bob/...`). Use `pathlib.Path.home()`. |
 
-Test files (`test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, paths under `/tests/`) are exempt from Category J except where the rule explicitly applies (e.g., J11 on `sys.path.insert`).
+The write-time hook (`code_rules_enforcer.py`) exempts test files (`test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, paths under `/tests/`) from most Category J sub-buckets, and skips the naming, logging, annotation, and unused-import rules on `.mjs` / `.js` files. J11 (`sys.path.insert`) always applies. Read the next section for the sub-buckets this audit applies more widely than the hook.
+
+## Write-time exemptions do not scope this audit
+
+The write-time hook skips several rules on test files and on `.mjs` / `.js` files. This audit does not. Apply these rules to every changed line — production files, test files, and JavaScript files alike:
+
+- **Naming (J5, J6)** — banned identifiers (`ctx`, `cfg`, `msg`, `result`, `data`, `output`, `value`, `item`, `temp`, `elem`, `val`, …) and banned function prefixes (`handle_`, `process_`, `manage_`, `do_`); boolean names prefixed `is_` / `has_` / `should_` / `can_` / `was_` / `did_`.
+- **Logging format (J9)** — the format string and its arguments pass as separate parameters (`log_*("...", arg)`), never an f-string.
+- **Type annotations (J7)** — every changed function parameter and return is typed; no `Any`, no bare `# type: ignore`.
+- **Unused imports** — a module-level import a changed file does not read is a finding.
+- **Function length** — a changed function that runs past the length threshold splits into named helpers.
+
+A `test_*.py` name or a `.mjs` extension takes the line out of the write-time gate, not out of this audit. When the diff touches a test or a JavaScript file, walk these five rules against the changed lines there too. J1 (magic values) and J3 (constants location) keep their test-file exemption.
 
 ---
 

package/audit-rubrics/category_rubrics/category-p-name-vs-behavior-contract.md

@@ -15,6 +15,25 @@ The label-vs-body gap is its own failure mode independent of behavior-equivalenc
 
 ---
 
+## Binding counterexample protocol
+
+For every regex, brace or token scanner, or word-list the diff adds or edits, build at least three concrete inputs and trace each one through the pattern by hand before you call the pattern clean:
+
+- **One intended match** — an input the pattern must catch.
+- **One near-miss** — an input a quick reading would expect to catch, but the contract says the pattern must reject.
+- **One structural edge** — an input whose shape stresses the scanner: a destructured parameter, a quoted key, a nested brace, an escaped delimiter.
+
+Walk each input character by character (or token by token) and write down what the pattern returns. A pattern that returns the wrong answer on any of the three inputs is a Category P finding; cite the input that breaks it. The pattern is clean only after all three inputs return the answer the contract promises.
+
+`hooks/blocking/` is the priority surface. Its patterns gate every write, so a pattern that matches too much or too little there fires on real edits across the whole codebase.
+
+Two canonical failures show why the hand trace is binding:
+
+- **Brace scan that reads a parameter as body.** A scanner counts braces from the signature's opening `(` and treats the first balanced close as the end of the function body. A destructured parameter closes a brace inside the signature — `renderRow({ id, label })` in JavaScript, or a `{a, b}` binding in another language — so the scanner marks the body one token too early and reads the parameter list as body code.
+- **`\bschema\b` that matches a value reference.** A `\bschema\b` pattern targets a `schema` declaration, yet it also matches `schema` as the value in `{ label: schema }`, where the word is a reference, not the declaration the pattern means to find. A word boundary alone does not tell a declaration from a key or a value.
+
+---
+
 ## Sub-bucket decomposition (Category P)
 
 Decomposition is by the **kind of identifier / reference data** whose label is being audited against its body.

package/audit-rubrics/category_rubrics/category-q-cross-surface-claims.md

@@ -0,0 +1,46 @@
+# Category Q — Cross-surface claim consistency (terminology, PR-description claims, message-vs-guard)
+
+**What this category audits:** claims a change makes on one surface that a second surface contradicts. A code field carries one spelling while the prose that names it uses a near-miss variant. A PR description states a fact that the diff or the repo does not bear out. A log or error string asserts a condition that the branch gating it does not guarantee. Each defect lives in the gap between two surfaces that must agree: the code and the prose about it, the PR body and the diff, the message text and the guard that fires it.
+
+**Why this category is its own bucket:** each surface reads as correct on its own. The code field is a valid identifier. The PR sentence is a well-formed claim. The log line is grammatical. The defect surfaces only when a reader holds two surfaces side by side and finds that one says a thing the other denies. Categories that read a single surface miss this; Q forces the reader to pair every claim with the surface that must back it.
+
+## Canonical examples
+
+- **PR #810 (Q1).** Eleven prose surfaces name the term one way while the code field reads `premium_interactions`. One divergent term spreads across README text, doc tables, and inline prose, so a reader who trusts any of the eleven surfaces reaches for a field name the code does not define.
+- **PR #808 (Q2).** The PR description claims zero remaining gate subjects while `converge.mjs` still holds them. The body asserts a cleanup the diff does not finish, so a reviewer who trusts the description approves a state the code contradicts.
+- **PR #823 (Q3).** A skip-branch log asserts a hardening PR opened, yet `spawnStandardsFollowUp` can return `hardeningPrOpened: false`. The message states an outcome the guard that reaches it does not guarantee, so the log reads as a success the run did not achieve.
+
+## Other typical patterns
+
+- A config key the diff adds reads `retry_budget`; a doc table row names it `retry-budget`, and a runbook names it `retry budget`.
+- An API field the diff introduces is `itemCount` (singular tail); a client doc calls it `itemCounts`.
+- A PR body says "this removes the last caller of `legacy_resolve`"; a reference search still finds a caller in a sibling module.
+- A PR body claims a 30-second ceiling; the config value the diff sets reads 60 seconds.
+- An error string says "config file is missing" while the branch that raises it fires on a parse failure, not an absent file.
+- A log line says "retry limit reached this run" while the counter it reads resets each round, so the wording overstates the lifetime of the state it names.
+
+**Companion reference:** see `../source-material-section-types.md`.
+
+---
+
+## Sub-bucket decomposition (Category Q)
+
+Decomposition is by the **pair of surfaces** that must agree.
+
+| ID | Axis name | Concrete checks |
+|---|---|---|
+| Q1 | Term sweep | Pull out every identifier, API field, and config key the diff introduces or reads. Sweep all changed prose surfaces for near-miss variants — hyphen or space in place of an underscore, singular where the code is plural (or the reverse), a shared prefix with a divergent tail. Run `packages/claude-dev-env/_shared/pr-loop/scripts/terminology_sweep.py` for mechanical recall — it reads a unified diff on stdin or via `--diff-file`, prints one `file:line` finding per near-miss, exits 1 when findings exist and 0 when clean — then adjudicate each finding, since a near-miss can be an intentional distinct term. |
+| Q2 | PR-description claim verification | Fetch the PR body. For each falsifiable claim, verify it two ways against the diff and the repo. A dead-code claim ("removes the last caller of X") gets a reference search across the repo. A performance or ceiling claim ("caps at 30 seconds", "cuts calls in half") gets checked against the actual config values and call sites the diff sets. |
+| Q3 | Message-vs-guard consistency | For every log, error, and evidence string the diff adds or edits, read the condition that gates it. The message text matches what the guard guarantees — a string that asserts an outcome fires only on a branch that reaches that outcome. Temporal wording matches the lifetime of the state variable it names: "this run" versus "this round", "is open" versus "was opened", "reached" versus "attempted". |
+
+Customize per-artifact: a change that adds no new identifier and no PR-body claim reduces Q to "verify every message the diff touches still matches its guard." A rename that spreads a term across many docs may need Q1 alone to list every prose surface.
+
+---
+
+## Sample prompt
+
+The reusable template for Category Q is in [`../prompts/category-q-cross-surface-claims.md`](../prompts/category-q-cross-surface-claims.md). The Category Q source-material block needs the diff, the PR body text, and the changed prose surfaces the agent must cross-reference against the code.
+
+## Why Category Q matters as its own bucket
+
+A reviewer walking a single surface at a time — the code alone, the docs alone, the PR body alone — judges each on its own merits and misses Q. The code field is a valid name; the PR sentence is a plausible claim; the log line is grammatical. Only pairing each claim with the surface that must back it surfaces the gap. Q forces that pairing: every identifier the diff touches is swept against the prose, every PR-body claim is checked against the diff and the repo, and every message is read against the guard that fires it.

package/audit-rubrics/prompts/CLAUDE.md

@@ -1,6 +1,6 @@
 # audit-rubrics/prompts
 
-Agent-ready audit prompt templates, one per category (A–P). An agent inlines the artifact under review into the `[INLINE THE FULL ARTIFACT HERE]` placeholder and runs the prompt as-is.
+Agent-ready audit prompt templates, one per category (A–Q). An agent inlines the artifact under review into the `[INLINE THE FULL ARTIFACT HERE]` placeholder and runs the prompt as-is.
 
 ## Files
 
@@ -22,6 +22,7 @@ Agent-ready audit prompt templates, one per category (A–P). An agent inlines t
 | `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
 | `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
 | `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
+| `category-q-cross-surface-claims.md` | Q — Cross-surface claim consistency |
 
 ## Prompt structure
 

package/audit-rubrics/prompts/category-a-api-contracts.md

@@ -16,6 +16,7 @@ ID prefix: `find`.
 - Flag calls that omit a required parameter relying on a default that does not exist on the current branch.
 - Verify decorators (`@staticmethod`, `@classmethod`, `@property`) do not silently shift the parameter binding (e.g., `self` / `cls` insertion).
 - Confirm sync-vs-async (is the symbol `async def`?), the exact access path a caller uses (free function vs instance method via an object attribute vs import path), and that a keyword-only parameter with no default is required — omitting it raises `TypeError`.
+- When a call passes a config value as an argument, confirm the value's documented role matches the parameter's role (poll interval vs timeout vs budget). A poll interval such as `PollingIntervals.resume_check` handed to a `progress_check_timeout` parameter type-checks but carries the wrong meaning.
 
 **A2. Return-type annotation vs every code path**
 - For each annotated function, walk every code path: explicit `return X`, fall-through to implicit `None`, exception-handler exit, generator `yield` paths, async coroutine return value.

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -11,10 +11,22 @@ ID prefix: `find`.
 
 ## Source material
 
-Inline the artifact (full diff or full file contents) under a clearly delimited block below this section. Use the chunking guide in [`../source-material-section-types.md`](../source-material-section-types.md) to choose the right Source-material section type (full-diff, file-set, patch-series, or excerpt-with-context). Mark every line range that is in scope; mark explicitly which files are test files (exempt) and which are production.
+Inline the artifact (full diff or full file contents) under a clearly delimited block below this section. Use the chunking guide in [`../source-material-section-types.md`](../source-material-section-types.md) to choose the right Source-material section type (full-diff, file-set, patch-series, or excerpt-with-context). Mark every line range that is in scope; mark explicitly which files are test files and which are production.
 
 Replace this paragraph with the chunked source material before issuing the prompt.
 
+## Write-time exemptions do not scope this audit
+
+The write-time hook skips several rules on test files and on `.mjs` / `.js` files; this audit does not. Apply these rules to every changed line — production, test, and JavaScript files alike:
+
+- Naming (J5, J6) — banned identifiers and banned function prefixes; boolean names prefixed `is_` / `has_` / `should_` / `can_` / `was_` / `did_`.
+- Logging format (J9) — the format string and its arguments pass as separate parameters, never an f-string.
+- Type annotations (J7) — every changed parameter and return is typed; no `Any`, no bare `# type: ignore`.
+- Unused imports — a module-level import a changed file does not read.
+- Function length — a changed function past the length threshold splits into named helpers.
+
+A `test_*.py` name or a `.mjs` extension takes the line out of the write-time gate, not out of this audit. J1 (magic values) and J3 (constants location) keep their test-file exemption; the five rules above do not.
+
 ## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
 
 **J1. Magic values in production function bodies**
@@ -40,18 +52,18 @@ Replace this paragraph with the chunked source material before issuing the promp
 - Adversarial probes: (a) is any imported constant referenced only once in the importing file (suggesting the import itself is gratuitous)? (b) is any helper function defined in a production file but never called from inside the same file (separate dead-code concern, surfaced here for completeness)? (c) does any constant in `config/` get imported from zero call sites across the repo?
 
 **J5. Abbreviations**
-- Walk every parameter, local, and attribute name in production code. Flag: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.
-- Test files are exempt.
+- Walk every parameter, local, and attribute name across production, test, and JavaScript changed lines. Flag: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) is there a borderline name (e.g., `removed`, `arguments`) that someone might mis-classify as an abbreviation but is actually a full English word? Confirm. (b) does any callback / parameter / attribute use a short variant of a domain term that is technically a full word but conventionally abbreviates a longer one? (c) does any variable in a comprehension or lambda use a single letter outside the `i`/`j`/`k`/`e` exemption?
 
 **J6. Vague names**
 - Flag any name from the vague list: `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague verb prefixes for function names: `handle`, `process`, `manage`, `do`.
-- Test files are exempt.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) does any local variable use a domain-adjacent name that is actually on the vague list (e.g., `result` from a parser, `data` from a fetch)? (b) does any newly-introduced function name start with a vague prefix? (c) does any public attribute / dict key use a vague label that the call site has to disambiguate by surrounding context?
 
 **J7. Type hints**
-- Walk every function in production files. Verify parameter and return types are present, no `Any`, no `# type: ignore`.
-- Test files are exempt.
+- Walk every function across production, test, and JavaScript changed lines. Verify parameter and return types are present, no `Any`, no `# type: ignore`.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) does any production function rely on inferred return type from a single `return` path? (b) does any parameter use a string-quoted forward reference that masks `Any`? (c) is there a `# type: ignore` anywhere? Grep the diff explicitly.
 
 **J8. New inline comments**
@@ -64,7 +76,7 @@ Replace this paragraph with the chunked source material before issuing the promp
 **J9. Logging format**
 - Walk every `log_*(...)` call. Must be `log_*("template with {}", arg)`, not `log_*(f"...")`.
 - The rule applies to the project's structured `log_*` family, not stdlib `print`. `print` f-strings are J2-scope (string-template magic), not J9-scope.
-- Test files are exempt.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) is there any imported `log_*` function in production code that uses an f-string? (b) is there a logger-equivalent call (e.g., `logger.info(f"...")` from `logging` stdlib) that should be subject to the same rule? (c) does any non-Python logger family (e.g., `console.log`, `Write-Host`, structured-log helpers) appear with a template-string pattern that mirrors the J9 anti-pattern?
 
 **J10. Imports inside functions**

package/audit-rubrics/prompts/category-p-name-vs-behavior-contract.md

@@ -19,6 +19,20 @@ ID prefix: `find`.
 
 [INLINE each fresh identifier in context — the constant declaration with the value, the function signature with the body, the flag with every assignment / reset site, the regex source with surrounding usage.]
 
+## Binding counterexample protocol (run before every Shape B "clean" verdict)
+
+For every regex, brace or token scanner, or word-list the diff adds or edits, build at least three concrete inputs and trace each one through the pattern by hand:
+
+- One intended match the pattern must catch.
+- One near-miss the pattern must reject (hyphen vs underscore, a value reference vs a declaration, a substring of a longer word).
+- One structural edge that stresses the scanner: a destructured parameter, a quoted key, a nested brace, an escaped delimiter.
+
+Record what the pattern returns for each input. A wrong answer on any input is a Shape A finding, cited with the breaking input; a clean verdict is earned only after all three inputs return the contract's answer. `hooks/blocking/` is the priority surface — its patterns gate every write.
+
+Two canonical failures to probe for:
+- A brace scan that counts from the signature `(` and reads a destructured parameter (`renderRow({ id, label })`) as the start of the function body.
+- A `\bschema\b` pattern that matches the value in `{ label: schema }`, not just the `schema` declaration it targets.
+
 ## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
 
 **P1. Boolean / flag names assert state the body keeps**

package/audit-rubrics/prompts/category-q-cross-surface-claims.md

@@ -0,0 +1,51 @@
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category Q only** (cross-surface claim consistency — terminology, PR-description claims, message-vs-guard). Skip A–P. Sub-bucket forced-exhaustion mode: Category Q is decomposed into 3 sub-buckets below. Each sub-bucket needs at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
+
+[ARTIFACT METADATA]
+
+- Title / one-line summary: [TITLE]
+- Base ref / SHA (state before the change): [BASE_SHA]
+- Head ref / SHA at audit time (state after the change): [HEAD_SHA]
+- Changed surfaces (file + line range + symbol/region name): [CHANGED_SURFACES]
+- New or read identifiers, API fields, and config keys the diff touches: [DIFF_TERMS]
+- Changed prose surfaces (README, doc tables, inline prose, log and error strings): [CHANGED_PROSE_SURFACES]
+- PR description body text: [PR_BODY]
+- Stated intent of the change: [INTENT]
+
+ID prefix: `find`.
+
+[ONE-PARAGRAPH FRAME: describe what the diff changed in plain English, naming the identifiers and config keys it introduces, the PR-body claims it makes, and the messages it adds or edits. State the audit goal: find any surface whose wording contradicts another surface that must agree with it — a prose term that misspells a code field, a PR-body claim the diff or repo does not bear out, or a message that asserts more than the guard gating it guarantees.]
+
+## Source material ([N] files/sections, all lines in scope)
+
+[INLINE THE FULL DIFF — the changed lines and enough surrounding context to show each identifier's definition and each message's guard.]
+
+[ALSO INLINE the PR description body text and every changed prose surface — README sections, doc tables, runbooks, log and error strings — so the agent can pair each claim with the code it names.]
+
+## Sub-buckets (each needs a Shape A finding OR Shape B with ≥3 adversarial probes)
+
+**Q1. Term sweep**
+- Pull out every identifier, API field, and config key the diff introduces or reads. For each, sweep all changed prose surfaces for a near-miss variant — a hyphen or a space in place of an underscore, a singular where the code is plural (or the reverse), a shared prefix with a divergent tail.
+- Run `packages/claude-dev-env/_shared/pr-loop/scripts/terminology_sweep.py` for mechanical recall. It reads a unified diff on stdin or via `--diff-file`, prints one `file:line` finding per near-miss, exits 1 when findings exist and 0 when clean. Feed it the PR diff, then adjudicate each finding: a near-miss can be an intentional distinct term, so cite the code definition and the prose line and judge whether they name the same thing.
+- Adversarial probes when the sweep is clean: (a) check camelCase versus snake_case spellings of the same field across code and docs; (b) check singular/plural drift on collection field names; (c) check a shared-prefix family (`retry_budget`, `retry_count`, `retry_limit`) for a doc that names the wrong member.
+
+**Q2. PR-description claim verification**
+- Read the PR body. List each falsifiable claim — a dead-code removal, a performance or ceiling number, a "last caller" assertion, a "no remaining X" cleanup claim.
+- Verify each claim two ways against the diff and the repo. A dead-code claim gets a reference search across the repo for the named symbol. A ceiling or performance claim gets checked against the actual config value the diff sets and the call sites it touches. Cite the PR-body line and the diff or repo line that confirms or contradicts it.
+- Adversarial probes when the body looks correct: (a) search the repo for a surviving caller of any symbol the body calls dead; (b) compare each stated number against the config constant the diff sets; (c) check whether a "this finishes the cleanup" claim leaves a matching pattern in an unchanged sibling file.
+
+**Q3. Message-vs-guard consistency**
+- For every log, error, and evidence string the diff adds or edits, read the branch condition that gates it. The message text matches what that guard guarantees: a string asserting an outcome fires only on a branch that reaches the outcome.
+- Check temporal wording against the lifetime of the state variable the message names: "this run" versus "this round", "is open" versus "was opened", "reached" versus "attempted". Cite the message line and the guard or state-variable line.
+- Adversarial probes when messages look aligned: (a) trace each success message back to the return value or flag it claims and confirm the branch cannot reach it with the opposite value; (b) check every "missing" / "not found" error against the exception class the branch actually catches; (c) check every counter-based message against where the counter resets.
+
+## Cross-bucket questions to answer at the end
+
+Q-a: Which single claim in this change is most likely to mislead a reader at runtime — a prose term that names a field the code does not define, a PR-body fact the diff contradicts, or a message that overstates its guard? Cite both surfaces by `path:line`.
+
+Q-b: Which surface is the strongest witness to the contradiction — the doc, PR body, or message a reader would trust while the code says otherwise?
+
+Q-c: Is there a term the diff introduces that appears correct in the code yet drifts across two or more prose surfaces at once? Cite each prose line and the code definition.
+
+## Output
+
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket Q1-Q3, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding cites BOTH surfaces — the claim and the surface that contradicts it — by `path:line`. The `failure_mode` describes the contradiction between the two surfaces. Cross-bucket Q-a through Q-c answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 cross-surface contradictions — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.

package/docs/CODE_RULES.md

@@ -23,7 +23,7 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 `code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-no new comments · imports at top · logging format args (`log_*("...", arg)`) · no `%s`/`%d` printf tokens in a `str.format`-logger message (`log_*` imported from `automation_logging`; `str.format` drops the args — use `{}`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost)
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no `%s`/`%d` printf tokens in a `str.format`-logger message (`log_*` imported from `automation_logging`; `str.format` drops the args — use `{}`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost) · JavaScript/TypeScript boolean declarations (`const`/`let`/`var` bound to a boolean literal or negation) and `@param {boolean}` JSDoc names prefixed `is`/`has`/`should`/`can`/`was`/`did` (camelCase forms) · banned identifiers as `.mjs`/`.js` declaration names (`result`, `data`, `ctx`, `msg`, …), scoped to changed lines · in test files, banned identifiers and unused module-level imports fire on changed lines, and pytest-collectable `test_*` functions need a return annotation · a `hooks/blocking/` command classifier anchors its multi-word command regex to the command start (`^`/`\A`) or tokenizes the first word (`shlex.split`), never matching a command as a bare substring
 
 Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 
@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–P) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.

package/hooks/blocking/CLAUDE.md

@@ -23,6 +23,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_annotations_length.py` | Parameter/return annotations, function length, pytest fixture annotation requirements |
 | `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
 | `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
+| `code_rules_command_dispatch.py` | A `hooks/blocking/` command classifier matching a multi-word command regex without a start anchor or first-word tokenization |
 | `code_rules_comments.py` | No new inline comments; no deletion of existing ones |
 | `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
 | `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
@@ -33,6 +34,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
 | `code_rules_duplicate_body.py` | A function body copied from a sibling module, or a helper body inlined as a block inside a larger function in the same file |
 | `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style; printf tokens in `str.format`-logger messages |
+| `code_rules_js_conventions.py` | Boolean-prefix naming and banned identifiers for JavaScript/TypeScript declarations and `@param {boolean}` JSDoc, scoped to changed lines |
 | `code_rules_magic_values.py` | No magic numbers or strings in production code bodies |
 | `code_rules_mock_completeness.py` | Mock calls that skip required arguments |
 | `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |

package/hooks/blocking/code_rules_annotations_length.py

@@ -384,24 +384,72 @@ def check_unused_known_pytest_fixture_parameters(
     return issues
 
 
-def check_return_annotations(content: str, file_path: str) -> list[str]:
-    if is_test_file(file_path):
-        return []
+def check_return_annotations(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag functions missing a return type annotation, scoped to changed lines.
+
+    In a production file every function definition needs a return annotation. In
+    a test file the requirement narrows to pytest-collectable test functions —
+    ``test_*`` at module top level or in a class body — which typically declare
+    ``-> None``; an ordinary helper in a test file stays exempt. Findings scope
+    to *all_changed_lines* so a pre-existing unannotated function on an untouched
+    line never blocks while a newly written one does.
+
+    Args:
+        content: The source text to inspect — the reconstructed full file on an
+            Edit so the parse succeeds.
+        file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a violation
+            blocks only when the function's definition line is among the changed
+            lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate scopes by added line through its ``Line N:``
+            partitioning.
+
+    Returns:
+        One issue per function missing a return type annotation, scoped to the
+        changed lines unless *defer_scope_to_caller* is True or *all_changed_lines*
+        is None.
+    """
     if is_workflow_registry_file(file_path) or is_migration_file(file_path):
         return []
     try:
         tree = ast.parse(content)
     except SyntaxError:
         return []
-    issues: list[str] = []
-    for each_node in ast.walk(tree):
-        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+    if is_test_file(file_path):
+        candidate_functions: list[ast.FunctionDef | ast.AsyncFunctionDef] = [
+            each_node
+            for each_node in _collect_pytest_collectable_functions(tree)
+            if _is_pytest_test_function(each_node)
+        ]
+    else:
+        candidate_functions = [
+            each_node
+            for each_node in ast.walk(tree)
+            if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        ]
+    all_violations_in_source_order: list[tuple[range, str]] = []
+    for each_node in candidate_functions:
+        if each_node.returns is not None:
             continue
-        if each_node.returns is None:
-            issues.append(
-                f"Line {each_node.lineno}: function {each_node.name!r} missing return type annotation (CODE_RULES §6)"
-            )
-    return issues
+        message = (
+            f"Line {each_node.lineno}: function {each_node.name!r} missing "
+            "return type annotation (CODE_RULES §6)"
+        )
+        all_violations_in_source_order.append(
+            (range(each_node.lineno, each_node.lineno + 1), message)
+        )
+    return _scope_violations_to_changed_lines(
+        all_violations_in_source_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
 
 
 def check_function_length(

package/hooks/blocking/code_rules_banned_identifiers.py

@@ -118,9 +118,39 @@ def _collect_banned_names_from_node(node: ast.AST) -> list[ast.Name]:
     return []
 
 
-def check_banned_identifiers(content: str, file_path: str) -> list[str]:
-    """Flag assignments to identifiers banned by the project Naming rules."""
-    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+def check_banned_identifiers(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag assignments to identifiers banned by the project Naming rules.
+
+    Test files are scoped rather than exempt: a banned identifier a test binds
+    is flagged only when its binding line is among the changed lines, so a
+    pre-existing ``result`` on an untouched line never blocks an edit while a
+    newly written one does. Production files scope the same way, and a new-file
+    or full-file write treats every line as changed. Hook infrastructure stays
+    exempt.
+
+    Args:
+        content: The source text to inspect — the reconstructed full file on an
+            Edit so the parse succeeds and the diff scoping is meaningful.
+        file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a violation
+            blocks only when its binding line is among the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate scopes by added line through its ``Line N:``
+            partitioning.
+
+    Returns:
+        One issue per banned binding, scoped to the changed lines unless
+        *defer_scope_to_caller* is True or *all_changed_lines* is None. The
+        terminal result is capped at the module limit; the deferred result is
+        uncapped so the gate can scope by added line and apply its own ceiling.
+    """
+    if is_hook_infrastructure(file_path):
         return []
 
     try:
@@ -135,15 +165,24 @@ def check_banned_identifiers(content: str, file_path: str) -> list[str]:
 
     banned_name_nodes.sort(key=lambda each_name: (each_name.lineno, each_name.col_offset))
 
-    issues: list[str] = []
+    all_violations_in_source_order: list[tuple[range, str]] = []
     for each_name in banned_name_nodes:
-        issues.append(
-            f"Line {each_name.lineno}: Banned identifier '{each_name.id}' - {BANNED_IDENTIFIER_MESSAGE_SUFFIX}"
+        message = (
+            f"Line {each_name.lineno}: Banned identifier '{each_name.id}' - "
+            f"{BANNED_IDENTIFIER_MESSAGE_SUFFIX}"
+        )
+        all_violations_in_source_order.append(
+            (range(each_name.lineno, each_name.lineno + 1), message)
         )
-        if len(issues) >= MAX_BANNED_IDENTIFIER_ISSUES:
-            break
 
-    return issues
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_source_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    if defer_scope_to_caller:
+        return scoped_issues
+    return scoped_issues[:MAX_BANNED_IDENTIFIER_ISSUES]
 
 
 def _identifier_word_parts(identifier: str) -> list[str]:

package/hooks/blocking/code_rules_command_dispatch.py

@@ -0,0 +1,140 @@
+"""Meta-gate flagging an unanchored multi-word command pattern in a blocker.
+
+A hook that classifies a shell command reads the command text and matches it
+against a regex. When that regex names a multi-word command such as
+``gh\\s+pr\\s+(create|edit)`` and is matched with a bare ``re.search`` — no
+start anchor and no first-word tokenization — the pattern matches the command
+as a substring anywhere in the string. A benign command like
+``echo gh pr create --title x`` then trips the gate. This check flags that shape
+at write time on files under ``hooks/blocking/`` so a new blocker anchors its
+command match to the start of the command or tokenizes the first word.
+"""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    _scope_violations_to_changed_lines,
+    is_test_file,
+)
+
+from hooks_constants.command_dispatch_constants import (  # noqa: E402
+    ALL_REGEX_START_ANCHOR_TOKENS,
+    COMMAND_DISPATCH_LITERAL_PATTERN,
+    COMMAND_DISPATCH_MESSAGE_SUFFIX,
+    COMMAND_DISPATCH_PATH_MARKER,
+    COMMAND_KEY_ACCESS_PATTERN,
+    FIRST_TOKEN_TOKENIZATION_PATTERN,
+    MAX_COMMAND_DISPATCH_ISSUES,
+)
+
+
+def _is_under_hooks_blocking(file_path: str) -> bool:
+    """Return whether the path sits under the ``hooks/blocking`` directory."""
+    return COMMAND_DISPATCH_PATH_MARKER in file_path.replace("\\", "/")
+
+
+def _command_literal_is_anchored(literal_value: str, match_start: int) -> bool:
+    """Return whether a start anchor precedes the command word in the pattern.
+
+    Args:
+        literal_value: The regex string literal the command word appears in.
+        match_start: The index where the command word match begins.
+
+    Returns:
+        True when a ``^`` or ``\\A`` anchor appears before the command word, so
+        the pattern binds the command to the start of the string.
+    """
+    prefix = literal_value[:match_start]
+    return any(each_anchor in prefix for each_anchor in ALL_REGEX_START_ANCHOR_TOKENS)
+
+
+def _unanchored_command_literals(
+    parsed_tree: ast.AST,
+) -> list[tuple[range, str]]:
+    """Return one span-tagged violation per unanchored command-regex literal.
+
+    Args:
+        parsed_tree: The parsed module to scan for string-constant nodes.
+
+    Returns:
+        ``(line_range, message)`` pairs in source order.
+    """
+    all_violations: list[tuple[range, str]] = []
+    for each_node in ast.walk(parsed_tree):
+        if not isinstance(each_node, ast.Constant) or not isinstance(
+            each_node.value, str
+        ):
+            continue
+        literal_match = COMMAND_DISPATCH_LITERAL_PATTERN.search(each_node.value)
+        if literal_match is None:
+            continue
+        if _command_literal_is_anchored(each_node.value, literal_match.start()):
+            continue
+        end_line = each_node.end_lineno or each_node.lineno
+        message = (
+            f"Line {each_node.lineno}: command pattern {each_node.value!r} "
+            f"{COMMAND_DISPATCH_MESSAGE_SUFFIX}"
+        )
+        all_violations.append((range(each_node.lineno, end_line + 1), message))
+    return all_violations
+
+
+def check_unanchored_command_dispatch(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag an unanchored multi-word command regex in a hooks/blocking file.
+
+    The check fires only on a file under ``hooks/blocking/`` that reads a
+    ``command`` key (a shell-command classifier) and does not tokenize the
+    command's first word (no ``shlex.split`` or ``.split(`` nearby). Under those
+    conditions, a regex string literal naming a known command word followed by
+    ``\\s+`` without a leading ``^``/``\\A`` anchor is flagged. Findings scope to
+    *all_changed_lines* so a pre-existing pattern on an untouched line does not
+    block an edit while a newly written one does.
+
+    Args:
+        content: The source text to inspect — the reconstructed full file on an
+            Edit so the parse succeeds.
+        file_path: The path the source will be written to, used for scoping to
+            ``hooks/blocking`` and skipping test files.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope.
+        defer_scope_to_caller: When True, return every violation so a downstream
+            scoper classifies by added line.
+
+    Returns:
+        One issue per unanchored command-regex literal, scoped to the changed
+        lines unless *defer_scope_to_caller* is True or *all_changed_lines* is
+        None, capped at the module limit.
+    """
+    if is_test_file(file_path) or not _is_under_hooks_blocking(file_path):
+        return []
+    if COMMAND_KEY_ACCESS_PATTERN.search(content) is None:
+        return []
+    if FIRST_TOKEN_TOKENIZATION_PATTERN.search(content) is not None:
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    all_violations_in_source_order = _unanchored_command_literals(parsed_tree)
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_source_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    if defer_scope_to_caller:
+        return scoped_issues
+    return scoped_issues[:MAX_COMMAND_DISPATCH_ISSUES]