claude-dev-env 2.31.1 → 2.33.0

package/hooks/blocking/javascript_comment_scanner.py

@@ -0,0 +1,99 @@
+"""Extract JavaScript comments without matching comment-like strings."""
+
+import io
+import re
+import tokenize
+from typing import NamedTuple
+
+from hooks_constants.code_rules_enforcer_constants import (
+    ALL_JAVASCRIPT_EXEMPT_COMMENT_PREFIXES,
+    ALL_JAVASCRIPT_EXEMPT_INLINE_COMMENT_PREFIXES,
+    ALL_PYTHON_TOKENIZE_FAILURE_EXCEPTIONS,
+)
+
+
+class JavaScriptCommentOccurrence(NamedTuple):
+    """One JavaScript comment with its source line and placement."""
+
+    text: str
+    line_number: int
+    is_inline: bool
+
+
+def _mask_javascript_strings(content: str) -> str:
+    """Replace quoted JavaScript strings while preserving source positions."""
+    string_pattern = r'''("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`)'''
+    return re.sub(
+        string_pattern,
+        lambda each_match: "".join(
+            "\n" if each_character == "\n" else " "
+            for each_character in each_match.group()
+        ),
+        content,
+        flags=re.DOTALL,
+    )
+
+
+def _is_allowed_comment(
+    comment_text: str, is_inline: bool, include_directive_comments: bool
+) -> bool:
+    """Return whether a comment is excluded from the policy comparison."""
+    if comment_text.startswith("/**"):
+        return True
+    if include_directive_comments:
+        return False
+    prefixes = (
+        ALL_JAVASCRIPT_EXEMPT_INLINE_COMMENT_PREFIXES
+        if is_inline
+        else ALL_JAVASCRIPT_EXEMPT_COMMENT_PREFIXES
+    )
+    comment_body = (
+        comment_text.removeprefix("//").lstrip()
+        if comment_text.startswith("//")
+        else comment_text
+    )
+    return comment_body.startswith(prefixes)
+
+
+def extract_javascript_comment_occurrences(
+    content: str, include_directive_comments: bool
+) -> list[JavaScriptCommentOccurrence]:
+    """Return real JavaScript comment occurrences with exact line numbers."""
+    masked_content = _mask_javascript_strings(content)
+    all_occurrences: list[JavaScriptCommentOccurrence] = []
+    for each_match in re.finditer(r"//[^\n]*|/\*[\s\S]*?\*/", masked_content):
+        comment_text = content[each_match.start() : each_match.end()].strip()
+        line_start = masked_content.rfind("\n", 0, each_match.start()) + 1
+        is_inline = bool(masked_content[line_start : each_match.start()].strip())
+        if _is_allowed_comment(comment_text, is_inline, include_directive_comments):
+            continue
+        line_number = content.count("\n", 0, each_match.start()) + 1
+        all_occurrences.append(
+            JavaScriptCommentOccurrence(comment_text, line_number, is_inline)
+        )
+    return all_occurrences
+
+
+def extract_python_comment_occurrences(
+    content: str,
+) -> tuple[list[JavaScriptCommentOccurrence], bool]:
+    """Return Python comments with exact lines and a tokenize status."""
+    source_lines = content.split("\n")
+    try:
+        all_tokens = list(tokenize.generate_tokens(io.StringIO(content).readline))
+    except ALL_PYTHON_TOKENIZE_FAILURE_EXCEPTIONS:
+        return [], False
+    all_occurrences: list[JavaScriptCommentOccurrence] = []
+    for each_token in all_tokens:
+        if each_token.type != tokenize.COMMENT:
+            continue
+        if each_token.string.startswith("#!") and each_token.start == (1, 0):
+            continue
+        source_line = source_lines[each_token.start[0] - 1]
+        is_inline = bool(source_line[: each_token.start[1]].strip())
+        all_occurrences.append(
+            JavaScriptCommentOccurrence(
+                each_token.string.strip(), each_token.start[0], is_inline
+            )
+        )
+    return all_occurrences, True

package/hooks/blocking/shell_substitution_blocker.py

@@ -23,6 +23,12 @@ ignored because bash performs no substitution inside them (for example
 are treated as literal only when the count of preceding backslashes is odd;
 an even count (including zero) means the backtick is a live substitution.
 
+A quoted heredoc body is stripped for the same reason. `<<'EOF'`, `<<"EOF"`
+and `<<\\EOF` each tell bash to expand nothing between the opener and the
+terminator, so a backtick there is text the file receives rather than a
+command the shell runs. A bare `<<EOF` expands its body and keeps its scan,
+and text outside any heredoc is scanned either way.
+
 Bash arithmetic expansion ``$((...))`` is explicitly NOT blocked: it does not
 spawn a subshell and does not defeat the allowlist matcher. Telling it apart
 from a disguised command substitution takes more than counting two open
@@ -41,11 +47,6 @@ another ``)`` (an ``))`` pair), the expansion is arithmetic and passes. When
 the closer that brings depth to zero is a lone ``)``, bash has fallen back to
 running a parenthesized command inside the substitution, so it is blocked.
 This hook applies that walk, tracking paren depth from the opening ``$((``.
-
-False positives are still possible when the user is intentionally writing
-shell-script content (for example, authoring a .sh file via heredoc) and the
-substitution is literal payload rather than something to execute. In that
-case, author the file with the Write tool, not a Bash heredoc.
 """
 
 from __future__ import annotations
@@ -53,6 +54,7 @@ from __future__ import annotations
 import json
 import sys
 from pathlib import Path
+from re import Match
 
 _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
@@ -74,6 +76,11 @@ from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
     PERMISSION_DECISION_KEY,
     PERMISSION_DECISION_REASON_KEY,
     PROCESS_SUBSTITUTION_PATTERN,
+    BACKSLASH_CHARACTER,
+    COMMAND_LINE_SEPARATOR,
+    DOUBLE_QUOTE_CHARACTER,
+    NO_TERMINATOR_INDEX,
+    SINGLE_QUOTE_CHARACTER,
     SINGLE_QUOTED_RUN_PATTERN,
     STRIPPED_RUN_REPLACEMENT,
     TOOL_INPUT_KEY,
@@ -81,10 +88,169 @@ from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
 )
 
 
+from hooks_constants.piped_pytest_blocker_constants import (  # noqa: E402
+    HEREDOC_ESCAPE_GROUP,
+    HEREDOC_OPENER_PATTERN,
+    HEREDOC_QUOTE_GROUP,
+    HEREDOC_TAB_STRIP_GROUP,
+    HEREDOC_TAB_STRIP_MARKER,
+    HEREDOC_TERMINATOR_GROUP,
+    HEREDOC_UNQUOTED_MARKER,
+)
+from hooks_constants.shell_command_pipeline import (  # noqa: E402
+    PendingHeredoc,
+    closes_the_heredoc,
+)
+
+
 def _strip_single_quoted_runs(command: str) -> str:
     return SINGLE_QUOTED_RUN_PATTERN.sub(STRIPPED_RUN_REPLACEMENT, command)
 
 
+def _opener_suppresses_expansion(opener_match: Match[str]) -> bool:
+    """Return whether an opener's delimiter is quoted or backslash-escaped.
+
+    ::
+
+        <<'EOF'  -> True   quoted, the body is literal
+        <<EOF    -> False  bare, bash expands the body
+
+    Args:
+        opener_match: One HEREDOC_OPENER_PATTERN match from a command line.
+
+    Returns:
+        True when bash expands nothing down to this opener's terminator.
+    """
+    is_quoted = opener_match.group(HEREDOC_QUOTE_GROUP) != HEREDOC_UNQUOTED_MARKER
+    is_escaped = opener_match.group(HEREDOC_ESCAPE_GROUP) != HEREDOC_UNQUOTED_MARKER
+    return is_quoted or is_escaped
+
+
+def _sits_outside_quotes(command_line: str, character_index: int) -> bool:
+    """Return whether a position on a line sits outside every quoted run.
+
+    ::
+
+        cat <<'EOF'      index of << -> True   bash reads an opener
+        echo "<<'EOF'"   index of << -> False  bash reads a string
+
+    Counting unescaped quotes before the position tells the two apart: an even
+    count of each quote character means every run opened before it also closed.
+
+    Args:
+        command_line: One line of the command.
+        character_index: Position of the candidate opener on that line.
+
+    Returns:
+        True when bash reads this position as shell syntax.
+    """
+    single_quote_count = 0
+    double_quote_count = 0
+    is_escaped = False
+    for each_character in command_line[:character_index]:
+        if is_escaped:
+            is_escaped = False
+            continue
+        if each_character == BACKSLASH_CHARACTER:
+            is_escaped = True
+            continue
+        if each_character == SINGLE_QUOTE_CHARACTER:
+            single_quote_count += 1
+        elif each_character == DOUBLE_QUOTE_CHARACTER:
+            double_quote_count += 1
+    return single_quote_count % 2 == 0 and double_quote_count % 2 == 0
+
+
+def _first_literal_opener(command_line: str) -> Match[str] | None:
+    """Return the line's first heredoc opener whose body bash leaves literal.
+
+    An opener spelled inside a quoted string is text bash passes on, so it
+    opens nothing and the lines below it stay in the scan.
+
+    Args:
+        command_line: One line of the command.
+
+    Returns:
+        The matching opener, or None when the line opens no literal heredoc.
+    """
+    for each_opener in HEREDOC_OPENER_PATTERN.finditer(command_line):
+        if not _sits_outside_quotes(command_line, each_opener.start()):
+            continue
+        if _opener_suppresses_expansion(each_opener):
+            return each_opener
+    return None
+
+
+def _index_past_literal_body(
+    all_lines: list[str], body_start_index: int, opener_match: Match[str]
+) -> int:
+    """Return the index of the line that closes a literal heredoc body.
+
+    The terminator match, including the ``<<-`` tab-strip rule, comes from
+    ``closes_the_heredoc`` so this hook and the shared pipeline agree on what
+    ends a body.
+
+    Args:
+        all_lines: Every line of the command.
+        body_start_index: Index of the body's first line.
+        opener_match: The opener whose terminator closes this body.
+
+    Returns:
+        The index of the terminator line, or NO_TERMINATOR_INDEX when the
+        command holds none.
+    """
+    pending_heredoc = PendingHeredoc(
+        terminator=opener_match.group(HEREDOC_TERMINATOR_GROUP),
+        allows_leading_tabs=(
+            opener_match.group(HEREDOC_TAB_STRIP_GROUP) == HEREDOC_TAB_STRIP_MARKER
+        ),
+    )
+    for each_index in range(body_start_index, len(all_lines)):
+        if closes_the_heredoc(all_lines[each_index], pending_heredoc):
+            return each_index
+    return NO_TERMINATOR_INDEX
+
+
+def _strip_quoted_heredoc_bodies(command: str) -> str:
+    """Return the command holding its openers, terminators, and shell text.
+
+    ::
+
+        cat <<'EOF'        ->  cat <<'EOF'
+        inert text             EOF
+        EOF
+
+    A quoted or escaped delimiter makes the lines below it text the shell hands
+    on, so a scan of those lines reports a substitution bash never runs. A bare
+    delimiter keeps its body, and text outside any heredoc keeps its scan.
+
+    An opener with no terminator returns the command whole. Bash consumes the
+    rest of the input in that case, and dropping those lines would hide a live
+    substitution among them.
+
+    Args:
+        command: The raw Bash command string from the tool input.
+
+    Returns:
+        The command with each literal heredoc body dropped.
+    """
+    all_lines = command.split(COMMAND_LINE_SEPARATOR)
+    all_kept_lines: list[str] = []
+    each_index = 0
+    while each_index < len(all_lines):
+        current_line = all_lines[each_index]
+        all_kept_lines.append(current_line)
+        each_index += 1
+        opener_match = _first_literal_opener(current_line)
+        if opener_match is None:
+            continue
+        terminator_index = _index_past_literal_body(all_lines, each_index, opener_match)
+        if terminator_index == NO_TERMINATOR_INDEX:
+            return command
+        each_index = terminator_index
+    return COMMAND_LINE_SEPARATOR.join(all_kept_lines)
+
+
 def _closes_as_arithmetic_expansion(command: str, scan_start_index: int) -> bool:
     """Return True when a ``$((`` expansion closes on an ``))`` pair.
 
@@ -132,8 +298,9 @@ def has_shell_substitution(command: str) -> bool:
         echo '$(not-executed)'         ok:   single-quoted, inert
         echo $((2 + 2))                ok:   arithmetic expansion
 
-    Single-quoted runs are stripped first because bash substitutes nothing
-    inside them. A backtick preceded by an odd backslash count is escaped.
+    Literal heredoc bodies are dropped first, then single-quoted runs are
+    stripped, because bash substitutes nothing inside either. A backtick
+    preceded by an odd backslash count is escaped.
     A `$((` pair is walked to its terminator (module docstring) to tell
     real arithmetic from a disguised subshell.
 
@@ -143,7 +310,7 @@ def has_shell_substitution(command: str) -> bool:
     Returns:
         True when a substitution the matcher cannot descend into is present.
     """
-    scannable_command = _strip_single_quoted_runs(command)
+    scannable_command = _strip_single_quoted_runs(_strip_quoted_heredoc_bodies(command))
     if _has_unsafe_dollar_paren_expansion(scannable_command):
         return True
     if EVEN_BACKSLASH_BACKTICK_PATTERN.search(scannable_command):

package/hooks/blocking/stop_dispatcher.py

@@ -12,11 +12,14 @@ from __future__ import annotations
 
 import json
 import sys
-from pathlib import Path
 
 import _path_setup  # noqa: F401
 
-from hooks_constants.hosted_hook_runner import HostedHookRun, run_hook_capturing_output
+from hooks_constants.hosted_hook_runner import (
+    run_hook_capturing_output,
+    HostedHookRun,
+    resolved_hook_script_path,
+)
 from hooks_constants.stop_dispatcher_constants import (
     ALL_STOP_HOSTED_HOOK_PATHS,
     BLOCK_DECISION,
@@ -24,12 +27,6 @@ from hooks_constants.stop_dispatcher_constants import (
 )
 
 
-def _resolve_hook_script_path(relative_path: str) -> str:
-    """Resolve a hooks/-relative path to an absolute script path."""
-    hooks_root = Path(__file__).resolve().parent.parent
-    return str(hooks_root / relative_path)
-
-
 def _is_block_decision(stdout_text: str) -> bool:
     """Return True when stdout carries a Stop decision of block."""
     stripped_text = stdout_text.strip()
@@ -58,7 +55,7 @@ def dispatch(payload_text: str) -> None:
     """Run every Stop hosted hook and emit the first block decision if any."""
     all_runs: list[HostedHookRun] = []
     for each_relative_path in ALL_STOP_HOSTED_HOOK_PATHS:
-        script_path = _resolve_hook_script_path(each_relative_path)
+        script_path = resolved_hook_script_path(each_relative_path)
         hook_run = run_hook_capturing_output(script_path, payload_text)
         all_runs.append(hook_run)
     block_stdout = select_first_block_stdout(all_runs)

package/hooks/blocking/tdd_enforcer.py

@@ -4,7 +4,9 @@ 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.
+differs from HEAD. A recorded failing pytest run, written by
+``hooks/observability/test_failure_recorder.py``, is read before that fallback
+and applies while the candidate's content still matches what failed.
 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.
 """

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

@@ -3,6 +3,9 @@
 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
@@ -22,6 +25,10 @@ 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"

package/hooks/blocking/tdd_enforcer_parts/content_hash_store.py

@@ -30,6 +30,7 @@ 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,
@@ -45,6 +46,10 @@ from tdd_enforcer_parts.config.tdd_enforcer_constants import (
     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,
 )
 
 
@@ -96,6 +101,26 @@ 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:
@@ -107,6 +132,34 @@ def _is_qualifying_first_sight(
     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,
@@ -117,18 +170,15 @@ def _evaluate_candidate(
     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
+    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(
@@ -142,7 +192,10 @@ def _apply_candidate_decisions(
     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
+            each_candidate,
+            all_stored_hashes.get(candidate_key),
+            current_time,
+            freshness_seconds,
         )
         if candidate_allowed:
             is_allowed = True
@@ -162,19 +215,84 @@ def has_recorded_or_fresh_test(
 
     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.
+        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.
+        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)
-    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)
+    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)