@boyingliu01/xp-gate 0.33.2 → 0.34.1

package/hooks/lib/diff-coverage.sh

@@ -0,0 +1,223 @@
+#!/bin/bash
+# Changed-line coverage for Gate 5 (#600).
+#
+# Gate 5 compares GLOBAL coverage against a floor (default 80, hard floor 60).
+# A commit that changes five lines and tests none of them passes as long as the
+# global number has not dipped below that floor -- so the only thing the gate ever
+# measured about a change was the average of everything else in the repo. 指南
+# §10.1/§10.3 asks for three measures the repo never computed: changed-line
+# coverage (>=90%), changed-branch coverage (>=85%), and module coverage that does
+# not go DOWN.
+#
+# This library reads vitest's v8 `coverage/coverage-final.json` (already produced;
+# the json reporter is on) plus the staged diff, and answers exactly one question
+# per changed file: of the lines this commit touched, how many did the tests
+# execute? Staged-only is deliberate -- the question is about the commit, and
+# scanning the working tree would report on code that is not being committed.
+#
+# Fail-closed on unmeasurable inputs (#570): no coverage file, unparseable JSON, or
+# a changed file absent from the coverage report all mean "not measured", and "not
+# measured" must never render as "passed". The one legitimate absence is a file
+# the coverage provider deliberately omits for being non-executable (type-only
+# `.d.ts`, or a source with no statements at all) -- that is reported as `n/a`,
+# not as 0%, because scoring it 0% would block every constants module.
+#
+# The whole computation lives in one node program rather than shell+awk because
+# coverage-final.json is a nested object keyed by absolute path; parsing it in
+# shell means three places to get the path normalisation wrong, and this repo has
+# already paid for that mistake twice (#632, #633).
+
+# Report one line per changed file: `<file> <covered> <total> <pct> <verdict>`.
+#
+# $1 = coverage-final.json path
+# $2 = file with changed line ranges, one per line: `<path> <start> <end>`
+# $3 = line-coverage threshold (default 90)
+# $4 = branch-coverage threshold (default 85)
+#
+# Prints:
+#   RESULT <covered> <total> <pct>          aggregate over all changed lines
+#   MISSING <file>                          changed file with no coverage entry
+#   UNCOVERED <file> <line> [<line>...]     individual uncovered changed lines
+#   BRANCH <covered> <total> <pct>          aggregate over changed branches
+#   NA <file>                               nothing executable changed
+# and exits 0 when the aggregate meets both thresholds, 1 otherwise, 2 when the
+# input could not be read at all (fail-closed).
+compute_diff_coverage() {
+  local coverage_file="$1" changes_file="$2"
+  local line_threshold="${3:-90}" branch_threshold="${4:-85}"
+
+  if [ ! -f "$coverage_file" ]; then
+    echo "ERROR no_coverage_data"
+    return 2
+  fi
+  if [ ! -f "$changes_file" ]; then
+    echo "ERROR no_changes"
+    return 2
+  fi
+
+  node -e '
+    const fs = require("fs");
+    const [covPath, chgPath, lineT, branchT] = process.argv.slice(1);
+    const lineThreshold = Number(lineT);
+    const branchThreshold = Number(branchT);
+
+    let cov;
+    try {
+      cov = JSON.parse(fs.readFileSync(covPath, "utf8"));
+    } catch (e) {
+      console.log("ERROR unparsable_coverage");
+      process.exit(2);
+    }
+
+    // Coverage keys are absolute paths emitted by the reporter; the diff paths are
+    // repo-relative with forward slashes. Reduce both to a comparable suffix so a
+    // Windows drive letter or a leading "./" cannot make every file "missing".
+    const norm = (p) => String(p).replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
+    const bySuffix = new Map();
+    for (const [absPath, entry] of Object.entries(cov)) {
+      const n = norm(absPath);
+      bySuffix.set(n, entry);
+      // Also index by the trailing two segments so a repo-relative "src/x.ts"
+      // can find "/abs/root/src/x.ts" without guessing the root.
+      const segs = n.split("/");
+      if (segs.length >= 2) bySuffix.set(segs.slice(-2).join("/"), entry);
+    }
+    const find = (p) => bySuffix.get(norm(p)) || bySuffix.get(norm(p).split("/").slice(-2).join("/"));
+
+    // Changed line ranges, keyed by file.
+    const wanted = new Map();
+    for (const raw of fs.readFileSync(chgPath, "utf8").split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line) continue;
+      const parts = line.split(/\s+/);
+      if (parts.length !== 3) continue;
+      const [file, s, e] = parts;
+      const start = Number(s);
+      const end = Number(e);
+      if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+      if (!wanted.has(file)) wanted.set(file, []);
+      wanted.get(file).push([start, end]);
+    }
+
+    let covLines = 0, totLines = 0, covBranches = 0, totBranches = 0;
+    for (const [file, ranges] of wanted) {
+      const entry = find(file);
+      if (!entry) { console.log("MISSING " + file); continue; }
+
+      // statementMap/s and branchMap/b are OBJECTS keyed by numeric string in the
+      // v8 provider this repo uses (they are arrays under the babel provider).
+      // Iterate whichever shape is present rather than assuming one.
+      const stmts = Array.isArray(entry.statementMap)
+        ? entry.statementMap.map((v, i) => [String(i), v])
+        : Object.entries(entry.statementMap || {});
+      const stmtHits = entry.s || {};
+      const brs = Array.isArray(entry.branchMap)
+        ? entry.branchMap.map((v, i) => [String(i), v])
+        : Object.entries(entry.branchMap || {});
+      const brHits = entry.b || {};
+
+      const inRange = (ln) => ranges.some(([s, e]) => ln >= s && ln <= e);
+      let fileTotal = 0, fileCov = 0;
+      const uncovered = [];
+      for (const [id, meta] of stmts) {
+        const ln = meta && meta.start ? meta.start.line : (meta && meta.line);
+        if (!ln || !inRange(ln)) continue;
+        fileTotal++;
+        if (Number(stmtHits[id] || 0) > 0) fileCov++;
+        else uncovered.push(ln);
+      }
+
+      let fileBTotal = 0, fileBCov = 0;
+      for (const [id, meta] of brs) {
+        const ln = meta && meta.line ? meta.line : (meta && meta.loc && meta.loc.start ? meta.loc.start.line : 0);
+        if (!ln || !inRange(ln)) continue;
+        const counts = brHits[id];
+        const arr = Array.isArray(counts) ? counts : [counts || 0];
+        for (const c of arr) {
+          fileBTotal++;
+          if (Number(c) > 0) fileBCov++;
+        }
+      }
+
+      covLines += fileCov; totLines += fileTotal;
+      covBranches += fileBCov; totBranches += fileBTotal;
+
+      if (fileTotal === 0 && fileBTotal === 0) { console.log("NA " + file); continue; }
+      if (uncovered.length) {
+        console.log("UNCOVERED " + file + " " + uncovered.join(" "));
+      }
+    }
+
+    const pct = (c, t) => (t === 0 ? 100 : Math.round((c / t) * 1000) / 10);
+    console.log("RESULT " + covLines + " " + totLines + " " + pct(covLines, totLines));
+    console.log("BRANCH " + covBranches + " " + totBranches + " " + pct(covBranches, totBranches));
+
+    // Nothing executable changed at all: not a failure, and not a pass either --
+    // the caller decides (docs-only commits SKIP upstream).
+    if (totLines === 0 && totBranches === 0) process.exit(0);
+    const lineOk = totLines === 0 || pct(covLines, totLines) >= lineThreshold;
+    const branchOk = totBranches === 0 || pct(covBranches, totBranches) >= branchThreshold;
+    process.exit(lineOk && branchOk ? 0 : 1);
+  ' "$coverage_file" "$changes_file" "$line_threshold" "$branch_threshold"
+}
+
+# Emit `<path> <start> <end>` triples for every added line range in the STAGED diff.
+#
+# Only files the coverage provider can measure are worth listing: a docs-only or
+# config-only diff yields no rows, which makes the caller's "nothing executable
+# changed" branch reachable instead of comparing 0/0.
+#
+# $1 = optional output file (defaults to stdout).
+staged_added_line_ranges() {
+  # Prints `<path> <start> <end>` to STDOUT; the caller redirects. Deliberately not
+  # "print to $1": awk's `> file` redirect is not portable across the awk builds on
+  # this project's target platforms (the Windows Git Bash awk silently wrote
+  # nothing), and a range extractor that yields an empty list makes every diff
+  # coverage result vacuously 100%.
+  #
+  # --unified=0 gives one `@@ -a,b +c,d @@` header per contiguous change, so the
+  # added range is exactly +c,d and no context lines need filtering. A header with
+  # no ",d" means a single-line change.
+  git diff --cached --unified=0 --no-color --diff-filter=ACM 2>/dev/null \
+    | awk '
+        /^\+\+\+ / {
+          path = $2
+          sub(/^b\//, "", path)
+          next
+        }
+        /^@@ / {
+          if (path == "" || path == "/dev/null") next
+          if (path !~ /\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|cs|scala|sh|bats|ps1)$/) next
+          line = $0
+          sub(/^@@ [^+]*\+/, "", line)
+          sub(/[^0-9,].*$/, "", line)
+          n = split(line, parts, ",")
+          start = parts[1] + 0
+          len = (n > 1 ? parts[2] + 0 : 1)
+          print path " " start " " (start + len - 1)
+          next
+        }
+      '
+  return 0
+}
+
+# Read a numeric threshold from .xp-gate/test-profile.yaml, falling back to the
+# documented default (指南 §10.1: 90% lines, 85% branches) when the file or key is
+# absent. Kept here, next to its only consumer, so the two can never drift.
+#
+# $1 = key name (diff_coverage_lines | diff_coverage_branches)
+# $2 = default
+diff_coverage_threshold() {
+  local key="$1" fallback="$2" profile=".xp-gate/test-profile.yaml"
+  if [ ! -f "$profile" ]; then
+    printf '%s' "$fallback"
+    return 0
+  fi
+  local value
+  value=$(grep -E "^[[:space:]]*${key}[[:space:]]*:" "$profile" 2>/dev/null \
+    | head -1 | sed 's/^[^:]*:[[:space:]]*//' | tr -d '"'"'"' \r')
+  case "$value" in
+    ''|*[!0-9.]*) printf '%s' "$fallback" ;;
+    *) printf '%s' "$value" ;;
+  esac
+}

package/hooks/pre-commit

@@ -402,6 +402,15 @@ source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/docs-only.sh"
 # so the fail-closed contract is unit-testable without executing this hook.
 source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/test-failure.sh"
 
+# Issue #602: test-suite hygiene detectors (.only / .skip / deleted test files),
+# sourced so the same vocabulary is unit-testable and reusable by Gate 5d (#601).
+source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/assertion-quality.sh"
+
+# Issue #600: changed-line coverage (指南 §10.1/§10.3), sourced for the same reason --
+# a shell-only parse of coverage-final.json would be a third place to get Windows
+# path normalisation wrong, and this repo has paid for that twice (#632, #633).
+source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/diff-coverage.sh"
+
 # Issue #477: Gate 2's jscpd config probe and outcome classification, same reason.
 source_gate_lib "${AUDIT_SCRIPT_DIR}/lib/jscpd-run.sh"
 
@@ -2228,6 +2237,121 @@ if [ "$PROJECT_LANG" = "documentation-only" ] || [ "$DOCS_ONLY_COMMIT" = true ];
   GATE_5_DETAIL="docs_only_change"
 
 else
+  # ========================================================================
+  # Gate 5-FOCUS / Gate 5-DELETE (#602): the two quietest ways to "fix" a red
+  # build are to commit a `.only` (CI then runs one case and reports green) and
+  # to delete a test file with no replacement (the safety net vanishes with no
+  # signal). 指南 §9.5/§12 forbid both. Gate 5a guards the ADD side -- "a new
+  # source file must have a test" -- so guarding only that side left the
+  # constraint asymmetric: tests could be silently removed but never silently
+  # added, which is backwards from what protects the codebase.
+  #
+  # Runs before the expensive Gate 5a machinery so a `.only` commit fails in
+  # milliseconds instead of after a full test run.
+  # ========================================================================
+  GATE_5_FOCUS_BLOCKED=0
+  GATE_5_SKIP_COUNT=0
+  GATE_5_DELETED_TESTS=""
+  if declare -f classify_test_focus >/dev/null 2>&1; then
+    STAGED_TEST_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+      | grep -E '\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|cs|scala|ps1)$|(^|/)(test_[^/]*\.py|[^/]*_test\.(py|go))$' || true)
+    if [ -n "$STAGED_TEST_FILES" ]; then
+      while IFS= read -r _tf; do
+        [ -n "$_tf" ] || continue
+        _tf_content=$(git show ":$tf" 2>/dev/null) || _tf_content=$(cat "$_tf" 2>/dev/null || true)
+        [ -n "$_tf_content" ] || continue
+
+        # --- focus markers: BLOCK ---
+        _focus_hits=$(printf '%s\n' "$_tf_content" | classify_test_focus || true)
+        if [ -n "$_focus_hits" ]; then
+          # XP_GATE_ALLOW_ONLY=1 is an explicit, audited override for the one
+          # legitimate case (debugging an unrelated failure mid-bisect). It is
+          # opt-in per run and printed, never silent.
+          if [ "${XP_GATE_ALLOW_ONLY:-0}" = "1" ]; then
+            echo "⚠️  WARN - focus marker in $_tf (allowed by XP_GATE_ALLOW_ONLY=1)"
+            record_gate_audit "gate-5-focus-override" "focus-override" "WARN" 1 "$GATE_5_START" "file=$_tf"
+          else
+            echo "❌ BLOCKED - focus marker(s) in $_tf:"
+            printf '%s\n' "$_focus_hits" | sed 's/^/     /'
+            GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+          fi
+        fi
+
+        # --- skip markers: WARN unless justified ---
+        _skip_hits=$(printf '%s\n' "$_tf_content" | classify_test_skip || true)
+        if [ -n "$_skip_hits" ]; then
+          if is_skip_justified "$_tf_content"; then
+            echo "ℹ️  Skipped case(s) in $_tf are justified via @skip-justified."
+          else
+            _skip_n=$(printf '%s\n' "$_skip_hits" | wc -l | tr -d ' ')
+            GATE_5_SKIP_COUNT=$((GATE_5_SKIP_COUNT + _skip_n))
+            echo "⚠️  WARN - $_skip_n skipped case(s) in $_tf without @skip-justified: <reason>"
+          fi
+        fi
+        # --- Gate 5d (#601): assertion quality ---
+        # 指南 §9.2 forbids six assertion anti-patterns, and until now nothing in
+        # XP-Gate looked at assertions at all: Gate M2/M3 examine how test doubles
+        # are built, never whether the test asserts anything. Tautologies and
+        # empty catches are BLOCK (certainly vacuous); weak-only / mock-echo /
+        # call-order shapes WARN, because each can be legitimate and blocking a
+        # legal style trains people to add justification annotations until the
+        # annotation stops meaning anything.
+        if declare -f classify_tautological_assertions >/dev/null 2>&1; then
+          if is_assertion_justified "$_tf_content"; then
+            echo "ℹ️  Assertion style in $_tf is justified via @assertion-justified."
+          else
+            _tauto=$(printf '%s\n' "$_tf_content" | classify_tautological_assertions || true)
+            _swallow=$(printf '%s\n' "$_tf_content" | classify_swallowed_errors || true)
+            _weak=$(printf '%s\n' "$_tf_content" | classify_weak_assertions || true)
+            if [ -n "$_tauto" ]; then
+              echo "❌ BLOCKED - tautological assertion(s) in $_tf (cannot fail):"
+              printf '%s\n' "$_tauto" | sed 's/^/     /'
+              echo "     See skills/test-driven-development/testing-anti-patterns.md"
+              GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+            fi
+            if [ -n "$_swallow" ]; then
+              echo "❌ BLOCKED - empty catch in $_tf swallows the failure it guards:"
+              printf '%s\n' "$_swallow" | sed 's/^/     /'
+              echo "     See skills/test-driven-development/testing-anti-patterns.md"
+              GATE_5_FOCUS_BLOCKED=$((GATE_5_FOCUS_BLOCKED + 1))
+            fi
+            if [ -n "$_weak" ]; then
+              echo "⚠️  WARN - test block(s) in $_tf assert only weak properties:"
+              printf '%s\n' "$_weak" | sed 's/^/     /'
+              echo "     toBeDefined/toBeTruthy alone cannot detect a wrong value."
+              GATE_5_SKIP_COUNT=$((GATE_5_SKIP_COUNT + $(printf '%s\n' "$_weak" | wc -l | tr -d ' ')))
+            fi
+          fi
+        fi
+      done <<< "$STAGED_TEST_FILES"
+
+      # --- deleted test files: WARN ---
+      DELETED_LIST=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/xp-deleted-$$")
+      ADDED_LIST=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/xp-added-$$")
+      git diff --cached --name-only --diff-filter=D > "$DELETED_LIST" 2>/dev/null || true
+      git diff --cached --name-only --diff-filter=A > "$ADDED_LIST" 2>/dev/null || true
+      GATE_5_DELETED_TESTS=$(classify_deleted_tests "$DELETED_LIST" "$ADDED_LIST" || true)
+      rm -f "$DELETED_LIST" "$ADDED_LIST"
+      if [ -n "$GATE_5_DELETED_TESTS" ]; then
+        echo "⚠️  WARN - test file(s) deleted with no same-named replacement:"
+        printf '%s\n' "$GATE_5_DELETED_TESTS" | sed 's/^/     /'
+        echo "     Deleting a test removes the safety net (指南 §9.5). If the code is"
+        echo "     genuinely gone, say so in the commit body; otherwise restore it."
+      fi
+    fi
+  fi
+
+  if [ "$GATE_5_FOCUS_BLOCKED" -gt 0 ]; then
+    echo ""
+    echo "❌ BLOCKED - Gate 5: $GATE_5_FOCUS_BLOCKED test-hygiene violation(s) (see above)."
+    echo "   Focus markers (.only/fit/fdescribe) make CI run one case and report green;"
+    echo "   tautological assertions and empty catches verify nothing at all."
+    echo "   See skills/test-driven-development/testing-anti-patterns.md"
+    echo "   Remove them, or add '@assertion-justified: <reason>' for a reviewed exception."
+    record_gate_audit "gate-5-focus" "test-focus" "FAIL" "$GATE_5_FOCUS_BLOCKED" "$GATE_5_START" "blocked=1"
+    exit 1
+  fi
+
   # ========================================================================
   # Gate 5a: Test-Source File Pairing Check
   # New .ts/.tsx files: BLOCK (no corresponding test → commit rejected)
@@ -3086,6 +3210,57 @@ else
           else
             echo "TypeScript coverage: ${COVERAGE_PERCENT}% ✅ (≥ ${COVERAGE_THRESHOLD:-80}%)"
           fi
+
+          # ---- Diff coverage (#600): 指南 §10.1/§10.3 ----
+          # The block above measures the WHOLE repo. A commit that changes five
+          # lines and tests none of them passes as long as the global average has
+          # not dipped -- so the only thing that gate ever knew about THIS change
+          # was the average of everything else. This block asks the narrower and
+          # more useful question: of the lines this commit touches, how many did
+          # the tests execute?
+          #
+          # Skipped on a subset run, like the global check above: a partial run
+          # legitimately leaves most changed lines unexecuted because the tests
+          # covering them were deselected, and reporting that as low coverage
+          # would punish the smart-selection feature for working.
+          if declare -f compute_diff_coverage >/dev/null 2>&1 \
+             && [ "${PARTIAL_TEST_RUN:-false}" != "true" ] \
+             && [ -f "coverage/coverage-final.json" ]; then
+            DIFF_COV_RANGES=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/diffcov-$$")
+            DIFF_COV_LINE_T=$(diff_coverage_threshold diff_coverage_lines 90)
+            DIFF_COV_BRANCH_T=$(diff_coverage_threshold diff_coverage_branches 85)
+            staged_added_line_ranges > "$DIFF_COV_RANGES" 2>/dev/null || true
+            if [ -s "$DIFF_COV_RANGES" ]; then
+              DIFF_COV_OUT=$(compute_diff_coverage coverage/coverage-final.json \
+                "$DIFF_COV_RANGES" "$DIFF_COV_LINE_T" "$DIFF_COV_BRANCH_T" 2>&1)
+              DIFF_COV_RC=$?
+              DIFF_COV_RESULT=$(printf '%s\n' "$DIFF_COV_OUT" | grep '^RESULT ' | head -1)
+              DIFF_COV_BRANCH=$(printf '%s\n' "$DIFF_COV_OUT" | grep '^BRANCH ' | head -1)
+              if [ "$DIFF_COV_RC" -eq 0 ]; then
+                echo "Changed-line coverage: ${DIFF_COV_RESULT#RESULT }% ✅ (lines, ≥ ${DIFF_COV_LINE_T}%)"
+                if printf '%s\n' "$DIFF_COV_OUT" | grep -q '^NA '; then
+                  printf '%s\n' "$DIFF_COV_OUT" | grep '^NA ' | sed 's/^NA /     n\/a (no executable statements): /'
+                fi
+              elif [ "$DIFF_COV_RC" -eq 1 ]; then
+                echo "❌ BLOCKED - Changed-line coverage below threshold (指南 §10.1)."
+                echo "   Lines: ${DIFF_COV_RESULT#RESULT } (need ≥ ${DIFF_COV_LINE_T}%)"
+                echo "   Branches: ${DIFF_COV_BRANCH#BRANCH } (need ≥ ${DIFF_COV_BRANCH_T}%)"
+                printf '%s\n' "$DIFF_COV_OUT" | grep '^UNCOVERED ' | sed 's/^UNCOVERED /   untested changed lines: /'
+                printf '%s\n' "$DIFF_COV_OUT" | grep '^MISSING ' | sed 's/^MISSING /   no coverage data for: /'
+                echo "   Add tests for the lines listed above, or set diff_coverage_lines in"
+                echo "   .xp-gate/test-profile.yaml if this file genuinely cannot be unit-tested."
+                rm -f "$DIFF_COV_RANGES"
+                exit 1
+              else
+                # #570: not measurable is not a pass. (The global check above already
+                # blocked on a missing/corrupt report; this arm covers the narrower
+                # case where coverage-final.json itself is unreadable.)
+                echo "⚠️  Changed-line coverage could not be measured (coverage-final.json unreadable)."
+                echo "   See: $(printf '%s\n' "$DIFF_COV_OUT" | grep '^ERROR ' | head -1)"
+              fi
+            fi
+            rm -f "$DIFF_COV_RANGES"
+          fi
         else
           # #570: an unparseable report is not a pass. Silently continuing here
           # meant a corrupt or unexpected-shape coverage-summary.json disabled the

package/lib/__tests__/foreign-hooks-global.test.js

@@ -0,0 +1,125 @@
+/**
+ * @test REQ-664
+ * @intent `setup-global` points `core.hooksPath` at `~/.config/xp-gate/hooks`, and
+ *         that setting is GLOBAL — it governs every repository on the machine. So
+ *         any third-party tool that writes hooks into `core.hooksPath` writes into
+ *         a directory xp-gate owns. `git lfs install` does exactly this, and the
+ *         measured result was four hooks xp-gate never installs appearing there:
+ *
+ *           hook-module-resolution.sh  lib/  post-checkout  post-commit
+ *           post-merge  pre-commit  pre-push
+ *
+ *         Two failures followed:
+ *
+ *           1. `doctor` only checked pre-commit / pre-push / post-merge. The extra
+ *              files were neither reported nor explained, so the user had no way to
+ *              learn that a global install had acquired foreign hooks.
+ *           2. `uninstall` did `rmSync(GLOBAL_HOOKS_DIR, {recursive: true})` — the
+ *              whole tree, including the lfs hooks someone else put there. The
+ *              file already had `verifyFileOwnership()`; the `type: 'dir'` branch
+ *              simply did not use it.
+ *
+ *         Deleting another tool's files is the more serious of the two: the user
+ *         loses a working git-lfs setup and has no idea which command did it. So
+ *         uninstall must classify before it removes, and SAY what it found.
+ * @covers AC-670-40, AC-670-41, AC-670-42
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/** Hooks xp-gate itself installs; anything else in the dir is foreign. */
+const XP_GATE_HOOKS = ['pre-commit', 'pre-push', 'post-merge'];
+
+function freshRequire(relPath) {
+  for (const key of Object.keys(require.cache)) {
+    if (key.includes(`${path.sep}npm-package${path.sep}lib${path.sep}`)) {
+      delete require.cache[key];
+    }
+  }
+  return require(relPath);
+}
+
+/** A hooks directory shaped like the measured post-`git lfs install` state. */
+function makeHooksDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'xpg-hooks-'));
+  for (const hook of XP_GATE_HOOKS) {
+    fs.writeFileSync(path.join(dir, hook), '#!/bin/sh\n# xp-gate\n');
+  }
+  // Foreign: two hooks git-lfs installs, plus its support file.
+  fs.writeFileSync(path.join(dir, 'post-checkout'), '#!/bin/sh\ngit lfs post-checkout "$@"\n');
+  fs.writeFileSync(path.join(dir, 'post-commit'), '#!/bin/sh\ngit lfs post-commit "$@"\n');
+  fs.writeFileSync(path.join(dir, 'hook-module-resolution.sh'), '#!/bin/sh\n');
+  return dir;
+}
+
+describe('foreign hooks in the global hooksPath (#664)', () => {
+  it('AC-670-40: the classifier names xp-gate hooks and flags everything else', () => {
+    const { classifyHooksDir } = freshRequire('../doctor');
+    expect(typeof classifyHooksDir).toBe('function');
+
+    const dir = makeHooksDir();
+    try {
+      const result = classifyHooksDir(dir);
+      expect(result.owned.sort()).toEqual([...XP_GATE_HOOKS].sort());
+      // Every foreign entry is reported, not silently dropped. `foreign` holds
+      // { name, source } records, so compare names.
+      const foreignNames = result.foreign.map((f) => f.name);
+      expect(foreignNames).toContain('post-checkout');
+      expect(foreignNames).toContain('post-commit');
+      // lib/ is xp-gate's own shared-library directory, not foreign.
+      expect(foreignNames).not.toContain('lib');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('AC-670-41: git-lfs hooks are identified by source, unknown files stay generic', () => {
+    const { classifyHooksDir } = freshRequire('../doctor');
+    const dir = makeHooksDir();
+    try {
+      const result = classifyHooksDir(dir);
+      // Naming the likely source is what turns a confusing listing into an
+      // actionable message: "git lfs" tells the user which tool to look at.
+      const lfs = result.foreign.filter((f) => f.source === 'git-lfs').map((f) => f.name);
+      expect(lfs).toContain('post-checkout');
+      expect(lfs).toContain('post-commit');
+
+      // A file with no recognizable signature must still be reported, but without
+      // guessing a source it cannot prove.
+      fs.writeFileSync(path.join(dir, 'post-rebase'), '#!/bin/sh\necho mine\n');
+      const again = classifyHooksDir(dir);
+      const unknown = again.foreign.find((f) => f.name === 'post-rebase');
+      expect(unknown).toBeDefined();
+      expect(unknown.source).not.toBe('git-lfs');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('AC-670-42: uninstall refuses to delete a hooks dir holding foreign files', () => {
+    const { planHooksDirRemoval } = freshRequire('../uninstall');
+    expect(typeof planHooksDirRemoval).toBe('function');
+
+    const dir = makeHooksDir();
+    try {
+      const plan = planHooksDirRemoval(dir);
+      // Recursive removal would take git-lfs's files with it, so it must not be
+      // the chosen action while foreign content is present.
+      expect(plan.action).not.toBe('remove-all');
+      expect(plan.foreign.length).toBeGreaterThan(0);
+
+      // A directory holding ONLY xp-gate files is safe to remove wholesale.
+      const clean = fs.mkdtempSync(path.join(os.tmpdir(), 'xpg-hooks-clean-'));
+      for (const hook of XP_GATE_HOOKS) {
+        fs.writeFileSync(path.join(clean, hook), '#!/bin/sh\n# xp-gate\n');
+      }
+      expect(planHooksDirRemoval(clean).action).toBe('remove-all');
+      fs.rmSync(clean, { recursive: true, force: true });
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});