diff --git a/.github/workflows/pr-build.yml b/.github/workflows/pr-build.yml
index 5c71aba493..249bcaf28f 100644
--- a/.github/workflows/pr-build.yml
+++ b/.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