Plan de l'étape 0a.4 : comparaison aux références

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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.4 | `make test` compare `engine-cli` aux références | ⏳ | |
+| 0a.4 | `make test` compare `engine-cli` aux références | 🔄 | `plans/2026-11-02-comparaison-references.md` |
 | 0b | Moteur en WebAssembly, page de test dans un Web Worker, `make deploy-web`, `make bench` | ⏳ | |
 | Mesures | Pierre relève les mesures sur le Fairphone 4 | ⏳ | |
 | Décision | Socle PWA ou Android natif, consigné dans un ADR — validation de Pierre | ⏳ | |

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

@@ -0,0 +1,76 @@
+# 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.