claude-dev-env 1.59.0 → 1.60.0

package/audit-rubrics/category_rubrics/category-b-selector-engine-compat.md

@@ -22,7 +22,7 @@
 | B3 | Regex syntax vs engine flavor | Lookbehind / lookahead support; named groups (`(?P<…>)` vs `(?<…>)`); backreferences; Unicode character classes. |
 | B4 | Shell / CLI / cmdlet syntax vs runtime version | PowerShell 5.1 vs 7+; bash 3 vs 5; cmdlet parameters added in later versions; CLI flag deprecations. |
 | B5 | JSON path / XPath / structural query vs library | jq vs Python jsonpath-ng vs JavaScript jsonpath syntax; XPath 1.0 vs 2.0/3.0 functions. |
-| B6 | Search query DSL vs engine | Lucene / Elasticsearch / Zoekt / OpenSearch syntax; differences in escaping, fuzzy matching, multi-field queries. |
+| B6 | Search query DSL vs engine | Lucene / Elasticsearch / OpenSearch syntax; differences in escaping, fuzzy matching, multi-field queries. |
 | B7 | ORM vs raw SQL semantic differences | SQLAlchemy `.filter()` vs `.filter_by()`; Django Q expressions vs raw SQL; lazy vs eager evaluation. |
 
 Use 5–10 sub-buckets for any single audit. For an audit that doesn't touch SQL or web frontends, drop B1 / B2 entirely and split B4 across the relevant runtimes.

package/audit-rubrics/category_rubrics/category-e-dead-code.md

@@ -26,6 +26,7 @@
 | E6 | Removed-but-not-deleted symbol references | Symbols renamed/removed elsewhere with stale import or call sites left behind. |
 | E7 | Test fixtures / helpers defined but never used | Pytest fixtures, test data builders, mock factories with no callers. |
 | E8 | Stub / placeholder code without TODO | `pass`, `...`, `raise NotImplementedError` left without explanation or tracking. |
+| E9 | Constants-module exports with no importer | A module-level `UPPER_SNAKE` constant added to a `*_constants.py` / `config/` module that no module in the repo imports and that the constants file itself never references. The file-global use-count gate exempts a constants module because every name it exports legitimately carries zero in-file references, so a genuinely dead export slips past the write-time gate. Distinguish dead from live by grepping the whole repo for each constant name: a sibling such as `MEDIUM_TERMINAL` imported by a consumer module is live; a `MEDIUM_TEXT` that no `from ... import` line and no in-file reference names is dead (CODE_RULES 9.8). Remove the dead export. |
 
 ---
 

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -25,7 +25,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
 | O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. |
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
-| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. See `../../rules/docstring-prose-matches-implementation.md`. |
+| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 
 ---

package/audit-rubrics/prompts/category-b-selector-engine-compat.md

@@ -52,7 +52,7 @@ ID prefix: `find`.
 **B6. Search query DSL vs engine**
 - Every Lucene/Elasticsearch query string — verify field syntax (`field:value`), required/excluded operators (`+`, `-`), fuzzy (`term~2`), proximity (`"a b"~5`), and wildcard rules (`*`, `?`) match the engine version's parser.
 - Every Elasticsearch query DSL object (`match`, `bool`, `should`, `must`, `filter`, `term`, `terms`) — verify removed/renamed clauses across major versions (e.g. `query_string` defaults, `term` vs `match` for `text` fields, mapping-type removal in ES 7+).
-- Every Zoekt / Sourcegraph / OpenSearch / Solr query — verify dialect-specific operators and that the deployment has the relevant features enabled (e.g. ES `query_string` may be disabled for security).
+- Every Sourcegraph / OpenSearch / Solr query — verify dialect-specific operators and that the deployment has the relevant features enabled (e.g. ES `query_string` may be disabled for security).
 - Every escaping rule for special characters in the DSL (`+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /`) — verify the producer escapes them before handing to the engine; flag any user-supplied input concatenated raw.
 - Every analyzer assumption (whitespace, standard, keyword, ngram) — verify the index mapping matches what the query string assumes.
 
@@ -375,7 +375,7 @@ Write-Host "$TaskName registered — runs every ${IntervalMinutes}min against '$
   - Probe B5.c: confirm no JSON-pointer (`/foo/bar`) string literals, no JsonPath-style `$.foo[?(@.bar)]` patterns, no XPath `/html/body//div[@class='x']` patterns in any string in the four files. Walk every f-string and string literal.
 
 **B6. Search query DSL vs engine**
-- The four PR #394 files contain no search-engine queries, no Lucene/Elasticsearch/Zoekt/OpenSearch DSL.
+- The four PR #394 files contain no search-engine queries, no Lucene/Elasticsearch/OpenSearch DSL.
 - Shape B proof-of-absence expected. Adversarial probes must each verify a distinct search-DSL dimension:
   - Probe B6.a: confirm no HTTP calls to `/_search`, `/_msearch`, `/_count`, `/_analyze` endpoints — `sweep_empty_dirs.py` does not import `requests`, `urllib`, `httpx`, `aiohttp`. Pure stdlib + local config.
   - Probe B6.b: confirm no Lucene-syntax fragments — no `field:value`, no `+required -excluded`, no fuzzy `term~2`, no proximity `"a b"~5`. The only colon-bearing literals in the diff are PowerShell hash separators (`$($action.Execute) $($action.Arguments)` at `Install-SweepEmptyDirs.ps1:31`) and the time literal `"00:00"` at line 71 — neither is a search-DSL fragment.

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -0,0 +1,321 @@
+"""Dead module-level constant check for dedicated constants modules.
+
+A constants module (`*_constants.py`, or any module under a ``config/``
+directory) exists to export named values to importer modules elsewhere in the
+project, so a constant defined there is never proven dead by a single-file scan
+alone. This check resolves the enclosing package tree — the scan root — and
+flags an UPPER_SNAKE constant defined in the written module whose name appears
+in no ``.py`` module anywhere under that root: not as an imported name, not as a
+read, not as a re-export. That is the ``MEDIUM_TEXT``-style dead constant the
+CODE_RULES §9.8 dead-code rule targets, caught at Write/Edit time before the
+unused constant lands.
+
+The scan is deliberately conservative to keep false positives near zero:
+
+- Only dedicated constants modules participate; ordinary production modules,
+  whose file-global constants are governed by the use-count rule, are skipped.
+- A module declaring ``__all__`` is skipped: the author has named its export
+  surface explicitly, so a name listed there is live by declaration and a name
+  absent there is the author's stated intent, neither of which this check second
+  guesses.
+- A constant is live when its name appears anywhere under the scan root —
+  imported, read, listed in ``__all__``, or referenced in a string annotation —
+  in any ``.py`` module, including the constants module itself.
+- Test modules under the scan root still count as references, so a constant used
+  only by a test stays live.
+"""
+
+import ast
+import os
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    is_migration_file,
+    is_test_file,
+)
+
+from hooks_constants.dead_module_constant_constants import (  # noqa: E402
+    CONFIG_DIRECTORY_SEGMENT,
+    CONSTANTS_MODULE_SUFFIX,
+    DEAD_MODULE_CONSTANT_GUIDANCE,
+    DUNDER_ALL_NAME,
+    DUNDER_INIT_FILENAME,
+    MAX_DEAD_MODULE_CONSTANT_ISSUES,
+    MAX_SCAN_ROOT_FILE_COUNT,
+    MINIMUM_UPPER_SNAKE_LENGTH,
+    PYTHON_SOURCE_SUFFIX,
+)
+
+
+def _is_dedicated_constants_module(file_path: str) -> bool:
+    """Return whether a path is a dedicated constants module.
+
+    A dedicated constants module is one whose filename ends in
+    ``_constants.py`` or whose path includes a ``config`` directory segment.
+    These modules export named values to importers, so their constants need a
+    cross-module scan to judge liveness.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        True for a constants-suffixed module or a module under ``config/``.
+    """
+    normalized_path = file_path.replace("\\", "/").lower()
+    if normalized_path.endswith(CONSTANTS_MODULE_SUFFIX):
+        return True
+    path_segments = normalized_path.split("/")
+    return CONFIG_DIRECTORY_SEGMENT in path_segments[:-1]
+
+
+def _is_upper_snake_name(name: str) -> bool:
+    """Return whether a name is an UPPER_SNAKE_CASE constant identifier."""
+    if len(name) < MINIMUM_UPPER_SNAKE_LENGTH:
+        return False
+    if not name.replace("_", "").isalnum():
+        return False
+    return name == name.upper() and any(each_char.isalpha() for each_char in name)
+
+
+def _module_constant_definitions(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return (name, line) for each module-scope UPPER_SNAKE constant assignment.
+
+    Both plain assignments (``NAME = value``) and annotated assignments
+    (``NAME: type = value``) at module scope are collected. A name bound more
+    than once keeps the line of its first binding.
+
+    Args:
+        tree: The parsed constants module.
+
+    Returns:
+        One (name, line) pair per distinct module-scope constant, in source
+        order.
+    """
+    line_by_name: dict[str, int] = {}
+    for each_statement in tree.body:
+        targets: list[ast.expr] = []
+        if isinstance(each_statement, ast.Assign):
+            targets = list(each_statement.targets)
+        elif isinstance(each_statement, ast.AnnAssign) and each_statement.value is not None:
+            targets = [each_statement.target]
+        for each_target in targets:
+            if not isinstance(each_target, ast.Name):
+                continue
+            if not _is_upper_snake_name(each_target.id):
+                continue
+            if each_target.id not in line_by_name:
+                line_by_name[each_target.id] = each_statement.lineno
+    return list(line_by_name.items())
+
+
+def _statement_binds_dunder_all(statement: ast.stmt) -> bool:
+    """Return whether a single statement assigns or annotates ``__all__``."""
+    if isinstance(statement, ast.Assign):
+        return any(
+            isinstance(each_target, ast.Name) and each_target.id == DUNDER_ALL_NAME
+            for each_target in statement.targets
+        )
+    return (
+        isinstance(statement, ast.AnnAssign)
+        and isinstance(statement.target, ast.Name)
+        and statement.target.id == DUNDER_ALL_NAME
+    )
+
+
+def _module_declares_dunder_all(tree: ast.Module) -> bool:
+    """Return whether the module body assigns or annotates ``__all__``."""
+    return any(_statement_binds_dunder_all(each_node) for each_node in tree.body)
+
+
+def _referenced_names_in_source(source: str, load_only: bool = False) -> set[str]:
+    """Return every name a module references — imported, read, or re-exported.
+
+    Collects imported binding names, ``from`` import member names, name
+    references, attribute roots, and string literals (so a name listed in an
+    ``__all__`` literal or named in a string annotation counts as a reference).
+    A module that fails to parse contributes no names. With ``load_only`` set,
+    only ``Load``-context names count, so a constant's own assignment target in
+    the module being judged does not count as a reference to itself.
+
+    Args:
+        source: The full text of a ``.py`` module under the scan root.
+        load_only: When True, count only ``Load``-context name references,
+            excluding ``Store``/``Del`` targets. Used for the written constants
+            module so a definition is not mistaken for its own consumer.
+
+    Returns:
+        The set of names the module references.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+    referenced_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Name):
+            if load_only and not isinstance(each_node.ctx, ast.Load):
+                continue
+            referenced_names.add(each_node.id)
+        elif isinstance(each_node, ast.Import | ast.ImportFrom):
+            for each_alias in each_node.names:
+                referenced_names.add(each_alias.asname or each_alias.name)
+                referenced_names.add(each_alias.name)
+        elif isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            referenced_names.add(each_node.value)
+    return referenced_names
+
+
+def _scan_root_for_constants_module(file_path: str) -> Path:
+    """Return the directory tree to scan for references to the module's constants.
+
+    For a constants module inside a package subdirectory
+    (``pkg/foo_constants.py``), the scan root is the package's parent, so an
+    importer one directory up (``pkg/../consumer.py``) is in scope. For a
+    constants module at the top of a directory, the scan root is that directory.
+    A ``config/`` module's scan root is the parent of the ``config`` directory.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        The absolute directory to scan recursively for references.
+    """
+    written_path = Path(file_path).resolve()
+    enclosing_directory = written_path.parent
+    if enclosing_directory.name.lower() == CONFIG_DIRECTORY_SEGMENT:
+        return enclosing_directory.parent
+    if (enclosing_directory / DUNDER_INIT_FILENAME).is_file():
+        return enclosing_directory.parent
+    return enclosing_directory
+
+
+def _all_referenced_names_under_root(
+    scan_root: Path,
+    written_path: Path,
+    written_content: str,
+) -> tuple[set[str], bool]:
+    """Return referenced names under the scan root and whether the file cap was hit.
+
+    The written module's on-disk text is replaced by ``written_content`` so the
+    post-edit view is judged, never the stale disk copy. Sibling modules are
+    read from disk. Reading stops after the configured file cap so a write under
+    an unexpectedly large tree cannot stall the hook; the boolean signals the
+    caller to treat that case as "cannot prove dead".
+
+    Args:
+        scan_root: The directory tree to scan.
+        written_path: The resolved path of the module being written.
+        written_content: The post-edit text of the written module.
+
+    Returns:
+        A (referenced_names, cap_was_hit) pair. The name set is the union across
+        every scanned module; cap_was_hit is True when the scan stopped at the
+        configured file cap before scanning the whole tree.
+    """
+    all_referenced_names = _referenced_names_in_source(written_content, load_only=True)
+    written_path_key = os.path.normcase(str(written_path))
+    scanned_file_count = 1
+    for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
+        if not each_path.is_file():
+            continue
+        if os.path.normcase(str(each_path.resolve())) == written_path_key:
+            continue
+        scanned_file_count += 1
+        if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
+            return all_referenced_names, True
+        try:
+            sibling_source = each_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        all_referenced_names |= _referenced_names_in_source(sibling_source)
+    return all_referenced_names, False
+
+
+def _module_is_exempt_from_constant_check(file_path: str) -> bool:
+    """Return whether a path is exempt from the dead module-constant check.
+
+    Test modules and migration modules are exempt, and any module that is not a
+    dedicated constants module is out of scope because its file-global constants
+    are governed by the use-count rule instead.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        True when the dead module-constant check must not run on this path.
+    """
+    if is_test_file(file_path):
+        return True
+    if is_migration_file(file_path):
+        return True
+    return not _is_dedicated_constants_module(file_path)
+
+
+def check_dead_module_constants(
+    content: str,
+    file_path: str,
+    full_file_content: str | None = None,
+) -> list[str]:
+    """Flag an UPPER_SNAKE constant in a constants module read by no module.
+
+    Runs only on a dedicated constants module (``*_constants.py`` or a module
+    under ``config/``); every other production module's file-global constants
+    are governed by the use-count rule instead. A constant is dead when its name
+    appears in no ``.py`` module anywhere under the enclosing package tree — not
+    imported, not read, not listed in an ``__all__`` literal, not named in a
+    string annotation. A module declaring its own ``__all__`` is skipped so the
+    author's explicit export surface is never second-guessed. Whole-file
+    analysis runs against ``full_file_content`` when supplied so an Edit fragment
+    is judged against the reconstructed post-edit file.
+
+    Args:
+        content: The new content under validation (Edit fragment or whole file).
+        file_path: The destination path, used for the constants-module gate and
+            the test/registry exemptions.
+        full_file_content: The reconstructed post-edit whole-file content for an
+            Edit, or None for a Write where ``content`` is already the whole file.
+
+    Returns:
+        One violation message per dead module-level constant, capped at the
+        configured maximum.
+    """
+    if _module_is_exempt_from_constant_check(file_path):
+        return []
+    effective_content = content if full_file_content is None else full_file_content
+    try:
+        tree = ast.parse(effective_content)
+    except SyntaxError:
+        return []
+    if _module_declares_dunder_all(tree):
+        return []
+    constant_definitions = _module_constant_definitions(tree)
+    if not constant_definitions:
+        return []
+    scan_root = _scan_root_for_constants_module(file_path)
+    written_path = Path(file_path).resolve()
+    all_referenced_names, cap_was_hit = _all_referenced_names_under_root(
+        scan_root,
+        written_path,
+        effective_content,
+    )
+    if cap_was_hit:
+        return []
+    issues: list[str] = []
+    for each_name, each_line in constant_definitions:
+        if each_name in all_referenced_names:
+            continue
+        issues.append(
+            f"Line {each_line}: module-level constant {each_name!r}"
+            f" - {DEAD_MODULE_CONSTANT_GUIDANCE}"
+        )
+        if len(issues) >= MAX_DEAD_MODULE_CONSTANT_ISSUES:
+            break
+    return issues

package/hooks/blocking/code_rules_duplicate_body.py

@@ -28,6 +28,15 @@ leave the exact violation class unguarded. The enforcer entry points route a
 hook ``.py`` target to this single check even though the full code-rules verdict
 stays off hook infrastructure, so a Write or pre-check against a file under the
 ``blocking/`` directory still blocks a copied sibling helper.
+
+``advise_cross_skill_duplicate_helper`` is the non-blocking companion for a
+different layout: a helper copied between two skills' ``scripts`` directories.
+Two skill folders install on their own, so a shared module would break
+independent install and a same-directory block would be a false positive on a
+sanctioned skill-isolation copy. The advisory prints a ``[CODE_RULES advisory]``
+line to stderr naming the source skill and function so a reviewer confirms the
+copy is intentional, and never enters the deny path. It fires only across skill
+folders; within one skill the blocking check above already covers the copy.
 """
 
 import ast
@@ -47,11 +56,16 @@ from code_rules_shared import (  # noqa: E402
 )
 
 from hooks_constants.duplicate_function_body_constants import (  # noqa: E402
+    CROSS_SKILL_ADVISORY_PREFIX,
+    CROSS_SKILL_DUPLICATE_GUIDANCE,
     DUNDER_INIT_FILENAME,
     DUPLICATE_BODY_GUIDANCE,
+    MAX_CROSS_SKILL_ADVISORY_ISSUES,
     MAX_DUPLICATE_BODY_ISSUES,
     MINIMUM_DUPLICATE_BODY_STATEMENTS,
     PYTHON_SOURCE_SUFFIX,
+    SKILL_SCRIPTS_DIRECTORY_NAME,
+    SKILLS_DIRECTORY_NAME,
 )
 
 
@@ -285,3 +299,141 @@ def check_duplicate_function_body_across_files(
         all_changed_lines,
         defer_scope_to_caller,
     )
+
+
+def _skill_scripts_root(file_path: str) -> Path | None:
+    """Return the ``skills/<name>/scripts`` root the written file sits under.
+
+    A skill's helper scripts live at ``<...>/skills/<skill-name>/scripts/<file>``.
+    This walks the written file's parents for a ``scripts`` directory whose own
+    parent's parent is named ``skills``, and returns that ``scripts`` directory.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        The ``skills/<name>/scripts`` directory containing the file, or None when
+        the file is not under a skill's ``scripts`` directory.
+    """
+    written_path = Path(file_path).resolve()
+    for each_ancestor in written_path.parents:
+        if each_ancestor.name != SKILL_SCRIPTS_DIRECTORY_NAME:
+            continue
+        skill_directory = each_ancestor.parent
+        if skill_directory.parent.name == SKILLS_DIRECTORY_NAME:
+            return each_ancestor
+    return None
+
+
+def _other_skill_scripts_directories(scripts_root: Path) -> list[Path]:
+    """List the ``scripts`` directories of every sibling skill folder.
+
+    Args:
+        scripts_root: The ``skills/<name>/scripts`` directory of the written file.
+
+    Returns:
+        The ``scripts`` directory of each sibling skill that has one, excluding
+        the written file's own skill.
+    """
+    own_skill_directory = scripts_root.parent
+    skills_directory = own_skill_directory.parent
+    all_other_scripts_directories: list[Path] = []
+    try:
+        all_skill_entries = sorted(skills_directory.iterdir())
+    except OSError:
+        return []
+    for each_skill_directory in all_skill_entries:
+        if not each_skill_directory.is_dir():
+            continue
+        if each_skill_directory == own_skill_directory:
+            continue
+        candidate_scripts = each_skill_directory / SKILL_SCRIPTS_DIRECTORY_NAME
+        if candidate_scripts.is_dir():
+            all_other_scripts_directories.append(candidate_scripts)
+    return all_other_scripts_directories
+
+
+def _cross_skill_source_signatures(
+    all_other_scripts_directories: list[Path],
+) -> dict[str, list[str]]:
+    """Map each function body signature to the ``skill/module::function`` copies.
+
+    Args:
+        all_other_scripts_directories: The ``scripts`` directory of each sibling skill.
+
+    Returns:
+        A signature-to-source-names mapping naming the skill, module, and function
+        that carry each comparable top-level body.
+    """
+    source_names_by_signature: dict[str, list[str]] = {}
+    for each_scripts_directory in all_other_scripts_directories:
+        skill_name = each_scripts_directory.parent.name
+        try:
+            all_entries = sorted(each_scripts_directory.iterdir())
+        except OSError:
+            continue
+        for each_entry in all_entries:
+            if not _is_comparable_sibling(each_entry, ""):
+                continue
+            try:
+                sibling_source = each_entry.read_text(encoding="utf-8")
+                sibling_tree = ast.parse(sibling_source)
+            except (OSError, UnicodeDecodeError, SyntaxError):
+                continue
+            for each_name, each_signature in _top_level_function_signatures(sibling_tree).items():
+                location = f"{skill_name}/{each_entry.name}::{each_name}"
+                source_names_by_signature.setdefault(each_signature, []).append(location)
+    return source_names_by_signature
+
+
+def advise_cross_skill_duplicate_helper(content: str, file_path: str) -> None:
+    """Emit non-blocking stderr advisories for helpers copied across skill folders.
+
+    A top-level function in the file being written whose normalized body matches a
+    top-level function in another skill's ``scripts`` directory is surfaced as a
+    ``[CODE_RULES advisory]`` line on stderr — never a block. Two skill folders
+    install on their own, so a shared module would break independent install; the
+    copy is a defensible skill-isolation tradeoff the writer confirms rather than
+    a violation the gate denies. Within one skill the blocking duplicate-body gate
+    already covers the copy, so this advisory fires only across skill folders.
+
+    Test files and ``__init__.py`` are skipped on both the writing side and the
+    sibling side, mirroring the blocking gate.
+
+    Args:
+        content: The full post-edit file content being written.
+        file_path: The destination path of the write.
+    """
+    written_name = Path(file_path).name
+    if written_name == DUNDER_INIT_FILENAME:
+        return
+    if is_test_file(file_path):
+        return
+    scripts_root = _skill_scripts_root(file_path)
+    if scripts_root is None:
+        return
+    try:
+        written_tree = ast.parse(content)
+    except SyntaxError:
+        return
+    written_signatures = _top_level_function_signatures(written_tree)
+    if not written_signatures:
+        return
+    all_other_scripts_directories = _other_skill_scripts_directories(scripts_root)
+    if not all_other_scripts_directories:
+        return
+    source_names_by_signature = _cross_skill_source_signatures(all_other_scripts_directories)
+    advisory_count = 0
+    for each_name, each_signature in written_signatures.items():
+        matching_locations = source_names_by_signature.get(each_signature)
+        if not matching_locations:
+            continue
+        print(
+            f"{CROSS_SKILL_ADVISORY_PREFIX} {file_path}: function {each_name!r} "
+            f"duplicates {matching_locations[0]} in another skill — "
+            f"{CROSS_SKILL_DUPLICATE_GUIDANCE}",
+            file=sys.stderr,
+        )
+        advisory_count += 1
+        if advisory_count >= MAX_CROSS_SKILL_ADVISORY_ISSUES:
+            break