pgr/docs/plans/005-V0_0_5_RECONCILIATION_PLAN.md

Plan 0.0.5 — réconciliation réelle avec KSP et sasedev-games

Statut et sources

Plan actif créé pendant 0.0.5-alpha.1 conformément à prompts/005-V0_0_5_START_PROMPT.md. La release confronte PGR à deux baselines autoritaires fournies sans présumer qu'elles ont déjà adopté PGR.

Sources contrôlées :

pgr-v0.0.4.zip                         7137bb084f017362323a2043d13ba71490be15b8786adc8d645981bf455b80ae
khadhroony-solana-project-v0.3.16.zip db3cc1b3fc3fb07ee864b02e2a7346c673d4cf63b33e8e872aca6c6458856ca0
games-v0.3.5.zip                      5f5fdee1a271386766d059657d6eaa831acdc263b3e722fed738808335c0a105

Le rapport externe pgr-0.0.4-publish.001-report.md est PASS et annonce le même hash pour la stable PGR. L'étude détaillée et les limites de l'environnement sont consignées dans ../studies/001-KSP_GAMES_RECONCILIATION.md.

Mission et garde-fous

0.0.5 doit améliorer PGR à partir des besoins réellement répétés dans KSP et Games sans transformer leurs conventions historiques en règles universelles.

Les deux projets ne sont pas encore gouvernés par PGR. Par conséquent :

• aucune divergence de leurs archives n'est qualifiée de défaut PGR par défaut ;
• aucune migration de KSP ou Games n'appartient au scope de cette release ;
• aucune ancienne tranche, nomenclature ou chaîne history n'est reconstruite rétroactivement ;
• tout nouvel owner PGR doit correspondre à un besoin réutilisable et non à un simple copier-coller de projet ;
• les règles métier, architecture, protocoles, distribution et infrastructure spécifiques restent locales.

Résultat du cadrage alpha.1

L'audit classe la majorité des mécanismes de gouvernance, documentation, validation et Rust/Cargo comme déjà OWNED par PGR. Les améliorations candidates réellement communes sont bornées à quatre axes :

1. prompt de démarrage de projet : le contrat actuel de 210-WORKFLOW.md est plus minimal que les prompts opératoires éprouvés dans les deux corpus ;
2. contrats documentaires locaux : les deux projets utilisent un registre de responsabilités de fichiers/familles qui peut devenir un pattern facultatif de la fondation ;
3. façade Rust et export completeness : les deux projets partagent pratiquement le même audit spécialisé, alors que PGR n'en fournit pas encore de version réutilisable ;
4. Tauri : le framework est utilisé indépendamment et de manière répétée dans les deux corpus, ce qui fournit enfin une base réelle pour activer la famille framework 700 sans généraliser Vite/Web/JNI au-delà des preuves disponibles.

Les audits composites, le Web autonome, WASM, JNI, règles serveur, distribution Games et frontières métier KSP restent différés ou locaux.

REPLAN alpha.4 — lifecycle inter-release et horizon

La gate alpha.3.fix.1 a validé son correctif local. Une revue séparée du plan, de ROADMAP.md et des historiques de conception PGR 0.0.1 à 0.0.4 a ensuite confirmé un besoin général non couvert explicitement par le forecast initial : PGR sait piloter une release active, mais n'assigne pas encore assez strictement où/quand sa fermeture et sa transition sont préparées, ni quand l'horizon des versions futures doit être rediscuté.

Les historiques montrent que plusieurs briques avaient déjà été décidées séparément — moment du CHANGELOG, ROADMAP, prompt suivant, REPLAN, abandon/supersession, continuation inter-session, handoff et distinction rel.001/publish.001. Le problème n'est donc pas d'inventer un second workflow, mais de les relier dans le contrat du plan et d'éviter qu'elles restent implicites.

Ce constat déclenche le point de décision REPLAN prévu par alpha.1. Aucun travail antérieur n'est invalidé. Les anciennes tranches alpha.4 à alpha.6 sont décalées d'un numéro et restent dans le scope.

Trajectoire prévisionnelle

alpha.1 — audit indépendant, étude et plan

Vérifier la stable PGR, son rapport post-tag et les deux archives externes ; exécuter les audits statiques disponibles ; classifier les écarts ; créer l'étude et le présent plan. Aucun changement normatif, script réutilisable, profil framework ou skeleton nouveau dans cette tranche.

alpha.2 — contrat générique des prompts de démarrage

Renforcer l'owner 210-WORKFLOW.md pour les prompts versionnés sans recopier les règles locales KSP/Games. Fournir une spécification réutilisable couvrant au minimum : baseline autoritaire, ordre de lecture, état déjà validé, mission/résultat, scope/hors-scope, décisions gelées/ouvertes, première gate, trajectoire prévisionnelle et validations.

Le template manuel 003-NEW_SESSION_PROMPT.md reste distinct : il sert au court message remis après publication, alors que cette tranche porte le prompt versionné du projet.

alpha.3 — pattern de contrats de fichiers/familles

Étendre 300-DOCUMENTATION.md et la fondation 001 uniquement si nécessaire pour décrire un registre local facultatif des fichiers ou familles dont le rôle et les règles de modification méritent d'être explicites. Fournir une spécification/template documentaire courte plutôt qu'un catalogue universel.

Le pattern ne doit pas imposer FILE_CONTRACTS.md à un petit projet, ni recopier les rôles déjà possédés par PGR. Le correctif alpha.3.fix.1 a en outre renforcé l'audit des tables Markdown fenced sans modifier ce scope fonctionnel.

alpha.4 — REPLAN : clôture, transition et revue d'horizon

Formaliser le lifecycle inter-release qui manquait au plan initial :

• imposer à un plan de release suffisamment complexe d'attribuer noir sur blanc les responsabilités de clôture/transition ;
• définir la revue d'horizon sans imposer un nombre artificiel de versions futures ;
• expliciter le passage idea/study → décision durable → roadmap/plan ;
• confirmer qu'une discussion stratégique peut vivre dans une session séparée sans changer VERSION ;
• rendre spontané le message manuel de reprise lorsque la prochaine cible est connue ;
• permettre la livraison history courant + delta suivant dans une même réponse lorsque la suite est déterministe, tout en maintenant deux archives et l'ordre commit/apply ;
• fournir un pattern réutilisable de plan de release pour l'adoption future dans KSP, Games et d'autres projets.

Cette tranche ne commence pas l'audit Rust ni le profil Tauri.

alpha.5 — audit Rust de façade/export completeness

Extraire le noyau réellement commun de audit_rust_export_completeness.py, l'aligner avec 510-RUST_CARGO.md, documenter son caractère facultatif et ses limites, et ajouter des tests positifs/négatifs.

La réconciliation a révélé que le script historique ne découvrait que crates/*/Cargo.toml : il couvrait les 22 packages KSP mais aucun des 23 packages Games imbriqués sous des sous-familles. La variante PGR corrige donc la découverte récursive et distingue aussi les cibles lib/bin d'un même package pour ne pas confondre plusieurs crates Rust compilées séparément.

La première livraison alpha.5 a ensuite révélé un second défaut de scope pendant la revue opérateur : elle ne détectait que les chemins internes longs tels que crate::module::Item, alors que le contrat attendu impose crate::Item pour toute référence intra-crate à un item partagé, y compris un nom nu dans son module propriétaire. La gate mécanique était verte mais l'acceptation fonctionnelle est donc FAIL; alpha.5.fix.1 corrige ce blind spot sans commencer Tauri.

Mesure alpha.5.fix.1 en --report-only --summary-only : KSP 0.3.16 = 1525 lignes candidates RUST-IMPORT-201 sur 22 packages ; Games 0.3.5 = 181 lignes candidates sur 23 packages (2 RUST-API-201, 179 RUST-IMPORT-201). Ces nombres forment un inventaire d'adoption future, pas une non-conformité rétroactive des baselines.

Cette tranche ne réimporte pas audit_rust_general_rules.py en bloc et ne réintroduit pas le diagnostic historique de résolution crate::X déjà possédé par le compilateur. Toute autre règle déjà possédée par Rustfmt, Clippy, le compilateur ou les audits PGR existants reste chez son owner actuel.

alpha.6 — premier profil framework : Tauri

La preuve commune est confirmée : 6 applications Tauri KSP et 2 applications Tauri Games partagent Tauri 2, un host Rust/Cargo, tauri-build, tauri.conf.json, des capability files, des hooks frontend et un frontendDist. Les valeurs applicatives divergent suffisamment pour exclure toute copie de ports, fenêtres, CSP, bundles, plugins ou commandes frontend particulières.

La première livraison active 700-FRAMEWORKS.md et 710-TAURI.md, mais la gate opérateur est FAIL pour deux raisons : le contrôle Python ciblé du delta contient une chaîne multilignes invalide et la revue fonctionnelle exige de mieux distinguer le profil Tauri universel des conventions d'instanciation des projets contrôlés. alpha.6.fix.1 corrige donc le gate et explicite que le host Tauri hérite intégralement des règles Rust sélectionnées, que WASM reste normalement une unité séparée et que l'ajout manuel de plugins à partir de leur documentation officielle est une stratégie valide.

Les préférences récurrentes de l'organisation — frontend sous frontend/, Vite, TypeScript, Sass, Bootstrap et contrôle explicite des dépendances — sont consignées comme candidat de skeleton, pas comme invariants de 710-TAURI.md. Un projet imposé de l'extérieur peut conserver une structure différente via ses règles project-specific.

La politique gen/ n'est pas généralisée : les sorties purement reproductibles restent générées, mais les projets mobiles modifiés intentionnellement doivent être classifiés selon leur rôle réel. L'échec du POC Tauri mobile Games ne constitue pas un rejet général de Tauri Android/iOS pour les autres produits.

La gate alpha.6.fix.1 révèle un second défaut de quoting Python (l'extérieur dans une chaîne simple) et la revue opérateur demande une seconde passe sur les règles réelles KSP/Games. alpha.6.fix.2 corrige le gate et renforce la convention des projets contrôlés avec le layout direct sans src-tauri/, lib.rs/main.rs/tauri.rs, TS-RS lorsque le frontend TypeScript partage des DTO Rust, modules de fenêtres/responsabilités et préférence pour l'intégration explicite des plugins. Les règles Rust générales et la nomenclature des crates restent volontairement dans alpha.7/alpha.8.

La gate mécanique de alpha.6.fix.2 est propre, mais la revue fonctionnelle révèle une troisième divergence : KSP et Games avaient tous deux converti la réduction du churn de version en préférence pour l'absence de tauri.conf.json > version et la stagnation de package.json. Cette solution ne doit pas devenir une règle PGR. alpha.6.fix.3 restaure la classification générale CANONICAL / MIRROR-EXACT / MIRROR-STABLE et définit pour Tauri/frontend une synchronisation de jalon X.Y.Z par défaut, sans bump à chaque tranche.

Comme fix.3 atteint le seuil de revue obligatoire des correctifs, le plan est réexaminé : résultat CONTINUE. Le scope Tauri reste cohérent et borné après cette correction ; les chantiers Rust alpha.7/alpha.8 et la décision de skeleton alpha.9 restent séparés et ne sont pas absorbés par le fix.

alpha.7 — profil Rust strict, chemins et nomenclature explicite

La réconciliation des règles versionnées KSP/Games retient KSP comme référence stricte et Games comme contrôle de généralisation. Pour une nouvelle baseline contrôlée, 510-RUST_CARGO.md impose désormais Rust 2024, réserve use aux traits réellement nécessaires, exige les chemins publics explicites les plus courts pour les autres symboles, les réexports internes self::, la façade crate-root et crate::Item, et conserve le contrôle de flux explicite sans unwrap, expect ni ? en production.

La nomenclature des crates devient également explicite : préfixe projet/abréviation obligatoire ; responsabilité puis rôle/cible lisibles lorsque ce classificateur apporte une information réelle. La forme recommandée est <project>-<responsibility>-<role-or-target> sans figer les vocabulaires KSP/Games ni imposer de renommage rétroactif. Les projets externes ou historiquement contraints peuvent documenter un override borné.

Le skeleton Rust/Cargo et le guide de manifest reflètent ces choix. Aucun gros audit composite n'est importé ; le marqueur KSP spécifique des trait imports n'est pas généralisé et les contrôles déjà possédés par Clippy, rustc ou l'audit de façade restent chez leur owner.

La gate mécanique alpha.7 est propre, mais la revue fonctionnelle post-gate montre que cette première matérialisation ne donnait pas encore de contrat architectural aux suffixes. alpha.7.fix.1 complète donc la tranche sans la replanifier : -api devient un vrai contrat extensible/passif et n'est jamais créé par symétrie ; -lib identifie l'implémentation réutilisable ; les exécutables sont des packages distincts et minces par défaut ; tracing et un owner de logging commun sont fortement recommandés dans les workspaces multi-runtime. L'ancienne préférence KSP pour un worker mixte lib/bin n'est pas généralisée. Tauri reste l'exception framework actuelle et impose des noms de targets lib/bin réellement distincts.

alpha.8 — formatage Rust structurel et audits monotâches

Réconcilier les règles KSP de blocs homogènes, visibilité, ordre alphabétique, espacement, modules et réexports avec les conventions plus légères de Games. Décider précisément ce qui appartient à rustfmt, aux audits PGR existants (blank_lines, const_blocks) ou à un nouvel audit monotâche justifié.

La tranche ne doit pas créer un parser Rust général ni imposer un ordre alphabétique lorsqu'un ordre métier/protocolaire est sémantique. Elle peut conclure qu'aucun nouveau script n'est nécessaire pour une propriété déjà correctement possédée.

alpha.9 — décision de skeleton Tauri pour projets contrôlés

Vérifier si le profil Tauri obtenu et les owners Web disponibles permettent une skeleton specification utile pour les projets que l'organisation contrôle. Le candidat à évaluer utilise le host Cargo direct sans src-tauri/, frontend/, Vite, TypeScript, Sass et Bootstrap, centralise l'assemblage/les commandes dans tauri.rs, utilise TS-RS pour les DTO Rust partagés avec le frontend, conserve WASM dans une unité séparée par défaut et privilégie l'ajout explicite des plugins à partir de leur documentation.

Si les profils Web nécessaires ne sont pas encore assez matérialisés pour posséder proprement Vite/TypeScript/Sass/Bootstrap, consigner explicitement le report de ces choix tout en conservant les conventions Tauri déjà prouvées ; ne pas fabriquer un skeleton décoratif ni faire de 710-TAURI.md un owner Web de substitution.

beta.1 — réconciliation intégrée

Rejouer la matrice de l'étude sur l'état PGR obtenu. Vérifier : owner unique, navigation, absence de règles KSP/Games aspirées par accident, caractère facultatif des patterns/audits concernés, cohérence des skeletons et domaines encore différés.

Cette tranche réconcilie aussi la documentation durable et vérifie que le présent plan possède un contrat de fermeture exécutable. Le prompt 006 vers 0.1.0 peut être préparé ici si la mission 0.1.0 reste suffisamment connue.

rc.1 — scope gelé et gate candidate

Geler le scope de 0.0.5, préparer l'entrée candidate du changelog, vérifier ROADMAP.md, finaliser/vérifier le prompt 006-V0_1_0_START_PROMPT.md si 0.1.0 reste la cible retenue et rejouer les tests/audits PGR ainsi que les validations ciblées des nouveaux scripts/templates/profils réellement livrés.

Aucune version postérieure à 0.1.0 n'est inventée à cette étape.

stable — 0.0.5

Promouvoir mécaniquement la RC validée : synchroniser VERSION, README/index, ROADMAP.md, CHANGELOG.md et statut du présent plan sans ajouter de nouveau besoin commun. Après history PASS, commit et tag v0.0.5, vérifier séparément l'archive publiée.

La vérification post-tag doit produire, si le mécanisme reste retenu, pgr-0.0.5-publish.001-report.md extérieur au tag. Le message manuel final doit alors indiquer spontanément à l'opérateur de fournir l'archive taggée et ce rapport avec le prompt 006 lors de la session 0.1.0.

Clôture et transition

Le présent plan attribue dès maintenant les responsabilités de fermeture :

• la documentation directement liée à chaque capacité évolue dans sa tranche ;
• beta.1 réalise la réconciliation durable globale et prépare le prompt suivant si sa mission est connue ;
• rc.1 porte le scope freeze, l'entrée CHANGELOG candidate, la vérification ROADMAP et le prompt suivant candidat ;
• rel.001/stable finalise CHANGELOG, marque 0.0.5 terminée dans ROADMAP, ferme le présent plan et effectue le promotion gate pré-tag ;
• publish.001 vérifie l'archive réellement produite après le tag et fournit la preuve externe requise par la reprise suivante ;
• aucune de ces opérations ne doit être repoussée implicitement à la session 0.1.0.

Revue d'horizon

Pour PGR, la prochaine release engagée est 0.1.0 — première baseline réutilisable. La trajectoire au-delà n'est pas suffisamment décidée et reste volontairement ouverte ; ce n'est pas un défaut de roadmap.

0.0.5 ne doit donc pas inventer 0.1.1, 0.2.0 ou un catalogue de versions futures. Le plan de 0.1.0-alpha.1 devra en revanche identifier un moment de revue d'horizon avant sa fermeture, une fois la baseline réutilisable suffisamment concrète pour juger la suite. Cette revue pourra se tenir dans une session stratégique séparée sans modifier VERSION.

Ses sorties autorisées seront : étendre la roadmap avec des objectifs réellement décidés, maintenir l'horizon ouvert avec un prochain déclencheur, différer/mettre en pause la trajectoire ou constater qu'un objectif macro est accompli.

Points de décision

Un REPLAN est requis si :

• le contrat de prompt devient une copie exhaustive des règles plutôt qu'un artefact de reprise ;
• le pattern de contrats de fichiers ajoute plus de cérémonie qu'il n'en retire ;
• le lifecycle de clôture impose des documents ou versions futures sans valeur opérationnelle ;
• la revue d'horizon devient un quota de versions à prévoir plutôt qu'un mécanisme de décision ;
• l'audit de façade Rust ne peut pas être séparé proprement des conventions strictes KSP/Games ;
• le profil Tauri universel absorbe des choix de skeleton/frontend qui devraient rester project-specific ou appartenir à un owner Web ;
• la réconciliation Rust stricte ne peut pas être séparée en owners fiables et audits monotâches ;
• le skeleton Tauri n'apporte pas de décisions réutilisables au-delà du profil framework et des conventions explicites de projets contrôlés ;
• une autre divergence des corpus apparaît comme un besoin commun critique non couvert par ce plan.

Stratégie de validation

Les tranches documentaires rejouent les trois audits Markdown et la suite Python PGR. Toute modification d'un script ajoute ou adapte des tests ciblés avant la suite globale. Les templates/configurations structurées sont parsés ou exercés avec l'outil le plus fiable disponible.

PGR ne compile pas KSP ou Games comme gate de sa propre release : ces projets servent de corpus de pression. Une validation croisée MAY exécuter leurs audits statiques sur leurs archives fournies lorsque cela vérifie une propriété précise, mais ne remplace jamais leurs propres gates opérateur.

La toolchain Cargo n'étant pas disponible dans l'environnement de préparation de alpha.1, aucune preuve Cargo externe n'est revendiquée pour cette tranche. La gate PGR reste documentaire et structurelle.