khadhroony-bot3/RULES_GENERAL.md

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 -- <chemin> 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

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.