Agent Playbook

Guidance for maintainers and automation agents working on DemoLoterie. Keep this playbook close, follow the checklists, and add context when you discover new constraints.

TL;DR Workflow

1. Prep – read open issues/TODOs, skim AGENTS.md + README.md, update dependencies if needed.
2. Build once – mvn clean package to ensure the shaded jar still assembles.
3. Code + test in lockstep – every time you add production code, create or extend its matching unit test before moving on.
4. Tight dev loop – run mvn javafx:run for UI changes, or mvn test -Dtest=ClassNameTest for focused suites; add logs where they clarify runtime behavior.
5. Validate everything – execute the full suite (mvn test) after every change, then note any manual UI/data spot checks.
6. Deliver – summarize intent, list changes, capture evidence in commit/PR body, reference affected data files.

Mission Brief

• Extend the JavaFX lottery simulator launched via org.example.Launcher.
• Keep new code in the org.example namespace unless there is a justified module boundary.
• Ship portable artifacts through the shaded jar (target/demoloterie.jar) or, when requested, the Windows installer profile.
• Treat UI fidelity and deterministic draws as non-negotiable requirements.

Exigences QA incontournables

• Chaque ajout de code doit s’accompagner de son test unitaire dédié avant de pousser plus loin.
• Chaque modification, même minime, impose d’exécuter toute la suite (mvn test) afin de garantir l’absence de régressions.
• Chaque flux sensible doit exposer des logs explicites (niveau INFO/DEBUG/WARN selon le cas) pour faciliter le diagnostic terrain.
• Documentez dans les PR quelles classes/tests/logs ont été ajoutés ou enrichis afin que la traçabilité reste totale.

Architecture Snapshot

• Launcher/Main (src/main/java/org/example/Main.java): bootstraps JavaFX, applies theming, and wires up the wheel, ledger, and controls.
• Roue & Gains: RNG-backed wheel, must stay deterministic under seeded tests.
• DonationsLedger & Participant: CSV-backed models that mirror loterie-dons.csv et al. Never mutate user data during tests.
• ScaledContentPane: owns the global UI scale. Always construct it with the design resolution (DESIGN_WIDTH/HEIGHT) and choose the upscale policy explicitly.
• Theme/resources: CSS, FXML, and images belong under src/main/resources/ so they are packaged with the jar.
• Runtime data: loterie-dons.csv, loterie-historique.txt, loterie-save.txt live at the repo root; prefer fixtures under src/test/resources/ when writing tests.

When adding new functionality, colocate related classes in org.example (or a small subpackage such as org.example.ledger) to keep imports tidy.

UI Layout & Scaling Rules

• The root scene is wrapped by ScaledContentPane. Set scaledViewport.setAllowUpscale(true) for "shrink + grow" behavior (recommended) or false for letterboxing on large displays.
• Never apply additional setScaleX/Y transformations to rootPane; all global scaling should remain inside ScaledContentPane.
• Keep the logical design size at 1920×1080. If you must change it, update constants, CSS expectations, tests, and documentation in the same change.
• When touching JavaFX layouts, run mvn javafx:run on both small (≤1366×768) and large (≥2560px wide) windows to confirm centering/clipping remain correct.
• Add concise comments for non-obvious layout constraints (drag thresholds, clip rectangles, animation timing).

Command Reference

• Build shaded jar: mvn clean package
• Run UI quickly: mvn javafx:run
• Execute packaged app: java -jar target/demoloterie.jar
• Unit tests: mvn test or mvn test -Dtest=ClassNameTest
• Windows installer: mvn clean package -Pwindows-installer (JDK 21+, Windows)

Cache these commands in scripts if you automate them, but keep the canonical invocation in this doc.

Coding Standards & Tooling

• Java 21, 4-space indentation, lines ≲120 chars. No tabs.
• Classes = UpperCamelCase, members = lowerCamelCase, constants = SCREAMING_SNAKE_CASE.
• Use JavaFX properties where state is observable; avoid static singletons for UI controllers.
• Prefer rg, mvn, and provided scripts inside the repo; do not introduce new build tools without discussion.
• Keep comments short and meaningful—explain why, not what.
• Instrument functional code with explicit logs (e.g., via Logger) so operational issues are visible without attaching a debugger; include context such as participant IDs, draw results, and ledger deltas.

Testing & QA Expectations

• Tests live under src/test/java/org/example/ and must follow the *Test suffix (e.g., DonationsLedgerTest).
• Every new feature or class must ship with at least one focused unit test that exercises the added behavior; do not merge production code without its companion test.
• Seed RNG-dependent code (wheel, gains) so tests are deterministic. Inject seeds or expose seam points when necessary.
• Use fixtures instead of mutating the runtime CSV/TXT files. If a bug depends on current data, clone the relevant rows into a test resource.
• Run the full suite (mvn test) after any change—no matter how small—to ensure regressions are caught early. Document any skipped suites or known flaky tests in the PR description.
• For UI-affecting changes, list manual verification steps (screen size, action performed, expected outcome).

Data & Configuration Discipline

• Preserve the column order and encoding of CSV/TXT files. Document any irreversible migration and supply conversion scripts when needed.
• New resource files (CSS/FXML/images) belong in src/main/resources/ and should be loaded via the classpath (getResource).
• Avoid hard-coded absolute paths. Use Paths.get or resource streams.
• When touching ledger persistence, mention the expected impact on loterie-dons.csv and ensure back-compat with existing entries.

Commit & PR Workflow

• Commit messages: imperative voice, ≤60 characters (Refine ledger persistence). Add a short body with context, data impacts, and test evidence.
• Reference issues (Fix #12) when relevant. If UI or data change, attach before/after notes or screenshots.
• PR checklist:
  • Intent + scope clearly stated.
  • Key changes enumerated (features, refactors, data updates).
  • Test evidence pasted (mvn test, mvn javafx:run, manual checks).
  • Data or config migrations explained, with rollback notes if applicable.

When in Doubt

• Prefer incremental, reversible changes. Leave TODO(username): context markers rather than half-finished refactors.
• Ask for clarification before moving files out of the documented structure or adding new external dependencies.
• Keep local experiments (scratch code, large datasets) out of commits; clean your workspace before pushing.
• Document surprises (API quirks, platform bugs) in this file so the next agent starts informed—feel free to append new sections following the style above.