@boyingliu01/xp-gate 0.23.0 → 0.25.0

package/adapter-common.sh

@@ -220,9 +220,58 @@ detect_mutation_testable() {
   fi
   return 1
 }
-# Detect if a Python project has mutmut installed and configured
+# Echo the pytest-xdist parallel arguments when xdist is importable, or an
+# empty string with a stderr warning when it is not (#516). NEVER fails and
+# never blocks: serial semantics are the safe fallback, the warning only tells
+# the user why Gate 5 is slow. `-n auto` uses every core; `--dist loadfile`
+# groups tests per file to avoid cross-file shared state (module-level
+# fixtures, shared sqlite) racing under parallel workers — measured on a
+# 2555-test project: 30-45min serial -> 2m23s parallel with zero flaky runs.
+# Callers must invoke unquoted and unset: `pytest $(python_xdist_args) ...`
+# (SC2086-intentional: the value is a multi-word argument list).
+python_xdist_args() {
+  if python -c "import xdist" >/dev/null 2>&1; then
+    printf '%s' "-n auto --dist loadfile"
+    return 0
+  fi
+  echo "⚠ pytest-xdist not installed — Gate 5 falls back to SERIAL (may be 10x slower). Install: pip install pytest-xdist" >&2
+  return 0
+}
+# Detect a usable Python mutation engine (#410).
+#
+# Two engines, probed in preference order:
+#   1. pytest-gremlins — mutation switching (no fork), natively cross-platform,
+#      requires Python >= 3.11. Preferred wherever it is installed.
+#   2. mutmut — fork()-based, so on Windows it is ONLY runnable under WSL.
+#
+# The original implementation returned success as soon as `mutmut --version`
+# worked, which on native Windows produced a structural deadlock: `mutmut run`
+# exits 1 with "please use the WSL", so every push was blocked by a check that
+# could never pass — while uninstalling mutmut flipped the gate to SKIP. The
+# platform branch below is what removes that deadlock; it never blocks, it only
+# decides whether Gate M runs or skips.
 detect_python_mutation_testable() {
-  # Check for mutmut installation
+  # Engine 1: pytest-gremlins (cross-platform, no fork).
+  if command -v python >/dev/null 2>&1 && python -c "import pytest_gremlins" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Determine whether mutmut can actually RUN here, not merely whether it is
+  # installed — that distinction is the whole point of this function on Windows.
+  local _uname_s
+  _uname_s="$(uname -s 2>/dev/null || echo unknown)"
+  case "$_uname_s" in
+    MINGW*|MSYS*|CYGWIN*)
+      # Native Windows: mutmut is unusable without WSL.
+      if command -v wsl >/dev/null 2>&1 && wsl mutmut --version >/dev/null 2>&1; then
+        return 0
+      fi
+      echo "⚠ Gate M (Python): mutmut cannot run on native Windows (fork()-based) and no WSL mutmut found — SKIP. Install pytest-gremlins instead: pip install pytest-gremlins (needs Python >= 3.11)." >&2
+      return 1
+      ;;
+  esac
+
+  # Unix: mutmut is fine natively.
   if command -v mutmut >/dev/null 2>&1; then
     return 0
   fi

package/adapters/python.sh

@@ -133,7 +133,12 @@ run_tests() {
 
   echo "Running Python tests..."
   # Skip e2e tests by default in pre-commit (require live API + network)
-  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short -m "not e2e" 2>&1)
+  # #516: pytest-xdist parallel when available, serial fallback otherwise.
+  # Unquoted expansion is intentional (multi-word arg list): the helper
+  # returns `-n auto --dist loadfile` as SEPARATE words, or an empty string
+  # for a serial fallback. Quoting would collapse it into one bogus argument.
+  # shellcheck disable=SC2046
+  PYTEST_OUTPUT=$(pytest $(python_xdist_args) --exitfirst --tb=short -m "not e2e" 2>&1)
   PYTEST_EXIT=$?
 
   # Show the short summary tail — this is where FAILED/assert diagnostics live.
@@ -176,7 +181,10 @@ run_coverage() {
   # 阈值不在此处硬编码：pytest-cov 自动读取 pyproject.toml 的
   # [tool.coverage.report] fail_under（唯一事实源）。此前这里重复写了
   # --cov-fail-under=79.9，改 pyproject 不会让门禁跟着变，属于假配置。
-  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short --cov=src -m "not e2e" 2>&1)
+  # #516: xdist 并行（可用时），pytest-cov 与 xdist 正常联动（worker 各自
+  # 测量、主进程合并），fail_under 判定不受影响。
+  # shellcheck disable=SC2046
+  PYTEST_OUTPUT=$(pytest $(python_xdist_args) --exitfirst --tb=short --cov=src -m "not e2e" 2>&1)
   PYTEST_EXIT=$?
   echo "$PYTEST_OUTPUT" | grep -E "(FAILED|PASSED|passed|failed|error|ERROR|TOTAL|assert)" | tail -10
   echo "$PYTEST_OUTPUT" | tail -5

package/bin/xp-gate.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const path = require('path');
 const { init } = require('../lib/init.js');
+const { delphiSetup } = require('../lib/delphi-setup.js');
 const { installSkill } = require('../lib/install-skill.js');
 const { updateSkill } = require('../lib/update-skill.js');
 const { uninstallSkill } = require('../lib/uninstall-skill.js');
@@ -80,6 +81,11 @@ const COMMANDS = {
     run: () => init(['--global']).then(code => process.exit(code)),
     usage: 'xp-gate setup-global'
   },
+  'delphi-setup': {
+    description: 'Rebind the three Qoder Delphi expert agents to distinct built-in models (#414)',
+    run: subargs => delphiSetup(subargs).then(code => process.exit(code)),
+    usage: 'xp-gate delphi-setup --model architecture=<id> --model technical=<id> --model feasibility=<id> [--global|--local --project <dir>]'
+  },
   'install-skill': {
     description: 'Install a xp-gate skill from the package bundle',
     run: subargs => {
@@ -139,7 +145,15 @@ const COMMANDS = {
   },
   'doctor': {
     description: 'Diagnose xp-gate installation health',
-    run: subargs => doctor(subargs).then(code => process.exit(code)),
+    run: subargs => {
+      // `xp-gate doctor delphi` is a dedicated chain diagnosis (#414 REQ-3),
+      // not a flag of the generic doctor run.
+      if (subargs[0] === 'delphi') {
+        const { doctorDelphi } = require('../lib/doctor.js');
+        return doctorDelphi({}).then(code => process.exit(code));
+      }
+      return doctor(subargs).then(code => process.exit(code));
+    },
     usage: 'xp-gate doctor [--fix [--install-tools] | --sync-hooks [--force]] | --json | --format json  (the two machine-readable modes print one JSON document and refuse --fix/--sync-hooks)'
   },
   'ui-review': {

package/hooks/adapter-common.sh

@@ -220,9 +220,58 @@ detect_mutation_testable() {
   fi
   return 1
 }
-# Detect if a Python project has mutmut installed and configured
+# Echo the pytest-xdist parallel arguments when xdist is importable, or an
+# empty string with a stderr warning when it is not (#516). NEVER fails and
+# never blocks: serial semantics are the safe fallback, the warning only tells
+# the user why Gate 5 is slow. `-n auto` uses every core; `--dist loadfile`
+# groups tests per file to avoid cross-file shared state (module-level
+# fixtures, shared sqlite) racing under parallel workers — measured on a
+# 2555-test project: 30-45min serial -> 2m23s parallel with zero flaky runs.
+# Callers must invoke unquoted and unset: `pytest $(python_xdist_args) ...`
+# (SC2086-intentional: the value is a multi-word argument list).
+python_xdist_args() {
+  if python -c "import xdist" >/dev/null 2>&1; then
+    printf '%s' "-n auto --dist loadfile"
+    return 0
+  fi
+  echo "⚠ pytest-xdist not installed — Gate 5 falls back to SERIAL (may be 10x slower). Install: pip install pytest-xdist" >&2
+  return 0
+}
+# Detect a usable Python mutation engine (#410).
+#
+# Two engines, probed in preference order:
+#   1. pytest-gremlins — mutation switching (no fork), natively cross-platform,
+#      requires Python >= 3.11. Preferred wherever it is installed.
+#   2. mutmut — fork()-based, so on Windows it is ONLY runnable under WSL.
+#
+# The original implementation returned success as soon as `mutmut --version`
+# worked, which on native Windows produced a structural deadlock: `mutmut run`
+# exits 1 with "please use the WSL", so every push was blocked by a check that
+# could never pass — while uninstalling mutmut flipped the gate to SKIP. The
+# platform branch below is what removes that deadlock; it never blocks, it only
+# decides whether Gate M runs or skips.
 detect_python_mutation_testable() {
-  # Check for mutmut installation
+  # Engine 1: pytest-gremlins (cross-platform, no fork).
+  if command -v python >/dev/null 2>&1 && python -c "import pytest_gremlins" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Determine whether mutmut can actually RUN here, not merely whether it is
+  # installed — that distinction is the whole point of this function on Windows.
+  local _uname_s
+  _uname_s="$(uname -s 2>/dev/null || echo unknown)"
+  case "$_uname_s" in
+    MINGW*|MSYS*|CYGWIN*)
+      # Native Windows: mutmut is unusable without WSL.
+      if command -v wsl >/dev/null 2>&1 && wsl mutmut --version >/dev/null 2>&1; then
+        return 0
+      fi
+      echo "⚠ Gate M (Python): mutmut cannot run on native Windows (fork()-based) and no WSL mutmut found — SKIP. Install pytest-gremlins instead: pip install pytest-gremlins (needs Python >= 3.11)." >&2
+      return 1
+      ;;
+  esac
+
+  # Unix: mutmut is fine natively.
   if command -v mutmut >/dev/null 2>&1; then
     return 0
   fi

package/hooks/lib/coverage-total.sh

@@ -46,6 +46,16 @@ parse_coverage_total() {
 # report reads it after the Stage-2 loop (last writer wins across languages),
 # exactly as the inline branch did.
 enforce_python_coverage() {
+  # Critical-1 (#399): when the test run was skipped (PY_STRATEGY=skip, set in
+  # pre-commit before this Stage-2 function), refuse to consume a stale
+  # .coverage left by an earlier subset run — its low % is meaningless for a
+  # commit that changed no Python and must not BLOCK a docs-only change. This
+  # mirrors the TS branch's TESTS_SKIPPED guard.
+  if [ "${PY_TEST_SKIPPED:-false}" = "true" ]; then
+    echo "ℹ️  Test run was skipped — skipping Python coverage check."
+    return 0
+  fi
+
   if ! command -v coverage &> /dev/null; then
     echo "⚠️  coverage.py not available, cannot enforce Python coverage threshold."
     return 0
@@ -61,6 +71,16 @@ enforce_python_coverage() {
 
   if [ -n "$COVERAGE_PERCENT" ]; then
     if [ "$COVERAGE_PERCENT" -lt 80 ]; then
+      # #399: a subset run (smart test selection) measures only the tested
+      # files, so its global total is meaningless as a verdict — the full
+      # suite may well be >=80% even when the subset is not. Warn exactly as
+      # the TypeScript branch does (#286) instead of blocking. Full runs keep
+      # the hard BLOCK below.
+      if [ "${PARTIAL_TEST_RUN:-false}" = "true" ]; then
+        echo "⚠️  Partial coverage ${COVERAGE_PERCENT}% (subset test run, not full suite)."
+        echo "    Run the full suite for a real Python coverage check."
+        return 0
+      fi
       echo "❌ BLOCKED - Python coverage ${COVERAGE_PERCENT}% below 80% threshold"
       return 1
     fi

package/hooks/lib/python-test-selection.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# Python smart test selection (#399) — the Python counterpart of the TypeScript
+# selector (#286). Kept in its own file so the strategy truth table and the
+# related-test lookup are unit-testable without executing the hook
+# (githooks/__tests__/issue-399-python-test-selection.test.bats).
+#
+# Why: Python pre-commit ran the FULL suite on every commit (2-5min on a
+# 1000+-test project). TypeScript already counts changed test files, resolves
+# related tests from changed sources, and only falls back to the full suite
+# for large batches. Python had no equivalent.
+#
+# Three tiers, matching the TS implementation:
+#   1. changed-tests — only test files changed: run exactly those.
+#   2. related      — source files changed, no test files: run the tests that
+#                     the path convention maps to them.
+#   3. full         — >20 test files changed, dependency files changed, or no
+#                     related tests found: run everything with the real
+#                     coverage threshold.
+# Tier 1/2 run WITHOUT the global coverage threshold (subset coverage is
+# meaningless globally); the caller marks the run partial so Stage 2 warns
+# instead of blocking.
+
+# Max changed test files before falling back to the full suite. Same value as
+# the TypeScript branch (#286) so the two languages behave alike.
+PY_MAX_CHANGED_TESTS=20
+
+# Dependency manifests: a change here can break ANY test, so the selector
+# always escalates to the full suite regardless of how few tests changed.
+PY_DEPENDENCY_PATTERNS='(^|/)(pyproject\.toml|setup\.py|setup\.cfg|requirements[^/]*\.txt)$'
+
+# Decide the strategy from three counts. Pure function — no filesystem access,
+# so the truth table is exhaustive and cheap to test.
+#
+#   $1 test_count  changed test files
+#   $2 src_count   changed non-test Python source files
+#   $3 deps_changed 1 when a dependency manifest changed, else 0
+#
+# Echoes exactly one of: full | changed-tests | related | skip
+select_python_test_strategy() {
+  local test_count="${1:-0}"
+  local src_count="${2:-0}"
+  local deps_changed="${3:-0}"
+
+  # Dependency changes can break anything -> always the full suite.
+  if [ "$deps_changed" = "1" ]; then
+    printf '%s' "full"
+    return 0
+  fi
+
+  # Large batch: the per-file selection loses its point, and the TS branch
+  # uses the same cutoff.
+  if [ "$test_count" -gt "$PY_MAX_CHANGED_TESTS" ] 2>/dev/null; then
+    printf '%s' "full"
+    return 0
+  fi
+
+  if [ "$test_count" -gt 0 ] 2>/dev/null; then
+    printf '%s' "changed-tests"
+    return 0
+  fi
+
+  if [ "$src_count" -gt 0 ] 2>/dev/null; then
+    printf '%s' "related"
+    return 0
+  fi
+
+  printf '%s' "skip"
+}
+
+# Resolve the test files related to one source file, following the conventions
+# pytest projects actually use. Echoes one path per line, deduplicated, in
+# discovery order. Echoes nothing when no candidate exists — the caller then
+# falls back to the full suite (tier 3).
+#
+#   $1 source path, e.g. src/foo/bar.py
+python_related_tests() {
+  local src_file="$1"
+  [ -n "$src_file" ] || return 0
+
+  local base="${src_file%.*}"
+  local filename="${base##*/}"
+  local dir
+  dir="$(dirname "$src_file")"
+
+  local candidates=""
+  # Directory-relative candidates first (most specific), then flat tests/,
+  # then the collocated forms. Covers both pytest naming conventions
+  # (test_<name>.py and <name>_test.py).
+  candidates="$candidates
+${dir}/test_${filename}.py
+${dir}/${filename}_test.py
+${dir}/__tests__/test_${filename}.py
+${dir}/__tests__/${filename}_test.py"
+  # tests/<dir-surviving-subpath>/… : src/foo/bar.py -> tests/foo/test_bar.py
+  local subpath="${dir#src/}"
+  [ "$subpath" = "$dir" ] && subpath="$dir"
+  candidates="$candidates
+tests/${subpath}/test_${filename}.py
+tests/${subpath}/${filename}_test.py"
+  candidates="$candidates
+tests/test_${filename}.py
+tests/${filename}_test.py"
+
+  local seen=""
+  local candidate
+  # IFS-safe iteration over newline-separated candidates.
+  while IFS= read -r candidate; do
+    [ -n "$candidate" ] || continue
+    [ -f "$candidate" ] || continue
+    # Dedupe: several patterns can resolve to the same file (e.g. a source at
+    # repo root has dir='.' so the relative and flat forms coincide).
+    case "$seen" in
+      *"|$candidate|"*) continue ;;
+    esac
+    seen="$seen|$candidate|"
+    printf '%s\n' "$candidate"
+  done <<EOF
+$candidates
+EOF
+}
+
+# True (0) when any of the given paths is a Python dependency manifest.
+python_dependency_changed() {
+  local path
+  for path in "$@"; do
+    [ -n "$path" ] || continue
+    if echo "$path" | grep -qE "$PY_DEPENDENCY_PATTERNS"; then
+      return 0
+    fi
+  done
+  return 1
+}

package/hooks/pre-commit

@@ -230,6 +230,11 @@ source "${AUDIT_SCRIPT_DIR}/lib/sprint-gate-report.sh"
 # unit-testable without executing this hook.
 source "${AUDIT_SCRIPT_DIR}/lib/coverage-total.sh"
 
+# Issue #399: Python smart test selection — strategy decision + related-test
+# lookup, kept in a library so the truth table and the path conventions are
+# unit-testable without executing this hook.
+source "${AUDIT_SCRIPT_DIR}/lib/python-test-selection.sh"
+
 # Read max_duration_ms from .xp-gate-config.json (default 7200000 = 2 hours)
 _MAX_DURATION_MS=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('${PROJECT_ROOT_FOR_AUDIT}/.xp-gate-config.json','utf8'));console.log((c.audit&&c.audit.max_duration_ms)||7200000);}catch(e){console.log(7200000);}" 2>/dev/null || echo "7200000")
 
@@ -2294,6 +2299,13 @@ else
   else
   echo "Running coverage check..."
 
+  # Major-2 (Delphi): COV_EXIT aggregates coverage-run failures across ALL
+  # languages in Stage 1. It starts at 0 and each language branch ORs its own
+  # result in (`COV_EXIT=$((COV_EXIT || $?))`), so a later language's success
+  # can never mask an earlier language's subset-run failure. Previously every
+  # branch overwrote COV_EXIT and the last language's status won.
+  COV_EXIT=0
+
   for CURRENT_LANG in $PROJECT_LANGS; do
   ADAPTER_FILE=$(resolve_adapter_path "$CURRENT_LANG")
   if [ "${CURRENT_LANG}" != "unknown" ] && [ -n "$ADAPTER_FILE" ]; then
@@ -2307,13 +2319,13 @@ else
           # If no tests were run (TESTS_SKIPPED=true), skip coverage check entirely.
           if [ "${TESTS_SKIPPED:-false}" = "true" ]; then
             echo "ℹ️  Test run was skipped — skipping coverage check."
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           elif [ -f "coverage/coverage-summary.json" ]; then
             echo "TypeScript coverage collected during test run."
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           else
             echo "ℹ️  No coverage data produced — test run was skipped (no TS changes)."
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           fi
           ;;
         "python")
@@ -2334,12 +2346,89 @@ else
             fi
             [ -z "$PY_COV_SOURCE" ] && PY_COV_SOURCE="--cov=."
             [ -z "$PY_COV_FAIL_UNDER" ] && PY_COV_FAIL_UNDER=80
-            pytest $PY_COV_SOURCE --cov-fail-under="$PY_COV_FAIL_UNDER" --tb=short
-            COV_EXIT=$?
+
+            # ── #399: smart test selection, the Python counterpart of #286 ──
+            # Three tiers (lib/python-test-selection.sh holds the pure
+            # decision logic + related-test lookup, unit-tested separately):
+            #   changed-tests / related -> run ONLY those targets, with the
+            #     repo's coverage SOURCE but WITHOUT the global fail_under
+            #     (subset coverage is meaningless globally). The run is marked
+            #     partial so Stage 2 warns instead of falsely blocking.
+            #   full -> unchanged behavior: whole suite + real threshold.
+            #   skip -> nothing test-relevant changed; no pytest at all.
+            PY_CHANGED_TEST_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+              | grep -E '(^|/)test_[^/]*\.py$|_test\.py$' || true)
+            PY_CHANGED_SRC_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+              | grep -E '\.py$' | grep -vE '(^|/)test_[^/]*\.py$|_test\.py$' || true)
+            PY_CHANGED_ALL=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)
+            # `grep -c '.'` prints its own zero AND exits 1 on an empty list
+            # (#493), so the count is derived with `|| true` + wc -l instead.
+            PY_TEST_COUNT=$(printf '%s\n' "$PY_CHANGED_TEST_FILES" | grep -c '.' || true)
+            PY_SRC_COUNT=$(printf '%s\n' "$PY_CHANGED_SRC_FILES" | grep -c '.' || true)
+            PY_DEPS_CHANGED=0
+            if python_dependency_changed $PY_CHANGED_ALL; then PY_DEPS_CHANGED=1; fi
+            PY_STRATEGY=$(select_python_test_strategy "$PY_TEST_COUNT" "$PY_SRC_COUNT" "$PY_DEPS_CHANGED")
+
+            # xdist parallel args (#516) — empty + warning when unavailable,
+            # never a BLOCK; unquoted expansion is the multi-word arg list.
+            PY_XDIST_ARGS=$(python_xdist_args 2>/dev/null || true)
+
+            if [ "$PY_STRATEGY" = "skip" ]; then
+              echo "ℹ️  Python: no test/source changes — skipping test run (#399)."
+              # Critical-1 (#399): mark the run skipped so Stage 2's
+              # enforce_python_coverage refuses to consume a stale .coverage
+              # left by a prior subset run. Without this flag the gate read the
+              # leftover low-% file and BLOCKED a docs-only commit that changed
+              # no Python. Mirrors the TS branch's TESTS_SKIPPED guard.
+              PY_TEST_SKIPPED=true
+              COV_EXIT=$((COV_EXIT || 0))
+            elif [ "$PY_STRATEGY" = "full" ]; then
+              if [ "$PY_DEPS_CHANGED" = "1" ]; then
+                echo "ℹ️  Python: dependency manifest changed — running FULL suite (#399)."
+              elif [ "$PY_TEST_COUNT" -gt 20 ] 2>/dev/null; then
+                echo "ℹ️  Python: $PY_TEST_COUNT changed test files (>20) — running FULL suite (#399)."
+              fi
+              # shellcheck disable=SC2086
+              pytest $PY_XDIST_ARGS $PY_COV_SOURCE --cov-fail-under="$PY_COV_FAIL_UNDER" --tb=short
+              COV_EXIT=$((COV_EXIT || $?))
+            else
+              # changed-tests | related → resolve the exact targets.
+              PY_TARGETS=""
+              if [ "$PY_STRATEGY" = "changed-tests" ]; then
+                PY_TARGETS="$PY_CHANGED_TEST_FILES"
+              else
+                for _py_src in $PY_CHANGED_SRC_FILES; do
+                  _py_related=$(python_related_tests "$_py_src")
+                  if [ -n "$_py_related" ]; then
+                    PY_TARGETS="${PY_TARGETS}${_py_related}
+"
+                  fi
+                done
+                PY_TARGETS=$(printf '%s\n' "$PY_TARGETS" | grep -v '^$' | sort -u)
+              fi
+
+              if [ -z "$PY_TARGETS" ]; then
+                # related lookup found nothing → tier 3 full run is safest.
+                echo "ℹ️  Python: no related tests found for changed sources — running FULL suite (#399)."
+                # shellcheck disable=SC2086
+                pytest $PY_XDIST_ARGS $PY_COV_SOURCE --cov-fail-under="$PY_COV_FAIL_UNDER" --tb=short
+                COV_EXIT=$((COV_EXIT || $?))
+              else
+                PY_TARGET_COUNT=$(printf '%s\n' "$PY_TARGETS" | grep -c '.' || true)
+                echo "ℹ️  Python: selective run ($PY_STRATEGY) — $PY_TARGET_COUNT target(s):"
+                printf '%s\n' "$PY_TARGETS" | sed 's/^/     /'
+                # Subset run: keep --cov so data is collected, but drop the
+                # global threshold — subset coverage is meaningless globally.
+                PARTIAL_TEST_RUN=true
+                # shellcheck disable=SC2086
+                pytest $PY_XDIST_ARGS $PY_COV_SOURCE --tb=short $PY_TARGETS
+                COV_EXIT=$((COV_EXIT || $?))
+              fi
+            fi
           else
             echo "pytest/coverage not available, running coverage via adapter..."
             run_coverage_output=$(run_coverage 2>&1)
-            COV_EXIT=$?
+            COV_EXIT=$((COV_EXIT || $?))
             echo "$run_coverage_output" | head -30
           fi
           ;;
@@ -2352,30 +2441,30 @@ else
               exit 1
             fi
             echo "Go coverage: $TOTAL_COVERAGE%"
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           fi
           ;;
         "shell")
           shell_cov_output=$(run_coverage 2>&1)
-          COV_EXIT=$?
+          COV_EXIT=$((COV_EXIT || $?))
           echo "$shell_cov_output" | head -10
           echo "ℹ️  Shell coverage not typically measured"
           ;;
         *)
           default_cov_output=$(run_coverage 2>&1)
-          COV_EXIT=$?
+          COV_EXIT=$((COV_EXIT || $?))
           echo "$default_cov_output" | head -30
           ;;
       esac
     else
       # Adapter source failed — warn and let Stage 2 attempt file-based enforcement
       echo "⚠️  Could not source ${CURRENT_LANG} adapter from ${ADAPTER_FILE}, will check coverage files directly..."
-      COV_EXIT=0
+      COV_EXIT=$((COV_EXIT || 0))
     fi
   else
     # No adapter available — warn and let Stage 2 attempt file-based enforcement
     echo "⚠️  No adapter found for ${CURRENT_LANG} (searched: ${ADAPTER_DIR}/, ${ADAPTER_DIR}/adapters/, ${PROJECT_GITHOOKS}/adapters/, ${SCRIPT_DIR}/adapters/) — will check coverage files directly..."
-    COV_EXIT=0
+    COV_EXIT=$((COV_EXIT || 0))
   fi
   done  # end for CURRENT_LANG (Stage 1 coverage)