# Règles générales du projet ## Hiérarchie normative - Les règles détaillées sont regroupées sous `docs/rules/` et indexées par `RULES.md` à la racine. - 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 membre du workspace possède exactement `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md` à sa racine. - Le contrat détaillé de ces quatre documents est défini dans `docs/rules/CRATE_DOCUMENTATION_RULES.md`. - `USAGES.md` est interdit au profit de `USAGE.md`. - `001.README.md` est autorisé uniquement comme index de répertoire lorsque le tri lexical au début d’un répertoire très fourni apporte une valeur réelle, notamment sous `idls/`; il ne remplace jamais le `README.md` obligatoire à la racine d’une crate. - Les documents actifs de bot3 sont réécrits pour l’architecture actuelle ; aucun document de `olddocs/archivekbot2/` ne doit être déplacé ou repris automatiquement. - Les matrices canoniques de `test-fixtures/contract-matrices/` doivent être référencées, non dupliquées dans `docs/`. - 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 utilise le nom Cargo courant du package : `_vX.Y.Z-pre.abc-delta.zip` (par exemple `ks-config_vX.Y.Z-pre.abc-delta.zip` ou un futur package applicatif `kb-*`). - 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`. ### Fin de fichier et formatters - La contrainte de fin de fichier avec exactement un saut de ligne terminal s’applique aux sources Rust, TypeScript, JavaScript, Python, shell, TOML, YAML et Markdown lorsqu’elle est vérifiée par les outils du projet. - Elle ne s’applique pas aux fichiers HTML ni JSON : leur formatter peut supprimer automatiquement la ligne vide terminale. - Aucun audit ne doit réintroduire artificiellement une ligne vide dans un fichier HTML ou JSON après formatage.