khadhroony-solana-project/docs/rules/FILE_CONTRACTS.md

Contrats des fichiers

Portée

Les règles FILE-* définissent la responsabilité et le mode de modification des principales familles de fichiers KSP. Un nouveau type de fichier durable doit recevoir un contrat avant de devenir une convention répétée.

Fichiers racine et configuration Cargo

Fichier	Responsabilité	Règle de modification
.gitignore	Exclure uniquement les artefacts non versionnés décidés par le projet.	Ajouter une exclusion lorsqu'un besoin réel apparaît ; éviter les exclusions spéculatives.
README.md	Présenter KSP, sa finalité, son périmètre général, ses principes et les points d'entrée.	Mettre à jour lorsqu'une définition structurante du projet change ; ne pas y consigner l'historique des versions.
RULES.md	Indexer les règles normatives.	Modifier uniquement lorsque la structure normative ou ses points d'entrée changent.
Cargo.toml	Définir le workspace, sa version Cargo, les métadonnées héritées et les lints communs.	Modifier lors de toute prerelease/release non-fix, lors d'un correctif touchant le code/build/runtime/configuration/migrations, lorsqu'une crate entre/sort du workspace ou lorsqu'un contrat Cargo commun change. Un correctif purement documentaire ou de référence non consommée par le runtime ne force pas un changement de version Cargo.
.cargo/config.toml	Définir les réglages Cargo propres au workspace qui ne relèvent pas du manifeste, notamment l'emplacement des artefacts de build.	Modifier lorsqu'un réglage Cargo commun change ; ne pas y placer de secret ni de configuration spécifique à une machine particulière.
rustfmt.toml	Définir le formatage Rust commun.	Modifier comme changement normatif, avec justification dans le delta.
clippy.toml	Définir les paramètres Clippy communs.	Modifier comme changement normatif, avec justification dans le delta.
ROADMAP.md	Décrire les objectifs globaux et les grandes étapes prévues par phase/version, avec leur état synthétique.	Modifier lorsqu'un objectif, une grande étape, un report, une annulation ou un état global change ; ne pas y recopier le détail des prereleases prévu dans les plans de version.
CHANGELOG.md	Résumer les releases stables dans un ordre chronologique décroissant, sous forme d'un ou plusieurs paragraphes par release.	Synchroniser lors de la phase documentaire finale ; ne pas dupliquer les deltas ni créer de changelog par crate/module.

Répertoire docs/

Fichier/famille	Responsabilité	Règle de modification
docs/000-README.md	Indexer et expliquer la documentation tout en restant en tête des listings et arbres de fichiers.	Modifier lorsque l'organisation durable de docs/ change ; 000-README.md reste prioritaire lorsqu'un ordre numérique existe.
docs/rules/*.md	Définir les règles normatives par portée.	Modifier uniquement pour une décision normative ; incrémenter la version du fichier à chaque enregistrement modifiant son contenu.
docs/IDEAS.md	Conserver les idées, pistes, questions et alternatives à explorer qui ne sont pas encore des engagements du roadmap.	Ajouter une idée dès qu'elle mérite d'être conservée ; mettre à jour son statut lorsqu'elle est explorée, retenue, rejetée ou transférée vers un plan, le roadmap, une règle ou une décision.
futurs documents d'architecture	Décrire l'architecture courante décidée.	Ne pas utiliser comme journal de livraison ; reporter les décisions depuis les deltas/plans.
futurs documents de référence	Définir vocabulaire, identifiants et références canoniques.	Mettre à jour quand la référence canonique évolue.
futurs plans	Organiser une phase ou version complexe.	Ils peuvent évoluer pendant la phase ; leur statut normatif doit être explicite.
futures validations	Conserver des résultats réellement exécutés.	Ne jamais enregistrer une validation supposée comme réussie.

Répertoire deltas/

Fichier	Responsabilité	Règle de modification
deltas/<X.Y.Z>/<delta-name>.md	Tracer une livraison précise, sa base, son contenu, ses suppressions, validations et questions ouvertes, regroupée sous la version cible X.Y.Z.	Créé avec la livraison ; une livraison déjà publiée n'est pas réécrite silencieusement. Les prereleases utilisent pre.NNN, leurs correctifs pre.NNN-fix.NNN, et les publications de release utilisent rel.NNN.

Rust

Fichier/famille	Responsabilité	Règle de modification
crates/<name>/Cargo.toml	Définir un package Rust et ses dépendances/features propres.	Toute dépendance doit correspondre à un usage réel ; les contraintes de version inhabituelles sont documentées.
src/lib.rs	Définir la façade d'une bibliothèque.	Les modules restent privés ; l'API est réexportée explicitement.
src/main.rs	Définir le point d'entrée d'un exécutable Rust.	Ne doit pas devenir un conteneur de logique métier réutilisable.
modules Rust	Porter une responsabilité cohérente.	Un module est séparé ou fusionné selon ses invariants et responsabilités, pas uniquement selon sa taille.
unit_tests/	Porter les tests unitaires physiquement séparés du code de production, en miroir de src/ autant que possible.	Les fichiers restent rattachés sous #[cfg(test)] au module testé afin de conserver l'accès au privé ; cette séparation est utilisée au maximum.
tests/	Porter exclusivement les tests d'intégration Cargo de la crate.	Les tests consomment uniquement l'API publique ; les contrats publics pertinents y sont testés lorsque techniquement possible.

Fichiers générés

• FILE-GEN-001 — Un fichier généré n'est jamais modifié manuellement lorsque sa source de vérité est un générateur.
• FILE-GEN-002 — Le choix de versionner ou ignorer une famille générée est décidé explicitement lorsqu'elle apparaît.
• FILE-GEN-003 — Les futurs artefacts Tauri bindings/ et gen/ ne sont pas encore une convention KSP en 0.0.2-pre.001-fix.001.