Cadrage et règles du projet

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 12:56:36 +01:00
parent 6effe33871
commit 6d4ff4e7b4
5 changed files with 1078 additions and 225 deletions
@@ -0,0 +1,73 @@
+# Étape 0 — Prototype technique
+
+**But** : prouver que la chaîne technique fonctionne avant d'investir dans le design, et trancher entre deux socles : PWA (moteur en WebAssembly) ou Android natif.
+
+**Règle** : chaque sous-étape se termine par une démonstration que le développeur peut lancer lui-même avec une commande `make`.
+
+---
+
+## 0a. Le moteur en ligne de commande
+
+**Objectif** : interroger le moteur GNU Backgammon sur une position, depuis le PC.
+
+À faire :
+1. Récupérer les sources du moteur (choisir entre gnubg, gnubg-nn ou le moteur extrait par CBG ; justifier le choix dans `docs/decisions.md`).
+2. Définir une **interface C minimale** du moteur (`engine/include/moteur.h`), indépendante de toute interface graphique :
+   - initialiser le moteur (charger réseaux, base de fin de partie, table d'équité de match) ;
+   - lister les coups légaux pour une position et des dés ;
+   - donner le meilleur coup et le classement des coups avec leur équité, pour un niveau d'évaluation donné ;
+   - donner la décision de videau (pas de double, double/prend, double/passe, avec équités) ;
+   - évaluer une position (probabilités de gain, gammon, backgammon).
+   Les positions entrent et sortent au format **GNU Position ID + Match ID**.
+3. Écrire `engine-cli`, un petit programme qui expose ces fonctions en ligne de commande, avec une sortie JSON.
+4. Générer un jeu de **positions de référence** (au moins 30 : ouvertures, contact, course, sortie, décisions de videau) avec le GNU Backgammon de bureau dans Docker, et stocker les résultats attendus dans `tests/reference/`.
+5. `make test` compare `engine-cli` aux références (même meilleur coup, équités à une tolérance près, à fixer).
+
+**Démo** : `make engine && ./build/engine-cli bestmove <position_id> <match_id> 31` affiche le meilleur coup en JSON ; `make test` passe.
+
+---
+
+## 0b. Le test WebAssembly (décisif)
+
+**Objectif** : savoir si le moteur tourne assez vite et léger dans le navigateur du téléphone.
+
+À faire :
+1. Compiler le même moteur et la même interface C en WebAssembly avec Emscripten (dans Docker).
+2. Charger le moteur dans un **Web Worker** (jamais sur le fil d'affichage).
+3. Page HTML minimale : un champ Position ID, des dés, un bouton « meilleur coup », l'affichage du résultat et du temps de calcul.
+4. Rejouer les positions de référence dans le navigateur : les résultats doivent concorder avec 0a.
+5. `make deploy-web` sert la page sur le réseau local pour l'ouvrir depuis le Fairphone 4.
+6. `make bench` (ou une page de mesure) produit un petit rapport : temps par coup selon le niveau d'évaluation, taille téléchargée, mémoire utilisée.
+
+**Critères de réussite (à ajuster après mesure)** :
+
+| Mesure sur le Fairphone 4 | Seuil |
+| --- | --- |
+| Meilleur coup, niveau rapide (0-ply GNU) | moins de 0,3 s |
+| Meilleur coup, niveau fort (2-ply GNU) | moins de 3 s |
+| Décision de videau, niveau fort | moins de 3 s |
+| Taille totale à télécharger (wasm + données, compressé) | moins de 40 Mo |
+| Résultats identiques aux références de 0a | 100 % |
+
+**Démo** : la page ouverte sur le Fairphone donne le meilleur coup d'une position de référence, avec le temps de calcul affiché.
+
+---
+
+## 0c. Android natif (seulement si 0b échoue)
+
+**Objectif** : la même démonstration en application Android.
+
+À faire :
+1. Compiler le moteur pour arm64 avec le NDK (dans Docker), en s'appuyant sur la configuration de CBG.
+2. Application Android minimale, construite en ligne de commande (Gradle sans Android Studio, `-j2`, démon Gradle limité en mémoire).
+3. Même écran de test et mêmes mesures qu'en 0b.
+4. `make deploy` installe l'APK sur le Fairphone via adb.
+
+---
+
+## 0d. Plateau minimal et décision
+
+1. Sur le socle retenu, un **plateau minimal** : une partie complète jouable contre le moteur, coups et videau décidés par le moteur, dés tirés par l'app.
+2. Rédiger `docs/decisions.md` : socle retenu (PWA ou Android natif), mesures obtenues, raisons, risques restants.
+
+**Critère de fin de l'étape 0** : une partie complète jouée sur le Fairphone 4, moins de 2 s par coup de l'IA en niveau standard, tous les tests au vert.