claude-dev-env 1.77.0 → 1.79.0

package/hooks/blocking/code_rules_docstrings.py

@@ -22,6 +22,8 @@ from code_rules_shared import (  # noqa: E402
 )
 
 from hooks_constants.blocking_check_limits import (  # noqa: E402
+    ALL_DATA_SCHEMA_CONSTANT_NAME_MARKERS,
+    ALL_DATA_SCHEMA_DOCSTRING_ACKNOWLEDGEMENT_PHRASES,
     ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES,
     ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES,
     ALL_DOCSTRING_FILE_REFERENCE_SUFFIXES,
@@ -30,41 +32,70 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES,
     ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES,
     ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES,
+    ALL_DOCSTRING_NO_NETWORK_CLAIM_PHRASES,
     ALL_DOCSTRING_NON_CONSTANT_REFERENCE_MARKERS,
+    ALL_DOCSTRING_PER_RECORD_WRITE_OUTCOME_PHRASES,
+    ALL_DOCSTRING_RUN_MODE_PHRASES,
+    ALL_DOCSTRING_RUNMODE_FLAG_FIELD_NAME_TOKENS,
     ALL_DOCSTRING_RUNON_JOINER_MARKERS,
+    ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES,
+    ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES,
+    ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES,
     ALL_GENERIC_CHECK_NAME_TOKENS,
+    ALL_LENGTH_CONSTANT_NAME_SUFFIXES,
+    ALL_LENGTH_SUPERLATIVE_RANGE_PHRASES,
     ALL_NAMING_CONVENTION_DESCRIPTOR_TOKENS,
+    ALL_PATH_METADATA_ACCESS_METHOD_NAMES,
+    ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES,
+    ALL_USER_FACING_TEXT_SCOPE_DOCSTRING_PHRASES,
+    ALL_ZIPFILE_WRITE_MODE_VALUES,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
+    DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME,
     DOCSTRING_REFERENCE_MARKER_WINDOW,
     DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN,
     DOCSTRING_RUNON_SENTENCE_WORD_LIMIT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
+    LENGTH_CONFIG_SUBDIRECTORY_NAME,
+    LENGTH_GATE_PACKAGE_SCAN_FILE_LIMIT,
     MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
+    MAX_COMPANION_MODULE_RESOLUTION_DEPTH,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
+    MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES,
     MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES,
     MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
+    MAX_DOCSTRING_FIELD_RUNMODE_OUTCOME_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
     MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES,
+    MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES,
     MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
+    MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES,
+    MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES,
+    MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
-    ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES,
-    ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES,
-    ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES,
-    MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES,
     MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
-    MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
     MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES,
     MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES,
+    MAX_LENGTH_CONSTANT_SUPERLATIVE_ISSUES,
     MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES,
+    MAX_MODULE_DOCSTRING_DATA_SCHEMA_SCOPE_ISSUES,
     MINIMUM_CONSTANT_FAMILY_MEMBERS_FOR_CARDINAL_CHECK,
     MINIMUM_DOCSTRING_FAMILY_OVERLAP_FOR_CARDINAL_CHECK,
     MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK,
+    MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
     MINIMUM_TOKENS_FOR_DISPATCH_CALLEE,
     MINIMUM_TUPLE_MEMBERS_FOR_DOCSTRING_ENUMERATION,
+    MODULE_DOCSTRING_DATA_SCHEMA_CONSTANT_SAMPLE_LIMIT,
+    PYTHON_MODULE_FILE_SUFFIX,
     SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT,
+    WORD_BOUNDARY_REGEX,
+    ZIPFILE_ALLOW_ZIP64_KEYWORD,
+    ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX,
+    ZIPFILE_MODE_KEYWORD,
+    ZIPFILE_MODE_POSITIONAL_INDEX,
+    ZIPFILE_WRITER_CLASS_NAME,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_CAPS_WITH_UNDERSCORE_PATTERN,
@@ -355,6 +386,71 @@ def check_docstring_args_match_signature(content: str, file_path: str) -> list[s
     return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
 
 
+def check_docstring_documents_unreferenced_parameter(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a documented Args parameter the function body never references.
+
+    A parameter that appears in the ``Args:`` block but is named nowhere in the
+    body is dead: the function does not read it, yet the docstring describes
+    behavior keyed to it. The common shape is a flag that a caller wired in,
+    then moved the real logic up a level — the parameter and its Args line stay
+    behind, claiming a behavior the body does not implement. Both the unused
+    parameter and the stale Args claim drift together, so the gate catches them
+    as one finding.
+
+    Functions whose signature accepts ``**kwargs`` are skipped, because a
+    documented name may be a keyword key consumed through the kwargs mapping
+    rather than a named parameter. Private, dunder, abstract, and stub-bodied
+    functions are skipped, since a parameter declared for interface conformance
+    legitimately goes unread.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per documented-but-unreferenced parameter, 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.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_private_or_dunder(each_node.name):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        if _function_body_line_count(each_node) <= DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT:
+            continue
+        if each_node.args.kwarg is not None:
+            continue
+        documented_names = _documented_argument_names(_function_docstring_text(each_node))
+        if not documented_names:
+            continue
+        real_names = _signature_parameter_names(each_node)
+        referenced_names = _names_referenced_in_function(each_node)
+        for each_documented_name in documented_names:
+            if each_documented_name not in real_names:
+                continue
+            if each_documented_name in referenced_names:
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: {each_node.name}() docstring Args: documents "
+                f"'{each_documented_name}' but the body never references it - drop the "
+                "unused parameter and its Args line, or use it"
+            )
+            if len(issues) >= MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES:
+                return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
+    return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
+
+
 def _callee_expression_name(expression: ast.expr) -> str:
     if isinstance(expression, ast.Name):
         return expression.id
@@ -777,6 +873,92 @@ def check_docstring_unguarded_malformed_payload_claim(
     return issues[:MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES]
 
 
+def _docstring_claims_no_network_access(docstring_text: str) -> str:
+    collapsed_docstring = " ".join(docstring_text.lower().split())
+    for each_phrase in ALL_DOCSTRING_NO_NETWORK_CLAIM_PHRASES:
+        if each_phrase in collapsed_docstring:
+            return each_phrase
+    return ""
+
+
+def _function_performs_path_metadata_access(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> str:
+    for each_descendant in ast.walk(function_node):
+        if not isinstance(each_descendant, ast.Call):
+            continue
+        callee = each_descendant.func
+        if (
+            isinstance(callee, ast.Attribute)
+            and callee.attr in ALL_PATH_METADATA_ACCESS_METHOD_NAMES
+        ):
+            return callee.attr
+    return ""
+
+
+def check_docstring_no_network_claim_with_metadata_access(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring promising no network touch while the body stats a path.
+
+    Picture a cache helper whose docstring says it returns the warm cache
+    "without touching the network." A reader trusts that a cache hit costs
+    nothing on the share. But the body calls ``share_path.is_file()`` and
+    ``share_path.stat().st_size`` before it can return the cache — and on a
+    network share each of those metadata calls is a round-trip over the wire.
+    The promise drifts: every cache hit still pays two network stats the
+    docstring swore it avoided.
+
+    This is the deterministic slice of Category O6 (docstring prose versus
+    implementation drift) for a no-network claim: a function docstring that
+    states the path returns ``without touching the network`` (or a sibling
+    no-network phrase) while the body calls ``is_file``, ``is_dir``,
+    ``exists``, ``stat``, or ``lstat``. Either reword the claim to state that
+    the path is stat-checked on every call, or short-circuit to the cached
+    path before the share is touched.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose no-network claim coexists with a
+        path-metadata call, 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.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        matched_phrase = _docstring_claims_no_network_access(docstring_text)
+        if not matched_phrase:
+            continue
+        accessed_method = _function_performs_path_metadata_access(each_node)
+        if not accessed_method:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring claims "
+            f"'{matched_phrase}' but the body calls .{accessed_method}() on a path — "
+            "a metadata stat is itself a network touch on a share, so the no-network "
+            "claim drifts; reword the docstring to state the path is stat-checked on "
+            "every call, or short-circuit before touching the share "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES]
+
+
 def _module_docstring_claims_no_inline_literal(module_docstring: str) -> str:
     collapsed_docstring = " ".join(module_docstring.lower().split())
     for each_phrase in ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES:
@@ -914,6 +1096,105 @@ def check_module_docstring_names_public_checks(content: str, file_path: str) ->
     return issues[:MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES]
 
 
+def _module_level_upper_snake_constant_names(parsed_tree: ast.Module) -> list[str]:
+    constant_names: list[str] = []
+    for each_statement in parsed_tree.body:
+        target_nodes: list[ast.expr] = []
+        if isinstance(each_statement, ast.Assign):
+            target_nodes = list(each_statement.targets)
+        elif isinstance(each_statement, ast.AnnAssign):
+            target_nodes = [each_statement.target]
+        for each_target in target_nodes:
+            if (
+                isinstance(each_target, ast.Name)
+                and ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(each_target.id)
+            ):
+                constant_names.append(each_target.id)
+    return constant_names
+
+
+def _constant_name_data_schema_marker(constant_name: str) -> str:
+    for each_marker in ALL_DATA_SCHEMA_CONSTANT_NAME_MARKERS:
+        if each_marker in constant_name:
+            return each_marker
+    return ""
+
+
+def _module_data_schema_constant_names(parsed_tree: ast.Module) -> list[str]:
+    return [
+        each_name
+        for each_name in _module_level_upper_snake_constant_names(parsed_tree)
+        if _constant_name_data_schema_marker(each_name)
+    ]
+
+
+def _module_docstring_claims_user_facing_text_scope(module_docstring: str) -> bool:
+    lowered_docstring = module_docstring.lower()
+    return any(
+        each_phrase in lowered_docstring
+        for each_phrase in ALL_USER_FACING_TEXT_SCOPE_DOCSTRING_PHRASES
+    )
+
+
+def _module_docstring_acknowledges_data_schema_scope(module_docstring: str) -> bool:
+    lowered_docstring = module_docstring.lower()
+    return any(
+        each_phrase in lowered_docstring
+        for each_phrase in ALL_DATA_SCHEMA_DOCSTRING_ACKNOWLEDGEMENT_PHRASES
+    )
+
+
+def check_module_docstring_scope_omits_data_schema_constants(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a user-facing-text module docstring that omits data-schema constants.
+
+    A module whose one-line docstring scopes its contents to user-facing text
+    claims a strings-only surface, and a reader trusts that line to map the whole
+    module. The drift this catches is a summary such as "User-facing strings: CLI
+    flag names, help text, and log messages". The body below it also defines
+    serialization field keys, run-metadata schema keys, and runtime config. The
+    summary then under-describes the module, the Category O module-responsibility
+    drift the repo flags. A constant counts as a data-schema or runtime-config
+    value when its name carries a ``_FIELD_``, ``_KEY_``, ``_SCHEMA_``,
+    ``_ENCODING``, or ``_FORMAT_STRING`` marker. The check fires only when the
+    docstring claims a user-facing-text scope and acknowledges no data-schema or
+    runtime-config category. A docstring that already names "field keys", "schema",
+    or "runtime config" passes, so broadening the summary clears the gate.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue naming the unacknowledged data-schema constants, capped at the
+        module limit.
+    """
+    if is_test_file(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    module_docstring = ast.get_docstring(parsed_tree) or ""
+    if not _module_docstring_claims_user_facing_text_scope(module_docstring):
+        return []
+    if _module_docstring_acknowledges_data_schema_scope(module_docstring):
+        return []
+    data_schema_constant_names = _module_data_schema_constant_names(parsed_tree)
+    if not data_schema_constant_names:
+        return []
+    sampled_names = ", ".join(
+        data_schema_constant_names[:MODULE_DOCSTRING_DATA_SCHEMA_CONSTANT_SAMPLE_LIMIT]
+    )
+    return [
+        "Line 1: module docstring scopes the module to user-facing text but the module "
+        f"defines data-schema or runtime-config constants ({sampled_names}) the summary "
+        "never names — broaden the summary to name the data-schema keys and "
+        "runtime-config constants it holds (Category O module-responsibility drift)"
+    ][:MAX_MODULE_DOCSTRING_DATA_SCHEMA_SCOPE_ISSUES]
+
+
 def _module_string_tuple_members(parsed_tree: ast.Module) -> dict[str, frozenset[str]]:
     members_by_constant: dict[str, frozenset[str]] = {}
     for each_statement in parsed_tree.body:
@@ -1024,6 +1305,203 @@ def check_docstring_tuple_enumeration_match(content: str, file_path: str) -> lis
     return issues[:MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES]
 
 
+def _known_glyph_marker_members(
+    sequence_node: ast.Tuple | ast.List,
+) -> frozenset[str] | None:
+    normalized_glyphs: set[str] = set()
+    for each_element in sequence_node.elts:
+        if not (
+            isinstance(each_element, ast.Constant)
+            and isinstance(each_element.value, str)
+        ):
+            return None
+        normalized_glyph = each_element.value.strip()
+        if normalized_glyph not in ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES:
+            return None
+        normalized_glyphs.add(normalized_glyph)
+    return frozenset(normalized_glyphs)
+
+
+def _assignment_targets_and_sequence(
+    statement: ast.stmt,
+) -> tuple[list[str], ast.Tuple | ast.List | None]:
+    if isinstance(statement, ast.Assign) and isinstance(
+        statement.value, (ast.Tuple, ast.List)
+    ):
+        plain_target_names = [
+            each_target.id
+            for each_target in statement.targets
+            if isinstance(each_target, ast.Name)
+        ]
+        return plain_target_names, statement.value
+    if (
+        isinstance(statement, ast.AnnAssign)
+        and isinstance(statement.target, ast.Name)
+        and isinstance(statement.value, (ast.Tuple, ast.List))
+    ):
+        return [statement.target.id], statement.value
+    return [], None
+
+
+def _module_glyph_marker_tuples(parsed_tree: ast.Module) -> dict[str, frozenset[str]]:
+    glyphs_by_constant: dict[str, frozenset[str]] = {}
+    for each_statement in parsed_tree.body:
+        target_names, sequence_node = _assignment_targets_and_sequence(each_statement)
+        if sequence_node is None:
+            continue
+        marker_glyphs = _known_glyph_marker_members(sequence_node)
+        if marker_glyphs is None:
+            continue
+        if len(marker_glyphs) < MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION:
+            continue
+        for each_target_name in target_names:
+            glyphs_by_constant[each_target_name] = marker_glyphs
+    return glyphs_by_constant
+
+
+def _companion_module_file(dotted_module: str, file_path: str) -> Path | None:
+    relative_module_path = Path(*dotted_module.split(".")).with_suffix(
+        PYTHON_MODULE_FILE_SUFFIX
+    )
+    file_directory = Path(file_path).parent
+    candidate_roots = [file_directory, *file_directory.parents]
+    for each_root in candidate_roots[:MAX_COMPANION_MODULE_RESOLUTION_DEPTH]:
+        candidate_path = each_root / relative_module_path
+        if candidate_path.is_file():
+            return candidate_path
+    return None
+
+
+def _companion_glyph_marker_tuples(companion_path: Path) -> dict[str, frozenset[str]]:
+    try:
+        companion_source = companion_path.read_text(encoding="utf-8")
+        companion_tree = ast.parse(companion_source)
+    except (OSError, ValueError, SyntaxError):
+        return {}
+    return _module_glyph_marker_tuples(companion_tree)
+
+
+def _import_brings_upper_snake_name(import_node: ast.ImportFrom) -> bool:
+    return any(
+        ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(each_alias.name)
+        for each_alias in import_node.names
+    )
+
+
+def _imported_glyph_marker_tuples(
+    parsed_tree: ast.Module, file_path: str
+) -> dict[str, frozenset[str]]:
+    glyphs_by_imported_name: dict[str, frozenset[str]] = {}
+    for each_statement in parsed_tree.body:
+        if not isinstance(each_statement, ast.ImportFrom):
+            continue
+        if not each_statement.module:
+            continue
+        if not _import_brings_upper_snake_name(each_statement):
+            continue
+        companion_path = _companion_module_file(each_statement.module, file_path)
+        if companion_path is None:
+            continue
+        companion_tuples = _companion_glyph_marker_tuples(companion_path)
+        for each_alias in each_statement.names:
+            if each_alias.name not in companion_tuples:
+                continue
+            imported_name = each_alias.asname or each_alias.name
+            glyphs_by_imported_name[imported_name] = companion_tuples[each_alias.name]
+    return glyphs_by_imported_name
+
+
+def _docstring_names_mark_glyph(docstring_text: str, normalized_glyph: str) -> bool:
+    lowercased_docstring = docstring_text.lower()
+    for each_name in ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES[normalized_glyph]:
+        boundary_wrapped_name = (
+            WORD_BOUNDARY_REGEX + re.escape(each_name) + WORD_BOUNDARY_REGEX
+        )
+        if re.search(boundary_wrapped_name, lowercased_docstring):
+            return True
+    return False
+
+
+def _marks_named_in_docstring(
+    docstring_text: str, all_marker_glyphs: frozenset[str]
+) -> set[str]:
+    return {
+        each_glyph
+        for each_glyph in all_marker_glyphs
+        if _docstring_names_mark_glyph(docstring_text, each_glyph)
+    }
+
+
+def _text_names_multiple_marks(content_text: str) -> bool:
+    all_known_glyphs = frozenset(ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES)
+    named_glyphs = _marks_named_in_docstring(content_text, all_known_glyphs)
+    return len(named_glyphs) >= MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION
+
+
+def check_docstring_punctuation_mark_enumeration_coverage(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring that names some marks of a glyph tuple but omits one.
+
+    A module reads a tuple of punctuation-mark glyphs as its detection set. The
+    tuple is defined in the module or imported from a companion module beside it.
+    A docstring then enumerates those marks by their English names. When the
+    prose names a closed set of marks but leaves one the tuple holds unnamed, a
+    reader trusts the enumeration and believes an active mark never triggers the
+    check. This is the shape that appears when a glyph joins the tuple while the
+    prose enumeration stays as it was.
+
+    The check binds only when a docstring names two or more marks of one tuple. A
+    docstring that mentions a single mark, names every mark, or describes
+    unrelated punctuation is left alone. This is the deterministic glyph-prose
+    slice of Category O6 docstring-prose-vs-implementation drift, the companion
+    to check_docstring_tuple_enumeration_match for glyph members named in prose
+    rather than identifier members named in inline code. It covers hook
+    infrastructure, where the affected detection tuples live.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per docstring whose mark enumeration omits a glyph the tuple it
+        describes holds, capped at the module limit.
+    """
+    if is_strict_test_file(file_path):
+        return []
+    if not _text_names_multiple_marks(content):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    glyphs_by_constant = {
+        **_module_glyph_marker_tuples(parsed_tree),
+        **_imported_glyph_marker_tuples(parsed_tree, file_path),
+    }
+    if not glyphs_by_constant:
+        return []
+    issues: list[str] = []
+    for each_line, each_docstring in _documentable_docstrings_with_line(parsed_tree):
+        for each_constant_name in sorted(glyphs_by_constant):
+            marker_glyphs = glyphs_by_constant[each_constant_name]
+            named_glyphs = _marks_named_in_docstring(each_docstring, marker_glyphs)
+            if len(named_glyphs) < MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION:
+                continue
+            omitted_glyphs = marker_glyphs - named_glyphs
+            if not omitted_glyphs:
+                continue
+            issues.append(
+                f"Line {each_line}: docstring names {sorted(named_glyphs)} from "
+                f"{each_constant_name} but omits {sorted(omitted_glyphs)} — name every "
+                "mark the tuple holds so the enumeration matches the detection set "
+                "(Category O6 docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES:
+                return issues[:MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES]
+    return issues[:MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES]
+
+
 def _returns_section_text(docstring_text: str) -> str:
     docstring_lines = docstring_text.splitlines()
     returns_section_lines: list[str] = []
@@ -1125,6 +1603,223 @@ def check_docstring_returns_plural_cardinality(content: str, file_path: str) ->
     return issues[:MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES]
 
 
+def _module_level_length_constant_names(parsed_tree: ast.Module) -> set[str]:
+    all_length_constant_names: set[str] = set()
+    for each_statement in parsed_tree.body:
+        target_names: list[str] = []
+        assigned_value: ast.expr | None = None
+        if isinstance(each_statement, ast.Assign):
+            assigned_value = each_statement.value
+            target_names = [
+                each_target.id
+                for each_target in each_statement.targets
+                if isinstance(each_target, ast.Name)
+            ]
+        elif isinstance(each_statement, ast.AnnAssign) and isinstance(
+            each_statement.target, ast.Name
+        ):
+            assigned_value = each_statement.value
+            target_names = [each_statement.target.id]
+        if not isinstance(assigned_value, ast.Constant) or not isinstance(
+            assigned_value.value, int
+        ):
+            continue
+        for each_name in target_names:
+            if not ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(each_name):
+                continue
+            if each_name.endswith(ALL_LENGTH_CONSTANT_NAME_SUFFIXES):
+                all_length_constant_names.add(each_name)
+    return all_length_constant_names
+
+
+def _superlative_phrase_by_length_constant(
+    parsed_tree: ast.Module, all_length_constant_names: set[str]
+) -> tuple[dict[str, str], str]:
+    module_docstring = ast.get_docstring(parsed_tree) or ""
+    phrase_by_constant: dict[str, str] = {}
+    unattributed_phrase = ""
+    for each_sentence in DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN.split(module_docstring):
+        lowered_sentence = each_sentence.lower()
+        sentence_phrase = next(
+            (
+                each_phrase
+                for each_phrase in ALL_LENGTH_SUPERLATIVE_RANGE_PHRASES
+                if each_phrase in lowered_sentence
+            ),
+            "",
+        )
+        if not sentence_phrase:
+            continue
+        named_constants = {
+            each_name
+            for each_name in all_length_constant_names
+            if each_name in each_sentence
+        }
+        if named_constants:
+            for each_name in named_constants:
+                phrase_by_constant.setdefault(each_name, sentence_phrase)
+        elif not unattributed_phrase:
+            unattributed_phrase = sentence_phrase
+    return phrase_by_constant, unattributed_phrase
+
+
+def _compare_targets_a_length_constant(
+    compare_node: ast.Compare, all_length_constant_names: set[str]
+) -> str:
+    operands = [compare_node.left, *compare_node.comparators]
+    has_length_call = any(
+        isinstance(each_operand, ast.Call)
+        and isinstance(each_operand.func, ast.Name)
+        and each_operand.func.id == "len"
+        for each_operand in operands
+    )
+    if not has_length_call:
+        return ""
+    for each_operand in operands:
+        if isinstance(each_operand, ast.Name) and each_operand.id in all_length_constant_names:
+            return each_operand.id
+    return ""
+
+
+def _length_gate_comparison_kinds_in_tree(
+    parsed_tree: ast.Module, all_length_constant_names: set[str]
+) -> dict[str, set[str]]:
+    comparison_kinds_by_constant: dict[str, set[str]] = {}
+    for each_node in ast.walk(parsed_tree):
+        if not isinstance(each_node, ast.Compare):
+            continue
+        compared_constant = _compare_targets_a_length_constant(
+            each_node, all_length_constant_names
+        )
+        if not compared_constant:
+            continue
+        for each_operator in each_node.ops:
+            kind = (
+                "equality"
+                if isinstance(each_operator, (ast.Eq, ast.NotEq))
+                else "ordered"
+            )
+            comparison_kinds_by_constant.setdefault(compared_constant, set()).add(kind)
+    return comparison_kinds_by_constant
+
+
+def _package_scan_python_files(file_path: str) -> list[Path]:
+    file = Path(file_path)
+    scan_root = (
+        file.parent.parent
+        if file.parent.name == LENGTH_CONFIG_SUBDIRECTORY_NAME
+        else file.parent
+    )
+    try:
+        all_python_files = sorted(scan_root.rglob(f"*{PYTHON_MODULE_FILE_SUFFIX}"))
+    except OSError:
+        return []
+    return [
+        each_file
+        for each_file in all_python_files[:LENGTH_GATE_PACKAGE_SCAN_FILE_LIMIT]
+        if each_file.resolve() != file.resolve()
+        and not is_test_file(str(each_file))
+    ]
+
+
+def _exact_length_gate_constants_in_package(
+    file_path: str, all_length_constant_names: set[str]
+) -> set[str]:
+    aggregate_kinds: dict[str, set[str]] = {}
+    for each_file in _package_scan_python_files(file_path):
+        try:
+            sibling_tree = ast.parse(each_file.read_text(encoding="utf-8"))
+        except (OSError, SyntaxError, ValueError):
+            continue
+        for each_constant, each_kinds in _length_gate_comparison_kinds_in_tree(
+            sibling_tree, all_length_constant_names
+        ).items():
+            aggregate_kinds.setdefault(each_constant, set()).update(each_kinds)
+    return {
+        each_constant
+        for each_constant, each_kinds in aggregate_kinds.items()
+        if "equality" in each_kinds and "ordered" not in each_kinds
+    }
+
+
+def check_docstring_length_constant_superlative_vs_exact_gate(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a length-constant docstring that calls an exact gate the "longest" form.
+
+    The drift this catches: a config module defines an integer ``*_LENGTH``
+    constant and its docstring describes that constant with a superlative or
+    range word (``the longest color string the swatch accepts``), while the only
+    code that consumes the constant treats it as an exact-length equality gate
+    (``len(hex_color) != COLOR_AARRGGBB_LENGTH``) — a shorter string is rejected,
+    not accepted at a shorter length. The superlative prose implies a range of
+    accepted lengths the code never allows. The consumer lives in a sibling
+    module, so the check scans the constant module's package tree (its own
+    directory, or its parent package when the module sits in a ``config/``
+    subdirectory) for the comparison; it binds only when a length constant is
+    compared with ``==``/``!=`` against ``len(...)`` somewhere in that tree and
+    never with an ordered operator, so a constant genuinely used as a ceiling
+    (``len(x) <= LIMIT``) is left alone. The superlative phrase is read from the
+    module docstring only, and it is bound to a constant before flagging: a
+    constant is flagged when the docstring sentence carrying the phrase names
+    that constant, or when the phrase sits in a sentence naming no length
+    constant and the docstring never names the constant elsewhere — so a phrase
+    describing one constant (``MAX_NAME_LENGTH is the longest label``) does not
+    flag a different exact-gated constant documented on its own terms. This is
+    the deterministic exact-gate slice of Category O6/O8
+    docstring-vs-implementation drift; the cross-module free-prose variant where
+    the docstring never names the constant stays an audit-lane finding.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions
+            and to locate the package tree the consumer lives in.
+
+    Returns:
+        One issue per length constant the package exact-gates while the module
+        docstring binds a superlative phrase to that constant, 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 []
+    all_length_constant_names = _module_level_length_constant_names(parsed_tree)
+    if not all_length_constant_names:
+        return []
+    phrase_by_constant, unattributed_phrase = _superlative_phrase_by_length_constant(
+        parsed_tree, all_length_constant_names
+    )
+    if not phrase_by_constant and not unattributed_phrase:
+        return []
+    module_docstring = ast.get_docstring(parsed_tree) or ""
+    named_length_constants = {
+        each_name for each_name in all_length_constant_names if each_name in module_docstring
+    }
+    exact_gate_constants = _exact_length_gate_constants_in_package(
+        file_path, all_length_constant_names
+    )
+    issues: list[str] = []
+    for each_constant in sorted(exact_gate_constants):
+        bound_phrase = phrase_by_constant.get(each_constant, "")
+        if not bound_phrase and each_constant not in named_length_constants:
+            bound_phrase = unattributed_phrase
+        if not bound_phrase:
+            continue
+        issues.append(
+            f"Line 1: module docstring says '{bound_phrase}' about "
+            f"{each_constant}, but the package compares len(...) against it only "
+            "with ==/!= (an exact-length gate that rejects every other length) — "
+            "state the exact required length, not a longest/maximum range "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_LENGTH_CONSTANT_SUPERLATIVE_ISSUES:
+            return issues[:MAX_LENGTH_CONSTANT_SUPERLATIVE_ISSUES]
+    return issues[:MAX_LENGTH_CONSTANT_SUPERLATIVE_ISSUES]
+
+
 def _referenced_constant_families(parsed_tree: ast.Module) -> dict[str, set[str]]:
     members_by_family: dict[str, set[str]] = {}
     for each_node in ast.walk(parsed_tree):
@@ -1796,7 +2491,7 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
     A readable docstring breaks its narrative into short sentences a general
     developer follows on the first read. The one mechanical mark of a wall is a
     single sentence that runs past the word limit while chaining clauses with an
-    em-dash or a semicolon. This check inspects the narrative prose of module,
+    em-dash, a double-hyphen, or a semicolon. This check inspects the narrative prose of module,
     class, and public-function docstrings — the text before the first structured
     section header (``Args:``, ``Arguments:``, ``Returns:``, ``Yields:``,
     ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) — and
@@ -1836,3 +2531,253 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
         if len(issues) >= MAX_DOCSTRING_RUNON_SENTENCE_ISSUES:
             break
     return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
+
+
+def _raises_section_text(docstring_text: str) -> str:
+    docstring_lines = docstring_text.splitlines()
+    raises_section_lines: list[str] = []
+    inside_raises_section = False
+    for each_line in docstring_lines:
+        stripped_line = each_line.strip()
+        if stripped_line == "Raises:":
+            inside_raises_section = True
+            continue
+        if not inside_raises_section:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        raises_section_lines.append(stripped_line)
+    return " ".join(raises_section_lines)
+
+
+def _call_argument_by_keyword_or_position(
+    call_node: ast.Call, keyword_name: str, positional_index: int
+) -> ast.expr | None:
+    for each_keyword in call_node.keywords:
+        if each_keyword.arg == keyword_name:
+            return each_keyword.value
+    if positional_index >= len(call_node.args):
+        return None
+    if any(
+        isinstance(each_argument, ast.Starred)
+        for each_argument in call_node.args[: positional_index + 1]
+    ):
+        return None
+    return call_node.args[positional_index]
+
+
+def _call_opens_zipfile_write_mode_writer(call_node: ast.Call) -> bool:
+    callee = call_node.func
+    if isinstance(callee, ast.Attribute):
+        callee_name = callee.attr
+    elif isinstance(callee, ast.Name):
+        callee_name = callee.id
+    else:
+        return False
+    if callee_name != ZIPFILE_WRITER_CLASS_NAME:
+        return False
+    mode_argument = _call_argument_by_keyword_or_position(
+        call_node, ZIPFILE_MODE_KEYWORD, ZIPFILE_MODE_POSITIONAL_INDEX
+    )
+    return (
+        isinstance(mode_argument, ast.Constant)
+        and mode_argument.value in ALL_ZIPFILE_WRITE_MODE_VALUES
+    )
+
+
+def _zipfile_writer_forbids_zip64(call_node: ast.Call) -> bool:
+    allow_zip64_argument = _call_argument_by_keyword_or_position(
+        call_node, ZIPFILE_ALLOW_ZIP64_KEYWORD, ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX
+    )
+    return (
+        isinstance(allow_zip64_argument, ast.Constant)
+        and allow_zip64_argument.value is False
+    )
+
+
+def _function_documents_unraisable_largezipfile(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    docstring_text: str,
+) -> bool:
+    if DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME not in _raises_section_text(docstring_text):
+        return False
+    write_mode_writers = [
+        each_descendant
+        for each_descendant in _walk_skipping_nested_functions(function_node)
+        if isinstance(each_descendant, ast.Call)
+        and _call_opens_zipfile_write_mode_writer(each_descendant)
+    ]
+    if not write_mode_writers:
+        return False
+    return not any(
+        _zipfile_writer_forbids_zip64(each_writer) for each_writer in write_mode_writers
+    )
+
+
+def _attributes_section_entries(docstring_text: str) -> list[tuple[str, str]]:
+    """Return each ``name: description`` entry under an Attributes section.
+
+    A continuation line indented under an entry joins that entry's description,
+    so a field whose description wraps across lines reads as one string. The
+    scan ends at the next Google-style section header or at the docstring end.
+
+    Args:
+        docstring_text: The full class docstring text to scan.
+
+    Returns:
+        One ``(field_name, description)`` pair per Attributes entry, in order.
+    """
+    all_lines = docstring_text.splitlines()
+    inside_section = False
+    entries: list[tuple[str, str]] = []
+    for each_line in all_lines:
+        stripped_line = each_line.strip()
+        if not inside_section:
+            if stripped_line in ("Attributes:", "Attrs:"):
+                inside_section = True
+            continue
+        if stripped_line.endswith(":") and not each_line.startswith((" ", "\t")):
+            break
+        if stripped_line in ALL_DOCSTRING_TERMINATING_SECTION_HEADERS:
+            break
+        entry_match = re.match(
+            r"^\s+(?P<field_name>[A-Za-z_][A-Za-z0-9_]*):\s*(?P<description>.*)$",
+            each_line,
+        )
+        if entry_match:
+            entries.append(
+                (entry_match.group("field_name"), entry_match.group("description"))
+            )
+        elif entries and stripped_line:
+            previous_name, previous_description = entries[-1]
+            entries[-1] = (previous_name, f"{previous_description} {stripped_line}")
+    return entries
+
+def _field_name_is_run_mode_flag(field_name: str) -> bool:
+    lowered_name = field_name.lower()
+    return any(
+        each_token in lowered_name
+        for each_token in ALL_DOCSTRING_RUNMODE_FLAG_FIELD_NAME_TOKENS
+    )
+
+def _description_claims_per_record_write_outcome(description: str) -> bool:
+    lowered_description = description.lower()
+    has_write_outcome_phrase = any(
+        each_phrase in lowered_description
+        for each_phrase in ALL_DOCSTRING_PER_RECORD_WRITE_OUTCOME_PHRASES
+    )
+    has_run_mode_phrase = any(
+        each_phrase in lowered_description
+        for each_phrase in ALL_DOCSTRING_RUN_MODE_PHRASES
+    )
+    return has_write_outcome_phrase and not has_run_mode_phrase
+
+def check_docstring_field_runmode_outcome(content: str, file_path: str) -> list[str]:
+    """Flag a run-mode flag field documented as a per-record write outcome.
+
+    The drift this catches: a dataclass or TypedDict field whose name marks a
+    run-mode flag (``is_dry_run``) is documented in the class Attributes block
+    with per-record write-outcome prose (``True when no STP was written``),
+    while the value is set the same way for every record from the run mode
+    (``is_dry_run=not is_execute``). An already-OK record in an execute run then
+    writes no file yet still stores ``False``, so the per-record prose misleads
+    every reader. The check binds only when the description carries a
+    write-outcome phrase and no run-mode phrase, so a field documented by its
+    run-mode meaning is left alone. This is the deterministic single-file slice
+    of Category O6 run-mode-versus-per-record docstring drift.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per run-mode flag field whose Attributes description claims a
+        per-record write outcome, 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 ast.walk(parsed_tree):
+        if not isinstance(each_node, ast.ClassDef):
+            continue
+        docstring_text = ast.get_docstring(each_node) or ""
+        if not docstring_text:
+            continue
+        for each_field_name, each_description in _attributes_section_entries(docstring_text):
+            if not _field_name_is_run_mode_flag(each_field_name):
+                continue
+            if not _description_claims_per_record_write_outcome(each_description):
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: {each_node.name}.{each_field_name} is a "
+                "run-mode flag but its Attributes description claims a per-record "
+                "write outcome — restate it as the run-mode meaning the assignment "
+                "gives it (Category O6 run-mode-versus-per-record docstring drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_FIELD_RUNMODE_OUTCOME_ISSUES:
+                return issues[:MAX_DOCSTRING_FIELD_RUNMODE_OUTCOME_ISSUES]
+    return issues[:MAX_DOCSTRING_FIELD_RUNMODE_OUTCOME_ISSUES]
+
+
+def check_docstring_raises_unraisable_largezipfile(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a Raises clause naming LargeZipFile over a default-ZIP64 writer.
+
+    The drift this catches: a function whose docstring Raises clause lists
+    ``zipfile.LargeZipFile`` while the function opens its ``zipfile.ZipFile``
+    writer in a write mode (``w``/``a``/``x``) with ``allowZip64`` left at its
+    default of True. The stdlib raises ``LargeZipFile`` only when an entry needs
+    ZIP64 AND ``allowZip64`` is False; with ZIP64 permitted the writer
+    transparently uses it and never raises. The Raises entry then documents an
+    exception the body cannot produce, so a caller guarding ``LargeZipFile`` on
+    the strength of the docstring guards an unreachable path. This is the
+    deterministic slice of Category O6 docstring-prose-vs-implementation drift
+    where a writer opened with default ZIP64 disagrees with a LargeZipFile
+    Raises clause.
+
+    The check binds only when the function opens at least one write-mode
+    ``ZipFile`` and every such writer permits ZIP64, so a function that forbids
+    ZIP64 on any writer (``allowZip64=False``, by keyword or position), a
+    read-only open, and a function that opens no writer — where the exception may
+    propagate from a callee — are all left alone.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose LargeZipFile Raises clause names an
+        unreachable exception, 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.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        if not _function_documents_unraisable_largezipfile(each_node, docstring_text):
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring Raises lists "
+            "zipfile.LargeZipFile, but the function opens its ZipFile writer with ZIP64 "
+            "permitted (allowZip64 defaults to True) — LargeZipFile raises only when "
+            "allowZip64 is False, so drop the entry or pass allowZip64=False "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES]