khadhroony-bot3/docs/rules/RULES_GENERAL.md

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

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.