@boyingliu01/xp-gate 0.35.17 → 0.35.19

package/hooks/gate-12-file-hygiene.sh

@@ -36,13 +36,35 @@ fi
 HYGIENE_ISSUES=0
 HYGIENE_FILES=""
 
+# Is this staged file binary (so line-based checks do not apply)?
+#
+# This replaces `grep -q $'\x00'`, which was a no-op guard: bash strips NUL from
+# `$'\x00'`, so the pattern was the EMPTY string and `grep -q ""` matches any
+# non-empty input. Every staged file was therefore judged binary and `continue`d,
+# silently disabling Check 1 (trailing whitespace), Check 2 (missing EOF newline)
+# and -- worst -- Check 3 (merge conflict markers, a BLOCK-level check). Checks 4
+# and 5 lacked the guard, which is why the gate looked half-working.
+#
+# Ask git instead of guessing: `--numstat` reports a binary entry as `-\t-\t<path>`
+# because git already made that determination. A byte-level NUL test cannot be
+# written with a shell pattern at all (variables and command substitution both drop
+# NUL), and `grep -I` only suppresses output on a binary input -- it does not make
+# `grep -q` fail, which is why that shortcut still reported text.
+is_binary_staged_file() {
+  local _file="$1"
+  case "$(git diff --cached --numstat -- "$_file" 2>/dev/null)" in
+    -[[:space:]]-*) return 0 ;;   # binary: git could not count lines
+    *) return 1 ;;                # text (or empty -- nothing for the line checks)
+  esac
+}
+
 # --- Check 1: Trailing whitespace ---
 TRAILING_WS_FILES=""
 if [ "${GATE_12_DOCS_ONLY:-false}" != true ]; then
 while IFS= read -r file; do
   [ -z "$file" ] && continue
-  # Skip binary files by checking if file contains null bytes
-  if git diff --cached --no-color -- "$file" 2>/dev/null | grep -q $'\x00'; then
+  # Skip binary files : they have no lines to check
+  if is_binary_staged_file "$file"; then
     continue
   fi
   # Check staged content for trailing whitespace (spaces/tabs at end of lines)
@@ -69,7 +91,7 @@ if [ "${GATE_12_DOCS_ONLY:-false}" != true ]; then
 while IFS= read -r file; do
   [ -z "$file" ] && continue
   # Skip binary files
-  if git diff --cached --no-color -- "$file" 2>/dev/null | grep -q $'\x00'; then
+  if is_binary_staged_file "$file"; then
     continue
   fi
   # Check if file content ends with newline
@@ -108,7 +130,7 @@ else
 while IFS= read -r file; do
   [ -z "$file" ] && continue
   # Skip binary files
-  if git diff --cached --no-color -- "$file" 2>/dev/null | grep -q $'\x00'; then
+  if is_binary_staged_file "$file"; then
     continue
   fi
   # Check for conflict markers in staged content

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

@@ -527,6 +527,18 @@ gate13_count_lint_findings() {
   [ -n "$src" ] || src=$(cat)
   printf '%s\n' "$src" | awk '
     BEGIN { n = 0 }
+    # (#673) Maven 3.9.7+ reactor summary appends the packaging type per module:
+    #     [INFO] whaleaudit-core  [jar]
+    # `[pom]`/`[jar]` match the open-category rule below, so a 3-module reactor
+    # reported 4 javac findings on code with ZERO warnings -- and got worse with
+    # every module added. The marker set is closed (packaging types are an enum in
+    # Maven itself), so excluding it does not reopen the #659 fail-open hole that
+    # the open-category rule was introduced to close.
+    #
+    # Scoped to `[INFO]` lines: a javac diagnostic is never prefixed with the
+    # Maven [INFO] banner, so this cannot mask a real finding even when a category
+    # name collides with a packaging type.
+    /^\[INFO\].*\[(pom|jar|war|ear|rar|ejb|maven-plugin|par|test-jar|java-source|javadoc|zip|tar\.gz|tar\.bz2)\][[:space:]]*$/ { next }
     # 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.

package/hooks/pre-commit

@@ -319,6 +319,32 @@ if ! declare -F run_tsx >/dev/null 2>&1; then
   }
 fi
 
+# Run a repo-local Node CLI (eslint, vitest, biome, ...) without npx when the
+# binary is already in this repo's node_modules.
+#
+# `npx <tool>` costs ~1.4-1.5 s more than the tool itself on this machine
+# (measured: eslint --version 1654 ms via npx vs 348 ms direct; vitest 1799 ms vs
+# 250 ms). That is npm resolving the package before it ever runs: on a cold
+# cache it may reach the network, which a quality gate must never depend on.
+# pre-commit invokes these tools a handful of times per commit, so the wrapper
+# was paying several seconds to start processes that were already installed.
+#
+# `run_node_bin <tool> <node-entry> [args...]`. Falls back to npx when the local
+# entry is absent (a globally-installed toolchain is still a valid setup).
+if ! declare -F run_node_bin >/dev/null 2>&1; then
+  run_node_bin() {
+    local _tool="$1" _entry="$2"
+    shift 2
+    local _root="${PROJECT_ROOT:-$(pwd)}"
+    local _local="$_root/node_modules/$_entry"
+    if [ -f "$_local" ] && command -v node >/dev/null 2>&1; then
+      node "$_local" "$@"
+    else
+      npx "$_tool" "$@"
+    fi
+  }
+fi
+
 # Gate 5's vitest exit-code judgement (is_runner_infrastructure_error,
 # is_partial_threshold_only_exit, handle_test_failure) is sourced from
 # lib/test-failure.sh below, next to the other hook libraries.
@@ -1677,9 +1703,9 @@ else
         # each linted file (found in the subdirectory automatically); flat
         # configs are discovered from the CWD, so point at them explicitly.
         if [ "$TS_PROJECT_DIR" != "." ] && [ -f "$TS_PROJECT_DIR/eslint.config.js" ]; then
-          ESLINT_OUTPUT=$(npx eslint --config "$TS_PROJECT_DIR/eslint.config.js" $ESLINT_FILES -f json --no-warn-ignored 2>&1)
+          ESLINT_OUTPUT=$(run_node_bin eslint eslint/bin/eslint.js --config "$TS_PROJECT_DIR/eslint.config.js" $ESLINT_FILES -f json --no-warn-ignored 2>&1)
         else
-          ESLINT_OUTPUT=$(npx eslint $ESLINT_FILES -f json --no-warn-ignored 2>&1)
+          ESLINT_OUTPUT=$(run_node_bin eslint eslint/bin/eslint.js $ESLINT_FILES -f json --no-warn-ignored 2>&1)
         fi
         ESLINT_EXIT=$?
         if [ "$ESLINT_EXIT" -ne 0 ]; then
@@ -3008,7 +3034,7 @@ else
     if source "$ADAPTER_FILE" 2>/dev/null; then
       # TypeScript: vitest with smart test selection
       if [ "$CURRENT_LANG" = "typescript" ] && { [ -f "package.json" ] || [ -f "$PROJECT_ROOT/package.json" ]; }; then
-        if run_without_git_context npx vitest --version >/dev/null 2>&1; then
+        if run_without_git_context run_node_bin vitest vitest/vitest.mjs --version >/dev/null 2>&1; then
           # Count changed test files to decide strategy. `grep -c '.'` prints its
           # own zero AND exits 1 on an empty list, so `|| echo "0"` used to yield
           # $'0\n0' -- the same two-value bug that false-blocked Gate 8 (#493).
@@ -3055,7 +3081,7 @@ else
           if [ "$CHANGED_TEST_FILE_COUNT" -gt 20 ] 2>/dev/null; then
             # Too many test files changed → full run
             echo "Too many test files changed ($CHANGED_TEST_FILE_COUNT), running full test suite..."
-            TESTS_OUTPUT=$(run_without_git_context npx vitest run --coverage 2>&1)
+            TESTS_OUTPUT=$(run_without_git_context run_node_bin vitest vitest/vitest.mjs run --coverage 2>&1)
             TESTS_EXIT_CODE=$?
             echo "$TESTS_OUTPUT" | head -60
             if [ "$TESTS_EXIT_CODE" -ne 0 ]; then
@@ -3069,7 +3095,7 @@ else
             SMART_TARGETS=$(echo "$SELECTED_TEST_FILES" | tr '\n' ' ')
             echo "Running ${CHANGED_TEST_FILE_COUNT} changed test file(s) with coverage..."
             echo "   Target(s): $(echo "$SELECTED_TEST_FILES" | tr '\n' ' ')"
-            TESTS_OUTPUT=$(run_without_git_context npx vitest run --coverage $SMART_TARGETS 2>&1)
+            TESTS_OUTPUT=$(run_without_git_context run_node_bin vitest vitest/vitest.mjs run --coverage $SMART_TARGETS 2>&1)
             TESTS_EXIT_CODE=$?
             echo "$TESTS_OUTPUT" | head -60
             if [ "$TESTS_EXIT_CODE" -ne 0 ]; then
@@ -3114,7 +3140,7 @@ else
             if [ -n "$RELATED_TESTS" ]; then
               echo "   Found related test(s): $(echo "$RELATED_TESTS" | tr '\n' ' ')"
               PARTIAL_TEST_RUN=true  # Mark as partial run for coverage check
-              TESTS_OUTPUT=$(run_without_git_context npx vitest run --coverage $RELATED_TESTS 2>&1)
+              TESTS_OUTPUT=$(run_without_git_context run_node_bin vitest vitest/vitest.mjs run --coverage $RELATED_TESTS 2>&1)
               TESTS_EXIT_CODE=$?
               echo "$TESTS_OUTPUT" | head -60
               if [ "$TESTS_EXIT_CODE" -ne 0 ]; then
@@ -3125,7 +3151,7 @@ else
             else
               # No related tests found → full run is safest
               echo "   No related test files found, running full test suite..."
-              TESTS_OUTPUT=$(run_without_git_context npx vitest run --coverage 2>&1)
+              TESTS_OUTPUT=$(run_without_git_context run_node_bin vitest vitest/vitest.mjs run --coverage 2>&1)
               TESTS_EXIT_CODE=$?
               echo "$TESTS_OUTPUT" | head -60
               if [ "$TESTS_EXIT_CODE" -ne 0 ]; then
@@ -3982,6 +4008,8 @@ else
     cd "$PROJECT_ROOT" || exit 1
     if [ "$ARCHLINT_KIND" = "npx" ]; then
       npx @archlinter/cli "$@"
+    elif [ "${ARCHLINT_NODE:-0}" = "1" ]; then
+      node "$ARCHLINT_BIN" "$@"
     else
       "$ARCHLINT_BIN" "$@"
     fi
@@ -4002,8 +4030,17 @@ else
     for CURRENT_LANG in $PROJECT_LANGS; do
     case "$CURRENT_LANG" in
       "typescript")
-        # Try local npx install first (devDependencies), fall back to global
-        if [ -x "$PROJECT_ROOT/node_modules/.bin/archlint" ]; then
+        # Prefer node on the package's own entry over the .bin shim: the shim's
+        # exec bit and extension vary by platform and package manager (npm writes
+        # archlint, archlint.cmd and archlint.ps1 on Windows), so `-x .bin/...`
+        # is true here while the no-extension shim is what Git Bash would run.
+        # `node <entry>` sidesteps all of that and also avoids npx's ~1.6 s
+        # package resolution (measured: 1909 ms via npx vs 319 ms direct).
+        if [ -f "$PROJECT_ROOT/node_modules/@archlinter/cli/bin/archlint.js" ] && command -v node >/dev/null 2>&1; then
+          ARCHLINT_KIND="binary"
+          ARCHLINT_BIN="$PROJECT_ROOT/node_modules/@archlinter/cli/bin/archlint.js"
+          ARCHLINT_NODE=1
+        elif [ -x "$PROJECT_ROOT/node_modules/.bin/archlint" ]; then
           ARCHLINT_KIND="binary"
           ARCHLINT_BIN="$PROJECT_ROOT/node_modules/.bin/archlint"
         elif command -v archlint >/dev/null 2>&1; then
@@ -4764,7 +4801,12 @@ if [ -n "$MIRROR_STAGED" ] && printf '%s\n' "$MIRROR_STAGED" | grep -qE '^(githo
     MIRROR_FAIL=0
     while IFS= read -r _mf; do
       [ -n "$_mf" ] || continue
+      # `__tests__/` has no mirror BY DESIGN: sync-package-content.js lists it in
+      # SKIP_DIRS so test suites never ship to consumers. Demanding a mirror for
+      # them makes every new BATS file un-committable -- the two rules contradicted
+      # each other, and the only way past was to edit a generated file by hand.
       case "$_mf" in
+        */__tests__/*) continue ;;
         githooks/*) _mm="src/npm-package/hooks/${_mf#githooks/}" ;;
         plugins/*/src/*) _mm=$(printf '%s' "$_mf" | sed 's|^plugins/\([^/]*\)/src/|src/npm-package/plugins/\1/src/|') ;;
         *) continue ;;
@@ -4880,7 +4922,22 @@ generate_quality_report() {
   local TIMESTAMP
   local BRANCH
   local PASSED_COUNT=0
-  local TOTAL_GATES=12
+  # #680: the gate list is the single source of truth. TOTAL_GATES, the scoring
+  # loop, the console table and the JSON `overall` block all derive from it.
+  #
+  # Gate 13 was added in v0.35.x with only its execution and JSON write -- these
+  # three sites kept saying "12". A machine with no C/C++ compiler therefore saw
+  # `10.0/10 effective`, `gatesWarned: 0` and a table that stopped at Gate 12,
+  # while the JSON `gates` object held 13 keys. "Compiler strictness was never
+  # checked" and "compiler reported zero warnings" rendered identically, which is
+  # the same silent-success pattern as #561/#570/#585.
+  #
+  # Adding a gate now means editing ALL_GATE_NUMBERS + ONE table row. Nothing
+  # else carries a count.
+  local ALL_GATE_NUMBERS="1 2 3 4 5 6 7 8 9 10 11 12 13"
+  local TOTAL_GATES=0
+  local _g
+  for _g in $ALL_GATE_NUMBERS; do TOTAL_GATES=$((TOTAL_GATES + 1)); done
   local SKIP_COUNT=0
   local WARN_COUNT=0
   local NONPASS_COUNT=0
@@ -4908,7 +4965,7 @@ generate_quality_report() {
   local DEGRADED_JSON=""
   local FAIL_COUNT=0
   local FAILED_JSON=""
-  for gate in 1 2 3 4 5 6 7 8 9 10 11 12; do
+  for gate in $ALL_GATE_NUMBERS; do
     local status_var="GATE_${gate}_STATUS"
     # Default mirrors the JSON report rendering below EXACTLY (gates 1-11
     # PASS, gate 12 WARN): a gate that never assigned a status is "not
@@ -4918,6 +4975,10 @@ generate_quality_report() {
     # Default direction is "did not run", never "passed": an unassigned status
     # is a gate that never reached a verdict, and scoring it PASS both claims a
     # success that did not happen and hides the gap in the effective rate.
+    #
+    # Gate 13 defaults to SKIP like the rest: it is only WARN when the toolchain
+    # is missing and the gate explicitly says so, and Gate 12 is the one gate
+    # whose "no verdict" is still a warning rather than "not applicable".
     if [ "$gate" -eq 12 ]; then gate_default="WARN"; else gate_default="SKIP"; fi
     gate_status="${!status_var:-$gate_default}"
     case "$gate_status" in
@@ -5264,6 +5325,9 @@ ENDJSON
   printf "  %-45s %s\n" "Gate 10: SAST Security" "${GATE_10_STATUS:-SKIP}"
   printf "  %-45s %s\n" "Gate 11: Sprint Flow" "${GATE_11_STATUS:-SKIP}"
   printf "  %-45s %s\n" "Gate 12: File Hygiene" "${GATE_12_STATUS:-WARN}"
+  # #680: Gate 13 ran and could block, but had no row here -- the table is what a
+  # human reads, so a gate missing from it reads as a gate that does not exist.
+  printf "  %-45s %s\n" "Gate 13: Compiler Strictness" "${GATE_13_STATUS:-SKIP}"
   echo ""
   # #564: both views in one line. The effective score answers "of the gates that
   # could run, how many passed"; the all-gates score counts a skip against the

package/hooks/pre-push

@@ -426,7 +426,16 @@ SPRINT_GATE_SCRIPT=""
 # ~/.config/xp-gate/hooks -- a correctly installed machine was told the file was
 # missing here too. Nothing is sourced for this: pre-push resolves its libraries
 # further down (ADAPTER_COMMON), and this gate must decide before that.
-for _sprint_gate_dir in "$PROJECT_ROOT/githooks" "$(dirname "$0")" "$HOME/.config/xp-gate/hooks"; do
+#
+# `$HOME/.config/xp-gate/adapters` is the tier #678 found missing: `xp-gate
+# setup-global` runs copyAdapters(), which ships every `gate-*.sh` AND
+# `sprint-gate.sh` into the ADAPTERS directory -- never into hooks/. So a globally
+# installed machine had sprint-gate.sh present under adapters/ while this loop
+# searched only hooks/, and Gate MS skipped on every push without complaint. Both
+# tiers are searched now: which directory `init` chose is an install detail this
+# gate should not depend on.
+for _sprint_gate_dir in "$PROJECT_ROOT/githooks" "$(dirname "$0")" \
+                        "$HOME/.config/xp-gate/hooks" "$HOME/.config/xp-gate/adapters"; do
   if [ -n "$_sprint_gate_dir" ] && [ -f "$_sprint_gate_dir/sprint-gate.sh" ]; then
     SPRINT_GATE_SCRIPT="$_sprint_gate_dir/sprint-gate.sh"
     break
@@ -440,7 +449,7 @@ if [ -n "$SPRINT_GATE_SCRIPT" ]; then
     exit 1
   fi
 else
-  echo "⏭️  SKIPPED - Gate MS: Sprint Flow (sprint-gate.sh not found; searched: $PROJECT_ROOT/githooks, $(dirname "$0"), $HOME/.config/xp-gate/hooks)"
+  echo "⏭️  SKIPPED - Gate MS: Sprint Flow (sprint-gate.sh not found; searched: $PROJECT_ROOT/githooks, $(dirname "$0"), $HOME/.config/xp-gate/hooks, $HOME/.config/xp-gate/adapters)"
   GATE_S_STATUS="SKIP"
 fi
 echo ""

package/lib/__tests__/doctor-delphi.test.js

@@ -337,3 +337,117 @@ describe('doctor delphi (#414 REQ-3/REQ-6)', () => {
     }
   });
 });
+
+// ── #684: the documented global-config fallback ──────────────────────────────
+// SKILL.md tells users to keep ONE machine-level config at
+// `~/.config/xp-gate/.delphi-config.json` and carry no repo-local copy. The
+// runner resolves that fallback, so a review works; the doctor did not, and
+// reported FAIL on a layout its own documentation recommends. Worse, the FAIL
+// detail told the user to copy the example into the project — which manufactures
+// exactly the drifted duplicate that #541 added a shadow warning for.
+//
+// The distinction this batch pins: "no config anywhere" is still a FAIL
+// (that is a genuinely broken install); "no project config but a valid global
+// one" is not.
+describe('doctor delphi #684 global config fallback', () => {
+  let tmpDirs;
+  let tmpHome;
+  let originalHome;
+
+  beforeEach(() => {
+    tmpDirs = makeTempDirs(['doctor-684-home']);
+    tmpHome = tmpDirs['doctor-684-home'];
+    originalHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+    fs.mkdirSync(path.join(tmpHome, '.qoder'), { recursive: true });
+    resetLibModules(vi, LIB_MODULES);
+    muteConsole(vi);
+  });
+
+  afterEach(() => {
+    if (originalHome === undefined) delete process.env.HOME; else process.env.HOME = originalHome;
+    removeTempDirs(tmpDirs);
+    vi.restoreAllMocks();
+  });
+
+  // Local copy: the suite above keeps its own writeConfig inside its describe
+  // scope, so this block cannot reach it.
+  function writeConfig(configPath) {
+    fs.writeFileSync(configPath, JSON.stringify({
+      active_profile: 'default',
+      profiles: {
+        default: {
+          providers: {
+            gw: { base_url: 'https://gw.example/v1', api_key: 'k' },
+          },
+          experts: {
+            architecture: { provider: 'gw', model: 'model-a' },
+            technical: { provider: 'gw', model: 'model-b' },
+            feasibility: { provider: 'gw', model: 'model-c' },
+          },
+        },
+      },
+    }));
+    return configPath;
+  }
+
+  function writeGlobalConfig() {
+    const dir = path.join(tmpHome, '.config', 'xp-gate');
+    fs.mkdirSync(dir, { recursive: true });
+    return writeConfig(path.join(dir, '.delphi-config.json'));
+  }
+
+  function captureLogs() {
+    const logs = [];
+    const spy = vi.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')));
+    return { logs, restore: () => spy.mockRestore() };
+  }
+
+  it('AC-684-01: a valid global config with no project copy PASSes instead of failing', async () => {
+    const globalPath = writeGlobalConfig();
+    const project = path.join(tmpHome, 'a-project-with-no-config');
+    fs.mkdirSync(project, { recursive: true });
+    const { logs, restore } = captureLogs();
+    const { doctorDelphi } = require('../doctor');
+    await doctorDelphi({ projectDir: project, globalConfigPath: globalPath, npmLatest: null });
+    restore();
+    const cfgLine = logs.find((l) => l.includes('Delphi config'));
+    expect(cfgLine).toBeDefined();
+    expect(cfgLine).not.toMatch(/FAIL/);
+    expect(cfgLine).toMatch(/global/i);
+  });
+
+  it('AC-684-02: no config in either scope still FAILs (fallback must not mask a broken install)', async () => {
+    const project = path.join(tmpHome, 'bare-project');
+    fs.mkdirSync(project, { recursive: true });
+    const { logs, restore } = captureLogs();
+    const { doctorDelphi } = require('../doctor');
+    const code = await doctorDelphi({
+      projectDir: project,
+      globalConfigPath: path.join(tmpHome, 'no-such-global.json'),
+      npmLatest: null,
+    });
+    restore();
+    expect(code).toBe(1);
+    // The rendered line carries a ✗ marker, not the literal word FAIL.
+    const cfgLine = logs.find((l) => l.includes('Delphi config (.delphi-config.json)'));
+    expect(cfgLine).toBeDefined();
+    expect(cfgLine).toContain('✗');
+    expect(cfgLine).toMatch(/not found/);
+  });
+
+  it('AC-684-03: a project config still wins over the global one', async () => {
+    const globalPath = writeGlobalConfig();
+    const project = path.join(tmpHome, 'project-with-own-config');
+    fs.mkdirSync(project, { recursive: true });
+    const localPath = writeConfig(path.join(project, '.delphi-config.json'));
+    const { logs, restore } = captureLogs();
+    const { doctorDelphi } = require('../doctor');
+    await doctorDelphi({ projectDir: project, globalConfigPath: globalPath, npmLatest: null });
+    restore();
+    const cfgLine = logs.find((l) => l.includes('Delphi config'));
+    expect(cfgLine).toBeDefined();
+    expect(cfgLine).toContain(localPath);
+    expect(cfgLine).not.toMatch(/global/i);
+  });
+});

package/lib/__tests__/doctor-tui-skill-freshness.test.js

@@ -294,3 +294,77 @@ describe('doctor-tui installed skills enumerate the filesystem (#635)', () => {
     expect(row.status).toBe('PASS');
   });
 });
+
+// ── #681: equal version is not proof of equal content ────────────────────────
+// The freshness check short-circuits on `compareSemver(...) === 0` and answers
+// "Up to date" without ever reading the bodies. A skill that gained a whole
+// chapter without a version bump therefore reported healthy while the installed
+// copy was ~20k characters behind — and `update-skill` agreed with it.
+//
+// The version number is a claim the publisher makes; the content is the fact.
+// When the claim says "same" the fact still has to be checked.
+describe('doctor-tui skill freshness #681 equal version, different content', () => {
+  let tmpHome;
+  let originalHome;
+  const bundledSkillsDir = path.join(__dirname, '..', '..', 'skills');
+
+  beforeEach(() => {
+    originalHome = process.env.HOME;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'xpgate-fresh681-'));
+    process.env.HOME = tmpHome;
+    vi.resetModules();
+    delete require.cache[require.resolve('../doctor-tui')];
+    delete require.cache[require.resolve('../shared-paths')];
+  });
+
+  afterEach(() => {
+    process.env.HOME = originalHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  function installSkill(name, content) {
+    const dir = path.join(tmpHome, '.config', 'opencode', 'skills', name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'SKILL.md'), content);
+  }
+
+  function runFreshness(name) {
+    const { diagnoseInstalledSkills } = require('../doctor-tui');
+    const checks = [];
+    const issues = diagnoseInstalledSkills({ installedSkills: { [name]: {} } }, checks);
+    return { issues, check: checks.find((c) => c.name === `Skill: ${name}`) };
+  }
+
+  it('AC-681-01: same version but a missing chapter is WARN, not "Up to date"', () => {
+    const bundled = fs.readFileSync(path.join(bundledSkillsDir, 'delphi-review', 'SKILL.md'), 'utf8');
+    // Keep the frontmatter (version included), drop a large slice of the body.
+    const idx = bundled.indexOf('\n---', 4);
+    const head = bundled.slice(0, idx + 4);
+    const body = bundled.slice(idx + 4);
+    const truncated = head + body.slice(0, Math.floor(body.length / 2));
+    installSkill('delphi-review', truncated);
+
+    const { issues, check } = runFreshness('delphi-review');
+    expect(check).toBeDefined();
+    expect(check.detail).not.toMatch(/Up to date/);
+    expect(check.status).toBe('WARN');
+    expect(issues).toBe(1);
+  });
+
+  it('AC-681-02: same version and same content is still "Up to date" (no false alarm)', () => {
+    const bundled = fs.readFileSync(path.join(bundledSkillsDir, 'delphi-review', 'SKILL.md'), 'utf8');
+    installSkill('delphi-review', bundled);
+    const { issues, check } = runFreshness('delphi-review');
+    expect(check.detail).toMatch(/Up to date/);
+    expect(issues).toBe(0);
+  });
+
+  it('AC-681-03: line endings alone still do not count as a difference', () => {
+    const bundled = fs.readFileSync(path.join(bundledSkillsDir, 'delphi-review', 'SKILL.md'), 'utf8');
+    installSkill('delphi-review', bundled.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n'));
+    const { issues, check } = runFreshness('delphi-review');
+    expect(check.detail).toMatch(/Up to date/);
+    expect(issues).toBe(0);
+  });
+});

package/lib/__tests__/doctor.test.js

@@ -13,7 +13,16 @@ const util = require('util');
 // tests run in parallel across worker threads.
 const DESCRIBE_ID = String(Math.random().toString(36).slice(2, 8));
 
+// Budget for every case in this file. `doctor --fix` walks the whole install
+// surface (hooks, adapters, config, version cache) and the default 5 s budget is
+// a measurement of an idle machine, not of one running a full suite: under
+// concurrent load the same passing case times out, which reads as a doctor
+// defect. 30 s keeps real hangs bounded while leaving the CPU contention room.
+const DOCTOR_TIMEOUT_MS = 30000;
+
 describe('doctor', () => {
+  // Applies to every `it` below (the per-test arg is only needed when overriding).
+  vi.setConfig({ testTimeout: DOCTOR_TIMEOUT_MS });
   let tmpHome;
   let tmpProject;
   let originalHome;

package/lib/__tests__/gate-numbering.test.js

@@ -0,0 +1,52 @@
+/**
+ * @test REQ-686
+ * @intent 验证 CLI 的门禁编号与钩子一致——钩子把 9 号门叫 Build integrity、
+ *         10 号门叫 SAST，而 CLI 注册表把两者对调了；用户按报错提示单跑对应门
+ *         会跑到另一道门上去（#677）
+ * @covers AC-686-01, AC-686-02, AC-686-03
+ *
+ * 为什么必须直接断言注册表：这个错误的表现是「跑起来了、报告绿了」。
+ * `xp-gate check --gates 9` 在编号错位时不会报错，它跑的是 semgrep 并如实报告
+ * semgrep 的结果——只有拿它和钩子里的门名对照才能看出跑错了门。
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { GATE_REGISTRY, resolveAlias } = require('../gate-runner');
+
+const REPO_ROOT = path.join(__dirname, '../../../..');
+
+describe('gate numbering matches the hook (#677)', () => {
+  it('AC-686-01: gate 9 is Build Integrity and gate 10 is SAST Security', () => {
+    expect(GATE_REGISTRY['9'].name).toBe('Build Integrity');
+    expect(GATE_REGISTRY['10'].name).toBe('SAST Security');
+  });
+
+  it('AC-686-02: the hook agrees — its own output names 9 as Build integrity', () => {
+    // Reads the hook rather than restating the constant: if the hook ever
+    // renumbers again, this fails and points at which side moved.
+    const hook = fs.readFileSync(path.join(REPO_ROOT, 'githooks/pre-commit'), 'utf8');
+    expect(hook).toMatch(/→ Gate 9: Build integrity/);
+    expect(hook).toMatch(/GATE 10: Semgrep SAST/);
+  });
+
+  it('AC-686-03: aliases resolve to the gate the user meant', () => {
+    expect(resolveAlias('sast')).toBe('10');
+    expect(resolveAlias('semgrep')).toBe('10');
+    expect(resolveAlias('build')).toBe('9');
+  });
+
+  it('AC-686-03: gates 12 and 13 are registered instead of "Unknown gate(s)"', () => {
+    // Both block commits in the hook. Answering "Unknown gate" for a gate that just
+    // blocked the user is the same category of wrong as running the wrong one.
+    expect(GATE_REGISTRY['12'].name).toBe('File Hygiene');
+    expect(GATE_REGISTRY['13'].name).toBe('Compiler Strictness');
+    // They are registered as hook-only, with a stated reason -- not as runnable
+    // stubs that would answer PASS without doing the work.
+    expect(GATE_REGISTRY['12'].preCommitOnly).toBe(true);
+    expect(GATE_REGISTRY['13'].preCommitOnly).toBe(true);
+    expect(GATE_REGISTRY['12'].reason).toBeTruthy();
+    expect(GATE_REGISTRY['13'].reason).toBeTruthy();
+  });
+});