pgr/docs/rules/700-FRAMEWORKS.md

<!-- file: docs/rules/700-FRAMEWORKS.md -->
<!-- version: 3 -->

# Règles de profils framework

## Scope

Cette famille définit le contrat commun des profils liés à un framework réellement utilisé par le projet.

Un framework peut combiner plusieurs owners déjà applicables — langage/écosystème, plateforme, frontend, packaging ou runtime — sans devenir propriétaire de leurs règles générales. Son profil possède uniquement les contraintes et l'orchestration ajoutées par le framework lui-même.

## Responsabilités de la famille

Un profil framework MAY posséder les règles spécifiques concernant notamment :

- les fichiers de configuration réellement possédés par le framework ;
- la relation entre plusieurs toolchains que le framework orchestre ;
- les commandes de développement, build, packaging ou génération qui passent par son CLI ;
- les hooks exécutés par ce CLI et leur ordre de responsabilité ;
- les permissions, capabilities, manifests ou métadonnées propres au framework ;
- les artefacts générés par le framework et leur classification source/généré ;
- la cohérence de version lorsque le framework possède une version applicative distincte ou dérivée ;
- les gates d'intégration que les outils sous-jacents ne prouvent pas isolément.

Un profil framework MUST NOT recopier les règles d'un langage, d'une plateforme ou d'un build tool lorsqu'elles restent valides sans spécialisation.

## Composition

Un framework s'ajoute aux profils réellement applicables au projet. Il n'annule pas silencieusement les conventions des owners qu'il compose.

Par exemple :

```text
GENERAL
+ Rust / Cargo
+ Tauri
```

ou, pour une cible Android :

```text
GENERAL
+ Rust / Cargo
+ Android
+ Tauri
```

Lorsque PGR gouverne la baseline du projet, les règles des profils hérités restent applicables dans leur scope avec leur force normative propre. Un framework MUST NOT contredire silencieusement un `MUST / MUST NOT` hérité ; une telle contradiction exige l'override ou l'exception applicable. Un framework MAY choisir différemment d'un `SHOULD / SHOULD NOT` sans que cet écart constitue à lui seul un override ou une non-conformité.

Un projet existant ou imposé de l'extérieur MAY conserver des contraintes différentes. Ces écarts appartiennent alors au niveau project-specific ou à une exception explicite et bornée ; ils ne doivent pas être remontés comme nouvelle règle générale du framework.

La présence d'un frontend WebView n'active pas automatiquement un futur profil Web/Vite/WASM. Ces technologies restent sélectionnées selon les faits du projet et leurs propres owners.

## Profil framework et convention d'instanciation

Le profil framework décrit ce qui reste vrai pour toute adoption conforme du framework. Une skeleton specification ou une baseline locale MAY choisir en plus un layout, un bundler, un langage frontend, un package manager ou des bibliothèques préférées pour les projets que l'organisation contrôle.

Ces valeurs d'instanciation ne deviennent pas des invariants du framework :

```text
profil framework
→ responsabilités et contraintes propres au framework

skeleton / projet local
→ choix réutilisables de structure et de stack
```

Cette séparation permet d'appliquer PGR à un projet imposé sans lui forcer le skeleton préféré des nouveaux projets.

## Ownership des commandes d'intégration

Lorsqu'un framework possède un CLI qui orchestre plusieurs étapes, la validation de l'intégration SHOULD utiliser ce CLI plutôt que rejouer manuellement ses sous-commandes comme si elles prouvaient le même contrat.

Une commande sous-jacente reste utile pour une preuve ciblée : compiler le backend ne prouve pas les hooks frontend ; construire le frontend seul ne prouve pas l'intégration native ; un build framework complet n'est pas requis pour une modification purement documentaire qui n'invalide aucune de ces propriétés.

La gate sélectionnée reste proportionnée au scope et à la maturité conformément à [`400-VALIDATION.md`](400-VALIDATION.md).

## Sources, générés et configuration locale

Un framework MAY produire des répertoires générés, projets de plateforme, schémas, bindings ou artefacts de build. Leur simple origine framework ne suffit pas à décider leur politique Git.

Le profil spécifique doit distinguer :

```text
source intentionnelle
configuration durable
artefact reproductible
généré modifié intentionnellement
généré purement transitoire
secret / configuration locale
```

PGR MUST NOT appliquer une règle globale « tout `gen/` est ignoré » ou « tout généré est versionné » sans examiner le rôle réel de l'artefact.

Les secrets et valeurs locales restent possédés par les règles générales et les profils plateforme applicables.

## Version du framework et version produit

La version du framework/de ses dépendances et la version du produit sont deux contrats distincts.

Un projet MAY utiliser une plage compatible, un pin ou une politique de mise à jour adaptée au framework ; PGR ne copie pas une version observée dans un projet source comme règle générale.

Lorsqu'un framework expose une version applicative qui représente la même unité de release que `VERSION`, le profil spécifique doit définir une source de vérité ou une synchronisation explicite afin d'éviter plusieurs valeurs indépendantes.

## Validation spécialisée

Un profil framework doit expliquer ce que prouvent ses commandes propres et ce qu'elles ne prouvent pas.

Selon le scope, la preuve peut être :

- un check du langage/backend ;
- un build/test frontend ;
- un lancement framework avec smoke ciblé ;
- un build/package framework ;
- une validation de plateforme réelle lorsque le framework cible Android, iOS ou une autre plateforme.

Aucune de ces catégories n'est obligatoire à chaque tranche par simple présence du framework.

## Nomenclature documentaire

Le document `700-FRAMEWORKS.md` possède le contrat commun de la famille.

Les profils spécifiques utilisent la plage `710` à `799`. Leur numéro sert à la navigation et ne représente ni priorité normative, ni version du framework.

La résolution avec les autres profils suit [`../architecture/003-RULE_PROFILE_MODEL.md`](../architecture/003-RULE_PROFILE_MODEL.md).