claude-dev-env 8.10.0 → 8.11.0

package/hooks/blocking/tdd_enforcer.py

@@ -1,195 +0,0 @@
-"""BDD Automate-phase gate (production code touch).
-
-Blocks a write to a production source file when no matching test was modified
-within the freshness window, enforcing "TDD IS NON-NEGOTIABLE" from CLAUDE.md.
-The gate records each candidate test's content hash at every sighting and
-compares that hash on the next write. A first sighting requires content that
-differs from HEAD. A stored failing pytest run is read before that fallback
-and applies while the candidate's content still matches the stored hash.
-Each concern lives in a ``tdd_enforcer_parts`` submodule; this entry wires them
-into one PreToolUse gate and re-exports their surface for the test suite.
-"""
-
-import json
-import sys
-from pathlib import Path
-
-try:
-    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
-    _blocking_directory = str(Path(__file__).resolve().parent)
-    for each_bootstrap_directory in (_hooks_root_directory, _blocking_directory):
-        if each_bootstrap_directory not in sys.path:
-            sys.path.insert(0, each_bootstrap_directory)
-    from code_rules_shared import (
-        is_agent_home_tooling,
-        is_ephemeral_script_path,
-        is_under_session_scratchpad,
-    )
-    from codex_apply_patch import (
-        payload_patch_target_paths,
-    )
-    from hooks_constants.pre_tool_use_dispatcher_constants import APPLY_PATCH_TOOL_NAME
-    from tdd_enforcer_parts import (
-        candidate_paths,
-        content_analysis,
-        content_hash_store,
-        decisions,
-        freshness,
-        git_tracking,
-        path_classification,
-    )
-    from tdd_enforcer_parts.config.tdd_enforcer_constants import PYTHON_SOURCE_EXTENSION
-except ImportError as import_error:
-    raise ImportError(
-        "tdd_enforcer: cannot import its tdd_enforcer_parts submodules; "
-        "ensure the hooks directory is importable."
-    ) from import_error
-
-
-def _is_session_scratchpad_write(file_path: str, input_data: dict) -> bool:
-    return is_under_session_scratchpad(file_path, input_data)
-
-
-def _is_agent_home_tooling_write(file_path: str) -> bool:
-    """A coding agent's own home-directory tooling is outside the TDD gate."""
-    return is_agent_home_tooling(file_path)
-
-
-production_extensions = path_classification.production_extensions
-skip_extensions = path_classification.skip_extensions
-_is_inside_dotclaude_segment = path_classification._is_inside_dotclaude_segment
-_directory_skip_components = path_classification._directory_skip_components
-_matches_any_skip_pattern = path_classification._matches_any_skip_pattern
-_extract_written_content = path_classification._extract_written_content
-candidate_test_paths_for = candidate_paths.candidate_test_paths_for
-_ancestor_tests_directories = candidate_paths._ancestor_tests_directories
-_parent_walk_limit = candidate_paths._parent_walk_limit
-_freshness_seconds = freshness._freshness_seconds
-_read_candidate_text = freshness._read_candidate_text
-has_recorded_or_fresh_test = content_hash_store.has_recorded_or_fresh_test
-_is_constants_only_python_content = content_analysis._is_constants_only_python_content
-_is_post_edit_import_only = content_analysis._is_post_edit_import_only
-_is_post_edit_constants_only = content_analysis._is_post_edit_constants_only
-is_absent_but_tracked = git_tracking.is_absent_but_tracked
-build_deny_reason = decisions.build_deny_reason
-emit_allow = decisions.emit_allow
-emit_deny = decisions.emit_deny
-
-
-def _resolve_payload(input_data: dict) -> tuple[str, dict, str]:
-    tool_input = input_data.get("tool_input", {})
-    return input_data.get("tool_name", ""), tool_input, tool_input.get("file_path", "")
-
-
-def _is_silently_skipped(
-    file_path: str, extension: str, path: Path, repository_root: str = ""
-) -> bool:
-    if _is_inside_dotclaude_segment(file_path) or is_ephemeral_script_path(
-        file_path, repository_root
-    ):
-        return True
-    if _is_agent_home_tooling_write(file_path):
-        return True
-    if extension in skip_extensions():
-        return True
-    if extension not in production_extensions():
-        return True
-    path_with_forward_slashes = str(path).lower().replace("\\", "/")
-    return _matches_any_skip_pattern(path.name.lower(), path_with_forward_slashes)
-
-
-def _edit_is_constants_or_import_only(
-    tool_name: str, tool_input: dict, path: Path, extension: str
-) -> bool:
-    if (
-        tool_name not in ("Edit", "MultiEdit")
-        or extension != PYTHON_SOURCE_EXTENSION
-        or not path.exists()
-    ):
-        return False
-    existing_content = _read_candidate_text(path)
-    if existing_content is None:
-        return False
-    if _is_post_edit_import_only(existing_content, tool_name, tool_input):
-        return True
-    return _is_post_edit_constants_only(existing_content, tool_name, tool_input)
-
-
-def _write_is_exempt(
-    tool_name: str, tool_input: dict, path: Path, extension: str
-) -> bool:
-    if is_absent_but_tracked(path):
-        return True
-    written_content = _extract_written_content(tool_name, tool_input)
-    if (
-        tool_name == "Write"
-        and extension == PYTHON_SOURCE_EXTENSION
-        and _is_constants_only_python_content(written_content)
-    ):
-        return True
-    return _edit_is_constants_or_import_only(tool_name, tool_input, path, extension)
-
-
-def _decide_for_target(
-    tool_name: str, tool_input: dict, file_path: str, input_data: dict
-) -> tuple[bool, str] | None:
-    """Return (is_allowed, deny_reason) for one target file, or None to skip silently."""
-    if not file_path:
-        return None
-    if _is_session_scratchpad_write(file_path, input_data):
-        return None
-    path = Path(file_path)
-    extension = path.suffix.lower()
-    repository_root = str(input_data.get("cwd") or "")
-    if _is_silently_skipped(file_path, extension, path, repository_root):
-        return None
-    if _write_is_exempt(tool_name, tool_input, path, extension):
-        return True, ""
-    all_candidates = candidate_test_paths_for(path)
-    session_id = str(input_data.get("session_id") or "")
-    is_recorded_or_fresh = has_recorded_or_fresh_test(
-        all_candidates, session_id, repository_root, _freshness_seconds()
-    )
-    if is_recorded_or_fresh:
-        return True, ""
-    return False, build_deny_reason(path, all_candidates)
-
-
-def _decide_apply_patch(input_data: dict, tool_input: dict) -> None:
-    """Run the TDD gate over every file a Codex apply_patch payload touches."""
-    for each_file_path in payload_patch_target_paths(input_data, tool_input):
-        decision = _decide_for_target(
-            APPLY_PATCH_TOOL_NAME, tool_input, each_file_path, input_data
-        )
-        if decision is None:
-            continue
-        is_allowed, deny_reason = decision
-        if not is_allowed:
-            emit_deny(deny_reason)
-            return
-    emit_allow()
-
-
-def main() -> None:
-    """Run the TDD gate over one PreToolUse Write, Edit, MultiEdit, or apply_patch payload."""
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-    tool_name, tool_input, file_path = _resolve_payload(input_data)
-    if tool_name == APPLY_PATCH_TOOL_NAME:
-        _decide_apply_patch(input_data, tool_input)
-        sys.exit(0)
-    decision = _decide_for_target(tool_name, tool_input, file_path, input_data)
-    if decision is None:
-        sys.exit(0)
-    is_allowed, deny_reason = decision
-    if is_allowed:
-        emit_allow()
-        sys.exit(0)
-    emit_deny(deny_reason)
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/blocking/tdd_enforcer_parts/candidate_paths.py

@@ -1,142 +0,0 @@
-"""Resolve the test files whose freshness can satisfy the gate for a module.
-
-Given a production file, builds every path a matching test could live at: the
-flat sibling ``test_<stem>.py``, the package-mirroring candidates under an
-ancestor ``tests`` directory, and the split test family for ``code_rules_*``
-modules.
-"""
-
-from pathlib import Path
-
-from tdd_enforcer_parts.config.tdd_enforcer_constants import (
-    ALL_JAVASCRIPT_TEST_EXTENSIONS,
-    ALL_REPO_BOUNDARY_SENTINELS,
-    PARENT_WALK_LIMIT,
-    PYTHON_SOURCE_EXTENSION,
-)
-
-
-def _tests_directory_name() -> str:
-    return "tests"
-
-
-def _parent_walk_limit() -> int:
-    return PARENT_WALK_LIMIT
-
-
-def _repo_boundary_sentinels() -> frozenset[str]:
-    return ALL_REPO_BOUNDARY_SENTINELS
-
-
-def _split_module_stem_prefix() -> str:
-    return "code_rules_"
-
-
-def _split_test_family_glob() -> str:
-    return "test_code_rules_enforcer_*.py"
-
-
-def _javascript_test_extensions() -> frozenset[str]:
-    return ALL_JAVASCRIPT_TEST_EXTENSIONS
-
-
-def _is_repo_boundary(candidate_directory: Path) -> bool:
-    for each_sentinel in _repo_boundary_sentinels():
-        if (candidate_directory / each_sentinel).exists():
-            return True
-    return False
-
-
-def _ancestor_tests_directories(start_directory: Path) -> list[tuple[Path, Path]]:
-    """Collect each ancestor's sibling ``tests`` directory up to the repo root.
-
-    Args:
-        start_directory: Directory of the production file under edit.
-
-    Returns:
-        Ordered ``(ancestor, tests_directory)`` pairs, nearer ancestors first.
-    """
-    all_pairs: list[tuple[Path, Path]] = []
-    current_directory = start_directory
-    remaining_steps = _parent_walk_limit()
-    while remaining_steps > 0:
-        remaining_steps -= 1
-        sibling_tests = current_directory / _tests_directory_name()
-        if sibling_tests.is_dir():
-            all_pairs.append((current_directory, sibling_tests))
-        if _is_repo_boundary(current_directory):
-            break
-        if current_directory.parent == current_directory:
-            break
-        current_directory = current_directory.parent
-    return all_pairs
-
-
-def _split_family_candidates(directory: Path, stem: str) -> list[Path]:
-    if not stem.startswith(_split_module_stem_prefix()):
-        return []
-    return sorted(directory.glob(_split_test_family_glob()))
-
-
-def _flat_stem_candidates(directory: Path, stem: str) -> list[Path]:
-    return [directory / f"test_{stem}.py", directory / f"{stem}_test.py"]
-
-
-def _mirrored_nested_candidates(
-    directory: Path, ancestor: Path, tests_directory: Path, stem: str
-) -> list[Path]:
-    all_candidates: list[Path] = []
-    nested_directory = tests_directory
-    for each_relative_part in directory.relative_to(ancestor).parts:
-        nested_directory = nested_directory / each_relative_part
-        all_candidates.append(nested_directory / f"test_{stem}.py")
-    return all_candidates
-
-
-def _nested_tests_candidates(directory: Path, stem: str) -> list[Path]:
-    all_candidates: list[Path] = []
-    for each_ancestor, each_tests_directory in _ancestor_tests_directories(directory):
-        all_candidates.append(each_tests_directory / f"test_{stem}.py")
-        all_candidates.extend(
-            _mirrored_nested_candidates(directory, each_ancestor, each_tests_directory, stem)
-        )
-    return all_candidates
-
-
-def _python_candidate_test_paths(directory: Path, stem: str) -> list[Path]:
-    all_candidates = _flat_stem_candidates(directory, stem)
-    all_candidates.extend(_nested_tests_candidates(directory, stem))
-    all_candidates.extend(_split_family_candidates(directory, stem))
-    return all_candidates
-
-
-def _javascript_candidate_test_paths(directory: Path, stem: str, extension: str) -> list[Path]:
-    return [directory / f"{stem}.test{extension}", directory / f"{stem}.spec{extension}"]
-
-
-def candidate_test_paths_for(production_path: Path) -> list[Path]:
-    """Return the test files that can satisfy the gate for a production file.
-
-    ::
-
-        pkg/orders.py -> pkg/test_orders.py, pkg/orders_test.py,
-                         pkg/tests/test_orders.py (and package mirrors)
-
-    ``code_rules_*`` Python modules also gain the split test family. Plain
-    stem-derived candidates always come first.
-
-    Args:
-        production_path: The production source file being written or edited.
-
-    Returns:
-        Ordered candidate test paths; stem-derived siblings precede any
-        split-family additions.
-    """
-    directory = production_path.parent
-    stem = production_path.stem
-    extension = production_path.suffix.lower()
-    if extension == PYTHON_SOURCE_EXTENSION:
-        return _python_candidate_test_paths(directory, stem)
-    if extension in _javascript_test_extensions():
-        return _javascript_candidate_test_paths(directory, stem, extension)
-    return []

package/hooks/blocking/tdd_enforcer_parts/config/__init__.py

@@ -1 +0,0 @@
-"""Configuration home for the TDD-enforcer parts constants."""

package/hooks/blocking/tdd_enforcer_parts/config/tdd_enforcer_constants.py

@@ -1,49 +0,0 @@
-"""Constants for the TDD-enforcer hook and its decomposed parts modules.
-
-Centralizes the freshness window, the ancestor-walk limit, the git-tracking
-and git-diff command tokens, the source-file extension sets, the join
-separator, and the last-observed-hash store's filename shape and JSON keys.
-The store's JSON keys also cover a recorded failing-test-run entry: the test
-file's content hash at failure time, the failure timestamp, the failing
-command, and its exit status.
-"""
-
-from __future__ import annotations
-
-FRESHNESS_WINDOW_SECONDS: int = 600
-PARENT_WALK_LIMIT: int = 10
-GIT_LS_FILES_TIMEOUT_SECONDS: int = 10
-GIT_DIFF_TIMEOUT_SECONDS: int = 10
-GIT_EXECUTABLE_NAME: str = "git"
-GIT_LS_FILES_SUBCOMMAND: str = "ls-files"
-GIT_DIFF_SUBCOMMAND: str = "diff"
-GIT_DIFF_QUIET_FLAG: str = "--quiet"
-GIT_HEAD_REVISION: str = "HEAD"
-GIT_PATHSPEC_SEPARATOR: str = "--"
-HASH_STATE_FILE_PREFIX: str = "claude-tdd-test-hashes-"
-HASH_STATE_FILE_SUFFIX: str = ".json"
-REPOSITORY_ROOT_DIGEST_LENGTH: int = 16
-STORED_CONTENT_HASH_KEY: str = "hash"
-STORED_CHANGED_AT_KEY: str = "changed_at"
-STORED_FAILURE_HASH_KEY: str = "failed_hash"
-STORED_FAILED_AT_KEY: str = "failed_at"
-STORED_FAILURE_COMMAND_KEY: str = "failed_command"
-STORED_FAILURE_EXIT_STATUS_KEY: str = "failed_exit_status"
-PYTHON_SOURCE_EXTENSION: str = ".py"
-ENTRY_HOOK_FILE_NAME: str = "tdd_enforcer.py"
-NEWLINE_JOIN_SEPARATOR: str = "\n"
-ALL_PRODUCTION_EXTENSIONS: frozenset[str] = frozenset({".py", ".ts", ".tsx", ".js", ".jsx"})
-ALL_SKIP_EXTENSIONS: frozenset[str] = frozenset(
-    {".md", ".json", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".txt"}
-)
-ALL_SKIP_NAME_PATTERNS: frozenset[str] = frozenset(
-    {"test_", "_test.", ".test.", "tests/", "__tests__/", "conftest", "fixture", "mock", "stub"}
-)
-ALL_DIRECTORY_SKIP_COMPONENTS: frozenset[str] = frozenset(
-    {"conftest", "fixture", "fixtures", "mock", "mocks", "stub", "stubs"}
-)
-ALL_DOTCLAUDE_PATH_SEGMENTS: frozenset[str] = frozenset({".claude"})
-ALL_REPO_BOUNDARY_SENTINELS: frozenset[str] = frozenset(
-    {".git", "pyproject.toml", "package.json", "Cargo.toml", "go.mod"}
-)
-ALL_JAVASCRIPT_TEST_EXTENSIONS: frozenset[str] = frozenset({".tsx", ".ts", ".jsx", ".js"})

package/hooks/blocking/tdd_enforcer_parts/content_hash_store.py

@@ -1,298 +0,0 @@
-"""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.state_file_lock import hold_state_file_lock
-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,
-    STORED_FAILED_AT_KEY,
-    STORED_FAILURE_COMMAND_KEY,
-    STORED_FAILURE_EXIT_STATUS_KEY,
-    STORED_FAILURE_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 _has_matching_recorded_failure(
-    stored_entry: object, current_hash: str, current_time: float, freshness_seconds: int
-) -> bool:
-    """Return whether a recorded test failure still evidences the candidate's content.
-
-    A failure counts as evidence only while the candidate's content is
-    exactly what failed and the record has not aged past the freshness
-    window -- editing the test again, or letting the record go stale, drops
-    it as evidence and falls back to the ordinary content-hash tracking.
-    """
-    if not isinstance(stored_entry, dict):
-        return False
-    if stored_entry.get(STORED_FAILURE_HASH_KEY) != current_hash:
-        return False
-    failed_at = stored_entry.get(STORED_FAILED_AT_KEY)
-    if not isinstance(failed_at, (int, float)):
-        return False
-    return current_time - failed_at <= freshness_seconds
-
-
-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 _first_sight_decision(
-    candidate_path: Path,
-    candidate_text: str,
-    current_time: float,
-    freshness_seconds: int,
-    current_hash: str,
-) -> tuple[bool, dict[str, object] | None]:
-    if not _is_qualifying_first_sight(
-        candidate_path, candidate_text, current_time, freshness_seconds
-    ):
-        return False, None
-    return True, _recorded_entry(current_hash, current_time)
-
-
-def _content_hash_decision(
-    all_stored_entry_fields: dict[str, object],
-    current_hash: str,
-    current_time: float,
-    freshness_seconds: int,
-) -> tuple[bool, dict[str, object] | None]:
-    if current_hash != all_stored_entry_fields.get(STORED_CONTENT_HASH_KEY):
-        return True, _recorded_entry(current_hash, current_time)
-    stored_changed_at = all_stored_entry_fields.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 _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 _has_matching_recorded_failure(
-        stored_entry, current_hash, current_time, freshness_seconds
-    ):
-        return True, None
-    if not isinstance(stored_entry, dict) or STORED_CONTENT_HASH_KEY not in stored_entry:
-        return _first_sight_decision(
-            candidate_path, candidate_text, current_time, freshness_seconds, current_hash
-        )
-    return _content_hash_decision(stored_entry, current_hash, current_time, freshness_seconds)
-
-
-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 carries a matching recorded test
-        failure, is a fresh dirty first sighting, has a recorded hash that
-        now differs, or has a recorded hash still in window.
-    """
-    state_file = _state_file_path(session_id, repository_root)
-    with hold_state_file_lock(state_file):
-        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
-
-
-def _merged_failure_entry(
-    existing_entry: object,
-    candidate_text: str,
-    command: str,
-    exit_status: int,
-    current_time: float,
-) -> dict[str, object]:
-    merged_entry = dict(existing_entry) if isinstance(existing_entry, dict) else {}
-    merged_entry[STORED_FAILURE_HASH_KEY] = _content_hash(candidate_text)
-    merged_entry[STORED_FAILED_AT_KEY] = current_time
-    merged_entry[STORED_FAILURE_COMMAND_KEY] = command
-    merged_entry[STORED_FAILURE_EXIT_STATUS_KEY] = exit_status
-    return merged_entry
-
-
-def _record_one_test_file_failure(
-    test_file_path: Path,
-    all_stored_hashes: dict[str, object],
-    command: str,
-    exit_status: int,
-    current_time: float,
-) -> bool:
-    candidate_text = freshness._read_candidate_text(test_file_path)
-    if candidate_text is None:
-        return False
-    candidate_key = _state_key_for(test_file_path)
-    all_stored_hashes[candidate_key] = _merged_failure_entry(
-        all_stored_hashes.get(candidate_key),
-        candidate_text,
-        command,
-        exit_status,
-        current_time,
-    )
-    return True
-
-
-def record_test_command_failure(
-    all_test_file_paths: list[Path],
-    command: str,
-    exit_status: int,
-    session_id: str,
-    repository_root: str,
-) -> None:
-    """Record a failing test command as gate evidence, one entry per test file.
-
-    Keyed exactly as the gate looks candidates up, so a failure satisfies the
-    gate only for the file it names, never a sibling the command also ran.
-    Existing content-hash fields on that entry are preserved, not overwritten.
-    """
-    state_file = _state_file_path(session_id, repository_root)
-    current_time = time.time()
-    with hold_state_file_lock(state_file):
-        all_stored_hashes = _load_state(state_file)
-        all_recorded = [
-            _record_one_test_file_failure(
-                each_path, all_stored_hashes, command, exit_status, current_time
-            )
-            for each_path in all_test_file_paths
-        ]
-        if any(all_recorded):
-            _atomic_write_state(state_file, all_stored_hashes)