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`](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), **N7 ✅** (conditioning diag, S2); **N1 ✅\*** subsumed by B1; **N2 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/H1 ✅** (status enum, S2); **I5/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.

**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`](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

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