From ec0f4daef3ad7ebd6efa604700705d980fa8c0ec Mon Sep 17 00:00:00 2001 From: Pierre MARTIN Date: Mon, 2 Nov 2026 13:32:50 +0100 Subject: [PATCH] =?UTF-8?q?Plan=20de=20l'=C3=A9tape=200a.2=20:=20gnubg=20e?= =?UTF-8?q?t=20positions=20de=20r=C3=A9f=C3=A9rence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- docs/feuille-de-route.md | 2 +- docs/plans/2026-11-02-moteur-reference.md | 81 +++++++++++++++++++++++ 2 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 docs/plans/2026-11-02-moteur-reference.md diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index db7db74..6d35b11 100644 --- a/docs/feuille-de-route.md +++ b/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` | ⏳ | | diff --git a/docs/plans/2026-11-02-moteur-reference.md b/docs/plans/2026-11-02-moteur-reference.md new file mode 100644 index 0000000..8c1f433 --- /dev/null +++ b/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 ` ; +- 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.