diff --git a/docs/etape-1.md b/docs/etape-1.md new file mode 100644 index 0000000..bb1a23c --- /dev/null +++ b/docs/etape-1.md @@ -0,0 +1,47 @@ +# Étape 1 — V1 « Jouer et comprendre » + +Document temporaire : il décrit l'étape en cours et sera supprimé à sa clôture, +après report de ce qui est durable dans les ADR et le journal. + +**Critère de fin** (cadrage) : un débutant apprend et joue seul ; un joueur de +club comprend ses erreurs. Livré avec un plan de test (`docs/guide-test-etape-1.md`) +que Pierre déroule sur le Fairphone 4. + +**Préalable** : les sous-étapes 0e (retours du premier test) de la feuille de +route, dont la revue UX validée par Pierre. + +## Périmètre + +Repris du cadrage (modules, écrans clés, IA générative en V1) et des ADR 0010, +0011 et 0012. Ce qui n'y figure pas est hors de l'étape 1. + +| Sous-étape | Contenu | Dépend de | +| --- | --- | --- | +| 1a. Moteur pour l'analyse | Niveaux de jeu (plis et bruit de GNU Backgammon : débutant à expert), classement des coups d'un jet avec équités, analyse d'un coup joué et d'une décision de videau, chance d'un jet ; exposés par `engine.h`, `engine-cli` et le Worker, avec positions de référence comparées à gnubg de bureau | — | +| 1b. Parties enregistrées | Stockage IndexedDB derrière l'interface de stockage existante : plusieurs parties, reprise automatique, branches (« Rejouer d'ici » crée une branche, l'originale reste intacte et rechargeable), export SGF avec variantes | — | +| 1c. Match et réglages | Partie libre ou match en N points, règle Crawford, règle Jacoby, choix du niveau de l'ordinateur, conseil du maître activable ou non ; écran de nouvelle partie | 1a, 1b | +| 1d. Conseil du maître | Après chaque coup du joueur, jamais avant (ADR 0011) : appréciation du moteur (bon coup, imprécision, erreur, gaffe) avec mot, icône et couleur, phrase du maître fondée sur les chiffres du moteur, coup recommandé montré sur demande ; aussi pour les décisions de videau ; calcul en arrière-plan sans retarder le jeu | 1a | +| 1e. Fin de partie et analyse | Bilan (ADR 0011) : résultat, coups par appréciation, taux d'erreur comparé à la chance, « le coup à revoir » ; écran d'analyse : graphe d'équité (toucher un point ouvre la position), liste des erreurs filtrable, visualiseur pas à pas coup joué contre meilleur coup, « Rejouer d'ici » | 1a, 1b, 1d | +| 1f. Prompts à copier | Gabarits versionnés et testés (`docs/prompts/` ou équivalent, source unique), bouton « Demander à une IA » sur le plateau, le conseil du maître, l'analyse et la fin de partie ; le moteur décide, l'IA explique | 1d, 1e | +| 1g. Accueil, tutoriel et leçons | Accueil (reprendre, nouvelle partie, prochaine leçon, progression résumée), tutoriel des règles interactif et illustré (0e.5), cinq premières leçons numérotées (ADR 0011) avec positions et « à vous de jouer », progression locale ; contenus CC BY-SA 4.0 en brouillon, à relire par un joueur fort | 0e.5, 1a | +| 1h. Progression | Historique des parties et courbe du taux d'erreur | 1b, 1e | +| 1i. Plateau soigné | Dessin du plateau aligné sur la charte (`docs/identite/charte/board.js`), animations des pions, glisser-déposer en plus du toucher, double toucher pour le seul coup évident | 0e.3 | +| 1j. Plan de test | `docs/guide-test-etape-1.md` : parcours du débutant et du joueur de club sur le téléphone, avec ce qu'il faut rapporter | toutes | + +## Questions pour Pierre (ne bloquent pas le démarrage) + +- **Indice** : le cadrage le liste dans le module Jeu, l'ADR 0011 l'a laissé + « à concevoir séparément ». Il n'est pas dans l'étape 1 sans décision. +- **Questionnaire de premier lancement** (choix du parcours) : le parcours 1 + seul existe en V1 ; proposé : un simple choix « Je découvre » / « Je connais + les règles » qui oriente vers le tutoriel ou la partie. +- **Seuils des appréciations** : proposés d'après ceux de GNU Backgammon + (douteux 0,04, mauvais 0,08, très mauvais 0,16 d'équité), à calibrer. +- **Relecture des leçons** par un joueur fort de l'Atelier du Huit. + +## Ordre de réalisation + +1a et 1b d'abord (fondations, sans conflit avec l'interface), en parallèle des +sous-étapes 0e. Puis 1c, 1d, 1e, 1f dans cet ordre ; 1g après la validation des +maquettes d'accueil et de tutoriel par Pierre ; 1h et 1i ; 1j en dernier. Chaque +sous-étape a son plan dans `docs/plans/` et sa merge request. diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index 9d96506..a3d5495 100644 --- a/docs/feuille-de-route.md +++ b/docs/feuille-de-route.md @@ -33,7 +33,7 @@ Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1. | Étape | Contenu | État | | --- | --- | --- | -| 1. V1 Jouer et comprendre | Charte graphique appliquée à la PWA (ADR 0010, `docs/identite/charte/`), plateau soigné, niveaux, conseil du maître après le coup, bilan de fin de partie, premières leçons numérotées (ADR 0011), mode immersif en paysage (ADR 0012), analyse, branches, tutoriel, prompts, sauvegarde | ⏳ | +| 1. V1 Jouer et comprendre | Détail et ordre dans `docs/etape-1.md` : moteur pour l'analyse, parties enregistrées et branches, match et réglages, conseil du maître, fin de partie et analyse, prompts, accueil, tutoriel et leçons, progression, plateau soigné, plan de test | 🔄 | | 2. V1.5 Apprendre | Parcours 2, exercices, progression | ⏳ | | 3. V2 Perfectionnement et IA | Parcours 3 et 4, rollouts, révision espacée | ⏳ | diff --git a/docs/journal.md b/docs/journal.md index 02f0d9f..0b6c5db 100644 --- a/docs/journal.md +++ b/docs/journal.md @@ -128,10 +128,11 @@ Une entrée datée par session : ce qui a été fait, décidé, et la suite. la session technique implémente. Numéros des flèches à 12 px minimum. - Décision de Pierre : la vue paysage « plateau = écran » s'applique dès la rotation du téléphone, sans plein écran (amendement de l'ADR 0012). +- Mode avion vérifié par Pierre sur le téléphone : l'application fonctionne + hors ligne. +- Étape 1 découpée dans `docs/etape-1.md` (sous-étapes 1a à 1j). - Nouvel objectif fixé par Pierre : traiter les retours 0e (les siens et ceux du designer), puis réaliser l'étape 1, livrée avec un plan de test. **Reste à faire** -- Le test en mode avion sur le téléphone n'a pas été rapporté ; le hors ligne - est vérifié dans Chromium par `make test-browser`. - Firefox sur le téléphone reste à mesurer. diff --git a/docs/plans/2026-11-03-moteur-analyse.md b/docs/plans/2026-11-03-moteur-analyse.md new file mode 100644 index 0000000..6e64ee6 --- /dev/null +++ b/docs/plans/2026-11-03-moteur-analyse.md @@ -0,0 +1,60 @@ +# 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.