diff --git a/CLAUDE.md b/CLAUDE.md index 18f1c71..436eeac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,7 +51,7 @@ Des cibles plus fines (`make engine`, `make engine-wasm`, `make bench`…) sont 2. **Tests d'abord pour le moteur.** Les positions de référence sont évaluées avec le GNU Backgammon de bureau (en ligne de commande, dans Docker) et stockées dans `tests/reference/`. Le moteur embarqué doit concorder. 3. **Expliquer simplement.** Après chaque étape : ce qui a été fait, comment le vérifier soi-même (commande exacte), ce qui reste. 4. **Ne jamais masquer un échec.** Pas de test désactivé, pas de résultat simulé. Dire clairement ce qui bloque et la cause probable. -5. **Commits fréquents**, messages courts en français. Ne jamais pousser sur le dépôt distant sans demande explicite. +5. **Commits fréquents**, messages courts en français, sur une branche dédiée. Jamais de commit direct sur `main` : chaque changement passe par une merge request Gitea (`tea pulls create --login sans-pub`), décrite selon `docs/organisation.md`. Claude Code la fusionne lui-même une fois `make lint` et `make test` au vert. 6. **Dépendances** : peu, maintenues, compatibles GPLv3. Signaler chaque nouvelle dépendance et sa licence. 7. **Journal** : `docs/journal.md` reçoit une entrée datée à la fin de chaque session (fait, décidé, reste à faire). Les décisions structurantes vont dans `docs/decisions.md`. diff --git a/docs/decisions.md b/docs/decisions.md index 7e62779..b86e953 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -27,3 +27,36 @@ devient `docs/feuille-de-route.md`. Chaque délégation a son plan dans `docs/plans/`. Fonctionnement détaillé dans `docs/organisation.md`. **Raison** : rendre le suivi et la mémoire du projet transparents et vérifiables a posteriori, en lisant le dépôt. + +## 2026-11-02 — Source du moteur : gnubg officiel, commit `14b6798` + +**Contexte** : étape 0a.1, trois candidats étudiés (gnubg, gnubg-nn, CBG). +Étude complète : `docs/plans/2026-11-02-choix-source-moteur.md`. +**Choix** (validé par Pierre) : GNU Backgammon officiel, figé au commit +`14b67984737ded0f6de43d63dcb789f729d9b06b` (1.08.003), dont on n'extrait que +le cœur (évaluation, coups, videau, identifiants, équité de match, fin de +partie) derrière `moteur.h`. +**Alternatives écartées** : +- gnubg-nn : 48 fichiers sous GPLv2 seule, incompatibles avec la GPLv3 ; videau + réimplémenté, donc sans concordance possible avec gnubg de bureau. +- CBG : même moteur, mais avec GLib complète et toute la logique de partie ; + interface orientée partie en cours ; pas de bases de fin de partie. Gardé + comme référence de lecture. +**Conséquences** : +- Le gnubg de bureau de référence est compilé dans Docker depuis le même + commit. +- GLib remplacée par un shim minimal ; tables d'équité XML à convertir. +- Les tests de concordance ont une tolérance, car gnubg de bureau est compilé + avec `-ffast-math`. + +## 2026-11-02 — Merge requests systématiques, fusion par Claude Code + +**Contexte** : Pierre veut comprendre chaque changement sans suivre le travail +au fil de l'eau. +**Choix** (demande de Pierre) : aucun commit direct sur `main`. Chaque +changement passe par une branche et une merge request Gitea dont la description +explique le pourquoi, le quoi, le comment, les choix, les risques, la +vérification et ce qui est hors périmètre. Claude Code la fusionne lui-même dès +que `make lint` et `make test` passent. +**Conséquence** : l'historique des MR sur git.sans.pub devient, avec `docs/`, +la trace vérifiable du projet. diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index dec2e5b..f8d716d 100644 --- a/docs/feuille-de-route.md +++ b/docs/feuille-de-route.md @@ -10,8 +10,8 @@ Légende : ✅ terminé · 🔄 en cours · ⏳ à venir · ⏸ conditionnel | Sous-étape | Contenu | État | Plans | | --- | --- | --- | --- | | Socle | Dépôt, Makefile, lint, tests, organisation | ✅ | — | -| 0a.1 | Choisir la source du moteur (gnubg, gnubg-nn, CBG) — validation de Pierre | 🔄 | `plans/2026-11-02-choix-source-moteur.md` | -| 0a.2 | Image Docker GNU Backgammon de bureau, 30+ positions de référence dans `tests/reference/` | ⏳ | | +| 0a.1 | Choisir la source du moteur : gnubg officiel, commit `14b6798` (validé) | ✅ | `plans/2026-11-02-choix-source-moteur.md` | +| 0a.2 | Image Docker GNU Backgammon de bureau (compilé depuis le commit `14b6798`), 30+ positions de référence dans `tests/reference/` | ⏳ | | | 0a.3 | Interface C `engine/include/moteur.h` et `engine-cli` (JSON) | ⏳ | | | 0a.4 | `make test` compare `engine-cli` aux références | ⏳ | | | 0b | Moteur en WebAssembly, page de test dans un Web Worker, `make deploy-web`, `make bench` | ⏳ | | diff --git a/docs/journal.md b/docs/journal.md index 84c0436..ceed663 100644 --- a/docs/journal.md +++ b/docs/journal.md @@ -14,7 +14,6 @@ Une entrée datée par session : ce qui a été fait, décidé, et la suite. `docs/decisions.md`. - Premiers tests : contrat du Makefile (`tests/test_makefile.sh`) ; lint du dépôt (`tests/lint.sh`, avec ShellCheck dans Docker). - - `main` poussé sur Gitea (`git@git.sans.pub:pierre/Ustagammon.git`), après fusion avec le commit initial créé par Gitea (LICENSE et README). Incident : le premier envoi contenait un `README.md` avec des marqueurs de conflit ; @@ -22,13 +21,19 @@ Une entrée datée par session : ce qui a été fait, décidé, et la suite. - `PROMPTS.md` supprimé ; ajout de `docs/organisation.md`, `docs/feuille-de-route.md` et `docs/plans/`. - Étape 0a.1 lancée : étude des trois sources du moteur confiée à un - sous-agent (`docs/plans/2026-11-02-choix-source-moteur.md`). + sous-agent (`docs/plans/2026-11-02-choix-source-moteur.md`), puis clôturée + avec vérification des points clés par la session principale. **Décidé** - Les outils de lint tournent dans Docker, comme les autres chaînes d'outils. - Claude Code pilote le projet par sous-agents ; tout le suivi est dans `docs/`. +- Moteur : gnubg officiel, commit `14b6798` (validé par Pierre). +- Toute modification passe par une merge request Gitea décrite en détail, + fusionnée par Claude Code une fois `make lint` et `make test` au vert + (demande de Pierre). **Reste à faire** -- Clôturer l'étude du moteur et soumettre la recommandation à Pierre. +- Étape 0a.2 : image Docker de gnubg de bureau compilé depuis le même commit, + et 30 positions de référence ou plus. - `adb` n'est pas installé sur le PC : `sudo apt install adb` avant les tests sur le téléphone. diff --git a/docs/organisation.md b/docs/organisation.md index 60c640e..85e1443 100644 --- a/docs/organisation.md +++ b/docs/organisation.md @@ -72,6 +72,29 @@ Rempli à la clôture : fait, écarts, preuves (sorties de commandes, mesures), suites à donner. ``` +## Branches et merge requests + +Aucun commit direct sur `main`. Pour chaque changement : + +1. Une branche au nom court et explicite (`moteur-reference`, `engine-cli`…). +2. Des commits petits, en français. +3. `make lint` et `make test` au vert. +4. Une merge request sur git.sans.pub (`tea pulls create --login sans-pub`), + dont la description permet à quelqu'un qui n'a pas suivi le travail de + comprendre le changement. Rédigée en prose, pas en liste de commits : + - **Pourquoi** : le problème, comment il est apparu, son impact, avec preuves ; + - **Quoi** : ce qui change, du point de vue du comportement ; + - **Comment** : l'approche technique et le raisonnement ; + - **Choix et compromis** : alternatives écartées, limites assumées ; + - **Risques** : ce qui peut casser, comment revenir en arrière ; + - **Comment vérifier** : commandes exactes ; + - **Hors périmètre** : ce qui a été repéré mais laissé de côté. +5. Fusion par Claude Code (commit de fusion, pour garder l'historique de la + branche), puis suppression de la branche. + +Une MR qui touche à un point soumis à validation (voir ci-dessous) n'est +fusionnée qu'après l'accord de Pierre, consigné dans `docs/decisions.md`. + ## Validation par Pierre Sont soumis à Pierre avant d'être appliqués : le choix de la source du moteur, diff --git a/docs/plans/2026-11-02-choix-source-moteur.md b/docs/plans/2026-11-02-choix-source-moteur.md index c6cb27b..187779e 100644 --- a/docs/plans/2026-11-02-choix-source-moteur.md +++ b/docs/plans/2026-11-02-choix-source-moteur.md @@ -2,7 +2,7 @@ - **Date** : 2026-11-02 - **Étape** : 0a.1 -- **Statut** : en cours +- **Statut** : terminé — recommandation validée par Pierre le 2026-11-02 - **Exécutant** : sous-agent general-purpose (étude, sans modification du dépôt) ## Objectif @@ -55,4 +55,85 @@ recommandée. ## Résultat -À remplir à la clôture. +**Recommandation** : partir de **gnubg officiel**, figé à un commit, et n'en +extraire que le cœur. CBG sert de référence à lire, pas de code à reprendre. +gnubg-nn est écarté. + +### Versions étudiées + +| Source | Commit | Date | +| --- | --- | --- | +| gnubg | `14b67984737ded0f6de43d63dcb789f729d9b06b` (1.08.003) | 2026-10-23 | +| gnubg-nn | `595a9e8f1fe094ee22db5a736bc05027643756df` | 2025-09-07 | +| CBG (`clavierhaus/gnubg-android`) | `62028573d7564275a7c9363f0ef5d4b63d8d0f26` (moteur gnubg `b1b2772c`) | 2026-10-26 | + +### Synthèse comparative + +| Point | gnubg | gnubg-nn | CBG | +| --- | --- | --- | --- | +| Activité | Active (corrections régulières) | Quasi arrêtée (outil d'entraînement des réseaux) | Très active ; un mainteneur, code très majoritairement écrit par IA | +| Licence | GPLv3 ou ultérieure | **48 fichiers en GPLv2 seule** : incompatible | GPLv3 ou ultérieure ; noms « CBG »/« Clavierhaus » revendiqués comme marques | +| Fonctions | Les cinq, avec videau, tables d'équité, Crawford, Jacoby, Position ID et Match ID | Partiel : pas de Match ID, videau réimplémenté en C++ (ne concordera pas) | Les cinq, mais interface pensée pour une partie en cours, pas pour une position isolée | +| Dépendances | GLib dans tout le cœur, remplaçable par un petit shim (~30 fonctions), sauf GMarkup (tables d'équité) et `g_mapped_file` ; SSE/AVX/**NEON** et repli C générique ; threads désactivables | C++14, Python 2, SSE seul | Compile GLib, GObject et libintl en entier pour Android | +| Isolement | Faisable : ~24 400 lignes ; état global partout (une instance, appels sérialisés) ; `backgammon.h` à réduire | Évaluation isolée, le reste à réécrire | 41 fichiers + 681 lignes de bouchons : pas une bibliothèque minimale | +| Données | `gnubg.weights` (1 097 796 octets) ; `gnubg.wd`, `gnubg_os0.bd`, `gnubg_ts0.bd` **générés au build** ; tables d'équité XML (`Kazaross-XG2.xml` par défaut) | Pas de poids fournis | Mêmes poids (identiques octet pour octet) ; **aucun `.bd` fourni** | +| Portabilité | NEON déjà présent ; pas de SIMD WebAssembly (C générique) ; un portage Emscripten tiers existe (`hwatheod/gnubg-web`, 2019, non lu) | Mauvais point de départ | Build CMake/NDK fonctionnel, sans WebAssembly | +| Concordance | Mêmes sources et poids que le bureau ; écart flottant inévitable car `configure.ac` force `-ffast-math` (approximation de la sigmoïde) | Non, pour le videau | Écarts ~1e-4 (réseau) à ~3e-3 (équité 2-ply) selon leur documentation, non vérifié | + +### Vérifié par la session principale + +Recoupé directement dans les clones : 48 fichiers de gnubg-nn sous GPLv2 sans +« or later » ; licence GPLv3+ de `gnubg/eval.c` ; `-ffast-math` ajouté par +`configure.ac:595` ; code NEON dans `lib/simd.h` et `lib/neuralnetsse.c` ; +`gnubg.weights` de 1 097 796 octets identique dans gnubg et CBG ; trois usages +de `g_markup` dans `matchequity.c` ; `makebearoff` produit au build ; commits et +dates ci-dessus. Les autres affirmations viennent du rapport de l'agent (lecture +du code, sans compilation ni édition des liens). + +### Fichiers à reprendre (gnubg `14b6798`) + +- Évaluation : `eval.c/h`, `movefilters.inc`, `lib/neuralnet.c/h`, + `lib/neuralnetsse.c`, `lib/inputs.c`, `lib/simd.h`, `lib/sigmoid.h`, + `lib/cache.c/h`, `lib/gnubg-types.h`, `lib/isaac.c/h`, `lib/isaacs.h`, + `lib/md5.c/h`. +- Fin de partie : `bearoff.c/h`, `bearoffgammon.c/h`. +- Identifiants : `positionid.c/h`, `matchid.c/h`. +- Équité de match : `matchequity.c/h`, `mec.c/h`, `lib/list.c/h`. +- En-têtes à réduire : `backgammon.h`, `common.h`, `multithread.h`, `util.h`. +- Données : `gnubg.weights`, `met/*.xml` ; outils hôte `makeweights.c`, + `makebearoff.c`. + +Liste issue des `#include` et d'un grep des symboles : elle sera confirmée à la +première édition des liens. + +### Plan d'isolement esquissé + +1. Copie figée du commit dans `engine/`, `config.h` écrit à la main (sans + threads ; NEON sur arm64 ; rien en WebAssembly). +2. Shim `glib.h` minimal ; `mmap`/`fread` à la place de `g_mapped_file`. +3. Tables d'équité converties en tableaux C au build (ou table Zadeh intégrée + pour commencer). +4. En-tête réduit à la place de `backgammon.h`, variables globales aux valeurs + par défaut de `gnubg.c` ; s'inspirer de `cbg/jni-bridge/src/stubs.c`. +5. Façade `moteur.h` sur `GenerateMoves`, `FindnSaveBestMoves`, + `GeneralCubeDecisionE`/`FindCubeDecision`, `PositionFromID`, `MatchFromID`. +6. `gnubg.wd` et bases `.bd` générées sur l'hôte avec les outils officiels. +7. Tests de concordance avec tolérance ; mesurer l'écart avec et sans + `-ffast-math`. + +### Risques + +1. Concordance au bit près impossible entre x86 avec `-ffast-math` et ARM ou + WebAssembly : les tests devront fixer une tolérance, et prévoir le cas où le + meilleur coup change entre deux coups presque équivalents. +2. Tables d'équité dépendantes de GMarkup. +3. État global : une seule instance du moteur. +4. Mises à jour de gnubg à reporter à la main sur la copie figée. +5. Tailles des `.bd` non mesurées (générées au build). + +### Suites à donner + +- Validation du choix par Pierre, puis entrée dans `docs/decisions.md`. +- Conséquence pour 0a.2 : le gnubg de bureau de référence doit être **compilé + dans Docker depuis le même commit** (et non pris dans un paquet Debian d'une + autre version), pour que les références soient comparables.