@boyingliu01/xp-gate 0.30.2 → 0.30.4

package/adapters/iac.sh

@@ -64,10 +64,29 @@ run_static_analysis() {
   if command -v checkov >/dev/null 2>&1; then
     echo "Running checkov IaC security scan..."
 
-    # checkov 3.x always exits 0 even on failures. We capture output to a
-    # temp file and parse it for "FAILED for resource" lines instead.
+    # checkov 3.x exits 0 on "found failures" (we parse the output for those),
+    # so the status cannot be the only signal. It is still NOT discardable:
+    # exit 2 means checkov itself crashed -- e.g. AttributeError from a broken
+    # detect_secrets dependency -- and a crashed scanner has not judged
+    # anything. Counting a traceback as findings invents security issues; a
+    # traceback that happens to lack the marker reports a clean pass. Both are
+    # wrong, so a crash is tracked separately and answered as "unusable" (#552).
     local checkov_log=$(mktemp)
     local checkov_args="--compact"
+    local CHECKOV_CRASHED=0
+    local checkov_scan_count=0
+
+    # Record a checkov run's exit status and flag a crash. Codes 0 and 1 are
+    # normal (1 = findings); anything else, or any traceback in the log, is the
+    # tool failing rather than reporting.
+    record_checkov_run() {
+      local status=$1 file=$2
+      checkov_scan_count=$((checkov_scan_count + 1))
+      if [ "$status" -ne 0 ] && [ "$status" -ne 1 ]; then
+        CHECKOV_CRASHED=1
+        echo "     ⚠️  checkov exited $status on $file — the scanner failed, this is not a finding"
+      fi
+    }
 
     # Run checkov on all detected IaC files
     local tf_files=$(echo "$iac_files" | grep "TERRAFORM:" | sed 's/TERRAFORM://')
@@ -79,6 +98,7 @@ run_static_analysis() {
       for file in $tf_files; do
         if [ -f "$file" ]; then
           checkov --file "$file" $checkov_args >> "$checkov_log" 2>&1
+          record_checkov_run $? "$file"
         fi
       done
     fi
@@ -99,6 +119,7 @@ run_static_analysis() {
         for file in $k8s_only; do
           if [ -f "$file" ]; then
             checkov --file "$file" $checkov_args --framework kubernetes >> "$checkov_log" 2>&1
+          record_checkov_run $? "$file"
           fi
         done
       fi
@@ -108,6 +129,7 @@ run_static_analysis() {
         for file in $gh_files; do
           if [ -f "$file" ]; then
             checkov --file "$file" $checkov_args --framework github_actions >> "$checkov_log" 2>&1
+            record_checkov_run $? "$file"
           fi
         done
       fi
@@ -118,20 +140,39 @@ run_static_analysis() {
       for file in $docker_files; do
         if [ -f "$file" ]; then
           checkov --file "$file" $checkov_args >> "$checkov_log" 2>&1
+          record_checkov_run $? "$file"
         fi
       done
     fi
 
     # Print captured output then check for failures
     cat "$checkov_log"
+
+    # A crash is answered before any parsing. The traceback is not evidence of
+    # anything: its text decides the verdict if we let grep see it.
+    if [ "$CHECKOV_CRASHED" -eq 1 ]; then
+      rm -f "$checkov_log"
+      echo ""
+      echo "❌ BLOCKED - checkov could not run (the scanner crashed, so nothing was scanned)."
+      echo "   This is NOT a security finding. Fix the environment, usually:"
+      echo "     pip install -U checkov detect-secrets"
+      echo "   (A common cause is a detect_secrets version whose FileType enum lacks JSON.)"
+      echo "   To accept the risk for this commit: XP_GATE_IAC_SOFT=1"
+      if [ "${XP_GATE_IAC_SOFT:-}" = "1" ]; then
+        echo "⚠️  XP_GATE_IAC_SOFT=1: unusable scanner downgraded to WARN"
+        return 3
+      fi
+      return 2
+    fi
+
     local failed_count=$(grep -c "FAILED for resource" "$checkov_log" 2>/dev/null || true)
     rm -f "$checkov_log"
 
     if [ "$failed_count" -gt 0 ]; then
-      echo "❌ $failed_count security issue(s) found by checkov. Blocking commit."
+      echo "❌ $failed_count security issue(s) found by checkov across $checkov_scan_count file(s). Blocking commit."
       exit_code=1
     fi
-    echo "checkov scan completed."
+    echo "checkov scan completed ($checkov_scan_count file(s) scanned)."
     return $exit_code
   fi
   

package/adapters/java.sh

@@ -106,10 +106,23 @@ java_staged_files() {
 #     counts from the object count -> unusable -> BLOCK;
 #   - a truncated response (no closing bracket) is unusable -> BLOCK.
 # Prints the violation (object) count on success; returns 1 if unusable.
+#
+# On rejection, a one-line reason goes to STDERR naming the invariant that
+# failed plus the measured counts (#545). Before this, every rejection looked
+# identical to the operator as "not a usable violations JSON", which is why
+# #545 was filed against a code path that was never involved. The number the
+# callers capture comes from stdout, so diagnostics on stderr change nothing
+# for `count=$(wc_java_json_violation_count ...)`.
+wc_java_diag() {
+  echo "     wc-java JSON rejected: $*" >&2
+}
 # ---------------------------------------------------------------------------
 wc_java_json_violation_count() {
   local json_file="$1"
-  [ -s "$json_file" ] || return 1
+  if [ ! -s "$json_file" ]; then
+    wc_java_diag "empty or missing response file ($json_file)"
+    return 1
+  fi
 
   # Two shapes are accepted, each closed by its own bracket:
   #   - bare array `[ ... ]` — the originally pinned contract ([] = clean);
@@ -122,9 +135,18 @@ wc_java_json_violation_count() {
   head1=$(head -c 1 "$json_file")
   tail=$(tr -d '[:space:]' < "$json_file" | tail -c 1)
   case "$head1" in
-    "[") shape=array;  [ "$tail" = "]" ] || return 1 ;;
-    "{") shape=object; [ "$tail" = "}" ] || return 1 ;;
-    *) return 1 ;;
+    "[") shape=array
+         if [ "$tail" != "]" ]; then
+           wc_java_diag "array response is unterminated (first char '[', tail '$tail' not ']') — truncated output?"
+           return 1
+         fi ;;
+    "{") shape=object
+         if [ "$tail" != "}" ]; then
+           wc_java_diag "object response is unterminated (first char '{', tail '$tail' not '}') — truncated output?"
+           return 1
+         fi ;;
+    *) wc_java_diag "response does not start with a JSON bracket (entry char '$head1') — a banner/log line on stdout would cause this"
+       return 1 ;;
   esac
 
   local structural obj_count file_count rule_count sev_count
@@ -155,15 +177,36 @@ wc_java_json_violation_count() {
     file_count=$(grep -o '"file"' <<< "$structural" | wc -l | tr -d '[:space:]')
     rule_count=$(grep -o '"rule"' <<< "$structural" | wc -l | tr -d '[:space:]')
     sev_count=$(grep -o '"severity"' <<< "$structural" | wc -l | tr -d '[:space:]')
-    [ "$file_count" -eq "$rule_count" ] || return 1
-    [ "$file_count" -eq "$sev_count" ] || return 1
+    if [ "$file_count" -ne "$rule_count" ] || [ "$file_count" -ne "$sev_count" ]; then
+      wc_java_diag "issue keys are out of sync (file=$file_count rule=$rule_count severity=$sev_count) — an issue record is missing a required key"
+      return 1
+    fi
     # Everything from the "issues" member onward (the tool emits it last; if
     # a future format moves it, keys before it fall outside record parsing ->
     # sum mismatch -> BLOCK, fail closed). Flatten to one line first: real
     # output is pretty-printed across lines.
     flattened=$(tr '\n' ' ' <<< "$structural")
     tail_from_issues=$(sed -n 's/.*"issues"[[:space:]]*:[[:space:]]*\[/\n/p' <<< "$flattened")
-    [ -n "$tail_from_issues" ] || return 1
+    if [ -z "$tail_from_issues" ]; then
+      # `"issues": null` is a legitimate zero-violation report, not a broken one
+      # (#545). The Go producer's nil slice marshals to null, and it does so
+      # whenever the scan hid at least one info-level finding -- so a file whose
+      # only problems are info-level gets null while a fully clean file gets [].
+      # Whichever branch produced it, null means "no visible violations".
+      if sed -n 's/.*"issues"[[:space:]]*:[[:space:]]*null.*/found/p' <<< "$flattened" | grep -q found; then
+        # null is only trustworthy when the summary agrees there is nothing to
+        # report. A nonzero total_issues with null is the lying-tool shape.
+        null_total=$(sed -n 's/.*"total_issues"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' <<< "$flattened")
+        if [ -n "$null_total" ] && [ "$null_total" -gt 0 ]; then
+          wc_java_diag "issues is null but total_issues=$null_total — the tool claims violations it did not report"
+          return 1
+        fi
+        echo 0
+        return 0
+      fi
+      wc_java_diag 'no "issues" array found after the summary object — the response is not the {summary, issues} contract'
+      return 1
+    fi
     records=$(awk '
       { rest = $0
         depth = 0; rec = ""
@@ -182,15 +225,17 @@ wc_java_json_violation_count() {
       cf=$(grep -o '"file"' <<< "$_rec" | wc -l | tr -d '[:space:]')
       cr=$(grep -o '"rule"' <<< "$_rec" | wc -l | tr -d '[:space:]')
       cs=$(grep -o '"severity"' <<< "$_rec" | wc -l | tr -d '[:space:]')
-      [ "$cf" -eq 1 ] || return 1
-      [ "$cr" -eq 1 ] || return 1
-      [ "$cs" -eq 1 ] || return 1
+      if [ "$cf" -ne 1 ] || [ "$cr" -ne 1 ] || [ "$cs" -ne 1 ]; then
+        wc_java_diag "issue record ${rec_count} has the wrong key multiplicity (file=$cf rule=$cr severity=$cs, each must be 1)"
+        return 1
+      fi
       rf=$((rf + cf)); rr=$((rr + cr)); rs=$((rs + cs))
       rec_count=$((rec_count + 1))
     done <<< "$records"
-    [ "$rf" -eq "$file_count" ] || return 1
-    [ "$rr" -eq "$rule_count" ] || return 1
-    [ "$rs" -eq "$sev_count" ] || return 1
+    if [ "$rf" -ne "$file_count" ] || [ "$rr" -ne "$rule_count" ] || [ "$rs" -ne "$sev_count" ]; then
+      wc_java_diag "per-record key totals do not match the document (records rf=$rf rr=$rr rs=$rs vs document file=$file_count rule=$rule_count severity=$sev_count) — a required key appears outside an issue record"
+      return 1
+    fi
     echo "$rec_count"
     return 0
   fi
@@ -199,9 +244,10 @@ wc_java_json_violation_count() {
   file_count=$(grep -o '"file"' <<< "$structural" | wc -l | tr -d '[:space:]')
   rule_count=$(grep -o '"rule"' <<< "$structural" | wc -l | tr -d '[:space:]')
   sev_count=$(grep -o '"severity"' <<< "$structural" | wc -l | tr -d '[:space:]')
-  [ "$obj_count" -eq "$file_count" ] || return 1
-  [ "$obj_count" -eq "$rule_count" ] || return 1
-  [ "$obj_count" -eq "$sev_count" ] || return 1
+  if [ "$obj_count" -ne "$file_count" ] || [ "$obj_count" -ne "$rule_count" ] || [ "$obj_count" -ne "$sev_count" ]; then
+    wc_java_diag "array elements and keys are out of sync (objects=$obj_count file=$file_count rule=$rule_count severity=$sev_count)"
+    return 1
+  fi
 
   echo "$obj_count"
 }
@@ -223,6 +269,26 @@ run_wc_java_lint() {
     return 9  # not installed -> caller falls back to the legacy chain
   fi
 
+  # #550: --staged means "only the Java files in the index", and wc-java-lint
+  # 0.4.1 honours that for checkstyle, PMD, lizard and simian -- but spotbugs
+  # scans the whole target/classes tree regardless. Measured with only
+  # docs/_tmp_probe.md staged: three tools reported "skipped: no Java files"
+  # while spotbugs reported "checked 1 .class file, found 3 issues" from a class
+  # compiled earlier. The verdict then blocks a docs commit over a warning that
+  # predates it and that its author never touched.
+  #
+  # The adapter cannot fix the tool, but it can refuse to relay a verdict the
+  # tool had no basis to produce. With no staged Java file there is nothing this
+  # gate is entitled to say, so it says nothing -- out loud, not silently.
+  local staged_java
+  staged_java=$(java_staged_files 2>/dev/null | grep -c '.' || true)
+  if [ "${staged_java:-0}" -eq 0 ]; then
+    echo "⏭️  SKIPPED - Java static analysis: no staged .java files (wc-java-lint --staged)"
+    echo "     (spotbugs scans all of target/classes regardless of --staged, so its"
+    echo "      verdict is withheld here - upstream defect, see xp-gate #550)"
+    return 0
+  fi
+
   timeout_s=$(resolve_wc_java_lint_timeout)
   out_file=$(mktemp "${TMPDIR:-/tmp}/wc-java-lint.XXXXXX")
   err_file="${out_file}.err"

package/adapters/powershell.sh

@@ -17,16 +17,46 @@
 #     SKIP for now.
 
 # Detect PowerShell executable (prefer pwsh 7+, fallback to powershell.exe 5.1)
+#
+# #547 finding 4: `command -v pwsh` alone is not enough. Under git-bash with a
+# stripped PATH, the standard Windows installs are invisible even though the
+# user can run pwsh from any terminal: pwsh 7 installs to
+# %LOCALAPPDATA%\Microsoft\WindowsApps (a PATH alias that git-bash does not
+# always inherit) and PS 5.1 lives at System32\WindowsPowerShell\v1.0. Probing
+# those absolute paths converts a silent degrade into a working gate.
+#
+# The order is unchanged: whatever is on PATH wins, absolute paths are a
+# fallback, and an empty result still means "not available" -- this widens
+# detection, it does not invent an interpreter.
 _detect_pwsh() {
   if command -v pwsh &>/dev/null 2>&1; then
     echo "pwsh"
-  elif command -v powershell.exe &>/dev/null 2>&1; then
+    return 0
+  fi
+  if command -v powershell.exe &>/dev/null 2>&1; then
     echo "powershell.exe"
-  elif command -v powershell &>/dev/null 2>&1; then
+    return 0
+  fi
+  if command -v powershell &>/dev/null 2>&1; then
     echo "powershell"
-  else
-    echo ""
+    return 0
   fi
+  # Windows absolute-path fallbacks.
+  local candidate
+  for candidate in \
+    "${LOCALAPPDATA:-$HOME/AppData/Local}/Microsoft/WindowsApps/pwsh.exe" \
+    "/c/Program Files/PowerShell/7/pwsh.exe" \
+    "/c/Program Files/PowerShell/6/pwsh.exe" \
+    "/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe" \
+    "/mnt/c/Program Files/PowerShell/7/pwsh.exe" \
+    "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe"; do
+    if [ -n "$candidate" ] && [ -x "$candidate" ]; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  echo ""
+  return 1
 }
 
 _find_powershell_files() {
@@ -87,18 +117,49 @@ run_static_analysis() {
     echo "Running PSScriptAnalyzer static analysis on PowerShell scripts..."
     # Recursively analyze all .ps1 files from repo root
     # Exit with non-zero if Error or Warning severity issues found
-    "$PWSH" "${POWERSHELL_ARGS[@]}" "
+    local PSSA_RC=0
+    local PSSA_OUT
+    PSSA_OUT=$("$PWSH" "${POWERSHELL_ARGS[@]}" "
+      if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
+        Write-Output 'PSSA_MODULE_MISSING'
+        exit 0
+      }
       \$results = Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error,Warning
       if (\$results) {
         \$results | Format-Table -AutoSize
         exit 1
       }
       exit 0
-    "
-    return $?
+    " 2>&1) || PSSA_RC=$?
+    printf '%s\n' "$PSSA_OUT"
+    case "$PSSA_RC" in
+      0)
+        if printf '%s\n' "$PSSA_OUT" | grep -q 'PSSA_MODULE_MISSING'; then
+          # #547 finding 2: the engine exists but its module does not. That is
+          # NOT a pass -- nothing was analysed. The XP_G1_REASON protocol (the
+          # one the java branch uses) turns this into a WARN that stays in the
+          # scoring denominator instead of vanishing.
+          echo "XP_G1_REASON: PSScriptAnalyzer module not installed (Install-Module PSScriptAnalyzer)"
+          return 3
+        fi
+        return 0
+        ;;
+      1)
+        return 1   # real findings -> BLOCK upstream
+        ;;
+      *)
+        echo "XP_G1_REASON: PSScriptAnalyzer run failed (exit $PSSA_RC)"
+        return 2   # unusable -> fail closed upstream
+        ;;
+    esac
   else
-    echo "PowerShell not available, skipping PowerShell static analysis"
-    return 0
+    # #547 finding 4: previously `return 0`, i.e. "no PowerShell available"
+    # was indistinguishable from "PowerShell is clean" -- a silent false pass on
+    # a PowerShell commit. Return the not-available verdict so the caller can
+    # WARN and record a reason.
+    echo "PowerShell executable not found (probe: pwsh, powershell.exe, and the standard Windows install paths)"
+    echo "XP_G1_REASON: pwsh not available (install PowerShell 7: https://aka.ms/powershell)"
+    return 3
   fi
 }
 

package/gate-10.sh

@@ -12,7 +12,20 @@ GATE_10_START=$(gate_start_ms)
 GATE_10_STATUS=""
 # #536: audit trail for "did this commit actually get scanned?". The report
 # surfaces reason + scanned_files so a non-scan never reads as a clean PASS.
+#
+# GATE_10_REASON and GATE_10_SCANNED_FILES are consumed by the sourcing parent
+# (pre-commit builds its report JSON from them after `source gate-10.sh`), not
+# inside this file. The linter checks one file at a time and cannot see the
+# consumer, so each assignment is flagged SC2034 "appears unused" -- which
+# blocks Gate 1 for any repo that vendors this adapter, because that repo's own
+# lint pass runs over the vendored copy (#548). Each assignment carries a
+# scoped directive with that reason stated at the site.
+#
+# Consumed by the sourcing parent (pre-commit report JSON), not here.
+# shellcheck disable=SC2034
 GATE_10_REASON=""
+# Consumed by the sourcing parent (pre-commit report JSON), not here.
+# shellcheck disable=SC2034
 GATE_10_SCANNED_FILES=0
 
 # Semgrep availability check
@@ -29,14 +42,21 @@ if [ -z "$SEMGREP_CMD" ]; then
   echo "     Pre-cache rules: semgrep --config=p/security-audit"
   echo "     Gate 10: SAST Security (WARN, semgrep not installed)"
   GATE_10_STATUS="WARN"
+  # Consumed by the sourcing parent (pre-commit report JSON), not here.
+  # shellcheck disable=SC2034
   GATE_10_REASON="tool_not_installed"
 else
-  # Get staged files filtered to Semgrep-supported languages
-  SEMGREP_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
+  # Get staged files filtered to Semgrep-supported languages.
+  # #547 finding 3: ps1|psm1 were missing, so a PowerShell-only commit never
+  # reached semgrep even when Gate 10 ran -- the SAST gate was simply absent
+  # for that language.
+  SEMGREP_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift|ps1|psm1)$' || true)
 
   if [ -z "$SEMGREP_FILES" ]; then
     echo "     ⏭️  SKIPPED - SAST (no supported language files changed)"
     GATE_10_STATUS="SKIP"
+    # Consumed by the sourcing parent (pre-commit report JSON), not here.
+    # shellcheck disable=SC2034
     GATE_10_REASON="no_supported_files"
   else
     # One path per line into an array. Quoting the newline-joined list would hand
@@ -71,11 +91,27 @@ else
       [ -n "$_semgrep_file" ] || continue
       SEMGREP_FILE_COUNT=$((SEMGREP_FILE_COUNT + 1))
       SEMGREP_ARGS+=("--include=${_semgrep_file##*/}")
-      _semgrep_dir="./${_semgrep_file%/*}"
-      # A repo-root file has no directory component ("./x.ts" strips to "./").
-      [ "$_semgrep_dir" = "./" ] && _semgrep_dir="."
+      # A repo-root file has no slash at all, so "%/*" returns it unchanged and
+      # the old comment's assumption (`"./x.ts" strips to "./"`) never held:
+      # the target became the FILE path dressed as a directory ("./x.ts").
+      # Strip only when a slash is present; otherwise the target is the repo
+      # root, spelled ".". Scanning "." widens the scan to the whole tree, which
+      # is the safe side (see the note above) and is what a root-level staged
+      # file requires in order to be analysed at all.
+      case "$_semgrep_file" in
+        */*) _semgrep_dir="./${_semgrep_file%/*}" ;;
+        *)   _semgrep_dir="." ;;
+      esac
+      # #558: dedup must match WHOLE lines. The previous `case "$SEEN" in
+      # *"$_semgrep_dir"*)` was an unanchored substring test: once
+      # ./fastdl/tests was recorded, the parent ./fastdl matched it and was
+      # never added as a target, so a staged fastdl/a.py contributed an
+      # --include= with no directory to scan it in. Nothing errored and nothing
+      # was reported -- the file was simply not analysed, which for a security
+      # gate is the worst outcome: a silent net loss that looks like a pass.
+      # Sibling prefixes (src/api vs src/app) collapsed the same way.
       case "$SEMGREP_DIRS_SEEN" in
-        *"$_semgrep_dir"*) : ;;
+        *$'\n'"$_semgrep_dir"$'\n'*) : ;;
         *) SEMGREP_ARGS+=("$_semgrep_dir"); SEMGREP_DIRS_SEEN="$SEMGREP_DIRS_SEEN$_semgrep_dir"$'\n' ;;
       esac
     done <<EOF
@@ -91,6 +127,8 @@ EOF
       echo "     Install node (https://nodejs.org); without it SAST findings cannot be classified"
       echo "     ⏭️  SKIPPED - SAST (node not installed)"
       GATE_10_STATUS="SKIP"
+      # Consumed by the sourcing parent (pre-commit report JSON), not here.
+      # shellcheck disable=SC2034
       GATE_10_REASON="tool_not_installed"
     else
 
@@ -109,9 +147,41 @@ EOF
     # code is demoted to "did the tool itself run". --error stays OFF: it would
     # add nothing the JSON does not already provide, and keeping it off leaves
     # failure exit codes unambiguous for the #475 diagnostics path.
-    SEMGREP_STDOUT_FILE=$(mktemp)
-    SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
-    SEMGREP_EXIT=$?
+    # #559: bound the run. Without a timeout, a wedged semgrep blocks the
+    # invocation for as long as its process lives; the fail-closed verdict logic
+    # below is correct but unreachable, so the hook hangs instead of judging.
+    # A gate that can wedge an interactive `git commit` gets bypassed with
+    # --no-verify, which is worse than any verdict it could have produced.
+    # `-k` after the primary signal: pysemgrep spinning in a syscall ignores
+    # SIGTERM, and the shipped 0.29 code used the same `-k 10` shape.
+    SEMGREP_TIMEOUT_S="${XP_GATE_SEMGREP_TIMEOUT:-180}"
+    SEMGREP_TIMED_OUT=false
+    if command -v timeout >/dev/null 2>&1; then
+      SEMGREP_STDOUT_FILE=$(mktemp)
+      SEMGREP_OUTPUT=$(timeout -k 10 "$SEMGREP_TIMEOUT_S" \
+        "$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check \
+        "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
+      SEMGREP_EXIT=$?
+      # 124 = timeout's own "I gave up" code. 137 = 128+SIGKILL, which is what
+      # `timeout -k` returns when the child ignored SIGTERM and had to be
+      # killed -- measured with a semgrep stand-in that traps TERM. Both mean
+      # "bounded, no verdict", so both must be reported as a timeout; checking
+      # only 124 told the user their semgrep was unparseable when in fact the
+      # scan had been cut off.
+      case "$SEMGREP_EXIT" in
+        124|137) SEMGREP_TIMED_OUT=true ;;
+      esac
+    else
+      # No `timeout` on this platform (stock macOS). Say so: an unbounded run
+      # nobody mentioned is exactly how #559 stayed invisible for a whole
+      # release. The scan still runs -- refusing to scan would be a worse
+      # trade -- but the unbounded window is now stated.
+      echo "     ⚠️  'timeout' command not available — semgrep runs UNBOUNDED (install coreutils or set up gtimeout)"
+      SEMGREP_STDOUT_FILE=$(mktemp)
+      SEMGREP_OUTPUT=$("$SEMGREP_CMD" scan --config=p/security-audit --json --disable-version-check \
+        "${SEMGREP_ARGS[@]}" 2>&1 >"$SEMGREP_STDOUT_FILE")
+      SEMGREP_EXIT=$?
+    fi
 
     # One node pass over the JSON: first line = verdict counts, remaining lines =
     # finding details. The severity vocabulary is the UNION of the two scales
@@ -153,7 +223,18 @@ console.log("");});
     if [ "$V_PARSE" != "OK" ] || [ -z "$V_RESULTS" ] || [ -z "$V_ERRORS" ] || [ -z "$V_BLOCKING" ] || [ -z "$V_WARNINGS" ]; then
       # Unparseable output: nothing the exit code claims can be trusted (#518).
       # Fail closed — SKIP with diagnostics, never a PASS.
-      echo "     ⚠️  semgrep output unparseable or verdict fields missing (exit code ${SEMGREP_EXIT}) — cannot determine verdict"
+      #
+      # #559: name a timeout as a timeout. The generic "unparseable" message
+      # would be true but useless here -- it points at the JSON parser when the
+      # real problem is that the scan was cut off. Same verdict (SKIP), but a
+      # diagnosis the reader can act on.
+      if [ "$SEMGREP_TIMED_OUT" = true ]; then
+        echo "     ⏱️  semgrep exceeded ${SEMGREP_TIMEOUT_S}s and was killed — no verdict is possible"
+        echo "     This is NOT a finding and NOT a clean scan. Raise XP_GATE_SEMGREP_TIMEOUT"
+        echo "     if the repo legitimately takes longer; investigate if semgrep itself is wedged."
+      else
+        echo "     ⚠️  semgrep output unparseable or verdict fields missing (exit code ${SEMGREP_EXIT}) — cannot determine verdict"
+      fi
       if [ -n "$SEMGREP_OUTPUT" ]; then
         echo "     ── what semgrep reported on stderr ──"
         printf '%s\n' "$SEMGREP_OUTPUT" | tail -10 | sed 's/^/     /'
@@ -162,9 +243,19 @@ console.log("");});
         echo "     ── what semgrep wrote to stdout (tail) ──"
         printf '%s\n' "$SEMGREP_STDOUT_TAIL" | sed 's/^/     /'
       fi
-      echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
-      GATE_10_STATUS="SKIP"
-      GATE_10_REASON="output_unparseable"
+      if [ "$SEMGREP_TIMED_OUT" = true ]; then
+        echo "     ⏭️  SKIPPED - SAST (semgrep timed out after ${SEMGREP_TIMEOUT_S}s)"
+        GATE_10_STATUS="SKIP"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
+        GATE_10_REASON="semgrep_timeout"
+      else
+        echo "     ⏭️  SKIPPED - SAST (semgrep output unparseable)"
+        GATE_10_STATUS="SKIP"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
+        GATE_10_REASON="output_unparseable"
+      fi
     elif [ "$V_RESULTS" -eq 0 ] && { [ "$V_ERRORS" -gt 0 ] || [ "$SEMGREP_EXIT" -ne 0 ]; }; then
       # Nothing was scanned to a verdict: semgrep either failed outright
       # (nonzero exit) or completed but reported scan errors for every input
@@ -178,6 +269,8 @@ console.log("");});
       fi
       echo "     ⏭️  SKIPPED - SAST (semgrep runtime error)"
       GATE_10_STATUS="SKIP"
+      # Consumed by the sourcing parent (pre-commit report JSON), not here.
+      # shellcheck disable=SC2034
       GATE_10_REASON="semgrep_runtime_error"
     elif [ "$V_BLOCKING" -gt 0 ]; then
       echo ""
@@ -192,9 +285,13 @@ console.log("");});
       echo "$FINDING_DETAILS"
       echo "  Run 'semgrep scan --config=p/security-audit' to review all findings."
       GATE_10_STATUS="FAIL"
+      # Consumed by the sourcing parent (pre-commit report JSON), not here.
+      # shellcheck disable=SC2034
       GATE_10_SCANNED_FILES=$SEMGREP_FILE_COUNT
       exit 1
     else
+      # Consumed by the sourcing parent (pre-commit report JSON), not here.
+      # shellcheck disable=SC2034
       GATE_10_SCANNED_FILES=$SEMGREP_FILE_COUNT
       echo ""
       echo "     ✅ PASSED - No blocking vulnerabilities (files scanned: $SEMGREP_FILE_COUNT)"

package/gate-3.sh

@@ -8,11 +8,15 @@
  2>&1 echo "→ Gate 3: Cyclomatic complexity..."
 GATE_3_START=$(gate_start_ms)
 # #537: every non-run records WHY so the report can say why a gate is SKIP.
+# Consumed by the sourcing parent (pre-commit report JSON), not here.
+# shellcheck disable=SC2034
 GATE_3_REASON=""
 
 if [ "$PROJECT_LANG" = "documentation-only" ]; then
   echo "⏭️  SKIPPED - Complexity (documentation project)."
   GATE_3_STATUS="SKIP"
+  # Consumed by the sourcing parent (pre-commit report JSON), not here.
+  # shellcheck disable=SC2034
   GATE_3_REASON="documentation_project"
 
 elif [ "$PROJECT_LANG" = "powershell" ]; then
@@ -21,6 +25,8 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
   GATE_3_STATUS="SKIP"
   # #537: a PowerShell-primary repo was invisible to this dimension while the
   # score implied full coverage — say exactly why nothing ran.
+  # Consumed by the sourcing parent (pre-commit report JSON), not here.
+  # shellcheck disable=SC2034
   GATE_3_REASON="no_powershell_tool"
   
 else
@@ -159,7 +165,10 @@ else
         # empty stdin — the verdict comes back empty and Gate 3 passes on zero
         # rows (measured while wiring #544: same input passed or blocked
         # depending only on where the prefix sat).
+        # Consumed by evaluate_ccn_ratchet in the sourced lib, not here.
+        # shellcheck disable=SC2034
         CCN_WARN_THRESHOLD="$CCN_THRESHOLD"
+        # shellcheck disable=SC2034
         CCN_BLOCK_THRESHOLD=$((CCN_THRESHOLD * 2))
         RATCHET_VERDICT=$(printf '%s\n' "$CC_CSV" | evaluate_ccn_ratchet ".ccn-baseline.json")
         CC_VIOLATIONS=$(printf '%s\n' "$RATCHET_VERDICT" | grep -c '^BLOCK ' || true)
@@ -205,6 +214,8 @@ else
                                                  END { exit(found ? 0 : 1) }'; then
         echo "⚠️  WARN - lizard produced no parsable results; complexity not verified"
         GATE_3_STATUS="WARN"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
         GATE_3_REASON="lizard_output_unparsable"
       elif [ "$CC_WARNINGS" -gt 0 ]; then
         echo "$CC_OUTPUT"
@@ -212,6 +223,8 @@ else
         echo "❌ BLOCKED - $CC_WARNINGS functions with CCN > $CCN_THRESHOLD found."
         echo "Refactor high-complexity functions to keep below $CCN_THRESHOLD complexity."
         GATE_3_STATUS="BLOCK"
+        # Consumed by the sourcing parent (pre-commit report JSON), not here.
+        # shellcheck disable=SC2034
         GATE_3_REASON="ccn_over_threshold"
         exit 1
       else
@@ -222,6 +235,8 @@ else
     else
       echo "⏭️  SKIPPED - Complexity (no source files to check)."
       GATE_3_STATUS="SKIP"
+      # Consumed by the sourcing parent (pre-commit report JSON), not here.
+      # shellcheck disable=SC2034
       GATE_3_REASON="no_source_files_changed"
     fi
   else
@@ -229,6 +244,8 @@ else
     echo "   Install with: pip install --user lizard"
     echo "   Gate 3: Complexity check (WARN, tool not available)"
     GATE_3_STATUS="WARN"
+    # Consumed by the sourcing parent (pre-commit report JSON), not here.
+    # shellcheck disable=SC2034
     GATE_3_REASON="tool_not_installed"
   fi
 fi