claude-dev-env 1.60.0 → 1.62.0

package/hooks/blocking/verification_verdict_store.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import ast
 import hashlib
 import json
+import re
 import subprocess
 import sys
 import time
@@ -25,20 +26,35 @@ if blocking_directory not in sys.path:
     sys.path.insert(0, blocking_directory)
 
 from config.verified_commit_constants import (
+    AGENT_META_SIDECAR_SUFFIX,
+    AGENT_META_TYPE_KEY,
+    AGENT_TRANSCRIPT_GLOB,
     CLAUDE_HOME_DIRECTORY_NAME,
     CONFTEST_FILE_NAME,
     DOCS_ONLY_EXTENSIONS,
     ALL_FALLBACK_BASE_REFERENCES,
     GIT_TIMEOUT_SECONDS,
+    MANIFEST_HASH_CLI_FLAG,
     MINIMUM_STATUS_FIELD_COUNT,
+    MINTING_AGENT_TYPE,
     PYTHON_EXTENSION,
     ROOT_KEY_HEX_LENGTH,
+    SUBAGENTS_DIRECTORY_NAME,
     TEST_FILE_PREFIX,
     TEST_FILE_SUFFIX,
     ALL_TOOLING_STATE_PREFIXES,
+    TRANSCRIPT_ASSISTANT_ENTRY_TYPE,
+    TRANSCRIPT_CONTENT_KEY,
+    TRANSCRIPT_CONTENT_TYPE_KEY,
+    TRANSCRIPT_ENTRY_TYPE_KEY,
+    TRANSCRIPT_MESSAGE_KEY,
+    TRANSCRIPT_TEXT_CONTENT_TYPE,
+    TRANSCRIPT_TEXT_KEY,
     VERDICT_DIRECTORY_NAME,
+    VERDICT_FENCE_PATTERN,
     VERDICT_JSON_INDENT,
     VERDICT_KEY_ALL_PASS,
+    VERDICT_KEY_FINDINGS,
     VERDICT_KEY_MANIFEST_SHA256,
 )
 
@@ -273,6 +289,187 @@ def load_valid_verdict(repo_root: str, expected_manifest_sha256: str) -> dict |
     return verdict_record
 
 
+def _subagents_directory_for_transcript(transcript_path: str) -> Path | None:
+    """Locate the live session's subagents directory from a transcript path.
+
+    Handles both transcript shapes the runtime produces: a transcript already
+    inside a ``.../subagents/...`` tree resolves to its nearest ancestor named
+    ``subagents``; a session transcript ``<dir>/<session-id>.jsonl`` resolves
+    to ``<dir>/<session-id>/subagents``.
+
+    Args:
+        transcript_path: The live session's transcript path from the payload.
+
+    Returns:
+        The existing subagents directory, or None when neither shape yields
+        an existing directory.
+    """
+    if not transcript_path:
+        return None
+    transcript_file = Path(transcript_path)
+    for each_ancestor in transcript_file.parents:
+        if each_ancestor.name == SUBAGENTS_DIRECTORY_NAME and each_ancestor.is_dir():
+            return each_ancestor
+    session_subagents_directory = (
+        transcript_file.with_suffix("") / SUBAGENTS_DIRECTORY_NAME
+    )
+    if session_subagents_directory.is_dir():
+        return session_subagents_directory
+    return None
+
+
+def _agent_type_for_transcript(transcript_file: Path) -> str | None:
+    """Read an agent transcript's sidecar to learn the agent type it ran as.
+
+    Args:
+        transcript_file: An ``agent-*.jsonl`` transcript path.
+
+    Returns:
+        The ``agentType`` recorded in the ``<stem>.meta.json`` sidecar, or
+        None when the sidecar is missing, unreadable, or carries no type.
+    """
+    sidecar_file = transcript_file.with_suffix(AGENT_META_SIDECAR_SUFFIX)
+    try:
+        sidecar_record = json.loads(sidecar_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(sidecar_record, dict):
+        return None
+    recorded_agent_type = sidecar_record.get(AGENT_META_TYPE_KEY)
+    return recorded_agent_type if isinstance(recorded_agent_type, str) else None
+
+
+def _assistant_text_blocks(transcript_file: Path) -> list[str]:
+    """Collect every assistant text block from an agent transcript.
+
+    Args:
+        transcript_file: An ``agent-*.jsonl`` transcript path.
+
+    Returns:
+        The text of each assistant message content block, in order; empty
+        when the file is missing, unreadable, or holds no assistant text.
+    """
+    try:
+        transcript_lines = transcript_file.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    all_text_blocks: list[str] = []
+    for each_line in transcript_lines:
+        if not each_line.strip():
+            continue
+        try:
+            transcript_entry = json.loads(each_line)
+        except json.JSONDecodeError:
+            continue
+        all_text_blocks.extend(_entry_text_blocks(transcript_entry))
+    return all_text_blocks
+
+
+def _entry_text_blocks(transcript_entry: object) -> list[str]:
+    """Extract assistant text from one parsed transcript entry.
+
+    Args:
+        transcript_entry: One parsed JSONL transcript entry.
+
+    Returns:
+        The text of each text content block on an assistant entry, in order;
+        empty for any other entry shape.
+    """
+    if not isinstance(transcript_entry, dict):
+        return []
+    if transcript_entry.get(TRANSCRIPT_ENTRY_TYPE_KEY) != TRANSCRIPT_ASSISTANT_ENTRY_TYPE:
+        return []
+    message_record = transcript_entry.get(TRANSCRIPT_MESSAGE_KEY)
+    if not isinstance(message_record, dict):
+        return []
+    content_blocks = message_record.get(TRANSCRIPT_CONTENT_KEY)
+    if not isinstance(content_blocks, list):
+        return []
+    all_text_blocks: list[str] = []
+    for each_block in content_blocks:
+        if not isinstance(each_block, dict):
+            continue
+        if each_block.get(TRANSCRIPT_CONTENT_TYPE_KEY) != TRANSCRIPT_TEXT_CONTENT_TYPE:
+            continue
+        block_text = each_block.get(TRANSCRIPT_TEXT_KEY)
+        if isinstance(block_text, str):
+            all_text_blocks.append(block_text)
+    return all_text_blocks
+
+
+def _last_verdict_record(all_text_blocks: list[str]) -> dict | None:
+    """Parse the last verdict fence across an agent's assistant text blocks.
+
+    Args:
+        all_text_blocks: The assistant text blocks from one transcript.
+
+    Returns:
+        The parsed verdict mapping when the last verdict fence carries a bool
+        ``all_pass``, a list ``findings``, and a string ``manifest_sha256``;
+        otherwise None.
+    """
+    verdict_fence_pattern = re.compile(VERDICT_FENCE_PATTERN, re.DOTALL)
+    all_fence_bodies = [
+        each_match.group(1)
+        for each_block in all_text_blocks
+        for each_match in verdict_fence_pattern.finditer(each_block)
+    ]
+    if not all_fence_bodies:
+        return None
+    try:
+        verdict_record = json.loads(all_fence_bodies[-1])
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(verdict_record, dict):
+        return None
+    if not isinstance(verdict_record.get(VERDICT_KEY_ALL_PASS), bool):
+        return None
+    if not isinstance(verdict_record.get(VERDICT_KEY_FINDINGS), list):
+        return None
+    if not isinstance(verdict_record.get(VERDICT_KEY_MANIFEST_SHA256), str):
+        return None
+    return verdict_record
+
+
+def workflow_verdict_covers_surface(
+    transcript_path: str, expected_manifest_sha256: str
+) -> bool:
+    """Decide whether a workflow code-verifier verdict covers the live surface.
+
+    A workflow-spawned ``code-verifier`` emits its verdict as assistant text in
+    its own transcript rather than through the SubagentStop minter, so this
+    walks the live session's subagent transcripts for a ``code-verifier`` whose
+    final verdict reports ``all_pass`` true and binds to the expected manifest
+    hash.
+
+    Args:
+        transcript_path: The live session's transcript path from the payload.
+        expected_manifest_sha256: Hash of the live surface manifest the verdict
+            must match exactly.
+
+    Returns:
+        True as soon as one ``code-verifier`` transcript carries a passing
+        verdict bound to the expected hash; False when none match or the
+        subagents directory cannot be located.
+    """
+    subagents_directory = _subagents_directory_for_transcript(transcript_path)
+    if subagents_directory is None:
+        return False
+    for each_transcript_file in subagents_directory.rglob(AGENT_TRANSCRIPT_GLOB):
+        if _agent_type_for_transcript(each_transcript_file) != MINTING_AGENT_TYPE:
+            continue
+        verdict_record = _last_verdict_record(
+            _assistant_text_blocks(each_transcript_file)
+        )
+        if verdict_record is None:
+            continue
+        if verdict_record[VERDICT_KEY_ALL_PASS] is not True:
+            continue
+        if verdict_record[VERDICT_KEY_MANIFEST_SHA256] == expected_manifest_sha256:
+            return True
+    return False
+
+
 def write_verdict(
     repo_root: str,
     bound_manifest_sha256: str,
@@ -444,3 +641,46 @@ def is_verification_exempt_diff(repo_root: str, merge_base_sha: str) -> bool:
         if not _is_python_change_docstring_only(repo_root, merge_base_sha, changed_path):
             return False
     return True
+
+
+def _print_live_manifest_hash(repo_directory: str) -> int:
+    """Print the live surface manifest hash for a repo, for a workflow verifier.
+
+    A workflow code-verifier runs this to learn the exact hash to bind its
+    verdict to, so stdout carries only the hash and nothing else.
+
+    Args:
+        repo_directory: A directory inside the work tree to bind the verdict to.
+
+    Returns:
+        0 after printing the hash; nonzero with no stdout when the repo root or
+        merge base cannot be resolved.
+    """
+    repo_root = resolve_repo_root(repo_directory)
+    if repo_root is None:
+        return 1
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return 1
+    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
+    if surface_manifest_text is None:
+        return 1
+    print(manifest_sha256(surface_manifest_text))
+    return 0
+
+
+def main() -> None:
+    """Run the verdict-store CLI: compute the live surface-manifest hash.
+
+    Reads ``--manifest-hash <repo_root>`` from argv and prints the live
+    ``manifest_sha256`` so a workflow code-verifier can bind its verdict to the
+    exact surface the gate checks. Exits nonzero with no stdout on any other
+    argument shape or when the surface cannot be resolved.
+    """
+    if len(sys.argv) == 3 and sys.argv[1] == MANIFEST_HASH_CLI_FLAG:
+        sys.exit(_print_live_manifest_hash(sys.argv[2]))
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/verified_commit_gate.py

@@ -5,6 +5,8 @@ Fires on Bash and PowerShell tool calls. When the command carries a
 targets, computes the live change-surface manifest against the merge base,
 and allows the command only when one of these holds:
 
+- the command carries the verification bypass marker (``# verify-skip``),
+  a manual on-the-fly override that skips the gate for that one command,
 - the repository has no resolvable upstream base — no ``origin/HEAD``, no
   configured tracking ref, and neither ``origin/main`` nor ``origin/master``
   (scratch repos with no remote branch are out of scope),
@@ -47,6 +49,7 @@ from config.verified_commit_constants import (
     OPTION_WITH_VALUE_STEP,
     REPO_DIRECTORY_OPTION,
     VALUE_TAKING_GIT_OPTIONS,
+    VERIFICATION_BYPASS_MARKER,
     WORK_TREE_OPTION,
 )
 from verification_verdict_store import (
@@ -56,6 +59,7 @@ from verification_verdict_store import (
     manifest_sha256,
     resolve_merge_base,
     resolve_repo_root,
+    workflow_verdict_covers_surface,
 )
 
 
@@ -464,15 +468,23 @@ def gated_repo_directories(command_text: str, fallback_directory: str) -> list[s
     return target_directories
 
 
-def deny_reason_for_directory(target_directory: str) -> str | None:
+def deny_reason_for_directory(target_directory: str, transcript_path: str) -> str | None:
     """Decide whether a commit/push in a directory must be blocked.
 
+    Accepts the command when a minted verdict binds to the live surface, or
+    when a workflow-spawned code-verifier emitted a passing verdict bound to
+    the same surface in its own transcript — the latter covers workflow runs,
+    where SubagentStop never fires to mint a verdict file.
+
     Args:
         target_directory: The directory the git command targets.
+        transcript_path: The live session's transcript path from the payload,
+            used to find a workflow code-verifier's verdict.
 
     Returns:
-        The deny reason when the branch diff needs a verdict and none binds
-        to it; None when the command may proceed.
+        The deny reason when the branch diff needs a verdict and neither a
+        minted nor a workflow verdict binds to it; None when the command may
+        proceed.
     """
     repo_root = resolve_repo_root(target_directory)
     if repo_root is None:
@@ -486,14 +498,21 @@ def deny_reason_for_directory(target_directory: str) -> str | None:
     if surface_manifest_text is None:
         return f"{CORRECTIVE_MESSAGE} (surface manifest failed in {repo_root})"
     live_manifest_sha256 = manifest_sha256(surface_manifest_text)
-    if load_valid_verdict(repo_root, live_manifest_sha256) is None:
-        hash_preview = live_manifest_sha256[:HASH_PREVIEW_LENGTH]
-        return f"{CORRECTIVE_MESSAGE} (repo: {repo_root}, surface sha256 {hash_preview}...)"
-    return None
+    if load_valid_verdict(repo_root, live_manifest_sha256) is not None:
+        return None
+    if workflow_verdict_covers_surface(transcript_path, live_manifest_sha256):
+        return None
+    hash_preview = live_manifest_sha256[:HASH_PREVIEW_LENGTH]
+    return f"{CORRECTIVE_MESSAGE} (repo: {repo_root}, surface sha256 {hash_preview}...)"
 
 
 def main() -> None:
-    """Read the PreToolUse payload and deny unverified commit/push commands."""
+    """Read the PreToolUse payload and decide whether to allow the command.
+
+    Allows the command without a verdict when it carries the verification
+    bypass marker (``VERIFICATION_BYPASS_MARKER``), a manual on-the-fly
+    override; otherwise denies an unverified commit or push.
+    """
     try:
         pretooluse_payload = json.load(sys.stdin)
     except json.JSONDecodeError:
@@ -503,9 +522,12 @@ def main() -> None:
     command_text = pretooluse_payload.get("tool_input", {}).get("command", "")
     if not command_text:
         return
+    if VERIFICATION_BYPASS_MARKER in command_text:
+        return
     session_directory = pretooluse_payload.get("cwd", ".")
+    transcript_path = pretooluse_payload.get("transcript_path", "")
     for each_target_directory in gated_repo_directories(command_text, session_directory):
-        deny_reason = deny_reason_for_directory(each_target_directory)
+        deny_reason = deny_reason_for_directory(each_target_directory, transcript_path)
         if deny_reason is None:
             continue
         deny_payload = {

package/hooks/blocking/verifier_verdict_minter.py

@@ -2,18 +2,18 @@
 
 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
+SubagentStop payload names the stopping subagent's own transcript
+(``agent_transcript_path``), which sits beside a harness-written
+``agent-<id>.meta.json`` sidecar naming the spawning ``agentType``. The hook
+reads that type from the sidecar, so it resolves identically in interactive,
+background, and worktree-switched sessions. 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.
+transcript (``agent_transcript_path``); the main session writes neither that
+transcript nor the sidecar, so text it prints 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::
 
@@ -29,18 +29,13 @@ 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 config.verified_commit_constants import MINTING_AGENT_TYPE
 from verification_verdict_store import (
     branch_surface_manifest,
     manifest_sha256,
@@ -119,131 +114,58 @@ def last_verdict_in_blocks(all_text_blocks: list[str]) -> dict | None:
     return None
 
 
-def _transcript_entries(transcript_path: str) -> list[dict]:
-    """Parse every JSON object line of a transcript file.
+def _agent_type_from_meta_sidecar(agent_transcript_path: str) -> str | None:
+    """Read the spawning agentType from a subagent transcript's sidecar.
 
-    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.
+    Each subagent transcript ``agent-<id>.jsonl`` sits beside a harness-written
+    ``agent-<id>.meta.json`` naming the spawning ``agentType``. Reading the type
+    from this sidecar binds it to the stopping subagent itself, so it resolves
+    identically in interactive, background, and worktree-switched sessions and
+    needs no parent-transcript scan or flush retry.
 
     Args:
-        transcript_node: A JSON value drawn from a parsed transcript entry.
-        agent_id: The stopping subagent's id from the payload.
+        agent_transcript_path: The stopping subagent's own transcript path from
+            the SubagentStop payload.
 
     Returns:
-        The ``agentType`` of the matching mapping, or None when no nested
-        value names this agent.
+        The recorded ``agentType``, or None when the path is empty, the sidecar
+        is absent or cannot be read or parsed, it does not hold a JSON object,
+        or it names no string ``agentType``.
     """
-    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
+    if not agent_transcript_path:
         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
+    transcript_file = Path(agent_transcript_path)
+    sidecar_file = transcript_file.with_name(f"{transcript_file.stem}.meta.json")
+    try:
+        sidecar_record = json.loads(sidecar_file.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(sidecar_record, dict):
+        return None
+    recorded_type = sidecar_record.get("agentType")
+    return recorded_type if isinstance(recorded_type, str) else 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.
+    The stopping subagent's own transcript (``agent_transcript_path``) sits
+    beside a harness-written ``agent-<id>.meta.json`` sidecar naming its
+    ``agentType``. Reading the type from that sidecar binds it to the subagent
+    itself, so it resolves the same across interactive, background, and
+    worktree-switched sessions.
 
     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.
+        The agent type this subagent was spawned with, or None when the
+        ``agent_transcript_path`` is empty, the sidecar is absent or cannot be
+        read or parsed, it does not hold a JSON object, or it names no string
+        ``agentType``.
     """
-    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
+    return _agent_type_from_meta_sidecar(
+        subagent_stop_payload.get("agent_transcript_path", "")
     )
 
 

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -124,6 +124,12 @@ KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX: str = (
     "(CODE_RULES §6; pytest builtin fixture reference "
     "https://docs.pytest.org/en/stable/reference/fixtures.html)"
 )
+UNUSED_PYTEST_FIXTURE_PARAMETER_MESSAGE_SUFFIX: str = (
+    "known pytest fixture parameter is declared but never referenced in the "
+    "function body; pytest still materializes its setup, so drop the unused "
+    "parameter (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_config_field_constants.py

@@ -0,0 +1,39 @@
+"""Constants for the dead config-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.
+"""
+
+from hooks_constants.dead_dataclass_field_constants import (
+    ALL_REFLECTIVE_FIELD_CONSUMER_NAMES,
+    WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME,
+)
+from hooks_constants.dead_module_constant_constants import (
+    CONFIG_DIRECTORY_SEGMENT,
+    DUNDER_INIT_FILENAME,
+    MAX_SCAN_ROOT_FILE_COUNT,
+    PYTHON_SOURCE_SUFFIX,
+)
+
+CONFIG_CLASS_NAME_SUFFIX: str = "Config"
+DATACLASSES_MODULE_NAME: str = "dataclasses"
+MAX_DEAD_CONFIG_FIELD_ISSUES: int = 25
+DEAD_CONFIG_FIELD_GUIDANCE: str = (
+    "config dataclass field is defined but read by no production module in the"
+    " enclosing package tree - remove the dead field, or read it where the value"
+    " is needed (CODE_RULES §9.8)"
+)
+
+__all__ = [
+    "ALL_REFLECTIVE_FIELD_CONSUMER_NAMES",
+    "CONFIG_CLASS_NAME_SUFFIX",
+    "CONFIG_DIRECTORY_SEGMENT",
+    "DATACLASSES_MODULE_NAME",
+    "DEAD_CONFIG_FIELD_GUIDANCE",
+    "DUNDER_INIT_FILENAME",
+    "MAX_DEAD_CONFIG_FIELD_ISSUES",
+    "MAX_SCAN_ROOT_FILE_COUNT",
+    "PYTHON_SOURCE_SUFFIX",
+    "WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME",
+]

package/hooks/hooks_constants/destructive_command_segment_constants.py

@@ -41,6 +41,7 @@ ALL_INTERPRETER_AND_WRAPPER_COMMANDS: frozenset[str] = frozenset(
         "su",
         "env",
         "xargs",
+        "parallel",
         "awk",
         "gawk",
         "mawk",
@@ -66,6 +67,12 @@ ALL_REMOTE_AND_PROGRAM_STRING_EXECUTORS: frozenset[str] = frozenset(
     }
 )
 ALL_STRING_ARGUMENT_EXECUTION_FLAGS: frozenset[str] = frozenset({"-c", "-e"})
+FIND_PROGRAM_NAME: str = "find"
+ALL_FIND_EXEC_ACTION_FLAGS: frozenset[str] = frozenset({"-exec", "-execdir"})
+ALL_FIND_EXEC_ACTION_TERMINATORS: frozenset[str] = frozenset({";", "+"})
+ALL_FIND_GLOBAL_OPTION_FLAGS_WITHOUT_VALUE: frozenset[str] = frozenset({"-H", "-L", "-P"})
+ALL_FIND_GLOBAL_OPTION_FLAGS_TAKING_A_VALUE: frozenset[str] = frozenset({"-D"})
+FIND_OPTIMIZATION_LEVEL_OPTION_PREFIX: str = "-O"
 ALL_BENIGN_COMPOUND_SEGMENT_COMMANDS: frozenset[str] = frozenset(
     {
         "echo",
@@ -176,3 +183,11 @@ ALL_LAUNCHER_OPTIONS_TAKING_SEPARATE_VALUE: frozenset[str] = frozenset(
     }
 )
 ALL_SUBSHELL_GROUPING_CHARACTERS: str = "({"
+ALL_KNOWN_TEMPORARY_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
+    {
+        "TEMP",
+        "TMP",
+        "TMPDIR",
+        "CLAUDE_JOB_DIR",
+    }
+)