ConformalLabpp/doc/reviewer/README.md

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).

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	N1: FD-Hessian step (1e-5) fights Newton tol (1e-8); clamps, cancellation, magic constants
math-derivation-citation-audit-2026-05-31.md	Derivations & citations	M1 Kolpakov–Mednykh missing from refs; M2 BPS cited "2010" vs "2015"

API, performance & packaging

Document	Focus	Headline
api-performance-audit-2026-05-31.md	API naming + Newton perf	A1–A5 naming (decided, see below); B1: block-FD Hessian exists but solver uses slow full-FD
cgal-submission-readiness-audit-2026-05-31.md	CGAL submission	G0 (rights), G1 (MIT≠GPL), layout, concept, user manual, test harness
dependency-license-audit-2026-05-31.md	Deps + data licensing	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 solver ok flag dropped; coverage gate decided: 80 % line / 70 % branch / 90 % func
input-validation-audit-2026-05-31.md	Malformed input	V3: NaN/Inf vertex coords flow silently into the solver
thread-safety-audit-2026-05-31.md	Concurrency	no mutable static state (good); same-mesh concurrency contract undocumented

Decisions taken (2026-05-31)

• Coverage gate: 80 % line / 70 % branch / 90 % function (after fixing the coverage script so it measures honestly — test-coverage C2/I5).
• API naming A1–A3 (internal): standardized on <verb>_<geom>_<rest> with [[deprecated]] aliases — implemented, open as PR #36 (refactor/api-naming-a1-a3), 277/277 tests green.
• 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. Suggested first batch (low-risk, high-value quick wins): B1 (HyperIdeal block-FD one-liner), B3, C1, C2, V3.

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

• 🌐 Reviewer-hub landing page: https://tmoussa.codeberg.page/ConformalLabpp/ (the hub shows status badges, a "what's new" banner with the most recent delta, the research-alignment table, and direct links into every document below)
• 📦 Source: https://codeberg.org/TMoussa/ConformalLabpp
• 📝 Architecture decisions (incl. the Q7 "no" prompt): ../architecture/locked-vs-flexible.md
• 📐 Schläfli derivation (for Q3): ../math/hyperideal-hessian-derivation.md
• 📚 Literature index (for Q1 + Q3): ../math/references.md
• 🗺️ Per-phase roadmap (for Q1): ../roadmap/phases.md
• 🧪 Research-track entries with acceptance criteria (Q1 + Q2): ../roadmap/research-track.md