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. Les tranches suivantes sont 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 avec deux utilitaires 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 quatre 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.

Candidat conditionnel : template de prompt manuel de nouvelle session

Les prompts 002 et 003 montrent un besoin récurrent de transmission de la baseline taggée, du rapport post-tag lorsqu'il existe et de la mission suivante. Une courte spécification Markdown réutilisable pourrait décrire les champs nécessaires et leur responsabilité, sans produire un générateur ni un prompt dupliquant tout le plan. La tranche dédiée n'est retenue qu'après avoir démontré que cette factorisation simplifie effectivement la prochaine clôture.

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

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.

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.

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.

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 à la tranche suivante, qui les reliera au profil Clippy retenu.

alpha.3 — 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 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.4 — 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. Les autres audits candidats restent à l'étude jusqu'à un sujet/owner avéré.

alpha.5 — 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.

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.

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

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.