conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
1063f3541f606956eb621dd6121f620e7d84b68c
ConformalLabpp/doc/reviewer/README.md
Tarik Moussa 4f8530628b docs(reviewer): mark S2 (I1/H1/N7) done in the plan + audit banners 
Update finding-orchestration.md (master table I1/H1/N7 → ✅, S2 session marked
done with the original plan folded into a <details>), README headline cells +
next-batch pointer (now S3), and the test-coverage / numerical-stability audit
banners.  S2 was implemented directly by Opus in the warm post-refactor session
(commit 90e966a); 301/301 tests green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-31 19:44:50 +02:00

9.1 KiB
Raw Blame History

Reviewer meeting materials

A single landing page for the three documents associated with an external-reviewer meeting. The materials are written for a peer who actively publishes in discrete differential geometry — specifically the decorated-DCE / Penner-coordinates / hyperideal-polyhedra / canonical-tessellations research line — and who would potentially use conformallab++ as numerical infrastructure for their own future experiments.

Document Audience Purpose
briefing.md the reviewer one-page orientation: what the project is, where to look first, what we want from them
questions.md the reviewer the 5 concrete decisions we want their opinion on (skim before the meeting)
agenda.md me my own meeting playbook: timing, order, the "no" question, post-meeting memo template

After the meeting, a fourth file 2026-XX-XX-meeting-notes.md should land here too — the memo template at the bottom of agenda.md is the suggested structure.

External audit documents (2026-05-30 / 2026-05-31)

Twelve self-contained audit documents covering the project from every angle. Each is written so a fresh session can pick up any finding and act on it without prior context: every finding has an exact file:line, a code snippet, a concrete fix, and acceptance criteria.

⛔ Cross-cutting blocker — resolve before any public release or CGAL submission

G0 — Porting rights. The original Varylab/TU-Berlin project (gitlab.discretization.de:varylab/conformallab) carries no license (all rights reserved), and conformallab++ is a documented port (derivative work). The right to port + (re)license must be clarified with the original authors before any license decision, public release, or CGAL submission. Referenced from three audits: cgal-submission-readiness (G0/G1), dependency-license (D1/D2 — incl. the unlicensed test meshes), and indirectly math-derivation-citation (provenance of the Sechelmann-2016 primary source).

🔄 Status 2026-05-31: the original authors (Sechelmann / Springborn, TU Berlin / Varylab) have been contacted by email to clarify porting/relicensing rights. Awaiting reply. Until a written answer exists, all G0-gated work (G1–G12, D1/D2, A4/A5, public release, CGAL submission) stays paused.

🗺️ Working plan across sessions & models

See finding-orchestration.md — the meta-plan that maps every finding to a session, an implementing model (Haiku/Sonnet/Opus), and an Opus review gate. Session 1 (2026-05-31) is complete: 26 findings resolved across Sonnet/Haiku/Opus, 298/298 CGAL tests green (branch fix/b1-v3-c1-quick-wins). The orchestration doc lists the remaining sessions S2–S6.

Correctness & port fidelity

Document Focus Headline
external-audit-2026-05-30.md Correctness bugs 3 findings (face_energy, Gauss–Bonnet, cotangent doc) — all resolved
java-port-audit.md Java→C++ math fidelity line-by-line port anomalies — mostly resolved
java-ignore-crossvalidation.md @Ignore cross-validation which Java tests were intentionally skipped and why
numerical-stability-audit-2026-05-31.md FP robustness N3/N4/N5/N6 ✅ (clamp mode, named constants, Kahan area), N7 ✅ (conditioning diag, S2); N1 ✅* subsumed by B1; N2 open
math-derivation-citation-audit-2026-05-31.md Derivations & citations M1/M2/M4 ✅ (refs + year + citation format); M3 open, M5 needs expert

API, performance & packaging

Document Focus Headline
api-performance-audit-2026-05-31.md API naming + Newton perf A1–A3 ✅, B1 ✅ (both halves), B2–B5 ✅ (newton_core refactor); A4/A5 deferred (G0/G1)
cgal-submission-readiness-audit-2026-05-31.md CGAL submission ⛔ blocked by G0 (author contacted); G1 (MIT≠GPL), layout, concept, manual, test harness all pending
dependency-license-audit-2026-05-31.md Deps + data licensing ⛔ blocked by G0; D1 matrix predicated on the G0-undermined MIT premise; D2 test meshes have no provenance
usability-audit-2026-05-31.md Examples & docs U1–U11 — all resolved (PR #34)

Robustness & operational

Document Focus Headline
test-coverage-error-handling-audit-2026-05-31.md Coverage + error handling C1/C2/C3 ✅, I2/I3/I4 ✅, H2 ✅ (newton_core), I1/H1 ✅ (status enum, S2); I5/H3/H4/H5 open; gate in ramp-up until I5
input-validation-audit-2026-05-31.md Malformed input V1/V2/V3/V4 ✅ (NaN/Inf guard + JSON/XML error handling); V5/V6 open (polish)
thread-safety-audit-2026-05-31.md Concurrency no mutable static state (good); same-mesh concurrency contract still undocumented (open, S4)

Session 1 — implemented (2026-05-31)

Branch fix/b1-v3-c1-quick-wins, 9 commits, 298/298 CGAL tests green. See finding-orchestration.md for the full plan.

  • Sonnet: B1(HyperIdeal)/V3/C1; C2/C3 (coverage gate, ramp-up); V1/V2/V4; I2/I3/I4.
  • Haiku: N4/N6 (named constants); M1/M2/M4 (citations); A1–A3 (naming + [[deprecated]] aliases).
  • Opus: B1 inversive-distance block-FD port; N5 (Kahan area); N3 (selectable clamp mode HardJava|SmoothBarrier); H2 + B2/B3/B4/B5 (newton_core refactor).
  • 🔍 Opus review: all Sonnet/Haiku commits validated (value-identity, error handling, coverage-gate logic, alias forwarding) — all correct.

Session 2 (Opus, same day): I1 (NewtonStatus enum) + H1 (iteration count) + N7 (sparse_qr_fallback_used / min_ldlt_pivot diagnostics) — done directly in the warm post-refactor session, commit 90e966a, 301/301 tests green.

Decisions standing

  • Coverage gate: 80 % line / 70 % branch / 90 % function. Script now measures honestly (C2 ✅); gate is in ramp-up (SKIP_COVERAGE_GATE=1) until I5 wires it to the full CGAL suite.
  • API naming A1–A3 (internal): standardized on <verb>_<geom>_<rest> with [[deprecated]] aliases — implemented.
  • API naming A4–A5 (public CGAL surface): decided (discrete_inversive_distance_euclidean; both packers return Circle_packing_result) but deferred until the G0/G1 outcome — no point stabilizing a public API on a package whose release status is open.

How to act on a finding in a new session

Open the relevant audit, pick a finding, follow its "Fix" + "Acceptance criteria". Build/verify with the commands in that document's header. The Session-1 quick-win batch (B1, B3, C1, C2, V3, …) is done — for what to pick up next, follow the session plan in finding-orchestration.md: S1+S2 done; the next pending batch is S3 (H3/H4/H5 + V5/V6, Sonnet→Opus review).

When to send to the reviewer

  • briefing.md + questions.md: as part of the meeting-confirmation email, ~5 business days before the meeting. Subject line: "Pre-read for our conformallab++ chat (~15 min)".
  • agenda.md: never send. This is internal scaffolding.

Hub-Page durability

The reviewer hub HTML at https://tmoussa.codeberg.page/ConformalLabpp/ is published from doc/reviewer/hub.html in the repo (not from a detached preview branch). This means:

  • Merging any of the open PRs into main triggers .gitea/workflows/doxygen-pages.yml which republishes the hub alongside fresh Doxygen HTML — the reviewer URL stays live across merges with no manual intervention.
  • The hub is source-controlled, so changes are reviewable via PR like any other doc, and old versions live in git history.
  • The original Doxygen index moves to /doxygen.html whenever the hub override is active; both are reachable from the hub itself.

Quick links the reviewer should bookmark