ADR 0008 : glossaire et scénarios, source unique pour le code, l'aide et les tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 13:45:34 +01:00
parent 463bc6f553
commit 77ca5a60ca
36 changed files with 518 additions and 1 deletions
@@ -0,0 +1,82 @@
+# 0008. Glossaire et scénarios : une source unique pour le code, l'aide et les tests
+
+- **Statut** : accepté
+- **Date** : 2026-11-02
+- **Décideurs** : Pierre, sur proposition de Claude Code pour le format
+
+## Contexte
+
+Le code est en anglais (ADR 0007), l'interface et la documentation en
+français. Il faut un lien explicite entre les deux langues pour que le code
+reste compréhensible et que les mots du jeu soient les mêmes partout. Le
+cadrage prévoit aussi un glossaire dans l'application (« chaque terme technique
+est touchable »).
+
+Pierre veut une documentation utilisateur fondée sur des cas d'usage réels,
+orientée tâches, versionnée avec le code, consultable dans l'application, et
+utilisable comme base des tests de bout en bout. Il impose une seule source de
+vérité : aucune documentation dupliquée.
+
+## Décision
+
+**Glossaire : `docs/glossaire/`, un fichier par terme.**
+
+- Chaque fichier (`videau.md`, `equite.md`…) commence par un en-tête qui donne
+  le terme français, sa traduction anglaise (le nom utilisé dans le code) et, le
+  cas échéant, le type du domaine qui l'implémente :
+
+  ```
+  ---
+  term: Videau
+  english: Cube
+  code: Cube
+  ---
+  ```
+
+- Puis un titre, une ligne « **En bref** : » (une phrase, celle que l'app
+  affiche quand on touche le terme), et des détails facultatifs.
+- Dans le code, chaque type du domaine qui correspond à un terme porte en
+  commentaire le chemin de sa fiche (`Glossaire : docs/glossaire/videau.md`).
+- Des tests vérifient la forme des fiches, l'unicité des traductions anglaises,
+  l'index, et, dès que le domaine existe, le lien dans les deux sens : chaque
+  `code:` désigne un type existant, chaque référence du code désigne une fiche
+  existante.
+
+**Documentation utilisateur : `docs/scenarios/`, des scénarios métier.**
+
+- Un fichier par tâche réelle de l'utilisateur (« Jouer une partie contre
+  l'ordinateur », « Comprendre mon erreur »…), écrit pour un joueur, en
+  français, à la deuxième personne, avec des étapes concrètes.
+- Le format est du Markdown avec Gherkin (fichiers `.feature.md`, pris en
+  charge par Cucumber) : le même fichier se lit comme une page d'aide et
+  s'exécute comme test de bout en bout. Les étapes s'écrivent en français
+  (« Étant donné », « Quand », « Alors »).
+- L'outil qui exécute ces scénarios est choisi avec le socle (PWA ou Android).
+  D'ici là, les scénarios sont déroulés à la main et servent de guide de test.
+
+**Une seule source.** L'application n'a pas sa propre copie de l'aide ni du
+glossaire : le build les copie depuis `docs/glossaire/` et `docs/scenarios/`
+vers les ressources de l'application. Ces copies ne sont jamais commitées. La
+documentation affichée est donc toujours celle de la version installée.
+
+## Alternatives écartées
+
+- **Un seul fichier de glossaire** : plus difficile à lier depuis le code et
+  depuis l'application (une fiche = un lien), et des conflits de fusion
+  fréquents.
+- **Documentation utilisateur rédigée à part des tests** : deux textes qui
+  divergent tôt ou tard.
+- **Gherkin classique (`.feature`)** : exécutable, mais austère comme page
+  d'aide. Le Markdown avec Gherkin donne les deux.
+- **Aide intégrée en dur dans l'application** : une seconde source à
+  maintenir.
+
+## Conséquences
+
+- Les textes du glossaire et des scénarios sont des contenus pédagogiques, sous
+  CC BY-SA 4.0. Leur ton relève de Pierre : les fiches rédigées par Claude Code
+  sont marquées « à relire » jusqu'à sa relecture.
+- Tout nouveau type du domaine qui correspond à un mot du jeu demande sa fiche
+  de glossaire dans la même merge request.
+- Toute fonction visible par l'utilisateur demande son scénario dans la même
+  merge request.
@@ -13,3 +13,4 @@ passe au statut « remplacé par NNNN ». Voir l'ADR 0001.
 | [0005](0005-moteur-gnubg-officiel.md) | Source du moteur : GNU Backgammon officiel, commit 14b6798 | accepté |
 | [0006](0006-merge-requests-systematiques.md) | Merge requests systématiques, fusionnées par Claude Code | accepté |
 | [0007](0007-architecture-et-conventions-de-code.md) | Architecture et conventions de code | accepté |
+| [0008](0008-glossaire-et-scenarios-source-unique.md) | Glossaire et scénarios : une source unique pour le code, l'aide et les tests | accepté |
@@ -21,7 +21,7 @@ Acquis : socle du dépôt, organisation (ADR 0001, 0003, 0006), source du moteur
 | Mesures | Pierre relève les mesures sur le Fairphone 4 | ⏳ | |
 | Décision | Socle PWA ou Android natif, consigné dans un ADR — validation de Pierre | ⏳ | |
 | 0c | Android natif (NDK, Gradle en ligne de commande, `make deploy` via adb) | ⏸ si 0b échoue | |
-| 0d | Plateau minimal jouable sur le socle retenu | ⏳ | |
+| 0d | Plateau minimal jouable sur le socle retenu ; vérifié avec Pierre en suivant `docs/scenarios/jouer-une-partie.feature.md` | ⏳ | |

 **Critère de fin** : 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.
@@ -0,0 +1,60 @@
+# Glossaire
+
+Les mots du jeu, une fiche par terme, avec leur traduction anglaise utilisée
+dans le code (ADR 0008). Ces fiches sont la seule source : l'application les
+affiche telles quelles quand on touche un terme.
+
+Fiches rédigées par Claude Code, **à relire** par Pierre (contenu pédagogique,
+CC BY-SA 4.0).
+
+## Format d'une fiche
+
+```
+---
+term: Videau
+english: Cube
+code: Cube
+---
+# Videau
+
+**En bref** : une phrase, celle qu'affiche l'application.
+
+Détails facultatifs.
+
+Voir aussi : [Doubler](doubler.md)
+```
+
+`code` est facultatif : il désigne le type du domaine qui implémente le terme,
+dès qu'il existe. Dans le code, ce type porte en commentaire le chemin de sa
+fiche (`Glossaire : docs/glossaire/videau.md`).
+
+## Termes
+
+| Terme | Anglais (code) |
+| --- | --- |
+| [Backgammon](backgammon.md) | Backgammon |
+| [Barre](barre.md) | Bar |
+| [Blot](blot.md) | Blot |
+| [Branche](branche.md) | Branch |
+| [Compte de points](compte-de-points.md) | Pip count |
+| [Coup](coup.md) | Move |
+| [Course](course.md) | Race |
+| [Doubler](doubler.md) | Double |
+| [Équité](equite.md) | Equity |
+| [Événement de partie](evenement-de-partie.md) | Game event |
+| [Gammon](gammon.md) | Gammon |
+| [Identifiant de match](identifiant-de-match.md) | Match ID |
+| [Identifiant de position](identifiant-de-position.md) | Position ID |
+| [Jet](jet.md) | Roll |
+| [Match](match.md) | Match |
+| [Moteur](moteur.md) | Engine |
+| [Partie](partie.md) | Game |
+| [Passer](passer.md) | Drop |
+| [Pion](pion.md) | Checker |
+| [Pli](pli.md) | Ply |
+| [Point](point.md) | Point |
+| [Prendre](prendre.md) | Take |
+| [Règle de Crawford](regle-de-crawford.md) | Crawford rule |
+| [Règle de Jacoby](regle-de-jacoby.md) | Jacoby rule |
+| [Sortie](sortie.md) | Bear-off |
+| [Videau](videau.md) | Cube |
@@ -0,0 +1,9 @@
+---
+term: Backgammon
+english: Backgammon
+---
+# Backgammon
+
+**En bref** : victoire triple : l'adversaire n'a sorti aucun pion et en a encore sur la barre ou dans votre dernier quart du plateau.
+
+Voir aussi : [Gammon](gammon.md)
@@ -0,0 +1,9 @@
+---
+term: Barre
+english: Bar
+---
+# Barre
+
+**En bref** : bande centrale du plateau où vont les pions frappés ; un joueur doit y faire rentrer ses pions avant de jouer les autres.
+
+Voir aussi : [Blot](blot.md)
@@ -0,0 +1,9 @@
+---
+term: Blot
+english: Blot
+---
+# Blot
+
+**En bref** : pion seul sur un point : l'adversaire peut le frapper et l'envoyer sur la barre.
+
+Voir aussi : [Point](point.md), [Barre](barre.md)
@@ -0,0 +1,9 @@
+---
+term: Branche
+english: Branch
+---
+# Branche
+
+**En bref** : suite de coups rejouée à partir d'un moment d'une partie (« Rejouer d'ici ») ; la partie d'origine reste intacte.
+
+Voir aussi : [Événement de partie](evenement-de-partie.md)
@@ -0,0 +1,9 @@
+---
+term: Compte de points
+english: Pip count
+---
+# Compte de points
+
+**En bref** : nombre total de cases que vos pions doivent encore parcourir pour tous sortir ; le plus petit compte est en avance dans la course.
+
+Voir aussi : [Course](course.md)
@@ -0,0 +1,9 @@
+---
+term: Coup
+english: Move
+---
+# Coup
+
+**En bref** : le déplacement complet des pions pour un jet, noté par exemple 8/5 6/5 : un pion de la case 8 à la case 5, un autre de la case 6 à la case 5.
+
+Voir aussi : [Jet](jet.md)
@@ -0,0 +1,9 @@
+---
+term: Course
+english: Race
+---
+# Course
+
+**En bref** : position où les pions des deux joueurs se sont croisés : plus aucun contact n'est possible, c'est au plus rapide.
+
+Voir aussi : [Compte de points](compte-de-points.md), [Sortie](sortie.md)
@@ -0,0 +1,9 @@
+---
+term: Doubler
+english: Double
+---
+# Doubler
+
+**En bref** : proposer à l'adversaire, avant de lancer les dés, de doubler la valeur de la partie ; il peut prendre ou passer.
+
+Voir aussi : [Videau](videau.md)
@@ -0,0 +1,9 @@
+---
+term: Équité
+english: Equity
+---
+# Équité
+
+**En bref** : ce que vaut une position selon le moteur, en points gagnés ou perdus en moyenne : +1 pour une victoire simple assurée, −1 pour une défaite simple assurée.
+
+Voir aussi : [Moteur](moteur.md), [Pli](pli.md)
@@ -0,0 +1,9 @@
+---
+term: Événement de partie
+english: Game event
+---
+# Événement de partie
+
+**En bref** : ce qui s'est passé à un moment de la partie : un jet, un coup, un double… ; une partie est la suite de ses événements.
+
+Voir aussi : [Branche](branche.md), [Partie](partie.md)
@@ -0,0 +1,9 @@
+---
+term: Gammon
+english: Gammon
+---
+# Gammon
+
+**En bref** : victoire double : l'adversaire n'a sorti aucun pion quand vous avez sorti tous les vôtres.
+
+Voir aussi : [Backgammon](backgammon.md)
@@ -0,0 +1,9 @@
+---
+term: Identifiant de match
+english: Match ID
+---
+# Identifiant de match
+
+**En bref** : code de 12 caractères qui décrit le reste de l'état du jeu : score, videau, joueur au trait, dés ; c'est le format de GNU Backgammon.
+
+Voir aussi : [Identifiant de position](identifiant-de-position.md)
@@ -0,0 +1,9 @@
+---
+term: Identifiant de position
+english: Position ID
+---
+# Identifiant de position
+
+**En bref** : code de 14 caractères, par exemple 4HPwATDgc/ABMA, qui décrit la place de tous les pions ; c'est le format de GNU Backgammon.
+
+Voir aussi : [Identifiant de match](identifiant-de-match.md)
@@ -0,0 +1,9 @@
+---
+term: Jet
+english: Roll
+---
+# Jet
+
+**En bref** : le lancer des deux dés ; un double (deux dés identiques) se joue quatre fois.
+
+Voir aussi : [Coup](coup.md)
@@ -0,0 +1,9 @@
+---
+term: Match
+english: Match
+---
+# Match
+
+**En bref** : suite de parties jouée jusqu'à ce qu'un joueur atteigne un nombre de points fixé à l'avance, par exemple 5 points.
+
+Voir aussi : [Partie](partie.md), [Règle de Crawford](regle-de-crawford.md)
@@ -0,0 +1,9 @@
+---
+term: Moteur
+english: Engine
+---
+# Moteur
+
+**En bref** : GNU Backgammon, le programme qui calcule les coups, le videau et les évaluations ; Ustagammon ne décide jamais rien sans lui.
+
+Voir aussi : [Équité](equite.md), [Pli](pli.md)
@@ -0,0 +1,9 @@
+---
+term: Partie
+english: Game
+---
+# Partie
+
+**En bref** : une partie se joue jusqu'à ce qu'un joueur ait sorti tous ses pions ; elle rapporte 1, 2 ou 3 points, multipliés par la valeur du videau.
+
+Voir aussi : [Match](match.md), [Gammon](gammon.md), [Videau](videau.md)
@@ -0,0 +1,9 @@
+---
+term: Passer
+english: Drop
+---
+# Passer
+
+**En bref** : refuser un double : vous abandonnez la partie et perdez sa valeur d'avant le double.
+
+Voir aussi : [Prendre](prendre.md), [Videau](videau.md)
@@ -0,0 +1,7 @@
+---
+term: Pion
+english: Checker
+---
+# Pion
+
+**En bref** : chacun des 15 jetons d'un joueur.
@@ -0,0 +1,9 @@
+---
+term: Pli
+english: Ply
+---
+# Pli
+
+**En bref** : profondeur de calcul du moteur : à 0 pli il juge la position telle quelle, à 2 plis il examine aussi les jets suivants des deux joueurs ; plus de plis, c'est plus fort et plus lent.
+
+Voir aussi : [Moteur](moteur.md)
@@ -0,0 +1,9 @@
+---
+term: Point
+english: Point
+---
+# Point
+
+**En bref** : chacune des 24 flèches du plateau ; un point est « fait » quand au moins deux de vos pions l'occupent, et l'adversaire ne peut plus s'y poser.
+
+Voir aussi : [Blot](blot.md)
@@ -0,0 +1,9 @@
+---
+term: Prendre
+english: Take
+---
+# Prendre
+
+**En bref** : accepter un double : la partie continue à valeur doublée, et vous possédez le videau, vous seul pourrez redoubler.
+
+Voir aussi : [Passer](passer.md), [Videau](videau.md)
@@ -0,0 +1,9 @@
+---
+term: Règle de Crawford
+english: Crawford rule
+---
+# Règle de Crawford
+
+**En bref** : en match, dans la partie qui suit le moment où un joueur arrive à un point de la victoire, personne ne peut doubler.
+
+Voir aussi : [Match](match.md), [Doubler](doubler.md)
@@ -0,0 +1,9 @@
+---
+term: Règle de Jacoby
+english: Jacoby rule
+---
+# Règle de Jacoby
+
+**En bref** : en partie libre, hors match, un gammon ou un backgammon ne compte que si le videau a été utilisé.
+
+Voir aussi : [Gammon](gammon.md), [Videau](videau.md)
@@ -0,0 +1,9 @@
+---
+term: Sortie
+english: Bear-off
+---
+# Sortie
+
+**En bref** : dernière phase : quand tous ses pions sont dans son dernier quart du plateau, un joueur peut les retirer du jeu ; le premier à tout sortir gagne.
+
+Voir aussi : [Course](course.md)
@@ -0,0 +1,9 @@
+---
+term: Videau
+english: Cube
+---
+# Videau
+
+**En bref** : le dé à doubler, marqué 2, 4, 8, 16, 32 et 64 : il indique la valeur actuelle de la partie.
+
+Voir aussi : [Doubler](doubler.md), [Prendre](prendre.md), [Passer](passer.md)
@@ -29,6 +29,8 @@ Deux familles de documents, de durée de vie différente (ADR 0001).
 | `docs/cadrage.md` | Vision, périmètre, architecture cible | Quand Pierre change le cadrage |
 | `docs/adr/` | Un ADR par décision structurante ; index dans `docs/adr/README.md` | À chaque décision ; jamais réécrit une fois accepté |
 | `docs/journal.md` | Une entrée datée par session : fait, décidé, suite | En fin de session |
+| `docs/glossaire/` | Une fiche par terme du jeu, avec sa traduction anglaise utilisée dans le code (ADR 0008) | Avec chaque nouveau terme du domaine |
+| `docs/scenarios/` | Documentation utilisateur en scénarios, aussi tests de bout en bout (ADR 0008) | Avec chaque fonction visible |
 | Merge requests (git.sans.pub) | Le détail de chaque changement : pourquoi, comment, vérification | À chaque changement |

 **Temporaires** : ils décrivent le travail à faire et disparaissent une fois
@@ -0,0 +1,30 @@
+# Scénarios d'utilisation
+
+La documentation utilisateur d'Ustagammon : un fichier par tâche réelle d'un
+joueur, écrit pour lui. Ces fichiers sont la seule source (ADR 0008) :
+l'application les affiche comme pages d'aide, et ils servent de tests de bout
+en bout.
+
+Tant que l'outil d'exécution n'est pas choisi (avec le socle, fin de
+l'étape 0), les scénarios se déroulent à la main : ils servent alors de guide
+de test.
+
+## Format
+
+Markdown avec Gherkin (`.feature.md`), étapes en français :
+
+- `# Fonctionnalité : <la tâche>`, puis un court paragraphe qui explique à quoi
+  elle sert, pour le joueur ;
+- `## Scénario : <un cas précis>` ;
+- des étapes en liste : `* Étant donné …`, `* Quand …`, `* Et …`, `* Alors …`.
+
+Règles d'écriture : la deuxième personne (« vous »), les mots du glossaire
+(`docs/glossaire/`), des étapes que le joueur peut faire et vérifier lui-même,
+pas de détail technique. La syntaxe exacte sera validée avec l'outil
+d'exécution.
+
+## Scénarios
+
+| Fichier | Tâche | Depuis |
+| --- | --- | --- |
+| [jouer-une-partie.feature.md](jouer-une-partie.feature.md) | Jouer une partie contre l'ordinateur | Étape 0d |
@@ -0,0 +1,48 @@
+# Fonctionnalité : Jouer une partie contre l'ordinateur
+
+Vous jouez une partie complète contre l'ordinateur, qui s'appuie sur le moteur
+GNU Backgammon. L'application tire les dés, vous propose uniquement des coups
+permis par les règles, et l'ordinateur joue et décide du videau tout seul.
+
+## Scénario : Commencer une partie
+
+* Étant donné que vous avez ouvert Ustagammon
+* Quand vous touchez « Nouvelle partie »
+* Alors le plateau s'affiche avec les pions en position de départ
+* Et le premier jet de dés désigne qui commence
+
+## Scénario : Jouer votre coup
+
+* Étant donné que c'est à vous de jouer et que les dés sont tirés
+* Quand vous touchez un pion puis la case où vous voulez l'amener
+* Alors le pion s'y déplace si ce déplacement est permis par les dés
+* Et un déplacement interdit est refusé sans changer le plateau
+* Quand vous avez utilisé vos dés
+* Alors votre coup est validé et c'est au tour de l'ordinateur
+
+## Scénario : L'ordinateur joue
+
+* Étant donné que c'est au tour de l'ordinateur
+* Quand ses dés sont tirés
+* Alors il joue son coup en moins de 2 secondes
+* Et son coup s'affiche sur le plateau
+
+## Scénario : Prendre le double de l'ordinateur
+
+* Étant donné que l'ordinateur vous propose de doubler
+* Quand vous touchez « Prendre »
+* Alors la partie continue à valeur doublée
+* Et le videau passe de votre côté : vous seul pourrez redoubler
+
+## Scénario : Passer le double de l'ordinateur
+
+* Étant donné que l'ordinateur vous propose de doubler
+* Quand vous touchez « Passer »
+* Alors la partie s'arrête
+* Et vous perdez la partie à sa valeur d'avant le double
+
+## Scénario : Finir la partie
+
+* Étant donné qu'un joueur a sorti tous ses pions
+* Alors la partie s'arrête
+* Et le résultat indique le gagnant et les points gagnés : simple, gammon ou backgammon, multipliés par le videau