claude-dev-env 1.34.1 → 1.36.0

package/hooks/blocking/code_rules_enforcer.py

@@ -28,14 +28,44 @@ import json
 import re
 import sys
 import tokenize
+from collections.abc import Iterator
 from pathlib import Path
 from typing import Optional
 
 _BLOCKING_DIR = str(Path(__file__).resolve().parent)
+_HOOKS_DIR = str(Path(__file__).resolve().parent.parent)
 if _BLOCKING_DIR not in sys.path:
     sys.path.insert(0, _BLOCKING_DIR)
+if _HOOKS_DIR not in sys.path:
+    sys.path.insert(0, _HOOKS_DIR)
 
 from code_rules_path_utils import is_config_file  # noqa: E402
+from config.banned_identifiers_constants import (  # noqa: E402
+    ALL_BANNED_IDENTIFIERS,
+    BANNED_IDENTIFIER_MESSAGE_SUFFIX,
+    BANNED_IDENTIFIER_SKIP_ADVISORY,
+    MAX_BANNED_IDENTIFIER_ISSUES,
+)
+from config.hardcoded_user_path_constants import (  # noqa: E402
+    HARDCODED_USER_PATH_GUIDANCE,
+    HARDCODED_USER_PATH_PATTERN,
+    MAX_HARDCODED_USER_PATH_ISSUES,
+)
+from config.stuttering_check_config import (  # noqa: E402
+    MAX_STUTTERING_PREFIX_ISSUES,
+    STUTTERING_ALL_PREFIX_PATTERN,
+)
+from config.sys_path_insert_constants import MAX_SYS_PATH_INSERT_ISSUES, SYS_PATH_INSERT_GUIDANCE  # noqa: E402
+from config.unused_module_import_constants import (  # noqa: E402
+    MAX_UNUSED_IMPORT_ISSUES,
+    TYPE_CHECKING_IDENTIFIER,
+    UNUSED_IMPORT_GUIDANCE,
+)
+from config.stuttering_import_binding_constants import (  # noqa: E402
+    AST_LINENO_ATTRIBUTE,
+    MODULE_PATH_SEPARATOR,
+    WILDCARD_IMPORT_SENTINEL,
+)
 
 PYTHON_EXTENSIONS = {".py"}
 JAVASCRIPT_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx"}
@@ -50,14 +80,12 @@ ADVISORY_LINE_THRESHOLD_SOFT = 400
 ADVISORY_LINE_THRESHOLD_HARD = 1000
 
 BOOLEAN_NAME_PREFIXES: tuple[str, ...] = ("is_", "has_", "should_", "can_")
-BOOLEAN_NAMING_ISSUE_CAP = 3
 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
-MAX_ISSUES_PER_CHECK = 3
 FILE_GLOBAL_UPPER_SNAKE_PATTERN = re.compile(r"^_?[A-Z][A-Z0-9_]*$")
 
 COLLECTION_TYPE_NAMES: frozenset[str] = frozenset({
@@ -355,9 +383,6 @@ def check_imports_at_top(content: str) -> list[str]:
             if stripped.startswith(IMPORT_STATEMENT_PREFIXES):
                 issues.append(f"Line {line_number}: Import inside function - move to top of file")
 
-        if len(issues) >= MAX_ISSUES_PER_CHECK:
-            break
-
     return issues
 
 
@@ -758,7 +783,7 @@ def check_constants_outside_config(content: str, file_path: str) -> list[str]:
     inside_function = False
     inside_class = False
 
-    constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})\s*=\s*[^=]")
+    constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
 
     for line_number, line in enumerate(lines, 1):
         stripped = line.strip()
@@ -787,9 +812,6 @@ def check_constants_outside_config(content: str, file_path: str) -> list[str]:
                 if constant_name not in ("__all__",):
                     issues.append(f"Line {line_number}: Constant {constant_name} - move to config/")
 
-        if len(issues) >= 3:
-            break
-
     return issues
 
 
@@ -811,12 +833,11 @@ def _scan_function_body_constants(content: str) -> list[str]:
 
     Only lines inside a function body (tracked via an indent stack) are
     flagged. Module-level assignments and class-body assignments are ignored.
-    Returns at most MAX_ISSUES_PER_CHECK entries.
     """
     advisory_issues: list[str] = []
     lines = content.split("\n")
     function_indent_stack: list[int] = []
-    constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})\s*=\s*[^=]")
+    constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
 
     for line_number, line in enumerate(lines, 1):
         stripped = line.strip()
@@ -846,9 +867,6 @@ def _scan_function_body_constants(content: str) -> list[str]:
                     f"Line {line_number}: Function-local constant {constant_name} - consider moving to config/"
                 )
 
-        if len(advisory_issues) >= MAX_ISSUES_PER_CHECK:
-            break
-
     return advisory_issues
 
 
@@ -866,39 +884,56 @@ def check_constants_outside_config_advisory(content: str, file_path: str) -> lis
     return _scan_function_body_constants(content)
 
 
-BANNED_IDENTIFIERS: frozenset[str] = frozenset({"result", "data", "output", "response", "value", "item", "temp"})
-MAX_BANNED_IDENTIFIER_ISSUES: int = 3
-BANNED_IDENTIFIER_MESSAGE_SUFFIX: str = "use descriptive name (see CODE_RULES Naming section)"
-BANNED_IDENTIFIER_SKIP_ADVISORY: str = (
-    "banned-identifier check skipped: file did not parse as Python"
-)
-
-
-def _collect_banned_names_from_target(target: ast.expr) -> list[ast.Name]:
-    """Return every banned ast.Name reachable through tuple/list unpacking or starred targets."""
+def _collect_target_names(target: ast.expr) -> list[ast.Name]:
+    """Return every ast.Name reachable through tuple/list/starred unpacking targets."""
     if isinstance(target, ast.Name):
-        if target.id in BANNED_IDENTIFIERS:
-            return [target]
-        return []
+        return [target]
     if isinstance(target, (ast.Tuple, ast.List)):
-        banned_names: list[ast.Name] = []
+        names: list[ast.Name] = []
         for each_element in target.elts:
-            banned_names.extend(_collect_banned_names_from_target(each_element))
-        return banned_names
+            names.extend(_collect_target_names(each_element))
+        return names
     if isinstance(target, ast.Starred):
-        return _collect_banned_names_from_target(target.value)
+        return _collect_target_names(target.value)
     return []
 
 
+def _collect_banned_names_from_target(target: ast.expr) -> list[ast.Name]:
+    """Return every banned ast.Name reachable through tuple/list unpacking or starred targets."""
+    return [
+        each_name_node
+        for each_name_node in _collect_target_names(target)
+        if each_name_node.id in ALL_BANNED_IDENTIFIERS
+    ]
+
+
+def _value_is_parse_args_namespace_call(value_node: ast.AST | None) -> bool:
+    if value_node is None:
+        return False
+    if not isinstance(value_node, ast.Call):
+        return False
+    callee = value_node.func
+    return isinstance(callee, ast.Attribute) and callee.attr == "parse_args"
+
+
+def _without_parse_args_namespace_exemption(
+    all_banned_names: list[ast.Name], value_node: ast.AST | None
+) -> list[ast.Name]:
+    if not _value_is_parse_args_namespace_call(value_node):
+        return all_banned_names
+    return [each_name for each_name in all_banned_names if each_name.id != "args"]
+
+
 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):
         banned_names: list[ast.Name] = []
         for each_target in node.targets:
             banned_names.extend(_collect_banned_names_from_target(each_target))
-        return banned_names
+        return _without_parse_args_namespace_exemption(banned_names, node.value)
     if isinstance(node, ast.AnnAssign):
-        return _collect_banned_names_from_target(node.target)
+        banned_names = _collect_banned_names_from_target(node.target)
+        return _without_parse_args_namespace_exemption(banned_names, node.value)
     if isinstance(node, (ast.For, ast.AsyncFor)):
         return _collect_banned_names_from_target(node.target)
     if isinstance(node, ast.comprehension):
@@ -908,7 +943,8 @@ def _collect_banned_names_from_node(node: ast.AST) -> list[ast.Name]:
             return []
         return _collect_banned_names_from_target(node.optional_vars)
     if isinstance(node, ast.NamedExpr):
-        return _collect_banned_names_from_target(node.target)
+        banned_names = _collect_banned_names_from_target(node.target)
+        return _without_parse_args_namespace_exemption(banned_names, node.value)
     return []
 
 
@@ -1066,8 +1102,6 @@ def check_boolean_naming(content: str, file_path: str) -> list[str]:
         issues.append(
             f"Line {line_number}: Boolean {name} - prefix with is_/has_/should_/can_"
         )
-        if len(issues) >= BOOLEAN_NAMING_ISSUE_CAP:
-            break
     return issues
 
 
@@ -1110,8 +1144,6 @@ def check_skip_decorators_in_tests(content: str, file_path: str) -> list[str]:
                     f"Line {each_decorator.lineno}: @skip decorator on test"
                     f" — tests must fail on missing deps"
                 )
-                if len(issues) >= MAX_ISSUES_PER_CHECK:
-                    return issues
 
     return issues
 
@@ -1215,8 +1247,6 @@ def check_existence_check_tests(content: str, file_path: str) -> list[str]:
                 f"Line {each_node.lineno}: existence-check test"
                 f" — delete or replace with a behavior test"
             )
-            if len(issues) >= MAX_ISSUES_PER_CHECK:
-                return issues
 
     return issues
 
@@ -1278,8 +1308,6 @@ def check_constant_equality_tests(content: str, file_path: str) -> list[str]:
                 f"Line {each_node.lineno}: constant-value test"
                 f" — delete; tests must cover behavior"
             )
-            if len(issues) >= MAX_ISSUES_PER_CHECK:
-                return issues
 
     return issues
 
@@ -1391,8 +1419,6 @@ def check_file_global_constants_use_count(content: str, file_path: str) -> list[
             issues.append(
                 f"Line {line_number}: File-global constant {each_constant_name} used by only 1 function/method - move to method scope or add a second caller"
             )
-        if len(issues) >= MAX_ISSUES_PER_CHECK:
-            break
 
     return issues
 
@@ -1934,21 +1960,40 @@ def check_unused_optional_parameters(content: str, file_path: str) -> list[str]:
                     f"Line {function_node.lineno}: optional parameter {param_name}"
                     f" is never varied — inline default or drop"
                 )
-                if len(issues) >= MAX_ISSUES_PER_CHECK:
-                    return issues
 
     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
-    if isinstance(annotation_node, ast.Subscript):
-        return _annotation_names_collection(annotation_node.value)
     if isinstance(annotation_node, ast.Attribute):
         return annotation_node.attr in COLLECTION_TYPE_NAMES
+    if isinstance(annotation_node, ast.BinOp) and isinstance(annotation_node.op, ast.BitOr):
+        return (
+            _annotation_names_collection(annotation_node.left)
+            or _annotation_names_collection(annotation_node.right)
+        )
+    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)
+        )
+        if is_optional_or_union_subscript:
+            slice_node = annotation_node.slice
+            if isinstance(slice_node, ast.Tuple):
+                return any(
+                    _annotation_names_collection(each_element)
+                    for each_element in slice_node.elts
+                )
+            return _annotation_names_collection(slice_node)
+        return _annotation_names_collection(outer_value)
     return False
 
 
@@ -1983,12 +2028,10 @@ def check_collection_prefix(content: str, file_path: str) -> list[str]:
         issues.append(
             f"Line {target_line}: Collection constant {target_name} - prefix with ALL_ (CODE_RULES §5)"
         )
-        if len(issues) >= MAX_ISSUES_PER_CHECK:
-            break
-    for node in ast.walk(tree):
-        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+    for each_walked_node in ast.walk(tree):
+        if not isinstance(each_walked_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
-        for each_arg in _collect_annotated_arguments(node):
+        for each_arg in _collect_annotated_arguments(each_walked_node):
             if not _annotation_names_collection(each_arg.annotation):
                 continue
             if each_arg.arg in {"self", "cls"}:
@@ -1998,8 +2041,369 @@ def check_collection_prefix(content: str, file_path: str) -> list[str]:
             issues.append(
                 f"Line {each_arg.lineno}: Collection parameter {each_arg.arg} - prefix with all_ (CODE_RULES §5)"
             )
-            if len(issues) >= MAX_ISSUES_PER_CHECK:
-                return issues
+    return issues
+
+
+def _is_stuttering_all_name(name: str) -> bool:
+    return bool(STUTTERING_ALL_PREFIX_PATTERN.match(name))
+
+
+def _walk_assignment_targets(target: ast.expr) -> list[ast.Name]:
+    """Recursively collect ast.Name targets through tuple/list/starred unpacking."""
+    if isinstance(target, ast.Name):
+        return [target]
+    if isinstance(target, (ast.Tuple, ast.List)):
+        names: list[ast.Name] = []
+        for each_element in target.elts:
+            names.extend(_walk_assignment_targets(each_element))
+        return names
+    if isinstance(target, ast.Starred):
+        return _walk_assignment_targets(target.value)
+    return []
+
+
+def _collect_stuttering_name_bindings(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return (name, line_number) for bindings whose introduced name stutters all_/ALL_ prefixes.
+
+    Covers assignments, loops, parameters, walrus targets, comprehensions, with/except
+    aliases, import aliases, and class definitions.
+    """
+    bindings: list[tuple[str, int]] = []
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Assign):
+            for each_target in each_node.targets:
+                for each_name in _walk_assignment_targets(each_target):
+                    if _is_stuttering_all_name(each_name.id):
+                        bindings.append((each_name.id, each_name.lineno))
+        elif isinstance(each_node, ast.AnnAssign) and isinstance(each_node.target, ast.Name):
+            if _is_stuttering_all_name(each_node.target.id):
+                bindings.append((each_node.target.id, each_node.target.lineno))
+        elif isinstance(each_node, (ast.For, ast.AsyncFor)):
+            for each_name in _walk_assignment_targets(each_node.target):
+                if _is_stuttering_all_name(each_name.id):
+                    bindings.append((each_name.id, each_name.lineno))
+        elif isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if _is_stuttering_all_name(each_node.name):
+                bindings.append((each_node.name, each_node.lineno))
+            for each_arg in _collect_annotated_arguments(each_node):
+                if _is_stuttering_all_name(each_arg.arg):
+                    bindings.append((each_arg.arg, each_arg.lineno))
+        elif isinstance(each_node, ast.NamedExpr) and isinstance(each_node.target, ast.Name):
+            if _is_stuttering_all_name(each_node.target.id):
+                bindings.append((each_node.target.id, each_node.target.lineno))
+        elif isinstance(each_node, ast.comprehension):
+            for each_name in _walk_assignment_targets(each_node.target):
+                if _is_stuttering_all_name(each_name.id):
+                    bindings.append((each_name.id, each_name.lineno))
+        elif isinstance(each_node, (ast.With, ast.AsyncWith)):
+            for each_with_item in each_node.items:
+                if each_with_item.optional_vars is None:
+                    continue
+                for each_name in _walk_assignment_targets(each_with_item.optional_vars):
+                    if _is_stuttering_all_name(each_name.id):
+                        bindings.append((each_name.id, each_name.lineno))
+        elif isinstance(each_node, ast.ExceptHandler):
+            if each_node.name is not None and _is_stuttering_all_name(each_node.name):
+                bindings.append((each_node.name, each_node.lineno))
+        elif isinstance(each_node, ast.Import):
+            for each_alias in each_node.names:
+                bound_name = (
+                    each_alias.asname
+                    if each_alias.asname is not None
+                    else each_alias.name.split(MODULE_PATH_SEPARATOR, 1)[0]
+                )
+                if _is_stuttering_all_name(bound_name):
+                    line_number = getattr(each_alias, AST_LINENO_ATTRIBUTE, None) or each_node.lineno
+                    bindings.append((bound_name, line_number))
+        elif isinstance(each_node, ast.ImportFrom):
+            for each_alias in each_node.names:
+                if each_alias.name == WILDCARD_IMPORT_SENTINEL:
+                    continue
+                bound_name = (
+                    each_alias.asname
+                    if each_alias.asname is not None
+                    else each_alias.name
+                )
+                if _is_stuttering_all_name(bound_name):
+                    line_number = getattr(each_alias, AST_LINENO_ATTRIBUTE, None) or each_node.lineno
+                    bindings.append((bound_name, line_number))
+        elif isinstance(each_node, ast.ClassDef):
+            if _is_stuttering_all_name(each_node.name):
+                bindings.append((each_node.name, each_node.lineno))
+    return bindings
+
+
+def check_stuttering_collection_prefix(content: str, file_path: str) -> list[str]:
+    """Flag identifiers stuttering the all_/ALL_ collection prefix (e.g., all_all_users)."""
+    if is_test_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 []
+    issues: list[str] = []
+    for each_name, each_line_number in _collect_stuttering_name_bindings(tree):
+        issues.append(
+            f"Line {each_line_number}: Stuttering collection prefix {each_name!r}"
+            f" - use a single all_/ALL_ prefix (CODE_RULES §5)"
+        )
+        if len(issues) >= MAX_STUTTERING_PREFIX_ISSUES:
+            break
+    return issues
+
+
+def check_hardcoded_user_paths(content: str, file_path: str) -> list[str]:
+    """Flag string literals naming a specific user's home directory.
+
+    Catches non-portable paths like `C:/Users/jon/...`, `/Users/alice/...`,
+    and `/home/bob/...` that surface in production code (PR #257 evidence).
+    Test files, config/ files, workflow registry files, migration files,
+    and hook infrastructure files are exempt. Hook infrastructure exemption
+    matches the pattern used by check_library_print and other check
+    functions, and prevents the enforcer from self-blocking on its own
+    HARDCODED_USER_PATH_PATTERN definition.
+    """
+    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 []
+    if is_hook_infrastructure(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    docstring_node_ids = _collect_docstring_node_ids(tree)
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Constant):
+            continue
+        if not isinstance(each_node.value, str):
+            continue
+        if id(each_node) in docstring_node_ids:
+            continue
+        match = HARDCODED_USER_PATH_PATTERN.search(each_node.value)
+        if match is None:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: hardcoded user path {match.group(0)!r}"
+            f" — {HARDCODED_USER_PATH_GUIDANCE}"
+        )
+        if len(issues) >= MAX_HARDCODED_USER_PATH_ISSUES:
+            break
+    return issues
+
+
+def _is_sys_path_insert_call(call_node: ast.Call) -> bool:
+    function_reference = call_node.func
+    if not isinstance(function_reference, ast.Attribute) or function_reference.attr != "insert":
+        return False
+    receiver = function_reference.value
+    if not isinstance(receiver, ast.Attribute) or receiver.attr != "path":
+        return False
+    receiver_value = receiver.value
+    return isinstance(receiver_value, ast.Name) and receiver_value.id == "sys"
+
+
+def _is_sys_path_membership_if_test(if_test_expression: ast.AST) -> bool:
+    """Return True when `if X not in sys.path:` would guard a then-branch insert.
+
+    Only `ast.NotIn` is accepted: `_scope_has_guard_for_insert` walks the
+    then-branch (`each_statement.body`) for the insert, so accepting `ast.In`
+    here would silently approve `if X in sys.path: sys.path.insert(0, X)` —
+    code that always inserts a duplicate. The else-branch is intentionally not
+    inspected; a guard that places the insert in the else-branch of `if X in
+    sys.path:` is unconventional and not supported.
+    """
+    if not isinstance(if_test_expression, ast.Compare):
+        return False
+    if len(if_test_expression.ops) != 1:
+        return False
+    if not isinstance(if_test_expression.ops[0], ast.NotIn):
+        return False
+    membership_target = if_test_expression.comparators[0]
+    if not isinstance(membership_target, ast.Attribute) or membership_target.attr != "path":
+        return False
+    membership_receiver = membership_target.value
+    return isinstance(membership_receiver, ast.Name) and membership_receiver.id == "sys"
+
+
+def _scope_has_guard_for_insert(
+    all_scope_statements: list[ast.stmt],
+    insert_call_node: ast.Call,
+) -> bool:
+    for each_statement in all_scope_statements:
+        if not isinstance(each_statement, ast.If):
+            continue
+        membership_test = each_statement.test
+        if not isinstance(membership_test, ast.Compare):
+            continue
+        if not _is_sys_path_membership_if_test(membership_test):
+            continue
+        for each_inner in each_statement.body:
+            if isinstance(each_inner, ast.Expr) and each_inner.value is insert_call_node:
+                if len(insert_call_node.args) < 2:
+                    return True
+                if ast.dump(membership_test.left) == ast.dump(insert_call_node.args[1]):
+                    return True
+    return False
+
+
+def _enclosing_scope_body(
+    insert_call_node: ast.Call,
+    parent_by_node_id: dict[int, ast.AST],
+) -> list[ast.stmt]:
+    parent = parent_by_node_id.get(id(insert_call_node))
+    while parent is not None:
+        if isinstance(parent, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            return list(parent.body)
+        parent = parent_by_node_id.get(id(parent))
+    return []
+
+
+def check_sys_path_insert_deduplication_guard(content: str, file_path: str) -> list[str]:
+    """Flag sys.path.insert calls that lack a `not in sys.path` guard.
+
+    Repeated module reloads can push the same entry onto sys.path multiple
+    times when the call is unguarded. The repo convention is to wrap the
+    call with `if <path> not in sys.path:`. PR #289 surfaced two scripts
+    (grant_project_claude_permissions.py, revoke_project_claude_permissions.py)
+    that bypassed the convention.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_hook_infrastructure(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 []
+    parent_by_node_id = _build_parent_map(tree)
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Call):
+            continue
+        if not _is_sys_path_insert_call(each_node):
+            continue
+        all_scope_statements = _enclosing_scope_body(each_node, parent_by_node_id)
+        if _scope_has_guard_for_insert(all_scope_statements, each_node):
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: unguarded sys.path.insert"
+            f" — {SYS_PATH_INSERT_GUIDANCE}"
+        )
+        if len(issues) >= MAX_SYS_PATH_INSERT_ISSUES:
+            break
+    return issues
+
+
+def _import_alias_pairs(
+    import_node: ast.Import | ast.ImportFrom,
+) -> list[tuple[str, int, int | None]]:
+    """Return (binding_name, alias_line, from_keyword_line) for each name introduced.
+
+    The from-keyword line is None for plain `import X` statements; for
+    `from X import (...)` it carries the line of the `from` keyword so
+    callers can honor a `# noqa` placed on the opening line of a
+    multi-line import block.
+    """
+    bindings: list[tuple[str, int, int | None]] = []
+    from_keyword_line = import_node.lineno if isinstance(import_node, ast.ImportFrom) else None
+    for each_alias in import_node.names:
+        if each_alias.name == "*":
+            continue
+        binding_name = each_alias.asname if each_alias.asname else each_alias.name.split(".")[0]
+        alias_line = each_alias.lineno or import_node.lineno
+        bindings.append((binding_name, alias_line, from_keyword_line))
+    return bindings
+
+
+def _name_appears_outside_imports(
+    all_content_lines: list[str],
+    all_import_line_numbers: set[int],
+    name: str,
+) -> bool:
+    name_pattern = re.compile(rf"\b{re.escape(name)}\b")
+    for each_line_index, each_line in enumerate(all_content_lines, start=1):
+        if each_line_index in all_import_line_numbers:
+            continue
+        if name_pattern.search(each_line):
+            return True
+    return False
+
+
+def _line_carries_noqa_marker(line_text: str) -> bool:
+    return "# noqa" in line_text or "#noqa" in line_text
+
+
+def check_unused_module_level_imports(content: str, file_path: str) -> list[str]:
+    """Flag module-level imports that are never referenced in the rest of the file.
+
+    The rule is intentionally conservative — files declaring __all__ or
+    using TYPE_CHECKING are skipped to avoid false positives on
+    re-exports and annotation-only imports.
+    """
+    if is_test_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 []
+    file_declares_dunder_all = any(
+        (
+            isinstance(each_node, ast.Assign)
+            and any(
+                isinstance(each_target, ast.Name) and each_target.id == "__all__"
+                for each_target in each_node.targets
+            )
+        )
+        or (
+            isinstance(each_node, ast.AnnAssign)
+            and isinstance(each_node.target, ast.Name)
+            and each_node.target.id == "__all__"
+        )
+        for each_node in tree.body
+    )
+    if file_declares_dunder_all:
+        return []
+    if TYPE_CHECKING_IDENTIFIER in content:
+        return []
+    content_lines = content.splitlines()
+    import_line_numbers: set[int] = set()
+    import_bindings: list[tuple[str, int, int | None]] = []
+    for each_node in tree.body:
+        if isinstance(each_node, (ast.Import, ast.ImportFrom)):
+            import_line_numbers.add(each_node.lineno)
+            for each_alias in each_node.names:
+                import_line_numbers.add(each_alias.lineno or each_node.lineno)
+            if isinstance(each_node, ast.ImportFrom) and each_node.module == "__future__":
+                continue
+            for each_binding in _import_alias_pairs(each_node):
+                import_bindings.append(each_binding)
+    issues: list[str] = []
+    for each_name, each_line_number, each_from_keyword_line in import_bindings:
+        if 1 <= each_line_number <= len(content_lines):
+            if _line_carries_noqa_marker(content_lines[each_line_number - 1]):
+                continue
+        if each_from_keyword_line is not None and 1 <= each_from_keyword_line <= len(content_lines):
+            if _line_carries_noqa_marker(content_lines[each_from_keyword_line - 1]):
+                continue
+        if _name_appears_outside_imports(content_lines, import_line_numbers, each_name):
+            continue
+        issues.append(
+            f"Line {each_line_number}: unused module-level import {each_name!r}"
+            f" — {UNUSED_IMPORT_GUIDANCE}"
+        )
+        if len(issues) >= MAX_UNUSED_IMPORT_ISSUES:
+            break
     return issues
 
 
@@ -2035,8 +2439,222 @@ def check_library_print(content: str, file_path: str) -> list[str]:
                     issues.append(
                         f"Line {node.lineno}: sys.{value_node.attr}.write - route through logger"
                     )
-        if len(issues) >= MAX_ISSUES_PER_CHECK:
-            break
+    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:
+    if not string_value:
+        return False
+    if ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(string_value):
+        return True
+    if DOTTED_SEGMENT_PATTERN.match(string_value):
+        return True
+    return False
+
+
+def _collect_docstring_node_ids(tree: ast.Module) -> set[int]:
+    docstring_ids: set[int] = set()
+    docstring_owner_node_types = (
+        ast.Module,
+        ast.FunctionDef,
+        ast.AsyncFunctionDef,
+        ast.ClassDef,
+    )
+    for node in ast.walk(tree):
+        if not isinstance(node, docstring_owner_node_types):
+            continue
+        if not node.body:
+            continue
+        first_statement = node.body[0]
+        if not isinstance(first_statement, ast.Expr):
+            continue
+        first_value = first_statement.value
+        if isinstance(first_value, ast.Constant) and isinstance(first_value.value, str):
+            docstring_ids.add(id(first_value))
+    return docstring_ids
+
+
+def _collect_fstring_part_node_ids(tree: ast.Module) -> set[int]:
+    fstring_part_ids: set[int] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.JoinedStr):
+            continue
+        for each_value in node.values:
+            if isinstance(each_value, ast.Constant) and isinstance(each_value.value, str):
+                fstring_part_ids.add(id(each_value))
+    return fstring_part_ids
+
+
+def _walk_skipping_nested_function_defs(start_node: ast.AST) -> Iterator[ast.AST]:
+    if isinstance(start_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return
+    nodes_to_visit: list[ast.AST] = [start_node]
+    while nodes_to_visit:
+        current_node = nodes_to_visit.pop()
+        yield current_node
+        all_child_nodes = list(ast.iter_child_nodes(current_node))
+        for each_child_node in reversed(all_child_nodes):
+            if isinstance(each_child_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            nodes_to_visit.append(each_child_node)
+
+
+def check_string_literal_magic(content: str, file_path: str) -> list[str]:
+    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 []
+    docstring_node_ids = _collect_docstring_node_ids(tree)
+    fstring_part_node_ids = _collect_fstring_part_node_ids(tree)
+    issues: list[str] = []
+    flagged_node_ids: set[int] = set()
+    for function_node in ast.walk(tree):
+        if not isinstance(function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, ast.Constant):
+                    continue
+                if not isinstance(each_descendant.value, str):
+                    continue
+                if id(each_descendant) in flagged_node_ids:
+                    continue
+                if id(each_descendant) in docstring_node_ids:
+                    continue
+                if id(each_descendant) in fstring_part_node_ids:
+                    continue
+                if not _is_magic_string_literal(each_descendant.value):
+                    continue
+                flagged_node_ids.add(id(each_descendant))
+                issues.append(
+                    f"Line {each_descendant.lineno}: string magic value {each_descendant.value!r}"
+                    f" - extract to config/"
+                )
+    return issues
+
+
+def check_inline_literal_collections(content: str, file_path: str) -> list[str]:
+    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 []
+    issues: list[str] = []
+    flagged_node_ids: set[int] = set()
+    for function_node in ast.walk(tree):
+        if not isinstance(function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, (ast.Set, ast.List)):
+                    continue
+                if id(each_descendant) in flagged_node_ids:
+                    continue
+                all_elements = each_descendant.elts
+                if len(all_elements) < INLINE_COLLECTION_MIN_LENGTH:
+                    continue
+                if not all(isinstance(each_element, ast.Constant) for each_element in all_elements):
+                    continue
+                flagged_node_ids.add(id(each_descendant))
+                collection_kind = "set" if isinstance(each_descendant, ast.Set) else "list"
+                issues.append(
+                    f"Line {each_descendant.lineno}: inline {collection_kind} literal of {len(all_elements)}"
+                    f" constants in function body - extract to config/"
+                )
+    return issues
+
+
+def check_loop_variable_naming(content: str, file_path: str) -> list[str]:
+    if is_test_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 []
+    issues: list[str] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.For, ast.AsyncFor)):
+            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:
+                continue
+            if target_name == BARE_EACH_TOKEN:
+                issues.append(
+                    f"Line {each_name_node.lineno}: loop variable 'each' is a bare token without subject"
+                    f" - rename to each_<subject> (CODE_RULES §5)"
+                )
+                continue
+            if target_name.startswith(EACH_PREFIX) and len(target_name) > len(EACH_PREFIX):
+                continue
+            issues.append(
+                f"Line {each_name_node.lineno}: loop variable {target_name!r} - prefix with each_ (CODE_RULES §5)"
+            )
+    return issues
+
+
+def check_parameter_annotations(content: str, file_path: str) -> list[str]:
+    if is_test_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 []
+    issues: list[str] = []
+    for node in ast.walk(tree):
+        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:
+                continue
+            if each_arg.annotation is None:
+                issues.append(
+                    f"Line {each_arg.lineno}: parameter {each_arg.arg!r} on {node.name!r} missing type annotation (CODE_RULES §6)"
+                )
+    return issues
+
+
+def check_return_annotations(content: str, file_path: str) -> list[str]:
+    if is_test_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 []
+    issues: list[str] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.returns is None:
+            issues.append(
+                f"Line {node.lineno}: function {node.name!r} missing return type annotation (CODE_RULES §6)"
+            )
     return issues
 
 
@@ -2061,8 +2679,7 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_magic_values(content, file_path))
         all_issues.extend(check_fstring_structural_literals(content, file_path))
         all_issues.extend(check_constants_outside_config(content, file_path))
-        for each_advisory in check_constants_outside_config_advisory(content, file_path):
-            print(f"[CODE_RULES advisory] {file_path}: {each_advisory}", file=sys.stderr)
+        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_banned_identifiers(content, file_path))
@@ -2072,7 +2689,16 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_constant_equality_tests(content, file_path))
         all_issues.extend(check_unused_optional_parameters(content, file_path))
         all_issues.extend(check_collection_prefix(content, file_path))
+        all_issues.extend(check_stuttering_collection_prefix(content, file_path))
+        all_issues.extend(check_hardcoded_user_paths(content, file_path))
+        all_issues.extend(check_sys_path_insert_deduplication_guard(content, file_path))
+        all_issues.extend(check_unused_module_level_imports(content, file_path))
         all_issues.extend(check_library_print(content, file_path))
+        all_issues.extend(check_parameter_annotations(content, file_path))
+        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_string_literal_magic(content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)
 
@@ -2143,4 +2769,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()