Ustagammon/docs/plans/2026-11-02-comparaison-references.md

Comparer le moteur embarqué aux références de gnubg de bureau

• Date : 2026-11-02
• Étape : 0a.4
• Statut : en cours
• Exécutant : sous-agent general-purpose, dans un worktree isolé

Objectif

make test vérifie automatiquement que le moteur embarqué (build/engine-cli) retrouve les résultats de gnubg de bureau sur les 32 positions de tests/reference/, aux niveaux 0 et 2 plis, avec une tolérance mesurée et justifiée.

Consignes

1. Sortie d'engine-cli alignée sur le contrat de tests/reference/README.md : une sous-commande (par exemple engine-cli reference <position_id> <match_id> [dés], ou une option) produit, pour une position et un niveau, un objet de même structure que la partie plies["<n>"] d'un fichier de résultat (evaluation, moves ou cube). Le classement des coups suit exactement la méthode de la commande hint de gnubg (documentée dans le README du format) : nombre de coups, notation, pli réel de chaque coup. Garder engine-cli simple : réutiliser les fonctions d'engine.h, compléter engine.h si nécessaire.
2. Comparateur : un script lisible (Python 3 ou shell avec jq) qui, pour chaque position et chaque niveau, appelle engine-cli, compare au résultat de référence et affiche un rapport clair (position, niveau, champ, valeur attendue, valeur obtenue, écart). Il tourne dans Docker (ajouter ce qu'il faut à docker/build-c/Dockerfile et changer l'étiquette de l'image dans le Makefile), jamais avec les outils du PC (ADR 0004).
3. Critères de concordance :
   • même nombre de coups légaux ;
   • même meilleur coup, sauf si gnubg lui-même sépare les deux premiers coups de moins que la tolérance (cas d'égalité : le dire dans le rapport) ;
   • même pli réel du meilleur coup ;
   • équités et probabilités à la tolérance près, pour les coups communs ;
   • même décision de videau, et équités du videau à la tolérance près.
4. Tolérance mesurée, pas devinée : mesurer l'écart maximal observé sur les 32 positions, l'expliquer (gnubg de bureau en SSE2 avec -ffast-math, moteur embarqué en C générique), et mesurer aussi l'écart d'un build du moteur sans -ffast-math. Fixer la tolérance avec une marge raisonnable et la justifier dans tests/reference/README.md.
5. tests/test_engine_reference.sh, lancé par make test : lance make engine si nécessaire puis le comparateur ; échoue avec le rapport si un critère n'est pas tenu.
6. tests/test_reference.sh n'utilise plus jq sur le PC : passer par l'image Docker de la chaîne C (ADR 0004), et mettre CREDITS.md à jour.

Contraintes :

• respecter CLAUDE.md et les ADR 0004, 0005 et 0007 : simplicité, identifiants en anglais, commentaires en français, aucune installation hors Docker, -j2 ;
• ne pas modifier les références (tests/reference/results/) ni les fichiers de engine/gnubg/ ; si une divergence vient d'un vrai défaut du moteur embarqué, corriger dans engine/compat/ ou engine/src, et le dire ;
• ne rien masquer : si une position ne concorde pas, le rapport doit le montrer, avec la cause trouvée ou les hypothèses ;
• 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.

Rapport attendu : ce qui a été fait, la tolérance retenue et sa justification (écarts mesurés avec et sans -ffast-math), les éventuelles divergences et leur cause, les commandes de vérification.

Critères de réussite

• make test compare les 32 positions aux deux niveaux et passe.
• La tolérance est documentée et justifiée par des mesures.
• Une divergence volontairement introduite (par exemple une référence modifiée dans une copie) fait échouer le test avec un rapport lisible.

Résultat

À remplir à la clôture.