claude-dev-env 2.9.0 → 2.11.0

package/hooks/blocking/code_rules_enforcer.py

@@ -18,6 +18,7 @@ concern focused. The separate ``tdd_enforcer.py`` hook accepts any
 import json
 import sys
 from collections import Counter
+from collections.abc import Callable
 from pathlib import Path
 from typing import TextIO
 
@@ -285,7 +286,15 @@ def validate_content(
         all_issues.extend(check_logging_adjacent_string_literals(content, file_path))
         all_issues.extend(check_windows_api_none(content))
         all_issues.extend(check_naive_datetime_construction(content, file_path))
-        all_issues.extend(check_magic_values(content, file_path))
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_magic_values,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_fstring_structural_literals(content, file_path))
         all_issues.extend(check_constants_outside_config(content, file_path))
         all_issues.extend(check_config_duplicate_path_anchor(content, file_path))
@@ -358,9 +367,21 @@ def validate_content(
         all_issues.extend(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
-        all_issues.extend(check_docstring_runon_sentence(effective_content, file_path))
         all_issues.extend(
-            check_docstring_prose_wall_without_illustration(effective_content, file_path)
+            check_docstring_runon_sentence(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            check_docstring_prose_wall_without_illustration(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
         )
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
@@ -508,8 +529,24 @@ def validate_content(
         all_issues.extend(check_polarity_name_contradiction(content, file_path))
         all_issues.extend(check_inline_literal_collections(content, file_path))
         all_issues.extend(check_inline_tuple_string_magic(content, file_path))
-        all_issues.extend(check_join_separator_string_magic(content, file_path))
-        all_issues.extend(check_string_literal_magic(content, file_path))
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_join_separator_string_magic,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_string_literal_magic,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_whitespace_indentation_magic(content, file_path))
         all_issues.extend(check_orphan_css_classes(effective_content, file_path))
         check_incomplete_mocks(content, file_path)
@@ -723,6 +760,124 @@ def _without_line_prefix(violation_text: str) -> str:
     return violation_text
 
 
+def _issues_absent_from_prior_bodies(
+    all_candidate_issues: list[str],
+    all_prior_issues: list[str],
+) -> list[str]:
+    """Return candidates whose message bodies are not covered by prior issues.
+
+    Matching is line-number-agnostic with per-occurrence accounting: each prior
+    entry consumes exactly one candidate carrying the same body.
+
+    ::
+
+        prior:    ["Line 1: magic 'X'"]
+        candidates: ["Line 4: magic 'X'", "Line 9: magic 'Y'"]
+        -> ["Line 9: magic 'Y'"]
+
+    Args:
+        all_candidate_issues: Findings from the scan under review.
+        all_prior_issues: Findings that already account for a body.
+
+    Returns:
+        Candidates not consumed by a matching prior body.
+    """
+    remaining_prior_counts = Counter(
+        _without_line_prefix(each_issue) for each_issue in all_prior_issues
+    )
+    all_uncovered_issues: list[str] = []
+    for each_issue in all_candidate_issues:
+        message_body = _without_line_prefix(each_issue)
+        if remaining_prior_counts[message_body] > 0:
+            remaining_prior_counts[message_body] -= 1
+            continue
+        all_uncovered_issues.append(each_issue)
+    return all_uncovered_issues
+
+
+def _fragment_or_deferred_check(
+    check_function: Callable[[str, str], list[str]],
+    old_content: str,
+    new_content: str,
+    file_path: str,
+    defer_scope_to_caller: bool,
+) -> list[str]:
+    """Run a check with fragment baselining, or full-file when the gate owns scope.
+
+    The commit/push gate sets ``defer_scope_to_caller`` and passes HEAD as
+    ``old_content`` while scanning the current file (often the same blob on a
+    clean worktree). Fragment baselining would grandfather every finding there,
+    so the gate path runs the check on ``new_content`` alone and classifies by
+    added line afterward. PreToolUse Edit keeps baselining against the prior
+    fragment.
+
+    ::
+
+        defer=True, old==new with magic 9999
+            -> [Line 2: Magic value 9999 ...]  gate still sees it
+        defer=False, old and new both carry the same magic
+            -> []  grandfathered for wide Edit
+
+    Args:
+        check_function: A ``(content, file_path) -> list[str]`` check.
+        old_content: Prior fragment or gate HEAD blob.
+        new_content: Proposed fragment or current full file.
+        file_path: Destination path used for path-based exemptions.
+        defer_scope_to_caller: True when the gate will scope by added line.
+
+    Returns:
+        Findings from the check, baselined against ``old_content`` only when
+        ``defer_scope_to_caller`` is False.
+    """
+    if defer_scope_to_caller:
+        return check_function(new_content, file_path)
+    return _issues_introduced_in_fragment(
+        check_function, old_content, new_content, file_path
+    )
+
+
+def _issues_introduced_in_fragment(
+    check_function: Callable[[str, str], list[str]],
+    old_content: str,
+    new_content: str,
+    file_path: str,
+) -> list[str]:
+    """Return fragment findings that are new relative to the pre-edit fragment.
+
+    Grades both the prior and proposed Edit fragments with the same check, then
+    subtracts findings whose message body already appears in the prior scan.
+    Per-occurrence accounting keeps a second identical new finding when only
+    one matching body existed before. Line numbers on kept findings come from
+    the proposed fragment so diagnostics point at the introduced location.
+
+    ::
+
+        old:  def f(): return os.environ['STRIPE_SECRET']
+        new:  def f(): return os.environ['STRIPE_SECRET']  # same body
+              -> []  grandfathered
+        old:  def f(): return 0
+        new:  def f(): return os.environ['STRIPE_SECRET']
+              -> [Line ...: string magic value 'STRIPE_SECRET' ...]
+
+    Args:
+        check_function: A ``(content, file_path) -> list[str]`` check.
+        old_content: The Edit's prior ``old_string`` fragment, or empty when
+            there is no prior region to baseline against.
+        new_content: The Edit's ``new_string`` fragment (or Write body).
+        file_path: Destination path used for path-based exemptions.
+
+    Returns:
+        Findings present in ``new_content`` that are absent from ``old_content``
+        under line-number-agnostic body matching. When ``old_content`` is empty,
+        every finding from ``new_content`` is returned.
+    """
+    all_new_issues = check_function(new_content, file_path)
+    if not old_content:
+        return all_new_issues
+    all_old_issues = check_function(old_content, file_path)
+    return _issues_absent_from_prior_bodies(all_new_issues, all_old_issues)
+
+
 def _forecast_full_file_violations(
     full_file_content_after_edit: str,
     file_path: str,
@@ -763,17 +918,7 @@ def _forecast_full_file_violations(
     all_full_file_issues = validate_content(
         full_file_content_after_edit, file_path, prior_full_file_content
     )
-    remaining_blocking_counts = Counter(
-        _without_line_prefix(each_issue) for each_issue in all_blocking_issues
-    )
-    forecast_issues: list[str] = []
-    for each_issue in all_full_file_issues:
-        message_body = _without_line_prefix(each_issue)
-        if remaining_blocking_counts[message_body] > 0:
-            remaining_blocking_counts[message_body] -= 1
-            continue
-        forecast_issues.append(each_issue)
-    return forecast_issues
+    return _issues_absent_from_prior_bodies(all_full_file_issues, all_blocking_issues)
 
 
 def _precheck_hint() -> str:

package/hooks/blocking/code_rules_shared.py

@@ -3,19 +3,12 @@
 import ast
 import difflib
 import os
-import sys
 import tempfile
 from collections.abc import Collection, Iterator
 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 hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+from hooks_constants.code_rules_enforcer_constants import (
+    ALL_AGENT_HOME_TOOLING_PATTERNS,
     ALL_DIFF_CHANGED_OPCODE_TAGS,
     ALL_EPHEMERAL_EXEMPT_DISABLE_TRUTHY_VALUES,
     ALL_HOOK_INFRASTRUCTURE_PATTERNS,
@@ -30,14 +23,14 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     LEADING_DRIVE_LETTER_PATTERN,
     STRICT_TEST_FILE_BASENAME_PATTERN,
 )
-from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+from hooks_constants.harness_scratchpad_constants import (
     CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME,
     HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
     HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME,
     HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX,
     HOOK_PAYLOAD_SESSION_ID_KEY,
 )
-from hooks_constants.unused_module_import_constants import (  # noqa: E402
+from hooks_constants.unused_module_import_constants import (
     TYPE_CHECKING_IDENTIFIER,
 )
 
@@ -56,6 +49,27 @@ def is_hook_infrastructure(file_path: str) -> bool:
     return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_HOOK_INFRASTRUCTURE_PATTERNS)
 
 
+def is_agent_home_tooling(file_path: str) -> bool:
+    """Check whether a path sits under a coding agent's home-directory tooling.
+
+    A coding agent installs helper scripts under a dot-directory in the home
+    tree, such as ``~/.grok/runs/``. That tree is vendored tooling rather than
+    project code, so the repository code rules do not govern it. The leading dot
+    is load-bearing: a project directory named ``grok/`` stays governed.
+
+    Args:
+        file_path: The candidate path to classify.
+
+    Returns:
+        True when the path sits under a recognized agent home directory.
+    """
+    path_lower = "/" + file_path.lower().replace("\\", "/").lstrip("/")
+    return any(
+        each_pattern.replace("\\", "/") in path_lower
+        for each_pattern in ALL_AGENT_HOME_TOOLING_PATTERNS
+    )
+
+
 def is_test_file(file_path: str) -> bool:
     """Check if file is a test file."""
     path_lower = file_path.lower()
@@ -405,17 +419,18 @@ def is_under_session_scratchpad(file_path: str, hook_payload: dict) -> bool:
 
 
 def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
-    """Return True when file_path is a throwaway scratch path exempt from repo gates.
-
-    Combines the two throwaway-path families a repo gate skips: the root-anchored
-    ephemeral scratch directories (``/tmp`` and ``$CLAUDE_JOB_DIR/tmp``) and the
-    harness session scratchpad. The session scratchpad match reads the session id
-    from the payload when one is supplied, and from the harness environment
-    variable otherwise, so a caller that holds no payload still gets the match.
-    The run_all_validators PreToolUse gate calls this predicate to skip a scratch
-    target before it validates. The code-rules and TDD gates call the two path
-    predicates ``is_ephemeral_script_path`` and ``is_under_session_scratchpad``
-    directly.
+    """Return True when file_path is exempt from the repository gates.
+
+    Combines the path families a repo gate skips: the root-anchored ephemeral
+    scratch directories (``/tmp`` and ``$CLAUDE_JOB_DIR/tmp``), the harness
+    session scratchpad, and a coding agent's own home-directory tooling such as
+    ``~/.grok/runs/``. The session scratchpad match reads the session id from the
+    payload when one is supplied, and from the harness environment variable
+    otherwise, so a caller that holds no payload still gets the match. The
+    run_all_validators PreToolUse gate calls this predicate to skip an exempt
+    target before it validates. The code-rules and TDD gates call the underlying
+    predicates ``is_ephemeral_script_path``, ``is_agent_home_tooling``, and
+    ``is_under_session_scratchpad`` directly.
 
     Args:
         file_path: The candidate path to classify.
@@ -423,10 +438,12 @@ def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
             read the session id from the environment alone.
 
     Returns:
-        True when the path is ephemeral scratch or under the session scratchpad.
+        True when the path is scratch, agent tooling, or the session scratchpad.
     """
     if is_ephemeral_script_path(file_path):
         return True
+    if is_agent_home_tooling(file_path):
+        return True
     return is_under_session_scratchpad(file_path, hook_payload or {})
 
 

package/hooks/blocking/config/CLAUDE.md

@@ -1,16 +1,14 @@
 # hooks/blocking/config
 
-A Python package that holds shared constants for the verified-commit gate family. Three modules in `blocking/` import from here:
-
-- `verification_verdict_store.py`
-- `verified_commit_gate.py`
-- `verifier_verdict_minter.py`
+A Python package that holds shared constants for blocking hooks. Verified-commit gate modules and 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` |
+| `code_review_enforcement_constants.py` | Stamp and effort tunables for the code-review enforcement gates |
+| `prose_style_enforcement_constants.py` | `CLAUDE_PROSE_STYLE_ENFORCEMENT` opt-in (default off) for opinionated prose gates |
 | `verified_commit_constants.py` | All tunables for the gate: directory names, regex patterns for detecting verdict paths and obfuscation attempts, timeout values, git subcommand sets, bypass marker, and corrective messages |
 | `verified_commit_context_constants.py` | `VERIFY_SKIP_ADDITIONAL_CONTEXT`, the ``# verify-skip`` usage rule the gate attaches to a deny payload's `additionalContext` |
 | `verified_commit_gate_output_constants.py` | `PRE_TOOL_USE_HOOK_EVENT_NAME` and `DENY_PERMISSION_DECISION` (the deny payload's event name and decision string), `GATE_HOOK_MODULE_NAME` (the gate's own module name for block logging), and `REGEX_ALTERNATION_SEPARATOR` (the `\|` join for the directory-change verb alternation in `gated_invocations.py`) |

package/hooks/blocking/config/prose_style_enforcement_constants.py

@@ -0,0 +1,38 @@
+"""Single source of truth for opinionated prose-style gate opt-in.
+
+::
+
+    CLAUDE_PROSE_STYLE_ENFORCEMENT=1  ->  PROSE_STYLE_ENFORCEMENT_ENABLED True
+    (unset)                           ->  PROSE_STYLE_ENFORCEMENT_ENABLED False
+
+Structural AskUserQuestion lean-block validation stays always on. The flag
+arms only opinionated prose gates (heavy-word swaps, hedging, historical
+state phrasing, intent-only endings, hook prose-detector consistency).
+"""
+
+from __future__ import annotations
+
+import os
+
+PROSE_STYLE_ENFORCEMENT_ENV_VAR = "CLAUDE_PROSE_STYLE_ENFORCEMENT"
+ALL_ENFORCEMENT_ENABLED_ENV_VALUES = frozenset({"1", "true", "yes", "on"})
+
+
+def prose_style_enforcement_enabled_in_environment() -> bool:
+    """Read whether this machine turns opinionated prose gates on.
+
+    ::
+
+        CLAUDE_PROSE_STYLE_ENFORCEMENT=1      -> True
+        CLAUDE_PROSE_STYLE_ENFORCEMENT=" On " -> True
+        CLAUDE_PROSE_STYLE_ENFORCEMENT=0      -> False
+        (variable unset)                      -> False
+
+    Returns:
+        True when the variable holds an enabled value, False otherwise.
+    """
+    raw_environment_setting = os.environ.get(PROSE_STYLE_ENFORCEMENT_ENV_VAR, "")
+    return raw_environment_setting.strip().lower() in ALL_ENFORCEMENT_ENABLED_ENV_VALUES
+
+
+PROSE_STYLE_ENFORCEMENT_ENABLED = prose_style_enforcement_enabled_in_environment()

package/hooks/blocking/config/test_prose_style_enforcement_constants.py

@@ -0,0 +1,45 @@
+"""Tests for the prose-style enforcement opt-in flag (default off)."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+_CONSTANTS_PATH = Path(__file__).resolve().parent / "prose_style_enforcement_constants.py"
+
+
+def _load_constants_module(monkeypatch: pytest.MonkeyPatch, env_value: str | None):
+    module_name = "prose_style_enforcement_constants_under_test"
+    if env_value is None:
+        monkeypatch.delenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", raising=False)
+    else:
+        monkeypatch.setenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", env_value)
+    module_spec = importlib.util.spec_from_file_location(module_name, _CONSTANTS_PATH)
+    assert module_spec is not None and module_spec.loader is not None
+    module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(module)
+    return module
+
+
+def test_absent_env_is_default_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    module = _load_constants_module(monkeypatch, None)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is False
+    assert module.prose_style_enforcement_enabled_in_environment() is False
+
+
+@pytest.mark.parametrize("enabled_value", ["1", "true", "yes", "on", " True "])
+def test_truthy_env_enables(
+    monkeypatch: pytest.MonkeyPatch, enabled_value: str
+) -> None:
+    module = _load_constants_module(monkeypatch, enabled_value)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is True
+
+
+@pytest.mark.parametrize("disabled_value", ["0", "false", "no", "off", ""])
+def test_falsy_env_stays_off(
+    monkeypatch: pytest.MonkeyPatch, disabled_value: str
+) -> None:
+    module = _load_constants_module(monkeypatch, disabled_value)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is False