@boyingliu01/xp-gate 0.30.5 → 0.31.1

package/adapters/powershell.sh

@@ -61,6 +61,69 @@ _detect_pwsh() {
 
 _find_powershell_files() {
   local name_pattern="$1"
+
+  # #573: repo-local extra prune entries. The list below covers the artifact
+  # directories xp-gate itself produces, but a consuming repo can have its own
+  # (a generated obj/, a vendored third_party/, a samples/ tree of
+  # intentionally broken scripts) and had no way to exclude them -- so its Gate 1
+  # stayed the warning wall #538 fixed for xp-gate's own layout.
+  #
+  # Entries are appended to the built-in list, never replace it: `wrc-drill` is
+  # pinned here for xp-gate's own admin drills. Matched by -name, so a listed
+  # directory is pruned at any depth.
+  #
+  # Built as an ARRAY, not a string spliced into an eval: the entries come from
+  # a file in the checked-out repo, and a directory name is not something to
+  # hand to a shell parser.
+  local -a prune_args=()
+  local prune_file=".xp-gate-powershell-prune-dirs"
+  if [ -f "$prune_file" ]; then
+    local entry
+    while IFS= read -r entry; do
+      entry="${entry%$'\r'}"
+      # #578: strip a UTF-8 BOM before anything else. PowerShell 5.1's
+      # `Set-Content -Encoding UTF8` writes one, and it glues itself to the first
+      # line -- so the first directory name would silently never match, and a
+      # leading '#' comment would stop looking like a comment.
+      entry="${entry#$'\xEF\xBB\xBF'}"
+      # Strip surrounding whitespace, then the ./ prefix and trailing / a repo
+      # may reasonably write; -name matches a bare directory name.
+      entry="${entry#"${entry%%[![:space:]]*}"}"
+      entry="${entry%"${entry##*[![:space:]]}"}"
+      case "$entry" in ''|'#'*) continue ;; esac
+      entry="${entry#./}"
+      entry="${entry%/}"
+      [ -n "$entry" ] || continue
+
+      # #574: discovery feeds THREE denominators at once (test discovery,
+      # coverage, static-analysis scope), so a bad entry does not merely fail to
+      # prune -- it silently shrinks all three while the file still looks
+      # reasonable.
+      #   -name '*'     matches EVERY directory -> prunes the whole tree -> the
+      #                 gate analyses nothing and still exits 0.
+      #   -name 'a/b'   matches nothing (names have no separators) -> a silent
+      #                 no-op that reads as working config.
+      # Only bare directory NAMES are honoured; anything else is reported and
+      # ignored. Reported, not silently dropped: an ignored entry is a config
+      # error the operator has to see.
+      case "$entry" in
+        */*|*\\*|*'*'*|*'?'*|*'['*)
+          echo "  ⚠️  $prune_file: ignoring invalid entry '$entry' (must be a bare directory name, no separators or glob metacharacters)" >&2
+          continue
+          ;;
+        .|..)
+          echo "  ⚠️  $prune_file: ignoring invalid entry '$entry'" >&2
+          continue
+          ;;
+      esac
+
+      echo "  ℹ️  pruning directory name '$entry' (from $prune_file)" >&2
+      prune_args[${#prune_args[@]}]=-o
+      prune_args[${#prune_args[@]}]=-name
+      prune_args[${#prune_args[@]}]="$entry"
+    done < "$prune_file"
+  fi
+
   # #538: gitignored drill/review artifact dirs hold hundreds of non-product
   # .ps1 files (admin drills, Delphi review copies). Collecting them turned
   # Gate 1 into an 800+ warning wall and made the pwsh gates unusable.
@@ -75,11 +138,16 @@ _find_powershell_files() {
       -name .workbuddy -o \
       -name .sprint-state -o \
       -name wrc-drill -o \
+      -name .xp-gate -o \
+      -name .vscode -o \
+      -name .idea -o \
+      -name .qoder -o \
       -path './plugins/claude-code/skills' -o \
       -path './plugins/opencode/skills' -o \
       -path './plugins/qoder/skills' -o \
       -path './src/npm-package/skills' -o \
       -path './src/npm-package/plugins' \
+      "${prune_args[@]+"${prune_args[@]}"}" \
     \) -prune \) -o \
     \( -type f -name "$name_pattern" -print \) 2>/dev/null
 }
@@ -115,22 +183,116 @@ run_static_analysis() {
     local POWERSHELL_ARGS
     _powershell_invocation "$PWSH"
     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
     local PSSA_RC=0
     local PSSA_OUT
-    PSSA_OUT=$("$PWSH" "${POWERSHELL_ARGS[@]}" "
-      if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
-        Write-Output 'PSSA_MODULE_MISSING'
+    local scope_file=".xp-gate-powershell-analysis-paths"
+    local analysis_targets=()
+    local scope_missing=0
+
+    # #571: repo-local analysis scope. Pester test files legitimately trip
+    # dozens of rule warnings under the Pester execution model, so a whole-repo
+    # scan either blocks every PowerShell commit or forces the rule set open —
+    # both end in PowerShell not being gated at all. A repo may list its PRODUCT
+    # scope (directories and/or single files, one per line, `#` comments) and
+    # the SAME rules then apply to just that code.
+    #
+    # The load-bearing half is staleness: a listed path that no longer exists
+    # means product code ESCAPED the gate (renamed, moved, or a new script added
+    # without updating the file). That emits a reason so the pre-commit arm maps
+    # it to WARN inside the scoring denominator, instead of silently analysing
+    # less and reporting PASS. Same for a scope file with no usable entries.
+    # Without the file the legacy whole-repo behavior is kept, so existing repos
+    # are unaffected.
+    if [ -f "$scope_file" ]; then
+      local target_line
+      local declared=0
+      while IFS= read -r target_line; do
+        target_line="${target_line%$'\r'}"
+        # #578: a UTF-8 BOM (PowerShell 5.1's `Set-Content -Encoding UTF8` writes
+        # one) glues itself to the FIRST line. On a path that manufactures a
+        # nonexistent entry -- and since #576 that returns 3, so a perfectly valid
+        # scope file would fail closed on every commit. On the '#' header it turns
+        # a comment into a phantom path. Strip it before classifying.
+        target_line="${target_line#$'\xEF\xBB\xBF'}"
+        # Strip surrounding whitespace before classifying: a line of spaces is
+        # not a path, and `case` alone would treat it as one — measured, a
+        # whitespace-only line became an "analysis path not found" entry.
+        target_line="${target_line#"${target_line%%[![:space:]]*}"}"
+        target_line="${target_line%"${target_line##*[![:space:]]}"}"
+        case "$target_line" in ''|'#'*) continue ;; esac
+        declared=$((declared + 1))
+        if [ -e "$target_line" ]; then
+          # shellcheck disable=SC2004  # explicit index arithmetic on an array
+          analysis_targets[${#analysis_targets[@]}]="$target_line"
+        else
+          scope_missing=$((scope_missing + 1))
+          echo "  ℹ️  analysis path not found (skipped): $target_line"
+          echo "XP_G1_REASON: analysis-path-missing:$target_line"
+        fi
+      done < "$scope_file"
+      if [ "$declared" -eq 0 ]; then
+        # The file exists but declares nothing: analysing zero paths would exit 0
+        # and read as a clean PASS. A file whose entries are all MISSING takes
+        # the per-entry branch above instead, so the two causes stay distinct.
+        echo "XP_G1_REASON: analysis-paths-empty"
+        echo "  ℹ️  $scope_file present but declares no paths - skipping analysis"
+        return 3
+      fi
+    fi
+
+    if [ "${#analysis_targets[@]}" -gt 0 ]; then
+      # Scoped per-path run. -Path binds ONE string only (an array argument
+      # throws "Cannot convert 'System.Object[]'..."), so each target is
+      # analyzed separately and findings are aggregated.
+      local target_array
+      target_array=$(_powershell_path_array "${analysis_targets[@]}")
+      PSSA_OUT=$("$PWSH" "${POWERSHELL_ARGS[@]}" "
+        if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
+          Write-Output 'PSSA_MODULE_MISSING'
+          exit 0
+        }
+        # Non-terminating errors must become terminating: otherwise a broken
+        # settings file or unreadable path yields an empty result set that LOOKS
+        # like a clean pass.
+        \$ErrorActionPreference = 'Stop'
+        try { Import-Module PSScriptAnalyzer -ErrorAction Stop | Out-Null } catch { exit 3 }
+        \$settings = Join-Path (Get-Location) 'PSScriptAnalyzerSettings.psd1'
+        \$all = @()
+        try {
+          foreach (\$p in $target_array) {
+            \$recurse = [System.IO.Directory]::Exists(\$p)
+            if (Test-Path -LiteralPath \$settings) {
+              \$all += @(Invoke-ScriptAnalyzer -Path \$p -Recurse:\$recurse -Severity Error,Warning -Settings \$settings -ErrorAction Stop)
+            } else {
+              \$all += @(Invoke-ScriptAnalyzer -Path \$p -Recurse:\$recurse -Severity Error,Warning -ErrorAction Stop)
+            }
+          }
+        } catch {
+          Write-Output ('PSSA_RUN_ERROR: ' + \$_.Exception.Message)
+          exit 3
+        }
+        if (\$all) {
+          \$all | Format-Table -AutoSize
+          exit 1
+        }
         exit 0
-      }
-      \$results = Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error,Warning
-      if (\$results) {
-        \$results | Format-Table -AutoSize
-        exit 1
-      }
-      exit 0
-    " 2>&1) || PSSA_RC=$?
+      " 2>&1) || PSSA_RC=$?
+    else
+      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
+      " 2>&1) || PSSA_RC=$?
+    fi
+
     printf '%s\n' "$PSSA_OUT"
     case "$PSSA_RC" in
       0)
@@ -142,11 +304,32 @@ run_static_analysis() {
           echo "XP_G1_REASON: PSScriptAnalyzer module not installed (Install-Module PSScriptAnalyzer)"
           return 3
         fi
+        # #576: a scope entry that vanished means product code may have ESCAPED
+        # the gate. The reason line was emitted above, but pre-commit switches on
+        # the RETURN CODE and only uses the reason for the message text -- so
+        # returning 0 here made the reason dead weight and Gate 1 printed
+        # PASSED. Measured before this fix: "RETURN CODE = 0". The scan being
+        # clean does not make an incomplete scope a pass.
+        if [ "$scope_missing" -gt 0 ]; then
+          echo "  ⚠️  $scope_missing scope entry(ies) did not exist - product code may have escaped the gate"
+          return 3
+        fi
         return 0
         ;;
       1)
         return 1   # real findings -> BLOCK upstream
         ;;
+      3)
+        # #576: the PowerShell fragment exits 3 when the scan itself raised. That
+        # is "could not verify", not "found violations" -- pwsh would exit 1 for
+        # findings, so mapping this to 1 would report an analysis crash as lint
+        # errors. Surface the actual exception where the fragment captured one.
+        echo "XP_G1_REASON: PSScriptAnalyzer raised an error during the run"
+        printf '%s\n' "$PSSA_OUT" | grep '^PSSA_RUN_ERROR: ' | sed 's/^PSSA_RUN_ERROR: //' | head -3 | while IFS= read -r _ps_err; do
+          echo "  ⚠️  $_ps_err"
+        done
+        return 2   # unusable -> fail closed upstream
+        ;;
       *)
         echo "XP_G1_REASON: PSScriptAnalyzer run failed (exit $PSSA_RC)"
         return 2   # unusable -> fail closed upstream

package/gate-10.sh

@@ -34,6 +34,22 @@ if command -v semgrep >/dev/null 2>&1; then
   SEMGREP_CMD="semgrep"
 elif [ -f "$HOME/.local/bin/semgrep" ]; then
   SEMGREP_CMD="$HOME/.local/bin/semgrep"
+else
+  # #572: Windows pip --user installs land in
+  # %APPDATA%\Python\<ver>\Scripts\semgrep.exe, which git-bash does NOT inherit
+  # on PATH -- so a working, installed semgrep read as "not installed" and this
+  # SAST gate degraded to WARN on the platform the project is developed on.
+  # The glob is expanded by the shell (one candidate per Python version) and
+  # probed by EXIT CODE, never by parsing `semgrep --version` output: a broken
+  # install can still print a plausible version string, and the probe must
+  # distinguish "runnable" from "present".
+  for candidate in "$HOME"/AppData/Roaming/Python/*/Scripts/semgrep.exe; do
+    [ -f "$candidate" ] || continue
+    if "$candidate" --version >/dev/null 2>&1; then
+      SEMGREP_CMD="$candidate"
+      break
+    fi
+  done
 fi
 
 if [ -z "$SEMGREP_CMD" ]; then

package/hooks/gate-10.sh

@@ -34,6 +34,22 @@ if command -v semgrep >/dev/null 2>&1; then
   SEMGREP_CMD="semgrep"
 elif [ -f "$HOME/.local/bin/semgrep" ]; then
   SEMGREP_CMD="$HOME/.local/bin/semgrep"
+else
+  # #572: Windows pip --user installs land in
+  # %APPDATA%\Python\<ver>\Scripts\semgrep.exe, which git-bash does NOT inherit
+  # on PATH -- so a working, installed semgrep read as "not installed" and this
+  # SAST gate degraded to WARN on the platform the project is developed on.
+  # The glob is expanded by the shell (one candidate per Python version) and
+  # probed by EXIT CODE, never by parsing `semgrep --version` output: a broken
+  # install can still print a plausible version string, and the probe must
+  # distinguish "runnable" from "present".
+  for candidate in "$HOME"/AppData/Roaming/Python/*/Scripts/semgrep.exe; do
+    [ -f "$candidate" ] || continue
+    if "$candidate" --version >/dev/null 2>&1; then
+      SEMGREP_CMD="$candidate"
+      break
+    fi
+  done
 fi
 
 if [ -z "$SEMGREP_CMD" ]; then

package/hooks/pre-commit

@@ -3889,6 +3889,28 @@ generate_quality_report() {
   if [ "$EFFECTIVE_TOTAL" -gt 0 ]; then
     EFFECTIVE_PASS_RATE=$(awk "BEGIN {printf \"%.1f\", ($PASSED_COUNT / $EFFECTIVE_TOTAL) * 100}")
   fi
+
+  # #564: `score` above divides by the EFFECTIVE total, so a SKIPped gate leaves
+  # the denominator instead of counting against it. Arithmetic on that formula:
+  # 1 passed / 11 skipped is 1/1 -> 10.0, identical to 10 passed / 2 skipped.
+  # .quality-history.jsonl shows Gate 3 running in 7% of runs and Gate 4 in 8%,
+  # every one of them recording score 10 -- skipping work raised the score.
+  #
+  # The effective view answers a real question ("of the gates that could run,
+  # how many passed?"), so it stays. What was missing is the denominator being
+  # visible, and a score that counts skips against the run. `scoreAllGates`
+  # divides by TOTAL_GATES, so a skipped gate costs exactly what a failed one
+  # costs in that view; `gatesRan` says how much of the suite was exercised.
+  # `score` keeps its current value and meaning so dashboard/ and
+  # .quality-history.jsonl consumers do not break (#507 already made it
+  # number-or-null; this stays within that contract).
+  local GATES_RAN=$EFFECTIVE_TOTAL
+  local SCORE_ALL="N/A"
+  if [ "$TOTAL_GATES" -gt 0 ]; then
+    SCORE_ALL=$(awk "BEGIN {printf \"%.1f\", ($PASSED_COUNT / $TOTAL_GATES) * 10}")
+  fi
+  local SCORE_ALL_JSON="$SCORE_ALL"
+  [ "$SCORE_ALL_JSON" = "N/A" ] && SCORE_ALL_JSON="null"
   # JSON bodies need a number or null -- a literal N/A breaks every consumer.
   local SCORE_JSON="$SCORE"
   [ "$SCORE_JSON" = "N/A" ] && SCORE_JSON="null"
@@ -3971,6 +3993,8 @@ generate_quality_report() {
     "degradedGates": [$DEGRADED_JSON],
     "gatesEffective": $EFFECTIVE_TOTAL,
     "effectivePassRate": $EFFECTIVE_PASS_RATE_JSON,
+    "gatesRan": $GATES_RAN,
+    "scoreAllGates": $SCORE_ALL_JSON,
     "score": $SCORE_JSON,
     "verdict": "$VERDICT"
   },
@@ -4098,7 +4122,10 @@ ENDJSON
   printf "  %-45s %s\n" "Gate 11: Sprint Flow" "${GATE_11_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 12: File Hygiene" "${GATE_12_STATUS:-WARN}"
   echo ""
-  echo "  Overall Score: $SCORE/10 | $PASSED_COUNT/$TOTAL_GATES gates passed (effective: $PASSED_COUNT/$EFFECTIVE_TOTAL, skipped: $SKIP_COUNT, verdict: $VERDICT)"
+  # #564: both views in one line. The effective score answers "of the gates that
+  # could run, how many passed"; the all-gates score counts a skip against the
+  # run. Printing only the first let a 1-of-12 run read as 10.0/10.
+  echo "  Overall Score: $SCORE/10 effective | $SCORE_ALL/10 of all gates ($GATES_RAN/$TOTAL_GATES ran, $SKIP_COUNT skipped, verdict: $VERDICT)"
   echo "  Branch status: $REPORT_FILE"
   echo "  Run report: $PERSISTED_REPORT_FILE"
   echo "  History saved: $HISTORY_FILE"

package/lib/__tests__/check-all-skip-accounting.test.js

@@ -0,0 +1,171 @@
+/**
+ * @test REQ-568 `check --all` must not count a gate it never ran as passed
+ * @intent Gate 5's own output already distinguishes four states — PASS, WARN,
+ *         SKIP and FAIL — and `xp-gate check --all` collapses them into two:
+ *         `code !== 0` is a failure, everything else is a pass. A gate whose
+ *         registry entry is `preCommitOnly` prints
+ *
+ *             ⏭️  SKIPPED - <reason>
+ *             return 0;
+ *
+ *         and that 0 is counted as a pass, so 15 registered gates report as
+ *         `10/10 gate(s) passed` with exit 0. Measured on the registry:
+ *
+ *             total gates      : 15
+ *             preCommitOnly    : 5   (ids 0, 1, 5, 10, 11)
+ *             check --all runs : 10
+ *
+ *         The user-visible number is therefore true about the ten gates that
+ *         ran and silent about the five that did not. `verdict: PARTIAL` in the
+ *         hook's own report exists for the same reason; the CLI had no such
+ *         notion. This is report §5 phase-0 action 0.2.
+ * @covers AC-568-01, AC-568-02, AC-568-03
+ */
+const gateRunner = require('../gate-runner.js');
+const { checkAllGates, formatGateTally } = require('../check.js');
+
+const { GATE_REGISTRY } = gateRunner;
+
+/** Original registry contents, restored after every test. */
+let ORIGINAL_REGISTRY;
+
+// Gate ids the CLI's `check --all` path should never treat as "passed" without
+// saying so. The five real preCommitOnly ids from the shipped registry.
+const PRECOMMIT_ONLY = ['0', '1', '5', '10', '11'];
+
+/**
+ * Swap every key in GATE_REGISTRY for the supplied object's keys.
+ * @param {object} next - registry contents to install
+ */
+function replaceRegistry(next) {
+  for (const id of Object.keys(GATE_REGISTRY)) delete GATE_REGISTRY[id];
+  for (const [id, info] of Object.entries(next)) GATE_REGISTRY[id] = info;
+}
+
+/**
+ * Replace the registry with a controlled set of stub gates.
+ *
+ * The registry is swapped WHOLESALE, not added to: `getAllGates()` maps every
+ * entry, so leaving the real fifteen in place would run them too — they spawn
+ * processes and take minutes — and the tally would be about the shipped
+ * registry rather than the fixture. Measured: the first draft of this test ran
+ * the real gates and reported "8 passed / 2 failed / 5 skipped / 15 total".
+ *
+ * @param {Array<{id: string, preCommitOnly?: boolean, code?: number}>} specs
+ * @returns {Function} cleanup that restores the original registry
+ */
+function installGates(specs) {
+  const stubs = {};
+  for (const spec of specs) {
+    stubs[spec.id] = spec.preCommitOnly
+      ? {
+          name: `Stub ${spec.id}`,
+          description: 'test double',
+          aliases: [],
+          preCommitOnly: true,
+          reason: 'runs during commit',
+        }
+      : {
+          name: `Stub ${spec.id}`,
+          description: 'test double',
+          aliases: [],
+          run: () => (typeof spec.code === 'number' ? spec.code : 0),
+        };
+  }
+  replaceRegistry(stubs);
+  return () => replaceRegistry(ORIGINAL_REGISTRY);
+}
+
+let cleanup = null;
+let logSpy;
+
+beforeAll(() => {
+  ORIGINAL_REGISTRY = { ...GATE_REGISTRY };
+});
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  if (cleanup) {
+    cleanup();
+    cleanup = null;
+  }
+  vi.restoreAllMocks();
+});
+
+/**
+ * Read everything the CLI printed during the run.
+ * @returns {string} joined output
+ */
+function printed() {
+  return logSpy.mock.calls.map(args => args.join(' ')).join('\n');
+}
+
+describe('check --all skip accounting', () => {
+  test('AC-568-01: a preCommitOnly gate is reported as skipped, not passed', async () => {
+    cleanup = installGates([
+      ...PRECOMMIT_ONLY.map(id => ({ id, preCommitOnly: true })),
+      { id: '2', code: 0 },
+      { id: '3', code: 0 },
+    ]);
+
+    const code = await checkAllGates('.');
+
+    const out = printed();
+    // The summary must name the skips and must not claim a bare N/N.
+    expect(out, 'the tally must distinguish skipped from passed').toMatch(/skipped/i);
+    expect(out).toMatch(/2 passed/);
+    expect(out).toMatch(/5 skipped/);
+    // A clean run with skips still exits 0 — skips are not failures.
+    expect(code).toBe(0);
+  });
+
+  test('AC-568-02: skipped gates never inflate the passed count', async () => {
+    // The defect in one assertion: before the fix this printed "2/2 gate(s)
+    // passed" for a run where zero gates were actually executed.
+    cleanup = installGates([...PRECOMMIT_ONLY.map(id => ({ id, preCommitOnly: true }))]);
+
+    await checkAllGates('.');
+
+    const out = printed();
+    expect(out).not.toMatch(/5\/5/);
+    expect(out).toMatch(/0 passed/);
+    expect(out).toMatch(/5 skipped/);
+  });
+
+  test('AC-568-03: a real failure still fails the run and is counted apart from skips', async () => {
+    // Anti-vacuity: the tally must not have been made honest by making it
+    // never fail. One failing gate among skips and passes fails the run.
+    cleanup = installGates([
+      { id: '0', preCommitOnly: true },
+      { id: '1', preCommitOnly: true },
+      { id: '2', code: 0 },
+      { id: '3', code: 1 },
+    ]);
+
+    const code = await checkAllGates('.');
+
+    const out = printed();
+    expect(code, 'a failing gate must still exit non-zero').toBe(1);
+    expect(out).toMatch(/1 passed/);
+    expect(out).toMatch(/1 failed/);
+    expect(out).toMatch(/2 skipped/);
+  });
+
+  test('AC-568-04: formatGateTally renders all four states without loss', () => {
+    // The pure formatter, exercised directly so the wording contract is pinned
+    // independently of the gate loop.
+    expect(formatGateTally({ passed: 3, skipped: 4, failed: 0, warned: 0, total: 7 })).toBe(
+      '3 passed / 4 skipped / 7 total'
+    );
+    expect(formatGateTally({ passed: 2, skipped: 1, failed: 1, warned: 0, total: 4 })).toBe(
+      '2 passed / 1 failed / 1 skipped / 4 total'
+    );
+    expect(formatGateTally({ passed: 1, skipped: 0, failed: 0, warned: 2, total: 3 })).toBe(
+      '1 passed / 2 warned / 3 total'
+    );
+  });
+});

package/lib/__tests__/find-bash-wsl.test.js

@@ -0,0 +1,121 @@
+/**
+ * @test REQ-570 findBash must reject a WSL bash and prefer Git for Windows
+ * @intent `findBash()` puts the bare name `bash` first in its candidate list, and
+ *         accepts whatever PATH resolves it to as long as `bash --version` exits
+ *         0. On a machine with WSL installed, `bash` on PATH IS WSL:
+ *
+ *             > (Get-Command bash -All).Source
+ *             C:\WINDOWS\system32\bash.exe
+ *             C:\Users\think\AppData\Local\Microsoft\WindowsApps\bash.exe
+ *             > bash -c "uname -s"
+ *             Linux
+ *             > bash --version ; echo $LASTEXITCODE
+ *             GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
+ *             (exit 0)
+ *
+ *         Exit code 0 is exactly the probe's acceptance condition, so `findBash`
+ *         returns the string `"bash"` — WSL — and every subsequent `bash -n
+ *         <windows path>` fails with "No such file or directory", because a
+ *         Linux bash cannot open `C:/...`. That is where doctor's "hook is not
+ *         parseable" came from.
+ *
+ *         This corrupts my own audit trail, so it is worth stating plainly: in
+ *         issue #563 I wrote that the §2.2 WSL-stub false positive "does not
+ *         reproduce" and downgraded it to robustness debt. I had measured
+ *         `where bash` (which lists the WSL stubs) and the stubs' `--version`
+ *         (status null / 1 with UTF-16 garbage) and concluded the probe already
+ *         rejected them. Both measurements were about DIFFERENT bash binaries
+ *         than the one `findBash` actually reaches: `spawnSync('bash', ...)`
+ *         from Node resolves through PATH the same way the shell does, and here
+ *         that reaches a healthy WSL bash which exits 0. The finding was real;
+ *         the retraction was wrong.
+ *
+ *         Related: the POSIX-path conversion in #565 is still correct and still
+ *         needed — Git bash accepts `C:/...` while a backslash path gets eaten by
+ *         escape processing. But with the wrong bash selected, no path form
+ *         works, which is why #565 alone did not fix doctor.
+ * @covers AC-570-01, AC-570-02, AC-570-03
+ */
+const path = require('path');
+
+const { findBash } = require('../hook-health');
+
+/** Windows-only: every assertion here is about Windows bash selection. */
+const itWin = process.platform === 'win32' ? test : test.skip;
+
+/**
+ * Run `bash -s` against a command and return trimmed stdout.
+ * @param {string} bashPath - binary to interrogate
+ * @param {string} script - shell snippet
+ * @returns {{status: number|null, out: string}} result
+ */
+function runBash(bashPath, script) {
+  const { spawnSync } = require('child_process');
+  const res = spawnSync(bashPath, ['-c', script], { encoding: 'utf8', timeout: 20000 });
+  return { status: res.status, out: String(res.stdout || '').trim() };
+}
+
+describe('findBash platform selection', () => {
+  itWin('AC-570-01: the resolved bash is a Windows bash, not WSL', () => {
+    const bin = findBash();
+
+    expect(bin, 'findBash returned nothing; every hook-health probe is skipped').not.toBeNull();
+
+    // `uname -s` is the discriminator the project already uses elsewhere
+    // (detect-deps.resolveWindowsBashCandidates): Git bash reports MINGW*/MSYS*/
+    // CYGWIN*, WSL reports Linux.
+    const { out } = runBash(bin, 'uname -s');
+    expect(out, `findBash() selected "${bin}" which reports uname -s = "${out}"`).toMatch(
+      /MINGW|MSYS|CYGWIN/i
+    );
+  });
+
+  itWin('AC-570-02: a WSL bash on PATH does not win over Git for Windows', () => {
+    // The defect, stated as a property rather than as a specific fix: whatever
+    // PATH offers first, a Git for Windows bash exists on this machine (the
+    // whole test suite only runs because it does), so findBash must reach it.
+    const gitBash = path.join(
+      process.env.ProgramFiles || 'C:\\Program Files',
+      'Git',
+      'bin',
+      'bash.exe'
+    );
+
+    const bin = findBash();
+
+    if (require('fs').existsSync(gitBash)) {
+      expect(
+        path.resolve(bin),
+        'a Git for Windows bash is installed but findBash picked something else'
+      ).toBe(path.resolve(gitBash));
+    } else {
+      // No Git bash here: the WSL bash would still be wrong, so requiring a
+      // MINGW report is the honest fallback rather than accepting "bash".
+      expect(runBash(bin, 'uname -s').out).toMatch(/MINGW|MSYS|CYGWIN/i);
+    }
+  });
+
+  itWin('AC-570-03: the selected bash can actually open a Windows hook path', () => {
+    // End to end, and the reason any of this matters: the probe that doctor runs
+    // is `bash -n <path>`, so the selected binary must be able to see a Windows
+    // file at all. This is the assertion that would have caught #563's
+    // retraction being wrong.
+    const fs = require('fs');
+    const os = require('os');
+
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'findbash-probe-'));
+    const hook = path.join(dir, 'pre-commit');
+    try {
+      fs.writeFileSync(hook, '#!/bin/bash\necho hi\n');
+      const bin = findBash();
+      const posix = hook.replace(/\\/g, '/');
+
+      // Both forms are tried: a correct bash accepts both on Windows, so this
+      // asserts the binary, not the path convention (that is #565's subject).
+      expect(runBash(bin, `bash -n '${posix}' && echo PARSE_OK`).out).toContain('PARSE_OK');
+      expect(runBash(bin, `bash -n '${hook}' && echo PARSE_OK`).out).toContain('PARSE_OK');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});