0.0.3-alpha.3

docs/plans/003-V0_0_3_TEMPLATES_AUDITS_PLAN.md

@@ -1,11 +1,11 @@
 <!-- file: docs/plans/003-V0_0_3_TEMPLATES_AUDITS_PLAN.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Plan 0.0.3 — templates initiaux et audits réutilisables
 
 ## Statut et sources
 
-Plan de cadrage créé dans `0.0.3-alpha.1` et corrigé dans `0.0.3-alpha.1.fix.1` après sa validation mécanique. `alpha.2` intègre la convention opérateur sur les fichiers d'outillage Rust et matérialise les premiers templates. Les tranches suivantes sont une prévision, non un état validé.
+Plan de cadrage créé dans `0.0.3-alpha.1` et corrigé dans `0.0.3-alpha.1.fix.1` après sa validation mécanique. `alpha.2` intègre la convention opérateur sur les fichiers d'outillage Rust et matérialise les premiers templates ; sa gate opérateur est PASS. Après cette gate, la demande de décomposer les audits de style Rust KSP/Games modifie le calendrier prévisionnel. Le résultat REPLAN de `alpha.3` est `SPLIT` : deux audits de style ciblés sont traités d'abord, les manifests Cargo puis les headers Markdown suivent dans des tranches distinctes. Les tranches suivantes restent une prévision, non un état validé.
 
 La source autoritaire est l'archive Gitea fournie `pgr-v0.0.2.zip`, issue selon l'opérateur du tag `v0.0.2`. Son SHA-256 vérifié localement est :
 
@@ -84,13 +84,21 @@ Les spécifications complètes de skeleton restent réservées à `0.0.4` ; Rust
 
 ## Sélection des audits et patterns
 
-Les deux audits existants (`tables`, `liens locaux`) sont les premiers patterns concrets : une propriété chacun, sélection explicite de chemins, lecture seule, messages déterministes et aucune invocation de toolchain. Ils doivent rester séparés.
+Les deux audits Markdown existants (`tables`, `liens locaux`) restent séparés : une propriété chacun, sélection explicite des chemins et lecture seule. Le contrôle récurrent des headers Markdown demeure un candidat prioritaire, possédé par `docs/rules/300-DOCUMENTATION.md`, à extraire dans une tranche distincte avec cas positifs et négatifs.
 
-Un contrôle supplémentaire de headers Markdown est candidat prioritaire. La propriété est précise : pour chaque fichier Markdown choisi, comparer `<!-- file: ... -->` à son chemin relatif et vérifier `<!-- version: N -->` avec `N >= 1`. Son owner est `docs/rules/300-DOCUMENTATION.md`, son sujet réel est le corpus de `73` Markdown PGR, et les gates précédents répètent ce contrôle en Python inline. Ni le compilateur ni les deux scripts existants ne le couvrent. Sa matérialisation doit garder la sélection de chemins explicite et tester au moins un header erroné, un header correct et un chemin absent.
+La comparaison des scripts Python KSP `0.3.16` et Games `0.3.5` montre que `audit_rust_general_rules.py` (~580 lignes dans chaque corpus) mélange headers et versions Rust, imports, rustdoc, structure des items, blancs, constantes et modules. `audit_rust_export_completeness.py` possède le contrat particulier des façades et réexports ; KSP ajoute `audit_ksp_workspace_rules.py` pour manifests/frontières/tracing, tandis que Games regroupe plusieurs intégrations Web/Android/Gradle dans `audit_distribution_layout.py`. `audit_rust_workspace_rules.py` est un orchestrateur ; il peut rester un lanceur sans devenir propriétaire de ces contrats.
 
-Les archives KSP et Games contiennent les mêmes familles `audit_rust_general_rules.py` et `audit_rust_export_completeness.py`, et un orchestrateur `audit_rust_workspace_rules.py`. Leur ressemblance vient de règles partagées entre ces projets ; les scripts généraux agrègent déjà plusieurs propriétés, telles que headers Rust, placement des imports, rustdoc, ordre d'items et façade publique. KSP ajoute un audit spécifique des dépendances/owners et Games un audit de layout avec des chemins Web/Android et versions Gradle propres au jeu. Un orchestrateur peut rester utile pour une gate, mais ne devient pas un nouvel audit propriétaire de plusieurs règles.
+| Propriété                                | Owner                   | Suite                                  |
+|------------------------------------------|-------------------------|----------------------------------------|
+| Ordre interne des `use` et `mod`         | Rustfmt                 | `cargo fmt --all -- --check`           |
+| Diagnostics du langage et des lints      | Rust/Clippy             | Outils officiels du projet             |
+| Espacement des lignes vides              | Profil `510` facultatif | `audit_rust_blank_lines.py`            |
+| Blocs de constantes racine               | Profil `510` facultatif | `audit_rust_const_blocks.py`           |
+| Headers, rustdoc, API, tests, plateforme | Profils locaux          | Audits séparés uniquement si justifiés |
 
-Pour PGR, les candidats réutilisables à étudier après les templates Cargo sont : vérification du miroir `VERSION`/`workspace.package.version` lorsque le projet déclare une seule unité de release, vérification de l'héritage explicite des lints dans les crates et éventuel contrôle d'une façade publique uniquement dans un profil qui possède ce contrat. Chacun exigerait un owner, un sujet réel et une propriété isolée ; Cargo/Clippy doivent rester responsables des erreurs qu'ils savent déjà détecter. Aucune de ces idées ne justifie un script Rust spécialisé dans ce fix documentaire. Le contrôle manuel du pairing delta/history reste suffisant à ce stade.
+Le balayage préalable des vrais sources `crates/**/src/**/*.rs` donne `300` fichiers KSP et `59` Games. Le contrôle des blancs passe les deux corpus. Un tri naïf de toutes les constantes racine trouve `17` signaux dans KSP et zéro dans Games ; plusieurs listes KSP sont ordonnées par contrat de protocole ou de schéma. Cela interdit de déclarer le tri globalement obligatoire ou de corriger ces fichiers sans revue. Les scripts livrés sont des patrons facultatifs : le propriétaire d'un projet choisit le sous-ensemble de sources concerné, applique `cargo fmt` avant ces audits et conserve l'ordre sémantique là où il existe. Un petit helper lexical partagé masque commentaires et littéraux ; il n'est pas un troisième audit ni un parseur Rust exhaustif. Les limites et le mode d'emploi sont dans `docs/validation/002-RUST_STYLE_AUDITS.md`.
+
+Les autres candidats demeurent conditionnels : miroir `VERSION`/`workspace.package.version` si une release unit est partagée, héritage explicite des lints dans les crates et façade publique seulement lorsqu'un projet possède ce contrat. Aucun audit spécialisé de ces domaines ni de layout Android/Web n'est justifié par le dépôt documentaire PGR lui-même.
 
 ## Trajectoire prévisionnelle
 
@@ -104,17 +112,21 @@ Après le history et le commit de `alpha.1`, documenter la comparaison réelle d
 
 ### alpha.2 — outillage Rust/Cargo partagé
 
-Créer les templates `rustfmt.toml`, `clippy.toml` et `.cargo/config.toml` à partir du noyau éprouvé dans KSP et Games. Documenter les responsabilités distinctes : formatage, paramètres Clippy, sortie Cargo hors du dépôt. Le nom du projet, l'édition Rust et les seuils ajustables sont explicités au point de copie ; vérifier syntaxe et chemins relatifs. Les niveaux de lint dans `Cargo.toml` restent à la tranche suivante, qui les reliera au profil Clippy retenu.
+Créer les templates `rustfmt.toml`, `clippy.toml` et `.cargo/config.toml` à partir du noyau éprouvé dans KSP et Games. Documenter les responsabilités distinctes : formatage, paramètres Clippy, sortie Cargo hors du dépôt. Le nom du projet, l'édition Rust et les seuils ajustables sont explicités au point de copie ; vérifier syntaxe et chemins relatifs. Les niveaux de lint dans `Cargo.toml` restent à `alpha.4` après le REPLAN, qui les reliera au profil Clippy retenu.
 
-### alpha.3 — manifests Cargo workspace et crate membre
+### alpha.3 — audits de style Rust découpés (REPLAN : SPLIT)
 
-Fournir des modèles minimaux de `Cargo.toml` racine et membre, incluant l'héritage des métadonnées et des lints et une explication des variations de scope. Vérifier les exemples sur un workspace d'essai sans recopier les listes de dépendances, versions et chemins de KSP/Games. Si les modèles exigent trop de décisions pour former des fichiers TOML valides, livrer des extraits complets avec procédure de substitution documentée, sans prétendre qu'un placeholder est prêt à compiler.
+Suite à la demande post-gate `alpha.2`, isoler deux contrôles réutilisables des scripts composites KSP/Games : espacement des lignes vides et blocs de constantes racine sans ordre sémantique. Posséder leur convention facultative dans le profil `510`, documenter sélection/limites et exécuter des cas ciblés positifs et négatifs. Vérifier sur les corpus réels que les ordres contractuels ne deviennent pas de faux changements imposés. Les manifests initialement prévus ici passent à `alpha.4` : aucune validation anticipée n'est déduite du PASS de `alpha.2`.
 
-### alpha.4 — audit de headers Markdown
+### alpha.4 — manifests Cargo workspace et crate membre
 
-Extraire le contrôle récurrent en un script read-only monotâche, documenter sa portée dans la matrice et vérifier des cas positifs et négatifs utiles. Ne pas fusionner cet audit avec les deux audits Markdown existants. Les autres audits candidats restent à l'étude jusqu'à un sujet/owner avéré.
+Fournir des modèles minimaux de `Cargo.toml` racine et membre, incluant l'héritage des métadonnées et des lints et une explication des variations de scope. Vérifier les exemples sur un workspace d'essai lorsque la toolchain est disponible, sans recopier les listes de dépendances, versions et chemins de KSP/Games. Si les modèles exigent trop de décisions pour former des fichiers TOML valides, livrer des extraits complets avec procédure de substitution documentée, sans prétendre qu'un placeholder est prêt à compiler.
 
-### alpha.5 — décision sur le template de workflow
+### alpha.5 — audit de headers Markdown
+
+Extraire le contrôle récurrent en un script read-only monotâche, documenter sa portée dans la matrice et vérifier des cas positifs et négatifs utiles. Ne pas fusionner cet audit avec les deux audits Markdown existants.
+
+### alpha.6 — décision sur le template de workflow
 
 Factoriser le prompt manuel seulement si la revue des prompts et du workflow confirme un bénéfice net ; sinon constater explicitement son report et passer à la stabilisation sans artefact artificiel.
 
@@ -132,6 +144,6 @@ Promouvoir la RC validée, produire le history de clôture pré-tag, committer e
 
 ## Points de décision et validation
 
-Le plan doit être revu si les manifests Cargo exigent des choix de projet incompatibles avec un modèle minimal, si l'audit de headers ne peut rester fiable et monotâche, si le template de workflow duplique le plan, ou si un autre examen des corpus révèle des contraintes nouvelles. Un REPLAN explicite indique `CONTINUE`, `SPLIT`, `CONTINUE-NEXT-SESSION` ou `ABANDON` ; la durée d'une conversation ne crée pas une nouvelle version.
+Le résultat `SPLIT` de `alpha.3` répond à la découverte post-gate de contrôles de style Rust utiles mais mêlés dans deux scripts de référence. Le plan doit encore être revu si les manifests Cargo exigent des choix de projet incompatibles avec un modèle minimal, si l'audit de headers ne peut rester fiable et monotâche, si le template de workflow duplique le plan, ou si un autre examen des corpus révèle des contraintes nouvelles. Un REPLAN explicite indique `CONTINUE`, `SPLIT`, `CONTINUE-NEXT-SESSION` ou `ABANDON` ; la durée d'une conversation ne crée pas une nouvelle version.
 
 La validation `alpha.1` a porté sur l'identité de `VERSION`, la portée du delta, les headers et audits Markdown, l'absence de changement historique rétroactif et le contrôle Git du dépôt de l'opérateur. Ses résultats observés sont conservés dans `history/0.0.3/alpha.1.md`. Le fix documentaire décrit ci-dessus possède sa propre gate et son propre history : le PASS de `alpha.1` ne vaut pas validation anticipée de `alpha.1.fix.1`.

docs/rules/510-RUST_CARGO.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/510-RUST_CARGO.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Profil Rust / Cargo
 
@@ -129,7 +129,11 @@ L'édition de ce fichier MUST rester cohérente avec l'édition réellement util
 
 Après une modification Rust, `cargo fmt --all` applique le formatage canonique puis `cargo fmt --all -- --check` vérifie l'état livré. Une modification produite uniquement par le formatter officiel ne crée pas artificiellement une nouvelle révision documentaire d'un fichier si aucun contenu réel n'a changé.
 
-Les micro-règles de mise en page qui ne sont pas communes aux corpus ou qui sont déjà correctement possédées par `rustfmt` ne sont pas élevées automatiquement au niveau PGR.
+Le profil de style strict supplémentaire peut être adopté par un projet qui souhaite appliquer les conventions KSP/Games. Dans ce scope choisi, les lignes vides consécutives SHOULD être supprimées, ainsi que les lignes vides à l'intérieur des fonctions/méthodes et des définitions `struct`/`enum`. Ces propriétés ne sont pas entièrement possédées par Rustfmt. L'audit facultatif `scripts/audit_rust_blank_lines.py` contrôle ces deux formes d'espacement sur les seuls fichiers Rust sélectionnés.
+
+Les constantes de module qui constituent un bloc homogène sans ordre sémantique SHOULD être regroupées dans l'ordre `pub`, `pub(crate)`, privé, puis par nom dans chaque visibilité : aucune ligne vide entre constantes d'une même visibilité et exactement une entre niveaux différents. `scripts/audit_rust_const_blocks.py` vérifie cette convention uniquement sur les constantes au niveau racine des fichiers choisis. Son exécution requiert une sélection explicite des fichiers pour lesquels cet ordre est réellement souhaité. Une table de protocole, une séquence de migrations ou tout autre ordre contractuel conserve son ordre propre ; le lecteur ne doit pas réordonner une telle séquence pour faire passer l'audit.
+
+L'ordre des `use`, réexports et déclarations `mod` que Rustfmt sait réordonner dans ses groupes appartient au formatteur ; les modules de test après les modules de production et l'organisation d'une façade relèvent de leur contrat local, avec revue ou audit dédié seulement si celui-ci apporte une preuve fiable. Les règles rustdoc et d'API conservent leurs propriétaires ci-dessus. Les scripts PGR ne prétendent pas parser toutes les macros ou les items Rust : une décision sémantique reste une revue.
 
 ## Configuration Cargo et artefacts générés
 
@@ -188,4 +192,4 @@ Lorsqu'une règle Rust devient objectivement automatisable dans un projet ou ske
 
 Un éventuel wrapper d'orchestration MAY appeler plusieurs audits, mais chaque audit propriétaire doit conserver une responsabilité identifiable et rester read-only.
 
-Aucun nouvel audit Rust n'est imposé par cette tranche à PGR lui-même : le dépôt PGR courant ne contient pas de workspace Rust sur lequel une telle gate fournirait une preuve réelle.
+Les deux audits de style disponibles sont documentés dans [`../validation/002-RUST_STYLE_AUDITS.md`](../validation/002-RUST_STYLE_AUDITS.md). Ils restent optionnels et prennent un corpus Rust explicitement sélectionné ; le dépôt PGR lui-même ne contient pas de workspace Rust sur lequel une telle gate fournirait une preuve réelle.

docs/templates/001-RUST_CARGO_TOOLING.md

@@ -1,5 +1,5 @@
 <!-- file: docs/templates/001-RUST_CARGO_TOOLING.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Templates d'outillage Rust/Cargo
 
@@ -11,7 +11,7 @@ Ces trois fichiers fournissent une baseline de configuration issue des conventio
 - [`clippy.toml`](../../templates/rust-cargo/clippy.toml) — paramètres de lints (seuils, exceptions de tests, identifiants courts) issus du noyau partagé des deux projets ;
 - [`.cargo/config.toml`](../../templates/rust-cargo/.cargo/config.toml) — emplacements des artefacts Cargo hors de la racine source.
 
-Les niveaux `deny`, `allow`, `warn` et `forbid` des lints Rust/Clippy appartiennent au `Cargo.toml` du workspace, selon [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). `clippy.toml` règle des paramètres de lints, pas leur niveau. Les modèles de manifests racine et membre, ainsi que l'héritage `[lints] workspace = true`, sont prévus dans la tranche suivante.
+Les niveaux `deny`, `allow`, `warn` et `forbid` des lints Rust/Clippy appartiennent au `Cargo.toml` du workspace, selon [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md). `clippy.toml` règle des paramètres de lints, pas leur niveau. Les modèles de manifests racine et membre, ainsi que l'héritage `[lints] workspace = true`, sont prévus en `alpha.4` après l'extraction des audits de style de `alpha.3`.
 
 ## Copier et adapter
 

docs/validation/001-VALIDATION_MATRIX.md

@@ -1,5 +1,5 @@
 <!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Matrice de validation PGR
 
@@ -32,6 +32,12 @@ Un contrôle manuel peut rester dans la matrice lorsqu'aucun audit automatisé f
 
 PGR préfère plusieurs audits simples avec une responsabilité identifiable à un script unique qui agrège des règles indépendantes.
 
+## Contrôles Rust réutilisables, hors gate du dépôt PGR
+
+[`002-RUST_STYLE_AUDITS.md`](002-RUST_STYLE_AUDITS.md) décrit deux audits facultatifs : `audit_rust_blank_lines.py` contrôle l'espacement des lignes vides, `audit_rust_const_blocks.py` contrôle l'ordre et l'espacement des blocs de constantes au niveau racine. Ils acceptent des chemins Rust sélectionnés et partagent un petit support lexical ; leur validation ciblée dans PGR est `python3 -B -m unittest discover -s tests -p test_rust_audits.py`.
+
+Leur disponibilité ne transforme pas PGR en workspace Rust et ne rend pas automatiquement l'ordre alphabétique applicable à chaque fichier d'un projet. Lors d'une adoption, le projet propriétaire sélectionne ses chemins après `cargo fmt` et applique sa propre gate ; Rustfmt et Clippy conservent les contrôles qu'ils possèdent.
+
 ## Politique Eclipse actuelle
 
 Les métadonnées Eclipse spécifiques à une machine restent ignorées, notamment `.project`, `.classpath` et les préférences non partagées.

docs/validation/002-RUST_STYLE_AUDITS.md

@@ -0,0 +1,34 @@
+<!-- file: docs/validation/002-RUST_STYLE_AUDITS.md -->
+<!-- version: 1 -->
+
+# Audits facultatifs de style Rust
+
+## Responsabilité et provenance
+
+Les sources KSP `0.3.16` et Games `0.3.5` possèdent chacune un `audit_rust_general_rules.py` qui mêle plusieurs règles. Le découpage PGR fournit deux contrôles ciblés sans copier l'orchestrateur ni les règles propres aux deux projets. Le contrat de style facultatif est dans [`510-RUST_CARGO.md`](../rules/510-RUST_CARGO.md), et la sélection des preuves dans [`400-VALIDATION.md`](../rules/400-VALIDATION.md).
+
+`scripts/audit_rust_blank_lines.py` contrôle les lignes vides consécutives et les lignes vides dans un corps de fonction/méthode, `struct` ou `enum`. `scripts/audit_rust_const_blocks.py` contrôle l'ordre `pub`, `pub(crate)`, privé, le tri naturel des noms dans chaque visibilité et l'espacement entre constantes consécutives au niveau racine du fichier. `scripts/_rust_audit_common.py` partage la sélection des chemins et le masquage des commentaires/littéraux : il ne définit aucune nouvelle politique.
+
+## Adoption et commandes
+
+Dans un projet Rust qui choisit ces conventions, copier les trois fichiers `scripts/*.py` concernés en gardant le helper à côté des deux audits. Adapter les headers `file` au chemin du projet et maintenir une révision de fichier propre à cette copie.
+
+Choisir explicitement les fichiers concernés par chaque contrat. Après formatage :
+
+```bash
+cargo fmt --all -- --check
+python3 -B scripts/audit_rust_blank_lines.py crates/example/src
+python3 -B scripts/audit_rust_const_blocks.py crates/example/src/constants.rs
+```
+
+Une invocation sans chemin est une erreur, de même qu'un chemin absent ou aucun fichier Rust sélectionné. Un répertoire sélectionne récursivement les fichiers `.rs` hors répertoires générés habituels. Les audits ne modifient ni les fichiers inspectés ni l'arborescence de build. Les sorties utilisent le chemin et la ligne ; le code de sortie est `0` si propre, `1` pour violation, `2` pour sélection/lecture impossible.
+
+Ne sélectionner pour l'audit des constantes que les fichiers dont les blocs racine sans sémantique d'ordre doivent effectivement suivre ce contrat. Un tri de table de protocole, des migrations, des champs de wire format ou de toute séquence métier peut casser le programme : sa revue appartient au projet. Ne pas utiliser la sortie du script comme justification pour les réordonner.
+
+## Limites mesurées
+
+La prévalidation des sources réels a porté sur `300` fichiers KSP et `59` Games sous `crates/**/src/`. L'audit des lignes vides n'y détecte aucun écart. L'audit de constantes détecte `17` signaux KSP et aucun Games lorsque tous ces fichiers lui sont soumis ; des fichiers KSP contiennent des séquences ordonnées selon le protocole ou le schéma, ce qui rend une gate globale du tri inappropriée. Ces observations ne sont pas une gate de validation opérateur PGR.
+
+L'analyse lexicale masque littéraux et commentaires courants, y compris commentaires imbriqués et chaînes Rust brutes. Elle n'est pas un parseur Rust : les macros élaborées, syntaxe nouvelle, attributs complexes, items associés dans `impl` et constantes dans modules inline n'entrent pas dans le contrat garanti de l'audit des blocs racine. Les lignes vides à l'intérieur d'un littéral multilignes sont exclues. Les cas qui demandent une interprétation sémantique nécessitent la revue humaine ou les outils Rust du projet.
+
+Rustfmt reste propriétaire de l'ordre qu'il réécrit déjà dans les groupes de `use`/`mod`. Clippy et le compilateur restent responsables de leurs diagnostics. La suite `tests/test_rust_audits.py` vérifie les propriétés ciblées avec des cas propres, des violations et des littéraux/commentaires qui contiennent des accolades.