claude-dev-env 1.34.1 → 1.36.0

package/hooks/blocking/es_exe_path_rewriter.py

@@ -26,6 +26,7 @@ def _insert_hooks_tree_for_imports() -> None:
 _insert_hooks_tree_for_imports()
 
 from config.dynamic_stderr_handler import DynamicStderrHandler
+from config.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from config.path_rewriter_constants import (
     BASH_TOOL_NAME,
     HOOK_EVENT_NAME,
@@ -135,12 +136,17 @@ def _build_allow_response(rewritten_command: str, original_tool_input: dict) ->
 
 def main() -> None:
     try:
-        hook_input = json.load(sys.stdin)
-        tool_name = hook_input.get("tool_name", "")
+        hook_input = read_hook_input_dictionary_from_stdin()
+        if hook_input is None:
+            sys.exit(0)
+        raw_tool_name = hook_input.get("tool_name", "")
+        raw_tool_input = hook_input.get("tool_input", {})
+        tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
+        tool_input = raw_tool_input if isinstance(raw_tool_input, dict) else {}
         if tool_name != BASH_TOOL_NAME:
             sys.exit(0)
-        tool_input = hook_input.get("tool_input", {})
-        command = tool_input.get("command", "")
+        raw_command = tool_input.get("command", "")
+        command = raw_command if isinstance(raw_command, str) else ""
         if not command_invokes_es_exe(command):
             sys.exit(0)
         known_registry = load_registry()

package/hooks/blocking/test_code_rules_enforcer.py

@@ -33,14 +33,82 @@ def _load_enforcer_module() -> ModuleType:
 code_rules_enforcer = _load_enforcer_module()
 
 _BLOCKING_DIR = Path(__file__).resolve().parent
+_HOOKS_TREE_DIR = _BLOCKING_DIR.parent
 if str(_BLOCKING_DIR) not in sys.path:
     sys.path.insert(0, str(_BLOCKING_DIR))
+if str(_HOOKS_TREE_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_TREE_DIR))
 
 from code_rules_path_utils import is_config_file as path_utils_is_config_file  # noqa: E402
+from config.banned_identifiers_constants import (  # noqa: E402
+    ALL_BANNED_IDENTIFIERS as config_all_banned_identifiers,
+    BANNED_IDENTIFIER_MESSAGE_SUFFIX as config_banned_identifier_message_suffix,
+    BANNED_IDENTIFIER_SKIP_ADVISORY as config_banned_identifier_skip_advisory,
+    MAX_BANNED_IDENTIFIER_ISSUES as config_max_banned_identifier_issues,
+)
+from config.hardcoded_user_path_constants import (  # noqa: E402
+    HARDCODED_USER_PATH_GUIDANCE as config_hardcoded_user_path_guidance,
+    HARDCODED_USER_PATH_PATTERN as config_hardcoded_user_path_pattern,
+    MAX_HARDCODED_USER_PATH_ISSUES as config_max_hardcoded_user_path_issues,
+)
+from config.stuttering_check_config import (  # noqa: E402
+    MAX_STUTTERING_PREFIX_ISSUES as config_max_stuttering_prefix_issues,
+    STUTTERING_ALL_PREFIX_PATTERN as config_stuttering_all_prefix_pattern,
+)
 
 PRODUCTION_FILE_PATH = "packages/claude-dev-env/hooks/blocking/example_production.py"
 
 
+def test_should_expose_all_banned_identifiers_from_config() -> None:
+    expected_banned_identifiers = frozenset({
+        "result", "data", "output", "response", "value", "item", "temp",
+        "argv", "args", "kwargs", "argc",
+    })
+    actual_banned_identifiers = getattr(
+        code_rules_enforcer, "ALL_BANNED_IDENTIFIERS", None
+    )
+    assert actual_banned_identifiers is not None, (
+        "Renamed constant ALL_BANNED_IDENTIFIERS must be importable from "
+        "config/banned_identifiers_constants.py and re-exposed on the "
+        f"enforcer module, got: {actual_banned_identifiers!r}"
+    )
+    assert expected_banned_identifiers <= actual_banned_identifiers, (
+        "ALL_BANNED_IDENTIFIERS must contain every expected banned identifier; "
+        f"missing: {expected_banned_identifiers - actual_banned_identifiers!r}"
+    )
+
+
+def test_should_source_banned_identifier_companion_constants_from_config() -> None:
+    assert (
+        code_rules_enforcer.MAX_BANNED_IDENTIFIER_ISSUES
+        is config_max_banned_identifier_issues
+    )
+    assert (
+        code_rules_enforcer.BANNED_IDENTIFIER_MESSAGE_SUFFIX
+        is config_banned_identifier_message_suffix
+    )
+    assert (
+        code_rules_enforcer.BANNED_IDENTIFIER_SKIP_ADVISORY
+        is config_banned_identifier_skip_advisory
+    )
+
+
+def test_should_reexport_hardcoded_user_path_pattern_from_config() -> None:
+    assert code_rules_enforcer.HARDCODED_USER_PATH_PATTERN is config_hardcoded_user_path_pattern
+
+
+def test_should_reexport_max_hardcoded_user_path_issues_from_config() -> None:
+    assert code_rules_enforcer.MAX_HARDCODED_USER_PATH_ISSUES == config_max_hardcoded_user_path_issues
+
+
+def test_should_reexport_hardcoded_user_path_guidance_from_config() -> None:
+    assert code_rules_enforcer.HARDCODED_USER_PATH_GUIDANCE == config_hardcoded_user_path_guidance
+
+
+def test_should_reexport_all_banned_identifiers_from_config() -> None:
+    assert code_rules_enforcer.ALL_BANNED_IDENTIFIERS is config_all_banned_identifiers
+
+
 def test_should_flag_constant_used_only_in_class_level_decorator() -> None:
     source = (
         "TIMEOUT = 5\n"
@@ -188,34 +256,6 @@ def test_should_flag_when_every_call_passes_the_exact_default() -> None:
     )
 
 
-def test_check_unused_optional_parameters_stops_at_max_issues_per_check() -> None:
-    source = (
-        "def make_url_one(path: str, prefix: str = '/api') -> str:\n"
-        "    return f'{prefix}{path}'\n"
-        "def make_url_two(path: str, prefix: str = '/api') -> str:\n"
-        "    return f'{prefix}{path}'\n"
-        "def make_url_three(path: str, prefix: str = '/api') -> str:\n"
-        "    return f'{prefix}{path}'\n"
-        "def make_url_four(path: str, prefix: str = '/api') -> str:\n"
-        "    return f'{prefix}{path}'\n"
-        "def make_url_five(path: str, prefix: str = '/api') -> str:\n"
-        "    return f'{prefix}{path}'\n"
-        "\n"
-        "def call_all() -> None:\n"
-        "    make_url_one('/a')\n"
-        "    make_url_two('/b')\n"
-        "    make_url_three('/c')\n"
-        "    make_url_four('/d')\n"
-        "    make_url_five('/e')\n"
-    )
-    issues = code_rules_enforcer.check_unused_optional_parameters(
-        source, UNUSED_OPTIONAL_PRODUCTION_FILE_PATH
-    )
-    assert len(issues) == code_rules_enforcer.MAX_ISSUES_PER_CHECK, (
-        f"Expected exactly MAX_ISSUES_PER_CHECK issues, got {len(issues)}: {issues}"
-    )
-
-
 INCOMPLETE_MOCK_TEST_FILE_PATH = "packages/app/tests/test_orders.py"
 INCOMPLETE_MOCK_PRODUCTION_FILE_PATH = "packages/app/services/orders.py"
 
@@ -675,22 +715,20 @@ def test_advisory_should_still_flag_actual_method_body_constant() -> None:
     assert "MAXIMUM_RETRIES" in advisory_issues[0]
 
 
-def test_advisory_cap_matches_max_issues_per_check_constant() -> None:
-    many_constants_source = (
-        "def crowded_function():\n"
-        "    ALPHA_CONSTANT = 1\n"
-        "    BETA_CONSTANT = 2\n"
-        "    GAMMA_CONSTANT = 3\n"
-        "    DELTA_CONSTANT = 4\n"
-        "    EPSILON_CONSTANT = 5\n"
+def test_advisory_should_flag_annotated_function_body_constant() -> None:
+    source_with_annotated_function_body_constant = (
+        "def example_function() -> None:\n"
+        "    MAXIMUM_RETRIES: int = 3\n"
+        "    return None\n"
     )
     advisory_issues = code_rules_enforcer.check_constants_outside_config_advisory(
-        many_constants_source,
+        source_with_annotated_function_body_constant,
         "example_module.py",
     )
-    assert len(advisory_issues) == code_rules_enforcer.MAX_ISSUES_PER_CHECK, (
-        "Advisory cap must equal MAX_ISSUES_PER_CHECK, not a hardcoded literal"
+    assert len(advisory_issues) == 1, (
+        "Annotated function-body UPPER_SNAKE constant (PEP 526) must surface as advisory"
     )
+    assert "MAXIMUM_RETRIES" in advisory_issues[0]
 
 
 def test_advisory_should_flag_outer_constants_after_nested_def() -> None:
@@ -958,3 +996,199 @@ def test_should_still_advise_when_duplicated_fstring_literal_is_long(capsys: obj
         "Expected the existing /api/<x> path-shape advisory to still fire, "
         f"got: {captured.err!r}"
     )
+
+
+LOOP_NAMING_PRODUCTION_FILE_PATH = "packages/app/services/loop_naming.py"
+
+
+def test_check_loop_variable_naming_flags_missing_each_prefix() -> None:
+    source = (
+        "def consume() -> None:\n"
+        "    for marker in []:\n"
+        "        return None\n"
+    )
+    issues = code_rules_enforcer.check_loop_variable_naming(
+        source, LOOP_NAMING_PRODUCTION_FILE_PATH
+    )
+    assert any("marker" in each_issue for each_issue in issues), (
+        f"Expected 'marker' loop variable flagged, got: {issues}"
+    )
+
+
+INLINE_LITERAL_PRODUCTION_FILE_PATH = "packages/app/services/inline_literal.py"
+
+
+def test_check_inline_literal_collections_flags_three_string_set_in_function() -> None:
+    source = (
+        "def is_known(value: str) -> bool:\n"
+        "    return value in {'true', 'false', 'none'}\n"
+    )
+    issues = code_rules_enforcer.check_inline_literal_collections(
+        source, INLINE_LITERAL_PRODUCTION_FILE_PATH
+    )
+    assert len(issues) == 1, f"Expected 3-element string set flagged, got: {issues}"
+
+
+STRING_MAGIC_PRODUCTION_FILE_PATH = "packages/app/services/string_magic.py"
+
+
+def test_check_string_literal_magic_flags_env_var_name() -> None:
+    source = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, STRING_MAGIC_PRODUCTION_FILE_PATH
+    )
+    assert any("STRIPE_SECRET" in each_issue for each_issue in issues), (
+        f"Expected env-var name flagged, got: {issues}"
+    )
+
+
+CONSTANTS_OUTSIDE_CONFIG_PRODUCTION_FILE_PATH = "packages/app/services/encoding.py"
+
+
+def test_check_constants_outside_config_flags_annotated_assignment() -> None:
+    source = "TEXT_FILE_ENCODING: str = 'utf-8'\n"
+    issues = code_rules_enforcer.check_constants_outside_config(
+        source, CONSTANTS_OUTSIDE_CONFIG_PRODUCTION_FILE_PATH
+    )
+    assert any("TEXT_FILE_ENCODING" in each_issue for each_issue in issues), (
+        f"Expected annotated UPPER_SNAKE assignment flagged, got: {issues}"
+    )
+
+
+def test_check_constants_outside_config_reports_more_than_three_constants() -> None:
+    source = (
+        "ALPHA_VALUE = 1\n"
+        "BETA_VALUE = 2\n"
+        "GAMMA_VALUE = 3\n"
+        "DELTA_VALUE = 4\n"
+        "EPSILON_VALUE = 5\n"
+        "\n"
+        "def consumer() -> int:\n"
+        "    return ALPHA_VALUE + BETA_VALUE\n"
+    )
+    issues = code_rules_enforcer.check_constants_outside_config(
+        source, CONSTANTS_OUTSIDE_CONFIG_PRODUCTION_FILE_PATH
+    )
+    expected_constant_count = 5
+    assert len(issues) == expected_constant_count, (
+        f"Expected all {expected_constant_count} constants reported, got {len(issues)}: {issues}"
+    )
+
+
+def test_stuttering_collection_prefix_flags_function_name_loop1_1() -> None:
+    source = "def all_all_process() -> None:\n    return None\n"
+    issues = code_rules_enforcer.check_stuttering_collection_prefix(
+        source, "packages/app/services/foo.py"
+    )
+    assert any("all_all_process" in each_issue for each_issue in issues), (
+        f"loop1-1: stuttering function name must be flagged, got: {issues}"
+    )
+
+
+def test_stuttering_collection_prefix_flags_with_as_binding_loop3_1() -> None:
+    source = "def f() -> None:\n    with open('x') as all_all_context:\n        pass\n"
+    issues = code_rules_enforcer.check_stuttering_collection_prefix(
+        source, "packages/app/services/foo.py"
+    )
+    assert any("all_all_context" in each_issue for each_issue in issues), (
+        f"loop3-1: stuttering with-as binding must be flagged, got: {issues}"
+    )
+
+
+def test_stuttering_collection_prefix_flags_except_as_binding_loop3_1() -> None:
+    source = (
+        "def f() -> None:\n"
+        "    try:\n"
+        "        pass\n"
+        "    except Exception as all_all_error:\n"
+        "        pass\n"
+    )
+    issues = code_rules_enforcer.check_stuttering_collection_prefix(
+        source, "packages/app/services/foo.py"
+    )
+    assert any("all_all_error" in each_issue for each_issue in issues), (
+        f"loop3-1: stuttering except-as binding must be flagged, got: {issues}"
+    )
+
+
+def test_stuttering_constants_live_under_config_subpackage() -> None:
+    """Stuttering-prefix constants must be sourced from the hooks-tree config package.
+
+    Per CODE_RULES, module-level UPPER_SNAKE constants must live under a
+    directory segment named ``config``. This test pins the move so the
+    constants cannot regress to inline definition at the enforcer module's
+    top level. The enforcer's own bootstrap inserts the hooks tree onto
+    ``sys.path`` so ``config.stuttering_check_config`` resolves at runtime.
+    """
+    assert (
+        code_rules_enforcer.STUTTERING_ALL_PREFIX_PATTERN
+        is config_stuttering_all_prefix_pattern
+    ), "Enforcer must reuse the hooks-tree config STUTTERING_ALL_PREFIX_PATTERN object"
+    assert (
+        code_rules_enforcer.MAX_STUTTERING_PREFIX_ISSUES
+        == config_max_stuttering_prefix_issues
+    ), "Enforcer must reuse the hooks-tree config MAX_STUTTERING_PREFIX_ISSUES value"
+
+
+SYS_PATH_INSERT_PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
+SYS_PATH_INSERT_HOOK_INFRASTRUCTURE_FILE_PATH = "/repo/.claude/hooks/blocking/some_hook.py"
+
+
+def test_sys_path_insert_should_flag_mismatched_guard_path() -> None:
+    source = (
+        "import sys\n"
+        'if "wrong_path" not in sys.path:\n'
+        '    sys.path.insert(0, "actual_path")\n'
+    )
+    issues = code_rules_enforcer.check_sys_path_insert_deduplication_guard(
+        source, SYS_PATH_INSERT_PRODUCTION_FILE_PATH
+    )
+    assert any("sys.path.insert" in each_issue for each_issue in issues), (
+        "Guard testing a different value than what is inserted must be flagged, "
+        f"got: {issues}"
+    )
+
+
+def test_sys_path_insert_should_not_flag_matching_guard_path() -> None:
+    source = (
+        "import sys\n"
+        'if "correct_path" not in sys.path:\n'
+        '    sys.path.insert(0, "correct_path")\n'
+    )
+    issues = code_rules_enforcer.check_sys_path_insert_deduplication_guard(
+        source, SYS_PATH_INSERT_PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Guard testing the same value that is inserted must not be flagged, got: {issues}"
+    )
+
+
+def test_sys_path_insert_should_not_flag_guarded_insert_in_class_body() -> None:
+    source = (
+        "import sys\n"
+        "class Configurator:\n"
+        "    target = '/some/path'\n"
+        "    if target not in sys.path:\n"
+        "        sys.path.insert(0, target)\n"
+    )
+    issues = code_rules_enforcer.check_sys_path_insert_deduplication_guard(
+        source, SYS_PATH_INSERT_PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Guarded sys.path.insert directly in a class body must not be flagged, got: {issues}"
+    )
+
+
+def test_sys_path_insert_should_skip_hook_infrastructure_files() -> None:
+    source = "import sys\nsys.path.insert(0, '/some/path')\n"
+    issues = code_rules_enforcer.check_sys_path_insert_deduplication_guard(
+        source, SYS_PATH_INSERT_HOOK_INFRASTRUCTURE_FILE_PATH
+    )
+    assert issues == [], (
+        f"Hook infrastructure files are exempt from this rule, got: {issues}"
+    )

package/hooks/blocking/test_code_rules_enforcer_annotations.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pathlib import Path
+import importlib.util
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location(
+    "code_rules_enforcer", ENFORCER_PATH
+)
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+PRODUCTION_FILE_PATH = "packages/app/services/foo.py"
+TEST_FILE_PATH = "packages/app/tests/test_foo.py"
+
+
+def test_should_flag_parameter_without_annotation() -> None:
+    source = "def consume(value) -> None:\n    return None\n"
+    issues = code_rules_enforcer.check_parameter_annotations(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("value" in each_issue for each_issue in issues), (
+        f"Expected unannotated parameter flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_annotated_parameters() -> None:
+    source = (
+        "def consume(value: int, label: str = 'default') -> None:\n    return None\n"
+    )
+    issues = code_rules_enforcer.check_parameter_annotations(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Expected no issues for annotated params, got: {issues}"
+
+
+def test_should_exempt_self_and_cls_parameters() -> None:
+    source = (
+        "class Foo:\n"
+        "    def method(self, value: int) -> None:\n"
+        "        return None\n"
+        "    @classmethod\n"
+        "    def factory(cls, value: int) -> 'Foo':\n"
+        "        return cls()\n"
+    )
+    issues = code_rules_enforcer.check_parameter_annotations(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"self/cls must be exempt from annotation requirement, got: {issues}"
+    )
+
+
+def test_should_flag_class_method_parameter_without_annotation() -> None:
+    source = "class Foo:\n    def method(self, value) -> None:\n        return None\n"
+    issues = code_rules_enforcer.check_parameter_annotations(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("value" in each_issue for each_issue in issues), (
+        f"Expected method param flagged, got: {issues}"
+    )
+
+
+def test_should_skip_parameter_check_in_test_files() -> None:
+    source = "def consume(value) -> None:\n    return None\n"
+    issues = code_rules_enforcer.check_parameter_annotations(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files must be exempt, got: {issues}"
+
+
+def test_should_flag_function_without_return_annotation() -> None:
+    source = "def fetch(url: str):\n    return url\n"
+    issues = code_rules_enforcer.check_return_annotations(source, PRODUCTION_FILE_PATH)
+    assert any("fetch" in each_issue for each_issue in issues), (
+        f"Expected function without return type flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_function_with_return_annotation() -> None:
+    source = "def fetch(url: str) -> str:\n    return url\n"
+    issues = code_rules_enforcer.check_return_annotations(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Function with return type must not be flagged, got: {issues}"
+
+
+def test_should_flag_async_function_without_return_annotation() -> None:
+    source = "async def fetch(url: str):\n    return url\n"
+    issues = code_rules_enforcer.check_return_annotations(source, PRODUCTION_FILE_PATH)
+    assert any("fetch" in each_issue for each_issue in issues), (
+        f"Expected async function without return type flagged, got: {issues}"
+    )
+
+
+def test_should_skip_return_check_in_test_files() -> None:
+    source = "def fetch(url: str):\n    return url\n"
+    issues = code_rules_enforcer.check_return_annotations(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files must be exempt, got: {issues}"
+
+

package/hooks/blocking/test_code_rules_enforcer_banned_identifier.py

@@ -229,3 +229,109 @@ def test_should_emit_stderr_advisory_on_syntax_error(
     captured = capsys.readouterr()  # type: ignore[attr-defined]
     assert "banned-identifier check skipped" in captured.err
     assert PRODUCTION_FILE_PATH in captured.err
+
+
+def test_should_flag_argv_assignment() -> None:
+    content = "def parse_command():\n    argv = collect()\n    return argv\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'argv'" in each_issue for each_issue in issues), (
+        f"Expected 'argv' flagged — use arguments_list, got: {issues}"
+    )
+
+
+def test_should_flag_args_assignment() -> None:
+    content = "def parse_command():\n    args = collect()\n    return args\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'args'" in each_issue for each_issue in issues), (
+        f"Expected 'args' flagged — use arguments, got: {issues}"
+    )
+
+
+def test_should_not_flag_args_assigned_parse_args_call() -> None:
+    content = (
+        "def main():\n"
+        "    parser = build_parser()\n"
+        "    args = parser.parse_args()\n"
+        "    return args\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "args = parser.parse_args() is established argparse idiom; must not flag, "
+        f"got: {issues}"
+    )
+
+
+def test_should_not_flag_args_annotated_parse_args_call() -> None:
+    content = (
+        "def main():\n"
+        "    parser = build_parser()\n"
+        "    args: object = parser.parse_args()\n"
+        "    return args\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Annotated parse_args binding must not flag, got: {issues}"
+
+
+def test_should_not_flag_args_walrus_parse_args_call() -> None:
+    content = (
+        "def main():\n"
+        "    parser = build_parser()\n"
+        "    if (args := parser.parse_args()):\n"
+        "        return args\n"
+        "    return None\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Walrus parse_args binding must not flag, got: {issues}"
+
+
+def test_should_flag_args_assigned_parse_args_method_reference() -> None:
+    content = (
+        "def main():\n"
+        "    parser = build_parser()\n"
+        "    args = parser.parse_args\n"
+        "    return args\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'args'" in each_issue for each_issue in issues), (
+        "Method reference (no call) is not the namespace idiom; must flag, "
+        f"got: {issues}"
+    )
+
+
+def test_should_flag_kwargs_assignment() -> None:
+    content = "def parse_command():\n    kwargs = collect()\n    return kwargs\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'kwargs'" in each_issue for each_issue in issues), (
+        f"Expected 'kwargs' flagged — use keyword_arguments, got: {issues}"
+    )
+
+
+def test_should_flag_argc_assignment() -> None:
+    content = "def parse_command():\n    argc = count()\n    return argc\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'argc'" in each_issue for each_issue in issues), (
+        f"Expected 'argc' flagged — use argument_count, got: {issues}"
+    )
+
+
+def test_should_not_flag_args_as_function_parameter() -> None:
+    content = (
+        "def passthrough(*args, **kwargs):\n"
+        "    return args, kwargs\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"*args/**kwargs parameters are Python convention, must not flag, got: {issues}"
+    )
+
+
+def test_should_not_flag_argv_substring_in_local_name() -> None:
+    content = (
+        "def parse_command():\n"
+        "    parsed_argv_entries = []\n"
+        "    return parsed_argv_entries\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Substring 'argv' inside parsed_argv_entries must not flag, got: {issues}"
+    )