Fusion de main dans moteur-analyse ; plan 1a clos

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/plans/2026-11-03-accueil-tutoriel-aide.md

@@ -0,0 +1,59 @@
+# Accueil, installation, tutoriel des règles, aide (0e.5)
+
+- **Date** : 2026-11-03
+- **Étape** : 0e.5 (feuille de route), qui couvre aussi le tutoriel de 1g
+- **Statut** : prévu (après la fusion de 0e.4)
+- **Exécutant** : sous-agent general-purpose, dans un worktree
+
+## Objectif
+
+Traiter les points 2 et 3 du message de Pierre du 2026-11-03 et sa demande d'installation en un toucher :
+- une page d'accueil ;
+- l'installation proposée par l'app ;
+- un tutoriel des règles très didactique, illustré par le plateau ;
+- une aide plus humaine.
+
+## Références
+
+- Règles : `docs/identite/charte/accueil-tutoriel-aide.md`. Le texte du tutoriel y figure en première version, à faire valider par Pierre.
+- Maquettes : https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe, rangée « Étape 0e.5 » et artboard « Accueil ».
+- ADR 0008 (source unique), ADR 0013 (positions par identifiants gnubg).
+
+## Consignes
+
+1. **Accueil**, selon la charte :
+   - au premier lancement, et une seule fois, le choix entre « Je découvre » et « Je connais les règles » ;
+   - ensuite : la partie en cours, la carte d'installation, la prochaine leçon et la progression résumée. La leçon et la progression restent en attente tant que 1g et 1h n'existent pas : n'afficher que ce qui existe.
+2. **Installation** :
+   - sous Chrome, garder l'invite reçue avec `beforeinstallprompt` ;
+   - sous Firefox et sur iPhone, une feuille en 3 étapes ;
+   - la carte n'apparaît qu'à partir de la première partie terminée. « Plus tard » la masque, et elle ne revient qu'une fois, après 3 parties. Le menu garde une ligne tant que l'app n'est pas installée ;
+   - plus rien en `display-mode: standalone` ni après l'événement `appinstalled`.
+3. **Tutoriel**, en 8 étapes :
+   - le texte vit dans un fichier source unique sous `docs/` (par exemple `docs/tutoriel/`), copié dans le site par `make site` comme le glossaire, sous licence CC BY-SA 4.0 ;
+   - positions données par leurs identifiants gnubg ;
+   - sur les écrans « à vous », le moteur vérifie le coup joué en le comparant aux coups attendus de l'étape ;
+   - le coup illustré se joue seul après 1 s, avec « Revoir » ;
+   - un test vérifie que chaque position du tutoriel est valide pour le moteur et que chaque coup attendu est légal ;
+   - ajouter la fiche du glossaire « camp ».
+4. **Aide**, en trois onglets :
+   - « Jouer » : les scénarios deviennent des questions repliables. Le titre est la question et la description la réponse ; les étapes Gherkin sont cachées. Reformuler les titres des `.feature` sans casser les tests ;
+   - « Les mots du jeu » : les cartes du glossaire, avec une recherche ;
+   - « À propos » : licence, crédits, version ;
+   - le tutoriel est proposé en tête de l'aide.
+5. **Scénarios Gherkin** : premier lancement, installation, suivre le tutoriel.
+6. **`make test-browser`** :
+   - premier lancement, tutoriel complet avec ses écrans « à vous », aide ;
+   - `beforeinstallprompt` simulé dans Chromium ;
+   - captures dans `build/browser-shots/accueil-tutoriel/` pour la recette design.
+
+`make lint`, `make test` et `make test-browser` doivent passer. Aucune nouvelle dépendance.
+
+## Critères de réussite
+
+- Un débutant suit le tutoriel jusqu'au bout sur le téléphone, et chaque écran « à vous » accepte le bon coup et refuse les autres.
+- Les trois commandes passent, et les captures sont livrées pour la recette.
+
+## Résultat
+
+À remplir à la clôture.

docs/plans/2026-11-03-moteur-analyse.md

@@ -1,96 +0,0 @@
-# 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
-
-Réalisé le 2026-11-03, branche `moteur-analyse`. Critères tenus : nouvelles
-commandes d'`engine-cli` en JSON, références concordantes en natif et en
-WebAssembly, `make lint` et `make test` au vert.
-
-- **Niveaux** : les neuf réglages prédéfinis de gnubg 1.08 (`aecSettings`) :
-  `beginner`, `casual`, `intermediate`, `advanced` (0 pli, bruit 0,06 / 0,05 /
-  0,04 / 0,015, déterministe), puis `0ply` à `4ply` sans bruit (anciens noms
-  gnubg : « expert » = 0 pli, « world class » = 2 plis). Coup choisi comme
-  l'ordinateur de gnubg (`ComputerTurn` : sans analyse, puis
-  `RefreshMoveList`). `engine.h` (`engine_level_*`), `engine-cli --level` et
-  `levels`, `Engine.levelMove` et `levelCubeDecision`.
-- **Analyses** : `engine_analyse_move` (comme `AnalyzeMove` : coup joué
-  évalué au niveau le plus profond, rang, perte, appréciation),
-  `engine_analyse_cube` (pas de double, double, prendre, passer ; pertes de
-  `AnalyzeMove`), `engine_luck_of` (portage de `LuckNormal` et `LuckFirst`
-  d'`analysis.c`, fichier non repris dans `engine/gnubg/`). Commandes
-  `analysemove`, `analysecube`, `luck` ; `Engine.analyseMove`, `analyseCube`,
-  `luck`.
-- **Seuils** : ceux de gnubg, `gnubg.c` : appréciation 0,03 / 0,06 / 0,12
-  (et non 0,04 / 0,08 / 0,16 comme proposé dans `docs/etape-1.md`) ; chance
-  0,3 / 0,6. Constantes dans `engine.h` et `SKILL_THRESHOLDS`,
-  `LUCK_THRESHOLDS` dans `engine.ts`, vérifiées égales par un test.
-- **Références** : `tests/reference/analyses.json` (16 coups joués, 14
-  décisions de videau, 7 cas de niveaux), résultats dans `analysis/`, produits
-  par l'analyse de partie de gnubg de bureau (« analyse game ») ; comparés par
-  `compare.py`. Écart maximal 1,64e-3 (`move-jacoby`, 2 plis), tolérance
-  inchangée (0,002).
-- **Écart au plan, décision à valider** : le moteur vide le cache
-  d'évaluation de gnubg à chaque calcul. Une recherche à 2 plis avec élagage
-  y laisse des évaluations à 0 pli des réseaux d'élagage, que les calculs à
-  0 pli suivants reprennent (même défaut dans gnubg de bureau : jusqu'à
-  2,5e-2 d'écart sur la chance). Coût : environ 3 ms par appel sur le PC.
-- **Mesure** (`make bench`, Node 18, i5-2450M) : analyse du coup joué à
-  2 plis, médiane 76 ms, maximum 451 ms (`opening-21`) ; seuil 3 s. Aussi
-  dans `bench.html` pour le téléphone.
-- **Glossaire** : Niveau de jeu (`Level`), Appréciation (`Skill`), Chance
-  (`Luck`).

docs/plans/2026-11-03-parties-enregistrees.md

@@ -0,0 +1,57 @@
+# Parties enregistrées, branches et export SGF (1b)
+
+- **Date** : 2026-11-03
+- **Étape** : 1b (`docs/etape-1.md`)
+- **Statut** : prévu (lancé après la fusion de 0e.1)
+- **Exécutant** : sous-agent general-purpose, dans un worktree
+
+## Objectif
+
+Garder toutes les parties du joueur sur le téléphone, avec leurs branches, et
+les exporter au format SGF de GNU Backgammon.
+
+## Consignes
+
+ADR 0007 (domaine pur, stockage derrière une interface), ADR 0008 (scénarios
+et glossaire). Aucune nouvelle dépendance : l'API IndexedDB du navigateur
+directement.
+
+1. **Stockage IndexedDB** derrière l'interface de `app/src/storage/` : une
+   liste de parties (identifiant, date de début et de dernière action,
+   adversaire et niveau, score, état en cours ou finie, résultat) et le
+   journal d'événements de chacune. Migration transparente de la partie
+   en cours enregistrée aujourd'hui dans `localStorage`. Si IndexedDB est
+   indisponible (navigation privée), repli sur le comportement actuel.
+2. **Branches** : le journal est déjà un arbre (événements avec parent,
+   `goBackTo`). Exposer dans le domaine la liste des branches d'une partie
+   (feuilles de l'arbre, avec le coup d'origine) et le passage de l'une à
+   l'autre. « Rejouer d'ici » depuis un coup passé crée une branche ; la
+   branche d'origine reste intacte et rechargeable. Pas d'écran d'analyse ici
+   (1e) : un accès minimal suffit pour le test (menu « Mes parties » :
+   reprendre une partie, voir ses branches).
+3. **Nouvelle partie annulable** : l'arbitrage UX (plan
+   `2026-11-03-revision-ux.md`, point 3) prévoit « Reprendre l'ancienne »
+   pendant 10 s. Fournir l'API de stockage qui le permet (reprendre une partie
+   par son identifiant) ; l'interface viendra avec la révision UX.
+4. **Export SGF** : une partie (et ses branches en variantes) au format SGF
+   de GNU Backgammon, téléchargeable depuis « Mes parties ». Vérification par
+   le gnubg de bureau de référence (Docker existant) : le fichier exporté se
+   charge sans erreur et ses positions successives sont les mêmes que celles
+   du journal, sur des parties générées par les tests.
+5. Scénarios Gherkin : reprendre une partie parmi plusieurs, rejouer d'ici
+   sans perdre l'original, exporter une partie. Fiches du glossaire pour les
+   nouveaux termes (branche, SGF…).
+
+`make lint`, `make test` et `make test-browser` passent (ajouter au test
+navigateur : deux parties enregistrées, reprise de la première après
+rechargement). Commits fréquents ; pas de push ni de MR.
+
+## Critères de réussite
+
+- Après rechargement, la liste des parties et chaque branche sont intactes.
+- Un SGF exporté se charge dans gnubg de bureau avec les mêmes positions.
+- Les trois commandes de test passent.
+
+## Résultat
+
+À remplir à la clôture.

docs/plans/2026-11-03-position-dans-l-adresse.md

@@ -0,0 +1,39 @@
+# Position dans l'adresse (0e.4)
+
+- **Date** : 2026-11-03
+- **Étape** : 0e.4 (feuille de route)
+- **Statut** : prévu (après la fusion de la révision UX, qui touche les mêmes fichiers)
+- **Exécutant** : sous-agent general-purpose, dans un worktree
+
+## Objectif
+
+Appliquer l'ADR 0013 : chaque position du plateau a un lien direct.
+
+## Consignes
+
+ADR 0007, 0008 et 0013. Aucune nouvelle dépendance.
+
+1. Lecture du fragment `#position=…&match=…` au chargement et sur
+   `hashchange` ; validation par le moteur ; message clair si illisible.
+2. Vue de la position, non jouable, avec « Jouer à partir d'ici » (nouvelle
+   partie depuis la position, la partie en cours restant reprenable) et
+   « Retour à ma partie ».
+3. Domaine : démarrer une partie depuis une position et un Match ID donnés
+   (événement GameStarted étendu de façon rétrocompatible, ou équivalent
+   justifié), sans règle réimplémentée.
+4. « Copier le lien de la position » depuis le menu de la partie et depuis la
+   vue du coup de l'ordinateur ; le lien copié rouvre exactement la même
+   position (test aller-retour).
+5. Scénarios Gherkin (« Ouvrir un lien vers une position », « Partager la
+   position »), fiches du glossaire (Position ID, Match ID si absentes).
+6. `make lint`, `make test`, `make test-browser` (ouvrir un lien, jouer à
+   partir d'ici, revenir, lien invalide).
+
+## Critères de réussite
+
+Un lien copié depuis l'app, ouvert dans un nouvel onglet, montre la même
+position ; les trois commandes passent.
+
+## Résultat
+
+À remplir à la clôture.

docs/plans/2026-11-03-revision-ux.md

@@ -2,7 +2,7 @@
 
 - **Date** : 2026-11-03
 - **Étape** : 0e.3 (feuille de route)
-- **Statut** : prévu (après la fusion de 0e.1, qui touche les mêmes fichiers)
+- **Statut** : prévu
 - **Exécutant** : sous-agent general-purpose, dans un worktree
 
 ## Objectif

docs/plans/2026-11-03-saisie-du-coup.md

@@ -1,65 +0,0 @@
-# Saisie du coup, videau confirmé, pages de test du moteur retirées
-
-- **Date** : 2026-11-03
-- **Étape** : 0e (retours du premier test de Pierre sur le téléphone)
-- **Statut** : en cours
-- **Exécutant** : sous-agent general-purpose, dans un worktree
-
-## Objectif
-
-Rendre la saisie du coup aussi confortable que dans CBG, d'après les retours de
-Pierre du 2026-11-03 (points 1, 6, 7, 8, 9 et 11 de son message), et retirer du
-site les pages de test du moteur.
-
-## Consignes
-
-Règles de code : ADR 0007 (domaine pur, aucune règle de backgammon
-réimplémentée : tout vient du moteur via le domaine). Glossaire et scénarios :
-ADR 0008 (chaque comportement visible a son scénario Gherkin dans
-`docs/scenarios/`, chaque nouveau terme sa fiche). Aucune nouvelle dépendance.
-
-1. **Pages de test du moteur retirées** (« supprimer la partie test du moteur
-   totalement ») : plus de `/moteur/` sur le site ni dans `make deploy`.
-   `make bench` (mesure sous Node) reste : déplacer ce dont il a besoin hors de
-   `web/`. Mettre à jour `tests/test_site.sh`, le Makefile, `deploy/`, le
-   service worker, `docs/guide-test-etape-0.md` et ajouter un amendement daté à
-   l'ADR 0009.
-2. **Un seul coup possible, le pion avance** : quand le joueur touche un pion
-   (ou une case) et qu'une seule case d'arrivée est possible pour ce pion, le
-   demi-coup est joué aussitôt, sans second toucher. S'il y en a plusieurs, la
-   sélection actuelle reste.
-3. **Coup à valider, annulable** : quand tous les demi-coups sont joués (ou
-   qu'aucun autre n'est possible), le coup n'est pas envoyé tout de suite. Le
-   joueur le valide en touchant ses dés (ou un bouton « Valider »). Tant qu'il
-   ne l'a pas validé, « Annuler » défait le dernier demi-coup, un par un. Le
-   journal d'événements ne reçoit `MovePlayed` qu'à la validation.
-4. **Dés joués marqués** : chaque dé déjà utilisé par un demi-coup est
-   visiblement estompé. Pour un double, quatre dés, marqués un par un.
-5. **Dés de l'adversaire touchables** : toucher la zone des dés de l'un ou
-   l'autre côté du plateau lance les dés quand le joueur peut lancer (et valide
-   le coup en attente de validation).
-6. **Confirmation du videau** : toucher le videau ou « Doubler » ouvre une
-   confirmation courte (« Doubler à 2 ? L'ordinateur pourra prendre ou
-   passer. » : Doubler / Annuler) avant d'envoyer le double.
-
-Tests : scénarios Gherkin mis à jour ou ajoutés (validation du coup, annulation
-demi-coup par demi-coup, confirmation du videau), tests unitaires, et
-`tests/browser/play.mjs` adapté (Playwright est validé par Pierre). Lancer
-`make lint`, `make test` et `make test-browser`.
-
-Rapporter : ce qui a été fait, les écarts, les résultats des trois commandes,
-et un brouillon de description de MR (7 sections, voir `docs/organisation.md`).
-Commits fréquents sur la branche du worktree ; ne pas pousser, ne pas ouvrir de
-MR : la session principale s'en charge.
-
-## Critères de réussite
-
-- `make lint`, `make test` et `make test-browser` passent.
-- Dans le navigateur : un pion à destination unique avance en un toucher ; un
-  coup complet attend la validation ; « Annuler » défait un demi-coup à la
-  fois ; les dés joués sont estompés ; le videau demande confirmation.
-- `https://…/moteur/` n'existe plus dans le site construit (`make site`).
-
-## Résultat
-
-À remplir à la clôture.