games/docs/rules/RULES_COMMANDS.md

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

# 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` n'est pas une gate et n'est pas utilisé en routine. Il n'est autorisé qu'en cas de diagnostic de build corrompu, de contrainte disque explicite ou de demande ciblée, avec justification.
- **CMD-RUST-012** — La suppression manuelle de `target/` ne remplace pas `cargo clean` et suit les mêmes restrictions.

## 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` n'est pas une gate normale et suit la même politique restrictive que `cargo clean`.
- **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.