claude-dev-env 1.49.1 → 1.50.1

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,
@@ -1717,7 +1723,7 @@ def _is_init_file(file_path: str) -> bool:
     return file_path.replace("\\", "/").rsplit("/", 1)[-1] == "__init__.py"
 
 
-def _statement_is_module_docstring(statement_node: ast.stmt) -> bool:
+def _statement_is_docstring(statement_node: ast.stmt) -> bool:
     return (
         isinstance(statement_node, ast.Expr)
         and isinstance(statement_node.value, ast.Constant)
@@ -1772,7 +1778,7 @@ def check_thin_wrapper_files(content: str, file_path: str) -> list[str]:
 
     statements_after_docstring = (
         body_statements[1:]
-        if _statement_is_module_docstring(body_statements[0])
+        if _statement_is_docstring(body_statements[0])
         else body_statements
     )
     if not statements_after_docstring:
@@ -1931,11 +1937,7 @@ def _function_body_line_count(
     if not function_node.body:
         return 0
     first_body_index = 0
-    if (
-        isinstance(function_node.body[0], ast.Expr)
-        and isinstance(function_node.body[0].value, ast.Constant)
-        and isinstance(function_node.body[0].value.value, str)
-    ):
+    if _statement_is_docstring(function_node.body[0]):
         if len(function_node.body) == 1:
             return 0
         first_body_index = 1
@@ -2092,6 +2094,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])")
 
 
@@ -2245,7 +2351,7 @@ def _statement_is_raise_not_implemented(statement_node: ast.stmt) -> bool:
 
 def _function_body_is_stub(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     body_statements = list(function_node.body)
-    if body_statements and _statement_is_module_docstring(body_statements[0]):
+    if body_statements and _statement_is_docstring(body_statements[0]):
         body_statements = body_statements[1:]
     if len(body_statements) != 1:
         return False
@@ -2440,8 +2546,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 +2646,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'."""
@@ -5334,6 +5626,37 @@ def _function_definition_line_span(
     return end_lineno - function_node.lineno + 1
 
 
+def _definition_docstring_line_span(
+    definition_node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef,
+) -> int:
+    """Return the source-line count of the definition's leading docstring.
+
+    The Google Python Style Guide pairs a small-function preference that
+    targets executable complexity (§3.18) with a requirement for complete
+    docstrings on public functions and classes (§3.8). Counting those
+    docstring lines toward the function-length gate would penalize the very
+    documentation §3.8 mandates, so the gate measures executable span and
+    excludes leading docstring statements.
+
+    Args:
+        definition_node: The function, method, or class definition node to
+            inspect.
+
+    Returns:
+        The number of source lines the leading docstring statement occupies,
+        or zero when the definition body is empty or does not open with a
+        string literal.
+    """
+    definition_body = definition_node.body
+    if not definition_body:
+        return 0
+    first_statement = definition_body[0]
+    if _statement_is_docstring(first_statement):
+        docstring_end = getattr(first_statement, "end_lineno", None) or first_statement.lineno
+        return docstring_end - first_statement.lineno + 1
+    return 0
+
+
 def changed_line_numbers(prior_content: str, post_edit_content: str) -> set[int]:
     """Return the post-edit line numbers an edit added or replaced.
 
@@ -5420,18 +5743,23 @@ def check_function_length(
     all_changed_lines: set[int] | None = None,
     defer_scope_to_caller: bool = False,
 ) -> list[str]:
-    """Flag functions whose definition span exceeds cognitive-load thresholds.
-
-    Function definition spans (signature line through last body statement,
-    inclusive) at or above ``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60
-    lines) appear in the returned issues list and block the write at the
-    gate. The threshold rests on the small-function guidance in Robert C.
-    Martin, *Clean Code* Ch. 3 ("Functions") and the Google Python Style
-    Guide's ~40-line function review hint
-    (https://google.github.io/styleguide/pyguide.html); this gate blocks on
-    body growth that pushes a function past that span. It does not derive
-    from CODE_RULES §6.5, which governs advisory file-length signals and
-    argues against hard numeric blocks.
+    """Flag functions whose executable span exceeds cognitive-load thresholds.
+
+    Function executable spans — the definition span (signature line through
+    last body statement, inclusive) minus the leading docstring lines of the
+    function and of every function or class nested within it, per
+    ``_definition_docstring_line_span`` summed over the nested definitions —
+    at or above
+    ``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60 lines) appear in the returned
+    issues list and block the write at the gate. The threshold rests on the
+    small-function guidance in Robert C. Martin, *Clean Code* Ch. 3
+    ("Functions") and the Google Python Style Guide's ~40-line function review
+    hint (https://google.github.io/styleguide/pyguide.html) — a measure of
+    executable complexity, paired with the Guide's complete-docstring mandate
+    for public APIs, so documentation lines never count against the gate; this
+    gate blocks on body growth that pushes a function past that span. It does
+    not derive from CODE_RULES §6.5, which governs advisory file-length
+    signals and argues against hard numeric blocks.
 
     The issue message carries ``Function NAME (defined at line X) is Y lines``
     precisely so the gate's ``function_length_span_range`` can recover the
@@ -5480,7 +5808,17 @@ def check_function_length(
         if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
         line_span = _function_definition_line_span(each_node)
-        if line_span >= FUNCTION_LENGTH_BLOCKING_THRESHOLD:
+        if line_span < FUNCTION_LENGTH_BLOCKING_THRESHOLD:
+            continue
+        docstring_line_total = sum(
+            _definition_docstring_line_span(each_definition)
+            for each_definition in ast.walk(each_node)
+            if isinstance(
+                each_definition, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+            )
+        )
+        executable_line_span = line_span - docstring_line_total
+        if executable_line_span >= FUNCTION_LENGTH_BLOCKING_THRESHOLD:
             span_range = range(each_node.lineno, each_node.lineno + line_span)
             message = (
                 f"Function {each_node.name!r} (defined at line {each_node.lineno}) "
@@ -5570,7 +5908,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/conftest.py

@@ -0,0 +1,30 @@
+"""Session-scoped cleanup fixture for the md_to_html_blocker test suites.
+
+The md_to_html_blocker suites share one lazily-created sandbox parent
+directory under the home directory. This fixture tears that sandbox down once
+the session ends so the suites leave no residue regardless of which split file
+pytest collects first.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+
+if str(_BLOCKING_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_BLOCKING_DIRECTORY))
+
+from _md_to_html_blocker_test_support import (  # noqa: E402
+    _force_rmtree,
+    _get_sandbox_parent_directory,
+)
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _cleanup_sandbox_parent_directory():
+    yield
+    if _get_sandbox_parent_directory.cache_info().currsize:
+        _force_rmtree(_get_sandbox_parent_directory())
+        _get_sandbox_parent_directory.cache_clear()

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."
     )