74d41e99a8
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>
147 lines
8.8 KiB
Markdown
147 lines
8.8 KiB
Markdown
# 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`](briefing.md) | **the reviewer** | one-page orientation: what the project is, where to look first, what we want from them |
|
||
| [`questions.md`](questions.md) | **the reviewer** | the 5 concrete decisions we want their opinion on (skim before the meeting) |
|
||
| [`agenda.md`](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`](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`](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 | **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`](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-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-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`](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`](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/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`](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`](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`](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`](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
|
||
|
||
- 🌐 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`](../architecture/locked-vs-flexible.md)
|
||
- 📐 Schläfli derivation (for Q3): [`../math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md)
|
||
- 📚 Literature index (for Q1 + Q3): [`../math/references.md`](../math/references.md)
|
||
- 🗺️ Per-phase roadmap (for Q1): [`../roadmap/phases.md`](../roadmap/phases.md)
|
||
- 🧪 Research-track entries with acceptance criteria (Q1 + Q2): [`../roadmap/research-track.md`](../roadmap/research-track.md)
|