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>

docs/adr/0008-glossaire-et-scenarios-source-unique.md

@@ -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.

docs/adr/README.md

@@ -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é |