conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
74d41e99a8ce37504d0dfedeb866b95ff1f9319a
ConformalLabpp/doc/reviewer/README.md
Tarik Moussa 74d41e99a8 docs(reviewer): update audit status + add finding-orchestration plan 
Session 1 (2026-05-31) resolved 26 findings across Sonnet/Haiku/Opus; 298/298
CGAL tests green.  Bring the audit docs in line with reality:

- README.md: G0 banner now records that the original authors were contacted by
  email about porting/relicensing rights (awaiting reply); headline-status cells
  updated per finding; new "Session 1 — implemented" record; link to the plan.
- Per-audit resolution banners (api-performance, numerical-stability,
  input-validation, test-coverage, math-citation, thread-safety) + G0-blocked
  banners (cgal-submission, dependency-license).
- NEW finding-orchestration.md: the meta-plan mapping every finding to a session,
  an implementing model (Haiku/Sonnet/Opus by the "how much must be understood"
  rule), and an Opus review gate after each implementation session.  Records S1
  (done) and lays out S2–S6 so the next session can be picked up cold.

Docs only — no code change.

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

8.8 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); N1 ✅* subsumed by B1 block-FD; N2/N7 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/I5/H1/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.

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: the next pending batch is S2 (I1 + H1 + N7, 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