Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.9-pre.012-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-24 20:56:04 +02:00
parent 813a45385a
commit 5b30bb9948
5 changed files with 260 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/rules/FILE_CONTRACTS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/FILE_CONTRACTS.md -->
<!-- version: 17 -->
<!-- version: 18 -->
# Contrats des fichiers
@@ -20,25 +20,25 @@ Les règles `FILE-*` définissent la responsabilité et le mode de modification
| `.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. |
| `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 ; pour une clôture de release, réserver sa synchronisation finale à la dernière prerelease de publication et 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 uniquement dans la dernière prerelease de préparation de publication ; ne pas le finaliser dans la prerelease de réconciliation README/USAGE et 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/formats/000-README.md` | Indexer les spécifications de formats durables KSP destinées à l'interopérabilité externe. | Modifier lorsqu'un format durable entre/sort de cette famille ou que son statut change ; conserver `000-README.md` comme point d'entrée. |
| `docs/formats/*.md` | Spécifier un wire KSP durable indépendamment de son implémentation, avec encodages, limites, parsing, auth et vecteurs. | Modifier avec traçabilité lorsqu'un contrat de format évolue ; après publication stable d'une version de format, toute incompatibilité de wire ouvre une nouvelle version de format plutôt qu'une tolérance silencieuse. |
| `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. |
| 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/formats/000-README.md` | Indexer les spécifications de formats durables KSP destinées à l'interopérabilité externe. | Modifier lorsqu'un format durable entre/sort de cette famille ou que son statut change ; conserver `000-README.md` comme point d'entrée. |
| `docs/formats/*.md` | Spécifier un wire KSP durable indépendamment de son implémentation, avec encodages, limites, parsing, auth et vecteurs. | Modifier avec traçabilité lorsqu'un contrat de format évolue ; après publication stable d'une version de format, toute incompatibilité de wire ouvre une nouvelle version de format plutôt qu'une tolérance silencieuse. |
| `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 les couloirs de fermeture. Sa réconciliation finale appartient à l'avant-dernière prerelease documentaire, pas à la dernière prerelease de publication. |
| `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. La validation finale est réconciliée et fermée dans l'avant-dernière prerelease documentaire, avant la dernière prerelease de publication. |
## Répertoire `config/`
@@ -61,10 +61,10 @@ Pour un document standard profilé, `default_profile` et `profiles` sont des cl
## 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. |
| 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 et le mettre à jour au fil des décisions ; sa finalisation appartient exclusivement à la dernière prerelease de préparation de publication, avec CHANGELOG et ROADMAP. |
## Répertoire `deltas/`
@@ -72,6 +72,12 @@ Pour un document standard profilé, `default_profile` et `profiles` sont des cl
|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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`. |
## Séparation des fichiers pendant la fermeture
La prerelease de réconciliation documentaire possède la dernière passe sur les README/USAGE, plans, validations et références durables de la release. Après son gate, ces familles sont considérées figées pour la préparation de publication.
La dernière prerelease ne rouvre pas ces documents : son payload fonctionnel est limité au prompt suivant, `CHANGELOG.md` et `ROADMAP.md`, en plus des fichiers mécaniques de version/delta exigés par le workflow. Si un document durable doit encore être corrigé, une nouvelle prerelease documentaire est ouverte et la tranche de publication finale est décalée.
## Rust
| Fichier/famille | Responsabilité | Règle de modification |

42
docs/rules/PROMPT_STRUCTURE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Structure des prompts KSP
@@ -19,8 +19,42 @@ Sauf raison explicitement documentée :
- `pre.001` = lectures obligatoires + audit interne/externe + brainstorming + sizing + planification ;
- les prereleases intermédiaires = tranches bornées de développement/validation ;
- la dernière prerelease = validation finale + documentation + nettoyage/archivage + prompt de la release suivante ;
- une `fix` corrige l'étape réellement livrée sans réécrire l'historique.
- la fermeture réserve des prereleases distinctes pour le gate technique/live, la réconciliation documentaire puis la préparation de publication ;
- la dernière prerelease avant `rel.NNN` est une tranche de publication minimale, distincte de la réconciliation documentaire et des smokes ;
- une `fix` corrige uniquement la responsabilité de la tranche à laquelle il est rattaché et ne sert pas à absorber un autre couloir de fermeture.
## Séparation obligatoire des dernières prereleases
La queue de fermeture d'une release est structurée de manière à empêcher qu'un correctif de dernière minute mélange tests réseau, documentation durable et préparation de publication.
Lorsqu'un smoke final ou un autre gate live est pertinent, les trois dernières responsabilités sont ordonnées ainsi :
```text
pre.N-2 gate technique/live : smoke(s), graphes ou vérifications finales directement liées au runtime
pre.N-1 réconciliation documentaire : plan, validation, README, USAGE et autres références durables concernées
pre.N préparation de publication : prompt suivant + CHANGELOG + ROADMAP uniquement
rel.001 mécanique de publication stable
```
Les numéros `N-2`, `N-1` et `N` sont relatifs : l'insertion d'une tranche ou d'une correction décale la numérotation réelle sans affaiblir cette séparation.
Si aucun smoke/gate live final n'existe, le couloir `pre.N-2` est omis ; les deux dernières prereleases restent néanmoins séparées entre réconciliation documentaire et préparation de publication.
La dernière prerelease ne modifie fonctionnellement que :
```text
prompt de démarrage de la release suivante
CHANGELOG.md
ROADMAP.md
```
Les fichiers mécaniques imposés par le workflow restent autorisés : `Cargo.toml` pour la version d'une prerelease non-fix et `deltas/<X.Y.Z>/pre.NNN.md` pour sa traçabilité. Aucun README, USAGE, plan, validation, code, test, schema, config ou règle normative ne doit être introduit ou corrigé dans cette dernière tranche.
La prerelease documentaire immédiatement précédente possède la réconciliation finale des documents durables de la release : README/USAGE, plan, validation, architecture/référence concernée et cohérence documentaire globale. Elle ne finalise ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt de la release suivante.
Le gate technique/live, lorsqu'il existe, précède cette réconciliation documentaire. Les smokes et leurs corrections restent donc isolés avant que les documents finaux soient figés.
Un `fix` reste local à son couloir. Si un défaut d'une responsabilité antérieure est découvert après avoir avancé, il ne doit pas être glissé dans le `fix` de la tranche courante : une nouvelle tranche dédiée à la responsabilité concernée est ouverte, puis les couloirs de fermeture postérieurs sont rejoués si nécessaire. La livraison `rel.NNN` ne sert jamais à absorber un correctif fonctionnel ou documentaire qui aurait dû être traité en prerelease.
## Dimensionnement
@@ -28,6 +62,8 @@ Lors de `pre.001`, une prerelease intermédiaire estimée à plus d'environ **15
La trajectoire initiale est **souple** : elle indique un nombre prévisionnel de prereleases, leur objectif et leur ordre, mais autorise l'insertion de tranches/fixes lorsqu'un audit ou une validation révèle un besoin réel. La fermeture ne doit jamais être forcée pour respecter un numéro prévu.
La prévision `pre.001` réserve explicitement les couloirs de fermeture applicables : gate technique/live éventuel, réconciliation documentaire, puis préparation de publication minimale. Leur numérotation peut dériver, mais leur ordre et leur séparation de responsabilités restent normatifs.
## Structure obligatoire d'un prompt de démarrage
Un prompt de nouvelle session contient explicitement, dans un ordre facile à retrouver :

12
docs/rules/VERSION_WORKFLOW.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/VERSION_WORKFLOW.md -->
<!-- version: 6 -->
<!-- version: 7 -->
# Versionnement, sessions et livraisons
@@ -69,6 +69,14 @@ Les règles `VER-*` définissent la progression des versions KSP, les identifian
- **VER-LIFECYCLE-001** — La première prerelease d'une nouvelle phase fonctionnelle est prioritairement consacrée au brainstorming, à l'inventaire, aux risques, dépendances, hors-périmètre, critères de validation et plan de travail.
- **VER-LIFECYCLE-002** — Une phase importante ne commence pas directement par des modifications fonctionnelles dispersées sans cadrage.
- **VER-LIFECYCLE-003** — La dernière prerelease d'une phase est prioritairement consacrée aux validations finales, écarts résiduels, documentation finale, synthèse changelog et prompt de reprise.
- **VER-LIFECYCLE-003** — La dernière prerelease avant `rel.NNN` est une tranche de préparation de publication minimale. Hors `Cargo.toml` et delta obligatoires, elle ne modifie que le prompt de démarrage de la release suivante, `CHANGELOG.md` et `ROADMAP.md`.
- **VER-LIFECYCLE-004** — Le document de planification établi ou révisé pendant `pre.001` d'une version détaille une prévision souple des prereleases de cette version : objectifs de chaque tranche, ordre envisagé, dépendances, validations et éventuels hors-périmètre. Cette prévision peut être réorganisée lorsque la réflexion ou le développement le justifie ; le delta trace ces changements.
- **VER-LIFECYCLE-005** — Le `ROADMAP.md` n'est pas obligé de reprendre une entrée par prerelease. Il décrit la trajectoire globale ; le plan de version porte le découpage prévisionnel plus fin des prereleases.
- **VER-LIFECYCLE-006** — La prerelease immédiatement antérieure à la dernière prerelease de publication est dédiée à la réconciliation documentaire finale : plan, validation, README, USAGE et autres documents durables concernés. Elle ne finalise pas `CHANGELOG.md`, `ROADMAP.md` ni le prompt de la release suivante.
- **VER-LIFECYCLE-007** — Lorsqu'un smoke final, un test live ou un gate réseau/provider est requis, une prerelease technique dédiée précède la prerelease de réconciliation documentaire. Cette tranche peut également porter les graphes et contrôles techniques finaux directement liés au gate, mais elle ne mélange pas la réconciliation README/USAGE ni la préparation de publication.
- **VER-LIFECYCLE-008** — Lorsqu'aucun smoke/gate live final n'est pertinent, la tranche technique dédiée peut être omise ; les deux dernières responsabilités restent obligatoirement séparées entre réconciliation documentaire puis préparation de publication.
- **VER-LIFECYCLE-009** — Un correctif `pre.NNN-fix.MMM` reste strictement dans le périmètre de responsabilité de `pre.NNN`. Un fix de smoke ne corrige pas README/USAGE/CHANGELOG/prompt ; un fix documentaire ne contient pas de nouveau smoke/runtime ; un fix de publication ne contient pas de correction documentaire durable hors `CHANGELOG.md`, `ROADMAP.md` et prompt suivant.
- **VER-LIFECYCLE-010** — Si une anomalie appartenant à un couloir antérieur est découverte après son franchissement, elle ouvre une nouvelle prerelease dédiée à cette responsabilité au lieu d'être mélangée au fix de la tranche courante. Les couloirs postérieurs sont ensuite rejoués si nécessaire afin que la dernière prerelease reste une préparation de publication minimale.
- **VER-LIFECYCLE-011** — Le plan établi en `pre.001` réserve explicitement, dans sa prévision souple, le gate technique/live éventuel, la réconciliation documentaire et la préparation de publication. La numérotation peut évoluer, mais l'ordre de ces responsabilités ne doit pas être fusionné pour raccourcir artificiellement la release.
- **VER-LIFECYCLE-012** — Une livraison `rel.NNN` effectue la mécanique de publication stable et ne sert pas de tranche de rattrapage. Tout nouveau défaut fonctionnel, test live manquant, correction README/USAGE/validation, ou préparation CHANGELOG/ROADMAP/prompt non achevée renvoie vers une prerelease appropriée avant `rel.NNN`.