claude-dev-env 1.59.0 → 1.60.0

package/hooks/blocking/code_rules_enforcer.py

@@ -54,11 +54,15 @@ from code_rules_constants_config import (  # noqa: E402
 from code_rules_dead_dataclass_field import (  # noqa: E402
     check_dead_dataclass_fields,
 )
+from code_rules_dead_module_constant import (  # noqa: E402
+    check_dead_module_constants,
+)
 from code_rules_docstrings import (  # noqa: E402
     check_docstring_args_match_signature,
     check_docstring_format,
 )
 from code_rules_duplicate_body import (  # noqa: E402
+    advise_cross_skill_duplicate_helper,
     check_duplicate_function_body_across_files,
 )
 from code_rules_imports_logging import (  # noqa: E402
@@ -120,6 +124,7 @@ from code_rules_typeddict_stub import (  # noqa: E402
     check_stub_implementations,
     check_thin_wrapper_files,
     check_typed_dict_encode_decode,
+    check_zero_payload_function_alias,
 )
 from code_rules_unused_imports import (  # noqa: E402
     check_unused_module_level_imports,
@@ -228,6 +233,7 @@ def validate_content(
         all_issues.extend(check_test_branching_in_production(effective_content, file_path))
         all_issues.extend(check_bare_except(effective_content, file_path))
         all_issues.extend(check_thin_wrapper_files(effective_content, file_path))
+        all_issues.extend(check_zero_payload_function_alias(effective_content, file_path))
         all_issues.extend(check_boundary_types(effective_content, file_path))
         all_issues.extend(check_docstring_format(effective_content, file_path))
         all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
@@ -269,6 +275,9 @@ def validate_content(
         all_issues.extend(
             check_dead_dataclass_fields(content, file_path, full_file_content)
         )
+        all_issues.extend(
+            check_dead_module_constants(content, file_path, full_file_content)
+        )
         all_issues.extend(check_library_print(content, file_path))
         all_issues.extend(check_parameter_annotations(content, file_path))
         all_issues.extend(check_known_pytest_fixture_annotations(content, file_path))
@@ -287,6 +296,7 @@ def validate_content(
         all_issues.extend(check_string_literal_magic(content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)
+        advise_cross_skill_duplicate_helper(effective_content, file_path)
 
     elif extension in ALL_JAVASCRIPT_EXTENSIONS:
         if not is_test_file(file_path):
@@ -383,18 +393,20 @@ def _is_hook_infrastructure_python_target(file_path: str) -> bool:
     return get_file_extension(file_path) in ALL_PYTHON_EXTENSIONS
 
 
-def _hook_infrastructure_duplicate_body_issues(
+def _hook_infrastructure_blocking_issues(
     content: str,
     file_path: str,
     full_file_content: str | None = None,
     prior_full_file_content: str = "",
 ) -> list[str]:
-    """Run only the cross-file duplicate-body check for a hook Python target.
+    """Run the checks that still guard a hook Python target.
 
     The whole code-rules verdict stays off hook-infrastructure files, so this
-    runs the single check that must still guard them, span-scoped to the lines
-    an edit touched exactly as ``validate_content`` scopes it for production
-    code.
+    runs the two checks that must still guard them: the cross-file duplicate-body
+    check, span-scoped to the lines an edit touched exactly as ``validate_content``
+    scopes it for production code; and the zero-payload alias check, whose
+    docstring names hook modules as its motivating case, run over the whole
+    post-edit file.
 
     Args:
         content: The fragment or whole-file body under validation.
@@ -405,7 +417,8 @@ def _hook_infrastructure_duplicate_body_issues(
             recover the changed lines on an Edit.
 
     Returns:
-        The in-scope duplicate-body violations for the target.
+        The in-scope duplicate-body violations and the zero-payload alias
+        violations for the target.
     """
     effective_content = content if full_file_content is None else full_file_content
     all_changed_lines = (
@@ -413,11 +426,13 @@ def _hook_infrastructure_duplicate_body_issues(
         if full_file_content is not None
         else None
     )
-    return check_duplicate_function_body_across_files(
+    all_issues = check_duplicate_function_body_across_files(
         effective_content,
         file_path,
         all_changed_lines,
     )
+    all_issues.extend(check_zero_payload_function_alias(effective_content, file_path))
+    return all_issues
 
 
 def _without_line_prefix(violation_text: str) -> str:
@@ -540,7 +555,7 @@ def _run_precheck(
         old_content = _read_existing_file_content(target_path) or ""
         all_issues = validate_content(candidate_content, target_path, old_content)
     else:
-        all_issues = _hook_infrastructure_duplicate_body_issues(
+        all_issues = _hook_infrastructure_blocking_issues(
             candidate_content, target_path
         )
     for each_issue in all_issues:
@@ -755,18 +770,18 @@ def _report_blocking_violations(
     )
 
 
-def _report_hook_duplicate_body(
+def _report_hook_blocking_issues(
     content: str,
     file_path: str,
     full_file_content_after_edit: str | None,
     prior_full_file_content: str,
     deny_stream: TextIO,
 ) -> None:
-    """Write a deny payload when a hook target copies a sibling function body.
+    """Write a deny payload when a hook target trips a check that still guards it.
 
-    The full code-rules verdict stays off hook-infrastructure files; this runs
-    the single duplicate-body check that must still guard them and emits the deny
-    payload when it fires.
+    The full code-rules verdict stays off hook-infrastructure files; this runs the
+    two checks that must still guard them — the cross-file duplicate-body check and
+    the zero-payload alias check — and emits the deny payload when either fires.
 
     Args:
         content: The fragment or whole-file body under validation.
@@ -776,7 +791,7 @@ def _report_hook_duplicate_body(
         prior_full_file_content: The on-disk content before the edit.
         deny_stream: The stream the JSON deny payload is written to.
     """
-    all_blocking_issues = _hook_infrastructure_duplicate_body_issues(
+    all_blocking_issues = _hook_infrastructure_blocking_issues(
         content,
         file_path,
         full_file_content_after_edit,
@@ -835,7 +850,7 @@ def main(all_arguments: list[str]) -> None:
         sys.exit(0)
 
     if not runs_full_verdict:
-        _report_hook_duplicate_body(
+        _report_hook_blocking_issues(
             content,
             file_path,
             full_file_content_after_edit,

package/hooks/blocking/code_rules_typeddict_stub.py

@@ -26,6 +26,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_STUB_IMPLEMENTATION_ISSUES,
     MAX_THIN_WRAPPER_ISSUES,
     MAX_TYPED_DICT_PAIR_ISSUES,
+    MAX_ZERO_PAYLOAD_ALIAS_ISSUES,
 )
 
 def _pascal_to_snake_case(pascal_name: str) -> str:
@@ -58,6 +59,16 @@ def _collect_module_function_names(parsed_tree: ast.AST) -> set[str]:
     return module_function_names
 
 
+def _collect_module_function_nodes_by_name(
+    parsed_tree: ast.AST,
+) -> dict[str, ast.FunctionDef | ast.AsyncFunctionDef]:
+    function_node_by_name: dict[str, ast.FunctionDef | ast.AsyncFunctionDef] = {}
+    for each_statement in parsed_tree.body:
+        if isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            function_node_by_name[each_statement.name] = each_statement
+    return function_node_by_name
+
+
 def _is_init_file(file_path: str) -> bool:
     return file_path.replace("\\", "/").rsplit("/", 1)[-1] == "__init__.py"
 
@@ -126,6 +137,167 @@ def check_thin_wrapper_files(content: str, file_path: str) -> list[str]:
     return issues[:MAX_THIN_WRAPPER_ISSUES]
 
 
+def _function_parameter_names_in_order(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[str]:
+    arguments = function_node.args
+    positional_arguments = [*arguments.posonlyargs, *arguments.args]
+    return [each_argument.arg for each_argument in positional_arguments]
+
+
+def _has_only_positional_parameters(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    arguments = function_node.args
+    has_no_parameter_defaults = not arguments.defaults and not arguments.kw_defaults
+    return (
+        not arguments.kwonlyargs
+        and arguments.vararg is None
+        and arguments.kwarg is None
+        and has_no_parameter_defaults
+    )
+
+
+def _single_return_call(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> ast.Call | None:
+    body_statements = function_node.body
+    statements_after_docstring = (
+        body_statements[1:]
+        if body_statements and _statement_is_docstring(body_statements[0])
+        else body_statements
+    )
+    if len(statements_after_docstring) != 1:
+        return None
+    only_statement = statements_after_docstring[0]
+    if not isinstance(only_statement, ast.Return):
+        return None
+    return only_statement.value if isinstance(only_statement.value, ast.Call) else None
+
+
+def _forwards_parameters_unchanged(call_node: ast.Call, all_parameter_names: list[str]) -> bool:
+    if call_node.keywords:
+        return False
+    if len(call_node.args) != len(all_parameter_names):
+        return False
+    for each_argument, each_parameter_name in zip(call_node.args, all_parameter_names):
+        if not isinstance(each_argument, ast.Name) or each_argument.id != each_parameter_name:
+            return False
+    return True
+
+
+def _function_is_async(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return isinstance(function_node, ast.AsyncFunctionDef)
+
+
+def _alias_target_name(call_node: ast.Call, all_sibling_function_names: set[str]) -> str:
+    callee = call_node.func
+    if not isinstance(callee, ast.Name):
+        return ""
+    return callee.id if callee.id in all_sibling_function_names else ""
+
+
+def _module_string_literal_values(parsed_tree: ast.AST) -> set[str]:
+    string_literal_values: set[str] = set()
+    for each_node in ast.walk(parsed_tree):
+        if isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            string_literal_values.add(each_node.value)
+    return string_literal_values
+
+
+def _target_accepts_forwarded_positional_call(
+    target_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    forwarded_argument_count: int,
+) -> bool:
+    arguments = target_node.args
+    if any(default is None for default in arguments.kw_defaults):
+        return False
+    positional_parameters = [*arguments.posonlyargs, *arguments.args]
+    total_positional_count = len(positional_parameters)
+    required_positional_count = total_positional_count - len(arguments.defaults)
+    if arguments.vararg is not None:
+        return forwarded_argument_count >= required_positional_count
+    return required_positional_count <= forwarded_argument_count <= total_positional_count
+
+
+def check_zero_payload_function_alias(content: str, file_path: str) -> list[str]:
+    """Flag a module-level function that only forwards its parameters to a sibling.
+
+    A function whose entire body (after an optional docstring) is a single
+    `return sibling_function(first_param, second_param, ...)` that forwards its
+    own parameters unchanged to another function defined in the same module is a
+    second name for one behavior — indirection without payload, which CODE_RULES
+    discourages. Callers should invoke the sibling directly. Both `def` and
+    `async def` forwarders are inspected.
+
+    A forwarder is left unflagged when any of these makes a direct call to the
+    target not equivalent to the alias: a decorator (caching, `@property`, route
+    registration); a parameter carrying a default value the target rejects; a
+    keyword-only / `*args` / `**kwargs` parameter on the alias; an awaitability
+    mismatch where one of the alias and target is `async def` and the other is
+    not; a forwarded positional call the live target's signature rejects (the
+    target has a keyword-only parameter without a default, or its positional
+    arity does not admit the forwarded argument count); or a name dispatched by a
+    string literal elsewhere in the module, where the named handler must exist for
+    a registry to resolve it.
+
+    Hook infrastructure is intentionally NOT exempt — pass-through aliases inside
+    hook modules are the motivating case. Test files and config files are exempt
+    because re-binding aliases are legitimate scaffolding there.
+
+    Args:
+        content: The source under inspection.
+        file_path: Path to the file, used for the test and config exemptions.
+
+    Returns:
+        One issue string per pass-through alias, capped at
+        MAX_ZERO_PAYLOAD_ALIAS_ISSUES.
+    """
+    if is_test_file(file_path) or is_config_file(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    function_node_by_name = _collect_module_function_nodes_by_name(parsed_tree)
+    all_sibling_function_names = set(function_node_by_name)
+    all_string_literal_values = _module_string_literal_values(parsed_tree)
+    issues: list[str] = []
+    for each_statement in parsed_tree.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if each_statement.decorator_list:
+            continue
+        if each_statement.name in all_string_literal_values:
+            continue
+        if not _has_only_positional_parameters(each_statement):
+            continue
+        call_node = _single_return_call(each_statement)
+        if call_node is None:
+            continue
+        target_name = _alias_target_name(call_node, all_sibling_function_names)
+        if not target_name or target_name == each_statement.name:
+            continue
+        target_node = function_node_by_name[target_name]
+        if _function_is_async(each_statement) != _function_is_async(target_node):
+            continue
+        forwarded_parameter_names = _function_parameter_names_in_order(each_statement)
+        if not _forwards_parameters_unchanged(call_node, forwarded_parameter_names):
+            continue
+        if not _target_accepts_forwarded_positional_call(
+            target_node, len(forwarded_parameter_names)
+        ):
+            continue
+        issues.append(
+            f"Line {each_statement.lineno}: {file_path}: zero-payload alias — "
+            f"{each_statement.name} only forwards its parameters to {target_name}; "
+            f"callers should call {target_name} directly (indirection without payload)"
+        )
+    return issues[:MAX_ZERO_PAYLOAD_ALIAS_ISSUES]
+
+
 def check_typed_dict_encode_decode(content: str, file_path: str) -> list[str]:
     """Flag TypedDict declarations missing companion `_encode_*` / `_decode_*` functions."""
     if (

package/hooks/blocking/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration package for the blocking hooks.
+
+A regular package (not a namespace package) so it resolves ahead of any
+same-named package later on ``sys.path``.
+"""

package/hooks/blocking/config/verified_commit_constants.py

@@ -0,0 +1,106 @@
+"""Constants for the verified-commit gate hook family.
+
+Shared by ``verification_verdict_store.py``, ``verified_commit_gate.py``,
+and ``verifier_verdict_minter.py`` so every tunable lives in one place.
+"""
+
+from __future__ import annotations
+
+GIT_TIMEOUT_SECONDS = 30
+ROOT_KEY_HEX_LENGTH = 16
+VERDICT_JSON_INDENT = 2
+CLAUDE_HOME_DIRECTORY_NAME = ".claude"
+VERDICT_DIRECTORY_NAME = "verification"
+VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN = r"['\"\\/,\s]+"
+VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN = r"(?=['\"]*[\\/,])"
+RELATIVE_VERDICT_DIRECTORY_PATTERN = r"(?:^|(?<=[\s;&|(='\"]))verification[\\/]"
+VERDICT_PATH_GLUE_PATTERN = r"['\"+\\/\s]*[\\/]['\"+\\/\s]*"
+VERDICT_DIRECTORY_CHANGE_TARGET_PATTERN = r"[ \t]+['\"]?verification[\\/]?['\"]?(?=[\s;&|]|$)"
+VERDICT_PATH_JOINED_VARIABLE_PATTERN = r"\$\{?(\w+)\}?[\\/]|[\\/]\$\{?(\w+)\}?"
+VERDICT_PATH_VARIABLE_ASSIGNMENT_PATTERN = r"(?:^|(?<=[\s;&|(]))%s=(\S+)"
+VERDICT_FILE_RELATIVE_REFERENCE_PATTERN = (
+    rf"(?:^|(?<=[\s;&|(='\"\\/]))verification[\\/][0-9a-f]{{{ROOT_KEY_HEX_LENGTH}}}\.json"
+)
+PATH_OBFUSCATION_PRIMITIVE_PATTERN = (
+    r"chr\s*\(|bytes\.fromhex\s*\(|b64decode\s*\(|codecs\.decode\s*\("
+    r"|(?:bytes|bytearray)\s*\(\s*\[|\[char\[?\]?\]"
+)
+ALL_VERDICT_PATH_SEGMENT_NAMES = (".claude", "verification")
+ALL_VERDICT_PATH_SEGMENT_BODIES = ("claude", "verification")
+HEX_TOKEN_PATTERN = r"(?<![0-9a-fx])([0-9a-f]{6,})(?![0-9a-f])"
+BASE64_TOKEN_PATTERN = r"[A-Za-z0-9+/]{8,}={0,2}"
+CHARACTER_CODE_SEQUENCE_PATTERN = r"\d{1,3}(?:\s*,\s*\d{1,3})+"
+CHR_CALL_CHAIN_PATTERN = r"chr\(\s*\d{1,3}\s*\)(?:\s*\+\s*chr\(\s*\d{1,3}\s*\))+"
+CHR_CALL_CODE_PATTERN = r"chr\(\s*(\d{1,3})\s*\)"
+HEX_DIGITS_PER_BYTE = 2
+FILE_WRITE_PRIMITIVE_PATTERN = (
+    r"\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b|>"
+)
+NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN = (
+    r"\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b"
+)
+WRITE_CALL_REGION_PATTERN = (
+    r"(?:\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b)[^;&|\n]*"
+)
+VERDICT_KEY_ALL_PASS = "all_pass"
+VERDICT_KEY_MANIFEST_SHA256 = "manifest_sha256"
+DOCS_ONLY_EXTENSIONS = frozenset(
+    {".md", ".txt", ".rst", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico"}
+)
+PYTHON_EXTENSION = ".py"
+TEST_FILE_PREFIX = "test_"
+TEST_FILE_SUFFIX = "_test.py"
+CONFTEST_FILE_NAME = "conftest.py"
+MINIMUM_STATUS_FIELD_COUNT = 2
+ALL_FALLBACK_BASE_REFERENCES = ("origin/main", "origin/master")
+ALL_TOOLING_STATE_PREFIXES = (
+    ".claude/verification/",
+    ".claude/worktrees/",
+    ".claude/daemon/",
+    ".claude/teams/",
+    ".claude/sessions/",
+    ".cursor/worktrees/",
+)
+GATED_GIT_SUBCOMMANDS = frozenset({"commit", "push"})
+ALL_GIT_BINARY_NAMES = frozenset({"git", "git.exe"})
+VALUE_TAKING_GIT_OPTIONS = frozenset({"-C", "-c", "--git-dir", "--work-tree", "--namespace"})
+REPO_DIRECTORY_OPTION = "-C"
+WORK_TREE_OPTION = "--work-tree"
+DIRECTORY_CHANGE_VERBS = frozenset({"cd", "pushd", "set-location", "sl"})
+DIRECTORY_CHANGE_PATH_OPTIONS = frozenset({"-path", "-literalpath"})
+DIRECTORY_CHANGE_OPTION_TERMINATOR = "--"
+DIRECTORY_CHANGE_PATTERN_PREFIX = r"(?:^|(?<=[\s;&|(]))(?:"
+DIRECTORY_CHANGE_PATTERN_SUFFIX = r")(?=\s|$)"
+DIRECTORY_CHANGE_OPTION_PREFIX_PATTERN = r"(?:[ \t]+(?:%s)(?=\s|$))*"
+DIRECTORY_CHANGE_TARGET_PATTERN = r"[ \t]+['\"]?\S*"
+CLAUDE_HOME_TARGET_BOUNDARY_PATTERN = r"[\\/]?['\"]?(?=[\s;&|]|$)"
+VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN = r"[\\/]?['\"]?(?=[\s;&|]|$)"
+COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN = r"[;&|\n][\s]*\S"
+OPTION_WITH_VALUE_STEP = 2
+ALL_GATED_TOOL_NAMES = ("Bash", "PowerShell")
+HASH_PREVIEW_LENGTH = 16
+MINTING_AGENT_TYPE = "code-verifier"
+SPAWN_LOOKUP_ATTEMPT_COUNT = 3
+SPAWN_LOOKUP_RETRY_DELAY_SECONDS = 0.1
+VERDICT_DIRECTORY_GUARD_MESSAGE = (
+    "BLOCKED: [VERDICT_DIRECTORY_GUARD] Shell access to the verification "
+    "verdict directory (~/.claude/verification/) is denied. Only the "
+    "verifier_verdict_minter.py SubagentStop hook writes verdict files; a "
+    "shell write here would forge a passing verdict and defeat the "
+    "verified-commit gate. Spawn the code-verifier agent to earn a verdict "
+    "instead of writing one."
+)
+CORRECTIVE_MESSAGE = (
+    "BLOCKED: [VERIFIED_COMMIT_GATE] This branch surface has no passing "
+    "verification verdict. Spawn the code-verifier agent (Agent tool, "
+    "subagent_type 'code-verifier') with the task texts, the diff scope, "
+    "and recorded baselines; when it finishes with a clean verdict the "
+    "SubagentStop hook mints the verdict and this command will pass. Any "
+    "file change after verification invalidates the verdict, so verify "
+    "last. Exempt automatically: docs/image files, pytest test files, and "
+    "Python files whose docstring- and comment-stripped AST is unchanged "
+    "(comment-only edits in non-Python files are not exempt)."
+)

package/hooks/blocking/test_code_rules_enforcer_cross_skill_duplicate.py

@@ -0,0 +1,146 @@
+"""Tests for the cross-skill duplicate-helper advisory.
+
+PR #233 on JonEcho/python-automation copied a Chrome-launch helper from the
+``stp-recolor`` skill's ``scripts`` directory into the ``iconize-and-recolor-stp``
+skill's ``scripts`` directory. The two skills install on their own, so a shared
+module would couple them and break independent install; the copy is a defensible
+skill-isolation tradeoff. ``advise_cross_skill_duplicate_helper`` surfaces that
+copy as a non-blocking ``[CODE_RULES advisory]`` on stderr so a reviewer confirms
+the copy was intentional, without denying the write.
+
+The tests build a real ``skills/<name>/scripts`` layout on disk and run the
+advisory against it, so they exercise the on-disk cross-skill scan rather than a
+stubbed view of the filesystem.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import shutil
+import sys
+import tempfile
+from collections.abc import Iterator
+
+import pytest
+
+_HOOK_DIRECTORY = pathlib.Path(__file__).parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+
+_hook_spec = importlib.util.spec_from_file_location(
+    "code_rules_duplicate_body",
+    _HOOK_DIRECTORY / "code_rules_duplicate_body.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)
+advise_cross_skill_duplicate_helper = _hook_module.advise_cross_skill_duplicate_helper
+
+
+CHROME_HELPER_SOURCE = (
+    "import winreg\n"
+    "from pathlib import Path\n"
+    "\n"
+    "chrome_app_paths_key = r'SOFTWARE\\Microsoft\\App Paths\\chrome.exe'\n"
+    "chrome_fallback_paths = ('C:/chrome.exe',)\n"
+    "\n"
+    "def _chrome_executable() -> Path | None:\n"
+    "    for each_root in (winreg.HKEY_CURRENT_USER, winreg.HKEY_LOCAL_MACHINE):\n"
+    "        try:\n"
+    "            registered = winreg.QueryValue(each_root, chrome_app_paths_key)\n"
+    "        except OSError:\n"
+    "            continue\n"
+    "        registered_path = Path(registered)\n"
+    "        if registered_path.exists():\n"
+    "            return registered_path\n"
+    "    for each_fallback in chrome_fallback_paths:\n"
+    "        fallback_path = Path(each_fallback)\n"
+    "        if fallback_path.exists():\n"
+    "            return fallback_path\n"
+    "    return None\n"
+)
+
+
+@pytest.fixture
+def skills_root() -> Iterator[pathlib.Path]:
+    base_directory = pathlib.Path(tempfile.mkdtemp())
+    skills_directory = base_directory / "skills"
+    skills_directory.mkdir()
+    try:
+        yield skills_directory
+    finally:
+        shutil.rmtree(base_directory, ignore_errors=False)
+
+
+def _make_skill_scripts(skills_directory: pathlib.Path, skill_name: str) -> pathlib.Path:
+    scripts_directory = skills_directory / skill_name / "scripts"
+    scripts_directory.mkdir(parents=True)
+    return scripts_directory
+
+
+def test_advises_when_helper_copied_from_another_skill(
+    skills_root: pathlib.Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source_scripts = _make_skill_scripts(skills_root, "stp-recolor")
+    (source_scripts / "palette_board.py").write_text(CHROME_HELPER_SOURCE, encoding="utf-8")
+    target_scripts = _make_skill_scripts(skills_root, "iconize-and-recolor-stp")
+    target_file = target_scripts / "combine_report.py"
+
+    advise_cross_skill_duplicate_helper(CHROME_HELPER_SOURCE, str(target_file))
+
+    captured = capsys.readouterr()
+    assert "[CODE_RULES advisory]" in captured.err, (
+        f"Expected a cross-skill advisory on stderr, got: {captured.err!r}"
+    )
+    assert "_chrome_executable" in captured.err, (
+        f"Expected the duplicated function named, got: {captured.err!r}"
+    )
+    assert "stp-recolor" in captured.err, f"Expected the source skill named, got: {captured.err!r}"
+
+
+def test_advisory_does_not_block(
+    skills_root: pathlib.Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source_scripts = _make_skill_scripts(skills_root, "stp-recolor")
+    (source_scripts / "palette_board.py").write_text(CHROME_HELPER_SOURCE, encoding="utf-8")
+    target_scripts = _make_skill_scripts(skills_root, "iconize-and-recolor-stp")
+    target_file = target_scripts / "combine_report.py"
+
+    returned = advise_cross_skill_duplicate_helper(CHROME_HELPER_SOURCE, str(target_file))
+
+    assert returned is None, "The advisory returns nothing so it never enters the deny path"
+
+
+def test_no_advisory_within_one_skill(
+    skills_root: pathlib.Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    scripts_directory = _make_skill_scripts(skills_root, "stp-recolor")
+    (scripts_directory / "palette_board.py").write_text(CHROME_HELPER_SOURCE, encoding="utf-8")
+    sibling_file = scripts_directory / "combine_report.py"
+
+    advise_cross_skill_duplicate_helper(CHROME_HELPER_SOURCE, str(sibling_file))
+
+    captured = capsys.readouterr()
+    assert captured.err == "", (
+        "Within one skill the blocking gate covers the copy; the cross-skill "
+        f"advisory must stay silent, got: {captured.err!r}"
+    )
+
+
+def test_no_advisory_outside_a_skill_scripts_directory(
+    skills_root: pathlib.Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source_scripts = _make_skill_scripts(skills_root, "stp-recolor")
+    (source_scripts / "palette_board.py").write_text(CHROME_HELPER_SOURCE, encoding="utf-8")
+    non_skill_directory = skills_root.parent / "elsewhere"
+    non_skill_directory.mkdir()
+    target_file = non_skill_directory / "combine_report.py"
+
+    advise_cross_skill_duplicate_helper(CHROME_HELPER_SOURCE, str(target_file))
+
+    captured = capsys.readouterr()
+    assert captured.err == "", (
+        f"A file outside a skill scripts directory draws no advisory, got: {captured.err!r}"
+    )