claude-dev-env 2.3.0 → 2.5.0

package/hooks/blocking/orchestrator_refresh_reschedule_gate.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""PreToolUse gate: deny orchestrator-refresh re-arm when the run is not active.
+
+Fires on ``ScheduleWakeup`` and ``CronCreate`` when the prompt targets
+``/orchestrator-refresh``. Uses the same status-file gate as
+``skills/orchestrator/scripts/status_gate.py`` so idle loops
+cannot be re-armed on the Claude host without an active status file.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Mapping
+
+_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
+from hooks_constants.orchestrator_refresh_reschedule_gate_constants import (  # noqa: E402
+    ALL_HOME_SKILLS_RELATIVE_PARTS,
+    ALL_SCHEDULE_TOOL_NAMES,
+    ALL_SKILL_SCRIPTS_RELATIVE_PARTS,
+    CALLING_HOOK_NAME,
+    CRON_CREATE_TOOL_NAME,
+    CWD_FIELD_NAME,
+    DENY_REASON_TEMPLATE,
+    HOOK_EVENT_NAME,
+    ORCHESTRATOR_REFRESH_PROMPT_TOKEN,
+    PLUGIN_ROOT_ENV_VAR,
+    PROMPT_FIELD_NAME,
+    REASON_CRON_CREATE_FORBIDDEN,
+    RUN_SLUG_PROMPT_FLAG,
+    RUN_SLUG_PROMPT_VALUE_PATTERN,
+    TOOL_INPUT_FIELD_NAME,
+    TOOL_NAME_FIELD_NAME,
+)
+
+
+def _candidate_skill_script_directories() -> list[Path]:
+    """Return ordered paths that may contain status_gate.py.
+
+    Returns:
+        Absolute candidate directories in preference order.
+    """
+    all_candidates: list[Path] = []
+    plugin_root = os.environ.get(PLUGIN_ROOT_ENV_VAR)
+    if plugin_root:
+        all_candidates.append(
+            Path(plugin_root).joinpath(*ALL_SKILL_SCRIPTS_RELATIVE_PARTS)
+        )
+    package_hooks_parent = Path(__file__).resolve().parents[2]
+    all_candidates.append(
+        package_hooks_parent.joinpath(*ALL_SKILL_SCRIPTS_RELATIVE_PARTS)
+    )
+    all_candidates.append(Path.home().joinpath(*ALL_HOME_SKILLS_RELATIVE_PARTS))
+    return all_candidates
+
+
+def _load_status_gate_module() -> ModuleType | None:
+    """Import status_gate from the skill scripts package.
+
+    Returns:
+        The loaded module, or None when no candidate path is usable.
+    """
+    for each_directory in _candidate_skill_script_directories():
+        module_path = each_directory / "status_gate.py"
+        if not module_path.is_file():
+            continue
+        scripts_directory = str(each_directory)
+        if scripts_directory not in sys.path:
+            sys.path.insert(0, scripts_directory)
+        spec = importlib.util.spec_from_file_location(
+            "orchestrator_status_gate_for_reschedule_hook",
+            module_path,
+        )
+        if spec is None or spec.loader is None:
+            continue
+        status_gate_module = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = status_gate_module
+        spec.loader.exec_module(status_gate_module)
+        return status_gate_module
+    return None
+
+
+def _prompt_targets_orchestrator_refresh(
+    all_tool_input: Mapping[str, object],
+) -> bool:
+    """Return True when the schedule prompt re-enters orchestrator-refresh.
+
+    Args:
+        all_tool_input: PreToolUse tool_input mapping.
+
+    Returns:
+        True when the prompt field contains the refresh skill token.
+    """
+    prompt_value = all_tool_input.get(PROMPT_FIELD_NAME, "")
+    if not isinstance(prompt_value, str):
+        return False
+    stripped_prompt = prompt_value.lstrip()
+    if not stripped_prompt.startswith(ORCHESTRATOR_REFRESH_PROMPT_TOKEN):
+        return False
+    if len(stripped_prompt) == len(ORCHESTRATOR_REFRESH_PROMPT_TOKEN):
+        return True
+    return stripped_prompt[len(ORCHESTRATOR_REFRESH_PROMPT_TOKEN)] in (" ", "\n", "\t")
+
+
+def _should_evaluate(all_payload_by_field: Mapping[str, object]) -> bool:
+    """Return True for schedule tools re-arming orchestrator-refresh.
+
+    Args:
+        all_payload_by_field: Full PreToolUse payload.
+
+    Returns:
+        True when this gate must run.
+    """
+    tool_name = all_payload_by_field.get(TOOL_NAME_FIELD_NAME, "")
+    if tool_name not in ALL_SCHEDULE_TOOL_NAMES:
+        return False
+    tool_input = all_payload_by_field.get(TOOL_INPUT_FIELD_NAME, {})
+    if not isinstance(tool_input, dict):
+        return False
+    return _prompt_targets_orchestrator_refresh(tool_input)
+
+
+def _run_slug_from_prompt(prompt_value: str) -> str:
+    """Extract ``--run-slug`` from a ScheduleWakeup prompt when present.
+
+    Args:
+        prompt_value: The schedule tool prompt text.
+
+    Returns:
+        The slug string, or empty when the flag is absent.
+    """
+    run_slug_from_prompt_pattern = re.compile(
+        re.escape(RUN_SLUG_PROMPT_FLAG) + RUN_SLUG_PROMPT_VALUE_PATTERN
+    )
+    matched = run_slug_from_prompt_pattern.search(prompt_value)
+    if matched is None:
+        return ""
+    return matched.group(1)
+
+
+def _resolve_status_file_path(
+    status_gate_module: ModuleType,
+    all_payload_by_field: Mapping[str, object],
+) -> Path:
+    """Resolve the run status file for this schedule attempt without chdir.
+
+    Args:
+        status_gate_module: Loaded status_gate module.
+        all_payload_by_field: PreToolUse payload (may carry cwd and prompt).
+
+    Returns:
+        Absolute status file path.
+    """
+    base_directory: Path | None = None
+    working_directory_value = all_payload_by_field.get(CWD_FIELD_NAME)
+    if isinstance(working_directory_value, str) and working_directory_value:
+        base_directory = Path(working_directory_value)
+    run_slug = ""
+    tool_input = all_payload_by_field.get(TOOL_INPUT_FIELD_NAME, {})
+    if isinstance(tool_input, dict):
+        prompt_value = tool_input.get(PROMPT_FIELD_NAME, "")
+        if isinstance(prompt_value, str):
+            run_slug = _run_slug_from_prompt(prompt_value)
+    return status_gate_module.resolve_status_file_path(
+        None, base_directory, run_slug
+    )
+
+
+def build_denial_response(reason_code: str) -> dict[str, dict[str, str]]:
+    """Build the PreToolUse deny payload.
+
+    Args:
+        reason_code: Machine reason from decide_should_reschedule.
+
+    Returns:
+        Hook-specific deny JSON structure.
+    """
+    denial_reason = DENY_REASON_TEMPLATE.format(reason=reason_code)
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": "deny",
+            "permissionDecisionReason": denial_reason,
+        }
+    }
+
+
+def _emit_denial(
+    reason_code: str,
+    all_payload_by_field: Mapping[str, object],
+) -> None:
+    """Log and print a deny decision for the current schedule attempt.
+
+    Args:
+        reason_code: Machine reason string.
+        all_payload_by_field: PreToolUse payload for logging context.
+    """
+    denial = build_denial_response(reason_code)
+    hook_specific_output = denial["hookSpecificOutput"]
+    block_reason = hook_specific_output["permissionDecisionReason"]
+    log_hook_block(
+        calling_hook_name=CALLING_HOOK_NAME,
+        hook_event=HOOK_EVENT_NAME,
+        block_reason=block_reason,
+        tool_name=str(all_payload_by_field.get(TOOL_NAME_FIELD_NAME, "")),
+        offending_input_preview=str(
+            all_payload_by_field.get(TOOL_INPUT_FIELD_NAME, {})
+        ),
+    )
+    print(json.dumps(denial))
+
+
+def main() -> None:
+    """Read PreToolUse stdin and deny idle orchestrator-refresh re-arms."""
+    try:
+        payload_by_field = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if not isinstance(payload_by_field, dict):
+        sys.exit(0)
+    if not _should_evaluate(payload_by_field):
+        sys.exit(0)
+
+    tool_name = payload_by_field.get(TOOL_NAME_FIELD_NAME, "")
+    if tool_name == CRON_CREATE_TOOL_NAME:
+        _emit_denial(REASON_CRON_CREATE_FORBIDDEN, payload_by_field)
+        sys.exit(0)
+
+    status_gate_module = _load_status_gate_module()
+    if status_gate_module is None:
+        _emit_denial("status_gate_unavailable", payload_by_field)
+        sys.exit(0)
+
+    status_file_path = _resolve_status_file_path(status_gate_module, payload_by_field)
+    is_reschedule_allowed, reason_code = status_gate_module.decide_should_reschedule(
+        status_file_path
+    )
+    if is_reschedule_allowed:
+        sys.exit(0)
+
+    _emit_denial(reason_code, payload_by_field)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/pr_description_proof_of_work.py

@@ -20,10 +20,11 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
-from blocking.pr_description_body_audit import _iter_section_headers  # noqa: E402
-from blocking.pr_description_pr_number import (  # noqa: E402
-    _extract_pr_number_from_command,
+from blocking.convergence_gate_blocker import (  # noqa: E402
+    _repo_flag_arguments,
+    _resolve_named_identity,
 )
+from blocking.pr_description_body_audit import _iter_section_headers  # noqa: E402
 from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
     BULLET_MARKER_PATTERN,
     FENCED_CODE_BLOCK_PATTERN,
@@ -32,7 +33,6 @@ from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
 from hooks_constants.pr_description_proof_of_work_constants import (  # noqa: E402
     ALL_HONEST_GAP_PHRASES,
     ALL_PR_DIFF_SUBCOMMANDS,
-    ALL_PR_VIEW_NUMBER_ARGUMENTS,
     ALL_PROOF_HEADING_KEYWORDS,
     ALL_VISUAL_FILE_SUFFIXES,
     COMMENT_BODY_JSON_FIELD,
@@ -49,7 +49,6 @@ from hooks_constants.pr_description_proof_of_work_constants import (  # noqa: E4
     PLAN_LINKAGE_KEYWORD_PATTERN,
     PR_COMMENTS_API_PATH_TEMPLATE,
     PR_DIFF_NAME_ONLY_FLAG,
-    PR_NUMBER_JSON_FIELD,
     PR_READY_GATE_MESSAGE_TEMPLATE,
     PR_READY_INVOCATION_PATTERN,
     PR_READY_UNDO_FLAG,
@@ -112,13 +111,18 @@ def audit_proof_comment_body(body: str, pr_number: int | None) -> list[str]:
         an honest-gaps statement, and (when the PR diff is visual) an
         image embed.
     """
-    is_visual_change = _detect_visual_change(pr_number)
+    is_visual_change = _detect_visual_change(pr_number, None)
     return _missing_proof_parts(body, is_visual_change)
 
 
 def evaluate_pr_ready_gate(command: str) -> str | None:
     """Decide whether a gh pr ready command may proceed.
 
+    Every gh read the gate runs binds to the repository the command names —
+    a full PR URL or a ``--repo``/``-R`` flag — so a command targeting one
+    repository from a working tree checked out to another audits the named
+    repository's PR, not the working tree's.
+
     Args:
         command: The raw shell command captured by the hook.
 
@@ -127,15 +131,14 @@ def evaluate_pr_ready_gate(command: str) -> str | None:
         carries no passing proof comment, or None when a passing proof
         comment exists or any gh query fails.
     """
-    resolved_pr_number = _extract_pr_number_from_command(command)
-    if resolved_pr_number is None:
-        resolved_pr_number = _resolve_current_pr_number()
-    if resolved_pr_number is None:
+    target_identity = _resolve_named_identity(command, None)
+    if target_identity is None:
         return None
-    all_comment_bodies = _fetch_pr_comment_bodies(resolved_pr_number)
+    all_target_repo, resolved_pr_number = target_identity
+    all_comment_bodies = _fetch_pr_comment_bodies(resolved_pr_number, all_target_repo)
     if all_comment_bodies is None:
         return None
-    is_visual_change = _detect_visual_change(resolved_pr_number)
+    is_visual_change = _detect_visual_change(resolved_pr_number, all_target_repo)
     for each_body in all_comment_bodies:
         if not is_proof_shaped_body(each_body):
             continue
@@ -173,29 +176,30 @@ def _run_gh_command(all_gh_arguments: list[str]) -> str | None:
     return completed_process.stdout
 
 
-def _resolve_current_pr_number() -> int | None:
-    """Resolve the PR number of the current branch's open PR.
+def _build_comments_api_path(pr_number: int, all_target_repo: tuple[str, str] | None) -> str:
+    """Build the issues-comments API path for the named repository's PR.
+
+    Args:
+        pr_number: The PR number whose comments to read.
+        all_target_repo: The (owner, repo) pair the command names, or None to
+            leave gh's ``{owner}``/``{repo}`` placeholders for gh to expand
+            from the current directory's repository.
 
     Returns:
-        The PR number from ``gh pr view``, or None when no PR resolves or
-        gh fails.
+        The ``repos/<owner>/<repo>/issues/<pr_number>/comments`` path with
+        the named owner and repo filled in, or the placeholder form when no
+        repository is named.
     """
-    view_stdout = _run_gh_command(list(ALL_PR_VIEW_NUMBER_ARGUMENTS))
-    if view_stdout is None:
-        return None
-    try:
-        view_record = json.loads(view_stdout)
-    except json.JSONDecodeError:
-        return None
-    if not isinstance(view_record, dict):
-        return None
-    resolved_number = view_record.get(PR_NUMBER_JSON_FIELD)
-    if isinstance(resolved_number, int):
-        return resolved_number
-    return None
+    comments_api_path = PR_COMMENTS_API_PATH_TEMPLATE.format(pr_number=pr_number)
+    if all_target_repo is None:
+        return comments_api_path
+    owner, repo = all_target_repo
+    return comments_api_path.format(owner=owner, repo=repo)
 
 
-def _fetch_pr_comment_bodies(pr_number: int) -> list[str] | None:
+def _fetch_pr_comment_bodies(
+    pr_number: int, all_target_repo: tuple[str, str] | None
+) -> list[str] | None:
     """Read every comment body on a PR through the paginated issues API.
 
     The query runs ``gh api --paginate --slurp`` so every page lands in one
@@ -204,13 +208,15 @@ def _fetch_pr_comment_bodies(pr_number: int) -> list[str] | None:
 
     Args:
         pr_number: The PR number whose comments to read.
+        all_target_repo: The (owner, repo) pair the command names, or None to
+            read the current directory's repository.
 
     Returns:
         The comment bodies across all pages, or None when gh fails or the
         output is not the slurped page-array shape — the caller fails open
         on None.
     """
-    comments_api_path = PR_COMMENTS_API_PATH_TEMPLATE.format(pr_number=pr_number)
+    comments_api_path = _build_comments_api_path(pr_number, all_target_repo)
     api_stdout = _run_gh_command(
         [GH_API_SUBCOMMAND, comments_api_path, GH_PAGINATE_FLAG, GH_SLURP_FLAG]
     )
@@ -232,7 +238,9 @@ def _fetch_pr_comment_bodies(pr_number: int) -> list[str] | None:
     return all_comment_bodies
 
 
-def _detect_visual_change(pr_number: int | None) -> bool:
+def _detect_visual_change(
+    pr_number: int | None, all_target_repo: tuple[str, str] | None
+) -> bool:
     """Decide whether the PR diff carries visual work.
 
     A diff is visual when a changed file carries an image, HTML, or
@@ -242,21 +250,31 @@ def _detect_visual_change(pr_number: int | None) -> bool:
     Args:
         pr_number: The PR number to diff, or None to diff the current
             branch's PR.
+        all_target_repo: The (owner, repo) pair the command names, or None to
+            diff the current directory's repository.
 
     Returns:
         True when the diff is visual; False when it is not or when any gh
         query fails — an unknowable diff never adds the visual requirement.
     """
     all_number_arguments = [str(pr_number)] if pr_number is not None else []
+    all_repo_arguments = _repo_flag_arguments(all_target_repo)
     name_only_stdout = _run_gh_command(
-        [*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments, PR_DIFF_NAME_ONLY_FLAG]
+        [
+            *ALL_PR_DIFF_SUBCOMMANDS,
+            *all_number_arguments,
+            *all_repo_arguments,
+            PR_DIFF_NAME_ONLY_FLAG,
+        ]
     )
     if name_only_stdout is None:
         return False
     for each_changed_path in name_only_stdout.splitlines():
         if Path(each_changed_path.strip()).suffix.lower() in ALL_VISUAL_FILE_SUFFIXES:
             return True
-    diff_stdout = _run_gh_command([*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments])
+    diff_stdout = _run_gh_command(
+        [*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments, *all_repo_arguments]
+    )
     if diff_stdout is None:
         return False
     return HEX_COLOR_ADDED_LINE_PATTERN.search(diff_stdout[:MAX_DIFF_SCAN_CHARS]) is not None

package/hooks/blocking/pre_tool_use_dispatcher.py

@@ -7,10 +7,10 @@ declared in the constants module, aggregates the results, and emits one deny
 decision when any hook denied (carrying every denying reason) or exits zero to
 allow.
 
-The per-hook coverage matrix:
-- Write  -> 20 hooks from ALL_HOSTED_HOOK_ENTRIES that list Write
-- Edit   -> 21 hooks from ALL_HOSTED_HOOK_ENTRIES that list Edit
-- MultiEdit -> 9 hooks from ALL_HOSTED_HOOK_ENTRIES that list MultiEdit
+Each tool runs the ``ALL_HOSTED_HOOK_ENTRIES`` whose ``applicable_tool_names``
+list that tool; that roster is the live source of the per-tool coverage, and the
+dispatcher roster tests in ``test_pre_tool_use_dispatcher.py`` assert the counts,
+rather than a hardcoded matrix here that would drift as hooks are added.
 """
 
 from __future__ import annotations
@@ -24,20 +24,18 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from pathlib import Path
 
-_hooks_directory = str(Path(__file__).resolve().parent.parent)
-if _hooks_directory not in sys.path:
-    sys.path.insert(0, _hooks_directory)
+import _path_setup  # noqa: F401
 
-from plain_language_blocker import (  # noqa: E402
+from plain_language_blocker import (
     build_deny_payload as build_plain_language_deny_payload,
 )
-from plain_language_blocker import evaluate as evaluate_plain_language  # noqa: E402
-from state_description_blocker import (  # noqa: E402
+from plain_language_blocker import evaluate as evaluate_plain_language
+from state_description_blocker import (
     build_deny_payload as build_state_description_deny_payload,
 )
-from state_description_blocker import evaluate as evaluate_state_description  # noqa: E402
+from state_description_blocker import evaluate as evaluate_state_description
 
-from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: E402
+from hooks_constants.pre_tool_use_dispatcher_constants import (
     ALL_HOSTED_HOOK_ENTRIES,
     ALLOW_DECISION,
     BLOCKING_CRASH_DENY_REASON,
@@ -49,7 +47,7 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: E402
     STATE_DESCRIPTION_BLOCKER_MODULE_NAME,
     HostedHookEntry,
 )
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 
 NativeEvaluator = Callable[[dict[str, object]], str | None]
 DenyPayloadBuilder = Callable[[str], dict[str, object]]
@@ -70,6 +68,18 @@ class NativeHook:
     build_deny_payload: DenyPayloadBuilder
 
 
+_native_hook_by_module_name: dict[str, NativeHook] = {
+    STATE_DESCRIPTION_BLOCKER_MODULE_NAME: NativeHook(
+        evaluate=evaluate_state_description,
+        build_deny_payload=build_state_description_deny_payload,
+    ),
+    PLAIN_LANGUAGE_BLOCKER_MODULE_NAME: NativeHook(
+        evaluate=evaluate_plain_language,
+        build_deny_payload=build_plain_language_deny_payload,
+    ),
+}
+
+
 @dataclass
 class HostedHookResult:
     """Outcome of running one hosted hook inside the dispatcher process.
@@ -477,17 +487,7 @@ def _run_one_hosted_hook(
         The HostedHookResult for this hook's run.
     """
     if each_entry.native_module_name is not None:
-        native_hook_by_module_name: dict[str, NativeHook] = {
-            STATE_DESCRIPTION_BLOCKER_MODULE_NAME: NativeHook(
-                evaluate=evaluate_state_description,
-                build_deny_payload=build_state_description_deny_payload,
-            ),
-            PLAIN_LANGUAGE_BLOCKER_MODULE_NAME: NativeHook(
-                evaluate=evaluate_plain_language,
-                build_deny_payload=build_plain_language_deny_payload,
-            ),
-        }
-        native_hook = native_hook_by_module_name[each_entry.native_module_name]
+        native_hook = _native_hook_by_module_name[each_entry.native_module_name]
         return run_native_hook(native_hook, payload_by_key, each_entry.is_blocking)
     script_path = _resolve_hook_script_path(each_entry.script_relative_path)
     return run_hosted_hook(script_path, payload_text, each_entry.is_blocking)

package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py

@@ -213,7 +213,7 @@ def test_additional_context_is_collected_from_deciding_hooks() -> None:
 
 
 def test_powershell_selects_the_three_shared_hooks() -> None:
-    """Selecting for PowerShell yields the three shared hooks in registration order."""
+    """Selecting for PowerShell yields the shared hooks in registration order."""
     powershell_paths = [
         each_entry.script_relative_path
         for each_entry in select_applicable_entries(POWERSHELL_TOOL_NAME)
@@ -222,6 +222,9 @@ def test_powershell_selects_the_three_shared_hooks() -> None:
         "blocking/pii_prevention_blocker.py",
         "blocking/verified_commit_gate.py",
         "blocking/verdict_directory_write_blocker.py",
+        "blocking/code_review_push_gate.py",
+        "blocking/code_review_pr_create_gate.py",
+        "blocking/code_review_stamp_directory_write_blocker.py",
     ]
 
 

package/hooks/blocking/test_code_review_enforcement_config_bootstrap.py

@@ -0,0 +1,62 @@
+"""Regression tests for the code-review enforcement constants bootstrap.
+
+These prove the shared constants module resolves to the sibling
+``config/code_review_enforcement_constants.py`` file even when a foreign
+``config`` package sits ahead of ``blocking`` on ``sys.path``, and that a
+registration a caller placed first is left untouched.
+"""
+
+import subprocess
+from collections.abc import Callable
+
+RunUnderConfigShadow = Callable[[str], subprocess.CompletedProcess[str]]
+
+
+def test_register_binds_dotted_name_to_sibling_constants_file(
+    run_under_config_shadow: RunUnderConfigShadow,
+) -> None:
+    completed_probe = run_under_config_shadow(
+        "import code_review_enforcement_config_bootstrap as bootstrap\n"
+        "bootstrap.register_code_review_enforcement_constants()\n"
+        "import config.code_review_enforcement_constants as loaded\n"
+        "print(loaded.__file__)\n"
+        "print(loaded.STAMP_DIRECTORY_NAME)\n"
+    )
+    assert completed_probe.returncode == 0, completed_probe.stderr
+    assert "IS_DECOY_CONFIG" not in completed_probe.stdout
+    resolved_file_line, stamp_directory_line = completed_probe.stdout.splitlines()[:2]
+    assert resolved_file_line.replace("\\", "/").endswith(
+        "blocking/config/code_review_enforcement_constants.py"
+    )
+    assert stamp_directory_line == "code-review-stamps"
+
+
+def test_register_binds_push_required_effort(
+    run_under_config_shadow: RunUnderConfigShadow,
+) -> None:
+    completed_probe = run_under_config_shadow(
+        "import code_review_enforcement_config_bootstrap as bootstrap\n"
+        "bootstrap.register_code_review_enforcement_constants()\n"
+        "import config.code_review_enforcement_constants as loaded\n"
+        "print(loaded.PUSH_REQUIRED_EFFORT)\n"
+    )
+    assert completed_probe.returncode == 0, completed_probe.stderr
+    assert completed_probe.stdout.strip().splitlines()[-1] == "low"
+
+
+def test_register_leaves_an_already_cached_module_untouched(
+    run_under_config_shadow: RunUnderConfigShadow,
+) -> None:
+    completed_probe = run_under_config_shadow(
+        "import sys\n"
+        "import types\n"
+        "sentinel = types.ModuleType('config.code_review_enforcement_constants')\n"
+        "sentinel.ORIGIN = 'caller-seeded'\n"
+        "sys.modules['config.code_review_enforcement_constants'] = sentinel\n"
+        "import code_review_enforcement_config_bootstrap as bootstrap\n"
+        "bootstrap.register_code_review_enforcement_constants()\n"
+        "import config.code_review_enforcement_constants as loaded\n"
+        "print(getattr(loaded, 'ORIGIN', 'displaced'))\n"
+    )
+    assert completed_probe.returncode == 0, completed_probe.stderr
+    assert completed_probe.stdout.strip().splitlines()[-1] == "caller-seeded"

package/hooks/blocking/test_code_review_gate_deny.py

@@ -0,0 +1,54 @@
+"""Behavioral tests for the shared code-review gate deny scaffold.
+
+The tests drive the two shared helpers directly: the payload builder's shape and
+the log-and-emit helper's stdout, so both code-review gates inherit one verified
+deny path.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_HOOK_DIR = Path(__file__).resolve().parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+
+def _load_module(module_name: str) -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        module_name, _HOOK_DIR / f"{module_name}.py"
+    )
+    assert module_spec is not None
+    assert module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+deny_module = _load_module("code_review_gate_deny")
+
+
+def test_build_payload_carries_reason_and_deny_decision() -> None:
+    deny_payload = deny_module.build_code_review_deny_payload("blocked reason")
+    hook_output = deny_payload["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert hook_output["permissionDecisionReason"] == "blocked reason"
+
+
+def test_log_and_emit_code_review_deny_writes_payload_to_stdout(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    deny_module.log_and_emit_code_review_deny("blocked reason", "Bash", "code_review_push_gate")
+    emitted_payload = json.loads(capsys.readouterr().out)
+    hook_output = emitted_payload["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert hook_output["permissionDecisionReason"] == "blocked reason"