khadhroony-bot3/RULES_GENERAL.md

<!-- file: RULES_GENERAL.md -->
<!-- version: 3 -->

# 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

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