docs(roadmap): add phase orchestration system mirroring the reviewer audit workflow
Brings doc/roadmap/ to the same operational level as doc/reviewer/ by adding the two missing structural files and updating existing docs to close the gap identified in the system review. New files: - doc/roadmap/phase-orchestration.md — master phase table (model assignments, session IDs, status, review-gate checklist); mirrors finding-orchestration.md - doc/roadmap/session-prompts.md — copy-paste-ready prompts for P1–P4 (Haiku/Sonnet/Opus) + universal Opus review gate; mirrors reviewer/session-prompts.md Updated files: - CLAUDE.md: roadmap section now lists porting-status.md, phase-orchestration.md, session-prompts.md; reviewer section adds finding-orchestration.md and session-prompts.md; agentic-workflow section has direct "S3 is next / P1 is next" entry points so agents don't need to derive the next action from scratch - doc/roadmap/phases.md: Current-focus table at the top (7 tracks, next session per track, gating); cross-links to geometry-central-comparison.md, software-landscape.md, complexity.md added in GC and 9b-analytic sections - doc/roadmap/porting-status.md: snapshot date updated to 2026-05-31 (post S1+S2); test count replaced by reference to doc/api/tests.md; §4 gains four new solver rows (newton_core refactor, NewtonStatus enum, diagnostics, selectable clamp mode); §7 gains four new research-extension rows from S1/S2 - doc/roadmap/research-track.md: header companion-docs section links to novelty-statement.md, software-landscape.md, and phase-orchestration.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
208
doc/roadmap/session-prompts.md
Normal file
208
doc/roadmap/session-prompts.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# Ready-to-paste session prompts (P1–P4 + review gate)
|
||||
|
||||
Copy one block into a fresh session, set the **model named in the prompt**, and go.
|
||||
Each prompt is self-contained: it names the phase(s), the detail doc to follow,
|
||||
the build/test commands, and the branch/push/PR + review-gate workflow.
|
||||
|
||||
Shared conventions (baked into each prompt):
|
||||
- Repo root: `/Users/tarikmoussa/Desktop/ConformalLabpp`, base branch `main`.
|
||||
- Branch + push to the **eulernest fork** = remote `origin`; open the PR via the
|
||||
Gitea API (`https://git.eulernest.eu/api/v1/repos/conformallab/ConformalLabpp/pulls`,
|
||||
basic-auth with the token embedded in the `origin` URL), base `main`.
|
||||
- Build/test command (CGAL suite):
|
||||
`cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON && cmake --build build-cgal --target conformallab_cgal_tests -j8 && ctest --test-dir build-cgal -R '^cgal\.'`
|
||||
- Phase details: `doc/roadmap/phases.md` (per-phase plan);
|
||||
`doc/roadmap/research-track.md` (research items with acceptance criteria).
|
||||
- Build flags reference: `CLAUDE.md` §Build commands (canonical source; use
|
||||
`-DCONFORMALLAB_LOW_MEMORY_BUILD=ON -j1` if on the Raspberry Pi runner).
|
||||
- After each implementation session, run the **Review gate** prompt (Opus).
|
||||
|
||||
---
|
||||
|
||||
## P1 — Quick wins (model: **Haiku**)
|
||||
|
||||
```
|
||||
Use the Haiku model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
|
||||
branch off main called `feat/p1-quick-wins`.
|
||||
|
||||
Implement four independent additions — full details (Java references, math
|
||||
references, acceptance criteria) in doc/roadmap/phases.md at the sections
|
||||
labelled 9h.1, 9h.2, 9g.1, 9d.3:
|
||||
|
||||
- 9h.1 Add --tol and --max-iter CLI options in code/src/conformallab_cli.cpp.
|
||||
Thread both through run_euclidean / run_spherical / run_hyper_ideal.
|
||||
Update doc/getting-started.md CLI parameter table.
|
||||
|
||||
- 9h.2 Add -g cp_euclidean and -g inversive_distance routes in the CLI,
|
||||
following the existing run_euclidean() pattern (~60 lines each).
|
||||
Add both geometry strings to the CLI::IsMember validator.
|
||||
Update README + doc/getting-started.md.
|
||||
|
||||
- 9g.1 Create code/include/conformal_quality.hpp implementing:
|
||||
IsothermicityMeasure, DiscreteConformalEquivalenceMeasure,
|
||||
FlippedTriangles, LengthCrossRatio, ConvergenceUtility measures.
|
||||
Java source classes are listed in phases.md §9g.1.
|
||||
Each function must have at least one sanity test in code/tests/cgal/
|
||||
(e.g. FlippedTriangles returns 0 on a valid layout; LengthCrossRatio
|
||||
is 1.0 on an equilateral triangle). Register in code/tests/cgal/CMakeLists.txt.
|
||||
|
||||
- 9d.3 Create code/include/stereographic_layout.hpp porting
|
||||
StereographicUnwrapper.java (266 LoC). See phases.md §9d.3 for the math
|
||||
(stereographic projection S²→ℂ∪{∞} + Möbius centring for genus-0 surfaces).
|
||||
Add at least one round-trip test (north pole → ∞; a unit-sphere point →
|
||||
expected complex value).
|
||||
|
||||
Run the full CGAL suite after all four are implemented:
|
||||
cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON && cmake --build build-cgal \
|
||||
--target conformallab_cgal_tests -j8 && ctest --test-dir build-cgal -R '^cgal\.'
|
||||
It must stay green with your new tests added.
|
||||
|
||||
Commit per phase (or in two logical commits) with trailer
|
||||
`Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>`.
|
||||
Push to origin and open a PR (base main) via the Gitea API using the token
|
||||
in the origin remote URL. Update doc/roadmap/phase-orchestration.md (mark each
|
||||
completed phase ✅ with the commit ref). Report the PR URL and test count.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## P2 — Decorated DCE transition (model: **Sonnet**)
|
||||
|
||||
```
|
||||
Use the Sonnet model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
|
||||
branch off main called `feat/p2-decorated-dce`.
|
||||
|
||||
Implement Phase 12 — Decorated DCE & geometric transition.
|
||||
Full details and acceptance criteria in:
|
||||
doc/roadmap/phases.md §Phase 12
|
||||
doc/roadmap/research-track.md §Phase 12
|
||||
|
||||
Mathematical reference: Bobenko, Lutz 2025 "Decorated Discrete Conformal
|
||||
Equivalence in Non-Euclidean Geometries" (Discrete & Comput. Geom.;
|
||||
arXiv:2310.17529) §3 — Penner-coordinate decoration unifying the three
|
||||
background geometries.
|
||||
|
||||
Scope (from phases.md):
|
||||
1. Decoration layer — per-vertex circle/horocycle radius as Penner coordinate;
|
||||
implement the map ↔ existing inversive distance I_ij via
|
||||
ℓ² = r_i² + r_j² + 2 r_i r_j η.
|
||||
→ Create code/include/decorated_dce.hpp.
|
||||
2. Transition driver — deform background curvature κ ∈ {+,0,−} while holding
|
||||
the discrete conformal invariant fixed; call the three existing solvers
|
||||
(euclidean, spherical, hyper_ideal).
|
||||
3. Validation harness — code/tests/cgal/test_decorated_dce.cpp.
|
||||
|
||||
All four acceptance criteria from phases.md must be met:
|
||||
- Decoration round-trip I_ij ↔ (r_i, r_j, ℓ) at machine precision.
|
||||
- At κ=0: bit-for-bit match with existing euclidean / inversive path.
|
||||
- Gauss-Bonnet holds per geometry across the κ-transition.
|
||||
- Invariant (I_ij) is constant across the three-geometry transition to tol.
|
||||
|
||||
Run the full CGAL suite (must stay green with new tests).
|
||||
Commit with trailer `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
|
||||
Push to origin, open a PR (base main) via the Gitea API. Update
|
||||
doc/roadmap/phase-orchestration.md (Phase 12 → ✅, session P2 + commit ref).
|
||||
Report the PR URL.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## P3 — Circle pattern embedding + Möbius centring + convergence study (model: **Sonnet**)
|
||||
|
||||
```
|
||||
Use the Sonnet model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
|
||||
branch off main called `feat/p3-circle-pattern-convergence`.
|
||||
|
||||
Three items — full details in doc/roadmap/phases.md:
|
||||
|
||||
- 9e Create code/include/circle_pattern_layout.hpp porting
|
||||
CirclePatternLayout + CirclePatternUtility. Phase 9a.1 (the CP-Euclidean
|
||||
energy + solver) is a prerequisite and is already landed on main.
|
||||
Java references: unwrapper/circlepattern/{CirclePatternLayout,
|
||||
CirclePatternUtility,CPEuclideanRotation}.java (phases.md §9e).
|
||||
Required test: given ρ values from a solved CP-Euclidean system, verify
|
||||
that the embedded vertex positions are self-consistent (each face's three
|
||||
circle-intersection points form the correct intersection angles to tol).
|
||||
|
||||
- 9d.4 Upgrade normalise_hyperbolic() in code/include/layout.hpp to use the
|
||||
variational MobiusCenteringFunctional (Lorentz energy
|
||||
E = Σ log(-⟨x,p⟩/√(-⟨x,x⟩)), gradient + Hessian).
|
||||
Java reference: functional/MobiusCenteringFunctional.java (289 LoC).
|
||||
Retain the existing Fréchet mean as a fallback if Newton fails.
|
||||
Required test: compare old vs new centring output on brezel.obj; both
|
||||
must place the centroid within tol of the origin.
|
||||
|
||||
- 9g.2 Add code/tests/cgal/test_period_matrix_convergence.cpp (experiment,
|
||||
not a library feature — see phases.md §9g.2):
|
||||
Generate a genus-1 elliptic mesh with a known analytic τ; subdivide via
|
||||
igl::loop; add per-vertex Gaussian noise; compute |τ_discrete − τ_analytic|
|
||||
after each step. Assert that the residual decreases monotonically with
|
||||
refinement (the discrete period matrix converges).
|
||||
|
||||
Run the full CGAL suite (must stay green).
|
||||
Commit with trailer `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
|
||||
Push to origin, open a PR (base main) via the Gitea API. Update
|
||||
doc/roadmap/phase-orchestration.md (9e/9d.4/9g.2 → ✅, P3 + commit ref).
|
||||
Report the PR URL and the convergence-study output.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## P4 — Analytic HyperIdeal Hessian (model: **Opus**) — ⏸ GATED on reviewer Q3
|
||||
|
||||
```
|
||||
PRECONDITION: do NOT start this session until the reviewer has answered Q3
|
||||
("Is the ~6× speedup over block-FD worth ~2 weeks at your typical mesh sizes?").
|
||||
If the answer is "no" or "not a priority", stop — Phase 9b-analytic stays ⏸.
|
||||
If the answer is "yes" or "above V > X", proceed.
|
||||
|
||||
Use the Opus model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
|
||||
branch off main called `feat/p4-analytic-hessian`.
|
||||
|
||||
Implement Phase 9b-analytic — the full analytic HyperIdeal Hessian via the
|
||||
Schläfli identity. The complete chain-rule derivation (805-line LaTeX note) and
|
||||
the implementation plan are in:
|
||||
doc/math/hyperideal-hessian-derivation.md
|
||||
doc/roadmap/phases.md §9b-analytic
|
||||
doc/roadmap/research-track.md §Phase 9b-analytic
|
||||
|
||||
Chain: (bᵢ, aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ → ∂²E/∂u².
|
||||
Replace the block-FD path in code/include/hyper_ideal_hessian.hpp with the
|
||||
analytic Hessian. Retain the block-FD path available as a compile-time flag
|
||||
(-DCONFORMALLAB_HYPER_IDEAL_FD_CHECK or runtime enum) for cross-validation.
|
||||
|
||||
Acceptance criteria:
|
||||
- All existing HyperIdeal golden-value tests pass bit-for-bit (HardJava clamp).
|
||||
- New test: analytic and block-FD Hessians agree to 1e-6 on the tetrahedron.
|
||||
- Benchmark: measure the analytic vs block-FD wall-time on the largest test
|
||||
mesh; report the ratio. Analytic must be faster for V > 500.
|
||||
|
||||
Run the full CGAL suite (must stay green). Commit; push; open PR via Gitea API.
|
||||
Update doc/roadmap/phase-orchestration.md (9b-analytic → ✅, P4 + commit ref).
|
||||
Report PR URL and the measured speed ratio.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Review gate (run after P1 / P2 / P3) (model: **Opus**)
|
||||
|
||||
```
|
||||
Use the Opus model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp. Review
|
||||
the open PR <PR_URL / branch name> as an independent reviewer. Check, and report
|
||||
a pass/fail per item:
|
||||
|
||||
- Builds clean; full CGAL suite green with no count regression
|
||||
(ctest --test-dir build-cgal -R '^cgal\.'); count matches doc/api/tests.md.
|
||||
- Any new functional has a gradient-check test (pattern in CLAUDE.md §Test design patterns).
|
||||
- No Java golden-vector / parity test perturbed; HardJava clamp default intact.
|
||||
- Numeric changes are value-identical where claimed, or justified + covered by a test.
|
||||
- New public surface (result types, enums, CGAL headers) is intentional and
|
||||
documented in doc/api/headers.md and doc/api/contracts.md.
|
||||
- Commit messages attribute the implementing model (Co-Authored-By trailer).
|
||||
- Phase(s) marked ✅ in doc/roadmap/phase-orchestration.md with the commit ref.
|
||||
|
||||
Read the actual diff (git diff main...HEAD -- code/include/ code/tests/ doc/)
|
||||
and the phases.md entry for the phase(s) involved. If you find a real problem,
|
||||
fix it directly (small) or list precise required changes (larger), then re-run
|
||||
the suite. Conclude with an explicit APPROVE / CHANGES-REQUESTED.
|
||||
```
|
||||
Reference in New Issue
Block a user