claude-dev-env 2.28.1 → 2.30.0

package/hooks/blocking/config/AGENTS.md

@@ -1,10 +1 @@
-# hooks/blocking/config
 
-A Python package that holds shared constants for blocking hooks. Opinionated prose-style gates import from here.
-
-## Key files
-
-| File | Contents |
-|---|---|
-| `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
-| `prose_style_enforcement_constants.py` | `CLAUDE_PROSE_STYLE_ENFORCEMENT` opt-in (default off) for opinionated prose gates |

package/hooks/blocking/inventory_intent_records/AGENTS.md

@@ -1,26 +1 @@
-# inventory_intent_records
 
-The shared pending-intent store that lets `package_inventory_stale_blocker.py`
-and `claude_md_orphan_file_blocker.py` add a new file and its inventory row in
-one change, in either order. When one blocker denies, it records a note; the
-sibling blocker reads that note to allow the matching second write.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `records.py` | Read, record, peek, and consume the per-session file and row intents; a missing or corrupt store reads as no notes |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The records-file name shape, the freshness window, the list keys, and the note field names (`intent_records_constants.py`) |
-| `tests/` | pytest suite for the records store |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/inventory_intent_records/tests/
-```

package/hooks/blocking/package_inventory_stale_blocker_parts/AGENTS.md

@@ -1,26 +1 @@
-# package_inventory_stale_blocker_parts
 
-The concern modules `package_inventory_stale_blocker.py` wires together to block a
-new production file its package inventory omits. The entry hook imports them and
-re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `inventory_detection.py` | Surveys a directory's `README.md`/`CLAUDE.md`/`SKILL.md`, collects the filenames they name, and reports whether a maintained inventory omits the file being written |
-| `decision.py` | Builds the deny payload naming the omitted file and closing with the retry hint, and emits the decision JSON |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The retry hint the deny reason closes with and the inventory-name join separator (`inventory_blocker_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/package_inventory_stale_blocker_parts/tests/
-```

package/hooks/blocking/pii_prevention_blocker_parts/AGENTS.md

@@ -1,24 +1 @@
-# pii_prevention_blocker_parts
 
-The concern modules `pii_prevention_blocker.py` wires together. The entry hook
-imports them and re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `repository_exemption.py` | Resolves a commit's origin owner/repo slug, decides whether the repository skips the staged PII scan, and resolves the exact values that repository allows past the scan |
-| `repository_resolution.py` | Reads the repository a commit command targets — composing multiple `-C` values and a leading `cd`/`pushd` — and builds the deny reason naming the path when the repository root does not resolve |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The repository-resolution deny-message template and the session-cwd label (`repository_resolution_constants.py`) |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/tests/
-```

package/hooks/blocking/tdd_enforcer_parts/AGENTS.md

@@ -1,30 +1 @@
-# tdd_enforcer_parts
 
-The concern modules `tdd_enforcer.py` wires together to run the TDD gate. Each
-module owns one concern; the entry hook imports them and re-exports their
-surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `path_classification.py` | Classifies a write target (docs, tests, `.claude` trees) the gate skips, and extracts the written text from a Write, Edit, or MultiEdit payload |
-| `content_analysis.py` | Decides whether a payload is constants-only, and whether an Edit or MultiEdit merely removes or reorders imports |
-| `candidate_paths.py` | Resolves the candidate test files whose freshness can satisfy the gate for a production file |
-| `freshness.py` | Checks whether a candidate test was modified within the window and holds a real test function |
-| `git_tracking.py` | Detects a write that restores a git-tracked file absent on disk, so a remove-then-Write rewrite is exempt from the gate |
-| `decisions.py` | Builds the deny reason and writes the allow or deny decision JSON to stdout |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The freshness window, the ancestor-walk limit, the git-tracking command tokens, the source-file extension sets, and the join separator (`tdd_enforcer_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/tdd_enforcer_parts/tests/
-```

package/hooks/blocking/test_code_rules_enforcer_banned_noun_word.py

@@ -28,7 +28,7 @@ assert hook_spec.loader is not None
 hook_module = importlib.util.module_from_spec(hook_spec)
 hook_spec.loader.exec_module(hook_module)
 check_banned_noun_word_boundary = hook_module.check_banned_noun_word_boundary
-validate_content = hook_module.validate_content
+validate_content = hook_module.validate_content_for_full_gate
 
 from code_rules_banned_identifiers import (  # noqa: E402
     _find_banned_noun_word,

package/hooks/blocking/test_code_rules_enforcer_class_docstring_methods.py

@@ -31,7 +31,7 @@ def check_class_docstring_names_public_methods(content: str, file_path: str) ->
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/break_reporter.py"

package/hooks/blocking/test_code_rules_enforcer_dispatch_wiring.py

@@ -1,25 +1,49 @@
-"""Meta-test asserting every check_* function is dispatched from validate_content.
+"""Meta-test asserting every check_* function is reachable from the full gate.
 
 The per-check test modules each prove one ``check_*`` function flags the right
 violation, but none proves the enforcer actually calls that function. A refactor
-that drops a dispatch line from ``validate_content`` leaves every per-check test
-green while the check stops firing at Write/Edit time — the precise failure mode
+that drops a dispatch line from ``validate_content_for_full_gate`` or from one
+of its extension-issue helper functions leaves every per-check test green
+while the check stops firing at Write/Edit time — the precise failure mode
 that would let a dead module-level constant (the ``MEDIUM_TEXT`` class) or an
 orphan CSS class slip past the gate again.
 
-This module reads ``validate_content``'s source and asserts every ``check_*``
-attribute on the enforcer module appears in it. A check that is intentionally
-not wired must be listed in ``KNOWN_UNDISPATCHED_CHECKS`` with a reason in this
-docstring. ``check_unanchored_command_dispatch`` is listed there: it guards a
-``hooks/blocking`` command classifier, and the whole ``validate_content`` verdict
-stays off hook-infrastructure files, so the enforcer dispatches it from
+::
+
+    validate_content_for_full_gate -> _python_extension_issues -> _python_magic_value_and_constant_issues
+                                                                        |
+                                                                        v
+                                                            references check_magic_values
+    -> check_magic_values counts as reachable
+
+    check_unanchored_command_dispatch: called only from
+    _hook_infrastructure_blocking_issues, which the full gate's call graph
+    never reaches -> stays in KNOWN_UNDISPATCHED_CHECKS
+
+This module walks the enforcer's real call graph from
+``validate_content_for_full_gate``, following every direct function call into
+the functions the enforcer module defines, and collects every
+``check_*``/``advise_*`` name each reached function body references — a direct
+call or a bare reference passed on as a callback (the
+``_fragment_or_deferred_check(check_magic_values, ...)`` shape). A name that
+surfaces only in an import statement or a docstring is not a reference inside
+a reached function body, so it does not count; this is what keeps the check
+from going vacuous the way a whole-module substring scan would.
+
+A check that is intentionally not wired must be listed in
+``KNOWN_UNDISPATCHED_CHECKS`` with a reason in this docstring.
+``check_unanchored_command_dispatch`` is listed there: it guards a
+``hooks/blocking`` command classifier, and the whole
+``validate_content_for_full_gate`` verdict stays off hook-infrastructure
+files, so the enforcer dispatches it from
 ``_hook_infrastructure_blocking_issues`` instead. The companion
-``test_code_rules_enforcer_cap_meta.py`` guards the payload-cap convention; this
-module guards the wiring.
+``test_code_rules_enforcer_cap_meta.py`` guards the payload-cap convention;
+this module guards the wiring.
 """
 
 from __future__ import annotations
 
+import ast
 import importlib.util
 import inspect
 import pathlib
@@ -42,6 +66,8 @@ KNOWN_UNDISPATCHED_CHECKS: frozenset[str] = frozenset(
     {"check_unanchored_command_dispatch"}
 )
 
+DISPATCH_ENTRY_POINT_NAME = "validate_content_for_full_gate"
+
 
 def _all_check_function_names() -> list[str]:
     return [
@@ -52,22 +78,91 @@ def _all_check_function_names() -> list[str]:
     ]
 
 
-def _validate_content_source() -> str:
-    return inspect.getsource(_hook_module.validate_content)
+def _module_level_function_defs(module_tree: ast.Module) -> dict[str, ast.FunctionDef]:
+    """Map each module-level function's name to its definition node."""
+    return {
+        each_node.name: each_node
+        for each_node in module_tree.body
+        if isinstance(each_node, ast.FunctionDef)
+    }
 
 
-def test_every_check_function_is_called_in_validate_content() -> None:
-    all_check_names = set(_all_check_function_names())
-    validate_content_source = _validate_content_source()
-    undispatched_check_names = {
-        each_name for each_name in all_check_names if each_name not in validate_content_source
+def _local_call_targets(function_node: ast.FunctionDef) -> set[str]:
+    """Return the plain-name targets one function directly calls."""
+    return {
+        each_call.func.id
+        for each_call in ast.walk(function_node)
+        if isinstance(each_call, ast.Call) and isinstance(each_call.func, ast.Name)
+    }
+
+
+def _unvisited_local_calls(
+    function_name: str,
+    function_defs_by_name: dict[str, ast.FunctionDef],
+    visited: set[str],
+) -> list[str]:
+    """Return *function_name*'s call targets not already visited by the walk."""
+    function_node = function_defs_by_name.get(function_name)
+    if function_node is None:
+        return []
+    return [each for each in _local_call_targets(function_node) if each not in visited]
+
+
+def _reachable_function_names(
+    start_name: str, function_defs_by_name: dict[str, ast.FunctionDef]
+) -> set[str]:
+    """Return every function name the call graph reaches, starting from start_name."""
+    visited: set[str] = set()
+    pending = [start_name]
+    while pending:
+        each_pending_name = pending.pop()
+        if each_pending_name in visited:
+            continue
+        visited.add(each_pending_name)
+        pending.extend(_unvisited_local_calls(each_pending_name, function_defs_by_name, visited))
+    return visited
+
+
+def _referenced_names(function_node: ast.FunctionDef) -> set[str]:
+    """Return every loaded identifier one function body references.
+
+    A callback-style dispatch (``_fragment_or_deferred_check(check_magic_values,
+    ...)``) passes the check function by bare name rather than calling it
+    directly, so this collects every loaded ``Name``, not only call targets.
+    """
+    return {
+        each_name.id
+        for each_name in ast.walk(function_node)
+        if isinstance(each_name, ast.Name) and isinstance(each_name.ctx, ast.Load)
     }
+
+
+def _reachable_referenced_names(
+    start_name: str, function_defs_by_name: dict[str, ast.FunctionDef]
+) -> set[str]:
+    """Return every identifier referenced by a function the call graph reaches."""
+    reachable_function_names = _reachable_function_names(start_name, function_defs_by_name)
+    referenced_names: set[str] = set()
+    for each_function_name in reachable_function_names:
+        function_node = function_defs_by_name.get(each_function_name)
+        if function_node is not None:
+            referenced_names.update(_referenced_names(function_node))
+    return referenced_names
+
+
+def test_every_check_function_is_reachable_from_the_full_gate() -> None:
+    module_tree = ast.parse(inspect.getsource(_hook_module))
+    function_defs_by_name = _module_level_function_defs(module_tree)
+    reachable_names = _reachable_referenced_names(DISPATCH_ENTRY_POINT_NAME, function_defs_by_name)
+    all_check_names = set(_all_check_function_names())
+    undispatched_check_names = all_check_names - reachable_names
     unexpected_undispatched = undispatched_check_names - KNOWN_UNDISPATCHED_CHECKS
     assert unexpected_undispatched == set(), (
-        f"check_* functions are imported but never called in validate_content: "
-        f"{sorted(unexpected_undispatched)}. Wire each into validate_content so the "
-        f"check fires at Write/Edit time, or list it in KNOWN_UNDISPATCHED_CHECKS "
-        f"with a reason in the test header docstring."
+        f"check_* functions are imported but never reachable from "
+        f"validate_content_for_full_gate's call graph: {sorted(unexpected_undispatched)}. "
+        f"Wire each into validate_content_for_phase or one of its extension-issue "
+        f"helpers so the check fires at Write/Edit time, or list it in "
+        f"KNOWN_UNDISPATCHED_CHECKS with a reason in the test header docstring."
     )
 
 

package/hooks/blocking/test_code_rules_enforcer_docstring_args_signature.py

@@ -30,7 +30,7 @@ def check_docstring_args_match_signature(content: str, file_path: str) -> list[s
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/services.py"

package/hooks/blocking/test_code_rules_enforcer_docstring_prose_wall_illustration.py

@@ -39,7 +39,7 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/tally.py"

package/hooks/blocking/test_code_rules_enforcer_docstring_runon_sentence.py

@@ -42,7 +42,7 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/run_lifecycle.py"

package/hooks/blocking/test_code_rules_enforcer_docstring_unreferenced_param.py

@@ -32,7 +32,7 @@ def check_documents_unreferenced_parameter(content: str, file_path: str) -> list
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/per_theme_loop.py"

package/hooks/blocking/test_code_rules_enforcer_fstring_scan.py

@@ -17,7 +17,7 @@ assert hook_spec.loader is not None
 hook_module = importlib.util.module_from_spec(hook_spec)
 hook_spec.loader.exec_module(hook_module)
 check_fstring_structural_literals = hook_module.check_fstring_structural_literals
-validate_content = hook_module.validate_content
+validate_content = hook_module.validate_content_for_full_gate
 
 PRODUCTION_FILE_PATH = "packages/claude-dev-env/example.py"
 TEST_FILE_PATH = "packages/claude-dev-env/test_example.py"

package/hooks/blocking/test_code_rules_enforcer_ignored_must_check_return.py

@@ -25,7 +25,7 @@ from code_rules_boolean_mustcheck import (  # noqa: E402
     check_ignored_must_check_return as _check_ignored_must_check_return,
 )
 from code_rules_enforcer import (  # noqa: E402
-    validate_content as _validate_content,
+    validate_content_for_full_gate as _validate_content,
 )
 
 code_rules_enforcer = SimpleNamespace(

package/hooks/blocking/test_code_rules_enforcer_inline_tuple_string_magic.py

@@ -23,7 +23,7 @@ assert hook_spec.loader is not None
 hook_module = importlib.util.module_from_spec(hook_spec)
 hook_spec.loader.exec_module(hook_module)
 check_inline_tuple_string_magic = hook_module.check_inline_tuple_string_magic
-validate_content = hook_module.validate_content
+validate_content = hook_module.validate_content_for_full_gate
 
 PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
 TEST_FILE_PATH = "packages/app/services/test_loader.py"

package/hooks/blocking/test_code_rules_enforcer_join_separator_magic.py

@@ -77,7 +77,7 @@ def test_should_grandfather_unchanged_join_separator_in_wide_edit() -> None:
         "    # keep the join separator the same\n"
         "    return ', '.join(str(each_path) for each_path in all_paths)\n"
     )
-    issues = code_rules_enforcer.validate_content(
+    issues = code_rules_enforcer.validate_content_for_full_gate(
         proposed_fragment,
         PRODUCTION_FILE_PATH,
         prior_fragment,
@@ -97,7 +97,7 @@ def test_should_block_new_join_separator_in_wide_edit() -> None:
         "def render(all_paths: list) -> str:\n"
         "    return ', '.join(all_paths)\n"
     )
-    issues = code_rules_enforcer.validate_content(
+    issues = code_rules_enforcer.validate_content_for_full_gate(
         proposed_fragment,
         PRODUCTION_FILE_PATH,
         prior_fragment,

package/hooks/blocking/test_code_rules_enforcer_js_returns_object.py

@@ -1,6 +1,6 @@
 """Enforcer-dispatch tests for the JS returns-object schema-less branch check.
 
-These drive ``validate_content`` end-to-end on a ``.mjs`` payload, so they prove
+These drive ``validate_content_for_full_gate`` end-to-end on a ``.mjs`` payload, so they prove
 the check is wired into the JavaScript branch of the enforcer, not just callable
 in isolation. The drift: a ``function`` whose JSDoc ``@returns {Promise<object>}``
 promises a structured object while one branch returns the agent helper with an
@@ -62,11 +62,11 @@ def _has_returns_object_finding(all_issues: list[str]) -> bool:
 
 def test_enforcer_reports_schema_less_branch_under_returns_object() -> None:
     drift_source = _mixed_schema_mjs()
-    all_issues = code_rules_enforcer.validate_content(drift_source, _MJS_PATH, drift_source)
+    all_issues = code_rules_enforcer.validate_content_for_full_gate(drift_source, _MJS_PATH, drift_source)
     assert _has_returns_object_finding(all_issues)
 
 
 def test_enforcer_accepts_every_branch_with_a_schema() -> None:
     clean_source = _all_schema_mjs()
-    all_issues = code_rules_enforcer.validate_content(clean_source, _MJS_PATH, clean_source)
+    all_issues = code_rules_enforcer.validate_content_for_full_gate(clean_source, _MJS_PATH, clean_source)
     assert not _has_returns_object_finding(all_issues)

package/hooks/blocking/test_code_rules_enforcer_module_docstring_roster.py

@@ -31,7 +31,7 @@ def check_module_docstring_names_public_checks(content: str, file_path: str) ->
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/code_rules_test_assertions.py"

package/hooks/blocking/test_code_rules_enforcer_naming_pattern.py

@@ -18,7 +18,7 @@ assert _hook_spec.loader is not None
 _hook_module = importlib.util.module_from_spec(_hook_spec)
 _hook_spec.loader.exec_module(_hook_module)
 check_boolean_naming = _hook_module.check_boolean_naming
-validate_content = _hook_module.validate_content
+validate_content = _hook_module.validate_content_for_full_gate
 
 
 PRODUCTION_FILE_PATH = "src/app/feature.py"

package/hooks/blocking/test_code_rules_enforcer_narrow_edit.py

@@ -20,7 +20,7 @@ if _HOOKS_DIRECTORY not in sys.path:
 
 from code_rules_enforcer import (  # noqa: E402
     main,
-    validate_content,
+    validate_content_for_full_gate as validate_content,
 )
 
 
@@ -165,47 +165,126 @@ def _validate_narrow_edit(narrow_edit_fixture: NarrowEditFixture) -> list[str]:
     )
 
 
-def _scope_aware_rule_names_from_source() -> frozenset[str]:
-    source_tree = ast.parse(inspect.getsource(validate_content))
-    all_rule_names: set[str] = set()
-    for each_call in ast.walk(source_tree):
-        if not isinstance(each_call, ast.Call):
+_SCOPE_CARRYING_ATTRIBUTE_NAMES = frozenset({"all_changed_lines", "defer_scope_to_caller"})
+
+
+def _assignment_target_names(target: ast.expr) -> list[str]:
+    """Return the plain names one assignment target binds, Name or Tuple-of-Name."""
+    if isinstance(target, ast.Name):
+        return [target.id]
+    if isinstance(target, ast.Tuple):
+        return [each.id for each in target.elts if isinstance(each, ast.Name)]
+    return []
+
+
+def _scope_aliases_for_pair(target_names: list[str], all_values: list[ast.expr]) -> dict[str, str]:
+    """Return the local-name-to-scope-attribute map one assignment pair contributes."""
+    aliases: dict[str, str] = {}
+    for each_name, each_value in zip(target_names, all_values):
+        if not isinstance(each_value, ast.Attribute):
             continue
-        if not isinstance(each_call.func, ast.Name):
+        if each_value.attr not in _SCOPE_CARRYING_ATTRIBUTE_NAMES:
             continue
-        if each_call.func.id == "_fragment_or_deferred_check":
-            all_argument_names = {
-                each_name.id
-                for each_argument in each_call.args[1:]
-                for each_name in ast.walk(each_argument)
-                if isinstance(each_name, ast.Name)
-            }
-            if (
-                "defer_scope_to_caller" in all_argument_names
-                and each_call.args
-                and isinstance(each_call.args[0], ast.Name)
-            ):
-                all_rule_names.add(each_call.args[0].id)
+        aliases[each_name] = each_value.attr
+    return aliases
+
+
+def _context_alias_map(function_node: ast.AST) -> dict[str, str]:
+    """Map each local name one function binds from ``context.<scope attribute>``.
+
+    A dispatch helper unpacks ``context.all_changed_lines`` and
+    ``context.defer_scope_to_caller`` into a short local name (``changed``,
+    ``defer``) before passing it on, so a call carrying that local name still
+    carries scope, even though the local name spells out none of it.
+    """
+    aliases: dict[str, str] = {}
+    for each_node in ast.walk(function_node):
+        if not isinstance(each_node, ast.Assign) or len(each_node.targets) != 1:
             continue
-        if not each_call.func.id.startswith("check_"):
+        target_names = _assignment_target_names(each_node.targets[0])
+        if not target_names:
             continue
-        all_argument_names = {
-            each_name.id
-            for each_argument in each_call.args
-            for each_name in ast.walk(each_argument)
-            if isinstance(each_name, ast.Name)
-        }
-        all_argument_names.update(
-            each_name.id
-            for each_keyword in each_call.keywords
-            for each_name in ast.walk(each_keyword.value)
-            if isinstance(each_name, ast.Name)
-        )
-        if (
-            "all_changed_lines" in all_argument_names
-            or "defer_scope_to_caller" in all_argument_names
-        ):
-            all_rule_names.add(each_call.func.id)
+        value = each_node.value
+        all_values = value.elts if isinstance(value, ast.Tuple) else [value]
+        aliases.update(_scope_aliases_for_pair(target_names, all_values))
+    return aliases
+
+
+def _scope_names_for_reference(reference: ast.AST, aliases: dict[str, str]) -> set[str]:
+    """Return the scope-carrying attribute name one AST reference resolves to, if any."""
+    if isinstance(reference, ast.Name) and reference.id in aliases:
+        return {aliases[reference.id]}
+    if isinstance(reference, ast.Attribute) and reference.attr in _SCOPE_CARRYING_ATTRIBUTE_NAMES:
+        return {reference.attr}
+    return set()
+
+
+def _referenced_scope_attribute_names(node: ast.AST, aliases: dict[str, str]) -> set[str]:
+    """Return every scope-carrying attribute name *node* references, direct or aliased."""
+    found: set[str] = set()
+    for each_reference in ast.walk(node):
+        found.update(_scope_names_for_reference(each_reference, aliases))
+    return found
+
+
+def _fragment_deferred_rule_name(call_node: ast.Call, aliases: dict[str, str]) -> str | None:
+    """Return the rule name one ``_fragment_or_deferred_check`` call selects, if scoped."""
+    argument_scope_names = {
+        each_scope_name
+        for each_argument in call_node.args[1:]
+        for each_scope_name in _referenced_scope_attribute_names(each_argument, aliases)
+    }
+    if "defer_scope_to_caller" not in argument_scope_names:
+        return None
+    if not call_node.args or not isinstance(call_node.args[0], ast.Name):
+        return None
+    return call_node.args[0].id
+
+
+def _check_call_rule_name(call_node: ast.Call, aliases: dict[str, str]) -> str | None:
+    """Return the rule name one direct ``check_*`` call selects, if it carries scope."""
+    func_name = call_node.func.id  # type: ignore[attr-defined]  # caller already narrowed func to ast.Name
+    if not func_name.startswith("check_"):
+        return None
+    all_call_arguments = (*call_node.args, *(each_keyword.value for each_keyword in call_node.keywords))
+    argument_scope_names = {
+        each_scope_name
+        for each_argument in all_call_arguments
+        for each_scope_name in _referenced_scope_attribute_names(each_argument, aliases)
+    }
+    return func_name if argument_scope_names else None
+
+
+def _rule_names_from_function(function_node: ast.FunctionDef) -> set[str]:
+    """Return the check_* names *function_node* calls with scope-carrying arguments."""
+    aliases = _context_alias_map(function_node)
+    rule_names: set[str] = set()
+    for each_call in ast.walk(function_node):
+        if not isinstance(each_call, ast.Call) or not isinstance(each_call.func, ast.Name):
+            continue
+        if each_call.func.id == "_fragment_or_deferred_check":
+            rule_name = _fragment_deferred_rule_name(each_call, aliases)
+        else:
+            rule_name = _check_call_rule_name(each_call, aliases)
+        if rule_name is not None:
+            rule_names.add(rule_name)
+    return rule_names
+
+
+def _scope_aware_rule_names_from_source() -> frozenset[str]:
+    """Return every check_* name dispatched anywhere in the enforcer with scope.
+
+    Walks every function in the enforcer module rather than only
+    ``validate_content``, since the extension-issue helper functions hold the
+    actual dispatch calls today.
+    """
+    enforcer_module = inspect.getmodule(validate_content)
+    assert enforcer_module is not None
+    module_tree = ast.parse(inspect.getsource(enforcer_module))
+    all_rule_names: set[str] = set()
+    for each_function in ast.walk(module_tree):
+        if isinstance(each_function, ast.FunctionDef):
+            all_rule_names.update(_rule_names_from_function(each_function))
     return frozenset(all_rule_names)