pgr/docs/plans/003-V0_0_3_TEMPLATES_AUDITS_PLAN.md

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 ; 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 :

8dc5c979a4d722b4ef6ec84b6227c8cbfffb3f865f4ea9063c03ecb1e365cdc4

Le rapport séparé pgr-0.0.2-publish.001-report.md indique PASS et donne le même hash. Il atteste la publication post-tag sans appartenir au tag. L'archive sans .git ne peut prouver indépendamment le commit ni l'identité du tag ; ces éléments sont les déclarations et preuves de publication de l'opérateur.

Le contrat de démarrage est prompts/003-V0_0_3_START_PROMPT.md. Les règles applicables partent de RULES.md, puis des familles 200, 210, 300, 400, du modèle de profils 003 et des profils 500/510, 520, 600/610 selon leur scope. PGR reste un dépôt documentaire doté d'outils Python ; les toolchains Rust, Java et Android ne deviennent pas des prérequis du dépôt.

Deux corpus de comparaison supplémentaires, fournis après le gate initial de alpha.1, ont été inspectés pour ce fix documentaire :

khadhroony-solana-project-v0.3.16.zip  SHA-256 db3cc1b3fc3fb07ee864b02e2a7346c673d4cf63b33e8e872aca6c6458856ca0
games-v0.3.5.zip                       SHA-256 5f5fdee1a271386766d059657d6eaa831acdc263b3e722fed738808335c0a105

Ce sont des sources de comparaison pour les décisions de templates et d'audits, non la baseline PGR et non des dépendances de build. Leur présence ne rend pas les conventions locales de KSP ou Games normatives pour tous les projets.

Audit indépendant de la stable v0.0.2

L'inspection de l'archive, sa lecture et la comparaison des fichiers extraits avec les membres ZIP ont établi :

• ZIP lisible, 94 entrées : 78 fichiers et 16 répertoires, une seule racine pgr/ ; aucun doublon, chemin absolu, traversée .., chemin Windows ambigu ou lien symbolique ;
• exactement 78 fichiers extraits ; VERSION contient 0.0.2 avec un seul retour final à la ligne ; .git absent comme attendu ;
• octets des fichiers distribués décodables en UTF-8, sans NUL, CR, espace de fin de ligne ou retour final manquant ;
• 73 fichiers Markdown dont les deux premières lignes correspondent exactement au chemin relatif file et à une révision positive version ;
• contrôle local des deux scripts existants : Markdown table audit: clean (2 table(s), 73 file(s)) et Markdown link audit: clean (50 local link(s), 73 file(s)) ;
• aucun répertoire de build/cache ou fichier local sensible connu dans les chemins distribués ; seule la préférence Eclipse UTF-8 intentionnellement conservée est présente sous .settings/.

La vérification de structure et de gouvernance a constaté :

• 12 deltas et 12 histories appariés exactement dans chacune des séries 0.0.1 et 0.0.2, y compris rel.001 ; chaque history possède un statut explicite ;
• les versions avant/après déclarées dans tous les deltas 0.0.2 forment une chaîne continue de 0.0.1 à 0.0.2 ; les deltas 0.0.1 au format homogène depuis alpha.1.fix.2 forment également une chaîne continue jusqu'à la stable ;
• dans 0.0.1, les FAIL de alpha.1, alpha.1.fix.1, alpha.4 et rc.1 sont suivis d'une tranche corrective PASS ; dans 0.0.2, même traitement pour alpha.1, alpha.4, beta.1 et rc.1 ; les deux rel.001 sont PASS ;
• README.md, ROADMAP.md et CHANGELOG.md présentent 0.0.2 comme terminé et 0.0.3 comme prévu ; les plans 001 et 002 restent historiques ; le prompt 003 nomme l'archive et la preuve post-tag fournies ;
• séparation cohérente entre objectifs durables, architecture, règles normatives, validation, plans, deltas prospectifs, histories rétrospectifs et changelog stable ; les index pointent vers les familles et profils réellement présents ;
• les profils réellement matérialisés sont 510 Rust/Cargo, 520 Java/Maven/Gradle et 610 Android ; les seuls scripts d'audit PGR sont ceux des tableaux et des liens Markdown locaux. Aucun skeleton, générateur ou profil différé n'est présent.

Aucun écart bloquant n'a été constaté dans ces contrôles. Les scripts Markdown ont chacun une portée volontairement limitée : le contrôle des liens vérifie l'existence des cibles inline locales, pas les ancres ; celui des tableaux vérifie leur structure source. Leur PASS n'atteste donc pas des propriétés hors de leur contrat.

Comparaison réelle des corpus Rust

KSP 0.3.16 et Games 0.3.5 possèdent chacun un workspace Cargo virtuel avec resolver = "3" et centralisent réellement dans [workspace.package] version, edition, license, repository, authors et publish. Ils utilisent [workspace.dependencies] pour des dépendances tierces, mais avec respectivement 37 et 19 entrées propres à leur projet. Les deux racines déclarent les mêmes trois lints Rust de base (missing_docs, unreachable_pub, unsafe_code) et les mêmes 18 niveaux Clippy ; les éventuels allow doivent être revus un par un avant réemploi.

Les 22 crates KSP héritent des lints workspace par [lints] workspace = true. Parmi 23 crates Games, 22 utilisent ce même héritage ; l'entrée Android déclare des lints locaux pour ajuster unsafe_code à sa frontière FFI. La capacité d'exception locale est donc réelle et doit être expliquée sans rendre l'exception Android générale.

Les deux rustfmt.toml ont un contenu technique identique et seulement un numéro de révision de fichier différent. Les deux clippy.toml partagent leurs seuils principaux et divergent sur les identifiants courts autorisés et quelques entrées vides. L'opérateur confirme qu'il réutilise ces conventions comme baseline de départ, telles quelles ou avec de petites adaptations. Les deux .cargo/config.toml déplacent les artefacts de build vers ../builds/<projet>/target/ ; Games ajoute des flags Web propres à sa cible. La configuration générique de déplacement est donc retenue avec un nom de projet à remplacer.

Sélection des templates

Retenu : famille Rust/Cargo minimale

Le besoin concret n'est pas limité à rustfmt.toml. La première famille doit couvrir cinq responsabilités distinctes :

1. rustfmt.toml : options communes dont la valeur est justifiée ; alignement de edition avec le projet destinataire ; ne pas reprendre mécaniquement chaque préférence des deux sources ;
2. configuration Clippy : niveaux de lint Rust/Clippy dans les sections Cargo [workspace.lints.rust] et [workspace.lints.clippy], plus clippy.toml pour les seuils et réglages conservés dans le profil de départ éprouvé ; chaque projet peut adapter ces choix ;
3. .cargo/config.toml : target-dir et build-dir vers un dossier frère ../builds/<projet>/target/, après remplacement explicite du nom ; les flags Web et les autres particularités restent locaux ;
4. Cargo.toml workspace : sections [workspace], [workspace.package], [workspace.dependencies] et [workspace.lints.*] avec les responsabilités et champs de décision explicités ; VERSION doit correspondre à workspace.package.version seulement pour une unité de release commune ;
5. Cargo.toml d'une crate membre ordinaire : identité locale, héritage explicite des métadonnées communes et des lints, et dépendances/features limitées aux besoins de la crate. Une adaptation locale des lints doit être documentée comme exception ciblée ; elle ne devient pas un deuxième jeu de valeurs globales.

Ces fichiers ou extraits doivent être copiables et compréhensibles sans figer le nom de projet, la version, les dépendances, le layout de toutes les crates, la publication, la toolchain ni le minimum de plateforme. Lorsqu'un champ obligatoire ne peut pas avoir de valeur générique sûre, des instructions Markdown guident son remplacement avant l'usage ; un fichier TOML présenté comme prêt à l'emploi doit être valide. Les crates bibliothèque et application peuvent partager un tronc commun, leurs différences réelles restant documentées sans créer des dizaines de variantes.

Pour la validation, comparer les templates au profil 510, parser les configs/manifests avec un parseur TOML et exercer sur un workspace d'essai les héritages et le cas d'une exception locale quand les toolchains sont disponibles. Tester rustfmt et Clippy pour les réglages réellement livrés dans un projet Rust concerné ; une compilation de KSP/Games n'est pas une gate de PGR.

Retenu : spécification courte du prompt manuel de nouvelle session

Les prompts 002 et 003 répètent la transmission de la baseline taggée, de la cible et de la première tranche ; 003 ajoute le rapport post-tag et le texte manuel remis à l'opérateur. Après comparaison, alpha.6 retient une courte spécification Markdown des champs et de la phrase de reprise. Elle facilite la prochaine clôture sans créer un générateur, un nouveau prompt versionné prématuré ou une copie du plan. Le rapport ne devient un champ rempli que s'il existe et que son résultat est réellement connu.

Différés

Les fichiers Maven/Gradle complets, wrappers, Android local.properties ou signing, règles .gitignore universelles et versions de dépendances ne sont pas copiés par anticipation. Games fournit un exemple Android concret, mais sa matrice AGP/Gradle/JDK, son build natif et ses flags Cargo Web restent propres à ce projet. Les wrappers restent soumis aux outils officiels et à la décision du projet ; un local.properties entièrement régénéré ne justifie pas d'exemple.

Les spécifications complètes de skeleton restent réservées à 0.0.4 ; Rust/JNI, Web/WASM, Tauri et les autres profils différés n'entrent pas dans cette release par simple proximité technologique.

Sélection des audits et patterns

Les trois audits Markdown (headers, tables, liens locaux) restent séparés : une propriété chacun, sélection explicite des chemins et lecture seule. L'audit des headers, livré en alpha.5, applique le contrat de docs/rules/300-DOCUMENTATION.md avec des cas positifs et négatifs ciblés ; il ne juge ni le rôle du document ni la pertinence de l'incrément de sa révision.

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.

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

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

alpha.1 — intake et dimensionnement

Enregistrer l'audit de la stable, confronter le prompt au dépôt réel, inventorier les candidats, fixer le scope et produire le présent plan ainsi que le delta. Aucune matérialisation technique importante. Attendre la validation opérateur, le history distinct et le commit avant tout delta suivant.

alpha.1.fix.1 — correction documentaire du plan

Après le history et le commit de alpha.1, documenter la comparaison réelle de KSP/Games, élargir les templates Rust à Cargo et Clippy et redimensionner les tranches. Aucun template ou audit nouveau dans ce fix.

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 à alpha.4 après le REPLAN, qui les reliera au profil Clippy retenu.

alpha.3 — audits de style Rust découpés (REPLAN : SPLIT)

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 — manifests Cargo workspace et crate membre

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 — 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

La comparaison des prompts 002 et 003 confirme une répétition utile à factoriser : baseline source, preuve post-tag éventuelle, prompt versionné et gate d'intake. Livrer une spécification courte de rédaction manuelle, détenue par 210-WORKFLOW.md, sans générateur ni prompt de version suivante avant la clôture stable. Le template reste distinct des configurations Rust/Cargo et ne modifie pas les prompts historiques.

beta.1 — réconciliation

Vérifier ownership, navigation, séparation règle/template/audit, absence de versions universelles arbitraires et proportion des contrôles. Aucun nouveau domaine majeur sans REPLAN.

La revue préparatoire de cette tranche constate que les sept deltas 0.0.3 de alpha.1 à alpha.6, fix inclus, forment une chaîne de versions continue depuis 0.0.2 et possèdent chacun un history PASS fondé sur la gate opérateur ; beta.1 n'a pas encore de history. Les propriétaires restent distincts : profil 510 pour les conventions Rust facultatives, règles 210 et 300 pour workflow et headers, documents de docs/templates/ pour l'adaptation, scripts monotâches pour les contrôles. Leurs validations ciblées ont été acquises dans les tranches précédentes ; beta.1 vérifie leur intégration et la navigation sans exiger de nouveau build des projets sources.

Trois écarts documentaires justifient le delta : l'index de docs/ présentait tous ses templates comme techniques alors que le troisième décrit la reprise de session ; le plan désignait toujours les headers Markdown comme candidat après leur livraison ; la matrice réservait l'audit de liens à beta/RC/stable alors que les gates alpha l'emploient également sur des changements de navigation. L'index racine ne pointait pas vers le plan actif. Ces renvois sont corrigés dans les documents vivants sans modifier les snapshots ni les choix de version 0.1.0 et d'édition 2024 explicitement présentés comme exemples adaptables dans les manifests et instructions Rust/Cargo. Le résultat de la gate beta.1 reste à constater par son history séparé.

rc.1 — gate de release candidate

Geler le scope, préparer le changelog et le prompt de la version suivante si la trajectoire est confirmée ; exécuter la gate documentaire et les vérifications ciblées des scripts réellement ajoutés.

stable — 0.0.3

Promouvoir la RC validée, produire le history de clôture pré-tag, committer et tagger, puis contrôler séparément l'archive du tag publiée.

Points de décision et validation

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.