claude-dev-env 1.84.0 → 1.86.0

package/_shared/pr-loop/scripts/terminology_sweep.py

@@ -1,40 +1,26 @@
-"""Flag prose terms that near-miss an identifier a diff introduces.
-
-Picture a change that adds an API field named ``premium_interactions``. On the
-same branch, the docs call it the ``premium-request`` budget. The code and the
-prose now name one thing two ways. A reader who searches for one term never
-finds the other.
-
-This sweep reads a unified diff and collects every multi-word identifier added
-on code lines. Then it scans each added prose line — a Markdown line, or a
-comment, docstring, or string inside a code file. It flags a hyphenated term
-that shares an identifier's leading word but diverges in the tail. Each
-near-miss prints as one ``file:line`` finding, and the run exits non-zero when
-any finding remains, so a commit gate can block on it.
-
-Only hyphenated terms are candidates. A hyphen marks a deliberate compound —
-the author bound the words into one term — so a divergent tail there is a real
-naming drift. A bare spaced word run is ordinary prose: windowing every
-sentence that starts with an identifier's first word ("each attempt", "file
-exists") floods a vocabulary-dense change with false findings and gives the
-gate nothing actionable.
-
-A shared leading token alone is too weak a signal: ordinary English compounds
-such as ``read-only`` and ``data-driven`` collide with unrelated identifiers
-(``read_config``, ``data_source``) and would block a commit falsely. To keep the
-grounding case (``premium-request`` against ``premium_interactions``) firing
-while sparing those compounds, a candidate whose final token is a common English
-compound tail word (``only``, ``driven``, ``safe``, and the rest listed in
-``ALL_COMMON_ENGLISH_COMPOUND_TAIL_WORDS``) is treated as ordinary prose, not a
-near-miss.
-
-Ordinary singular/plural prose is spared the same way. A candidate that differs
-from an identifier only by a singular/plural form of one or more tokens
-(``test files`` against ``test_file``, ``retry policies`` against
-``retry_policy``) is treated as the same term, not a near-miss.
+"""Flag a prose term that names a code identifier a hair differently.
+
+A change adds the field ``premium_interactions`` while the same branch's docs
+call it the ``premium-request`` budget: one thing, two names, and a reader who
+searches one never finds the other.
+
+::
+
+    code adds:  premium_interactions            the identifier
+    prose adds: the premium-request budget       a hyphenated term
+    flag: premium-request  vs  premium_interactions  -- shared first word, tail diverges
+    ok:   premium-interactions                   -- exact hyphen form, agrees
+    ok:   read-only,  test files,  to a file     -- English compound, plural, or stopword
+
+The sweep reads a unified diff, collects the multi-word identifiers added on
+code lines, and scans each added prose line for a hyphen or space variant that
+shares an identifier's leading word but diverges after it. It spares ordinary
+prose: English compound tails, singular/plural forms, stopword windows, and
+words that are themselves tokens of another introduced identifier.
 """
 
 import argparse
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -45,6 +31,16 @@ if parent_directory not in sys.path:
 
 from pr_loop_shared_constants.terminology_sweep_constants import (  # noqa: E402
     ALL_COMMON_ENGLISH_COMPOUND_TAIL_WORDS,
+    ALL_GIT_GREP_BASE_TREE_COMMAND_PREFIX,
+    ALL_PROSE_STOPWORD_TOKENS,
+    ALL_STRING_ESCAPE_SEQUENCES,
+    ALL_TEST_FILE_NAME_INFIX_MARKERS,
+    GIT_BASE_TREE_REVISION,
+    IDENTIFIER_TOKEN_SEPARATOR,
+    PROSE_WINDOW_WORD_SEPARATOR,
+    TEST_DIRECTORY_PATH_SEGMENT,
+    TEST_FILE_PREFIX,
+    TEST_FILE_SUFFIX,
     ALL_DIFF_FILE_PATH_STRIP_PREFIXES,
     ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND,
     ALL_SWEEP_CODE_FILE_EXTENSIONS,
@@ -59,10 +55,12 @@ from pr_loop_shared_constants.terminology_sweep_constants import (  # noqa: E402
     DIFF_REMOVED_LINE_PREFIX,
     GIT_DIFF_SUBPROCESS_TIMEOUT_SECONDS,
     HYPHENATED_PROSE_TOKEN_PATTERN,
+    INLINE_CODE_SPAN_PATTERN,
     JAVASCRIPT_LINE_COMMENT_MARKER,
     JSDOC_CONTINUATION_MARKER,
     MARKDOWN_FILE_EXTENSION,
     MINIMUM_IDENTIFIER_TOKEN_COUNT,
+    PROSE_WORD_PATTERN,
     PYTHON_COMMENT_MARKER,
     SNAKE_CASE_IDENTIFIER_PATTERN,
     STRING_LITERAL_CONTENT_PATTERN,
@@ -151,32 +149,30 @@ def _identifier_tuples_in_text(code_text: str) -> list[IdentifierTuple]:
 
 def _collect_introduced_identifiers(
     all_added_lines: list[tuple[str, int, str]],
-) -> tuple[frozenset[IdentifierTuple], dict[str, list[IdentifierTuple]]]:
+) -> frozenset[IdentifierTuple]:
     """Return the identifier tuples introduced on added code lines.
 
     Args:
         all_added_lines: Added-line triples from :func:`_parse_added_lines`.
 
     Returns:
-        A ``(all_identifier_tuples, identifiers_by_first_token)`` pair. The map
-        groups the tuples by their leading token so the near-miss check reaches
-        every candidate for a given prefix without rescanning the whole set.
+        Every multi-word identifier tuple appearing on an added code line.
     """
     all_identifier_tuples: set[IdentifierTuple] = set()
     for each_file_path, _, each_text in all_added_lines:
         if _file_extension(each_file_path) in ALL_SWEEP_CODE_FILE_EXTENSIONS:
             all_identifier_tuples.update(_identifier_tuples_in_text(each_text))
-    identifiers_by_first_token: dict[str, list[IdentifierTuple]] = {}
-    for each_tuple in all_identifier_tuples:
-        identifiers_by_first_token.setdefault(each_tuple[0], []).append(each_tuple)
-    return frozenset(all_identifier_tuples), identifiers_by_first_token
+    return frozenset(all_identifier_tuples)
 
 
 def _prose_fragments(file_path: str, line_text: str) -> list[str]:
     """Return the prose fragments of an added line worth scanning for terms.
 
-    A Markdown line is prose in full. A code line contributes its comment tail,
-    its JSDoc continuation text, and the contents of its string literals.
+    A Markdown line is prose with its inline-code spans removed, since a
+    backticked span names code verbatim. A code line contributes its comment
+    tail, its JSDoc continuation text, and the contents of its string
+    literals. A test module contributes its comment tail and JSDoc text only
+    — its string literals hold fixture data, not prose.
 
     Args:
         file_path: The path the added line belongs to.
@@ -185,19 +181,61 @@ def _prose_fragments(file_path: str, line_text: str) -> list[str]:
     Returns:
         The prose fragments to scan for near-miss terms.
     """
-    if _file_extension(file_path) == MARKDOWN_FILE_EXTENSION:
-        return [line_text]
-    if _file_extension(file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+    extension = _file_extension(file_path)
+    if extension == MARKDOWN_FILE_EXTENSION:
+        return [INLINE_CODE_SPAN_PATTERN.sub(" ", line_text)]
+    if extension not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
         return []
     all_fragments: list[str] = []
     stripped_line = line_text.strip()
     if stripped_line.startswith(JSDOC_CONTINUATION_MARKER):
         all_fragments.append(stripped_line)
     all_fragments.extend(_comment_fragments(line_text))
-    all_fragments.extend(_string_literal_fragments(line_text))
+    if not _is_test_file(file_path):
+        all_fragments.extend(_string_literal_fragments(line_text))
     return all_fragments
 
 
+def _is_test_file(file_path: str) -> bool:
+    """Return whether a diff path names a test code module.
+
+    A test module's string literals hold fixture data — embedded diffs,
+    generated source, file trees — not documentation prose, so the sweep
+    reads only its comments and JSDoc lines. A ``quota.test.mjs``, a
+    ``layout.spec.ts``, and a ``fixtures.py`` under a tests directory are all
+    test modules, so every one of these paths counts::
+
+        tests/fixtures.py        -- under a tests/ directory
+        api/test_quota.py        -- test_ prefixed stem
+        api/quota_test.py        -- _test suffixed stem
+        api/quota.test.mjs       -- .test. name marker
+        api/layout.spec.ts       -- .spec. name marker
+
+    A non-code path (a Markdown design doc) is prose worth scanning whatever
+    its name, so it is never a test module here.
+
+    Args:
+        file_path: The diff path of the added line's file.
+
+    Returns:
+        True for a code file under a ``tests`` directory, or one whose name
+        carries a ``test_`` prefix, a ``_test`` suffix, or a
+        ``_test.``/``.test.``/``.spec.`` marker. False for any other path.
+    """
+    if _file_extension(file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+        return False
+    normalized_path = file_path.replace("\\", "/").lower()
+    if TEST_DIRECTORY_PATH_SEGMENT in f"/{normalized_path}":
+        return True
+    basename = normalized_path.rsplit("/", 1)[-1]
+    stem = Path(normalized_path).stem
+    if stem.startswith(TEST_FILE_PREFIX) or stem.endswith(TEST_FILE_SUFFIX):
+        return True
+    return any(
+        each_marker in basename for each_marker in ALL_TEST_FILE_NAME_INFIX_MARKERS
+    )
+
+
 def _comment_fragments(line_text: str) -> list[str]:
     """Return the comment tail of a code line, or an empty list when absent."""
     all_fragments: list[str] = []
@@ -215,7 +253,14 @@ def _comment_fragments(line_text: str) -> list[str]:
 
 
 def _string_literal_fragments(line_text: str) -> list[str]:
-    """Return the contents of every quoted string literal on a code line."""
+    """Return the contents of every quoted string literal on a code line.
+
+    Escape sequences inside a literal (``\\n``, ``\\t``) are replaced with
+    spaces before the words are read, so an escape letter never glues onto a
+    neighbouring word as a phantom prose term. A literal left with no
+    whitespace after that replacement is an identifier-shaped value — a UID,
+    a key, a path — not prose, and contributes nothing.
+    """
     all_fragments: list[str] = []
     for each_match in STRING_LITERAL_CONTENT_PATTERN.finditer(line_text):
         each_content = next(
@@ -226,6 +271,10 @@ def _string_literal_fragments(line_text: str) -> list[str]:
             ),
             "",
         )
+        for each_escape in ALL_STRING_ESCAPE_SEQUENCES:
+            each_content = each_content.replace(each_escape, " ")
+        if not any(each_character.isspace() for each_character in each_content):
+            continue
         all_fragments.append(each_content)
     return all_fragments
 
@@ -240,6 +289,36 @@ def _hyphenated_candidates(fragment: str) -> list[tuple[str, IdentifierTuple]]:
     return all_candidates
 
 
+def _spaced_candidates(
+    fragment: str,
+    identifiers_by_first_token: dict[str, list[IdentifierTuple]],
+) -> list[tuple[str, IdentifierTuple]]:
+    """Return spaced word windows whose first word matches an identifier prefix.
+
+    Only a window anchored at a known identifier prefix and sized to one of that
+    prefix's identifiers is returned, which bounds the windows to the shapes the
+    near-miss check can act on.
+
+    Args:
+        fragment: The prose fragment to scan.
+        identifiers_by_first_token: Identifier tuples grouped by leading token.
+
+    Returns:
+        ``(display, token_tuple)`` pairs for each candidate window.
+    """
+    all_words = [
+        each_word.lower() for each_word in PROSE_WORD_PATTERN.findall(fragment)
+    ]
+    all_candidates: list[tuple[str, IdentifierTuple]] = []
+    for each_index, each_word in enumerate(all_words):
+        for each_identifier in identifiers_by_first_token.get(each_word, []):
+            window = tuple(all_words[each_index : each_index + len(each_identifier)])
+            if len(window) == len(each_identifier):
+                display = PROSE_WINDOW_WORD_SEPARATOR.join(window)
+                all_candidates.append((display, window))
+    return all_candidates
+
+
 def _tokens_are_plural_variants(first_word: str, second_word: str) -> bool:
     """Return whether two words are singular/plural forms of one word.
 
@@ -266,10 +345,41 @@ def _tuples_match_ignoring_plural(
     )
 
 
+def _word_is_identifier_vocabulary(
+    prose_word: str, all_identifier_tokens: frozenset[str]
+) -> bool:
+    """Return whether a prose word is a token of any introduced identifier.
+
+    A singular/plural form of an identifier token counts as the same word,
+    so ``uids`` matches an identifier token ``uid``.
+
+    Args:
+        prose_word: The lowercase prose word to look up.
+        all_identifier_tokens: Every token of every introduced identifier.
+
+    Returns:
+        True when the word, or a plural variant of it, is a known token.
+    """
+    if prose_word in all_identifier_tokens:
+        return True
+    if prose_word.endswith("y") and prose_word[:-1] + "ies" in all_identifier_tokens:
+        return True
+    if prose_word + "s" in all_identifier_tokens or prose_word + "es" in all_identifier_tokens:
+        return True
+    if prose_word.endswith("s") and prose_word[:-1] in all_identifier_tokens:
+        return True
+    if prose_word.endswith("es") and prose_word[:-2] in all_identifier_tokens:
+        return True
+    if prose_word.endswith("ies") and prose_word[:-3] + "y" in all_identifier_tokens:
+        return True
+    return False
+
+
 def _near_miss_identifier(
     candidate_tuple: IdentifierTuple,
     all_identifier_tuples: frozenset[IdentifierTuple],
     identifiers_by_first_token: dict[str, list[IdentifierTuple]],
+    all_identifier_tokens: frozenset[str],
 ) -> IdentifierTuple | None:
     """Return an identifier the candidate near-misses, or None when it does not.
 
@@ -277,20 +387,27 @@ def _near_miss_identifier(
         candidate_tuple: The prose term's lowercase token tuple.
         all_identifier_tuples: Every introduced identifier tuple.
         identifiers_by_first_token: Identifier tuples grouped by leading token.
+        all_identifier_tokens: Every token of every identifier on added code
+            lines, used to spare prose built from real code vocabulary.
 
     Returns:
-        The first identifier sharing the candidate's leading token and length but
-        differing in a later token, or None when the candidate matches an
-        identifier exactly, shares no prefix, ends in a common English compound
-        tail word (``read-only``, ``data-driven``), or differs from the
+        The first identifier sharing the candidate's leading token and length
+        but differing in a later token. None marks the candidate ordinary
+        prose instead, on any of these grounds: it matches an identifier
+        exactly; it shares no prefix with one; it ends in a common English
+        compound tail word (``read-only``, ``data-driven``); it contains an
+        English stopword (``to a``, ``each image``); it differs from the
         identifier only by a singular/plural form of one or more tokens
-        (``test files`` against ``test_file``) — each of which marks the
-        candidate ordinary prose rather than a near-miss of the identifier.
+        (``test files`` against ``test_file``); or every diverging word is
+        itself a token of some introduced identifier (``target box`` when
+        ``box_height`` is also in the diff).
     """
     if not candidate_tuple or candidate_tuple in all_identifier_tuples:
         return None
     if candidate_tuple[-1] in ALL_COMMON_ENGLISH_COMPOUND_TAIL_WORDS:
         return None
+    if any(each_word in ALL_PROSE_STOPWORD_TOKENS for each_word in candidate_tuple):
+        return None
     for each_identifier in identifiers_by_first_token.get(candidate_tuple[0], []):
         if len(each_identifier) != len(candidate_tuple):
             continue
@@ -298,6 +415,16 @@ def _near_miss_identifier(
             continue
         if _tuples_match_ignoring_plural(each_identifier, candidate_tuple):
             continue
+        diverging_words = [
+            each_word
+            for each_word, each_token in zip(candidate_tuple, each_identifier)
+            if not _tokens_are_plural_variants(each_word, each_token)
+        ]
+        if all(
+            _word_is_identifier_vocabulary(each_word, all_identifier_tokens)
+            for each_word in diverging_words
+        ):
+            continue
         return each_identifier
     return None
 
@@ -308,6 +435,7 @@ def _findings_for_line(
     line_text: str,
     all_identifier_tuples: frozenset[IdentifierTuple],
     identifiers_by_first_token: dict[str, list[IdentifierTuple]],
+    all_identifier_tokens: frozenset[str],
 ) -> list[str]:
     """Return the near-miss findings for one added line.
 
@@ -317,6 +445,8 @@ def _findings_for_line(
         line_text: The added line's text without its diff marker.
         all_identifier_tuples: Every introduced identifier tuple.
         identifiers_by_first_token: Identifier tuples grouped by leading token.
+        all_identifier_tokens: Every token of every identifier on added code
+            lines, used to spare prose built from real code vocabulary.
 
     Returns:
         One finding string per distinct near-miss term on the line.
@@ -325,9 +455,13 @@ def _findings_for_line(
     reported_tuples: set[IdentifierTuple] = set()
     for each_fragment in _prose_fragments(file_path, line_text):
         all_candidates = _hyphenated_candidates(each_fragment)
+        all_candidates += _spaced_candidates(each_fragment, identifiers_by_first_token)
         for each_display, each_tuple in all_candidates:
             matched_identifier = _near_miss_identifier(
-                each_tuple, all_identifier_tuples, identifiers_by_first_token
+                each_tuple,
+                all_identifier_tuples,
+                identifiers_by_first_token,
+                all_identifier_tokens,
             )
             if matched_identifier is None or each_tuple in reported_tuples:
                 continue
@@ -337,27 +471,43 @@ def _findings_for_line(
                     file_path=file_path,
                     line_number=line_number,
                     candidate=each_display,
-                    identifier="_".join(matched_identifier),
+                    identifier=IDENTIFIER_TOKEN_SEPARATOR.join(matched_identifier),
                 )
             )
     return all_findings
 
 
-def sweep_diff(diff_text: str) -> list[str]:
+def sweep_diff(
+    diff_text: str,
+    all_preexisting_identifier_tuples: frozenset[IdentifierTuple] = frozenset(),
+) -> list[str]:
     """Return every terminology near-miss finding for a unified diff.
 
     Args:
         diff_text: The unified-diff text to sweep.
+        all_preexisting_identifier_tuples: Token tuples of added-line identifiers
+            the base tree already names. A pre-existing identifier is not one
+            the diff introduces, so no prose is flagged against it. Its
+            tokens still count as code vocabulary.
 
     Returns:
         One finding string per near-miss term on an added prose line.
     """
     all_added_lines = _parse_added_lines(diff_text)
-    all_identifier_tuples, identifiers_by_first_token = _collect_introduced_identifiers(
-        all_added_lines
+    all_identifier_tuples = _collect_introduced_identifiers(all_added_lines)
+    all_identifier_tokens = frozenset(
+        each_token for each_tuple in all_identifier_tuples for each_token in each_tuple
+    )
+    introduced_tuples = frozenset(
+        each_tuple
+        for each_tuple in all_identifier_tuples
+        if each_tuple not in all_preexisting_identifier_tuples
     )
-    if not all_identifier_tuples:
+    if not introduced_tuples:
         return []
+    introduced_by_first_token: dict[str, list[IdentifierTuple]] = {}
+    for each_tuple in introduced_tuples:
+        introduced_by_first_token.setdefault(each_tuple[0], []).append(each_tuple)
     all_findings: list[str] = []
     for each_file_path, each_line_number, each_text in all_added_lines:
         all_findings.extend(
@@ -365,16 +515,102 @@ def sweep_diff(diff_text: str) -> list[str]:
                 each_file_path,
                 each_line_number,
                 each_text,
-                all_identifier_tuples,
-                identifiers_by_first_token,
+                introduced_tuples,
+                introduced_by_first_token,
+                all_identifier_tokens,
             )
         )
     return all_findings
 
 
+def repository_environment() -> dict[str, str]:
+    """Return the process environment with every GIT_ variable removed.
+
+    The sweep and the commit gate name their repository through an explicit
+    root argument. An inherited GIT_DIR or GIT_WORK_TREE would override
+    that root and point git at a different repository, so each spawned
+    subprocess runs with a scrubbed environment.
+
+    Returns:
+        A copy of ``os.environ`` without any variable whose name starts
+        with ``GIT_``.
+    """
+    return {
+        each_key: each_setting
+        for each_key, each_setting in os.environ.items()
+        if not each_key.startswith("GIT_")
+    }
+
+
+def _identifier_names_on_added_code_lines(diff_text: str) -> frozenset[str]:
+    """Return every multi-word identifier name on the diff's added code lines.
+
+    Args:
+        diff_text: The unified-diff text to scan.
+
+    Returns:
+        The distinct snake_case and camelCase names of two or more tokens.
+    """
+    all_names: set[str] = set()
+    for each_file_path, _, each_text in _parse_added_lines(diff_text):
+        if _file_extension(each_file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+            continue
+        all_found_names = SNAKE_CASE_IDENTIFIER_PATTERN.findall(each_text)
+        all_found_names += CAMEL_CASE_IDENTIFIER_PATTERN.findall(each_text)
+        for each_name in all_found_names:
+            token_tuple = _identifier_token_tuple(each_name)
+            if len(token_tuple) >= MINIMUM_IDENTIFIER_TOKEN_COUNT:
+                all_names.add(each_name)
+    return frozenset(all_names)
+
+
+def _base_tree_names(
+    repository_root: Path, all_names: frozenset[str]
+) -> frozenset[str]:
+    """Return the names the repository's base tree already contains.
+
+    Each name is looked up as a whole word in the base revision's tree. A
+    repository with no commits yet, or a lookup that git cannot run, reports
+    the name as absent, so the sweep then treats it as newly introduced —
+    the behaviour the sweep has with no base-tree check at all.
+
+    Args:
+        repository_root: The repository root the lookups run in.
+        all_names: The identifier names to look up.
+
+    Returns:
+        The subset of names present in the base tree.
+    """
+    all_present_names: set[str] = set()
+    for each_name in sorted(all_names):
+        try:
+            grep_process = subprocess.run(
+                [
+                    *ALL_GIT_GREP_BASE_TREE_COMMAND_PREFIX,
+                    each_name,
+                    GIT_BASE_TREE_REVISION,
+                ],
+                cwd=str(repository_root),
+                capture_output=True,
+                text=True,
+                timeout=GIT_DIFF_SUBPROCESS_TIMEOUT_SECONDS,
+                check=False,
+                env=repository_environment(),
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            continue
+        if grep_process.returncode == 0:
+            all_present_names.add(each_name)
+    return frozenset(all_present_names)
+
+
 def staged_terminology_findings(repository_root: Path) -> list[str]:
     """Return terminology near-miss findings for a repository's staged diff.
 
+    An identifier the base tree already names is not one the staged diff
+    introduces, so no prose is flagged against it — only genuinely new
+    identifiers are swept.
+
     Args:
         repository_root: The repository root the staged diff is read from.
 
@@ -391,10 +627,16 @@ def staged_terminology_findings(repository_root: Path) -> list[str]:
         errors="replace",
         timeout=GIT_DIFF_SUBPROCESS_TIMEOUT_SECONDS,
         check=False,
+        env=repository_environment(),
     )
     if diff_process.returncode != 0:
         return []
-    return sweep_diff(diff_process.stdout)
+    all_added_names = _identifier_names_on_added_code_lines(diff_process.stdout)
+    preexisting_tuples = frozenset(
+        _identifier_token_tuple(each_name)
+        for each_name in _base_tree_names(repository_root, all_added_names)
+    )
+    return sweep_diff(diff_process.stdout, preexisting_tuples)
 
 
 def _read_diff_text(diff_file_path: str | None) -> str:

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -64,6 +64,7 @@ def run_git_in_repository(repository_root: Path, *arguments: str) -> str:
         encoding="utf-8",
         errors="replace",
         check=True,
+        env=gate_module.repository_environment(),
     )
     return completion.stdout
 
@@ -2329,3 +2330,91 @@ def test_parse_arguments_applies_documented_defaults() -> None:
     assert parsed_arguments.repo_root is None
     assert parsed_arguments.only_under == []
     assert parsed_arguments.paths == []
+
+
+def test_staged_mode_resolves_scan_roots_from_outside_the_repository(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    package_directory = temporary_git_repository / "pkg"
+    config_directory = package_directory / "config"
+    write_file(package_directory / "__init__.py", "")
+    write_file(config_directory / "__init__.py", "")
+    write_file(
+        config_directory / "pkg_constants.py",
+        '"""Frame constants."""\n\nFRAME_COUNT: int = 9\n',
+    )
+    write_file(
+        package_directory / "consumer.py",
+        '"""Consumer of the frame constants."""\n\n'
+        "from pkg.config.pkg_constants import FRAME_COUNT\n\n"
+        "frame_total = FRAME_COUNT\n",
+    )
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(
+        config_directory / "pkg_constants.py",
+        '"""Frame constants."""\n\nFRAME_COUNT: int = 9\nPLATE_COUNT: int = 4\n',
+    )
+    write_file(
+        package_directory / "consumer.py",
+        '"""Consumer of the frame constants."""\n\n'
+        "from pkg.config.pkg_constants import FRAME_COUNT, PLATE_COUNT\n\n"
+        "frame_total = FRAME_COUNT + PLATE_COUNT\n",
+    )
+    stage_file(temporary_git_repository, "pkg/config/pkg_constants.py")
+    stage_file(temporary_git_repository, "pkg/consumer.py")
+
+    monkeypatch.chdir(tmp_path_factory.mktemp("elsewhere"))
+    exit_code = gate_module.main(
+        ["--repo-root", str(temporary_git_repository), "--staged"]
+    )
+
+    assert exit_code == 0
+
+
+def test_paths_from_git_staged_ignores_inherited_git_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    target_repository = tmp_path / "target_repository"
+    target_repository.mkdir()
+    initialize_git_repository(target_repository)
+    write_file(target_repository / "pkg" / "example_module.py", "EXAMPLE = 1\n")
+    stage_file(target_repository, "pkg/example_module.py")
+    victim_repository = tmp_path / "victim_repository"
+    victim_repository.mkdir()
+    initialize_git_repository(victim_repository)
+    monkeypatch.setenv("GIT_DIR", str(victim_repository / ".git"))
+    monkeypatch.setenv("GIT_WORK_TREE", str(victim_repository))
+    monkeypatch.setenv("GIT_INDEX_FILE", str(victim_repository / ".git" / "index"))
+
+    all_staged_names = [
+        each_path.name
+        for each_path in gate_module.paths_from_git_staged(target_repository)
+    ]
+
+    assert all_staged_names == ["example_module.py"]
+
+
+def test_run_staged_test_files_runs_pytest_without_git_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    repository_root = tmp_path / "repository_under_test"
+    repository_root.mkdir()
+    initialize_git_repository(repository_root)
+    staged_test_body = (
+        "import os\n"
+        "\n"
+        "\n"
+        "def test_environment_carries_no_git_variables() -> None:\n"
+        "    all_git_names = sorted(\n"
+        "        each_name for each_name in os.environ"
+        " if each_name.startswith('GIT_')\n"
+        "    )\n"
+        "    assert all_git_names == []\n"
+    )
+    write_file(repository_root / "test_environment_scrub.py", staged_test_body)
+    stage_file(repository_root, "test_environment_scrub.py")
+    monkeypatch.setenv("GIT_AUTHOR_NAME", "Hostile Hook Environment")
+
+    assert gate_module.run_staged_test_files(repository_root) == 0