claude-dev-env 2.30.1 → 2.31.1

package/hooks/blocking/tdd_enforcer_parts/content_hash_store.py

@@ -0,0 +1,180 @@
+"""Persist each candidate test file's last-observed content hash per session.
+
+The freshness check alone cannot tell a real test edit from a bare touch:
+both refresh the file's mtime, so a touch reopens the TDD gate for every
+production write it looks at afterward. This module remembers what a
+candidate test file contained the last time the gate looked at it, keyed by
+session and repository root, so a touch that leaves the content unchanged no
+longer satisfies the gate.
+
+::
+
+    first sight, dirty + fresh + real test -> allow, record hash + time
+    first sight, otherwise                 -> deny, record nothing
+    seen before, hash now differs          -> allow, record new hash + time
+    seen before, hash matches, in window   -> allow (green/refactor continues)
+    seen before, hash matches, expired     -> deny
+
+The state lives in one JSON file per (session, repository root) pair under the
+OS temp directory, shaped like the per-session tracker in
+hooks/observability/session_file_edit_tracker.py, so two worktrees open in one
+session never share a file.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tempfile
+import time
+from pathlib import Path
+
+from atomic_file_writer import write_text_atomically
+from hooks_constants.session_edit_stage_gate_constants import (
+    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
+    STATE_FILE_ATOMIC_WRITE_SUFFIX,
+    STATE_FILE_DEFAULT_SESSION_ID,
+    STATE_FILE_JSON_INDENT_SPACES,
+)
+from hooks_constants.setup_project_paths_constants import UTF8_ENCODING
+from json_file_reader import read_json_object
+from tdd_enforcer_parts import freshness, git_tracking
+from tdd_enforcer_parts.config.tdd_enforcer_constants import (
+    HASH_STATE_FILE_PREFIX,
+    HASH_STATE_FILE_SUFFIX,
+    REPOSITORY_ROOT_DIGEST_LENGTH,
+    STORED_CHANGED_AT_KEY,
+    STORED_CONTENT_HASH_KEY,
+)
+
+
+def _sanitized_session_id(session_id: str) -> str:
+    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", session_id)
+    return sanitized_session_id or STATE_FILE_DEFAULT_SESSION_ID
+
+
+def _repository_root_digest(repository_root: str) -> str:
+    full_digest = hashlib.sha256(repository_root.encode("utf-8")).hexdigest()
+    return full_digest[:REPOSITORY_ROOT_DIGEST_LENGTH]
+
+
+def _state_file_path(session_id: str, repository_root: str) -> Path:
+    file_name = (
+        f"{HASH_STATE_FILE_PREFIX}{_sanitized_session_id(session_id)}-"
+        f"{_repository_root_digest(repository_root)}{HASH_STATE_FILE_SUFFIX}"
+    )
+    return Path(tempfile.gettempdir()) / file_name
+
+
+def _state_key_for(candidate_path: Path) -> str:
+    try:
+        return str(candidate_path.resolve())
+    except OSError:
+        return str(candidate_path)
+
+
+def _load_state(state_file: Path) -> dict[str, object]:
+    return read_json_object(state_file, encoding=UTF8_ENCODING) or {}
+
+
+def _atomic_write_state(state_file: Path, all_stored_hashes: dict[str, object]) -> None:
+    write_text_atomically(
+        state_file,
+        json.dumps(all_stored_hashes, indent=STATE_FILE_JSON_INDENT_SPACES),
+        encoding=UTF8_ENCODING,
+        temporary_prefix=HASH_STATE_FILE_PREFIX,
+        temporary_suffix=STATE_FILE_ATOMIC_WRITE_SUFFIX,
+        should_reap_orphans=False,
+    )
+
+
+def _content_hash(candidate_text: str) -> str:
+    return hashlib.sha256(candidate_text.encode(UTF8_ENCODING)).hexdigest()
+
+
+def _recorded_entry(current_hash: str, current_time: float) -> dict[str, object]:
+    return {STORED_CONTENT_HASH_KEY: current_hash, STORED_CHANGED_AT_KEY: current_time}
+
+
+def _is_qualifying_first_sight(
+    candidate_path: Path, candidate_text: str, current_time: float, freshness_seconds: int
+) -> bool:
+    candidate_mtime = freshness._safe_mtime(candidate_path)
+    if candidate_mtime is None or current_time - candidate_mtime > freshness_seconds:
+        return False
+    if not freshness.has_test_evidence_in(candidate_text):
+        return False
+    return git_tracking.has_uncommitted_change_from_head(candidate_path)
+
+
+def _evaluate_candidate(
+    candidate_path: Path,
+    stored_entry: object,
+    current_time: float,
+    freshness_seconds: int,
+) -> tuple[bool, dict[str, object] | None]:
+    candidate_text = freshness._read_candidate_text(candidate_path)
+    if candidate_text is None:
+        return False, None
+    current_hash = _content_hash(candidate_text)
+    if not isinstance(stored_entry, dict):
+        if _is_qualifying_first_sight(
+            candidate_path, candidate_text, current_time, freshness_seconds
+        ):
+            return True, _recorded_entry(current_hash, current_time)
+        return False, None
+    if current_hash != stored_entry.get(STORED_CONTENT_HASH_KEY):
+        return True, _recorded_entry(current_hash, current_time)
+    stored_changed_at = stored_entry.get(STORED_CHANGED_AT_KEY)
+    if not isinstance(stored_changed_at, (int, float)):
+        return False, None
+    return current_time - stored_changed_at <= freshness_seconds, None
+
+
+def _apply_candidate_decisions(
+    all_candidates: list[Path],
+    all_stored_hashes: dict[str, object],
+    current_time: float,
+    freshness_seconds: int,
+) -> tuple[bool, bool]:
+    is_allowed = False
+    state_changed = False
+    for each_candidate in all_candidates:
+        candidate_key = _state_key_for(each_candidate)
+        candidate_allowed, updated_entry = _evaluate_candidate(
+            each_candidate, all_stored_hashes.get(candidate_key), current_time, freshness_seconds
+        )
+        if candidate_allowed:
+            is_allowed = True
+        if updated_entry is not None:
+            all_stored_hashes[candidate_key] = updated_entry
+            state_changed = True
+    return is_allowed, state_changed
+
+
+def has_recorded_or_fresh_test(
+    all_candidates: list[Path],
+    session_id: str,
+    repository_root: str,
+    freshness_seconds: int,
+) -> bool:
+    """Return whether any candidate's tracked content hash satisfies the gate.
+
+    Args:
+        all_candidates: Candidate test paths for the production file.
+        session_id: Raw ``session_id`` from the hook payload.
+        repository_root: Raw ``cwd`` from the hook payload.
+        freshness_seconds: Maximum age, in seconds, a stored hash may have.
+
+    Returns:
+        True when at least one candidate is a fresh, dirty first sighting, a
+        recorded hash that now differs, or a recorded hash still in window.
+    """
+    state_file = _state_file_path(session_id, repository_root)
+    all_stored_hashes = _load_state(state_file)
+    is_allowed, state_changed = _apply_candidate_decisions(
+        all_candidates, all_stored_hashes, time.time(), freshness_seconds
+    )
+    if state_changed:
+        _atomic_write_state(state_file, all_stored_hashes)
+    return is_allowed

package/hooks/blocking/tdd_enforcer_parts/decisions.py

@@ -47,8 +47,12 @@ def build_deny_reason(production_path: Path, all_candidates: list[Path]) -> str:
     hook_source_path = _entry_hook_path()
     return (
         f"[TDD] Blocking write to production file: {production_path}\n"
-        f"No matching test file exists, or it has not been modified within the last "
-        f"{FRESHNESS_WINDOW_SECONDS} seconds.\n"
+        f"No matching test file exists. Or none of them is fresh, carries real test "
+        f"evidence, and holds content HEAD does not have yet. Or a previously "
+        f"recorded test's content has not changed within the last "
+        f"{FRESHNESS_WINDOW_SECONDS} seconds. Write a new test or change an "
+        f"existing one; touching a file without changing its content does not "
+        f"satisfy this gate.\n"
         f"Expected one of:\n{candidate_lines}\n"
         f"Write a failing test first (RED), then the minimum code to pass it (GREEN).\n\n"
         f"If this file legitimately does not need a test (for example, a module containing only "

package/hooks/blocking/tdd_enforcer_parts/freshness.py

@@ -42,13 +42,28 @@ def _read_candidate_text(candidate_path: Path) -> str | None:
         return None
 
 
+def has_test_evidence_in(candidate_text: str) -> bool:
+    """Return whether the given text holds a real test function.
+
+    Takes the text rather than the path, so a caller that has already read the
+    file does not read it a second time.
+
+    Args:
+        candidate_text: The candidate test file's full text.
+
+    Returns:
+        True when the text matches any test-function pattern.
+    """
+    return any(
+        each_pattern.search(candidate_text) for each_pattern in _test_function_patterns()
+    )
+
+
 def _contains_test_evidence(candidate_path: Path) -> bool:
     test_file_content = _read_candidate_text(candidate_path)
     if test_file_content is None:
         return False
-    return any(
-        each_pattern.search(test_file_content) for each_pattern in _test_function_patterns()
-    )
+    return has_test_evidence_in(test_file_content)
 
 
 def _candidate_is_fresh_test(

package/hooks/blocking/tdd_enforcer_parts/git_tracking.py

@@ -1,4 +1,4 @@
-"""Detect a write that restores a tracked-but-absent production file.
+"""Ask git about a candidate path: is it a restore, and does it carry a real edit.
 
 ::
 
@@ -8,13 +8,22 @@
 A full rewrite happens as remove-then-Write, so the file is absent on disk
 between the two steps. Restoring committed code is not new production code, so
 the gate exempts a Write whose target is absent yet tracked in git.
+
+``has_uncommitted_change_from_head`` answers a second, related question the
+content-hash store's first-sight check needs: whether a candidate test file
+already carries content HEAD does not have, so a `touch` on an already-clean,
+committed test cannot pass as a first sighting.
 """
 
 import subprocess
 from pathlib import Path
 
 from tdd_enforcer_parts.config.tdd_enforcer_constants import (
+    GIT_DIFF_QUIET_FLAG,
+    GIT_DIFF_SUBCOMMAND,
+    GIT_DIFF_TIMEOUT_SECONDS,
     GIT_EXECUTABLE_NAME,
+    GIT_HEAD_REVISION,
     GIT_LS_FILES_SUBCOMMAND,
     GIT_LS_FILES_TIMEOUT_SECONDS,
     GIT_PATHSPEC_SEPARATOR,
@@ -25,6 +34,17 @@ def _git_ls_files_command(file_name: str) -> list[str]:
     return [GIT_EXECUTABLE_NAME, GIT_LS_FILES_SUBCOMMAND, GIT_PATHSPEC_SEPARATOR, file_name]
 
 
+def _git_diff_quiet_against_head_command(file_name: str) -> list[str]:
+    return [
+        GIT_EXECUTABLE_NAME,
+        GIT_DIFF_SUBCOMMAND,
+        GIT_DIFF_QUIET_FLAG,
+        GIT_HEAD_REVISION,
+        GIT_PATHSPEC_SEPARATOR,
+        file_name,
+    ]
+
+
 def _git_tracks_path(path: Path) -> bool:
     parent_directory = path.parent
     if not parent_directory.is_dir():
@@ -43,6 +63,29 @@ def _git_tracks_path(path: Path) -> bool:
     return completed.returncode == 0 and bool(completed.stdout.strip())
 
 
+def _working_tree_differs_from_head(path: Path) -> bool:
+    """Compare the working tree to HEAD, not to the index.
+
+    A plain ``git diff`` (no revision argument) compares the working tree to
+    the index, so a file that was just ``git add``-ed reads as unchanged even
+    when it holds content HEAD never had. Naming ``HEAD`` folds the index and
+    the working tree into one comparison against the last commit, catching a
+    staged-but-uncommitted new file and a staged edit alike.
+    """
+    try:
+        completed = subprocess.run(
+            _git_diff_quiet_against_head_command(path.name),
+            cwd=str(path.parent),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=GIT_DIFF_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return True
+    return completed.returncode != 0
+
+
 def is_absent_but_tracked(path: Path) -> bool:
     """Return whether a write target is absent on disk yet tracked in git.
 
@@ -61,3 +104,25 @@ def is_absent_but_tracked(path: Path) -> bool:
     if path.exists():
         return False
     return _git_tracks_path(path)
+
+
+def has_uncommitted_change_from_head(path: Path) -> bool:
+    """Return whether *path* carries content its git HEAD does not have.
+
+    ::
+
+        untracked file                -> True  (no HEAD entry to match)
+        tracked, working tree != HEAD -> True  (a real edit this session)
+        tracked, working tree == HEAD -> False (clean; a touch cannot pass)
+        git unavailable or errors     -> True  (cannot prove it is clean)
+
+    Args:
+        path: The candidate test file to check.
+
+    Returns:
+        True unless git can positively confirm the file is tracked and its
+        working-tree content matches HEAD exactly.
+    """
+    if not _git_tracks_path(path):
+        return True
+    return _working_tree_differs_from_head(path)

package/hooks/blocking/tdd_enforcer_parts/tests/test_content_hash_store.py

@@ -0,0 +1,143 @@
+"""Behavioral tests for the content_hash_store parts module."""
+
+import json
+import os
+import time
+from pathlib import Path
+
+from tdd_enforcer_parts import content_hash_store
+
+
+def _write_fresh_test_file(directory: Path, content: str = "def test_fulfill(): pass\n") -> Path:
+    candidate = directory / "test_orders.py"
+    candidate.write_text(content)
+    return candidate
+
+
+def test_state_file_path_differs_by_repository_root(tmp_path: Path) -> None:
+    first_root_path = content_hash_store._state_file_path("session-a", str(tmp_path / "one"))
+    second_root_path = content_hash_store._state_file_path("session-a", str(tmp_path / "two"))
+    assert first_root_path != second_root_path
+
+
+def test_state_file_path_is_stable_for_the_same_inputs(tmp_path: Path) -> None:
+    first_lookup = content_hash_store._state_file_path("session-a", str(tmp_path))
+    second_lookup = content_hash_store._state_file_path("session-a", str(tmp_path))
+    assert first_lookup == second_lookup
+
+
+def test_first_sight_allows_and_stores_a_fresh_dirty_test(tmp_path: Path) -> None:
+    candidate = _write_fresh_test_file(tmp_path)
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [candidate], "session-1", str(tmp_path), 600
+    )
+
+    assert is_allowed is True
+    state_file = content_hash_store._state_file_path("session-1", str(tmp_path))
+    state = json.loads(state_file.read_text())
+    assert content_hash_store._state_key_for(candidate) in state
+
+
+def test_first_sight_denies_when_test_evidence_is_missing(tmp_path: Path) -> None:
+    candidate = _write_fresh_test_file(tmp_path, content="orders = 'not a test'\n")
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [candidate], "session-2", str(tmp_path), 600
+    )
+
+    assert is_allowed is False
+
+
+def test_first_sight_denies_when_test_file_is_stale(tmp_path: Path) -> None:
+    candidate = _write_fresh_test_file(tmp_path)
+    stale_timestamp = time.time() - 700
+    os.utime(candidate, (stale_timestamp, stale_timestamp))
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [candidate], "session-3", str(tmp_path), 600
+    )
+
+    assert is_allowed is False
+
+
+def test_second_sight_denies_a_touch_that_leaves_content_unchanged(tmp_path: Path) -> None:
+    candidate = _write_fresh_test_file(tmp_path)
+    session_id, repository_root = "session-4", str(tmp_path)
+    assert content_hash_store.has_recorded_or_fresh_test(
+        [candidate], session_id, repository_root, 600
+    )
+    state_file = content_hash_store._state_file_path(session_id, repository_root)
+    state = json.loads(state_file.read_text())
+    candidate_key = content_hash_store._state_key_for(candidate)
+    state[candidate_key][content_hash_store.STORED_CHANGED_AT_KEY] -= 700
+    state_file.write_text(json.dumps(state))
+    candidate.touch()
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [candidate], session_id, repository_root, 600
+    )
+
+    assert is_allowed is False
+
+
+def test_second_sight_allows_when_content_actually_changed_after_the_window(
+    tmp_path: Path,
+) -> None:
+    candidate = _write_fresh_test_file(tmp_path)
+    session_id, repository_root = "session-5", str(tmp_path)
+    assert content_hash_store.has_recorded_or_fresh_test(
+        [candidate], session_id, repository_root, 600
+    )
+    state_file = content_hash_store._state_file_path(session_id, repository_root)
+    state = json.loads(state_file.read_text())
+    candidate_key = content_hash_store._state_key_for(candidate)
+    state[candidate_key][content_hash_store.STORED_CHANGED_AT_KEY] -= 700
+    state_file.write_text(json.dumps(state))
+    candidate.write_text("def test_fulfill(): assert True\n")
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [candidate], session_id, repository_root, 600
+    )
+
+    assert is_allowed is True
+
+
+def test_second_sight_allows_a_repeat_write_within_the_window_untouched(
+    tmp_path: Path,
+) -> None:
+    candidate = _write_fresh_test_file(tmp_path)
+    session_id, repository_root = "session-6", str(tmp_path)
+    assert content_hash_store.has_recorded_or_fresh_test(
+        [candidate], session_id, repository_root, 600
+    )
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [candidate], session_id, repository_root, 600
+    )
+
+    assert is_allowed is True
+
+
+def test_any_candidate_satisfying_the_gate_allows_the_write(tmp_path: Path) -> None:
+    stale_candidate = _write_fresh_test_file(tmp_path)
+    stale_timestamp = time.time() - 700
+    os.utime(stale_candidate, (stale_timestamp, stale_timestamp))
+    fresh_candidate = tmp_path / "orders_test.py"
+    fresh_candidate.write_text("def test_fulfill(): pass\n")
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [stale_candidate, fresh_candidate], "session-7", str(tmp_path), 600
+    )
+
+    assert is_allowed is True
+
+
+def test_denies_when_no_candidate_file_exists(tmp_path: Path) -> None:
+    missing_candidate = tmp_path / "test_missing.py"
+
+    is_allowed = content_hash_store.has_recorded_or_fresh_test(
+        [missing_candidate], "session-8", str(tmp_path), 600
+    )
+
+    assert is_allowed is False

package/hooks/blocking/tdd_enforcer_parts/tests/test_decisions.py

@@ -20,6 +20,18 @@ def test_build_deny_reason_points_exemption_guidance_at_entry_hook() -> None:
     assert "decisions.py" not in reason
 
 
+def test_build_deny_reason_names_content_not_only_modification_time() -> None:
+    reason = decisions.build_deny_reason(Path("pkg/orders.py"), [Path("pkg/test_orders.py")])
+    assert "content" in reason.lower()
+
+
+def test_build_deny_reason_covers_first_sight_and_stale_hash_and_names_the_fix() -> None:
+    reason = decisions.build_deny_reason(Path("pkg/orders.py"), [Path("pkg/test_orders.py")]).lower()
+    assert "fresh" in reason
+    assert "change" in reason
+    assert "touch" in reason
+
+
 def test_emit_allow_writes_allow_decision(capsys: pytest.CaptureFixture[str]) -> None:
     decisions.emit_allow()
     parsed = json.loads(capsys.readouterr().out)

package/hooks/blocking/tdd_enforcer_parts/tests/test_git_tracking.py

@@ -46,3 +46,66 @@ def test_absent_but_tracked_false_when_file_present(tmp_path: Path) -> None:
     _git(tmp_path, "add", "-A")
     _git(tmp_path, "commit", "-q", "-m", "init")
     assert git_tracking.is_absent_but_tracked(present) is False
+
+
+def test_has_uncommitted_change_from_head_true_for_untracked_file(tmp_path: Path) -> None:
+    _init_repository(tmp_path)
+    untracked = tmp_path / "test_orders.py"
+    untracked.write_text("def test_fulfill(): pass\n")
+    assert git_tracking.has_uncommitted_change_from_head(untracked) is True
+
+
+def test_has_uncommitted_change_from_head_true_for_tracked_modified_file(tmp_path: Path) -> None:
+    _init_repository(tmp_path)
+    tracked = tmp_path / "test_orders.py"
+    tracked.write_text("def test_fulfill(): pass\n")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-q", "-m", "init")
+    tracked.write_text("def test_fulfill(): assert True\n")
+    assert git_tracking.has_uncommitted_change_from_head(tracked) is True
+
+
+def test_has_uncommitted_change_from_head_false_for_tracked_clean_file(tmp_path: Path) -> None:
+    _init_repository(tmp_path)
+    tracked = tmp_path / "test_orders.py"
+    tracked.write_text("def test_fulfill(): pass\n")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-q", "-m", "init")
+    tracked.touch()
+    assert git_tracking.has_uncommitted_change_from_head(tracked) is False
+
+
+def test_has_uncommitted_change_from_head_true_outside_a_git_repository(tmp_path: Path) -> None:
+    stray = tmp_path / "test_orders.py"
+    stray.write_text("def test_fulfill(): pass\n")
+    assert git_tracking.has_uncommitted_change_from_head(stray) is True
+
+
+def test_has_uncommitted_change_from_head_true_for_staged_new_file_never_committed(
+    tmp_path: Path,
+) -> None:
+    """A brand-new file only ``git add``-ed carries content HEAD never had.
+
+    Regression guard: comparing the working tree to the index (rather than to
+    HEAD) reads a freshly staged file as unchanged, since staging makes the
+    index match the working tree exactly. That misses every staged-but-never-
+    committed file, which is exactly how a RED-step test file is staged.
+    """
+    _init_repository(tmp_path)
+    _git(tmp_path, "commit", "--allow-empty", "-q", "-m", "baseline")
+    staged_new_test = tmp_path / "test_orders.py"
+    staged_new_test.write_text("def test_fulfill(): pass\n")
+    _git(tmp_path, "add", "-A")
+    assert git_tracking.has_uncommitted_change_from_head(staged_new_test) is True
+
+
+def test_has_uncommitted_change_from_head_true_for_staged_modification(tmp_path: Path) -> None:
+    """A tracked test's staged edit still differs from HEAD, not only the index."""
+    _init_repository(tmp_path)
+    tracked = tmp_path / "test_orders.py"
+    tracked.write_text("def test_fulfill(): pass\n")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-q", "-m", "init")
+    tracked.write_text("def test_fulfill(): assert True\n")
+    _git(tmp_path, "add", "-A")
+    assert git_tracking.has_uncommitted_change_from_head(tracked) is True

package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py

@@ -222,6 +222,7 @@ def test_powershell_selects_the_shared_hooks_in_registration_order() -> None:
         "blocking/cursor_cli_python_misfire_blocker.py",
         "blocking/unscoped_search_blocker.py",
         "blocking/pii_prevention_blocker.py",
+        "blocking/pr_description_writer_gate.py",
     ]