claude-dev-env 2.28.0 → 2.29.0

package/hooks/blocking/code_rules_enforcer.py

@@ -63,45 +63,14 @@ from code_rules_constants_config import (  # noqa: E402
     check_constants_outside_config_advisory,
     check_file_global_constants_use_count,
 )
-from code_rules_dead_argparse_argument import (  # noqa: E402
-    check_dead_argparse_arguments,
-)
-from code_rules_dead_config_field import (  # noqa: E402
-    check_dead_config_dataclass_fields,
-)
-from code_rules_dead_dataclass_field import (  # noqa: E402
-    check_dead_dataclass_fields,
-)
-from code_rules_dead_module_constant import (  # noqa: E402
-    check_dead_module_constants,
-)
-from code_rules_dead_split_branch import (  # noqa: E402
-    check_dead_split_truthiness_branch,
-)
 from code_rules_docstrings import (  # noqa: E402
     check_class_docstring_names_public_methods,
     check_docstring_args_match_signature,
-    check_docstring_args_single_line_scope_vs_span,
-    check_docstring_cardinal_count_matches_constant_family,
-    check_docstring_delegation_summary_enumeration_drift,
     check_docstring_documents_unreferenced_parameter,
-    check_docstring_fallback_branch_coverage,
-    check_docstring_field_runmode_outcome,
     check_docstring_format,
-    check_docstring_length_constant_superlative_vs_exact_gate,
-    check_docstring_names_absent_type_checking_gate,
     check_docstring_names_undefined_constant,
-    check_docstring_no_consumer_claim,
-    check_docstring_no_inline_literal_claim,
-    check_docstring_no_network_claim_with_metadata_access,
     check_docstring_prose_wall_without_illustration,
-    check_docstring_punctuation_mark_enumeration_coverage,
-    check_docstring_raises_unraisable_largezipfile,
-    check_docstring_returns_plural_cardinality,
     check_docstring_runon_sentence,
-    check_docstring_step_enumeration_dispatch_coverage,
-    check_docstring_tuple_enumeration_match,
-    check_docstring_unguarded_malformed_payload_claim,
     check_module_docstring_names_public_checks,
     check_module_docstring_scope_omits_data_schema_constants,
 )
@@ -113,7 +82,6 @@ from code_rules_duplicate_body import (  # noqa: E402
 from code_rules_imports_logging import (  # noqa: E402
     advise_file_line_count,
     check_e2e_test_naming,
-    check_import_block_sorted,
     check_imports_at_top,
     check_js_bare_flag_return_directive,
     check_js_resume_task_enumeration_coverage,
@@ -134,9 +102,6 @@ from code_rules_magic_values import (  # noqa: E402
     check_fstring_structural_literals,
     check_magic_values,
 )
-from code_rules_mock_completeness import (  # noqa: E402
-    check_incomplete_mocks,
-)
 from code_rules_naming_collection import (  # noqa: E402
     check_collection_prefix,
     check_loop_variable_naming,
@@ -203,9 +168,6 @@ from code_rules_typeddict_stub import (  # noqa: E402
     check_typed_dict_encode_decode,
     check_zero_payload_function_alias,
 )
-from code_rules_unused_imports import (  # noqa: E402
-    check_unused_module_level_imports,
-)
 from codex_apply_patch import (  # noqa: E402
     CodexPatchError,
     CodexPatchFile,
@@ -355,14 +317,6 @@ def validate_content(
         if not is_test_file(file_path):
             all_issues.extend(check_comment_changes(old_content, content, file_path))
         all_issues.extend(check_imports_at_top(content))
-        all_issues.extend(
-            check_import_block_sorted(
-                effective_content,
-                file_path,
-                all_changed_lines,
-                defer_scope_to_caller,
-            )
-        )
         all_issues.extend(check_logging_fstrings(content))
         all_issues.extend(check_logging_printf_tokens(content, file_path))
         all_issues.extend(check_logging_adjacent_string_literals(content, file_path))
@@ -440,21 +394,6 @@ def validate_content(
         all_issues.extend(
             check_docstring_documents_unreferenced_parameter(effective_content, file_path)
         )
-        all_issues.extend(check_docstring_fallback_branch_coverage(effective_content, file_path))
-        all_issues.extend(check_docstring_no_consumer_claim(effective_content, file_path))
-        all_issues.extend(
-            check_docstring_no_network_claim_with_metadata_access(
-                effective_content, file_path
-            )
-        )
-        all_issues.extend(
-            check_docstring_unguarded_malformed_payload_claim(
-                effective_content, file_path
-            )
-        )
-        all_issues.extend(
-            check_docstring_no_inline_literal_claim(effective_content, file_path)
-        )
         all_issues.extend(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
@@ -482,52 +421,9 @@ def validate_content(
                 effective_content, file_path
             )
         )
-        all_issues.extend(
-            check_docstring_tuple_enumeration_match(effective_content, file_path)
-        )
-        all_issues.extend(
-            check_docstring_punctuation_mark_enumeration_coverage(
-                effective_content, file_path
-            )
-        )
-        all_issues.extend(
-            check_docstring_step_enumeration_dispatch_coverage(
-                effective_content, file_path
-            )
-        )
-        all_issues.extend(
-            check_docstring_returns_plural_cardinality(effective_content, file_path)
-        )
-        all_issues.extend(
-            check_docstring_length_constant_superlative_vs_exact_gate(
-                effective_content, file_path
-            )
-        )
-        all_issues.extend(
-            check_docstring_field_runmode_outcome(effective_content, file_path)
-        )
-        all_issues.extend(
-            check_docstring_raises_unraisable_largezipfile(effective_content, file_path)
-        )
-        all_issues.extend(
-            check_docstring_cardinal_count_matches_constant_family(
-                effective_content, file_path
-            )
-        )
         all_issues.extend(
             check_docstring_names_undefined_constant(effective_content, file_path)
         )
-        all_issues.extend(
-            check_docstring_names_absent_type_checking_gate(effective_content, file_path)
-        )
-        all_issues.extend(
-            check_docstring_args_single_line_scope_vs_span(effective_content, file_path)
-        )
-        all_issues.extend(
-            check_docstring_delegation_summary_enumeration_drift(
-                effective_content, file_path
-            )
-        )
         all_issues.extend(
             check_boolean_naming(
                 effective_content,
@@ -563,22 +459,6 @@ def validate_content(
         all_issues.extend(check_stuttering_collection_prefix(content, file_path))
         all_issues.extend(check_hardcoded_user_paths(content, file_path))
         all_issues.extend(check_sys_path_insert_deduplication_guard(content, file_path))
-        all_issues.extend(
-            check_unused_module_level_imports(content, file_path, full_file_content)
-        )
-        all_issues.extend(
-            check_dead_dataclass_fields(content, file_path, full_file_content)
-        )
-        all_issues.extend(
-            check_dead_argparse_arguments(content, file_path, full_file_content)
-        )
-        all_issues.extend(
-            check_dead_config_dataclass_fields(content, file_path, full_file_content)
-        )
-        all_issues.extend(
-            check_dead_module_constants(content, file_path, full_file_content)
-        )
-        all_issues.extend(check_dead_split_truthiness_branch(content, file_path))
         all_issues.extend(check_library_print(content, file_path))
         all_issues.extend(check_parameter_annotations(content, file_path))
         all_issues.extend(check_known_pytest_fixture_annotations(content, file_path))
@@ -640,7 +520,6 @@ def validate_content(
         )
         all_issues.extend(check_whitespace_indentation_magic(content, file_path))
         all_issues.extend(check_orphan_css_classes(effective_content, file_path))
-        check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)
         advise_cross_skill_duplicate_helper(effective_content, file_path)
 

package/hooks/blocking/code_rules_imports_logging.py

@@ -1,9 +1,7 @@
-"""Imports-at-top, import-block-sorted, logging f-string, logging printf-token, win32gui None, naive datetime construction, E2E spec naming, JS resume-task enumeration coverage, JS returns-object schema-less branch, JS sibling return-object key drift, JS bare-flag return-directive, file-length advisory, and library-print checks."""
+"""Import and logging convention checks: check_imports_at_top, check_logging_fstrings, check_logging_printf_tokens, check_logging_adjacent_string_literals, check_windows_api_none, check_naive_datetime_construction, check_e2e_test_naming, check_js_resume_task_enumeration_coverage, check_js_returns_object_schemaless_branch, check_js_sibling_return_object_key_drift, check_js_bare_flag_return_directive, and check_library_print."""
 
 import ast
-import json
 import re
-import subprocess
 import sys
 from pathlib import Path
 
@@ -28,14 +26,9 @@ from code_rules_shared import (  # noqa: E402
 from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_ALWAYS_NAIVE_DATETIME_CONSTRUCTORS,
     ALL_FORMAT_LOGGER_FUNCTION_NAMES,
-    ALL_IMPORT_BLOCK_SORT_RUFF_COMMAND_PREFIX,
-    ALL_RUFF_STANDALONE_CONFIG_FILENAMES,
     DATETIME_CLASS_ATTRIBUTE_NAME,
     FROMTIMESTAMP_POSITIONAL_TIMEZONE_ARGUMENT_COUNT,
-    IMPORT_BLOCK_SORT_RUFF_TIMEOUT_SECONDS,
-    IMPORT_BLOCK_SORT_RULE_CODE,
     MAX_E2E_TEST_NAMING_ISSUES,
-    MAX_IMPORT_BLOCK_SORT_ISSUES,
     MAX_JS_BARE_FLAG_RETURN_DIRECTIVE_ISSUES,
     MAX_JS_RESUME_TASK_ENUMERATION_ISSUES,
     MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES,
@@ -51,9 +44,6 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     NAIVE_DATETIME_TIMEZONE_KEYWORD,
     NAIVE_DATETIME_UTCFROMTIMESTAMP_CONSTRUCTOR,
     NAIVE_DATETIME_UTCNOW_CONSTRUCTOR,
-    RUFF_PYPROJECT_CONFIG_FILENAME,
-    RUFF_PYPROJECT_TOOL_TABLE_MARKER,
-    RUFF_STDIN_ENCODING,
     SIBLING_RETURN_OBJECT_EXACT_MISSING_KEY_COUNT,
     SIBLING_RETURN_OBJECT_SINGLE_AGREED_MISSING_KEY_COUNT,
 )
@@ -234,231 +224,6 @@ def check_imports_at_top(content: str) -> list[str]:
     return issues
 
 
-def check_import_block_sorted(
-    content: str,
-    file_path: str,
-    all_changed_lines: set[int] | None = None,
-    defer_scope_to_caller: bool = False,
-) -> list[str]:
-    """Flag a Python import block left un-sorted per isort rules (ruff I001).
-
-    ruff/isort treats a contiguous run of ``import`` and ``from`` statements as
-    one sortable unit. An edit that re-touches such a block pulls the whole block
-    into the gate's scope, so a pre-existing mis-ordering in an untouched line of
-    that block becomes a quality-gate failure (``check.ps1`` runs ruff over
-    ``hooks/blocking``). This catches that drift at Write/Edit time by delegating
-    to ruff itself, the same sorter the quality gate uses, so the two surfaces
-    never disagree.
-
-    The check resolves *file_path* to an absolute path and runs ruff against
-    *content* on stdin under that path, so ruff walks parents to find the repo's
-    ``[tool.ruff]`` config. Without a discoverable config ruff falls back to
-    default isort first-party grouping, which orders sibling imports differently
-    and produces false positives, so the check fails open when no ruff config is
-    found above the file. Non-Python files and test files are exempt. When ruff
-    is not installed, times out, or returns output the parser cannot read, the
-    check also fails open and reports nothing — a missing or slow tool never
-    blocks a write.
-
-    An I001 finding covers the whole sortable block, so each finding carries a
-    span from the block's anchor line (``location.row``) through its last line
-    (``end_location.row``) scoped through the shared
-    ``_scope_violations_to_changed_lines`` helper. On a terminal diff-scoped Edit
-    a finding is returned when any line in that block span is among
-    ``all_changed_lines``, so an edit touching any line of an unsorted block
-    blocks while an edit far from the block does not. On a new-file or full-file
-    write (``all_changed_lines`` None) every finding is in scope;
-    ``defer_scope_to_caller`` returns every finding so the commit/push gate
-    scopes by added line through its own ``Line N:`` partitioning.
-
-    Args:
-        content: The full file content the Write or Edit would leave on disk.
-        file_path: The destination path, used both to gate by extension and to
-            give ruff the filename it needs for config discovery.
-        all_changed_lines: Post-edit line numbers the current edit touched, or
-            None to treat the whole file as in scope. When provided, a finding
-            blocks only when any line of its block span is among the changed
-            lines.
-        defer_scope_to_caller: When True, return every finding so the commit/push
-            gate's ``Line N:`` partitioning scopes by added line.
-
-    Returns:
-        One issue string per detected I001 finding, capped at
-        ``MAX_IMPORT_BLOCK_SORT_ISSUES``; an empty list when the block sorts
-        cleanly, every finding falls outside the changed lines, or the check
-        fails open.
-    """
-    if get_file_extension(file_path) not in ALL_PYTHON_EXTENSIONS:
-        return []
-    if is_test_file(file_path):
-        return []
-
-    absolute_file_path = Path(file_path).resolve()
-    if not _ruff_config_discoverable(absolute_file_path):
-        return []
-
-    ruff_findings = _run_ruff_import_sort_check(content, str(absolute_file_path))
-    if ruff_findings is None:
-        return []
-
-    span_end_line_offset = 1
-    all_violations_in_finding_order: list[tuple[range, str]] = []
-    for each_finding in ruff_findings:
-        if each_finding.get("code") != IMPORT_BLOCK_SORT_RULE_CODE:
-            continue
-        line_number = _finding_line_number(each_finding.get("location"))
-        block_end_line_number = _finding_block_end_line_number(
-            each_finding.get("end_location"), line_number
-        )
-        span_range = range(line_number, block_end_line_number + span_end_line_offset)
-        message = (
-            f"Line {line_number}: Import block is un-sorted (ruff I001) - "
-            f"run 'ruff check --fix' to sort the block before writing"
-        )
-        all_violations_in_finding_order.append((span_range, message))
-        if len(all_violations_in_finding_order) >= MAX_IMPORT_BLOCK_SORT_ISSUES:
-            break
-
-    return _scope_violations_to_changed_lines(
-        all_violations_in_finding_order,
-        all_changed_lines,
-        defer_scope_to_caller,
-    )
-
-
-def _run_ruff_import_sort_check(content: str, file_path: str) -> list[dict[str, object]] | None:
-    """Run ruff's I001 check over *content* and return its parsed JSON findings.
-
-    Args:
-        content: The file content fed to ruff on stdin.
-        file_path: The filename ruff is told the stdin content belongs to, so it
-            discovers the surrounding ``[tool.ruff]`` config.
-
-    Returns:
-        The list of ruff finding dictionaries, or ``None`` when ruff is absent,
-        times out, or emits output that is not the expected JSON list.
-    """
-    ruff_command = [
-        *ALL_IMPORT_BLOCK_SORT_RUFF_COMMAND_PREFIX,
-        "--stdin-filename",
-        file_path,
-        "-",
-    ]
-    try:
-        completed_process = subprocess.run(
-            ruff_command,
-            input=content.encode(RUFF_STDIN_ENCODING),
-            capture_output=True,
-            timeout=IMPORT_BLOCK_SORT_RUFF_TIMEOUT_SECONDS,
-            check=False,
-        )
-    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
-        return None
-
-    try:
-        ruff_stdout = completed_process.stdout.decode(RUFF_STDIN_ENCODING)
-    except UnicodeDecodeError:
-        return None
-
-    try:
-        parsed_findings = json.loads(ruff_stdout)
-    except json.JSONDecodeError:
-        return None
-
-    if not isinstance(parsed_findings, list):
-        return None
-    return [each_finding for each_finding in parsed_findings if isinstance(each_finding, dict)]
-
-
-def _ruff_config_discoverable(absolute_file_path: Path) -> bool:
-    """Return whether a ruff config sits above *absolute_file_path*.
-
-    Walks the file's parent directories looking for a standalone ``ruff.toml`` /
-    ``.ruff.toml`` or a ``pyproject.toml`` that declares a ``[tool.ruff`` table.
-    ruff uses this same nearest-ancestor walk to resolve its settings; mirroring
-    it lets the check confirm ruff will see the project's isort configuration
-    rather than its built-in defaults before trusting an I001 finding.
-
-    Args:
-        absolute_file_path: The resolved path of the file under validation.
-
-    Returns:
-        True when a ruff config is found in the file's directory or any ancestor;
-        False when the walk reaches the filesystem root without one.
-    """
-    for each_directory in absolute_file_path.parents:
-        for each_standalone_name in ALL_RUFF_STANDALONE_CONFIG_FILENAMES:
-            if (each_directory / each_standalone_name).is_file():
-                return True
-        pyproject_path = each_directory / RUFF_PYPROJECT_CONFIG_FILENAME
-        if _pyproject_declares_ruff_table(pyproject_path):
-            return True
-    return False
-
-
-def _pyproject_declares_ruff_table(pyproject_path: Path) -> bool:
-    """Return whether *pyproject_path* exists and declares a ``[tool.ruff`` table.
-
-    Args:
-        pyproject_path: The candidate ``pyproject.toml`` path to inspect.
-
-    Returns:
-        True when the file exists and its text contains the ``[tool.ruff`` table
-        marker; False when the file is absent or unreadable.
-    """
-    if not pyproject_path.is_file():
-        return False
-    try:
-        pyproject_text = pyproject_path.read_text(encoding=RUFF_STDIN_ENCODING)
-    except OSError:
-        return False
-    return RUFF_PYPROJECT_TOOL_TABLE_MARKER in pyproject_text
-
-
-def _finding_line_number(location: object) -> int:
-    """Return the source line a ruff finding's location anchors to.
-
-    Args:
-        location: The ``location`` value from one ruff JSON finding, expected to
-            be a mapping carrying an integer ``row``; any other shape yields a
-            zero line number.
-
-    Returns:
-        The ``row`` value as an integer, or a zero line number when the location
-        is absent or carries no readable row.
-    """
-    if not isinstance(location, dict):
-        return 0
-    row = location.get("row")
-    if not isinstance(row, int):
-        return 0
-    return row
-
-
-def _finding_block_end_line_number(end_location: object, anchor_line_number: int) -> int:
-    """Return the last source line a ruff finding's block spans.
-
-    ruff anchors an I001 finding at its block's first line and records the
-    block's last line in ``end_location.row``, so the two together bound the
-    whole sortable run. The end row falls back to the anchor line when the
-    ``end_location`` is absent or carries no readable row, or when it would land
-    above the anchor — keeping the span to at least the anchor line itself.
-
-    Args:
-        end_location: The ``end_location`` value from one ruff JSON finding,
-            expected to be a mapping carrying an integer ``row``.
-        anchor_line_number: The finding's block-anchor line, used as the floor
-            for the returned end line.
-
-    Returns:
-        The block's last line as an integer, never below *anchor_line_number*.
-    """
-    if not isinstance(end_location, dict):
-        return anchor_line_number
-    row = end_location.get("row")
-    if not isinstance(row, int) or row < anchor_line_number:
-        return anchor_line_number
-    return row
 
 
 def _update_triple_quote_state_for_line(

package/hooks/blocking/code_rules_shared.py

@@ -19,6 +19,8 @@ from hooks_constants.code_rules_enforcer_constants import (
     ALL_WORKFLOW_REGISTRY_PATTERNS,
     CLAUDE_JOB_DIR_ENVIRONMENT_VARIABLE_NAME,
     CLAUDE_JOB_DIR_SCRATCH_SUBDIRECTORY,
+    CONFIG_DIRECTORY_SEGMENT,
+    CONSTANTS_MODULE_SUFFIX,
     EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME,
     LEADING_DRIVE_LETTER_PATTERN,
     STRICT_TEST_FILE_BASENAME_PATTERN,
@@ -447,6 +449,27 @@ def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
     return is_under_session_scratchpad(file_path, hook_payload or {})
 
 
+def _is_dedicated_constants_module(file_path: str) -> bool:
+    """Return whether a path is a dedicated constants module.
+
+    A dedicated constants module is one whose filename ends in
+    ``_constants.py`` or whose path includes a ``config`` directory segment.
+    These modules export named values to importers, so a same-file reference
+    count cannot prove one of their constants dead.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        True for a constants-suffixed module or a module under ``config/``.
+    """
+    normalized_path = file_path.replace("\\", "/").lower()
+    if normalized_path.endswith(CONSTANTS_MODULE_SUFFIX):
+        return True
+    path_segments = normalized_path.split("/")
+    return CONFIG_DIRECTORY_SEGMENT in path_segments[:-1]
+
+
 def is_migration_file(file_path: str) -> bool:
     """Check if file is a Django migration (must be self-contained)."""
     path_lower = file_path.lower().replace("\\", "/")

package/hooks/blocking/code_rules_test_layout.py

@@ -10,15 +10,14 @@ test functions, which exports nothing, so a single-file scan proves a constant
 no other line reads is dead. A ``conftest.py``, a shared helper module reached
 only through the ``tests/`` directory gate, and a dedicated constants or
 ``config/`` module all export their constants to importer modules, so the
-cross-module ``check_dead_module_constants`` governs their constants and the
-dead-constant check leaves them alone.
+audit lane governs their constants cross-module (see
+rules/file-global-constants.md) and this write-time check leaves them alone.
 """
 
 import ast
 from typing import TypeGuard
 
-from code_rules_dead_module_constant import _is_dedicated_constants_module
-from code_rules_shared import is_strict_test_file
+from code_rules_shared import _is_dedicated_constants_module, is_strict_test_file
 from hooks_constants.test_layout_constants import (
     CLASS_METHOD_FIRST_PARAMETER_NAME,
     DEAD_TEST_CONSTANT_GUIDANCE,
@@ -55,7 +54,7 @@ def _is_dead_constant_scan_target(file_path: str) -> bool:
     constant no other line reads is dead. A ``conftest.py``, a shared helper
     module reached only through the ``tests/`` directory gate, and a dedicated
     constants or ``config/`` module all export to importer modules, where the
-    cross-module ``check_dead_module_constants`` governs their constants.
+    cross-module audit lane governs their constants (see rules/file-global-constants.md).
 
     Args:
         file_path: The destination path of the write.
@@ -78,8 +77,8 @@ def _is_private_constant_name(name: str) -> bool:
         EXPECTED_TOTAL           ->  public constant, left alone
 
     Only a leading-underscore name qualifies. A public module constant exports
-    to importer modules, so the cross-module ``check_dead_module_constants``
-    governs it and this single-file scan leaves it alone.
+    to importer modules, so the cross-module audit lane governs it (see
+    rules/file-global-constants.md) and this single-file scan leaves it alone.
     """
     if not name.startswith(PRIVATE_NAME_PREFIX):
         return False
@@ -164,7 +163,8 @@ def check_dead_test_module_constant(content: str, file_path: str) -> list[str]:
     dead scaffolding an edit stranded. A public constant, a ``conftest.py``, a
     shared helper module under ``tests/``, and a dedicated constants or
     ``config/`` module all export to importer modules, so the cross-module
-    ``check_dead_module_constants`` judges those and this check skips them.
+    audit lane judges those (see rules/file-global-constants.md) and this
+    check skips them.
 
     Args:
         content: The post-edit file content under validation.

package/hooks/blocking/config/AGENTS.md

@@ -1,10 +1 @@
-# hooks/blocking/config
 
-A Python package that holds shared constants for blocking hooks. Opinionated prose-style gates import from here.
-
-## Key files
-
-| File | Contents |
-|---|---|
-| `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
-| `prose_style_enforcement_constants.py` | `CLAUDE_PROSE_STYLE_ENFORCEMENT` opt-in (default off) for opinionated prose gates |

package/hooks/blocking/config/prose_style_enforcement_constants.py

@@ -6,8 +6,10 @@
     (unset)                           ->  PROSE_STYLE_ENFORCEMENT_ENABLED False
 
 Structural AskUserQuestion lean-block validation stays always on. The flag
-arms only opinionated prose gates (heavy-word swaps, hedging, historical
-state phrasing, intent-only endings, hook prose-detector consistency).
+arms only two opinionated prose gates: `plain_language_blocker.py` (heavy-word
+swaps) and `hook_prose_detector_consistency.py`. Historical-state phrasing
+(`state_description_blocker.py`) runs unconditionally and does not read this
+flag.
 """
 
 from __future__ import annotations

package/hooks/blocking/config/test_prose_style_enforcement_constants.py

@@ -1,4 +1,8 @@
-"""Tests for the prose-style enforcement opt-in flag (default off)."""
+"""Tests for the prose-style enforcement opt-in flag.
+
+Gates ``plain_language_blocker.py`` and ``hook_prose_detector_consistency.py``;
+default off.
+"""
 
 from __future__ import annotations
 

package/hooks/blocking/inventory_intent_records/AGENTS.md

@@ -1,26 +1 @@
-# inventory_intent_records
 
-The shared pending-intent store that lets `package_inventory_stale_blocker.py`
-and `claude_md_orphan_file_blocker.py` add a new file and its inventory row in
-one change, in either order. When one blocker denies, it records a note; the
-sibling blocker reads that note to allow the matching second write.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `records.py` | Read, record, peek, and consume the per-session file and row intents; a missing or corrupt store reads as no notes |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The records-file name shape, the freshness window, the list keys, and the note field names (`intent_records_constants.py`) |
-| `tests/` | pytest suite for the records store |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/inventory_intent_records/tests/
-```

package/hooks/blocking/package_inventory_stale_blocker_parts/AGENTS.md

@@ -1,26 +1 @@
-# package_inventory_stale_blocker_parts
 
-The concern modules `package_inventory_stale_blocker.py` wires together to block a
-new production file its package inventory omits. The entry hook imports them and
-re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `inventory_detection.py` | Surveys a directory's `README.md`/`CLAUDE.md`/`SKILL.md`, collects the filenames they name, and reports whether a maintained inventory omits the file being written |
-| `decision.py` | Builds the deny payload naming the omitted file and closing with the retry hint, and emits the decision JSON |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The retry hint the deny reason closes with and the inventory-name join separator (`inventory_blocker_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/package_inventory_stale_blocker_parts/tests/
-```

package/hooks/blocking/pii_prevention_blocker_parts/AGENTS.md

@@ -1,24 +1 @@
-# pii_prevention_blocker_parts
 
-The concern modules `pii_prevention_blocker.py` wires together. The entry hook
-imports them and re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `repository_exemption.py` | Resolves a commit's origin owner/repo slug, decides whether the repository skips the staged PII scan, and resolves the exact values that repository allows past the scan |
-| `repository_resolution.py` | Reads the repository a commit command targets — composing multiple `-C` values and a leading `cd`/`pushd` — and builds the deny reason naming the path when the repository root does not resolve |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The repository-resolution deny-message template and the session-cwd label (`repository_resolution_constants.py`) |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/tests/
-```