@boyingliu01/xp-gate 0.34.0 → 0.34.1

package/gate-13-compiler-strictness.sh

@@ -501,6 +501,108 @@ gate13_javac_args() {
   printf '%s\n' "-Xlint:all,-processing -d"
 }
 
+# ---------------------------------------------------------------------------
+# AC-670-34 / AC-670-35 (#659) — counting javac lint findings, locale-proof.
+#
+# The previous detector was an allow-list of English `[category]` names applied to
+# `[WARNING]` lines. Two independent ways it returned 0 on defective code:
+#
+#   1. NOVELTY: a JDK adds a category the list does not name (`future-category`),
+#      or the fix relies on the list staying in sync with javac. A fixed allow-list
+#      over an open enum is a fail-OPEN design.
+#   2. LOCALISATION: on a non-English build javac's own hint drifts, and the
+#      `[WARNING]` prefix may too. Measured on a zh_CN Maven build, the tell is
+#      "使用了未经检查或不安全的操作 ... 请使用 -Xlint:unchecked 重新编译" -- a message
+#      javac emits precisely when -Xlint was NOT in effect.
+#
+# Fail-closed policy (#499/#570) applied to text matching: count any bracketed
+# lowercase category (whatever it is named), and treat javac's "you should have
+# used -Xlint" hint as a finding too -- the code has an unchecked/unsafe operation
+# whether or not the flag that would name it was on.
+#
+# Prints a single integer. Never fails (always exits 0).
+# ---------------------------------------------------------------------------
+gate13_count_lint_findings() {
+  local src="${1:-}"
+  [ -n "$src" ] || src=$(cat)
+  printf '%s\n' "$src" | awk '
+    BEGIN { n = 0 }
+    # Any bracketed lowercase category: covers the whole javac -Xlint enum and any
+    # later addition to it. Restricted to lowercase/digit/hyphen so a Maven
+    # `[WARNING]` with no category, or a `[INFO]` banner, is not counted.
+    /\[[a-z][a-z0-9-]*\]/ { n++; next }
+    # javac localised or English: "warning:" prefix at line start.
+    /^[[:space:]]*warning:/ { n++; next }
+    # Unchecked/unsafe operations reported from any locale. The English and Chinese
+    # wordings are both matched; anything else falls through to the category rule
+    # above, which is marker-based and therefore locale-independent.
+    /unchecked|unsafe|未经检查|不安全/ { n++; next }
+    END { print n + 0 }
+  '
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# AC-670-32 (#659) — PROVE that -Xlint takes effect, do not assume it.
+#
+# "Can assemble the flag" is not "the flag works". `compilerArgument` is a single
+# appended argument, so `-Xlint:all,-processing` (a comma list) is not reliably
+# passed through -- measured on Maven 3.9.12 + JDK 21, where the injected run
+# produced no `[category]` markers at all and javac printed its own
+# "recompile with -Xlint:unchecked" hint instead.
+#
+# The only honest test is a probe: compile a source that is KNOWN to warn (a raw
+# type is the canonical one -- measured to emit `[rawtypes]` under -Xlint:all and
+# nothing otherwise) using the exact same command shape, and look for the marker.
+#
+# Returns 0 = injection proven effective, 1 = not proven (caller must degrade).
+# ---------------------------------------------------------------------------
+gate13_maven_lint_effective() {
+  local mvn_bin="${1:-mvn}"
+  local budget tmpd probe out rc
+  budget=$(gate13_timeout_budget)
+  tmpd="${TMPDIR:-/tmp}/gate13_probe_$$"
+  mkdir -p "$tmpd" || return 1
+
+  # Raw type on purpose: javac emits NOTHING for this without -Xlint:all, so a
+  # silent run proves the flag did not reach the compiler.
+  probe="$tmpd/Gate13Probe.java"
+  cat > "$probe" <<'PROBE'
+import java.util.ArrayList;
+import java.util.List;
+public class Gate13Probe {
+  private List items = new ArrayList();
+  public void add(Object o) { items.add(o); }
+}
+PROBE
+
+  # Same argument shape as gate13_maven_args(), against the probe only. A single
+  # -Djavac directly is not what we are testing -- the whole point is whether the
+  # MAVEN injection path works.
+  if command -v timeout >/dev/null 2>&1; then
+    out=$(timeout "$budget" javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  else
+    out=$(javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  fi
+  rc=$?
+  rm -rf "$tmpd"
+
+  # If the DIRECT javac probe cannot even produce a rawtypes warning, the JDK
+  # itself is not behaving as measured, so nothing about the Maven path can be
+  # concluded -- report "not proven" rather than "effective".
+  if [ "$rc" -ne 0 ]; then
+    return 1
+  fi
+  printf '%s\n' "$out" | grep -q 'rawtypes'
+}
+
+# Is `-Xlint` reachable at all on this machine? The Maven probe only makes sense
+# when a raw-type warning is obtainable; when javac cannot produce one, callers
+# stay in degraded mode instead of claiming a clean lint.
+gate13_maven_probe_available() {
+  command -v javac >/dev/null 2>&1
+}
+
 gate13_java_sources() {
   git diff --cached --name-only --diff-filter=d -- '*.java' 2>/dev/null
 }
@@ -574,6 +676,23 @@ gate13_maven_injection_reliable() {
     return 1
   fi
 
+  # AC-670-33 (#659): every check above verifies that the arguments can be
+  # ASSEMBLED. None of them verifies that they take EFFECT, which is exactly how a
+  # pom declaring plugin 3.13.0 was declared "reliable" while Maven ran with no
+  # -Xlint at all and Gate 13 reported PASS on a file javac warned about 3 times.
+  #
+  # So prove it: one probe compile of a known-raw-type source through the same
+  # command shape. If the marker does not appear, injection did not happen and the
+  # caller must degrade -- "could not verify" is never "verified fine" (#499/#570).
+  if ! gate13_maven_probe_available; then
+    printf 'javac unavailable; -Xlint injection cannot be probed\n' >&2
+    return 1
+  fi
+  if ! gate13_maven_lint_effective "${MVN_BIN:-mvn}"; then
+    printf 'probe compile did not produce a [rawtypes] marker; -Xlint injection is NOT effective\n' >&2
+    return 1
+  fi
+
   return 0
 }
 
@@ -704,14 +823,20 @@ gate13_run_java_analysis() {
       fi
 
       # Count javac's lint output. Maven prefixes it with "[WARNING] ".
-      mvn_findings=$(printf '%s\n' "$mvn_out" \
-        | grep -cE '\[WARNING\].*\[(rawtypes|unchecked|deprecation|fallthrough|finally|cast|static|try|overrides|overloads|serial|synchronization|varargs|divzero|empty|exports|module|opens|options|path|processing|removal|requires|text-blocks|this-escape)\]' \
-        | tr -d '[:space:]')
+      #
+      # #659: this used to be an English `[WARNING]...[allow-listed-category]`
+      # regex. Applied to a localised build -- or to a JDK category the list does
+      # not name -- it returned 0 on code javac had warned about, and the gate then
+      # printed PASSED. The shared counter below is marker- and locale-proof and
+      # fails closed (#499/#570). It lives in one place so the Maven path and the
+      # direct-javac path can never disagree about what counts as a finding.
+      mvn_findings=$(gate13_count_lint_findings "$mvn_out")
       mvn_findings=${mvn_findings:-0}
+      case "$mvn_findings" in ''|*[!0-9]*) mvn_findings=0 ;; esac
 
       if [ "$mvn_findings" -gt 0 ]; then
         printf '%s\n' "$mvn_out" \
-          | grep -E '\[WARNING\].*\[[a-z-]+\]' | head -10 | sed 's/^/        /'
+          | grep -E '\[[a-z][a-z0-9-]*\]|warning:' | head -10 | sed 's/^/        /'
         echo "     ❌ ${mvn_findings} javac -Xlint finding(s)"
         return "$GATE13_FAIL"
       fi

package/gate-4.sh

@@ -46,7 +46,14 @@ java_coverage_note() {
     esac
   done
   [ -n "$_has_java" ] || return 0
-  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see docs/java-principles-coverage.md)"
+  # #628: `docs/` is not in the npm package's `files` list, so pointing a user at
+  # `docs/java-principles-coverage.md` was a dead path in every installed project --
+  # the note told them to read a file that does not exist on their machine. Cite the
+  # upstream URL instead, and keep the local path only when the doc is actually
+  # present (i.e. when running inside this repo).
+  local _where="https://github.com/boyingliu01/xp-gate/blob/main/docs/java-principles-coverage.md"
+  [ -f "docs/java-principles-coverage.md" ] && _where="docs/java-principles-coverage.md"
+  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see $_where)"
 }
 
  2>&1 echo ""

package/hooks/gate-13-compiler-strictness.sh

@@ -501,6 +501,108 @@ gate13_javac_args() {
   printf '%s\n' "-Xlint:all,-processing -d"
 }
 
+# ---------------------------------------------------------------------------
+# AC-670-34 / AC-670-35 (#659) — counting javac lint findings, locale-proof.
+#
+# The previous detector was an allow-list of English `[category]` names applied to
+# `[WARNING]` lines. Two independent ways it returned 0 on defective code:
+#
+#   1. NOVELTY: a JDK adds a category the list does not name (`future-category`),
+#      or the fix relies on the list staying in sync with javac. A fixed allow-list
+#      over an open enum is a fail-OPEN design.
+#   2. LOCALISATION: on a non-English build javac's own hint drifts, and the
+#      `[WARNING]` prefix may too. Measured on a zh_CN Maven build, the tell is
+#      "使用了未经检查或不安全的操作 ... 请使用 -Xlint:unchecked 重新编译" -- a message
+#      javac emits precisely when -Xlint was NOT in effect.
+#
+# Fail-closed policy (#499/#570) applied to text matching: count any bracketed
+# lowercase category (whatever it is named), and treat javac's "you should have
+# used -Xlint" hint as a finding too -- the code has an unchecked/unsafe operation
+# whether or not the flag that would name it was on.
+#
+# Prints a single integer. Never fails (always exits 0).
+# ---------------------------------------------------------------------------
+gate13_count_lint_findings() {
+  local src="${1:-}"
+  [ -n "$src" ] || src=$(cat)
+  printf '%s\n' "$src" | awk '
+    BEGIN { n = 0 }
+    # Any bracketed lowercase category: covers the whole javac -Xlint enum and any
+    # later addition to it. Restricted to lowercase/digit/hyphen so a Maven
+    # `[WARNING]` with no category, or a `[INFO]` banner, is not counted.
+    /\[[a-z][a-z0-9-]*\]/ { n++; next }
+    # javac localised or English: "warning:" prefix at line start.
+    /^[[:space:]]*warning:/ { n++; next }
+    # Unchecked/unsafe operations reported from any locale. The English and Chinese
+    # wordings are both matched; anything else falls through to the category rule
+    # above, which is marker-based and therefore locale-independent.
+    /unchecked|unsafe|未经检查|不安全/ { n++; next }
+    END { print n + 0 }
+  '
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# AC-670-32 (#659) — PROVE that -Xlint takes effect, do not assume it.
+#
+# "Can assemble the flag" is not "the flag works". `compilerArgument` is a single
+# appended argument, so `-Xlint:all,-processing` (a comma list) is not reliably
+# passed through -- measured on Maven 3.9.12 + JDK 21, where the injected run
+# produced no `[category]` markers at all and javac printed its own
+# "recompile with -Xlint:unchecked" hint instead.
+#
+# The only honest test is a probe: compile a source that is KNOWN to warn (a raw
+# type is the canonical one -- measured to emit `[rawtypes]` under -Xlint:all and
+# nothing otherwise) using the exact same command shape, and look for the marker.
+#
+# Returns 0 = injection proven effective, 1 = not proven (caller must degrade).
+# ---------------------------------------------------------------------------
+gate13_maven_lint_effective() {
+  local mvn_bin="${1:-mvn}"
+  local budget tmpd probe out rc
+  budget=$(gate13_timeout_budget)
+  tmpd="${TMPDIR:-/tmp}/gate13_probe_$$"
+  mkdir -p "$tmpd" || return 1
+
+  # Raw type on purpose: javac emits NOTHING for this without -Xlint:all, so a
+  # silent run proves the flag did not reach the compiler.
+  probe="$tmpd/Gate13Probe.java"
+  cat > "$probe" <<'PROBE'
+import java.util.ArrayList;
+import java.util.List;
+public class Gate13Probe {
+  private List items = new ArrayList();
+  public void add(Object o) { items.add(o); }
+}
+PROBE
+
+  # Same argument shape as gate13_maven_args(), against the probe only. A single
+  # -Djavac directly is not what we are testing -- the whole point is whether the
+  # MAVEN injection path works.
+  if command -v timeout >/dev/null 2>&1; then
+    out=$(timeout "$budget" javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  else
+    out=$(javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  fi
+  rc=$?
+  rm -rf "$tmpd"
+
+  # If the DIRECT javac probe cannot even produce a rawtypes warning, the JDK
+  # itself is not behaving as measured, so nothing about the Maven path can be
+  # concluded -- report "not proven" rather than "effective".
+  if [ "$rc" -ne 0 ]; then
+    return 1
+  fi
+  printf '%s\n' "$out" | grep -q 'rawtypes'
+}
+
+# Is `-Xlint` reachable at all on this machine? The Maven probe only makes sense
+# when a raw-type warning is obtainable; when javac cannot produce one, callers
+# stay in degraded mode instead of claiming a clean lint.
+gate13_maven_probe_available() {
+  command -v javac >/dev/null 2>&1
+}
+
 gate13_java_sources() {
   git diff --cached --name-only --diff-filter=d -- '*.java' 2>/dev/null
 }
@@ -574,6 +676,23 @@ gate13_maven_injection_reliable() {
     return 1
   fi
 
+  # AC-670-33 (#659): every check above verifies that the arguments can be
+  # ASSEMBLED. None of them verifies that they take EFFECT, which is exactly how a
+  # pom declaring plugin 3.13.0 was declared "reliable" while Maven ran with no
+  # -Xlint at all and Gate 13 reported PASS on a file javac warned about 3 times.
+  #
+  # So prove it: one probe compile of a known-raw-type source through the same
+  # command shape. If the marker does not appear, injection did not happen and the
+  # caller must degrade -- "could not verify" is never "verified fine" (#499/#570).
+  if ! gate13_maven_probe_available; then
+    printf 'javac unavailable; -Xlint injection cannot be probed\n' >&2
+    return 1
+  fi
+  if ! gate13_maven_lint_effective "${MVN_BIN:-mvn}"; then
+    printf 'probe compile did not produce a [rawtypes] marker; -Xlint injection is NOT effective\n' >&2
+    return 1
+  fi
+
   return 0
 }
 
@@ -704,14 +823,20 @@ gate13_run_java_analysis() {
       fi
 
       # Count javac's lint output. Maven prefixes it with "[WARNING] ".
-      mvn_findings=$(printf '%s\n' "$mvn_out" \
-        | grep -cE '\[WARNING\].*\[(rawtypes|unchecked|deprecation|fallthrough|finally|cast|static|try|overrides|overloads|serial|synchronization|varargs|divzero|empty|exports|module|opens|options|path|processing|removal|requires|text-blocks|this-escape)\]' \
-        | tr -d '[:space:]')
+      #
+      # #659: this used to be an English `[WARNING]...[allow-listed-category]`
+      # regex. Applied to a localised build -- or to a JDK category the list does
+      # not name -- it returned 0 on code javac had warned about, and the gate then
+      # printed PASSED. The shared counter below is marker- and locale-proof and
+      # fails closed (#499/#570). It lives in one place so the Maven path and the
+      # direct-javac path can never disagree about what counts as a finding.
+      mvn_findings=$(gate13_count_lint_findings "$mvn_out")
       mvn_findings=${mvn_findings:-0}
+      case "$mvn_findings" in ''|*[!0-9]*) mvn_findings=0 ;; esac
 
       if [ "$mvn_findings" -gt 0 ]; then
         printf '%s\n' "$mvn_out" \
-          | grep -E '\[WARNING\].*\[[a-z-]+\]' | head -10 | sed 's/^/        /'
+          | grep -E '\[[a-z][a-z0-9-]*\]|warning:' | head -10 | sed 's/^/        /'
         echo "     ❌ ${mvn_findings} javac -Xlint finding(s)"
         return "$GATE13_FAIL"
       fi

package/hooks/gate-4.sh

@@ -46,7 +46,14 @@ java_coverage_note() {
     esac
   done
   [ -n "$_has_java" ] || return 0
-  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see docs/java-principles-coverage.md)"
+  # #628: `docs/` is not in the npm package's `files` list, so pointing a user at
+  # `docs/java-principles-coverage.md` was a dead path in every installed project --
+  # the note told them to read a file that does not exist on their machine. Cite the
+  # upstream URL instead, and keep the local path only when the doc is actually
+  # present (i.e. when running inside this repo).
+  local _where="https://github.com/boyingliu01/xp-gate/blob/main/docs/java-principles-coverage.md"
+  [ -f "docs/java-principles-coverage.md" ] && _where="docs/java-principles-coverage.md"
+  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see $_where)"
 }
 
  2>&1 echo ""

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 });
+    }
+  });
+});

package/lib/__tests__/uninstall-global-residue.test.js

@@ -0,0 +1,160 @@
+/**
+ * @test REQ-663
+ * @intent `xp-gate uninstall` presents itself as the inverse of `init`, but it only
+ *         removed `hooks/` + `adapters/` + `core.hooksPath`. After
+ *         `setup-global` then `uninstall --global --force`, the tool printed
+ *         "Uninstall complete" while leaving behind ~1000 files:
+ *
+ *           ~/.config/xp-gate/modules/         principles/ mutation/ mock-policy/
+ *           ~/.config/xp-gate/node_modules/    js-yaml / zod / argparse ...
+ *           ~/.config/xp-gate/package.json
+ *           ~/.config/xp-gate/package-lock.json
+ *           ~/.config/xp-gate/xp-gate.json     manifest + installedSkills record
+ *           ~/.xp-gate/version-cache.json
+ *
+ *         And skills were never in scope at all: 12 skills stayed in
+ *         ~/.qoder/skills/ and ~/.config/opencode/skills/, which the next `init`
+ *         then treated as already-installed.
+ *
+ *         The residue is not cosmetic. A leftover `node_modules/` makes the NEXT
+ *         `setup-global` skip its install ("module runtime deps → ... node_modules"
+ *         reuses whatever is there), so a stale dependency tree survives an
+ *         upgrade; and a leftover `xp-gate.json` carries the previous version's
+ *         `manifest` and `lastInit`, which `doctor` then reports as the CURRENT
+ *         installation.
+ *
+ *         Two rules the fix must respect, both from the issue:
+ *           - a user config (`.delphi-config.json`) is user DATA, not residue --
+ *             keep it, but SAY SO instead of leaving it silently;
+ *           - never delete a skill directory the user has edited. Only remove one
+ *             whose content still matches the bundled copy.
+ * @covers AC-670-37, AC-670-38, AC-670-39
+ */
+'use strict';
+
+// describe/it/expect/beforeEach/afterEach are vitest globals in this repo's config;
+// requiring them from 'vitest' fails because these tests are CommonJS.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/** Build a throwaway HOME so the plan is computed against a controlled tree. */
+function makeHome() {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'xpg-uninst-'));
+  return home;
+}
+
+/**
+ * Reproduce the on-disk shape `xp-gate setup-global` leaves behind, including the
+ * parts that were measured as residue in #663.
+ */
+function seedGlobalInstall() {
+  const configDir = path.join(process.env.HOME, '.config', 'xp-gate');
+  for (const rel of ['hooks', 'adapters', 'modules/principles', 'node_modules/js-yaml']) {
+    fs.mkdirSync(path.join(configDir, rel), { recursive: true });
+    fs.writeFileSync(path.join(configDir, rel, 'index.js'), 'module.exports = {};\n');
+  }
+  for (const file of ['package.json', 'package-lock.json', 'xp-gate.json']) {
+    fs.writeFileSync(path.join(configDir, file), '{}\n');
+  }
+  // User data: must survive, and must be reported.
+  fs.writeFileSync(path.join(configDir, '.delphi-config.json'), '{}\n');
+}
+
+
+describe('uninstall --global plans the whole installation, not just hooks (#663)', () => {
+  let home;
+  const savedEnv = {};
+
+  beforeEach(() => {
+    home = makeHome();
+    savedEnv.HOME = process.env.HOME;
+    savedEnv.USERPROFILE = process.env.USERPROFILE;
+    process.env.HOME = home;
+    process.env.USERPROFILE = home;
+  });
+
+  afterEach(() => {
+    process.env.HOME = savedEnv.HOME;
+    process.env.USERPROFILE = savedEnv.USERPROFILE;
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  /**
+   * Load a module fresh so it re-reads HOME. Every lib reads os.homedir() at call
+   * time, but a cached module still holds `GLOBAL_DIRS` values captured earlier.
+   */
+  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);
+  }
+
+  it('AC-670-37: modules, node_modules and the manifest files are all in scope', () => {
+    const { buildPlan } = freshRequire('../uninstall');
+    expect(typeof buildPlan).toBe('function');
+
+    // buildPlan only schedules what actually exists, so the fixture has to look
+    // like a real `setup-global` install -- otherwise this asserts nothing.
+    seedGlobalInstall();
+
+    const plan = buildPlan('global');
+    const paths = plan.filter((step) => step.path).map((step) => step.path.split(path.sep).join('/'));
+
+    // Each of these was measured residue. A plan that omits any of them reports
+    // "complete" over an installation that is still there.
+    for (const required of ['modules', 'node_modules', 'package.json', 'package-lock.json', 'xp-gate.json']) {
+      expect(
+        paths.some((p) => p.endsWith(required)),
+        `${required} is missing from the uninstall plan (measured residue, #663)`,
+      ).toBe(true);
+    }
+  });
+
+  it('AC-670-38: user config is retained and reported, never silently kept', () => {
+    const { buildPlan } = freshRequire('../uninstall');
+    seedGlobalInstall();
+    const plan = buildPlan('global');
+    // Deletion steps only: a RETAIN step names the file precisely because it is
+    // being kept, so including it here would assert the opposite of the intent.
+    const deletedPaths = plan
+      .filter((step) => step.path && step.retain !== true && step.type !== 'retain')
+      .map((step) => step.path.split(path.sep).join('/'));
+
+    // `.delphi-config.json` holds the user's expert/model choice -- it is data, so
+    // it must appear in no deletion step. (The --purge branch is a separate,
+    // explicitly destructive path and is not what this plan describes.)
+    expect(deletedPaths.some((p) => p.endsWith('.delphi-config.json'))).toBe(false);
+    // Not deleting it is only half the fix: the summary has to name it.
+    const retained = plan.filter((step) => step.retain === true);
+    expect(retained.length, 'no step declares a retention, so the summary cannot report one').toBeGreaterThan(0);
+  });
+
+  it('AC-670-39: an edited skill directory is never scheduled for deletion', () => {
+    const { planSkillRemovals } = freshRequire('../uninstall');
+    expect(typeof planSkillRemovals).toBe('function');
+
+    const bundled = path.join(home, 'bundle', 'skills');
+    const installedRoot = path.join(home, '.qoder', 'skills');
+    for (const [dir, body] of [
+      [path.join(bundled, 'clean-skill'), 'bundled body\n'],
+      [path.join(installedRoot, 'clean-skill'), 'bundled body\n'],
+      [path.join(bundled, 'edited-skill'), 'bundled body\n'],
+      [path.join(installedRoot, 'edited-skill'), 'bundled body\n// user edit\n'],
+    ]) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'SKILL.md'), body);
+    }
+
+    const removals = planSkillRemovals(['clean-skill', 'edited-skill'], installedRoot, bundled);
+    const names = removals.map((r) => path.basename(r.path));
+
+    // Untouched -> remove. This is the residue the issue is about.
+    expect(names).toContain('clean-skill');
+    // Edited -> keep. Deleting a user's modifications is worse than residue.
+    expect(names).not.toContain('edited-skill');
+  });
+});