# 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.