ci(coverage): polish diff-cover step and clarify metric semantics

- Guard against empty SRC_ROOTS before invoking diff-cover; exits with a
  readable error instead of letting --fail-under be consumed as a
  src-root value.
- Verify that diff-cover actually wrote diff-cover.json; surface the
  exit code in the failure message so a runner/binary crash is
  diagnosable without hunting through logs.
- Drop the trailing "diff-cover exit code" log; --fail-under=0 means
  DIFF_RC is always 0 in the happy path, so the line carries no signal.
- Clarify the metrics panel: Changed-line is LINE coverage (diff-cover)
  while Overall / Delta are INSTRUCTION coverage (jacoco-report). Add a
  footnote to both the console output and the step summary so readers
  do not silently compare the two counters.

Author: bladehan1

.github/workflows/pr-build.yml

@@ -298,6 +298,10 @@ jobs:
           PR_XMLS=$(find coverage/pr -name "jacocoTestReport.xml" | sort)
           SRC_ROOTS=$(find . -type d -path '*/src/main/java' \
             -not -path './coverage/*' -not -path './.git/*' | sort)
+          if [ -z "$SRC_ROOTS" ]; then
+            echo "No src/main/java directories found; cannot run diff-cover." >&2
+            exit 1
+          fi
 
           set +e
           diff-cover $PR_XMLS \
@@ -309,6 +313,11 @@ jobs:
           DIFF_RC=$?
           set -e
 
+          if [ ! -f diff-cover.json ]; then
+            echo "diff-cover did not produce JSON report (exit=${DIFF_RC})." >&2
+            exit 1
+          fi
+
           TOTAL_NUM_LINES=$(jq -r '.total_num_lines // 0' diff-cover.json)
           if [ "${TOTAL_NUM_LINES}" = "0" ]; then
             echo "No changed Java source lines; skipping changed-line gate."
@@ -332,8 +341,6 @@ jobs:
             fi
           } >> "$GITHUB_STEP_SUMMARY"
 
-          echo "diff-cover exit code: ${DIFF_RC}"
-
       - name: Aggregate base coverage
         id: jacoco-base
         uses: madrapps/jacoco-report@v1.7.2
@@ -431,6 +438,7 @@ jobs:
           Delta (PR - Base): ${DELTA}%
           Changed-line Gate: ${CHANGED_LINE_STATUS}
           Overall Delta Gate: ${OVERALL_STATUS}
+          Note: Changed-line uses LINE coverage (diff-cover); Overall/Delta use INSTRUCTION coverage (jacoco-report). The two counters are not directly comparable.
           EOF
           )
 
@@ -445,6 +453,8 @@ jobs:
             echo "- Delta (PR - Base): ${DELTA}%"
             echo "- Changed-line Gate: ${CHANGED_LINE_STATUS}"
             echo "- Overall Delta Gate: ${OVERALL_STATUS}"
+            echo ""
+            echo "_Note: Changed-line uses LINE coverage (diff-cover); Overall/Delta use INSTRUCTION coverage (jacoco-report). The two counters are not directly comparable._"
           } >> "$GITHUB_STEP_SUMMARY"
 
           # 4) Decide CI pass/fail