claude-dev-env 1.72.0 → 1.74.0

package/hooks/blocking/code_rules_enforcer.py

@@ -69,7 +69,14 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_args_match_signature,
     check_docstring_fallback_branch_coverage,
     check_docstring_format,
+    check_docstring_names_undefined_constant,
     check_docstring_no_consumer_claim,
+    check_docstring_no_inline_literal_claim,
+    check_docstring_returns_plural_cardinality,
+    check_docstring_step_enumeration_dispatch_coverage,
+    check_docstring_tuple_enumeration_match,
+    check_docstring_unguarded_malformed_payload_claim,
+    check_module_docstring_names_public_checks,
 )
 from code_rules_duplicate_body import (  # noqa: E402
     advise_cross_skill_duplicate_helper,
@@ -154,6 +161,7 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     PRECHECK_USAGE_EXIT_CODE,
     PRECHECK_USAGE_MESSAGE,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.setup_project_paths_constants import (  # noqa: E402
     UTF8_BYTE_ORDER_MARK,
 )
@@ -255,9 +263,34 @@ def validate_content(
         all_issues.extend(check_docstring_args_match_signature(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_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)
         )
+        all_issues.extend(
+            check_module_docstring_names_public_checks(effective_content, file_path)
+        )
+        all_issues.extend(
+            check_docstring_tuple_enumeration_match(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_names_undefined_constant(effective_content, file_path)
+        )
         all_issues.extend(
             check_boolean_naming(
                 effective_content,
@@ -761,6 +794,11 @@ def _write_deny_payload(deny_reason: str, deny_stream: TextIO) -> None:
             "permissionDecisionReason": deny_reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="code_rules_enforcer.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+    )
     deny_stream.write(json.dumps(deny_payload) + "\n")
     deny_stream.flush()
 

package/hooks/blocking/code_rules_shared.py

@@ -20,12 +20,14 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_HOOK_INFRASTRUCTURE_PATTERNS,
     ALL_MIGRATION_PATH_PATTERNS,
     ALL_ROOT_ANCHORED_EPHEMERAL_DIRECTORIES,
+    ALL_STRICT_TEST_DIRECTORY_SEGMENTS,
     ALL_TEST_PATH_PATTERNS,
     ALL_WORKFLOW_REGISTRY_PATTERNS,
     CLAUDE_JOB_DIR_ENVIRONMENT_VARIABLE_NAME,
     CLAUDE_JOB_DIR_SCRATCH_SUBDIRECTORY,
     EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME,
     LEADING_DRIVE_LETTER_PATTERN,
+    STRICT_TEST_FILE_BASENAME_PATTERN,
 )
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
     TYPE_CHECKING_IDENTIFIER,
@@ -55,6 +57,23 @@ def is_test_file(file_path: str) -> bool:
     return any(pattern in path_lower for pattern in ALL_TEST_PATH_PATTERNS)
 
 
+def is_strict_test_file(file_path: str) -> bool:
+    """Check if a file is a genuine test module by its basename, not a mid-name match.
+
+    A production module whose name carries the substring ``test`` mid-name —
+    such as ``code_rules_test_assertions.py`` — is not a test module. This
+    predicate anchors on the basename shape (``test_*`` / ``*_test.*`` /
+    ``*.test.*`` / ``*.spec.*`` / ``conftest.py``) or a ``/tests/`` path
+    segment, so it keeps such production modules out of the test exemption that
+    the substring-based is_test_file applies.
+    """
+    normalized_path = file_path.lower().replace("\\", "/")
+    if any(segment in normalized_path for segment in ALL_STRICT_TEST_DIRECTORY_SEGMENTS):
+        return True
+    basename_lower = normalized_path.rsplit("/", 1)[-1]
+    return STRICT_TEST_FILE_BASENAME_PATTERN.match(basename_lower) is not None
+
+
 def is_workflow_registry_file(file_path: str) -> bool:
     """Check if file is a workflow state/module registry file.
 

package/hooks/blocking/code_verifier_spawn_preflight_gate.py

@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: pre-flight gate for the code-verifier subagent spawn.
+
+The hook fires only on an ``Agent`` tool call whose ``subagent_type`` is
+``code-verifier``. Before that verification spawn runs, the hook checks the
+branch for two committability problems against the resolved base ref: a real
+merge conflict (a non-mutating trial-merge of HEAD against the base ref) and a
+CODE_RULES violation on a line added in the uncommitted working tree. When
+either fires, the hook denies the spawn with a reason addressed to the spawning
+agent that names the conflicting files and the violating file:line, so that
+agent fixes them and re-spawns. Both checks fail OPEN on any infrastructure
+problem — a non-repo cwd, an absent base ref, a git or engine failure, or a
+timeout — because the authoritative fail-closed CODE_RULES enforcement already
+runs at Write time and at commit time. The hook never network-fetches and never
+mutates the index or working tree.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import TextIO
+
+_blocking_dir = str(Path(__file__).resolve().parent)
+if _blocking_dir not in sys.path:
+    sys.path.insert(0, _blocking_dir)
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.append(_hooks_dir)
+
+from verification_verdict_store import (  # noqa: E402
+    candidate_base_references,
+    resolve_merge_base,
+    resolve_repo_root,
+    run_git,
+    untracked_file_paths,
+)
+
+from hooks_constants.code_verifier_spawn_preflight_gate_constants import (  # noqa: E402
+    ALL_MERGE_TREE_COMMAND_FLAGS,
+    ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS,
+    ALL_UNIFIED_ZERO_DIFF_FLAGS,
+    CODE_RULES_SECTION_HEADER,
+    CODE_VERIFIER_SUBAGENT_TYPE,
+    DENY_REASON_LEAD,
+    GATE_SCRIPTS_RELATIVE_PATH,
+    MERGE_CONFLICT_SECTION_HEADER,
+    MERGE_TREE_CLEAN_EXIT_CODE,
+    MERGE_TREE_CONFLICT_EXIT_CODE,
+    MERGE_TREE_TIMEOUT_SECONDS,
+)
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.pr_converge_bugteam_enforcer_constants import (  # noqa: E402
+    AGENT_TOOL_NAME,
+)
+
+_scripts_dir = str(Path(__file__).resolve().parents[2] / GATE_SCRIPTS_RELATIVE_PATH)
+if _scripts_dir not in sys.path:
+    sys.path.insert(0, _scripts_dir)
+
+from code_rules_gate import (  # noqa: E402
+    ValidateContentCallable,
+    _collect_partitioned_violations,
+    _report_partitioned_violations,
+    is_code_path,
+    load_validate_content,
+    parse_added_line_numbers,
+    whole_file_line_set,
+)
+
+
+def _should_run(payload_by_field: dict[str, object]) -> bool:
+    """Return True only for a code-verifier Agent spawn.
+
+    Args:
+        payload_by_field: The full PreToolUse hook payload (already
+            JSON-parsed), keyed by top-level field name.
+
+    Returns:
+        True when the tool is Agent and ``tool_input.subagent_type`` is
+        ``code-verifier``; False for every other shape.
+    """
+    if payload_by_field.get("tool_name", "") != AGENT_TOOL_NAME:
+        return False
+    tool_input = payload_by_field.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return False
+    return tool_input.get("subagent_type", "") == CODE_VERIFIER_SUBAGENT_TYPE
+
+
+def _resolve_repo_root_and_base(working_directory: str | None) -> tuple[str, str, str] | None:
+    """Resolve the repo root, merge-base sha, and chosen base ref.
+
+    Args:
+        working_directory: The spawn's working directory from the payload, or
+            None when the payload carries no ``cwd``.
+
+    Returns:
+        A ``(repo_root, merge_base_sha, base_ref)`` triple, or None when the
+        directory is not a work tree or no base ref resolves on disk — the
+        caller fails OPEN on None.
+    """
+    start_directory = working_directory if working_directory else str(Path.cwd())
+    repo_root = resolve_repo_root(start_directory)
+    if repo_root is None:
+        return None
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    for each_reference in candidate_base_references(repo_root):
+        if run_git(repo_root, "merge-base", "HEAD", each_reference) is not None:
+            return repo_root, merge_base_sha, each_reference
+    return None
+
+
+def _run_trial_merge(repo_root: str, base_ref: str) -> tuple[int, str] | None:
+    """Run the non-mutating trial-merge and return its exit code and stdout.
+
+    Args:
+        repo_root: The repository top-level directory.
+        base_ref: The base ref to trial-merge HEAD against.
+
+    Returns:
+        A ``(returncode, stdout)`` pair, or None when the command is missing,
+        times out, or raises an OS-level error — the caller fails OPEN on None.
+    """
+    try:
+        completed_process = subprocess.run(
+            ["git", "-C", repo_root, *ALL_MERGE_TREE_COMMAND_FLAGS, base_ref, "HEAD"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=MERGE_TREE_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return completed_process.returncode, completed_process.stdout
+
+
+def _conflicting_files(repo_root: str, base_ref: str) -> list[str] | None:
+    """Return the files that conflict when HEAD trial-merges against the base.
+
+    Args:
+        repo_root: The repository top-level directory.
+        base_ref: The base ref to trial-merge HEAD against.
+
+    Returns:
+        The conflicting file paths on a conflict exit, an empty list on a
+        clean merge, or None on any infrastructure failure (command missing,
+        timeout, or an exit code that is neither clean nor conflict) — the
+        caller fails OPEN on None.
+    """
+    merge_outcome = _run_trial_merge(repo_root, base_ref)
+    if merge_outcome is None:
+        return None
+    return_code, merge_stdout = merge_outcome
+    if return_code == MERGE_TREE_CLEAN_EXIT_CODE:
+        return []
+    if return_code != MERGE_TREE_CONFLICT_EXIT_CODE:
+        return None
+    return _parse_conflicting_paths(merge_stdout)
+
+
+def _parse_conflicting_paths(merge_stdout: str) -> list[str]:
+    """Extract conflicting paths from trial-merge stdout.
+
+    Args:
+        merge_stdout: The stdout of a conflict-exit trial-merge: the written
+            tree-OID line, then one conflicting path per line, then a blank
+            line and informational text.
+
+    Returns:
+        The conflicting file paths — the lines after the tree-OID up to the
+        first blank line.
+    """
+    all_lines = merge_stdout.splitlines()
+    conflicting_paths: list[str] = []
+    for each_line in all_lines[1:]:
+        if not each_line.strip():
+            break
+        conflicting_paths.append(each_line)
+    return conflicting_paths
+
+
+def _working_tree_added_lines_by_path(
+    repo_root: str, merge_base_sha: str
+) -> tuple[list[Path], dict[Path, set[int]]] | None:
+    """Build the code-file surface and its working-tree-vs-merge-base added lines.
+
+    Args:
+        repo_root: The repository top-level directory.
+        merge_base_sha: The merge-base sha the surface diffs against.
+
+    Returns:
+        A ``(file_paths, added_lines_by_path)`` pair keyed by resolved
+        absolute path, or None when a surface git query fails — the caller
+        fails OPEN on None.
+    """
+    tracked_changed_text = run_git(repo_root, *ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS, merge_base_sha)
+    if tracked_changed_text is None:
+        return None
+    untracked_paths = untracked_file_paths(repo_root)
+    if untracked_paths is None:
+        return None
+    repo_root_path = Path(repo_root)
+    file_paths: list[Path] = []
+    added_lines_by_path: dict[Path, set[int]] = {}
+    for each_relative in tracked_changed_text.splitlines():
+        if not each_relative or not is_code_path(Path(each_relative)):
+            continue
+        resolved_path = (repo_root_path / each_relative).resolve()
+        file_paths.append(resolved_path)
+        added_lines_by_path[resolved_path] = _tracked_file_added_lines(
+            repo_root, merge_base_sha, each_relative
+        )
+    for each_relative in untracked_paths:
+        if not is_code_path(Path(each_relative)):
+            continue
+        resolved_path = (repo_root_path / each_relative).resolve()
+        file_paths.append(resolved_path)
+        added_lines_by_path[resolved_path] = whole_file_line_set(resolved_path)
+    return file_paths, added_lines_by_path
+
+
+def _tracked_file_added_lines(repo_root: str, merge_base_sha: str, relative_path: str) -> set[int]:
+    """Return the working-tree-added line numbers for one tracked file.
+
+    Args:
+        repo_root: The repository top-level directory.
+        merge_base_sha: The merge-base sha the diff runs against.
+        relative_path: The repo-relative path of the tracked changed file.
+
+    Returns:
+        The 1-indexed line numbers added vs the merge base in the working
+        tree, or an empty set when the per-file diff fails.
+    """
+    unified_diff_text = run_git(
+        repo_root, *ALL_UNIFIED_ZERO_DIFF_FLAGS, merge_base_sha, "--", relative_path
+    )
+    if unified_diff_text is None:
+        return set()
+    return parse_added_line_numbers(unified_diff_text)
+
+
+def _code_rules_report(
+    repo_root: str, all_file_paths: list[Path], all_added_lines_by_path: dict[Path, set[int]]
+) -> str | None:
+    """Run the CODE_RULES engine and return its blocking report, or None.
+
+    Args:
+        repo_root: The repository top-level directory.
+        all_file_paths: The resolved code-file paths to inspect.
+        all_added_lines_by_path: Per-file working-tree-added line numbers keyed
+            by resolved absolute path.
+
+    Returns:
+        The engine's grouped file:line report when a blocking violation lands
+        on an added line, or None when the surface is clean, only an unreadable
+        changed file caused a non-zero gate exit, the engine fails to load, or
+        any engine error arises — every non-block outcome fails OPEN. The
+        harness hook timeout in hooks.json is the wall-clock bound on a runaway
+        engine.
+    """
+    if not all_file_paths:
+        return None
+    try:
+        validate_content = load_validate_content()
+    except SystemExit:
+        return None
+    try:
+        blocking_present, captured_report = _run_gate_capturing_stderr(
+            validate_content, all_file_paths, Path(repo_root), all_added_lines_by_path
+        )
+    except OSError:
+        return None
+    if not blocking_present:
+        return None
+    return captured_report
+
+
+def _run_gate_capturing_stderr(
+    validate_content: ValidateContentCallable,
+    all_file_paths: list[Path],
+    repository_root: Path,
+    all_added_lines_by_path: dict[Path, set[int]],
+) -> tuple[bool, str]:
+    """Run the gate, reporting whether a blocking violation was actually found.
+
+    Args:
+        validate_content: The enforcer ``validate_content`` callable.
+        all_file_paths: The resolved code-file paths to inspect.
+        repository_root: The repository root path the gate resolves against.
+        all_added_lines_by_path: Per-file working-tree-added line numbers keyed
+            by resolved absolute path.
+
+    Returns:
+        A ``(blocking_present, captured_report)`` pair. ``blocking_present`` is
+        True only when at least one blocking violation landed on an added line;
+        an unreadable changed file alone (which exits the gate non-zero) leaves
+        it False, so the caller fails OPEN. ``captured_report`` is the gate's
+        grouped stderr report.
+    """
+    blocking_by_file, advisory_by_file, skipped_unreadable_count = (
+        _collect_partitioned_violations(
+            validate_content,
+            all_file_paths,
+            repository_root,
+            all_added_lines_by_path,
+            False,
+        )
+    )
+    captured_stderr = io.StringIO()
+    with contextlib.redirect_stderr(captured_stderr):
+        _report_partitioned_violations(
+            blocking_by_file,
+            advisory_by_file,
+            repository_root,
+            False,
+            skipped_unreadable_count,
+        )
+    return bool(blocking_by_file), captured_stderr.getvalue()
+
+
+def _build_deny_reason(
+    all_conflicting_files: list[str] | None, base_ref: str, code_rules_report: str | None
+) -> str | None:
+    """Assemble the spawner-addressed deny reason from the two check results.
+
+    Args:
+        all_conflicting_files: The conflicting file paths from the conflict
+            check, an empty list when clean, or None when that check failed open.
+        base_ref: The base ref named in the conflict section header.
+        code_rules_report: The grouped report from the CODE_RULES check, or None
+            when that check found nothing or failed open.
+
+    Returns:
+        The full deny reason when either check fired, or None when neither
+        produced an issue.
+    """
+    reason_sections: list[str] = []
+    if all_conflicting_files:
+        conflict_lines = "\n".join(f"  {each_path}" for each_path in all_conflicting_files)
+        conflict_header = MERGE_CONFLICT_SECTION_HEADER.format(base_ref=base_ref)
+        reason_sections.append(f"{conflict_header}\n{conflict_lines}")
+    if code_rules_report:
+        reason_sections.append(f"{CODE_RULES_SECTION_HEADER}\n{code_rules_report.strip()}")
+    if not reason_sections:
+        return None
+    return DENY_REASON_LEAD + "\n\n" + "\n\n".join(reason_sections)
+
+
+def _emit_deny_payload(output_stream: TextIO, reason: str) -> None:
+    """Write the PreToolUse deny payload to the provided stream.
+
+    Args:
+        output_stream: Writable text stream — production code passes
+            ``sys.stdout``; tests pass a ``StringIO`` to capture the JSON.
+        reason: The ``permissionDecisionReason`` text for the deny payload.
+    """
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+    log_hook_block(
+        calling_hook_name="code_verifier_spawn_preflight_gate.py",
+        hook_event="PreToolUse",
+        block_reason=reason,
+    )
+    output_stream.write(json.dumps(deny_payload) + "\n")
+    output_stream.flush()
+
+
+def _preflight_deny_reason(payload_by_field: dict[str, object]) -> str | None:
+    """Run both pre-flight checks and return a deny reason, or None to allow.
+
+    Args:
+        payload_by_field: The full PreToolUse hook payload, keyed by top-level
+            field name.
+
+    Returns:
+        The deny reason when a check fired, or None when both checks pass or
+        fail open.
+    """
+    working_directory = payload_by_field.get("cwd")
+    resolution = _resolve_repo_root_and_base(
+        working_directory if isinstance(working_directory, str) else None
+    )
+    if resolution is None:
+        return None
+    repo_root, merge_base_sha, base_ref = resolution
+    conflicting_files = _conflicting_files(repo_root, base_ref)
+    surface = _working_tree_added_lines_by_path(repo_root, merge_base_sha)
+    code_rules_report = None
+    if surface is not None:
+        file_paths, added_lines_by_path = surface
+        code_rules_report = _code_rules_report(repo_root, file_paths, added_lines_by_path)
+    return _build_deny_reason(conflicting_files, base_ref, code_rules_report)
+
+
+def main() -> None:
+    try:
+        hook_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+    if not isinstance(hook_payload, dict):
+        sys.exit(0)
+    if not _should_run(hook_payload):
+        sys.exit(0)
+    deny_reason = _preflight_deny_reason(hook_payload)
+    if deny_reason is not None:
+        _emit_deny_payload(sys.stdout, deny_reason)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/convergence_gate_blocker.py

@@ -14,6 +14,13 @@ import subprocess
 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.hook_block_logger import log_hook_block  # noqa: E402
+
+
 def _resolve_pr_number(command: str, cwd: str | None) -> int | None:
     direct_match = re.search(r"\bgh\s+pr\s+ready\s+(\d+)", command)
     if direct_match:
@@ -112,15 +119,22 @@ def main() -> None:
     if completed_process.returncode in (0, 2):
         sys.exit(0)
 
+    block_reason = (
+        "Convergence check failed — PR is not ready to mark ready:\n\n" + completed_process.stdout
+    )
     deny_payload = {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
-            "permissionDecisionReason": (
-                "Convergence check failed — PR is not ready to mark ready:\n\n" + completed_process.stdout
-            ),
+            "permissionDecisionReason": block_reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="convergence_gate_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=block_reason,
+        tool_name="Bash",
+    )
     print(json.dumps(deny_payload))
     sys.stdout.flush()
     sys.exit(0)

package/hooks/blocking/destructive_command_blocker.py

@@ -19,6 +19,7 @@ from hooks_constants.convergence_branch_constants import (  # noqa: E402
     CONVERGENCE_BRANCH_SUFFIX_PATTERN,
     CONVERGENCE_FORCE_PUSH_DETECTION_PATTERN,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.destructive_command_segment_constants import (  # noqa: E402
     ALL_BENIGN_COMPOUND_SEGMENT_COMMANDS,
     ALL_COMMAND_LAUNCHER_WRAPPER_COMMANDS,
@@ -197,6 +198,12 @@ def _build_silent_gh_deny_response(matched_description: str) -> dict:
         "Bash call prevents duplicate execution."
     )
     _append_destructive_gate_log_entry(brief_label, full_reason)
+    log_hook_block(
+        calling_hook_name="destructive_command_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=full_reason,
+        tool_name="Bash",
+    )
     return {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",