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.
.env	Fournir les valeurs d'environnement locales KSP/KSPB du runtime lorsqu'elles ne viennent pas du processus externe.	Fichier local non versionné et non échangé ; lu puis, à terme, modifié uniquement par ksp-config-lib. L'environnement du processus garde priorité sur cette source.
.env.example	Inventorier le contrat versionné de toutes les variables d'environnement runtime KSP/KSPB utilisées par les fichiers Config ou le code.	Ajouter la variable dans le même delta que sa première utilisation. Chaque entrée est précédée d'un commentaire décrivant son usage ; elle peut être active avec une valeur par défaut/générique non secrète ou rester commentée. Ce fichier ne contient jamais de vrai secret.
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/rules/PROMPT_STRUCTURE.md	Définir la structure, le cycle de vie et le dimensionnement des prompts/sessions KSP.	Modifier lorsque le contrat des prompts ou les règles de découpage de sessions/prereleases changent.
docs/architecture/000-README.md	Indexer les documents décrivant l'architecture KSP décidée ou en cours de cadrage explicite.	Modifier lorsque la structure documentaire d'architecture change.
docs/architecture/*.md	Décrire les objectifs, frontières, responsabilités et architecture courante ou explicitement proposée.	Ne pas utiliser comme journal de livraison ; distinguer clairement les décisions validées des hypothèses encore ouvertes.
docs/plans/000-README.md	Indexer les plans de versions/phases.	Modifier lorsque l'organisation des plans change.
docs/plans/*.md	Organiser une version ou phase complexe et, pour pre.001, détailler la prévision souple de ses prereleases.	Faire évoluer le plan lorsque la planification change ; prévoir des tranches intermédiaires bornées et redécouper toute tranche estimée trop lourde.
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.
futurs documents de référence	Définir vocabulaire, identifiants et références canoniques.	Mettre à jour quand la référence canonique évolue.
futures validations	Conserver des résultats réellement exécutés.	Ne jamais enregistrer une validation supposée comme réussie.

Répertoire config/

Fichier/famille	Responsabilité	Règle de modification
config/std.<domain>.json	Document runtime spécialisé Config possédé par ksp-config-lib.	Identifié par un file_id stable, validé par son schema enregistré et lu/modifié uniquement via Config. Comme JSON ne porte pas de commentaires de header, la version du format appartient au champ JSON format_version.
config/composite.<consumer>.json	Composition runtime propre à un consumer concret.	Référence uniquement des documents standards par file_id; son descriptor référence schema.composite tant qu’un schema spécialisé n’est pas requis. Aucun composite runtime fictif n’est créé avant l’existence du consumer.
config/schemas/*.schema.json	JSON Schema des documents Config gérés.	Identifié par un file_id schema.*; le schema doit être valide pour le draft déclaré avant validation d'une instance. Aucun secret/runtime local ne doit y apparaître.
config/examples/*.json	Exemples versionnés séparés des vrais fichiers runtime.	Doivent rester schema-valides et illustratifs ; ils ne constituent jamais une source runtime implicite.

Les noms physiques sont remplaçables via le registre Config lorsque le contrat le permet ; les consumers référencent les documents par file_id, pas par filename.

Le fichier runtime d'environnement est toujours ./.env pour 0.1.3. Il n'est ni un document config/ ni une source de bootstrap de cfgpath/schemapath. Le template .env.example est la référence versionnée permettant de créer localement .env et d'identifier par diff les nouvelles clés attendues.

La persistance management des documents Config et du .env utilise un fichier temporaire créé dans le même répertoire puis un remplacement par rename après validation/écriture/synchronisation. Les documents JSON sont sérialisés lisiblement avec newline final. Le writer préserve les permissions d'un fichier existant ; sur Unix, un .env nouvellement créé par Config reçoit le mode 0600. Les mutations .env ciblées préservent les lignes/commentaires non concernés et ne modifient jamais l'environnement du processus.

Pour config/std.logging.json, logs_directory accepte un chemin absolu ou relatif. Après interpolation, un chemin relatif est ancré sur le current working directory du processus au moment où Config construit LoggingSettings. Une valeur explicitement définie mais vide/invalide ne retombe jamais sur le fallback logs. Les files[].path restent relatifs sous ce root et sont revalidés après interpolation afin d'interdire un chemin absolu ou un traversal introduit dynamiquement.

Pour un document standard profilé, default_profile et profiles sont des clés structurelles réservées. Les autres propriétés top-level sont des valeurs globales. Chaque entrée de profiles possède un profile_id unique ; default_profile référence obligatoirement l'un de ces identifiants. La résolution Config peut sélectionner le profil par défaut ou un profil explicite et conserve séparément la provenance Global / Profile de la vue effective. Les consumers ne reconstituent jamais eux-mêmes cette fusion.

Répertoire prompts/

Fichier/famille	Responsabilité	Règle de modification
prompts/000-README.md	Point d'entrée des prompts et de leur cycle de vie.	Modifier lorsque l'organisation pratique des prompts change ; les règles normatives restent sous docs/rules/PROMPT_STRUCTURE.md.
prompts/*START_PROMPT*.md	Conserver un prompt de reprise versionné et réutilisable pour ouvrir une phase/version de travail.	Le créer tôt sous forme de brouillon lorsque la trajectoire devient assez claire, le mettre à jour au fil des décisions, puis le finaliser pendant la phase documentaire de clôture avant son utilisation.

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 ; ils seront traités lorsqu'ils apparaîtront.

Documentation durable des crates et applications

Une crate ou un composant considéré comme complété possède un README.md descriptif durable.

Une bibliothèque complétée possède également un USAGE.md sans notes de version. Ce guide privilégie la surface publique et fournit un exemple d'utilisation pour chaque API publique destinée à être consommée directement ; plusieurs APIs étroitement liées peuvent être démontrées dans le même exemple lorsque le flux réel les compose. Les notes de release restent dans CHANGELOG.md et les deltas.

Une application Tauri complétée possède un USAGE.md orienté opérateur décrivant les fenêtres, leurs rôles, les actions disponibles et les flux usuels.

Le README.md d'une application Tauri n'est jamais chargé comme contenu de présentation de l'interface. Si l'application possède une vue/fenêtre de présentation Markdown, elle utilise un fichier dédié :

PRESENTATION.md

Ce fichier est optionnel. Une application monofenêtre sans présentation ne le crée pas. Lorsqu'il existe :

• il est destiné au renderer Markdown embarqué de l'application (markdown-it est la référence historique KSP lorsqu'un renderer est nécessaire) ;
• il ne contient aucun lien navigable Markdown ou HTML susceptible de provoquer une navigation hors du flux Tauri ;
• il reste distinct du README.md de package et du USAGE.md opérateur.