fix(coverage+validation): C2/C3 script gate, V1/V2/V4 JSON/XML errors, I2/I3/I4 tests

C2: Fix coverage.sh — remove || true from lcov capture/extract steps so real
    lcov failures are visible; empty coverage.info now exits with code 3.
C3: Add coverage gate to quality-gates CI job (SKIP_COVERAGE_GATE=1 ramp-up
    mode until I5 is resolved — fast suite covers ~9.6% not 80%). Thresholds:
    80% line / 70% branch / 90% function (agreed 2026-05-31).

V1: Wrap JSON parse + field extraction in try/catch — nlohmann parse_error and
    type_error now surface as std::runtime_error with the file path.
V2: Wrap stoi/stod in XML Solver parser — missing/non-numeric attributes throw
    std::runtime_error instead of leaking std::invalid_argument.
V4: Validate required JSON keys (dof_vector, solver, solver.*) before access —
    missing field produces a clear named-field error message.

I2: 6 serialization negative tests (missing file, malformed JSON, missing
    dof_vector, missing solver block, missing XML file, non-numeric XML attr).
I3: load_mesh throws on non-triangulated (quad) mesh — covers the
    is_triangle_mesh guard that was previously untested.
I4: spherical_hessian throws on edge DOFs — covers the logic_error guard.

290/290 tests pass (+8 new).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

scripts/quality/coverage.sh

@@ -9,9 +9,9 @@
 #   * build-coverage/lcov-html/index.html — browseable HTML report
 #   * stdout: per-file summary + grand total
 #
-# Local-only.  Not gated in CI yet; once a coverage threshold is agreed
-# with the reviewer (e.g. 80 %), the gate can be a single line in
-# cpp-tests.yml.
+# Local + CI.  Threshold gate: 80 % line / 70 % branch / 90 % function.
+# Set SKIP_COVERAGE_GATE=1 to measure without failing (ramp-up mode).
+# CI: invoked from cpp-tests.yml test-cgal job (after the full suite runs).
 #
 # Usage:
 #   bash scripts/quality/coverage.sh              # gcc default
@@ -20,9 +20,11 @@
 # Prerequisites: gcov + lcov (apt install lcov / brew install lcov)
 #
 # Exit codes:
-#   0  coverage report generated; prints %
+#   0  coverage report generated and all thresholds met
 #   1  tests failed (no usable trace)
-#   2  prerequisite missing
+#   2  prerequisite missing (lcov / compiler not found)
+#   3  coverage.info is empty after lcov run (version mismatch)
+#   4  coverage below threshold
 
 set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
@@ -92,20 +94,24 @@ LCOV_TOLERANT=(
     --rc lcov_branch_coverage=1
 )
 
+# C2 fix: capture and extract must succeed (or we have no valid trace).
+# The --ignore-errors flags above suppress the gcov-version noise; any
+# remaining error is real (e.g. no .gcda files, compiler mismatch) and
+# should be visible as a non-zero exit.
 lcov --capture --directory "$BUILD_DIR" \
      --output-file "$BUILD_DIR/coverage.raw.info" \
      --no-external \
      "${LCOV_TOLERANT[@]}" \
-     >/dev/null 2>&1 || true
+     >/dev/null 2>&1
 
 # Restrict to code/include/  (our public API surface; ignore deps/tests).
 lcov --extract "$BUILD_DIR/coverage.raw.info" \
      "*/code/include/*" \
      --output-file "$BUILD_DIR/coverage.info" \
      "${LCOV_TOLERANT[@]}" \
-     >/dev/null 2>&1 || true
+     >/dev/null 2>&1
 
-# ── HTML report ──────────────────────────────────────────────────────────────
+# ── HTML report (best-effort; failure here does not fail the script) ──────────
 genhtml --branch-coverage --legend \
         --output-directory "$BUILD_DIR/lcov-html" \
         "${LCOV_TOLERANT[@]}" \
@@ -114,15 +120,69 @@ genhtml --branch-coverage --legend \
 # ── Summary to stdout ────────────────────────────────────────────────────────
 echo
 echo "── Coverage summary (code/include/) ─────────────────────────"
-if [ -s "$BUILD_DIR/coverage.info" ]; then
-    lcov --summary "$BUILD_DIR/coverage.info" "${LCOV_TOLERANT[@]}" 2>/dev/null \
-        | grep -E "lines\.\.\.\.|functions|branches" \
-        | sed 's/^/    /'
-    echo
-    echo "HTML report:  $BUILD_DIR/lcov-html/index.html"
-    echo "              open $BUILD_DIR/lcov-html/index.html"
-else
-    echo "    WARN: coverage.info is empty — likely an lcov/gcov version"
-    echo "          mismatch.  Tests passed; raw .gcda files are in $BUILD_DIR."
-    echo "          Inspect with:  find $BUILD_DIR -name '*.gcda' | head"
+if [ ! -s "$BUILD_DIR/coverage.info" ]; then
+    echo "    FAIL: coverage.info is empty — likely an lcov/gcov version" >&2
+    echo "          mismatch.  Tests passed; raw .gcda files are in $BUILD_DIR." >&2
+    echo "          Inspect with:  find $BUILD_DIR -name '*.gcda' | head" >&2
+    exit 3
 fi
+
+lcov --summary "$BUILD_DIR/coverage.info" "${LCOV_TOLERANT[@]}" 2>/dev/null \
+    | grep -E "lines\.\.\.\.|functions|branches" \
+    | sed 's/^/    /'
+echo
+echo "HTML report:  $BUILD_DIR/lcov-html/index.html"
+echo "              open $BUILD_DIR/lcov-html/index.html"
+echo
+
+# ── Coverage threshold gate (C3) ─────────────────────────────────────────────
+# Agreed thresholds (2026-05-31): 80 % line / 70 % branch / 90 % function.
+# Set SKIP_COVERAGE_GATE=1 to print without failing (useful during ramp-up).
+THRESHOLD_LINE=80
+THRESHOLD_BRANCH=70
+THRESHOLD_FUNC=90
+
+if [ "${SKIP_COVERAGE_GATE:-0}" = "1" ]; then
+    echo "NOTE: SKIP_COVERAGE_GATE=1 — thresholds not enforced."
+    exit 0
+fi
+
+SUMMARY=$(lcov --summary "$BUILD_DIR/coverage.info" "${LCOV_TOLERANT[@]}" 2>/dev/null)
+
+extract_pct() {
+    echo "$SUMMARY" | grep -i "$1" | grep -oE '[0-9]+\.[0-9]+' | head -1
+}
+
+LINE_PCT=$(extract_pct "lines")
+BRANCH_PCT=$(extract_pct "branches")
+FUNC_PCT=$(extract_pct "functions")
+
+FAIL=0
+check_threshold() {
+    local label="$1" actual="$2" threshold="$3"
+    if [ -z "$actual" ]; then
+        echo "    WARN: could not parse $label coverage — skipping gate" >&2
+        return
+    fi
+    # Use awk for float comparison (bash cannot do floats)
+    if awk "BEGIN { exit ($actual >= $threshold) ? 0 : 1 }"; then
+        printf "    ✓ %-10s %s%% >= %s%%\n" "$label" "$actual" "$threshold"
+    else
+        printf "    ✗ %-10s %s%% < %s%%  (threshold: %s%%)\n" \
+            "$label" "$actual" "$threshold" "$threshold" >&2
+        FAIL=1
+    fi
+}
+
+echo "── Coverage gate ─────────────────────────────────────────────"
+check_threshold "lines"     "$LINE_PCT"   "$THRESHOLD_LINE"
+check_threshold "branches"  "$BRANCH_PCT" "$THRESHOLD_BRANCH"
+check_threshold "functions" "$FUNC_PCT"   "$THRESHOLD_FUNC"
+echo
+
+if [ "$FAIL" -eq 1 ]; then
+    echo "FAIL: coverage below threshold — see above." >&2
+    echo "      To suppress (ramp-up): SKIP_COVERAGE_GATE=1 bash $0" >&2
+    exit 4
+fi
+echo "PASS: all coverage thresholds met."