diff --git a/RULES.md b/RULES.md index c0773e7..67b10ab 100644 --- a/RULES.md +++ b/RULES.md @@ -1,5 +1,5 @@ - + # Index normatif games.sasedev @@ -17,8 +17,9 @@ Les règles détaillées sont maintenues sous `docs/rules/` et sont cumulatives 6. [`docs/rules/VERSION_WORKFLOW.md`](docs/rules/VERSION_WORKFLOW.md) — SemVer, niveaux de maturité, fixes, deltas et livraisons ; 7. [`docs/rules/RULES_COMMANDS.md`](docs/rules/RULES_COMMANDS.md) — politique d’exécution des commandes Cargo, audits, runners, Android, Web et Git ; 8. [`docs/rules/RULES_VALIDATION_MATRIX.md`](docs/rules/RULES_VALIDATION_MATRIX.md) — matrice évolutive des commandes, dépendances de validation et politiques de nettoyage ; -9. [`docs/rules/RULES_SESSION_PLANNING.md`](docs/rules/RULES_SESSION_PLANNING.md) — cadrage `pre.1`, dimensionnement des sessions et contrat des prompts de reprise ; -10. [`docs/rules/RULES_SERVER_HOSTING.md`](docs/rules/RULES_SERVER_HOSTING.md) — contraintes durables de portabilité et préférence d'auto-hébergement. +9. [`docs/rules/RULES_SESSION_PLANNING.md`](docs/rules/RULES_SESSION_PLANNING.md) — cadrage `pre.1`, dimensionnement des sessions et cycle de transmission ; +10. [`docs/rules/PROMPT_STRUCTURE.md`](docs/rules/PROMPT_STRUCTURE.md) — structure minimale des prompts de reprise et rappels de workflow obligatoires ; +11. [`docs/rules/RULES_SERVER_HOSTING.md`](docs/rules/RULES_SERVER_HOSTING.md) — contraintes durables de portabilité et préférence d'auto-hébergement. ## Hiérarchie diff --git a/deltas/0.3.0/2-beta.2.fix.1.md b/deltas/0.3.0/2-beta.2.fix.1.md new file mode 100644 index 0000000..a3d0698 --- /dev/null +++ b/deltas/0.3.0/2-beta.2.fix.1.md @@ -0,0 +1,67 @@ + + + +# Delta 0.3.0-2-beta.2.fix.1 + +## Base requise + +`0.3.0-2-beta.2` validée mécaniquement par l'utilisateur le 2026-09-20. + +## Objectif + +Corriger la transmission documentaire de `2-beta.2` : rendre le prompt `0.3.1` suffisamment autonome pour limiter les rappels conversationnels et les fixes évitables, sans reproduire l'intégralité des règles KSP ni modifier le code/runtime. + +## Changements + +- enrichissement de `prompts/003-V0_3_1_START_PROMPT.md` avec ordre de lecture, handoff `0.3.0`, cadrage `pre.1`, invariants Tauri/Android/WASM, documentation, commandes, validations, forecast et condition de fin de session ; +- ajout de `docs/rules/PROMPT_STRUCTURE.md`, inspiré du principe KSP de prompt autonome mais volontairement plus compact ; +- ajout de règles explicites sur le rôle de `deltas/`/`history/`, le timing `ROADMAP`/`CHANGELOG`/prompt suivant et la séparation des validations utilisateur ; +- ajout d'une politique `DOC-CRATE-*` pour décider utilement de `README.md`/`USAGE.md` sans créer de fichiers cérémoniels ; +- clarification du cycle du prompt suivant : rédaction pendant la consolidation, vérification/complément à la première RC gelée ; +- clarification du versionnement des fixes strictement documentaires : le delta porte `.fix.1` mais `workspace.package.version` et les packages runtime restent `0.3.0-2-beta.2` ; +- ajout de `history/0.3.0/2-beta.2.md` avec les résultats réellement validés et le motif humain du fix ; +- réconciliation du plan `0.3.0` avec ce correctif de transmission. + +`CHANGELOG.md` et `ROADMAP.md` ne sont pas modifiés : le fix ne change ni la publication candidate ni le scope produit. + +## Fichiers ajoutés + +```text +docs/rules/PROMPT_STRUCTURE.md +history/0.3.0/2-beta.2.md +deltas/0.3.0/2-beta.2.fix.1.md +``` + +## Fichiers modifiés + +```text +RULES.md +docs/000-README.md +docs/plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md +docs/rules/RULES_DOCUMENTATION.md +docs/rules/RULES_SESSION_PLANNING.md +docs/rules/VERSION_WORKFLOW.md +prompts/003-V0_3_1_START_PROMPT.md +``` + +## Fichiers supprimés + +Aucun. + +## Version technique + +Ce correctif est strictement documentaire. Conformément à `VER-DOCFIX-001`, il ne modifie ni `workspace.package.version` ni la version du package Web : la version technique reste `0.3.0-2-beta.2`. + +## Validation attendue + +```bash +python3 scripts/audit_rust_workspace_rules.py +python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android Web deltas history +python3 scripts/audit_distribution_layout.py +``` + +Aucun build Cargo/npm ni smoke n'est requis pour ce fix : aucun fichier consommé par le build/runtime n'est modifié. + +## Après validation + +Si la revue humaine du prompt enrichi est satisfaisante, ouvrir `0.3.0-3-rc.1` et appliquer la matrice RC. La RC vérifie/complète le prompt `0.3.1`, écrit l'entrée RC du `CHANGELOG.md` et ne rouvre pas le scope fonctionnel. diff --git a/docs/000-README.md b/docs/000-README.md index 771eb67..4c07b98 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation games.sasedev @@ -56,7 +56,7 @@ ## Règles -Voir [`../RULES.md`](../RULES.md), notamment [`rules/RULES_DOCUMENTATION.md`](rules/RULES_DOCUMENTATION.md) pour la gouvernance documentaire, [`rules/RULES_COMMANDS.md`](rules/RULES_COMMANDS.md) pour la politique d'exécution, [`rules/RULES_VALIDATION_MATRIX.md`](rules/RULES_VALIDATION_MATRIX.md) pour la matrice des gates, [`rules/RULES_SESSION_PLANNING.md`](rules/RULES_SESSION_PLANNING.md) pour le cadrage des sessions et [`rules/RULES_SERVER_HOSTING.md`](rules/RULES_SERVER_HOSTING.md) pour la portabilité d'auto-hébergement. +Voir [`../RULES.md`](../RULES.md), notamment [`rules/RULES_DOCUMENTATION.md`](rules/RULES_DOCUMENTATION.md) pour la gouvernance documentaire, [`rules/RULES_COMMANDS.md`](rules/RULES_COMMANDS.md) pour la politique d'exécution, [`rules/RULES_VALIDATION_MATRIX.md`](rules/RULES_VALIDATION_MATRIX.md) pour la matrice des gates, [`rules/RULES_SESSION_PLANNING.md`](rules/RULES_SESSION_PLANNING.md) pour le cadrage des sessions, [`rules/PROMPT_STRUCTURE.md`](rules/PROMPT_STRUCTURE.md) pour le contrat des prompts de reprise et [`rules/RULES_SERVER_HOSTING.md`](rules/RULES_SERVER_HOSTING.md) pour la portabilité d'auto-hébergement. ## Validation diff --git a/docs/plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md b/docs/plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md index ceb2496..d423f48 100644 --- a/docs/plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md +++ b/docs/plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md @@ -1,5 +1,5 @@ - + # Plan v0.3.0 — baseline Snake et premier POC Web direct @@ -115,6 +115,8 @@ Cette tranche est une responsabilité obligatoire du cycle même si son numéro Gate : cohérence docs/plan/deltas/`CHANGELOG.md`/`ROADMAP.md`/history/prompt, audits documentaires, `cargo check --workspace` pour le bump de version et `npm run build` pour confirmer la version frontend. +Suivi `2-beta.2.fix.1` : la gate mécanique de `2-beta.2` passe, mais la revue humaine juge le prompt `0.3.1` trop synthétique pour éviter des rappels de workflow au cours de la prochaine session. Le fix enrichit ce prompt, formalise une structure durable de prompts, précise le timing prompt/RC/CHANGELOG/ROADMAP/history et introduit une politique non cérémonielle pour `README.md`/`USAGE.md`. Le fix est strictement documentaire et conserve donc la version technique `0.3.0-2-beta.2`. + ### `3-rc.1` — candidate gelée Reproductibilité, validation finale de la candidate et derniers défauts strictement nécessaires à la publication. Le prompt suivant préparé pendant la consolidation est vérifié/complété si l'état RC apporte une information nouvelle. Aucun nouveau POC ni nouvelle capability. diff --git a/docs/rules/PROMPT_STRUCTURE.md b/docs/rules/PROMPT_STRUCTURE.md new file mode 100644 index 0000000..4306201 --- /dev/null +++ b/docs/rules/PROMPT_STRUCTURE.md @@ -0,0 +1,64 @@ + + + +# Structure des prompts de reprise + +## Objet + +Un prompt de démarrage est un contrat opératoire autonome pour la version suivante. Il doit permettre de reprendre le travail sans dépendre de la mémoire conversationnelle, tout en évitant de recopier intégralement les règles du dépôt. + +Le prompt rappelle les invariants qui évitent les erreurs de workflow et renvoie aux documents normatifs pour leur détail exact. + +## Contenu minimal + +- **PROMPT-STR-001** — Le prompt identifie la baseline exacte, la version cible et l'autorité de la base fournie. Une archive annoncée comme téléchargement d'un tag est traitée selon `CMD-GIT-003`/`CMD-GIT-004` sans exiger `.git`. +- **PROMPT-STR-002** — Le prompt fournit un ordre de lecture court des sources de vérité : `RULES.md`, `ROADMAP.md`, `CHANGELOG.md`, `docs/000-README.md`, règles directement pertinentes, plan/historique de la version précédente et documents d'architecture concernés. +- **PROMPT-STR-003** — Le prompt distingue explicitement l'état déjà validé hérité de la baseline des validations qui devront être exécutées dans la nouvelle version. +- **PROMPT-STR-004** — Le prompt décrit la mission, le résultat attendu, le scope inclus, le hors-périmètre et les invariants architecturaux gelés. +- **PROMPT-STR-005** — Le prompt rappelle que `0-pre.1` est le gate de cadrage : audit, requirements, sizing, risques, validations prévues et création/révision du plan sous `docs/plans/` avant développement lourd. +- **PROMPT-STR-006** — Le prompt contient un forecast souple jusqu'à la stable. Il réserve les responsabilités de développement, validation large, consolidation documentaire, préparation de publication/RC et release mécanique sans rendre les numéros immuables. +- **PROMPT-STR-007** — Le prompt rappelle où se trouve la définition des commandes : `docs/rules/RULES_COMMANDS.md` pour la politique d'exécution et `docs/rules/RULES_VALIDATION_MATRIX.md` pour les IDs, dépendances et déclencheurs. Il ne recopie que les commandes indispensables à la reprise ou au premier gate. +- **PROMPT-STR-008** — Le prompt rappelle la séparation utilisateur/générateur : les audits statiques peuvent être exécutés par le générateur, mais les builds, tests et smokes finaux restent côté utilisateur conformément à `CMD-BUILD-005` et ne sont jamais déclarés réussis sans sortie réelle. + +## Documentation et traçabilité à rappeler + +- **PROMPT-STR-010** — Le prompt rappelle que `deltas/` décrit la livraison candidate et ses validations attendues, alors que `history/` enregistre uniquement le résultat d'un jalon effectivement accepté. +- **PROMPT-STR-011** — Le prompt rappelle qu'une entrée `history//.md` est créée par le delta suivant ou le fix suivant après validation, jamais avant la validation qu'elle décrit. +- **PROMPT-STR-012** — Le prompt rappelle que `CHANGELOG.md` n'est normalement mis à jour qu'à partir de la RC puis à la stable ; les détails `pre`/`beta` restent dans `deltas/` et `history/`. +- **PROMPT-STR-013** — Le prompt rappelle que `ROADMAP.md` reste macroscopique et n'est modifié que lorsque le scope, son ordre ou son statut évolue réellement ; le plan de version porte le découpage fin. +- **PROMPT-STR-014** — Le prompt rappelle que la documentation propre à une fonctionnalité évolue avec la tranche qui l'introduit ; la consolidation finale réconcilie l'ensemble mais ne sert pas à repousser toute documentation à la fin. +- **PROMPT-STR-015** — Le prompt mentionne explicitement la politique `README.md`/`USAGE.md` lorsque la version crée ou finalise une crate, une application ou un package : appliquer `DOC-CRATE-*` et décider dans le plan quels fichiers ont une valeur durable réelle. + +## README et USAGE dans une version + +Le prompt ne doit pas imposer mécaniquement des fichiers vides. Il doit en revanche forcer la question au cadrage puis à la consolidation : + +```text +nouvelle crate/package durable ? + -> README utile pour responsabilité/frontières/points d'entrée ? + +API ou workflow de consommation non trivial ? + -> USAGE utile pour préconditions/commandes/exemples ? + +simple adapter/POC déjà documenté durablement ailleurs ? + -> document supplémentaire non obligatoire s'il n'apporte rien +``` + +## Timing du prompt suivant + +- **PROMPT-STR-020** — Le prompt de la version suivante est rédigé pendant la consolidation finale lorsque la cible suivante est suffisamment connue ; il n'est pas reporté à une future session. +- **PROMPT-STR-021** — La première RC gelée vérifie et complète ce prompt à partir de l'état réellement candidat à publication ; elle ne lui attribue pas de validations futures. +- **PROMPT-STR-022** — La stable ne doit normalement effectuer qu'une mise à jour mécanique de la base de départ ou des références devenues certaines depuis la RC. + +## Versionnement, deltas et fixes + +- **PROMPT-STR-030** — Le prompt rappelle le format SemVer applicable et le rôle des `.fix.N` lorsqu'une erreur est découverte dans une tranche déjà livrée. +- **PROMPT-STR-031** — Le prompt rappelle que chaque delta indique sa base requise, son scope, les fichiers touchés, les validations attendues et l'état connu du jalon précédent. +- **PROMPT-STR-032** — Une validation propre permet de poursuivre automatiquement vers la tranche planifiée suivante ; un échec reste dans un `.fix.N` de la tranche courante sauf décision explicite contraire. +- **PROMPT-STR-033** — Le prompt rappelle qu'une session est dimensionnée pour fermer au minimum une version concrète jusqu'à sa stable, pas pour s'arrêter volontairement sur une prerelease. + +## Niveau de détail attendu + +Le prompt doit être assez complet pour éviter les rappels conversationnels récurrents, mais il ne devient pas une duplication exhaustive de `docs/rules/`. + +Une taille de quelques centaines de lignes est acceptable lorsqu'elle porte du contexte opérationnel réel. Les listes de toutes les règles Rust ou de toutes les commandes du dépôt restent dans leurs documents normatifs ; le prompt cite les règles et reproduit seulement les garde-fous susceptibles d'être oubliés dans la version ciblée. diff --git a/docs/rules/RULES_DOCUMENTATION.md b/docs/rules/RULES_DOCUMENTATION.md index 13c96d9..d01734c 100644 --- a/docs/rules/RULES_DOCUMENTATION.md +++ b/docs/rules/RULES_DOCUMENTATION.md @@ -1,5 +1,5 @@ - + # Règles de documentation @@ -41,6 +41,14 @@ - **DOC-NAME-007** — Dans un répertoire documentaire destiné à contenir plusieurs fichiers Markdown, le point d'entrée porte le nom `000-README.md` afin d'être trié en premier. - **DOC-NAME-008** — Un nouveau répertoire documentaire multi-fichiers ne crée pas de `README.md` concurrent à `000-README.md`. +## Documentation des crates, applications et packages + +- **DOC-CRATE-001** — Toute nouvelle crate, application ou package frontend évalue explicitement pendant son cadrage puis sa consolidation finale si un `README.md` ou un `USAGE.md` apporte une information durable utile ; ces fichiers ne sont jamais créés uniquement pour satisfaire une cérémonie. +- **DOC-CRATE-002** — Un `README.md` local décrit la responsabilité, les frontières, les dépendances structurantes et les principaux points d'entrée lorsqu'un composant devient durable ou réutilisable et que ces informations ne sont pas suffisamment couvertes par une documentation centrale. +- **DOC-CRATE-003** — Un `USAGE.md` est ajouté lorsqu'une API, un binaire, une application ou un package possède un workflow de consommation/opérateur, des préconditions, des commandes, de la configuration ou des exemples suffisamment non triviaux pour mériter un guide stable. +- **DOC-CRATE-004** — Un adapter ou POC très petit peut rester documenté uniquement par les documents d'architecture/développement existants lorsque cela couvre réellement son contrat ; l'absence de `README.md`/`USAGE.md` doit alors être un choix de valeur documentaire, pas un oubli. +- **DOC-CRATE-005** — `README.md` et `USAGE.md` restent durables et ne contiennent pas de journal de release ; les changements de version appartiennent à `CHANGELOG.md`, `deltas/` et `history/`. + ## Listes de tâches et d'état - **DOC-TASK-001** — Toute liste Markdown qui représente durablement des tâches, objectifs ou éléments suivis utilise les marqueurs `( )`, `(x)`, `(d)` et `(c)` plutôt que les task lists Markdown `[ ]` / `[x]`. diff --git a/docs/rules/RULES_SESSION_PLANNING.md b/docs/rules/RULES_SESSION_PLANNING.md index 7535767..b25a556 100644 --- a/docs/rules/RULES_SESSION_PLANNING.md +++ b/docs/rules/RULES_SESSION_PLANNING.md @@ -1,5 +1,5 @@ - + # Règles de cadrage des versions, sessions et prompts @@ -49,6 +49,7 @@ Ces règles imposent un découpage suffisamment petit pour qu'une version puisse - **PROMPT-006** — Le prompt contient suffisamment de contexte pour reprendre la version sans dépendre de la mémoire conversationnelle ni relire toute l'histoire du dépôt. - **PROMPT-007** — Le prompt précise la condition de fin de session et les livrables attendus. - **PROMPT-008** — Si `pre.1` invalide le sizing prévu par le prompt, le nouveau découpage est documenté immédiatement avant le développement lourd. +- **PROMPT-009** — Tout nouveau prompt de version applique `docs/rules/PROMPT_STRUCTURE.md`; le présent document fixe le cycle de session tandis que `PROMPT_STRUCTURE.md` fixe le contenu opératoire à rappeler. ## Relation avec VERSION_WORKFLOW diff --git a/docs/rules/VERSION_WORKFLOW.md b/docs/rules/VERSION_WORKFLOW.md index 79a31bd..e40f78e 100644 --- a/docs/rules/VERSION_WORKFLOW.md +++ b/docs/rules/VERSION_WORKFLOW.md @@ -1,5 +1,5 @@ - + # Versionnement, maturité et livraisons @@ -98,9 +98,16 @@ La promotion `rc` puis stable d'une version de conception exige une validation h ## Prompt de la version suivante -- **VER-PROMPT-001** — Le prompt de démarrage de la version suivante n'est pas créé à un numéro arbitraire de RC. -- **VER-PROMPT-002** — Sa génération devient recommandée après validation de la première RC dont le périmètre est effectivement gelé. +- **VER-PROMPT-001** — Le prompt de démarrage de la version suivante est rédigé pendant la consolidation finale lorsque la cible suivante est suffisamment connue ; il ne dépend pas d'une future session pour exister. +- **VER-PROMPT-002** — La première RC dont le périmètre est effectivement gelé vérifie et complète ce prompt à partir de l'état réellement candidat à publication. - **VER-PROMPT-003** — Le prompt peut être complété pendant les fixes RC ou la release stable, mais ne doit pas contenir de résultats futurs présentés comme déjà validés. +- **VER-PROMPT-004** — La structure et les rappels opératoires obligatoires du prompt sont définis par `docs/rules/PROMPT_STRUCTURE.md`. + +## Correctifs strictement documentaires + +- **VER-DOCFIX-001** — Un `.fix.N` limité à la documentation, aux prompts, aux deltas, à `history/` ou aux règles non consommées par le build/runtime ne modifie pas `workspace.package.version` ni les versions de packages runtime. L'identité du correctif est portée par le delta et son archive. +- **VER-DOCFIX-002** — Une prerelease non-fix (`pre.N`, `alpha.N`, `beta.N`, `rc.N`) synchronise sa version technique selon le workflow de phase même lorsque son contenu est principalement documentaire. +- **VER-DOCFIX-003** — Dès qu'un correctif touche du code, une configuration exécutable, un manifeste consommé par le build/runtime ou un artefact distribué, la version technique suit l'identifiant `.fix.N`. ## Phases de développement diff --git a/history/0.3.0/2-beta.2.md b/history/0.3.0/2-beta.2.md new file mode 100644 index 0000000..3567930 --- /dev/null +++ b/history/0.3.0/2-beta.2.md @@ -0,0 +1,51 @@ + + + +# Historique 0.3.0-2-beta.2 + +## Statut + +Consolidation `2-beta.2` validée par l'utilisateur le 2026-09-20. Les audits, le check workspace et le build frontend de production passent ; aucun défaut mécanique n'est remonté. + +Une revue humaine du prompt `0.3.1` relève toutefois qu'il est trop court pour servir de contrat de reprise suffisamment autonome. La correction appartient à `2-beta.2` puisqu'elle concerne la consolidation/transmission et ouvre `2-beta.2.fix.1`. + +## Gate documentaire et workspace + +Les validations suivantes passent : + +```text +cargo fmt --all -- --check: clean +General Rust rule audit: clean +Rust export completeness audit: 0 candidate(s) +games.sasedev workspace audit: clean +Markdown table audit: clean (5 table(s), 198 file(s)) +Distribution layout audit: clean (31 required path(s), 1 forbidden path(s) absent) +cargo check --workspace: clean +``` + +## Frontend + +Le package Web Snake est confirmé cohérent avec le jalon beta : + +```text +npm install: 64 packages audités, 0 vulnérabilité +npm run build: clean +Vite: 30 modules transformés +vite-plugin-static-copy: 2 items copiés +``` + +Le warning npm non bloquant relatif au script d'installation de `@parcel/watcher@2.6.0` reste présent. + +## Revue humaine + +Le contenu de consolidation est accepté mécaniquement, mais le prompt `prompts/003-V0_3_1_START_PROMPT.md` doit être enrichi avant la RC afin de rappeler de manière autonome : + +- le timing du prompt suivant, du `CHANGELOG.md` et du `ROADMAP.md` ; +- le rôle respectif de `deltas/` et `history/` ; +- où se trouvent les définitions de commandes et leur matrice ; +- la politique `README.md` / `USAGE.md` des crates et applications ; +- le workflow de validation/fix et la condition de fin de session. + +## Suite + +`0.3.0-2-beta.2.fix.1` corrige uniquement la transmission documentaire et les règles associées. Aucun changement code/build/runtime n'est attendu. diff --git a/prompts/003-V0_3_1_START_PROMPT.md b/prompts/003-V0_3_1_START_PROMPT.md index d0d8eae..032f803 100644 --- a/prompts/003-V0_3_1_START_PROMPT.md +++ b/prompts/003-V0_3_1_START_PROMPT.md @@ -1,70 +1,560 @@ - + -# Prompt de démarrage 0.3.1 — second host Snake Tauri Android +# Prompt de démarrage `0.3.1` — second host Snake Tauri Android -Partir de la version stable `0.3.0`. Si ce prompt est lu avant la publication effective de `0.3.0`, ne pas ouvrir `0.3.1` : terminer d'abord la RC et la release stable. +## 1. Base exacte et autorité de la reprise -Lire intégralement `RULES.md`, `ROADMAP.md`, `CHANGELOG.md`, `docs/000-README.md`, `docs/architecture/015-PLATFORM_POC_ARCHITECTURE.md`, `docs/architecture/018-V0_3_0_WEB_SNAKE_BASELINE.md`, `docs/plans/` et le dernier historique validé de `0.3.0` avant toute proposition. - -## Mission - -`0.3.1` doit produire le second host Snake : Tauri Android. Le but est d'éprouver la réutilisation de la baseline Web/WASM validée en `0.3.0`, pas de refactorer préventivement le framework. - -Le résultat attendu est un Snake exécutable dans le WebView Tauri Android, avec lifecycle, input, assets, logging et provenance cohérents, construit par les toolchains natives prévues sans nouvel orchestrateur Python. - -## `0.3.1-0-pre.1` — cadrage obligatoire - -Avant le développement lourd : - -- auditer la stable `0.3.0` et ses résultats Web/WASM ; -- auditer le POC historique `game-reflex-poc-tauri` et ses hooks ; -- auditer la baseline Android Java/SDL/JNI sans la confondre avec le host Tauri Android ; -- identifier les prérequis Tauri Android/SDK/NDK réellement disponibles ; -- déterminer ce qui peut être réutilisé tel quel depuis `game-snake-poc-wasm` et `Web/game-snake-poc` ; -- repérer la duplication réelle avant toute extraction ; -- définir les smokes appareil/émulateur et la provenance attendue ; -- créer ou réviser le plan `0.3.1` sous `docs/plans/` avec découpage prévisionnel souple jusqu'à la stable. - -## Contraintes gelées - -- `game-snake-poc` reste indépendant de Tauri, Android, DOM et providers ; -- `game-snake-poc-wasm` reste l'adapter WASM Snake tant qu'un besoin réel ne justifie pas une extraction ; -- ne pas copier le gameplay dans le frontend Tauri ; -- ne pas généraliser le frontend Web avant observation du second consommateur ; -- si une factorisation Web/WebView devient justifiée, la documenter avec ses deux consommateurs réels ; -- ne pas réintroduire `scripts/build_reflex_tauri_wasm.py` ni créer un nouvel orchestrateur Python pour le chemin touché ; -- les builds sont pilotés par Cargo, Tauri CLI, npm/Vite et les toolchains Android natives appropriées ; -- ne pas démarrer Tauri Desktop, Android SDL multi-ABI, réseau realtime ou Uroburas dans `0.3.1`. - -## Forecast initial souple - -Le forecast doit être confirmé ou corrigé pendant `0-pre.1`. Une trajectoire plausible est : +Partir uniquement de la version stable/taggée : ```text -0-pre.1 audit / requirements / sizing / plan -0-pre.2 host Tauri Android Snake minimal + build natif -0-pre.3 lifecycle / input / assets / provenance / logging -0-pre.4 factorisation uniquement si deux consommateurs la justifient -2-beta.1 validation large Android + non-régression Web/Desktop -2-beta.2 consolidation documentaire et transmission -3-rc.1 candidate gelée -0.3.1 release mécanique +v0.3.0 ``` -Cette numérotation reste révisable conformément aux règles de session. +Si ce prompt est lu avant la publication effective de `0.3.0`, ne pas ouvrir `0.3.1`. Terminer d'abord la RC puis la release stable `0.3.0`. -## Validation attendue +Lorsqu'une archive est fournie comme téléchargement du tag `v0.3.0`, elle constitue la baseline autoritaire même si elle ne contient pas `.git`. Appliquer `CMD-GIT-003` et `CMD-GIT-004` : vérifier la cohérence interne des versions et des fichiers, ne pas inventer un état Git inaccessible. -Les commandes exactes sont fixées en `pre.1` à partir de l'environnement disponible. Au minimum, conserver : +Version cible : -- audits statiques du dépôt ; -- format/check/Clippy/tests Rust proportionnels ; -- build Tauri Android par le chemin natif retenu ; -- smoke sur émulateur ou appareil réellement disponible ; -- non-régression du host Web Snake `0.3.0` ; -- non-régression Desktop SDL3 lorsque la frontière Snake/WASM est touchée. +```text +0.3.1 +``` -## Condition de fin de session +Première tranche obligatoire : -La session ne s'arrête normalement pas sur une prerelease. Elle doit fermer `0.3.1` jusqu'à la stable ou reporter explicitement le scope non indispensable vers une version suivante si le sizing de `pre.1` démontre que la cible est trop grande. +```text +0.3.1-0-pre.1 +``` + +`0-pre.1` est un gate de lecture, audit, requirements, sizing, validation et planification. Ne pas commencer directement par le scaffold Android/Tauri ou par la copie du POC Reflex. + +## 2. Sources de vérité — ordre de lecture obligatoire + +Lire intégralement, dans cet ordre : + +```text +RULES.md +ROADMAP.md +CHANGELOG.md +docs/000-README.md +``` + +Puis lire les règles directement pertinentes : + +```text +docs/rules/RULES_GENERAL.md +docs/rules/RULES_RUST.md +docs/rules/RULES_PROJECT.md +docs/rules/RULES_DOCUMENTATION.md +docs/rules/FILE_CONTRACTS.md +docs/rules/VERSION_WORKFLOW.md +docs/rules/RULES_COMMANDS.md +docs/rules/RULES_VALIDATION_MATRIX.md +docs/rules/RULES_SESSION_PLANNING.md +docs/rules/PROMPT_STRUCTURE.md +``` + +Le prompt résume les garde-fous nécessaires à `0.3.1`; les règles restent normatives en cas de détail absent ici. + +Lire ensuite la transmission `0.3.0` : + +```text +docs/plans/001-V0_3_0_WEB_SNAKE_POC_PLAN.md +docs/architecture/015-PLATFORM_POC_ARCHITECTURE.md +docs/architecture/018-V0_3_0_WEB_SNAKE_BASELINE.md +docs/testing/004-V0_3_0_RC_VALIDATION_MATRIX.md +history/0.3.0/ +deltas/0.3.0/ +``` + +Enfin auditer les implémentations réellement concernées : + +```text +crates/games/game-snake-poc/ +crates/apps/game-snake-poc-wasm/ +Web/game-snake-poc/ +crates/apps/game-snake-poc-desktop/ +crates/apps/game-reflex-poc-tauri/ +crates/apps/game-reflex-poc-wasm/ +Android/ +assets/ +``` + +Ne pas déduire l'état d'une crate depuis ce prompt lorsque le code stable `0.3.0` dit autre chose. + +## 3. État hérité attendu de `0.3.0` + +La stable `0.3.0` doit avoir validé au minimum : + +```text +Snake gameplay indépendant des hosts +runner Desktop SDL3 fonctionnel +adapter Snake WASM dédié +host navigateur direct Vite/TypeScript +shell HTML Bootstrap 5 / Bootswatch / SimpleBar +Canvas respectant le ratio logique Snake +clavier + contrôles pointer/tactiles +lifecycle navigateur fixed-step sans catch-up massif +assets common/game packagés depuis assets/ +logging frontend structuré +RuntimeProvenance Web / Browser / Wasm +build WASM release + wasm-bindgen +build Vite production + preview +``` + +Cette liste est un handoff attendu, pas une validation à réexécuter aveuglément au premier instant. Confirmer l'état réel de la stable puis définir les non-régressions nécessaires à `0.3.1`. + +## 4. Mission de `0.3.1` + +`0.3.1` doit produire le second host Snake : Tauri Android. + +Le but est de vérifier que la baseline Web/WASM de `0.3.0` peut être réutilisée dans un WebView mobile Tauri sans recopier le gameplay, sans dupliquer inutilement le bridge WASM et sans créer un framework abstrait avant preuve d'un besoin partagé. + +Résultat attendu : + +```text +Snake exécutable dans un host Tauri Android +build Android piloté par les outils Tauri/Android natifs retenus +lifecycle mobile cohérent +input tactile et comportement WebView cohérents +assets accessibles dans le package final +logging Rust/Tauri/frontend cohérent +RuntimeProvenance distincte du navigateur direct +non-régression du host Web direct 0.3.0 +non-régression Desktop SDL3 si une frontière partagée change +``` + +## 5. `0.3.1-0-pre.1` — cadrage obligatoire + +Avant tout développement lourd, produire un audit réel de la stable `0.3.0` et de l'environnement disponible. + +### 5.1 Baseline Snake + +Auditer : + +```text +game-snake-poc +game-snake-poc-wasm +Web/game-snake-poc +game-snake-poc-desktop +engine-v1-common +engine-v1-platform-api +assets communs et Snake +``` + +Identifier explicitement : + +- ce qui est réutilisable tel quel ; +- ce qui est spécifique au navigateur direct ; +- ce qui appartient déjà à l'adapter WASM ; +- ce qui deviendrait réellement partagé entre navigateur et WebView Tauri ; +- toute duplication prouvée avant extraction. + +### 5.2 Référence Tauri existante + +Auditer intégralement : + +```text +crates/apps/game-reflex-poc-tauri/ +crates/apps/game-reflex-poc-wasm/ +docs/development/008-WASM_TAURI_POC.md +``` + +Le POC Reflex est une référence technique de structure, de bridge Tauri, de frontend et de logging. Il n'est pas un template à copier aveuglément si sa baseline historique contredit les règles `0.3.x`. + +Vérifier notamment : + +```text +src/lib.rs comme façade/reexports +src/tauri.rs comme assemblage Tauri et pont Web/Rust +modules propriétaires séparés +tauri.conf.json / capabilities / permissions +hooks frontend Vite +tauri-plugin-tracing / @fltsci/tauri-plugin-tracing +organisation frontend HTML/Sass/TypeScript +``` + +### 5.3 Android existant + +Auditer `Android/` et les documents Android existants pour distinguer : + +```text +baseline Android SDL3/Java/JNI +host Tauri Android de 0.3.1 +``` + +Ils peuvent partager des contraintes plateforme, SDK/NDK ou documentation, mais ne doivent pas être confondus ni couplés artificiellement. + +### 5.4 Toolchains réelles + +Inventorier ce qui est réellement disponible dans l'environnement utilisateur : + +```text +Rust targets Android nécessaires +Tauri CLI/version réellement utilisée +Android SDK +Android NDK +Java/JDK +Gradle/tooling éventuellement piloté par Tauri +adb +émulateur/AVD éventuel +appareil réel éventuel +Node/npm +``` + +Ne pas déclarer un smoke appareil/émulateur possible avant de confirmer qu'une cible est effectivement accessible. + +### 5.5 Sizing et plan + +Créer ou réviser obligatoirement le plan de `0.3.1` sous : + +```text +docs/plans/ +``` + +Le plan doit contenir : + +- objectif et scope ; +- décisions acquises ; +- risques/dépendances utiles ; +- hors-périmètre ; +- validations prévues ; +- découpage prévisionnel souple jusqu'à `0.3.1` stable ; +- tranche de validation large ; +- tranche de consolidation documentaire ; +- RC gelée ; +- release stable mécanique. + +Si le sizing montre que Tauri Android complet ne tient pas raisonnablement dans une session, réduire ou scinder le scope avant l'implémentation lourde. + +## 6. Contraintes architecturales gelées + +Préserver les frontières suivantes : + +```text +game-snake-poc + gameplay et règles de jeu + +engine-v1-common + contrats moteur portables + +engine-v1-platform-api + provenance/capabilities plateforme + +game-snake-poc-wasm + adaptation WASM Snake + +host Web direct / host Tauri + lifecycle, DOM/WebView, inputs physiques, packaging et UI +``` + +Règles spécifiques : + +- `game-snake-poc` reste indépendant de Tauri, Android, DOM, Canvas et providers ; +- ne pas copier le gameplay dans TypeScript, Java ou le backend Tauri ; +- conserver `game-snake-poc-wasm` comme adapter WASM tant qu'un besoin réel ne justifie pas une extraction ; +- ne pas généraliser `Web/game-snake-poc` avant observation du second consommateur ; +- une extraction commune Web/WebView n'est autorisée que si deux consommateurs réels prouvent sa valeur ; +- `lib.rs` d'une app Tauri reste une façade/reexport ; +- `tauri.rs` assemble Tauri et délègue aux modules propriétaires ; +- les traces frontend Tauri utilisent le bridge tracing prévu par les règles, pas des `console.*` applicatifs dispersés ; +- ne pas réintroduire d'orchestrateur Python de build ; +- ne pas utiliser `scripts/build_reflex_tauri_wasm.py` pour le nouveau chemin `0.3.x` ; +- ne pas introduire réseau realtime, Uroburas, ads, billing ou leaderboard dans `0.3.1`. + +## 7. Frontend Tauri et commandes Web + +Le frontend Tauri peut reprendre les conventions de shell déjà éprouvées dans les applications Desk KSP et dans le POC existant lorsque cela reste pertinent : + +```text +Vite +TypeScript +HTML/Sass +Bootstrap 5 / thème retenu +Font Awesome +SimpleBar + ResizeObserver si le layout le nécessite +``` + +Mais appliquer `CMD-WEB-005` : pour une application Tauri, `npm run dev` et `npm run build` sont possédés par les hooks Tauri et ne deviennent pas automatiquement des gates manuelles indépendantes. + +Ne pas traiter le host Tauri comme le host navigateur direct de `0.3.0` : le mode de lancement, le packaging, les permissions et les smokes sont différents. + +## 8. Provenance attendue + +Le host Tauri Android doit produire une provenance distincte du navigateur direct. + +`0-pre.1` doit auditer les enums/contrats réels de `engine-v1-platform-api` avant de fixer les valeurs exactes, mais préserver les dimensions : + +```text +platform family +runtime host +execution model +device class +input profile +``` + +Ne pas ajouter une identification matérielle fine uniquement pour ce POC. + +## 9. Documentation des crates/packages + +Pendant `0-pre.1`, appliquer `DOC-CRATE-*` à tout composant créé ou finalisé. + +La question doit être explicitement tranchée pour la nouvelle app Tauri : + +```text +README.md ? + responsabilité / frontières / architecture locale / points d'entrée + +USAGE.md ? + prérequis / commandes / installation / lancement / smoke opérateur +``` + +Ne pas créer des fichiers vides ou redondants. Si la documentation centrale couvre réellement un petit adapter, le plan peut documenter pourquoi un fichier local séparé n'apporte rien. + +Lors de la consolidation finale, refaire cette revue pour chaque crate/package considéré durable dans `0.3.1`. + +## 10. Deltas, history et état validé + +Ne pas confondre : + +```text +deltas// + décrit la livraison candidate + base requise + fichiers ajoutés/modifiés/supprimés + décisions + validations à exécuter + validations non exécutées + +history// + décrit un jalon effectivement validé + résultats réellement fournis par l'utilisateur + défauts acceptés/corrigés + état transmis au jalon suivant +``` + +Une entrée `history/` n'est jamais pré-écrite pour le delta courant. Après validation utilisateur, le delta suivant ou son fix crée l'entrée historique du jalon accepté conformément à `DOC-HIST-*`. + +Les anciens fichiers de `deltas/` et `history/` restent immuables sur le fond. + +## 11. CHANGELOG, ROADMAP, plan et prompt suivant + +Appliquer ces responsabilités sans les mélanger : + +### Plan + +`docs/plans/` porte le suivi fin et vivant de `0.3.1`. Il est créé/révisé en `0-pre.1` puis réconcilié lorsqu'un résultat réel modifie la trajectoire. + +### ROADMAP + +`ROADMAP.md` reste macroscopique. Le modifier lorsqu'un scope est ajouté, réalisé, reporté ou annulé ; ne pas ajouter une ligne pour chaque prerelease/fix. + +### CHANGELOG + +`CHANGELOG.md` est une synthèse de publication. Les `pre`, `alpha`, `beta` et fixes ne créent normalement pas d'entrée. Écrire la synthèse candidate à partir de la RC, puis la synthèse stable lors de la release. + +### Prompt de la version suivante + +Rédiger le prompt suivant pendant la consolidation finale de `0.3.1` lorsque la cible `0.3.2` est suffisamment connue. La première RC gelée vérifie/complète le prompt à partir de l'état réellement candidat à publication. + +Ne jamais présenter dans ce prompt futur une validation RC/stable qui n'a pas encore été exécutée. + +## 12. Commandes et matrice de validation + +Ne pas inventer une procédure de commandes parallèle dans le prompt. + +Sources normatives : + +```text +docs/rules/RULES_COMMANDS.md +docs/rules/RULES_VALIDATION_MATRIX.md +``` + +`RULES_COMMANDS.md` définit quand utiliser les audits, Cargo, Web, Android, Tauri et les smokes. + +`RULES_VALIDATION_MATRIX.md` définit les IDs `CMD-*`, leurs dépendances et leurs déclencheurs. + +Chaque delta sélectionne les commandes proportionnelles à son scope. Une commande non exécutée n'est jamais déclarée PASS. + +Après modification Rust, la base habituelle reste : + +```bash +cargo fmt --all +cargo fmt --all -- --check +python3 scripts/audit_rust_workspace_rules.py +python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android Web deltas history +python3 scripts/audit_distribution_layout.py +cargo check --workspace +``` + +Clippy/tests/builds/smokes sont ajoutés selon la matrice et la phase. + +## 13. Qui exécute quoi + +Le générateur peut exécuter les audits statiques en lecture seule afin de préparer un delta. + +Les validations de build/runtime restent côté utilisateur : + +```text +cargo check/clippy/test final +build Tauri Android +Gradle/SDK/NDK lorsque le chemin Tauri les invoque +installation émulateur/appareil +smoke mobile +smoke Web direct de non-régression +smoke Desktop SDL3 si requis +``` + +Ne jamais annoncer un build ou un smoke comme réussi uniquement parce que le code paraît correct. + +Une gate utilisateur propre permet de passer automatiquement à la tranche planifiée suivante sauf instruction contraire. Une gate en échec reste normalement dans un `.fix.N` de la tranche courante. + +## 14. Forecast initial souple + +Le forecast suivant est une hypothèse à confirmer ou corriger en `0-pre.1`. + +### `0-pre.1` — audit / requirements / sizing / plan + +- audit stable `0.3.0` ; +- audit Reflex Tauri/WASM ; +- audit environnement Tauri Android ; +- matrice réutilisation vs duplication ; +- stratégie de build/smoke ; +- plan `0.3.1` ; +- décision README/USAGE attendue pour les nouveaux composants. + +### `0-pre.2` — host Tauri Android Snake minimal + +- nouvelle app Tauri Android au bon emplacement ; +- consommation de l'adapter WASM Snake existant ou adaptation minimale justifiée ; +- premier build natif reproductible ; +- aucune généralisation prématurée. + +### `0-pre.3` — lifecycle / input / assets / provenance / logging + +- lifecycle WebView/mobile ; +- tactile/input ; +- assets ; +- provenance ; +- tracing Rust/Tauri/frontend ; +- erreurs de runtime visibles et sûres. + +### `0-pre.4` — extraction conditionnelle + +Créer uniquement si le second host révèle une duplication partagée réelle entre navigateur direct et Tauri WebView. + +Sinon omettre la tranche. + +### `2-beta.1` — validation large + +- workspace complet ; +- build Tauri Android ; +- smoke émulateur/appareil disponible ; +- non-régression Web direct ; +- non-régression Desktop SDL3 lorsque nécessaire ; +- vérification dépendances/package/distribution. + +### `2-beta.2` — consolidation documentaire + +- documentation durable ; +- README/USAGE réellement nécessaires ; +- plan réconcilié ; +- history ; +- ROADMAP selon le scope réellement livré ; +- préparation du prompt `0.3.2` ; +- matière de CHANGELOG prête sans créer une entrée beta artificielle. + +### `3-rc.1` — candidate gelée + +- scope fonctionnel gelé ; +- entrée RC du `CHANGELOG.md` ; +- matrice RC ; +- reproductibilité packaging ; +- prompt `0.3.2` vérifié/complété ; +- seulement bugs/release blockers ensuite. + +### `0.3.1` — stable + +Release mécanique de la RC validée : versions finales, synthèse stable, delta/release et tag selon le workflow applicable. + +La numérotation est révisable. Les responsabilités ne doivent pas être fusionnées uniquement pour raccourcir artificiellement la version. + +## 15. Hors-périmètre explicite + +Ne pas ouvrir dans `0.3.1` sans décision de replanification : + +```text +Tauri Desktop Snake comme nouveau produit +refonte générale engine-v1 +engine-v2 +Android SDL3 multi-ABI supplémentaire +nouveau framework frontend générique +serveur realtime +WebSocket/WebTransport/QUIC gameplay +Uroburas +ads/billing +leaderboard/auth +refactor massif de Reflex +mise à niveau opportuniste des dépendances +``` + +Une dépendance peut être mise à jour uniquement si elle est nécessaire au chemin `0.3.1` et que le delta le documente. + +## 16. Packaging et fichiers générés + +Respecter : + +```text +../builds/sasedev-games/ +``` + +pour les sorties Cargo/Tauri/Vite et caches concernés. + +Ne pas livrer : + +```text +node_modules/ +dist/ +target/ +bindings wasm générés +caches +secrets +lockfiles interdits par les règles du dépôt +``` + +Le ZIP d'un delta contient uniquement les fichiers ajoutés/modifiés par la tranche plus son document de delta, et les suppressions éventuelles utilisent le manifest contractuel prévu. + +## 17. Première séquence de travail de la session + +À l'ouverture de `0.3.1` : + +1. vérifier que la base fournie correspond réellement à la stable `0.3.0` ; +2. lire les sources de vérité dans l'ordre indiqué ; +3. lire le dernier `history/0.3.0` et le delta/release stable ; +4. exécuter les audits statiques applicables à la baseline ; +5. auditer `game-reflex-poc-tauri` et le chemin Tauri Android disponible ; +6. auditer `game-snake-poc-wasm` et le host Web direct ; +7. inventorier SDK/NDK/Tauri/adb/AVD/appareil réellement accessibles ; +8. produire requirements, risques, hors-périmètre et sizing ; +9. créer le plan `0.3.1` sous `docs/plans/` ; +10. seulement ensuite ouvrir le premier delta de développement. + +## 18. Condition de fin de session + +La session est dimensionnée pour fermer `0.3.1` jusqu'à sa stable. + +Une prerelease n'est pas une cible normale de fin de session. Si le sizing ou une contrainte externe rend l'objectif trop grand, reporter explicitement le scope non indispensable vers `0.3.2+` plutôt que prolonger indéfiniment `0.3.1`. + +La stable doit arriver avec : + +```text +scope validé +builds/smokes applicables validés +documentation durable réconciliée +history complet des jalons acceptés +ROADMAP cohérente +CHANGELOG RC/stable cohérent +prompt de la version suivante prêt et vérifié +delta/release mécanique sans nouveau scope +```