claude-dev-env 1.49.1 → 1.50.0

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

@@ -21,10 +21,10 @@ 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. |
-| 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. |
+| 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`. |
+| 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. |
+| 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. |
 | A5 | subprocess invocation contract | `subprocess.run` kwargs valid for the targeted Python; `args=[list]` shape; exception propagation under `check=True`. |
 | A6 | PowerShell cmdlet parameter sets and binding | `param(...)` with `ParameterSetName=`; `[CmdletBinding(DefaultParameterSetName=…)]` presence; cmdlet parameter combinations valid per Microsoft docs. |
 | A7 | Cross-language argv boundary | The `-Argument` string composition → Windows process loader → C-runtime argv parser → Python `sys.argv` → argparse. Trailing-backslash and embedded-space hazards. |
@@ -34,6 +34,20 @@ Adapt these axes for your artifact. For a pure Python codebase, drop A6 and A7 a
 
 ---
 
+### Documentation as contract: verifying a doc claim about code
+
+When the audited artifact is documentation — a CLAUDE.md, a rule file, a README, a table mapping symbols to behavior — that asserts facts about the codebase, API-contract verification means checking every assertion against the current code, not just confirming the symbol exists and its return type matches. A doc that passes the happy-path contract can still be wrong on any of the seven checks below. Run all seven up front. Checks 1, 2, and 6 are the full-contract sharpening of sub-buckets A1, A2, and A4 applied to a doc claim; checks 3, 4, 5, and 7 are specific to documentation artifacts.
+
+1. **Full failure contract** — the failure signals of a function are its return value AND every exception it raises; trace the body and the docstring `Raises:` for every `raise`. _Example:_ a docs PR says a UI helper "returns `bool`", but it also raises a custom not-found error, and a database writer documented by its return type also raises `ValueError` / `RuntimeError` / a driver error, so "returns bool" understates the contract.
+2. **Call shape** — required versus optional parameters (a keyword-only parameter with NO default is required; omitting it raises `TypeError`), sync versus async, and the exact access path (free function versus instance method reached through an object attribute versus import path). _Example:_ a doc presents a helper as a free function, but it is an `async` instance method reached through an object attribute and one keyword-only parameter has no default, so the call example in the doc would raise `TypeError`.
+3. **Reuse-first** — before a doc endorses a hand-written snippet, search for a dedicated helper that already does it. _Example:_ a doc endorses hand-composing `normalize(name).lower()` inline while a dedicated `normalize_for_matching()` helper already does exactly that, contradicting the reuse-before-building rule the doc itself states.
+4. **Path resolution** — every file or directory path a doc cites resolves from the repository root. _Example:_ a doc cites a bare `snapshots/` directory as if it sat at the repo root, but the tree lives under `subsystem/snapshots/`.
+5. **Cross-entry consistency** — scan parallel rows, sections, and table entries for claims that contradict each other. _Example:_ two adjacent table rows map the same subsystem to two different exception base classes.
+6. **Catch-site precision** — when a doc claims code "catches X", confirm the exact site and scope of the catch. _Example:_ a doc says a context manager catches a driver error, but the `except` wraps only the rollback inside `finally`, so an error raised in the `with` body propagates uncaught.
+7. **Citation freshness** — re-derive every `file:line` claim against the current code; never trust a prior "verified" assertion or wording borrowed from a comment. _Example:_ an attribute name carried over from a review comment names a member the class does not define; the current code exposes it under a different name.
+
+---
+
 ## Sample prompt
 
 The literal text used in the May 2026 audit experiment is in [`../prompts/category-a-api-contracts.md`](../prompts/category-a-api-contracts.md). It produced 8–10 findings (P0=1–2, P1=2–6, P2=2–5) across two runs. Inline the full diff verbatim — do not ask the agent to fetch it.

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

@@ -1,4 +1,4 @@
-Audit [REPO/ARTIFACT] [TARGET_ID] for **Category A only** (API contract verification). Skip B–K. Sub-bucket forced-exhaustion mode: Category A is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES 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.
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category A only** (API contract verification). Skip B–N. Sub-bucket forced-exhaustion mode: Category A is decomposed into 9 sub-buckets below. Each sub-bucket REQUIRES 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 / change description / head SHA or revision identifier / scope summary]
 ID prefix: `find`.
@@ -15,6 +15,7 @@ ID prefix: `find`.
 - Flag positional arguments passed to keyword-only parameters and vice versa.
 - 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`.
 
 **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.
@@ -22,6 +23,7 @@ ID prefix: `find`.
 - For functions that raise instead of returning on some path, confirm the annotation does not promise a value the caller will dereference.
 - Inspect `try/except/finally` chains for paths that return from `finally` and override `try`/`except` returns.
 - For async functions, confirm the annotation refers to the awaited type, not the coroutine wrapper.
+- The full failure contract is the return value AND every exception raised — list each `raise` in the body and the docstring `Raises:`; a `-> bool` that can also raise is not fully described as "returns bool".
 
 **A3. CLI/argument-parser declaration → downstream Namespace contract**
 - For every `add_argument(...)` (or equivalent CLI declaration), verify the auto-derived or explicit `dest=` matches the attribute name accessed downstream on the parsed namespace.
@@ -34,6 +36,7 @@ ID prefix: `find`.
 - Identify every callback handed to a library function (e.g., `os.walk(onerror=...)`, sort `key=`, `filter`, `map`, `re.sub(repl=callable)`, signal handlers, threading callbacks). Verify each callback's signature matches what the library calls it with — arity, positional-vs-keyword, return type the library consumes.
 - For every stdlib function the artifact calls, verify argument types and exception contracts: which exceptions can each call raise, and is each caller prepared (or deliberately not prepared) for them.
 - Verify kwargs to stdlib functions are spelled correctly for the targeted runtime version (deprecated/renamed kwargs, version-introduced kwargs).
+- Catch-site precision — for any "catches X" claim confirm the exact catch site and scope (an `except` around only a rollback inside `finally` does not catch the same error from the `with` body).
 - Flag callbacks whose return value the library consumes but the implementation returns `None` (or vice versa).
 - Confirm callback exception behavior: which exceptions in the callback bubble out, which are swallowed by the library, which terminate iteration.
 
@@ -66,6 +69,18 @@ ID prefix: `find`.
 - For write calls, verify the signature against the provider's own published API contract — their REST reference docs, OpenAPI spec, SDK source code, or `--help` output. When a read endpoint exposes the same state, call it to confirm the write contract.
 - Flag every call where documented parameters, types, or behavior diverge from the official API contract.
 
+**A9. Documentation claims about the codebase (when the artifact asserts facts about the code)**
+
+When the artifact is documentation that asserts facts about the codebase (symbol names, signatures, return types, exceptions, file paths), run all seven documentation-as-contract checks below; each yields a confirmation or a finding. For a pure-code artifact, A9 is one line of proof-of-absence (the artifact asserts no code facts).
+
+- Full failure contract — the failure signals of a function are its return value AND every exception it raises; trace the body and the docstring `Raises:` for every `raise`. _Example:_ a docs PR says a UI helper "returns `bool`", but it also raises a custom not-found error, so "returns bool" understates the contract.
+- Call shape — required versus optional parameters (a keyword-only parameter with NO default is required; omitting it raises `TypeError`), sync versus async, and the exact access path (free function versus instance method reached through an object attribute versus import path). _Example:_ a doc presents a helper as a free function, but it is an `async` instance method reached through an object attribute, so the doc's call example would raise `TypeError`.
+- Reuse-first — before a doc endorses a hand-written snippet, search for a dedicated helper that already does it. _Example:_ a doc endorses hand-composing `normalize(name).lower()` inline while a dedicated `normalize_for_matching()` helper already does exactly that.
+- Path resolution — every file or directory path a doc cites resolves from the repository root. _Example:_ a doc cites a bare `snapshots/` directory as if it sat at the repo root, but the tree lives under `subsystem/snapshots/`.
+- Cross-entry consistency — scan parallel rows, sections, and table entries for claims that contradict each other. _Example:_ two adjacent table rows map the same subsystem to two different exception base classes.
+- Catch-site precision — when a doc claims code "catches X", confirm the exact site and scope of the catch. _Example:_ a doc says a context manager catches a driver error, but the `except` wraps only the rollback inside `finally`, so an error raised in the `with` body propagates uncaught.
+- Citation freshness — re-derive every `file:line` claim against the current code; never trust a prior "verified" assertion or wording borrowed from a comment. _Example:_ an attribute name carried over from a review comment names a member the class does not define; the current code exposes it under a different name.
+
 ## Cross-bucket questions to answer at the end
 
 Q1: Are there any contracts that span two sub-buckets that single-bucket analysis would miss?
@@ -74,7 +89,7 @@ Q3: Where would a future refactor most likely break a cross-bucket or cross-lang
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket A1–A8, produce Shape A or Shape B (with ≥3 adversarial probes). Cross-bucket Q1–Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P1 bugs across these 8 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket A1–A9, produce Shape A or Shape B (with ≥3 adversarial probes). Cross-bucket Q1–Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P1 bugs across these 9 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 ---
 

package/docs/CODE_RULES.md

@@ -62,6 +62,8 @@ These rules are automatically enforced by `code_rules_enforcer.py`. Violations b
 | Test-mode branching in production | Reading `TESTING`, `PYTEST_CURRENT_TEST`, `IS_TEST`, etc. from production code creates two parallel implementations. Use dependency injection so production stays single-path. **Test files and hook infrastructure exempt.** |
 | Thin wrapper files | A non-`__init__.py` module whose body is only imports (optionally with an `__all__` assignment) is a re-export indirection with no payload. Callers should import from the real module. `__init__.py` is the canonical re-export surface and is exempt. |
 | Docstring format (Google-style) | Public functions/methods (no leading underscore, not dunder, body > 3 lines, not `@property`/`@abstractmethod`) require Google-style `Args:` / `Returns:` (or `Yields:`) / `Raises:` sections matching the signature. **Test files exempt.** |
+| Docstring Args match signature | A public function whose docstring `Args:` section names a parameter the signature does not declare is flagged — a rename that left the adjacent `Args:` line stale. Only the `Args:` section is compared against the signature; `Raises:` is left alone because callee-propagated exceptions cause false positives. **Test files and hook infrastructure exempt.** |
+| Ignored must-check return | A bare-statement call to a function whose return value is its only failure signal (the curated `find_and_click`, `write_outcome` set) is flagged — the discarded boolean lets the caller move on silently after a failure. Assign the return and check it. Assigned (`clicked = …`) and branched-on (`if …:`) calls are exempt. Attribute calls are matched by their terminal method name alone (the receiver type is not resolved), so an unrelated `obj.write_outcome()` or `widget.find_and_click()` whose method name collides with a curated name is also flagged. **Test files exempt.** |
 
 ### Where UPPER_SNAKE is allowed
 
@@ -124,7 +126,7 @@ Full words only. No mental translation.
 
 **Extended naming rules** :
 - Loop vars: `each_order`, `each_user` (prefix `each_`)
-- Booleans: `is_valid`, `has_permission`, `should_retry` (prefix `is_`/`has_`/`should_`/`can_`)
+- Booleans: `is_valid`, `has_permission`, `should_retry`, `was_clicked`, `did_succeed` (prefix `is_`/`has_`/`should_`/`can_`/`was_`/`did_`). The hook covers both boolean assignments and boolean-typed function parameters (a parameter annotated `bool` or defaulting to a boolean literal); `self`/`cls` and single-character names are exempt.
 - Collections: `all_orders`, `all_users` (prefix `all_`)
 - Maps: `price_by_product`, `user_by_id` (pattern `X_by_Y`)
 - Preposition params: `from_path=`, `to=`, `into=`
@@ -400,6 +402,9 @@ Hook will enforce:
 [⚡] No test-mode branching in production (TESTING / PYTEST_CURRENT_TEST)
 [⚡] No thin wrapper modules (imports only, optionally with __all__, outside __init__.py)
 [⚡] Public functions have Google-style Args:/Returns:/Raises: when warranted
+[⚡] Docstring Args: names match the signature (a stale renamed param is flagged)
+[⚡] Boolean names prefixed is_/has_/should_/can_/was_/did_ (assignments AND bool-typed parameters)
+[⚡] No discarded must-check return (assign and check find_and_click/write_outcome outcomes)
 
 Manual check:
 [ ] No abbreviations?

package/hooks/blocking/code_rules_enforcer.py

@@ -91,7 +91,9 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_BANNED_PREFIX_ISSUES,
     MAX_BARE_EXCEPT_ISSUES,
     MAX_BOUNDARY_TYPE_ISSUES,
+    MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
+    MAX_IGNORED_MUST_CHECK_RETURN_ISSUES,
     MAX_STUB_IMPLEMENTATION_ISSUES,
     MAX_TEST_BRANCHING_ISSUES,
     MAX_TYPED_DICT_PAIR_ISSUES,
@@ -132,6 +134,10 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     BANNED_NOUN_SPAN_FRAGMENT_TEMPLATE,
     BARE_EACH_TOKEN,
     ALL_BOOLEAN_NAME_PREFIXES,
+    ALL_DOCSTRING_ARGS_SECTION_HEADERS,
+    ALL_DOCSTRING_TERMINATING_SECTION_HEADERS,
+    DOCSTRING_ARG_ENTRY_PATTERN,
+    ALL_MUST_CHECK_RETURN_FUNCTION_NAMES,
     ALL_BUILTIN_DICT_METHOD_NAMES,
     ALL_CLI_FILE_PATH_MARKERS,
     CHAINED_INLINE_COMMENT_PATTERN,
@@ -2092,6 +2098,110 @@ def check_docstring_format(content: str, file_path: str) -> list[str]:
     return issues[:MAX_DOCSTRING_FORMAT_ISSUES]
 
 
+def _signature_parameter_names(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> set[str]:
+    arguments = function_node.args
+    real_names: set[str] = set()
+    for each_argument in arguments.posonlyargs + arguments.args + arguments.kwonlyargs:
+        real_names.add(each_argument.arg)
+    if arguments.vararg is not None:
+        real_names.add(arguments.vararg.arg)
+    if arguments.kwarg is not None:
+        real_names.add(arguments.kwarg.arg)
+    return real_names - ALL_SELF_AND_CLS_PARAMETER_NAMES
+
+
+def _is_docstring_terminating_section_header(stripped_line: str) -> bool:
+    return stripped_line in ALL_DOCSTRING_TERMINATING_SECTION_HEADERS
+
+
+def _documented_argument_names(docstring_text: str) -> list[str]:
+    docstring_lines = docstring_text.splitlines()
+    args_section_index = _find_args_section_index(docstring_lines)
+    if args_section_index is None:
+        return []
+    documented_names: list[str] = []
+    entry_indent: int | None = None
+    for each_line in docstring_lines[args_section_index + 1:]:
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        current_indent = len(each_line) - len(each_line.lstrip())
+        if current_indent == 0:
+            break
+        if entry_indent is None:
+            entry_indent = current_indent
+        if current_indent > entry_indent:
+            continue
+        entry_match = DOCSTRING_ARG_ENTRY_PATTERN.match(stripped_line)
+        if entry_match is not None:
+            documented_names.append(entry_match.group(1))
+    return documented_names
+
+
+def _find_args_section_index(all_docstring_lines: list[str]) -> int | None:
+    for each_line_index, each_line in enumerate(all_docstring_lines):
+        if each_line.strip() in ALL_DOCSTRING_ARGS_SECTION_HEADERS:
+            return each_line_index
+    return None
+
+
+def check_docstring_args_match_signature(content: str, file_path: str) -> list[str]:
+    """Flag docstring Args: entries naming a parameter the signature lacks.
+
+    A fix that renames a parameter often leaves the adjacent ``Args:`` line
+    stale. Each documented argument name is compared to the real signature;
+    a documented name with no matching parameter is reported. Only the
+    ``Args:`` section is validated — ``Raises:`` is left alone because
+    callee-propagated exceptions cause false positives. Functions that
+    accept ``**kwargs`` are skipped because their documented names may be
+    keyword keys the signature cannot enumerate.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per stale documented argument, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_private_or_dunder(each_node.name):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        if _function_body_line_count(each_node) <= DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT:
+            continue
+        if each_node.args.kwarg is not None:
+            continue
+        documented_names = _documented_argument_names(_function_docstring_text(each_node))
+        if not documented_names:
+            continue
+        real_names = _signature_parameter_names(each_node)
+        for each_documented_name in documented_names:
+            if each_documented_name in real_names:
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: {each_node.name}() docstring Args: lists "
+                f"'{each_documented_name}' which is not a parameter - update the "
+                "docstring to match the signature"
+            )
+            if len(issues) >= MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES:
+                return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
+    return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
+
+
 _PASCAL_TO_SNAKE_WORD_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
 
 
@@ -2440,8 +2550,89 @@ def _collect_boolean_assignments(tree: ast.Module) -> list[tuple[str, int, bool]
     return collected
 
 
-def check_boolean_naming(content: str, file_path: str) -> list[str]:
-    """Flag boolean assignments whose target name lacks a required prefix."""
+def _argument_is_boolean(argument_node: ast.arg, default_node: ast.expr | None) -> bool:
+    annotation_is_bool = (
+        isinstance(argument_node.annotation, ast.Name)
+        and argument_node.annotation.id == "bool"
+    )
+    default_is_bool = default_node is not None and _is_bool_constant(default_node)
+    return annotation_is_bool or default_is_bool
+
+
+def _bool_parameters_for_function(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[tuple[str, int]]:
+    arguments = function_node.args
+    positional_arguments = arguments.posonlyargs + arguments.args
+    positional_defaults = arguments.defaults
+    leading_without_default = len(positional_arguments) - len(positional_defaults)
+    bool_parameters: list[tuple[str, int]] = []
+    for each_position, each_argument in enumerate(positional_arguments):
+        default_index = each_position - leading_without_default
+        default_node = (
+            positional_defaults[default_index] if default_index >= 0 else None
+        )
+        if each_argument.arg in ALL_SELF_AND_CLS_PARAMETER_NAMES:
+            continue
+        if _argument_is_boolean(each_argument, default_node):
+            bool_parameters.append((each_argument.arg, each_argument.lineno))
+    for each_argument, each_default in zip(arguments.kwonlyargs, arguments.kw_defaults):
+        if each_argument.arg in ALL_SELF_AND_CLS_PARAMETER_NAMES:
+            continue
+        if _argument_is_boolean(each_argument, each_default):
+            bool_parameters.append((each_argument.arg, each_argument.lineno))
+    return bool_parameters
+
+
+def _collect_bool_parameter_names(tree: ast.Module) -> list[tuple[str, int]]:
+    """Collect (name, line_number) for boolean-typed function parameters.
+
+    A parameter counts as boolean when its annotation is the ``bool`` name or
+    its default is a boolean literal. ``self`` and ``cls`` are skipped.
+
+    Args:
+        tree: The parsed module to inspect.
+
+    Returns:
+        Each boolean parameter as a (name, line_number) pair.
+    """
+    bool_parameters: list[tuple[str, int]] = []
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            bool_parameters.extend(_bool_parameters_for_function(each_node))
+    return bool_parameters
+
+
+def check_boolean_naming(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag boolean assignments and parameters whose name lacks a required prefix.
+
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module rather than an Edit's ``new_string`` fragment, which is
+    rarely valid standalone Python. Findings are then scoped to *all_changed_lines*
+    so an Edit blocks on the unprefixed boolean it just introduced while a
+    pre-existing violation on an untouched line does not block the edit.
+
+    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 its source line intersects the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
+
+    Returns:
+        One issue per unprefixed boolean assignment and parameter, scoped to the
+        changed lines unless *defer_scope_to_caller* is True or *all_changed_lines*
+        is None. This check has no module cap.
+    """
     if is_test_file(file_path):
         return []
     if is_hook_infrastructure(file_path):
@@ -2459,20 +2650,125 @@ def check_boolean_naming(content: str, file_path: str) -> list[str]:
             file=sys.stderr,
         )
         return []
-    issues: list[str] = []
-    for name, line_number, is_in_upper_snake_scope in _collect_boolean_assignments(tree):
-        if len(name) == 1:
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for each_name, each_line_number, each_is_in_upper_snake_scope in _collect_boolean_assignments(tree):
+        if len(each_name) == 1:
             continue
-        if is_in_upper_snake_scope and UPPER_SNAKE_CONSTANT_PATTERN.match(name):
+        if each_is_in_upper_snake_scope and UPPER_SNAKE_CONSTANT_PATTERN.match(each_name):
             continue
-        if name.startswith(ALL_BOOLEAN_NAME_PREFIXES):
+        if each_name.startswith(ALL_BOOLEAN_NAME_PREFIXES):
             continue
-        issues.append(
-            f"Line {line_number}: Boolean {name} - prefix with is_/has_/should_/can_"
+        message = (
+            f"Line {each_line_number}: Boolean {each_name} - prefix with "
+            "is_/has_/should_/can_/was_/did_"
         )
-    return issues
+        all_violations_in_walk_order.append(
+            (range(each_line_number, each_line_number + 1), message)
+        )
+    for each_name, each_line_number in _collect_bool_parameter_names(tree):
+        if len(each_name) == 1:
+            continue
+        if each_name.startswith(ALL_BOOLEAN_NAME_PREFIXES):
+            continue
+        message = (
+            f"Line {each_line_number}: Boolean parameter {each_name} - prefix with "
+            "is_/has_/should_/can_/was_/did_"
+        )
+        all_violations_in_walk_order.append(
+            (range(each_line_number, each_line_number + 1), message)
+        )
+    return _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
 
 
+def _called_terminal_name(call_node: ast.Call) -> str | None:
+    callee = call_node.func
+    if isinstance(callee, ast.Name):
+        return callee.id
+    if isinstance(callee, ast.Attribute):
+        return callee.attr
+    return None
+
+
+def check_ignored_must_check_return(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag bare-expression calls whose discarded return is the only failure signal.
+
+    Functions in ``ALL_MUST_CHECK_RETURN_FUNCTION_NAMES`` report success or failure
+    solely through their return value. A bare-statement call discards that value,
+    so the caller silently proceeds on failure. Bare ``ast.Expr`` calls are flagged,
+    including a bare ``await``-wrapped call (``await find_and_click(...)`` as a
+    statement); an assigned or branched-on call is exempt.
+
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module rather than an Edit's ``new_string`` fragment, which is
+    rarely valid standalone Python (a bare ``await find_and_click(...)`` line is a
+    SyntaxError on its own). Findings are then scoped to *all_changed_lines* so an
+    Edit blocks on the discarded return it just introduced while a pre-existing
+    violation on an untouched line does not block the edit.
+
+    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 bare call's line intersects the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
+
+    Returns:
+        One issue per discarded must-check return, scoped to the changed lines
+        unless *defer_scope_to_caller* is True or *all_changed_lines* is None. When
+        *defer_scope_to_caller* is True every violation is returned uncapped so the
+        gate can scope by added line and apply its own ceiling; otherwise the
+        terminal result is capped at the module limit.
+    """
+    if is_test_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Expr):
+            continue
+        expression_value = each_node.value
+        call_node = (
+            expression_value.value
+            if isinstance(expression_value, ast.Await)
+            else expression_value
+        )
+        if not isinstance(call_node, ast.Call):
+            continue
+        called_name = _called_terminal_name(call_node)
+        if called_name is None or called_name not in ALL_MUST_CHECK_RETURN_FUNCTION_NAMES:
+            continue
+        end_line_number = each_node.end_lineno or each_node.lineno
+        line_span = range(each_node.lineno, end_line_number + 1)
+        message = (
+            f"Line {each_node.lineno}: return value of {called_name}() is discarded - "
+            "assign and check it (the boolean/outcome is the only failure signal)"
+        )
+        all_violations_in_walk_order.append((line_span, message))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    if defer_scope_to_caller:
+        return scoped_issues
+    return scoped_issues[:MAX_IGNORED_MUST_CHECK_RETURN_ISSUES]
+
 
 def _decorator_name_contains_skip(decorator_node: ast.expr) -> bool:
     """Return True when a decorator AST node references an identifier containing 'skip'."""
@@ -5570,7 +5866,23 @@ def validate_content(
         all_issues.extend(check_thin_wrapper_files(effective_content, file_path))
         all_issues.extend(check_boundary_types(effective_content, file_path))
         all_issues.extend(check_docstring_format(effective_content, file_path))
-        all_issues.extend(check_boolean_naming(content, file_path))
+        all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
+        all_issues.extend(
+            check_boolean_naming(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            check_ignored_must_check_return(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_skip_decorators_in_tests(content, file_path))
         all_issues.extend(
             check_tests_use_isolated_filesystem_paths(

package/hooks/blocking/md_to_html_blocker.py

@@ -68,7 +68,7 @@ def _block_context() -> str:
         f"- Files under {_exempt_plugin_segments_summary} directories\n"
         f"- Files under {_claude_dev_env_source_directories_summary} source directories\n"
         f"- Files under any directory whose ancestor contains {PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/\n"
-        "- README.md and CHANGELOG.md at any repo root\n"
+        "- README.md, CHANGELOG.md, CLAUDE.md, and AGENTS.md at any repo root\n"
         f"- Files under {_exempt_home_directories_summary}\n"
         "- Files under the OS temp directory"
     )
@@ -83,7 +83,7 @@ def _block_system_message() -> str:
         f"{_exempt_anywhere_filenames_summary} anywhere, {_exempt_plugin_segments_summary} trees, "
         f"{_claude_dev_env_source_directories_summary} source trees, "
         f"files under a {PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/ root, "
-        f"README.md/CHANGELOG.md at any repo root, {_exempt_home_directories_summary}, "
+        f"README.md/CHANGELOG.md/CLAUDE.md/AGENTS.md at any repo root, {_exempt_home_directories_summary}, "
         "and the OS temp directory."
     )
 

package/hooks/blocking/test_code_rules_enforcer.py

@@ -2602,3 +2602,68 @@ def test_banned_noun_word_boundary_flags_plural_results_identifier() -> None:
         "a plural banned-noun identifier must be flagged by the word-boundary "
         f"check; got: {issues!r}"
     )
+
+
+def test_ignored_must_check_return_flags_bare_awaited_call() -> None:
+    """A bare ``await find_and_click(...)`` statement discards its only failure signal.
+
+    The curated must-check functions are async, so the common real call site is a
+    bare ``await``-wrapped call. Unwrapping ``ast.Await`` before the Call check is
+    required for this case to be flagged.
+    """
+    source = "async def step() -> None:\n    await find_and_click('#x')\n"
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source, "/project/src/clicker.py"
+    )
+    assert any("find_and_click" in each_issue for each_issue in issues), (
+        f"a bare awaited must-check call must be flagged; got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_ignored_must_check_return_exempts_consumed_awaited_call() -> None:
+    """An assigned or branched-on awaited must-check call consumes its outcome."""
+    assigned = "async def step() -> None:\n    clicked = await find_and_click('#x')\n    print(clicked)\n"
+    branched = "async def step() -> None:\n    if await find_and_click('#x'):\n        pass\n"
+    assert (
+        code_rules_enforcer.check_ignored_must_check_return(assigned, "/project/src/clicker.py")
+        == []
+    )
+    assert (
+        code_rules_enforcer.check_ignored_must_check_return(branched, "/project/src/clicker.py")
+        == []
+    )
+
+
+def test_ignored_must_check_return_flags_edited_line_past_a_cap_of_earlier_violations() -> None:
+    """The cap must apply after scoping so the edited-line violation is never dropped.
+
+    Collecting only a cap's worth of violations in ``ast.walk`` order, then scoping,
+    fills the cap with earlier out-of-scope calls and discards the edited-line one —
+    the very violation the scoped enforcer exists to block. Every violation must be
+    collected before scoping so the edited line survives the diff filter.
+    """
+    pre_existing_call_count = 5
+    edited_call_line_number = pre_existing_call_count + 2
+    all_pre_existing_call_lines = [
+        f"    await find_and_click('#x{each_index}')"
+        for each_index in range(pre_existing_call_count)
+    ]
+    all_lines = (
+        ["async def step() -> None:"]
+        + all_pre_existing_call_lines
+        + ["    await find_and_click('#edited')"]
+    )
+    source = "\n".join(all_lines) + "\n"
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source,
+        "/project/src/clicker.py",
+        {edited_call_line_number},
+        False,
+    )
+    assert len(issues) == 1, (
+        f"the edited-line violation must survive a cap's worth of earlier calls; got: {issues!r}"
+    )
+    assert f"Line {edited_call_line_number}:" in issues[0], (
+        f"the single issue must name the edited line {edited_call_line_number}; got: {issues!r}"
+    )