docs(reviewer): add math-derivation & citation audit

Checks code/docs against the published mathematics (vs java-port-audit which
checks code vs Java):
- M1: Kolpakov-Mednykh volume formula used in code but missing from references.md
- M2: BPS circle-packing paper cited as '2010' in code vs '2015' in references.md
- M3: post-2023/preprint citations back unimplemented phases — re-verify + clarify
  scope before submission
- M4: no canonical citation-key convention
- M5: large derivations numerically validated but prose unreviewed — expert sign-off

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

doc/reviewer/math-derivation-citation-audit-2026-05-31.md

@@ -0,0 +1,192 @@
+# Math-Derivation & Citation Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Correctness of the mathematical derivations in `doc/math/` and the
+integrity/consistency of the literature citations in code comments and docs.
+**Focus:** Are the derivations sound and are the citations accurate, complete, and
+consistent? Distinct from `java-port-audit.md` (which checks code vs. Java) — this
+checks code/docs vs. *the published mathematics*.
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Polish
+
+> **Good news up front:** `doc/math/references.md` is unusually scholarly and already
+> contains several *self-corrections* (the Glickenstein "eq. (4.6)" numbering fix →
+> §5.2 parametrization; the Schläfli boundary-term re-attribution to Rivin–Schlenker
+> 1999; the Bowers–Stephenson formula-vs-theory clarification). That is exemplary and
+> rare. The findings below are the gaps that remain *despite* this strong baseline.
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Location |
+|----|-----|-------|----------|
+| M1 | 🟡 | Kolpakov–Mednykh volume formula is used in code but **absent from `references.md`** | `hyper_ideal_utility.hpp:80`, `hyper_ideal_functional.hpp:321` |
+| M2 | 🟡 | BPS circle-packing paper cited as **"2010"** in code but **"2015"** in `references.md` — inconsistent year for a load-bearing reference of an *implemented* phase | `cp_euclidean_functional.hpp`, `newton_solver.hpp`, `Discrete_circle_packing.h` vs `references.md` |
+| M3 | 🟡 | Future-dated / arXiv-only citations (2025, 2026) back *unimplemented* phases but sit alongside implemented ones — re-verify against published versions before submission | `references.md` |
+| M4 | 🔵 | No canonical citation-key convention — the same work appears as `Luo 2004` / `Luo-2004` / `Luo (2004)` / `Luo's 2004` etc. | code + docs |
+| M5 | 🔵 | The large hand-derivations (notably `hyperideal-hessian-derivation.md`, 34 KB) have their *results* numerically validated but the *prose derivations* are unreviewed by a domain expert | `doc/math/*-derivation.md` |
+
+---
+
+## M1 — 🟡 Kolpakov–Mednykh volume formula not in references.md
+
+### Evidence
+```cpp
+// hyper_ideal_utility.hpp:80
+/// the Kolpakov-Mednykh formula (arxiv math/0603097).  Same as Java …
+// hyper_ideal_functional.hpp:321
+///   * Exactly one vertex ideal (…) → Kolpakov-Mednykh volume
+```
+`grep -c Kolpakov doc/math/references.md` → **0**.
+
+### Problem
+The hyper-ideal **volume** computation — a core ingredient of the Springborn-2020
+functional and the energy itself — rests on the Kolpakov–Mednykh formula (and a
+Meyerhoff/Ushijima component, cited 6× elsewhere). The code cites it inline by arXiv
+ID, but `references.md`, the stated "citation source of truth", omits it entirely. A
+reviewer auditing the math foundation against the references file would find a
+load-bearing formula with no entry.
+
+### Fix
+Add a `references.md` row: Kolpakov, Mednykh — *(full title)*, arXiv `math/0603097`,
+mapped to `hyper_ideal_utility.hpp`. Likewise confirm the Meyerhoff / Ushijima 2006
+volume reference (cited in code) has a row.
+
+### Acceptance criteria
+- Every formula cited inline in `code/include/` has a matching `references.md` entry.
+
+---
+
+## M2 — 🟡 BPS paper: "2010" in code vs "2015" in references.md
+
+### Evidence
+- Code/docs cite it as **2010** (e.g. `cp_euclidean_functional.hpp`,
+  `newton_solver.hpp`, `CGAL/Discrete_circle_packing.h`, plus 26 doc hits of
+  "Bobenko-Pinkall-Springborn 2010").
+- `references.md` lists it as **2015**: *"Discrete conformal maps and ideal hyperbolic
+  polyhedra, Geometry & Topology 19(4) (2015), arXiv 1005.2698."*
+
+### Problem
+Both are "correct" in a sense — the arXiv preprint (`1005.2698`) is **2010**, the
+published Geometry & Topology version is **2015** — but the project uses the two years
+interchangeably for the *same* paper, including in the public CGAL header
+(`Discrete_circle_packing.h`) and the `phase-9a-validation.md` mapping. This is the
+reference for an **implemented, shipped** phase (9a.1 CP-Euclidean), so the
+inconsistency is user-visible and would be flagged in CGAL review.
+
+### Fix
+Pick one canonical citation (recommend the **published 2015** Geometry & Topology
+version, with the arXiv 2010 ID noted) and use it everywhere. Update the code comments
+and docs that say "2010" to match `references.md`, or vice-versa — but make them agree.
+
+### Acceptance criteria
+- The BPS circle-packing paper is cited with a single, consistent year across code and
+  docs (matching `references.md`).
+
+---
+
+## M3 — 🟡 Future-dated / preprint citations must be re-verified before submission
+
+### Evidence
+`references.md` cites, among others:
+- Bobenko, Lutz **2025** (arXiv 2310.17529) — Phase 9d.2 (🔜 planned)
+- Bowers, Bowers, Lutz **2026** (arXiv 2601.22903) — Phase 9b-analytic / 10c′
+- Lutz **2024** PhD thesis; Bobenko-Lutz 2024 IMRN
+
+### Problem
+Two issues:
+1. **Verification:** arXiv-only and future-dated (2025/2026) references can change
+   (version bumps, final published venue, even withdrawal). Before any public release
+   or CGAL submission, each should be re-checked against its final published form. The
+   arXiv ID `2601.22903` in particular (Jan 2026) is very recent relative to this
+   audit and warrants a manual confirmation that it resolves.
+2. **Scope confusion:** these back **unimplemented "future research"** phases (🔜),
+   but the Bowers-Bowers-Lutz 2026 row claims it "supports correctness of the analytic
+   Hessian" — which *is* implemented (Phase 9b-analytic, ✅). A reader could conclude
+   the shipped analytic Hessian *depends* on a 2026 preprint. Clarify that the
+   implemented derivation stands on its own (it is numerically validated, see M5) and
+   the 2026 paper is corroborating, not foundational.
+
+### Fix
+- Re-verify every 2024–2026 / arXiv-only citation against its published version; add
+  DOIs once available.
+- Sharpen the wording so implemented-phase correctness is never described as resting
+  on an unpublished/future reference.
+
+### Acceptance criteria
+- All post-2023 citations are confirmed to resolve; no implemented-phase correctness
+  claim depends solely on a preprint/future reference.
+
+---
+
+## M4 — 🔵 No canonical citation-key convention
+
+### Evidence
+The same works appear in many surface forms across code and docs:
+`Luo 2004` / `Luo-2004` / `Luo (2004)` / `Luo's 2004`; `Springborn 2020` /
+`Springborn (2020)` / `Springborn-2020`; `Bowers-Stephenson` vs `Bowers, Stephenson`.
+
+### Problem
+Cosmetic but it defeats grep-ability and cross-referencing (cf. the false-negative in
+this audit's own tooling: `Bowers-Bowers-Lutz 2026` did not match the comma-form
+`Bowers, Bowers, Lutz`). For a library aiming at CGAL, a consistent citation key
+(e.g. `[SpringbornDCG2020]`) referenced from both code and `references.md` is the
+clean solution.
+
+### Fix
+Define short citation keys in `references.md` and use them verbatim in code comments
+and docs.
+
+### Acceptance criteria
+- One canonical key per reference; code/docs cite the key, not free-form variants.
+
+---
+
+## M5 — 🔵 Large derivations: results validated, prose unreviewed
+
+### Evidence
+`doc/math/hyperideal-hessian-derivation.md` (34 KB) derives the analytic HyperIdeal
+Hessian; `validation.md` and the FD-vs-analytic tests (`test_hyper_ideal_hessian.cpp`,
+block-FD vs full-FD) check the *result* numerically.
+
+### Problem
+The derivation **result** is well-protected — the analytic Hessian is tested against
+finite differences, so an algebra error would surface as a test failure. But the
+**prose derivation itself** (the step-by-step algebra a reader would follow to trust
+or extend it) has not been reviewed by a domain expert, and a derivation that "happens
+to match FD at the tested points" can still contain a sign/indexing slip that the
+specific test meshes don't excite.
+
+### Fix
+- Have a discrete-differential-geometry expert read `hyperideal-hessian-derivation.md`
+  and `discrete-conformal-theory.md` for derivational soundness (this is naturally
+  part of the planned reviewer meeting — see `briefing.md`).
+- Strengthen confidence cheaply by adding a randomized/property-based FD check (random
+  valid DOF vectors on several genera) so the numerical safety net covers more than the
+  fixed smoke meshes.
+
+### Acceptance criteria
+- The key derivations are signed off by a domain reviewer, and/or the FD validation is
+  randomized rather than fixed-mesh-only.
+
+---
+
+## What is already good
+
+- `references.md` is **scholarly and self-correcting** — it explicitly fixes its own
+  earlier over-citations (Glickenstein equation numbering, Schläfli→Rivin–Schlenker,
+  Bowers–Stephenson). This is well above typical project hygiene.
+- Implemented vs. planned references are marked ✅ / 🔜 — the reader can tell which
+  citations underpin shipped code (M3 only asks to keep that discipline airtight).
+- The primary source (Sechelmann 2016 PhD thesis, CC BY-SA 4.0) is correctly
+  identified, and the Java provenance is linked — directly relevant to CGAL audit G0.
+- Derivation results are numerically validated (FD vs analytic) — the right safety net
+  (M5 just asks to widen it and get a human sign-off).
+
+## Suggested order
+1. **M2** (BPS year) + **M1** (Kolpakov–Mednykh) — quick citation fixes, user-visible.
+2. **M3** (re-verify post-2023 refs; fix scope wording) — before any submission.
+3. **M5** (expert sign-off + randomized FD) — fold into the reviewer meeting.
+4. **M4** (citation keys) — polish.