claude-dev-env 1.68.0 → 1.69.1

package/hooks/blocking/test_code_rules_enforcer_class_docstring_methods.py

@@ -0,0 +1,262 @@
+"""Tests for check_class_docstring_names_public_methods — class prose breadth.
+
+A class whose docstring is a single summary line names one responsibility. When
+the class exposes a second public entry point the summary never names, the prose
+under-describes the class — the same drift the os_update_workflow break reporter
+hit when it grew a regular-pace method beside its coffee-break method.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_class_docstring_names_public_methods(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_class_docstring_names_public_methods(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+PRODUCTION_FILE_PATH = "/project/src/break_reporter.py"
+TEST_FILE_PATH = "/project/src/test_break_reporter.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _narrow_class_with_widened_surface() -> str:
+    return (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility: announce, then count down."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+
+
+def test_should_flag_single_line_docstring_omitting_two_public_methods() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), PRODUCTION_FILE_PATH
+    )
+    assert any("pause_then_resume" in each for each in issues), (
+        f"Expected omitted-method flag, got: {issues!r}"
+    )
+    assert any("stretch_then_resume" in each for each in issues)
+    assert len(issues) == 1
+
+
+def test_should_not_flag_when_summary_names_every_public_method() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Announce a pause then resume, or stretch then resume, with a countdown."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Summary naming every method must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_when_only_one_public_method_is_omitted() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Pause then resume the submission run with an operator countdown."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A single omitted method must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_multi_line_docstring_body() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility.\n'
+        "\n"
+        "    Also paces the regular between-theme waits through the same seam.\n"
+        '    """\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Multi-line docstrings go to the audit lane, got: {issues!r}"
+
+
+def test_should_not_flag_class_with_single_public_method() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A one-method class must not flag, got: {issues!r}"
+
+
+def test_should_skip_private_methods_when_counting_surface() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def _sleep(self, seconds: float) -> None:\n"
+        "        await self._clock.sleep(seconds)\n"
+        "\n"
+        "    def __init__(self) -> None:\n"
+        "        self._clock = None\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private and dunder methods are not public surface, got: {issues!r}"
+
+
+def test_should_skip_class_without_docstring() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"No-docstring classes are out of scope, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_class_docstring_names_public_methods("class Broken(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def _real_break_reporter_drift() -> str:
+    return (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee-break with operator visibility: announce, then count down."""\n'
+        "\n"
+        "    async def announce_and_pause(self, nominal_break_seconds: float) -> None:\n"
+        "        await self._announce(nominal_break_seconds)\n"
+        "\n"
+        "    async def announce_and_pause_exact(self, break_seconds: float) -> None:\n"
+        "        await self._announce(break_seconds)\n"
+    )
+
+
+def test_should_flag_real_break_reporter_widened_surface() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _real_break_reporter_drift(), PRODUCTION_FILE_PATH
+    )
+    assert any("announce_and_pause_exact" in each for each in issues), (
+        f"Expected the regular-pace method to flag, got: {issues!r}"
+    )
+    assert any("announce_and_pause" in each for each in issues)
+    assert len(issues) == 1
+
+
+def _overload_class_omitting_the_only_method() -> str:
+    return (
+        "from typing import overload\n"
+        "\n"
+        "class PayloadTransformer:\n"
+        '    """Hold a fixed payload value for later use."""\n'
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: str) -> dict[str, str]: ...\n"
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: bytes) -> dict[str, str]: ...\n"
+        "\n"
+        "    def transform(self, payload: str | bytes) -> dict[str, str]:\n"
+        "        return self._normalize(payload)\n"
+    )
+
+
+def test_should_not_flag_single_overloaded_method_below_breadth_threshold() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _overload_class_omitting_the_only_method(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"One overloaded public method must not flag, got: {issues!r}"
+
+
+def test_should_not_repeat_an_overloaded_name_in_the_issue_message() -> None:
+    source = (
+        "from typing import overload\n"
+        "\n"
+        "class PayloadTransformer:\n"
+        '    """Hold a fixed payload value for later use."""\n'
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: str) -> dict[str, str]: ...\n"
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: bytes) -> dict[str, str]: ...\n"
+        "\n"
+        "    def transform(self, payload: str | bytes) -> dict[str, str]:\n"
+        "        return self._normalize(payload)\n"
+        "\n"
+        "    def reset(self) -> None:\n"
+        "        self._payload = None\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1, f"Expected a single drift issue, got: {issues!r}"
+    only_issue = issues[0]
+    assert only_issue.count("transform") == 1, (
+        f"Overloaded name must appear once in the message, got: {only_issue!r}"
+    )
+    assert "reset" in only_issue
+
+
+def test_validate_content_surfaces_class_docstring_breadth_drift() -> None:
+    issues = validate_content(
+        _narrow_class_with_widened_surface(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [
+        each for each in issues if "pause_then_resume" in each and "public method" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the class-breadth drift, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_dead_config_field.py

@@ -223,19 +223,260 @@ def test_does_not_flag_field_used_only_as_replace_keyword(neutral_root: Path) ->
     )
 
 
-def test_does_not_flag_field_used_only_as_constructor_keyword(neutral_root: Path) -> None:
+def test_flags_field_set_only_by_constructor_keyword_and_read_nowhere(
+    neutral_root: Path,
+) -> None:
+    """A field set ONLY by a ``*Config`` constructor keyword, read nowhere, is dead.
+
+    A constructor keyword writes the field; it is not a read. When ``debug_port``
+    is set by ``ThemeUpdateConfig(debug_port=1)`` and read through no config
+    instance anywhere in production, tuning it has no effect, so it is flagged as
+    dead config (CODE_RULES §9.8).
+    """
     consumer_body = (
         "from os_update_workflow.config import ThemeUpdateConfig\n"
         "\n"
         "def build() -> ThemeUpdateConfig:\n"
-        "    return ThemeUpdateConfig(portal_url='x', debug_port=1, timeout_seconds=99)\n"
+        "    configuration = ThemeUpdateConfig(portal_url='x', debug_port=1, timeout_seconds=99)\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+        "    return configuration\n"
     )
     config_path = _build_config_package(
         neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
     )
     issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Field set only by constructor keyword and read nowhere must be flagged, got: {issues}"
+    )
+    assert not any(
+        "'portal_url'" in each_issue or "'timeout_seconds'" in each_issue for each_issue in issues
+    ), f"Fields read through the config instance must not be flagged, got: {issues}"
+
+
+def test_qualified_config_constructor_keyword_does_not_clear_field(
+    neutral_root: Path,
+) -> None:
+    """A qualified ``module.ThemeUpdateConfig(field=value)`` keyword is a write, not a read.
+
+    The constructor callee may be a qualified attribute (``config_module.ThemeUpdateConfig``)
+    rather than a bare name. Its keyword still writes the field, so a field set only
+    this way and read through no config instance is flagged dead.
+    """
+    consumer_body = (
+        "import os_update_workflow.config as config_module\n"
+        "\n"
+        "def build() -> config_module.ThemeUpdateConfig:\n"
+        "    configuration = config_module.ThemeUpdateConfig(\n"
+        "        portal_url='x', debug_port=1, timeout_seconds=99\n"
+        "    )\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+        "    return configuration\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"A qualified config constructor keyword is a write, so debug_port is flagged, got: {issues}"
+    )
+
+
+def test_does_not_flag_field_set_by_constructor_keyword_and_read_elsewhere(
+    neutral_root: Path,
+) -> None:
+    """A field set by a constructor keyword AND read via attribute elsewhere is live.
+
+    The constructor keyword does not clear the field, but a genuine attribute read
+    of the same field in another module does, so the field is not flagged.
+    """
+    builder_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def build() -> ThemeUpdateConfig:\n"
+        "    return ThemeUpdateConfig(portal_url='x', debug_port=1, timeout_seconds=99)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, builder_body
+    )
+    reader_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def connect(configuration: ThemeUpdateConfig) -> int:\n"
+        "    return configuration.debug_port\n"
+    )
+    (config_path.parent.parent / "reader.py").write_text(reader_body, encoding="utf-8")
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"An attribute read in another module keeps debug_port live, got: {issues}"
+    )
+
+
+def test_flags_field_set_by_default_and_constructor_keyword_only(
+    neutral_root: Path,
+) -> None:
+    """The PR #317 dead-config shape: field set by config default + constructor keyword only.
+
+    ``AppInfoConfig.sound_upload_max_attempts: int = submission_timing.sound_upload_max_attempts``
+    sets the field from a same-named attribute on another object inside the config
+    body, and the orchestrator sets ``sound_upload_timeout_ms`` by a constructor
+    keyword. Neither field is read through any config instance. The default-value
+    read inside the config body and the constructor keyword are both writes, so
+    both fields are flagged dead.
+
+    Residual limitation: when a consumer module's constructor VALUE expression
+    itself reads a same-named attribute on a different object
+    (``AppInfoConfig(field=other.field)``), the object-blind attribute-read
+    collector counts ``field`` as read and the field escapes. This test keeps the
+    constructor value a literal so the keyword-write and default-write exclusions
+    are exercised without that foreign-attribute leak.
+    """
+    config_body = (
+        "from dataclasses import dataclass\n"
+        "import submission_timing_module as submission_timing\n"
+        "\n"
+        "@dataclass(frozen=True)\n"
+        "class AppInfoConfig:\n"
+        "    sound_upload_timeout_ms: int = submission_timing.sound_upload_timeout_ms\n"
+        "    sound_upload_max_attempts: int = submission_timing.sound_upload_max_attempts\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(config_body, encoding="utf-8")
+    orchestrator_body = (
+        "from os_update_workflow.config import AppInfoConfig\n"
+        "\n"
+        "def build() -> AppInfoConfig:\n"
+        "    config = AppInfoConfig(sound_upload_timeout_ms=60000)\n"
+        "    return config\n"
+    )
+    (workflow_directory / "orchestrator.py").write_text(orchestrator_body, encoding="utf-8")
+    issues = _check(config_body, str(config_path))
+    assert any("'sound_upload_timeout_ms'" in each_issue for each_issue in issues), (
+        f"Field set by constructor keyword and read nowhere must be flagged, got: {issues}"
+    )
+    assert any("'sound_upload_max_attempts'" in each_issue for each_issue in issues), (
+        f"Field set by config default only and read nowhere must be flagged, got: {issues}"
+    )
+
+
+def test_does_not_flag_config_default_field_read_through_instance(
+    neutral_root: Path,
+) -> None:
+    """A field whose default reads a foreign attribute but is read through the instance is live.
+
+    The default-value exclusion only drops the self-referential read inside the
+    config body; a genuine ``config.sound_upload_timeout_ms`` read in production
+    keeps the field live.
+    """
+    config_body = (
+        "from dataclasses import dataclass\n"
+        "import submission_timing_module as submission_timing\n"
+        "\n"
+        "@dataclass(frozen=True)\n"
+        "class AppInfoConfig:\n"
+        "    sound_upload_timeout_ms: int = submission_timing.sound_upload_timeout_ms\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(config_body, encoding="utf-8")
+    processor_body = (
+        "from os_update_workflow.config import AppInfoConfig\n"
+        "\n"
+        "def wait(config: AppInfoConfig) -> int:\n"
+        "    return config.sound_upload_timeout_ms\n"
+    )
+    (workflow_directory / "processor.py").write_text(processor_body, encoding="utf-8")
+    issues = _check(config_body, str(config_path))
     assert issues == [], (
-        f"Constructor keyword arguments name every field, so none may be flagged, got: {issues}"
+        f"A genuine config-instance read keeps the field live, got: {issues}"
+    )
+
+
+def test_config_default_sourcing_differently_named_field_keeps_it_live(
+    neutral_root: Path,
+) -> None:
+    """A default that sources a DIFFERENTLY-named field on another config keeps it live.
+
+    ``AppConfig.timeout_ms: int = DEFAULT_TIMING.base_timeout`` reads
+    ``base_timeout`` on another config object inside the class body. The
+    default-value exclusion drops only the self-referential read whose attribute
+    name equals the field being defined; a differently-named attribute read is a
+    genuine consumer of ``base_timeout``, so it stays live and is not flagged.
+    """
+    config_body = (
+        "from dataclasses import dataclass\n"
+        "\n"
+        "@dataclass(frozen=True)\n"
+        "class TimingConfig:\n"
+        "    base_timeout: int\n"
+        "    poll_interval: int\n"
+        "\n"
+        "DEFAULT_TIMING = TimingConfig(base_timeout=30, poll_interval=5)\n"
+        "\n"
+        "@dataclass(frozen=True)\n"
+        "class AppConfig:\n"
+        "    timeout_ms: int = DEFAULT_TIMING.base_timeout\n"
+        "    poll_interval: int = DEFAULT_TIMING.poll_interval\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(config_body, encoding="utf-8")
+    consumer_body = (
+        "from os_update_workflow.config import AppConfig\n"
+        "\n"
+        "def run(app_config: AppConfig) -> int:\n"
+        "    return app_config.timeout_ms + app_config.poll_interval\n"
+    )
+    (workflow_directory / "runner.py").write_text(consumer_body, encoding="utf-8")
+    issues = _check(config_body, str(config_path))
+    assert not any("'base_timeout'" in each_issue for each_issue in issues), (
+        f"A default sourcing a differently-named field must keep it live, got: {issues}"
+    )
+    assert not any("'poll_interval'" in each_issue for each_issue in issues), (
+        f"poll_interval is read both in the default and the consumer, got: {issues}"
+    )
+
+
+def test_self_referential_default_still_excludes_only_the_self_read(
+    neutral_root: Path,
+) -> None:
+    """The self-referential default read is still excluded after narrowing.
+
+    ``sound_upload_timeout_ms: int = submission_timing.sound_upload_timeout_ms``
+    reads an attribute whose name equals the field being defined, so it is still
+    excluded; when that field is read by no module it stays flagged dead.
+    """
+    config_body = (
+        "from dataclasses import dataclass\n"
+        "import submission_timing_module as submission_timing\n"
+        "\n"
+        "@dataclass(frozen=True)\n"
+        "class AppInfoConfig:\n"
+        "    sound_upload_timeout_ms: int = submission_timing.sound_upload_timeout_ms\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(config_body, encoding="utf-8")
+    (workflow_directory / "runner.py").write_text(
+        "def noop() -> None:\n    pass\n", encoding="utf-8"
+    )
+    issues = _check(config_body, str(config_path))
+    assert any("'sound_upload_timeout_ms'" in each_issue for each_issue in issues), (
+        f"Self-referential default read is excluded, so the field stays flagged, got: {issues}"
     )
 
 
@@ -416,6 +657,98 @@ def test_dataclasses_qualified_replace_call_suppresses_so_no_field_flagged(
     )
 
 
+def test_aliased_replace_read_keeps_field_live_despite_constructor_keyword(
+    neutral_root: Path,
+) -> None:
+    """An aliased ``replace`` keyword read survives a same-module constructor keyword.
+
+    A module constructs ``ThemeUpdateConfig(debug_port=1)`` (a write) and also reads
+    the field through an aliased ``dataclasses.replace`` —
+    ``from dataclasses import replace as rep; rep(cfg, debug_port=2)``. The alias is
+    not the bare ``replace`` name, so the whole-instance reflective suppression does
+    not fire and the ``rep`` keyword stays a genuine field read. The constructor
+    keyword exclusion is scoped per-call, so the constructor's ``debug_port`` keyword
+    does not strip the ``rep`` keyword read and the field stays live.
+    """
+    consumer_body = (
+        "from dataclasses import replace as rep\n"
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def build_then_repoint() -> ThemeUpdateConfig:\n"
+        "    configuration = ThemeUpdateConfig(portal_url='x', debug_port=1, timeout_seconds=99)\n"
+        "    return rep(configuration, debug_port=2)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Aliased replace keyword read must keep debug_port live despite a"
+        f" same-module constructor keyword, got: {issues}"
+    )
+
+
+def test_factory_function_ending_in_config_keeps_field_live(
+    neutral_root: Path,
+) -> None:
+    """A keyword to a factory FUNCTION ending in ``Config`` is a read, not a write.
+
+    ``getThemeConfig(debug_port=1)`` calls a factory function, not a ``*Config``
+    dataclass constructor. The keyword passes a value into the function, so it
+    counts as a field read. The constructor-keyword exclusion fires only for a
+    callee that names a known ``*Config`` dataclass defined under the scan root, so
+    a factory function whose name merely ends in ``Config`` does not strip the
+    field.
+    """
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def getThemeConfig(portal_url: str, debug_port: int) -> ThemeUpdateConfig:\n"
+        "    return ThemeUpdateConfig(\n"
+        "        portal_url=portal_url, debug_port=debug_port, timeout_seconds=30\n"
+        "    )\n"
+        "\n"
+        "def run() -> ThemeUpdateConfig:\n"
+        "    print('x')\n"
+        "    return getThemeConfig(portal_url='x', debug_port=1)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"A keyword passed to a factory function ending in Config must keep the"
+        f" field live, got: {issues}"
+    )
+
+
+def test_dead_config_field_module_has_no_collection_parameter_naming_violation() -> None:
+    """The hook module's own source must pass the collection-parameter naming check.
+
+    The cross-module dead-config-field check passes a ``set[str]`` of config class
+    names through several helpers; every such collection parameter must carry the
+    ``all_`` prefix (CODE_RULES §5). Run the real collection-prefix check over this
+    module's on-disk source so a regression that drops the prefix fails here.
+    """
+    collection_naming_path = (
+        Path(__file__).resolve().parent / "code_rules_naming_collection.py"
+    )
+    naming_specification = importlib.util.spec_from_file_location(
+        "code_rules_naming_collection", collection_naming_path
+    )
+    assert naming_specification is not None and naming_specification.loader is not None
+    code_rules_naming_collection = importlib.util.module_from_spec(naming_specification)
+    naming_specification.loader.exec_module(code_rules_naming_collection)
+    module_path = Path(__file__).resolve().parent / "code_rules_dead_config_field.py"
+    module_source = module_path.read_text(encoding="utf-8")
+    issues = code_rules_naming_collection.check_collection_prefix(
+        module_source, str(module_path)
+    )
+    assert not any("Collection parameter" in each_issue for each_issue in issues), (
+        f"dead-config-field module has a collection-parameter naming violation: {issues}"
+    )
+
+
 def test_validate_content_dispatch_runs_dead_config_field_check(neutral_root: Path) -> None:
     workflow_directory = neutral_root / "workflow"
     config_package = workflow_directory / "os_update_workflow"

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -56,6 +56,12 @@ def _check(source: str, file_path: str) -> list[str]:
     return code_rules_enforcer.check_dead_module_constants(source, file_path)
 
 
+def _check_edit(fragment: str, full_file_content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_dead_module_constants(
+        fragment, file_path, full_file_content
+    )
+
+
 def _build_constants_package(
     workflow_directory: Path,
     constants_body: str,
@@ -94,6 +100,36 @@ def test_flags_constant_imported_by_no_module_in_the_tree(neutral_root: Path) ->
     ), f"Imported constants must not be flagged, got: {issues}"
 
 
+def test_flags_a_dead_constant_added_by_an_edit_to_an_existing_module(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from report_constants.render_report_constants import (\n"
+        "    MEDIUM_CODE,\n"
+        "    MEDIUM_TERMINAL,\n"
+        ")\n"
+        "\n"
+        "def panel_class(medium: str) -> str:\n"
+        "    if medium == MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    return 'code-panel' if medium == MEDIUM_CODE else 'text-panel'\n"
+    )
+    prior_body = 'MEDIUM_TERMINAL = "terminal"\nMEDIUM_CODE = "code"\n'
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", prior_body, consumer_body
+    )
+    edit_fragment = 'MEDIUM_CODE = "code"\nMEDIUM_TEXT = "text"\n'
+    post_edit_body = prior_body + 'MEDIUM_TEXT = "text"\n'
+    issues = _check_edit(edit_fragment, post_edit_body, str(constants_path))
+    assert any("MEDIUM_TEXT" in each_issue for each_issue in issues), (
+        f"An Edit that inserts a dead constant must be flagged, got: {issues}"
+    )
+    assert not any(
+        "MEDIUM_TERMINAL" in each_issue or "MEDIUM_CODE" in each_issue
+        for each_issue in issues
+    ), f"Imported constants must not be flagged on an edit, got: {issues}"
+
+
 def test_does_not_flag_constant_imported_one_directory_up(neutral_root: Path) -> None:
     consumer_uses_text = (
         "from report_constants.render_report_constants import (\n"