games/docs/rules/RULES_COMMANDS.md

<!-- file: docs/rules/RULES_COMMANDS.md -->
<!-- version: 13 -->

# Règles d'exécution des commandes

## Principes

- **CMD-GEN-001** — Une commande est exécutée avec un objectif explicite : inspection, formatage, compilation, lint, test, packaging ou diagnostic.
- **CMD-GEN-002** — Une commande mutante n'est pas utilisée lorsqu'une commande de contrôle en lecture seule suffit.
- **CMD-GEN-003** — Les commandes destructives ou de nettoyage global ne sont jamais exécutées par habitude.
- **CMD-GEN-004** — Une gate n'est déclarée réussie que si la commande exacte a été exécutée sur l'état livré.
- **CMD-GEN-005** — Les commandes ciblées sont préférées dès que leur portée est connue ; les gates workspace complètes ne sont imposées que lorsque leur coût est justifié par la portée du changement ou la phase de validation.
- **CMD-GEN-006** — Les scripts `audit_*` sont des contrôles en lecture seule et ne corrigent jamais automatiquement les fichiers.
- **CMD-GEN-007** — Sauf demande explicite contraire, les commandes Cargo de validation finale sont exécutées par l'utilisateur sur son workspace local et non déclarées réussies par le générateur.
- **CMD-GEN-008** — Chaque fichier delta indique les commandes de validation que l'utilisateur doit exécuter et le statut connu de la validation du delta précédent.
- **CMD-GEN-009** — Lorsque l'utilisateur fournit une gate complète propre, le delta est considéré validé et le travail peut passer automatiquement au delta planifié suivant sauf instruction contraire.
- **CMD-GEN-010** — Si une gate échoue, la progression vers le delta suivant est suspendue ; le correctif est livré sous le suffixe `.fix.N` du delta courant, sauf décision explicite contraire.
- **CMD-GEN-011** — Les commandes d'audit Markdown couvrent également `history/` dès que cette arborescence existe.
- **CMD-GEN-012** — Les audits Python sont sélectionnés selon les fichiers réellement touchés : audit Rust/workspace pour le périmètre Rust/Cargo/workspace concerné, audit Markdown pour les fichiers Markdown concernés, audit de distribution pour les changements de layout/build/packaging. Ils ne sont pas tous exécutés par habitude sur chaque delta.
- **CMD-GEN-013** — Toute commande nécessitant un changement temporaire de répertoire est exécutée dans un sous-shell, par exemple `(cd Web/game-snake-poc && npm run build)`, afin de revenir automatiquement à la racine du workspace après la commande.

## Rust et Cargo

- **CMD-RUST-001** — Dès qu'un delta modifie du code Rust, un manifeste Cargo, une feature ou une dépendance Rust, l'utilisateur exécute `cargo fmt --all`; les changements purement produits par rustfmt constituent l'unique exception à l'incrément obligatoire de l'en-tête de version du fichier.
- **CMD-RUST-002** — `cargo fmt --all -- --check` suit le formatage et constitue la gate canonique de conformité rustfmt.
- **CMD-RUST-003** — Tout delta qui touche du code Rust ou ses dépendances exécute `cargo check --workspace` après les audits statiques applicables. Un `cargo check -p <crate>` peut servir de diagnostic rapide, mais ne remplace pas cette gate workspace.
- **CMD-RUST-004** — Tout delta qui touche du code Rust ou ses dépendances exécute ensuite `cargo clippy --workspace --all-targets --all-features -- -D warnings`. Cette gate n'est pas réservée aux seules phases finales.
- **CMD-RUST-005** — Les tests ciblés `cargo test -p <crate> --all-targets --all-features` sont la stratégie normale d'un delta et couvrent les crates directement affectées ainsi que les consommateurs dont le contrat est réellement impacté.
- **CMD-RUST-006** — `cargo test --workspace --all-targets --all-features` est une gate lourde exécutée seulement un petit nombre de fois explicitement prévues dans le plan de version/session, typiquement à une validation initiale si elle apporte une valeur réelle, à une validation préfinale/finale, lors d'un changement transverse important ou lorsqu'il existe un doute raisonnable sur la portée des tests ciblés. Elle n'est pas répétée à chaque delta.
- **CMD-RUST-007** — `cargo run -p <desktop-runner>` sert aux smokes manuels Desktop et n'est pas substitué aux tests automatisés.
- **CMD-RUST-008** — `cargo build` est utilisé lorsqu'un artefact exécutable ou une bibliothèque est réellement nécessaire ; il n'est pas lancé systématiquement en plus de `cargo check`.
- **CMD-RUST-009** — `cargo tree` et ses variantes ne sont exécutés que lorsqu'un delta modifie les dépendances/features, lorsqu'une frontière de dépendances doit être vérifiée ou lorsqu'un diagnostic explicite le justifie. Ils ne font pas partie de la validation automatique d'un delta sans changement de dépendances.
- **CMD-RUST-010** — `cargo update` n'est jamais exécuté opportunistement. Toute mise à jour de dépendance doit appartenir à une tranche explicitement consacrée aux dépendances ou être nécessaire à la fonctionnalité en cours.
- **CMD-RUST-011** — `cargo clean` est l'outil canonique de remise à zéro complète du cache de build Cargo et peut être utilisé périodiquement pour maîtriser la taille de `../builds/sasedev-games/target`.
- **CMD-RUST-012** — Un nettoyage complet n'est pas exécuté à chaque delta. Il est planifié à un jalon de cycle approprié, normalement au démarrage de la première prerelease de développement lorsque l'ancien cache doit être évacué, ou au plus tard avant la validation finale RC/stable si l'accumulation disque le justifie.
- **CMD-RUST-013** — Entre deux nettoyages complets, les variantes ciblées de `cargo clean` (`-p`, `--release`, `--profile`, `--target`) sont préférées lorsqu'elles répondent au besoin de libération d'espace sans supprimer tout le cache.
- **CMD-RUST-014** — `cargo clean --dry-run --verbose` peut être utilisé pour estimer l'impact d'un nettoyage avant suppression.
- **CMD-RUST-015** — La suppression manuelle de `target/` ne remplace pas `cargo clean` et n'est utilisée qu'en diagnostic exceptionnel.

## Runners Desktop

- **CMD-DESKTOP-001** — Chaque jeu possédant une crate lib dispose d'une crate binaire Desktop distincte sous `crates/apps/` dès qu'un smoke local exécutable est utile.
- **CMD-DESKTOP-002** — Le runner Desktop dépend de la crate lib du jeu et ne duplique pas le gameplay.
- **CMD-DESKTOP-003** — Le runner Desktop est la voie privilégiée pour les itérations fonctionnelles rapides qui ne nécessitent pas une capacité Android spécifique.
- **CMD-DESKTOP-004** — Un test Android reste obligatoire pour toute fonctionnalité dépendant du lifecycle, du tactile réel, de JNI, d'Ads, de Billing, de haptique ou d'une API Android.
- **CMD-DESKTOP-005** — Le runner Desktop natif SDL3 est la distribution Desktop de jeu par défaut. Une variante Tauri est optionnelle, distincte et n'est créée que pour un besoin explicite.
- **CMD-DESKTOP-006** — Une variante Tauri dépend de la même crate lib de jeu et ne duplique jamais le gameplay du runner natif.

## Android et Gradle

- **CMD-ANDROID-001** — Les commandes Gradle Android sont exécutées depuis `Android/` ou avec un chemin explicite vers le wrapper du projet.
- **CMD-ANDROID-002** — Les tâches ciblées par application sont préférées, par exemple `./gradlew :game-reflex-poc:assembleDebug`, lorsqu'elles existent.
- **CMD-ANDROID-003** — Un build Android global n'est pas exécuté si la tranche ne touche ni Android ni le contrat natif utilisé par Android.
- **CMD-ANDROID-004** — `gradle clean` ou `./gradlew clean` reste un nettoyage Android ciblé ; il n'est pas rendu obligatoire uniquement parce qu'un `cargo clean` est planifié.
- **CMD-ANDROID-005** — Les commandes Android réelles ne deviennent des gates qu'après introduction du wrapper Gradle, de l'AGP, du NDK, de SDL3 et des modules exécutables correspondants.

## Web

- **CMD-WEB-001** — Aucun gestionnaire de paquets JavaScript ni build Web n'est exécuté tant qu'un frontend Web réel n'a pas été introduit dans le dépôt.
- **CMD-WEB-002** — Lorsqu'une cible Web existe, ses commandes de build et test sont documentées avant d'être ajoutées aux gates.
- **CMD-WEB-003** — Le POC Tauri/WASM historique `0.1.0` utilise `scripts/build_reflex_tauri_wasm.py` ; ce script reste une référence de baseline mais ne doit pas être réutilisé comme orchestrateur par un POC `0.3.x`, conformément à `CMD-BUILD-004`.
- **CMD-WEB-004** — Les fichiers produits par `wasm-bindgen` sont générés localement et ne sont pas commités.
- **CMD-WEB-005** — Dans une app Tauri, `npm` sert uniquement à gérer les dépendances frontend lorsque nécessaire, par exemple `npm i <package>`, `npm i -D <package>` ou leur opération inverse. Les scripts `npm run dev`, `npm run build` ou équivalents ne sont pas des gates manuelles : Vite/TypeScript/WASM sont déclenchés par les hooks Tauri configurés.
- **CMD-WEB-006** — Le smoke normal d'une app Tauri est lancé via `(cd <tauri-app> && cargo tauri dev)`. Cette commande possède le serveur Vite et les hooks frontend nécessaires.
- **CMD-WEB-007** — Le packaging Tauri est validé dans les phases finales prévues par le plan via `(cd <tauri-app> && cargo tauri build)`, typiquement en beta préfinale, RC ou avant release selon le scope. Il n'est pas exécuté après chaque petit delta Tauri.
- **CMD-WEB-008** — Pour un host Web navigateur direct sous `Web/<game>/`, les commandes npm/Vite peuvent être exécutées directement, toujours dans un sous-shell lorsqu'un changement de répertoire est nécessaire, par exemple `(cd Web/<game> && npm install && npm run build)`.
- **CMD-WEB-009** — Le build d'un host Web direct qui consomme un adapter `wasm-bindgen` exécute d'abord le build Rust/WASM et la génération des bindings hors dépôt, puis seulement le build TypeScript/Vite.
- **CMD-WEB-010** — Un smoke navigateur manuel d'un host Web direct vérifie au minimum le chargement WASM, le Canvas, les entrées prévues par la tranche et le comportement responsive concerné.

## Git et fichiers générés

- **CMD-GIT-001** — Les commandes Git destructives (`reset --hard`, nettoyage forcé, réécriture non demandée) ne sont jamais utilisées pour remettre artificiellement le workspace en état.
- **CMD-GIT-002** — Les fichiers générés ne sont pas commités sauf contrat explicite du dépôt ou exigence de distribution.
- **CMD-GIT-003** — Lorsqu'une archive fournie par l'utilisateur est déclarée comme téléchargement d'un tag du dépôt, cette archive est la baseline autoritaire de ce tag. L'absence de `.git` dans l'archive est normale et ne constitue ni une anomalie ni une validation manquante.
- **CMD-GIT-004** — Les contrôles nécessitant le répertoire `.git` s'appliquent uniquement à un checkout Git local lorsqu'il est effectivement fourni ; sur une archive taggée, on contrôle la cohérence interne des versions et fichiers sans inventer un état Git inaccessible.

## Beta et packaging

- **CMD-BETA-001** — À l'entrée en beta, `scripts/audit_distribution_layout.py` vérifie les frontières statiques nécessaires aux runners et packagings supportés.
- **CMD-BETA-002** — La transition alpha vers beta exécute une suite Cargo workspace complète en plus des tests ciblés.
- **CMD-BETA-003** — Si la version touche le périmètre Tauri, le plan réserve au moins une validation de packaging dans une phase finale appropriée via `(cd <tauri-app> && cargo tauri build)` ; les itérations et smokes courants utilisent `cargo tauri dev`.
- **CMD-BETA-004** — Les APK Debug servent à la validation multi-appareils beta ; la signature de publication appartient à la phase RC/stable.

## RC et release

- **CMD-RC-001** — L'entrée en RC gèle le périmètre fonctionnel de la version courante ; seuls les correctifs, la reproductibilité des builds, le packaging, la documentation de livraison et les défauts de release sont admis.
- **CMD-RC-002** — La validation d'une RC exécute `cargo test --workspace --all-targets --all-features` en plus des audits, du check et de Clippy strict.
- **CMD-RC-003** — Les deux runners Desktop natifs sont construits en `--release` et font l'objet d'un smoke sur les binaires de release.
- **CMD-RC-004** — Une RC Tauri est construite via `(cd <tauri-app> && cargo tauri build)` ; ses hooks possèdent toujours le build WASM et Vite/TypeScript. Les smokes interactifs restent lancés avec `(cd <tauri-app> && cargo tauri dev)`.
- **CMD-RC-005** — Android RC revalide au minimum x86_64 sur AVD et ARM64 sur appareil réel avec les APK issus de l'état RC.
- **CMD-RC-006** — Les secrets de signature, keystores et credentials de publication ne sont jamais commités. Leur présence est une condition externe de publication, pas une donnée du dépôt.
- **CMD-RC-007** — Une RC n'est promue en stable que si aucun correctif `.fix.N` n'est nécessaire après la gate RC complète.

## Matrice de validation

- **CMD-MATRIX-001** — `docs/rules/RULES_VALIDATION_MATRIX.md` associe des identifiants stables aux commandes et décrit leurs dépendances.
- **CMD-MATRIX-002** — Lorsqu'une modification affecte une crate dont dépendent d'autres crates, les validations ciblées couvrent la crate modifiée et les consommateurs directement ou transitivement impactés selon la portée de l'API.
- **CMD-MATRIX-003** — La matrice évolue avec le workspace ; ajouter une nouvelle plateforme ou un nouveau type de build doit ajouter ou adapter les commandes concernées plutôt que créer une procédure informelle parallèle.

## Outils de build et scripts d'audit

- **CMD-BUILD-001** — Les scripts Python du dépôt sont autorisés pour les audits, audits complémentaires, validations et validations complémentaires.
- **CMD-BUILD-002** — À partir de `0.3.x`, aucun chemin de build nouveau ou modifié n’est piloté par Python. Les orchestrateurs historiques `scripts/build_reflex_tauri_wasm.py` et `scripts/build_android_rust.py` restent tolérés uniquement comme mécanismes gelés de la baseline `0.1.0` jusqu’à la tranche qui réactive leur chemin ; ils ne sont ni copiés, ni généralisés, ni utilisés pour un nouveau POC.
- **CMD-BUILD-003** — Les builds utilisent l'outil natif approprié au périmètre : Cargo pour Rust, Gradle pour Android, Tauri CLI pour Tauri, ou l'outil officiellement retenu par la plateforme concernée.
- **CMD-BUILD-004** — Les POC `0.3.x` doivent remplacer toute orchestration de build Python restante par des procédures explicites, reproductibles et testées avec les outils natifs.
- **CMD-BUILD-005** — Les builds, tests unitaires, tests d'intégration et smoke tests de validation sont exécutés côté utilisateur ; les scripts d'audit peuvent vérifier statiquement leur préparation mais ne les simulent pas.