@boyingliu01/xp-gate 0.31.1 → 0.31.3

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

@@ -20,15 +20,250 @@ if [ "$PROJECT_LANG" = "documentation-only" ]; then
   GATE_3_REASON="documentation_project"
 
 elif [ "$PROJECT_LANG" = "powershell" ]; then
-  echo "ℹ️  No PowerShell Clean Code / SOLID tool available"
-  echo "⏭️  SKIPPED - Complexity (no PowerShell tool)"
-  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"
-  
+  # #537/#598: this arm used to be a hard SKIP with "no PowerShell tool". That
+  # was true of lizard (it cannot parse .ps1) but NOT of the platform:
+  # PowerShell's own AST gives an exact decision-point count, which is the same
+  # quantity lizard measures for other languages. A PowerShell-primary repo
+  # therefore had a permanently unmeasured quality dimension while the score
+  # implied full coverage.
+  #
+  # The measurement lives in lib/Measure-PowerShellComplexity.ps1 because the
+  # hook cannot know a project's refactor history; the adapter only runs it and
+  # translates the verdict.
+  #
+  # The threshold resolution is duplicated from the lizard arm on purpose: the
+  # arms are read independently of each other, and a shared helper here would
+  # make the PowerShell path depend on the code path it replaces.
+  _gate3_ps_threshold() {
+    local default=5 val
+    if [ -f ".xp-gate/ccn-threshold" ]; then
+      val=$(sed -n '1s/[[:space:]]*$//p' ".xp-gate/ccn-threshold" 2>/dev/null || true)
+      case "$val" in
+        ''|*[!0-9]*) echo "WARN - invalid .xp-gate/ccn-threshold value '${val}' (expected a positive integer), falling back to ${default}" >&2 ;;
+        0) echo "WARN - invalid .xp-gate/ccn-threshold value '0' (expected a positive integer), falling back to ${default}" >&2 ;;
+        *) echo "$val"; return 0 ;;
+      esac
+    fi
+    val=${XP_GATE_CCN_THRESHOLD:-}
+    case "$val" in
+      '') echo "$default" ;;
+      *[!0-9]*) echo "WARN - invalid XP_GATE_CCN_THRESHOLD value '${val}' (expected a positive integer), falling back to ${default}" >&2; echo "$default" ;;
+      0) echo "WARN - invalid XP_GATE_CCN_THRESHOLD value '0' (expected a positive integer), falling back to ${default}" >&2; echo "$default" ;;
+      *) echo "$val" ;;
+    esac
+  }
+
+  # Resolve a PowerShell engine LOCALLY.
+  #
+  # This arm must NOT call _detect_pwsh, which is defined in
+  # adapters/powershell.sh: the hook sources that adapter inside a SUBSHELL for
+  # Gate 1 --
+  #     PS_G1_OUTPUT=$(source "$POWERSHELL_ADAPTER"; run_static_analysis)
+  # -- so its functions never reach this gate. Depending on it printed
+  # "no PowerShell engine found" on a machine with both pwsh 7 AND PS 5.1
+  # installed, i.e. the verdict was about bash scoping, not about the engine.
+  # A gate must not depend on another gate having sourced a library first.
+  _gate3_detect_pwsh() {
+    if command -v pwsh >/dev/null 2>&1; then echo pwsh; return 0; fi
+    if command -v powershell.exe >/dev/null 2>&1; then echo powershell.exe; return 0; fi
+    local _c
+    for _c in \
+      "${LOCALAPPDATA:-$HOME/AppData/Local}/Microsoft/WindowsApps/pwsh.exe" \
+      "/c/Program Files/PowerShell/7/pwsh.exe" \
+      "/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe"; do
+      [ -x "$_c" ] && { echo "$_c"; return 0; }
+    done
+    return 1
+  }
+
+  PS_CC_SCRIPT="${AUDIT_SCRIPT_DIR}/lib/Measure-PowerShellComplexity.ps1"
+  if [ ! -f "$PS_CC_SCRIPT" ]; then
+    echo "ℹ️  No PowerShell complexity tool available"
+    echo "     (expected at lib/Measure-PowerShellComplexity.ps1)"
+    echo "⏭️  SKIPPED - Complexity (no PowerShell tool)"
+    GATE_3_STATUS="SKIP"
+    # Consumed by the sourcing parent (pre-commit report JSON), not here.
+    # shellcheck disable=SC2034
+    GATE_3_REASON="no_powershell_tool"
+  else
+    # #581: pwsh.exe is a NATIVE binary and cannot open the POSIX path this hook
+    # holds (`/c/Users/...` or `/tmp/...`). Handed one unchanged it resolves the
+    # leading `/` to `<current drive>:\`, silently measures zero files, and the
+    # gate then reports "no functions" -- an environment fault reported as a
+    # verdict about the repository. Convert the script path once, here.
+    PS_CC_SCRIPT_NATIVE="$PS_CC_SCRIPT"
+    if command -v to_native_path >/dev/null 2>&1; then
+      PS_CC_SCRIPT_NATIVE=$(to_native_path "$PS_CC_SCRIPT" 2>/dev/null || echo "$PS_CC_SCRIPT")
+    fi
+    PS_CC_SCRIPT="$PS_CC_SCRIPT_NATIVE"
+    PS_CC_PWSH=$(_gate3_detect_pwsh 2>/dev/null || true)
+    if [ -z "$PS_CC_PWSH" ]; then
+      echo "⚠️  WARN - no PowerShell engine found; complexity not measured"
+      GATE_3_STATUS="WARN"
+      # Consumed by the sourcing parent (pre-commit report JSON), not here.
+      # shellcheck disable=SC2034
+      GATE_3_REASON="no_powershell_engine"
+    else
+      PS_CC_THRESHOLD=$(_gate3_ps_threshold)
+      PS_ADDED=$(git diff --cached --name-only --diff-filter=A 2>/dev/null | grep -E '\.ps(m)?1$' || true)
+      PS_BASELINE=".xp-gate-powershell-ccn-baseline.json"
+
+      if [ -z "$PS_ADDED" ]; then
+        # No added files, but modified ones can still get MORE complex. That is
+        # what the ratchet baseline is for; without a baseline there is nothing
+        # to compare, and silently passing would be the #584 failure mode.
+        PS_TOUCHED=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.ps(m)?1$' || true)
+        PS_TOUCHED=$(printf '%s\n' "$PS_TOUCHED" | grep -vE '(^|/)tests/' || true)
+        if [ -z "$PS_TOUCHED" ] || [ ! -f "$PS_BASELINE" ]; then
+          echo "⏭️  SKIPPED - Complexity (no added PowerShell files to measure)."
+          GATE_3_STATUS="SKIP"
+          # Consumed by the sourcing parent (pre-commit report JSON), not here.
+          # shellcheck disable=SC2034
+          GATE_3_REASON="no_added_powershell_files"
+        else
+          PS_CC_ARGS=()
+          for _f in $PS_TOUCHED; do PS_CC_ARGS[${#PS_CC_ARGS[@]}]="'$_f'"; done
+
+          # #598: the ratchet branch must use the SAME threshold as the baseline
+          # collector. -Threshold 1 used to make every function with CCN >= 2
+          # print OVER, so a brand-new well-factored function (CCN 2-4, below the
+          # real threshold) was diffed against a baseline that can never contain
+          # it and reported as a "regression": the gate blocked exactly the shape
+          # it exists to encourage. -List additionally emits the full population,
+          # so the comparison covers functions that are below the threshold on
+          # both sides.
+          PS_CC_OUT=$("$PS_CC_PWSH" -NoProfile -NonInteractive -ExecutionPolicy Bypass \
+            -Command "& '$PS_CC_SCRIPT' -Path @($(IFS=','; echo "${PS_CC_ARGS[*]}")) -Threshold ${PS_CC_THRESHOLD} -List" 2>&1 || true)
+
+          PS_CC_MEASURED=$(printf '%s\n' "$PS_CC_OUT" | sed -n 's/^functions_measured=//p' | tail -1)
+          if [ -z "$PS_CC_MEASURED" ] || [ "${PS_CC_MEASURED:-0}" -eq 0 ]; then
+            echo "⏭️  SKIPPED - Complexity (no functions in changed PowerShell files)."
+            GATE_3_STATUS="SKIP"
+            # Consumed by the sourcing parent (pre-commit report JSON), not here.
+            # shellcheck disable=SC2034
+            GATE_3_REASON="no_functions_found"
+          else
+            PS_CC_NODE=""
+            if command -v node >/dev/null 2>&1; then PS_CC_NODE="node"; fi
+            if [ -z "$PS_CC_NODE" ]; then
+              echo "ℹ️  node unavailable — complexity measured (${PS_CC_MEASURED} function(s)) but ratchet not compared"
+              echo "✅ PASSED - PowerShell complexity measured (ratchet unavailable)."
+              GATE_3_DETAIL="mode=measured_no_ratchet"
+            else
+              # Compare every measured function against the baseline. A function
+              # absent from the baseline is NEW: it is only a regression if it is
+              # above the threshold, which is exactly what the old -Threshold 1
+              # comparison got wrong. An unreadable baseline is ERR, not a pass.
+              PS_CC_VERDICT=$(printf '%s\n' "$PS_CC_OUT" | "$PS_CC_NODE" -e '
+                let raw = "";
+                process.stdin.on("data", (c) => { raw += c; });
+                process.stdin.on("end", () => {
+                  const fs = require("fs");
+                  const fsPath = process.argv[1];
+                  const threshold = Number(process.argv[2]);
+                  let baseline;
+                  try {
+                    baseline = JSON.parse(fs.readFileSync(fsPath, "utf8"));
+                  } catch (e) {
+                    console.log("ERR " + e.message);
+                    return;
+                  }
+                  const known = new Map();
+                  const entries = baseline.functions || baseline.entries || baseline;
+                  if (Array.isArray(entries)) {
+                    for (const e of entries) {
+                      if (!e || !e.file || !e.name) continue;
+                      known.set(norm(e.file) + "::" + e.name, Number(e.ccn) || 0);
+                    }
+                  }
+                  function norm(p) { return String(p).replace(/\\\\/g, "/").replace(/^\.\//, ""); }
+                  const seen = new Set();
+                  const regressions = [];
+                  const improved = [];
+                  for (const line of raw.split(/\r?\n/)) {
+                    const m = line.match(/^(?:OVER|FUNC) (.+):(\d+) (\S+) ccn=(\d+)$/);
+                    if (!m) continue;
+                    const key = norm(m[1]) + "::" + m[3];
+                    const now = Number(m[4]);
+                    seen.add(key);
+                    const was = known.has(key) ? known.get(key) : null;
+                    if (was === null) {
+                      if (now > threshold) {
+                        regressions.push(m[1] + ":" + m[2] + "  " + m[3] + "  new function at ccn=" + now);
+                      }
+                      continue;
+                    }
+                    if (now > was) {
+                      regressions.push(m[1] + ":" + m[2] + "  " + m[3] + "  ccn " + was + " -> " + now);
+                    } else if (now < was) {
+                      improved.push(m[1] + ":" + m[2] + "  " + m[3] + "  ccn " + was + " -> " + now);
+                    }
+                  }
+                  for (const r of regressions) console.log("REGRESSION " + r);
+                  for (const i of improved) console.log("IMPROVED " + i);
+                  if (regressions.length > 0) {
+                    console.log("FAIL " + regressions.length + " function(s) increased cyclomatic complexity vs " + fsPath + ".");
+                  }
+                });
+              ' "$PS_BASELINE" "$PS_CC_THRESHOLD" 2>&1 || true)
+
+              if printf '%s\n' "$PS_CC_VERDICT" | grep -q '^FAIL '; then
+                PS_CC_REG=$(printf '%s\n' "$PS_CC_VERDICT" | sed -n 's/^FAIL //p' | tail -1)
+                printf '%s\n' "$PS_CC_VERDICT" | grep '^REGRESSION ' | sed 's/^REGRESSION /     ❌ /'
+                echo "❌ BLOCKED - ${PS_CC_REG}"
+                GATE_3_STATUS="BLOCK"
+                GATE_3_REASON="ccn_ratchet_regression"
+                exit 1
+              elif printf '%s\n' "$PS_CC_VERDICT" | grep -q '^ERR '; then
+                echo "⚠️  WARN - complexity ratchet baseline unreadable: $(printf '%s\n' "$PS_CC_VERDICT" | sed -n 's/^ERR //p' | head -1)"
+                GATE_3_STATUS="WARN"
+                GATE_3_REASON="baseline_unreadable"
+              else
+                PS_CC_IMPROVED=$(printf '%s\n' "$PS_CC_VERDICT" | grep -c '^IMPROVED ' || true)
+                printf '%s\n' "$PS_CC_VERDICT" | grep '^IMPROVED ' | sed 's/^IMPROVED /     📉 /'
+                echo "✅ PASSED - PowerShell complexity within ratchet (${PS_CC_MEASURED} function(s), ${PS_CC_IMPROVED} improved, threshold ${PS_CC_THRESHOLD})."
+                GATE_3_STATUS="PASS"
+                GATE_3_DETAIL="powerShell_ratchet improved=${PS_CC_IMPROVED}"
+              fi
+            fi
+          fi
+        fi
+      else
+        # Freshly added files: this arm has no history to compare, so it judges
+        # each file's functions against the threshold. A file that is merely
+        # being touched keeps its history (that is what the baseline is for);
+        # measuring only ADDED files means the arm can never retroactively block
+        # a cleanup commit.
+        PS_CC_ARGS=()
+        for _f in $PS_ADDED; do PS_CC_ARGS[${#PS_CC_ARGS[@]}]="'$_f'"; done
+        PS_CC_OUT=$("$PS_CC_PWSH" -NoProfile -NonInteractive -ExecutionPolicy Bypass \
+          -Command "& '$PS_CC_SCRIPT' -Path @($(IFS=','; echo "${PS_CC_ARGS[*]}")) -Threshold ${PS_CC_THRESHOLD}" 2>&1 || true)
+        PS_CC_MEASURED=$(printf '%s\n' "$PS_CC_OUT" | sed -n 's/^functions_measured=//p' | tail -1)
+        PS_CC_OVER=$(printf '%s\n' "$PS_CC_OUT" | sed -n 's/^over_threshold=//p' | tail -1)
+        PS_CC_MAX=$(printf '%s\n' "$PS_CC_OUT" | sed -n 's/^max_ccn=//p' | tail -1)
+        if [ -z "$PS_CC_MEASURED" ] || [ "${PS_CC_MEASURED:-0}" -eq 0 ]; then
+          echo "⏭️  SKIPPED - Complexity (no functions in added PowerShell files)."
+          GATE_3_STATUS="SKIP"
+          # Consumed by the sourcing parent (pre-commit report JSON), not here.
+          # shellcheck disable=SC2034
+          GATE_3_REASON="no_functions_found"
+        elif [ "${PS_CC_OVER:-0}" -gt 0 ]; then
+          echo "   Measured ${PS_CC_MEASURED} function(s) via AST; max CCN ${PS_CC_MAX} (threshold ${PS_CC_THRESHOLD})"
+          printf '%s\n' "$PS_CC_OUT" | grep '^OVER ' | sed 's/^/     /'
+          echo "❌ BLOCKED - ${PS_CC_OVER} newly added function(s) with CCN > ${PS_CC_THRESHOLD}."
+          echo "Refactor high-complexity functions, or raise the threshold deliberately."
+          GATE_3_STATUS="BLOCK"
+          GATE_3_REASON="ccn_over_threshold"
+          exit 1
+        else
+          echo "✅ PASSED - All added PowerShell functions within complexity threshold (${PS_CC_THRESHOLD})."
+          echo "   Measured ${PS_CC_MEASURED} function(s) via AST; max CCN ${PS_CC_MAX}."
+          GATE_3_STATUS="PASS"
+        fi
+      fi
+    fi
+  fi
+
 else
   # S2 (#507): three-level CCN threshold override --
   # .xp-gate/ccn-threshold (positive integer) > XP_GATE_CCN_THRESHOLD > 5.
@@ -233,7 +468,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