@boyingliu01/xp-gate 0.35.18 → 0.35.20

package/adapters/gate-3.sh

@@ -172,8 +172,19 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
                   const entries = baseline.functions || baseline.entries || baseline;
                   if (Array.isArray(entries)) {
                     for (const e of entries) {
-                      if (!e || !e.file || !e.name) continue;
-                      known.set(norm(e.file) + "::" + e.name, Number(e.ccn) || 0);
+                      // #632: accept the key the baseline WRITER actually emits.
+                      // tools/Update-ComplexityBaseline.ps1 (the tool this gate
+                      // points at in its own fix-it message) writes "function",
+                      // while this reader only knew "name" -- so every entry was
+                      // dropped, "known" stayed empty, and every function above
+                      // the threshold became a brand-new function. The ratchet
+                      // could never pass. Both spellings are read: this is a
+                      // reader, and the writer vocabulary is not ours to
+                      // redefine from here.
+                      if (!e || !e.file) continue;
+                      const fnName = e.name || e.function;
+                      if (!fnName) continue;
+                      known.set(norm(e.file) + "::" + fnName, Number(e.ccn) || 0);
                     }
                   }
                   // The measurement emits ABSOLUTE paths (pwsh resolved them), while
@@ -450,6 +461,52 @@ else
           GATE_3_DETAIL="mode=ratchet verifier=MISSING"
           exit 1
         fi
+        RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"
+        [ -f "$RATCHET_LIB" ] || RATCHET_LIB="$(git rev-parse --show-toplevel 2>/dev/null)/githooks/lib/ccn-ratchet.sh"
+        # #617: grade exactly the population the baseline was written from.
+        #
+        # The comment below has always said so, but only as a comment: a repo whose
+        # baseline came from a narrower scan (a Java-only ccn-report, say) had its
+        # vendored minified JS graded anyway, and --csv-verified then disagreed with
+        # lizard on single-line code and fail-closed with "could not be
+        # span-verified". That BLOCK has no repair: the file has no baseline entry
+        # to ratchet, so there is nothing the user could add to clear it.
+        #
+        # The population filter runs BEFORE verification on purpose. Domain
+        # restriction is decidable from the path alone, so asking the expensive
+        # span re-derivation about a file that will not be graded anyway only
+        # manufactures failures for code the ratchet never claims to cover.
+        if [ -f "$RATCHET_LIB" ]; then
+          # shellcheck source=/dev/null
+          . "$RATCHET_LIB" 2>/dev/null || true
+          if declare -F ccn_file_in_population >/dev/null 2>&1; then
+            _cc_pop_kept=""
+            _cc_pop_skipped=""
+            while IFS= read -r _cc_row; do
+              [ -n "$_cc_row" ] || continue
+              _cc_row_path=$(printf '%s' "$_cc_row" | awk -F, '{print $1}')
+              if ccn_file_in_population ".ccn-baseline.json" "$_cc_row_path"; then
+                _cc_pop_kept="${_cc_pop_kept}${_cc_row}
+"
+              else
+                _cc_pop_skipped="${_cc_pop_skipped}${_cc_row_path}
+"
+              fi
+            done <<CC_POP_EOF
+$CC_CSV
+CC_POP_EOF
+            CC_CSV=$(printf '%s' "$_cc_pop_kept")
+            if [ -n "$_cc_pop_skipped" ]; then
+              _cc_pop_skip_n=$(printf '%s' "$_cc_pop_skipped" | grep -c . || true)
+              echo "ℹ️  Gate 3: ${_cc_pop_skip_n:-0} file(s) outside the baseline population — not graded, not ratcheted:"
+              printf '%s' "$_cc_pop_skipped" | sed 's/^/     /' | sed -n '1,5p'
+              if [ "${_cc_pop_skip_n:-0}" -gt 5 ]; then
+                echo "     ... and $((_cc_pop_skip_n - 5)) more"
+              fi
+              echo "     (declare or widen the population in .ccn-baseline.json to grade them)"
+            fi
+          fi
+        fi
         if [ -f "$CC_REPORT" ] && command -v node >/dev/null 2>&1; then
           _cc_verify_failed=0
           CC_CSV_VERIFIED=$(printf '%s\n' "$CC_CSV" | node "$CC_REPORT" --csv-verified batch --root "$(git rev-parse --show-toplevel 2>/dev/null)") || _cc_verify_failed=1
@@ -460,8 +517,6 @@ else
           fi
           CC_CSV="$CC_CSV_VERIFIED"
         fi
-        RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"
-        [ -f "$RATCHET_LIB" ] || RATCHET_LIB="$(git rev-parse --show-toplevel 2>/dev/null)/githooks/lib/ccn-ratchet.sh"
         # Fail closed when the ratchet library is missing. Sourcing a nonexistent
         # file only prints "No such file or directory" and leaves
         # evaluate_ccn_ratchet undefined; the verdict then came back empty, every
@@ -529,13 +584,43 @@ else
       # this, a crashing or mis-invoked lizard yields 0 warnings and the gate
       # reports PASSED on zero analysed functions -- the same silent-success
       # failure this issue is about.
+      #
+      # #666: "no rows" has TWO causes and they must not share a verdict. A
+      # module of pure constants legitimately has zero functions, and lizard
+      # emits no row for it at all (measured: `lizard pure_data.py --csv` prints
+      # nothing and exits 0). That was reported as `lizard_output_unparsable`
+      # /WARN, which is the message for a BROKEN lizard -- so a healthy run on a
+      # data-only diff was indistinguishable from a tooling fault. The two are
+      # separated by a POSITIVE probe: ask lizard to describe a fixture known to
+      # contain a function. If it produces rows, lizard works and the input
+      # simply had no functions (SKIP, `no_functions_in_input`); if it does not,
+      # the tool really is broken (WARN, `lizard_output_unparsable`).
       if ! printf '%s\n' "$CC_CSV_FLAT" | awk -F, 'NF > 1 && $2 ~ /^[0-9]+$/ { found = 1; exit }
                                                  END { exit(found ? 0 : 1) }'; then
-        echo "⚠️  WARN - lizard produced no parsable results; complexity not verified"
-        GATE_3_STATUS="WARN"
-        # Consumed by the sourcing parent (pre-commit report JSON), not here.
-        # shellcheck disable=SC2034
-        GATE_3_REASON="lizard_output_unparsable"
+        _lizard_probe_dir=$(mktemp -d 2>/dev/null || echo "${TMPDIR:-/tmp}")
+        _lizard_probe_file="$_lizard_probe_dir/xp-gate-lizard-probe.py"
+        printf 'def _xp_gate_probe(x):\n    if x:\n        return 1\n    return 0\n' > "$_lizard_probe_file" 2>/dev/null
+        _lizard_probe_rows=0
+        if [ -f "$_lizard_probe_file" ]; then
+          _lizard_probe_rows=$(printf '%s\n' "$_lizard_probe_file" \
+            | lizard_batches --csv 2>/dev/null \
+            | awk -F, 'NF > 1 && $2 ~ /^[0-9]+$/ { c++ } END { print c + 0 }')
+        fi
+        rm -rf "$_lizard_probe_dir" 2>/dev/null || true
+        if [ "${_lizard_probe_rows:-0}" -gt 0 ]; then
+          echo "⏭️  SKIPPED - Complexity: the changed source files define no functions (pure data module)."
+          echo "   Verified: lizard parsed a probe fixture normally, so this is an empty result set, not a broken tool."
+          GATE_3_STATUS="SKIP"
+          # Consumed by the sourcing parent (pre-commit report JSON), not here.
+          # shellcheck disable=SC2034
+          GATE_3_REASON="no_functions_in_input"
+        else
+          echo "⚠️  WARN - lizard produced no parsable results; complexity not verified"
+          GATE_3_STATUS="WARN"
+          # Consumed by the sourcing parent (pre-commit report JSON), not here.
+          # shellcheck disable=SC2034
+          GATE_3_REASON="lizard_output_unparsable"
+        fi
       elif [ "$CC_WARNINGS" -gt 0 ]; then
         echo "$CC_OUTPUT"
         echo ""

package/adapters/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 ""
@@ -165,42 +172,30 @@ else
         rm -f "$PRINCIPLES_STDERR"
 
         if [ "$PRINCIPLES_EXIT" -ge 2 ]; then
-          # Fail-closed (#661), same rule as Gate 8 (#499): a gate that cannot run
-          # must not report success.
+          # #661: exit>=2 means the checker did not RUN (crash, module not found,
+          # bad invocation). This used to record SKIP, and pre-commit treats SKIP
+          # as non-blocking, so a tool failure was absorbed into the green light --
+          # the reproduction printed a module-not-found stack trace and then
+          # "✅ PASSED - Principles checker (no errors found)".
           #
-          # This branch used to settle on SKIP, which the caller reads as
-          # non-blocking -- so a checker that crashed on startup
-          # (`Cannot find module 'C:\c\Users\...'`, the POSIX-path-to-native-node
-          # bug) still printed "PASSED - Principles checker (no errors found)".
-          # The path conversion fixed that one cause; any other way of breaking
-          # the launch (missing tsx, corrupt module, OOM) lands here too, and all
-          # of them would have been absorbed into a green light.
+          # The distinction the gate must keep:
+          #   - tool NOT INSTALLED  -> SKIP is honest; nothing is being claimed.
+          #   - tool PRESENT, CRASH -> WARN. Not a pass (nothing was checked) and
+          #     not a silent skip (the user must know their code went unaudited).
           #
-          # SKIP stays reserved for "language not applicable / tool not
-          # installed", which is not what this is: the checker exists and failed.
-          echo ""
-          echo "❌ BLOCKED - Principles checker failed to execute (exit $PRINCIPLES_EXIT)"
-          echo "This is a tool fault, NOT a clean result. A gate that cannot run must not pass."
-          echo "  Fix the checker, or set PRINCIPLES_SKIP_TOOL_FAULT=1 to downgrade to a warning."
-          echo "  (downgrade is audit-logged and never allowed on main/master)"
-          GATE_4_STATUS="FAIL"
+          # WARN rather than FAIL on purpose: the commit itself is not necessarily
+          # bad, the TOOL is broken, and blocking every commit until node/tsx is
+          # repaired would blame the change for an environment fault. What must
+          # never happen is the green light.
+          echo "⚠️  Principles checker did not run (exit ${PRINCIPLES_EXIT}) — this code is NOT verified."
+          echo "     Gate 4 cannot claim a pass for a check that never executed."
+          echo "     Fix the checker invocation above (or run 'npx xp-gate check principles .')."
+          echo "⏭️  WARN - Principles check (checker execution error)"
+          GATE_4_STATUS="WARN"
+          # Consumed by the sourcing parent, not here (see #548).
           # shellcheck disable=SC2034
           GATE_4_REASON="checker_execution_error"
           rm -f "$PRINCIPLES_JSON"
-          if [ "${PRINCIPLES_SKIP_TOOL_FAULT:-0}" = "1" ]; then
-            echo "⚠️  ESCAPE VALVE: PRINCIPLES_SKIP_TOOL_FAULT=1 — downgrading to SKIP"
-            # Same asymmetry as Gate 5a: a downgrade is tolerable on a feature
-            # branch, never on main/master, where it would green-light the trunk.
-            _g4_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
-            if [ "$_g4_branch" = "main" ] || [ "$_g4_branch" = "master" ]; then
-              echo "❌ ESCAPE VALVE BLOCKED: PRINCIPLES_SKIP_TOOL_FAULT not allowed on $_g4_branch"
-              GATE_4_STATUS="FAIL"
-              exit 1
-            fi
-            GATE_4_STATUS="SKIP"
-          else
-            exit 1
-          fi
         else
           # Check severity levels. The reporter emits JSON.stringify(out, null, 2),
           # i.e. `"severity": "warning"` WITH a space; tolerate any whitespace so a

package/adapters/gate-8.sh

@@ -59,10 +59,24 @@ fi
 # revisions and reports "0 commits scanned" on a pre-commit run -- so a staged
 # secret was never seen and Gate 8 always passed. `git --staged` scans
 # `git diff --cached`, which is exactly the pre-commit payload (#449).
+#
+# #616: `--all` is a different question, and the index is the wrong place to ask
+# it. Under `xp-gate check . --all` the user asked "is the whole tree clean", the
+# index is usually empty, `git --staged` legitimately found nothing, and that
+# nothing was counted as PASSED -- a secret sitting in a tracked file was
+# invisible to the one command meant to find it. The runner already exports
+# GATE_SCOPE (#589); this fragment just has to read it. `dir --no-git` scans the
+# filesystem so tracked-but-unmodified files are covered.
 GITLEAKS_REPORT="${TMPDIR:-/tmp}/gitleaks-report.json"
 rm -f "$GITLEAKS_REPORT"
-GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --staged --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
-GITLEAKS_EXIT=$?
+if [ "${GATE_SCOPE:-diff}" = "all" ]; then
+  echo "     Scope: --all (scanning the working tree, not the index)"
+  GITLEAKS_OUTPUT=$($GITLEAKS_CMD dir --no-git --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
+  GITLEAKS_EXIT=$?
+else
+  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --staged --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
+  GITLEAKS_EXIT=$?
+fi
 
 if [ "$GITLEAKS_EXIT" -eq 0 ]; then
   # Decide SKIP from the REPORT ARTIFACT, not from log wording. Parsing stdout
@@ -183,7 +197,22 @@ fi
 # if-condition (errexit-exempt); a non-zero hook exit lands in the else branch.
 if command -v detect-secrets-hook >/dev/null 2>&1 && [ -f ".secrets.baseline" ]; then
   DS_TMP="$(dirname "$(mktemp -u)")/ds-output.$$"
-  if git diff --cached --name-only --diff-filter=ACM -z \
+  # #616: same scope split as the gitleaks call above. Under `--all` the index is
+  # usually empty, so piping `git diff --cached -z` into xargs fed the hook zero
+  # files and it reported success without reading anything.
+  if [ "${GATE_SCOPE:-diff}" = "all" ]; then
+    if git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline > "$DS_TMP" 2>&1; then
+      echo "     ✅ detect-secrets PASSED - no new secrets beyond baseline (scope: --all)."
+    else
+      cat "$DS_TMP"
+      echo ""
+      echo "     ❌ BLOCKED - detect-secrets found secrets not in .secrets.baseline."
+      echo "   If these are false positives, regenerate the baseline (cross-platform):"
+      echo "     detect-secrets scan --update .secrets.baseline && git add .secrets.baseline"
+      rm -f "$DS_TMP"
+      exit 1
+    fi
+  elif git diff --cached --name-only --diff-filter=ACM -z \
       | xargs -0 detect-secrets-hook --baseline .secrets.baseline > "$DS_TMP" 2>&1; then
     echo "     ✅ detect-secrets PASSED - no new secrets beyond baseline."
   else

package/adapters/gate-9.sh

@@ -32,8 +32,20 @@ if [ -z "$SEMGREP_CMD" ]; then
   echo "     Gate 9: SAST Security (WARN, semgrep not installed)"
   GATE_9_STATUS="WARN"
 else
-  # Get staged files filtered to Semgrep-supported languages
-  SEMGREP_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
+  # Get staged files filtered to Semgrep-supported languages.
+  #
+  # #616: under `--all` the index is usually empty, so the staged diff yielded no
+  # files and the gate reported SKIPPED -- "no supported language files changed"
+  # -- for a run whose whole purpose was to scan the tree. Same fail-open shape
+  # #589 fixed in Gate 3, one layer down: the CLI says the tree was checked and
+  # the fragment checks a diff that does not exist. The runner exports GATE_SCOPE;
+  # read it and enumerate tracked files instead.
+  if [ "${GATE_SCOPE:-diff}" = "all" ]; then
+    echo "     Scope: --all (scanning tracked files, not the index)"
+    SEMGREP_FILES=$(git ls-files 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
+  else
+    SEMGREP_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
+  fi
 
   if [ -z "$SEMGREP_FILES" ]; then
     echo "     ⏭️  SKIPPED - SAST (no supported language files changed)"

package/hooks/pre-commit

@@ -4017,6 +4017,30 @@ else
 
   # Check if architecture config exists (use $PROJECT_ROOT — hook may have cd'd to a subdir via ARCH-03)
   if [ -f "$PROJECT_ROOT/architecture.yaml" ] || [ -f "$PROJECT_ROOT/.architecturerc" ] || [ -f "$PROJECT_ROOT/.archlint.yaml" ]; then
+    # #686: an `architecture.yaml` is NOT evidence that layer boundaries are
+    # checked. Gate 6 only ever tested for the file's existence; archlint is
+    # invoked without --config, and even with a config it cannot enforce layers:
+    # @archlinter/cli 0.16.0 lists a `layer_violation` detector but produces no
+    # results for it under any configuration (-A, -d layer_violation, enabled:
+    # true, globs, exact paths — all exit 0 with zero layer findings). See
+    # docs/plans/2026-11-02-arch-01-gate6-layers-not-enforced-design.md §2.2.
+    #
+    # So a repo that declares layers gets a generic-smell check and a green
+    # verdict, which reads as "layers are clean". It is not: nothing looked.
+    # This block records that fact as a per-language reason so the quality
+    # report cannot score the dimension as covered, and emits a marker the
+    # terminal output can be asserted against.
+    #
+    # Deliberately NOT a capability probe: archlint silently tolerates unknown
+    # config keys, so "it did not complain" is a tautological guard — it would
+    # return "supported" no matter what. File presence is the only honest input.
+    GATE_6_LAYERS_UNCHECKED=0
+    if [ -f "$PROJECT_ROOT/architecture.yaml" ] || [ -f "$PROJECT_ROOT/.architecturerc" ]; then
+      GATE_6_LAYERS_UNCHECKED=1
+      echo "     ⚠️  [WARN:LAYERS_UNCHECKED] 分层规则未校验：architecture.yaml 声明的层边界当前不被任何检测器消费"
+      echo "        (实测 @archlinter/cli 0.16.0 的 layer_violation 启用后亦无输出；见 #686)"
+      echo "        本次仅校验通用架构坏味道（循环依赖 / 上帝类 / 死代码）。"
+    fi
     # #537: per-language reason bookkeeping. Gate 3/4 are single-language gates
     # and get away with one scalar reason; Gate 6 loops, so a scalar would lose
     # information ("TS passed, PS has no detector" cannot be one string).
@@ -4265,6 +4289,20 @@ JAVAARCHROOTS
     GATE_6_LANG_REASONS=""
     _g6_seen=""
     _g6_mixed=0
+    # #686: a language that archlint actually measured and passed still carries a
+    # reason when the repo declared layer boundaries, because the layer dimension
+    # itself was never measured. Only languages WITHOUT a reason get this stamp —
+    # an existing reason (tool missing, tests failed, ...) is more specific and
+    # must not be overwritten. The `-z` test is what keeps this honest: stamping
+    # unconditionally would erase the real reason and make every language look
+    # alike in the report.
+    if [ "${GATE_6_LAYERS_UNCHECKED:-0}" = "1" ] && [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
+      for _g6_lang in $PROJECT_LANGS; do
+        if [ -z "${GATE_6_REASON_BY_LANG[$_g6_lang]:-}" ]; then
+          GATE_6_REASON_BY_LANG["$_g6_lang"]="layers_config_not_enforced"
+        fi
+      done
+    fi
     for _g6_lang in $PROJECT_LANGS; do
       _g6_r=""
       if [ "${BASH_VERSINFO[0]:-0}" -ge 4 ]; then
@@ -4313,19 +4351,27 @@ JAVAARCHROOTS
       echo "   Required configuration file (.archlint.yaml / architecture.yaml) is NOT found."
       echo "   Architecture Quality Gate requires explicit architecture constraints."
       echo ""
-  echo "   Quick fix: create .archlint.yaml with: npx archlint init --no-interactive"
-      echo "   Or architecture.yaml for custom Clean Architecture layer definitions:"
-      echo "     layers:"
-      echo "       - name: api"
-      echo "         paths: [\"src/api/**\"]"
-      echo "       - name: domain"
-      echo "         paths: [\"src/domain/**\"]"
-      echo "         allowed_imports: [domain]"
-      echo "       - name: infrastructure"
-      echo "         paths: [\"src/infrastructure/**\"]"
-      echo "         allowed_imports: [domain, infrastructure]"
+      echo "   Quick fix: create .archlint.yaml with: npx archlint init --no-interactive"
+      echo "   Or write one by hand — this is archlint's own config format, and the"
+      echo "   only one it actually reads:"
+      echo "     rules:"
+      echo "       cyclic_dependency:"
+      echo "         severity: high"
+      echo "       god_module:"
+      echo "         severity: high"
+      echo ""
+      # #686: this used to recommend a top-level `layers:` block. That format is
+      # silently ignored by @archlinter/cli 0.16.0 (verified against a fixture
+      # with a textbook domain->infra violation: the layer_violation detector is
+      # listed by `archlint detectors list` but produces no results under any
+      # configuration, including -A and an explicit -d layer_violation). The hint
+      # therefore taught users to write a file that bought them nothing while
+      # Gate 6 reported green — the worst possible combination.
+      echo "   NOTE: layer-boundary rules are NOT enforced by archlint 0.16.0."
+      echo "   Do not write a top-level 'layers:' block expecting it to be checked;"
+      echo "   Gate 6 will tell you when that changes. See #686 / #690 / #692."
       echo ""
-      echo "   After creating architecture.yaml, retry the commit."
+      echo "   After creating the config, retry the commit."
       echo "   (To skip with warning, create .architecture-skip file)"
       exit 1
     fi

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