From 5f3c6aa0d5c809d3950bcb7d9050c67fe4c37bcd Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Sun, 31 May 2026 18:57:02 +0200 Subject: [PATCH] =?UTF-8?q?docs(reviewer):=20add=20ready-to-paste=20sessio?= =?UTF-8?q?n=20prompts=20(S3=E2=80=93S6=20+=20review=20gate)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit session-prompts.md: one self-contained, copy-paste prompt per pending session, each naming the model (Sonnet/Haiku/Opus), the findings + audit doc, the build/test commands, and the branch/push/PR + review-gate workflow. S6 carries the G0 precondition. Linked from finding-orchestration.md. Co-Authored-By: Claude Opus 4.8 --- doc/reviewer/finding-orchestration.md | 4 + doc/reviewer/session-prompts.md | 146 ++++++++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 doc/reviewer/session-prompts.md diff --git a/doc/reviewer/finding-orchestration.md b/doc/reviewer/finding-orchestration.md index c3e00f4..be1de3f 100644 --- a/doc/reviewer/finding-orchestration.md +++ b/doc/reviewer/finding-orchestration.md @@ -13,6 +13,10 @@ know exactly what it covers and how its output gets validated. --- +> **Ready-to-paste prompts** for every pending session (S3–S6 + the review gate) +> live in [`session-prompts.md`](session-prompts.md) — copy one block, set the +> named model, go. + ## How to use this 1. Pick the next **⬜ pending** session from the [sequence](#session-sequence). diff --git a/doc/reviewer/session-prompts.md b/doc/reviewer/session-prompts.md new file mode 100644 index 0000000..e8cedf9 --- /dev/null +++ b/doc/reviewer/session-prompts.md @@ -0,0 +1,146 @@ +# 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 `. 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 `. 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 `. +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 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. +```