claude-dev-env 1.68.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/code_rules_docstrings.py

@@ -26,9 +26,11 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
+    MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
     MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
+    MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_DOCSTRING_ARGS_SECTION_HEADERS,
@@ -462,3 +464,98 @@ def check_docstring_fallback_branch_coverage(content: str, file_path: str) -> li
         if len(issues) >= MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES:
             break
     return issues[:MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES]
+
+
+def _class_docstring_summary_is_single_line(docstring_text: str) -> bool:
+    stripped_text = docstring_text.strip()
+    if not stripped_text:
+        return False
+    summary_line, separator, _remainder = stripped_text.partition("\n")
+    if separator and stripped_text[len(summary_line):].strip():
+        return False
+    return bool(summary_line.strip())
+
+
+def _public_method_names(class_node: ast.ClassDef) -> list[str]:
+    deduplicated_names: dict[str, None] = {}
+    for each_statement in class_node.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_private_or_dunder(each_statement.name):
+            continue
+        deduplicated_names[each_statement.name] = None
+    return list(deduplicated_names)
+
+
+def _name_tokens(method_name: str) -> list[str]:
+    return [each_token for each_token in method_name.split("_") if each_token]
+
+
+def _docstring_mentions_method(docstring_text: str, method_name: str) -> bool:
+    lowered_docstring = docstring_text.lower()
+    if method_name.lower() in lowered_docstring:
+        return True
+    return all(
+        each_token.lower() in lowered_docstring for each_token in _name_tokens(method_name)
+    )
+
+
+def _unmentioned_public_methods(class_node: ast.ClassDef, docstring_text: str) -> list[str]:
+    return [
+        each_name
+        for each_name in _public_method_names(class_node)
+        if not _docstring_mentions_method(docstring_text, each_name)
+    ]
+
+
+def check_class_docstring_names_public_methods(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a one-line class docstring that omits two or more public methods.
+
+    A class whose docstring is a single summary line names one responsibility,
+    so a reader trusts that line to describe the whole class. When the class
+    later gains a second public entry point — the drift pattern where a
+    coffee-break reporter grows a regular-pace method — the terse summary keeps
+    describing only the original feature. Each public method whose name (or all
+    of its underscore-separated tokens) appears nowhere in the summary counts as
+    omitted; a class with two or more omitted public methods is reported so the
+    summary is widened to name the broader surface. Classes with a multi-line
+    docstring body are left to the audit lane, since their prose can carry the
+    enumeration without naming each method by name.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per class whose single-line docstring omits two or more of its
+        public methods, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ClassDef):
+            continue
+        class_docstring = ast.get_docstring(each_node) or ""
+        if not _class_docstring_summary_is_single_line(class_docstring):
+            continue
+        public_names = _public_method_names(each_node)
+        if len(public_names) < MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH:
+            continue
+        unmentioned_names = _unmentioned_public_methods(each_node, class_docstring)
+        if len(unmentioned_names) < MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name} one-line docstring omits "
+            f"public method(s) {', '.join(unmentioned_names)} — widen the summary "
+            "so it names the class's full public surface"
+        )
+        if len(issues) >= MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES:
+            break
+    return issues[:MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES]

package/hooks/blocking/code_rules_enforcer.py

@@ -65,6 +65,7 @@ from code_rules_dead_module_constant import (  # noqa: E402
     check_dead_module_constants,
 )
 from code_rules_docstrings import (  # noqa: E402
+    check_class_docstring_names_public_methods,
     check_docstring_args_match_signature,
     check_docstring_fallback_branch_coverage,
     check_docstring_format,
@@ -250,6 +251,9 @@ def validate_content(
         all_issues.extend(check_docstring_format(effective_content, file_path))
         all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
         all_issues.extend(check_docstring_fallback_branch_coverage(effective_content, file_path))
+        all_issues.extend(
+            check_class_docstring_names_public_methods(effective_content, file_path)
+        )
         all_issues.extend(
             check_boolean_naming(
                 effective_content,

package/hooks/blocking/config/CLAUDE.md

@@ -0,0 +1,22 @@
+# hooks/blocking/config
+
+A Python package that holds shared constants for the verified-commit gate family. Three modules in `blocking/` import from here:
+
+- `verification_verdict_store.py`
+- `verified_commit_gate.py`
+- `verifier_verdict_minter.py`
+
+## Key files
+
+| File | Contents |
+|---|---|
+| `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
+| `verified_commit_constants.py` | All tunables for the gate: directory names, regex patterns for detecting verdict paths and obfuscation attempts, timeout values, git subcommand sets, bypass marker, and corrective messages |
+
+## Key constants in `verified_commit_constants.py`
+
+- `VERIFICATION_BYPASS_MARKER` — the `# verify-skip` comment that exempts a single commit/push from the gate
+- `MINTING_AGENT_TYPE` — `"code-verifier"`, the agent type whose SubagentStop hook mints verdicts
+- `VERDICT_DIRECTORY_NAME` — `"verification"`, the directory under `~/.claude/` that holds verdict JSON files
+- `DOCS_ONLY_EXTENSIONS` — extensions (`.md`, `.txt`, images) whose changes are mechanically exempt from the gate
+- `CORRECTIVE_MESSAGE` / `VERDICT_DIRECTORY_GUARD_MESSAGE` — user-facing block messages