claude-dev-env 1.58.0 → 1.60.0

package/hooks/blocking/verifier_verdict_minter.py

@@ -0,0 +1,299 @@
+"""SubagentStop hook: mint a commit-gate verdict when code-verifier finishes.
+
+Only this hook writes verdict files — the main session is denied writes to
+the verdict directory, so a session cannot fabricate a passing verdict. The
+SubagentStop payload names the stopping subagent by ``agent_id``. The hook
+recovers the spawning agent type from the parent transcript
+(``transcript_path``), where the agent's completion record carries its
+identity as sibling ``agentId`` and ``agentType`` keys. When that type is
+``code-verifier``, the hook pulls the verdict block out of the agent's own
+transcript — the payload key ``agent_transcript_path``; the parent
+``transcript_path`` supplies only the spawning type and never the verdict, so
+text printed by the main session can never mint — recomputes the live
+change-surface hash for the session
+repository, and writes the verdict bound to that hash. The companion
+``verified_commit_gate.py`` (PreToolUse) then allows ``git commit`` /
+``git push`` only while the work tree still matches the verified state.
+
+The verifier's final message must end with a fenced block::
+
+    ```verdict
+    {"all_pass": true, "findings": []}
+    ```
+
+A missing or unparseable block mints nothing, which leaves the gate closed.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from config.verified_commit_constants import (
+    MINTING_AGENT_TYPE,
+    SPAWN_LOOKUP_ATTEMPT_COUNT,
+    SPAWN_LOOKUP_RETRY_DELAY_SECONDS,
+)
+from verification_verdict_store import (
+    branch_surface_manifest,
+    manifest_sha256,
+    resolve_merge_base,
+    resolve_repo_root,
+    write_verdict,
+)
+
+
+def assistant_text_blocks(transcript_path: str) -> list[str]:
+    """Collect every assistant text block from a transcript JSONL file.
+
+    Args:
+        transcript_path: Path to the subagent's transcript.
+
+    Returns:
+        The text of each assistant content block, in transcript order;
+        empty when the file is missing or holds no assistant text.
+    """
+    collected_blocks: list[str] = []
+    try:
+        transcript_lines = (
+            Path(transcript_path).read_text(encoding="utf-8", errors="replace").splitlines()
+        )
+    except OSError:
+        return collected_blocks
+    for each_line in transcript_lines:
+        try:
+            transcript_entry = json.loads(each_line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(transcript_entry, dict):
+            continue
+        if transcript_entry.get("type") != "assistant":
+            continue
+        message_body = transcript_entry.get("message")
+        if not isinstance(message_body, dict):
+            continue
+        content_blocks = message_body.get("content")
+        if not isinstance(content_blocks, list):
+            continue
+        for each_block in content_blocks:
+            if isinstance(each_block, dict) and each_block.get("type") == "text":
+                block_text = each_block.get("text")
+                if isinstance(block_text, str):
+                    collected_blocks.append(block_text)
+    return collected_blocks
+
+
+def last_verdict_in_blocks(all_text_blocks: list[str]) -> dict | None:
+    """Extract the final verdict fence from assistant text blocks.
+
+    Args:
+        all_text_blocks: Assistant text blocks in transcript order.
+
+    Returns:
+        The parsed verdict mapping carrying a boolean ``all_pass`` and a
+        list ``findings``, or None when no block holds a wellformed fence.
+    """
+    verdict_fence_pattern = re.compile(r"```verdict\s*\n(.*?)```", re.DOTALL)
+    fence_bodies: list[str] = []
+    for each_block in all_text_blocks:
+        fence_bodies.extend(verdict_fence_pattern.findall(each_block))
+    for each_fence_body in reversed(fence_bodies):
+        try:
+            verdict_record = json.loads(each_fence_body)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(verdict_record, dict):
+            continue
+        if not isinstance(verdict_record.get("all_pass"), bool):
+            continue
+        if not isinstance(verdict_record.get("findings"), list):
+            continue
+        return verdict_record
+    return None
+
+
+def _transcript_entries(transcript_path: str) -> list[dict]:
+    """Parse every JSON object line of a transcript file.
+
+    Args:
+        transcript_path: Path to the parent session transcript.
+
+    Returns:
+        Each parseable object entry in transcript order; empty when the
+        file is missing or holds no object lines.
+    """
+    parsed_entries: list[dict] = []
+    try:
+        transcript_lines = (
+            Path(transcript_path).read_text(encoding="utf-8", errors="replace").splitlines()
+        )
+    except OSError:
+        return parsed_entries
+    for each_line in transcript_lines:
+        try:
+            transcript_entry = json.loads(each_line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(transcript_entry, dict):
+            parsed_entries.append(transcript_entry)
+    return parsed_entries
+
+
+def _agent_type_in_node(transcript_node: object, agent_id: str) -> str | None:
+    """Search one parsed transcript value for a spawn record naming an agent.
+
+    Walks a transcript value and its nested mappings and sequences for a
+    mapping whose ``agentId`` equals the stopping agent and whose
+    ``agentType`` is a string. Only a structured ``agentType`` key counts, so
+    a main-session text block that merely quotes the words cannot match.
+
+    Args:
+        transcript_node: A JSON value drawn from a parsed transcript entry.
+        agent_id: The stopping subagent's id from the payload.
+
+    Returns:
+        The ``agentType`` of the matching mapping, or None when no nested
+        value names this agent.
+    """
+    if isinstance(transcript_node, dict):
+        recorded_type = transcript_node.get("agentType")
+        if transcript_node.get("agentId") == agent_id and isinstance(recorded_type, str):
+            return recorded_type
+        for each_value in transcript_node.values():
+            nested_type = _agent_type_in_node(each_value, agent_id)
+            if nested_type is not None:
+                return nested_type
+        return None
+    if isinstance(transcript_node, list):
+        for each_item in transcript_node:
+            nested_type = _agent_type_in_node(each_item, agent_id)
+            if nested_type is not None:
+                return nested_type
+    return None
+
+
+def _agent_type_from_entries(all_entries: list[dict], agent_id: str) -> str | None:
+    """Find the spawn record naming an agent across parent-transcript entries.
+
+    Args:
+        all_entries: Parsed parent-transcript entries.
+        agent_id: The stopping subagent's id from the payload.
+
+    Returns:
+        The ``agentType`` recorded for the agent, or None when no entry's
+        spawn record names it.
+    """
+    for each_entry in all_entries:
+        recorded_type = _agent_type_in_node(each_entry, agent_id)
+        if recorded_type is not None:
+            return recorded_type
+    return None
+
+
+def _resolve_agent_type_with_retry(transcript_path: str, agent_id: str) -> str | None:
+    """Read the parent transcript and resolve the agent's type, with retry.
+
+    The agent's completion record is not reliably flushed to the parent
+    transcript at the instant SubagentStop fires, so a single read can miss it
+    and silently mint nothing. Each attempt re-reads the transcript; a bounded
+    sleep separates attempts so a late-arriving record resolves on a later read.
+
+    Args:
+        transcript_path: Path to the parent session transcript.
+        agent_id: The stopping subagent's id from the payload.
+
+    Returns:
+        The recorded ``agentType``, or None when no attempt finds the spawn
+        record naming this agent.
+    """
+    for each_attempt_index in range(SPAWN_LOOKUP_ATTEMPT_COUNT):
+        all_entries = _transcript_entries(transcript_path)
+        recorded_type = _agent_type_from_entries(all_entries, agent_id)
+        if recorded_type is not None:
+            return recorded_type
+        if each_attempt_index < SPAWN_LOOKUP_ATTEMPT_COUNT - 1:
+            time.sleep(SPAWN_LOOKUP_RETRY_DELAY_SECONDS)
+    return None
+
+
+def resolved_subagent_type(subagent_stop_payload: dict) -> str | None:
+    """Recover the spawning agent type for a SubagentStop payload.
+
+    The payload names the stopping subagent by ``agent_id``. Its spawn type
+    lives on the agent's completion record in the parent transcript, attached
+    as sibling ``agentId`` and ``agentType`` keys, so the type is read from
+    that record. The read retries because the record may not be flushed at the
+    instant the hook fires.
+
+    Args:
+        subagent_stop_payload: The SubagentStop hook payload.
+
+    Returns:
+        The agent type this subagent was spawned with, or None when the agent
+        id is absent or no spawn record names its type.
+    """
+    agent_id = subagent_stop_payload.get("agent_id", "")
+    if not agent_id:
+        return None
+    return _resolve_agent_type_with_retry(
+        subagent_stop_payload.get("transcript_path", ""), agent_id
+    )
+
+
+def mint_for_payload(subagent_stop_payload: dict) -> Path | None:
+    """Mint a verdict file for a code-verifier stop event.
+
+    Args:
+        subagent_stop_payload: The SubagentStop hook payload.
+
+    Returns:
+        The verdict file path when minted; None when the payload is not a
+        code-verifier stop, the transcript holds no verdict, or the
+        session directory is not a work tree with an upstream base.
+    """
+    if resolved_subagent_type(subagent_stop_payload) != MINTING_AGENT_TYPE:
+        return None
+    agent_transcript_path = subagent_stop_payload.get("agent_transcript_path", "")
+    if not agent_transcript_path:
+        return None
+    verdict_record = last_verdict_in_blocks(assistant_text_blocks(agent_transcript_path))
+    if verdict_record is None:
+        return None
+    repo_root = resolve_repo_root(subagent_stop_payload.get("cwd", "."))
+    if repo_root is None:
+        return None
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
+    if surface_manifest_text is None:
+        return None
+    return write_verdict(
+        repo_root,
+        manifest_sha256(surface_manifest_text),
+        verdict_record["all_pass"],
+        verdict_record["findings"],
+        str(subagent_stop_payload.get("agent_id", "")),
+    )
+
+
+def main() -> None:
+    """Read the SubagentStop payload and mint a verdict when one applies."""
+    try:
+        subagent_stop_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(subagent_stop_payload, dict):
+        return
+    mint_for_payload(subagent_stop_payload)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/workflow_substitution_slot_blocker.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block bare per-iteration index tokens in .workflow.js templates.
+
+Root cause: a `.workflow.js` agent-prompt block that loops over an index (for
+example "For EACH candidate i, build a dir cand_i ...") sometimes writes the
+per-iteration directory or output key as a bare token like `cand_i`. A bare
+`_i`-suffixed token reads as a fixed literal rather than a substitution slot, so
+an agent can plausibly create one literal directory named `cand_i` and overwrite
+it across every iteration -- collapsing an N-iteration gate into a single run.
+
+The established convention in these templates marks every per-call substitution
+slot with angle brackets (`<plate.svg>`, `<object.svg>`, `<glow_hex>`). The fix
+is to mark the index the same way: `cand_<i>`.
+
+Detection strategy: act only on Write/Edit to a path ending in `.workflow.js`.
+Within the written content, fire only when ALL of the following hold, so the
+hook catches exactly the bare-literal shape and never a template that does not
+use the substitution convention at all:
+
+  1. the content uses the angle-bracket substitution convention somewhere
+     (a `<...>` slot), proving the author marks per-call values that way;
+  2. the content establishes a per-iteration loop (an "each"/"EACH"/"for i"
+     style phrase, or an explicit `cand_0` enumeration);
+  3. a bare `<word>_<i|j|k>` token appears as a per-iteration path segment
+     (adjacent to a path separator). A quoted structured-output key whose name
+     ends in `_i|_j|_k` (a permanent identifier with no per-iteration path) does
+     not fire on its own; only the per-iteration path shape triggers a block.
+
+Fails OPEN (approves) on malformed input or a non-workflow path; the violation
+shape is narrow enough that a false negative is preferable to blocking
+unrelated edits.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.workflow_substitution_slot_blocker_constants import (  # noqa: E402
+    CORRECTIVE_MESSAGE,
+    EDIT_TOOL_NAME,
+    MULTI_EDIT_TOOL_NAME,
+    WORKFLOW_FILE_SUFFIX,
+    WRITE_TOOL_NAME,
+)
+
+def multi_edit_new_strings(all_tool_input: dict[str, object]) -> str:
+    all_edits = all_tool_input.get("edits", [])
+    if not isinstance(all_edits, list):
+        return ""
+    all_new_strings = [
+        each_edit["new_string"]
+        for each_edit in all_edits
+        if isinstance(each_edit, dict) and isinstance(each_edit.get("new_string"), str)
+    ]
+    return "\n".join(all_new_strings)
+
+
+def written_content(tool_name: str, all_tool_input: dict[str, object]) -> str:
+    if tool_name == WRITE_TOOL_NAME:
+        content = all_tool_input.get("content", "")
+        return content if isinstance(content, str) else ""
+    if tool_name == EDIT_TOOL_NAME:
+        new_string = all_tool_input.get("new_string", "")
+        return new_string if isinstance(new_string, str) else ""
+    if tool_name == MULTI_EDIT_TOOL_NAME:
+        return multi_edit_new_strings(all_tool_input)
+    return ""
+
+
+def target_path(all_tool_input: dict[str, object]) -> str:
+    file_path = all_tool_input.get("file_path", "")
+    return file_path if isinstance(file_path, str) else ""
+
+
+def uses_angle_slot_convention(content: str) -> bool:
+    angle_slot_pattern = re.compile(r"<[^<>\n]+>")
+    return bool(angle_slot_pattern.search(content))
+
+
+def has_iteration_loop(content: str) -> bool:
+    loop_phrase_pattern = re.compile(
+        r"\b(?:for\s+each|each\s+candidate|for\s+[ijk]\b|candidate\s+[ijk]\b|cand_0)\b",
+        re.IGNORECASE,
+    )
+    uppercase_each_keyword_pattern = re.compile(r"\bEACH\b")
+    return bool(
+        loop_phrase_pattern.search(content)
+        or uppercase_each_keyword_pattern.search(content)
+    )
+
+
+def find_bare_path_segments(content: str) -> set[str]:
+    loop_letters = "ijk"
+    path_context = re.compile(
+        r"(?:[\\/]\s*([A-Za-z][\w]*?_[" + loop_letters + r"])(?![\w>])"
+        r"|([A-Za-z][\w]*?_[" + loop_letters + r"])(?![\w>])\s*[\\/])"
+    )
+    all_path_segments: set[str] = set()
+    for each_match in path_context.finditer(content):
+        each_token = next(
+            (each_group for each_group in each_match.groups() if each_group),
+            "",
+        )
+        if each_token:
+            all_path_segments.add(each_token)
+    return all_path_segments
+
+
+def find_bare_index_segments(content: str) -> set[str]:
+    return find_bare_path_segments(content)
+
+
+def content_has_violation(content: str) -> bool:
+    if not uses_angle_slot_convention(content):
+        return False
+    if not has_iteration_loop(content):
+        return False
+    return bool(find_bare_index_segments(content))
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name not in (WRITE_TOOL_NAME, EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME):
+        sys.exit(0)
+
+    all_tool_input = hook_input.get("tool_input", {})
+    if not isinstance(all_tool_input, dict):
+        sys.exit(0)
+
+    if not target_path(all_tool_input).endswith(WORKFLOW_FILE_SUFFIX):
+        sys.exit(0)
+
+    if not content_has_violation(written_content(tool_name, all_tool_input)):
+        sys.exit(0)
+
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": CORRECTIVE_MESSAGE,
+        }
+    }
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/diagnostic/test_hook_log_extractor.py

@@ -82,7 +82,7 @@ def _make_blocking_line(
     hook_event: str = "PreToolUse",
     tool_use_id: str = "toolu_002",
     blocking_message: str = "blocked for reason",
-    command: str = "python C:/Users/jon/.claude/hooks/blocking/content_search_to_zoekt_redirector.py",
+    command: str = "python C:/Users/jon/.claude/hooks/blocking/block_main_commit.py",
     timestamp: str = "2026-04-24T13:32:54.293Z",
     cwd: str = "Y:\\Projects\\repo",
     git_branch: str = "main",
@@ -640,7 +640,7 @@ def test_run_summary_prints_table_when_rows_returned(
 ) -> None:
     fake_cursor = MagicMock()
     fake_cursor.fetchall.return_value = [
-        ("content_search_to_zoekt_redirector.py", "blocking", 7, "Bash(grep foo)"),
+        ("block_main_commit.py", "blocking", 7, "Bash(git commit)"),
     ]
     fake_connection = MagicMock()
     fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
@@ -652,7 +652,7 @@ def test_run_summary_prints_table_when_rows_returned(
 
     captured = capsys.readouterr()
     assert exit_code == 0
-    assert "content_search_to_zoekt_redirector.py" in captured.out
+    assert "block_main_commit.py" in captured.out
     assert "blocking" in captured.out
     assert "7" in captured.out
 

package/hooks/hooks.json

@@ -44,12 +44,32 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/state_description_blocker.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/subprocess_budget_completeness.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/hook_prose_detector_consistency.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verified_commit_message_accuracy_blocker.py",
+            "timeout": 10
           }
         ]
       },
       {
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/workflow_substitution_slot_blocker.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/open_questions_in_plans_blocker.py",
@@ -103,7 +123,7 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/precommit_code_rules_gate.py",
-            "timeout": 30
+            "timeout": 150
           },
           {
             "type": "command",
@@ -129,6 +149,31 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_pr_author_enforcer.py",
             "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verified_commit_gate.py",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verdict_directory_write_blocker.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verified_commit_gate.py",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verdict_directory_write_blocker.py",
+            "timeout": 10
           }
         ]
       },
@@ -232,6 +277,18 @@
         ]
       }
     ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verifier_verdict_minter.py",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": "",

package/hooks/hooks_constants/blocking_check_limits.py

@@ -20,6 +20,7 @@ MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES: int = 5
 MAX_IGNORED_MUST_CHECK_RETURN_ISSUES: int = 5
 MAX_TYPE_ESCAPE_HATCH_ISSUES: int = 5
 MAX_THIN_WRAPPER_ISSUES: int = 1
+MAX_ZERO_PAYLOAD_ALIAS_ISSUES: int = 3
 MAX_LOGGING_FSTRING_ISSUES: int = 3
 MAX_WINDOWS_API_NONE_ISSUES: int = 3
 MAX_E2E_TEST_NAMING_ISSUES: int = 3

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -24,6 +24,8 @@ ALL_MIGRATION_PATH_PATTERNS = {"/migrations/", "\\migrations\\"}
 ADVISORY_LINE_THRESHOLD_SOFT = 400
 ADVISORY_LINE_THRESHOLD_HARD = 1000
 
+DENY_REASON_ISSUE_PREVIEW_COUNT = 10
+
 ALL_BOOLEAN_NAME_PREFIXES: tuple[str, ...] = ("is_", "has_", "should_", "can_", "was_", "did_")
 UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
 
@@ -108,6 +110,20 @@ ALL_BUILTIN_DICT_METHOD_NAMES: frozenset[str] = frozenset({
 })
 ALL_UNION_TYPING_NAMES: frozenset[str] = frozenset({"Optional", "Union"})
 ALL_SELF_AND_CLS_PARAMETER_NAMES: frozenset[str] = frozenset({"self", "cls"})
+ANNOTATION_BY_PYTEST_FIXTURE: dict[str, str] = {
+    "tmp_path": "Path",
+    "tmp_path_factory": "pytest.TempPathFactory",
+    "monkeypatch": "pytest.MonkeyPatch",
+    "capsys": "pytest.CaptureFixture[str]",
+    "capfd": "pytest.CaptureFixture[str]",
+    "caplog": "pytest.LogCaptureFixture",
+    "request": "pytest.FixtureRequest",
+}
+KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX: str = (
+    "known pytest fixture parameter must carry its single documented type "
+    "(CODE_RULES §6; pytest builtin fixture reference "
+    "https://docs.pytest.org/en/stable/reference/fixtures.html)"
+)
 ALL_LOOP_INDEX_LETTER_EXEMPTIONS: frozenset[str] = frozenset({"i", "j", "k", "_"})
 EACH_PREFIX = "each_"
 BARE_EACH_TOKEN = "each"

package/hooks/hooks_constants/dead_dataclass_field_constants.py

@@ -0,0 +1,25 @@
+"""Constants for the dead dataclass-field detector in ``code_rules_enforcer``.
+
+Lives under the hooks-tree ``hooks_constants`` package so module-level
+UPPER_SNAKE constants satisfy the CODE_RULES "constants live in config"
+requirement and share a home with the other hook-tree configuration.
+"""
+
+ALL_DATACLASS_DECORATOR_NAMES: frozenset[str] = frozenset({"dataclass", "dataclasses"})
+ATTRGETTER_FUNCTION_NAME: str = "attrgetter"
+CLASSVAR_ANNOTATION_NAME: str = "ClassVar"
+GETATTR_FUNCTION_NAME: str = "getattr"
+GETATTR_NAME_ARGUMENT_MINIMUM: int = 2
+ALL_REFLECTIVE_FIELD_CONSUMER_NAMES: frozenset[str] = frozenset(
+    {"asdict", "astuple", "fields", "replace", "vars"}
+)
+WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME: str = "__dict__"
+ALL_WHOLE_INSTANCE_STRINGIFY_NAMES: frozenset[str] = frozenset(
+    {"str", "repr", "format"}
+)
+MAX_DEAD_DATACLASS_FIELD_ISSUES: int = 25
+DEAD_DATACLASS_FIELD_GUIDANCE: str = (
+    "field is assigned but never read in this file - remove the field and the code"
+    " that only exists to populate it, or read it where the value is needed"
+    " (CODE_RULES §9.8)"
+)

package/hooks/hooks_constants/dead_module_constant_constants.py

@@ -0,0 +1,20 @@
+"""Constants for the dead module-level constant detector in ``code_rules_enforcer``.
+
+Lives under the hooks-tree ``hooks_constants`` package so module-level
+UPPER_SNAKE constants satisfy the CODE_RULES "constants live in config"
+requirement and share a home with the other hook-tree configuration.
+"""
+
+PYTHON_SOURCE_SUFFIX: str = ".py"
+DUNDER_INIT_FILENAME: str = "__init__.py"
+CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
+CONFIG_DIRECTORY_SEGMENT: str = "config"
+DUNDER_ALL_NAME: str = "__all__"
+MINIMUM_UPPER_SNAKE_LENGTH: int = 2
+MAX_DEAD_MODULE_CONSTANT_ISSUES: int = 25
+MAX_SCAN_ROOT_FILE_COUNT: int = 2000
+DEAD_MODULE_CONSTANT_GUIDANCE: str = (
+    "module-level constant is defined here but never imported or read by any"
+    " module in the enclosing package tree - remove the constant, or reference it"
+    " where its value is needed (CODE_RULES §9.8)"
+)