@boyingliu01/xp-gate 0.19.3 → 0.20.0

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

@@ -0,0 +1,206 @@
+/**
+ * @test REQ-495 xp-gate doctor sees the gate modules that actually execute
+ * @intent doctor 对全局目录只做存在性检查（checkAdapters），drift 检查只看
+ *         pre-commit/pre-push/post-merge + lib/；而 pre-commit 把 GATE_DIR 解析到
+ *         ~/.config/xp-gate/adapters（`if [ -f "$ADAPTER_DIR/gate-3.sh" ]`），
+ *         门禁模块全部在那里执行。于是本仓库里 gate-4/gate-8/typescript.sh 与机器
+ *         副本三份互异，doctor 却报全绿，#493 那类仓库侧修复在本地根本不会被执行
+ *         （#495）。更糟的是任何单向同步都会销毁另一侧的机器独有加固，所以判定
+ *         必须给出"双向发散"这一态并拒绝静默覆盖。
+ * @covers AC-495-01, AC-495-02, AC-495-03, AC-495-04, AC-495-05, AC-495-06
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, utimesSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Build a repo + global-install pair. `spec` names each module's repo copy and
+ * installed copy; null means "not present on that side".
+ */
+function fixture(spec) {
+  const root = mkdtempSync(join(tmpdir(), 'xp-gate-drift-'));
+  const repoHooks = join(root, 'githooks');
+  const installedHooks = join(root, 'hooks');
+  const installedAdapters = join(root, 'adapters');
+  mkdirSync(join(repoHooks, 'adapters'), { recursive: true });
+  mkdirSync(installedHooks, { recursive: true });
+  mkdirSync(installedAdapters, { recursive: true });
+
+  const write = (file, text) => {
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, text);
+  };
+
+  for (const [name, sides] of Object.entries(spec)) {
+    if (sides.repo !== null) {
+      // gate-*/adapter-common.sh live at the githooks root; language adapters
+      // live under githooks/adapters/ -- the same split the installer uses.
+      const rootLevel = name.startsWith('gate-') || name === 'adapter-common.sh' || name.startsWith('lib/');
+      write(join(repoHooks, rootLevel ? name : join('adapters', name)), sides.repo);
+    }
+    if (sides.installed !== null) {
+      write(join(installedAdapters, sides.nested ? join('adapters', name) : name), sides.installed);
+    }
+    if (sides.repoMtime) utimesSync(join(repoHooks, name), sides.repoMtime, sides.repoMtime);
+  }
+
+  // A canonical hook source is what makes the drift surface apply at all.
+  write(join(repoHooks, 'pre-commit'), '#!/bin/bash\necho repo\n');
+  write(join(installedHooks, 'pre-commit'), '#!/bin/bash\necho repo\n');
+
+  // Resolution anchors: pre-commit only makes the installed dir the ADAPTER_DIR
+  // when `adapter-common.sh` is in it (:34), and only reads gate modules from it
+  // when `gate-3.sh` is (:80). Without both, the fixture describes a tier the hook
+  // never resolves to, and the comparison silently targets some other directory
+  // (#495 Round 3 -- the tier list is no longer an assumption).
+  const ANCHOR = '#!/bin/bash\nanchor\n';
+  for (const anchor of ['adapter-common.sh', 'gate-3.sh']) {
+    if (spec[anchor]) continue;
+    write(join(repoHooks, anchor), ANCHOR);
+    write(join(installedAdapters, anchor), ANCHOR);
+  }
+
+  return { repoHooks, installedHooks, installedAdapters, root, write };
+}
+
+function drift(ctx) {
+  const { diagnoseModuleDrift } = require('../doctor');
+  expect(typeof diagnoseModuleDrift).toBe('function');
+  return diagnoseModuleDrift(ctx);
+}
+
+/**
+ * Name every tier the hook can resolve into, so a test can never end up
+ * comparing against this machine's real `~/.config/xp-gate` (#495 Round 3).
+ */
+function ctxFor(f, extra = {}) {
+  return {
+    repoRoot: f.root,
+    repoHooks: f.repoHooks,
+    installedAdapters: f.installedAdapters,
+    scriptDir: f.installedHooks,
+    ...extra,
+  };
+}
+
+function checkOf(result, needle) {
+  const hit = result.checks.find((c) => c.name.includes(needle));
+  expect(hit, `no check named like ${needle} in ${JSON.stringify(result.checks)}`).toBeDefined();
+  return hit;
+}
+
+describe('doctor module drift (#495)', () => {
+  it('AC-495-01: a stale executed gate module is reported, not waved through on presence', () => {
+    const f = fixture({
+      'gate-8.sh': { repo: '#!/bin/bash\n# repo version\n', installed: '#!/bin/bash\n# installed version\n' },
+    });
+    const result = drift(ctxFor(f));
+    expect(result.issues).toBeGreaterThanOrEqual(1);
+    expect(checkOf(result, 'gate-8.sh').status).toBe('FAIL');
+  });
+
+  it('AC-495-02: language adapters are compared through the hook\'s own lookup order', () => {
+    // Flat installed copy wins at runtime, so the repo's nested source is the
+    // right counterpart for it.
+    const flat = fixture({
+      'typescript.sh': { repo: 'run_tests() { echo repo; }\n', installed: 'run_tests() { echo stale; }\n' },
+    });
+    const flatResult = drift(ctxFor(flat));
+    expect(checkOf(flatResult, 'typescript.sh').status).toBe('FAIL');
+
+    // When the flat copy is absent the hook falls back to adapters/<name>.sh,
+    // and that nested file is the one that executes -- it must be checked too.
+    const nested = fixture({
+      'python.sh': { repo: 'run_tests() { echo repo; }\n', installed: 'run_tests() { echo stale; }\n', nested: true },
+    });
+    expect(checkOf(drift(ctxFor(nested)), 'python.sh').status).toBe('FAIL');
+  });
+
+  it('AC-495-03: equal content passes and a module missing on either side stays silent', () => {
+    const same = 'run_tests() { echo same; }\n';
+    const f = fixture({
+      'python.sh': { repo: same, installed: same },
+      'gate-3.sh': { repo: '#!/bin/bash\nv1\n', installed: '#!/bin/bash\nv1\n' },
+      // Repo-only and install-only modules have no counterpart to compare with.
+      'go.sh': { repo: 'echo repo only\n', installed: null },
+      'swift.sh': { repo: null, installed: 'echo installed only\n' },
+    });
+    const result = drift(ctxFor(f));
+    expect(result.issues).toBe(0);
+    expect(checkOf(result, 'python.sh').status).toBe('PASS');
+    expect(result.checks.filter((c) => c.name.includes('go.sh'))).toHaveLength(0);
+    expect(result.checks.filter((c) => c.name.includes('swift.sh'))).toHaveLength(0);
+
+    // A consumer project has no githooks/ at all -- the whole surface must stay
+    // completely quiet there, exactly like the hook drift check does.
+    const absent = drift(ctxFor(f, { repoHooks: join(f.root, 'nope') }));
+    expect(absent.checks).toHaveLength(0);
+    expect(absent.issues).toBe(0);
+  });
+
+  it('AC-495-04: bidirectional divergence is a distinct verdict from one-way staleness', () => {
+    // Installed carries lines the repo lacks (the machine-only detect-secrets
+    // hardening) AND the repo carries lines the install lacks (#449 verdict).
+    const f = fixture({
+      'gate-8.sh': {
+        repo: '#!/bin/bash\nrepo_has_report_artifact_verdict\n',
+        installed: '#!/bin/bash\ninstalled_has_detect_secrets_fallback\n',
+      },
+      'gate-4.sh': { repo: '#!/bin/bash\nline_a\nline_b\n', installed: '#!/bin/bash\nline_a\n' },
+    });
+    const result = drift(ctxFor(f));
+
+    const diverged = checkOf(result, 'gate-8.sh');
+    expect(diverged.status).toBe('FAIL');
+    expect(diverged.detail).toMatch(/both sides|diverged/i);
+
+    // One-way staleness must NOT be described as divergence, or the guard fires
+    // on every routine upgrade and the real case stops standing out.
+    const stale = checkOf(result, 'gate-4.sh');
+    expect(stale.status).toBe('FAIL');
+    expect(stale.detail).not.toMatch(/both sides|diverged/i);
+  });
+
+  it('AC-495-05: sync copies stale modules and refuses to overwrite diverged ones', () => {
+    const { syncModulesFromRepo } = require('../doctor');
+    expect(typeof syncModulesFromRepo).toBe('function');
+
+    const f = fixture({
+      'gate-8.sh': {
+        repo: '#!/bin/bash\nrepo_has_report_artifact_verdict\n',
+        installed: '#!/bin/bash\ninstalled_has_detect_secrets_fallback\n',
+      },
+      'gate-4.sh': { repo: '#!/bin/bash\nline_a\nline_b\n', installed: '#!/bin/bash\nline_a\n' },
+    });
+
+    const first = syncModulesFromRepo(ctxFor(f));
+    expect(first.synced).toContain('gate-4.sh');
+    expect(readFileSync(join(f.installedAdapters, 'gate-4.sh'), 'utf8')).toContain('line_b');
+    // The guard is the point: the machine-only hardening survives untouched.
+    expect(first.refused.map((r) => r.name)).toContain('gate-8.sh');
+    expect(readFileSync(join(f.installedAdapters, 'gate-8.sh'), 'utf8')).toContain('detect_secrets');
+
+    // An explicit decision still wins, because the developer may have judged the
+    // repo copy to be the correct one.
+    const forced = syncModulesFromRepo(ctxFor(f, { force: true }));
+    expect(forced.synced).toContain('gate-8.sh');
+    expect(readFileSync(join(f.installedAdapters, 'gate-8.sh'), 'utf8')).toContain('report_artifact_verdict');
+    expect(existsSync(join(f.installedAdapters, 'gate-8.sh'))).toBe(true);
+  });
+
+  it('AC-495-06: anti-vacuity -- the surface is wired into the report and the repair', () => {
+    const source = readFileSync(join(__dirname, '..', 'doctor.js'), 'utf8');
+
+    // Detection must run in the real diagnosis, not only in the exported helper.
+    expect(/diagnoseModuleDrift\(/.test(source)).toBe(true);
+    expect(/diagnoseModuleDrift\(\)/.test(source)).toBe(true);
+    // Repair must be reachable from the doctor command surface.
+    expect(/syncModulesFromRepo\(/.test(source)).toBe(true);
+    // The developer has to be able to see WHICH directory executes (#495's
+    // "print the resolved GATE_DIR/ADAPTER_DIR" requirement).
+    expect(source).toMatch(/printEffectiveModules|Effective (hooks|modules)/);
+    // The presence-only verdict that hid this is gone for gate scripts.
+    expect(source).not.toMatch(/status: 'PASS', detail: `\$\{EXPECTED_GATE_SCRIPTS\.length\} gate script\(s\)`/);
+  });
+});

package/lib/__tests__/doctor-module-resolution-parity.test.js

@@ -0,0 +1,314 @@
+/**
+ * @test REQ-495 the JS mirror of the hook's module lookup must be reconciled against the bash original
+ * @intent #495 的修复把 pre-commit 的 flat-优先-nested 解析顺序用 JavaScript 重写了一份
+ *         （doctor.js listExecutedModules）。本仓库在本批次已经示范过正确范式：
+ *         src/mutation/__tests__/test-filter-parity.test.ts（AC-480-04）把 bash 与 TS
+ *         两份"非生产代码定义"钉成同一文本。跨语言的解析顺序同样不能靠注释宣称一致：
+ *         hook 侧一旦演化，doctor 就会镜像旧秩序，"doctor 全绿、执行面另起炉灶"重现。
+ *         因此这里直接抽取 pre-commit 的 resolve_adapter_path 函数体，交给 bash 执行，
+ *         与 doctor 的 listExecutedModules 在同一棵合成目录树上逐模块对账。第三轮把它
+ *         扩到四层全填充的场景树：ADAPTER_DIR 链、GATE_DIR 链、resolve_adapter_path 三段
+ *         全部从 pre-commit 原文抽取后交给 bash 执行，与 doctor 的
+ *         resolveExecutedModuleDirs()+executedModulePath() 对同一棵树逐一比对；hook 侧
+ *         一旦改动解析顺序，这里立刻失配，而不是让 doctor 继续镜像旧秩序。
+ * @covers AC-495-11, AC-495-12, AC-495-21, AC-495-22
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+
+const PRE_COMMIT = readFileSync(resolve(__dirname, '..', '..', '..', '..', 'githooks', 'pre-commit'), 'utf8');
+
+/**
+ * Extract one bash function's full text, brace-balanced from the declaration.
+ */
+function extractFunction(source, signature) {
+  const start = source.indexOf(signature);
+  expect(start, `pre-commit no longer declares ${signature}`).toBeGreaterThan(-1);
+  let depth = 0;
+  let index = source.indexOf('{', start);
+  const bodyStart = index;
+  for (; index < source.length; index++) {
+    const ch = source[index];
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) return source.slice(start, index + 1);
+    }
+  }
+  throw new Error(`unbalanced braces in ${signature}`);
+}
+
+/**
+ * Grab one `if`-chain verbatim from the hook, up to and including its `fi`.
+ */
+function matchBlock(source, pattern, label) {
+  const hit = source.match(pattern);
+  expect(hit, `pre-commit no longer carries ${label}`).not.toBeNull();
+  return hit[0];
+}
+
+function bashBin() {
+  const candidate = process.env.XP_GATE_BASH_BIN || 'bash';
+  const probe = spawnSync(candidate, ['-c', 'echo ok'], { encoding: 'utf8' });
+  // A missing runner must fail loudly, never read as a passing guard.
+  if (probe.status !== 0 || probe.error) {
+    throw new Error(`bash runner unavailable (${candidate}): ${probe.error ? probe.error.message : `exit ${probe.status}`}`);
+  }
+  return candidate;
+}
+
+/**
+ * Compare a path the bash resolver printed with one Node built. Bash emits the
+ * separators it was handed and mixes them (`$ADAPTER_DIR/adapters/x.sh`), so the
+ * comparison is on a single separator view, not on either side's spelling.
+ */
+function samePath(a, b) {
+  const normalize = (p) => p.replace(/\\/g, '/').replace(/\/+/g, '/');
+  return normalize(a) === normalize(b);
+}
+
+/**
+ * Build an ADAPTER_DIR holding the requested flat and nested modules.
+ */
+function adapterTree(spec) {
+  const root = mkdtempSync(join(tmpdir(), 'xp-gate-parity-'));
+  const adapterDir = join(root, 'adapters');
+  mkdirSync(join(adapterDir, 'adapters'), { recursive: true });
+  // Empty PROJECT_GITHOOKS / SCRIPT_DIR tiers so only tiers 1-2 can answer.
+  mkdirSync(join(root, 'project'), { recursive: true });
+  mkdirSync(join(root, 'script'), { recursive: true });
+  for (const [name, sides] of Object.entries(spec)) {
+    if (sides.flat) writeFileSync(join(adapterDir, name), 'flat\n');
+    if (sides.nested) writeFileSync(join(adapterDir, 'adapters', name), 'nested\n');
+  }
+  return { root, adapterDir };
+}
+
+/**
+ * Where a module copy can sit across all four tiers the hook looks at. Each key
+ * is a location name, so a scenario reads as a statement about the tree.
+ */
+const LAYOUTS = {
+  globalFlat: (t, name) => join(t.globalAdapters, name),
+  globalNested: (t, name) => join(t.globalAdapters, 'adapters', name),
+  projectFlat: (t, name) => join(t.projectGithooks, name),
+  projectNested: (t, name) => join(t.projectGithooks, 'adapters', name),
+  scriptFlat: (t, name) => join(t.scriptDir, name),
+  scriptNested: (t, name) => join(t.scriptDir, 'adapters', name),
+};
+
+/**
+ * A tree with all tiers present, including their resolution anchors, so tier
+ * precedence is decided by the hook's own text rather than by the fixture's
+ * assumptions (AC-495-13's project-tier pair depends on this too).
+ */
+function fourTierTree(layouts) {
+  const root = mkdtempSync(join(tmpdir(), 'xp-gate-parity4-'));
+  const t = {
+    root,
+    globalAdapters: join(root, 'global', 'adapters'),
+    projectGithooks: join(root, 'repo', 'githooks'),
+    scriptDir: join(root, 'installed', 'hooks'),
+  };
+  for (const dir of [t.globalAdapters, t.projectGithooks, t.scriptDir]) {
+    mkdirSync(join(dir, 'adapters'), { recursive: true });
+  }
+  for (const [name, places] of Object.entries(layouts)) {
+    for (const place of places) {
+      const file = LAYOUTS[place](t, name);
+      mkdirSync(join(file, '..'), { recursive: true });
+      writeFileSync(file, `${place}\n`);
+    }
+  }
+  return t;
+}
+
+/**
+ * Run the hook's own ADAPTER_DIR chain, GATE_DIR chain and resolve_adapter_path
+ * over one tree, and report all three answers.
+ */
+function hookResolvesAll(blocks, resolverText, t, lang, gateModule) {
+  // Bash assignment uses single quotes below; a temp path containing one would
+  // change the tree the two sides are looking at, so refuse rather than lie.
+  for (const dir of [t.globalAdapters, t.projectGithooks, t.scriptDir]) {
+    expect(dir, `fixture path contains a quote: ${dir}`).not.toMatch(/'/);
+  }
+  const script = [
+    `GLOBAL_ADAPTER_DIR='${t.globalAdapters}'`,
+    `PROJECT_GITHOOKS='${t.projectGithooks}'`,
+    `SCRIPT_DIR='${t.scriptDir}'`,
+    blocks.adapterDir,
+    blocks.gateDir,
+    'echo "ADAPTER=$ADAPTER_DIR"',
+    'echo "GATE=$GATE_DIR"',
+    `if [ -f "$ADAPTER_DIR/adapter-common.sh" ]; then echo "COMMON=$ADAPTER_DIR/adapter-common.sh"; else echo "COMMON="; fi`,
+    `if [ -f "$GATE_DIR/${gateModule}" ]; then echo "MODULE=$GATE_DIR/${gateModule}"; else echo "MODULE="; fi`,
+    resolverText,
+    // Captured by substitution rather than read off the last stdout line: the
+    // script ends with a newline, so "last line" is always the empty one.
+    `echo "LANG=$(resolve_adapter_path ${lang} || true)"`,
+  ].join('\n');
+  const run = spawnSync(bashBin(), ['-c', script], { encoding: 'utf8' });
+  expect(run.status, `resolver run failed: ${run.stderr}`).toBe(0);
+  const lines = run.stdout.split(/\r?\n/);
+  const named = (prefix) => {
+    const hit = lines.find((l) => l.startsWith(`${prefix}=`));
+    expect(hit, `bash printed no ${prefix}= line:\n${run.stdout}`).toBeDefined();
+    return hit ? hit.slice(prefix.length + 1) : '';
+  };
+  return {
+    adapterDir: named('ADAPTER'),
+    gateDir: named('GATE'),
+    common: named('COMMON'),
+    gateModule: named('MODULE'),
+    langPath: named('LANG'),
+  };
+}
+
+/**
+ * Ask the hook's own resolver which file executes for one language.
+ */
+function hookResolves(fnText, tree, lang) {
+  const script = [
+    `ADAPTER_DIR='${tree.adapterDir}'`,
+    `PROJECT_GITHOOKS='${join(tree.root, 'project')}'`,
+    `SCRIPT_DIR='${join(tree.root, 'script')}'`,
+    fnText,
+    `resolve_adapter_path ${lang}`,
+  ].join('\n');
+  const run = spawnSync(bashBin(), ['-c', script], { encoding: 'utf8' });
+  expect(run.status, `resolver run failed: ${run.stderr}`).toBe(0);
+  return run.stdout.trim();
+}
+
+describe('doctor module resolution parity with pre-commit (#495)', () => {
+  const resolverText = extractFunction(PRE_COMMIT, 'resolve_adapter_path() {');
+  // The two tier chains the hook runs before it ever calls the resolver. Read
+  // from the hook's text, not restated here: #495 Round 2's project-tier label
+  // was wrong precisely because doctor carried a second, hand-written tier list.
+  const blocks = {
+    adapterDir: matchBlock(PRE_COMMIT, /if \[ -f "\$GLOBAL_ADAPTER_DIR\/adapter-common\.sh" \]; then[\s\S]*?\nfi/, 'the ADAPTER_DIR tier chain'),
+    gateDir: matchBlock(PRE_COMMIT, /if \[ -f "\$ADAPTER_DIR\/gate-3\.sh" \]; then[\s\S]*?\nfi/, 'the GATE_DIR tier chain'),
+  };
+
+  it('AC-495-11: flat and nested present -> both languages pick the flat copy', () => {
+    const { listExecutedModules } = require('../doctor');
+    const tree = adapterTree({ 'typescript.sh': { flat: true, nested: true } });
+
+    const hookChoice = hookResolves(resolverText, tree, 'typescript');
+    expect(samePath(hookChoice, join(tree.adapterDir, 'typescript.sh'))).toBe(true);
+
+    const doctorChoice = listExecutedModules(tree.adapterDir).find((m) => m.name === 'typescript.sh');
+    expect(doctorChoice).toBeDefined();
+    expect(samePath(doctorChoice.file, hookChoice)).toBe(true);
+  });
+
+  it('AC-495-12: every module the hook can resolve in the executed dir is in doctor\'s surface, and agrees on each path', () => {
+    const { listExecutedModules } = require('../doctor');
+    const tree = adapterTree({
+      'typescript.sh': { nested: true },
+      'python.sh': { flat: true, nested: true },
+      'gate-4.sh': { flat: true },
+      'go.sh': { nested: true },
+    });
+
+    const doctorModules = listExecutedModules(tree.adapterDir);
+    const doctorByName = new Map(doctorModules.map((m) => [m.name, m.file]));
+
+    // Same set of module names, no extras, no omissions.
+    expect([...doctorByName.keys()].sort()).toEqual(['gate-4.sh', 'go.sh', 'python.sh', 'typescript.sh']);
+
+    for (const lang of ['typescript', 'python', 'go']) {
+      const hookChoice = hookResolves(resolverText, tree, lang);
+      expect(existsSync(hookChoice), `hook resolved a missing file: ${hookChoice}`).toBe(true);
+      expect(doctorByName.has(`${lang}.sh`), `doctor does not see ${lang}.sh at all`).toBe(true);
+      expect(
+        samePath(doctorByName.get(`${lang}.sh`), hookChoice),
+        `doctor disagrees with the hook for ${lang}.sh`,
+      ).toBe(true);
+    }
+
+    // Anti-vacuity: the guard executed the hook's real text, not a paraphrase.
+    expect(resolverText).toMatch(/\$ADAPTER_DIR\/\$\{lang\}\.sh/);
+    expect(resolverText).toMatch(/\$ADAPTER_DIR\/adapters\/\$\{lang\}\.sh/);
+  });
+
+  // The scenarios below put a copy of the same module in EVERY tier the hook can
+  // reach, so agreement can only come from following the real precedence. Round 2
+  // had a hand-written two-tier list in doctor and called whatever it found
+  // "executed" -- which both mislabelled files nothing runs and left a FAIL no
+  // repair could clear (#495 Round 3).
+  const SCENARIOS = [
+    {
+      name: 'global install present: the global flat copy wins over every other tier',
+      layouts: {
+        'adapter-common.sh': ['globalFlat', 'projectFlat', 'scriptFlat'],
+        'gate-3.sh': ['globalFlat', 'projectFlat', 'scriptFlat'],
+        'gate-4.sh': ['globalFlat', 'projectFlat', 'scriptFlat'],
+        'typescript.sh': ['globalFlat', 'globalNested', 'projectFlat', 'projectNested', 'scriptNested'],
+      },
+    },
+    {
+      name: 'no global install: ADAPTER_DIR resolves to the project tier and its flat copy runs',
+      layouts: {
+        'adapter-common.sh': ['projectFlat', 'scriptFlat'],
+        'gate-3.sh': ['projectFlat', 'scriptFlat'],
+        'gate-4.sh': ['projectFlat', 'scriptFlat'],
+        'typescript.sh': ['projectFlat', 'projectNested', 'scriptNested'],
+      },
+    },
+    {
+      name: 'project tier carries no anchor: GATE_DIR falls through to the installed hooks dir',
+      layouts: {
+        'adapter-common.sh': ['globalFlat'],
+        'gate-3.sh': ['scriptFlat'],
+        'gate-4.sh': ['globalFlat', 'projectFlat', 'scriptFlat'],
+        'typescript.sh': ['globalNested', 'projectNested', 'scriptNested'],
+      },
+    },
+  ];
+
+  it('AC-495-21: the JS resolution picks the same file as the hook for every tier scenario', () => {
+    const { resolveExecutedModuleDirs, executedModulePath } = require('../doctor');
+    for (const scenario of SCENARIOS) {
+      const t = fourTierTree(scenario.layouts);
+      const hook = hookResolvesAll(blocks, resolverText, t, 'typescript', 'gate-4.sh');
+      const dirs = resolveExecutedModuleDirs({
+        globalAdapterDir: t.globalAdapters,
+        projectGithooks: t.projectGithooks,
+        scriptDir: t.scriptDir,
+      });
+
+      expect(samePath(dirs.adapterDir, hook.adapterDir), `${scenario.name} (ADAPTER_DIR)`).toBe(true);
+      expect(samePath(dirs.gateDir, hook.gateDir), `${scenario.name} (GATE_DIR)`).toBe(true);
+
+      const jsLang = executedModulePath('typescript.sh', dirs);
+      expect(jsLang, `${scenario.name}: doctor finds no executed copy the hook resolves`).not.toBeNull();
+      expect(samePath(jsLang, hook.langPath), `${scenario.name} (typescript.sh)`).toBe(true);
+
+      // Gate modules come from GATE_DIR, language adapters from the resolver chain.
+      expect(samePath(executedModulePath('gate-4.sh', dirs), hook.gateModule), `${scenario.name} (gate-4.sh)`).toBe(true);
+      expect(samePath(executedModulePath('adapter-common.sh', dirs), hook.common), `${scenario.name} (adapter-common.sh)`).toBe(true);
+    }
+  });
+
+  it('AC-495-22: a module no tier installs resolves to nothing on both sides', () => {
+    const { resolveExecutedModuleDirs, executedModulePath } = require('../doctor');
+    const t = fourTierTree({
+      'adapter-common.sh': ['globalFlat'],
+      'gate-3.sh': ['globalFlat'],
+    });
+    const dirs = resolveExecutedModuleDirs({
+      globalAdapterDir: t.globalAdapters,
+      projectGithooks: t.projectGithooks,
+      scriptDir: t.scriptDir,
+    });
+    const hook = hookResolvesAll(blocks, resolverText, t, 'rust', 'gate-9.sh');
+    expect(hook.langPath).toBe('');
+    expect(executedModulePath('rust.sh', dirs)).toBeNull();
+    expect(executedModulePath('gate-9.sh', dirs)).toBeNull();
+  });
+});

package/lib/__tests__/doctor-path-equivalence.test.js

@@ -0,0 +1,59 @@
+/**
+ * @test REQ-496 xp-gate doctor compares configured paths the way the OS does
+ * @intent doctor 用 `git config core.hooksPath` 的字符串直接 !== path.join 生成的常量：
+ *         Windows 上 git 回读的是正斜杠形式，常量是反斜杠形式，两者指向同一目录却被
+ *         判为不一致，于是每台配置正确的机器都恒报 FAIL，而 --fix 写入后回读仍是斜杠
+ *         形式、永远消不掉（#496）。本套件把"同一目录"的判定收敛到一个比较器上。
+ * @covers AC-496-01, AC-496-02, AC-496-03
+ */
+const fs = require('fs');
+const path = require('path');
+
+describe('doctor path equivalence (#496)', () => {
+  function comparator() {
+    const { pathsEquivalent } = require('../doctor');
+    return pathsEquivalent;
+  }
+
+  it('AC-496-01: the same directory spelled with either separator is equivalent', () => {
+    const same = comparator();
+    expect(typeof same).toBe('function');
+    const back = 'C:\\Users\\think\\.config\\xp-gate\\hooks';
+    const slash = 'C:/Users/think/.config/xp-gate/hooks';
+    expect(same(slash, back)).toBe(true);
+    expect(same(back, slash)).toBe(true);
+  });
+
+  it('AC-496-02: drive-letter case and a trailing separator do not break equivalence', () => {
+    const same = comparator();
+    expect(same('c:/Users/think/.config/xp-gate/hooks', 'C:\\Users\\think\\.config\\xp-gate\\hooks')).toBe(true);
+    expect(same('C:/Users/think/.config/xp-gate/hooks/', 'C:\\Users\\think\\.config\\xp-gate\\hooks')).toBe(true);
+    // POSIX paths must keep working (no drive letter, leading slash is content).
+    expect(same('/home/u/.config/xp-gate/hooks', '/home/u/.config/xp-gate/hooks')).toBe(true);
+    expect(same('/home/u/.config/xp-gate/hooks/', '/home/u/.config/xp-gate/hooks')).toBe(true);
+  });
+
+  it('AC-496-03: different directories still compare unequal, including near misses', () => {
+    const same = comparator();
+    expect(same('C:/Users/think/.config/xp-gate/hooks', 'C:/Users/think/.config/xp-gate/hooks-v2')).toBe(false);
+    expect(same('C:/Users/other/.config/xp-gate/hooks', 'C:/Users/think/.config/xp-gate/hooks')).toBe(false);
+    expect(same('/home/u/.config/xp-gate/hooks', '/home/u/.config/xp-gate/adapters')).toBe(false);
+    // A path that is a prefix of another is not the same directory.
+    expect(same('/home/u/.config/xp-gate', '/home/u/.config/xp-gate/hooks')).toBe(false);
+    expect(same('', 'C:/Users/think/.config/xp-gate/hooks')).toBe(false);
+  });
+
+  it('AC-496-04: anti-vacuity -- the comparator is what the hooksPath check uses', () => {
+    const source = fs.readFileSync(
+      path.join(__dirname, '..', 'doctor.js'),
+      'utf8'
+    );
+    // The two comparison sites that made the Windows call fail must both route
+    // through the equivalence check rather than a byte comparison.
+    const callSites = source
+      .split('\n')
+      .filter((line) => /hooksPath\s*!==\s*GLOBAL_HOOKS_DIR/.test(line));
+    expect(callSites).toHaveProperty('length', 0);
+    expect(source).toMatch(/pathsEquivalent\(hooksPath, GLOBAL_HOOKS_DIR\)/);
+  });
+});

package/lib/__tests__/doctor-repair-boundary.test.js

@@ -0,0 +1,52 @@
+/**
+ * @test REQ-502 the repair surface of doctor must not mutate the machine unasked
+ * @intent Delphi code-walkthrough Round 1 给出两条修复面越界：(1) --fix 在
+ *         langIssues>0 时直接 execSync 包管理器安装，#468 扩大检出语言后触发面变宽，
+ *         一次 doctor --fix（或 xp-gate install 末尾自动跑的 doctor --fix）就会给
+ *         机器装上新语言的工具；(2) install-cmd 把 doctor 的诊断退出码原样当作安装
+ *         结果，#495 的 Module drift FAIL 会让"装成功却 exit 1"，训练脚本误判失败。
+ *         另外 bin 的 usage 行没同步 --force/--install-tools，未知 flag 已被严格拒绝，
+ *         帮助文本比实现更旧就会把人引向失败命令。Round 3 给 KNOWN_FLAGS 加了
+ *         --json/--format，同一条"帮助比实现旧"的缺口会原样复现，故断言改为直接
+ *         读解析器的白名单，不再在本文件里维护第二张表。
+ * @covers AC-502-01, AC-502-02, AC-502-03
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const DOCTOR = readFileSync(join(__dirname, '..', 'doctor.js'), 'utf8');
+const INSTALL_CMD = readFileSync(join(__dirname, '..', 'install-cmd.js'), 'utf8');
+const BIN = readFileSync(join(__dirname, '..', '..', 'bin', 'xp-gate.js'), 'utf8');
+
+describe('doctor/install repair boundary (#502)', () => {
+  it('AC-502-01: language tool auto-install requires an explicit opt-in flag', () => {
+    expect(DOCTOR).toMatch(/KNOWN_FLAGS\s*=\s*\[[^\]]*'--install-tools'/);
+    // The execSync-backed installer must be gated by the flag, not just by --fix.
+    expect(DOCTOR).toMatch(/if \(fixMode && installToolsFlag && langIssues > 0\)/);
+    expect(DOCTOR).not.toMatch(/if \(fixMode && langIssues > 0\)\s*\{/);
+  });
+
+  it('AC-502-02: xp-gate install reports doctor findings without adopting its exit code', () => {
+    expect(INSTALL_CMD).not.toMatch(/return doctorCode/);
+    // The install action's own failure still has to fail the command.
+    expect(INSTALL_CMD).toMatch(/return code/);
+  });
+
+  it('AC-502-03: the doctor usage line advertises every flag the parser accepts', () => {
+    const usage = BIN.match(/usage: 'xp-gate doctor[^']*'/);
+    expect(usage, 'bin/xp-gate.js has no doctor usage line').not.toBeNull();
+    // Read the accepted set from the parser instead of repeating a list here:
+    // a hardcoded list goes stale exactly when a flag is added, which is the
+    // defect this assertion exists to prevent (#488 Round 3 did it for the
+    // release notes; the CLI help is the same command surface).
+    const accepted = DOCTOR.match(/const KNOWN_FLAGS\s*=\s*\[([^\]]*)\]/)[1]
+      .split(',')
+      .map((entry) => entry.trim().replace(/^'|'$/g, ''))
+      .filter(Boolean);
+    expect(accepted.length).toBeGreaterThan(4);
+    for (const flag of accepted) {
+      expect(usage[0], `usage line does not mention ${flag}`).toContain(flag);
+    }
+  });
+});