claude-dev-env 8.106.3 → 8.106.5

package/_shared/pr-loop/scripts/code_rules_gate_parts/tests/test_gate_running.py

@@ -119,7 +119,7 @@ def test_gate_caller_scans_staged_content_with_commit_stage_scope(
     init_repository(repository_root)
     committed_source = "def calculate_total() -> int:\n    return 0\n"
     staged_source = (
-        "def calculate_total() -> int:\n    total = 9999\n    return total\n"
+        "def calculate_total() -> int:\n    total = abs(9999)\n    return total\n"
     )
     file_path = write_commit_and_stage_change(
         repository_root,

package/docs/CODE_RULES.md

@@ -13,13 +13,13 @@ A keep marker is the one comment that may be added and kept: a comment that open
 
 ## CORE PRINCIPLES
 
-Use clear names. Keep shared constants in `config/`. Search before adding helpers. Put construction and formatting with the data owner. Encapsulation enables cleaner naming, so prefer `isMaxLevel(level)` to `level >= MAXIMUM_LEVEL`. Session policy lives in [`code-standards.md`](../rules/code-standards.md).
+Use clear names. Keep shared and tuned constants in `config/`; a value used once stays in its function under a local name. Search before adding helpers. Put construction and formatting with the data owner. Encapsulation enables cleaner naming, so prefer `isMaxLevel(level)` to `level >= MAXIMUM_LEVEL`. Session policy lives in [`code-standards.md`](../rules/code-standards.md).
 
 Open [details](code-rules/core-principles-and-config.md) when adding shared values or construction logic.
 
 ## ⚡ LINT-ENFORCED RULES
 
-Staged lint runs `code_rules_enforcer.py`. Keep imports at the top, parameterize logging, guard path insertion, use specific exceptions, and follow checks for values, types, docstrings, names, and tests. Magic values exempt 0, 1, and -1. Type escape hatches are allowed in boundary files. Stub bodies are allowed in abstract and Protocol classes.
+Staged lint runs `code_rules_enforcer.py`. Keep imports at the top, parameterize logging, guard path insertion, use specific exceptions, and follow checks for values, types, docstrings, names, and tests. Magic values exempt 0, 1, and -1, and a number bound alone to a named local passes. Type escape hatches are allowed in boundary files. Stub bodies are allowed in abstract and Protocol classes.
 
 - UPPER_SNAKE constants belong in `config/`. Exemptions include `config/*`, `/migrations/`, and test paths or names matching `test_`, `_test.`, `.spec.`, `conftest`, or `/tests/`.
 - Workflow registries: a path that contains any of these substrings, `/workflow/`, `_tab.py`, `/states.py`, or `/modules.py`, is exempt; each matches independently as a substring.
@@ -62,7 +62,7 @@ Open [details](code-rules/design-and-structure.md) when adding a class or parame
 
 ## 7.5 SOLID PRINCIPLES
 
-Apply SRP throughout. Apply OCP, LSP, ISP, and DIP when two concrete implementations share a contract. Keep cohesive classes together.
+Keep a function whole while it reads top to bottom. Split it when the new piece has a second caller or makes the caller easier to read, or when it reaches the 60-line cap the lint and the write-time hook enforce. Apply OCP, LSP, ISP, and DIP when two concrete implementations share a contract. Keep cohesive classes together.
 
 Open [details](code-rules/design-and-structure.md) when extracting a responsibility.
 

package/docs/code-rules/core-principles-and-config.md

@@ -24,7 +24,7 @@ I search for shared code and configuration before adding a constant or repeating
 
 The code-rules enforcer runs constant, path, magic-value, and duplicate-format checks on changed *.py files. String and collection checks inspect production function bodies in *.py files.
 
-Search config for the exact value and a semantic match. Add timing to config/timing.py, ports and thresholds to config/constants.py, and selectors to config/selectors.py. Keep construction and formatting with the owner of the data. Constants outside config are exempt in migrations, workflow registries, and test files. Workflow registry matching uses path substrings /workflow/, _tab.py, /states.py, and /modules.py. The test-file patterns include test_, _test., .spec., conftest, and /tests/.
+A value used once stays in its function under a local name, such as `retry_backoff_factor = 2.5`. A value moves to config when two modules share it or someone tunes it, such as a timeout, threshold, port, or selector. Search config for the exact value and a semantic match. Add timing to config/timing.py, ports and thresholds to config/constants.py, and selectors to config/selectors.py. Keep construction and formatting with the owner of the data. Constants outside config are exempt in migrations, workflow registries, and test files. Workflow registry matching uses path substrings /workflow/, _tab.py, /states.py, and /modules.py. The test-file patterns include test_, _test., .spec., conftest, and /tests/.
 
 ## Proving it
 
@@ -35,6 +35,7 @@ Run the named pytest node or command with the described input. A breach produces
 - check_constants_outside_config_advisory: a function-local UPPER_SNAKE constant; `python -m pytest packages/claude-dev-env/hooks/blocking/test_code_rules_enforcer_split_constants_config.py::test_advisory_should_flag_annotated_function_body_constant` reports a stderr advisory.
 - check_fstring_structural_literals: an f-string that embeds a URL path fragment; `python -m pytest packages/claude-dev-env/hooks/blocking/test_code_rules_enforcer_fstring_scan.py::test_should_flag_fstring_with_url_path` reports a named violation.
 - check_magic_values: a production function comparing a value with 2; `python -m pytest packages/claude-dev-env/hooks/blocking/test_code_rules_enforcer_magic_allowlist.py::test_check_magic_values_should_flag_literal_two_in_function_body` reports a named violation.
+- check_magic_values exemption: a function binding `retry_backoff_factor = 2.5` alone on its line; `python -m pytest packages/claude-dev-env/hooks/blocking/test_code_rules_magic_values.py::test_should_pass_a_number_bound_to_a_local_name` passes with no violation.
 - check_duplicated_format_patterns: the same f-string skeleton at three call sites; `python -m pytest packages/claude-dev-env/hooks/blocking/test_code_rules_enforcer_split_optional_params.py::test_should_advise_when_fstring_skeleton_appears_three_or_more_times` reports a stderr advisory.
 - check_hardcoded_user_paths: a fixed user-home path in source; `python -m pytest packages/claude-dev-env/hooks/blocking/test_code_rules_enforcer_hardcoded_user_path.py::test_should_flag_windows_user_path_with_forward_slashes` reports a named violation.
 - check_sys_path_insert_deduplication_guard: an unguarded module-level sys.path.insert call; `python -m pytest packages/claude-dev-env/hooks/blocking/test_code_rules_enforcer_sys_path_insert.py::test_should_flag_unguarded_module_level_insert` reports a named violation.

package/hooks/blocking/code_rules_magic_values.py

@@ -3,6 +3,9 @@
 import ast
 import re
 import sys
+import textwrap
+from collections import Counter
+from collections.abc import Iterator
 from pathlib import Path
 
 _blocking_directory = str(Path(__file__).resolve().parent)
@@ -148,15 +151,135 @@ def _is_magic_number_inside_slice_bound(masked_line: str, number_text: str) -> b
     return False
 
 
+def _named_number_binding_line_numbers(content: str) -> set[int] | None:
+    """Return the lines where a function binds one number literal to one name.
+
+    The name carries the meaning, so the number needs no constant::
+
+        def backoff_seconds(attempt: int) -> float:
+            retry_backoff_factor = 2.5
+
+    A binding sharing its line with another statement, a number in an
+    expression, a keyword argument, a module-level binding, and a ``global``
+    or ``nonlocal`` name still fire. A fragment is dedented before the
+    parse; content that does not parse returns None.
+    """
+    try:
+        syntax_tree = ast.parse(textwrap.dedent(content))
+    except SyntaxError:
+        return None
+
+    all_outer_scope_names = _global_and_nonlocal_names(syntax_tree)
+    statement_count_by_line = Counter(
+        each_node.lineno for each_node in ast.walk(syntax_tree) if isinstance(each_node, ast.stmt)
+    )
+    return {
+        each_node.lineno
+        for each_node in _nodes_inside_functions(syntax_tree)
+        if isinstance(each_node, ast.stmt)
+        and _number_bound_name(each_node) not in (None, *all_outer_scope_names)
+        and each_node.lineno == each_node.end_lineno
+        and statement_count_by_line[each_node.lineno] == 1
+    }
+
+
+def _global_and_nonlocal_names(syntax_tree: ast.AST) -> set[str]:
+    """Return every name a ``global`` or ``nonlocal`` statement declares in the file."""
+    return {
+        each_name
+        for each_node in ast.walk(syntax_tree)
+        if isinstance(each_node, (ast.Global, ast.Nonlocal))
+        for each_name in each_node.names
+    }
+
+
+def _nodes_inside_functions(syntax_tree: ast.AST) -> Iterator[ast.AST]:
+    """Yield every node whose nearest enclosing scope is a function, each one once."""
+    all_pending: list[tuple[ast.AST, bool]] = [(syntax_tree, False)]
+    while all_pending:
+        node, is_inside_function = all_pending.pop()
+        if is_inside_function:
+            yield node
+        is_child_inside_function = not isinstance(node, ast.ClassDef) and (
+            is_inside_function or isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        )
+        all_pending.extend((each_child, is_child_inside_function) for each_child in ast.iter_child_nodes(node))
+
+
+def _fragment_global_and_nonlocal_names(content: str) -> set[str]:
+    """Return every name a ``global`` or ``nonlocal`` line declares in text that does not parse."""
+    return {
+        each_name.strip()
+        for each_match in re.finditer(r"^[ \t]*(?:global|nonlocal)[ \t]+([\w \t,]+)", content, re.MULTILINE)
+        for each_name in each_match.group(1).split(",")
+    }
+
+
+def _is_fragment_named_number_line(
+    all_lines: list[str], line_number: int, function_indent: int, all_outer_scope_names: set[str]
+) -> bool:
+    """Return True when a line of unparseable content binds one number to one name in a function.
+
+    An Edit fragment that ends partway through a block does not parse whole::
+
+        def backoff_seconds(attempt: int) -> float:
+            retry_backoff_factor = 2.5
+            if attempt > 0:
+
+    The line must sit deeper than the last ``def`` line and parse alone as
+    the binding, so ``retry_backoff_factor = 2.5`` passes there. A name a
+    ``global`` or ``nonlocal`` line declares still fires, and so does a line
+    after one ending in ``,``, ``(``, ``[`` or ``{``, such as the last
+    keyword argument of a call split across lines.
+    """
+    line = all_lines[line_number - 1]
+    stripped_line = line.strip()
+    all_earlier_code_lines = [each_line.strip() for each_line in all_lines[: line_number - 1] if each_line.strip()]
+    is_inside_brackets = bool(all_earlier_code_lines) and all_earlier_code_lines[-1].endswith((",", "(", "[", "{"))
+    if is_inside_brackets or len(line) - len(line.lstrip()) <= function_indent:
+        return False
+    try:
+        line_tree = ast.parse(stripped_line)
+    except SyntaxError:
+        return False
+    return len(line_tree.body) == 1 and _number_bound_name(line_tree.body[0]) not in (None, *all_outer_scope_names)
+
+
+def _number_bound_name(node: ast.AST) -> str | None:
+    """Return the name ``node`` binds one signed number literal to, else None."""
+    if isinstance(node, ast.Assign):
+        all_targets, bound_value = node.targets, node.value
+    elif isinstance(node, ast.AnnAssign) and node.value is not None:
+        all_targets, bound_value = [node.target], node.value
+    else:
+        return None
+    if len(all_targets) != 1 or not isinstance(all_targets[0], ast.Name):
+        return None
+    while isinstance(bound_value, ast.UnaryOp) and isinstance(bound_value.op, (ast.USub, ast.UAdd)):
+        bound_value = bound_value.operand
+    is_number_literal = isinstance(bound_value, ast.Constant) and type(bound_value.value) in (int, float)
+    return all_targets[0].id if is_number_literal else None
+
+
 def check_magic_values(content: str, file_path: str) -> list[str]:
-    """Check for magic values in function bodies."""
+    """Check for magic values in function bodies.
+
+    A line inside a function that binds a single number literal to a name
+    passes, since the name explains the number. A number inside a larger
+    expression fires.
+    """
     if is_config_file(file_path) or is_test_file(file_path):
         return []
 
     issues = []
     lines = content.split("\n")
     all_docstring_line_numbers = docstring_line_numbers(content)
+    all_named_number_line_numbers = _named_number_binding_line_numbers(content)
+    all_fragment_outer_scope_names = (
+        _fragment_global_and_nonlocal_names(content) if all_named_number_line_numbers is None else set()
+    )
     is_inside_function = False
+    function_indent = 0
 
     number_pattern = re.compile(r"(?<![.\w])(\d+\.?\d*)(?![.\w])")
     allowed_numbers = ALL_ALLOWED_MAGIC_NUMBER_LITERALS
@@ -172,6 +295,7 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
 
         if re.match(r"^(async\s+)?def\s+\w+", stripped):
             is_inside_function = True
+            function_indent = len(each_line) - len(each_line.lstrip())
             continue
 
         if re.match(r"^class\s+\w+", stripped):
@@ -182,6 +306,15 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
             if "=" in stripped and stripped.split("=")[0].strip().isupper():
                 continue
 
+            if all_named_number_line_numbers is None:
+                is_named_number_line = _is_fragment_named_number_line(
+                    lines, each_line_number, function_indent, all_fragment_outer_scope_names
+                )
+            else:
+                is_named_number_line = each_line_number in all_named_number_line_numbers
+            if is_named_number_line:
+                continue
+
             if stripped.startswith(("return", "yield", "raise")):
                 continue
 

package/hooks/blocking/test_code_rules_enforcer_stage.py

@@ -171,7 +171,7 @@ def test_gate_caller_scans_staged_content_with_commit_stage_scope(
     committed_source = "def calculate_total() -> int:\n    return 0\n"
     staged_source = (
         "def calculate_total() -> int:\n"
-        "    total = 9999\n"
+        "    total = abs(9999)\n"
         "    return total\n"
     )
     file_path = write_commit_and_stage_change(

package/hooks/blocking/test_code_rules_enforcer_string_magic.py

@@ -317,7 +317,7 @@ def test_should_block_second_identical_string_magic_per_occurrence() -> None:
 def test_should_surface_magic_when_gate_defers_scope_with_head_as_old() -> None:
     source = (
         "def compute() -> int:\n"
-        "    old_number = 9999\n"
+        "    old_number = abs(9999)\n"
         "    return old_number\n"
     )
     issues = code_rules_enforcer.validate_content_for_full_gate(

package/hooks/blocking/test_code_rules_magic_values.py

@@ -52,3 +52,165 @@ def test_magic_value_check_still_flags_real_magic_number_in_code_statement() ->
     assert any(issue.endswith("Magic value 42 - extract to named constant") for issue in issues), (
         f"Expected the real magic number 42 to stay flagged, got: {issues}"
     )
+
+
+def _magic_issues_for_function_line(function_body_line: str) -> list[str]:
+    source = f"def backoff_seconds(attempt: int) -> float:\n    {function_body_line}\n    return attempt\n"
+    return check_magic_values(source, PRODUCTION_FILE_PATH)
+
+
+def test_should_pass_a_number_bound_to_a_local_name() -> None:
+    assert _magic_issues_for_function_line("retry_backoff_factor = 2.5") == []
+
+
+def test_should_pass_an_annotated_number_bound_to_a_local_name() -> None:
+    assert _magic_issues_for_function_line("header_row_count: int | None = 30") == []
+
+
+def test_should_pass_a_named_number_with_a_trailing_comment() -> None:
+    assert _magic_issues_for_function_line("header_row_count = 30  # rows") == []
+
+
+def test_should_pass_a_negative_number_bound_to_a_local_name() -> None:
+    assert _magic_issues_for_function_line("lowest_offset = -40") == []
+
+
+def test_should_flag_a_number_inside_an_expression() -> None:
+    assert _magic_issues_for_function_line("backoff = attempt * 2.5") == [
+        "Line 2: Magic value 2.5 - extract to named constant"
+    ]
+
+
+def test_should_flag_a_number_in_a_comparison_assignment() -> None:
+    assert _magic_issues_for_function_line("is_slow = attempt > 40") == [
+        "Line 2: Magic value 40 - extract to named constant"
+    ]
+
+
+def test_should_flag_a_keyword_argument_on_its_own_line() -> None:
+    source = "def backoff_seconds(attempt: int) -> float:\n    wait_for(\n        attempt,\n        timeout=30\n    )\n    return attempt\n"
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 4: Magic value 30 - extract to named constant"
+    ]
+
+
+def test_should_flag_a_module_level_binding_after_a_function() -> None:
+    source = "def backoff_seconds(attempt: int) -> float:\n    return attempt\nretry_limit = 30\n"
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 3: Magic value 30 - extract to named constant"
+    ]
+
+
+def test_should_pass_a_positive_signed_number_bound_to_a_local_name() -> None:
+    assert _magic_issues_for_function_line("lowest_offset = +40") == []
+
+
+def test_should_flag_a_number_sharing_a_line_with_a_named_binding() -> None:
+    assert _magic_issues_for_function_line("limit = 5; scaled = attempt * 99") == [
+        "Line 2: Magic value 5 - extract to named constant"
+    ]
+
+
+def test_should_flag_two_named_bindings_sharing_one_line() -> None:
+    assert _magic_issues_for_function_line("low_offset = 30; high_offset = 40") == [
+        "Line 2: Magic value 30 - extract to named constant"
+    ]
+
+
+def test_should_flag_a_condition_number_beside_a_named_binding() -> None:
+    assert _magic_issues_for_function_line("if attempt > 99: limit = 40") == [
+        "Line 2: Magic value 99 - extract to named constant"
+    ]
+
+
+def test_should_pass_a_named_number_in_an_indented_method_fragment() -> None:
+    fragment = "    def backoff_seconds(self) -> float:\n        retry_backoff_factor = 2.5\n        return retry_backoff_factor\n"
+    assert check_magic_values(fragment, PRODUCTION_FILE_PATH) == []
+
+
+def test_should_pass_a_doubly_signed_number_bound_to_a_local_name() -> None:
+    assert _magic_issues_for_function_line("lowest_offset = --40") == []
+
+
+def test_should_flag_a_keyword_argument_in_an_indented_method_fragment() -> None:
+    fragment = "    def wait(self) -> None:\n        wait_for(\n            self,\n            timeout=30\n        )\n"
+    assert check_magic_values(fragment, PRODUCTION_FILE_PATH) == [
+        "Line 4: Magic value 30 - extract to named constant"
+    ]
+
+
+def test_should_flag_a_module_level_binding_in_unparseable_content() -> None:
+    source = "def build() -> int:\n    return 0\nretry_limit = 30\nprint 'x'\n"
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 3: Magic value 30 - extract to named constant"
+    ]
+
+
+def test_should_flag_a_number_bound_to_a_global_name() -> None:
+    source = "retry_limit = 0\ndef raise_limit() -> None:\n    global retry_limit\n    retry_limit = 40\n"
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 4: Magic value 40 - extract to named constant"
+    ]
+
+
+def test_should_pass_a_named_number_in_a_fragment_ending_inside_a_block() -> None:
+    source = "def backoff_seconds(attempt: int) -> float:\n    retry_backoff_factor = 2.5\n    if attempt > 0:\n"
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == []
+
+
+def test_should_pass_a_named_number_in_a_method_fragment_with_a_column_zero_string() -> None:
+    source = (
+        "    def backoff_seconds(self) -> float:\n"
+        "        retry_backoff_factor = 2.5\n"
+        '        banner = """\n'
+        "hello\n"
+        '"""\n'
+        "        return retry_backoff_factor\n"
+    )
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == []
+
+
+def test_should_flag_a_global_name_binding_in_a_fragment_ending_inside_a_block() -> None:
+    source = "def raise_limit(attempt: int) -> None:\n    global retry_limit\n    retry_limit = 40\n    if attempt > 0:\n"
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 3: Magic value 40 - extract to named constant"
+    ]
+
+
+def test_should_flag_the_last_keyword_argument_in_a_fragment_ending_inside_a_block() -> None:
+    source = (
+        "def fetch(address: str) -> None:\n"
+        "    response = send(\n"
+        "        address,\n"
+        "        timeout=30\n"
+        "    )\n"
+        "    if response:\n"
+    )
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 4: Magic value 30 - extract to named constant"
+    ]
+
+
+def test_should_flag_each_name_of_consecutive_global_lines_in_a_fragment() -> None:
+    source = (
+        "def tally(attempt: int) -> None:\n"
+        "    global total\n"
+        "    global count\n"
+        "    total = 7\n"
+        "    if attempt > 0:\n"
+    )
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 4: Magic value 7 - extract to named constant"
+    ]
+
+
+def test_should_flag_a_global_name_declared_beside_a_comment_in_a_fragment() -> None:
+    source = (
+        "def tally(attempt: int) -> None:\n"
+        "    global total  # shared\n"
+        "    total = 7\n"
+        "    if attempt > 0:\n"
+    )
+    assert check_magic_values(source, PRODUCTION_FILE_PATH) == [
+        "Line 3: Magic value 7 - extract to named constant"
+    ]

package/hooks/blocking/test_code_rules_validation_phase.py

@@ -185,7 +185,7 @@ def _write_scoped_service_file_with_a_committed_baseline(repository_root: Path)
         repository_root,
         "service.py",
         "def read_port() -> int:\n    return 0\n",
-        "def read_port() -> int:\n    port_number = 9999\n    return port_number\n",
+        "def read_port() -> int:\n    port_number = abs(9999)\n    return port_number\n",
     )
 
 

package/hooks/validators/magic_value_checks.py

@@ -9,6 +9,7 @@ Note: Only checks for magic numbers. Magic string detection is not implemented.
 import ast
 import re
 import sys
+from collections import Counter
 from pathlib import Path
 from typing import Dict, FrozenSet, List, Set, Tuple, Type
 
@@ -16,7 +17,7 @@ from .exempt_paths import (
     is_config_file,
     is_test_file,
 )
-from .validator_base import Violation
+from .validator_base import Violation, run_file_validator_cli
 
 
 ALLOWED_NUMBERS: FrozenSet[int] = frozenset({-1, 0, 1})
@@ -35,6 +36,8 @@ def check_magic_values(tree: ast.AST, filename: str) -> List[Violation]:
     violations: List[Violation] = []
     negated_literal_ids: Set[int] = set()
     parent_by_child_id = _build_parent_map(tree)
+    all_outer_scope_names = _global_and_nonlocal_names(tree)
+    all_shared_statement_lines = _lines_holding_several_statements(tree)
 
     for node in ast.walk(tree):
         if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
@@ -55,6 +58,10 @@ def check_magic_values(tree: ast.AST, filename: str) -> List[Violation]:
                     continue
                 if _is_in_constant_definition(outermost_unary, parent_by_child_id):
                     continue
+                if _is_named_function_local_binding(
+                    outermost_unary, parent_by_child_id, all_outer_scope_names, all_shared_statement_lines
+                ):
+                    continue
                 violations.append(
                     Violation(
                         filename,
@@ -74,6 +81,10 @@ def check_magic_values(tree: ast.AST, filename: str) -> List[Violation]:
                 continue
             if _is_in_constant_definition(node, parent_by_child_id):
                 continue
+            if _is_named_function_local_binding(
+                node, parent_by_child_id, all_outer_scope_names, all_shared_statement_lines
+            ):
+                continue
             violations.append(
                 Violation(
                     filename,
@@ -130,6 +141,70 @@ def _is_in_constant_definition(
     return False
 
 
+def _global_and_nonlocal_names(tree: ast.AST) -> Set[str]:
+    """Return every name a ``global`` or ``nonlocal`` statement declares in the tree."""
+    return {
+        each_name
+        for each_node in ast.walk(tree)
+        if isinstance(each_node, (ast.Global, ast.Nonlocal))
+        for each_name in each_node.names
+    }
+
+
+def _lines_holding_several_statements(tree: ast.AST) -> Set[int]:
+    """Return the line numbers where more than one statement starts."""
+    statement_count_by_line = Counter(
+        each_node.lineno for each_node in ast.walk(tree) if isinstance(each_node, ast.stmt)
+    )
+    return {each_line for each_line, each_count in statement_count_by_line.items() if each_count > 1}
+
+
+def _is_named_function_local_binding(
+    node: ast.AST,
+    parent_by_child_id: Dict[int, ast.AST],
+    all_outer_scope_names: Set[str],
+    all_shared_statement_lines: Set[int],
+) -> bool:
+    """Return True when a function binds ``node`` alone to one plain name.
+
+    ``header_row_count = 30`` on one line inside a function passes, since
+    the name explains the number. A number inside an expression, a default
+    parameter, a keyword argument, a module-level or class-level binding, a
+    binding that shares its line with another statement, and a binding to a
+    name the tree declares ``global`` or ``nonlocal`` still fire.
+    """
+    bound_value: ast.AST = node
+    parent = parent_by_child_id.get(id(bound_value))
+    while isinstance(parent, ast.UnaryOp) and isinstance(parent.op, (ast.USub, ast.UAdd)):
+        bound_value = parent
+        parent = parent_by_child_id.get(id(bound_value))
+    if not isinstance(parent, (ast.Assign, ast.AnnAssign)) or parent.value is not bound_value:
+        return False
+    all_targets = parent.targets if isinstance(parent, ast.Assign) else [parent.target]
+    if len(all_targets) != 1 or not isinstance(all_targets[0], ast.Name):
+        return False
+    is_one_line = parent.lineno == parent.end_lineno
+    is_alone_on_line = parent.lineno not in all_shared_statement_lines
+    if not (is_one_line and is_alone_on_line) or all_targets[0].id in all_outer_scope_names:
+        return False
+    return _encloses_in_function(parent, parent_by_child_id)
+
+
+def _encloses_in_function(
+    node: ast.AST,
+    parent_by_child_id: Dict[int, ast.AST],
+) -> bool:
+    """Return True when the nearest enclosing scope of ``node`` is a function."""
+    current_node: ast.AST = node
+    while id(current_node) in parent_by_child_id:
+        current_node = parent_by_child_id[id(current_node)]
+        if isinstance(current_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            return True
+        if isinstance(current_node, ast.ClassDef):
+            return False
+    return False
+
+
 def _is_upper_snake_constant_assignment(node: ast.AST) -> bool:
     if isinstance(node, ast.Assign):
         for target in node.targets:
@@ -164,17 +239,7 @@ def validate_file(file_path: Path) -> List[Violation]:
 
 
 def main() -> int:
-    if len(sys.argv) < 2:
-        return 1
-
-    all_violations: List[Violation] = []
-    for file_arg in sys.argv[1:]:
-        all_violations.extend(validate_file(Path(file_arg)))
-
-    for violation in all_violations:
-        print(violation)
-
-    return 1 if all_violations else 0
+    return run_file_validator_cli(validate_file)
 
 
 if __name__ == "__main__":

package/hooks/validators/test_magic_value_checks.py

@@ -27,8 +27,8 @@ def process():
 '''
 
 BAD_MAGIC_NUMBER = '''
-def process():
-    timeout = 5000
+def process(attempts):
+    timeout = attempts * 5000
     return timeout
 '''
 
@@ -113,8 +113,8 @@ SETTINGS: dict[str, int] = {"timeout": 30}
 '''
 
 NON_CONSTANT_ASSIGNMENT_IN_FUNCTION = '''
-def configure():
-    delay = 30
+def configure(base):
+    delay = base + 30
     return delay
 '''
 
@@ -415,3 +415,87 @@ class TestValidateFilePathExemptions:
             violations = validate_file(production_path)
             assert len(violations) == 1
             assert "42" in violations[0].message
+
+
+NAMED_FUNCTION_LOCAL_NUMBERS = """
+def configure():
+    header_row_count: int = 30
+    lowest_offset = -40
+    highest_offset = +40
+    return header_row_count, lowest_offset, highest_offset
+"""
+
+DEFAULT_PARAMETER_NUMBER = """
+def configure(header_row_count=30):
+    return header_row_count
+"""
+
+CLASS_LEVEL_NUMBER = """
+class Settings:
+    header_row_count = 30
+"""
+
+
+def test_should_pass_numbers_bound_alone_to_function_local_names() -> None:
+    assert check_magic_values(ast.parse(NAMED_FUNCTION_LOCAL_NUMBERS), "test.py") == []
+
+
+def test_should_flag_a_default_parameter_number() -> None:
+    violations = check_magic_values(ast.parse(DEFAULT_PARAMETER_NUMBER), "test.py")
+    assert [violation.message for violation in violations] == ["Magic number 30 - use named constant"]
+
+
+def test_should_flag_a_class_level_number() -> None:
+    violations = check_magic_values(ast.parse(CLASS_LEVEL_NUMBER), "test.py")
+    assert [violation.message for violation in violations] == ["Magic number 30 - use named constant"]
+
+
+GLOBAL_NAME_NUMBER = """
+def raise_limit():
+    global retry_limit
+    retry_limit = 40
+"""
+
+MIXED_SIGN_NAMED_LOCAL = """
+def configure():
+    lowest_offset = -+40
+    return lowest_offset
+"""
+
+
+def test_should_flag_a_number_bound_to_a_global_name() -> None:
+    violations = check_magic_values(ast.parse(GLOBAL_NAME_NUMBER), "test.py")
+    assert [violation.message for violation in violations] == ["Magic number 40 - use named constant"]
+
+
+def test_should_pass_a_mixed_sign_number_bound_to_a_local_name() -> None:
+    assert check_magic_values(ast.parse(MIXED_SIGN_NAMED_LOCAL), "test.py") == []
+
+
+MULTI_LINE_NAMED_LOCAL = """
+def configure():
+    header_row_count = (
+        30
+    )
+    return header_row_count
+"""
+
+
+def test_should_flag_a_number_bound_across_several_lines() -> None:
+    violations = check_magic_values(ast.parse(MULTI_LINE_NAMED_LOCAL), "test.py")
+    assert [violation.message for violation in violations] == ["Magic number 30 - use named constant"]
+
+
+SHARED_LINE_NAMED_LOCALS = """
+def configure():
+    low_offset = 30; high_offset = 40
+    return low_offset, high_offset
+"""
+
+
+def test_should_flag_numbers_bound_on_a_line_shared_with_another_statement() -> None:
+    violations = check_magic_values(ast.parse(SHARED_LINE_NAMED_LOCALS), "test.py")
+    assert sorted(violation.message for violation in violations) == [
+        "Magic number 30 - use named constant",
+        "Magic number 40 - use named constant",
+    ]

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -458,7 +458,7 @@ class TestBaselineScopedGate:
                 "tool_input": {
                     "file_path": str(target_file),
                     "old_string": "    return 199\n",
-                    "new_string": "    threshold = 42\n    return 199 + threshold\n",
+                    "new_string": "    threshold = abs(42)\n    return 199 + threshold\n",
                 },
             }
         )

package/hooks/validators/test_todo_checks.py

@@ -1,8 +1,10 @@
 """Tests for TODO/FIXME detection."""
 
+from pathlib import Path
+
 import pytest
 
-from .todo_checks import check_untracked_todos
+from .todo_checks import check_untracked_todos, main
 from .validator_base import Violation
 
 
@@ -38,3 +40,13 @@ class TestUntrackedTodos:
         code = "# FIXME: broken\ndef foo(): pass"
         violations = check_untracked_todos(code, "test.py")
         assert len(violations) == 1
+
+
+def test_main_should_report_an_untracked_todo_in_a_named_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source_path = tmp_path / "worker.py"
+    source_path.write_text("def run():\n    pass  # TODO tidy up\n", encoding="utf-8")
+    monkeypatch.setattr("sys.argv", ["todo_checks", str(source_path)])
+    assert main() == 1
+    assert capsys.readouterr().out.startswith(f"{source_path}:2:")

package/hooks/validators/test_validator_base.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 import pytest
 
-from .validator_base import Violation, source_text, syntax_tree
+from .validator_base import Violation, run_file_validator_cli, source_text, syntax_tree
 
 
 class TestViolation:
@@ -73,3 +73,21 @@ def test_syntax_tree_raises_syntax_error_for_unparseable_source() -> None:
     """A caller's own SyntaxError branch still fires."""
     with pytest.raises(SyntaxError):
         syntax_tree("def broken(:\n")
+
+
+def _flag_every_file(file_path: Path) -> list[Violation]:
+    return [Violation(file=str(file_path), line=3, message="flagged")]
+
+
+def test_run_file_validator_cli_should_print_violations_and_fail(capsys: pytest.CaptureFixture[str]) -> None:
+    exit_code = run_file_validator_cli(_flag_every_file, ["validator", "a.py", "b.py"])
+    assert exit_code == 1
+    assert capsys.readouterr().out == "a.py:3: flagged\nb.py:3: flagged\n"
+
+
+def test_run_file_validator_cli_should_pass_clean_files() -> None:
+    assert run_file_validator_cli(lambda file_path: [], ["validator", "a.py"]) == 0
+
+
+def test_run_file_validator_cli_should_fail_with_no_file_named() -> None:
+    assert run_file_validator_cli(_flag_every_file, ["validator"]) == 1

package/hooks/validators/todo_checks.py

@@ -8,7 +8,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from .validator_base import Violation, source_text
+from .validator_base import Violation, run_file_validator_cli, source_text
 
 
 TODO_PATTERN = re.compile(r"#\s*(TODO|FIXME)\b(?!.*#\d+)", re.IGNORECASE)
@@ -42,17 +42,7 @@ def validate_file(file_path: Path) -> List[Violation]:
 
 
 def main() -> int:
-    if len(sys.argv) < 2:
-        return 1
-
-    all_violations: List[Violation] = []
-    for file_arg in sys.argv[1:]:
-        all_violations.extend(validate_file(Path(file_arg)))
-
-    for violation in all_violations:
-        print(violation)
-
-    return 1 if all_violations else 0
+    return run_file_validator_cli(validate_file)
 
 
 if __name__ == "__main__":

package/hooks/validators/validator_base.py

@@ -1,10 +1,13 @@
 """Base classes for validators.
 
-Provides shared dataclasses used across all validator modules, and the one
-read and the one parse each of those modules shares for a given file.
+Provides shared dataclasses used across all validator modules, the one
+read and the one parse each of those modules shares for a given file, and
+the command-line runner a validator module's ``main`` can call.
 """
 
 import ast
+import sys
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from functools import lru_cache
 from pathlib import Path
@@ -89,3 +92,31 @@ def syntax_tree(source: str) -> ast.Module:
         The parsed module.
     """
     return ast.parse(source)
+
+
+def run_file_validator_cli(
+    validate_file: Callable[[Path], list[Violation]],
+    all_arguments: Sequence[str] | None = None,
+) -> int:
+    """Validate each file named on the command line and print its violations.
+
+    ``python -m validators.todo_checks a.py b.py`` prints one line per
+    violation and exits 1 when any file has one.
+
+    Args:
+        validate_file: The module's per-file check.
+        all_arguments: The command-line arguments, program name first.
+            Defaults to ``sys.argv``.
+
+    Returns:
+        1 with no file named or any violation found, else 0.
+    """
+    all_file_arguments = list(sys.argv if all_arguments is None else all_arguments)[1:]
+    if not all_file_arguments:
+        return 1
+    all_violations: list[Violation] = []
+    for each_file_argument in all_file_arguments:
+        all_violations.extend(validate_file(Path(each_file_argument)))
+    for each_violation in all_violations:
+        sys.stdout.write(f"{each_violation}\n")
+    return 1 if all_violations else 0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.106.3",
+    "version": "8.106.5",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/policy_lint/config/check_catalog_constants.py

@@ -61,6 +61,9 @@ ALL_CHECK_CATALOG_ENTRIES: tuple[CheckCatalogEntry, ...] = (
         "paired-test-missing-function",
     ),
     CheckCatalogEntry("but exercises nowhere", "paired-test-omitted-function"),
+    CheckCatalogEntry(") - consider splitting", "file-length"),
+    CheckCatalogEntry(" lines (max ", "function-line-cap"),
+    CheckCatalogEntry(" has nesting depth ", "nesting-depth"),
 )
 
 SEVERITY_BREAKING: str = "breaking"
@@ -68,5 +71,8 @@ SEVERITY_SMELL: str = "smell"
 SEVERITY_BY_CHECK_ID: dict[str, str] = {
     "code-rules/paired-test-missing-function": SEVERITY_SMELL,
     "code-rules/paired-test-omitted-function": SEVERITY_SMELL,
+    "validators/file-length": SEVERITY_SMELL,
+    "validators/function-line-cap": SEVERITY_SMELL,
+    "validators/nesting-depth": SEVERITY_SMELL,
     "test-pairing": SEVERITY_SMELL,
 }

package/scripts/tests/test_policy_lint_rules_check_catalog.py

@@ -18,6 +18,7 @@ from policy_lint.config.check_catalog_constants import (
 from policy_lint.model import Diagnostic, Severity
 
 _BUNDLING_RULE_ID = "code-rules"
+_VALIDATORS_RULE_ID = "validators"
 _HOOKS_DIRECTORY = Path(__file__).resolve().parents[2] / "hooks"
 _TEST_FILE_PREFIX = "test_"
 _PYTHON_GLOB = "*.py"
@@ -82,6 +83,9 @@ ALL_MESSAGE_SAMPLES: tuple[tuple[str, str], ...] = (
         " already covers another public function in that module",
         "paired-test-omitted-function",
     ),
+    ("src/app.py:1: File is 412 lines (max 400) - consider splitting", "file-length"),
+    ("src/app.py:4: Function 'run' is 37 lines (max 30)", "function-line-cap"),
+    ("src/app.py:9: Function 'run' has nesting depth 3 (max 2)", "nesting-depth"),
 )
 
 
@@ -169,6 +173,23 @@ def test_a_paired_test_check_reports_as_a_warning(check_name: str) -> None:
     assert severity_for_check_id(f"{_BUNDLING_RULE_ID}/{check_name}") is Severity.WARNING
 
 
+@pytest.mark.parametrize(
+    ("sample_message", "check_name"),
+    tuple(
+        each_sample
+        for each_sample in ALL_MESSAGE_SAMPLES
+        if each_sample[1] in ("file-length", "function-line-cap", "nesting-depth")
+    ),
+)
+def test_a_validator_smell_reports_as_a_warning(
+    sample_message: str, check_name: str
+) -> None:
+    check_id = check_id_for_message(_VALIDATORS_RULE_ID, sample_message)
+
+    assert check_id == f"{_VALIDATORS_RULE_ID}/{check_name}"
+    assert severity_for_check_id(check_id) is Severity.WARNING
+
+
 def test_an_unclassified_check_reports_as_an_error() -> None:
     unclassified_check_id = f"{_BUNDLING_RULE_ID}/{UNCLASSIFIED_CHECK_NAME}"