ci+quality: structural gates (CI: 3 new; local: 7 new + .clang-tidy)

CI gates (active on every PR via .gitea/workflows/)
───────────────────────────────────────────────────
1. test-count consistency
   cpp-tests.yml gains a step after test-cgal that runs
   `scripts/check-test-counts.sh` against the just-built ./build dir
   (reuse via new BUILD_DIR env var, ~5 s overhead).  Drift between
   `doc/api/tests.md` and ctest reality now fails the PR.

2. End-to-end smoke
   `scripts/try_it.sh` (the documented user quick-start) is now part of
   the CGAL job, so README quick-start regressions fail the PR rather
   than silently breaking when users land.

3. Internal markdown link checker
   New `.gitea/workflows/markdown-links.yml` + `scripts/check-markdown
   -links.py`.  PRs that touch any *.md file run the check; main pushes
   trigger it too; a weekly cron catches external link rot.  Pure
   Python, no third-party action.  Validated against the current tree:
   122 internal links across 37 *.md files, 0 broken.

Local quality scripts (`scripts/quality/`, not in CI)
─────────────────────────────────────────────────────
* `license-headers.sh`   — `SPDX-License-Identifier: MIT` audit over
                            code/{include,src,tests}/.  Currently
                            reports 60/66 files missing it — that's
                            a follow-up; the script captures the
                            structural gap.
* `sanitizers.sh`        — ASan + UBSan over the fast test suite.
* `coverage.sh`          — gcov/lcov line + branch coverage of
                            code/include/, HTML report under
                            build-coverage/lcov-html/.
* `clang-tidy.sh`        — runs the curated `.clang-tidy` policy over
                            every public header.
* `multi-compiler.sh`    — sequential build + test against every
                            detected g++/clang++ (auto-discovery or
                            explicit list).
* `cgal-version-matrix.sh`— sequential build + CGAL test suite against
                            every CGAL tree under `~/cgal/<ver>/` (or
                            via `CGAL_ROOTS=...` env var).
* `reproducible-build.sh`— two `Release -j1` builds, fail if any test
                            executable byte-differs.
* `run-all.sh`           — driver: `--fast` for the ~5-min subset,
                            no arg for the ~25–40 min full sweep;
                            captures per-gate logs to
                            build-quality-logs/.

+ `.clang-tidy`          — curated, deliberately-small policy (only
                            checks that fire on OUR code, never on
                            transitive CGAL/Eigen/Boost headers).

+ `scripts/quality/README.md` — explains the structure, lists each
                            gate's wall-time + prereqs, and codifies
                            the promotion path: a gate moves into CI
                            only when it's green on the dev machine
                            AND has a recovery-instructions paragraph
                            in `doc/release-policy.md`.

Doc updates
───────────
`doc/architecture/locked-vs-flexible.md` (reviewer-facing) gains 4
"closed" rows in the limitations table — the 3 CI gates above and the
local quality-script suite.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

scripts/quality/clang-tidy.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# scripts/quality/clang-tidy.sh
+#
+# Run clang-tidy over every public header under code/include/.  We use
+# `--use-color` and tee output to build-tidy/clang-tidy.log for later
+# diffing.
+#
+# Local-only.  The check is exploratory until we agree on which warning
+# classes are reasonable to enforce — CGAL header-only code triggers a
+# lot of `modernize-*` / `readability-*` warnings that are upstream's
+# choice, not ours.  See `.clang-tidy` for the curated subset.
+#
+# Usage:
+#   bash scripts/quality/clang-tidy.sh                   # all headers
+#   bash scripts/quality/clang-tidy.sh code/include/CGAL # subset
+#
+# Prerequisite: a compile_commands.json with the right include paths
+# (cmake generates this automatically with CMAKE_EXPORT_COMPILE_COMMANDS=ON).
+#
+# Exit codes:
+#   0  clang-tidy ran (output captured)
+#   1  clang-tidy reported at least one error (post-policy filter)
+#   2  prerequisite missing
+
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT"
+
+BUILD_DIR="build-tidy"
+LOG="$BUILD_DIR/clang-tidy.log"
+
+command -v clang-tidy >/dev/null 2>&1 || {
+    echo "FAIL: clang-tidy not in PATH." >&2
+    echo "       macOS: brew install llvm  && export PATH=\"\$(brew --prefix llvm)/bin:\$PATH\"" >&2
+    echo "       Linux: sudo apt install clang-tidy" >&2
+    exit 2
+}
+
+TARGET_DIR="${1:-code/include}"
+[ -d "$TARGET_DIR" ] || { echo "FAIL: $TARGET_DIR is not a directory" >&2; exit 2; }
+
+# Generate compile_commands.json (clang-tidy needs it for include paths).
+cmake -S code -B "$BUILD_DIR" \
+    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
+    -DCMAKE_BUILD_TYPE=Release \
+    -Wno-dev >/dev/null
+
+mkdir -p "$BUILD_DIR"
+: > "$LOG"
+
+# Find every .h / .hpp under TARGET_DIR (skip deps + macOS dup files).
+HEADERS=$(find "$TARGET_DIR" \
+    \( -name "*.h" -o -name "*.hpp" \) \
+    -type f \
+    | grep -v "code/deps/" \
+    | grep -v " 2\." \
+    | sort)
+
+echo "========================================"
+echo "  clang-tidy run"
+echo "  target:  $TARGET_DIR"
+echo "  config:  .clang-tidy"
+echo "  log:     $LOG"
+echo "========================================"
+echo
+
+n=0
+for h in $HEADERS; do
+    n=$((n + 1))
+    echo "── [$n] $h ─────────────────────────────────"
+    # Use --quiet so we only see actual diagnostics, not "n warnings
+    # generated" boilerplate.  Pipe through tee for the log file.
+    clang-tidy --quiet \
+        -p "$BUILD_DIR" \
+        "$h" 2>&1 | tee -a "$LOG" || true
+done
+
+echo
+echo "── Summary ──────────────────────────────────"
+warn=$(grep -c "warning:" "$LOG" || true)
+err=$(grep -c "error:"   "$LOG" || true)
+echo "  files inspected: $n"
+echo "  warnings:        $warn"
+echo "  errors:          $err"
+echo "  full log:        $LOG"
+
+if [ "${err:-0}" -gt 0 ]; then
+    exit 1
+fi
+exit 0