claude-dev-env 1.38.0 → 1.39.0

package/hooks/blocking/convergence_gate_blocker.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block gh pr ready until convergence pre-conditions pass.
+
+Runs check_convergence.py against the PR and denies the gh pr ready
+call if any condition fails. The agent sees exactly which conditions
+failed and can address them before retrying.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+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:
+        return int(direct_match.group(1))
+    try:
+        completed_process = subprocess.run(
+            ["gh", "pr", "view", "--json", "number", "--jq", ".number"],
+            capture_output=True,
+            text=True,
+            cwd=cwd or None,
+            check=False,
+        )
+    except OSError:
+        return None
+    if completed_process.returncode != 0:
+        return None
+    try:
+        return int(completed_process.stdout.strip())
+    except (ValueError, TypeError):
+        return None
+
+
+def _resolve_owner_repo(cwd: str | None) -> tuple[str, str] | None:
+    try:
+        completed_process = subprocess.run(
+            ["gh", "repo", "view", "--json", "owner,name", "--jq", ".owner.login,.name"],
+            capture_output=True,
+            text=True,
+            cwd=cwd or None,
+            check=False,
+        )
+    except OSError:
+        return None
+    if completed_process.returncode != 0:
+        return None
+    parts = completed_process.stdout.strip().splitlines()
+    if len(parts) <= 1:
+        match = re.match(
+            r"https://github\.com/([^/]+)/([^/]+?)(?:\.git)?$",
+            completed_process.stdout.strip(),
+        )
+        if match:
+            return match.group(1), match.group(2)
+        return None
+    return parts[0], parts[1]
+
+
+def main() -> None:
+    check_convergence_script = str(
+        Path.home() / ".claude/skills/pr-converge/scripts/check_convergence.py"
+    )
+
+    if not Path(check_convergence_script).is_file():
+        sys.exit(0)
+
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name != "Bash":
+        sys.exit(0)
+
+    command = hook_input.get("tool_input", {}).get("command", "")
+    gh_pr_ready_pattern = re.compile(r"\bgh\s+pr\s+ready\b(?![^&|;\n]*--undo)")
+    if not gh_pr_ready_pattern.search(command):
+        sys.exit(0)
+
+    cwd = hook_input.get("tool_input", {}).get("cwd")
+    pr_number = _resolve_pr_number(command, cwd)
+    if pr_number is None:
+        sys.exit(0)
+
+    owner_repo = _resolve_owner_repo(cwd)
+    if owner_repo is None:
+        sys.exit(0)
+    owner, repo = owner_repo
+
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            check_convergence_script,
+            "--owner",
+            owner,
+            "--repo",
+            repo,
+            "--pr-number",
+            str(pr_number),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    if completed_process.returncode in (0, 2):
+        sys.exit(0)
+
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": (
+                "Convergence check failed — PR is not ready to mark ready:\n\n" + completed_process.stdout
+            ),
+        }
+    }
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/destructive_command_blocker.py

@@ -9,6 +9,16 @@ import sys
 import tempfile
 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 config.convergence_branch_constants import (  # noqa: E402
+    ALL_CONVERGENCE_BRANCH_PREFIXES,
+    CONVERGENCE_BRANCH_SUFFIX_PATTERN,
+    CONVERGENCE_FORCE_PUSH_DETECTION_PATTERN,
+)
+
 CLAUDE_DIRECTORY_PATH = os.path.normpath(os.path.expanduser("~/.claude"))
 GH_REDIRECT_ACTIVE_ENV_VAR = "CLAUDE_GH_REDIRECT_ACTIVE"
 GH_REDIRECT_ACTIVE_TRUTHY_VALUES = frozenset({"1", "true", "yes", "on"})
@@ -86,6 +96,9 @@ DESTRUCTIVE_BASH_PATTERNS = [
     (re.compile(r'\bDROP\s+TABLE\b', re.IGNORECASE), "DROP TABLE (destroys database table)"),
     (re.compile(r'\bDROP\s+DATABASE\b', re.IGNORECASE), "DROP DATABASE (destroys entire database)"),
     (re.compile(r'\bTRUNCATE\s+TABLE\b', re.IGNORECASE), "TRUNCATE TABLE (removes all table rows)"),
+    (re.compile(r'\bgit\s+(?:[^\s]+\s+)*--no-verify\b', re.IGNORECASE), "git --no-verify (skips pre-commit / pre-push hooks; NON-NEGOTIABLE per git-workflow.md)"),
+    (re.compile(r'\bgit\s+(?:[^\s]+\s+)*--no-gpg-sign\b', re.IGNORECASE), "git --no-gpg-sign (bypasses commit signing; NON-NEGOTIABLE per git-workflow.md)"),
+    (re.compile(r"\bgit\s+-c\s+['\"]?commit\.gpgsign=['\"]?false['\"]?(?!\w)", re.IGNORECASE), "git -c commit.gpgsign=false (bypasses commit signing; NON-NEGOTIABLE per git-workflow.md)"),
 ]
 
 def find_destructive_pattern(command: str) -> str | None:
@@ -483,6 +496,52 @@ def _git_reset_hard_allowed_for_command(command: str, current_working_directory:
     return False
 
 
+def _is_convergence_branch(branch: str) -> bool:
+    all_convergence_branch_prefixes = ALL_CONVERGENCE_BRANCH_PREFIXES
+    for each_prefix in all_convergence_branch_prefixes:
+        if branch.startswith(each_prefix):
+            return True
+    return bool(re.match(CONVERGENCE_BRANCH_SUFFIX_PATTERN, branch))
+
+
+def _all_refspecs_are_convergence_branches(post_remote_text: str) -> bool:
+    if not post_remote_text.strip():
+        return False
+    is_any_refspec_checked = False
+    for each_token in post_remote_text.split():
+        if each_token.startswith("-"):
+            continue
+        is_any_refspec_checked = True
+        destination_branch = each_token.split(":")[-1]
+        if not _is_convergence_branch(destination_branch):
+            return False
+    return is_any_refspec_checked
+
+
+def _force_push_targets_convergence_branch(command: str) -> bool:
+    convergence_force_push_detection_pattern = (
+        CONVERGENCE_FORCE_PUSH_DETECTION_PATTERN
+    )
+    is_force_push_found = False
+    for each_match in re.finditer(
+        convergence_force_push_detection_pattern, command, re.IGNORECASE
+    ):
+        is_force_push_found = True
+        post_push_text = each_match.group(1).strip()
+        all_tokens = post_push_text.split()
+        remote_index = 1 if all_tokens and all_tokens[0] in ("--force", "-f") else 0
+        all_refspec_tokens = [
+            token for token in all_tokens[remote_index + 1 :]
+            if token not in ("--force", "-f")
+        ]
+        post_remote_text = " ".join(all_refspec_tokens)
+        if not post_remote_text:
+            return False
+        if not _all_refspecs_are_convergence_branches(post_remote_text):
+            return False
+    return is_force_push_found
+
+
 def main() -> None:
     try:
         hook_input = json.load(sys.stdin)
@@ -524,6 +583,21 @@ def main() -> None:
         if _git_reset_hard_allowed_for_command(command, os.getcwd()):
             sys.exit(0)
 
+    if (
+        matched_description is not None
+        and "git push" in matched_description
+        and ("force" in matched_description or "-f" in matched_description)
+        and _force_push_targets_convergence_branch(command)
+    ):
+        for each_pattern, each_description in DESTRUCTIVE_BASH_PATTERNS:
+            if "git push" in each_description and ("force" in each_description or "-f" in each_description):
+                continue
+            if each_pattern.search(command):
+                matched_description = each_description
+                break
+        else:
+            sys.exit(0)
+
     if matched_description is not None:
         ask_response = {
             "hookSpecificOutput": {

package/hooks/blocking/gh_body_arg_blocker.py

@@ -24,6 +24,7 @@ import re
 import sys
 
 from _gh_body_arg_utils import (
+    _is_bash_continuation,
     all_body_flags,
     all_body_flag_prefixes,
     get_logical_first_line,
@@ -69,6 +70,32 @@ def _logical_line_has_bare_body_token(logical_line: str) -> bool:
     return bool(_BARE_BODY_TOKEN_PATTERN.search(logical_line))
 
 
+def _has_backtick(command: str) -> bool:
+    """Return True if command contains a backtick that is not a bash continuation.
+
+    Joins all bash `` \\ `` continuation lines so backticks in multi-line body
+    values on later non-continuation lines are not missed. Only strips bash
+    continuations — this hook runs on the Bash tool, and PowerShell-style
+    backtick continuations are not continuation markers in bash.
+
+    Scans the entire command string for backtick characters, not just --body
+    argument content. This is intentionally conservative — any command
+    containing backticks should use --body-file regardless of where they
+    appear. False positives (backticks in non-body flags) are safe
+    over-blocks.
+    """
+    continuation_separator = " "
+    all_joined_lines: list[str] = []
+    for each_line in command.splitlines():
+        stripped_line = each_line.rstrip()
+        if _is_bash_continuation(stripped_line):
+            all_joined_lines.append(stripped_line[:-1].rstrip() + continuation_separator)
+            continue
+        all_joined_lines.append(each_line)
+    full_logical_command = "".join(all_joined_lines)
+    return "`" in full_logical_command
+
+
 def _uses_body_string_arg(command: str) -> bool:
     """Return True if command calls an affected gh subcommand with --body <string>.
 
@@ -114,6 +141,9 @@ def main() -> None:
     if not _uses_body_string_arg(command):
         sys.exit(0)
 
+    if not _has_backtick(command):
+        sys.exit(0)
+
     deny_payload = {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",

package/hooks/blocking/md_to_html_blocker.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: blocks Write/Edit targeting .md files, redirecting to .html.
+
+HTML preserves spatial structure (diffs, timelines, comparisons, diagrams)
+that markdown flattens. See https://thariqs.github.io/html-effectiveness/
+"""
+
+import json
+import os
+import sys
+from typing import TextIO
+
+
+_markdown_extension = ".md"
+_html_effectiveness_url = "https://thariqs.github.io/html-effectiveness/"
+_exempt_root_filenames = ("readme.md", "changelog.md")
+
+
+def _is_exempt_path(file_path: str) -> bool:
+    normalized = os.path.normpath(file_path).replace("\\", "/")
+    lower_normalized = normalized.lower()
+    if "/.claude/" in lower_normalized or lower_normalized.startswith(".claude/"):
+        return True
+    basename = os.path.basename(normalized)
+    if basename.lower() in _exempt_root_filenames:
+        directory = os.path.dirname(normalized)
+        if directory in ("", "."):
+            return True
+    return False
+
+
+def _block_reason(file_path: str) -> str:
+    return (
+        f"BLOCKED: Write/Edit to .md file '{file_path}' is not permitted. "
+        "Use .html files instead for documentation. "
+        f"See {_html_effectiveness_url} for why HTML "
+        "is more effective than Markdown for structured information."
+    )
+
+
+def _block_context() -> str:
+    return (
+        "Generate a self-contained .html file instead of .md. "
+        "Design freely — HTML can express spatial structure, interactivity, "
+        "and visual hierarchy that markdown cannot.\n\n"
+        "Reference for HTML effectiveness patterns:\n"
+        f"{_html_effectiveness_url}\n"
+        "Exceptions (.md still allowed):\n"
+        "- Files inside .claude/ directories\n"
+        "- README.md and CHANGELOG.md at repo root"
+    )
+
+
+def _block_system_message() -> str:
+    return (
+        ".md files are blocked in this project — generate a self-contained .html "
+        f"file instead. See {_html_effectiveness_url} for "
+        "design patterns and examples. Exemptions: .claude/ infrastructure, "
+        "README.md, CHANGELOG.md at repo root."
+    )
+
+
+def main() -> None:
+    """Read hook input JSON from stdin, deny .md writes or pass through silently.
+
+    Returns:
+        None (exits process).
+    """
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if not isinstance(input_data, dict):
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    if not isinstance(tool_name, str):
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    if tool_name not in ("Write", "Edit"):
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        sys.exit(0)
+
+    if not file_path.lower().endswith(_markdown_extension):
+        sys.exit(0)
+
+    if _is_exempt_path(file_path):
+        sys.exit(0)
+
+    block_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": _block_reason(file_path),
+            "additionalContext": _block_context(),
+        },
+        "systemMessage": _block_system_message(),
+        "suppressOutput": True,
+    }
+
+    _emit_hook_result(block_payload, sys.stdout)
+    sys.exit(0)
+
+
+def _emit_hook_result(all_hook_data: dict, output_stream: TextIO) -> None:
+    output_stream.write(json.dumps(all_hook_data) + "\n")
+    output_stream.flush()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_bot_mention_comment_blocker.py

@@ -0,0 +1,131 @@
+"""Unit tests for bot-mention-comment-blocker PreToolUse hook."""
+
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+hook_spec = importlib.util.spec_from_file_location(
+    "bot_mention_comment_blocker",
+    _HOOK_DIR / "bot_mention_comment_blocker.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+_detect_bot_mention = hook_module._detect_bot_mention
+_body_contains_token = hook_module._body_contains_token
+
+from config.bot_mention_comment_blocker_constants import (
+    CORRECTIVE_MESSAGE_COPILOT,
+    CORRECTIVE_MESSAGE_CURSOR,
+    CURSOR_MENTION_TOKEN,
+)
+
+
+def test_passes_clean_body() -> None:
+    assert _detect_bot_mention("bugbot run") is None
+
+
+def test_passes_empty_body() -> None:
+    assert _detect_bot_mention("") is None
+
+
+def test_passes_unrelated_body() -> None:
+    assert _detect_bot_mention("please review this PR") is None
+
+
+def test_blocks_cursor_mention() -> None:
+    reason = _detect_bot_mention("@cursor bugbot run")
+    assert reason is not None
+    assert "bugbot run" in reason
+
+
+def test_blocks_cursor_bracket_mention() -> None:
+    reason = _detect_bot_mention("@cursor[bot] bugbot run")
+    assert reason is not None
+    assert "bugbot run" in reason
+
+
+def test_blocks_copilot_mention() -> None:
+    reason = _detect_bot_mention("@copilot review this")
+    assert reason is not None
+    assert "copilot-pull-request-reviewer" in reason
+
+
+def test_returns_cursor_message_for_cursor() -> None:
+    assert _detect_bot_mention("@cursor run") == CORRECTIVE_MESSAGE_CURSOR
+
+
+def test_returns_copilot_message_for_copilot() -> None:
+    assert _detect_bot_mention("@copilot help") == CORRECTIVE_MESSAGE_COPILOT
+
+
+def test_copilot_wins_when_both_present() -> None:
+    assert _detect_bot_mention("@cursor and @copilot") == CORRECTIVE_MESSAGE_COPILOT
+
+
+def test_body_contains_token_case_insensitive() -> None:
+    assert _body_contains_token("Hello @CURSOR world", "@cursor")
+    assert _body_contains_token("Hello @CoPilot world", "@copilot")
+
+
+def test_body_contains_token_no_at_sign() -> None:
+    assert not _body_contains_token("cursor without at-sign", CURSOR_MENTION_TOKEN)
+
+
+from unittest import mock
+
+
+def _run_main_with_io(input_text: str) -> str:
+    with mock.patch("sys.stdin", io.StringIO(input_text)):
+        with mock.patch("sys.stdout", new_callable=io.StringIO) as mock_stdout:
+            try:
+                hook_module.main()
+            except SystemExit:
+                pass
+            return mock_stdout.getvalue()
+
+
+def test_main_blocks_matching_cursor_comment() -> None:
+    hook_input = {
+        "tool_name": "mcp__plugin_github_github__add_issue_comment",
+        "tool_input": {"body": "@cursor bugbot run"},
+    }
+    output_text = _run_main_with_io(json.dumps(hook_input))
+    output = json.loads(output_text)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_main_passes_wrong_tool_name() -> None:
+    hook_input = {
+        "tool_name": "some_other_tool",
+        "tool_input": {"body": "@cursor bugbot run"},
+    }
+    assert _run_main_with_io(json.dumps(hook_input)) == ""
+
+
+def test_main_passes_empty_body() -> None:
+    hook_input = {
+        "tool_name": "mcp__plugin_github_github__add_issue_comment",
+        "tool_input": {"body": ""},
+    }
+    assert _run_main_with_io(json.dumps(hook_input)) == ""
+
+
+def test_main_passes_non_matching_body() -> None:
+    hook_input = {
+        "tool_name": "mcp__plugin_github_github__add_issue_comment",
+        "tool_input": {"body": "please review this PR"},
+    }
+    assert _run_main_with_io(json.dumps(hook_input)) == ""
+
+
+def test_main_passes_malformed_json() -> None:
+    assert _run_main_with_io("not valid json {{{") == ""

package/hooks/blocking/test_code_rules_enforcer.py

@@ -1192,3 +1192,24 @@ def test_sys_path_insert_should_skip_hook_infrastructure_files() -> None:
     assert issues == [], (
         f"Hook infrastructure files are exempt from this rule, got: {issues}"
     )
+
+
+def test_validate_content_honors_empty_full_file_content_for_thin_wrapper_check() -> None:
+    """An empty `full_file_content` must not be silently replaced with the pre-edit fragment.
+
+    Regression for loop1-8: the `or` short-circuit at the thin-wrapper call
+    site treated `""` identically to `None`, so an Edit collapsing a file to
+    empty was scanned against the pre-edit fragment instead of the empty
+    post-edit content. Mirror the canonical idiom at line 3438.
+    """
+    pre_edit_fragment_with_imports_only = (
+        "from real_module import do_thing\n__all__ = ['do_thing']\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        pre_edit_fragment_with_imports_only,
+        "/project/src/aliases.py",
+        full_file_content="",
+    )
+    assert not any("thin wrapper" in each.lower() for each in issues), (
+        f"empty post-edit file must not be flagged as a thin wrapper, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_any_exempt_files.py

@@ -0,0 +1,70 @@
+"""Tests for ANY_ALLOWED_PATTERNS exemption from check_type_escape_hatches.
+
+Per Plan 1b: __init__.py, protocols.py, types.py, conftest.py are exempt
+from the Any/cast checks because their primary purpose is type re-export
+or runtime protocol declaration.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+check_type_escape_hatches = code_rules_enforcer.check_type_escape_hatches
+
+ANY_USING_SOURCE = "from typing import Any\nx: Any = 1\n"
+
+
+def test_should_exempt_init_py() -> None:
+    issues = check_type_escape_hatches(ANY_USING_SOURCE, "/project/src/foo/__init__.py")
+    assert issues == [], f"__init__.py must be exempt, got: {issues!r}"
+
+
+def test_should_exempt_protocols_py() -> None:
+    issues = check_type_escape_hatches(ANY_USING_SOURCE, "/project/src/protocols.py")
+    assert issues == [], f"protocols.py must be exempt, got: {issues!r}"
+
+
+def test_should_exempt_types_py() -> None:
+    issues = check_type_escape_hatches(ANY_USING_SOURCE, "/project/src/types.py")
+    assert issues == [], f"types.py must be exempt, got: {issues!r}"
+
+
+def test_should_exempt_conftest_py() -> None:
+    issues = check_type_escape_hatches(ANY_USING_SOURCE, "/project/src/conftest.py")
+    assert issues == [], f"conftest.py must be exempt, got: {issues!r}"
+
+
+def test_should_still_flag_in_regular_module() -> None:
+    issues = check_type_escape_hatches(ANY_USING_SOURCE, "/project/src/models.py")
+    assert issues != [], (
+        f"Regular .py files must still be flagged for Any usage, got: {issues!r}"
+    )
+
+
+def test_any_type_config_module_exists_and_exposes_constant() -> None:
+    config_module_path = Path(__file__).parent.parent / "config" / "any_type_config.py"
+    assert config_module_path.is_file(), f"Missing: {config_module_path}"
+    spec = importlib.util.spec_from_file_location("any_type_config_under_test", config_module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(loaded_module)
+    allowed_patterns = loaded_module.ALL_ANY_ALLOWED_PATTERNS
+    assert isinstance(allowed_patterns, tuple)
+    assert "__init__.py" in allowed_patterns
+    assert "protocols.py" in allowed_patterns
+    assert "types.py" in allowed_patterns