ConformalLabpp/doc/reviewer/session-prompts.md

Ready-to-paste session prompts (S3–S6 + review gate)

Copy one block into a fresh session, set the model named in the prompt, and go. Each prompt is self-contained: it names the findings, the audit doc to follow, the build/test commands, and the branch/push/PR + review-gate workflow.

Shared conventions (already baked into each prompt):

• Repo: /Users/tarikmoussa/Desktop/ConformalLabpp, base branch main.
• Branch + push to the eulernest fork = remote origin; open the PR via the Gitea API (https://git.eulernest.eu/api/v1/repos/conformallab/ConformalLabpp/pulls, basic-auth with the token embedded in the origin URL), base main.
• Build/test: cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON && cmake --build build-cgal --target conformallab_cgal_tests -j8 && ctest --test-dir build-cgal -R '^cgal\.'
• Plan + finding details: doc/reviewer/finding-orchestration.md and the per-finding audit docs in doc/reviewer/.
• After each implementation session, run the Review gate prompt (Opus).

---

S3 — Robustness & test-gap closure (model: Sonnet)

Use the Sonnet model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
branch off main called `fix/s3-robustness-gaps`.

Implement audit findings H3, H4, H5, V5, V6 — details (file:line, fix, acceptance
criteria) are in doc/reviewer/test-coverage-error-handling-audit-2026-05-31.md
(H3/H4/H5) and doc/reviewer/input-validation-audit-2026-05-31.md (V5/V6):
- H3: enforce_gauss_bonnet reports the magnitude of the applied correction.
- H4: test reduce_to_fundamental_domain at the boundary Im(τ)==0.0.
- H5: integration test for the degenerate-triangle path in the Newton solver.
- V5: make the hand-rolled XML reader REJECT reformatted-but-valid XML instead of
  silently mis-reading it into zeros (document the strict internal-only subset).
- V6: DOF-vector-vs-mesh size check on load, with a clear error.

Add a negative/boundary test for each. Build and run the full CGAL suite
(cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON && cmake --build build-cgal
--target conformallab_cgal_tests -j8 && ctest --test-dir build-cgal -R '^cgal\.') —
it must stay green with your new tests added. Do NOT change the default behaviour
of any existing valid round-trip.

Commit per finding (or in two logical commits) with trailer
`Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`. Push to origin and
open a PR (base main) via the Gitea API using the token in the origin remote URL.
Then update the status in doc/reviewer/finding-orchestration.md (H3/H4/H5/V5/V6 → ✅, S3)
and the audit banners. Report the PR URL and test count.

---

S4 — Documentation & citations (model: Haiku)

Use the Haiku model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
branch off main called `docs/s4-tolerances-threadsafety-citations`.

Three documentation findings — no code logic changes:
- N2 (numerical-stability audit): create doc/math/tolerances.md listing EVERY
  numerical threshold (Newton tol, FD hess_eps, Armijo c1, sparsity drop,
  Gauss-Bonnet tol, spherical asin guard, the named constants in constants.hpp),
  each with its role and the constraints between them — include the N1 coupling
  "FD floor must be ≪ Newton tol". Cross-link from constants.hpp.
- thread-safety audit: document the same-mesh concurrency contract (the code has
  NO mutable static state; this is purely the written contract — state what is and
  isn't safe to call concurrently on the same vs different meshes).
- M3 (math-citation audit): re-verify the future-dated / arXiv-only citations in
  doc/math/references.md against their published versions; correct any that have
  since appeared in a journal/proceedings.

Build still succeeds; run the full CGAL suite to confirm no accidental code change
(should stay green). Commit with trailer
`Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>`. Push to origin, open a
PR (base main) via the Gitea API. Update doc/reviewer/finding-orchestration.md
(N2/thread-safety/M3 → ✅, S4) and the audit banners. Report the PR URL.

---

S5 — Coverage truthfulness (model: Sonnet)

Use the Sonnet model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
branch off main called `ci/s5-coverage-full-suite`.

Implement audit finding I5 (test-coverage-error-handling audit): the coverage
script currently measures only the 26 fast tests (~9.6%), not the CGAL suite.
- Wire scripts/quality/coverage.sh to build + run the full CGAL test suite
  (WITH_CGAL_TESTS=ON) under coverage instrumentation, so code/include/ is measured
  honestly.
- Once the measured numbers are real, remove the SKIP_COVERAGE_GATE=1 ramp-up flag
  from .gitea/workflows/cpp-tests.yml so the agreed 80% line / 70% branch / 90%
  function gate goes live. If real coverage is below threshold, either raise it
  with targeted tests or document the gap and keep ramp-up — but state which.
- Verify locally: bash scripts/quality/coverage.sh should report the full-suite
  numbers and pass/fail the gate correctly.

Commit with trailer `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
Push to origin, open a PR (base main) via the Gitea API. Update
doc/reviewer/finding-orchestration.md (I5 → ✅, S5; flip the gate note in the
test-coverage banner). Report the PR URL and the measured coverage numbers.

---

S6 — Public CGAL surface + packaging (model: Opus) — ⛔ BLOCKED until G0

PRECONDITION: do NOT start this session until the original Varylab/TU-Berlin
authors have replied in writing granting porting/relicensing rights (finding G0).
If there is no written reply yet, stop and report that S6 is still blocked.

Use the Opus model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp.
Once G0 is cleared, implement, in dependency order, from the CGAL submission audit
(doc/reviewer/cgal-submission-readiness-audit-2026-05-31.md) and api-performance
audit (A4/A5):
- A4/A5: public entry-point renames (discrete_inversive_distance_euclidean; both
  packers return Circle_packing_result), with [[deprecated]] aliases + CHANGELOG.
- G1 (license headers per the chosen license), G2/G3/G8 (CGAL package layout,
  drop vendored CGAL on the submission branch), G9 (public/internal header split),
  G4/G5 (concept doc + user manual + PackageDescription), G6 (CGAL test harness),
  G7 (deliver or narrow genericity), G10/G12 (benchmark + headers).

This is a large, mostly-mechanical effort — split into several PRs. Keep the
standalone MIT build working in parallel. Report progress against the G-series list.

---

Review gate (run after S3 / S4 / S5) (model: Opus)

Use the Opus model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp. Review the
open PR <PR_URL / branch name> as an independent reviewer. Check, and report a
pass/fail per item:
- Builds clean; full CGAL suite green with no test-count regression
  (ctest --test-dir build-cgal -R '^cgal\.').
- No Java golden-vector / parity test perturbed; HardJava clamp default intact.
- Numeric changes are value-identical where claimed, or justified + covered by a test.
- Any new public surface (result types, enums, API, file formats) is intentional
  and documented; existing valid round-trips still work.
- Commit messages attribute the implementing model.
- The finding is marked ✅ in doc/reviewer/finding-orchestration.md with the commit ref.
Read the actual diff (git diff main...HEAD) and the touched audit doc. If you find
a real problem, fix it directly (small) or list precise required changes (larger),
then re-run the suite. Conclude with an explicit APPROVE / CHANGES-REQUESTED.