diff --git a/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md b/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md index ae45a7a..f376dfb 100644 --- a/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md +++ b/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md @@ -1,5 +1,5 @@ - + # Clôture de la migration `khadhroony-bot3` @@ -79,7 +79,7 @@ Ce fichier est temporaire. Il doit disparaître lorsque la migration est close, ## 1.1 Règles - [x] Reprendre dans les règles Bot3 toutes les règles Bot2 encore applicables. -- [x] Remplacer les anciens fichiers de règles par `RULES_GENERAL.md`, `RULES_RUST.md`, `RULES_SPECIFIC_KHADHROONY.md` et un index `RULES.md`. +- [x] Remplacer les anciens fichiers de règles par `docs/rules/RULES_GENERAL.md`, `docs/rules/RULES_RUST.md`, `docs/rules/RULES_SPECIFIC_KHADHROONY.md` et un index `RULES.md`. - [x] Adapter le workflow des deltas à Bot3. - [ ] Effectuer une dernière lecture croisée des règles portant sur imports, réexports, façades, Tauri, TS-RS, logging, versionnement et archives. - [ ] Supprimer de cette checklist toute demande de justification historique sans valeur normative. diff --git a/RULES.md b/RULES.md index 89b7583..012bc88 100644 --- a/RULES.md +++ b/RULES.md @@ -1,16 +1,21 @@ - + -# Index des règles `khadhroony-bot3` +# Index normatif de `khadhroony-bot3` -La lecture des fichiers suivants est obligatoire avant toute modification : +`RULES.md` est l’unique fichier de règles conservé à la racine du workspace. Il constitue le point d’entrée obligatoire et renvoie vers les règles détaillées maintenues sous `docs/rules/`. -1. [`RULES_GENERAL.md`](RULES_GENERAL.md) — gouvernance documentaire, méthode de travail et livraisons delta ; -2. [`RULES_RUST.md`](RULES_RUST.md) — règles Rust réutilisables ; -3. [`RULES_SPECIFIC_KHADHROONY.md`](RULES_SPECIFIC_KHADHROONY.md) — architecture et conventions propres au workspace. +La lecture des documents suivants est obligatoire avant toute modification : + +1. [`docs/rules/RULES_GENERAL.md`](docs/rules/RULES_GENERAL.md) — gouvernance, méthode de travail, documentation et livraisons ; +2. [`docs/rules/RULES_RUST.md`](docs/rules/RULES_RUST.md) — règles Rust réutilisables ; +3. [`docs/rules/RULES_SPECIFIC_KHADHROONY.md`](docs/rules/RULES_SPECIFIC_KHADHROONY.md) — architecture et conventions propres au workspace ; +4. [`docs/rules/CRATE_DOCUMENTATION_RULES.md`](docs/rules/CRATE_DOCUMENTATION_RULES.md) — contrat des `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md` de crates. Ces règles sont cumulatives. En cas de conflit, la règle la plus stricte s’applique. Une exception doit être explicite, locale, bornée et documentée. +Les documents de `olddocs/` sont historiques et non normatifs. Ils peuvent servir de sources pour réécrire une documentation bot3, mais ne doivent pas être copiés ou activés automatiquement. + Toute tranche commence par : ```bash @@ -18,4 +23,4 @@ cargo fmt --all python3 scripts/audit_rust_workspace_rules.py ``` -La migration ne peut être déclarée terminée qu’après validation de la checklist active et des critères de clôture. +Une validation n’est déclarée réussie que si elle a réellement été exécutée. diff --git a/docs/DOCUMENTATION_REFACTOR_AUDIT.md b/docs/DOCUMENTATION_REFACTOR_AUDIT.md index d10ca0c..337c17b 100644 --- a/docs/DOCUMENTATION_REFACTOR_AUDIT.md +++ b/docs/DOCUMENTATION_REFACTOR_AUDIT.md @@ -1,5 +1,5 @@ - + # Audit de refonte documentaire @@ -19,9 +19,9 @@ Les fichiers suivants existent à la racine : - `CHANGELOG.md` ; - `ROADMAP.md` ; - `RULES.md` ; -- `RULES_GENERAL.md` ; -- `RULES_RUST.md` ; -- `RULES_SPECIFIC_KHADHROONY.md` ; +- `docs/rules/RULES_GENERAL.md` ; +- `docs/rules/RULES_RUST.md` ; +- `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ; - `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md`. ### 2.2 Documentation active bot3 @@ -123,7 +123,7 @@ Le workspace déclare 11 crates : Aucune crate ne satisfait donc le contrat complet `README.md`, `TODO.md`, `USAGE.md`, `CHANGELOG.md`. -Une contradiction normative existe dans `RULES_GENERAL.md` : le fichier exige encore un `README.md` ou `001.README.md` et, à terme, un `USAGES.md`. La convention retenue est `USAGE.md`, nom singulier couramment utilisé pour un guide d’utilisation. La règle doit imposer exactement `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md`. +La contradiction `USAGES.md` contre `USAGE.md` est résolue en faveur de `USAGE.md`. `001.README.md` reste autorisé uniquement comme index lexical de répertoire très fourni, notamment sous `idls/`, et ne remplace jamais le `README.md` obligatoire d’une crate. ### 4.4 Frontière de l’archive documentaire @@ -162,8 +162,8 @@ Le déplacement des règles secondaires vers `docs/rules/` ne doit pas être eff Références actives identifiées : - `RULES.md` lie directement les trois fichiers secondaires à la racine ; -- `RULES_GENERAL.md` cite leurs chemins racine et le contrat documentaire obsolète `USAGES.md` ; -- `RULES_SPECIFIC_KHADHROONY.md` lie `RULES_GENERAL.md` et `RULES_RUST.md` par chemins relatifs racine ; +- les scripts, prompts et documents actifs doivent employer les chemins `docs/rules/...` ; +- `docs/rules/RULES_SPECIFIC_KHADHROONY.md` lie `docs/rules/RULES_GENERAL.md` et `docs/rules/RULES_RUST.md` par chemins relatifs racine ; - `scripts/audit_khadhroony_workspace_rules.py` vérifie explicitement les quatre chemins racine à deux endroits ; - les deux prompts bot3 citent les chemins racine ; - `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md` décrit l’organisation actuelle. diff --git a/docs/DOCUMENTATION_REFACTOR_PLAN.md b/docs/DOCUMENTATION_REFACTOR_PLAN.md index 6049211..d5c69f3 100644 --- a/docs/DOCUMENTATION_REFACTOR_PLAN.md +++ b/docs/DOCUMENTATION_REFACTOR_PLAN.md @@ -1,5 +1,5 @@ - + # Plan de refonte documentaire @@ -164,8 +164,8 @@ Aucun document bot3 actif ne doit encore être supprimé. Travail : -1. corriger `RULES_GENERAL.md` pour imposer les quatre fichiers exacts par crate ; -2. supprimer les variantes obsolètes `001.README.md` et `USAGES.md`, et retenir définitivement `USAGE.md` ; +1. corriger `docs/rules/RULES_GENERAL.md` pour imposer les quatre fichiers exacts par crate ; +2. interdire `USAGES.md`, retenir définitivement `USAGE.md` et encadrer l’exception `001.README.md` pour les index lexicaux ; 3. créer `docs/rules/CRATE_DOCUMENTATION_RULES.md` ; 4. définir la frontière entre README, TODO, USAGE, CHANGELOG général et changelogs de crates ; 5. imposer que `USAGE.md` documente uniquement les APIs publiques réellement accessibles ; @@ -182,7 +182,7 @@ Les règles secondaires restent temporairement à la racine dans ce delta. Travail : 1. créer `docs/rules/` ; -2. déplacer `RULES_GENERAL.md`, `RULES_RUST.md` et `RULES_SPECIFIC_KHADHROONY.md` ; +2. déplacer `docs/rules/RULES_GENERAL.md`, `docs/rules/RULES_RUST.md` et `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ; 3. mettre à jour `RULES.md` ; 4. corriger les liens internes ; 5. adapter `scripts/audit_khadhroony_workspace_rules.py` ; diff --git a/docs/rules/CRATE_DOCUMENTATION_RULES.md b/docs/rules/CRATE_DOCUMENTATION_RULES.md index 2a7e4f9..467b269 100644 --- a/docs/rules/CRATE_DOCUMENTATION_RULES.md +++ b/docs/rules/CRATE_DOCUMENTATION_RULES.md @@ -1,5 +1,5 @@ - + # Règles documentaires des crates @@ -16,7 +16,7 @@ USAGE.md CHANGELOG.md ``` -Les variantes `001.README.md`, `USAGES.md` ou tout autre nom concurrent sont interdites dans la documentation active. +`USAGES.md` et les autres noms concurrents sont interdits. `001.README.md` reste autorisé comme index de répertoire lorsque le tri lexical au début d’un répertoire très fourni est utile, par exemple sous `idls/`; il ne remplace jamais le `README.md` obligatoire à la racine d’une crate. Ces fichiers doivent être écrits pour l’architecture actuelle de `khadhroony-bot3`. Les documents de `olddocs/archivekbot2/` sont des sources historiques : leur contenu peut être étudié, vérifié, réinterprété et adapté, mais ne doit jamais être déplacé, copié automatiquement ou rendu normatif sans réécriture explicite. @@ -114,6 +114,8 @@ Une réexportation publique doit être vérifiée jusqu’à son chemin d’acc Chaque API publique significative doit disposer d’au moins un exemple ou être couverte par un exemple de scénario explicitement identifié. Les APIs triviales ou regroupées peuvent partager un exemple lorsqu’il démontre réellement leur usage. +Les tests unitaires peuvent être documentés lorsqu’ils illustrent un contrat public, un invariant, un format canonique ou une régression importante. `USAGE.md` doit alors les référencer et expliquer ce qu’ils démontrent, sans transformer les helpers internes en API publique. + ### 4.4 Crates sans API bibliothèque publique Une crate principalement binaire ou interne conserve un `USAGE.md`. Le document décrit alors ses commandes, entrées, sorties, configuration, contrats d’intégration et limites, sans inventer une API Rust publique. @@ -164,7 +166,7 @@ Une idée encore exploratoire reste dans `docs/IDEA_REMINDERS.md` ou dans un doc Le TODO ne doit pas : -- répéter les travaux déjà terminés ; +- conserver ou répéter les travaux déjà terminés ; - contenir l’historique des corrections ; - recopier le ROADMAP général ; - transformer une hypothèse en obligation ; @@ -186,7 +188,7 @@ Chaque changelog de crate doit contenir au minimum : - l’adoption des nouvelles règles Rust et Khadhroony applicables ; - les validations réellement exécutées et les limitations encore connues. -La section `0.1.0` peut regrouper les prereleases de migration lorsque leur détail exhaustif n’apporte pas de valeur. Les prereleases ou correctifs importants peuvent être conservés lorsqu’ils expliquent une rupture, une correction notable ou une validation structurante. +La section `0.1.0` synthétise la migration initiale. À partir de cette base, le changelog de crate conserve le détail des prereleases et correctifs `fix` qui ont touché la crate, afin de reprendre durablement les informations pertinentes de chaque `delta.md`. ### 6.3 Catégories @@ -206,13 +208,15 @@ Ne pas créer des sections vides. ### 6.4 Versions et corrections -Le changelog distingue clairement : +Le changelog de crate distingue clairement : - version publiée ; - prerelease ; - correctif `fix` ; - changement non publié. +Le changelog général suit une granularité différente : il décrit les changements entre versions fonctionnelles, par exemple de `0.4.6` à `0.4.7`, sans détailler les prereleases ni les correctifs `fix`. Les détails de livraison restent dans les changelogs des crates concernées. + Une modification fonctionnelle de la crate impose une mise à jour de son changelog. Une modification documentaire pure peut être regroupée sous `Non publié / Documentation`. ### 6.5 Provenance bot2 @@ -237,7 +241,7 @@ Les matrices actives maintenues sous : test-fixtures/contract-matrices/ ``` -restent les références canoniques. Elles ne doivent pas être dupliquées dans `docs/`. +restent les références canoniques. Elles servent à la fois de contrats documentaires et de fixtures exécutées par des tests unitaires ou d’intégration. Elles ne doivent pas être dupliquées dans `docs/`. Les documents de crate et de protocole doivent les référencer par lien et expliquer leur rôle, leur portée et leur statut de validation. diff --git a/RULES_GENERAL.md b/docs/rules/RULES_GENERAL.md similarity index 94% rename from RULES_GENERAL.md rename to docs/rules/RULES_GENERAL.md index a6e2f2c..1e85539 100644 --- a/RULES_GENERAL.md +++ b/docs/rules/RULES_GENERAL.md @@ -1,11 +1,11 @@ - + # 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 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. @@ -29,7 +29,8 @@ - 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`. -- Les variantes `001.README.md` et `USAGES.md` sont interdites dans la documentation active. +- `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. diff --git a/RULES_RUST.md b/docs/rules/RULES_RUST.md similarity index 99% rename from RULES_RUST.md rename to docs/rules/RULES_RUST.md index fb414b5..c17117a 100644 --- a/RULES_RUST.md +++ b/docs/rules/RULES_RUST.md @@ -1,4 +1,4 @@ - + # Règles Rust générales diff --git a/RULES_SPECIFIC_KHADHROONY.md b/docs/rules/RULES_SPECIFIC_KHADHROONY.md similarity index 99% rename from RULES_SPECIFIC_KHADHROONY.md rename to docs/rules/RULES_SPECIFIC_KHADHROONY.md index f4c8292..0fcafd2 100644 --- a/RULES_SPECIFIC_KHADHROONY.md +++ b/docs/rules/RULES_SPECIFIC_KHADHROONY.md @@ -1,4 +1,4 @@ - + # Règles spécifiques à `khadhroony-bot3` diff --git a/docs/templates/CRATE_CHANGELOG_TEMPLATE.md b/docs/templates/CRATE_CHANGELOG_TEMPLATE.md index 73002f9..10315fb 100644 --- a/docs/templates/CRATE_CHANGELOG_TEMPLATE.md +++ b/docs/templates/CRATE_CHANGELOG_TEMPLATE.md @@ -1,5 +1,5 @@ - + # Modèle de changelog de crate @@ -28,3 +28,7 @@ ### Limitations connues - Indiquer les fonctionnalités partielles, non raccordées ou non validées. + +## Historique détaillé des livraisons + +Ajouter les prereleases et correctifs `fix` ayant réellement modifié cette crate, en reprenant les informations pertinentes des `delta.md`. diff --git a/docs/templates/CRATE_TODO_TEMPLATE.md b/docs/templates/CRATE_TODO_TEMPLATE.md index 3c6f05b..784227f 100644 --- a/docs/templates/CRATE_TODO_TEMPLATE.md +++ b/docs/templates/CRATE_TODO_TEMPLATE.md @@ -1,5 +1,5 @@ - + # Modèle de TODO de crate @@ -22,3 +22,5 @@ ## Hors périmètre > Ne reprendre une idée de `docs/IDEA_REMINDERS.md` qu’après confirmation, attribution à cette crate et reformulation en tâche vérifiable. + +> Supprimer toute tâche dès que sa réalisation est confirmée et la reporter dans le changelog de la crate. diff --git a/docs/templates/CRATE_USAGE_TEMPLATE.md b/docs/templates/CRATE_USAGE_TEMPLATE.md index 2066a2a..da56f8c 100644 --- a/docs/templates/CRATE_USAGE_TEMPLATE.md +++ b/docs/templates/CRATE_USAGE_TEMPLATE.md @@ -1,5 +1,5 @@ - + # Modèle de guide d’utilisation de crate @@ -39,6 +39,10 @@ Pour chaque API ou groupe cohérent : Supprimer cette section si aucun binaire public n’existe. +## Tests de référence + +Documenter les tests unitaires particulièrement instructifs qui démontrent un contrat public, un invariant, un format canonique ou une non-régression. + ## Limites connues ## Références diff --git a/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md b/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md index 05d0f63..03a910f 100644 --- a/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md +++ b/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md @@ -20,9 +20,9 @@ Avant toute modification de code : 1. relire intégralement : - `RULES.md` - - `RULES_GENERAL.md` - - `RULES_RUST.md` - - `RULES_SPECIFIC_KHADHROONY.md` + - `docs/rules/RULES_GENERAL.md` + - `docs/rules/RULES_RUST.md` + - `docs/rules/RULES_SPECIFIC_KHADHROONY.md` - `README.md` - `ROADMAP.md` - `CHANGELOG.md` @@ -668,9 +668,9 @@ Ils doivent présenter : - aperçu minimal ; - liens vers la documentation détaillée. -### `USAGES.md` +### `USAGE.md` -Créer un `USAGES.md` pour chaque crate publique. +Créer un `USAGE.md` pour chaque crate publique. Contenu : @@ -766,7 +766,7 @@ cargo clippy --all-targets - [ ] démos devnet Metaplex validées ; - [ ] Clippy/Tauri finalisés ; - [ ] refonte documentaire terminée ; -- [ ] `USAGES.md` présent pour chaque crate publique ; +- [ ] `USAGE.md` présent pour chaque crate publique ; - [ ] passage à `0.4.7` justifié. --- diff --git a/prompts/khadhroony-bot3_next-session_after-v0.1.0-pre.062.md b/prompts/khadhroony-bot3_next-session_after-v0.1.0-pre.062.md index 6b93fa7..4ddd077 100644 --- a/prompts/khadhroony-bot3_next-session_after-v0.1.0-pre.062.md +++ b/prompts/khadhroony-bot3_next-session_after-v0.1.0-pre.062.md @@ -157,9 +157,9 @@ README.md CHANGELOG.md ROADMAP.md RULES.md -RULES_GENERAL.md -RULES_RUST.md -RULES_SPECIFIC_KHADHROONY.md +docs/rules/RULES_GENERAL.md +docs/rules/RULES_RUST.md +docs/rules/RULES_SPECIFIC_KHADHROONY.md KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md docs/ olddocs/ diff --git a/scripts/audit_khadhroony_workspace_rules.py b/scripts/audit_khadhroony_workspace_rules.py index a91c23f..7944a3e 100755 --- a/scripts/audit_khadhroony_workspace_rules.py +++ b/scripts/audit_khadhroony_workspace_rules.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # file: scripts/audit_khadhroony_workspace_rules.py -# version: 11 +# version: 12 """Audit mechanically verifiable rules specific to khadhroony-bot3.""" @@ -464,9 +464,9 @@ def audit_token_2022_naming(root: pathlib.Path) -> list[Violation]: root / "README.md", root / "ROADMAP.md", root / "RULES.md", - root / "RULES_GENERAL.md", - root / "RULES_RUST.md", - root / "RULES_SPECIFIC_KHADHROONY.md", + root / "docs/rules/RULES_GENERAL.md", + root / "docs/rules/RULES_RUST.md", + root / "docs/rules/RULES_SPECIFIC_KHADHROONY.md", root / "kb-lib/README.md", ] candidates.extend(sorted((root / "docs").glob("*.md"))) @@ -496,9 +496,9 @@ def audit_private_kb_lib_paths_in_active_docs(root: pathlib.Path) -> list[Violat root / "README.md", root / "ROADMAP.md", root / "RULES.md", - root / "RULES_GENERAL.md", - root / "RULES_RUST.md", - root / "RULES_SPECIFIC_KHADHROONY.md", + root / "docs/rules/RULES_GENERAL.md", + root / "docs/rules/RULES_RUST.md", + root / "docs/rules/RULES_SPECIFIC_KHADHROONY.md", root / "kb-lib/README.md", root / "kb-program-ids/README.md", ]