claude-dev-env 1.38.1 → 1.40.0

package/hooks/blocking/code_rules_enforcer.py

@@ -51,6 +51,13 @@ from config.hardcoded_user_path_constants import (  # noqa: E402
     HARDCODED_USER_PATH_PATTERN,
     MAX_HARDCODED_USER_PATH_ISSUES,
 )
+from config.inline_tuple_string_magic_constants import (  # noqa: E402
+    ALL_SNAKE_CASE_KEYWORD_EXEMPTIONS,
+    EXPECTED_TUPLE_PAIR_LENGTH,
+    INLINE_TUPLE_STRING_MAGIC_MESSAGE_SUFFIX,
+    MAX_INLINE_TUPLE_STRING_MAGIC_ISSUES,
+    SNAKE_CASE_LITERAL_PATTERN,
+)
 from config.stuttering_check_config import (  # noqa: E402
     MAX_STUTTERING_PREFIX_ISSUES,
     STUTTERING_ALL_PREFIX_PATTERN,
@@ -68,34 +75,57 @@ from config.stuttering_import_binding_constants import (  # noqa: E402
     MODULE_PATH_SEPARATOR,
     WILDCARD_IMPORT_SENTINEL,
 )
+from config.any_type_config import ALL_ANY_ALLOWED_PATTERNS  # noqa: E402
+from config.blocking_check_limits import (  # noqa: E402
+    ALL_BANNED_PREFIX_NAMES,
+    ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES,
+    ALL_BOUNDARY_TYPE_EXEMPT_FILENAMES,
+    ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES,
+    ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES,
+    ALL_TEST_INDICATING_ENVIRONMENT_VARIABLE_NAMES,
+    DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
+    MAX_BANNED_PREFIX_ISSUES,
+    MAX_BARE_EXCEPT_ISSUES,
+    MAX_BOUNDARY_TYPE_ISSUES,
+    MAX_DOCSTRING_FORMAT_ISSUES,
+    MAX_STUB_IMPLEMENTATION_ISSUES,
+    MAX_TEST_BRANCHING_ISSUES,
+    MAX_TYPED_DICT_PAIR_ISSUES,
+    MAX_TYPE_ESCAPE_HATCH_ISSUES,
+    MAX_THIN_WRAPPER_ISSUES,
+)
 
-PYTHON_EXTENSIONS = {".py"}
-JAVASCRIPT_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx"}
-ALL_CODE_EXTENSIONS = PYTHON_EXTENSIONS | JAVASCRIPT_EXTENSIONS
-
-TEST_PATH_PATTERNS = {"test_", "_test.", ".test.", ".spec.", "/tests/", "\\tests\\", "/tests.py", "\\tests.py"}
-HOOK_INFRASTRUCTURE_PATTERNS = {"/.claude/hooks/", "\\.claude\\hooks\\", "\\.claude/hooks/", "/packages/claude-dev-env/hooks/", "\\packages\\claude-dev-env\\hooks\\"}
-WORKFLOW_REGISTRY_PATTERNS = {"/workflow/", "\\workflow\\", "_tab.py", "/states.py", "\\states.py", "/modules.py", "\\modules.py"}
-MIGRATION_PATH_PATTERNS = {"/migrations/", "\\migrations\\"}
-
-ADVISORY_LINE_THRESHOLD_SOFT = 400
-ADVISORY_LINE_THRESHOLD_HARD = 1000
-
-BOOLEAN_NAME_PREFIXES: tuple[str, ...] = ("is_", "has_", "should_", "can_")
-UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
-
-
-TYPE_CHECKING_BLOCK_PATTERN = re.compile(r"^(?P<indent>\s*)if\s+(typing\.)?TYPE_CHECKING\s*:\s*$")
-IMPORT_STATEMENT_PREFIXES: tuple[str, ...] = ("import ", "from ")
-NOT_INSIDE_TYPE_CHECKING_BLOCK = -1
-FILE_GLOBAL_UPPER_SNAKE_PATTERN = re.compile(r"^_?[A-Z][A-Z0-9_]*$")
-
-COLLECTION_TYPE_NAMES: frozenset[str] = frozenset({
-    "list", "tuple", "set", "frozenset", "dict",
-    "Iterable", "Sequence", "Mapping", "MutableMapping", "FrozenSet",
-})
-COLLECTION_BY_NAME_PATTERN: re.Pattern[str] = re.compile(r"^[a-z][a-z0-9]*_by_[a-z][a-z0-9_]*$")
-CLI_FILE_PATH_MARKERS: tuple[str, ...] = ("/scripts/", "\\scripts\\", "_cli.py", "/cli.py", "\\cli.py")
+from config.code_rules_enforcer_constants import (  # noqa: E402
+    ADVISORY_LINE_THRESHOLD_HARD,
+    ADVISORY_LINE_THRESHOLD_SOFT,
+    ALL_CODE_EXTENSIONS,
+    ALL_CAPS_WITH_UNDERSCORE_PATTERN,
+    BARE_EACH_TOKEN,
+    ALL_BOOLEAN_NAME_PREFIXES,
+    ALL_BUILTIN_DICT_METHOD_NAMES,
+    ALL_CLI_FILE_PATH_MARKERS,
+    COLLECTION_BY_NAME_PATTERN,
+    ALL_COLLECTION_TYPE_NAMES,
+    ALL_SUBSCRIPT_ONLY_COLLECTION_TYPE_NAMES,
+    DOTTED_SEGMENT_PATTERN,
+    EACH_PREFIX,
+    FILE_GLOBAL_UPPER_SNAKE_PATTERN,
+    ALL_HOOK_INFRASTRUCTURE_PATTERNS,
+    ALL_IMPORT_STATEMENT_PREFIXES,
+    INLINE_COLLECTION_MIN_LENGTH,
+    ALL_JAVASCRIPT_EXTENSIONS,
+    LOGGING_FSTRING_PATTERN,
+    ALL_LOOP_INDEX_LETTER_EXEMPTIONS,
+    ALL_MIGRATION_PATH_PATTERNS,
+    NOT_INSIDE_TYPE_CHECKING_BLOCK,
+    ALL_PYTHON_EXTENSIONS,
+    ALL_SELF_AND_CLS_PARAMETER_NAMES,
+    ALL_TEST_PATH_PATTERNS,
+    TYPE_CHECKING_BLOCK_PATTERN,
+    ALL_UNION_TYPING_NAMES,
+    UPPER_SNAKE_CONSTANT_PATTERN,
+    ALL_WORKFLOW_REGISTRY_PATTERNS,
+)
 
 
 def get_file_extension(file_path: str) -> str:
@@ -109,7 +139,7 @@ def get_file_extension(file_path: str) -> str:
 def is_hook_infrastructure(file_path: str) -> bool:
     """Check if file is a Claude Code hook (standalone infrastructure, not project code)."""
     path_lower = file_path.lower().replace("\\", "/")
-    return any(pattern.replace("\\", "/") in path_lower for pattern in HOOK_INFRASTRUCTURE_PATTERNS)
+    return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_HOOK_INFRASTRUCTURE_PATTERNS)
 
 
 def is_test_file(file_path: str) -> bool:
@@ -118,7 +148,7 @@ def is_test_file(file_path: str) -> bool:
     basename_lower = path_lower.replace("\\", "/").rsplit("/", 1)[-1]
     if basename_lower == "conftest.py":
         return True
-    return any(pattern in path_lower for pattern in TEST_PATH_PATTERNS)
+    return any(pattern in path_lower for pattern in ALL_TEST_PATH_PATTERNS)
 
 
 def is_workflow_registry_file(file_path: str) -> bool:
@@ -129,7 +159,7 @@ def is_workflow_registry_file(file_path: str) -> bool:
     These are module-level singletons, not misplaced literal constants.
     """
     path_lower = file_path.lower().replace("\\", "/")
-    return any(pattern.replace("\\", "/") in path_lower for pattern in WORKFLOW_REGISTRY_PATTERNS)
+    return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_WORKFLOW_REGISTRY_PATTERNS)
 
 
 def is_spec_file(file_path: str) -> bool:
@@ -163,23 +193,26 @@ def check_comments_python(content: str) -> list[str]:
         if stripped.startswith("# pragma:"):
             continue
 
+        if stripped.startswith(("# TODO", "# FIXME", "# HACK", "# XXX")):
+            continue
+
         comment_index = line.find("#")
         if comment_index != -1:
             before_comment = line[:comment_index]
             if not before_comment.strip().startswith(("'", '"')):
-                in_string = False
+                is_in_string = False
                 quote_char = None
-                for i, char in enumerate(before_comment):
-                    if char in ("'", '"') and (i == 0 or before_comment[i - 1] != "\\"):
-                        if not in_string:
-                            in_string = True
-                            quote_char = char
-                        elif char == quote_char:
-                            in_string = False
-
-                if not in_string:
+                for i, each_char in enumerate(before_comment):
+                    if each_char in ("'", '"') and (i == 0 or before_comment[i - 1] != "\\"):
+                        if not is_in_string:
+                            is_in_string = True
+                            quote_char = each_char
+                        elif each_char == quote_char:
+                            is_in_string = False
+
+                if not is_in_string:
                     comment_text = line[comment_index + 1 :].strip()
-                    if comment_text and not comment_text.startswith(("type:", "noqa", "pylint:", "pragma:")):
+                    if comment_text and not comment_text.startswith(("type:", "noqa", "pylint:", "pragma:", "TODO", "FIXME", "HACK", "XXX")):
                         issues.append(f"Line {line_number}: Comment found - refactor to self-documenting code")
 
         if len(issues) >= 3:
@@ -192,28 +225,28 @@ def check_comments_javascript(content: str) -> list[str]:
     """Check for comments in JavaScript/TypeScript code."""
     issues = []
     lines = content.split("\n")
-    in_multiline_comment = False
+    is_in_multiline_comment = False
 
-    for line_number, line in enumerate(lines, 1):
-        stripped = line.strip()
+    for each_line_number, each_line in enumerate(lines, 1):
+        stripped = each_line.strip()
 
         if not stripped:
             continue
 
-        if in_multiline_comment:
+        if is_in_multiline_comment:
             if "*/" in stripped:
-                in_multiline_comment = False
+                is_in_multiline_comment = False
             continue
 
         if stripped.startswith("/*"):
-            in_multiline_comment = "*/" not in stripped
+            is_in_multiline_comment = "*/" not in stripped
             if not stripped.startswith("/**"):
-                issues.append(f"Line {line_number}: Block comment found - refactor to self-documenting code")
+                issues.append(f"Line {each_line_number}: Block comment found - refactor to self-documenting code")
             continue
 
         if stripped.startswith("//"):
-            if not stripped.startswith(("// @ts-", "// eslint-", "// prettier-", "/// ")):
-                issues.append(f"Line {line_number}: Comment found - refactor to self-documenting code")
+            if not stripped.startswith(("// @ts-", "// eslint-", "// prettier-", "/// ", "// TODO", "// FIXME", "// HACK", "// XXX")):
+                issues.append(f"Line {each_line_number}: Comment found - refactor to self-documenting code")
 
         if len(issues) >= 3:
             break
@@ -237,55 +270,58 @@ def extract_comment_texts(content: str, file_path: str) -> tuple[set[str], set[s
 
     lines = content.split("\n")
 
-    if extension in PYTHON_EXTENSIONS:
+    if extension in ALL_PYTHON_EXTENSIONS:
         for line in lines:
             stripped = line.strip()
             if not stripped:
                 continue
             if stripped.startswith("#"):
-                if stripped.startswith(("#!", "# type:", "# noqa", "# pylint:", "# pragma:")):
+                if stripped.startswith(("#!", "# type:", "# noqa", "# pylint:", "# pragma:", "# TODO", "# FIXME", "# HACK", "# XXX")):
                     continue
                 standalone_comments.add(stripped)
             elif "#" in line:
                 comment_index = line.find("#")
                 before_comment = line[:comment_index]
                 if not before_comment.strip().startswith(("'", '"')):
-                    in_string = False
+                    is_in_string = False
                     quote_char = None
                     for i, char in enumerate(before_comment):
                         if char in ("'", '"') and (i == 0 or before_comment[i - 1] != "\\"):
-                            if not in_string:
-                                in_string = True
+                            if not is_in_string:
+                                is_in_string = True
                                 quote_char = char
                             elif char == quote_char:
-                                in_string = False
-                    if not in_string:
+                                is_in_string = False
+                    if not is_in_string:
                         comment_text = line[comment_index + 1 :].strip()
-                        if comment_text and not comment_text.startswith(("type:", "noqa", "pylint:", "pragma:")):
+                        if comment_text and not comment_text.startswith(("type:", "noqa", "pylint:", "pragma:", "TODO", "FIXME", "HACK", "XXX")):
                             inline_comments.add(line[comment_index:].strip())
 
-    elif extension in JAVASCRIPT_EXTENSIONS:
-        in_multiline = False
+    elif extension in ALL_JAVASCRIPT_EXTENSIONS:
+        is_in_multiline = False
         for line in lines:
             stripped = line.strip()
             if not stripped:
                 continue
-            if in_multiline:
+            if is_in_multiline:
                 if "*/" in stripped:
-                    in_multiline = False
+                    is_in_multiline = False
                 continue
             if stripped.startswith("/*"):
-                in_multiline = "*/" not in stripped
+                is_in_multiline = "*/" not in stripped
                 if not stripped.startswith("/**"):
                     standalone_comments.add(stripped)
                 continue
             if stripped.startswith("//"):
-                if not stripped.startswith(("// @ts-", "// eslint-", "// prettier-", "/// ")):
+                if not stripped.startswith(("// @ts-", "// eslint-", "// prettier-", "/// ", "// TODO", "// FIXME", "// HACK", "// XXX")):
                     standalone_comments.add(stripped)
             elif "//" in line:
                 before_slash = line[:line.index("//")]
                 if before_slash.strip():
-                    inline_comments.add(stripped[stripped.index("//"):])
+                    comment_start = stripped.index("//")
+                    comment_text = stripped[comment_start + 2 :].strip()
+                    if not comment_text.startswith(("TODO", "FIXME", "HACK", "XXX")):
+                        inline_comments.add(stripped[comment_start:])
 
     return inline_comments, standalone_comments
 
@@ -349,7 +385,7 @@ def check_imports_at_top(content: str) -> list[str]:
     """
     issues: list[str] = []
     lines = content.split("\n")
-    inside_function = False
+    is_inside_function = False
     function_indent = 0
     type_checking_block_indent = NOT_INSIDE_TYPE_CHECKING_BLOCK
 
@@ -372,29 +408,22 @@ def check_imports_at_top(content: str) -> list[str]:
 
         function_match = re.match(r"^(\s*)(async\s+)?def\s+\w+", each_line)
         if function_match:
-            inside_function = True
+            is_inside_function = True
             function_indent = len(function_match.group(1)) if function_match.group(1) else 0
             continue
 
-        if inside_function:
+        if is_inside_function:
             if current_indent <= function_indent and stripped and not stripped.startswith(("#", "@", ")")):
-                inside_function = False
+                is_inside_function = False
 
         is_inside_type_checking_block = type_checking_block_indent != NOT_INSIDE_TYPE_CHECKING_BLOCK
-        if inside_function and not is_inside_type_checking_block:
-            if stripped.startswith(IMPORT_STATEMENT_PREFIXES):
+        if is_inside_function and not is_inside_type_checking_block:
+            if stripped.startswith(ALL_IMPORT_STATEMENT_PREFIXES):
                 issues.append(f"Line {line_number}: Import inside function - move to top of file")
 
     return issues
 
 
-LOGGING_FSTRING_PATTERN = re.compile(
-    r'\b(?:log_(?:debug|info|warning|error|critical|exception)'
-    r'|(?:logger|logging|log)\.(?:debug|info|warning|error|critical|exception))'
-    r'\s*\(\s*(?:[rR][fF]|[fF][rR]?)["\']'
-)
-
-
 def check_logging_fstrings(content: str) -> list[str]:
     """Check for f-strings in logging calls."""
     issues = []
@@ -482,7 +511,7 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
 
     issues = []
     lines = content.split("\n")
-    inside_function = False
+    is_inside_function = False
 
     number_pattern = re.compile(r"(?<![.\w])(\d+\.?\d*)(?![.\w])")
     allowed_numbers = {"0", "1", "-1", "0.0", "1.0"}
@@ -494,14 +523,14 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
             continue
 
         if re.match(r"^(async\s+)?def\s+\w+", stripped):
-            inside_function = True
+            is_inside_function = True
             continue
 
         if re.match(r"^class\s+\w+", stripped):
-            inside_function = False
+            is_inside_function = False
             continue
 
-        if inside_function:
+        if is_inside_function:
             if "=" in stripped and stripped.split("=")[0].strip().isupper():
                 continue
 
@@ -693,7 +722,7 @@ def _find_any_annotation_lines(source: str) -> list[int]:
 
     offending_line_numbers: list[int] = []
     already_reported_lines: set[int] = set()
-    for each_node in ast.walk(parsed_tree):
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
         if isinstance(each_node, ast.AnnAssign) and _annotation_uses_any(each_node.annotation):
             if each_node.lineno not in already_reported_lines:
                 offending_line_numbers.append(each_node.lineno)
@@ -742,20 +771,138 @@ def _find_unjustified_type_ignore_lines(source: str) -> list[int]:
     return offending_line_numbers
 
 
+def _find_typing_any_imports(source: str) -> list[int]:
+    """Return line numbers of `from typing import ... Any ...` statements."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    offending_line_numbers: list[int] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if each_node.module != "typing":
+            continue
+        for each_alias in each_node.names:
+            if each_alias.name == "Any":
+                offending_line_numbers.append(each_node.lineno)
+                break
+    return offending_line_numbers
+
+
+def _find_typing_wildcard_imports(source: str) -> list[int]:
+    """Return line numbers of `from typing import *` statements."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    offending_line_numbers: list[int] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if each_node.module != "typing":
+            continue
+        for each_alias in each_node.names:
+            if each_alias.name == "*":
+                offending_line_numbers.append(each_node.lineno)
+                break
+    return offending_line_numbers
+
+
+def _collect_typing_cast_import_names(source: str) -> frozenset[str]:
+    """Return the set of names bound to typing.cast via `from typing import cast`."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return frozenset()
+
+    cast_names: set[str] = set()
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if each_node.module != "typing":
+            continue
+        for each_alias in each_node.names:
+            if each_alias.name == "cast":
+                cast_names.add(each_alias.asname or each_alias.name)
+    return frozenset(cast_names)
+
+
+def _is_typing_cast_call(call_node: ast.Call, all_cast_import_names: frozenset[str]) -> bool:
+    """Return True when a Call node represents a typing.cast() or known bare cast()."""
+    function_node = call_node.func
+    if isinstance(function_node, ast.Attribute) and function_node.attr == "cast":
+        if isinstance(function_node.value, ast.Name) and function_node.value.id == "typing":
+            return True
+    if isinstance(function_node, ast.Name) and function_node.id in all_cast_import_names:
+        return True
+    return False
+
+
+def _find_cast_call_lines(source: str) -> list[int]:
+    """Return line numbers of cast(...) calls (typing.cast or bare cast)."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    all_cast_import_names = _collect_typing_cast_import_names(source)
+
+    offending_line_numbers: list[int] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if isinstance(each_node, ast.Call) and _is_typing_cast_call(each_node, all_cast_import_names):
+            offending_line_numbers.append(each_node.lineno)
+    return offending_line_numbers
+
+
+def _file_path_matches_any_exemption(file_path: str) -> bool:
+    filename = file_path.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    return filename in {each_pattern.lower() for each_pattern in ALL_ANY_ALLOWED_PATTERNS}
+
+
 def check_type_escape_hatches(content: str, file_path: str) -> list[str]:
-    """Flag Any annotations and unjustified # type: ignore comments."""
-    if is_test_file(file_path):
+    """Flag Any annotations, Any imports, cast() calls, and unjustified # type: ignore."""
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
         return []
 
     issues: list[str] = []
+    is_any_exempt = _file_path_matches_any_exemption(file_path)
+
+    if not is_any_exempt:
+        any_annotation_issues: list[str] = []
+        for each_any_line in _find_any_annotation_lines(content):
+            any_annotation_issues.append(f"Line {each_any_line}: Any annotation - replace with explicit type")
+        issues.extend(any_annotation_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
+
+        any_import_issues: list[str] = []
+        for each_import_line in _find_typing_any_imports(content):
+            any_import_issues.append(
+                f"Line {each_import_line}: 'from typing import Any' - remove the Any import and use explicit types"
+            )
+        issues.extend(any_import_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
 
-    for each_any_line in _find_any_annotation_lines(content):
-        issues.append(f"Line {each_any_line}: Any annotation - replace with explicit type")
+        wildcard_issues: list[str] = []
+        for each_wildcard_line in _find_typing_wildcard_imports(content):
+            wildcard_issues.append(
+                f"Line {each_wildcard_line}: 'from typing import *' wildcard import - import explicit names instead"
+            )
+        issues.extend(wildcard_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
+
+        cast_issues: list[str] = []
+        for each_cast_line in _find_cast_call_lines(content):
+            cast_issues.append(
+                f"Line {each_cast_line}: cast() call - escape hatch around the type system; use explicit types or runtime validation"
+            )
+        issues.extend(cast_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
 
+    type_ignore_issues: list[str] = []
     for each_ignore_line in _find_unjustified_type_ignore_lines(content):
-        issues.append(
+        type_ignore_issues.append(
             f"Line {each_ignore_line}: Unjustified # type: ignore - add trailing '# reason' explaining why"
         )
+    issues.extend(type_ignore_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
 
     return issues
 
@@ -763,7 +910,7 @@ def check_type_escape_hatches(content: str, file_path: str) -> list[str]:
 def is_migration_file(file_path: str) -> bool:
     """Check if file is a Django migration (must be self-contained)."""
     path_lower = file_path.lower().replace("\\", "/")
-    return any(pattern.replace("\\", "/") in path_lower for pattern in MIGRATION_PATH_PATTERNS)
+    return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_MIGRATION_PATH_PATTERNS)
 
 
 def check_constants_outside_config(content: str, file_path: str) -> list[str]:
@@ -782,8 +929,8 @@ def check_constants_outside_config(content: str, file_path: str) -> list[str]:
 
     issues = []
     lines = content.split("\n")
-    inside_function = False
-    inside_class = False
+    is_inside_function = False
+    is_inside_class = False
 
     constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
 
@@ -794,20 +941,20 @@ def check_constants_outside_config(content: str, file_path: str) -> list[str]:
             continue
 
         if re.match(r"^(async\s+)?def\s+\w+", stripped):
-            inside_function = True
+            is_inside_function = True
             continue
 
         if re.match(r"^class\s+\w+", stripped):
-            inside_class = True
-            inside_function = False
+            is_inside_class = True
+            is_inside_function = False
             continue
 
         indent = len(line) - len(line.lstrip())
         if indent == 0 and stripped and not stripped.startswith(("#", "@", ")")):
-            inside_function = False
-            inside_class = False
+            is_inside_function = False
+            is_inside_class = False
 
-        if not inside_function and not inside_class:
+        if not is_inside_function and not is_inside_class:
             match = constant_pattern.match(stripped)
             if match:
                 constant_name = match.group(1)
@@ -926,6 +1073,28 @@ def _without_parse_args_namespace_exemption(
     return [each_name for each_name in all_banned_names if each_name.id != "args"]
 
 
+def _synthesize_alias_name_node(
+    bound_identifier: str, alias_node: ast.alias
+) -> ast.Name:
+    synthetic_name = ast.Name(id=bound_identifier, ctx=ast.Store())
+    synthetic_name.lineno = alias_node.lineno
+    synthetic_name.col_offset = alias_node.col_offset
+    return synthetic_name
+
+
+def _collect_banned_names_from_import(
+    import_statement: ast.Import | ast.ImportFrom,
+) -> list[ast.Name]:
+    banned_alias_nodes: list[ast.Name] = []
+    for each_alias in import_statement.names:
+        bound_identifier = each_alias.asname or each_alias.name.split(".")[0]
+        if bound_identifier in ALL_BANNED_IDENTIFIERS:
+            banned_alias_nodes.append(
+                _synthesize_alias_name_node(bound_identifier, each_alias)
+            )
+    return banned_alias_nodes
+
+
 def _collect_banned_names_from_node(node: ast.AST) -> list[ast.Name]:
     """Return banned ast.Name nodes introduced by a single binding construct."""
     if isinstance(node, ast.Assign):
@@ -947,6 +1116,8 @@ def _collect_banned_names_from_node(node: ast.AST) -> list[ast.Name]:
     if isinstance(node, ast.NamedExpr):
         banned_names = _collect_banned_names_from_target(node.target)
         return _without_parse_args_namespace_exemption(banned_names, node.value)
+    if isinstance(node, (ast.Import, ast.ImportFrom)):
+        return _collect_banned_names_from_import(node)
     return []
 
 
@@ -978,6 +1149,795 @@ def check_banned_identifiers(content: str, file_path: str) -> list[str]:
     return issues
 
 
+
+
+def _string_constant_value(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _is_environ_attribute(node: ast.expr) -> bool:
+    if isinstance(node, ast.Attribute) and node.attr == "environ":
+        return isinstance(node.value, ast.Name) and node.value.id == "os"
+    return False
+
+
+def _environ_get_call_argument_names(call_node: ast.Call) -> list[str]:
+    function_node = call_node.func
+    if not isinstance(function_node, ast.Attribute):
+        return []
+    if function_node.attr != "get":
+        return []
+    if not _is_environ_attribute(function_node.value):
+        return []
+    if not call_node.args:
+        return []
+    first_argument = _string_constant_value(call_node.args[0])
+    return [first_argument] if first_argument is not None else []
+
+
+def _environ_subscript_key_names(subscript_node: ast.Subscript) -> list[str]:
+    if not _is_environ_attribute(subscript_node.value):
+        return []
+    key = _string_constant_value(subscript_node.slice)
+    return [key] if key is not None else []
+
+
+def _environ_membership_key_names(compare_node: ast.Compare) -> list[str]:
+    if not compare_node.ops:
+        return []
+    if not isinstance(compare_node.ops[0], (ast.In, ast.NotIn)):
+        return []
+    if not compare_node.comparators:
+        return []
+    if not _is_environ_attribute(compare_node.comparators[0]):
+        return []
+    key = _string_constant_value(compare_node.left)
+    return [key] if key is not None else []
+
+
+def _collect_test_env_variable_references(parsed_tree: ast.AST) -> list[tuple[int, str]]:
+    references: list[tuple[int, str]] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        candidate_names: list[str] = []
+        if isinstance(each_node, ast.Call):
+            candidate_names = _environ_get_call_argument_names(each_node)
+        elif isinstance(each_node, ast.Subscript):
+            candidate_names = _environ_subscript_key_names(each_node)
+        elif isinstance(each_node, ast.Compare):
+            candidate_names = _environ_membership_key_names(each_node)
+        for each_candidate_name in candidate_names:
+            if each_candidate_name in ALL_TEST_INDICATING_ENVIRONMENT_VARIABLE_NAMES:
+                references.append((each_node.lineno, each_candidate_name))
+    return references
+
+
+def check_test_branching_in_production(content: str, file_path: str) -> list[str]:
+    """Flag production code that branches on TESTING-style env vars.
+
+    Production code reading TESTING / PYTEST_CURRENT_TEST creates two
+    parallel implementations and hides bugs. Use dependency injection
+    (override the dependency in tests) instead.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    references = _collect_test_env_variable_references(parsed_tree)
+    references.sort(key=lambda each_reference: each_reference[0])
+
+    issues: list[str] = []
+    already_reported_lines: set[int] = set()
+    for each_line_number, each_variable_name in references:
+        if each_line_number in already_reported_lines:
+            continue
+        already_reported_lines.add(each_line_number)
+        issues.append(
+            f"Line {each_line_number}: Production code reads test indicator '{each_variable_name}' — "
+            "use dependency injection so production stays single-path"
+        )
+        if len(issues) >= MAX_TEST_BRANCHING_ISSUES:
+            break
+
+    return issues
+
+
+def _bare_except_handler_label(handler_node: ast.ExceptHandler) -> str | None:
+    """Return a label for handlers we flag, or None for safe handlers."""
+    handler_type = handler_node.type
+    if handler_type is None:
+        return "bare except:"
+    if isinstance(handler_type, ast.Name) and handler_type.id in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES:
+        return f"except {handler_type.id}:"
+    if (
+        isinstance(handler_type, ast.Attribute)
+        and handler_type.attr in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES
+    ):
+        return f"except {handler_type.attr}:"
+    if isinstance(handler_type, ast.Tuple):
+        banned_names: list[str] = []
+        for each_element in handler_type.elts:
+            if isinstance(each_element, ast.Name) and each_element.id in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES:
+                banned_names.append(each_element.id)
+            elif (
+                isinstance(each_element, ast.Attribute)
+                and each_element.attr in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES
+            ):
+                banned_names.append(each_element.attr)
+        if banned_names:
+            return f"except {', '.join(banned_names)} (in tuple):"
+    return None
+
+
+def check_bare_except(content: str, file_path: str) -> list[str]:
+    """Flag bare/over-broad exception handlers in production code.
+
+    ``except:`` and ``except BaseException:`` swallow KeyboardInterrupt and
+    SystemExit; ``except Exception:`` hides bugs by catching nearly every
+    error class. Production code should name the specific exception(s) it
+    intends to catch
+    (a tuple form like `except (ValueError, KeyError):` is fine).
+    """
+    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.ExceptHandler):
+            continue
+        handler_label = _bare_except_handler_label(each_node)
+        if handler_label is None:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {handler_label} is over-broad — name the "
+            "specific exception(s) you intend to handle"
+        )
+        if len(issues) >= MAX_BARE_EXCEPT_ISSUES:
+            break
+    return issues
+
+
+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:
+    return (
+        isinstance(statement_node, ast.Expr)
+        and isinstance(statement_node.value, ast.Constant)
+        and isinstance(statement_node.value.value, str)
+    )
+
+
+def _statement_is_dunder_all_assignment(statement_node: ast.stmt) -> bool:
+    if isinstance(statement_node, ast.Assign):
+        for each_target in statement_node.targets:
+            if isinstance(each_target, ast.Name) and each_target.id == "__all__":
+                return True
+        return False
+    if isinstance(statement_node, ast.AnnAssign):
+        target = statement_node.target
+        return isinstance(target, ast.Name) and target.id == "__all__"
+    return False
+
+
+def _statement_is_import_or_reexport(statement_node: ast.stmt) -> bool:
+    if isinstance(statement_node, (ast.Import, ast.ImportFrom)):
+        return True
+    if _statement_is_dunder_all_assignment(statement_node):
+        return True
+    return False
+
+
+def check_thin_wrapper_files(content: str, file_path: str) -> list[str]:
+    """Flag non-`__init__.py` modules that are only imports + `__all__`.
+
+    A re-export-only wrapper outside `__init__.py` forces callers through an
+    indirection layer with no payload of its own. Callers should import from
+    the real module. `__init__.py` is the canonical re-export surface and is
+    exempt; test files, hook infrastructure, and `config/` are also exempt.
+    """
+    if (
+        is_test_file(file_path)
+        or is_hook_infrastructure(file_path)
+        or is_config_file(file_path)
+        or _is_init_file(file_path)
+    ):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    body_statements = list(parsed_tree.body)
+    if not body_statements:
+        return []
+
+    statements_after_docstring = (
+        body_statements[1:]
+        if _statement_is_module_docstring(body_statements[0])
+        else body_statements
+    )
+    if not statements_after_docstring:
+        return []
+
+    for each_statement in statements_after_docstring:
+        if not _statement_is_import_or_reexport(each_statement):
+            return []
+
+    issues = [
+        f"Line 1: {file_path}: thin wrapper file — module body is only imports (optionally with __all__); "
+        "callers should import from the real module instead of going through this indirection"
+    ]
+    return issues[:MAX_THIN_WRAPPER_ISSUES]
+
+
+def _annotation_node_references_any(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    for each_descendant in ast.walk(annotation_node):
+        if isinstance(each_descendant, ast.Name) and each_descendant.id == "Any":
+            return True
+        if isinstance(each_descendant, ast.Attribute) and each_descendant.attr == "Any":
+            return True
+    return False
+
+
+def _file_has_exempt_boundary_filename(file_path: str) -> bool:
+    filename = file_path.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    return filename in {each_name.lower() for each_name in ALL_BOUNDARY_TYPE_EXEMPT_FILENAMES}
+
+
+def _signature_annotations(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[
+    tuple[ast.expr, str, int]
+]:
+    collected_annotations: list[tuple[ast.expr, str, int]] = []
+    function_name = function_node.name
+    for each_argument in function_node.args.args:
+        if each_argument.annotation is not None:
+            collected_annotations.append(
+                (each_argument.annotation, f"{function_name}({each_argument.arg})", each_argument.lineno)
+            )
+    for each_argument in function_node.args.posonlyargs:
+        if each_argument.annotation is not None:
+            collected_annotations.append(
+                (each_argument.annotation, f"{function_name}({each_argument.arg})", each_argument.lineno)
+            )
+    for each_argument in function_node.args.kwonlyargs:
+        if each_argument.annotation is not None:
+            collected_annotations.append(
+                (each_argument.annotation, f"{function_name}({each_argument.arg})", each_argument.lineno)
+            )
+    if function_node.args.vararg is not None and function_node.args.vararg.annotation is not None:
+        collected_annotations.append(
+            (function_node.args.vararg.annotation, f"{function_name}(*{function_node.args.vararg.arg})", function_node.args.vararg.lineno)
+        )
+    if function_node.args.kwarg is not None and function_node.args.kwarg.annotation is not None:
+        collected_annotations.append(
+            (function_node.args.kwarg.annotation, f"{function_name}(**{function_node.args.kwarg.arg})", function_node.args.kwarg.lineno)
+        )
+    if function_node.returns is not None:
+        collected_annotations.append(
+            (function_node.returns, f"{function_name} -> return", function_node.returns.lineno)
+        )
+    return collected_annotations
+
+
+def _class_attribute_annotations(class_node: ast.ClassDef) -> list[tuple[ast.expr, str, int]]:
+    collected_annotations: list[tuple[ast.expr, str, int]] = []
+    for each_statement in class_node.body:
+        if isinstance(each_statement, ast.AnnAssign) and isinstance(each_statement.target, ast.Name):
+            collected_annotations.append(
+                (
+                    each_statement.annotation,
+                    f"{class_node.name}.{each_statement.target.id}",
+                    each_statement.lineno,
+                )
+            )
+    return collected_annotations
+
+
+def check_boundary_types(content: str, file_path: str) -> list[str]:
+    """Flag `Any` appearing in function signatures or class attribute annotations.
+
+    Module boundaries (function parameters, return types, class attributes)
+    must name the concrete shape they accept and produce. Local variable
+    annotations are private and exempt; `protocols.py` and `types.py` are
+    interface-declaration files and exempt.
+    """
+    if (
+        is_test_file(file_path)
+        or is_hook_infrastructure(file_path)
+        or _file_has_exempt_boundary_filename(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 isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for each_annotation, each_label, each_line_number in _signature_annotations(each_node):
+                if _annotation_node_references_any(each_annotation):
+                    issues.append(
+                        f"Line {each_line_number}: {each_label} uses Any at module boundary — "
+                        "name the concrete shape callers receive/produce"
+                    )
+        elif isinstance(each_node, ast.ClassDef):
+            for each_annotation, each_label, each_line_number in _class_attribute_annotations(each_node):
+                if _annotation_node_references_any(each_annotation):
+                    issues.append(
+                        f"Line {each_line_number}: {each_label} uses Any at class boundary — "
+                        "name the concrete shape this attribute holds"
+                    )
+        if len(issues) >= MAX_BOUNDARY_TYPE_ISSUES:
+            break
+    return issues[:MAX_BOUNDARY_TYPE_ISSUES]
+
+
+def _function_is_private_or_dunder(function_name: str) -> bool:
+    if function_name.startswith("__") and function_name.endswith("__"):
+        return True
+    return function_name.startswith("_")
+
+
+def _decorator_label(decorator_node: ast.expr) -> str:
+    if isinstance(decorator_node, ast.Name):
+        return decorator_node.id
+    if isinstance(decorator_node, ast.Attribute):
+        prefix = (
+            decorator_node.value.id
+            if isinstance(decorator_node.value, ast.Name)
+            else ""
+        )
+        return f"{prefix}.{decorator_node.attr}" if prefix else decorator_node.attr
+    if isinstance(decorator_node, ast.Call):
+        return _decorator_label(decorator_node.func)
+    return ""
+
+
+def _function_has_exempt_decorator(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    for each_decorator in function_node.decorator_list:
+        if _decorator_label(each_decorator) in ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES:
+            return True
+    return False
+
+
+def _function_body_line_count(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> int:
+    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 len(function_node.body) == 1:
+            return 0
+        first_body_index = 1
+    last_statement = function_node.body[-1]
+    end_line = getattr(last_statement, "end_lineno", last_statement.lineno)
+    first_line = function_node.body[first_body_index].lineno
+    return max(0, end_line - first_line + 1)
+
+
+def _function_documentable_parameter_count(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> int:
+    documentable_count = 0
+    for each_argument in function_node.args.args:
+        if each_argument.arg in ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES:
+            continue
+        documentable_count += 1
+    documentable_count += len(function_node.args.kwonlyargs)
+    for each_argument in function_node.args.posonlyargs:
+        if each_argument.arg in ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES:
+            continue
+        documentable_count += 1
+    if function_node.args.vararg is not None:
+        documentable_count += 1
+    if function_node.args.kwarg is not None:
+        documentable_count += 1
+    return documentable_count
+
+
+def _annotation_is_explicit_none_return(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Constant) and annotation_node.value is None:
+        return True
+    return isinstance(annotation_node, ast.Name) and annotation_node.id == "None"
+
+
+def _annotation_is_noreturn(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Name) and annotation_node.id == "NoReturn":
+        return True
+    return isinstance(annotation_node, ast.Attribute) and annotation_node.attr == "NoReturn"
+
+
+def _walk_skipping_nested_functions(node: ast.AST) -> "Iterator[ast.AST]":
+    for each_child in ast.iter_child_nodes(node):
+        if isinstance(each_child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        yield each_child
+        yield from _walk_skipping_nested_functions(each_child)
+
+
+def _is_type_checking_guard(if_node: ast.If) -> bool:
+    test_node = if_node.test
+    if isinstance(test_node, ast.Name) and test_node.id == TYPE_CHECKING_IDENTIFIER:
+        return True
+    return isinstance(test_node, ast.Attribute) and test_node.attr == TYPE_CHECKING_IDENTIFIER
+
+
+def _walk_skipping_type_checking_blocks(node: ast.AST) -> "Iterator[ast.AST]":
+    for each_child in ast.iter_child_nodes(node):
+        if isinstance(each_child, ast.If) and _is_type_checking_guard(each_child):
+            continue
+        yield each_child
+        yield from _walk_skipping_type_checking_blocks(each_child)
+
+
+def _function_body_contains_raise(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    return any(
+        isinstance(each_descendant, ast.Raise)
+        for each_descendant in _walk_skipping_nested_functions(function_node)
+    )
+
+
+def _function_body_contains_yield(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    return any(
+        isinstance(each_descendant, (ast.Yield, ast.YieldFrom))
+        for each_descendant in _walk_skipping_nested_functions(function_node)
+    )
+
+
+def _function_docstring_text(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> str:
+    docstring_value = ast.get_docstring(function_node)
+    return docstring_value or ""
+
+
+def _missing_docstring_sections(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[str]:
+    docstring_text = _function_docstring_text(function_node)
+    documentable_parameter_count = _function_documentable_parameter_count(function_node)
+    has_non_none_return = (
+        function_node.returns is not None
+        and not _annotation_is_explicit_none_return(function_node.returns)
+        and not _annotation_is_noreturn(function_node.returns)
+    )
+    has_raise_statement = _function_body_contains_raise(function_node)
+    has_yield_statement = _function_body_contains_yield(function_node)
+    missing_sections: list[str] = []
+    if documentable_parameter_count > 0 and "Args:" not in docstring_text:
+        missing_sections.append("Args:")
+    if has_non_none_return and not (
+        "Returns:" in docstring_text or "Yields:" in docstring_text
+    ):
+        section_label = "Yields:" if has_yield_statement else "Returns:"
+        missing_sections.append(section_label)
+    if has_raise_statement and "Raises:" not in docstring_text:
+        missing_sections.append("Raises:")
+    return missing_sections
+
+
+def check_docstring_format(content: str, file_path: str) -> list[str]:
+    """Flag public functions missing required Google-style docstring sections.
+
+    A public function whose signature has documentable parameters, returns
+    a non-None value, or raises must have the matching `Args:` / `Returns:`
+    (or `Yields:`) / `Raises:` sections so callers can read the contract
+    without scanning the body.
+    """
+    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
+        missing_sections = _missing_docstring_sections(each_node)
+        if not missing_sections:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring missing required "
+            f"section(s): {', '.join(missing_sections)} — Google style required for public APIs"
+        )
+        if len(issues) >= MAX_DOCSTRING_FORMAT_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_FORMAT_ISSUES]
+
+
+_PASCAL_TO_SNAKE_WORD_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+
+
+def _pascal_to_snake_case(pascal_name: str) -> str:
+    return _PASCAL_TO_SNAKE_WORD_BOUNDARY.sub("_", pascal_name).lower()
+
+
+def _class_inherits_from_typed_dict(class_node: ast.ClassDef) -> bool:
+    for each_base in class_node.bases:
+        if isinstance(each_base, ast.Name) and each_base.id == "TypedDict":
+            return True
+        if isinstance(each_base, ast.Attribute) and each_base.attr == "TypedDict":
+            return True
+    return False
+
+
+def _collect_typed_dict_class_names(parsed_tree: ast.AST) -> list[tuple[str, int]]:
+    typed_dict_entries: list[tuple[str, int]] = []
+    for each_statement in parsed_tree.body:
+        if isinstance(each_statement, ast.ClassDef) and _class_inherits_from_typed_dict(each_statement):
+            typed_dict_entries.append((each_statement.name, each_statement.lineno))
+    return typed_dict_entries
+
+
+def _collect_module_function_names(parsed_tree: ast.AST) -> set[str]:
+    module_function_names: set[str] = set()
+    for each_statement in parsed_tree.body:
+        if isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            module_function_names.add(each_statement.name)
+    return module_function_names
+
+
+def check_typed_dict_encode_decode(content: str, file_path: str) -> list[str]:
+    """Flag TypedDict declarations missing companion `_encode_*` / `_decode_*` functions."""
+    if (
+        is_test_file(file_path)
+        or is_hook_infrastructure(file_path)
+        or _is_init_file(file_path)
+    ):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    typed_dict_entries = _collect_typed_dict_class_names(parsed_tree)
+    if not typed_dict_entries:
+        return []
+
+    module_function_names = _collect_module_function_names(parsed_tree)
+
+    issues: list[str] = []
+    for each_typed_dict_name, each_typed_dict_line in typed_dict_entries:
+        snake_name = _pascal_to_snake_case(each_typed_dict_name)
+        encoder_function_name = f"_encode_{snake_name}"
+        decoder_function_name = f"_decode_{snake_name}"
+        is_encoder_present = encoder_function_name in module_function_names
+        is_decoder_present = decoder_function_name in module_function_names
+        if is_encoder_present and is_decoder_present:
+            continue
+        missing_companions: list[str] = []
+        if not is_encoder_present:
+            missing_companions.append(encoder_function_name)
+        if not is_decoder_present:
+            missing_companions.append(decoder_function_name)
+        issues.append(
+            f"Line {each_typed_dict_line}: TypedDict '{each_typed_dict_name}' missing companion "
+            f"{' and '.join(missing_companions)} — add explicit encode/decode functions"
+        )
+        if len(issues) >= MAX_TYPED_DICT_PAIR_ISSUES:
+            break
+
+    return issues
+
+
+def _function_decorator_is_abstractmethod(decorator_node: ast.expr) -> bool:
+    if isinstance(decorator_node, ast.Name) and decorator_node.id == "abstractmethod":
+        return True
+    if isinstance(decorator_node, ast.Attribute) and decorator_node.attr == "abstractmethod":
+        return True
+    return False
+
+
+def _function_is_abstract(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return any(
+        _function_decorator_is_abstractmethod(each_decorator)
+        for each_decorator in function_node.decorator_list
+    )
+
+
+def _function_is_overload(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    for each_decorator in function_node.decorator_list:
+        if isinstance(each_decorator, ast.Name) and each_decorator.id == "overload":
+            return True
+        if isinstance(each_decorator, ast.Attribute) and each_decorator.attr == "overload":
+            return True
+    return False
+
+
+def _class_is_protocol(class_node: ast.ClassDef) -> bool:
+    for each_base in class_node.bases:
+        if isinstance(each_base, ast.Name) and each_base.id == "Protocol":
+            return True
+        if isinstance(each_base, ast.Attribute) and each_base.attr == "Protocol":
+            return True
+    return False
+
+
+def _class_inherits_from_protocol_or_abc(class_node: ast.ClassDef) -> bool:
+    for each_base in class_node.bases:
+        if isinstance(each_base, ast.Name) and each_base.id in {"Protocol", "ABC"}:
+            return True
+        if isinstance(each_base, ast.Attribute) and each_base.attr in {"Protocol", "ABC"}:
+            return True
+    return False
+
+
+
+
+
+
+def _statement_is_pass(statement_node: ast.stmt) -> bool:
+    return isinstance(statement_node, ast.Pass)
+
+
+def _statement_is_ellipsis(statement_node: ast.stmt) -> bool:
+    return (
+        isinstance(statement_node, ast.Expr)
+        and isinstance(statement_node.value, ast.Constant)
+        and statement_node.value.value is Ellipsis
+    )
+
+
+def _statement_is_raise_not_implemented(statement_node: ast.stmt) -> bool:
+    if not isinstance(statement_node, ast.Raise):
+        return False
+    raised_expression = statement_node.exc
+    if raised_expression is None:
+        return False
+    if isinstance(raised_expression, ast.Name) and raised_expression.id == "NotImplementedError":
+        return True
+    if (
+        isinstance(raised_expression, ast.Call)
+        and isinstance(raised_expression.func, ast.Name)
+        and raised_expression.func.id == "NotImplementedError"
+    ):
+        return True
+    return False
+
+
+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]):
+        body_statements = body_statements[1:]
+    if len(body_statements) != 1:
+        return False
+    sole_statement = body_statements[0]
+    return (
+        _statement_is_pass(sole_statement)
+        or _statement_is_ellipsis(sole_statement)
+        or _statement_is_raise_not_implemented(sole_statement)
+    )
+
+
+def check_stub_implementations(content: str, file_path: str) -> list[str]:
+    """Flag production functions whose body is only pass/.../raise NotImplementedError.
+
+    Stubs ship as placeholders that the rest of the system depends on but the
+    function does not deliver. ABC/Protocol abstract methods are exempt — they
+    are placeholders BY contract, not by oversight.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    abstract_class_function_ids: set[int] = set()
+    for each_node in ast.walk(parsed_tree):
+        if isinstance(each_node, ast.ClassDef) and _class_inherits_from_protocol_or_abc(each_node):
+            is_protocol = _class_is_protocol(each_node)
+            for each_class_member in each_node.body:
+                if not isinstance(each_class_member, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                if is_protocol or _function_is_abstract(each_class_member):
+                    abstract_class_function_ids.add(id(each_class_member))
+
+    stub_function_nodes: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_abstract(each_node) or _function_is_overload(each_node):
+            continue
+        if id(each_node) in abstract_class_function_ids:
+            continue
+        if _function_body_is_stub(each_node):
+            stub_function_nodes.append(each_node)
+
+    stub_function_nodes.sort(key=lambda each_function: each_function.lineno)
+
+    issues: list[str] = []
+    for each_function in stub_function_nodes:
+        issues.append(
+            f"Line {each_function.lineno}: Function '{each_function.name}' is a stub "
+            "(pass/.../raise NotImplementedError) — implement or remove"
+        )
+        if len(issues) >= MAX_STUB_IMPLEMENTATION_ISSUES:
+            break
+
+    return issues
+
+
+def check_banned_prefixes(content: str, file_path: str) -> list[str]:
+    """Flag function and method names using generic banned prefixes.
+
+    Per CODE_RULES.md / AGENTS.md Naming, function names use specific verbs.
+    Generic prefixes ``handle_``, ``process_``, ``manage_``, ``do_`` are
+    placeholders that hide the actual responsibility and are flagged so the
+    author renames the function to a specific verb.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path) or is_config_file(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    flagged_function_nodes: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if any(each_node.name.startswith(each_prefix) for each_prefix in ALL_BANNED_PREFIX_NAMES):
+            flagged_function_nodes.append(each_node)
+
+    flagged_function_nodes.sort(key=lambda each_function: each_function.lineno)
+
+    issues: list[str] = []
+    for each_function in flagged_function_nodes:
+        issues.append(
+            f"Line {each_function.lineno}: Function '{each_function.name}' uses banned prefix - "
+            "rename to a specific verb (see CODE_RULES Naming section)"
+        )
+        if len(issues) >= MAX_BANNED_PREFIX_ISSUES:
+            break
+
+    return issues
+
+
 def _is_bool_constant(node: ast.AST) -> bool:
     return isinstance(node, ast.Constant) and isinstance(node.value, bool)
 
@@ -1099,7 +2059,7 @@ def check_boolean_naming(content: str, file_path: str) -> list[str]:
             continue
         if is_in_upper_snake_scope and UPPER_SNAKE_CONSTANT_PATTERN.match(name):
             continue
-        if name.startswith(BOOLEAN_NAME_PREFIXES):
+        if name.startswith(ALL_BOOLEAN_NAME_PREFIXES):
             continue
         issues.append(
             f"Line {line_number}: Boolean {name} - prefix with is_/has_/should_/can_"
@@ -1385,7 +2345,7 @@ def check_file_global_constants_use_count(content: str, file_path: str) -> list[
         return []
     if is_config_file(file_path):
         return []
-    if get_file_extension(file_path) not in PYTHON_EXTENSIONS:
+    if get_file_extension(file_path) not in ALL_PYTHON_EXTENSIONS:
         return []
     if file_path.replace("\\", "/").endswith("hooks/blocking/code_rules_enforcer.py"):
         return []
@@ -1445,9 +2405,9 @@ def _collect_optional_param_defaults(
 _NON_LITERAL_DEFAULT_SENTINEL = object()
 
 
-def _is_non_literal_default(value: object) -> bool:
+def _is_non_literal_default(candidate_default: object) -> bool:
     """Return True when a value is the sentinel for a non-literal default."""
-    return value is _NON_LITERAL_DEFAULT_SENTINEL
+    return candidate_default is _NON_LITERAL_DEFAULT_SENTINEL
 
 
 def _ast_constant_value(node: ast.expr) -> object:
@@ -1536,12 +2496,6 @@ def _function_name_from_call(call_node: ast.Call) -> str | None:
     return None
 
 
-BUILTIN_DICT_METHOD_NAMES: frozenset[str] = frozenset({
-    "get", "items", "keys", "values", "update", "pop",
-    "setdefault", "copy", "clear",
-})
-
-
 def _collect_mock_dict_keys(assign_value: ast.expr) -> set[str] | None:
     """Return the string key set for a dict literal, or None if not a dict literal."""
     if not isinstance(assign_value, ast.Dict):
@@ -1695,7 +2649,7 @@ def _collect_mock_field_accesses_in_scope(
         if isinstance(each_node, ast.Attribute):
             if isinstance(each_node.value, ast.Name) and each_node.value.id == mock_name:
                 if isinstance(each_node.ctx, ast.Load):
-                    if each_node.attr in BUILTIN_DICT_METHOD_NAMES:
+                    if each_node.attr in ALL_BUILTIN_DICT_METHOD_NAMES:
                         continue
                     accesses.append((each_node.attr, each_node.lineno))
         elif isinstance(each_node, ast.Subscript):
@@ -1966,16 +2920,15 @@ def check_unused_optional_parameters(content: str, file_path: str) -> list[str]:
     return issues
 
 
-UNION_TYPING_NAMES: frozenset[str] = frozenset({"Optional", "Union"})
 
 
 def _annotation_names_collection(annotation_node: ast.expr | None) -> bool:
     if annotation_node is None:
         return False
     if isinstance(annotation_node, ast.Name):
-        return annotation_node.id in COLLECTION_TYPE_NAMES
+        return annotation_node.id in ALL_COLLECTION_TYPE_NAMES
     if isinstance(annotation_node, ast.Attribute):
-        return annotation_node.attr in COLLECTION_TYPE_NAMES
+        return annotation_node.attr in ALL_COLLECTION_TYPE_NAMES
     if isinstance(annotation_node, ast.BinOp) and isinstance(annotation_node.op, ast.BitOr):
         return (
             _annotation_names_collection(annotation_node.left)
@@ -1984,8 +2937,8 @@ def _annotation_names_collection(annotation_node: ast.expr | None) -> bool:
     if isinstance(annotation_node, ast.Subscript):
         outer_value = annotation_node.value
         is_optional_or_union_subscript = (
-            (isinstance(outer_value, ast.Name) and outer_value.id in UNION_TYPING_NAMES)
-            or (isinstance(outer_value, ast.Attribute) and outer_value.attr in UNION_TYPING_NAMES)
+            (isinstance(outer_value, ast.Name) and outer_value.id in ALL_UNION_TYPING_NAMES)
+            or (isinstance(outer_value, ast.Attribute) and outer_value.attr in ALL_UNION_TYPING_NAMES)
         )
         if is_optional_or_union_subscript:
             slice_node = annotation_node.slice
@@ -1995,6 +2948,12 @@ def _annotation_names_collection(annotation_node: ast.expr | None) -> bool:
                     for each_element in slice_node.elts
                 )
             return _annotation_names_collection(slice_node)
+        is_subscript_only_collection_type = (
+            (isinstance(outer_value, ast.Name) and outer_value.id in ALL_SUBSCRIPT_ONLY_COLLECTION_TYPE_NAMES)
+            or (isinstance(outer_value, ast.Attribute) and outer_value.attr in ALL_SUBSCRIPT_ONLY_COLLECTION_TYPE_NAMES)
+        )
+        if is_subscript_only_collection_type:
+            return True
         return _annotation_names_collection(outer_value)
     return False
 
@@ -2675,7 +3634,7 @@ def check_unused_module_level_imports(
 
 def _is_cli_entry_point(file_path: str) -> bool:
     path_lower = file_path.lower().replace("\\", "/")
-    return any(marker.replace("\\", "/") in path_lower for marker in CLI_FILE_PATH_MARKERS)
+    return any(marker.replace("\\", "/") in path_lower for marker in ALL_CLI_FILE_PATH_MARKERS)
 
 
 def check_library_print(content: str, file_path: str) -> list[str]:
@@ -2683,7 +3642,7 @@ def check_library_print(content: str, file_path: str) -> list[str]:
         return []
     if _is_cli_entry_point(file_path):
         return []
-    if get_file_extension(file_path) not in PYTHON_EXTENSIONS:
+    if get_file_extension(file_path) not in ALL_PYTHON_EXTENSIONS:
         return []
     try:
         tree = ast.parse(content)
@@ -2708,13 +3667,6 @@ def check_library_print(content: str, file_path: str) -> list[str]:
     return issues
 
 
-SELF_AND_CLS_PARAMETER_NAMES: frozenset[str] = frozenset({"self", "cls"})
-LOOP_INDEX_LETTER_EXEMPTIONS: frozenset[str] = frozenset({"i", "j", "k", "_"})
-EACH_PREFIX = "each_"
-BARE_EACH_TOKEN = "each"
-INLINE_COLLECTION_MIN_LENGTH = 3
-ALL_CAPS_WITH_UNDERSCORE_PATTERN = re.compile(r"^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$")
-DOTTED_SEGMENT_PATTERN = re.compile(r"^\.[a-z][a-z0-9_]*$")
 
 
 def _is_magic_string_literal(string_value: str) -> bool:
@@ -2850,6 +3802,58 @@ def check_inline_literal_collections(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def check_inline_tuple_string_magic(content: str, file_path: str) -> list[str]:
+    """Flag inline two-tuple literals whose first element is a snake_case string.
+
+    Catches the pattern ``("kept", "Unknown status")`` and similar
+    column-name/key-value pairs declared inside function bodies. Files under
+    ``config/`` and test files are exempt because that is where named
+    constants are expected to live.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_config_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    snake_case_pattern = re.compile(SNAKE_CASE_LITERAL_PATTERN)
+    issues: list[str] = []
+    seen_tuple_node_ids: set[int] = set()
+    for each_function_node in ast.walk(tree):
+        if not isinstance(each_function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in each_function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, ast.Tuple):
+                    continue
+                if id(each_descendant) in seen_tuple_node_ids:
+                    continue
+                seen_tuple_node_ids.add(id(each_descendant))
+                if len(each_descendant.elts) != EXPECTED_TUPLE_PAIR_LENGTH:
+                    continue
+                first_element = each_descendant.elts[0]
+                if not isinstance(first_element, ast.Constant):
+                    continue
+                if not isinstance(first_element.value, str):
+                    continue
+                literal_text = first_element.value
+                if not snake_case_pattern.match(literal_text):
+                    continue
+                if literal_text in ALL_SNAKE_CASE_KEYWORD_EXEMPTIONS:
+                    continue
+                issues.append(
+                    f"Line {first_element.lineno}: Column-name string magic "
+                    f"{literal_text!r} - {INLINE_TUPLE_STRING_MAGIC_MESSAGE_SUFFIX}"
+                )
+                if len(issues) >= MAX_INLINE_TUPLE_STRING_MAGIC_ISSUES:
+                    return issues
+    return issues
+
+
 def check_loop_variable_naming(content: str, file_path: str) -> list[str]:
     if is_test_file(file_path):
         return []
@@ -2865,7 +3869,7 @@ def check_loop_variable_naming(content: str, file_path: str) -> list[str]:
             continue
         for each_name_node in _collect_target_names(node.target):
             target_name = each_name_node.id
-            if target_name in LOOP_INDEX_LETTER_EXEMPTIONS:
+            if target_name in ALL_LOOP_INDEX_LETTER_EXEMPTIONS:
                 continue
             if target_name == BARE_EACH_TOKEN:
                 issues.append(
@@ -2895,7 +3899,7 @@ def check_parameter_annotations(content: str, file_path: str) -> list[str]:
         if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
         for each_arg in _collect_annotated_arguments(node):
-            if each_arg.arg in SELF_AND_CLS_PARAMETER_NAMES:
+            if each_arg.arg in ALL_SELF_AND_CLS_PARAMETER_NAMES:
                 continue
             if each_arg.annotation is None:
                 issues.append(
@@ -2946,8 +3950,9 @@ def validate_content(
     """
     extension = get_file_extension(file_path)
     all_issues = []
+    effective_content = content if full_file_content is None else full_file_content
 
-    if extension in PYTHON_EXTENSIONS:
+    if extension in ALL_PYTHON_EXTENSIONS:
         if not is_test_file(file_path):
             all_issues.extend(check_comment_changes(old_content, content, file_path))
         all_issues.extend(check_imports_at_top(content))
@@ -2958,8 +3963,16 @@ def validate_content(
         all_issues.extend(check_constants_outside_config(content, file_path))
         all_issues.extend(check_constants_outside_config_advisory(content, file_path))
         all_issues.extend(check_file_global_constants_use_count(content, file_path))
-        all_issues.extend(check_type_escape_hatches(content, file_path))
+        all_issues.extend(check_type_escape_hatches(effective_content, file_path))
         all_issues.extend(check_banned_identifiers(content, file_path))
+        all_issues.extend(check_banned_prefixes(effective_content, file_path))
+        all_issues.extend(check_stub_implementations(effective_content, file_path))
+        all_issues.extend(check_typed_dict_encode_decode(effective_content, file_path))
+        all_issues.extend(check_test_branching_in_production(effective_content, file_path))
+        all_issues.extend(check_bare_except(effective_content, file_path))
+        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_skip_decorators_in_tests(content, file_path))
         all_issues.extend(check_existence_check_tests(content, file_path))
@@ -2977,11 +3990,12 @@ def validate_content(
         all_issues.extend(check_return_annotations(content, file_path))
         all_issues.extend(check_loop_variable_naming(content, file_path))
         all_issues.extend(check_inline_literal_collections(content, file_path))
+        all_issues.extend(check_inline_tuple_string_magic(content, file_path))
         all_issues.extend(check_string_literal_magic(content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)
 
-    elif extension in JAVASCRIPT_EXTENSIONS:
+    elif extension in ALL_JAVASCRIPT_EXTENSIONS:
         if not is_test_file(file_path):
             all_issues.extend(check_comment_changes(old_content, content, file_path))
         all_issues.extend(check_e2e_test_naming(content, file_path))
@@ -3062,14 +4076,14 @@ def main() -> None:
 
     if issues:
         issue_list = "; ".join(issues[:10])
-        result = {
+        deny_payload = {
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "deny",
                 "permissionDecisionReason": f"BLOCKED: [CODE_RULES] {len(issues)} violation(s): {issue_list}",
             }
         }
-        print(json.dumps(result))
+        print(json.dumps(deny_payload))
         sys.stdout.flush()
 
     sys.exit(0)