Plan de l'étape 0a.2 : gnubg et positions de référence

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

docs/feuille-de-route.md

@@ -14,7 +14,7 @@ Acquis : socle du dépôt, organisation (ADR 0001, 0003, 0006), source du moteur
 
 | Sous-étape | Contenu | État | Plan |
 | --- | --- | --- | --- |
-| 0a.2 | Image Docker GNU Backgammon de bureau (compilé depuis le commit 14b6798), 30+ positions de référence dans `tests/reference/` | ⏳ | |
+| 0a.2 | Image Docker GNU Backgammon de bureau (compilé depuis le commit 14b6798), 30+ positions de référence dans `tests/reference/` | 🔄 | `plans/2026-11-02-moteur-reference.md` |
 | 0a.3 | Interface C `engine/include/moteur.h` et `engine-cli` (JSON) | ⏳ | |
 | 0a.4 | `make test` compare `engine-cli` aux références | ⏳ | |
 | 0b | Moteur en WebAssembly, page de test dans un Web Worker, `make deploy-web`, `make bench` | ⏳ | |

docs/plans/2026-11-02-moteur-reference.md

@@ -0,0 +1,81 @@
+# gnubg de référence et positions de référence
+
+- **Date** : 2026-11-02
+- **Étape** : 0a.2
+- **Statut** : en cours
+- **Exécutant** : sous-agent general-purpose, dans un worktree isolé
+
+## Objectif
+
+Disposer d'un GNU Backgammon de bureau, compilé dans Docker depuis le commit
+14b67984737ded0f6de43d63dcb789f729d9b06b (ADR 0005), et d'au moins 30
+positions de référence évaluées par lui, stockées dans `tests/reference/` dans
+un format que le futur `engine-cli` (0a.3) pourra comparer automatiquement.
+
+## Consignes
+
+1. `docker/gnubg-reference/Dockerfile` : image de compilation de gnubg au
+   commit figé, sans interface graphique (pas de GTK, pas de 3D), avec ce qu'il
+   faut pour piloter gnubg sans interface (le scripting Python intégré de gnubg
+   est le chemin recommandé pour obtenir des résultats structurés). Base Debian
+   figée (`debian:trixie`, déjà présente). Compilation en `-j2` maximum.
+   L'image doit aussi produire, avec les outils officiels, `gnubg.wd`,
+   `gnubg_os0.bd` et `gnubg_ts0.bd`, et le documenter : le moteur embarqué
+   devra utiliser exactement les mêmes données.
+2. Cibles make, visibles dans `make help` :
+   - `make reference-image` : construit l'image (sans effet si à jour) ;
+     `make setup` l'appelle.
+   - `make reference` : régénère `tests/reference/` depuis la liste des
+     positions. Résultat déterministe : deux exécutions donnent des fichiers
+     identiques.
+3. Une liste de positions d'entrée versionnée (par exemple
+   `tests/reference/positions.txt` ou `.json`), au moins 30, couvrant :
+   ouvertures (plusieurs jets), milieu de partie avec contact, prime et blitz,
+   course, sortie (fin de partie dans la base de bearoff), décisions de videau
+   (pas de double, double/prend, double/passe), au moins quelques positions en
+   match (score, Crawford) et en partie libre (Jacoby). Chaque position est
+   donnée par Position ID + Match ID, avec les dés pour les décisions de coup.
+4. Pour chaque position, le générateur enregistre, aux niveaux 0-ply et 2-ply
+   de gnubg (réglages prédéfinis, sans bruit) :
+   - décision de coup : liste des coups légaux classés (au moins les 5
+     premiers, avec notation gnubg, équité et les 5 probabilités), et le
+     nombre total de coups légaux ;
+   - décision de videau : équités sans double, double/prend, double/passe,
+     et la décision proposée ;
+   - évaluation de la position : les 5 probabilités (gain, gain gammon, gain
+     backgammon, perte gammon, perte backgammon) et l'équité.
+5. Format des résultats : JSON, documenté dans `tests/reference/README.md`
+   (schéma, unités, conventions de signe et de joueur, niveau, table d'équité
+   de match utilisée, version exacte de gnubg et des données). C'est le contrat
+   que respectera `engine-cli`.
+6. `tests/test_reference.sh` : vérifie la cohérence des références elles-mêmes
+   (JSON valide avec `jq` ou équivalent, nombre de positions ≥ 30, chaque
+   catégorie présente, champs obligatoires présents). Il ne lance pas Docker.
+7. Mentions : `CREDITS.md` (image Debian, gnubg compilé pour la référence),
+   `.gitignore` si besoin.
+
+Contraintes :
+- respecter `CLAUDE.md` (français, `-j2`, aucune installation hors Docker) ;
+- les sources de gnubg sont téléchargées dans l'image (clone au commit figé),
+  pas copiées dans le dépôt ;
+- `make lint` et `make test` doivent passer ; commits petits, en français,
+  avec la ligne `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>` ;
+- ne pas pousser ni créer de merge request : la session principale s'en charge ;
+- ne rien simuler : si une valeur ne peut pas être obtenue de gnubg, le dire.
+
+Rapport attendu : ce qui a été fait, les commandes de vérification, le temps
+de construction de l'image, la taille des données (`.wd`, `.bd`), le schéma
+JSON retenu, les difficultés et tout écart au plan.
+
+## Critères de réussite
+
+- `make reference-image && make reference` fonctionne depuis un dépôt propre.
+- Deux exécutions de `make reference` produisent des fichiers identiques
+  (`git diff --exit-code tests/reference`).
+- `tests/reference/` contient au moins 30 positions couvrant toutes les
+  catégories, aux niveaux 0-ply et 2-ply.
+- `make lint` et `make test` passent.
+
+## Résultat
+
+À remplir à la clôture.