diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index f4c7a8b..12f4f08 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.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 | ⏳ | | diff --git a/docs/plans/2026-11-02-comparaison-references.md b/docs/plans/2026-11-02-comparaison-references.md new file mode 100644 index 0000000..9e85935 --- /dev/null +++ b/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 [dés]`, ou une option) produit, + pour une position et un niveau, un objet de même structure que la partie + `plies[""]` 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 ` ; +- 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.