@boyingliu01/xp-gate 0.19.3 → 0.20.1

package/adapters/gate-4.sh

@@ -16,29 +16,97 @@ if [ "$PROJECT_LANG" = "documentation-only" ]; then
 else
   # Get source files to check against principles
   PRINCIPLES_FILES=$(echo "$CHANGED_FILES" | grep -E '\.(ts|tsx|js|jsx|py|go|java|kt|dart|swift|cpp|c|hpp|h|m|mm)$' || true)
+
+  # One path per line, into an array. Passing $PRINCIPLES_FILES unquoted relies on
+  # word splitting to turn the list into separate argv entries, which also splits
+  # any path containing a space -- handing the checker two bogus paths and checking
+  # neither. Quoting it would instead collapse the list into one argument. An array
+  # is the only form that does both. Same defect class as the --config fix (#457).
+  PRINCIPLES_ARGS=()
+  while IFS= read -r _principles_file; do
+    [ -n "$_principles_file" ] && PRINCIPLES_ARGS+=("$_principles_file")
+  done <<< "$PRINCIPLES_FILES"
   
   if [ -n "$PRINCIPLES_FILES" ]; then
-    # Check for principles checker in installed modules first, then project src/
+    # Same anchoring as githooks/gate-4.sh: CHANGED_FILES paths are repo-root relative
+    # and the checker resolves them against its own working directory, so both the
+    # probes and the invocation run from the repo root. Resolving them against the
+    # hook's CWD lost the checker in single-language subdir mode (#478).
+    PRINCIPLES_BASE="${PROJECT_ROOT:-$(pwd)}"
+
     PRINCIPLES_DIR=""
-    if [ -d ".xp-gate/modules/principles" ]; then
-      PRINCIPLES_DIR=".xp-gate/modules/principles"
-    elif [ -f "src/principles/index.ts" ]; then
-      PRINCIPLES_DIR="src/principles"
-    elif [ -d "$HOME/.config/xp-gate/modules/principles" ]; then
-      PRINCIPLES_DIR="$HOME/.config/xp-gate/modules/principles"
-    fi
+    for _principles_candidate in \
+      "$PRINCIPLES_BASE/.xp-gate/modules/principles" \
+      "$PRINCIPLES_BASE/src/principles" \
+      "$(pwd)/.xp-gate/modules/principles" \
+      "$(pwd)/src/principles" \
+      "$HOME/.config/xp-gate/modules/principles"; do
+      if [ -f "$_principles_candidate/index.ts" ]; then
+        PRINCIPLES_DIR="$_principles_candidate"
+        break
+      fi
+    done
     
     if [ -n "$PRINCIPLES_DIR" ]; then
       echo "Checking Clean Code + SOLID principles..."
       
       if command -v npx > /dev/null 2>&1; then
-        # Run principles checker and store results
-        if npx tsx $PRINCIPLES_DIR/index.ts --files $PRINCIPLES_FILES --format json > /tmp/principles-output.json 2>/dev/null; then
-          # Check severity levels
-          ERROR_COUNT=$(grep -c '"severity":"error"' /tmp/principles-output.json 2>/dev/null || true)
+        # Run principles checker and store results.
+        #
+        # Do NOT wrap this in `if ...; then`: the checker's exit codes are
+        # deliberately distinct (0 clean, 1 ERROR-severity findings, >=2 tool
+        # failure), and an `if` collapses 1 and 2 into "failed". That sent real
+        # error-severity findings down the crash branch, which SKIPs and prints
+        # PASSED -- releasing exactly the most serious violations.
+        # The trailing `|| PRINCIPLES_EXIT=$?` captures the exit status without
+        # letting a non-zero return abort the hook under `set -e`. pre-commit itself
+        # runs with only `set -o pipefail` (no `set -e`, pinned by
+        # scripts/__tests__/gate-5-runner-error.test.ts AC-454-08), but this module is
+        # also sourced by consumer hooks that may set it, and a bare call followed by
+        # `PRINCIPLES_EXIT=$?` never reaches the assignment under `set -e`. `|| true`
+        # would erase the status -- which is exactly the distinction this gate depends
+        # on.
+        PRINCIPLES_EXIT=0
+        # Keep stderr: it carries the checker's configuration warnings -- a rejected
+        # threshold or an out-of-vocabulary severity says so here and nowhere else.
+        # Sending it to /dev/null made an exit-2 SKIP undiagnosable and hid every
+        # .principlesrc typo (Delphi walkthrough MC-03). Captured to a file so a clean
+        # run stays quiet, then replayed only when the checker had a problem.
+        # `cd || exit 2`: a base we cannot enter means the checker never ran, which is
+        # this module's tool-failure code. Falling through would return the exit status
+        # of the failed cd (1), and 1 asserts "I examined files and found errors" -- an
+        # empty report at 1 reads as a clean pass.
+        #
+        # The report is a PER-INVOCATION mktemp, not a shared `/tmp/principles-output.json`:
+        # two commits racing on one machine (two worktrees, a hook and a CI job) overwrote
+        # each other's report before it was counted, so a run with ERROR findings could
+        # read a clean report and PASS (#457). PRINCIPLES_JSON is exported so a caller can
+        # point a harness at the same file.
+        PRINCIPLES_STDERR=$(mktemp)
+        PRINCIPLES_JSON=$(mktemp)
+        export PRINCIPLES_JSON
+        ( cd "$PRINCIPLES_BASE" 2>/dev/null || exit 2
+          npx tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format json ) > "$PRINCIPLES_JSON" 2>"$PRINCIPLES_STDERR" || PRINCIPLES_EXIT=$?
+
+        if [ -s "$PRINCIPLES_STDERR" ]; then
+          sed 's/^/     /' "$PRINCIPLES_STDERR"
+        fi
+        rm -f "$PRINCIPLES_STDERR"
+
+        if [ "$PRINCIPLES_EXIT" -ge 2 ]; then
+          echo "⚠️  Warning: Principles checker execution failed"
+          echo "⏭️  SKIPPED - Principles check (execution issue)"
+          GATE_4_STATUS="SKIP"
+          rm -f "$PRINCIPLES_JSON"
+        else
+          # Check severity levels. The reporter emits JSON.stringify(out, null, 2),
+          # i.e. `"severity": "warning"` WITH a space; tolerate any whitespace so a
+          # future minified format cannot silently zero these counts again (#444).
+          ERROR_COUNT=$(grep -cE '"severity"[[:space:]]*:[[:space:]]*"error"' "$PRINCIPLES_JSON" 2>/dev/null || true)
           ERROR_COUNT=${ERROR_COUNT:-0}
-          WARNING_COUNT=$(grep -c '"severity":"warning"' /tmp/principles-output.json 2>/dev/null || true)
+          WARNING_COUNT=$(grep -cE '"severity"[[:space:]]*:[[:space:]]*"warning"' "$PRINCIPLES_JSON" 2>/dev/null || true)
           WARNING_COUNT=${WARNING_COUNT:-0}
+          rm -f "$PRINCIPLES_JSON"
           
           if [ "$ERROR_COUNT" -gt 0 ]; then
             echo ""
@@ -47,7 +115,8 @@ else
             echo "  - error-handling violations"
             echo "  - SOLID principle violations"
             echo "  - architectural violations"
-            npx tsx $PRINCIPLES_DIR/index.ts --files $PRINCIPLES_FILES --format console
+            ( cd "$PRINCIPLES_BASE" 2>/dev/null || exit 2
+              npx tsx "$PRINCIPLES_DIR/index.ts" --files ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"} --format console )
             GATE_4_STATUS="FAIL"
             exit 1
           fi
@@ -57,10 +126,6 @@ else
           if [ "$WARNING_COUNT" -gt 0 ]; then
             echo "ℹ️  $WARNING_COUNT warnings found (will be handled by Boy Scout Rule)."
           fi
-        else
-          echo "⚠️  Warning: Principles checker execution failed"
-          echo "⏭️  SKIPPED - Principles check (execution issue)"
-          GATE_4_STATUS="SKIP"
         fi
       else
         echo "ℹ️  npx not available - skipping principles check"

package/adapters/gate-8.sh

@@ -1,11 +1,14 @@
 # ============================================================================
-# GATE 8: Secret Scanning (gitleaks)
-# Detects secrets (API keys, passwords, tokens) in staged files
-# Tool: gitleaks -- https://github.com/gitleaks/gitleaks
+# GATE 8: Secret Scanning (gitleaks + detect-secrets)
+# Detects secrets (API keys, passwords, tokens) in staged files.
+# Tools:
+#   gitleaks        -- primary, fail-closed (missing or non-0/1 exit => BLOCK, #499)
+#   detect-secrets  -- secondary, baseline-diff: only blocks on secrets NOT in
+#                      .secrets.baseline; silently does nothing when unavailable
 # ============================================================================
 
  2>&1 echo ""
- 2>&1 echo "→ Gate 8: Secret scanning (gitleaks)..."
+ 2>&1 echo "→ Gate 8: Secret scanning (gitleaks + detect-secrets)..."
 GATE_8_START=$(gate_start_ms)
 
 # Gitleaks availability check
@@ -16,41 +19,124 @@ elif [ -f "$HOME/.local/bin/gitleaks" ]; then
   GITLEAKS_CMD="$HOME/.local/bin/gitleaks"
 fi
 
-if [ -n "$GITLEAKS_CMD" ]; then
-  GITLEAKS_CONFIG=""
-  if [ -f ".gitleaks.toml" ]; then
-    GITLEAKS_CONFIG="--config=.gitleaks.toml"
+if [ -z "$GITLEAKS_CMD" ]; then
+  # fail-closed (#499): an uninstalled gitleaks used to SKIP the gate, so any
+  # contributor without it shipped commits with zero secret protection and no
+  # signal. A security gate that cannot run must not report success.
+  echo "     ❌ BLOCKED - gitleaks not installed (fail-closed, #499)."
+  echo "   Secret scanning is mandatory before commit. Install gitleaks then retry:"
+  echo "     macOS:   brew install gitleaks"
+  echo "     Windows: winget install gitleaks"
+  echo "     Linux:   scripts/install-gitleaks.sh  (or https://github.com/gitleaks/gitleaks)"
+  exit 1
+fi
+
+GITLEAKS_CONFIG=""
+if [ -f ".gitleaks.toml" ]; then
+  # gitleaks is a native binary and may not understand MSYS 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
+    GITLEAKS_CONFIG="--config=$(cygpath -w "$(pwd)/.gitleaks.toml")"
+  else
+    GITLEAKS_CONFIG="--config=$(pwd)/.gitleaks.toml"
   fi
+fi
 
-  # Run gitleaks on staged changes only (pre-commit mode for speed)
-  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --pre-commit --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path=/tmp/gitleaks-report.json 2>&1)
-  GITLEAKS_EXIT=$?
+# Scan the INDEX, not history. gitleaks 8.x `git --pre-commit` walks committed
+# revisions and reports "0 commits scanned" on a pre-commit run -- so a staged
+# secret was never seen and Gate 8 always passed. `git --staged` scans
+# `git diff --cached`, which is exactly the pre-commit payload (#449).
+GITLEAKS_REPORT="${TMPDIR:-/tmp}/gitleaks-report.json"
+rm -f "$GITLEAKS_REPORT"
+GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --staged --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
+GITLEAKS_EXIT=$?
 
-  if [ "$GITLEAKS_EXIT" -eq 0 ]; then
+if [ "$GITLEAKS_EXIT" -eq 0 ]; then
+  # Decide SKIP from the REPORT ARTIFACT, not from log wording. Parsing stdout
+  # meant a gitleaks message change would silently turn a no-evidence run into
+  # a PASS -- the same fail-open class this gate just fixed (#449).
+  # The report exists and is a JSON array of findings; `[]` == clean scan.
+  GITLEAKS_FINDINGS="?"
+  if [ -f "$GITLEAKS_REPORT" ]; then
+    # A report that is not shaped like a JSON array is no evidence: leave the
+    # '?' sentinel so the gate reports SKIP, never a PASS it cannot support
+    # (the fail-closed-on-the-claim rule #449 established).
+    if grep -q '^\[' "$GITLEAKS_REPORT" 2>/dev/null; then
+      # Count occurrences, not matching lines: `grep -c` prints its own zero AND
+      # exits 1 on a clean report, so the old `|| echo 0` handed the verdict table
+      # $'0\n0' -- no branch matched and a clean scan was BLOCKED as if it leaked
+      # (#493). wc -l emits exactly one value, and `|| true` keeps the assignment
+      # errexit/pipefail-safe (#489).
+      GITLEAKS_FINDINGS=$(grep -o '"RuleID"' "$GITLEAKS_REPORT" 2>/dev/null | wc -l | tr -d '[:space:]') || true
+    fi
+  fi
+
+  if [ "$GITLEAKS_FINDINGS" = "0" ]; then
     echo "     ✅ PASSED - No secrets detected."
     GATE_8_STATUS="PASS"
-  elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
-    # Secrets found — output details
+  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)"
+    GATE_8_STATUS="SKIP"
+  else
+    echo "     ❌ BLOCKED - gitleaks reported $GITLEAKS_FINDINGS finding(s)"
     echo "$GITLEAKS_OUTPUT"
     echo ""
-    echo "❌ BLOCKED - Secrets detected in staged files."
-    echo ""
-    echo "Remediation options:"
-    echo "  1. Remove the secret and use environment variables instead"
-    echo "  2. Add a false positive to .gitleaks.toml allowlist"
-    echo "  3. Use git secret or vault for sensitive data"
-    echo ""
-    echo "See: https://github.com/gitleaks/gitleaks"
+    echo "Remediation: remove the secret, or allowlist a false positive in .gitleaks.toml."
     exit 1
+  fi
+elif [ "$GITLEAKS_EXIT" -eq 1 ]; then
+  # Secrets found — output details
+  echo "$GITLEAKS_OUTPUT"
+  echo ""
+  echo "     ❌ BLOCKED - Secrets detected in staged files."
+  echo ""
+  echo "Remediation options:"
+  echo "  1. Remove the secret and use environment variables instead"
+  echo "  2. Add a false positive to .gitleaks.toml allowlist"
+  echo "  3. Use git secret or vault for sensitive data"
+  echo ""
+  echo "See: https://github.com/gitleaks/gitleaks"
+  exit 1
+else
+  # fail-closed (#499): a non-0/1 exit (config error, crash) used to SKIP, which
+  # let a broken scanner wave every commit through without any scan.
+  echo "     ❌ BLOCKED - gitleaks exited with code $GITLEAKS_EXIT (fail-closed, #499)."
+  echo "$GITLEAKS_OUTPUT"
+  echo "   Secret scanning could not complete; fix the gitleaks error above and retry."
+  exit 1
+fi
+
+# ---- detect-secrets（次要防线，基线比对）----
+# detect-secrets-hook comes from the project's Python dev extra; it blocks only
+# on secrets NOT yet registered in .secrets.baseline, so test-fixture dummy keys
+# recorded in the baseline never trip it.
+#
+# The file list is piped NUL-delimited STRAIGHT into xargs -0 — never through a
+# command substitution. `var=$(cmd -z)` strips every NUL byte (bash cannot hold
+# NULs in a variable), which concatenated all filenames into one giant
+# nonexistent path and would have BLOCKED every commit once a project shipped
+# both detect-secrets-hook and .secrets.baseline. The pipeline lives inside an
+# if-condition (errexit-exempt); a non-zero hook exit lands in the else branch.
+if command -v detect-secrets-hook >/dev/null 2>&1 && [ -f ".secrets.baseline" ]; then
+  DS_TMP="$(dirname "$(mktemp -u)")/ds-output.$$"
+  if git diff --cached --name-only --diff-filter=ACM -z \
+      | xargs -0 detect-secrets-hook --baseline .secrets.baseline > "$DS_TMP" 2>&1; then
+    echo "     ✅ detect-secrets PASSED - no new secrets beyond baseline."
   else
-    echo "     ⚠️  gitleaks exited with code $GITLEAKS_EXIT - skipping gate"
-    echo "     ✅ Secret Scanning (SKIP, gitleaks error)"
-    GATE_8_STATUS="SKIP"
+    cat "$DS_TMP"
+    echo ""
+    echo "     ❌ BLOCKED - detect-secrets found secrets not in .secrets.baseline."
+    echo "   If these are false positives, regenerate the baseline (cross-platform):"
+    echo "     detect-secrets scan --update .secrets.baseline && git add .secrets.baseline"
+    rm -f "$DS_TMP"
+    exit 1
   fi
+  rm -f "$DS_TMP"
 else
-  echo "     ℹ️  gitleaks not installed — secret scanning unavailable"
-  echo "     Install: brew install gitleaks (macOS) | winget install gitleaks (Windows) | scripts/install-gitleaks.sh (Linux)"
-  echo "     ⏭️  SKIPPED - Secret scanning (gitleaks not installed)"
-  GATE_8_STATUS="SKIP"
+  echo "     ⚠️  detect-secrets-hook unavailable (install: pip install -e \".[dev]\") — gitleaks only."
 fi
+
 record_gate_audit "gate-8" "secret-scanning" "$GATE_8_STATUS" "0" "$GATE_8_START"

package/adapters/iac.sh

@@ -124,7 +124,7 @@ run_static_analysis() {
 
     # Print captured output then check for failures
     cat "$checkov_log"
-    local failed_count=$(grep -c "FAILED for resource" "$checkov_log" 2>/dev/null || echo 0)
+    local failed_count=$(grep -c "FAILED for resource" "$checkov_log" 2>/dev/null || true)
     rm -f "$checkov_log"
 
     if [ "$failed_count" -gt 0 ]; then

package/adapters/powershell.sh

@@ -190,17 +190,72 @@ run_coverage() {
       source_files[${#source_files[@]}]="$path"
     done < "$discovery_file"
     rm -f "$discovery_file"
+
+    # Optional project-level exclusions. Some scripts cannot be instrumented or
+    # exercised by a unit-test runner at all (e.g. a bootstrap script whose Main
+    # ends in `exit`, which terminates the Pester host when invoked in-process).
+    # Counting them as 0% coverage permanently caps the achievable percentage and
+    # makes the threshold unsatisfiable no matter how good the suite is.
+    # Format: one glob per line in .xp-gate-powershell-coverage-ignore
+    local ignore_file=".xp-gate-powershell-coverage-ignore"
+    if [ -f "$ignore_file" ]; then
+      local filtered=()
+      local src
+      for src in "${source_files[@]}"; do
+        local skip=0
+        local pat
+        # Discovery yields paths like "./setup.ps1"; match the pattern against the
+        # raw path AND the "./"-stripped form so a plain "setup.ps1" glob works.
+        local src_norm="${src#./}"
+        while IFS= read -r pat; do
+          # skip blanks and comments
+          case "$pat" in ''|'#'*) continue ;; esac
+          local pat_norm="${pat#./}"
+          # shellcheck disable=SC2254
+          case "$src" in $pat|$pat_norm) skip=1; break ;; esac
+          # shellcheck disable=SC2254
+          case "$src_norm" in $pat_norm) skip=1; break ;; esac
+        done < "$ignore_file"
+        if [ "$skip" -eq 0 ]; then
+          filtered[${#filtered[@]}]="$src"
+        else
+          echo "  ℹ️  Coverage exclusion matched: $src"
+        fi
+      done
+      # Assign back unconditionally: when EVERY source file matched an
+      # exclusion, `filtered` is empty and the check below must see 0 to skip
+      # coverage. Only assigning on >0 silently ignored a full exclusion.
+      # (Empty-array guards keep this bash-3.2 / `set -u` safe.)
+      if [ "${#filtered[@]}" -gt 0 ]; then
+        source_files=("${filtered[@]}")
+      else
+        source_files=()
+      fi
+    fi
+
+    if [ "${#source_files[@]}" -eq 0 ]; then
+      echo "No PowerShell source files left after exclusions, skipping coverage"
+      return 0
+    fi
+
     test_paths=$(_powershell_path_array "${test_files[@]}")
     coverage_paths=$(_powershell_path_array "${source_files[@]}")
     echo "Running Pester with code coverage..."
+    # Pester 5 requires the modern configuration object: `-Path ... -CodeCoverage ...`
+    # is the deprecated Pester 4 parameter set and fails outright on Pester 5.x
+    # ("cannot resolve parameter set"). Using it silently produced no coverage.xml,
+    # which the pre-commit hook then reported as an unparseable/zero result.
     _pester_timeout "$PWSH" "${POWERSHELL_ARGS[@]}" "
-      \$results = Invoke-Pester -Path $test_paths -CodeCoverage $coverage_paths -PassThru
+      \$cfg = New-PesterConfiguration
+      \$cfg.Run.Path = $test_paths
+      \$cfg.CodeCoverage.Enabled = \$true
+      \$cfg.CodeCoverage.Path = $coverage_paths
+      \$cfg.CodeCoverage.OutputFormat = 'JaCoCo'
+      \$cfg.CodeCoverage.OutputPath = (Join-Path (Get-Location) 'coverage.xml')
+      \$cfg.Run.PassThru = \$true
+      \$results = Invoke-Pester -Configuration \$cfg
       \$pct = [math]::Round(\$results.CodeCoverage.CoveragePercent, 1)
       Write-Host \"Coverage: \$pct%\"
-      if (\$pct -lt 80) {
-        Write-Host \"WARNING: Coverage \$pct% is below 80% threshold\"
-        exit 0
-      }
       exit 0
     " 2>&1
     local cov_exit=$?

package/adapters/python.sh

@@ -4,13 +4,33 @@
 # 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
 
 run_static_analysis() {
   require_tool mypy "mypy" || return 1
 
+  # 口径 = CI type job（.github/workflows/ci.yml:43-45）的两条命令，逐字一致。
+  # 为什么不能写 `mypy .`：`.` 会递归扫到两类文件，而它们在仓库里从未被声明为
+  # 门禁面，CI 也从不检查：
+  #   ① 根目录一次性调研/演示脚本（fetch_*.py、demo_*.py、validate_*.py 等）——
+  #      `[tool.ruff] exclude`（pyproject.toml:217-238）已逐文件把它们列为"历史产物，
+  #      从未被 `ruff check src/ tests/` 覆盖"，mypy 侧却没有对应排除；
+  #   ② `tests/` —— CI 只跑 `mypy src/` 与 `mypy scripts/`，测试域的类型问题
+  #      没有任何门禁核对过。
+  # 两份清单不一致的后果是钩子恒红且与本仓任何真实缺陷无关：实测 `mypy .` 87 条
+  # error（本机），而 `mypy src/`（136 files）与 `mypy scripts/`（42 files）各自
+  # exit 0。即当时钩子会阻断**任何**提交，包括纯文档改动。
+  # 处置是让钩子对齐已声明的 CI 口径，而不是给那 87 处补注解——补注解既不在声明
+  # 口径内，又会顺手动几十个无关文件（含 tests/）。
+  # 口径一致性由仓库侧 BATS 测试双向锁住：
+  # githooks/__tests__/adapter-mypy-pester-scope.test.bats（含"适配器里不得再
+  # 出现裸 mypy ."），防止 `mypy .` 被写回来时无人报警。
   echo "Running Python static analysis (mypy)..."
-  mypy .
+  mypy src/ || return 1
+  mypy scripts/
   return $?
 }
 
@@ -45,7 +65,8 @@ run_tests() {
   require_tool pytest "pytest" || return 1
 
   echo "Running Python tests..."
-  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short 2>&1)
+  # Skip e2e tests by default in pre-commit (require live API + network)
+  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short -m "not e2e" 2>&1)
   PYTEST_EXIT=$?
 
   # Show the short summary tail — this is where FAILED/assert diagnostics live.
@@ -85,7 +106,10 @@ run_coverage() {
   require_tool pytest "pytest" || return 1
 
   echo "Running Python coverage..."
-  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short --cov=. --cov-fail-under=80 2>&1)
+  # 阈值不在此处硬编码：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)
   PYTEST_EXIT=$?
   echo "$PYTEST_OUTPUT" | grep -E "(FAILED|PASSED|passed|failed|error|ERROR|TOTAL|assert)" | tail -10
   echo "$PYTEST_OUTPUT" | tail -5
@@ -152,7 +176,17 @@ run_mutation() {
   local MUTATION_OUTPUT
   MUTATION_OUTPUT=$(mktemp)
 
-  timeout "${timeout_s}s" mutmut run --paths-to-mutate $file_list > "$MUTATION_OUTPUT" 2>&1
+  local MUTMUT_CMD="mutmut"
+  if ! command -v mutmut >/dev/null 2>&1; then
+    MUTMUT_CMD="python3 -m mutmut"
+  fi
+
+  # SC2086：`$MUTMUT_CMD` 与 `$file_list` 都是**故意按空白分词**的——
+  # 前者可能是两个词（`python3 -m mutmut`），后者是空格分隔的多条路径，
+  # 加引号会把它们并成单个参数、直接让命令失败。故此处显式声明意图，
+  # 而不是改成引号（引号在这里不是修 bug，是造 bug）。
+  # shellcheck disable=SC2086
+  timeout "${timeout_s}s" $MUTMUT_CMD run --paths-to-mutate $file_list > "$MUTATION_OUTPUT" 2>&1
   local EXIT_CODE=$?
 
   cat "$MUTATION_OUTPUT"

package/adapters/typescript.sh

@@ -3,70 +3,25 @@
 # TypeScript adapter for quality gates
 
 run_static_analysis() {
-  if ! command -v npx >/dev/null 2>&1; then
-    echo "npx not available, skipping TypeScript static analysis"
-    return 0
-  fi
-
-  local HAS_ERRORS=0
-  local TSC_VERSION
-
-  echo "Running TypeScript static analysis..."
-  npx tsc --noEmit
-  TSC_EXIT=$?
-  if [ $TSC_EXIT -ne 0 ]; then
-    HAS_ERRORS=1
+  # The type-check decision is shared with pre-commit's Gate 1 (#436): a project's
+  # own checker (typecheck script, or GATE_TS_TYPECHECK_CMD) is used when declared,
+  # otherwise the pre-#436 `npx tsc --noEmit` path. This adapter's contract predates
+  # that split, so it keeps reporting only 0 (clean/skipped) or 1 (type errors).
+  local lib_dir
+  lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)"
+  if [ -n "$lib_dir" ] && [ -f "$lib_dir/typecheck.sh" ]; then
+    # shellcheck source=/dev/null
+    source "$lib_dir/typecheck.sh"
   fi
 
-  # Also check test files if tsconfig.json exists (see Issue #293).
-  # Many projects exclude __tests__/ from tsconfig.json, so test file type
-  # errors silently accumulate. We detect this and run a second tsc pass.
-  local HAS_TESTS=false
-  if [ -d "src/__tests__" ] || [ -d "src/tests" ] || [ -d "tests" ] || [ -d "__tests__" ]; then
-    HAS_TESTS=true
-  fi
-
-  if [ "$HAS_TESTS" = true ] && [ -f "tsconfig.json" ]; then
-    # Check if tsconfig.json already includes test files
-    if npx tsc --noEmit --listFiles 2>/dev/null | grep -qE '__tests__/|\.test\.ts|\.spec\.ts'; then
-      : # Test files already checked — no additional pass needed
-    elif [ -f "tsconfig.tests.json" ]; then
-      echo "Checking test files with tsconfig.tests.json..."
-      npx tsc --noEmit --project tsconfig.tests.json
-      TSC_TEST_EXIT=$?
-      if [ $TSC_TEST_EXIT -ne 0 ]; then
-        HAS_ERRORS=1
-      fi
-    else
-      # Generate a temp tsconfig that includes test files for the additional pass
-      local TSC_TEST_EXIT=0
-      echo "Checking test files for type errors (generating temp tsconfig)..."
-      npx tsc --noEmit 2>/dev/null
-      # Create temp tsconfig extending the original but with test files included
-      local TEMP_TSCONFIG=".tsconfig.withtests.json"
-      if [ ! -f "$TEMP_TSCONFIG" ]; then
-        node -e "
-          const cfg = JSON.parse(require('fs').readFileSync('tsconfig.json','utf8'));
-          delete cfg.exclude;
-          cfg.include = cfg.include || ['src/**/*'];
-          cfg.include.push('src/**/__tests__/**','src/**/*.test.ts','src/**/*.spec.ts');
-          require('fs').writeFileSync('$TEMP_TSCONFIG', JSON.stringify(cfg, null, 2));
-        " 2>/dev/null
-        npx tsc --noEmit --project "$TEMP_TSCONFIG"
-        TSC_TEST_EXIT=$?
-        rm -f "$TEMP_TSCONFIG"
-      fi
-      if [ $TSC_TEST_EXIT -ne 0 ]; then
-        echo ""
-        echo "❌ BLOCKED - TYPE ERRORS in test files"
-        echo "Your project's tsconfig.json excludes test files from type checking."
-        echo "Fix the type errors above or add a tsconfig.tests.json to customise test file checking."
-        HAS_ERRORS=1
-      fi
-    fi
+  if ! command -v run_typescript_typecheck >/dev/null 2>&1; then
+    echo "typecheck.sh not resolvable, skipping TypeScript static analysis"
+    return 0
   fi
 
-  return $HAS_ERRORS
+  run_typescript_typecheck
+  [ $? -eq 1 ] && return 1
+  return 0
 }
 
 run_lint() {

package/bin/xp-gate.js

@@ -6,6 +6,7 @@ const { updateSkill } = require('../lib/update-skill.js');
 const { uninstallSkill } = require('../lib/uninstall-skill.js');
 const { uninstall } = require('../lib/uninstall.js');
 const { doctor } = require('../lib/doctor.js');
+const { parseSkillFlags, SKILL_FLAGS_BY_COMMAND } = require('../lib/shared-utils.js');
 const { checkDeps } = require('../lib/detect-deps.js');
 const { migrate } = require('../lib/migrate.js');
 const { handleBaseline } = require('../lib/baseline.js');
@@ -80,18 +81,18 @@ const COMMANDS = {
     usage: 'xp-gate setup-global'
   },
   'install-skill': {
-    description: 'Install a xp-gate skill from GitHub',
+    description: 'Install a xp-gate skill from the package bundle',
     run: subargs => {
       const name = subargs[0];
       if (!name) {
         console.error('Error: Skill name required');
-        console.error('Usage: xp-gate install-skill <name>[@<version>]');
+        console.error('Usage: xp-gate install-skill <name> [--verbose] [--force]');
         process.exit(1);
       }
-      const options = parseOptions(subargs.slice(1));
+      const options = parseOptions(subargs.slice(1), 'install-skill');
       installSkill(name, options).then(code => process.exit(code));
     },
-    usage: 'xp-gate install-skill <name>[@<version>] [--offline] [--verbose] [--force]'
+    usage: 'xp-gate install-skill <name> [--verbose] [--force]'
   },
   'update-skill': {
     description: 'Update installed skill(s)',
@@ -101,12 +102,12 @@ const COMMANDS = {
       let name, options;
       if (allFlagIndex !== -1) {
         // Remove --all from args before parsing, name is undefined
-        options = parseOptions([...subargs.slice(0, allFlagIndex), ...subargs.slice(allFlagIndex + 1)]);
+        options = parseOptions([...subargs.slice(0, allFlagIndex), ...subargs.slice(allFlagIndex + 1)], 'update-skill');
         options.all = true;
         name = undefined;  // explicit: no single name when --all is used
       } else {
         name = subargs[0];
-        options = parseOptions(subargs.slice(1));
+        options = parseOptions(subargs.slice(1), 'update-skill');
       }
       updateSkill(name, options).then(code => process.exit(code));
     },
@@ -121,7 +122,7 @@ const COMMANDS = {
         console.error('Usage: xp-gate uninstall-skill <name>');
         process.exit(1);
       }
-      const options = parseOptions(subargs.slice(1));
+      const options = parseOptions(subargs.slice(1), 'uninstall-skill');
       uninstallSkill(name, options).then(code => process.exit(code));
     },
     usage: 'xp-gate uninstall-skill <name> [--force]'
@@ -139,7 +140,7 @@ const COMMANDS = {
   'doctor': {
     description: 'Diagnose xp-gate installation health',
     run: subargs => doctor(subargs).then(code => process.exit(code)),
-    usage: 'xp-gate doctor [--fix]'
+    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': {
     description: 'Run UI review for non-sprint developers (generates .ui-gate-result.json)',
@@ -487,14 +488,12 @@ function printStatsTable(stats) {
   console.log('└──────────────────┴────────┴────────┴────────────┘');
 }
 
-function parseOptions(args) {
-  const options = { offline: false, verbose: false, force: false, all: false, check: false };
-  for (const arg of args) {
-    if (arg === '--offline') options.offline = true;
-    if (arg === '--verbose') options.verbose = true;
-    if (arg === '--force') options.force = true;
-    if (arg === '--all') options.all = true;
-    if (arg === '--check') options.check = true;
+function parseOptions(args, command) {
+  const { options, unknown } = parseSkillFlags(args, command);
+  if (unknown.length > 0) {
+    console.error(`Unknown argument(s) for ${command}: ${unknown.join(', ')}`);
+    console.error(`Supported flags: ${(SKILL_FLAGS_BY_COMMAND[command] || []).join(', ') || '(none)'}`);
+    process.exit(1);
   }
   return options;
 }