124 lines
9.0 KiB
Markdown
124 lines
9.0 KiB
Markdown
<!-- file: docs/rules/220-SKELETONS.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Skeleton specification rules
|
|
|
|
## Scope
|
|
|
|
Ce document définit le contrat transversal des skeleton specifications PGR : applicabilité, sélection des règles et profils, composition de skeletons, usage des templates, décisions propres au projet, overrides, instanciation et validation initiale.
|
|
|
|
Il ne définit pas les règles propres à une technologie. Les profils restent possédés par leurs documents normatifs, notamment le modèle de composition de [`../architecture/003-RULE_PROFILE_MODEL.md`](../architecture/003-RULE_PROFILE_MODEL.md). Les règles de validation restent possédées par [`400-VALIDATION.md`](400-VALIDATION.md) et le workflow delta/history par [`210-WORKFLOW.md`](210-WORKFLOW.md).
|
|
|
|
Les skeleton specifications concrètes vivent sous [`../skeletons/`](../skeletons/000-README.md).
|
|
|
|
## Nature d'un skeleton
|
|
|
|
Un skeleton PGR est une spécification Markdown procédurale permettant de construire une baseline locale cohérente à partir de règles, profils, templates et décisions explicites.
|
|
|
|
Un skeleton MUST NOT devenir :
|
|
|
|
- un générateur obligatoire de projet ;
|
|
- une dépendance runtime ou build vers PGR ;
|
|
- un nouveau propriétaire implicite de règles déjà possédées ailleurs ;
|
|
- un moyen de figer une architecture au-delà du scope qu'il déclare ;
|
|
- un catalogue de technologies ou de fichiers créés par anticipation.
|
|
|
|
Après instanciation, le projet destinataire possède ses fichiers, ses décisions et ses règles locales. Une évolution ultérieure de PGR ne modifie pas automatiquement ce projet.
|
|
|
|
## Applicabilité
|
|
|
|
Chaque skeleton MUST rendre explicites son objectif et les faits qui déterminent son applicabilité.
|
|
|
|
L'applicabilité MUST reposer sur le besoin réel du projet : type de baseline recherchée, langage ou écosystème utilisé, plateforme ciblée, framework réellement présent ou autre propriété concrète du scope.
|
|
|
|
Un skeleton MUST NOT être appliqué uniquement parce qu'il est fréquent, recommandé dans un autre projet ou disponible dans PGR.
|
|
|
|
Un skeleton spécialisé MAY déclarer un autre skeleton comme fondation. Cette relation doit être explicite et ne rend pas les spécialisations sœurs applicables entre elles.
|
|
|
|
## Contenu minimal d'une specification
|
|
|
|
Une skeleton specification MUST permettre d'identifier sans ambiguïté :
|
|
|
|
- son objectif et son applicabilité ;
|
|
- les règles et profils sélectionnés ou requis ;
|
|
- les autres skeletons dont elle dépend éventuellement pour sa composition ;
|
|
- les fichiers à créer, copier, adapter ou omettre ;
|
|
- les templates techniques utilisés et les décisions d'adaptation associées ;
|
|
- les décisions obligatoires qui appartiennent au projet destinataire ;
|
|
- les options, exceptions et overrides explicitement permis ;
|
|
- l'ordre d'instanciation lorsque cet ordre est significatif ;
|
|
- la validation initiale proportionnée ;
|
|
- les éléments volontairement hors scope.
|
|
|
|
La structure Markdown exacte MAY varier si ces responsabilités restent clairement séparées. PGR MUST NOT imposer des sections vides uniquement pour respecter un format cérémoniel.
|
|
|
|
## Sélection des règles et profils
|
|
|
|
Un skeleton sélectionne les owners normatifs applicables ; il ne redéfinit pas leur contenu.
|
|
|
|
La sélection des profils MUST respecter l'applicabilité, la hiérarchie et la résolution définies dans [`../architecture/003-RULE_PROFILE_MODEL.md`](../architecture/003-RULE_PROFILE_MODEL.md).
|
|
|
|
Lorsqu'une règle générale est déjà applicable sans spécialisation, le skeleton SHOULD la référencer plutôt que la recopier comme si elle lui appartenait. Lors de l'instanciation, le projet destinataire doit néanmoins disposer localement des règles nécessaires à son fonctionnement autonome, sous la forme documentaire réellement adaptée à son propre référentiel.
|
|
|
|
Un skeleton MUST NOT sélectionner toute la bibliothèque PGR par défaut. Les profils ou familles sans rapport avec le projet restent absents.
|
|
|
|
## Templates et artefacts techniques
|
|
|
|
Un template reste un artefact technique copiable distinct du skeleton et de la règle qui justifie son usage.
|
|
|
|
Lorsqu'un skeleton utilise un template, il MUST identifier le template source et les valeurs qui doivent être revues ou adaptées avant adoption. Une valeur d'exemple, un placeholder, une version de toolchain, un nom de crate, un chemin de build ou un seuil de lint présent dans un template MUST NOT devenir une valeur universelle par simple copie.
|
|
|
|
Un skeleton MAY demander de copier un template tel quel seulement lorsque le contrat du template indique qu'aucune décision locale n'est requise pour le scope visé.
|
|
|
|
Un skeleton MUST NOT télécharger des dépendances, installer des toolchains ou exécuter implicitement des commandes externes à la place du projet destinataire. Ces opérations peuvent faire partie d'une validation explicitement demandée lorsque l'environnement et le scope les justifient.
|
|
|
|
## Décisions propres au projet
|
|
|
|
Toute décision qui ne découle pas d'une règle applicable ou d'une contrainte technique établie reste une décision du projet destinataire.
|
|
|
|
Le skeleton MUST distinguer une obligation normative d'une valeur d'exemple, d'un choix recommandé et d'une option libre lorsque cette distinction est nécessaire pour éviter une adoption accidentelle.
|
|
|
|
Les décisions nécessaires à une baseline fonctionnelle MUST être résolues ou laissées comme entrées explicites avant que l'instanciation soit présentée comme terminée. Un choix encore ouvert MUST NOT être converti silencieusement en règle ou valeur par défaut arbitraire.
|
|
|
|
Les décisions locales SHOULD être consignées dans les documents ou configurations qui les possèdent durablement dans le projet créé, et non uniquement dans une trace temporaire d'instanciation.
|
|
|
|
## Composition de plusieurs skeletons
|
|
|
|
La composition SHOULD partir de la fondation la plus générale explicitement requise, puis ajouter les spécialisations réellement applicables.
|
|
|
|
Un skeleton spécialisé SHOULD référencer les responsabilités déjà couvertes par sa fondation plutôt que les recopier. Il MAY ajouter des fichiers, décisions, templates ou validations propres à son scope.
|
|
|
|
L'ordre de composition ne crée aucune priorité normative implicite. Une règle plus spécifique ne remplace une règle plus générale que selon la hiérarchie normative, un profil applicable ou une exception explicitement documentée.
|
|
|
|
Si deux skeletons applicables exigent des choix incompatibles sans relation de spécialisation ou override défini, l'instanciation MUST s'arrêter sur cette décision au lieu de choisir arbitrairement le dernier appliqué.
|
|
|
|
PGR SHOULD NOT créer un skeleton composite pour chaque combinaison de technologies. Un skeleton composite n'est justifié que lorsqu'une interaction réelle possède des étapes, artefacts ou décisions qui ne peuvent pas être correctement possédés par les skeletons composants.
|
|
|
|
## Overrides et exceptions
|
|
|
|
Un override ou une exception MUST identifier la règle, le template, le choix ou l'étape concerné, son scope et sa raison.
|
|
|
|
Un skeleton MAY prévoir des points d'override lorsqu'ils correspondent à une variabilité légitime du projet. Il MUST NOT utiliser cette possibilité pour affaiblir silencieusement une règle applicable ou masquer une incompatibilité entre profils.
|
|
|
|
Une exception propre au projet est possédée par le projet destinataire après instanciation. Elle ne devient pas automatiquement une règle générale PGR.
|
|
|
|
## Validation de l'instanciation
|
|
|
|
Chaque skeleton MUST définir une validation initiale proportionnée à ce qu'il matérialise réellement.
|
|
|
|
La validation SHOULD utiliser le mécanisme le plus fiable disponible : parseur ou build tool officiel, linter, audit structurel read-only, test ciblé ou revue humaine selon la propriété à prouver.
|
|
|
|
Lorsqu'un skeleton prétend produire une baseline directement utilisable par une toolchain, une instanciation temporaire MAY être utilisée pour vérifier les fichiers copiés ou adaptés. Les ressources temporaires SHOULD être isolées et nettoyées après la gate.
|
|
|
|
La réussite d'un audit structurel ne remplace pas une validation de toolchain lorsque le contrat à prouver appartient à cette toolchain. Inversement, PGR SHOULD NOT imposer un build coûteux lorsqu'une propriété purement documentaire ou structurelle suffit à la tranche.
|
|
|
|
Une prévalidation réalisée lors de la préparation d'un delta ne remplace jamais la gate opérateur autoritaire définie par les règles de validation.
|
|
|
|
## Évolution
|
|
|
|
Une skeleton specification est un document vivant tant qu'elle reste la specification courante de son type de projet. Sa révision interne suit les règles documentaires PGR.
|
|
|
|
Modifier un skeleton PGR n'altère pas rétroactivement les projets déjà instanciés. Une migration depuis une ancienne baseline est une décision explicite du projet concerné.
|
|
|
|
PGR matérialise un nouveau skeleton uniquement lorsqu'un besoin réel, des owners normatifs suffisants et les artefacts nécessaires existent. Une technologie encore insuffisamment cadrée reste différée plutôt que représentée par un skeleton placeholder.
|