From b274591aa8f2a301ea9a7aeaea817acef41217c7 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Sun, 31 May 2026 10:46:05 +0200 Subject: [PATCH] docs(reviewer): aggregate all 12 audits into the index + record decisions Adds a comprehensive 'External audit documents' section to the reviewer index: - groups all 12 audits (correctness, API/perf/packaging, robustness) - surfaces G0 (porting rights) as the cross-cutting release blocker - records the decisions taken: coverage gate 80/70/90, API naming A1-A5 (A1-A3 implemented in PR #36, A4-A5 deferred pending G0/G1) - points a new session at the low-risk quick-win findings Co-Authored-By: Claude Opus 4.8 --- doc/reviewer/README.md | 65 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/doc/reviewer/README.md b/doc/reviewer/README.md index 829f082..2a339f6 100644 --- a/doc/reviewer/README.md +++ b/doc/reviewer/README.md @@ -18,6 +18,71 @@ 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`](external-audit-2026-05-30.md) | Correctness bugs | 3 findings (face_energy, Gauss–Bonnet, cotangent doc) — **all resolved** | +| [`java-port-audit.md`](java-port-audit.md) | Java→C++ math fidelity | line-by-line port anomalies — mostly resolved | +| [`java-ignore-crossvalidation.md`](java-ignore-crossvalidation.md) | `@Ignore` cross-validation | which Java tests were intentionally skipped and why | +| [`numerical-stability-audit-2026-05-31.md`](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`](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-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-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`](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`](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`](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`](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`](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 `__` 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