Ustagammon/docs/plans/2026-11-02-domaine-partie.md

Domaine « partie » en TypeScript, scénarios exécutés, garde-fous

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

Objectif

Le domaine d'une partie contre l'ordinateur existe en TypeScript, sous forme de journal d'événements (ADR 0007), branché au moteur WebAssembly par une interface Engine. Le scénario docs/scenarios/jouer-une-partie.feature s'exécute sous Node, sur le vrai moteur, dans make test. Les règles d'architecture et le lien glossaire ↔ code sont vérifiés par les tests. L'interface graphique et la PWA sont l'étape suivante (0d.2), pas celle-ci.

Consignes

1. Outillage (ADR 0009, ADR 0004) : une image docker/web/ (Node node:22.11.0-alpine3.20 déjà présent, versions npm figées et vérifiées) avec TypeScript, Biome, @cucumber/cucumber et dependency-cruiser. Cibles make web (compile app/ vers build/web/ avec tsc), et intégration à make lint (Biome et tsc --noEmit) et make test. Étiquette d'image dans le Makefile, make setup la construit. CREDITS.md à jour.
2. Arborescence (à ajuster si plus simple) :
   • app/src/domain/ : le domaine pur, sous-dossier game/ ;
   • app/src/engine/ : l'adaptateur qui implémente Engine avec le moteur WebAssembly (réutiliser web/engine-wasm.mjs et build/wasm/) ;
   • app/src/ui/ : vide pour l'instant (étape 0d.2) ;
   • app/tests/ : tests unitaires (runner intégré de Node, node:test) et définitions des étapes Cucumber. Les pages de prototype existantes (web/index.html, web/bench.html) doivent continuer de fonctionner.
3. Interface Engine définie par le domaine (coups légaux avec position résultante, meilleur coup pour un niveau, décision de videau, décodage d'une position en plateau pour l'affichage). Compléter engine.h et engine-cli si une information manque (par exemple décoder un Position ID en nombre de pions par case, savoir si la partie est finie et combien elle rapporte), en restant simple, avec tests natifs.
4. Journal d'événements (ADR 0007, point 3) : événements immuables avec identifiant, parent et version de format (GameStarted, DiceRolled, MovePlayed, CubeOffered, CubeTaken, CubeDropped, GameEnded). L'état se calcule en rejouant le journal. Une branche est un nouvel événement accroché à un ancien ; annuler revient à repartir du parent. Le hasard des dés est injecté (source de dés passée au domaine).
5. Règles de la partie de 0d : partie libre contre l'ordinateur (Jacoby selon les réglages par défaut de gnubg) ; l'ordinateur joue le meilleur coup au niveau « standard » (choisir un niveau qui tienne les 2 s sur téléphone : 2 plis d'après les mesures 0b, à confirmer) ; il décide du videau avec le moteur ; le joueur peut prendre ou passer, et peut lui-même doubler (le moteur décide alors si l'ordinateur prend ou passe). Le joueur saisit son coup demi-coup par demi-coup (case de départ, case d'arrivée) ; le domaine n'accepte que ce qui mène à un coup légal complet. Aucune règle du jeu n'est réimplémentée : tout vient du moteur.
6. Glossaire ↔ code (ADR 0008) : chaque type du domaine qui correspond à un terme porte Glossaire : docs/glossaire/<fiche>.md en commentaire, et la fiche reçoit code: <Type>. Ajouter les fiches manquantes. Étendre tests/test_glossary.sh pour vérifier le lien dans les deux sens.
7. Scénarios exécutés : définitions des étapes en français pour docs/scenarios/jouer-une-partie.feature, branchées sur le domaine et le vrai moteur WebAssembly (sous Node), avec des dés imposés pour être reproductibles. Si une étape du scénario est impossible à exécuter telle quelle, ajuster le scénario en gardant son sens pour le joueur, et le dire.
8. Garde-fous d'architecture (dependency-cruiser) : le domaine n'importe ni engine/, ni ui/, ni rien de spécifique au navigateur ; ui/ n'importe pas engine/ ; pas de dépendance circulaire. Vérifier qu'une violation volontaire fait échouer make test.

Contraintes :

• CLAUDE.md, ADR 0004, 0007, 0008, 0009 : simplicité avant tout, pas de patron de conception sans besoin, identifiants en anglais, commentaires et docs en français, tout outil dans Docker, -j2 ;
• ne pas modifier engine/gnubg/ ni les références ;
• 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 ; ne rien simuler.

Rapport attendu : ce qui a été fait, l'API du domaine en quelques lignes, les fiches de glossaire ajoutées, le résultat des scénarios, les vérifications des garde-fous, les difficultés, les écarts au plan.

Critères de réussite

• make test exécute le scénario « Jouer une partie contre l'ordinateur » sur le vrai moteur et passe.
• Une partie complète (jusqu'à GameEnded) se joue dans un test, l'ordinateur contre une stratégie simple du joueur, avec des dés imposés.
• Les garde-fous d'architecture et le lien glossaire ↔ code échouent sur une violation volontaire.
• make lint et make test passent.

Résultat

À remplir à la clôture.