@boyingliu01/xp-gate 0.34.0 → 0.35.0

package/gate-13-compiler-strictness.sh

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

package/gate-3.sh

@@ -461,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
@@ -471,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

package/gate-4.sh

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

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

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

package/hooks/gate-3.sh

@@ -461,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
@@ -471,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

package/hooks/gate-4.sh

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

package/hooks/lib/ccn-ratchet.sh

@@ -11,6 +11,23 @@
 # improves we say so and suggest refreshing the baseline, because a stale
 # ceiling invites nobody to finish the job.
 #
+# ── Population (#617) ───────────────────────────────────────────────────────
+# A ratchet is only meaningful over the population it was recorded from. Gate 3
+# grades every extension it recognises; a repo whose baseline came from a
+# narrower scan then reports pre-existing code as "new", which is a false BLOCK
+# no repair can clear — the file has no baseline entry to fix.
+#
+# The baseline may therefore DECLARE its population:
+#
+#   { "population": { "roots": ["src/main/java"], "extensions": [".java"] },
+#     "entries": { "src/main/java/A.java::f": 4 } }
+#
+# A baseline without that key is LEGACY and is treated as unrestricted, which is
+# exactly the historical behaviour: every baseline already in the field has the
+# flat `{ "path::fn": ccn }` shape, and refusing to load it would break every
+# install on upgrade. Absent metadata must never be read as an empty population
+# -- that would silently grade nothing at all, the opposite failure.
+#
 # Key = "<relative/path>::<functionName>". Rename or move = new key = treated
 # as a new function. That is deliberate: fuzzy matching would hide debt moves.
 # `node scripts/ccn-report.cjs --write-baseline` regenerates the file after a
@@ -41,6 +58,98 @@
 # every row is read as a single field).
 CSV_FS=$'\x1f'
 
+# ---------------------------------------------------------------------------
+# #617: baseline population.
+#
+# Prints the declared population as `<root>|<ext>|<ext>...` on one line, or
+# NOTHING when the baseline carries no `population` key (legacy => unrestricted).
+# Printing nothing is deliberate: "no declaration" and "empty population" are
+# opposite meanings, and a caller that cannot tell them apart would either grade
+# everything (wrong for a Java-only repo) or nothing (catastrophic -- the ratchet
+# would report a clean run while comparing zero functions).
+# ---------------------------------------------------------------------------
+ccn_baseline_population() {
+  local _bl="${1:-.ccn-baseline.json}"
+  [ -f "$_bl" ] || return 0
+  command -v node >/dev/null 2>&1 || return 0
+  node -e '
+    const fs = require("fs");
+    let data;
+    try { data = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); }
+    catch { process.exit(0); }
+    // Legacy shape: a flat map of "path::fn" -> ccn. No declaration.
+    if (!data || typeof data !== "object" || !data.population) process.exit(0);
+    const pop = data.population || {};
+    const roots = Array.isArray(pop.roots) ? pop.roots : [];
+    const exts = Array.isArray(pop.extensions) ? pop.extensions : [];
+    // A declared-but-empty population is not a legitimate declaration: it would
+    // excuse every file. Treat it as no declaration so the gate keeps grading.
+    if (roots.length === 0 && exts.length === 0) process.exit(0);
+    // One line: "<roots csv>|<exts csv>". Callers split on the single pipe.
+    process.stdout.write(roots.join(",") + "|" + exts.join(","));
+  ' "$_bl" 2>/dev/null
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# #617: is this file inside the baseline's declared population?
+#
+# Returns 0 when the file may be graded, 1 when it is outside the population.
+# A legacy baseline (no declaration) permits everything, preserving the
+# behaviour every existing install already relies on.
+#
+# Both axes are ANDed only when both are declared; a baseline declaring just
+# roots (or just extensions) narrows on that axis alone.
+# ---------------------------------------------------------------------------
+ccn_file_in_population() {
+  local _bl="${1:-.ccn-baseline.json}"
+  local _file="${2:-}"
+  [ -n "$_file" ] || return 1
+
+  local _pop
+  _pop=$(ccn_baseline_population "$_bl")
+  # No declaration => unrestricted (legacy baseline).
+  [ -n "$_pop" ] || return 0
+
+  local _roots="${_pop%%|*}"
+  local _exts="${_pop#*|}"
+  # Normalise separators so a Windows path and a POSIX path compare the same way.
+  # sed, not `tr '\' '/'`: a lone backslash is a portability trap in tr's SET
+  # argument (GNU tr warns "unescaped backslash at end of string" and MSYS tr
+  # behaviour differs), while the sed regex below is unambiguous everywhere.
+  _norm=$(printf '%s' "$_file" | sed 's|\\|/|g')
+
+  if [ -n "$_roots" ]; then
+    local _hit=0 _r
+    local _oldifs="$IFS"
+    IFS=','
+    for _r in $_roots; do
+      IFS="$_oldifs"
+      case "$_norm" in
+        "$_r"|"$_r"/*) _hit=1; break ;;
+      esac
+    done
+    IFS="$_oldifs"
+    [ "$_hit" -eq 1 ] || return 1
+  fi
+
+  if [ -n "$_exts" ]; then
+    local _match=0 _e
+    local _oldifs2="$IFS"
+    IFS=','
+    for _e in $_exts; do
+      IFS="$_oldifs2"
+      case "$_norm" in
+        *"$_e") _match=1; break ;;
+      esac
+    done
+    IFS="$_oldifs2"
+    [ "$_match" -eq 1 ] || return 1
+  fi
+
+  return 0
+}
+
 csv_to_unit_separated() {
   awk '
     function emit(line,   cur, i, ch, q, nf) {