@boyingliu01/xp-gate 0.31.1 → 0.31.2

package/adapter-common.sh

@@ -155,19 +155,57 @@ require_tool() {
   local tool_name="$1"
   local gate_name="${2:-Gate}"
   local install_hint="${3:-}"
-  
+
+  # #593: on Windows the hook runs under git-bash, which does not see the
+  # toolchains installed on the Windows side (%APPDATA%\npm, the node dir,
+  # pip --user Scripts, ~/bin). Bootstrapping before probing turns "not on this
+  # shell's PATH" back into "found", instead of reporting an installed tool as
+  # missing. lib/toolchain-path.sh is sourced by pre-commit before this runs; the
+  # guard keeps require_tool usable from adapters that load on their own.
+  if command -v bootstrap_toolchain_path >/dev/null 2>&1; then
+    bootstrap_toolchain_path
+  fi
+
+  # #580: on WSL (appendWindowsPath=false) and in git-bash, `command -v node`
+  # returns 1 while node.exe sits in the same directory and runs. One root cause
+  # gave Gate 1 a silent SKIP, Gate 1 a false "Biome check failed" and Gate 8 a
+  # false "gitleaks not installed" — an environment fault reported as a code
+  # verdict in all three. tool_is_available also counts the .exe suffix and the
+  # XP_GATE_<TOOL>_BIN override.
+  if command -v tool_is_available >/dev/null 2>&1 && tool_is_available "$tool_name"; then
+    return 0
+  fi
+
   if command -v "$tool_name" >/dev/null 2>&1; then
     return 0
   fi
-  
+
+  if command -v "${tool_name}.exe" >/dev/null 2>&1; then
+    return 0
+  fi
+
   if command -v npx >/dev/null 2>&1 && npx --no-install "$tool_name" --version >/dev/null 2>&1; then
     return 0
   fi
-  
+
+  # #593: monorepos keep the tool in a subproject's node_modules/.bin, where
+  # neither PATH nor `npx` from the repo root can see it.
+  if command -v resolve_tool_path >/dev/null 2>&1 && resolve_tool_path "$tool_name" >/dev/null 2>&1; then
+    if command -v ensure_tool_dir_on_path >/dev/null 2>&1; then
+      ensure_tool_dir_on_path "$tool_name" || true
+    fi
+    return 0
+  fi
+
   echo "❌ BLOCKED - Required tool '$tool_name' not available for $gate_name"
   if [ -n "$install_hint" ]; then
     echo "   Install: $install_hint"
   fi
+  # #593 point 3: "not installed" and "installed but not found" need different
+  # fixes, so name every location that was searched.
+  if command -v describe_tool_search >/dev/null 2>&1; then
+    describe_tool_search "$tool_name"
+  fi
   echo "   Per QUALITY-GATES-CODE-OF-CONDUCT.md: tool unavailable = BLOCK, not SKIP"
   return 1
 }

package/adapters/gate-3.sh

@@ -109,7 +109,14 @@ else
         GATE_3_STATUS="PASS"
       fi
     else
-      echo "⏭️  SKIPPED - Complexity (no source files to check)."
+      # #589: "no source files to check" described an empty PROJECT when the real
+      # cause is an empty CHANGED_FILES. The old wording read like a pass.
+      if [ -n "${GATE_SCOPE:-}" ] && [ "$GATE_SCOPE" = "all" ]; then
+        echo "⏭️  SKIPPED - Complexity: no tracked source files in this repository (scope: --all, whole tree)."
+      else
+        echo "⏭️  SKIPPED - Complexity: no changed source files in this run (scope: diff)."
+        echo "   Run 'xp-gate check . --all' to scan the whole tree."
+      fi
       GATE_3_STATUS="SKIP"
       GATE_3_REASON="no_source_files_changed"
     fi

package/adapters/gate-8.sh

@@ -33,10 +33,23 @@ fi
 
 GITLEAKS_CONFIG=""
 if [ -f ".gitleaks.toml" ]; then
-  # gitleaks is a native binary and may not understand MSYS paths, so pass an
+  # gitleaks is a native binary and may not understand MSYS/WSL 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
+  #
+  # #582 found this the hard way: `cygpath` exists only in Git-for-Windows/MSYS, and on
+  # WSL its absence meant the fallback handed `/mnt/d/projects/<repo>/.gitleaks.toml`
+  # to the native gitleaks.exe. It could not open the file, exited 1, and Gate 8
+  # reported "Secrets detected". The conversion now lives in a shared library so the
+  # next gate handing a path to a native binary does not re-derive it (#581).
+  #
+  # This script may also run standalone (archived/copied hook) without the library, so
+  # the converter is used when present and the inline branch kept as the fallback.
+  if declare -F to_native_path >/dev/null 2>&1; then
+    GITLEAKS_CONFIG="--config=$(to_native_path "$(pwd)/.gitleaks.toml")"
+  elif command -v cygpath >/dev/null 2>&1; then
     GITLEAKS_CONFIG="--config=$(cygpath -w "$(pwd)/.gitleaks.toml")"
+  elif command -v wslpath >/dev/null 2>&1; then
+    GITLEAKS_CONFIG="--config=$(wslpath -w "$(pwd)/.gitleaks.toml")"
   else
     GITLEAKS_CONFIG="--config=$(pwd)/.gitleaks.toml"
   fi
@@ -75,10 +88,41 @@ if [ "$GITLEAKS_EXIT" -eq 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)"
+    # #592: exit 0 with no usable report has TWO very different causes, and the
+    # operator can only act if we tell them which one happened:
+    #
+    #   (a) the scan never ran — config unreadable, FTL, bad --report-path.
+    #       Nothing was checked, so this must fail closed with the tool's own
+    #       words, not be filed as "no evidence about the code".
+    #   (b) the scan ran and found nothing, but the tool wrote no file (reported
+    #       for gitleaks 8.30.1 on WSL; measured NOT to happen in git-bash with
+    #       the same version, so the code must handle both). Only stdout is left,
+    #       and stdout is weaker evidence than an artifact, so it still may not
+    #       produce a PASS.
+    #
+    # The order matters and is the point: artifact first, tool failure second,
+    # tool output last (#449 established the principle; #592 re-opens it).
+    if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -qiE '(^|[[:space:]])(FTL|fatal error)[[:space:]:]|unable to load'; then
+      echo "     ❌ BLOCKED - ENVIRONMENT: gitleaks exited 0 but reported a failure, so"
+      echo "        NO secret scan took place. This is a tooling problem, not a verdict"
+      echo "        about the staged code."
+      printf '%s\n' "$GITLEAKS_OUTPUT" | grep -iE 'FTL|fatal|unable' | head -3 | sed 's/^/        /'
+      echo "   Fix the gitleaks config/invocation above and commit again."
+      exit 1
+    fi
+
+    if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -q 'no leaks found'; then
+      # The scan demonstrably ran and found nothing, but there is no artifact to
+      # prove it beyond this line. Reporting PASS from log wording is exactly what
+      # #449 forbade, so this stays SKIP — and says WHY, which the old message did
+      # not: without that, SKIP is indistinguishable from "tool missing".
+      echo "     ⚠️  gitleaks scanned and reported no leaks, but wrote no report file"
+      echo "        (${GITLEAKS_REPORT} missing). No artifact means no PASS (#449)."
+      echo "     ⏭️  SKIPPED - secret scanning produced no artifact (scan reported clean)."
+    else
+      echo "     ⚠️  gitleaks exited 0 but produced no readable report and no scan summary"
+      echo "     ⏭️  SKIPPED - secret scanning produced no evidence (not a pass)"
+    fi
     GATE_8_STATUS="SKIP"
   else
     echo "     ❌ BLOCKED - gitleaks reported $GITLEAKS_FINDINGS finding(s)"
@@ -88,6 +132,23 @@ if [ "$GITLEAKS_EXIT" -eq 0 ]; then
     exit 1
   fi
 elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
+  # #582: gitleaks exits 1 for BOTH "leaks found" and "I could not start" (unreadable
+  # config, bad path, IO error). Treating every exit 1 as a finding produced the
+  # loudest possible wrong answer: "Secrets detected in staged files", plus
+  # instructions to rotate a key, on a repository where nothing had been scanned --
+  # because WSL handed a POSIX path to the native binary (#582's own case).
+  #
+  # #592 established this distinction for exit 0 + FTL. The same test applies here,
+  # and the order matters as much: a scanner that could not start must never be
+  # reported as having found something, or the gate teaches people to disable it.
+  if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -qiE '(^|[[:space:]])(FTL|fatal error)[[:space:]:]|unable to load|cannot find the path'; then
+    echo "     ❌ BLOCKED - ENVIRONMENT: gitleaks exited 1 because it could not start, so"
+    echo "        NO secret scan took place. This is a tooling problem, not a verdict"
+    echo "        about the staged code."
+    printf '%s\n' "$GITLEAKS_OUTPUT" | grep -iE 'FTL|fatal|unable|cannot find' | head -3 | sed 's/^/        /'
+    echo "   Fix the gitleaks config/invocation above and commit again."
+    exit 1
+  fi
   # Secrets found — output details
   echo "$GITLEAKS_OUTPUT"
   echo ""

package/adapters/go.sh

@@ -4,7 +4,24 @@
 # Tools: go vet, golangci-lint, arch-go (architecture), go test
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/../adapter-common.sh" 2>/dev/null || true
+# #597: the library can be beside the adapters or one level up, depending on how
+# the package was installed:
+#   global install   ~/.config/xp-gate/adapters/adapter-common.sh   (inside)
+#   npm package      src/npm-package/adapters/../adapter-common.sh  (above)
+# The old single "$SCRIPT_DIR/../adapter-common.sh" only ever matched the second,
+# so in the global layout the library never loaded - and "2>/dev/null || true"
+# made that indistinguishable from success, leaving every shared function
+# undefined with no warning.
+for _ac_candidate in \
+  "$SCRIPT_DIR/adapter-common.sh" \
+  "$SCRIPT_DIR/../adapter-common.sh"; do
+  if [ -f "$_ac_candidate" ]; then
+    # shellcheck source=/dev/null
+    source "$_ac_candidate"
+    break
+  fi
+done
+unset _ac_candidate
 
 run_static_analysis() {
   require_tool go "Go SDK" || return 1

package/adapters/iac.sh

@@ -5,7 +5,24 @@
 # Tools: checkov (primary), hadolint (Docker), kube-score (K8s)
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/../adapter-common.sh" 2>/dev/null || true
+# #597: the library can be beside the adapters or one level up, depending on how
+# the package was installed:
+#   global install   ~/.config/xp-gate/adapters/adapter-common.sh   (inside)
+#   npm package      src/npm-package/adapters/../adapter-common.sh  (above)
+# The old single "$SCRIPT_DIR/../adapter-common.sh" only ever matched the second,
+# so in the global layout the library never loaded - and "2>/dev/null || true"
+# made that indistinguishable from success, leaving every shared function
+# undefined with no warning.
+for _ac_candidate in \
+  "$SCRIPT_DIR/adapter-common.sh" \
+  "$SCRIPT_DIR/../adapter-common.sh"; do
+  if [ -f "$_ac_candidate" ]; then
+    # shellcheck source=/dev/null
+    source "$_ac_candidate"
+    break
+  fi
+done
+unset _ac_candidate
 
 # Detect IaC files in changed files
 detect_iac_files() {

package/adapters/powershell.sh

@@ -279,12 +279,48 @@ run_static_analysis() {
         exit 0
       " 2>&1) || PSSA_RC=$?
     else
+      # #595: the unscoped path used to be a bare `-Path . -Recurse`, which walks
+      # node_modules. In a repo with Playwright installed that analyses
+      # playwright-core/bin/*.ps1 -- vendored files that use Write-Host and WMI
+      # cmdlets by design, that `npm ci` overwrites, and that the author cannot
+      # edit. Gate 1 then blocked EVERY commit, permanently. A gate that can never
+      # pass is not strict; it is one people learn to bypass.
+      #
+      # The adapter already had the right discovery: _find_powershell_files prunes
+      # .git, node_modules, dist, coverage and the rest. The two paths disagreed
+      # only because this one never called it. Now both use it, so "what this
+      # adapter refuses to analyse" has one definition.
+      local legacy_files
+      legacy_files=$(_find_powershell_files '*.ps1')
+      if [ -z "$legacy_files" ]; then
+        # Nothing to analyse is NOT a pass: say so via the reason protocol the
+        # module-missing branch uses, so it stays visible in the gate output.
+        echo "XP_G1_REASON: no PowerShell files found outside the pruned directories"
+        return 3
+      fi
+      local legacy_array
+      legacy_array=$(_powershell_path_array $legacy_files)
       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
+        \$ErrorActionPreference = 'Stop'
+        try { Import-Module PSScriptAnalyzer -ErrorAction Stop | Out-Null } catch { exit 3 }
+        \$settings = Join-Path (Get-Location) 'PSScriptAnalyzerSettings.psd1'
+        \$results = @()
+        try {
+          foreach (\$p in $legacy_array) {
+            if (Test-Path -LiteralPath \$settings) {
+              \$results += @(Invoke-ScriptAnalyzer -Path \$p -Severity Error,Warning -Settings \$settings -ErrorAction Stop)
+            } else {
+              \$results += @(Invoke-ScriptAnalyzer -Path \$p -Severity Error,Warning -ErrorAction Stop)
+            }
+          }
+        } catch {
+          Write-Output ('PSSA_RUN_ERROR: ' + \$_.Exception.Message)
+          exit 3
+        }
         if (\$results) {
           \$results | Format-Table -AutoSize
           exit 1

package/adapters/python.sh

@@ -4,10 +4,24 @@
 # Tools: mypy, ruff/flake8, pytest, import-linter (architecture)
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# SC1091：adapter-common.sh 由调用方按查找顺序提供，路径靠变量拼接，shellcheck 无法静态跟随。
-# `source … || true` 是既有容错口径（仓库存档时该文件可能不在），不要改成硬依赖。
-# shellcheck source=/dev/null
-source "$SCRIPT_DIR/../adapter-common.sh" 2>/dev/null || true
+# #597: the library can be beside the adapters or one level up, depending on how
+# the package was installed:
+#   global install   ~/.config/xp-gate/adapters/adapter-common.sh   (inside)
+#   npm package      src/npm-package/adapters/../adapter-common.sh  (above)
+# The old single "$SCRIPT_DIR/../adapter-common.sh" only ever matched the second,
+# so in the global layout the library never loaded - and "2>/dev/null || true"
+# made that indistinguishable from success, leaving every shared function
+# undefined with no warning.
+for _ac_candidate in \
+  "$SCRIPT_DIR/adapter-common.sh" \
+  "$SCRIPT_DIR/../adapter-common.sh"; do
+  if [ -f "$_ac_candidate" ]; then
+    # shellcheck source=/dev/null
+    source "$_ac_candidate"
+    break
+  fi
+done
+unset _ac_candidate
 
 # A mypy target must exist AND actually contain .py files: a bare directory
 # check lets through TS repos' src/ (mypy exits 2 with "There are no .py[i]

package/gate-3.sh

@@ -233,7 +233,16 @@ else
       fi
       fi
     else
-      echo "⏭️  SKIPPED - Complexity (no source files to check)."
+      # #589: "no source files to check" described an empty PROJECT when the real
+      # cause is an empty CHANGED_FILES — an empty DIFF, or a `--all` run whose
+      # tree genuinely has no sources. The old wording read like a pass, which is
+      # why the reporter worked around the gate by running lizard by hand.
+      if [ -n "${GATE_SCOPE:-}" ] && [ "$GATE_SCOPE" = "all" ]; then
+        echo "⏭️  SKIPPED - Complexity: no tracked source files in this repository (scope: --all, whole tree)."
+      else
+        echo "⏭️  SKIPPED - Complexity: no changed source files in this run (scope: diff)."
+        echo "   Run 'xp-gate check . --all' to scan the whole tree."
+      fi
       GATE_3_STATUS="SKIP"
       # Consumed by the sourcing parent (pre-commit report JSON), not here.
       # shellcheck disable=SC2034

package/gate-8.sh

@@ -33,10 +33,23 @@ fi
 
 GITLEAKS_CONFIG=""
 if [ -f ".gitleaks.toml" ]; then
-  # gitleaks is a native binary and may not understand MSYS paths, so pass an
+  # gitleaks is a native binary and may not understand MSYS/WSL 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
+  #
+  # #582 found this the hard way: `cygpath` exists only in Git-for-Windows/MSYS, and on
+  # WSL its absence meant the fallback handed `/mnt/d/projects/<repo>/.gitleaks.toml`
+  # to the native gitleaks.exe. It could not open the file, exited 1, and Gate 8
+  # reported "Secrets detected". The conversion now lives in a shared library so the
+  # next gate handing a path to a native binary does not re-derive it (#581).
+  #
+  # This script may also run standalone (archived/copied hook) without the library, so
+  # the converter is used when present and the inline branch kept as the fallback.
+  if declare -F to_native_path >/dev/null 2>&1; then
+    GITLEAKS_CONFIG="--config=$(to_native_path "$(pwd)/.gitleaks.toml")"
+  elif command -v cygpath >/dev/null 2>&1; then
     GITLEAKS_CONFIG="--config=$(cygpath -w "$(pwd)/.gitleaks.toml")"
+  elif command -v wslpath >/dev/null 2>&1; then
+    GITLEAKS_CONFIG="--config=$(wslpath -w "$(pwd)/.gitleaks.toml")"
   else
     GITLEAKS_CONFIG="--config=$(pwd)/.gitleaks.toml"
   fi
@@ -75,10 +88,41 @@ if [ "$GITLEAKS_EXIT" -eq 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)"
+    # #592: exit 0 with no usable report has TWO very different causes, and the
+    # operator can only act if we tell them which one happened:
+    #
+    #   (a) the scan never ran — config unreadable, FTL, bad --report-path.
+    #       Nothing was checked, so this must fail closed with the tool's own
+    #       words, not be filed as "no evidence about the code".
+    #   (b) the scan ran and found nothing, but the tool wrote no file (reported
+    #       for gitleaks 8.30.1 on WSL; measured NOT to happen in git-bash with
+    #       the same version, so the code must handle both). Only stdout is left,
+    #       and stdout is weaker evidence than an artifact, so it still may not
+    #       produce a PASS.
+    #
+    # The order matters and is the point: artifact first, tool failure second,
+    # tool output last (#449 established the principle; #592 re-opens it).
+    if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -qiE '(^|[[:space:]])(FTL|fatal error)[[:space:]:]|unable to load'; then
+      echo "     ❌ BLOCKED - ENVIRONMENT: gitleaks exited 0 but reported a failure, so"
+      echo "        NO secret scan took place. This is a tooling problem, not a verdict"
+      echo "        about the staged code."
+      printf '%s\n' "$GITLEAKS_OUTPUT" | grep -iE 'FTL|fatal|unable' | head -3 | sed 's/^/        /'
+      echo "   Fix the gitleaks config/invocation above and commit again."
+      exit 1
+    fi
+
+    if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -q 'no leaks found'; then
+      # The scan demonstrably ran and found nothing, but there is no artifact to
+      # prove it beyond this line. Reporting PASS from log wording is exactly what
+      # #449 forbade, so this stays SKIP — and says WHY, which the old message did
+      # not: without that, SKIP is indistinguishable from "tool missing".
+      echo "     ⚠️  gitleaks scanned and reported no leaks, but wrote no report file"
+      echo "        (${GITLEAKS_REPORT} missing). No artifact means no PASS (#449)."
+      echo "     ⏭️  SKIPPED - secret scanning produced no artifact (scan reported clean)."
+    else
+      echo "     ⚠️  gitleaks exited 0 but produced no readable report and no scan summary"
+      echo "     ⏭️  SKIPPED - secret scanning produced no evidence (not a pass)"
+    fi
     GATE_8_STATUS="SKIP"
   else
     echo "     ❌ BLOCKED - gitleaks reported $GITLEAKS_FINDINGS finding(s)"
@@ -88,6 +132,23 @@ if [ "$GITLEAKS_EXIT" -eq 0 ]; then
     exit 1
   fi
 elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
+  # #582: gitleaks exits 1 for BOTH "leaks found" and "I could not start" (unreadable
+  # config, bad path, IO error). Treating every exit 1 as a finding produced the
+  # loudest possible wrong answer: "Secrets detected in staged files", plus
+  # instructions to rotate a key, on a repository where nothing had been scanned --
+  # because WSL handed a POSIX path to the native binary (#582's own case).
+  #
+  # #592 established this distinction for exit 0 + FTL. The same test applies here,
+  # and the order matters as much: a scanner that could not start must never be
+  # reported as having found something, or the gate teaches people to disable it.
+  if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -qiE '(^|[[:space:]])(FTL|fatal error)[[:space:]:]|unable to load|cannot find the path'; then
+    echo "     ❌ BLOCKED - ENVIRONMENT: gitleaks exited 1 because it could not start, so"
+    echo "        NO secret scan took place. This is a tooling problem, not a verdict"
+    echo "        about the staged code."
+    printf '%s\n' "$GITLEAKS_OUTPUT" | grep -iE 'FTL|fatal|unable|cannot find' | head -3 | sed 's/^/        /'
+    echo "   Fix the gitleaks config/invocation above and commit again."
+    exit 1
+  fi
   # Secrets found — output details
   echo "$GITLEAKS_OUTPUT"
   echo ""

package/hooks/adapter-common.sh

@@ -155,19 +155,57 @@ require_tool() {
   local tool_name="$1"
   local gate_name="${2:-Gate}"
   local install_hint="${3:-}"
-  
+
+  # #593: on Windows the hook runs under git-bash, which does not see the
+  # toolchains installed on the Windows side (%APPDATA%\npm, the node dir,
+  # pip --user Scripts, ~/bin). Bootstrapping before probing turns "not on this
+  # shell's PATH" back into "found", instead of reporting an installed tool as
+  # missing. lib/toolchain-path.sh is sourced by pre-commit before this runs; the
+  # guard keeps require_tool usable from adapters that load on their own.
+  if command -v bootstrap_toolchain_path >/dev/null 2>&1; then
+    bootstrap_toolchain_path
+  fi
+
+  # #580: on WSL (appendWindowsPath=false) and in git-bash, `command -v node`
+  # returns 1 while node.exe sits in the same directory and runs. One root cause
+  # gave Gate 1 a silent SKIP, Gate 1 a false "Biome check failed" and Gate 8 a
+  # false "gitleaks not installed" — an environment fault reported as a code
+  # verdict in all three. tool_is_available also counts the .exe suffix and the
+  # XP_GATE_<TOOL>_BIN override.
+  if command -v tool_is_available >/dev/null 2>&1 && tool_is_available "$tool_name"; then
+    return 0
+  fi
+
   if command -v "$tool_name" >/dev/null 2>&1; then
     return 0
   fi
-  
+
+  if command -v "${tool_name}.exe" >/dev/null 2>&1; then
+    return 0
+  fi
+
   if command -v npx >/dev/null 2>&1 && npx --no-install "$tool_name" --version >/dev/null 2>&1; then
     return 0
   fi
-  
+
+  # #593: monorepos keep the tool in a subproject's node_modules/.bin, where
+  # neither PATH nor `npx` from the repo root can see it.
+  if command -v resolve_tool_path >/dev/null 2>&1 && resolve_tool_path "$tool_name" >/dev/null 2>&1; then
+    if command -v ensure_tool_dir_on_path >/dev/null 2>&1; then
+      ensure_tool_dir_on_path "$tool_name" || true
+    fi
+    return 0
+  fi
+
   echo "❌ BLOCKED - Required tool '$tool_name' not available for $gate_name"
   if [ -n "$install_hint" ]; then
     echo "   Install: $install_hint"
   fi
+  # #593 point 3: "not installed" and "installed but not found" need different
+  # fixes, so name every location that was searched.
+  if command -v describe_tool_search >/dev/null 2>&1; then
+    describe_tool_search "$tool_name"
+  fi
   echo "   Per QUALITY-GATES-CODE-OF-CONDUCT.md: tool unavailable = BLOCK, not SKIP"
   return 1
 }

package/hooks/gate-3.sh

@@ -233,7 +233,16 @@ else
       fi
       fi
     else
-      echo "⏭️  SKIPPED - Complexity (no source files to check)."
+      # #589: "no source files to check" described an empty PROJECT when the real
+      # cause is an empty CHANGED_FILES — an empty DIFF, or a `--all` run whose
+      # tree genuinely has no sources. The old wording read like a pass, which is
+      # why the reporter worked around the gate by running lizard by hand.
+      if [ -n "${GATE_SCOPE:-}" ] && [ "$GATE_SCOPE" = "all" ]; then
+        echo "⏭️  SKIPPED - Complexity: no tracked source files in this repository (scope: --all, whole tree)."
+      else
+        echo "⏭️  SKIPPED - Complexity: no changed source files in this run (scope: diff)."
+        echo "   Run 'xp-gate check . --all' to scan the whole tree."
+      fi
       GATE_3_STATUS="SKIP"
       # Consumed by the sourcing parent (pre-commit report JSON), not here.
       # shellcheck disable=SC2034

package/hooks/gate-8.sh

@@ -33,10 +33,23 @@ fi
 
 GITLEAKS_CONFIG=""
 if [ -f ".gitleaks.toml" ]; then
-  # gitleaks is a native binary and may not understand MSYS paths, so pass an
+  # gitleaks is a native binary and may not understand MSYS/WSL 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
+  #
+  # #582 found this the hard way: `cygpath` exists only in Git-for-Windows/MSYS, and on
+  # WSL its absence meant the fallback handed `/mnt/d/projects/<repo>/.gitleaks.toml`
+  # to the native gitleaks.exe. It could not open the file, exited 1, and Gate 8
+  # reported "Secrets detected". The conversion now lives in a shared library so the
+  # next gate handing a path to a native binary does not re-derive it (#581).
+  #
+  # This script may also run standalone (archived/copied hook) without the library, so
+  # the converter is used when present and the inline branch kept as the fallback.
+  if declare -F to_native_path >/dev/null 2>&1; then
+    GITLEAKS_CONFIG="--config=$(to_native_path "$(pwd)/.gitleaks.toml")"
+  elif command -v cygpath >/dev/null 2>&1; then
     GITLEAKS_CONFIG="--config=$(cygpath -w "$(pwd)/.gitleaks.toml")"
+  elif command -v wslpath >/dev/null 2>&1; then
+    GITLEAKS_CONFIG="--config=$(wslpath -w "$(pwd)/.gitleaks.toml")"
   else
     GITLEAKS_CONFIG="--config=$(pwd)/.gitleaks.toml"
   fi
@@ -75,10 +88,41 @@ if [ "$GITLEAKS_EXIT" -eq 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)"
+    # #592: exit 0 with no usable report has TWO very different causes, and the
+    # operator can only act if we tell them which one happened:
+    #
+    #   (a) the scan never ran — config unreadable, FTL, bad --report-path.
+    #       Nothing was checked, so this must fail closed with the tool's own
+    #       words, not be filed as "no evidence about the code".
+    #   (b) the scan ran and found nothing, but the tool wrote no file (reported
+    #       for gitleaks 8.30.1 on WSL; measured NOT to happen in git-bash with
+    #       the same version, so the code must handle both). Only stdout is left,
+    #       and stdout is weaker evidence than an artifact, so it still may not
+    #       produce a PASS.
+    #
+    # The order matters and is the point: artifact first, tool failure second,
+    # tool output last (#449 established the principle; #592 re-opens it).
+    if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -qiE '(^|[[:space:]])(FTL|fatal error)[[:space:]:]|unable to load'; then
+      echo "     ❌ BLOCKED - ENVIRONMENT: gitleaks exited 0 but reported a failure, so"
+      echo "        NO secret scan took place. This is a tooling problem, not a verdict"
+      echo "        about the staged code."
+      printf '%s\n' "$GITLEAKS_OUTPUT" | grep -iE 'FTL|fatal|unable' | head -3 | sed 's/^/        /'
+      echo "   Fix the gitleaks config/invocation above and commit again."
+      exit 1
+    fi
+
+    if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -q 'no leaks found'; then
+      # The scan demonstrably ran and found nothing, but there is no artifact to
+      # prove it beyond this line. Reporting PASS from log wording is exactly what
+      # #449 forbade, so this stays SKIP — and says WHY, which the old message did
+      # not: without that, SKIP is indistinguishable from "tool missing".
+      echo "     ⚠️  gitleaks scanned and reported no leaks, but wrote no report file"
+      echo "        (${GITLEAKS_REPORT} missing). No artifact means no PASS (#449)."
+      echo "     ⏭️  SKIPPED - secret scanning produced no artifact (scan reported clean)."
+    else
+      echo "     ⚠️  gitleaks exited 0 but produced no readable report and no scan summary"
+      echo "     ⏭️  SKIPPED - secret scanning produced no evidence (not a pass)"
+    fi
     GATE_8_STATUS="SKIP"
   else
     echo "     ❌ BLOCKED - gitleaks reported $GITLEAKS_FINDINGS finding(s)"
@@ -88,6 +132,23 @@ if [ "$GITLEAKS_EXIT" -eq 0 ]; then
     exit 1
   fi
 elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
+  # #582: gitleaks exits 1 for BOTH "leaks found" and "I could not start" (unreadable
+  # config, bad path, IO error). Treating every exit 1 as a finding produced the
+  # loudest possible wrong answer: "Secrets detected in staged files", plus
+  # instructions to rotate a key, on a repository where nothing had been scanned --
+  # because WSL handed a POSIX path to the native binary (#582's own case).
+  #
+  # #592 established this distinction for exit 0 + FTL. The same test applies here,
+  # and the order matters as much: a scanner that could not start must never be
+  # reported as having found something, or the gate teaches people to disable it.
+  if printf '%s\n' "$GITLEAKS_OUTPUT" | grep -qiE '(^|[[:space:]])(FTL|fatal error)[[:space:]:]|unable to load|cannot find the path'; then
+    echo "     ❌ BLOCKED - ENVIRONMENT: gitleaks exited 1 because it could not start, so"
+    echo "        NO secret scan took place. This is a tooling problem, not a verdict"
+    echo "        about the staged code."
+    printf '%s\n' "$GITLEAKS_OUTPUT" | grep -iE 'FTL|fatal|unable|cannot find' | head -3 | sed 's/^/        /'
+    echo "   Fix the gitleaks config/invocation above and commit again."
+    exit 1
+  fi
   # Secrets found — output details
   echo "$GITLEAKS_OUTPUT"
   echo ""

package/hooks/lib/coverage-total.sh

@@ -81,12 +81,27 @@ enforce_python_coverage() {
         echo "    Run the full suite for a real Python coverage check."
         return 0
       fi
-      echo "❌ BLOCKED - Python coverage ${COVERAGE_PERCENT}% below 80% threshold"
+      echo "❌ BLOCKED - Python coverage ${COVERAGE_PERCENT}% below ${COVERAGE_THRESHOLD:-80}% threshold"
       return 1
     fi
-    echo "Python coverage: ${COVERAGE_PERCENT}% ✅ (≥ 80%)"
-  else
-    echo "⚠️  Could not determine Python coverage percentage. Ensure pytest-cov or coverage.py data exists."
+    echo "Python coverage: ${COVERAGE_PERCENT}% ✅ (≥ ${COVERAGE_THRESHOLD:-80}%)"
+    return 0
+  fi
+
+  # #570: reaching here means the gate produced NO measurement. That is a FAILED
+  # answer to "is coverage at or above the floor?", not a lenient one — the gate
+  # exists to answer that question and answered nothing. Warning and returning 0
+  # made the gate fail-open: deleting .coverage (or a pytest run that died before
+  # writing it) disabled the coverage check while the summary still looked clean.
+  #
+  # The one legitimate exception is a subset run: nothing was measured because
+  # only part of the suite was run, so there is no total to compare.
+  if [ "${PARTIAL_TEST_RUN:-false}" = "true" ]; then
+    echo "⚠️  Could not determine Python coverage percentage (subset test run) — not blocking."
+    return 0
   fi
-  return 0
+  echo "❌ BLOCKED - Could not determine Python coverage percentage."
+  echo "   No .coverage / coverage report was produced, so the ${COVERAGE_THRESHOLD:-80}% floor"
+  echo "   cannot be verified. Run the suite with coverage (pytest --cov) and commit again."
+  return 1
 }