@boyingliu01/xp-gate 0.30.1 → 0.30.3

package/hooks/pre-push

@@ -1,4 +1,20 @@
 #!/bin/bash
+# Line-ending self-check (#546). Must stay on the first executable line: if this
+# file is ever rewritten with CRLF, bash needs to reach this check before the
+# parser chokes somewhere far away and blames an innocent line. `tr` also
+# strips the \r from this very line, so the check runs even when everything
+# around it is broken.
+if tr -d '\r' < "$0" | sed -n '2p' | tr -d '\r' | grep -q 'Line-ending self-check'; then
+  if [ "$(tr -cd '\r' < "$0" | wc -c | tr -d '[:space:]')" -gt 0 ]; then
+    echo "======================================================================" >&2
+    echo "FATAL: hook has CRLF line endings — bash cannot parse it (#546)." >&2
+    echo "  file: $0" >&2
+    echo "  fix : tr -d '\\r' < \"$0\" > \"$0.tmp\" && mv \"$0.tmp\" \"$0\" && chmod +x \"$0\"" >&2
+    echo "Or re-sync the installed copy: xp-gate doctor --sync-hooks" >&2
+    echo "======================================================================" >&2
+    exit 1
+  fi
+fi
 # Pre-push Hook — 8 gates: Gate 10 (Build Integrity) + M/M-Python/M-Go/M-Java/M-Kotlin (Mutation)
 # + M2 (Mock Density, WARNING) + ML (Mock Layering) + UI (UI Sprint Gates) + MW (Code Walkthrough) + S (Sprint Flow)
 #
@@ -220,6 +236,10 @@ if [ -f "$MP_ROOT/scripts/check-hook-mirror.sh" ]; then
   fi
 else
   echo "⚠️ Gate MP: check-hook-mirror.sh not found. SKIP — Gate MP."
+  echo "   Gate MP did not run; this push was not checked for mirror drift."
+  GATE_MP_STATUS="SKIP"
+  GATE_MP_SKIP_REASON="mirror_script_not_found"
+  GATES_SKIPPED="${GATES_SKIPPED:-}Gate MP (mirror parity: script not found)|"
   MP_DURATION_MS=0
 fi
 echo ""
@@ -491,6 +511,13 @@ PY_SOURCE_FILES=$(echo "$PY_FILES" | grep -v '/venv/' | grep -v '/\.venv/' || tr
 
 if [ -z "$PY_SOURCE_FILES" ]; then
   echo "📚 No changed Python source files. SKIP — Gate M (Python)."
+  # #557: this outermost branch was the only Gate M (Python) path that assigned
+  # no status, while Gate M (TypeScript) records a reason on every path. Without
+  # it, "no Python in this push" and "the tool is missing" look identical in the
+  # journals, which is the gap #404 P0 spent effort closing for the TS gate.
+  GATE_M_PY_STATUS="SKIP"
+  GATE_M_PY_SKIP_REASON="no_python_source_files"
+  GATES_SKIPPED="${GATES_SKIPPED:-}Gate M Python (no changed Python source files)|"
 else
   PYTHON_FILE_LIST=$(echo "$PY_SOURCE_FILES" | tr '\n' ',' | sed 's/,$//')
   echo "🐍 Changed Python files: $PYTHON_FILE_LIST"
@@ -504,6 +531,7 @@ else
       case $MUTATION_EXIT in
         0)
           echo "✅ Gate M (Python): PASS"
+          GATE_M_PY_STATUS="PASS"
           ;;
         1)
           echo ""
@@ -519,16 +547,28 @@ else
         124)
           cat "$MUTATION_OUTPUT"
           echo "⏱ Gate M (Python): TIMEOUT (120s). Allowing push with warning."
+          # A timeout means the mutation score was never measured. Saying
+          # nothing here let the closing banner claim success for a gate that
+          # started work and could not finish (#557).
+          GATE_M_PY_STATUS="TIMEOUT"
+          GATE_M_PY_SKIP_REASON="timeout_120s"
+          GATES_SKIPPED="${GATES_SKIPPED:-}Gate M Python (TIMEOUT — score never measured)|"
           ;;
         *)
           cat "$MUTATION_OUTPUT"
           echo "⚠ Gate M (Python): Unexpected exit code $MUTATION_EXIT. Allowing push with warning."
+          GATE_M_PY_STATUS="ERROR"
+          GATE_M_PY_SKIP_REASON="unexpected_exit_${MUTATION_EXIT}"
+          GATES_SKIPPED="${GATES_SKIPPED:-}Gate M Python (error, exit ${MUTATION_EXIT} — score never measured)|"
           ;;
       esac
 
       rm -f "$MUTATION_OUTPUT"
     else
       echo "⚠ Gate M script not found. SKIP — Gate M (Python)."
+      GATE_M_PY_STATUS="SKIP"
+      GATE_M_PY_SKIP_REASON="gate_m_script_not_found"
+      GATES_SKIPPED="${GATES_SKIPPED:-}Gate M Python (gate-m.ts not found)|"
     fi
   else
     echo "⚠ mutmut not installed. SKIP — Gate M (Python)."
@@ -929,11 +969,51 @@ if [[ "$XP_GATE_SKIP_UI_GATES" == "1" ]]; then
   AUDIT_ENTRY="{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"branch\":\"$CURRENT_BRANCH\",\"commit\":\"$(git rev-parse HEAD)\",\"user\":\"$(git config user.name || echo 'unknown')\",\"reason\":\"$XP_GATE_BYPASS_REASON\",\"bypass_type\":\"ui-gates\"}"
   echo "$AUDIT_ENTRY" >> .audit-log.jsonl
 else
-    # Detect UI changes in pushed files
-    UI_DETECTION=$(echo "$PUSHED_FILES" | npx -y tsx src/npm-package/lib/ui-detector.ts --push-mode --from-stdin 2>/dev/null) || true
-    
-    IS_UI_SPRINT=$(echo "$UI_DETECTION" | jq -r '.isUiSprint' 2>/dev/null || echo "false")
-    
+    # Detect UI changes in pushed files.
+    #
+    # stderr is kept out of the captured value but its ABSENCE is no longer
+    # treated as a clean "no UI here" answer (#553). jq -r prints the empty
+    # string and exits 0 on empty input, so the old `|| echo "false"` fallback
+    # was unreachable; an empty verdict became "", which is not "true", which
+    # silently took the "No UI changes detected — skipping" branch. A push whose
+    # only change was src/ui/streamlit_app.py was therefore told there was
+    # nothing to review — the failure Gate UI exists to prevent, inverted.
+    UI_DETECTION=$(echo "$PUSHED_FILES" | npx -y tsx src/npm-package/lib/ui-detector.ts --push-mode --from-stdin 2>/dev/null)
+    UI_DETECT_EXIT=$?
+
+    if [ "$UI_DETECT_EXIT" -eq 0 ] && [ -n "$UI_DETECTION" ]; then
+      IS_UI_SPRINT=$(echo "$UI_DETECTION" | jq -r 'if type == "object" then (.isUiSprint | tostring) else "unknown" end' 2>/dev/null)
+    else
+      IS_UI_SPRINT=""
+    fi
+    # Three answers, not two. "" (detector missing, crashed, or emitted nothing)
+    # is "unknown", and unknown must never read as "no UI".
+    if [ -z "$IS_UI_SPRINT" ] || [ "$IS_UI_SPRINT" = "null" ]; then
+      IS_UI_SPRINT="unknown"
+    fi
+
+    if [ "$IS_UI_SPRINT" = "unknown" ]; then
+      # A missing detector must not disable UI review. Fall back to a path
+      # check over the same file list: a cheap, conservative substitute for a
+      # verdict we do not have.
+      UI_PATH_HITS=$(echo "$PUSHED_FILES" | grep -Ei '(^|/)(src/ui|ui|components|pages|views|screens)/|[.](tsx|jsx|vue|svelte|css|scss|sass|less)$' || true)
+      if [ -n "$UI_PATH_HITS" ]; then
+        echo ""
+        echo "❌ Gate UI: could not evaluate the UI verdict (detector unavailable or produced no verdict, exit ${UI_DETECT_EXIT})."
+        echo "   This push touches UI-looking paths:"
+        echo "$UI_PATH_HITS" | sed 's/^/     /'
+        echo ""
+        echo "   The gate cannot claim there is nothing to review when it never got an answer."
+        echo "   Fix: install the detector (npx -y tsx must be able to load src/npm-package/lib/ui-detector.ts),"
+        echo "   or run the review explicitly: xp-gate ui-review"
+        echo "   To accept the risk for this push: XP_GATE_SKIP_UI_GATES=1 XP_GATE_BYPASS_REASON=\"<why>\""
+        echo ""
+        exit 1
+      fi
+      echo "ℹ️  Gate UI: detector unavailable (exit ${UI_DETECT_EXIT}) and no UI-looking paths in this push — nothing to review."
+      IS_UI_SPRINT="false"
+    fi
+
     if [[ "$IS_UI_SPRINT" == "true" ]]; then
       UI_RESULT_FILE=".ui-gate-result.json"
       MISSING_RESULTS=()
@@ -1067,10 +1147,21 @@ fi
 fi
 
 # ============================================================================
-# ALL CHECKS PASSED
+# Closing banner. States what actually happened (#557): a gate that skipped is
+# named. The heading used to read "ALL CHECKS PASSED" unconditionally while Gate
+# MP and Gate M (Python) skipped on a typical push without recording why, so a
+# reviewer skimming the log had no signal that mutation testing never ran.
 # ============================================================================
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+# Trim the trailing separator and turn it into a displayable list.
+SKIPPED_DISPLAY=$(printf '%s' "${GATES_SKIPPED:-}" | sed 's/|$//' | sed 's/|/ , /g')
+if [ -n "$SKIPPED_DISPLAY" ]; then
+  echo "   ⚠️  NO BLOCKING FAILURES — but not every gate ran:"
+  echo "$SKIPPED_DISPLAY" | tr ',' '\n' | sed '/^[[:space:]]*$/d' | sed 's/^[[:space:]]*/     - /'
+else
+  echo "   ✅ ALL CHECKS PASSED"
+fi
 # Say what actually happened. Printing "VERIFIED" on a skipped gate would be a
 # claim the hook cannot support — the same dishonesty (evidence asserting an
 # unperformed check) that Gate MW exists to prevent.

package/hooks/sprint-gate.sh

@@ -181,6 +181,65 @@ read_verdict() {
   json_extract "$APPROVED_FILE" '.verdict // ""' || echo ""
 }
 
+# --- Helper: sprint age in days, or empty if unknown ---
+# Reads status + started_at from sprint-state.json. #551: the gate judged only
+# `phase` and the delphi verdict, so a state file left at status=in_progress
+# reported "sprint phase 6 validated" on unrelated commits for as long as
+# nobody fixed it. An advancing sprint and an abandoned one were
+# indistinguishable -- worse than SKIP, because SKIP is honest and PASS lies.
+read_sprint_status() {
+  if [ ! -f "$SPRINT_STATE_JSON" ] || [ "$JSON_PARSER" = "none" ]; then
+    echo ""
+    return
+  fi
+  json_validate "$SPRINT_STATE_JSON" || { echo ""; return; }
+  json_extract "$SPRINT_STATE_JSON" '.status // ""' 2>/dev/null || echo ""
+}
+
+read_sprint_age_days() {
+  if [ ! -f "$SPRINT_STATE_JSON" ] || [ "$JSON_PARSER" = "none" ]; then
+    echo ""
+    return
+  fi
+  json_validate "$SPRINT_STATE_JSON" || { echo ""; return; }
+  local started
+  started=$(json_extract "$SPRINT_STATE_JSON" '.started_at // ""' 2>/dev/null || echo "")
+  # Older state files may carry updated_at only; either is the last sign of life.
+  if [ -z "$started" ] || [ "$started" = "null" ]; then
+    started=$(json_extract "$SPRINT_STATE_JSON" '.updated_at // ""' 2>/dev/null || echo "")
+  fi
+  if [ -z "$started" ] || [ "$started" = "null" ]; then
+    echo ""
+    return
+  fi
+  # Portable ISO-8601 -> epoch. GNU date first, BSD date second, node last; if
+  # all fail the age is unknown and the caller must not invent one.
+  local epoch=""
+  epoch=$(date -u -d "$started" +%s 2>/dev/null || true)
+  if [ -z "$epoch" ]; then
+    epoch=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$started" +%s 2>/dev/null || true)
+  fi
+  if [ -z "$epoch" ] && command -v node >/dev/null 2>&1; then
+    epoch=$(node -e "const t=Date.parse(process.argv[1]);if(Number.isFinite(t))process.stdout.write(String(Math.floor(t/1000)))" "$started" 2>/dev/null || true)
+  fi
+  if [ -z "$epoch" ]; then
+    echo ""
+    return
+  fi
+  local now
+  now=$(date -u +%s)
+  local age=$(( (now - epoch) / 86400 ))
+  [ "$age" -lt 0 ] && age=0
+  echo "$age"
+}
+
+# Threshold in days beyond which an in_progress sprint is considered abandoned.
+# Configurable because the right number is project-specific: a weekly cadence
+# wants 14, a monthly one wants more. Default 14 = two full weeks without
+# progress: enough that a sprint paused over a holiday is not called dead, tight
+# enough that the reported 12-day case is caught within two days of it firing.
+SPRINT_STALE_DAYS="${SPRINT_STALE_DAYS:-14}"
+
 # --- Pre-commit mode ---
 if [ "$MODE" = "pre-commit" ]; then
   PHASE=$(read_phase)
@@ -222,8 +281,28 @@ if [ "$MODE" = "pre-commit" ]; then
       exit 1
     fi
 
-    # All checks passed
-    echo "{\"decision\":\"allow\",\"message\":\"delphi-review APPROVED, sprint phase ${PHASE} validated\"}"
+    # #551: staleness. A sprint left at status=in_progress past the threshold is
+    # abandoned, not validated -- reporting PASS for it means the gate cannot
+    # distinguish an advancing sprint from a forgotten one, and it injects
+    # ancient phase_history into every unrelated commit's audit trail. SKIP is
+    # the honest answer: the gate declines to certify a sprint nobody is
+    # driving, without blocking work that has nothing to do with it.
+    SPRINT_STATUS=$(read_sprint_status)
+    SPRINT_AGE_DAYS=$(read_sprint_age_days)
+    if [ "$SPRINT_STATUS" = "in_progress" ] && [ -n "$SPRINT_AGE_DAYS" ] \
+       && [ "$SPRINT_AGE_DAYS" -ge "$SPRINT_STALE_DAYS" ] 2>/dev/null; then
+      echo "{\"decision\":\"skip\",\"reason\":\"STALE SPRINT: status=in_progress for ${SPRINT_AGE_DAYS} days (threshold ${SPRINT_STALE_DAYS}) — not certifying it. Finish it (sprint-flow close) or clear .sprint-state/sprint-state.json\"}"
+      exit 0
+    fi
+
+    # All checks passed. Name the age so "validated" is not an unconditional
+    # claim: a 29-day-old sprint under a 30-day threshold is a very different
+    # situation from one opened today, and the log should say which it is.
+    if [ -n "$SPRINT_AGE_DAYS" ]; then
+      echo "{\"decision\":\"allow\",\"message\":\"delphi-review APPROVED, sprint phase ${PHASE} validated (sprint open ${SPRINT_AGE_DAYS} day(s), staleness threshold ${SPRINT_STALE_DAYS})\"}"
+    else
+      echo "{\"decision\":\"allow\",\"message\":\"delphi-review APPROVED, sprint phase ${PHASE} validated (sprint age unknown — started_at unreadable)\"}"
+    fi
     exit 0
   fi
 

package/lib/__tests__/crap-cli.test.js

@@ -0,0 +1,76 @@
+/**
+ * @test REQ-404 CRAP advisory CLI
+ * @intent Verify `xp-gate crap` renders a ranking, stays advisory (exit 0 no
+ *         matter what it finds), and refuses to invent a ranking when its
+ *         inputs are missing.
+ * @covers AC-404
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { handleCrap, parseArgs } = require('../crap-cli.js');
+
+function capture(fn) {
+  const logs = [];
+  const errs = [];
+  const origLog = console.log;
+  const origErr = console.error;
+  console.log = (...a) => logs.push(a.join(' '));
+  console.error = (...a) => errs.push(a.join(' '));
+  return fn()
+    .then((code) => ({ code, out: logs.join('\n'), err: errs.join('\n') }))
+    .finally(() => {
+      console.log = origLog;
+      console.error = origErr;
+    });
+}
+
+describe('crap-cli.js - argument parsing', () => {
+  it('defaults to top 20, threshold 6, mirrors excluded', () => {
+    const opts = parseArgs([]);
+    expect(opts.top).toBe(20);
+    expect(opts.threshold).toBe(6);
+    expect(opts.includeMirrors).toBe(false);
+    expect(opts.json).toBe(false);
+  });
+
+  it('parses the documented flags', () => {
+    const opts = parseArgs(['--top', '5', '--threshold', '12', '--json', '--include-mirrors']);
+    expect(opts.top).toBe(5);
+    expect(opts.threshold).toBe(12);
+    expect(opts.json).toBe(true);
+    expect(opts.includeMirrors).toBe(true);
+  });
+
+  it('collects multiple --paths values', () => {
+    expect(parseArgs(['--paths', 'src', 'scripts']).paths).toEqual(['src', 'scripts']);
+  });
+});
+
+describe('crap-cli.js - advisory contract', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'crap-cli-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('prints usage and exits 0 on --help', async () => {
+    const res = await capture(() => handleCrap(['--help']));
+    expect(res.code).toBe(0);
+    expect(res.out).toContain('ADVISORY ONLY');
+  });
+
+  it('refuses to rank when there is no coverage artifact', async () => {
+    // Without coverage every function is unmeasured; printing an empty ranking
+    // would read as "nothing to fix", which is the opposite of the truth.
+    const missing = path.join(tmpDir, 'does-not-exist.json');
+    const res = await capture(() => handleCrap(['--coverage', missing]));
+    expect(res.code).toBe(1);
+    expect(res.err).toContain('No coverage artifact');
+  });
+});

package/lib/__tests__/crap.test.js

@@ -0,0 +1,137 @@
+/**
+ * @test REQ-404 CRAP advisory ranking
+ * @intent Verify the CRAP indicator ranks "complex and weakly tested" functions
+ *         without silently treating missing coverage as either perfect or zero,
+ *         and that it never presents itself as a blocking gate (#404 P1-2).
+ * @covers AC-404
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  computeCrap,
+  joinCoverage,
+  buildCrapReport,
+  isMirrorPath,
+} = require('../crap.js');
+
+describe('crap.js - CRAP formula', () => {
+  it('computes comp^2 * (1 - cov) + comp', () => {
+    // CCN 10, 50% covered -> 100 * 0.5 + 10 = 60
+    expect(computeCrap(10, 0.5)).toBeCloseTo(60, 5);
+    // CCN 4, fully covered -> 0 + 4 = 4
+    expect(computeCrap(4, 1)).toBeCloseTo(4, 5);
+    // CCN 12, no coverage -> 144 + 12 = 156
+    expect(computeCrap(12, 0)).toBeCloseTo(156, 5);
+  });
+
+  it('returns null when coverage is unknown rather than guessing', () => {
+    // The whole reason this function exists: an unmeasured function must not be
+    // scored as if it were untested (that inflates it to the top of the ranking)
+    // nor as if it were fully tested (that hides it). It is simply unmeasured.
+    expect(computeCrap(10, null)).toBeNull();
+    expect(computeCrap(10, undefined)).toBeNull();
+    expect(computeCrap(10, NaN)).toBeNull();
+  });
+
+  it('clamps out-of-range coverage instead of producing negative scores', () => {
+    // Istanbul occasionally reports slightly out-of-range values; a negative
+    // CRAP would sort below genuinely clean functions and hide a hotspot.
+    expect(computeCrap(5, 1.2)).toBeCloseTo(5, 5);
+    expect(computeCrap(5, -0.1)).toBeCloseTo(30, 5);
+  });
+});
+
+describe('crap.js - coverage joining', () => {
+  it('joins per-file coverage using a repo-relative path', () => {
+    const coverage = new Map([['src/a.ts', 0.5]]);
+    const functions = [{ file: 'src/a.ts', name: 'f', ccn: 10 }];
+    const joined = joinCoverage(functions, coverage);
+    expect(joined).toHaveLength(1);
+    expect(joined[0].cov).toBeCloseTo(0.5, 5);
+    expect(joined[0].crap).toBeCloseTo(60, 5);
+  });
+
+  it('marks functions whose file has no coverage as unmeasured', () => {
+    const coverage = new Map([['src/a.ts', 0.5]]);
+    const functions = [{ file: 'src/never-loaded.ts', name: 'g', ccn: 20 }];
+    const joined = joinCoverage(functions, coverage);
+    expect(joined[0].cov).toBeNull();
+    expect(joined[0].crap).toBeNull();
+  });
+});
+
+describe('crap.js - report', () => {
+  const functions = [
+    { file: 'src/gates/gate-7.ts', name: 'runGate7', ccn: 14, cov: 0 },
+    { file: 'src/gates/ok.ts', name: 'clean', ccn: 3, cov: 1 },
+    { file: 'src/gates/mid.ts', name: 'mid', ccn: 9, cov: 0.8 },
+  ];
+
+  it('ranks by CRAP descending and drops functions below the bar', () => {
+    const report = buildCrapReport(functions, { threshold: 6 });
+    // clean: 9 * 0 + 3 = 3 -> below the bar, excluded
+    // mid:   81 * 0.2 + 9 = 25.2
+    // runGate7: 196 + 14 = 210
+    expect(report.hotspots.map((h) => h.name)).toEqual(['runGate7', 'mid']);
+    expect(report.hotspots[0].crap).toBeCloseTo(210, 5);
+  });
+
+  it('reports how many functions could not be measured', () => {
+    const withUnknown = [
+      ...functions,
+      { file: 'src/gates/never.ts', name: 'nope', ccn: 30, cov: null },
+    ];
+    const report = buildCrapReport(withUnknown, { threshold: 6 });
+    expect(report.unmeasured).toBe(1);
+    expect(report.measured).toBe(3);
+  });
+
+  it('labels itself advisory', () => {
+    const report = buildCrapReport(functions, { threshold: 6 });
+    // A ranking nobody is blocked by must say so; the RFC is explicit that this
+    // navigates refactoring and does not replace security/performance review.
+    expect(report.advisory).toBe(true);
+    expect(report.blocking).toBe(false);
+  });
+
+  it('honours an explicit top-N limit', () => {
+    const report = buildCrapReport(functions, { threshold: 6, top: 1 });
+    expect(report.hotspots).toHaveLength(1);
+  });
+});
+
+describe('crap.js - mirror exclusion', () => {
+  it('recognises the generated npm-package mirror', () => {
+    // Refactoring a mirror is refactoring a copy that prepack overwrites.
+    expect(isMirrorPath('src/npm-package/lib/doctor.js')).toBe(true);
+    expect(isMirrorPath('src/npm-package/principles/config.ts')).toBe(true);
+  });
+
+  it('does not treat real source as a mirror', () => {
+    expect(isMirrorPath('src/gates/gate-7.ts')).toBe(false);
+    expect(isMirrorPath('plugins/qoder/src/index.ts')).toBe(false);
+  });
+
+  it('excludes mirror-tree functions from the ranking by default', () => {
+    // A mirror hotspot outranks everything real (measured: findBodyBrace at
+    // CRAP 4830 for being a big untested generated copy), so the default has to
+    // be exclusion or the ranking is useless out of the box.
+    const mixed = [
+      { file: 'src/npm-package/lib/huge.js', name: 'mirrorFn', ccn: 60, cov: 0 },
+      { file: 'src/gates/real.ts', name: 'realFn', ccn: 10, cov: 0 },
+    ];
+    const report = buildCrapReport(mixed, { threshold: 6 });
+    expect(report.hotspots.map((h) => h.name)).toEqual(['realFn']);
+  });
+
+  it('includes mirrors only when explicitly asked', () => {
+    const mixed = [
+      { file: 'src/npm-package/lib/huge.js', name: 'mirrorFn', ccn: 60, cov: 0 },
+      { file: 'src/gates/real.ts', name: 'realFn', ccn: 10, cov: 0 },
+    ];
+    const report = buildCrapReport(mixed, { threshold: 6, mirrors: true });
+    expect(report.hotspots.map((h) => h.name)).toEqual(['mirrorFn', 'realFn']);
+  });
+});

package/lib/__tests__/hook-health.test.js

@@ -0,0 +1,85 @@
+/**
+ * @test REQ-546 hook health: line endings and bash parseability
+ * @intent Verify doctor can tell a hook that merely EXISTS from a hook git can
+ *         actually run. #546: a pre-commit rewritten with CRLF line endings
+ *         failed every commit while `xp-gate doctor` reported it healthy,
+ *         because the check only asked whether the file was there.
+ * @covers AC-05, AC-08
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { inspectHookFile } = require('../hook-health');
+
+let TMP_DIR;
+
+beforeAll(() => {
+  TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'hook-health-'));
+});
+
+afterAll(() => {
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+function write(name, content) {
+  const p = path.join(TMP_DIR, name);
+  fs.writeFileSync(p, content);
+  return p;
+}
+
+describe('inspectHookFile', () => {
+  test('a healthy LF hook reports ok', () => {
+    const p = write('good.sh', '#!/bin/bash\nfoo() {\n  echo hi\n}\nfoo\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(true);
+    expect(r.crlfLines).toBe(0);
+    expect(r.problems).toEqual([]);
+  });
+
+  test('an all-CRLF hook is reported with a CRLF count', () => {
+    const p = write('crlf.sh', '#!/bin/bash\r\nfoo() {\r\n  echo hi\r\n}\r\nfoo\r\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.crlfLines).toBe(5);
+    expect(r.problems.join(' ')).toMatch(/CRLF/);
+  });
+
+  test('a single stray CRLF is enough to fail', () => {
+    // One bad line is all bash needs to choke on, and it is the case an
+    // "is the file mostly fine" heuristic would wave through.
+    const p = write('one.sh', '#!/bin/bash\necho one\necho two\r\necho three\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.crlfLines).toBe(1);
+  });
+
+  test('CRLF in the middle of a multi-line construct is flagged', () => {
+    // The exact shape from #546: the \r lands inside a construct bash is
+    // mid-way through parsing, so the reported line number drifts far from
+    // the real cause.
+    const p = write('mid.sh', 'case "$x" in\r\n  a) echo a ;;\r\nesac\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.crlfLines).toBe(2);
+  });
+
+  test('a syntax error with clean line endings is reported as unparseable', () => {
+    const p = write('bad.sh', '#!/bin/bash\nif [ 1 -eq 1 ]; then\n  echo x\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.problems.join(' ')).toMatch(/not parseable|syntax/i);
+  });
+
+  test('a binary-looking file does not crash the inspector', () => {
+    const p = path.join(TMP_DIR, 'bin.sh');
+    fs.writeFileSync(p, Buffer.from([0x00, 0xff, 0xfe, 0x0a]));
+    expect(() => inspectHookFile(p)).not.toThrow();
+  });
+
+  test('a missing file reports missing rather than throwing', () => {
+    const r = inspectHookFile(path.join(TMP_DIR, 'nope.sh'));
+    expect(r.ok).toBe(false);
+    expect(r.problems.join(' ')).toMatch(/missing/i);
+  });
+});