claude-dev-env 1.78.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,46 +32,53 @@ 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,
-    PYTHON_MODULE_FILE_SUFFIX,
-    WORD_BOUNDARY_REGEX,
     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_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,
-    ALL_ZIPFILE_WRITE_MODE_VALUES,
-    DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME,
+    MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES,
     MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES,
-    MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
     MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
+    MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
+    MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
-    ZIPFILE_ALLOW_ZIP64_KEYWORD,
-    ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX,
-    ZIPFILE_MODE_KEYWORD,
-    ZIPFILE_MODE_POSITIONAL_INDEX,
-    ZIPFILE_WRITER_CLASS_NAME,
     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,
@@ -78,7 +87,15 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     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,
@@ -369,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
@@ -791,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:
@@ -928,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:
@@ -1336,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):
@@ -2007,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
@@ -2130,6 +2614,115 @@ def _function_documents_unraisable_largezipfile(
     )
 
 
+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]: