Fusion de la MR !51 : conseil du maître, une ligne après chaque coup, l'explication sur demande (1d)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit was merged in pull request #51.
This commit is contained in:
Pierre MARTIN
2026-11-10 09:32:34 +01:00
co-authored by Claude Opus 5.5
35 changed files with 3123 additions and 103 deletions
@@ -128,3 +128,25 @@ ne change pas (version 1) : le résumé d'une partie gagne un champ facultatif
`match`, recalculé à chaque enregistrement, et les réglages
(`ustagammon.settings`) quatre champs (`gameKind`, `matchLength`, `level`,
`masterAdvice`) qui ont une valeur par défaut quand ils manquent.
### 2026-11-10 — Le conseil du maître rattaché au journal
Avec le conseil du maître (étape 1d), le journal d'une partie
(`GameJournal`, `app/src/domain/game/events.ts`) gagne un champ facultatif
`advice` : pour chaque décision du joueur analysée (coup, jet sans doubler,
double, prise ou refus d'un double), l'analyse du moteur à 2 plis, rangée
sous l'identifiant de l'événement de la décision
(`app/src/domain/game/advice.ts`). Ce n'est pas un événement : l'analyse
arrive après coup, d'un second moteur, et ne change pas la partie ; les
événements gardent leur version (2). Le bilan de fin de partie (1e) la
relira sans recalcul.
- Chaque conseil porte sa version (`ADVICE_VERSION`, 1). À la reprise
(`migrateJournal`), un conseil d'une autre version, ou rattaché à un
événement absent, est oublié : ce n'est qu'une analyse, qui peut être
refaite. Un journal enregistré avant l'étape 1d n'a pas de champ `advice`
et se reprend tel quel. Testé dans `app/tests/advice.test.ts`.
- Ajouter un événement, revenir en arrière ou changer de branche garde les
conseils ; un conseil reste attaché à son événement, même hors de la
branche courante.
- Le schéma IndexedDB ne change pas : le journal est enregistré tel quel.
+18
View File
@@ -112,3 +112,21 @@ Le menu, l'accueil et « Nouvelle partie » en fin de partie y mènent. « Comme
remplace cette adresse par celle de la partie (`#/`) : le retour du téléphone
ne rouvre pas l'écran. Le lien d'une position d'une partie de match porte le
Match ID du match (longueur, score, partie Crawford), écrit par le moteur.
### 2026-11-10 — Adresse de la feuille d'explication du maître
Ajoutée avec le conseil du maître (étape 1d), dans le même schéma :
| Écran | Adresse |
| --- | --- |
| Feuille d'explication du maître sur une décision de la partie en cours | `#/explication/<événement>` |
`<événement>` est l'identifiant, dans le journal de la partie en cours, de
l'événement de la décision commentée (le coup, le double, la prise…). La
ligne du maître est un lien vers cette adresse ; la feuille monte au-dessus
de la partie, comme le menu, et « Fermer » (ou le retour du téléphone)
revient à la partie. Rechargée, l'adresse rouvre la même explication : le
conseil est enregistré dans le journal (ADR 0007, amendement du
2026-11-10). Un événement sans conseil donne un message, jamais une page
cassée. L'adresse n'a de sens que sur l'appareil qui a joué la partie : ce
n'est pas un lien à partager (le lien de la position, lui, se partage).
+1 -1
View File
@@ -20,7 +20,7 @@ Repris du cadrage (modules, écrans clés, IA générative en V1) et des ADR 001
| 1a. Moteur pour l'analyse (fait) | 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 (fait) | 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 (fait) | 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, grosse erreur) 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 |
| 1d. Conseil du maître (fait) | Après chaque coup du joueur, jamais avant (ADR 0011) : appréciation du moteur (bon coup, imprécision, erreur, grosse erreur) 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 |
+1
View File
@@ -43,6 +43,7 @@ exportée. `make test` vérifie le lien dans les deux sens : chaque fiche avec
| [Camp](camp.md) | Home board |
| [Chance](chance.md) | Luck |
| [Compte de points](compte-de-points.md) | Pip count |
| [Conseil du maître](conseil-du-maitre.md) | Advice |
| [Coup](coup.md) | Move |
| [Demi-coup](demi-coup.md) | Half-move |
| [Course](course.md) | Race |
+18
View File
@@ -0,0 +1,18 @@
---
term: Conseil du maître
english: Advice
code: Advice
---
# Conseil du maître
**En bref** : après chacun de vos coups et chacune de vos décisions de videau, une ligne qui donne l'appréciation du moteur et ce que le maître aurait joué.
Le maître ne parle jamais avant votre coup : il commente ce que vous venez de
jouer, avec un mot (bon coup, imprécision, erreur, grosse erreur) choisi
d'après l'[équité](equite.md) perdue par rapport au meilleur choix (voir
[Appréciation](appreciation.md)). Toucher la ligne ouvre l'explication : votre
coup et celui du maître, joués sur le plateau, et les chiffres du
[moteur](moteur.md) si vous les demandez. Le conseil se coupe dans le menu ou
sur l'écran « Nouvelle partie ».
Voir aussi : [Appréciation](appreciation.md), [Coup](coup.md), [Videau](videau.md)
+233
View File
@@ -0,0 +1,233 @@
# Les phrases du maître
Les mots et les phrases du conseil du maître (étape 1d), en une seule source
(ADR 0008) : `make site` copie ce dossier dans le site publié
(`docs/maitre/`), l'application le lit à l'exécution
(`app/src/domain/analysis/phrases.ts`), et `make test` rend chaque gabarit
sur de vraies analyses du moteur (`app/tests/advice.test.ts`).
Texte sous licence **CC BY-SA 4.0**. Version 1, rédigée par Claude Code
d'après la charte (`docs/identite/charte/ecrans-etape-1.md`, « Les phrases du
maître »), **à relire** par la session « identité » puis par Pierre.
## Règles
- Le maître parle à la première personne et vouvoie : « J'aurais joué… »,
jamais « Vous auriez dû… ».
- Il ne cite que des faits donnés par le moteur : le coup recommandé, le rang
du coup joué, le nombre de coups possibles, les pions frappés et les points
faits (lus sur les plateaux décodés par le moteur), la décision de videau
qu'il préfère. Aucune explication stratégique.
- La ligne (le mot et la phrase) fait moins de 140 caractères ; pas de point
d'exclamation, pas d'émoji, pas de superlatif.
- Quand une section a plusieurs gabarits, ils tournent d'un coup à l'autre
(l'identifiant de l'événement choisit), pour ne pas lasser.
## Format
Une section `## clé` par emploi, suivie d'un gabarit par ligne (`- …`). Les
mots entre accolades sont remplis avec les données du moteur :
| Repère | Ce qu'il devient |
| --- | --- |
| `{best}` | le coup du maître, en notation de gnubg (« 8/5 6/5 ») |
| `{played}` | votre coup, même notation |
| `{move}` | le coup dont parle le fait (le vôtre ou celui du maître) |
| `{rank}` | le rang de votre coup dans le classement du moteur (2 ou 3 seulement) |
| `{points}` | « votre point 5 » ou « vos points 5 et 7 » |
| `{roll}` | le jet, « 3-1 » |
| `{hits}` | le nombre de pions frappés, en chiffres |
Un fait (sections `fait.…`) s'ajoute à la phrase seulement si la ligne reste
sous 140 caractères.
Tout ce qui précède la première section `## mot.…` n'est pas lu.
## mot.coup.bon
- Bon coup
## mot.videau.bon
- Bonne décision
## mot.douteux
- Imprécision
## mot.mauvais
- Erreur
## mot.tres-mauvais
- Grosse erreur
## coup.meilleur
- C'est le coup du maître.
- Exactement ce que j'aurais joué.
- Bien vu.
- C'est aussi mon choix.
## coup.seul
- C'était le seul coup possible.
## coup.proche
« Bon coup » sans être le meilleur, votre coup étant le 2e ou le 3e choix du
moteur. Le rang n'est cité qu'ici et dans coup.douteux : il mesure mal la
gravité d'une erreur (un 2e choix peut être loin du premier), et le
classement complet est dans « Voir les chiffres du moteur ».
- Tout près : j'aurais joué {best}, votre coup était le {rank}e choix.
## coup.douteux
Imprécision, votre coup étant le 2e ou le 3e choix.
- J'aurais joué {best}. Votre coup était le {rank}e choix, tout près.
## coup.loin
« Bon coup » non meilleur ou imprécision, votre coup étant au-delà du 3e
choix : le rang n'est pas cité.
- J'aurais joué {best}.
## coup.mauvais
Erreur : le rang n'est jamais cité.
- J'aurais joué {best}.
## coup.tres-mauvais
Grosse erreur : le rang n'est jamais cité.
- J'aurais joué {best}.
## fait.frappe
- {move} frappe un pion.
## fait.frappe-plusieurs
- {move} frappe {hits} pions.
## fait.point
- {move} fait {points}.
## fait.frappe-et-point
- {move} frappe un pion et fait {points}.
## fait.maitre-frappe
- Mon coup frappe un pion.
## fait.maitre-point
- Mon coup fait {points}.
## fait.joueur-frappe
- Votre coup frappe un pion, le mien non.
## videau.bon.double
- Doubler était le bon choix.
## videau.bon.pas-de-double
- Ne pas doubler était le bon choix.
## videau.bon.prendre
- Prendre était le bon choix.
## videau.bon.passer
- Passer était le bon choix.
## videau.proche.double
- Les deux choix étaient très proches. J'aurais doublé.
## videau.proche.pas-de-double
- Les deux choix étaient très proches. Je n'aurais pas doublé.
## videau.proche.prendre
- Les deux choix étaient très proches. J'aurais pris.
## videau.proche.passer
- Les deux choix étaient très proches. J'aurais passé.
## videau.autre.double
- Ici, j'aurais doublé.
## videau.autre.pas-de-double
- Ici, je n'aurais pas doublé.
## videau.autre.prendre
- Ici, j'aurais pris.
## videau.autre.passer
- Ici, j'aurais passé.
## titre.coup.meme
- C'est aussi le coup que j'aurais joué
## titre.coup.autre
- J'aurais joué {best}
## titre.videau.meme
- C'est aussi ce que j'aurais fait
## titre.videau.double
- J'aurais doublé
## titre.videau.pas-de-double
- Je n'aurais pas doublé
## titre.videau.prendre
- J'aurais pris
## titre.videau.passer
- J'aurais passé
## contexte.coup
- votre {roll}
## contexte.coup.ouverture
- votre {roll} d'ouverture
## contexte.videau.double
- votre double
## contexte.videau.pas-de-double
- avant votre jet
## contexte.videau.reponse
- le double de l'ordinateur
@@ -1,64 +0,0 @@
# Conseil du maître (1d)
- **Date** : 2026-11-03
- **Étape** : 1d (`docs/etape-1.md`)
- **Statut** : prévu (après 1c)
- **Exécutant** : sous-agent general-purpose, dans un worktree
## Objectif
Le coach bienveillant, « mis en avant mais discret » (Pierre, 2026-11-03) :
après chaque coup et chaque décision de videau du joueur, jamais avant
(ADR 0011), une appréciation et une phrase du maître fondées sur les chiffres
du moteur.
## Références
- ADR 0011 ; maquette « conseil du maître après le coup » du canevas
https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe ; règles de la charte
(`docs/identite/charte/`, dont interaction.md) ; la ligne réservée de 44 px
de la révision UX.
- Moteur : `analyseMove`, `analyseCube`, `luck`, seuils `SKILL_THRESHOLDS`
(gnubg : 0,03 / 0,06 / 0,12).
## Consignes
1. **Analyse en arrière-plan** : après la validation d'un coup (ou une
décision de videau), l'analyse à 2 plis part dans le Worker sans retarder le
tour de l'ordinateur ; son résultat est rattaché au coup dans le journal
(événement d'analyse rétrocompatible, ou cache séparé justifié) pour servir
au bilan (1e) sans recalcul.
2. **Ligne du maître** : icône d'appréciation, mot en couleur (« Bon coup. »,
« Imprécision. », « Erreur. », « Grosse erreur. » (choix de Pierre du 2026-11-09, plutôt que « gaffe ») : correspondance avec les seuils
de gnubg documentée), phrase courte en italique, chevron. Toucher ouvre la
feuille d'explication : coup joué et meilleur coup montrés sur le plateau
(pions animés, ADR 0011 « comparaison visuelle »), écart d'équité seulement
sur demande, lien vers la fiche du glossaire du concept en jeu si le moteur
permet de le déterminer, sinon rien.
3. **Phrases du maître** : gabarits versionnés en français dans une source
unique sous `docs/` (CC BY-SA 4.0). Référence de ton, approuvée par Pierre
le 2026-11-09 : la section « Les phrases du maître » de
`docs/identite/charte/ecrans-etape-1.md` (1re personne et vouvoiement,
faits du moteur uniquement, moins de 140 caractères, ton sobre sans
exclamation, formules qui tournent pour les bons coups, exemples). Un test
vérifie la longueur et l'absence de « ! » sur chaque gabarit rendu. Les
phrases livrées passent par la session « identité » puis par Pierre pour
la relecture finale.
4. **Discret** : rien n'apparaît pendant que le joueur réfléchit ; la ligne
s'efface à l'action suivante ; désactivable (réglage de 1c et menu).
5. **Videau** : même traitement pour doubler, ne pas doubler, prendre, passer.
6. Scénarios Gherkin (bon coup, erreur avec meilleur coup montré, conseil
désactivé, décision de videau commentée) avec positions et dés imposés ;
tests unitaires des gabarits (chaque gabarit rendu sur des analyses réelles
du moteur). `make lint`, `make test`, `make test-browser`, captures pour la
recette design.
## Critères de réussite
Après une erreur volontaire dans une position connue, la ligne du maître dit
« Erreur. », nomme le coup recommandé par le moteur et le montre sur demande ;
le tour de l'ordinateur n'est pas retardé ; les trois commandes passent.
## Résultat
À remplir à la clôture.
+1
View File
@@ -57,6 +57,7 @@ Règles d'écriture :
| --- | --- | --- |
| [jouer-une-partie.feature](jouer-une-partie.feature) | Jouer une partie contre l'ordinateur | Étape 0d |
| [jouer-un-match.feature](jouer-un-match.feature) | Choisir sa partie (libre ou match, niveau) et jouer un match | Étape 1c |
| [comprendre-mes-coups.feature](comprendre-mes-coups.feature) | Comprendre ses coups avec le conseil du maître | Étape 1d |
| [mes-parties.feature](mes-parties.feature) | Retrouver mes parties, leurs branches, les exporter en SGF | Étape 1b |
| [partager-une-position.feature](partager-une-position.feature) | Ouvrir et partager le lien d'une position | Étape 0e.4 |
| [regler-l-application.feature](regler-l-application.feature) | Régler l'application (menu), la mettre à jour | Étape 0e |
@@ -0,0 +1,52 @@
# language: fr
Fonctionnalité: Comprendre mes coups avec le conseil du maître
Après chacun de vos coups, et après chacune de vos décisions de videau,
le maître dit en une ligne ce qu'il en pense : « Bon coup. »,
« Imprécision. », « Erreur. » ou « Grosse erreur. », puis une phrase,
par exemple le coup qu'il aurait joué. Il ne parle jamais avant que vous
ayez joué, et la ligne s'efface dès que vous lancez les dés ou touchez un
pion. Touchez-la pour ouvrir l'explication. Le maître, c'est GNU
Backgammon : il ne dit que ce que le programme a calculé.
Scénario: Que dit le maître après un bon coup ?
« Bon coup. », avec une phrase qui change d'une fois à l'autre et, s'il
y en a, ce que votre coup fait sur le plateau : un pion frappé, un point
fait. Avec 3-1 à l'ouverture, 8/5 6/5 est le meilleur coup.
Étant donné que vous avez 3-1 à jouer à la position de départ
Quand vous validez le coup 8/5 6/5
Alors le maître dit « Bon coup. »
Et sa phrase dit que 8/5 6/5 fait votre point 5
Scénario: Comment voir le coup que le maître aurait joué ?
Après une imprécision ou une erreur, la ligne nomme le coup du maître.
Touchez-la : l'explication montre, sur le plateau, votre coup et le coup
du maître joués pion par pion depuis la même position. Les chiffres,
repliés en bas, donnent l'écart entre les coups si vous les voulez.
Étant donné que vous avez 3-1 à jouer à la position de départ
Quand vous validez le coup 24/23 13/10
Alors le maître dit « Grosse erreur. »
Et sa phrase commence par « J'aurais joué 8/5 6/5. »
Et l'explication peut montrer votre coup et le coup du maître sur le plateau
Scénario: Comment faire taire le maître ?
Coupez « Conseil du maître » dans le menu, ou sur l'écran « Nouvelle
partie ». La ligne reste alors vide, et rien d'autre ne bouge. Vos coups
restent analysés pour le bilan de fin de partie.
Étant donné que vous avez coupé le conseil du maître
Et que vous avez 3-1 à jouer à la position de départ
Quand vous validez le coup 24/23 13/10
Alors le maître ne dit rien
Scénario: Le maître commente-t-il le videau ?
Oui : après votre double, votre réponse à un double de l'ordinateur, ou
quand vous avez lancé les dés alors qu'il aurait doublé, le maître dit
si vous avez bien fait.
Étant donné que l'ordinateur vous propose de doubler dans une position où il faut prendre
Quand vous passez son double
Alors le maître dit « Erreur. »
Et sa phrase dit « Ici, j'aurais pris. »