Ustagammon/docs/plans/2026-11-03-moteur-analyse.md

Moteur pour l'analyse et les niveaux (1a)

• Date : 2026-11-03
• Étape : 1a (docs/etape-1.md)
• Statut : en cours
• Exécutant : sous-agent general-purpose, dans un worktree

Objectif

Donner au domaine tout ce dont l'étape 1 a besoin du moteur : niveaux de jeu de l'ordinateur, analyse d'un coup joué et d'une décision de videau, chance d'un jet. Tout vient de GNU Backgammon, comparé à gnubg de bureau.

Consignes

ADR 0005, 0007 et la méthode de comparaison de tests/reference/ (README). Ne pas modifier engine/gnubg/ (copie fidèle). Pas de nouvelle dépendance.

1. Niveaux de jeu : les niveaux de GNU Backgammon (débutant, amateur, intermédiaire, avancé, expert, champion du monde…), avec leurs plis, filtres et bruit, repris des réglages prédéfinis de gnubg (pas inventés). Le bruit doit être déterministe (option « deterministic » de gnubg) pour que les tests soient reproductibles. API C (engine.h), engine-cli, adaptateur WebAssembly et interface Engine du domaine (ajout seulement : ne pas toucher au reste de app/src/domain/game/, qu'un autre agent modifie).
2. Analyse d'un coup joué : pour une position, un jet et un coup joué, l'équité du coup joué, celle du meilleur coup, l'écart, et le rang du coup joué, au niveau d'analyse demandé (comme l'analyse de partie de gnubg).
3. Analyse d'une décision de videau : équités sans double, double/prend, double/passe, et l'écart de la décision prise (double, pas de double, prendre, passer), comme gnubg.
4. Chance d'un jet : la chance (luck) d'un jet au sens de gnubg, et son classement (très chanceux… très malchanceux) avec les seuils de gnubg.
5. Seuils d'appréciation : exposer les seuils de gnubg (douteux, mauvais, très mauvais) comme constantes documentées ; l'interface les traduira.
6. Références : ajouter des positions de référence évaluées par gnubg de bureau (Docker existant, make reference) pour l'analyse d'un coup, d'une décision de videau et la chance, comparées par make test (natif et WebAssembly) avec la tolérance existante. Les niveaux avec bruit : vérifier au moins que le coup choisi est reproductible et identique à celui de gnubg de bureau sur quelques positions.
7. Glossaire : fiches pour les nouveaux termes (niveau, chance, appréciation, équité si absente…), reliées au code.
8. Mesurer sous Node (make bench ou équivalent) le temps d'une analyse de coup au niveau prévu pour le conseil du maître (2 plis), pour vérifier qu'elle tient en arrière-plan sur le téléphone (repère : ADR 0009).

Machine ancienne : -j2, ne recompiler le moteur que si nécessaire. make lint et make test doivent passer. Commits fréquents ; git add avec chemins explicites ; ne pas pousser, pas de MR.

Critères de réussite

• engine-cli répond aux nouvelles commandes en JSON.
• Les nouvelles références concordent avec gnubg de bureau, natif et WebAssembly.
• make lint et make test passent.

Résultat

À remplir à la clôture.