@boyingliu01/xp-gate 0.19.3 → 0.20.0

package/gate-8.sh

@@ -19,16 +19,60 @@ fi
 if [ -n "$GITLEAKS_CMD" ]; then
   GITLEAKS_CONFIG=""
   if [ -f ".gitleaks.toml" ]; then
-    GITLEAKS_CONFIG="--config=.gitleaks.toml"
+    # gitleaks is a native binary and may not understand MSYS paths, so pass an
+    # absolute path in the host's own format when we can derive one (#449).
+    if command -v cygpath >/dev/null 2>&1; then
+      GITLEAKS_CONFIG="--config=$(cygpath -w "$(pwd)/.gitleaks.toml")"
+    else
+      GITLEAKS_CONFIG="--config=$(pwd)/.gitleaks.toml"
+    fi
   fi
 
-  # Run gitleaks on staged changes only (pre-commit mode for speed)
-  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --pre-commit --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path=/tmp/gitleaks-report.json 2>&1)
+  # Scan the INDEX, not history. gitleaks 8.x `git --pre-commit` walks committed
+  # revisions and reports "0 commits scanned" on a pre-commit run -- so a staged
+  # secret was never seen and Gate 8 always passed. `git --staged` scans
+  # `git diff --cached`, which is exactly the pre-commit payload (#449).
+  GITLEAKS_REPORT="${TMPDIR:-/tmp}/gitleaks-report.json"
+  rm -f "$GITLEAKS_REPORT"
+  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --staged --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
   GITLEAKS_EXIT=$?
 
   if [ "$GITLEAKS_EXIT" -eq 0 ]; then
-    echo "     ✅ PASSED - No secrets detected."
-    GATE_8_STATUS="PASS"
+    # Decide SKIP from the REPORT ARTIFACT, not from log wording. Parsing stdout
+    # meant a gitleaks message change would silently turn a no-evidence run into
+    # a PASS -- the same fail-open class this gate just fixed (#449).
+    # The report exists and is a JSON array of findings; `[]` == clean scan.
+    GITLEAKS_FINDINGS="?"
+    if [ -f "$GITLEAKS_REPORT" ]; then
+      # A report that is not shaped like a JSON array is no evidence: leave the
+      # '?' sentinel so the gate reports SKIP, never a PASS it cannot support
+      # (the fail-closed-on-the-claim rule #449 established).
+      if grep -q '^\[' "$GITLEAKS_REPORT" 2>/dev/null; then
+        # Count occurrences, not matching lines: `grep -c` prints its own zero AND
+        # exits 1 on a clean report, so the old `|| echo 0` handed the verdict table
+        # $'0\n0' -- no branch matched and a clean scan was BLOCKED as if it leaked
+        # (#493). wc -l emits exactly one value, and `|| true` keeps the assignment
+        # errexit/pipefail-safe (#489).
+        GITLEAKS_FINDINGS=$(grep -o '"RuleID"' "$GITLEAKS_REPORT" 2>/dev/null | wc -l | tr -d '[:space:]') || true
+      fi
+    fi
+
+    if [ "$GITLEAKS_FINDINGS" = "0" ]; then
+      echo "     ✅ PASSED - No secrets detected."
+      GATE_8_STATUS="PASS"
+    elif [ "$GITLEAKS_FINDINGS" = "?" ]; then
+      # Exit 0 but no readable report: we have no evidence the scan happened.
+      # Fail closed on the *claim*: report SKIP, never PASS.
+      echo "     ⚠️  gitleaks exited 0 but produced no readable report"
+      echo "     ⏭️  SKIPPED - secret scanning produced no evidence (not a pass)"
+      GATE_8_STATUS="SKIP"
+    else
+      echo "     ❌ BLOCKED - gitleaks reported $GITLEAKS_FINDINGS finding(s)"
+      echo "$GITLEAKS_OUTPUT"
+      echo ""
+      echo "Remediation: remove the secret, or allowlist a false positive in .gitleaks.toml."
+      exit 1
+    fi
   elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
     # Secrets found — output details
     echo "$GITLEAKS_OUTPUT"

package/hooks/gate-10.sh

@@ -33,15 +33,39 @@ else
     echo "     ⏭️  SKIPPED - SAST (no supported language files changed)"
     GATE_10_STATUS="SKIP"
   else
+    # One path per line into an array. Quoting the newline-joined list would hand
+    # semgrep ONE argument containing newlines -> "Invalid scanning root" once
+    # >=2 files are staged (#490). Same defect class as the Gate 4 --files fix
+    # (#457): an array is the only form that keeps spaces intact AND splits files.
+    #
+    # Each element gets a ./ prefix: a tracked path may legitimately start with
+    # '-' (`git add -- ./-o.ts`), and bare in argv that element reads as an option
+    # and rewrites the scan it was meant to constrain. ./ is a path to every
+    # argument parser.
+    #
+    # The unquoted heredoc below expands $SEMGREP_FILES once, then feeds literal
+    # lines to `read`; bash never rescans the result for separators. Its correct
+    # reading rests on one property of the producer above, not of the loop:
+    # `git diff --cached --name-only` terminates paths with LF and quotes control
+    # characters (a CR in a name arrives as the four bytes \215, never as a bare
+    # CR), so one line is exactly one path. Asserted for spaces and a leading '-'
+    # by AC-490-04.
+    SEMGREP_ARGS=()
+    while IFS= read -r _semgrep_file; do
+      [ -n "$_semgrep_file" ] && SEMGREP_ARGS+=("./$_semgrep_file")
+    done <<EOF
+$SEMGREP_FILES
+EOF
+
     # Run semgrep with JSON output
     # --config=p/security-audit: explicit security ruleset
     # --json: machine-readable output
     # --disable-version-check: skip network call
-    SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check "$SEMGREP_FILES" 2>&1)
+    SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check "${SEMGREP_ARGS[@]}" 2>&1)
     SEMGREP_EXIT=$?
 
     if [ "$SEMGREP_EXIT" -eq 0 ]; then
-      echo "     ✅ PASSED - No security vulnerabilities found."
+      echo "     ✅ PASSED - No security vulnerabilities found (files scanned: ${#SEMGREP_ARGS[@]})."
       GATE_10_STATUS="PASS"
     elif [ "$SEMGREP_EXIT" -eq 1 ]; then
       # Findings detected - parse JSON to categorize
@@ -96,7 +120,16 @@ console.log('  ['+severity+'] '+ruleId);console.log('  '+path+':'+line+' → '+m
       fi
     else
       # semgrep runtime error (timeout, config error, etc.)
+      #
+      # SEMGREP_OUTPUT is captured above and was never shown here, so an intermittent
+      # ruleset-fetch failure looked identical to a broken install: the gate printed
+      # "runtime error" and kept the reason to itself (#475). The verdict stays SKIP --
+      # an operational failure must not block the commit, and must not be called a pass.
       echo "     ⚠️  semgrep exited with code ${SEMGREP_EXIT} — skipping gate"
+      if [ -n "$SEMGREP_OUTPUT" ]; then
+        echo "     ── what semgrep reported ──"
+        printf '%s\n' "$SEMGREP_OUTPUT" | tail -10 | sed 's/^/     /'
+      fi
       echo "     ⏭️  SKIPPED - SAST (semgrep runtime error)"
       GATE_10_STATUS="SKIP"
     fi

package/hooks/gate-4.sh

@@ -3,6 +3,26 @@
 # Reuses existing principles checker logic
 # ============================================================================
 
+# Run a TypeScript entrypoint under tsx without routing arguments through the
+# npx shim: Windows cmd.exe caps command lines at 8191 chars and long staged
+# file lists overflow it, turning a healthy run into a false BLOCK. Prefer the
+# repo-local tsx CLI driven by node directly; keep npx as fallback for consumer
+# repos relying on a global install. Defined here as well so this module also
+# works when sourced outside pre-commit.
+if ! declare -F run_tsx >/dev/null 2>&1; then
+  run_tsx() {
+    local _root="${PROJECT_ROOT:-$(pwd)}" _timeout=()
+    if [ -n "${RUN_TSX_TIMEOUT:-}" ]; then
+      _timeout=(timeout "$RUN_TSX_TIMEOUT")
+    fi
+    if [ -f "$_root/node_modules/tsx/dist/cli.mjs" ] && command -v node >/dev/null 2>&1; then
+      "${_timeout[@]}" node "$_root/node_modules/tsx/dist/cli.mjs" "$@"
+    else
+      "${_timeout[@]}" npx tsx "$@"
+    fi
+  }
+fi
+
  2>&1 echo ""
  2>&1 echo "→ Gate 4: Principles checker (Clean Code + SOLID)..."
 GATE_4_START=$(gate_start_ms)
@@ -16,29 +36,101 @@ if [ "$PROJECT_LANG" = "documentation-only" ]; then
 else
   # Get source files to check against principles
   PRINCIPLES_FILES=$(echo "$CHANGED_FILES" | grep -E '\.(ts|tsx|js|jsx|py|go|java|kt|dart|swift|cpp|c|hpp|h|m|mm)$' || true)
+
+  # One path per line, into an array. Passing $PRINCIPLES_FILES unquoted relies on
+  # word splitting to turn the list into separate argv entries, which also splits
+  # any path containing a space -- handing the checker two bogus paths and checking
+  # neither. Quoting it would instead collapse the list into one argument. An array
+  # is the only form that does both. Same defect class as the --config fix (#457).
+  PRINCIPLES_ARGS=()
+  while IFS= read -r _principles_file; do
+    [ -n "$_principles_file" ] && PRINCIPLES_ARGS+=("$_principles_file")
+  done <<< "$PRINCIPLES_FILES"
   
   if [ -n "$PRINCIPLES_FILES" ]; then
-    # Check for principles checker in installed modules first, then project src/
+    # The checker resolves every path it is given -- and every path in CHANGED_FILES
+    # comes from `git diff`, so it is repo-root relative -- against its own working
+    # directory. Resolving against the hook's CWD broke in single-language subdir
+    # mode, where pre-commit has already cd'd into $PROJECT_SUBDIR: web/src/a.ts was
+    # looked up as web/web/src/a.ts, the probes below missed the checker that was
+    # installed one level up, and a working gate degraded to SKIPPED (#478).
+    # Everything this gate reads is therefore anchored at the repo root.
+    PRINCIPLES_BASE="${PROJECT_ROOT:-$(pwd)}"
+
     PRINCIPLES_DIR=""
-    if [ -d ".xp-gate/modules/principles" ]; then
-      PRINCIPLES_DIR=".xp-gate/modules/principles"
-    elif [ -f "src/principles/index.ts" ]; then
-      PRINCIPLES_DIR="src/principles"
-    elif [ -d "$HOME/.config/xp-gate/modules/principles" ]; then
-      PRINCIPLES_DIR="$HOME/.config/xp-gate/modules/principles"
-    fi
+    for _principles_candidate in \
+      "$PRINCIPLES_BASE/.xp-gate/modules/principles" \
+      "$PRINCIPLES_BASE/src/principles" \
+      "$(pwd)/.xp-gate/modules/principles" \
+      "$(pwd)/src/principles" \
+      "$HOME/.config/xp-gate/modules/principles"; do
+      if [ -f "$_principles_candidate/index.ts" ]; then
+        PRINCIPLES_DIR="$_principles_candidate"
+        break
+      fi
+    done
     
     if [ -n "$PRINCIPLES_DIR" ]; then
       echo "Checking Clean Code + SOLID principles..."
       
-      if command -v npx > /dev/null 2>&1; then
-        # Run principles checker and store results
-        if npx tsx $PRINCIPLES_DIR/index.ts --files $PRINCIPLES_FILES --format json > /tmp/principles-output.json 2>/dev/null; then
-          # Check severity levels
-          ERROR_COUNT=$(grep -c '"severity":"error"' /tmp/principles-output.json 2>/dev/null || true)
+      if command -v npx > /dev/null 2>&1 || [ -f "$PRINCIPLES_BASE/node_modules/tsx/dist/cli.mjs" ]; then
+        # Run principles checker and store results.
+        #
+        # Do NOT wrap this in `if ...; then`: the checker's exit codes are
+        # deliberately distinct (0 clean, 1 ERROR-severity findings, >=2 tool
+        # failure), and an `if` collapses 1 and 2 into "failed". That sent real
+        # error-severity findings down the crash branch, which SKIPs and prints
+        # PASSED -- releasing exactly the most serious violations.
+        # The trailing `|| PRINCIPLES_EXIT=$?` captures the exit status without
+        # letting a non-zero return abort the hook under `set -e`. pre-commit itself
+        # runs with only `set -o pipefail` (no `set -e`, pinned by
+        # scripts/__tests__/gate-5-runner-error.test.ts AC-454-08), but this module is
+        # also sourced by consumer hooks that may set it, and a bare call followed by
+        # `PRINCIPLES_EXIT=$?` never reaches the assignment under `set -e`. `|| true`
+        # would erase the status -- which is exactly the distinction this gate depends
+        # on.
+        PRINCIPLES_EXIT=0
+        # Keep stderr: it carries the checker's configuration warnings -- a rejected
+        # threshold or an out-of-vocabulary severity says so here and nowhere else.
+        # Sending it to /dev/null made an exit-2 SKIP undiagnosable and hid every
+        # .principlesrc typo (Delphi walkthrough MC-03). Captured to a file so a clean
+        # run stays quiet, then replayed only when the checker had a problem.
+        #
+        # `cd || exit 2`: a base we cannot enter means the checker never ran, which is
+        # this module's tool-failure code. Falling through would return the exit status
+        # of the failed cd (1), and 1 asserts "I examined files and found errors" -- an
+        # empty report at 1 reads as a clean pass.
+        #
+        # The report is a PER-INVOCATION mktemp, not a shared `/tmp/principles-output.json`:
+        # two commits racing on one machine (two worktrees, a hook and a CI job) overwrote
+        # each other's report before it was counted, so a run with ERROR findings could
+        # read a clean report and PASS (#457). PRINCIPLES_JSON is exported so a caller can
+        # point a harness at the same file.
+        PRINCIPLES_STDERR=$(mktemp)
+        PRINCIPLES_JSON=$(mktemp)
+        export PRINCIPLES_JSON
+        ( cd "$PRINCIPLES_BASE" 2>/dev/null || exit 2
+          run_tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format json ) > "$PRINCIPLES_JSON" 2>"$PRINCIPLES_STDERR" || PRINCIPLES_EXIT=$?
+
+        if [ -s "$PRINCIPLES_STDERR" ]; then
+          sed 's/^/     /' "$PRINCIPLES_STDERR"
+        fi
+        rm -f "$PRINCIPLES_STDERR"
+
+        if [ "$PRINCIPLES_EXIT" -ge 2 ]; then
+          echo "⚠️  Warning: Principles checker execution failed"
+          echo "⏭️  SKIPPED - Principles check (execution issue)"
+          GATE_4_STATUS="SKIP"
+          rm -f "$PRINCIPLES_JSON"
+        else
+          # Check severity levels. The reporter emits JSON.stringify(out, null, 2),
+          # i.e. `"severity": "warning"` WITH a space; tolerate any whitespace so a
+          # future minified format cannot silently zero these counts again (#444).
+          ERROR_COUNT=$(grep -cE '"severity"[[:space:]]*:[[:space:]]*"error"' "$PRINCIPLES_JSON" 2>/dev/null || true)
           ERROR_COUNT=${ERROR_COUNT:-0}
-          WARNING_COUNT=$(grep -c '"severity":"warning"' /tmp/principles-output.json 2>/dev/null || true)
+          WARNING_COUNT=$(grep -cE '"severity"[[:space:]]*:[[:space:]]*"warning"' "$PRINCIPLES_JSON" 2>/dev/null || true)
           WARNING_COUNT=${WARNING_COUNT:-0}
+          rm -f "$PRINCIPLES_JSON"
           
           if [ "$ERROR_COUNT" -gt 0 ]; then
             echo ""
@@ -47,7 +139,8 @@ else
             echo "  - error-handling violations"
             echo "  - SOLID principle violations"
             echo "  - architectural violations"
-            npx tsx $PRINCIPLES_DIR/index.ts --files $PRINCIPLES_FILES --format console
+            ( cd "$PRINCIPLES_BASE" 2>/dev/null || exit 2
+              run_tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format console )
             GATE_4_STATUS="FAIL"
             exit 1
           fi
@@ -57,14 +150,10 @@ else
           if [ "$WARNING_COUNT" -gt 0 ]; then
             echo "ℹ️  $WARNING_COUNT warnings found (will be handled by Boy Scout Rule)."
           fi
-        else
-          echo "⚠️  Warning: Principles checker execution failed"
-          echo "⏭️  SKIPPED - Principles check (execution issue)"
-          GATE_4_STATUS="SKIP"
         fi
       else
-        echo "ℹ️  npx not available - skipping principles check"
-        echo "⏭️  SKIPPED - Principles check (no Node.js/npx)"
+        echo "ℹ️  npx/tsx not available - skipping principles check"
+        echo "⏭️  SKIPPED - Principles check (no Node.js/tsx)"
         GATE_4_STATUS="SKIP"
       fi
     else

package/hooks/gate-8.sh

@@ -19,16 +19,60 @@ fi
 if [ -n "$GITLEAKS_CMD" ]; then
   GITLEAKS_CONFIG=""
   if [ -f ".gitleaks.toml" ]; then
-    GITLEAKS_CONFIG="--config=.gitleaks.toml"
+    # gitleaks is a native binary and may not understand MSYS paths, so pass an
+    # absolute path in the host's own format when we can derive one (#449).
+    if command -v cygpath >/dev/null 2>&1; then
+      GITLEAKS_CONFIG="--config=$(cygpath -w "$(pwd)/.gitleaks.toml")"
+    else
+      GITLEAKS_CONFIG="--config=$(pwd)/.gitleaks.toml"
+    fi
   fi
 
-  # Run gitleaks on staged changes only (pre-commit mode for speed)
-  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --pre-commit --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path=/tmp/gitleaks-report.json 2>&1)
+  # Scan the INDEX, not history. gitleaks 8.x `git --pre-commit` walks committed
+  # revisions and reports "0 commits scanned" on a pre-commit run -- so a staged
+  # secret was never seen and Gate 8 always passed. `git --staged` scans
+  # `git diff --cached`, which is exactly the pre-commit payload (#449).
+  GITLEAKS_REPORT="${TMPDIR:-/tmp}/gitleaks-report.json"
+  rm -f "$GITLEAKS_REPORT"
+  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --staged --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
   GITLEAKS_EXIT=$?
 
   if [ "$GITLEAKS_EXIT" -eq 0 ]; then
-    echo "     ✅ PASSED - No secrets detected."
-    GATE_8_STATUS="PASS"
+    # Decide SKIP from the REPORT ARTIFACT, not from log wording. Parsing stdout
+    # meant a gitleaks message change would silently turn a no-evidence run into
+    # a PASS -- the same fail-open class this gate just fixed (#449).
+    # The report exists and is a JSON array of findings; `[]` == clean scan.
+    GITLEAKS_FINDINGS="?"
+    if [ -f "$GITLEAKS_REPORT" ]; then
+      # A report that is not shaped like a JSON array is no evidence: leave the
+      # '?' sentinel so the gate reports SKIP, never a PASS it cannot support
+      # (the fail-closed-on-the-claim rule #449 established).
+      if grep -q '^\[' "$GITLEAKS_REPORT" 2>/dev/null; then
+        # Count occurrences, not matching lines: `grep -c` prints its own zero AND
+        # exits 1 on a clean report, so the old `|| echo 0` handed the verdict table
+        # $'0\n0' -- no branch matched and a clean scan was BLOCKED as if it leaked
+        # (#493). wc -l emits exactly one value, and `|| true` keeps the assignment
+        # errexit/pipefail-safe (#489).
+        GITLEAKS_FINDINGS=$(grep -o '"RuleID"' "$GITLEAKS_REPORT" 2>/dev/null | wc -l | tr -d '[:space:]') || true
+      fi
+    fi
+
+    if [ "$GITLEAKS_FINDINGS" = "0" ]; then
+      echo "     ✅ PASSED - No secrets detected."
+      GATE_8_STATUS="PASS"
+    elif [ "$GITLEAKS_FINDINGS" = "?" ]; then
+      # Exit 0 but no readable report: we have no evidence the scan happened.
+      # Fail closed on the *claim*: report SKIP, never PASS.
+      echo "     ⚠️  gitleaks exited 0 but produced no readable report"
+      echo "     ⏭️  SKIPPED - secret scanning produced no evidence (not a pass)"
+      GATE_8_STATUS="SKIP"
+    else
+      echo "     ❌ BLOCKED - gitleaks reported $GITLEAKS_FINDINGS finding(s)"
+      echo "$GITLEAKS_OUTPUT"
+      echo ""
+      echo "Remediation: remove the secret, or allowlist a false positive in .gitleaks.toml."
+      exit 1
+    fi
   elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
     # Secrets found — output details
     echo "$GITLEAKS_OUTPUT"

package/hooks/lib/jscpd-run.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# ============================================================================
+# Gate 2 duplicate-code helpers (issue #477)
+#
+# Extracted from pre-commit so the outcome contract is unit-testable without
+# executing the hook, and so an installed hook can source it the same way it
+# sources the other libraries in this directory.
+# ============================================================================
+
+# Echo the jscpd config the gate should pass, or nothing when the project has
+# none.
+#
+# pre-commit used to hand jscpd `--config jscpd.conf.json` unconditionally. When
+# that file was not in the working directory jscpd printed
+# "config file jscpd.conf.json: ... (os error 2)" and the gate then read the
+# non-zero exit as "duplicates found" -- a fabricated finding on top of a
+# fabricated error (#477). The probe is anchored at PROJECT_ROOT first because
+# git hands the gate repo-root-relative state while the hook may have cd'd into
+# a language subdirectory.
+resolve_jscpd_config() {
+  local _base="${PROJECT_ROOT:-$(pwd)}" _candidate
+  for _candidate in "$_base/jscpd.conf.json" "$(pwd)/jscpd.conf.json"; do
+    if [ -f "$_candidate" ]; then
+      printf '%s\n' "$_candidate"
+      return 0
+    fi
+  done
+  return 0
+}
+
+# Echo exactly one of `clean`, `duplicates`, `error` for a finished jscpd run.
+#
+#   $1 -- the tool's exit status
+#   $2 -- everything it printed (stdout and stderr together)
+#
+# jscpd's exit status cannot carry this distinction: the default CLI exits 0
+# after a report that contains clones, and exits non-zero for a config or IO
+# failure that produced no report at all. The report is the evidence; the exit
+# status only explains a run that left none.
+#
+# Nothing here blocks or unblocks: Gate 2's severity is unchanged (duplicates
+# stay a warning). This only stops the gate from naming the wrong reason.
+classify_jscpd_run() {
+  local _exit="$1" _out="$2" _report _count
+  _report=$(printf '%s' "$_out" | grep -oE 'Found [0-9]+ (clones?|duplicates?)' | tail -1)
+  if [ -n "$_report" ]; then
+    _count=$(printf '%s' "$_report" | sed -E 's/^Found ([0-9]+).*/\1/')
+    if [ "$_count" -gt 0 ] 2>/dev/null; then
+      printf 'duplicates\n'
+    else
+      printf 'clean\n'
+    fi
+    return 0
+  fi
+  if [ "$_exit" -ne 0 ] 2>/dev/null; then
+    printf 'error\n'
+    return 0
+  fi
+  # Exit 0 with no report: the run said nothing we can stand behind, but calling
+  # it an error would turn every unfamiliar jscpd format into a SKIP. Leave the
+  # gate's verdict as it was.
+  printf 'clean\n'
+}

package/hooks/lib/sprint-gate-report.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# ============================================================================
+# Gate 11 Sprint Flow reporting helpers (issue #476)
+#
+# Extracted from pre-commit so the resolution chain and the decision translation
+# are unit-testable without executing the hook, and reachable from an installed
+# hook through the lib/ directory install.sh copies beside it.
+# ============================================================================
+
+# Echo the first <dir>/sprint-gate.sh that exists among the given directories.
+#
+# The chain used to stop after three tiers that all point at *gate script*
+# directories. The flat global layout ($HOME/.config/xp-gate/adapters) holds
+# gate-3/4/7/8/9/10.sh but not sprint-gate.sh, which update-hooks installs under
+# $HOME/.config/xp-gate/hooks instead -- so a machine with the canonical install
+# reported "sprint-gate.sh not found" about a file that was there (#476).
+#
+# Returns non-zero when nothing matched; the caller must then name every place it
+# looked.
+resolve_sprint_gate_script() {
+  local _dir
+  for _dir in "$@"; do
+    [ -n "$_dir" ] || continue
+    if [ -f "$_dir/sprint-gate.sh" ]; then
+      printf '%s\n' "$_dir/sprint-gate.sh"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Echo the decision verb from a sprint-gate JSON line: allow, deny, skip, or
+# unknown when the text carries no recognisable decision at all.
+#
+# jq is not a dependency of the hooks, so this reads the field the way it is
+# actually written by sprint-gate.sh: one flat object per line.
+sprint_gate_decision() {
+  local _decision
+  _decision=$(printf '%s' "${1:-}" | sed -n 's/.*"decision"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | tail -1)
+  case "$_decision" in
+    allow|deny|skip) printf '%s\n' "$_decision" ;;
+    *) printf 'unknown\n' ;;
+  esac
+}
+
+# Echo the human-readable detail of a decision (reason, message, or warning --
+# in that order of preference), or nothing when the gate gave none.
+sprint_gate_detail() {
+  local _out="${1:-}" _field _detail
+  for _field in reason message warning; do
+    _detail=$(printf '%s' "$_out" | sed -n "s/.*\"$_field\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | tail -1)
+    if [ -n "$_detail" ]; then
+      printf '%s\n' "$_detail"
+      return 0
+    fi
+  done
+  return 0
+}

package/hooks/lib/test-failure.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# Gate 5 exit-code judgement for vitest runs, shared by every pre-commit branch
+# that invokes vitest. Sourced by githooks/pre-commit; kept in its own file so
+# the contract is unit-testable without executing the hook
+# (githooks/__tests__/gate-5-runner-error.test.bats, gate-5-partial-threshold.test.bats).
+
+# The one condition every excuse below shares: a real failure always wins.
+#
+# Kept as a single expression because a marker added for one exit class and
+# forgotten in another re-opens the false BLOCK the excuse exists to close.
+has_real_failure_marker() {
+  printf '%s' "$1" | grep -qE 'Tests +[0-9]+ failed|FAIL |AssertionError'
+}
+
+# Detect a vitest *runner infrastructure* failure as opposed to a real test
+# failure. On Windows, vitest 1.6.x can exit non-zero while reporting zero failed
+# tests, because its temp/ssr module cache hits EPERM (#454). Treating that as
+# "Tests FAILED" sends developers chasing a bug that does not exist.
+#
+# The two patterns below are vitest's DEFAULT-REPORTER shape for the assumed major
+# (declared as `vitest: ^1.6.1` in package.json). They are not universal: a reporter
+# change or a vitest 2 upgrade could stop emitting "Unhandled Error", and the
+# detection would silently revert to false BLOCKs. That assumption is therefore
+# asserted, not assumed -- scripts/__tests__/gate-5-runner-error.test.ts
+# (AC-454-07) fails the moment the declared version leaves the pinned range, which
+# is the signal to re-verify these patterns against the new output shape.
+#
+# Returns 0 (true) only when both hold:
+#   - the output mentions "Unhandled Error" (vitest's runner-level failure), AND
+#   - no real test failure marker is present.
+is_runner_infrastructure_error() {
+  local _out="$1"
+  [ -n "$_out" ] || return 1
+  printf '%s' "$_out" | grep -qE 'Unhandled Error' || return 1
+  has_real_failure_marker "$_out" && return 1
+  return 0
+}
+
+# Detect the partial-run coverage-threshold exit (#473).
+#
+# Gate 5's "changed test files" and "related test files" branches run
+# `npx vitest run --coverage <a few files>`. vitest applies the project's GLOBAL
+# coverage thresholds to whatever subset it ran, so a subset in which every test
+# passed still exits 1 with
+#   ERROR: Coverage for lines (10.87%) does not meet global threshold (80%)
+# Reading that as "Tests FAILED" false-blocked every partial run on any machine
+# with node installed.
+#
+# Scoped to PARTIAL_TEST_RUN=true on purpose: a full-suite threshold miss is a
+# genuine coverage failure and must still block.
+#
+# Returns 0 only when all three hold:
+#   - this was a partial run,
+#   - the output carries the threshold complaint, AND
+#   - no real test failure marker is present.
+is_partial_threshold_only_exit() {
+  local _out="$1"
+  [ "${PARTIAL_TEST_RUN:-false}" = "true" ] || return 1
+  [ -n "$_out" ] || return 1
+  printf '%s' "$_out" | grep -qE 'does not meet global threshold' || return 1
+  # A real failure must still block.
+  has_real_failure_marker "$_out" && return 1
+  return 0
+}
+
+# Detect the third non-failure exit: vitest found nothing to run at all (#498).
+#
+# A TypeScript project with no test files, and a partial run whose every target
+# falls outside the suite it is being run from, both make vitest print
+#   No test files found, exiting with code 1
+# and exit non-zero. No test failed; none ran. Reporting that as "Tests FAILED"
+# blocked every commit in such a repo, including the fixtures that were written
+# to prove Gate 5a blocks a *missing test* (githooks/__tests__/gate-5a-block.test.bats
+# died in setup, before any assertion of its own was reached).
+#
+# Matched as vitest's whole sentence including its exit-code clause rather than
+# as the bare phrase: a test that logs the phrase from its own title describes a
+# run that did collect files, and must not be excused.
+#
+# Returns 0 only when both hold:
+#   - the output carries vitest's no-test-files sentence, AND
+#   - no real test failure marker is present.
+is_no_test_files_found() {
+  local _out="$1"
+  [ -n "$_out" ] || return 1
+  printf '%s' "$_out" | grep -qE 'No test files found, exiting with code [0-9]+' || return 1
+  has_real_failure_marker "$_out" && return 1
+  return 0
+}
+
+# Judge a non-zero vitest exit and report the outcome (Issues #454, #473, #498).
+#
+# Before this helper existed, each Gate 5 branch carried its own
+# `echo "❌ BLOCKED - Tests FAILED"`, and only ONE of them consulted
+# is_runner_infrastructure_error. The others therefore reported a Windows
+# EPERM-on-temp-cache runner error as a genuine test failure, sending
+# developers hunting for a bug that did not exist. Routing every vitest branch
+# through one helper makes that class of drift structurally impossible.
+#
+# Usage: handle_test_failure <output> <site-context>
+#   $1 = captured test output (passed EXPLICITLY -- never read a global, so a
+#        branch that forgets to set one fails loudly instead of silently
+#        treating empty output as "no runner error")
+#   $2 = short context label used in the BLOCK message; may be empty
+# Returns 0 when the run should be treated as SKIPPED (a runner infrastructure
+# error, a partial run that only missed the global coverage threshold, or a run
+# that matched no test files at all), 1 when it must BLOCK. Callers use
+# `|| exit 1`.
+#
+# NOTE: only vitest branches may call this. The generic `run_tests` fallbacks
+# (non-TS adapters) are deliberately left unguarded: their output format is not
+# guaranteed to look like vitest's, so guarding them could let a real failure
+# through.
+handle_test_failure() {
+  local _out="$1"
+  local _ctx="$2"
+  if is_runner_infrastructure_error "$_out"; then
+    echo ""
+    echo "⏭️  SKIPPED - vitest runner infrastructure error (no test failed)"
+    echo "    Detected: Unhandled Errors with 0 failed tests."
+    echo "    Known Windows issue: EPERM on vitest temp/ssr cache (#454)."
+    echo "    Workaround: npx vitest run --no-file-parallelism <targets>"
+    TESTS_SKIPPED=true
+    TESTS_EXIT_CODE=0
+    return 0
+  fi
+  if is_partial_threshold_only_exit "$_out"; then
+    echo ""
+    echo "⏭️  SKIPPED - coverage threshold judgement for this partial run (no test failed)"
+    echo "    Detected: 'does not meet global threshold' with 0 failed tests."
+    echo "    vitest scores the whole project against a subset of tests (#473)."
+    echo "    Full-suite coverage is still enforced by the full run and by CI."
+    TESTS_EXIT_CODE=0
+    # TESTS_SKIPPED is deliberately NOT set here, unlike the runner-error path:
+    # this run produced real coverage data, and the coverage section downstream
+    # carries the new-file coverage block, which must stay live.
+    return 0
+  fi
+  if is_no_test_files_found "$_out"; then
+    echo ""
+    echo "⏭️  SKIPPED - no test files matched, so Gate 5 ran zero tests"
+    echo "    Detected: 'No test files found, exiting with code N' with 0 failed tests."
+    echo "    This is not a pass: nothing executed (#498)."
+    echo "    Test presence is enforced by Gate 5a and by CI, not by this exit."
+    TESTS_SKIPPED=true
+    TESTS_EXIT_CODE=0
+    return 0
+  fi
+  echo ""
+  echo "❌ BLOCKED - Tests FAILED${_ctx:+ in ${_ctx}}"
+  return 1
+}