claude-dev-env 1.84.0 → 1.86.0

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

@@ -5,6 +5,8 @@ import subprocess
 from pathlib import Path
 from types import ModuleType
 
+import pytest
+
 
 def _load_sweep_module() -> ModuleType:
     module_path = Path(__file__).parent.parent / "terminology_sweep.py"
@@ -23,13 +25,22 @@ main = sweep_module.main
 parse_added_lines = sweep_module._parse_added_lines
 
 
+_hermetic_git_environment = sweep_module.repository_environment
+
+
 def _init_git_repository(repository_path: Path) -> None:
     for each_command in (
         ["git", "init"],
         ["git", "config", "user.email", "test@example.com"],
         ["git", "config", "user.name", "Test"],
     ):
-        subprocess.run(each_command, cwd=repository_path, check=True, capture_output=True)
+        subprocess.run(
+            each_command,
+            cwd=repository_path,
+            check=True,
+            capture_output=True,
+            env=_hermetic_git_environment(),
+        )
 
 
 CODE_AND_PROSE_DIFF = (
@@ -191,7 +202,7 @@ def test_does_not_flag_y_to_ies_plural_variant() -> None:
     assert sweep_diff(diff) == []
 
 
-def test_does_not_flag_spaced_prose_sharing_identifier_prefix() -> None:
+def test_still_flags_non_plural_divergent_tail() -> None:
     diff = (
         "diff --git a/api/quota.py b/api/quota.py\n"
         "--- a/api/quota.py\n"
@@ -204,19 +215,9 @@ def test_does_not_flag_spaced_prose_sharing_identifier_prefix() -> None:
         "@@ -0,0 +1,1 @@\n"
         "+The premium request budget gates the run.\n"
     )
-    assert sweep_diff(diff) == []
-
-
-def test_does_not_flag_ordinary_sentence_sharing_loop_variable_prefix() -> None:
-    diff = (
-        "diff --git a/api/scan.py b/api/scan.py\n"
-        "--- a/api/scan.py\n"
-        "+++ b/api/scan.py\n"
-        "@@ -0,0 +1,2 @@\n"
-        "+each_node = walk(tree)\n"
-        '+DESCRIPTION = "Each attempt polls the review endpoint once."\n'
-    )
-    assert sweep_diff(diff) == []
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "premium request" in findings[0]
 
 
 def test_flags_near_miss_inside_code_comment() -> None:
@@ -267,13 +268,17 @@ def test_main_exits_zero_when_clean(tmp_path: Path) -> None:
 
 def test_staged_terminology_findings_flags_staged_prose(tmp_path: Path) -> None:
     _init_git_repository(tmp_path)
-    (tmp_path / "quota.py").write_text(
-        "premium_interactions = 5\n", encoding="utf-8"
-    )
+    (tmp_path / "quota.py").write_text("premium_interactions = 5\n", encoding="utf-8")
     (tmp_path / "README.md").write_text(
         "The premium-request budget gates the run.\n", encoding="utf-8"
     )
-    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True, capture_output=True)
+    subprocess.run(
+        ["git", "add", "-A"],
+        cwd=tmp_path,
+        check=True,
+        capture_output=True,
+        env=_hermetic_git_environment(),
+    )
     findings = staged_terminology_findings(tmp_path)
     assert any("premium-request" in each_finding for each_finding in findings)
 
@@ -281,7 +286,13 @@ def test_staged_terminology_findings_flags_staged_prose(tmp_path: Path) -> None:
 def test_staged_terminology_findings_empty_when_clean(tmp_path: Path) -> None:
     _init_git_repository(tmp_path)
     (tmp_path / "README.md").write_text("Nothing notable here.\n", encoding="utf-8")
-    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True, capture_output=True)
+    subprocess.run(
+        ["git", "add", "-A"],
+        cwd=tmp_path,
+        check=True,
+        capture_output=True,
+        env=_hermetic_git_environment(),
+    )
     assert staged_terminology_findings(tmp_path) == []
 
 
@@ -299,9 +310,177 @@ def test_parse_added_lines_counts_pre_increment_content_as_added_line() -> None:
     all_added_lines = parse_added_lines(diff_with_pre_increment)
 
     assert [
-        (each_line_number, each_text) for _, each_line_number, each_text in all_added_lines
+        (each_line_number, each_text)
+        for _, each_line_number, each_text in all_added_lines
     ] == [
         (1, "++counter;"),
         (2, "let first_total = read_first_value();"),
         (3, "let second_total = read_second_value();"),
     ]
+
+
+def test_does_not_flag_window_containing_a_stopword() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+to_path = destination\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+Writes the report to a fresh location.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_tail_word_that_is_identifier_vocabulary() -> None:
+    diff = (
+        "diff --git a/api/layout.py b/api/layout.py\n"
+        "--- a/api/layout.py\n"
+        "+++ b/api/layout.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+target_width = box_height\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+Scale the art until it covers the target box.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_staged_skips_identifier_already_in_base_tree(tmp_path: Path) -> None:
+    _init_git_repository(tmp_path)
+    (tmp_path / "api.py").write_text("box_height = 4\n", encoding="utf-8")
+    subprocess.run(
+        ["git", "add", "."],
+        cwd=tmp_path,
+        check=True,
+        capture_output=True,
+        env=_hermetic_git_environment(),
+    )
+    subprocess.run(
+        ["git", "commit", "-m", "base"],
+        cwd=tmp_path,
+        check=True,
+        capture_output=True,
+        env=_hermetic_git_environment(),
+    )
+    all_api_lines = ("box_height = 4", "box_frame_total = box_height")
+    (tmp_path / "api.py").write_text(chr(10).join(all_api_lines), encoding="utf-8")
+    (tmp_path / "README.md").write_text(
+        "The box is read from the capture.", encoding="utf-8"
+    )
+    subprocess.run(
+        ["git", "add", "."],
+        cwd=tmp_path,
+        check=True,
+        capture_output=True,
+        env=_hermetic_git_environment(),
+    )
+    assert staged_terminology_findings(tmp_path) == []
+
+
+def test_does_not_flag_escape_sequence_letter_as_prose() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+box_frame_total = 5\n"
+        '+content = "box_height = 4\\nbox_frame_total = 5\\n"\n'
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_skips_string_literal_fragments_in_test_files() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_interactions = 5\n"
+        "diff --git a/tests/test_quota.py b/tests/test_quota.py\n"
+        "--- a/tests/test_quota.py\n"
+        "+++ b/tests/test_quota.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        '+fixture_text = "the premium-request budget gates the run"\n'
+        "+# the premium-request path resets the counter\n"
+    )
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "test_quota.py:2" in findings[0]
+
+
+def test_repository_environment_strips_every_git_variable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("GIT_DIR", "hostile-git-dir")
+    monkeypatch.setenv("PRESERVED_SETTING", "kept")
+
+    scrubbed_environment = sweep_module.repository_environment()
+
+    assert "GIT_DIR" not in scrubbed_environment
+    assert scrubbed_environment["PRESERVED_SETTING"] == "kept"
+
+
+def test_skips_markdown_inline_code_spans() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+scale_expression_reference = 1\n"
+        "diff --git a/docs/guide.md b/docs/guide.md\n"
+        "--- a/docs/guide.md\n"
+        "+++ b/docs/guide.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+Its `scale_expression.py` evaluates the layer's `scale` prop here.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_skips_identifier_shaped_string_literals() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+icon_entry = 1\n"
+        '+MASTER_UID = "HOMESCREEN_APPICONS_APP_ICON_IMAGE"\n'
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_skips_string_literal_fragments_in_dot_test_named_files() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_interactions = 5\n"
+        "diff --git a/api/quota.test.mjs b/api/quota.test.mjs\n"
+        "--- a/api/quota.test.mjs\n"
+        "+++ b/api/quota.test.mjs\n"
+        "@@ -0,0 +1,1 @@\n"
+        '+const fixture_line = "the premium-request budget gates the run"\n'
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_skips_string_literal_fragments_in_tests_directory_files() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_interactions = 5\n"
+        "diff --git a/tests/fixtures.py b/tests/fixtures.py\n"
+        "--- a/tests/fixtures.py\n"
+        "+++ b/tests/fixtures.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        '+sample_line = "the premium-request budget gates the run"\n'
+    )
+    assert sweep_diff(diff) == []

package/hooks/blocking/CLAUDE.md

@@ -88,6 +88,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `reviewer_spawn_gate.py` | PreToolUse (Bash) | A sentinel-marked autoconverge reviewer-spawn command (Copilot review request, Bugbot rerun comment) run while `reviewer_availability.py` reports that reviewer down or out of quota |
 | `send_user_file_open_locally_blocker.py` | PreToolUse (SendUserFile) | A desk-side file attach (`SendUserFile` with `status` not `proactive`); points to opening the file locally via `Show-Asset.ps1` |
 | `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
+| `session_edit_stage_gate.py` | PreToolUse (Bash) | A `git commit` that would drop files edited this session because they are tracked but left unstaged |
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
 | `stale_comment_reference_blocker.py` | PreToolUse (Edit) | An Edit that rewrites a Python code line while keeping the standalone comment directly above it, when that comment names an identifier the rewrite removes from the line |
 | `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation |

package/hooks/blocking/claude_md_orphan_file_blocker.py

@@ -45,11 +45,11 @@ from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E
     SEPARATOR_CELL_PATTERN,
     TABLE_ROW_PATTERN,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
     apply_edits,
     edits_for_tool,
 )
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
     read_hook_input_dictionary_from_stdin,
 )

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -501,13 +501,16 @@ def check_dead_module_constants(
 
     Returns:
         One violation message per dead module-level constant, capped at the
-        configured maximum. Returns an empty list when the file is exempt, no
-        constant is in scope (none defined, or none exported when ``__all__`` is
-        declared), the scan exceeds the file cap, or a SyntaxError prevents
-        parsing.
+        configured maximum. Returns an empty list when the file is exempt, the
+        path is relative (the scan root cannot be resolved against a known
+        base, so the check cannot prove a constant dead), no constant is in
+        scope (none defined, or none exported when ``__all__`` is declared),
+        the scan exceeds the file cap, or a SyntaxError prevents parsing.
     """
     if _module_is_exempt_from_constant_check(file_path):
         return []
+    if not Path(file_path).is_absolute():
+        return []
     effective_content = content if full_file_content is None else full_file_content
     try:
         tree = ast.parse(effective_content)

package/hooks/blocking/code_rules_docstrings.py

@@ -93,6 +93,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
+    MINIMUM_RANGE_ARGS_FOR_SPAN,
     MINIMUM_SIBLING_OCCURRENCES_FOR_SHARED_TOKEN,
     MINIMUM_TOKENS_FOR_DISPATCH_CALLEE,
     MINIMUM_TUPLE_MEMBERS_FOR_DOCSTRING_ENUMERATION,
@@ -2019,13 +2020,14 @@ def _documentable_docstrings_with_line(parsed_tree: ast.Module) -> list[tuple[in
 def check_docstring_cardinal_count_matches_constant_family(
     content: str, file_path: str
 ) -> list[str]:
-    """Flag a docstring cardinal count that under-names a referenced constant family.
+    """Flag a docstring cardinal count that differs from a referenced constant family.
 
     The drift this catches: a docstring states a cardinal count of an outcome
     family (``Covers the four outcome branches: ...``) and enumerates that
-    family's members in prose, while the module references more members of the
-    same ``UPPER_SNAKE`` constant family than the count names. The prose
-    under-describes the code — a reader trusts the count and the enumeration to
+    family's members in prose, while the module references a member set of the
+    same ``UPPER_SNAKE`` constant family whose size differs from the stated
+    count — above it and below it both trip. The prose
+    misdescribes the code — a reader trusts the count and the enumeration to
     be the full set, but the module imports and exercises an outcome the summary
     omits. The check binds only when the docstring states a cardinal beside an
     outcome noun, names two or more members of one referenced family, leaves at
@@ -2038,7 +2040,8 @@ def check_docstring_cardinal_count_matches_constant_family(
 
     Args:
         content: The source text to inspect.
-        file_path: The path the source will be written to, used for exemptions.
+        file_path: Accepted for the uniform check interface; the body does not
+            read it.
 
     Returns:
         One issue per docstring whose cardinal count and enumeration omit a
@@ -2473,12 +2476,12 @@ def _argument_prose_scopes_a_single_line(argument_prose: str) -> bool:
     )
 
 
-def _call_node_builds_two_argument_range(call_node: ast.Call) -> bool:
+def _call_node_builds_explicit_start_range(call_node: ast.Call) -> bool:
     callee = call_node.func
     return (
         isinstance(callee, ast.Name)
         and callee.id == "range"
-        and len(call_node.args) >= MINIMUM_TOKENS_FOR_DISPATCH_CALLEE
+        and len(call_node.args) >= MINIMUM_RANGE_ARGS_FOR_SPAN
     )
 
 
@@ -2490,7 +2493,7 @@ def _function_body_scopes_a_span_by_intersection(
     for each_node in ast.walk(function_node):
         if not isinstance(each_node, ast.Call):
             continue
-        if _call_node_builds_two_argument_range(each_node):
+        if _call_node_builds_explicit_start_range(each_node):
             builds_range_span = True
         if _call_callee_name(each_node) in ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES:
             calls_span_scoper = True
@@ -2510,11 +2513,12 @@ def check_docstring_args_single_line_scope_vs_span(content: str, file_path: str)
     is the deterministic slice of Category O6 docstring-vs-implementation drift
     for an Args single-line scope claim disagreeing with a span-intersection body.
 
-    An entry is left alone when its prose says "any line of" / "any line in" its
-    span, since that wording matches the span body. The body is judged a
-    span-intersection scoper only when it both builds a two-argument ``range(...)``
-    and calls a known span scoper, so a body that scopes by a single line never
-    trips the check. Hook infrastructure is in scope here — the import-sort gate
+    An entry is left alone when its prose says "any line of" / "any line in" /
+    "any of its lines" / "any span line" about its span, since that wording
+    matches the span body. The body is judged a span-intersection scoper only
+    when it both builds an explicit-start ``range(...)`` (two or more
+    arguments) and calls a known span scoper, so a body that scopes by a
+    single line never trips the check. Hook infrastructure is in scope here — the import-sort gate
     that carries this drift class is itself a hook — and test files are exempt.
 
     Args:

package/hooks/blocking/code_rules_imports_logging.py

@@ -244,7 +244,8 @@ def check_import_block_sorted(
             give ruff the filename it needs for config discovery.
         all_changed_lines: Post-edit line numbers the current edit touched, or
             None to treat the whole file as in scope. When provided, a finding
-            blocks only when its block-anchor line is among the changed lines.
+            blocks only when any line of its block span is among the changed
+            lines.
         defer_scope_to_caller: When True, return every finding so the commit/push
             gate's ``Line N:`` partitioning scopes by added line.
 
@@ -813,9 +814,9 @@ def _naive_datetime_remediation(constructor_name: str) -> str:
     """Return the fix guidance for a specific naive datetime constructor.
 
     ``utcnow`` and ``utcfromtimestamp`` accept no ``tz`` argument, so each points
-    at its aware replacement (``datetime.now(tz=...)`` and
-    ``datetime.fromtimestamp(..., tz=...)``); ``fromtimestamp`` keeps its shape and
-    only needs a ``tz=`` argument.
+    at its aware replacement (``now(tz=...)`` and ``fromtimestamp(..., tz=...)``
+    on the same datetime class, whichever import form the call used);
+    ``fromtimestamp`` keeps its shape and only needs a ``tz=`` argument.
 
     Args:
         constructor_name: The naive constructor the call used.
@@ -824,9 +825,12 @@ def _naive_datetime_remediation(constructor_name: str) -> str:
         The remediation clause to embed in the emitted issue.
     """
     if constructor_name == NAIVE_DATETIME_UTCNOW_CONSTRUCTOR:
-        return "use datetime.now(tz=timezone.utc)"
+        return "replace utcnow() with now(tz=timezone.utc) on the same datetime class"
     if constructor_name == NAIVE_DATETIME_UTCFROMTIMESTAMP_CONSTRUCTOR:
-        return "use datetime.fromtimestamp(..., tz=timezone.utc)"
+        return (
+            "replace utcfromtimestamp(...) with fromtimestamp(..., tz=timezone.utc) "
+            "on the same datetime class"
+        )
     return "pass tz= (e.g. tz=timezone.utc)"
 
 

package/hooks/blocking/code_rules_naming_collection.py

@@ -434,7 +434,7 @@ def _contradicting_polarity_pair(target_name: str, called_name: str) -> tuple[st
 
 
 def check_polarity_name_contradiction(content: str, file_path: str) -> list[str]:
-    """Flag a boolean assignment whose target and callee assert opposite polarity.
+    """Flag an assignment whose target and callee assert opposite polarity.
 
     ::
 
@@ -445,8 +445,10 @@ def check_polarity_name_contradiction(content: str, file_path: str) -> list[str]
         flag: is_inside_allowed = _point_hits_any_forbidden(...)
 
     The target token and the callee token contradict each other, so the reader
-    cannot tell which name states the truth. Rename the callee to a neutral form
-    the two names agree on at every call site.
+    cannot tell which name states the truth. Any single-name assignment from a
+    call is inspected — collections and counts included, not only booleans.
+    Rename the callee to a neutral form the two names agree on at every call
+    site.
     """
     if is_test_file(file_path):
         return []

package/hooks/blocking/code_rules_paired_test.py

@@ -164,8 +164,9 @@ def _stem_matched_test_path(module_path: Path) -> Path | None:
 
     Returns:
         The path of the first existing ``test_<stem>.py`` or ``<stem>_test.py``
-        file — beside the module or under an ancestor ``tests`` directory — or
-        None when the module has no dedicated test file.
+        file beside the module, or ``test_<stem>.py`` under an ancestor
+        ``tests`` directory — or None when the module has no dedicated test
+        file.
     """
     module_directory = module_path.parent
     module_stem = module_path.stem

package/hooks/blocking/code_rules_string_magic.py

@@ -1,4 +1,4 @@
-"""Bare string-literal magic, inline literal-collection, inline tuple string-magic, and whitespace-indentation magic checks."""
+"""Bare string-literal magic, join-separator string magic, inline literal-collection, inline tuple string-magic, and whitespace-indentation magic checks."""
 
 import ast
 import re

package/hooks/blocking/code_rules_unused_imports.py

@@ -1,4 +1,4 @@
-"""Unused module-level import check and its import-range and type-checking-gate helpers."""
+"""Unused module-level import check and its import-range helpers."""
 
 import ast
 import sys
@@ -143,7 +143,7 @@ def check_unused_module_level_imports(
 
     When ``full_file_content`` is provided, ``content`` is treated as an Edit
     fragment containing the imports being added or replaced, while the
-    ``__all__`` / ``TYPE_CHECKING`` gate detection and reference scanning run
+    ``__all__`` gate detection and reference scanning run
     against ``full_file_content`` (the post-edit file as it will look once the
     Edit applies). This prevents false-positive flags on imports added in the
     same Edit as their consumers.