claude-dev-env 1.69.0 → 1.69.1

package/hooks/blocking/code_rules_dead_config_field.py

@@ -20,10 +20,23 @@ The scan is deliberately conservative to keep false positives near zero:
 - Field reads are collected as ``ast.Attribute.attr`` values (``obj.field``),
   augmented-assignment targets (``cfg.field += 1`` reads ``field`` before
   writing it), string literals (covers ``getattr(obj, "field")``),
-  keyword-argument names (covers ``ThemeUpdateConfig(debug_port=1)`` and
+  keyword-argument names on non-constructor calls (covers
   ``replace(cfg, debug_port=1)``), and match-pattern keyword attribute names
-  (``case Config(field=found)``). Plain ``ast.Name`` references are excluded — a
-  local variable named ``debug_port`` is not a read of ``config.debug_port``.
+  (``case Config(field=found)``). Two field-write forms are excluded because they
+  name a field without consuming it: a keyword that writes a field in a constructor
+  of a known ``*Config`` dataclass defined under the scan root
+  (``ThemeUpdateConfig(debug_port=1)``, excluded per keyword node so a same-named
+  keyword on a ``replace`` call stays a read, and a factory function whose name
+  merely ends in ``"Config"`` is not excluded), and a self-referential attribute
+  read inside a ``*Config`` field's own default-value expression in the class body
+  whose attribute name equals the field being defined
+  (``debug_port: int = source.debug_port``) — a field written only these ways and
+  read by no module is the dead-config case this check exists to catch. A default
+  that sources a differently-named field on another object
+  (``timeout_ms: int = other_config.base_timeout``) leaves that read counted, so
+  ``base_timeout`` stays a live consumer. Plain
+  ``ast.Name`` references are excluded — a local variable named ``debug_port`` is
+  not a read of ``config.debug_port``.
 - A production module that reflectively reads a whole instance — a bare or
   ``dataclasses``-qualified call to ``asdict``, ``astuple``, ``fields``,
   ``replace``, or ``vars``, or a read of ``obj.__dict__`` — consumes every field
@@ -50,6 +63,7 @@ before writing it) is precise and remains a counted read.
 import ast
 import os
 import sys
+from collections.abc import Iterator
 from pathlib import Path
 
 _blocking_directory = str(Path(__file__).resolve().parent)
@@ -137,79 +151,242 @@ def _reads_whole_instance_reflectively(tree: ast.Module) -> bool:
     return False
 
 
-def _attribute_read_names_in_source(source: str) -> tuple[set[str], bool]:
-    """Return attribute names read in a module's source and a suppression flag.
+def _config_dataclass_names(tree: ast.Module) -> set[str]:
+    """Return names of ``*Config`` ``@dataclass`` classes defined in a module.
+
+    A constructor-keyword exclusion fires only for a callee that names a genuine
+    config dataclass, so the caller first gathers the config dataclass names a
+    module defines, then unions those names across the scan root.
+
+    Args:
+        tree: The parsed module to inspect.
+
+    Returns:
+        Every class name in the module that is a ``@dataclass`` whose name ends in
+        the config class name suffix.
+    """
+    config_dataclass_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.ClassDef) and _is_config_dataclass(each_node):
+            config_dataclass_names.add(each_node.name)
+    return config_dataclass_names
+
+
+def _call_constructs_config_class(
+    call_node: ast.Call, all_known_config_class_names: set[str]
+) -> bool:
+    """Return whether a call constructs a known ``*Config`` dataclass.
+
+    A call whose callee names a ``*Config`` dataclass defined under the scan root —
+    ``AppInfoConfig(...)`` or a qualified ``module.AppInfoConfig(...)`` —
+    constructs a config instance, and its keyword arguments write the named fields
+    rather than read them. A factory function whose name merely ends in
+    ``"Config"`` (``getThemeConfig(...)``) is not a known config dataclass, so its
+    keyword arguments stay genuine reads.
+
+    Args:
+        call_node: The call expression to test.
+        all_known_config_class_names: Names of ``*Config`` dataclasses defined under
+            the scan root.
+
+    Returns:
+        True when the callee names a known ``*Config`` dataclass.
+    """
+    callee_node = call_node.func
+    if isinstance(callee_node, ast.Name):
+        return callee_node.id in all_known_config_class_names
+    if isinstance(callee_node, ast.Attribute):
+        return callee_node.attr in all_known_config_class_names
+    return False
+
+
+def _config_constructor_keyword_node_ids(
+    tree: ast.Module, all_known_config_class_names: set[str]
+) -> set[int]:
+    """Return ids of keyword nodes that write fields in a known ``*Config`` constructor.
+
+    A keyword in an ``AppInfoConfig(field=value)`` call sets ``field`` rather than
+    reading it, so its node id is collected for the caller to exclude. The
+    exclusion is keyed per keyword node, not by name, so a same-named keyword in a
+    ``replace(cfg, field=value)`` call — which reuses a live instance and stays a
+    read — keeps its own distinct node and is not stripped.
+
+    Args:
+        tree: The parsed module to inspect.
+        all_known_config_class_names: Names of ``*Config`` dataclasses defined under
+            the scan root.
+
+    Returns:
+        The ``id()`` of every keyword node passed to a known ``*Config``
+        constructor call.
+    """
+    constructor_keyword_node_ids: set[int] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Call):
+            continue
+        if not _call_constructs_config_class(each_node, all_known_config_class_names):
+            continue
+        for each_keyword in each_node.keywords:
+            if each_keyword.arg is not None:
+                constructor_keyword_node_ids.add(id(each_keyword))
+    return constructor_keyword_node_ids
+
+
+def _self_referential_default_attribute_node_ids(
+    field_name: str, default_value: ast.expr
+) -> set[int]:
+    """Return ids of attribute reads in a default whose name equals the field.
+
+    Walks a ``*Config`` field's default-value expression and collects the ``id()``
+    of each ``ast.Attribute`` read whose ``.attr`` equals ``field_name``. Such a
+    read — ``sound_upload_timeout_ms: int = submission_timing.sound_upload_timeout_ms``
+    — names the field being defined inside the class body, so it is not a consumer
+    of the field. An attribute read of a differently-named field
+    (``timeout_ms: int = other_config.base_timeout``) is a genuine consumer and is
+    left out of the returned set.
+
+    Args:
+        field_name: The name of the field being defined.
+        default_value: The default-value expression of that field.
+
+    Returns:
+        The ``id()`` of every self-referential attribute read inside the
+        default-value expression.
+    """
+    self_referential_node_ids: set[int] = set()
+    for each_inner_node in ast.walk(default_value):
+        if isinstance(each_inner_node, ast.Attribute) and each_inner_node.attr == field_name:
+            self_referential_node_ids.add(id(each_inner_node))
+    return self_referential_node_ids
+
+
+def _config_field_default_value_nodes(tree: ast.Module) -> set[int]:
+    """Return ids of self-referential attribute reads in ``*Config`` field defaults.
+
+    A field default such as ``sound_upload_timeout_ms: int =``
+    ``submission_timing.sound_upload_timeout_ms`` is an attribute read whose name
+    matches the field being defined. That self-referential read inside the config
+    class body is not a consumer of the field, so its node id is collected here for
+    the caller to exclude from the attribute-read set. Only the attribute read
+    whose ``.attr`` equals the field name is collected; a default that sources a
+    differently-named field on another object
+    (``timeout_ms: int = other_config.base_timeout``) leaves that read counted, so
+    ``base_timeout`` stays a live consumer.
+
+    Args:
+        tree: The parsed module to inspect.
+
+    Returns:
+        The ``id()`` of every self-referential attribute read within the
+        default-value expression of a field declared in a ``*Config`` dataclass
+        body.
+    """
+    default_value_node_ids: set[int] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.ClassDef) or not _is_config_dataclass(each_node):
+            continue
+        for each_statement in each_node.body:
+            if not isinstance(each_statement, ast.AnnAssign):
+                continue
+            if each_statement.value is None:
+                continue
+            if not isinstance(each_statement.target, ast.Name):
+                continue
+            default_value_node_ids |= _self_referential_default_attribute_node_ids(
+                each_statement.target.id, each_statement.value
+            )
+    return default_value_node_ids
+
+
+def _attribute_read_names_in_tree(
+    tree: ast.Module, all_known_config_class_names: set[str]
+) -> tuple[set[str], bool]:
+    """Return attribute names read in a parsed module and a suppression flag.
 
     Collects attribute names via five mechanisms: ``ast.Attribute.attr`` values
     in Load context, augmented-assignment targets (so ``cfg.debug_port += 1``
     contributes ``"debug_port"`` because ``+=`` reads the attribute before
     writing it), string literals (so ``getattr(obj, "field")`` contributes
-    ``"field"``), keyword-argument names (so ``ThemeUpdateConfig(debug_port=1)``
-    and ``replace(cfg, debug_port=1)`` each contribute ``"debug_port"``), and
-    ``ast.MatchClass.kwd_attrs`` names (so ``case Config(field=x)`` contributes
-    ``"field"``). The boolean reports whether the module suppresses the
-    dead-field check, which it does only when it reflectively reads a whole
-    instance — a bare or ``dataclasses``-qualified ``asdict``/``astuple``/
-    ``fields``/``replace``/``vars`` call, or an ``obj.__dict__`` read — because
-    that pattern reads every field at once without naming any single field, so
-    the caller treats it as "cannot prove any field dead". A ``SyntaxError``
-    contributes no names and no suppression.
+    ``"field"``), keyword-argument names (so ``replace(cfg, debug_port=1)``
+    contributes ``"debug_port"``), and ``ast.MatchClass.kwd_attrs`` names (so
+    ``case Config(field=x)`` contributes ``"field"``). Two field-write forms are
+    excluded because they name a field without consuming it: a keyword that writes
+    a field in a known ``*Config`` constructor (``AppInfoConfig(field=value)``,
+    excluded per keyword node so a same-named ``replace`` keyword stays a read),
+    and a self-referential attribute read inside a ``*Config`` dataclass field's
+    own default-value expression (``field: int = source.field`` in the class body,
+    excluded only when the read name equals the field name) — counting either
+    would hide a field that is written but read by no module. A keyword passed to a
+    factory function whose name merely ends in ``"Config"`` is not a known config
+    constructor, so it stays a read. The boolean reports whether the module
+    suppresses the dead-field check, which it does only when it reflectively reads a
+    whole instance — a bare or ``dataclasses``-qualified
+    ``asdict``/``astuple``/``fields``/``replace``/``vars`` call, or an
+    ``obj.__dict__`` read — because that pattern reads every field at once without
+    naming any single field, so the caller treats it as "cannot prove any field
+    dead".
 
     Args:
-        source: The full text of a ``.py`` module.
+        tree: The parsed module to inspect.
+        all_known_config_class_names: Names of ``*Config`` dataclasses defined under
+            the scan root, used to scope the constructor-keyword exclusion to
+            genuine config constructors.
 
     Returns:
         A (read_names, suppresses_dead_field_check) pair. The name set is every
-        attribute name the module reads via any of the five mechanisms above;
-        suppresses_dead_field_check is True only when a reflective whole-instance
-        read is present.
+        attribute name the module reads via the mechanisms above, excluding known
+        ``*Config`` constructor keyword nodes and self-referential config-field
+        default-value attribute reads; suppresses_dead_field_check is True only when
+        a reflective whole-instance read is present.
     """
-    try:
-        tree = ast.parse(source)
-    except SyntaxError:
-        return set(), False
     all_read_names: set[str] = _augmented_assignment_attribute_names(tree)
+    config_constructor_keyword_node_ids = _config_constructor_keyword_node_ids(
+        tree, all_known_config_class_names
+    )
+    config_field_default_node_ids = _config_field_default_value_nodes(tree)
     for each_node in ast.walk(tree):
-        if isinstance(each_node, ast.Attribute) and isinstance(each_node.ctx, ast.Load):
+        if (
+            isinstance(each_node, ast.Attribute)
+            and isinstance(each_node.ctx, ast.Load)
+            and id(each_node) not in config_field_default_node_ids
+        ):
             all_read_names.add(each_node.attr)
         elif isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
             all_read_names.add(each_node.value)
         elif isinstance(each_node, ast.MatchClass):
             all_read_names.update(each_node.kwd_attrs)
-        elif isinstance(each_node, ast.keyword) and each_node.arg is not None:
+        elif (
+            isinstance(each_node, ast.keyword)
+            and each_node.arg is not None
+            and id(each_node) not in config_constructor_keyword_node_ids
+        ):
             all_read_names.add(each_node.arg)
     suppresses_dead_field_check = _reads_whole_instance_reflectively(tree)
     return all_read_names, suppresses_dead_field_check
 
 
-def _all_production_read_names_under_root(
+def _iter_production_module_sources(
     scan_root: Path,
     written_path: Path,
     written_content: str,
-) -> tuple[set[str], bool, bool]:
-    """Return read names, a cap-hit flag, and a suppression flag for the tree.
+) -> Iterator[str | None]:
+    """Yield the source of each production module under the scan root.
 
-    Scans every production ``.py`` module under ``scan_root`` (excluding test and
-    migration files) for attribute reads. The written module's post-edit content
-    replaces its on-disk text so the current edit is included. Scanning stops at
-    the configured file cap. A module that reflectively reads a whole instance —
-    a bare or ``dataclasses``-qualified ``asdict``/``astuple``/``fields``/
-    ``replace``/``vars`` call, or an ``obj.__dict__`` read — sets the suppression
-    flag, signalling the caller that no field can be proven dead.
+    Yields ``written_content`` for the written module so the current edit is
+    included, then each sibling production module's source (excluding test and
+    migration files). A sibling whose text cannot be read is skipped. A single
+    ``None`` is yielded when the production module count exceeds the configured
+    file cap, signalling the caller that no field can be proven dead.
 
     Args:
         scan_root: The directory tree to scan.
         written_path: The resolved path of the module being written.
         written_content: The post-edit text of the written module.
 
-    Returns:
-        A (read_names, cap_was_hit, suppresses_dead_field_check) triple. The name
-        set is the union of attribute reads across every scanned production
-        module; cap_was_hit is True when the scan stopped at the configured file
-        cap before finishing the tree; suppresses_dead_field_check is True when
-        any scanned module reflectively reads a whole instance.
+    Yields:
+        Each production module's source text, or a single ``None`` on a cap hit.
     """
-    all_read_names, suppresses_dead_field_check = _attribute_read_names_in_source(written_content)
+    yield written_content
     written_path_key = os.path.normcase(str(written_path))
     scanned_file_count = 1
     for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
@@ -223,17 +400,71 @@ def _all_production_read_names_under_root(
             continue
         scanned_file_count += 1
         if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
-            return all_read_names, True, suppresses_dead_field_check
+            yield None
+            return
         try:
-            sibling_source = each_path.read_text(encoding="utf-8")
+            yield each_path.read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError):
             continue
-        sibling_read_names, sibling_suppresses_dead_field_check = _attribute_read_names_in_source(
-            sibling_source
+
+
+def _all_production_read_names_under_root(
+    scan_root: Path,
+    written_path: Path,
+    written_content: str,
+) -> tuple[set[str], bool, bool]:
+    """Return read names, a cap-hit flag, and a suppression flag for the tree.
+
+    Reads and AST-parses every production ``.py`` module under ``scan_root``
+    (excluding test and migration files) at most once: the module sources are
+    materialized once, a first pass over the cached sources gathers every
+    ``*Config`` dataclass name defined under the root so the constructor-keyword
+    exclusion fires only for a genuine config constructor, and a second pass over
+    the same cached sources collects attribute reads. The written module's
+    post-edit content replaces its on-disk text so the current edit is included.
+    Scanning stops at the configured file cap. A module that reflectively reads a
+    whole instance — a bare or ``dataclasses``-qualified
+    ``asdict``/``astuple``/``fields``/``replace``/``vars`` call, or an
+    ``obj.__dict__`` read — sets the suppression flag, signalling the caller that
+    no field can be proven dead.
+
+    Args:
+        scan_root: The directory tree to scan.
+        written_path: The resolved path of the module being written.
+        written_content: The post-edit text of the written module.
+
+    Returns:
+        A (read_names, cap_was_hit, suppresses_dead_field_check) triple. The name
+        set is the union of attribute reads across every scanned production
+        module; cap_was_hit is True when the scan stopped at the configured file
+        cap before finishing the tree; suppresses_dead_field_check is True when
+        any scanned module reflectively reads a whole instance.
+    """
+    all_module_sources = list(
+        _iter_production_module_sources(scan_root, written_path, written_content)
+    )
+    if None in all_module_sources:
+        return set(), True, False
+    all_production_trees: list[ast.Module] = []
+    for each_source in all_module_sources:
+        if each_source is None:
+            continue
+        try:
+            all_production_trees.append(ast.parse(each_source))
+        except SyntaxError:
+            continue
+    all_known_config_class_names: set[str] = set()
+    for each_tree in all_production_trees:
+        all_known_config_class_names |= _config_dataclass_names(each_tree)
+    all_read_names: set[str] = set()
+    suppresses_dead_field_check = False
+    for each_tree in all_production_trees:
+        module_read_names, module_suppresses_dead_field_check = _attribute_read_names_in_tree(
+            each_tree, all_known_config_class_names
         )
-        all_read_names |= sibling_read_names
+        all_read_names |= module_read_names
         suppresses_dead_field_check = (
-            suppresses_dead_field_check or sibling_suppresses_dead_field_check
+            suppresses_dead_field_check or module_suppresses_dead_field_check
         )
     return all_read_names, False, suppresses_dead_field_check
 
@@ -247,9 +478,12 @@ def check_dead_config_dataclass_fields(
     in ``"Config"``. For each such config dataclass in the written file, every
     instance field whose name does not appear as an attribute read (``obj.field``),
     augmented-assignment target (``cfg.field += 1``), string literal,
-    keyword-argument name (constructor or ``replace`` keyword), or match-pattern
+    non-constructor keyword-argument name (``replace`` keyword), or match-pattern
     keyword attribute in any production module under the enclosing scan root is
-    flagged as dead. When any production module under the scan root reflectively
+    flagged as dead. A keyword that writes a field in a ``*Config`` constructor
+    (``ThemeUpdateConfig(debug_port=1)``) is a write, not a read, so it does not
+    clear a field — a field set by a constructor keyword and read by no module is
+    flagged. When any production module under the scan root reflectively
     reads a whole instance — a bare or ``dataclasses``-qualified call to
     ``asdict``, ``astuple``, ``fields``, ``replace``, or ``vars``, or a read of
     ``obj.__dict__`` — the check is suppressed for the whole tree and returns

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/package.json

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