games/docs/rules/RULES_COMMANDS.md

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.

Rust et Cargo

• CMD-RUST-001 — Lorsqu’un delta a modifié au moins un fichier Rust, l’utilisateur exécute cargo fmt --all au début de la validation afin d’appliquer le formatage canonique; 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 immédiatement le formatage et constitue la gate canonique de conformité rustfmt.
• CMD-RUST-003 — cargo check --workspace est la première gate de compilation globale après les audits statiques.
• CMD-RUST-004 — cargo clippy --workspace --all-targets --all-features -- -D warnings est exécuté après un cargo check --workspace propre pour la gate complète.
• CMD-RUST-005 — Les tests ciblés cargo test -p <crate> --all-targets --all-features sont la stratégie normale d’un delta et doivent couvrir toutes les crates directement ou transitivement affectées lorsque cela est raisonnablement déterminable.
• CMD-RUST-006 — cargo test --workspace --all-targets --all-features est une gate lourde réservée au démarrage d’une nouvelle version X.Y.Z, à la fin d’une phase/version, aux changements transverses importants ou lorsqu’il existe un doute raisonnable sur la portée des tests ciblés.
• 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 sont des commandes de diagnostic de dépendances, pas des gates obligatoires de chaque delta.
• 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 utilise scripts/build_reflex_tauri_wasm.py pour WASM et Vite/TypeScript pour le frontend local ; aucun site distant n'est requis.
• CMD-WEB-004 — Les fichiers produits par wasm-bindgen sont générés localement et ne sont pas commités.

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-WEB-005 — npm run dev et npm run build du frontend Tauri sont pilotés par les hooks Tauri ; ils ne constituent pas des gates manuelles indépendantes.

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, au moins un build de packaging beta est lancé via cargo tauri build; ses hooks possèdent le build WASM et Vite/TypeScript.
• 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 0.1.0 ; 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 — Le POC Tauri est construit uniquement via cargo tauri build; ses hooks possèdent toujours le build WASM et Vite/TypeScript.
• 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.