@bookedsolid/rea 0.10.2 → 0.11.0

package/hooks/_lib/push-review-core.sh

@@ -1,1250 +0,0 @@
-#!/bin/bash
-# hooks/_lib/push-review-core.sh — shared core for push-review adapters.
-#
-# Source, do not execute. Callers (adapters) must:
-#   1. capture stdin into INPUT
-#   2. source this file
-#   3. call `pr_core_run "$0" "$INPUT" "$@"` (passing the adapter's own
-#      script path as $1, the raw stdin as $2, and the adapter's argv after)
-#
-# BUG-008 cleanup (0.7.0): the same core serves two physical adapters —
-#
-#   hooks/push-review-gate.sh       — Claude Code PreToolUse adapter. Stdin
-#                                      is JSON `.tool_input.command`; argv
-#                                      is empty. BUG-008 sniff handles the
-#                                      case where this hook is wired into
-#                                      `.husky/pre-push` directly and git's
-#                                      native refspec lines arrive on stdin.
-#
-#   hooks/push-review-gate-git.sh   — Native `.husky/pre-push` adapter. Stdin
-#                                      is always git's refspec contract; argv
-#                                      $1 is the remote name, $2 is the URL.
-#
-# Both adapters delegate here unchanged. The sniff inside `pr_core_run`
-# recognizes the two stdin shapes and routes accordingly.
-#
-# The functions are prefixed `pr_` (push-review) so sourcing this file into
-# another hook (which may already define its own helpers) is safe.
-
-# The caller sets `set -uo pipefail`; core inherits.
-
-# Unused-in-isolation globals that `pr_core_run` writes as locals:
-# REA_ROOT, CMD, CODEX_REQUIRED, ZERO_SHA. We do NOT declare them at file
-# scope — dynamic scoping means `pr_core_run`'s `local` declarations are
-# visible inside the helpers it calls.
-
-# ── pr_parse_prepush_stdin ───────────────────────────────────────────────────
-# Parse git's pre-push stdin contract.
-#
-# Stdin shape: one line per refspec, with fields
-#   `<local_ref> <local_sha> <remote_ref> <remote_sha>`
-# Emits one record per accepted line on stdout:
-#   `local_sha|remote_sha|local_ref|remote_ref`
-# Returns non-zero with no output if stdin does not match the contract, so
-# the caller can switch to argv fallback. Portable to macOS /bin/bash 3.2.
-pr_parse_prepush_stdin() {
-  local raw="$1"
-  local accepted=0
-  local line local_ref local_sha remote_ref remote_sha rest
-  local -a records
-  records=()
-  while IFS= read -r line; do
-    [[ -z "$line" ]] && continue
-    read -r local_ref local_sha remote_ref remote_sha rest <<<"$line"
-    if [[ -z "$local_ref" || -z "$local_sha" || -z "$remote_ref" || -z "$remote_sha" ]]; then
-      continue
-    fi
-    if [[ ! "$local_sha" =~ ^[0-9a-f]{40}$ ]] || [[ ! "$remote_sha" =~ ^[0-9a-f]{40}$ ]]; then
-      return 1
-    fi
-    records+=("${local_sha}|${remote_sha}|${local_ref}|${remote_ref}")
-    accepted=1
-  done <<<"$raw"
-  if [[ "$accepted" -ne 1 ]]; then
-    return 1
-  fi
-  local r
-  for r in "${records[@]}"; do
-    printf '%s\n' "$r"
-  done
-}
-
-# ── pr_resolve_argv_refspecs ─────────────────────────────────────────────────
-# Fallback refspec resolver: parse `git push [remote] [refspec...]` from the
-# command string when stdin has no pre-push lines. Emits newline-separated
-# records as "local_sha|remote_sha|local_ref|remote_ref" where `local_sha` is
-# HEAD of the named source ref (or HEAD itself for bare refspecs) and
-# `remote_sha` is zero so merge-base logic falls back to the configured
-# default. Exits the script with code 2 on operator-error conditions
-# (HEAD target, unresolvable source ref).
-#
-# Reads REA_ROOT and ZERO_SHA from the caller's function scope.
-pr_resolve_argv_refspecs() {
-  local cmd="$1"
-  local segment
-  segment=$(printf '%s' "$cmd" | awk '
-    {
-      idx = match($0, /git[[:space:]]+push([[:space:]]|$)/)
-      if (!idx) exit
-      tail = substr($0, idx)
-      n = match(tail, /[;&|]|&&|\|\|/)
-      if (n > 0) tail = substr(tail, 1, n - 1)
-      print tail
-    }
-  ')
-
-  local -a specs
-  specs=()
-  local seen_push=0 remote_seen=0 delete_mode=0 tok
-  # shellcheck disable=SC2086
-  set -- $segment
-  for tok in "$@"; do
-    case "$tok" in
-      git|push) seen_push=1; continue ;;
-      --delete|-d)
-        delete_mode=1
-        continue
-        ;;
-      --delete=*)
-        delete_mode=1
-        specs+=("${tok#--delete=}")
-        continue
-        ;;
-      -*) continue ;;
-    esac
-    [[ "$seen_push" -eq 0 ]] && continue
-    if [[ "$remote_seen" -eq 0 ]]; then
-      remote_seen=1
-      continue
-    fi
-    if [[ "$delete_mode" -eq 1 ]]; then
-      specs+=("__REA_DELETE__${tok}")
-    else
-      specs+=("$tok")
-    fi
-  done
-
-  if [[ "${#specs[@]}" -eq 0 ]]; then
-    local upstream dst_ref head_sha
-    upstream=$(cd "$REA_ROOT" && git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || echo "")
-    dst_ref="refs/heads/main"
-    if [[ -n "$upstream" && "$upstream" == */* ]]; then
-      dst_ref="refs/heads/${upstream#*/}"
-    fi
-    head_sha=$(cd "$REA_ROOT" && git rev-parse HEAD 2>/dev/null || echo "")
-    [[ -z "$head_sha" ]] && return 1
-    printf '%s|%s|HEAD|%s\n' "$head_sha" "$ZERO_SHA" "$dst_ref"
-    return 0
-  fi
-
-  local spec src dst src_sha is_delete
-  for spec in "${specs[@]}"; do
-    is_delete=0
-    if [[ "$spec" == __REA_DELETE__* ]]; then
-      is_delete=1
-      spec="${spec#__REA_DELETE__}"
-    fi
-    spec="${spec#+}"
-    if [[ "$spec" == *:* ]]; then
-      src="${spec%%:*}"
-      dst="${spec##*:}"
-    else
-      src="$spec"
-      dst="$spec"
-    fi
-    if [[ -z "$dst" ]]; then
-      dst="${spec##*:}"
-      src=""
-    fi
-    dst="${dst#refs/heads/}"
-    dst="${dst#refs/for/}"
-    if [[ "$is_delete" -eq 1 ]]; then
-      if [[ -z "$dst" || "$dst" == "HEAD" ]]; then
-        {
-          printf 'PUSH BLOCKED: --delete refspec resolves to HEAD or empty (from %q)\n' "$spec"
-        } >&2
-        exit 2
-      fi
-      printf '%s|%s|(delete)|refs/heads/%s\n' "$ZERO_SHA" "$ZERO_SHA" "$dst"
-      continue
-    fi
-    if [[ "$dst" == "HEAD" || -z "$dst" ]]; then
-      {
-        printf 'PUSH BLOCKED: refspec resolves to HEAD (from %q)\n' "$spec"
-        printf '\n'
-        # shellcheck disable=SC2016
-        printf '  `git push <remote> HEAD:<branch>` or similar is almost always\n'
-        printf '  operator error in this context. Name the destination branch\n'
-        printf '  explicitly so the review gate can diff against it.\n'
-        printf '\n'
-      } >&2
-      exit 2
-    fi
-    if [[ -z "$src" ]]; then
-      printf '%s|%s|(delete)|refs/heads/%s\n' "$ZERO_SHA" "$ZERO_SHA" "$dst"
-      continue
-    fi
-    src_sha=$(cd "$REA_ROOT" && git rev-parse --verify "${src}^{commit}" 2>/dev/null || echo "")
-    if [[ -z "$src_sha" ]]; then
-      {
-        printf 'PUSH BLOCKED: could not resolve source ref %q to a commit.\n' "$src"
-      } >&2
-      exit 2
-    fi
-    printf '%s|%s|refs/heads/%s|refs/heads/%s\n' "$src_sha" "$ZERO_SHA" "$src" "$dst"
-  done
-}
-
-# ── pr_core_run ──────────────────────────────────────────────────────────────
-# Main orchestrator. Arguments:
-#   $1 = adapter script path (BASH_SOURCE[0] from the adapter)
-#   $2 = raw stdin (INPUT) captured by the adapter
-#   $3..$N = adapter's original argv ($@). For git-native adapters, $3 is the
-#            remote name and $4 is the URL. For Claude Code, typically absent.
-#
-# The function may `exit 0` (allow), `exit 2` (block), or fall through to
-# section 9 which prints the review prompt and exits 2.
-pr_core_run() {
-  local adapter_script="$1"
-  local INPUT="$2"
-  shift 2
-  # Remaining positional args are the adapter's original argv. For a git
-  # native pre-push the first is the remote name; for Claude Code it is
-  # typically unset. Default to `origin` for BUG-008 sniff consistency.
-  local argv_remote="${1:-origin}"
-
-  # 0.8.0 (#85): when REA_SKIP_CODEX_REVIEW is set, this flag flips to 1
-  # in section 5c. The protected-path Codex-audit check (section 7) then
-  # treats the requirement as satisfied — but every other gate (HALT,
-  # cross-repo guard, ref-resolution, push-review cache, blocked-paths)
-  # still runs. Full-gate bypass moved to REA_SKIP_PUSH_REVIEW a release
-  # cycle ago; this narrows REA_SKIP_CODEX_REVIEW to what its name implies.
-  local CODEX_WAIVER_ACTIVE=0
-
-  # ── 1a. Cross-repo guard (must come FIRST — before any rea-scoped check) ──
-  # BUG-012 (0.6.2) — anchor the install to the SCRIPT'S OWN LOCATION on disk.
-  # The hook knows where it lives: installed at `<root>/.claude/hooks/<name>.sh`,
-  # so `<root>` is two levels up from the adapter's BASH_SOURCE. No
-  # caller-controlled env var participates in the trust decision.
-  #
-  # See THREAT_MODEL.md § CLAUDE_PROJECT_DIR for the full rationale.
-  local SCRIPT_DIR
-  SCRIPT_DIR="$(cd -- "$(dirname -- "$adapter_script")" && pwd -P 2>/dev/null)"
-  # Walk up from SCRIPT_DIR looking for `.rea/policy.yaml`. This resolves
-  # correctly for every reasonable topology — installed copy at
-  # `<root>/.claude/hooks/<name>.sh` (2 up), source-of-truth copy at
-  # `<root>/hooks/<name>.sh` (1 up, used when rea dogfoods itself or a
-  # developer runs `bash hooks/push-review-gate.sh` to smoke-test), and any
-  # future `hooks/_lib/` nesting. Cap at 4 levels so a stray hook dropped in
-  # the wrong spot fails fast instead of walking to the filesystem root.
-  local REA_ROOT=""
-  local _anchor_candidate="$SCRIPT_DIR"
-  local _i
-  for _i in 1 2 3 4; do
-    _anchor_candidate="$(cd -- "$_anchor_candidate/.." && pwd -P 2>/dev/null || true)"
-    if [[ -n "$_anchor_candidate" && -f "$_anchor_candidate/.rea/policy.yaml" ]]; then
-      REA_ROOT="$_anchor_candidate"
-      break
-    fi
-  done
-  if [[ -z "$REA_ROOT" ]]; then
-    printf 'rea-hook: no .rea/policy.yaml found within 4 parents of %s\n' \
-      "$SCRIPT_DIR" >&2
-    printf 'rea-hook:   is this an installed rea hook, or is `.rea/policy.yaml`\n' >&2
-    printf 'rea-hook:   nested more than 4 directories above the hook script?\n' >&2
-    exit 2
-  fi
-
-  # Advisory-only: warn if the caller set CLAUDE_PROJECT_DIR to a path that
-  # does not match the script anchor. Never let the env var override the
-  # decision.
-  if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
-    local CPD_REAL
-    CPD_REAL=$(cd -- "${CLAUDE_PROJECT_DIR}" 2>/dev/null && pwd -P 2>/dev/null || true)
-    if [[ -n "$CPD_REAL" && "$CPD_REAL" != "$REA_ROOT" ]]; then
-      printf 'rea-hook: ignoring CLAUDE_PROJECT_DIR=%s — anchoring to script location %s\n' \
-        "$CLAUDE_PROJECT_DIR" "$REA_ROOT" >&2
-    fi
-  fi
-
-  local CWD_REAL CWD_COMMON REA_COMMON CWD_COMMON_REAL REA_COMMON_REAL
-  CWD_REAL=$(pwd -P 2>/dev/null || pwd)
-  CWD_COMMON=$(git -C "$CWD_REAL" rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)
-  REA_COMMON=$(git -C "$REA_ROOT" rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)
-  if [[ -n "$CWD_COMMON" && -n "$REA_COMMON" ]]; then
-    # Both sides are git checkouts. Realpath'd common-dirs match IFF they
-    # point at the same underlying repository (main or linked worktree).
-    CWD_COMMON_REAL=$(cd "$CWD_COMMON" 2>/dev/null && pwd -P 2>/dev/null || echo "$CWD_COMMON")
-    REA_COMMON_REAL=$(cd "$REA_COMMON" 2>/dev/null && pwd -P 2>/dev/null || echo "$REA_COMMON")
-    if [[ "$CWD_COMMON_REAL" != "$REA_COMMON_REAL" ]]; then
-      exit 0
-    fi
-  elif [[ -z "$CWD_COMMON" && -z "$REA_COMMON" ]]; then
-    # Both sides non-git: legitimate 0.5.1 non-git escape-hatch. Fall back to
-    # a literal path-prefix match. Quoted expansions prevent glob expansion.
-    case "$CWD_REAL/" in
-      "$REA_ROOT"/*|"$REA_ROOT"/) : ;;  # inside rea — run the gate
-      *) exit 0 ;;                       # outside rea — not our gate
-    esac
-  fi
-  # Mixed state (one side git, other not) or either probe failed → fail
-  # CLOSED: run the gate.
-
-  # ── 2. Dependency check ───────────────────────────────────────────────────
-  if ! command -v jq >/dev/null 2>&1; then
-    printf 'REA ERROR: jq is required but not installed.\n' >&2
-    printf 'Install: brew install jq  OR  apt-get install -y jq\n' >&2
-    exit 2
-  fi
-
-  # ── 3. HALT check ─────────────────────────────────────────────────────────
-  local HALT_FILE="${REA_ROOT}/.rea/HALT"
-  if [ -f "$HALT_FILE" ]; then
-    printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \
-      "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
-    exit 2
-  fi
-
-  # ── 4. Parse command ──────────────────────────────────────────────────────
-  local CMD
-  CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
-
-  # ── 4a. BUG-008: self-detect git's native pre-push contract ───────────────
-  # When the hook is wired into `.husky/pre-push`, git invokes it with
-  #   `$1 = remote name`, `$2 = remote url`
-  # and delivers one line per refspec on stdin:
-  #   `<local_ref> <local_sha> <remote_ref> <remote_sha>`
-  # The Claude Code PreToolUse wrapper instead delivers JSON on stdin, which
-  # is what the jq parse above targets. When jq returns empty, the stdin may
-  # in fact be git's pre-push ref-list — sniff the first non-blank line, and
-  # if it matches the `<ref> <40-hex> <ref> <40-hex>` shape, synthesize CMD
-  # as `git push <remote>` (from the adapter's argv_remote) so the remainder
-  # of the gate runs through the pre-push parser in step 6 rather than the
-  # argv fallback.
-  #
-  # Any other stdin shape (empty, random JSON, a non-push tool call) still
-  # exits 0 here — the gate is a no-op for non-push Bash calls by design.
-  local FIRST_STDIN_LINE
-  FIRST_STDIN_LINE=$(printf '%s' "$INPUT" | awk 'NF { print; exit }')
-  if [[ -z "$CMD" ]]; then
-    if [[ -n "$FIRST_STDIN_LINE" ]] \
-       && printf '%s' "$FIRST_STDIN_LINE" \
-          | grep -qE '^[^[:space:]]+[[:space:]]+[0-9a-f]{40}[[:space:]]+[^[:space:]]+[[:space:]]+[0-9a-f]{40}[[:space:]]*$'; then
-      CMD="git push ${argv_remote}"
-    else
-      exit 0
-    fi
-  fi
-
-  # Only trigger on git push commands
-  if ! printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+push'; then
-    exit 0
-  fi
-
-  # ── 5. REA_SKIP_PUSH_REVIEW — whole-gate escape hatch ─────────────────────
-  # An opt-in bypass for the ENTIRE push-review gate (not just the Codex
-  # branch). Exists to unblock consumers when rea itself is broken or a
-  # corrupt policy/audit file would otherwise deadlock a push. Requires an
-  # explicit non-empty reason; the value of REA_SKIP_PUSH_REVIEW is recorded
-  # verbatim in the audit record as the reason.
-  #
-  # Audit tool_name is `push.review.skipped`. This is intentionally NOT
-  # `codex.review` or `codex.review.skipped` — a skip of the whole gate is a
-  # separately-audited event and does not satisfy the Codex-review jq
-  # predicate.
-  if [[ -n "${REA_SKIP_PUSH_REVIEW:-}" ]]; then
-    local SKIP_REASON="$REA_SKIP_PUSH_REVIEW"
-    local AUDIT_APPEND_JS="${REA_ROOT}/dist/audit/append.js"
-
-    if [[ ! -f "$AUDIT_APPEND_JS" ]]; then
-      {
-        printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW requires rea to be built.\n'
-        printf '\n'
-        printf '  REA_SKIP_PUSH_REVIEW is set but %s is missing.\n' "$AUDIT_APPEND_JS"
-        printf '  Run: pnpm build\n'
-        printf '\n'
-      } >&2
-      exit 2
-    fi
-
-    # Codex F2: CI-aware refusal.
-    if [[ -n "${CI:-}" ]]; then
-      local ALLOW_CI_SKIP=""
-      local READ_FIELD_JS="${REA_ROOT}/dist/scripts/read-policy-field.js"
-      if [[ -f "$READ_FIELD_JS" ]]; then
-        ALLOW_CI_SKIP=$(REA_ROOT="$REA_ROOT" node "$READ_FIELD_JS" review.allow_skip_in_ci 2>/dev/null || echo "")
-      fi
-      if [[ "$ALLOW_CI_SKIP" != "true" ]]; then
-        {
-          printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW refused in CI context.\n'
-          printf '\n'
-          printf '  CI env var is set. An unauthenticated env-var bypass in a shared\n'
-          printf '  build agent is not trusted. To enable, set\n'
-          printf '    review:\n'
-          printf '      allow_skip_in_ci: true\n'
-          printf '  in .rea/policy.yaml — explicitly authorizing env-var skips in CI.\n'
-          printf '\n'
-        } >&2
-        exit 2
-      fi
-    fi
-
-    local SKIP_ACTOR
-    SKIP_ACTOR=$(cd "$REA_ROOT" && git config user.email 2>/dev/null || echo "")
-    if [[ -z "$SKIP_ACTOR" ]]; then
-      SKIP_ACTOR=$(cd "$REA_ROOT" && git config user.name 2>/dev/null || echo "")
-    fi
-    if [[ -z "$SKIP_ACTOR" ]]; then
-      {
-        printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW requires a git identity.\n'
-        printf '\n'
-        # shellcheck disable=SC2016  # backticks are literal markdown in user-facing message
-        printf '  Neither `git config user.email` nor `git config user.name`\n'
-        printf '  is set. The skip audit record would have no actor; refusing\n'
-        printf '  to bypass without one.\n'
-        printf '\n'
-      } >&2
-      exit 2
-    fi
-
-    local SKIP_BRANCH SKIP_HEAD
-    SKIP_BRANCH=$(cd "$REA_ROOT" && git branch --show-current 2>/dev/null || echo "")
-    SKIP_HEAD=$(cd "$REA_ROOT" && git rev-parse HEAD 2>/dev/null || echo "")
-
-    # Codex F2: record OS identity alongside the (mutable, git-sourced) actor
-    # so downstream auditors can reconstruct who REALLY invoked the bypass on
-    # a shared host. None of these are forgeable from inside the push process
-    # alone.
-    local SKIP_OS_UID SKIP_OS_WHOAMI SKIP_OS_HOST SKIP_OS_PID SKIP_OS_PPID
-    local SKIP_OS_PPID_CMD SKIP_OS_TTY SKIP_OS_CI
-    SKIP_OS_UID=$(id -u 2>/dev/null || echo "")
-    SKIP_OS_WHOAMI=$(whoami 2>/dev/null || echo "")
-    SKIP_OS_HOST=$(hostname 2>/dev/null || echo "")
-    SKIP_OS_PID=$$
-    SKIP_OS_PPID=$PPID
-    SKIP_OS_PPID_CMD=$(ps -o command= -p "$PPID" 2>/dev/null | head -c 512 || echo "")
-    SKIP_OS_TTY=$(tty 2>/dev/null || echo "not-a-tty")
-    SKIP_OS_CI="${CI:-}"
-
-    local SKIP_METADATA
-    SKIP_METADATA=$(jq -n \
-      --arg head_sha "$SKIP_HEAD" \
-      --arg branch "$SKIP_BRANCH" \
-      --arg reason "$SKIP_REASON" \
-      --arg actor "$SKIP_ACTOR" \
-      --arg os_uid "$SKIP_OS_UID" \
-      --arg os_whoami "$SKIP_OS_WHOAMI" \
-      --arg os_hostname "$SKIP_OS_HOST" \
-      --argjson os_pid "$SKIP_OS_PID" \
-      --argjson os_ppid "$SKIP_OS_PPID" \
-      --arg os_ppid_cmd "$SKIP_OS_PPID_CMD" \
-      --arg os_tty "$SKIP_OS_TTY" \
-      --arg os_ci "$SKIP_OS_CI" \
-      '{
-        head_sha: $head_sha,
-        branch: $branch,
-        reason: $reason,
-        actor: $actor,
-        verdict: "skipped",
-        os_identity: {
-          uid: $os_uid,
-          whoami: $os_whoami,
-          hostname: $os_hostname,
-          pid: $os_pid,
-          ppid: $os_ppid,
-          ppid_cmd: $os_ppid_cmd,
-          tty: $os_tty,
-          ci: $os_ci
-        }
-      }' 2>/dev/null)
-
-    if [[ -z "$SKIP_METADATA" ]]; then
-      {
-        printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW could not serialize audit metadata.\n' >&2
-      } >&2
-      exit 2
-    fi
-
-    REA_ROOT="$REA_ROOT" REA_SKIP_METADATA="$SKIP_METADATA" \
-      node --input-type=module -e "
-        const mod = await import(process.env.REA_ROOT + '/dist/audit/append.js');
-        const metadata = JSON.parse(process.env.REA_SKIP_METADATA);
-        await mod.appendAuditRecord(process.env.REA_ROOT, {
-          tool_name: 'push.review.skipped',
-          server_name: 'rea.escape_hatch',
-          status: mod.InvocationStatus.Allowed,
-          tier: mod.Tier.Read,
-          metadata,
-        });
-      " 2>/dev/null
-    local NODE_STATUS=$?
-    if [[ "$NODE_STATUS" -ne 0 ]]; then
-      {
-        printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW audit-append failed (node exit %s).\n' "$NODE_STATUS"
-        printf '  Refusing to bypass the push gate without a receipt.\n'
-      } >&2
-      exit 2
-    fi
-
-    {
-      printf '\n'
-      printf '==  PUSH REVIEW GATE SKIPPED via REA_SKIP_PUSH_REVIEW\n'
-      printf '    Reason:  %s\n' "$SKIP_REASON"
-      printf '    Actor:   %s\n' "$SKIP_ACTOR"
-      printf '    Branch:  %s\n' "${SKIP_BRANCH:-<detached>}"
-      printf '    Head:    %s\n' "${SKIP_HEAD:-<unknown>}"
-      printf '    Audited: .rea/audit.jsonl (tool_name=push.review.skipped)\n'
-      printf '\n'
-      printf '    This is a gate weakening. Every invocation is permanently audited.\n'
-      printf '\n'
-    } >&2
-    exit 0
-  fi
-
-  # ── 5b. Resolve review.codex_required (hoisted from section 7a) ───────────
-  # We need this BEFORE the REA_SKIP_CODEX_REVIEW check so G11.4 first-class
-  # no-Codex mode stays a clean no-op: when the policy says Codex is not
-  # required at all, there is nothing to skip, and setting
-  # REA_SKIP_CODEX_REVIEW must not write a skip audit record.
-  #
-  # Fail-closed: a malformed/unparseable policy is treated as
-  # codex_required=true so we never silently drop the Codex gate on a broken
-  # policy file.
-  local READ_FIELD_JS="${REA_ROOT}/dist/scripts/read-policy-field.js"
-  local CODEX_REQUIRED="true"
-  if [[ -f "$READ_FIELD_JS" ]]; then
-    local FIELD_VALUE FIELD_STATUS
-    FIELD_VALUE=$(REA_ROOT="$REA_ROOT" node "$READ_FIELD_JS" review.codex_required 2>/dev/null)
-    FIELD_STATUS=$?
-    case "$FIELD_STATUS" in
-      0)
-        if [[ "$FIELD_VALUE" == "false" ]]; then
-          CODEX_REQUIRED="false"
-        elif [[ "$FIELD_VALUE" == "true" ]]; then
-          CODEX_REQUIRED="true"
-        else
-          printf 'REA WARN: review.codex_required resolved to non-boolean %q — treating as true\n' "$FIELD_VALUE" >&2
-          CODEX_REQUIRED="true"
-        fi
-        ;;
-      1)
-        CODEX_REQUIRED="true"
-        ;;
-      *)
-        printf 'REA WARN: read-policy-field exited %s — treating review.codex_required as true (fail-closed)\n' "$FIELD_STATUS" >&2
-        CODEX_REQUIRED="true"
-        ;;
-    esac
-  fi
-
-  # ── 5c. REA_SKIP_CODEX_REVIEW — Codex-review bypass ───────────────────────
-  # Runs here (before ref-resolution) so ref-resolution failures in section 6
-  # do not strand an operator who has committed to the skip. See the
-  # adapter's file-top docstring for the ordering rationale (0.7.0).
-  #
-  # Gated on CODEX_REQUIRED=true (from section 5b): if policy explicitly opts
-  # into no-Codex mode, the skip is a no-op — nothing to skip, no audit noise.
-  if [[ -n "${REA_SKIP_CODEX_REVIEW:-}" && "$CODEX_REQUIRED" == "true" ]]; then
-    local SKIP_REASON="$REA_SKIP_CODEX_REVIEW"
-    local AUDIT_APPEND_JS="${REA_ROOT}/dist/audit/append.js"
-
-    if [[ ! -f "$AUDIT_APPEND_JS" ]]; then
-      {
-        printf 'PUSH BLOCKED: escape hatch requires rea to be built.\n'
-        printf '\n'
-        printf '  REA_SKIP_CODEX_REVIEW is set but %s is missing.\n' "$AUDIT_APPEND_JS"
-        printf '  Run: pnpm build\n'
-        printf '\n'
-      } >&2
-      exit 2
-    fi
-
-    local SKIP_ACTOR
-    SKIP_ACTOR=$(cd "$REA_ROOT" && git config user.email 2>/dev/null || echo "")
-    if [[ -z "$SKIP_ACTOR" ]]; then
-      SKIP_ACTOR=$(cd "$REA_ROOT" && git config user.name 2>/dev/null || echo "")
-    fi
-    if [[ -z "$SKIP_ACTOR" ]]; then
-      {
-        printf 'PUSH BLOCKED: escape hatch requires a git identity.\n'
-        printf '\n'
-        # shellcheck disable=SC2016  # backticks are literal markdown in user-facing message
-        printf '  Neither `git config user.email` nor `git config user.name`\n'
-        printf '  is set. The skip audit record would have no actor; refusing\n'
-        printf '  to bypass without one.\n'
-        printf '\n'
-      } >&2
-      exit 2
-    fi
-
-    # Metadata source of truth: the pre-push stdin contract. Parse the FIRST
-    # well-formed refspec line from the captured INPUT so the skip audit
-    # record describes the actual push, not the checkout that happened to be
-    # active.
-    local SKIP_HEAD="" SKIP_TARGET="" SKIP_SOURCE=""
-    local SKIP_UPSTREAM
-
-    local __line __lref __lsha __rref __rsha __rest
-    while IFS= read -r __line; do
-      # shellcheck disable=SC2034  # field-splitting into named vars is the intent
-      read -r __lref __lsha __rref __rsha __rest <<< "$__line"
-      if [[ -z "$__rest" && "$__lsha" =~ ^[0-9a-f]{40}$ && -n "$__rref" ]]; then
-        SKIP_HEAD="$__lsha"
-        SKIP_TARGET="${__rref#refs/heads/}"
-        SKIP_SOURCE="prepush-stdin"
-        break
-      fi
-    done <<< "$INPUT"
-
-    if [[ -z "$SKIP_HEAD" ]]; then
-      SKIP_HEAD=$(cd "$REA_ROOT" && git rev-parse HEAD 2>/dev/null || echo "")
-      SKIP_UPSTREAM=$(cd "$REA_ROOT" && git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || echo "")
-      SKIP_TARGET="main"
-      if [[ -n "$SKIP_UPSTREAM" && "$SKIP_UPSTREAM" == */* ]]; then
-        SKIP_TARGET="${SKIP_UPSTREAM#*/}"
-      fi
-      SKIP_SOURCE="local-fallback"
-    fi
-
-    local SKIP_METADATA
-    SKIP_METADATA=$(jq -n \
-      --arg head_sha "$SKIP_HEAD" \
-      --arg target "$SKIP_TARGET" \
-      --arg reason "$SKIP_REASON" \
-      --arg actor "$SKIP_ACTOR" \
-      --arg source "$SKIP_SOURCE" \
-      '{
-        head_sha: $head_sha,
-        target: $target,
-        reason: $reason,
-        actor: $actor,
-        verdict: "skipped",
-        files_changed: null,
-        metadata_source: $source
-      }' 2>/dev/null)
-
-    if [[ -z "$SKIP_METADATA" ]]; then
-      {
-        printf 'PUSH BLOCKED: escape hatch could not serialize audit metadata.\n' >&2
-      } >&2
-      exit 2
-    fi
-
-    REA_ROOT="$REA_ROOT" REA_SKIP_METADATA="$SKIP_METADATA" \
-      node --input-type=module -e "
-        const mod = await import(process.env.REA_ROOT + '/dist/audit/append.js');
-        const metadata = JSON.parse(process.env.REA_SKIP_METADATA);
-        await mod.appendAuditRecord(process.env.REA_ROOT, {
-          tool_name: 'codex.review.skipped',
-          server_name: 'rea.escape_hatch',
-          status: mod.InvocationStatus.Allowed,
-          tier: mod.Tier.Read,
-          metadata,
-        });
-      " 2>/dev/null
-    local NODE_STATUS=$?
-    if [[ "$NODE_STATUS" -ne 0 ]]; then
-      {
-        printf 'PUSH BLOCKED: escape hatch audit-append failed (node exit %s).\n' "$NODE_STATUS"
-        printf '  Refusing to bypass the Codex-review gate without a receipt.\n'
-      } >&2
-      exit 2
-    fi
-
-    {
-      printf '\n'
-      printf '==  CODEX REVIEW WAIVER active (REA_SKIP_CODEX_REVIEW)\n'
-      printf '    Reason:   %s\n' "$SKIP_REASON"
-      printf '    Actor:    %s\n' "$SKIP_ACTOR"
-      printf '    Head SHA: %s\n' "${SKIP_HEAD:-<unknown>}"
-      printf '    Audited:  .rea/audit.jsonl (tool_name=codex.review.skipped)\n'
-      printf '\n'
-      printf '    Scope:    waives the protected-path Codex-audit requirement only.\n'
-      printf '    Still active: HALT, cross-repo guard, ref-resolution,\n'
-      printf '                  push-review cache. For a full-gate bypass\n'
-      # shellcheck disable=SC2016  # backticks are literal markdown in user-facing message
-      printf '                  use `REA_SKIP_PUSH_REVIEW=<reason>`.\n'
-      printf '\n'
-      printf '    This is a gate weakening. The waiver receipt is written BEFORE\n'
-      printf '    this banner — seeing this banner means the audit is durable.\n'
-      printf '\n'
-    } >&2
-    CODEX_WAIVER_ACTIVE=1
-  fi
-
-  # ── 6. Determine source/target commits for each refspec ───────────────────
-  # The authoritative source for which commits are being pushed is the pre-
-  # push hook stdin contract: one line per refspec, with fields
-  #     <local_ref> <local_sha> <remote_ref> <remote_sha>
-  # (https://git-scm.com/docs/githooks#_pre_push). We drive the gate off
-  # those SHAs directly — NOT off HEAD — so that `git push origin hotfix:main`
-  # from a checked-out `foo` branch reviews the `hotfix` commits, not `foo`.
-  #
-  # If what we read on stdin does not look like pre-push refspec lines, we
-  # treat it as "no stdin" and use the argv fallback.
-  local ZERO_SHA='0000000000000000000000000000000000000000'
-  local CURRENT_BRANCH
-  CURRENT_BRANCH=$(cd "$REA_ROOT" && git branch --show-current 2>/dev/null || echo "")
-
-  # Collect refspec records. Stdin takes priority; fall back to argv parsing.
-  local -a REFSPEC_RECORDS
-  REFSPEC_RECORDS=()
-  local RECORDS_OUT _rec
-  if RECORDS_OUT=$(pr_parse_prepush_stdin "$INPUT") && [[ -n "$RECORDS_OUT" ]]; then
-    :
-  else
-    RECORDS_OUT=$(pr_resolve_argv_refspecs "$CMD")
-  fi
-  while IFS= read -r _rec; do
-    [[ -z "$_rec" ]] && continue
-    REFSPEC_RECORDS+=("$_rec")
-  done <<<"$RECORDS_OUT"
-
-  if [[ "${#REFSPEC_RECORDS[@]}" -eq 0 ]]; then
-    {
-      printf 'PUSH BLOCKED: no push refspecs could be resolved.\n'
-      printf '  Refusing to pass without a source commit to review.\n'
-    } >&2
-    exit 2
-  fi
-
-  # ── 7. Pick the source commit and merge-base to review ────────────────────
-  # Across all refspecs, we pick the one whose source commit is furthest from
-  # its merge-base (i.e. the largest diff). That way a mixed push like
-  # `foo:main bar:dev` is gated on whichever refspec actually contributes new
-  # commits. A deletion refspec (local_sha all zeros) is still concerning —
-  # we check the remote side for protected-path changes against the merge-
-  # base of the remote sha and the default branch, but the diff body comes
-  # from the non-delete refspec if present. If every refspec is a delete, we
-  # fail-closed and require an explicit review.
-  local SOURCE_SHA="" MERGE_BASE="" TARGET_BRANCH="" SOURCE_REF=""
-  local HAS_DELETE=0 BEST_COUNT=0
-  local rec local_sha remote_sha local_ref remote_ref target resolved_base mb mb_status count count_status
-  for rec in "${REFSPEC_RECORDS[@]}"; do
-    IFS='|' read -r local_sha remote_sha local_ref remote_ref <<<"$rec"
-    target="${remote_ref#refs/heads/}"
-    target="${target#refs/for/}"
-    [[ -z "$target" ]] && target="main"
-    # Defect N: track the SEMANTIC base (the ref the diff was anchored on)
-    # distinctly from `target` (the pushed remote ref). For a tracked branch
-    # they coincide; for a new branch, `target` is the branch name being
-    # created — which is NOT what we reviewed against, so `Target:` must
-    # echo `resolved_base` instead. Default to `target` for the tracked
-    # case; the new-branch path overrides with the resolved default_ref
-    # short name below.
-    resolved_base="$target"
-
-    if [[ "$local_sha" == "$ZERO_SHA" ]]; then
-      HAS_DELETE=1
-      continue
-    fi
-
-    if [[ "$remote_sha" != "$ZERO_SHA" ]]; then
-      if ! (cd "$REA_ROOT" && git cat-file -e "${remote_sha}^{commit}" 2>/dev/null); then
-        {
-          printf 'PUSH BLOCKED: remote object %s is not in the local object DB.\n' "$remote_sha"
-          printf '\n'
-          printf '  The gate cannot compute a review diff without it. Fetch the\n'
-          printf '  remote and retry:\n'
-          printf '\n'
-          printf '    git fetch origin\n'
-          printf '    # then retry the push\n'
-          printf '\n'
-        } >&2
-        exit 2
-      fi
-      mb=$(cd "$REA_ROOT" && git merge-base "$remote_sha" "$local_sha" 2>/dev/null)
-      mb_status=$?
-      if [[ "$mb_status" -ne 0 || -z "$mb" ]]; then
-        {
-          printf 'PUSH BLOCKED: no merge-base between remote %s and local %s\n' \
-            "${remote_sha:0:12}" "${local_sha:0:12}"
-          printf '  The two histories are unrelated; refusing to pass without a\n'
-          printf '  reviewable diff.\n'
-        } >&2
-        exit 2
-      fi
-    else
-      # New branch (remote_sha == ZERO). `target` is the REMOTE ref name (the
-      # branch being created on origin), not a sensible merge-base anchor:
-      # if the local repo already has a branch by that name pointing at
-      # `local_sha`, `git merge-base <target> <local_sha>` returns `local_sha`
-      # — collapsing the reviewable diff to empty and silently bypassing the
-      # gate.
-      #
-      # We MUST anchor on a REMOTE-TRACKING ref (e.g. refs/remotes/origin/main),
-      # not the bare branch name. Bare `main` resolves to the local short ref
-      # `refs/heads/main`, which the pusher controls — a local `main` that has
-      # been fast-forwarded to contain the feature tip (or a rebased topic
-      # branch) would give `merge-base main <local_sha> == local_sha`, silently
-      # passing the gate. Remote-tracking refs are server-authoritative from
-      # the most recent fetch, so they cannot be tampered with locally.
-      #
-      # argv_remote is set from the adapter's argv (git passes the remote name
-      # as $1 on pre-push); defaults to "origin" when absent (BUG-008 sniff).
-      #
-      # Defect N (0.10.1): BEFORE falling back to the remote's default branch,
-      # consult per-branch config `branch.<source>.base`. A feature branch
-      # targeting `dev` in a main-as-production repo would otherwise resolve
-      # against `origin/main` silently, producing a diff that spans the entire
-      # dev→main history — reviewers see "Scope: 28690 lines" for a 4-file
-      # change. The git-config route uses local branch knowledge that is
-      # authoritative for this working copy (set via `git branch --set-upstream`,
-      # or by CI tooling that tracks the intended target). This is consulted
-      # BEFORE origin/HEAD because the latter is a server-default that may
-      # mis-represent the reviewer's actual intent for this specific branch.
-      local default_ref default_ref_status configured_base source_branch
-      source_branch="${local_ref#refs/heads/}"
-      default_ref=""
-      # Codex 0.10.1 finding #1: `local` is function-scoped, not loop-
-      # iteration-scoped — without an explicit reset, iteration N inherits
-      # iteration N-1's configured_base and falsely promotes resolved_base
-      # when the current refspec's local_ref does NOT begin with refs/heads/
-      # (tag push, gerrit-style refs/for/, etc.). Reset before every
-      # potential assignment so each iteration sees a clean slate.
-      configured_base=""
-
-      if [[ -n "$source_branch" && "$source_branch" != "HEAD" ]]; then
-        configured_base=$(cd "$REA_ROOT" && git config --get "branch.${source_branch}.base" 2>/dev/null || echo "")
-        if [[ -n "$configured_base" ]]; then
-          # Prefer the REMOTE-TRACKING form so the gate still anchors on a
-          # server-authoritative ref (see the local-ref hijack explanation
-          # above). Fall back to the local short ref only if the remote
-          # counterpart doesn't exist, with a visible WARN on stderr — the
-          # local ref is less trustworthy and the reviewer should know.
-          if cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/${configured_base}" >/dev/null 2>&1; then
-            default_ref="refs/remotes/${argv_remote}/${configured_base}"
-          elif cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/heads/${configured_base}" >/dev/null 2>&1; then
-            default_ref="refs/heads/${configured_base}"
-            printf 'WARN: branch.%s.base=%s resolved to local ref; remote counterpart %s/%s missing — reviewer-side diff may be stale\n' \
-              "$source_branch" "$configured_base" "$argv_remote" "$configured_base" >&2
-          fi
-        fi
-      fi
-
-      if [[ -z "$default_ref" ]]; then
-        default_ref=$(cd "$REA_ROOT" && git symbolic-ref "refs/remotes/${argv_remote}/HEAD" 2>/dev/null)
-        default_ref_status=$?
-        if [[ "$default_ref_status" -ne 0 || -z "$default_ref" ]]; then
-          # symbolic-ref failed (common on shallow or mirror clones where
-          # origin/HEAD was never set). Probe the common default-branch names in
-          # order: main, then master. Both are remote-tracking refs and still
-          # server-authoritative; the order matters only for projects that still
-          # default to `master` (older internal forks), where without this
-          # fallback the first push of a new branch would fail closed.
-          if cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/main" >/dev/null 2>&1; then
-            default_ref="refs/remotes/${argv_remote}/main"
-          elif cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/master" >/dev/null 2>&1; then
-            default_ref="refs/remotes/${argv_remote}/master"
-          else
-            default_ref=""
-          fi
-        fi
-      fi
-      if [[ -n "$default_ref" ]]; then
-        # Defect N: if operator-configured `branch.<source>.base` resolved the
-        # ref we're about to diff against, overwrite `resolved_base` with the
-        # short name so TARGET_BRANCH (and the Target: label) reflect the
-        # actual review anchor. Without an explicit config override, leave
-        # `resolved_base` at the refspec target — this preserves the cache
-        # contract for new-branch pushes where remote_ref is the same as the
-        # source branch (the common case) and for bare pushes that
-        # argv-resolve via `@{upstream}`. Only operators who opted into a
-        # per-branch base get the label promoted, keeping the change
-        # backward-compatible for every other path.
-        if [[ -n "$configured_base" ]]; then
-          resolved_base="${default_ref#refs/remotes/${argv_remote}/}"
-          resolved_base="${resolved_base#refs/heads/}"
-          [[ -z "$resolved_base" ]] && resolved_base="$default_ref"
-        fi
-        mb=$(cd "$REA_ROOT" && git merge-base "$default_ref" "$local_sha" 2>/dev/null || echo "")
-        if [[ -z "$mb" ]]; then
-          # default_ref resolved but merge-base came back empty (unrelated
-          # histories, grafted branch, or transient git failure). Mirror the
-          # `.husky/pre-push` fix in 701b631 by falling through to the
-          # empty-tree baseline rather than silently `continue`-ing (the
-          # pre-pass-4 behavior). `continue` here combined with the
-          # longest-diff selection below let a protected-path refspec with
-          # an empty merge-base silently bypass the gate whenever another
-          # refspec in the same push was selected as BEST. Flagged HIGH by
-          # Codex pass-4 finding #1.
-          mb='4b825dc642cb6eb9a060e54bf8d69288fbee4904'
-        fi
-      else
-        # Bootstrap: no remote-tracking ref resolved. Use the well-known
-        # empty-tree SHA as the merge-base baseline so the per-refspec diff
-        # covers the full push content and the per-refspec protected-path
-        # check below still runs. Prior behavior silently `continue`d here,
-        # which — combined with the longest-diff selection accumulator at
-        # :822-828 — let a bootstrap protected-path refspec bypass the gate
-        # whenever a second, well-anchored refspec in the same push was
-        # selected as BEST instead. Flagged HIGH by Codex pass-3 and fixed
-        # for the `.husky/pre-push` side in 701b631. `git diff` accepts a
-        # tree SHA as LHS, so :861 `git diff "${MERGE_BASE}..${SOURCE_SHA}"`
-        # (two-dot is required — three-dot would compute an implicit
-        # merge-base with the tree on LHS and fail) works transparently
-        # with this baseline.
-        mb='4b825dc642cb6eb9a060e54bf8d69288fbee4904'
-      fi
-    fi
-    if [[ -z "$mb" ]]; then
-      continue
-    fi
-
-    # Per-refspec protected-path check (Codex pass-4 finding #2). The
-    # BEST_COUNT accumulator below selects a single winning refspec for
-    # the general push-review gate, but the protected-path Codex audit
-    # requirement must run on EVERY refspec — otherwise a multi-refspec
-    # push like `git push origin big-feature:big-feature hotfix:main` can
-    # hide a small protected-path refspec behind a larger, non-protected
-    # one (husky's per-refspec loop at .husky/pre-push:89-175 blocks this
-    # case; pre-pass-4 shared core did not).
-    if [[ "$CODEX_REQUIRED" == "true" ]]; then
-      local _refspec_hits _refspec_diff_status
-      _refspec_hits=$(cd "$REA_ROOT" && git diff --name-status "${mb}..${local_sha}" 2>/dev/null)
-      _refspec_diff_status=$?
-      if [[ "$_refspec_diff_status" -ne 0 ]]; then
-        {
-          printf 'PUSH BLOCKED: git diff --name-status %s..%s failed (exit %s)\n' \
-            "${mb:0:12}" "${local_sha:0:12}" "$_refspec_diff_status"
-          printf '  Refspec: %s\n' "${local_ref:-<unknown>}"
-          printf '  Cannot determine whether protected paths changed; refusing to pass.\n'
-        } >&2
-        exit 2
-      fi
-      if printf '%s\n' "$_refspec_hits" | awk -v re='^(src/gateway/middleware/|hooks/|[.]claude/hooks/|src/policy/|[.]github/workflows/|[.]rea/|[.]husky/)' '
-          {
-            status = $1
-            if (status !~ /^[ACDMRTU]/) next
-            for (i = 2; i <= NF; i++) {
-              if ($i ~ re) { found = 1; next }
-            }
-          }
-          END { exit found ? 0 : 1 }
-        '; then
-        local _audit="${REA_ROOT}/.rea/audit.jsonl"
-        local _codex_ok=0
-        # 0.8.0 (#85): Codex-only waiver satisfies this check without a real
-        # audit entry. Every other gate still ran — HALT, cross-repo guard,
-        # ref-resolution, push-review cache — and the waiver itself is
-        # already recorded in .rea/audit.jsonl as tool_name=codex.review.skipped.
-        if [[ "$CODEX_WAIVER_ACTIVE" == "1" ]]; then
-          _codex_ok=1
-        elif [[ -f "$_audit" ]]; then
-          # Defect P (0.10.1): require .emission_source == "rea-cli" or
-          # "codex-cli" so agents cannot forge a codex.review record by
-          # directly calling appendAuditRecord() from an ad-hoc .mjs script
-          # (the generic helper stamps "other"). Legacy records (pre-0.10.1)
-          # have no emission_source field and are rejected — the first push
-          # on an upgraded consumer requires a fresh `rea audit record
-          # codex-review` (or Codex CLI emission) which stamps "rea-cli".
-          #
-          # Defect T/U (0.10.2): read the audit file as raw lines and parse
-          # each with `fromjson?`. Before 0.10.2 this scan used
-          # `jq -e '<filter>' "$_audit"` which feeds the file as a single
-          # JSON stream — a single malformed line (literal backslash-u
-          # followed by non-hex characters inside a string, for example)
-          # makes jq bail on the stream with exit 2 and the `select` never
-          # runs against ANY record, including legitimate codex.review
-          # entries further down the file. The failure is total: every
-          # cached codex.review receipt becomes unreachable until the
-          # corrupt line is hand-edited out. `-R` flips jq into raw-input
-          # mode (one string per line), and `fromjson?` is the error-
-          # suppressing parser — malformed lines silently yield empty
-          # output. The `select` filter then inspects each successfully
-          # parsed record exactly as before, and `grep -q .` detects
-          # whether ANY record survived the filter. Lines 1107 and the
-          # earlier cache_result scans at :432/:612 operate on a single
-          # printf'd JSON string, not audit.jsonl, so they remain `jq -e`.
-          if jq -R --arg sha "$local_sha" '
-              fromjson?
-              | select(
-                  .tool_name == "codex.review"
-                  and .metadata.head_sha == $sha
-                  and (.metadata.verdict == "pass" or .metadata.verdict == "concerns")
-                  and (.emission_source == "rea-cli" or .emission_source == "codex-cli")
-                )
-            ' "$_audit" 2>/dev/null | grep -q .; then
-            _codex_ok=1
-          fi
-        fi
-        if [[ "$_codex_ok" -eq 0 ]]; then
-          {
-            printf 'PUSH BLOCKED: protected paths changed — /codex-review required for %s\n' "$local_sha"
-            printf '\n'
-            printf '  Source ref: %s\n' "${local_ref:-<unknown>}"
-            printf '  Diff touches one of:\n'
-            printf '    - src/gateway/middleware/\n'
-            printf '    - hooks/\n'
-            printf '    - .claude/hooks/\n'
-            printf '    - src/policy/\n'
-            printf '    - .github/workflows/\n'
-            printf '    - .rea/\n'
-            printf '    - .husky/\n'
-            printf '\n'
-            printf '  Run /codex-review against %s, then retry the push.\n' "$local_sha"
-            printf '  The codex-adversarial agent emits the required audit entry.\n'
-            # shellcheck disable=SC2016  # backticks are literal markdown in user-facing message
-            printf '  Only `pass` or `concerns` verdicts satisfy this gate.\n'
-            printf '\n'
-          } >&2
-          exit 2
-        fi
-      fi
-    fi
-
-    count=$(cd "$REA_ROOT" && git rev-list --count "${mb}..${local_sha}" 2>/dev/null)
-    count_status=$?
-    if [[ "$count_status" -ne 0 ]]; then
-      {
-        printf 'PUSH BLOCKED: git rev-list --count %s..%s failed (exit %s)\n' \
-          "${mb:0:12}" "${local_sha:0:12}" "$count_status"
-        printf '  Cannot size the diff; refusing to pass.\n'
-      } >&2
-      exit 2
-    fi
-    if [[ -z "$count" ]]; then
-      count=0
-    fi
-    if [[ -z "$SOURCE_SHA" ]] || [[ "$count" -gt "$BEST_COUNT" ]]; then
-      SOURCE_SHA="$local_sha"
-      MERGE_BASE="$mb"
-      # Defect N: use `resolved_base` (the actual merge-base anchor we
-      # diffed against), not `target` (the pushed-ref name). For tracked
-      # branches these are the same; for new branches without an upstream
-      # the distinction is the difference between "Target: <source-branch>"
-      # (misleading) and "Target: main" (or whichever base was resolved).
-      TARGET_BRANCH="$resolved_base"
-      SOURCE_REF="$local_ref"
-      BEST_COUNT="$count"
-    fi
-  done
-
-  # Defect J (rea#61): branch-deletion guard MUST fail closed regardless of
-  # whether another refspec in the same push resolved a SOURCE_SHA. A mixed
-  # push like `git push origin safe:safe :main` iterates both refspecs; the
-  # safe refspec sets SOURCE_SHA from its local_sha, and the deletion refspec
-  # sets only HAS_DELETE=1 via its `continue` branch. If we check HAS_DELETE
-  # INSIDE the `-z SOURCE_SHA` fallback, the delete slips through unchecked.
-  # Hoist the check above the fallback so any deletion anywhere in the push
-  # blocks the entire push.
-  if [[ "$HAS_DELETE" -eq 1 ]]; then
-    {
-      printf 'PUSH BLOCKED: refspec is a branch deletion.\n'
-      printf '\n'
-      printf '  Branch deletions are sensitive operations and require explicit\n'
-      printf '  human action outside the agent. Perform the deletion manually.\n'
-      printf '\n'
-    } >&2
-    exit 2
-  fi
-
-  if [[ -z "$SOURCE_SHA" || -z "$MERGE_BASE" ]]; then
-    {
-      printf 'PUSH BLOCKED: could not resolve a merge-base for any push refspec.\n'
-      printf '\n'
-      printf '  Fetch the remote and retry, or name an explicit destination.\n'
-      printf '\n'
-    } >&2
-    exit 2
-  fi
-
-  # Capture git diff exit status explicitly.
-  #
-  # Use two-dot (`A..B`) rather than three-dot (`A...B`). Three-dot form
-  # computes an implicit merge-base between A and B, which FAILS when A
-  # is a tree (e.g. the empty-tree baseline used on bootstrap refspecs
-  # — see pr_parse_prepush_stdin's new-branch block). Two-dot accepts
-  # any revision on the left and is equivalent to `A...B` here because
-  # MERGE_BASE is ALREADY the merge-base of the two commit cases, so the
-  # implicit merge-base in three-dot would be redundant.
-  local DIFF_FULL DIFF_STATUS
-  DIFF_FULL=$(cd "$REA_ROOT" && git diff "${MERGE_BASE}..${SOURCE_SHA}" 2>/dev/null)
-  DIFF_STATUS=$?
-  if [[ "$DIFF_STATUS" -ne 0 ]]; then
-    {
-      printf 'PUSH BLOCKED: git diff %s..%s failed (exit %s)\n' \
-        "${MERGE_BASE:0:12}" "${SOURCE_SHA:0:12}" "$DIFF_STATUS"
-      printf '  Cannot compute reviewable diff; refusing to pass.\n'
-    } >&2
-    exit 2
-  fi
-
-  if [[ -z "$DIFF_FULL" ]]; then
-    exit 0
-  fi
-
-  # Defect K (rea#62): `grep -c ... || echo "0"` captures `0\n0` when grep
-  # exits non-zero on no-match — grep still prints its own `0` to stdout before
-  # exiting, and the `|| echo "0"` branch appends another. `|| true` swallows
-  # the non-zero exit, and `${LINE_COUNT:-0}` defaults an empty result to 0.
-  local LINE_COUNT
-  LINE_COUNT=$(printf '%s' "$DIFF_FULL" | grep -cE '^\+[^+]|^-[^-]' 2>/dev/null || true)
-  LINE_COUNT="${LINE_COUNT:-0}"
-
-  # ── 7a. Protected-path Codex adversarial review gate ──────────────────────
-  # The per-refspec check runs inside the main loop (section 7, above) so
-  # that a multi-refspec push cannot hide a protected-path refspec behind
-  # a larger, non-protected one. See Codex pass-4 finding #2. If any
-  # protected-path refspec lacked a valid Codex audit, the loop already
-  # exited with code 2; reaching this point means every protected-path
-  # refspec was either clean or had an acceptable audit.
-
-  # ── 8. Check review cache ─────────────────────────────────────────────────
-  # Defect L (rea#63): `shasum` is not installed on Alpine, distroless, or
-  # most minimal Linux CI images — only `sha256sum` is. The prior `shasum -a
-  # 256 ... || echo ""` chain silently produced an empty PUSH_SHA, which the
-  # rest of the gate treats as "no cache entry" rather than "hasher missing".
-  # Combined with the silent-cache-miss fallback (Defect F), every push from
-  # such a runner burned a full fresh codex review invisibly.
-  #
-  # Portable chain: sha256sum → shasum → openssl. The openssl branch uses
-  # `awk '{print $NF}'` WITHOUT `-r` — `-r` was added in OpenSSL 3.0 /
-  # LibreSSL 3.3+; on OpenSSL 1.1.1 (Debian 11, Ubuntu 20.04, RHEL 8,
-  # Amazon Linux 2, Alpine 3.13–3.14) `-r` is rejected and stdout is empty.
-  # `$NF` handles BOTH default output shapes: `(stdin)= <hex>` (1.1.x) and
-  # `<hex> *stdin` (3.x/LibreSSL coreutils-style).
-  #
-  # Hex-64 validation catches broken pipes, partial reads, or unexpected
-  # hasher output that would otherwise be silently cached as garbage.
-  local PUSH_SHA=""
-  if command -v sha256sum >/dev/null 2>&1; then
-    PUSH_SHA=$(printf '%s' "$DIFF_FULL" | sha256sum 2>/dev/null | awk '{print $1}')
-  elif command -v shasum >/dev/null 2>&1; then
-    PUSH_SHA=$(printf '%s' "$DIFF_FULL" | shasum -a 256 2>/dev/null | awk '{print $1}')
-  elif command -v openssl >/dev/null 2>&1; then
-    PUSH_SHA=$(printf '%s' "$DIFF_FULL" | openssl dgst -sha256 2>/dev/null | awk '{print $NF}')
-  else
-    printf 'rea push-review: WARN no sha256 hasher found (sha256sum/shasum/openssl); cache disabled\n' >&2
-  fi
-  if [[ -n "$PUSH_SHA" && ! "$PUSH_SHA" =~ ^[0-9a-f]{64}$ ]]; then
-    printf 'rea push-review: WARN hasher returned invalid output; cache disabled\n' >&2
-    PUSH_SHA=""
-  fi
-
-  local -a REA_CLI_ARGS
-  REA_CLI_ARGS=()
-  # node_modules/.bin/rea is a launcher (pnpm writes a POSIX shell shim, npm
-  # writes a symlink to dist/cli/index.js with its own `#!/usr/bin/env node`
-  # shebang). Either way it is NOT a plain JS file, so running `node` on it
-  # would parse shell syntax as JavaScript and SyntaxError. Execute the shim
-  # directly — it handles `exec node` itself — and only prepend `node` on the
-  # dist fallback, which is a real JS module. The `-x` guard picks up both
-  # pnpm shims (executable regular file) and npm symlinks (executable target).
-  if [[ -x "${REA_ROOT}/node_modules/.bin/rea" ]]; then
-    REA_CLI_ARGS=("${REA_ROOT}/node_modules/.bin/rea")
-  elif [[ -f "${REA_ROOT}/dist/cli/index.js" ]]; then
-    REA_CLI_ARGS=(node "${REA_ROOT}/dist/cli/index.js")
-  fi
-
-  # Cache-branch derivation (Codex 0.8.0 pass-2 finding #2, pass-3 finding #1):
-  # Use the PUSHED source ref (from pre-push stdin / bootstrap walk), not the
-  # checkout branch. `git push origin hotfix:main` from a `feature` checkout
-  # must look up a cache entry keyed on `hotfix`, not `feature`. Strip the
-  # `refs/heads/` prefix.
-  #
-  # Fall back to the checkout branch when SOURCE_REF is:
-  #   • unset (defence-in-depth, not reached on any observed path), or
-  #   • the literal string "HEAD" — emitted by pr_resolve_argv_refspecs for a
-  #     bare `git push` with no explicit refspec. Keying a cache lookup on
-  #     "HEAD" would force a miss on every bare push; the checkout branch
-  #     name is the right lookup key for that workflow.
-  local SOURCE_BRANCH="${SOURCE_REF#refs/heads/}"
-  if [[ -z "$SOURCE_BRANCH" || "$SOURCE_BRANCH" == "HEAD" ]]; then
-    SOURCE_BRANCH="$CURRENT_BRANCH"
-  fi
-
-  if [[ -n "$PUSH_SHA" ]] && [[ ${#REA_CLI_ARGS[@]} -gt 0 ]]; then
-    # Defect F (rea#75): distinguish cache-miss from cache-error. Prior version
-    # swallowed all non-zero exits and stderr into a silent `{hit:false}`, which
-    # masked Defect A (0.9.2 `node <shim>` SyntaxError) for weeks. Now we
-    # capture stderr + exit code separately and emit a visible WARN with an
-    # actionable filename when the CLI failed.
-    local CACHE_RESULT
-    local CACHE_STDOUT=""
-    local CACHE_STDERR_FILE
-    # SECURITY (Codex LOW 4): require mktemp. A predictable /tmp path like
-    # /tmp/rea-cache-err.$PID is a TOCTOU attack surface on shared hosts —
-    # another user can pre-create a symlink from that name to a file they
-    # want us to clobber. If mktemp is unavailable, fail loudly rather than
-    # silently falling back to a predictable path.
-    if ! CACHE_STDERR_FILE=$(mktemp -t rea-cache-err.XXXXXX 2>/dev/null); then
-      printf 'rea push-review: mktemp unavailable; cannot capture cache-check stderr. Aborting.\n' >&2
-      return 2
-    fi
-    local CACHE_EXIT=0
-    CACHE_STDOUT=$("${REA_CLI_ARGS[@]}" cache check "$PUSH_SHA" --branch "$SOURCE_BRANCH" --base "$TARGET_BRANCH" 2>"$CACHE_STDERR_FILE") || CACHE_EXIT=$?
-    local CACHE_STDERR=""
-    CACHE_STDERR=$(cat "$CACHE_STDERR_FILE" 2>/dev/null || true)
-    rm -f "$CACHE_STDERR_FILE"
-    if [[ "$CACHE_EXIT" -ne 0 ]]; then
-      # SECURITY (Codex LOW 5): strip C0/C1 control characters from CLI
-      # stderr before echoing to the terminal. A tampered dist/ or hostile
-      # CLI could otherwise emit OSC/CSI sequences that rewrite lines above
-      # the deny message and mislead the operator. We strip both C0 + DEL
-      # AND C1 (0x80-0x9F) — some terminal emulators still honor bare C1
-      # bytes as CSI introducers (0x9B) or OSC (0x9D).
-      local CACHE_STDERR_SAFE
-      CACHE_STDERR_SAFE=$(printf '%s' "$CACHE_STDERR" | LC_ALL=C tr -d '\000-\037\177\200-\237')
-      printf 'rea push-review: CACHE CHECK FAILED (exit=%d): %s\n' "$CACHE_EXIT" "$CACHE_STDERR_SAFE" >&2
-      printf 'rea push-review: treating as miss; file bookedsolidtech/rea issue if unexpected.\n' >&2
-      CACHE_RESULT='{"hit":false,"reason":"query_error"}'
-    elif [[ -z "$CACHE_STDOUT" ]]; then
-      CACHE_RESULT='{"hit":false,"reason":"cold"}'
-    else
-      CACHE_RESULT="$CACHE_STDOUT"
-    fi
-    # Require BOTH hit == true AND result == "pass". A cached `fail` verdict
-    # (Codex 0.8.0 pass-2 finding #1) must NOT satisfy the gate — cache.ts
-    # serializes `result` verbatim, so a negative verdict would otherwise
-    # slip through. Under the #85 narrowed semantic the cache is the ONLY
-    # way a waiver-using operator reaches exit 0, so a permissive predicate
-    # here would be a real security regression.
-    if printf '%s' "$CACHE_RESULT" | jq -e '.hit == true and .result == "pass"' >/dev/null 2>&1; then
-      local DISCORD_LIB="${REA_ROOT}/hooks/_lib/discord.sh"
-      if [ -f "$DISCORD_LIB" ]; then
-        # shellcheck source=/dev/null
-        source "$DISCORD_LIB"
-        discord_notify "dev" "Push passed quality gates on \`${SOURCE_BRANCH}\` -- $(cd "$REA_ROOT" && git log -1 --oneline 2>/dev/null)" "green"
-      fi
-      exit 0
-    fi
-  fi
-
-  # ── 9. Block and request review ───────────────────────────────────────────
-  # Defect K (rea#62): same `0\n0` bug as LINE_COUNT above.
-  local FILE_COUNT
-  FILE_COUNT=$(printf '%s' "$DIFF_FULL" | grep -c '^\+\+\+ ' 2>/dev/null || true)
-  FILE_COUNT="${FILE_COUNT:-0}"
-
-  {
-    printf 'PUSH REVIEW GATE: Review required before pushing\n'
-    printf '\n'
-    printf '  Source ref: %s (%s)\n' "${SOURCE_REF:-HEAD}" "${SOURCE_SHA:0:12}"
-    printf '  Target: %s\n' "$TARGET_BRANCH"
-    printf '  Scope: %s files changed, %s lines\n' "$FILE_COUNT" "$LINE_COUNT"
-    printf '\n'
-    printf '  Action required:\n'
-    printf '  1. Spawn a code-reviewer agent to review: git diff %s..%s\n' "$MERGE_BASE" "$SOURCE_SHA"
-    printf '  2. Spawn a security-engineer agent for security review\n'
-    # Defect L (rea#63) follow-up: when no sha256 hasher is available the
-    # cache is disabled and PUSH_SHA is empty. Emitting `rea cache set <blank>
-    # pass ...` would be a dead-end — the CLI rejects the empty positional.
-    # Print an alternate completion path in that case. The Codex-adversarial
-    # review concerns list flagged this UX cliff in the 0.9.4 pass.
-    if [[ -n "$PUSH_SHA" ]]; then
-      printf '  3. After both pass, cache the result:\n'
-      printf '     rea cache set %s pass --branch %s --base %s\n' "$PUSH_SHA" "$SOURCE_BRANCH" "$TARGET_BRANCH"
-    else
-      printf '  3. Cache is DISABLED on this host (no sha256 hasher found).\n'
-      printf '     After both reviews pass, bypass the push-review gate with:\n'
-      printf '       REA_SKIP_PUSH_REVIEW="<reason>" git push ...\n'
-      printf '     The bypass is audited as push.review.skipped — this is the\n'
-      printf '     documented escape hatch when cache is unavailable.\n'
-      printf '     To restore the cache path, install one of: sha256sum,\n'
-      printf '     shasum (Perl Digest::SHA), or openssl.\n'
-    fi
-    printf '\n'
-  } >&2
-  exit 2
-}