# Règles générales du projet ## Hiérarchie normative - Les règles sont réparties entre `RULES_GENERAL.md`, `RULES_RUST.md` et `RULES_SPECIFIC_KHADHROONY.md`. - Les trois fichiers sont normatifs et cumulatifs. - En cas de conflit, la règle la plus stricte s’applique. - Une règle spécifique ne peut jamais assouplir une règle générale sans exception explicite, bornée et documentée. - `RULES.md` est l’index de lecture obligatoire et ne duplique pas les règles détaillées. - Avant toute tranche de travail, relire les quatre fichiers de règles, le prompt actif, `README.md`, `ROADMAP.md` et `CHANGELOG.md`. - Toute divergence documentaire est corrigée avant le code. ## Fichiers et nomenclature documentaire - Tous les noms de fichiers et de répertoires sont en anglais, sans accent, espace ou caractère spécial inutile. - Les fichiers Markdown du projet sont rédigés en français, sauf contrat externe ou documentation technique devant rester en anglais. - Tout fichier texte qui supporte des commentaires commence par son chemin relatif et une version entière. - Chaque fichier texte se termine par exactement une fin de ligne. - Les documents livrés sont au format Markdown lorsqu’un format textuel suffit. ## Responsabilités documentaires - `README.md` décrit le projet, son rôle, ses objectifs et son organisation ; il ne sert pas de changelog. - `ROADMAP.md` contient les futures étapes, versions et changements prévus. - `CHANGELOG.md` n’est modifié qu’après validation explicite d’une version. - Les documents de session et checklists conservent des critères d’acceptation vérifiables. - Chaque crate publique possède un `README.md` ou `001.README.md` et, à la clôture de la migration, un `USAGES.md`. - Une API publique ajoutée ou modifiée n’est pas considérée comme documentée tant que la documentation de sa crate n’est pas synchronisée. ## Travail par tranches - Commencer par les règles et les audits structurels. - Travailler par deltas courts et cohérents. - Corriger immédiatement les erreurs locales remontées. - Ne pas masquer les erreurs métier par des exceptions globales. - Ne pas déclarer une tâche validée sans commande, test, audit ou contrôle runtime correspondant. - Une validation non exécutée doit être indiquée comme telle. ## Frontières JSON et JavaScript - Tout payload de commande, d’événement ou d’IPC traversant une frontière JSON ne doit jamais exiger un `bigint` JavaScript. - Pour un entier Rust borné et garanti représentable par l’interface, utiliser un override TS-rs `number`. - Lorsque l’exactitude au-delà de `Number.MAX_SAFE_INTEGER` est nécessaire, sérialiser explicitement une chaîne décimale côté Rust et exporter `string`. - Ne jamais construire un `BigInt` dans un objet transmis à une commande, un événement ou une API sérialisée en JSON. ## Helpers de contrôle - Les scripts Python, shell ou autres helpers d’audit sont strictement en lecture seule vis-à-vis du code et de la documentation contrôlés. - Un helper peut rechercher, analyser et signaler des erreurs ou motifs potentiellement suspects, mais ne doit jamais réécrire, reformater, renommer, supprimer ou corriger automatiquement un fichier du workspace. - Les résultats des helpers sont des diagnostics à vérifier ; une recherche heuristique ou regex ne constitue pas à elle seule une preuve de non-conformité. - Les helpers peuvent inclure des recherches regex ciblées, notamment sur les chemins Rust longs comme `crate::module::Item`, afin de faciliter une revue manuelle des façades et réexports. - Toute modification du code reste une action explicite, séparée de l’audit, et doit apparaître dans le delta correspondant. ## Livraisons delta - Après le squelette initial, livrer uniquement des ZIP delta sauf demande explicite d’archive complète. - Un delta touchant la racine ou plusieurs modules se nomme `khadhroony-bot3_vX.Y.Z-pre.abc-delta.zip`. - Un delta limité à un package Rust se nomme `kb-modulename_vX.Y.Z-pre.abc-delta.zip`. - Un correctif d’un delta déjà livré conserve le même numéro de prerelease et utilise `-delta-fix-001.zip`, puis `-fix-002.zip`, etc. - La numérotation des correctifs recommence à `fix-001` pour chaque nouvelle prerelease. - Le numéro de prerelease suivant est réservé à une nouvelle tranche fonctionnelle. - Chaque archive contient un `delta.md` à sa racine. Son titre et son en-tête ne contiennent aucun numéro de version, de prerelease ou de correctif. - `delta.md` liste : base requise, correctifs antérieurs requis, fichiers ajoutés, fichiers modifiés, fichiers à supprimer, validations exécutées, validations non exécutées et remarques d’application. - Chaque fichier à supprimer est accompagné d’une commande indépendante `rm -- ` directement copiable depuis la racine du workspace. - Le ZIP ne contient que les fichiers ajoutés ou modifiés et `delta.md`. - Les suppressions sont documentées dans `delta.md`, car l’extraction d’un ZIP ne supprime rien. - Toute livraison exclut les fichiers locaux, secrets, caches, sorties de compilation et artefacts régénérables, même lorsqu’ils existent dans le workspace de développement. - Sont notamment exclus : `Cargo.lock`, `package-lock.json`, `node_modules/`, `target/`, `dist/`, `gen/`, les bindings TS-RS générés, `__pycache__/`, les logs, les PID, les bases locales, `data/`, `dbdata/`, les fichiers d’IDE et les fichiers de configuration locale. - Les fichiers `.env` et `.env.*` sont exclus, sauf exemples explicitement publiables tels que `.env.example` et profils sans secret expressément autorisés. - `Cargo.lock` peut être nécessaire dans le workspace local pour stabiliser une résolution transitive, mais il reste non versionné et non livrable dans ce projet. - `package-lock.json` reste non versionné et non livrable ; les dépendances frontend sont restaurées depuis `package.json`. - `delta.md` constitue l’unique exception aux motifs locaux `delta*.md` : il est généré pour la livraison et doit être placé à la racine du ZIP. - Aucun manifeste de livraison n’est généré ou inclus : ni `manifest.json`, ni manifeste SHA, ni liste de checksums. - Aucune empreinte SHA256 n’est produite ou incluse dans les livraisons. - Une archive déjà livrée ne doit jamais être remplacée silencieusement sous le même nom. ## Contrôle minimal avant livraison ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py ``` Les validations supplémentaires dépendent du périmètre du delta et sont consignées dans `delta.md`.