@boyingliu01/xp-gate 0.25.0 → 0.27.0

package/adapters/python.sh

@@ -91,12 +91,62 @@ run_static_analysis() {
       return 0
     fi
   fi
-  # 逐目标调用并聚合退出码（口径见函数头注释）。
-  require_tool mypy "mypy" || return 1
+  # #534: engine selection. mypy is ALWAYS the authoritative engine (determinism —
+  # ty is an alpha, ~70% spec conformance, config-incompatible). ty is used ONLY
+  # as an explicit opt-in accelerator when XP_GATE_TY=1 AND `ty` is installed:
+  #   - XP_GATE_TY=1 + ty present  -> `ty check <target>` (ty's CLI is `ty check`,
+  #     not `ty`; exit 1 = type errors -> BLOCK, exit 2 = config/CLI error -> SKIP)
+  #   - XP_GATE_TY=1 + ty missing   -> SKIP (return 0), never BLOCK: the opt-in
+  #     path must not route through require_tool mypy and false-block a repo that
+  #     opted into ty but lacks mypy (Delphi R1 Critical).
+  #   - XP_GATE_TY unset            -> pure mypy (authoritative), unchanged.
+  # Scope semantics (.xp-gate-mypy-scope / src/ scripts/) are engine-independent
+  # and preserved verbatim below.
+  local _engine=mypy
+  if [ "${XP_GATE_TY:-}" = "1" ]; then
+    if command -v ty >/dev/null 2>&1; then
+      _engine=ty
+      echo "  ⚙  engine: ty (Rust, explicit opt-in via XP_GATE_TY=1) — mypy remains the default"
+    elif command -v mypy >/dev/null 2>&1; then
+      # ty opted in but missing; mypy present -> fall back to the authoritative
+      # engine with a warning (never silently drop the type gate, #534 R2 arch).
+      echo "  ⚠ ty requested (XP_GATE_TY=1) but not installed — falling back to mypy"
+    else
+      echo "  ⚠ ty opted in via XP_GATE_TY=1 but neither ty nor mypy is installed — SKIPPING type check (no BLOCK)"
+      echo "    install: pip install mypy, or pip install ty (alpha)"
+      return 0
+    fi
+  fi
+  # require_tool mypy only on the authoritative (mypy) engine path: when the
+  # user opted into ty, a missing mypy must NOT false-BLOCK (Delphi R1 Critical).
+  if [ "$_engine" = "mypy" ]; then
+    require_tool mypy "mypy" || return 1
+  fi
   local _mypy_rc=0
   local _mypy_t
   for _mypy_t in "${MYPY_TARGETS[@]}"; do
-    mypy "$_mypy_t" || _mypy_rc=1
+    if [ "$_engine" = "ty" ]; then
+      # ty's CLI is `ty check <path>`, not `ty <path>`. Bare `ty`/`ty check .`
+      # without targets would recurse the whole tree (== the anti `mypy .`
+      # guard #501/#513): targets are always explicit here. Capture ty's own
+      # exit code and diagnostics via a temp file (never discard them): a BLOCK
+      # with no reason is undebuggable, and a pipe `| head` would lose the code.
+      local _ty_rc=0
+      local _ty_tmp
+      _ty_tmp="$(mktemp)"
+      ty check "$_mypy_t" > "$_ty_tmp" 2>&1 || _ty_rc=$?
+      if [ "$_ty_rc" -eq 2 ]; then
+        echo "  ⚠ ty exited $_ty_rc on target '$_mypy_t' (config/CLI error) — SKIPPING, not blocking"
+        head -30 "$_ty_tmp"
+      elif [ "$_ty_rc" -ne 0 ]; then
+        echo "  ty report for '$_mypy_t' (exit $_ty_rc):"
+        head -30 "$_ty_tmp"
+        _mypy_rc=1
+      fi
+      rm -f "$_ty_tmp"
+    else
+      mypy "$_mypy_t" || _mypy_rc=1
+    fi
   done
   return $_mypy_rc
 }

package/bin/xp-gate.js

@@ -19,15 +19,127 @@ const { bootstrap } = require('../lib/bootstrap.js');
 const { updateHooks } = require('../lib/update-hooks.js');
 const gateRunner = require('../lib/gate-runner.js');
 
+// #392-#6: a user-supplied path embedded in a shell command string lets cmd.exe
+// interpret metacharacters (& | ^ < > % ! " and newline) and execute injected
+// commands. On POSIX a bare spawn (shell:false) passes argv as discrete,
+// uninterpreted bytes, so nothing is injectable. On win32 a `.cmd` wrapper such
+// as npx.cmd cannot be launched without a shell (CreateProcess raises EINVAL),
+// so we must shell out through cmd.exe -- and we only do so AFTER rejecting any
+// argument that carries a cmd metacharacter. Rejection, not escaping, is the
+// safe defense: a path containing a metachar is refused outright rather than
+// risk a quoting mistake. This guard must stay in front of every launcher.
+// \r joins \n: cmd treats a stray carriage return as a command separator too
+// (Delphi walkthrough R1, MN-01).
+const CMD_METACHAR_RE = /[&|^<>%!"\n\r]/;
+
+// The ONLY place a child process may be launched with an engaged shell.
+// Named so a static grep stays readable, and pinned by check-alignment-cli
+// .test.mjs: no other launcher in this file may enable a shell.
+const SHELL_ON_WINDOWS_ONLY = process.platform === 'win32';
+
+function firstUnsafeArg(argv) {
+  for (const arg of argv) {
+    if (typeof arg === 'string' && CMD_METACHAR_RE.test(arg)) return arg;
+  }
+  return undefined;
+}
+
+function quoteForCmdShell(arg) {
+  // With an engaged shell node concatenates file+args into one cmd.exe command
+  // string WITHOUT quoting (DEP0190), so an argument carrying a space would
+  // split into multiple argv elements downstream. Double-quoting is safe here
+  // ONLY because every caller has already run firstUnsafeArg: the character "
+  // that could break out of the quote is on the rejection list.
+  return `"${arg}"`;
+}
+
+function spawnNpx(tsxArgs) {
+  const { spawnSync } = require('child_process');
+  // Reject any user-supplied argument that could be interpreted by cmd.exe.
+  // Every element of tsxArgs beyond the fixed tokens (-y tsx <script>) is a
+  // user path; a metachar there is refused, not quoted, per #392-#6.
+  const unsafe = firstUnsafeArg(tsxArgs);
+  if (unsafe) {
+    console.error(`check-alignment: refusing path containing a shell metacharacter: ${unsafe}`);
+    return { status: 1 };
+  }
+  const isWin = process.platform === 'win32';
+  // The shell engages on win32 only, and is only safe because every user
+  // argument above is guaranteed metachar-free; each token additionally gets
+  // cmd quoting so spaces survive (see quoteForCmdShell).
+  // Guarded IO: a failed spawn must surface as a result, not crash the CLI.
+  const argv = ['-y', 'tsx', ...tsxArgs];
+  let result;
+  try {
+    result = spawnSync(isWin ? 'npx.cmd' : 'npx', isWin ? argv.map(quoteForCmdShell) : argv, {
+      stdio: 'inherit',
+      shell: SHELL_ON_WINDOWS_ONLY,
+    });
+  } catch (err) {
+    return { status: 1, error: err };
+  }
+  return result || { status: 1 };
+}
+
 function handleUIReview() {
-  const { execSync } = require('child_process');
   const uiReviewPath = path.join(__dirname, '..', 'lib', 'ui-review.ts');
+  const result = spawnNpx([uiReviewPath]);
+  process.exitCode = result.error ? 1 : (result.status === 0 ? 0 : 1);
+}
+
+function runAlignmentInProcess(specPath, testDirs, outputPath, jsonMode, runFullAlignment) {
+  const { execFileSync } = require('child_process');
+  if (!runFullAlignment) {
+    // Loaded lazily by the caller inside the tsx guard; kept optional so an
+    // in-repo direct call still works.
+    ({ runFullAlignment } = require('../lib/test-alignment.ts'));
+  }
+  let headCommit = 'unknown';
   try {
-    execSync(`npx -y tsx "${uiReviewPath}"`, { stdio: 'inherit' });
-    process.exit(0);
+    headCommit = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim() || 'unknown';
   } catch (err) {
-    process.exit(1);
+    headCommit = 'unknown';
   }
+  let report;
+  try {
+    report = runFullAlignment({
+      specPath,
+      testDirs: testDirs || undefined,
+      headCommit,
+      outputPath: outputPath || undefined,
+    });
+  } catch (err) {
+    console.error('check-alignment failed:', err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+  if (jsonMode) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log('Status:', report.alignment_status);
+    console.log('Score:', report.score);
+    console.log('Misaligned:', report.misaligned_tests.length);
+  }
+  // exitCode-style contract (#392 review): never process.exit() right after a
+  // JSON print — buffered stdout must flush. Returning the code and letting the
+  // dispatcher end the turn naturally is what keeps --json output complete.
+  return report.alignment_status === 'PASS' ? 0 : 1;
+}
+
+function runAlignmentViaNpx(runnerPath, specPath, testDirs, outputPath, jsonMode) {
+  // User-supplied paths travel as discrete argv elements routed through
+  // spawnNpx, which refuses any argument carrying a cmd metacharacter before a
+  // shell can see it (#392-#6). The runner script path is a fixed internal path.
+  const argv = [runnerPath, '--spec', specPath];
+  if (testDirs) argv.push('--tests', testDirs[0]);
+  if (outputPath) argv.push('--output', outputPath);
+  if (jsonMode) argv.push('--json');
+  const result = spawnNpx(argv);
+  if (result.error) {
+    console.error('check-alignment: unable to load the alignment engine (tsx unavailable).');
+    console.error(result.error.message);
+    return 1;
+  }
+  return result.status === 0 ? 0 : 1;
 }
 
 async function runAlignmentCheck(subargs) {
@@ -42,32 +154,43 @@ async function runAlignmentCheck(subargs) {
 
   const jsonMode = subargs.includes('--json');
 
-  // Load TS module via tsx
-  const { execSync } = require('child_process');
-  const alignmentPath = path.join(__dirname, '..', 'lib', 'test-alignment.ts');
+  // Injection guard (#392-#6) runs BEFORE any launcher, including the
+  // in-process fast path: a metachar path must be refused identically on both
+  // platforms (Delphi walkthrough R1, MJ-02 — behavioral, not shape-only).
+  for (const value of [specPath, ...(testDirs || []), outputPath].filter(v => v !== undefined)) {
+    const unsafe = firstUnsafeArg([value]);
+    if (unsafe) {
+      console.error(`check-alignment: refusing path containing a shell metacharacter: ${unsafe}`);
+      return 1;
+    }
+  }
+
+  const runnerPath = path.join(__dirname, '..', 'lib', 'check-alignment-runner.cjs');
 
+  // Primary: run the engine in-process via tsx/cjs (fast path, works in-repo
+  // where tsx is a devDependency). Fall back to `npx -y tsx` when tsx is not
+  // resolvable, which happens in the published global install (the package
+  // ships zero runtime deps per the zero-install contract). npx self-provisions
+  // tsx on demand, so the published command stays functional without adding a dep.
+  //
+  // The try guards ONLY the tsx loader's module-load step. The engine call sits
+  // outside it: an engine-level failure is a real bug that must surface, not be
+  // silently swallowed and misattributed to "tsx unavailable" by the fallback.
+  // Delphi walkthrough R2 CI-02: require('../lib/test-alignment.ts') also needs
+  // the loader, so it belongs INSIDE the guard — if the .ts file itself cannot
+  // load, the npx fallback re-attempts it under a provisioned tsx instead of
+  // crashing with an unhandled exception. Engine EXECUTION stays outside.
+  let runFullAlignment;
   try {
-    execSync(`npx tsx -e "
-      import { runFullAlignment } from '${alignmentPath}';
-      const report = runFullAlignment({
-        specPath: '${specPath}',
-        testDirs: ${JSON.stringify(testDirs || null)},
-        headCommit: require('child_process').execSync('git rev-parse HEAD 2>/dev/null || echo unknown').toString().trim(),
-        outputPath: ${outputPath ? `'${outputPath}'` : 'undefined'},
-      });
-      if (${jsonMode}) {
-        console.log(JSON.stringify(report, null, 2));
-      } else {
-        console.log('Status:', report.alignment_status);
-        console.log('Score:', report.score);
-        console.log('Misaligned:', report.misaligned_tests.length);
-      }
-      process.exit(report.alignment_status === 'PASS' ? 0 : 1);
-    "`, { stdio: 'inherit' });
+    require('tsx/cjs');
+    ({ runFullAlignment } = require('../lib/test-alignment.ts'));
   } catch (err) {
-    return 1;
+    if (!err || (err.code !== 'MODULE_NOT_FOUND' && !/Cannot find module/.test(String(err && err.message)))) {
+      throw err;
+    }
+    return runAlignmentViaNpx(runnerPath, specPath, testDirs, outputPath, jsonMode);
   }
-  return 0;
+  return runAlignmentInProcess(specPath, testDirs, outputPath, jsonMode, runFullAlignment);
 }
 
 const COMMANDS = {
@@ -154,7 +277,7 @@ const COMMANDS = {
       }
       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)'
+    usage: 'xp-gate doctor [--fix [--install-tools] | --sync-hooks [--force] | --refresh-env] | --json | --format json  (the two machine-readable modes print one JSON document and refuse --fix/--sync-hooks; --refresh-env is read-only so it combines with them)'
   },
   'ui-review': {
     description: 'Run UI review for non-sprint developers (generates .ui-gate-result.json)',
@@ -188,7 +311,17 @@ const COMMANDS = {
   },
   'check-alignment': {
     description: 'Run test-specification alignment check (deterministic, no LLM)',
-    run: subargs => runAlignmentCheck(subargs).then(code => process.exit(code)),
+    run: subargs => runAlignmentCheck(subargs).then(code => {
+      // exitCode, not process.exit(): the in-process --json document must flush
+      // its buffered stdout before the process ends (#392 review, MJ-01).
+      process.exitCode = code;
+    }).catch(err => {
+      // A quality gate must fail with a deterministic exit code and a real
+      // message — never an unhandled rejection whose code depends on Node's
+      // default mode (Delphi walkthrough R2, MJ-02).
+      console.error('check-alignment: unexpected failure:', err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+    }),
     usage: 'xp-gate check-alignment [--spec <path>] [--tests <dir>] [--json] [--output <path>]'
   },
   'upgrade': {

package/hooks/lib/python-incremental-typecheck.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+
+# Incremental Python type-checking helpers for the pre-commit Python branch
+# (#534). This is the FAST staged-only pass: pre-commit runs it on just the
+# .py/.pyi files that changed, so a large repo doesn't pay full-inference CPU
+# on every commit. It complements the FULL mypy pass (githooks/adapters/
+# python.sh run_static_analysis, reachable via the adapter CLI / CI), which is
+# where cross-module blind spots get caught.
+#
+# Sourced by githooks/pre-commit (the python) case. Requires CHANGED_FILES
+# (space/newline separated, repo-root relative) to be in scope, matching the
+# rest of the inline branch.
+#
+# Shellcheck: functions are the public API used by pre-commit; SC1091 sources
+# are intentionally not resolved here (adapter-common not needed).
+
+# Extract the staged .py/.pyi files from CHANGED_FILES, one per line.
+# Excludes vendored/ignored trees (.venv, venv, node_modules) that a hook
+# should never type-check. Handles whitespace in paths (echo + grep would
+# split them).
+python_staged_py_files() {
+  local f
+  while IFS= read -r f || [ -n "$f" ]; do
+    case "$f" in
+      .venv/*|venv/*|node_modules/*) continue ;;
+      *.py|*.pyi) printf '%s\n' "$f" ;;
+    esac
+  done <<< "$CHANGED_FILES"
+}
+
+# Run incremental mypy over the given staged files, returning mypy's REAL exit
+# code (never a pipe stage's). Adds --follow-imports=silent so that a change to
+# A.py that references an unchanged B.py does not surface B's own pre-existing
+# diagnostics — only caller-level signature errors are reported. Callers must
+# pass the file list as arguments (already filtered to .py/.pyi).
+#
+# Scope discipline (same .xp-gate-mypy-scope contract as python.sh): a staged
+# file OUTSIDE the declared mypy scope is skipped with a note rather than type-
+# checked, keeping the incremental pass consistent with the full pass. Files in
+# scope default to "under src/ or scripts/" when no scope file exists.
+python_typecheck_incremental() {
+  [ "$#" -gt 0 ] || return 0
+
+  # Resolve the declared scope (identical precedence to run_static_analysis):
+  #   .xp-gate-mypy-scope (one target per line) wins; else src/ and scripts/
+  #   are the implicit default. Any staged .py outside this surface is skipped.
+  local -a SCOPE_DIRS=()
+  local _declared=0 line target
+  if [ -f .xp-gate-mypy-scope ]; then
+    while IFS= read -r line || [ -n "$line" ]; do
+      line="${line%%#*}"
+      line="${line#"${line%%[![:space:]]*}"}"
+      line="${line%"${line##*[![:space:]]}"}"
+      [ -z "$line" ] && continue
+      _declared=1
+      # Normalize trailing slashes (`src/` -> `src`) so the `$target/*` prefix
+      # match below never sees a doubled slash (`src//a.py` would never match).
+      line="${line%/}"
+      SCOPE_DIRS+=("$line")
+    done < .xp-gate-mypy-scope
+  else
+    [ -d src ] && SCOPE_DIRS+=(src)
+    [ -d scripts ] && SCOPE_DIRS+=(scripts)
+  fi
+
+  # If a scope file is declared but yields nothing, every staged .py is out of
+  # scope -> SKIP (exit 0), mirroring the full pass.
+  local _in_scope=false
+  local -a TYPECHECK_FILES=()
+  local f
+  if [ "${#SCOPE_DIRS[@]}" -gt 0 ]; then
+    for f in "$@"; do
+      _in_scope=false
+      for target in "${SCOPE_DIRS[@]}"; do
+        case "$f" in
+          "$target"/*) _in_scope=true ;;
+        esac
+        [ "$_in_scope" = true ] && break
+      done
+      if [ "$_in_scope" = true ]; then
+        TYPECHECK_FILES+=("$f")
+      else
+        echo "  ℹ️  mypy incremental: '$f' is outside declared scope — skipped"
+      fi
+    done
+  fi
+
+  [ "${#TYPECHECK_FILES[@]}" -gt 0 ] || return 0
+
+  # Capture mypy's exit code directly. A pipeline like
+  #   mypy ... | head -20 | tail -10; rc=$?
+  # loses mypy's real status (the pipe stage's rc is used instead), which made
+  # the gate pass silently on real type errors. Redirect to a temp file, take
+  # mypy's own exit code, then print a truncated view.
+  local tmp
+  tmp="$(mktemp)"
+  echo "Running mypy type checking (incremental)..."
+  mypy --follow-imports=silent --ignore-missing-imports "${TYPECHECK_FILES[@]}" > "$tmp" 2>&1
+  local _mypy_rc=$?
+  head -20 "$tmp"
+  tail -10 "$tmp"
+  rm -f "$tmp"
+  return "$_mypy_rc"
+}

package/hooks/lib/typecheck.sh

@@ -3,6 +3,16 @@
 # Gate 1 TypeScript static analysis — the single place that decides HOW a project
 # is type-checked (#436).
 #
+# NOT incremental (deliberately, #534): TypeScript type-checking cannot be
+# reduced to "staged files only". `tsc` has no single-file check mode — it must
+# resolve the whole module graph to report a file's real type errors, so
+# type-checking only the changed files would silently miss "changing B.ts breaks
+# an unchanged caller in A.ts". Pre-commit therefore runs the project's full
+# typecheck (`npm run typecheck` / `npx tsc --noEmit`) every commit. This is the
+# CORRECTNESS-preserving exception to xp-gate's incremental rule: lint (ESLint /
+# Biome) IS incremental (staged files / --staged), but type-check stays full
+# because incremental type-checking would be wrong, not just slower.
+#
 # Before this file, `githooks/pre-commit` and `githooks/adapters/typescript.sh` each
 # hardcoded `npx tsc --noEmit`. Plain tsc cannot resolve `.vue` single-file
 # components, so every `import X from './Foo.vue'` became a TS2307 and a Vue project

package/hooks/pre-commit

@@ -179,11 +179,15 @@ run_in_subdir() {
   
   if [ -n "$PROJECT_SUBDIR" ] && [ "$PROJECT_SUBDIR" != "." ]; then
     # Run command in subdirectory, then return to original directory
-    pushd "$PROJECT_SUBDIR" > /dev/null 2>&1
-    eval "$cmd"
-    local exit_code=$?
-    popd > /dev/null 2>&1
-    return $exit_code
+    # #392-#10: guard cd/pushd so a missing directory cannot run the gate in
+    # the wrong cwd.
+    if pushd "$PROJECT_SUBDIR" > /dev/null 2>&1; then
+      eval "$cmd"
+      local exit_code=$?
+      popd > /dev/null 2>&1
+      return $exit_code
+    fi
+    return 1
   else
     # Run in current directory
     eval "$cmd"
@@ -235,6 +239,11 @@ source "${AUDIT_SCRIPT_DIR}/lib/coverage-total.sh"
 # unit-testable without executing this hook.
 source "${AUDIT_SCRIPT_DIR}/lib/python-test-selection.sh"
 
+# Issue #534: incremental Python type-check for the pre-commit python branch —
+# staged-only mypy (fast) that complements python.sh's CI-aligned full pass.
+# Kept in a library so the exit-code capture and scope handling are unit-testable.
+source "${AUDIT_SCRIPT_DIR}/lib/python-incremental-typecheck.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")
 
@@ -979,10 +988,14 @@ IN_PROJECT_SUBDIR=0
 _lang_count=$(echo "$PROJECT_LANGS" | wc -w)
 if [ -n "$PROJECT_SUBDIR" ] && [ "$PROJECT_SUBDIR" != "." ] && [ "$PROJECT_LANG" != "documentation-only" ] && [ "$_lang_count" -le 1 ]; then
   ORIGINAL_DIR=$(pwd)
-  cd "$PROJECT_SUBDIR"
-  IN_PROJECT_SUBDIR=1
-  echo "Working in: $PROJECT_SUBDIR/"
-  echo ""
+  # #392-#10: guard cd so a missing subdir cannot run gates in the wrong cwd.
+  if cd "$PROJECT_SUBDIR" 2>/dev/null; then
+    IN_PROJECT_SUBDIR=1
+    echo "Working in: $PROJECT_SUBDIR/"
+    echo ""
+  else
+    echo "WARN: could not enter $PROJECT_SUBDIR — continuing at repo root" >&2
+  fi
 fi
 
 # ============================================================================
@@ -1308,24 +1321,38 @@ else
       fi
     fi
     
-    # Optional: Type checking with mypy
+    # Optional: Type checking with mypy — INCREMENTAL (fast, staged-only).
+    #
+    # Responsibility boundary (#534):
+    #   * This branch (python case) runs mypy ONLY over the staged .py/.pyi
+    #     files via python_typecheck_incremental — seconds, not a full inference
+    #     pass. Uses --follow-imports=silent so a change to A.py that references
+    #     an unchanged B.py does NOT surface B's pre-existing diagnostics; only
+    #     caller-level signature errors still block. Its exit code is captured
+    #     directly (temp file), which is deterministic and does not depend on
+    #     set -o pipefail (the old `... | head | tail; rc=$?` worked only under
+    #     pipefail and could drop mypy's status when the pattern is copied into
+    #     a non-pipefail context).
+    #   * The FULL mypy pass lives OUTSIDE this hook: run_static_analysis()
+    #     (githooks/adapters/python.sh) is reachable via the adapter CLI and the
+    #     general adapter route, and CI installs mypy (quality-gates.yml) for
+    #     typed projects. NOTE: the pre-commit python case is fully inline and
+    #     never routes to run_static_analysis — so the incremental blind spot
+    #     (cross-module signature break on an unchanged file) is the accepted
+    #     trade-off here, backstopped by full mypy wherever that surface runs.
+    #     Both paths coexist: this one is the fast pre-commit pass.
     if command -v mypy &> /dev/null; then
+      # Collect staged .py/.pyi via the helper (whitespace-safe, bash-3
+      # compatible — macOS default bash is 3.2, so avoid mapfile).
       MYPY_ARGS=()
       while IFS= read -r staged_file; do
-        case "$staged_file" in
-          *.py|*.pyi) MYPY_ARGS+=("$staged_file") ;;
-        esac
-      done <<< "$CHANGED_FILES"
-      if [ "${#MYPY_ARGS[@]}" -eq 0 ]; then
-        MYPY_EXIT=0
-      else
-        echo "Running mypy type checking (optional)..."
-        mypy --ignore-missing-imports "${MYPY_ARGS[@]}" 2>&1 | head -20 | tail -10
-        MYPY_EXIT=$?
-      fi
+        MYPY_ARGS+=("$staged_file")
+      done < <(python_staged_py_files)
+      python_typecheck_incremental "${MYPY_ARGS[@]}"
+      MYPY_EXIT=$?
       if [ "$MYPY_EXIT" -ne 0 ]; then
         echo ""
-        echo "❌ BLOCKED - MYPI TYPE ERRORS detected"
+        echo "❌ BLOCKED - MYPY TYPE ERRORS detected"
         echo "Fix the type errors above before committing."
         exit 1
       fi
@@ -1342,16 +1369,32 @@ else
     echo "ℹ️  golangci-lint not available — skipping Go linting"
     echo "⏭️  SKIPPED - Code quality (golangci-lint not available)"
   else
-    echo "Running golangci-lint (comprehensive static analysis)..."
-    golangci-lint run 2>&1 | head -30
-    GOLANGCI_EXIT=$?
-    if [ "$GOLANGCI_EXIT" -ne 0 ]; then
-      echo ""
-      echo "❌ BLOCKED - GOLANGCI-LINT ERRORS detected"
-      echo "Fix the lint errors above before committing."
-      exit 1
+    # #534: run golangci-lint over ONLY the staged .go files (incremental),
+    # not the whole repo. `golangci-lint run` with no args scans every package
+    # and dominates pre-commit time on large Go repos. golangci-lint accepts
+    # explicit file targets. No staged .go files -> SKIP (nothing to lint).
+    GO_FILES=$(echo "$CHANGED_FILES" | grep '\.go$' || true)
+    if [ -z "$GO_FILES" ]; then
+      echo "✅ PASSED - No staged Go files to lint."
+    else
+      echo "Running golangci-lint (incremental, staged .go)..."
+      # #534: capture golangci-lint's REAL exit code via a temp file, not a
+      # pipe stage's (`... | head -30; rc=$?` would take head's status; it only
+      # works because of set -o pipefail, which is fragile and inconsistent with
+      # the python incremental helper's temp-file pattern).
+      GO_TMP=$(mktemp)
+      golangci-lint run $GO_FILES > "$GO_TMP" 2>&1
+      GOLANGCI_EXIT=$?
+      head -30 "$GO_TMP"
+      rm -f "$GO_TMP"
+      if [ "$GOLANGCI_EXIT" -ne 0 ]; then
+        echo ""
+        echo "❌ BLOCKED - GOLANGCI-LINT ERRORS detected"
+        echo "Fix the lint errors above before committing."
+        exit 1
+      fi
+      echo "✅ PASSED - golangci-lint."
     fi
-    echo "✅ PASSED - golangci-lint."
   fi
     ;;
     
@@ -1604,7 +1647,16 @@ else
   echo "Running jscpd for Go duplicate code detection..."
   FILES_TO_CHECK=$(echo "$CHANGED_FILES" | grep "\.go$" | head -20)
   if [ -n "$FILES_TO_CHECK" ]; then
-    jscpd $FILES_TO_CHECK 2>&1 | head -10
+    # #392-#9: capture jscpd's real exit code via temp file instead of piping
+    # through head (which would swallow the exit status under pipefail analysis).
+    GO_JSCPD_TMP=$(mktemp)
+    jscpd $FILES_TO_CHECK > "$GO_JSCPD_TMP" 2>&1
+    JSCPD_GO_EXIT=$?
+    head -10 "$GO_JSCPD_TMP"
+    rm -f "$GO_JSCPD_TMP"
+    if [ "$JSCPD_GO_EXIT" -ne 0 ]; then
+      echo "⚠️  jscpd (Go) exited with code $JSCPD_GO_EXIT"
+    fi
   fi
   echo "✅ PASSED - Go duplicate code check completed."
     ;;

package/lib/__tests__/check-alignment-cli.test.mjs

@@ -0,0 +1,77 @@
+/**
+ * @test check-alignment CLI
+ * @intent Guard the #392-#6 injection fix and the zero-install fallback path:
+ *         (1) no spawn/exec call in bin/xp-gate.js may enable a shell (which on
+ *         win32 would let cmd.exe interpret metacharacters embedded in
+ *         user-supplied paths); (2) the published runner emits a complete,
+ *         parseable --json document instead of truncating it on process.exit().
+ * @covers AC-392-06 (injection), zero-install contract (fallback)
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const BIN = join(here, '..', '..', 'bin', 'xp-gate.js');
+const RUNNER = join(here, '..', 'check-alignment-runner.cjs');
+
+describe('check-alignment CLI injection surface (#392-#6)', () => {
+  it('bin/xp-gate.js rejects shell metacharacters before any launch', () => {
+    const src = readFileSync(BIN, 'utf8');
+    // The injection guard must be in front of every subprocess launch: any
+    // argument carrying a cmd.exe metacharacter is refused outright, never
+    // escaped, before a shell can see it (#392-#6, Delphi R1-C). This holds on
+    // both platforms -- on win32 a .cmd wrapper needs cmd.exe (EINVAL without
+    // one), so the metachar guard is the only thing that makes shelling safe.
+    expect(src).toMatch(/CMD_METACHAR_RE/);
+    expect(src).toMatch(/firstUnsafeArg/);
+    // The metachar class must cover the cmd.exe separators/redirection.
+    expect(src).toMatch(/CMD_METACHAR_RE\s*=.*[&|^<>%!]/);
+    // Any shell a launcher may engage must be gated on the metachar rejection
+    // having run first, and never enabled unconditionally on win32. The single
+    // sanctioned engagement is the named SHELL_ON_WINDOWS_ONLY constant.
+    expect(src).not.toMatch(/shell\s*:\s*(?:true|process\.platform)/);
+    expect(src).toMatch(/shell:\s*SHELL_ON_WINDOWS_ONLY/);
+    // execSync interpolates argv into a command string via a shell, so it is
+    // banned; execFileSync is fine only for hardcoded binaries with non-user
+    // argv (git rev-parse HEAD). The launchers below are the user-input path.
+    expect(src).not.toMatch(/\bexecSync\s*\(/);
+  });
+
+  it('a metacharacter path is refused end to end before any launch (MJ-02)', () => {
+    // Behavioral, not shape: invoke the real CLI with a --spec whose path
+    // carries a cmd metacharacter and assert the documented refusal — exit 1
+    // plus the "refusing" message, never a spawned engine.
+    const evil = join(here, 'evil&echo.spec.yaml');
+    const result = spawnSync(process.execPath, [BIN, 'check-alignment', '--spec', evil, '--json'], {
+      encoding: 'utf8',
+      timeout: 60000,
+    });
+    expect(result.status).toBe(1);
+    expect(`${result.stderr}${result.stdout}`).toMatch(/metacharacter|refus/i);
+  }, 90000);
+});
+
+describe('check-alignment runner output integrity', () => {
+  it('emits a complete parseable JSON document with --json', () => {
+    const spec = join(here, 'test-alignment.test.ts');
+    const result = spawnSync(process.execPath, [RUNNER, '--spec', spec, '--json'], {
+      encoding: 'utf8',
+    });
+    expect(result.error).toBeUndefined();
+    // The whole stdout stream must be one valid JSON document. A process.exit()
+    // immediately after console.log would truncate it on some platforms.
+    const parsed = JSON.parse(result.stdout);
+    expect(parsed).toHaveProperty('alignment_status');
+    expect(parsed).toHaveProperty('score');
+    expect(parsed).toHaveProperty('head_commit');
+  });
+
+  it('fails fast with exit code 1 when --spec is missing', () => {
+    const result = spawnSync(process.execPath, [RUNNER], { encoding: 'utf8' });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('--spec <path> is required');
+  });
+});