ci(test-cgal): switch to manual comment trigger (/test-cgal on PR)

Instead of triggering on every pull_request push, test-cgal now fires
only when a PR comment contains "/test-cgal".  This prevents the Pi
runner (3-4 GB RAM, swap constantly loaded) from queuing CGAL builds
faster than it can drain them on every WIP commit.

Workflow changes:
- Add `issue_comment: types: [created]` to the top-level `on:` block
- test-cgal `if:` condition:
    event is issue_comment
    AND comment is on a PR (issue.pull_request != null)
    AND comment body contains "/test-cgal"
- Checkout uses `refs/pull/N/head` so the PR branch is checked out
  correctly (issue_comment sets GITHUB_REF to the default branch, not
  the PR branch)

Usage: write "/test-cgal" as a PR comment to trigger the 277-test
CGAL suite.  The build uses CONFORMALLAB_LOW_MEMORY_BUILD=ON (-O0,
no PCH, unity batch 1) and runs in a 2000 MB container.

CLAUDE.md: CI table + status paragraph updated accordingly.

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

.gitea/workflows/cpp-tests.yml

@@ -8,6 +8,9 @@ on:
       - "claude/**"
       - "feature/**"
   pull_request:
+  # /test-cgal comment on any PR triggers the CGAL test suite manually.
+  issue_comment:
+    types: [created]
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Job 1 — test-fast
@@ -57,45 +60,50 @@ jobs:
 #
 #   Boost (libboost-dev) is already present in the container since the image rebuild.
 # ─────────────────────────────────────────────────────────────────────────────
-  # ─── RE-ENABLED 2026-05-31 with CONFORMALLAB_LOW_MEMORY_BUILD ────────────
-  # Root cause of previous OOMs: CGAL+Eigen at -O3 drives cc1plus peak to
-  # ~700 MB per Unity compilation unit on ARM64.  With a 1600 MB container
-  # limit and 4 files per unity batch, the 2nd or 3rd TU reliably OOMs.
+  # ─── CGAL tests: manual trigger via PR comment ───────────────────────────
   #
-  # Fix: CONFORMALLAB_LOW_MEMORY_BUILD=ON applies three measures:
-  #   1. -O0 (no debug info): drops cc1plus backend RAM from ~700 MB to
-  #      ~150-200 MB per TU (optimizer passes are entirely skipped).
-  #   2. CONFORMALLAB_USE_PCH=OFF: saves the ~200 MB PCH compilation cost.
-  #   3. UNITY_BUILD_BATCH_SIZE=1: one source file per cc1plus invocation,
-  #      removing the "4-file template-explosion" multiplier.
-  #   4. --no-keep-memory linker flag: reduces GNU ld RSS by ~15-25 %.
+  # Trigger: write "/test-cgal" as a comment on any pull request.
   #
-  # Memory budget (ARM64, GCC, estimated peak per cc1plus after fix):
-  #   ~150-200 MB/TU × 1 TU at a time (-j1) → fits in 2000 MB container.
-  # Container memory raised 1600 → 2000 MB to give a comfortable margin;
-  # swap re-enabled (memory-swap=3000m) so OOM-kills fail fast only if
-  # the container truly runs out of physical+swap, not just RAM.
+  # Why comment-triggered (not automatic on every PR push):
+  #   The Pi runner has 3-4 GB RAM total with swap constantly loaded.
+  #   Even with LOW_MEMORY_BUILD the CGAL build takes ~5 min and stresses
+  #   the runner.  Triggering on every push would queue builds faster than
+  #   the Pi can drain them.  A manual trigger gives full control: run the
+  #   277-test suite when a PR is ready for review, not on every WIP commit.
   #
-  # Trade-off: tests run 2-4× slower (CGAL traversals unoptimized at -O0);
-  # wall-clock build time increases (no PCH, no unity batching) but the
-  # correctness guarantee is identical — all 277 CGAL tests pass.
+  # How it works:
+  #   - `issue_comment` fires on all PR + issue comments.
+  #   - The `if:` condition checks:
+  #       1. Event is a comment (not a push or PR sync)
+  #       2. The comment is on a PR (issue.pull_request != null)
+  #       3. The comment body contains "/test-cgal"
+  #   - The checkout uses refs/pull/N/head to get the PR branch, because
+  #     `issue_comment` does not set GITHUB_REF to the PR branch by default.
   #
-  # Trigger: pull requests only (same as before).
+  # LOW_MEMORY_BUILD applies four RAM-saving measures so the build fits in
+  # 2000 MB: -O0, PCH off, unity batch 1, --no-keep-memory linker.
+  # See code/tests/cgal/CMakeLists.txt for the full explanation.
   test-cgal:
     needs: test-fast
-    if: github.event_name == 'pull_request'
+    if: |
+      github.event_name == 'issue_comment' &&
+      github.event.issue.pull_request != null &&
+      contains(github.event.comment.body, '/test-cgal')
     runs-on: eulernest
     container:
       image: git.eulernest.eu/conformallab/ci-cpp:latest
-      # 2000 MB hard limit for the container; swap headroom up to 3000 MB
-      # (memory-swap = total of RAM + swap, so 3000-2000 = 1000 MB swap).
-      # This uses ~half of the Pi's 3-4 GB while leaving room for the OS
-      # and the runner daemon.  With LOW_MEMORY_BUILD the peak per TU is
-      # ~150-200 MB, well within the 2000 MB ceiling.
+      # 2000 MB hard limit; 1000 MB swap headroom (memory-swap = RAM + swap).
+      # Uses ~half of the Pi's 3-4 GB, leaving margin for OS + runner daemon.
+      # With LOW_MEMORY_BUILD peak per TU is ~150-200 MB → well within limit.
       options: "--memory=2000m --memory-swap=3000m"
 
     steps:
+      # Check out the PR branch, not the default branch.
+      # issue_comment events set GITHUB_REF to the default branch; we need
+      # refs/pull/N/head to get the actual PR code.
       - uses: actions/checkout@v4
+        with:
+          ref: refs/pull/${{ github.event.issue.number }}/head
 
       - name: Configure (LOW_MEMORY_BUILD — -O0, no PCH, unity batch 1)
         run: |

CLAUDE.md

@@ -265,14 +265,14 @@ Three jobs in `.gitea/workflows/cpp-tests.yml`:
 | Job | CMake flags | Deps | Triggers on | Status |
 |---|---|---|---|---|
 | `test-fast` | *(none)* | Eigen + GTest only | all branches | **active** |
-| `test-cgal` | `-DWITH_CGAL_TESTS=ON -DCONFORMALLAB_LOW_MEMORY_BUILD=ON` | + Boost | pull requests only | **active** (re-enabled 2026-05-31) |
+| `test-cgal` | `-DWITH_CGAL_TESTS=ON -DCONFORMALLAB_LOW_MEMORY_BUILD=ON` | + Boost | `/test-cgal` PR comment | **active** (comment-triggered, 2026-05-31) |
 | `quality-gates` | *(none)* | + codespell, shellcheck | all branches (`needs: test-fast`) | **active** |
 
 Runner: `eulernest` — self-hosted Raspberry Pi, ARM64, Ubuntu 22.04. Docker image: `git.eulernest.eu/conformallab/ci-cpp:latest`. `test-cgal` and `quality-gates` both need `test-fast` to pass first (`needs: test-fast`).
 
 `quality-gates` runs four required structural gates: `license-headers.sh`, `cgal-conventions.py`, `codespell.sh`, `shellcheck.sh --strict`.  Seven more gates (clang-format, cmake-format, cppcheck, sanitizers, clang-tidy, multi-compiler, reproducible-build) are local-only — see `scripts/quality/README.md`.
 
-**`test-cgal` re-enabled 2026-05-31** with `CONFORMALLAB_LOW_MEMORY_BUILD=ON`: uses `-O0` (no debug info), PCH off, unity batch size 1 and `--no-keep-memory` linker flag. This drops cc1plus peak RAM from ~700 MB to ~150-200 MB per TU, fitting within a 2000 MB container on the 3-4 GB Raspberry Pi runner. Container memory raised from 1600 → 2000 MB (with 1000 MB swap headroom). Tests run ~15× slower at -O0 but all 277 pass. The two structural sub-gates (`scripts/check-test-counts.sh`, `scripts/try_it.sh`) remain inside the CGAL job and run after the test step.
+**`test-cgal` is comment-triggered** (2026-05-31): write `/test-cgal` as a comment on any PR to start the CGAL suite manually. Not triggered on every push — the Pi runner (3-4 GB RAM, swap heavily loaded) cannot sustain a build on every WIP commit. `LOW_MEMORY_BUILD=ON` (-O0, no PCH, unity batch 1) keeps peak cc1plus RAM at ~150-200 MB, fitting in a 2000 MB container. All 277 tests pass in ~31 s run time. The two structural sub-gates (`scripts/check-test-counts.sh`, `scripts/try_it.sh`) still run after the test step.
 
 Two other workflows are also restricted to `workflow_dispatch:` only (auto-trigger disabled 2026-05-26 while the codeberg pages-branch push is being stabilised):
 - `.gitea/workflows/doxygen-pages.yml` — publishes Doxygen HTML + reviewer hub to the codeberg `pages` branch.