0.1.0-alpha.4

2026-09-26 19:31:22 +02:00
parent 351025b4f2
commit e4b5992266
10 changed files with 598 additions and 8 deletions
--- a/docs/000-README.md
+++ b/docs/000-README.md
@@ -1,5 +1,5 @@
 <!-- file: docs/000-README.md -->
-<!-- version: 19 -->
+<!-- version: 20 -->

 # Documentation PGR

@@ -24,6 +24,8 @@ Les templates techniques copiables sous `templates/` restent séparés des instr

 - [`plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md`](plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md) — audit de la stable `v0.0.5`, cadrage du workflow de clôture/publication et préparation de la première baseline PGR réellement réutilisable.
 - [`templates/006-OPERATOR_COMMAND_HANDOFF.md`](templates/006-OPERATOR_COMMAND_HANDOFF.md) — pattern de remise automatique des commandes entre history, commit/push, delta suivant, tag et vérification post-tag.
+- [`rules/230-ADOPTION.md`](rules/230-ADOPTION.md) — contrat d’adoption proportionnée de PGR par un projet existant sans réécriture rétroactive de son historique.
+- [`templates/007-EXISTING_PROJECT_ADOPTION.md`](templates/007-EXISTING_PROJECT_ADOPTION.md) — pattern court de baseline, mapping `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`, découpage et validation d’une migration existante.

 ## Points d'entrée de 0.0.5

--- a/docs/architecture/002-GOVERNANCE_ARCHITECTURE.md
+++ b/docs/architecture/002-GOVERNANCE_ARCHITECTURE.md
@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/002-GOVERNANCE_ARCHITECTURE.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->

 # Architecture de gouvernance PGR

@@ -55,6 +55,26 @@ PGR rules + templates + skeleton specifications

 Une évolution ultérieure de PGR ne modifie jamais automatiquement les projets déjà créés.

+## Adoption d’un projet existant
+
+Un dépôt déjà existant ne repasse pas artificiellement par le flux d’instanciation. Son adoption part de sa baseline réelle et compare les owners PGR applicables avec les contrats locaux avant toute migration. Le mapping utilise la classification `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`.
+
+Le flux conceptuel est :
+
+```text
+baseline autoritaire du projet
+            ↓
+inventaire + owners PGR applicables
+            ↓
+ADOPT / KEEP-LOCAL / OVERRIDE / DEFER
+            ↓
+migration progressive + validation
+            ↓
+projet autonome avec historique préservé
+```
+
+Le contrat normatif appartient à [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md). Un skeleton MAY servir de référence de comparaison, mais l’adoption ne prétend pas que le projet existant a été créé depuis ce skeleton et ne réécrit pas rétroactivement ses snapshots historiques.
+
 ## Hiérarchie

 Les règles générales sont raffinées par les scopes plus spécifiques. Un choix spécialisé, par exemple une contrainte Tauri Android, ne devient pas automatiquement une règle Android ou Java générale.
--- a/docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md
+++ b/docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md
@@ -1,5 +1,5 @@
 <!-- file: docs/plans/006-V0_1_0_REUSABLE_BASELINE_PLAN.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->

 # Plan 0.1.0 — première baseline PGR réutilisable

@@ -197,13 +197,21 @@ La gate spécifique n'a toutefois pas pu s'exécuter jusqu'au bout : le littéra

 ### alpha.3.fix.1 — correction de la gate du handoff opérateur

-Corriger uniquement la syntaxe du contrôle Python de `alpha.3`, conserver les owners et le delta historique inchangés, puis reconfirmer le handoff automatique, les tests, audits Markdown et le scope minimal du fix.
+Statut opérateur : **PASS**.
+
+Le fix a conservé `210-WORKFLOW.md`, `006-OPERATOR_COMMAND_HANDOFF.md`, l'index documentaire et le delta historique `alpha.3.md` inchangés. La gate corrigée a reconfirmé le `FAIL` historique de `alpha.3`, le contenu normatif du handoff et le pattern opérateur.
+
+La validation a exécuté `48/48` tests et les trois audits Markdown sans diagnostic. Aucun nouveau fix ni REPLAN n'est requis.

 ### alpha.4 — adoption d'un projet existant

+Statut opérateur : **à valider**.
+
 Formaliser une méthode courte d'adoption PGR pour un dépôt existant : audit de la baseline réelle, mapping des owners applicables, classification `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`, migration progressive et interdiction de réécrire l'historique uniquement pour le rendre rétroactivement conforme.

-Ce contrat doit permettre de préparer Games puis KSP sans imposer tous les profils PGR à chaque projet.
+Le nouvel owner `230-ADOPTION.md` doit distinguer explicitement adoption et instanciation par skeleton. Le pattern `007-EXISTING_PROJECT_ADOPTION.md` doit fournir une forme réutilisable sans devenir un manifest obligatoire.
+
+Ce contrat doit permettre de préparer Games puis KSP sans imposer tous les profils PGR à chaque projet ni migrer effectivement ces dépôts dans `0.1.0`.

 ### alpha.5 — baseline réutilisable et dry-run de composition

--- a/docs/rules/000-README.md
+++ b/docs/rules/000-README.md
@@ -1,5 +1,5 @@
 <!-- file: docs/rules/000-README.md -->
-<!-- version: 13 -->
+<!-- version: 14 -->

 # Index des règles PGR

@@ -14,6 +14,7 @@ Les règles générales actuellement nécessaires restent dans `RULES.md`. La fa
 - [`200-GOVERNANCE.md`](200-GOVERNANCE.md) — versioning, lifecycle des releases, fixes, cadrage, replan et abandon/supersession.
 - [`210-WORKFLOW.md`](210-WORKFLOW.md) — contrats des artefacts workflow, ordre delta/history/commit, prompts versionnés, reprise et baselines de release.
 - [`220-SKELETONS.md`](220-SKELETONS.md) — contrat commun des skeleton specifications, sélection des profils/templates, décisions, overrides et validation.
+- [`230-ADOPTION.md`](230-ADOPTION.md) — contrat d’adoption PGR pour un dépôt existant, classification `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` et migration incrémentale.
 - [`300-DOCUMENTATION.md`](300-DOCUMENTATION.md) — rôles des documents, taxonomie, révisions internes, documents vivants et snapshots historiques.
 - [`400-VALIDATION.md`](400-VALIDATION.md) — matrice de validation, preuves proportionnelles, tests/audits/diagnostics, doubles de test et autorité du gate opérateur.
 - [`500-LANGUAGES.md`](500-LANGUAGES.md) — contrat commun des profils langage/écosystème et de leurs spécialisations de build.
--- a/docs/rules/230-ADOPTION.md
+++ b/docs/rules/230-ADOPTION.md
@@ -0,0 +1,127 @@
+<!-- file: docs/rules/230-ADOPTION.md -->
+<!-- version: 1 -->
+
+# Existing project adoption rules
+
+## Scope
+
+Ce document définit le contrat transversal d’adoption de PGR par un projet **déjà existant**. Il couvre la reprise d’une baseline réelle, l’inventaire des owners applicables, la comparaison avec les contrats locaux, la classification des décisions d’adoption, la migration progressive, les exceptions et la validation de l’état obtenu.
+
+L’adoption d’un dépôt existant est distincte de l’instanciation d’un nouveau projet par skeleton. Les skeleton specifications restent possédées par [`220-SKELETONS.md`](220-SKELETONS.md) ; l’adoption peut les utiliser comme référence de composition sans prétendre recréer rétroactivement le projet.
+
+Les règles de workflow et de validation restent respectivement possédées par [`210-WORKFLOW.md`](210-WORKFLOW.md) et [`400-VALIDATION.md`](400-VALIDATION.md).
+
+## Principe
+
+PGR s’adapte au besoin réel du projet existant ; il ne cherche pas à effacer l’histoire du dépôt ni à imposer toute la bibliothèque de profils disponible.
+
+Une adoption MUST partir d’une baseline autoritaire réellement observée : commit, tag, archive de release ou autre état explicitement accepté par le projet. Le travail d’adoption MUST distinguer ce qui existe déjà de ce que PGR propose d’ajouter ou de modifier.
+
+Une migration réussie produit un projet autonome gouverné localement. Le projet destinataire ne devient pas dépendant runtime ou build du dépôt PGR.
+
+## Audit initial de la baseline
+
+Avant de modifier le projet, l’adoption MUST établir au minimum :
+
+- la baseline autoritaire et son niveau de confiance ;
+- les règles, conventions, outils, fichiers de gouvernance et validations déjà présents ;
+- les langages, plateformes, frameworks et autres profils réellement applicables ;
+- les contraintes locales qui ne doivent pas être remplacées par une règle générique ;
+- les incohérences ou dettes qui nécessitent une décision au lieu d’une conversion automatique.
+
+L’audit SHOULD réutiliser les outils du projet et les audits PGR applicables lorsqu’ils sont disponibles. Il MUST NOT interpréter l’absence d’un artefact PGR comme un défaut en soi tant qu’aucune règle applicable ne l’exige.
+
+## Mapping des owners applicables
+
+L’adoption MUST sélectionner les owners PGR à partir du scope réel du dépôt. Elle MUST NOT activer tous les profils PGR par défaut.
+
+Chaque owner ou contrat candidat à l’adoption doit être comparé avec l’état local avant décision. Un profil non applicable reste hors scope ; une technologie envisagée mais non encore présente MAY rester `DEFER`.
+
+Les owners PGR servent de référence normative pour ce qui est réellement adopté. Les règles propres au projet restent locales et ne deviennent pas automatiquement des règles générales PGR.
+
+## Classification des décisions
+
+Le mapping d’adoption utilise les quatre classifications suivantes :
+
+```text
+ADOPT
+KEEP-LOCAL
+OVERRIDE
+DEFER
+```
+
+### ADOPT
+
+`ADOPT` signifie que le projet retient le contrat PGR applicable et migre son état local lorsque nécessaire.
+
+L’adoption MAY être immédiate ou découpée en plusieurs tranches si le changement est trop large pour être validé proprement en une fois.
+
+### KEEP-LOCAL
+
+`KEEP-LOCAL` signifie qu’un contrat local existant reste préférable ou nécessaire et qu’il n’entre pas en contradiction avec une obligation PGR réellement adoptée.
+
+Cette classification ne crée pas une exception : elle reconnaît qu’un choix local demeure hors du besoin de normalisation ou qu’un owner PGR ne possède pas ce détail.
+
+### OVERRIDE
+
+`OVERRIDE` signifie qu’une règle PGR applicable est volontairement remplacée ou raffinée dans un scope local.
+
+L’override MUST identifier la règle concernée, le scope, la raison et le contrat local retenu. Il ne doit pas être utilisé pour masquer une migration incomplète ou faire disparaître une violation non résolue.
+
+### DEFER
+
+`DEFER` signifie qu’une décision applicable est volontairement différée parce qu’un prérequis, un owner, une preuve ou une priorité manque encore.
+
+Le report SHOULD indiquer ce qui permettrait de reprendre la décision. `DEFER` MUST NOT être présenté comme une adoption accomplie.
+
+## Migration progressive
+
+L’adoption SHOULD privilégier des tranches cohérentes et validables. Une migration massive n’est justifiée que si elle apporte moins de risque et de coût qu’une progression incrémentale.
+
+Une tranche d’adoption SHOULD :
+
+1. identifier le sous-ensemble de décisions concerné ;
+2. modifier uniquement les owners locaux, configurations, templates ou structures nécessaires ;
+3. appliquer une validation proportionnée aux contrats réellement modifiés ;
+4. enregistrer les décisions durables chez leurs owners locaux ;
+5. laisser les domaines non concernés inchangés.
+
+L’adoption d’un profil ne force pas l’adoption simultanée des profils voisins. Par exemple, un dépôt Rust utilisant Tauri peut adopter les règles Rust/Cargo disponibles tout en différant les owners Web encore insuffisants.
+
+## Préservation de l’historique
+
+PGR MUST NOT demander de réécrire des commits, tags, histories, changelogs ou autres snapshots historiques uniquement pour donner l’apparence d’une conformité rétroactive.
+
+Les conventions nouvelles s’appliquent à partir du point d’adoption explicitement établi. Les artefacts historiques restent interprétés selon leur contexte d’origine, sauf correction exceptionnelle justifiée par une erreur factuelle ou un risque réel.
+
+Une adoption MAY documenter des écarts hérités comme dette, exception temporaire ou contexte historique sans modifier les snapshots qui les ont produits.
+
+## Relation avec les skeletons et templates
+
+Un skeleton PGR MAY servir de checklist de comparaison pour un projet existant. Il ne doit pas être appliqué comme si le dépôt était vide.
+
+Lorsqu’un template PGR est pertinent, l’adoption MUST comparer sa responsabilité et ses valeurs avec le fichier local avant remplacement. Un fichier local fonctionnel ne doit pas être écrasé uniquement pour obtenir une copie identique au template PGR.
+
+Une différence locale MAY être conservée si elle relève d’une décision du projet, d’un `KEEP-LOCAL` ou d’un `OVERRIDE` valide.
+
+## Validation de l’adoption
+
+Chaque étape d’adoption MUST sélectionner des preuves proportionnées selon [`400-VALIDATION.md`](400-VALIDATION.md).
+
+La validation SHOULD d’abord prouver que le projet reste fonctionnel dans son environnement réel, puis que les nouveaux contrats de gouvernance ou de structure sont respectés. Un audit PGR read-only ne remplace pas une toolchain ou un smoke autoritaire lorsqu’un contrat appartient à cette toolchain ou à cet environnement.
+
+Une adoption n’est terminée que lorsque les décisions de son scope sont classifiées, les changements retenus sont appliqués, les validations requises sont acquises et les `DEFER` restants sont explicitement hors du scope déclaré.
+
+## Résultat attendu
+
+Une adoption PGR réussie laisse :
+
+- un projet autonome ;
+- uniquement les owners PGR réellement applicables ;
+- les choix locaux légitimes préservés ;
+- les overrides explicites ;
+- les domaines différés clairement identifiés ;
+- un historique non falsifié ;
+- une validation proportionnée au changement réellement effectué.
+
+[`../templates/007-EXISTING_PROJECT_ADOPTION.md`](../templates/007-EXISTING_PROJECT_ADOPTION.md) fournit un pattern documentaire court pour préparer et suivre ce mapping sans imposer un format de migration unique.
--- a/docs/templates/007-EXISTING_PROJECT_ADOPTION.md
+++ b/docs/templates/007-EXISTING_PROJECT_ADOPTION.md
@@ -0,0 +1,97 @@
+<!-- file: docs/templates/007-EXISTING_PROJECT_ADOPTION.md -->
+<!-- version: 1 -->
+
+# Pattern — adoption PGR d’un projet existant
+
+## Usage
+
+Ce pattern aide à préparer une adoption PGR sur un dépôt existant conformément à [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md). Il n’est pas un manifest obligatoire, un générateur de migration ni un remplacement du plan de release local.
+
+Il peut être instancié comme étude, plan, tableau de décision ou section d’un document existant si le projet a besoin d’une trace durable. Un petit alignement dont les décisions sont évidentes MAY rester directement documenté dans le delta et le history correspondants.
+
+## Baseline autoritaire
+
+Consigner uniquement ce qui est réellement établi :
+
+```text
+repository / archive : <source>
+commit / tag          : <si connu>
+version               : <si applicable>
+validation connue     : <preuves déjà acquises et encore pertinentes>
+```
+
+Ne pas reconstruire une baseline à partir d’hypothèses ou d’une version plus récente de PGR.
+
+## Inventaire utile
+
+Identifier les éléments qui déterminent l’applicabilité :
+
+- gouvernance et workflow déjà présents ;
+- langages et build systems réellement utilisés ;
+- plateformes et frameworks présents ;
+- validations et scripts existants ;
+- contraintes locales ou historiques à préserver ;
+- profils PGR sans rapport avec le dépôt, explicitement hors scope si leur confusion est probable.
+
+## Mapping d’adoption
+
+La classification canonique est `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`. La forme exacte du mapping reste libre. Une table courte peut suffire :
+
+```text
+Owner / contrat        État local        Décision      Action / justification
+--------------------   ----------------  ------------  -----------------------
+<RULE/PGR owner>       <état observé>    ADOPT         <migration ciblée>
+<contrat local>        <état observé>    KEEP-LOCAL    <raison>
+<RULE/PGR owner>       <état observé>    OVERRIDE      <scope + raison>
+<RULE/PGR owner>       <état observé>    DEFER         <prérequis / déclencheur>
+```
+
+Les quatre décisions ont le sens normatif défini par `230-ADOPTION.md`. Ne pas créer une cinquième catégorie uniquement pour éviter de décider si un point est adopté, local, overridé ou différé.
+
+## Découpage de migration
+
+Pour chaque tranche réellement nécessaire, préciser :
+
+```text
+scope            : <owners / fichiers / contrats concernés>
+hors scope       : <domaines laissés intacts>
+risque principal : <ce qui pourrait être cassé>
+preuve            : <gate proportionnée>
+```
+
+Le découpage SHOULD favoriser des changements vérifiables indépendamment. Une migration ne doit pas embarquer une technologie future uniquement parce qu’un profil PGR existe.
+
+## Historique et compatibilité
+
+Noter les conventions qui commencent au point d’adoption et les snapshots historiques qui doivent rester inchangés.
+
+Exemples :
+
+```text
+- ancienne nomenclature de tags conservée avant <point d’adoption> ;
+- anciennes règles locales conservées dans les histories ;
+- nouvelle convention appliquée uniquement aux prochaines tranches ;
+- dette héritée documentée mais non réécrite rétroactivement.
+```
+
+## Validation de sortie
+
+L’adoption du scope est prête lorsque :
+
+- chaque owner candidat du scope est classifié ;
+- les changements `ADOPT` sont réellement appliqués ;
+- les `KEEP-LOCAL` et `OVERRIDE` sont compréhensibles et possédés localement ;
+- les `DEFER` ont un motif et restent hors du résultat présenté comme terminé ;
+- les validations nécessaires ont réussi ;
+- le projet reste autonome par rapport au dépôt PGR.
+
+## Limites
+
+Ce pattern ne décide pas à la place du projet :
+
+- quels profils sont applicables ;
+- si Games, KSP ou un autre dépôt doit migrer maintenant ;
+- si une règle locale doit devenir une règle PGR générale ;
+- si une migration doit occuper une ou plusieurs releases.
+
+Ces décisions appartiennent au contexte réel du projet et à son plan actif.