pierre/Ustagammon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity

Étape 0a.2 : gnubg de référence et 32 positions de référence #6

Manually merged
pierre merged 0 commits from reference into main 2026-11-02 18:03:48 +00:00
Conversation 0 Commits - Files Changed -
pierre commented 2026-11-02 13:00:58 +00:00
Owner
Copy Link
Copy Source

Pourquoi

Les tests sont le filet de sécurité du projet (CLAUDE.md) et le moteur embarqué doit concorder avec GNU Backgammon de bureau (cadrage). Il faut donc des résultats de référence produits par le vrai gnubg de bureau, au même commit que le moteur embarqué (ADR 0005 : 14b67984737ded0f6de43d63dcb789f729d9b06b), et non pas par un paquet Debian d'une autre version. C'est l'étape 0a.2 de la feuille de route.

Quoi

  • docker/gnubg-reference/Dockerfile : construit gnubg de bureau dans Docker sur debian:trixie. Les sources sont clonées au commit figé, avec vérification du hash. La compilation se fait en -j2, sans interface graphique, avec le scripting Python intégré de gnubg. Les données du moteur sont produites par les outils officiels : gnubg.wd (408 016 octets), gnubg_os0.bd (1 465 788 octets) et gnubg_ts0.bd (6 830 248 octets). Leurs SHA-256 sont consignés dans l'image.
  • make reference-image construit l'image ; make setup l'appelle.
  • make reference régénère tests/reference/results/ à partir de tests/reference/positions.json.
  • 32 positions de référence, dans 18 catégories :
    • ouvertures, milieux de partie, primes, blitz, courses et sorties (bases à un et deux côtés) ;
    • aucun coup légal, coup forcé ;
    • décisions de videau : pas de double, double/prend, double/passe, redouble, trop bon ;
    • règle de Jacoby, positions en match (3-away, double match point, Crawford, post-Crawford).
  • Pour chaque position, aux niveaux 0 et 2 plis, le générateur enregistre l'évaluation (5 probabilités et équité), le classement des coups (10 premiers, avec notation gnubg, pli réel, équité, écart et probabilités) ou la décision de videau.
  • tests/reference/README.md : le format JSON, qui est le contrat que respectera engine-cli (clés en anglais, conventions de joueur et de signe, normalisation des équités en match).
  • tests/test_reference.sh (lancé par make test) : vérifie la cohérence des références elles-mêmes, sans Docker. Il contrôle le JSON, le nombre de positions, l'unicité, les catégories, les champs, la présence des deux niveaux, et la cohérence des décisions de videau avec les catégories.

Comment

Le travail a été délégué à un sous-agent selon un plan écrit avant la délégation (supprimé à la clôture ; son contenu durable est repris ici). Le générateur (tests/reference/generate.py) tourne à l'intérieur de gnubg. Pour chaque position et chaque niveau, il vide le cache, recharge la position, et vérifie que gnubg relit les mêmes identifiants et les mêmes dés. Il contrôle aussi le filtre de coups « Normal » et la table d'équité Kazaross-XG2. Toute incohérence fait échouer make reference.

Les Position ID et Match ID ont été calculés par gnubg lui-même à partir de plateaux décrits à la main. Le générateur revérifie qu'il les relit à l'identique.

Vérification par la session principale, sur la branche fusionnée avec main :

  • make setup && make reference (13 s) ;
  • git diff --exit-code tests/reference : aucune différence, la régénération est déterministe ;
  • sondages : ouverture 31 → 8/5 6/5, 42 → 8/4 6/4 ; positions de videau → NODOUBLE_TAKE, DOUBLE_TAKE, DOUBLE_PASS, REDOUBLE_TAKE, TOOGOOD_PASS comme attendu ;
  • make lint et make test (5/5).

Choix et compromis

  • « 2 plis » ne veut pas dire que tous les coups sont évalués à 2 plis. gnubg s'arrête au pli où un seul coup survit au filtre. Pour le 3-1 d'ouverture, 8/5 6/5 est évalué à 1 pli, comme l'affiche gnubg lui-même. Chaque coup porte donc son champ ply, et engine-cli devra appeler le moteur exactement comme la commande hint de gnubg (documenté dans le README du format).
  • Castors : le module Python de gnubg ne les autorise pas en partie libre, alors que les analyses de gnubg les autorisent. Le générateur rétablit le réglage de gnubg. Aucune valeur numérique ne change sur ces 32 positions.
  • SIMD forcé à SSE2 dans l'image, pour que les références ne dépendent pas du processeur qui construit l'image. Les options officielles de gnubg (-O3 -ffast-math) sont conservées : c'est le gnubg de bureau tel que distribué.
  • Image de 1,14 Go (sources de compilation conservées). Une construction en deux étapes la réduirait ; ce n'est pas fait, par simplicité.
  • jq tourne sur le PC dans tests/test_reference.sh, contrairement à l'ADR 0004 (tout outil dans Docker). Ce sera corrigé à l'étape 0a.4, en le faisant passer par l'image de compilation C qui arrive avec 0a.3.

Risques et déploiement

  • make setup construit maintenant l'image de référence : la première fois, comptez environ 5 à 9 minutes et un téléchargement des paquets Debian.
  • make reference n'est pas lancé par make test : les résultats sont commités, et les tests ne dépendent pas de Docker pour cette partie.
  • Si l'on change le commit de gnubg, il faut reconstruire l'image et régénérer les références dans la même MR.

Retour arrière : annuler le commit de fusion.

Comment vérifier

git switch main && git pull
make setup
make reference && git diff --exit-code tests/reference
make lint && make test
jq '.plies["2"].moves.ranking[0]' tests/reference/results/opening-31.json

Hors périmètre

  • La comparaison du moteur embarqué avec ces références, c'est l'étape 0a.4.
  • La mesure de l'écart dû à -ffast-math, aussi à l'étape 0a.4.
  • Le Match ID cAkAAAAAAAAA cité dans docs/etape-0.md met le joueur 1 au trait, pas le joueur 0 (constaté à l'étape 0a.3). La doc sera corrigée avec 0a.3.
  • La MR ne sera pas marquée « fusionnée » par Gitea après fusion : les hooks git du serveur ne s'exécutent pas (diagnostic en cours, à part).

Generated with Claude Code https://claude.com/claude-code

## Pourquoi Les tests sont le filet de sécurité du projet (CLAUDE.md) et le moteur embarqué doit concorder avec GNU Backgammon de bureau (cadrage). Il faut donc des résultats de référence produits par le vrai gnubg de bureau, au même commit que le moteur embarqué (ADR 0005 : 14b67984737ded0f6de43d63dcb789f729d9b06b), et non pas par un paquet Debian d'une autre version. C'est l'étape 0a.2 de la feuille de route. ## Quoi - **`docker/gnubg-reference/Dockerfile`** : construit gnubg de bureau dans Docker sur `debian:trixie`. Les sources sont clonées au commit figé, avec vérification du hash. La compilation se fait en `-j2`, sans interface graphique, avec le scripting Python intégré de gnubg. Les données du moteur sont produites par les outils officiels : `gnubg.wd` (408 016 octets), `gnubg_os0.bd` (1 465 788 octets) et `gnubg_ts0.bd` (6 830 248 octets). Leurs SHA-256 sont consignés dans l'image. - **`make reference-image`** construit l'image ; `make setup` l'appelle. - **`make reference`** régénère `tests/reference/results/` à partir de `tests/reference/positions.json`. - **32 positions de référence**, dans 18 catégories : - ouvertures, milieux de partie, primes, blitz, courses et sorties (bases à un et deux côtés) ; - aucun coup légal, coup forcé ; - décisions de videau : pas de double, double/prend, double/passe, redouble, trop bon ; - règle de Jacoby, positions en match (3-away, double match point, Crawford, post-Crawford). - **Pour chaque position, aux niveaux 0 et 2 plis**, le générateur enregistre l'évaluation (5 probabilités et équité), le classement des coups (10 premiers, avec notation gnubg, pli réel, équité, écart et probabilités) ou la décision de videau. - **`tests/reference/README.md`** : le format JSON, qui est le contrat que respectera `engine-cli` (clés en anglais, conventions de joueur et de signe, normalisation des équités en match). - **`tests/test_reference.sh`** (lancé par `make test`) : vérifie la cohérence des références elles-mêmes, sans Docker. Il contrôle le JSON, le nombre de positions, l'unicité, les catégories, les champs, la présence des deux niveaux, et la cohérence des décisions de videau avec les catégories. ## Comment Le travail a été délégué à un sous-agent selon un plan écrit avant la délégation (supprimé à la clôture ; son contenu durable est repris ici). Le générateur (`tests/reference/generate.py`) tourne à l'intérieur de gnubg. Pour chaque position et chaque niveau, il vide le cache, recharge la position, et vérifie que gnubg relit les mêmes identifiants et les mêmes dés. Il contrôle aussi le filtre de coups « Normal » et la table d'équité Kazaross-XG2. Toute incohérence fait échouer `make reference`. Les Position ID et Match ID ont été calculés par gnubg lui-même à partir de plateaux décrits à la main. Le générateur revérifie qu'il les relit à l'identique. Vérification par la session principale, sur la branche fusionnée avec `main` : - `make setup && make reference` (13 s) ; - `git diff --exit-code tests/reference` : aucune différence, la régénération est déterministe ; - sondages : ouverture 31 → `8/5 6/5`, 42 → `8/4 6/4` ; positions de videau → `NODOUBLE_TAKE`, `DOUBLE_TAKE`, `DOUBLE_PASS`, `REDOUBLE_TAKE`, `TOOGOOD_PASS` comme attendu ; - `make lint` et `make test` (5/5). ## Choix et compromis - **« 2 plis » ne veut pas dire que tous les coups sont évalués à 2 plis.** gnubg s'arrête au pli où un seul coup survit au filtre. Pour le 3-1 d'ouverture, `8/5 6/5` est évalué à 1 pli, comme l'affiche gnubg lui-même. Chaque coup porte donc son champ `ply`, et `engine-cli` devra appeler le moteur exactement comme la commande `hint` de gnubg (documenté dans le README du format). - **Castors** : le module Python de gnubg ne les autorise pas en partie libre, alors que les analyses de gnubg les autorisent. Le générateur rétablit le réglage de gnubg. Aucune valeur numérique ne change sur ces 32 positions. - **SIMD forcé à SSE2** dans l'image, pour que les références ne dépendent pas du processeur qui construit l'image. Les options officielles de gnubg (`-O3 -ffast-math`) sont conservées : c'est le gnubg de bureau tel que distribué. - **Image de 1,14 Go** (sources de compilation conservées). Une construction en deux étapes la réduirait ; ce n'est pas fait, par simplicité. - **`jq` tourne sur le PC** dans `tests/test_reference.sh`, contrairement à l'ADR 0004 (tout outil dans Docker). Ce sera corrigé à l'étape 0a.4, en le faisant passer par l'image de compilation C qui arrive avec 0a.3. ## Risques et déploiement - `make setup` construit maintenant l'image de référence : la première fois, comptez environ 5 à 9 minutes et un téléchargement des paquets Debian. - `make reference` n'est pas lancé par `make test` : les résultats sont commités, et les tests ne dépendent pas de Docker pour cette partie. - Si l'on change le commit de gnubg, il faut reconstruire l'image et régénérer les références dans la même MR. Retour arrière : annuler le commit de fusion. ## Comment vérifier ``` git switch main && git pull make setup make reference && git diff --exit-code tests/reference make lint && make test jq '.plies["2"].moves.ranking[0]' tests/reference/results/opening-31.json ``` ## Hors périmètre - La comparaison du moteur embarqué avec ces références, c'est l'étape 0a.4. - La mesure de l'écart dû à `-ffast-math`, aussi à l'étape 0a.4. - Le Match ID `cAkAAAAAAAAA` cité dans `docs/etape-0.md` met le joueur 1 au trait, pas le joueur 0 (constaté à l'étape 0a.3). La doc sera corrigée avec 0a.3. - La MR ne sera pas marquée « fusionnée » par Gitea après fusion : les hooks git du serveur ne s'exécutent pas (diagnostic en cours, à part). Generated with Claude Code https://claude.com/claude-code
pierre added 5 commits 2026-11-02 13:00:58 +00:00
Plan de l'étape 0a.2 : gnubg et positions de référence ec0f4daef3 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Image Docker du gnubg de référence (commit 14b6798) 8677193bee 
Compile gnubg sans interface graphique, avec Python, SIMD forcé à SSE2,
et produit gnubg.wd, gnubg_os0.bd, gnubg_ts0.bd avec les outils officiels.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Positions de référence évaluées par gnubg (0 et 2 plis) b199698b11 
32 positions (ouvertures, milieu, prime, blitz, course, sortie, videau,
match, Crawford, Jacoby), générées par make reference ; format documenté
dans tests/reference/README.md, vérifié par tests/test_reference.sh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Plan 0a.2 : résultat c1baf1a5d3 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Étape 0a.2 : gnubg de référence et 32 positions de référence b273b96c33 
Fusion du travail du sous-agent (branche moteur-reference-travail) ; plan
supprimé à la clôture, son résultat est repris dans la merge request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pierre manually merged commit 1d97d40a7c into main 2026-11-02 18:03:48 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
pierre (Pierre Martin)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: pierre/Ustagammon#6