pgr/docs/rules/230-ADOPTION.md

<!-- file: docs/rules/230-ADOPTION.md -->
<!-- version: 3 -->

# 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. Une fois la baseline locale établie, elle devient l'autorité des sessions et releases suivantes du projet. Le projet destinataire ne devient pas dépendant runtime, build ou documentaire implicite du dépôt PGR et MUST NOT rechercher automatiquement « la dernière version de 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
```

Ces classifications n'augmentent pas la force normative d'une règle. En particulier, choisir une solution différente d'un `SHOULD` / `SHOULD NOT` ne crée pas à lui seul un `OVERRIDE` obligatoire ; le projet MAY conserver ce choix comme décision locale et documenter sa raison lorsque cette trace apporte une valeur durable.

### 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 obligation PGR réellement applicable, ou un contrat localement rendu obligatoire, est volontairement remplacé ou raffiné 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. Un simple écart à une recommandation `SHOULD` / `SHOULD NOT` MUST NOT exiger un override uniquement parce que la recommandation n'est pas suivie.

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

## Autorité locale et réalignement futur

Après clôture du scope d'adoption, les règles, plans, décisions, validations et historiques locaux gouvernent les travaux suivants. Les sessions et releases ultérieures MUST partir de cette baseline locale et non d'une recherche automatique d'une version PGR plus récente.

PGR n'est pas un upstream documentaire implicite. Une référence, URL ou archive PGR utilisée pendant l'adoption reste une source de comparaison de cette opération ; elle ne crée pas un abonnement aux évolutions futures du référentiel. Une dépendance documentaire externe MAY exister uniquement si le projet la choisit et la possède explicitement comme contrat local.

Un réalignement futur avec PGR MAY être engagé lorsqu'il apporte une valeur réelle. Cette opération MUST être explicite et bornée. Elle doit au minimum :

1. identifier le snapshot PGR choisi, par exemple version, tag, commit ou archive ;
2. repartir de la baseline locale autoritaire du projet ;
3. comparer les owners applicables et classifier les écarts utiles selon `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` ;
4. définir le scope et les validations de la migration ;
5. préserver les histories, tags et décisions historiques au lieu de les réécrire pour simuler une conformité continue.

Le réalignement ne doit pas être présenté comme une mise à jour automatique. Entre deux opérations explicitement décidées, la gouvernance locale reste autonome et suffisante pour reprendre le projet.

## 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 dont la baseline locale gouverne les sessions et releases suivantes ;
- uniquement les owners PGR réellement applicables ;
- les choix locaux légitimes préservés ;
- les overrides explicites lorsqu'une obligation applicable est volontairement remplacée ;
- 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.