@boyingliu01/xp-gate 0.30.1 → 0.30.3

package/lib/__tests__/retro-gate-m.test.js

@@ -0,0 +1,144 @@
+/**
+ * @test REQ-404 Gate M in retrospective
+ * @intent Verify `xp-gate retro` reports Gate M (mutation) evidence from the
+ *         pre-push journal, and that it distinguishes "never measured" from
+ *         "measured and scored well" instead of printing a healthy average over
+ *         an empty sample (#404 P1-3).
+ *
+ * @covers AC-404
+ */
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const { handleRetro } = require('../retro');
+
+let TMP_DIR;
+let cwdSpy;
+
+beforeAll(() => {
+  TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'retro-gatem-test-'));
+  cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(TMP_DIR);
+});
+
+afterAll(() => {
+  cwdSpy.mockRestore();
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+function cleanDir() {
+  for (const sub of ['.xp-gate', '.sprint-state', 'coverage']) {
+    fs.rmSync(path.join(TMP_DIR, sub), { recursive: true, force: true });
+  }
+  fs.rmSync(path.join(TMP_DIR, '.quality-history.jsonl'), { force: true });
+}
+
+/** Write pre-push journals. `runs` is a list of Gate M detail objects. */
+function writeJournals(runs) {
+  const dir = path.join(TMP_DIR, '.xp-gate', 'reports', 'pre-push');
+  fs.mkdirSync(dir, { recursive: true });
+  runs.forEach((gateM, i) => {
+    const stamp = `2026-10-${String(10 + i).padStart(2, '0')}T00:00:00Z`;
+    fs.writeFileSync(
+      path.join(dir, `${stamp.replace(/[:]/g, '-')}.json`),
+      JSON.stringify({
+        timestamp: stamp,
+        trigger: 'pre-push',
+        branch: 'main',
+        commit: `sha${i}`,
+        changed_files: ['src/a.ts'],
+        overall: gateM.status,
+        gates: [{ id: 'M', name: 'Mutation Testing', status: gateM.status, details: gateM.details || {} }],
+        warnings: [],
+        errors: [],
+      })
+    );
+  });
+}
+
+async function runRetro(args = ['--days', '30']) {
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  const code = await handleRetro(args);
+  const output = logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+  logSpy.mockRestore();
+  return { code, output };
+}
+
+describe('retro - Gate M evidence (#404)', () => {
+  test('reports skip rate, measured duration and score distribution', async () => {
+    cleanDir();
+    writeJournals([
+      { status: 'PASS', details: { duration_ms: '120000', mutation_score: '75.5', skip_reason: '' } },
+      { status: 'PASS', details: { duration_ms: '180000', mutation_score: '82.1', skip_reason: '' } },
+      { status: 'SKIP', details: { skip_reason: 'stryker_not_installed' } },
+      { status: 'SKIP', details: { skip_reason: 'no_mutable_files' } },
+    ]);
+
+    const { code, output } = await runRetro();
+    expect(code).toBe(0);
+    expect(output).toContain('Gate M');
+    // 2 of 4 skipped
+    expect(output).toContain('50.0%');
+    // Both skip reasons must survive into the report, not be collapsed.
+    expect(output).toContain('stryker_not_installed');
+    expect(output).toContain('no_mutable_files');
+    // score median of [75.5, 82.1] is 82.1 with this sort convention; assert the
+    // scores are present rather than pinning the exact tie-break.
+    expect(output).toMatch(/75\.5|82\.1/);
+  });
+
+  test('says "never measured" rather than reporting a clean 0% average', async () => {
+    cleanDir();
+    // The exact shape of all 68 journals before the #404 fix: SKIP with an empty
+    // details object. An average over zero samples is not a healthy score.
+    writeJournals([
+      { status: 'SKIP', details: {} },
+      { status: 'SKIP', details: {} },
+    ]);
+
+    const { code, output } = await runRetro();
+    expect(code).toBe(0);
+    expect(output).toContain('Gate M');
+    expect(output).toMatch(/no measured|never measured|not measured/i);
+    // A fabricated average over an empty sample is the failure being prevented.
+    expect(output).not.toMatch(/median mutation score.*\d+\.\d+%/i);
+  });
+
+  test('reports no Gate M data at all when there are no journals', async () => {
+    cleanDir();
+    const { code, output } = await runRetro();
+    expect(code).toBe(0);
+    expect(output).toMatch(/no pre-push|no Gate M/i);
+  });
+
+  test('counts a TIMEOUT separately from a SKIP', async () => {
+    cleanDir();
+    writeJournals([
+      { status: 'TIMEOUT', details: { skip_reason: 'exceeded_budget' } },
+      { status: 'SKIP', details: { skip_reason: 'no_mutable_files' } },
+    ]);
+
+    const { output } = await runRetro();
+    // Timeouts are a distinct failure mode: lumping them into SKIP hides a
+    // gate that started work and could not finish.
+    expect(output).toMatch(/TIMEOUT|timeout/i);
+  });
+
+  test('counts BLOCKED, which is the spelling the journals actually write', async () => {
+    cleanDir();
+    // Measured against this repo's real journals: 62 SKIP, 5 BLOCKED, 1 PASS.
+    // An implementation that only matched "BLOCK" reported the 5 real mutation
+    // blocks as zero -- precisely the silent-success failure #404 is about.
+    writeJournals([
+      { status: 'BLOCKED', details: { skip_reason: 'mutation_score_below_threshold' } },
+      { status: 'BLOCKED', details: {} },
+      { status: 'SKIP', details: { skip_reason: 'no_mutable_files' } },
+      { status: 'PASS', details: { mutation_score: '71.0' } },
+    ]);
+
+    const { output } = await runRetro();
+    expect(output).toContain('BLOCK 2');
+    expect(output).toContain('SKIP 1');
+    expect(output).toContain('PASS 1');
+  });
+});

package/lib/coverage-total.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Gate 5's Python coverage parsing and threshold verdict (#523).
+#
+# Sourced by githooks/pre-commit; kept in its own file so the contract is
+# unit-testable without executing the hook
+# (githooks/__tests__/issue-523-python-coverage-parse.test.bats).
+#
+# The defect this file exists for: `coverage report --format=total` prints a
+# BARE number ("97"), but the hook piped it through `grep -o '[0-9]*%'` — a
+# pattern that requires a literal percent sign — so COVERAGE_PERCENT was always
+# empty and the 80% threshold branch never executed. The gate answered "Could
+# not determine" forever: a silent no-op, not a verdict.
+
+# Parse the raw output of `coverage report --format=total` (stdin) and echo the
+# integer total percentage — or nothing when the input carries no number.
+#
+# coverage.py 7.x --format=total prints a bare number; other tools (and older
+# forms) append a percent sign. Only a line that IS a bare number (optionally
+# %-suffixed) is accepted — a line that merely CONTAINS a number ("WARNING: 2
+# files skipped") must not be mistaken for the total, so the whole line is
+# matched, not the first token. A decimal part is truncated (floor — the
+# conservative direction for a threshold gate, the same convention as the Java
+# path's ${VAR%.*}). Inputs without any bare-number line (empty, "No data to
+# report.", warnings) produce NO output so the caller takes its
+# cannot-determine path: a wrong number is worse than none.
+parse_coverage_total() {
+  awk '
+    {
+      line = $0
+      sub(/%$/, "", line)
+      gsub(/^[ \t]+|[ \t]+$/, "", line)
+      if (line ~ /^[0-9]+(\.[0-9]+)?$/) {
+        sub(/\.[0-9]+$/, "", line)
+        print line
+        exit
+      }
+    }
+  '
+}
+
+# Gate 5 Stage 2 Python coverage enforcement — the hook's python case body,
+# extracted so the mock-PATH test exercises the real control flow. Echoes the
+# verdict lines and returns 1 on BLOCK (the caller turns that into `exit 1`).
+#
+# COVERAGE_PERCENT is deliberately NOT declared local: the hook's quality
+# 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
+  fi
+
+  COVERAGE_PERCENT=""
+  if [ -f ".coverage" ]; then
+    COVERAGE_PERCENT=$(coverage report --format=total 2>/dev/null | parse_coverage_total) || true
+  fi
+  if [ -z "$COVERAGE_PERCENT" ] && [ -f "coverage/.coverage" ]; then
+    COVERAGE_PERCENT=$(coverage report --format=total -i coverage 2>/dev/null | parse_coverage_total) || true
+  fi
+
+  if [ -n "$COVERAGE_PERCENT" ]; then
+    if [ "$COVERAGE_PERCENT" -lt "${COVERAGE_THRESHOLD:-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
+    echo "Python coverage: ${COVERAGE_PERCENT}% ✅ (≥ 80%)"
+  else
+    echo "⚠️  Could not determine Python coverage percentage. Ensure pytest-cov or coverage.py data exists."
+  fi
+  return 0
+}

package/lib/crap-cli.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * `xp-gate crap` — advisory CRAP hotspot ranking (#404 P1-2).
+ *
+ * Prints the functions whose CRAP score is at or above the bar, worst first.
+ * This is a NAVIGATION aid: it exits 0 whatever it finds, because the indicator
+ * depends on coverage that 21.8% of this repo's source files do not have (see
+ * crap.js). A ranking that cannot measure a fifth of its population must not
+ * be allowed to fail a build.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const {
+  buildCrapReport,
+  joinCoverage,
+  readFileCoverage,
+  parseLizardCsv,
+} = require('./crap.js');
+
+const USAGE = `Usage: xp-gate crap [options]
+
+Rank functions by CRAP score = CCN^2 * (1 - coverage) + CCN, worst first.
+ADVISORY ONLY: never blocks, always exits 0.
+
+Options:
+  --top N            show at most N hotspots (default 20)
+  --threshold N      CRAP bar; functions at or above it are listed (default 6)
+  --json             machine-readable output
+  --coverage <file>  istanbul coverage-final.json (default coverage/coverage-final.json)
+  --paths <p...>     directories to scan (default src)
+  --include-mirrors  also rank src/npm-package/** (overwritten at publish)
+  -h, --help         show this help
+
+Unmeasured = the function's file was never loaded by any test, so coverage is
+unknown. Those functions are counted, not scored. Treating them as 0% would put
+every untested file at the top of the ranking; treating them as 100% would hide
+them.
+`;
+
+function parseArgs(argv) {
+  const opts = {
+    top: 20,
+    threshold: 6,
+    json: false,
+    coverage: path.join(process.cwd(), 'coverage', 'coverage-final.json'),
+    paths: ['src'],
+    includeMirrors: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--top':
+        opts.top = Number(argv[++i]);
+        break;
+      case '--threshold':
+        opts.threshold = Number(argv[++i]);
+        break;
+      case '--json':
+        opts.json = true;
+        break;
+      case '--coverage':
+        opts.coverage = argv[++i];
+        break;
+      case '--include-mirrors':
+        opts.includeMirrors = true;
+        break;
+      case '--paths': {
+        opts.paths = [];
+        while (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+          opts.paths.push(argv[++i]);
+        }
+        break;
+      }
+      case '-h':
+      case '--help':
+        opts.help = true;
+        break;
+      default:
+        break;
+    }
+  }
+  return opts;
+}
+
+/** Run lizard and return its CSV. Missing lizard is not an error for a
+ *  navigation command: the caller reports that it could not measure. */
+function runLizard(paths) {
+  try {
+    return execFileSync('lizard', ['--csv', '-C', '99999', ...paths], {
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (err) {
+    // lizard exits non-zero when it cannot scan everything; its stdout is still
+    // usable. Anything else (ENOENT) means no data at all.
+    if (err && typeof err.stdout === 'string' && err.stdout.length) return err.stdout;
+    return null;
+  }
+}
+
+function formatRow(hotspot) {
+  const crap = hotspot.crap.toFixed(1).padStart(8);
+  const ccn = String(hotspot.ccn).padStart(4);
+  const cov = `${Math.round(hotspot.cov * 100)}%`.padStart(4);
+  return `  ${crap}  CCN ${ccn}  cov ${cov}  ${hotspot.file}  ${hotspot.name}`;
+}
+
+function render(report, opts) {
+  const lines = [];
+  lines.push('━━━ CRAP hotspot ranking (advisory, never blocks) ━━━');
+
+  if (!report.measured && !report.unmeasured) {
+    lines.push('');
+    lines.push('No functions found. Check that lizard is installed and --paths points at real code:');
+    lines.push(`  lizard --csv -C 99999 ${opts.paths.join(' ')}`);
+    return lines.join('\n');
+  }
+
+  lines.push('');
+  lines.push(
+    `measured ${report.measured} functions, ${report.unmeasured} unmeasured (no coverage for their file)`
+  );
+  lines.push(`CRAP >= ${report.threshold}: ${report.hotspots.length} shown`);
+
+  if (!report.hotspots.length) {
+    lines.push('');
+    lines.push(`✅ Nothing at or above CRAP ${report.threshold}.`);
+    return lines.join('\n');
+  }
+
+  lines.push('');
+  lines.push('  CRAP      complexity coverage  location');
+  const dash = '  ' + '─'.repeat(74);
+  lines.push(dash);
+  for (const hotspot of report.hotspots) lines.push(formatRow(hotspot));
+  lines.push(dash);
+  lines.push('');
+  lines.push('Navigation aid: pick from the top. This does not replace security,');
+  lines.push('performance or architecture review, and score-chasing is not a goal.');
+  return lines.join('\n');
+}
+
+async function handleCrap(argv) {
+  const opts = parseArgs(argv);
+
+  if (opts.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const csv = runLizard(opts.paths);
+  if (csv === null) {
+    console.error('✗ Could not run lizard. Install it with: pip install --user lizard');
+    return 1;
+  }
+
+  if (!fs.existsSync(opts.coverage)) {
+    console.error(`✗ No coverage artifact at ${opts.coverage}`);
+    console.error('  Run the test suite with coverage first: npx vitest run --coverage');
+    console.error('  (Without it every function is unmeasured, which is not a ranking.)');
+    return 1;
+  }
+
+  const functions = parseLizardCsv(csv);
+  const coverage = readFileCoverage(opts.coverage);
+  const joined = joinCoverage(functions, coverage);
+
+  const report = buildCrapReport(joined, {
+    threshold: opts.threshold,
+    top: opts.top,
+    mirrors: opts.includeMirrors,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  console.log(render(report, opts));
+  // Advisory by construction: the ranking never changes the exit code.
+  return 0;
+}
+
+module.exports = { handleCrap, parseArgs, render, runLizard };

package/lib/crap.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * CRAP advisory ranking (#404 P1-2).
+ *
+ * CRAP(m) = comp(m)^2 * (1 - cov(m)) + comp(m)
+ *
+ * Uncle Bob's combined signal: complexity is only half the story, because a
+ * gnarly function with dense tests is cheap to change while a simple one with
+ * none is not. This module produces a RANKING for navigation. It is explicitly
+ * not a gate -- see README/issue #404 for why.
+ *
+ * Three constraints came out of measuring the indicator on this repo before
+ * writing it, each of which changes the design:
+ *
+ *  1. Coverage is per FILE in the artifact the gates already produce
+ *     (coverage-final.json). Function-level positions could not be joined to
+ *     lizard's reliably (8.4% match rate measured), so cov(m) here is the
+ *     enclosing file's coverage. That over-smooths within a file; it is
+ *     acceptable for ranking and not acceptable for a pass/fail verdict.
+ *
+ *  2. 21.8% of non-mirror source files are never loaded by any test and so have
+ *     no coverage at all. Treating those as 0% would push every untested file to
+ *     the top of the ranking purely for being unmeasured; treating them as 100%
+ *     would hide them. They are reported separately as `unmeasured`.
+ *
+ *  3. src/npm-package/** is a generated mirror (canonical source is
+ *     plugins/* / the repo root) and is overwritten at publish. Ranking it would
+ *     direct refactoring at a file that does not survive. Excluded by default.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Repository-relative paths whose canonical source lives elsewhere. */
+const MIRROR_PREFIXES = ['src/npm-package/'];
+
+function isMirrorPath(filePath) {
+  if (!filePath) return false;
+  const normalized = String(filePath).split('\\').join('/').replace(/^\.\//, '');
+  return MIRROR_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+/**
+ * CRAP for one function.
+ *
+ * @param {number} comp cyclomatic complexity
+ * @param {number|null} cov coverage ratio in [0,1], or null when unmeasured
+ * @returns {number|null} null when coverage is unknown -- deliberately NOT a
+ *   number, so an unmeasured function cannot be ranked at all
+ */
+function computeCrap(comp, cov) {
+  if (cov === null || cov === undefined || Number.isNaN(cov)) return null;
+  if (!Number.isFinite(comp)) return null;
+
+  // Out-of-range coverage does occur in real istanbul output (a file counted at
+  // >100% after source-map folding). Clamping keeps the score monotonic and
+  // never negative, which a negative CRAP would violate by sorting below honest
+  // clean functions.
+  const clamped = Math.min(1, Math.max(0, cov));
+  return comp * comp * (1 - clamped) + comp;
+}
+
+/** Normalise a path to the repo-relative form used by the coverage artifact. */
+function toRepoRelative(filePath) {
+  return String(filePath).split('\\').join('/').replace(/^\.\//, '');
+}
+
+/**
+ * Attach each function's file coverage and CRAP score.
+ *
+ * @param {Array<{file:string,name:string,ccn:number}>} functions
+ * @param {Map<string, number>} coverage repo-relative path -> ratio
+ * @returns {Array<object>} each with `cov` and `crap` (either may be null)
+ */
+function joinCoverage(functions, coverage) {
+  return functions.map((fn) => {
+    const key = toRepoRelative(fn.file);
+    const cov = coverage instanceof Map ? coverage.get(key) : undefined;
+    const known = cov === undefined ? null : cov;
+    return { ...fn, file: key, cov: known, crap: computeCrap(fn.ccn, known) };
+  });
+}
+
+/**
+ * Build the advisory report.
+ *
+ * @param {Array<object>} functions joined functions (may carry null cov)
+ * @param {{threshold?: number, top?: number, mirrors?: boolean}} options
+ *   `mirrors: true` also ranks the generated mirror tree; default false.
+ */
+function buildCrapReport(functions, options = {}) {
+  const threshold = Number.isFinite(options.threshold) ? options.threshold : 6;
+  const excludeMirrors = options.mirrors !== true;
+
+  const scored = [];
+  let unmeasured = 0;
+
+  for (const fn of functions) {
+    if (excludeMirrors && isMirrorPath(fn.file)) continue;
+
+    if (fn.cov === null || fn.cov === undefined) {
+      unmeasured += 1;
+      continue;
+    }
+    const crap = fn.crap === null || fn.crap === undefined ? computeCrap(fn.ccn, fn.cov) : fn.crap;
+    if (crap === null) {
+      unmeasured += 1;
+      continue;
+    }
+    scored.push({ ...fn, crap });
+  }
+
+  scored.sort((a, b) => b.crap - a.crap || a.file.localeCompare(b.file));
+
+  const hotspots = scored.filter((s) => s.crap >= threshold);
+  const limited = Number.isFinite(options.top) && options.top >= 0 ? hotspots.slice(0, options.top) : hotspots;
+
+  return {
+    hotspots: limited,
+    measured: scored.length,
+    unmeasured,
+    threshold,
+    advisory: true,
+    blocking: false,
+  };
+}
+
+/**
+ * Read per-file coverage ratios out of an istanbul coverage-final.json.
+ * Missing or unreadable input yields an empty map, which surfaces as "every
+ * function unmeasured" rather than as a silently perfect score.
+ */
+function readFileCoverage(coverageFile) {
+  const coverage = new Map();
+  let raw;
+  try {
+    raw = fs.readFileSync(coverageFile, 'utf8');
+  } catch {
+    return coverage;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return coverage;
+  }
+
+  const root = process.cwd();
+  for (const [absPath, entry] of Object.entries(parsed)) {
+    if (!entry || !entry.s) continue;
+    const counts = Object.values(entry.s);
+    if (!counts.length) continue;
+    const covered = counts.filter((c) => c > 0).length;
+    const rel = path.isAbsolute(absPath)
+      ? toRepoRelative(path.relative(root, absPath))
+      : toRepoRelative(absPath);
+    coverage.set(rel, covered / counts.length);
+  }
+  return coverage;
+}
+
+/**
+ * Parse lizard's CSV into functions with a repo-relative file and a CCN.
+ * Column order: NLOC,CCN,token,PARAM,length,location,file,name,signature,...
+ */
+function parseLizardCsv(csvText) {
+  const functions = [];
+  for (const line of String(csvText || '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const cells = line.match(/("([^"]|"")*"|[^,]*)(,|$)/g);
+    if (!cells || cells.length < 8) continue;
+    const clean = (i) => cells[i].replace(/,$/, '').replace(/^"|"$/g, '');
+
+    const ccn = Number(clean(1));
+    if (!Number.isFinite(ccn)) continue; // header row
+
+    functions.push({
+      file: toRepoRelative(clean(6)),
+      name: clean(7),
+      ccn,
+    });
+  }
+  return functions;
+}
+
+module.exports = {
+  computeCrap,
+  joinCoverage,
+  buildCrapReport,
+  isMirrorPath,
+  readFileCoverage,
+  parseLizardCsv,
+  MIRROR_PREFIXES,
+};

package/lib/doctor.js

@@ -18,6 +18,14 @@ const { GATE_CLI_TOOLS, checkCliTool, getToolInstallCmd, checkBash } = require('
 // #505: the single source of truth for module resolution order. The hook reads a
 // generated shell projection of this same module.
 const { RESOLUTION_ORDER } = require('./hook-module-resolution.js');
+const { inspectHookFile } = require('./hook-health.js');
+
+/**
+ * Files above this size get a `bash -n` probe in addition to the CRLF scan.
+ * Real xp-gate hooks are 40 KB (pre-push) to 190 KB (pre-commit); test fixtures
+ * and stubs are a few hundred bytes. 4 KB separates them comfortably.
+ */
+const PARSE_CHECK_MIN_BYTES = 4096;
 const {
   diagnoseTuiRegistration, diagnoseInstalledSkills,
   fixTuiRegistration, ensureTuiRegistration, readTuiJson,
@@ -1256,10 +1264,46 @@ function checkSingleHook(hooksDir, name, signature, label, checks) {
     checks.push({ name: `${label}: ${name}`, status: 'FAIL', detail: 'Missing or not xp-gate' });
     return 1;
   }
+  // Existence and signature are not enough (#546): a hook rewritten with CRLF
+  // line endings, or truncated mid-write, satisfies both and still cannot run.
+  // Reporting it as healthy is worse than reporting nothing, because the
+  // operator stops looking.
+  //
+  // The CRLF scan is pure and cheap; the `bash -n` probe spawns a process, so it
+  // is skipped for files under the size floor below — test fixtures and stub
+  // hooks are not the things that break here, and spawning bash per stub made
+  // doctor slower than its own test timeout.
+  const health = inspectHookFile(hookPath, { parseCheck: shouldParseCheck(hookPath) });
+  if (!health.ok) {
+    checks.push({
+      name: `${label}: ${name}`,
+      status: 'FAIL',
+      detail: health.problems.join('; '),
+    });
+    return 1;
+  }
   checks.push({ name: `${label}: ${name}`, status: 'PASS', detail: hookPath });
   return 0;
 }
 
+/**
+ * Should the `bash -n` probe run for this hook?
+ *
+ * Measured on a real install: a 190 KB pre-commit takes ~90 ms to parse, but a
+ * dozen stubs in a test fixture still add up to seconds of process spawns. The
+ * CRLF scan catches the #546 failure without spawning anything, so the probe is
+ * reserved for files large enough to be a real hook.
+ * @param {string} hookPath - Hook path
+ * @returns {boolean} Whether to run the parse check
+ */
+function shouldParseCheck(hookPath) {
+  try {
+    return fs.statSync(hookPath).size > PARSE_CHECK_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Expected gate scripts that should be present in the adapters directory.
  * gate-5.sh and gate-6.sh are inline in pre-commit, so they are NOT expected here.