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

gnubg de référence et positions de référence

• Date : 2026-11-02
• Étape : 0a.2
• Statut : terminé
• 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

Terminé le 2026-11-02 sur la branche moteur-reference-travail.

• docker/gnubg-reference/Dockerfile : gnubg 1.08.003 au commit figé, sans GTK ni 3D ni SQLite, Python intégré, SIMD forcé à SSE2 (résultat indépendant du processeur hôte), drapeaux par défaut -O3 -ffast-math. Construction complète environ 9 minutes (dont 4 de paquets Debian et 1,5 de compilation en -j2) ; image de 1,14 Go.
• Données produites par make de gnubg : gnubg.wd 408 016 octets, gnubg_os0.bd 1 465 788 octets, gnubg_ts0.bd 6 830 248 octets ; sommes SHA-256 dans l'image (/usr/local/share/gnubg/donnees.sha256).
• make reference-image, make reference (une vingtaine de secondes, déterministe : deux exécutions identiques), 32 positions dans tests/reference/positions.json, résultats dans tests/reference/results/, format dans tests/reference/README.md, contrôle par tests/test_reference.sh (jq sur le PC).
• Écarts au plan : clés JSON et identifiants en anglais (consigne reçue en cours de tâche) ; jq est utilisé sur le PC, hors Docker.
• Points notables pour 0a.3 : à 2 plis, gnubg s'arrête au pli où un seul coup survit au filtre (le 3-1 d'ouverture est classé à 1 pli) ; gnubg.cubeinfo() ne reflète pas les castors, le générateur reprend le réglage de gnubg (castors autorisés en partie libre).