claude-dev-env 2.7.1 → 2.8.0

package/hooks/git-hooks/pre_push.py

@@ -15,20 +15,31 @@ branch is blocked before the gate runs. This catches a branch that tracks
 resolves to `main`. The guard runs whether or not the CODE_RULES gate is
 installed; deletions and same-name pushes pass.
 
-Gate base: the first non-zero remote-sha is used as the gate `--base`, so
-violations are scoped to commits that are not already on the remote. When
-every remote object name is zero (new branch) or stdin is empty, the gate
-falls back to the default branch of the remote git names in argv: its
-symbolic ref first, then the first candidate default branch that exists
-under that remote.
+Gate base: a branch push takes its `--base` from the merge base between the
+pushed object and the remote default branch, so a rebase onto the default
+branch leaves the gate reading only the branch's own work. The stdin remote
+object name is the base when no default-branch ref resolves and when the
+pushed branch is the default branch. When every remote object name is zero
+(new branch) or stdin is empty, the gate falls back to the remote's default
+branch symbolic ref. When a default-branch ref resolves and git still reports
+no merge base, the base is unknown, so CODE_RULES enforcement is skipped with
+a printed reason rather than scoped to the stdin remote object name, which on
+a rebased tip would re-flag replayed commits.
+
+Gate scope: the gate process this hook launches diffs its `--base` against the
+current checkout's HEAD, so the surface is the commits between that base and
+HEAD. A push whose pushed object is HEAD reads as the branch's own work; a
+push of any other object is still scoped to HEAD.
 
 Exit codes:
   0 - the push destination is allowed and its commits pass the gate (or
-      the gate is not installed).
+      the gate is not installed, or CODE_RULES is skipped because a
+      default-branch ref resolved and git still reported no merge base).
   1 - the push would land a non-protected local branch onto a protected
       remote branch, or a commit introduces a blocking violation.
-  2 - unexpected invocation failure (e.g., subprocess could not launch), or
-      no gate base that git resolves.
+  2 - unexpected invocation failure (e.g., subprocess could not launch),
+      stdin carried no parseable line, or a new-branch/empty-stdin base
+      could not be turned into a usable commit name.
 """
 
 from __future__ import annotations
@@ -38,9 +49,13 @@ import os
 import subprocess
 import sys
 from pathlib import Path
+from typing import NamedTuple
 
-from gate_utils import is_safe_regular_file, resolve_gate_script_path
 from git_hooks_constants import (
+    ALL_DEFAULT_BRANCH_FALLBACK_REFERENCES,
+    ALL_GIT_MERGE_BASE_COMMAND_PREFIX,
+    ALL_GIT_SYMBOLIC_REFERENCE_COMMAND_PREFIX,
+    ALL_GIT_VERIFY_REFERENCE_COMMAND_PREFIX,
     ALL_PROTECTED_BRANCH_PUSH_NAMES,
     ALL_ZEROS_OBJECT_NAME_CHARACTER,
     BASE_REFERENCE_ARGUMENT,
@@ -57,6 +72,7 @@ from git_hooks_constants import (
     GIT_EXECUTABLE_NAME,
     GIT_OUTPUT_DECODE_ERRORS_POLICY,
     GIT_OUTPUT_ENCODING_NAME,
+    GIT_REFERENCE_QUERY_TIMEOUT_SECONDS,
     INVOKE_GATE_FAILURE_MESSAGE,
     LOCAL_BRANCH_REFERENCE_PREFIX,
     LOCAL_REFERENCE_FIELD_INDEX,
@@ -64,6 +80,8 @@ from git_hooks_constants import (
     MALFORMED_STDIN_LINE_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_SENTINEL,
+    ORIGIN_HEAD_SYMBOLIC_REFERENCE,
+    ORIGIN_REMOTE_TRACKING_REFERENCE_PREFIX,
     PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE,
     PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE,
     PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE,
@@ -71,7 +89,10 @@ from git_hooks_constants import (
     STDIN_LINE_FIELD_COUNT,
     STDIN_READ_FAILURE_MESSAGE,
     STDIN_REMOTE_OBJECT_FIELD_INDEX,
+    UNRESOLVABLE_MERGE_BASE_MESSAGE,
+    UNRESOLVABLE_MERGE_BASE_SENTINEL,
 )
+from gate_utils import is_safe_regular_file, resolve_gate_script_path
 from pre_push_base_reference import (
     resolve_remote_name_from_arguments,
     resolve_usable_base_reference,
@@ -139,71 +160,331 @@ def is_all_zeros_object_name(object_name: str) -> bool:
     )
 
 
-def resolve_base_reference_from_stdin(stdin_text: str) -> str | None:
-    stdin_line_field_count = STDIN_LINE_FIELD_COUNT
-    stdin_remote_object_field_index = STDIN_REMOTE_OBJECT_FIELD_INDEX
-    local_sha_field_index = LOCAL_SHA_FIELD_INDEX
-    default_remote_base_reference = DEFAULT_REMOTE_BASE_REFERENCE
-    malformed_stdin_line_message = MALFORMED_STDIN_LINE_MESSAGE
-    has_seen_any_valid_line = False
-    is_all_valid_lines_deletions = True
+class PushLine(NamedTuple):
+    """One parsed ``<local-ref> <local-sha> <remote-ref> <remote-sha>`` stdin line."""
+
+    local_branch_name: str
+    local_object_name: str
+    remote_branch_name: str
+    remote_object_name: str
+
+
+def parse_push_line(stripped_line: str) -> PushLine | None:
+    """Return the four fields of one push line, or None when the line is malformed.
+
+    Args:
+        stripped_line: One whitespace-stripped stdin line.
+
+    Returns:
+        The parsed line with both ref names reduced to branch names, or None
+        when the line carries fewer than the four fields git writes.
+    """
+    fields = stripped_line.split()
+    if len(fields) < STDIN_LINE_FIELD_COUNT:
+        return None
+    return PushLine(
+        local_branch_name=fields[LOCAL_REFERENCE_FIELD_INDEX].removeprefix(
+            LOCAL_BRANCH_REFERENCE_PREFIX
+        ),
+        local_object_name=fields[LOCAL_SHA_FIELD_INDEX],
+        remote_branch_name=fields[REMOTE_REFERENCE_FIELD_INDEX].removeprefix(
+            LOCAL_BRANCH_REFERENCE_PREFIX
+        ),
+        remote_object_name=fields[STDIN_REMOTE_OBJECT_FIELD_INDEX],
+    )
+
+
+def is_branch_update(push_line: PushLine) -> bool:
+    """Report whether a push line moves a branch the remote already holds.
+
+    Args:
+        push_line: One parsed push line.
+
+    Returns:
+        True when the local and the remote object names are both non-zero.
+    """
+    if is_all_zeros_object_name(push_line.local_object_name):
+        return False
+    return not is_all_zeros_object_name(push_line.remote_object_name)
+
+
+class ParsedPushStdin(NamedTuple):
+    """Every well-formed push line from one stdin payload, and whether text arrived."""
+
+    all_push_lines: tuple[PushLine, ...]
+    has_stdin_content: bool
+
+
+def _parse_push_stdin(stdin_text: str) -> ParsedPushStdin:
+    """Parse the whole stdin payload once, warning on each malformed line.
+
+    Args:
+        stdin_text: The pre-push stdin payload.
+
+    Returns:
+        Every well-formed line in stdin order, paired with whether stdin
+        carried any non-blank text at all.
+    """
+    all_push_lines: list[PushLine] = []
     has_stdin_content = False
     for each_line in stdin_text.splitlines():
         stripped_line = each_line.strip()
         if not stripped_line:
             continue
         has_stdin_content = True
-        fields = stripped_line.split()
-        if len(fields) < stdin_line_field_count:
+        push_line = parse_push_line(stripped_line)
+        if push_line is None:
             print(
-                malformed_stdin_line_message.format(line=stripped_line),
+                MALFORMED_STDIN_LINE_MESSAGE.format(line=stripped_line),
                 file=sys.stderr,
             )
             continue
-        has_seen_any_valid_line = True
-        if is_all_zeros_object_name(fields[local_sha_field_index]):
+        all_push_lines.append(push_line)
+    return ParsedPushStdin(tuple(all_push_lines), has_stdin_content)
+
+
+def _resolve_base_reference_from_lines(parsed_stdin: ParsedPushStdin) -> str | None:
+    """Return the stdin-derived base reference for already-parsed lines.
+
+    Args:
+        parsed_stdin: The parsed stdin payload.
+
+    Returns:
+        The first branch update's remote object name, the no-parseable-lines
+        sentinel, None for a deletion-only push, or the remote default branch
+        reference.
+    """
+    is_all_valid_lines_deletions = True
+    for each_push_line in parsed_stdin.all_push_lines:
+        if is_all_zeros_object_name(each_push_line.local_object_name):
             continue
         is_all_valid_lines_deletions = False
-        remote_object_name = fields[stdin_remote_object_field_index]
-        if not is_all_zeros_object_name(remote_object_name):
-            return remote_object_name
-    if has_stdin_content and not has_seen_any_valid_line:
+        if is_branch_update(each_push_line):
+            return each_push_line.remote_object_name
+    if parsed_stdin.has_stdin_content and not parsed_stdin.all_push_lines:
         return NO_PARSEABLE_STDIN_LINES_SENTINEL
-    if has_seen_any_valid_line and is_all_valid_lines_deletions:
+    if parsed_stdin.all_push_lines and is_all_valid_lines_deletions:
         return None
-    return default_remote_base_reference
+    return DEFAULT_REMOTE_BASE_REFERENCE
 
 
-def find_protected_branch_push_violation(stdin_text: str) -> tuple[str, str] | None:
-    stdin_line_field_count = STDIN_LINE_FIELD_COUNT
-    local_reference_field_index = LOCAL_REFERENCE_FIELD_INDEX
-    local_sha_field_index = LOCAL_SHA_FIELD_INDEX
-    remote_reference_field_index = REMOTE_REFERENCE_FIELD_INDEX
-    local_branch_reference_prefix = LOCAL_BRANCH_REFERENCE_PREFIX
-    protected_branch_push_names = ALL_PROTECTED_BRANCH_PUSH_NAMES
-    for each_line in stdin_text.splitlines():
-        stripped_line = each_line.strip()
-        if not stripped_line:
-            continue
-        fields = stripped_line.split()
-        if len(fields) < stdin_line_field_count:
-            continue
-        if is_all_zeros_object_name(fields[local_sha_field_index]):
-            continue
-        local_branch_name = fields[local_reference_field_index].removeprefix(
-            local_branch_reference_prefix
+def resolve_base_reference_from_stdin(stdin_text: str) -> str | None:
+    return _resolve_base_reference_from_lines(_parse_push_stdin(stdin_text))
+
+
+def run_git_reference_query(all_git_arguments: tuple[str, ...]) -> str | None:
+    """Return the stripped stdout of a read-only git query.
+
+    Output decodes with the same replacing policy as ``run_git_text_command``,
+    so locale-invalid bytes become a marked string instead of crashing the hook.
+
+    Args:
+        all_git_arguments: The full git argv, including the ``git`` word.
+
+    Returns:
+        The stripped stdout, or None when git exits non-zero, prints nothing,
+        or cannot run.
+    """
+    try:
+        completion = subprocess.run(
+            list(all_git_arguments),
+            capture_output=True,
+            check=False,
+            timeout=GIT_REFERENCE_QUERY_TIMEOUT_SECONDS,
         )
-        remote_branch_name = fields[remote_reference_field_index].removeprefix(
-            local_branch_reference_prefix
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completion.returncode != 0:
+        return None
+    decoded_output = completion.stdout.decode(
+        GIT_OUTPUT_ENCODING_NAME, errors=GIT_OUTPUT_DECODE_ERRORS_POLICY
+    )
+    return decoded_output.strip() or None
+
+
+def resolve_default_branch_reference() -> str | None:
+    """Return the remote-tracking ref name of the remote's default branch.
+
+    The remote's HEAD symbolic ref answers first. When it is unset, each
+    candidate default-branch remote-tracking ref answers in turn.
+
+    Resolution reads ``origin`` alone and never the remote name git passes as
+    argv[1], and its unset-``origin/HEAD`` fallback prefers ``origin/main``
+    over ``origin/master``, so a repo whose default is another branch beside a
+    legacy ``main`` resolves the wrong base ΓÇö the assumption set tracked at
+    ~/.claude/orchestrator-runs/falsify-first/parked-items.md row 3.
+
+    Returns:
+        A remote-tracking ref name, or None when no default-branch ref
+        resolves.
+    """
+    symbolic_reference = run_git_reference_query(
+        (*ALL_GIT_SYMBOLIC_REFERENCE_COMMAND_PREFIX, ORIGIN_HEAD_SYMBOLIC_REFERENCE)
+    )
+    if symbolic_reference is not None:
+        verified_symbolic_target = run_git_reference_query(
+            (*ALL_GIT_VERIFY_REFERENCE_COMMAND_PREFIX, symbolic_reference)
+        )
+        if verified_symbolic_target is not None:
+            return symbolic_reference
+    for each_candidate_reference in ALL_DEFAULT_BRANCH_FALLBACK_REFERENCES:
+        verified_reference = run_git_reference_query(
+            (*ALL_GIT_VERIFY_REFERENCE_COMMAND_PREFIX, each_candidate_reference)
+        )
+        if verified_reference is not None:
+            return each_candidate_reference
+    return None
+
+
+def _find_branch_update_in_lines(
+    all_push_lines: tuple[PushLine, ...],
+) -> PushLine | None:
+    """Return the first already-parsed line that moves an existing remote branch.
+
+    Args:
+        all_push_lines: Well-formed push lines in stdin order.
+
+    Returns:
+        The first branch-update line, or None when no line updates a branch
+        the remote already holds.
+    """
+    for each_push_line in all_push_lines:
+        if is_branch_update(each_push_line):
+            return each_push_line
+    return None
+
+
+def find_branch_update_push(stdin_text: str) -> PushLine | None:
+    """Return the first stdin line that moves a branch the remote already holds.
+
+    Args:
+        stdin_text: The pre-push stdin payload.
+
+    Returns:
+        The parsed branch-update line, or None when no line updates a branch
+        the remote already holds.
+    """
+    return _find_branch_update_in_lines(_parse_push_stdin(stdin_text).all_push_lines)
+
+
+def resolve_default_branch_merge_base(
+    remote_branch_name: str, pushed_object_name: str
+) -> str | None:
+    """Return the merge base of the pushed object and the default branch.
+
+    The remote branch the push updates decides whether a merge base applies,
+    so ``git push origin release-candidate:develop`` reads as an update of
+    ``develop`` whatever the local branch is called.
+
+    Args:
+        remote_branch_name: The remote branch the push updates.
+        pushed_object_name: The object name the push carries.
+
+    Returns:
+        The merge-base object name; None when no default-branch ref resolves or
+        when the push updates the default branch, which are the two cases where
+        no merge base applies; or the unresolvable-merge-base sentinel when a
+        default-branch ref resolves and git still reports no merge base.
+    """
+    default_branch_reference = resolve_default_branch_reference()
+    if default_branch_reference is None:
+        return None
+    default_branch_name = default_branch_reference.removeprefix(
+        ORIGIN_REMOTE_TRACKING_REFERENCE_PREFIX
+    )
+    if remote_branch_name == default_branch_name:
+        return None
+    # Anchors to the pushed object; deferring to the gate's HEAD-based merge-base would change behavior on non-HEAD pushes.
+    merge_base_object_name = run_git_reference_query(
+        (
+            *ALL_GIT_MERGE_BASE_COMMAND_PREFIX,
+            pushed_object_name,
+            default_branch_reference,
         )
+    )
+    if merge_base_object_name is None:
+        return UNRESOLVABLE_MERGE_BASE_SENTINEL
+    return merge_base_object_name
+
+
+def resolve_gate_base_reference(stdin_text: str) -> str | None:
+    """Return the reference the gate scopes its changed lines to.
+
+    A branch update reads from the merge base with the remote default branch,
+    and every other push reads from the stdin remote object name::
+
+        branch update, default branch resolved -> merge-base(pushed, default)
+        branch update, no merge base found     -> unresolvable-merge-base sentinel
+        branch update, no default branch ref   -> stdin remote object name
+        default-branch push                    -> stdin remote object name
+        new branch or empty stdin              -> remote default branch ref
+        deletion                               -> None
+
+    Args:
+        stdin_text: The pre-push stdin payload.
+
+    Returns:
+        The gate's base reference, the no-parseable-lines sentinel, the
+        unresolvable-merge-base sentinel, or None when the push only deletes
+        remote branches.
+    """
+    return _resolve_gate_base_from_parsed(_parse_push_stdin(stdin_text))
+
+
+def _resolve_gate_base_from_parsed(parsed_stdin: ParsedPushStdin) -> str | None:
+    """Return the gate's base reference for an already-parsed stdin payload.
+
+    Args:
+        parsed_stdin: The parsed stdin payload.
+
+    Returns:
+        The merge base with the remote default branch for a branch update, the
+        branch update's remote object name when no merge base applies, the
+        unresolvable-merge-base sentinel when a default-branch ref resolves and
+        git reports no merge base anyway, and otherwise whatever the
+        stdin-derived base reference reports.
+    """
+    branch_update = _find_branch_update_in_lines(parsed_stdin.all_push_lines)
+    if branch_update is None:
+        return _resolve_base_reference_from_lines(parsed_stdin)
+    merge_base_object_name = resolve_default_branch_merge_base(
+        branch_update.remote_branch_name, branch_update.local_object_name
+    )
+    if merge_base_object_name is None:
+        return branch_update.remote_object_name
+    return merge_base_object_name
+
+
+def _find_protected_violation_in_lines(
+    all_push_lines: tuple[PushLine, ...],
+) -> tuple[str, str] | None:
+    """Return the first already-parsed line that pushes onto a protected branch.
+
+    Args:
+        all_push_lines: Well-formed push lines in stdin order.
+
+    Returns:
+        The local and protected remote branch names, or None when no line
+        lands a differently named branch on a protected one.
+    """
+    for each_push_line in all_push_lines:
+        if is_all_zeros_object_name(each_push_line.local_object_name):
+            continue
         if (
-            remote_branch_name in protected_branch_push_names
-            and local_branch_name != remote_branch_name
+            each_push_line.remote_branch_name in ALL_PROTECTED_BRANCH_PUSH_NAMES
+            and each_push_line.local_branch_name != each_push_line.remote_branch_name
         ):
-            return (local_branch_name, remote_branch_name)
+            return (
+                each_push_line.local_branch_name,
+                each_push_line.remote_branch_name,
+            )
     return None
 
 
+def find_protected_branch_push_violation(stdin_text: str) -> tuple[str, str] | None:
+    return _find_protected_violation_in_lines(_parse_push_stdin(stdin_text).all_push_lines)
+
+
 def invoke_gate(gate_script_path: Path, base_reference: str) -> int:
     base_reference_argument = BASE_REFERENCE_ARGUMENT
     invoke_gate_failure_message = INVOKE_GATE_FAILURE_MESSAGE
@@ -310,6 +591,8 @@ def main() -> int:
     pre_push_gate_script_not_found_message = PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE
     no_parseable_stdin_lines_message = NO_PARSEABLE_STDIN_LINES_MESSAGE
     no_parseable_stdin_lines_sentinel = NO_PARSEABLE_STDIN_LINES_SENTINEL
+    unresolvable_merge_base_message = UNRESOLVABLE_MERGE_BASE_MESSAGE
+    unresolvable_merge_base_sentinel = UNRESOLVABLE_MERGE_BASE_SENTINEL
     protected_branch_push_block_message = PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE
     protected_branch_push_block_exit_code = PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
     try:
@@ -320,7 +603,10 @@ def main() -> int:
             file=sys.stderr,
         )
         return gate_infrastructure_failure_exit_code
-    protected_branch_push_violation = find_protected_branch_push_violation(stdin_text)
+    parsed_stdin = _parse_push_stdin(stdin_text)
+    protected_branch_push_violation = _find_protected_violation_in_lines(
+        parsed_stdin.all_push_lines
+    )
     if protected_branch_push_violation is not None:
         local_branch_name, remote_branch_name = protected_branch_push_violation
         print(
@@ -338,12 +624,15 @@ def main() -> int:
             file=sys.stderr,
         )
         return code_review_stamp_block_exit_code()
-    base_reference = resolve_base_reference_from_stdin(stdin_text)
+    base_reference = _resolve_gate_base_from_parsed(parsed_stdin)
     if base_reference is None:
         return 0
     if base_reference == no_parseable_stdin_lines_sentinel:
         print(no_parseable_stdin_lines_message, file=sys.stderr)
         return gate_infrastructure_failure_exit_code
+    if base_reference == unresolvable_merge_base_sentinel:
+        print(unresolvable_merge_base_message, file=sys.stderr)
+        return code_review_stamp_block_exit_code()
     remote_name = resolve_remote_name_from_arguments(sys.argv)
     try:
         usable_base_reference = resolve_usable_base_reference(