@boyingliu01/xp-gate 0.19.2 → 0.20.0

package/lib/__tests__/doctor-executed-surface.test.js

@@ -0,0 +1,209 @@
+/**
+ * @test REQ-495 Round 3: only the module the hook resolves may be reported as executed
+ * @intent Round 2 的两位专家指向同一处缺陷：F5 把项目 tier 无条件标成"executed from the
+ *         project tier"，而 pre-commit 的解析顺序是 ADAPTER_DIR 优先取全局目录
+ *         （githooks/pre-commit:34-35），语言适配器在项目 tier 只经 nested 命中
+ *         （:67-69），平铺副本在全局安装存在时根本不执行。于是 doctor 既会把不执行的
+ *         文件判成 FAIL（R1-2 那一类"断言了假方向"的 FAIL），又因为修复面只走全局目录
+ *         而让该 FAIL 永远清不掉（永久 exit 1）。本文件把"哪个路径被执行"收敛到
+ *         resolveExecutedModuleDirs()+executedModulePath() 这一个模型上：执行的才计入
+ *         issues 并可被 sync 清除，不执行的作为 residue 报告并给出绝对路径与手工处置，
+ *         不计入 issues。AC-495-17 补上旧 tier 列表完全忽略的第 4 层（SCRIPT_DIR），
+ *         AC-495-19 钉住"读不到就拒绝覆盖"的守卫缝隙。
+ * @covers AC-495-14, AC-495-15, AC-495-16, AC-495-17, AC-495-18, AC-495-19
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const REPO_ADAPTER = '#!/bin/bash\nfixed_count_guard\n';
+const STALE_FLAT = '#!/bin/bash\nstale_echo_zero\n';
+// One-way stale: every line it holds is also in the repo, so the copy guard lets
+// the sync through. The divergence cases keep STALE_FLAT and must refuse.
+const SUBSET_FLAT = '#!/bin/bash\n';
+
+function write(file, text) {
+  mkdirSync(join(file, '..'), { recursive: true });
+  writeFileSync(file, text);
+}
+
+function tempRoot(prefix) {
+  return mkdtempSync(join(tmpdir(), `xp-gate-${prefix}-`));
+}
+
+/**
+ * A tree carrying all the tiers the hook can resolve into, so precedence between
+ * tiers is part of the fixture instead of an assumption.
+ */
+function tree(overrides = {}) {
+  const root = tempRoot('tier');
+  const repoDir = join(root, 'repo');
+  const repoHooks = join(repoDir, 'githooks');
+  const globalAdapters = join(root, 'global', 'adapters');
+  const scriptDir = join(root, 'global', 'hooks');
+  for (const dir of [join(repoHooks, 'adapters'), globalAdapters, join(globalAdapters, 'adapters'), scriptDir]) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Canonical repo source of truth: nested language adapter, flat gate module.
+  write(join(repoHooks, 'adapter-common.sh'), '#!/bin/bash\nshared\n');
+  write(join(repoHooks, 'pre-commit'), '#!/bin/bash\necho repo\n');
+  write(join(repoHooks, 'adapters', 'iac.sh'), REPO_ADAPTER);
+  write(join(repoHooks, 'gate-4.sh'), '#!/bin/bash\ngate_a\ngate_b\n');
+
+  // Installed global tier: the installer's nested copy is current...
+  write(join(globalAdapters, 'adapter-common.sh'), '#!/bin/bash\nshared\n');
+  write(join(globalAdapters, 'adapters', 'iac.sh'), REPO_ADAPTER);
+  if (overrides.globalFlatIac) write(join(globalAdapters, 'iac.sh'), overrides.globalFlatIac);
+  if (overrides.globalGate4) write(join(globalAdapters, 'gate-4.sh'), overrides.globalGate4);
+
+  // Project-tier flat copy (gitignored installer residue): stale by default.
+  if (overrides.projectFlatIac !== null) {
+    write(join(repoHooks, 'iac.sh'), overrides.projectFlatIac || STALE_FLAT);
+  }
+
+  return {
+    root,
+    repoDir,
+    repoHooks,
+    globalAdapters,
+    scriptDir,
+    projectFlatIac: join(repoHooks, 'iac.sh'),
+  };
+}
+
+function ctxFor(t, extra = {}) {
+  return {
+    repoRoot: t.repoDir,
+    repoHooks: t.repoHooks,
+    globalAdapterDir: t.globalAdapters,
+    projectGithooks: t.repoHooks,
+    scriptDir: t.scriptDir,
+    ...extra,
+  };
+}
+
+function drift(t, extra = {}) {
+  const { diagnoseModuleDrift } = require('../doctor');
+  return diagnoseModuleDrift(ctxFor(t, extra));
+}
+
+function checkOf(result, name) {
+  return result.checks.find((c) => c.name === name);
+}
+
+describe('doctor executed surface (#495 Round 3)', () => {
+  it('AC-495-14: the executed copy is the flat global one the hook resolves first, so its staleness is a FAIL', () => {
+    const t = tree({ globalFlatIac: STALE_FLAT });
+    const result = drift(t);
+    const check = checkOf(result, 'Module drift: iac.sh');
+    expect(check, 'a stale copy the hook executes must FAIL').toBeDefined();
+    expect(check.status).toBe('FAIL');
+    expect(result.issues).toBe(1);
+  });
+
+  it('AC-495-15: with a global install present, a flat copy in the project githooks/ does NOT execute and is reported as residue, not as drift', () => {
+    const t = tree({ projectFlatIac: undefined });
+    const result = drift(t);
+    const residue = result.checks.find((c) => /Non-executed copy: iac\.sh/.test(c.name));
+    expect(residue, 'the project-tier flat copy must still be surfaced').toBeDefined();
+    // The hook consults $PROJECT_GITHOOKS/adapters/<lang>.sh only (pre-commit:67-69),
+    // never a flat project copy, so claiming it "executes" would repeat the R1-2 defect.
+    expect(residue.status).not.toBe('FAIL');
+    expect(result.issues, 'a copy nothing executes cannot be an unrepairable FAIL').toBe(0);
+    // Actionable: the offending absolute path, and the manual remedy (#500 is still open).
+    expect(residue.detail).toContain(t.projectFlatIac);
+    expect(residue.detail, 'residue must name itself as not executed').toMatch(/not executed|does not execute/i);
+    expect(residue.detail, 'residue must say how to get rid of it').toMatch(/gitignore|residue|remove/i);
+  });
+
+  it('AC-495-16: the same project-tier flat copy IS executed once ADAPTER_DIR resolves to the project tier, and then it FAILs', () => {
+    const t = tree({ projectFlatIac: undefined });
+    // No global install -> pre-commit:36-37 resolves ADAPTER_DIR to the repo.
+    const result = drift(t, { globalAdapterDir: join(t.root, 'no-global-install') });
+    const check = result.checks.find((c) => /iac\.sh$/.test(c.name));
+    expect(check, 'the executed project-tier copy must be diagnosed').toBeDefined();
+    expect(check.status).toBe('FAIL');
+    expect(result.issues).toBe(1);
+  });
+
+  it('AC-495-17: gate modules follow GATE_DIR down to the hook\'s last tier ($SCRIPT_DIR)', () => {
+    // The installed hooks dir is the only tier carrying adapter-common.sh and
+    // gate-3.sh, so ADAPTER_DIR == GATE_DIR == $SCRIPT_DIR (pre-commit:39, 80-81)
+    // and a stale gate module lives there -- invisible to the old two-tier walk.
+    const root = tempRoot('scriptdir');
+    const repoDir = join(root, 'repo');
+    const repoHooks = join(repoDir, 'githooks');
+    const scriptDir = join(root, 'installed', 'hooks');
+    mkdirSync(join(repoHooks, 'adapters'), { recursive: true });
+    write(join(repoHooks, 'pre-commit'), '#!/bin/bash\necho repo\n');
+    write(join(repoHooks, 'gate-4.sh'), '#!/bin/bash\ngate_a\ngate_b\n');
+    // A repo without adapter-common.sh/gate-3.sh installed alongside: the hook's
+    // fallback chain ends at SCRIPT_DIR.
+    write(join(scriptDir, 'adapter-common.sh'), '#!/bin/bash\nshared\n');
+    write(join(scriptDir, 'gate-3.sh'), '#!/bin/bash\ngate3\n');
+    // One-way stale, so this test judges reachability of the repair, not the
+    // divergence guard (which AC-495-05 already pins).
+    write(join(scriptDir, 'gate-4.sh'), '#!/bin/bash\ngate_a\n');
+
+    const { diagnoseModuleDrift, syncModulesFromRepo } = require('../doctor');
+    const ctx = {
+      repoRoot: repoDir,
+      repoHooks,
+      globalAdapterDir: join(root, 'nothing', 'adapters'),
+      projectGithooks: repoHooks,
+      scriptDir,
+    };
+    const result = diagnoseModuleDrift(ctx);
+    const check = result.checks.find((c) => /gate-4\.sh$/.test(c.name));
+    expect(check, 'an executed copy under the installed hooks dir is invisible to doctor').toBeDefined();
+    expect(check.status).toBe('FAIL');
+    expect(result.issues).toBe(1);
+
+    // And the repair reaches the same tier, so the FAIL is not permanent.
+    const synced = syncModulesFromRepo(ctx);
+    expect(synced.synced).toContain('gate-4.sh');
+    expect(readFileSync(join(scriptDir, 'gate-4.sh'), 'utf8')).toContain('gate_b');
+    expect(diagnoseModuleDrift(ctx).issues).toBe(0);
+  });
+
+  it('AC-495-18: every FAIL the resolution can produce, syncModulesFromRepo can clear', () => {
+    const { syncModulesFromRepo, diagnoseModuleDrift } = require('../doctor');
+    const t = tree({ globalFlatIac: SUBSET_FLAT, projectFlatIac: null });
+    const ctx = ctxFor(t);
+    expect(diagnoseModuleDrift(ctx).issues).toBe(1);
+
+    const synced = syncModulesFromRepo(ctx);
+    expect(synced.synced).toContain('iac.sh');
+    expect(readFileSync(join(t.globalAdapters, 'iac.sh'), 'utf8')).toContain('fixed_count_guard');
+    expect(diagnoseModuleDrift(ctx).issues).toBe(0);
+  });
+
+  it('AC-495-18b: the sync never deletes or rewrites non-executed residue on its own initiative', () => {
+    const { syncModulesFromRepo } = require('../doctor');
+    const t = tree({ globalFlatIac: SUBSET_FLAT });
+    const before = readFileSync(t.projectFlatIac, 'utf8');
+    const synced = syncModulesFromRepo(ctxFor(t));
+    expect(synced.synced).toContain('iac.sh');
+    expect(readFileSync(t.projectFlatIac, 'utf8')).toBe(before);
+  });
+
+  it('AC-495-19: an unreadable destination is refused, not overwritten', () => {
+    const { copyGuardDecision } = require('../doctor');
+    const root = tempRoot('guard');
+    const source = join(root, 'source.sh');
+    write(source, '#!/bin/bash\nrepo_line\n');
+    // A directory where a file is expected: readFileSync throws, so the delta is unknown.
+    const targetIsDir = join(root, 'target.sh');
+    mkdirSync(targetIsDir, { recursive: true });
+
+    expect(copyGuardDecision(source, targetIsDir, false).refuse, 'unknown content must never be overwritten silently').toBe(true);
+    // Content known to be a subset still syncs; an explicit force still proceeds.
+    const targetOk = join(root, 'stale.sh');
+    write(targetOk, '#!/bin/bash\n');
+    expect(copyGuardDecision(source, targetOk, false).refuse).toBe(false);
+    expect(copyGuardDecision(source, targetIsDir, true).forced).toBe(true);
+    expect(existsSync(targetIsDir)).toBe(true);
+  });
+});

package/lib/__tests__/doctor-hook-drift.test.js

@@ -0,0 +1,329 @@
+/**
+ * @test REQ-451 xp-gate doctor detects stale global hook copies
+ * @intent Detect when the hooks actually executed (core.hooksPath) drift from the
+ *         repository's source-of-truth githooks/, and report the direction of drift
+ * @covers AC-451-01 (drift is reported with a direction)
+ * @covers AC-451-02 (matching copies report no drift)
+ * @covers AC-451-03 (non-repo / no-githooks contexts stay unchanged)
+ *
+ * Issue #451: editing githooks/pre-commit in the repo silently has no effect,
+ * because core.hooksPath points at an installed copy under ~/.config/xp-gate/hooks.
+ * The source-of-truth hooks are never executed on a developer machine, and nothing
+ * reports how far the installed copy has drifted or in which direction.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DESCRIBE_ID = String(Math.random().toString(36).slice(2, 8));
+
+describe('doctor hook source-of-truth drift (#451)', () => {
+  let tmpHome;
+  let tmpProject;
+  let originalHome;
+  let originalUserProfile;
+  let originalXpGateCacheDir;
+
+  beforeAll(() => {
+    originalHome = process.env.HOME;
+    originalUserProfile = process.env.USERPROFILE;
+    originalXpGateCacheDir = process.env.XP_GATE_CACHE_DIR;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), `xp-gate-451-home-${DESCRIBE_ID}-`));
+    tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), `xp-gate-451-proj-${DESCRIBE_ID}-`));
+    process.env.HOME = tmpHome;
+    process.env.USERPROFILE = tmpHome;
+  });
+
+  afterAll(() => {
+    // Every path this suite touches is passed in explicitly, so there is no cwd
+    // to restore (process.chdir is unavailable inside vitest workers anyway).
+    process.env.HOME = originalHome;
+    process.env.USERPROFILE = originalUserProfile;
+    process.env.XP_GATE_CACHE_DIR = originalXpGateCacheDir;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+    fs.rmSync(tmpProject, { recursive: true, force: true });
+  });
+
+  /**
+   * Build a repo-like tree with a canonical githooks/ and an installed copy.
+   * The installed copy lives outside the repo, mirroring the real layout.
+   */
+  function scaffold({ repoPreCommit, installedPreCommit }) {
+    const repoRoot = path.join(tmpProject, 'repo');
+    const repoHooks = path.join(repoRoot, 'githooks');
+    const installedHooks = path.join(tmpHome, '.config', 'xp-gate', 'hooks');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+    fs.rmSync(installedHooks, { recursive: true, force: true });
+    fs.mkdirSync(repoHooks, { recursive: true });
+    fs.mkdirSync(path.join(repoRoot, '.git'), { recursive: true });
+    fs.mkdirSync(installedHooks, { recursive: true });
+
+    fs.writeFileSync(path.join(repoHooks, 'pre-commit'), repoPreCommit);
+    fs.writeFileSync(
+      path.join(installedHooks, 'pre-commit'),
+      installedPreCommit === undefined ? repoPreCommit : installedPreCommit
+    );
+
+    return { repoRoot, repoHooks, installedHooks };
+  }
+
+  /** require the module fresh so it picks up the patched HOME. */
+  function loadDoctor() {
+    for (const key of Object.keys(require.cache)) {
+      if (key.includes(`${path.sep}lib${path.sep}doctor.js`)) delete require.cache[key];
+    }
+    return require('../doctor');
+  }
+
+  // -------------------------------------------------------------------------
+  // AC-451-01: drift is detected and its direction reported
+  // -------------------------------------------------------------------------
+
+  it('AC-451-01: reports the installed hook is NEWER than the repo copy', () => {
+    const repoBody = '#!/bin/bash\n# xp-gate pre-commit\nv1\n';
+    const installedBody = '#!/bin/bash\n# xp-gate pre-commit\nv2-newer\n';
+    const { repoRoot, repoHooks, installedHooks } = scaffold({
+      repoPreCommit: repoBody,
+      installedPreCommit: installedBody,
+    });
+
+    const { diagnoseHookDrift } = loadDoctor();
+    const result = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+
+    expect(result.issues).toBeGreaterThan(0);
+    const check = result.checks.find((c) => c.name.includes('pre-commit'));
+    expect(check).toBeDefined();
+    expect(check.status).toBe('FAIL');
+    // The direction must be explicit -- "differs" alone does not tell a
+    // developer whether their local gate is stricter or looser than the repo.
+    expect(check.detail).toMatch(/installed.*newer|newer.*installed/i);
+  });
+
+  it('AC-451-01: reports the installed hook is OLDER than the repo copy', () => {
+    const repoBody = '#!/bin/bash\n# xp-gate pre-commit\nrepo-edited\n';
+    const installedBody = '#!/bin/bash\n# xp-gate pre-commit\nstale\n';
+    const { repoRoot, repoHooks, installedHooks } = scaffold({
+      repoPreCommit: repoBody,
+      installedPreCommit: installedBody,
+    });
+
+    // mtime granularity is coarse enough that two writes in the same test tick
+    // can land on the same millisecond, which would make the comparison
+    // ambiguous. Pin the times explicitly so the direction is unambiguous.
+    const now = Date.now() / 1000;
+    fs.utimesSync(path.join(installedHooks, 'pre-commit'), now - 3600, now - 3600);
+    fs.utimesSync(path.join(repoHooks, 'pre-commit'), now, now);
+
+    const { diagnoseHookDrift } = loadDoctor();
+    const result = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+
+    expect(result.issues).toBeGreaterThan(0);
+    const check = result.checks.find((c) => c.name.includes('pre-commit'));
+    expect(check.status).toBe('FAIL');
+    expect(check.detail).toMatch(/installed.*older|older.*installed|repo.*newer/i);
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-451-02: identical copies are silent
+  // -------------------------------------------------------------------------
+
+  it('AC-451-02: no issue when the installed copy matches the repo', () => {
+    const body = '#!/bin/bash\n# xp-gate pre-commit\nsame\n';
+    const { repoRoot, repoHooks, installedHooks } = scaffold({ repoPreCommit: body });
+
+    const { diagnoseHookDrift } = loadDoctor();
+    const result = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+
+    expect(result.issues).toBe(0);
+    const check = result.checks.find((c) => c.name.includes('pre-commit'));
+    expect(check.status).toBe('PASS');
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-451-03: no drift check outside a repo with githooks/
+  // -------------------------------------------------------------------------
+
+  it('AC-451-03: reports nothing when the project has no githooks/ directory', () => {
+    const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-gate-451-bare-'));
+    fs.mkdirSync(path.join(bare, '.git'), { recursive: true });
+
+    const { diagnoseHookDrift } = loadDoctor();
+    const result = diagnoseHookDrift({
+      repoRoot: bare,
+      repoHooks: path.join(bare, 'githooks'),
+      installedHooks: path.join(tmpHome, '.config', 'xp-gate', 'hooks'),
+    });
+
+    expect(result.issues).toBe(0);
+    expect(result.checks).toHaveLength(0);
+    fs.rmSync(bare, { recursive: true, force: true });
+  });
+
+  it('AC-451-03: reports nothing when no global copy is installed', () => {
+    const { repoRoot, repoHooks } = scaffold({
+      repoPreCommit: '#!/bin/bash\n# xp-gate pre-commit\nx\n',
+    });
+
+    const { diagnoseHookDrift } = loadDoctor();
+    const result = diagnoseHookDrift({
+      repoRoot,
+      repoHooks,
+      installedHooks: path.join(tmpHome, 'nowhere', 'hooks'),
+    });
+
+    expect(result.issues).toBe(0);
+    expect(result.checks).toHaveLength(0);
+  });
+
+  it('AC-451-03: ignores a githooks/ that holds only adapters (consumer layout)', () => {
+    // `xp-gate init` gives consumer projects githooks/adapters/ but no hook
+    // files. That is not a hook source of truth, so it must not be compared --
+    // otherwise every consumer project with a global install reports drift.
+    const { repoRoot, repoHooks, installedHooks } = scaffold({
+      repoPreCommit: '#!/bin/bash\n# xp-gate pre-commit\nx\n',
+    });
+    fs.rmSync(path.join(repoHooks, 'pre-commit'));
+    fs.mkdirSync(path.join(repoHooks, 'adapters'), { recursive: true });
+    fs.writeFileSync(path.join(repoHooks, 'adapters', 'typescript.sh'), '#!/bin/bash\n');
+
+    const { diagnoseHookDrift } = loadDoctor();
+    const result = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+
+    expect(result.issues).toBe(0);
+    expect(result.checks).toHaveLength(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-451-04: only hooks that exist in BOTH places are compared
+  // -------------------------------------------------------------------------
+
+  it('compares pre-commit and pre-push, ignoring hooks absent from either side', () => {
+    const { repoRoot, repoHooks, installedHooks } = scaffold({
+      repoPreCommit: '#!/bin/bash\n# xp-gate pre-commit\nsame\n',
+    });
+    fs.writeFileSync(path.join(repoHooks, 'pre-push'), '#!/bin/bash\n# xp-gate pre-push\nrepo\n');
+    fs.writeFileSync(
+      path.join(installedHooks, 'pre-push'),
+      '#!/bin/bash\n# xp-gate pre-push\ninstalled\n'
+    );
+    // post-merge exists only in the installed copy -> not a drift (the repo may
+    // legitimately not carry it), and must not crash the comparison.
+    fs.writeFileSync(path.join(installedHooks, 'post-merge'), '#!/bin/bash\n# xp-gate post-merge\n');
+
+    const { diagnoseHookDrift } = loadDoctor();
+    const result = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+
+    const names = result.checks.map((c) => c.name);
+    expect(names.some((n) => n.includes('pre-push'))).toBe(true);
+    expect(names.some((n) => n.includes('post-merge'))).toBe(false);
+    expect(result.issues).toBe(1);
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-451-02 (REQ-2): one-command sync makes the repo copy effective
+  // -------------------------------------------------------------------------
+
+  it('REQ-2: syncGlobalHooksFromRepo copies repo hooks over the installed copy', () => {
+    const repoBody = '#!/bin/bash\n# xp-gate pre-commit\nrepo-authoritative\n';
+    const { repoRoot, repoHooks, installedHooks } = scaffold({
+      repoPreCommit: repoBody,
+      installedPreCommit: '#!/bin/bash\n# xp-gate pre-commit\nstale\n',
+    });
+
+    const { syncGlobalHooksFromRepo, diagnoseHookDrift } = loadDoctor();
+    const syncResult = syncGlobalHooksFromRepo({ repoRoot, repoHooks, installedHooks });
+
+    expect(syncResult.errors).toEqual([]);
+    expect(syncResult.synced).toContain('pre-commit');
+    expect(fs.readFileSync(path.join(installedHooks, 'pre-commit'), 'utf8')).toBe(repoBody);
+
+    // The drift must be gone afterwards -- that is the whole point of the sync.
+    const after = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+    expect(after.issues).toBe(0);
+  });
+
+  it('REQ-2: sync reports an error when there is no githooks/ to copy from', () => {
+    const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-gate-451-nogit-'));
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+
+    const result = syncGlobalHooksFromRepo({
+      repoRoot: bare,
+      repoHooks: path.join(bare, 'githooks'),
+      installedHooks: path.join(tmpHome, '.config', 'xp-gate', 'hooks'),
+    });
+
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0]).toMatch(/no githooks/i);
+    fs.rmSync(bare, { recursive: true, force: true });
+  });
+
+  it('REQ-2: sync leaves already-identical hooks untouched', () => {
+    const body = '#!/bin/bash\n# xp-gate pre-commit\nsame\n';
+    const { repoRoot, repoHooks, installedHooks } = scaffold({ repoPreCommit: body });
+    const installedFile = path.join(installedHooks, 'pre-commit');
+    const before = fs.statSync(installedFile).mtimeMs;
+
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    const result = syncGlobalHooksFromRepo({ repoRoot, repoHooks, installedHooks });
+
+    expect(result.synced).toEqual([]);
+    expect(result.skipped).toContain('pre-commit');
+    expect(fs.statSync(installedFile).mtimeMs).toBe(before);
+  });
+
+  // -------------------------------------------------------------------------
+  // REQ-488: sync and drift must cover the githooks/lib/ shared libraries.
+  // After pre-commit was refactored to `source lib/*.sh`, a synced pre-commit
+  // died at the source line on the machine: sync copied only the three hook
+  // files, so the installed lib/ stayed stale or empty (#488).
+  // -------------------------------------------------------------------------
+
+  it('REQ-488: syncGlobalHooksFromRepo copies githooks/lib/ shared libraries', () => {
+    const { repoRoot, repoHooks, installedHooks } = scaffold({
+      repoPreCommit: '#!/bin/bash\n# xp-gate pre-commit\nsource lib/typecheck.sh\n',
+    });
+    fs.mkdirSync(path.join(repoHooks, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(repoHooks, 'lib', 'typecheck.sh'), 'typecheck-lib\n');
+    fs.writeFileSync(path.join(repoHooks, 'lib', 'validate-code-walkthrough.cjs'), 'walkthrough-lib\n');
+
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    const result = syncGlobalHooksFromRepo({ repoRoot, repoHooks, installedHooks });
+
+    expect(result.errors).toEqual([]);
+    expect(fs.readFileSync(path.join(installedHooks, 'lib', 'typecheck.sh'), 'utf8')).toBe('typecheck-lib\n');
+    expect(fs.readFileSync(path.join(installedHooks, 'lib', 'validate-code-walkthrough.cjs'), 'utf8')).toBe('walkthrough-lib\n');
+    expect(result.synced).toContain('lib/typecheck.sh');
+  });
+
+  it('REQ-488: drift reports a missing or stale installed lib/ file', () => {
+    const { repoRoot, repoHooks, installedHooks } = scaffold({ repoPreCommit: 'same\n' });
+    fs.mkdirSync(path.join(repoHooks, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(repoHooks, 'lib', 'typecheck.sh'), 'repo-version\n');
+
+    const { diagnoseHookDrift } = loadDoctor();
+
+    const missing = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+    expect(missing.issues).toBe(1);
+    expect(missing.checks.some(c => c.name === 'Hook drift: lib/typecheck.sh' && c.status === 'FAIL')).toBe(true);
+
+    fs.mkdirSync(path.join(installedHooks, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(installedHooks, 'lib', 'typecheck.sh'), 'installed-version\n');
+    const stale = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+    expect(stale.issues).toBe(1);
+
+    fs.writeFileSync(path.join(installedHooks, 'lib', 'typecheck.sh'), 'repo-version\n');
+    const ok = diagnoseHookDrift({ repoRoot, repoHooks, installedHooks });
+    expect(ok.issues).toBe(0);
+  });
+
+  it('REQ-488: a repo without lib/ still syncs and drifts cleanly', () => {
+    const { repoRoot, repoHooks, installedHooks } = scaffold({ repoPreCommit: '#!/bin/bash\n# xp-gate pre-commit\n' });
+
+    const { syncGlobalHooksFromRepo, diagnoseHookDrift } = loadDoctor();
+    const syncResult = syncGlobalHooksFromRepo({ repoRoot, repoHooks, installedHooks });
+
+    expect(syncResult.errors).toEqual([]);
+    expect(diagnoseHookDrift({ repoRoot, repoHooks, installedHooks }).issues).toBe(0);
+  });
+});

package/lib/__tests__/doctor-machine-mutation.test.js

@@ -0,0 +1,116 @@
+/**
+ * @test REQ-502 Round 3: --fix must be the only way anything mutates the machine
+ * @intent Round 2 的两位专家各自命中一条"修复面越界"的残留路径：
+ *         (1) F7 只把 langIssues 那条分支挂上 --install-tools，而 fixIssues() 里的
+ *             fixMissingCliTools() 仍然无条件 require('./bootstrap.js') 并 execSync
+ *             安装缺失的门禁 CLI（gitleaks/semgrep/lizard…），`xp-gate install` 末尾
+ *             又自动跑 doctor --fix —— 与 #502 立项时同一类、且被 F7 自己的注释否定；
+ *         (2) fixStaleHooks() 用 updateHooks({force:true, noBackup:true, scope:'all'})
+ *             覆盖 hooks/adapters/gate 脚本，而同一次发布里 syncModulesFromRepo 对
+ *             同类风险显式拒绝并保留字节 —— 同一命令面内两套销毁标准，且 force 让
+ *             update-hooks 的本地改动守卫直接返回 0，无备份地抹掉机器独有内容。
+ * @covers AC-502-04, AC-502-05, AC-502-06, AC-495-20
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const DOCTOR = readFileSync(join(__dirname, '..', 'doctor.js'), 'utf8');
+
+function tempRoot(prefix) {
+  return mkdtempSync(join(tmpdir(), `xp-gate-${prefix}-`));
+}
+
+function write(file, text) {
+  mkdirSync(join(file, '..'), { recursive: true });
+  writeFileSync(file, text);
+}
+
+describe('doctor machine-mutation boundary (#502/#495 Round 3)', () => {
+  it('AC-502-04: the CLI-tool bootstrap is reachable only behind --install-tools', () => {
+    // fixIssues must take the flag and gate the installer on it, exactly like the
+    // language-tool branch already does.
+    expect(DOCTOR).toMatch(/function fixIssues\([^)]*installToolsFlag/);
+    expect(DOCTOR).toMatch(/if \(installToolsFlag\) \{\s*\n\s*fixed = fixMissingCliTools\(\) \|\| fixed;/);
+    expect(DOCTOR).not.toMatch(/fixed = fixMissingCliTools\(\) \|\| fixed;\n\s*fixed = fixTuiRegistration/);
+    // The call site has to hand it the flag; --fix alone must not.
+    expect(DOCTOR).toMatch(/fixIssues\([^)]*installToolsFlag[^)]*\)/);
+    // Guidance stays ungated: reporting is not a machine mutation.
+    expect(DOCTOR).toMatch(/fixed = printCliToolGuidance\(\)/);
+    // No second route into the installer.
+    expect((DOCTOR.match(/require\('\.\/bootstrap\.js'\)/g) || []).length).toBe(1);
+    expect(INSTALL_CMD_NEVER_OPTED_IN()).toEqual([]);
+  });
+
+  function INSTALL_CMD_NEVER_OPTED_IN() {
+    const src = readFileSync(join(__dirname, '..', 'install-cmd.js'), 'utf8');
+    const offenders = [];
+    for (const call of src.match(/doctor\(\[[^\]]*\]\)/g) || []) {
+      if (call.includes('--install-tools')) offenders.push(call);
+    }
+    return offenders;
+  }
+
+  it('AC-502-05: the stale-hook refresh writes only what the plan judged safe', () => {
+    // A blanket forced updateHooks() overwrites exactly the files the plan just
+    // refused, and the backup-less variant of it is what destroyed the machine-only
+    // content in the first place. The repair surface is now a per-file copy of the
+    // judged-safe entries; nothing in doctor forces, and nothing leaves .bak litter
+    // in the user's work tree (#428's guard would reject that too).
+    expect(DOCTOR).not.toMatch(/updateHooks\(\s*\{[^}]*force:\s*true/);
+    expect(DOCTOR).toMatch(/for \(const entry of plan\.safe\)/);
+    expect(DOCTOR).not.toMatch(/noBackup:/);
+  });
+
+  // AC-502-06 (#488 Round 4, feasibility): removing the backup-less forced write
+  // also removed the only recovery the old path had. The judgement is still the
+  // right one — .bak litter is what #428's guard caught — but a user who does run
+  // `--sync-hooks --force` must be told before the bytes are gone that nothing
+  // keeps a copy for them.
+  it('AC-502-06: the path that suggests --force says it overwrites with no backup', () => {
+    expect(DOCTOR).toMatch(/function fixStaleHooks[\s\S]{0,3500}no automatic backup/);
+    expect(DOCTOR).toMatch(/--sync-hooks --force[^\n]*no backup|no backup[^\n]*--sync-hooks --force/);
+  });
+
+  it('AC-495-20: planStaleHookSync splits stale files (safe to sync) from diverged ones (must be judged)', () => {    const { planStaleHookSync } = require('../doctor');
+    const root = tempRoot('stale-plan');
+    const srcDir = join(root, 'pkg', 'githooks');
+    const destDir = join(root, 'installed', 'adapters');
+
+    write(join(srcDir, 'gate-4.sh'), '#!/bin/bash\nline_a\nline_b\n');
+    write(join(destDir, 'gate-4.sh'), '#!/bin/bash\nline_a\n'); // stale: repo ahead
+    write(join(srcDir, 'gate-8.sh'), '#!/bin/bash\nline_a\nline_b\n');
+    write(join(destDir, 'gate-8.sh'), '#!/bin/bash\nline_a\nmachine_only_hardening\n'); // diverged
+    write(join(srcDir, 'typescript.sh'), '#!/bin/bash\nline_a\nline_b\n');
+    write(join(destDir, 'typescript.sh'), '#!/bin/bash\nline_a\nline_b\n'); // identical
+
+    const plan = planStaleHookSync(
+      ['gate-4.sh', 'gate-8.sh', 'typescript.sh'].map((name) => ({
+        name,
+        source: join(srcDir, name),
+        target: join(destDir, name),
+      })),
+    );
+
+    expect(plan.safe.map((e) => e.name)).toContain('gate-4.sh');
+    expect(plan.diverged.map((e) => e.name)).toContain('gate-8.sh');
+    expect(plan.diverged[0].installedOnly).toBe(1);
+    expect(plan.unknown.map((e) => e.name)).toEqual([]);
+    // A plan that is entirely safe is what allows the sync; one diverged file is not.
+    expect(plan.hasBlocking).toBe(true);
+
+    const unreadable = planStaleHookSync([{
+      name: 'gate-9.sh',
+      source: join(srcDir, 'gate-9.sh'),
+      target: destDir, // directory where a file is expected
+    }]);
+    expect(unreadable.unknown.map((e) => e.name)).toContain('gate-9.sh');
+    expect(unreadable.hasBlocking).toBe(true);
+
+    // fixStaleHooks has to consult the plan instead of forcing over it.
+    expect(DOCTOR).toMatch(/planStaleHookSync\(/);
+    expect(DOCTOR).toMatch(/function fixStaleHooks[\s\S]{0,2000}plan\.hasBlocking/);
+    expect(readFileSync(join(destDir, 'gate-8.sh'), 'utf8')).toContain('machine_only_hardening');
+  });
+});