0.0.5-alpha.3

docs/templates/004-FILE_FAMILY_CONTRACTS.md

@@ -0,0 +1,80 @@
+<!-- file: docs/templates/004-FILE_FAMILY_CONTRACTS.md -->
+<!-- version: 1 -->
+
+# Pattern — contrats locaux de fichiers ou familles
+
+## Objectif
+
+Ce pattern aide un projet à expliciter quelques responsabilités de fichiers ou familles durables lorsqu'elles deviennent difficiles à déduire de l'arborescence, de la toolchain ou des règles déjà existantes.
+
+Il complète le contrat documentaire de [`../rules/300-DOCUMENTATION.md`](../rules/300-DOCUMENTATION.md). Il n'impose aucun fichier particulier au projet destinataire.
+
+## Quand l'utiliser
+
+Créer un registre local seulement lorsqu'il réduit une ambiguïté réelle, par exemple lorsque :
+
+- plusieurs familles voisines ont des rôles différents qui provoquent régulièrement des erreurs de placement ;
+- un fichier est une source de vérité tandis qu'un autre est généré ou dérivé ;
+- une famille possède une règle de modification ou de synchronisation non évidente ;
+- des contributeurs doivent savoir quel owner modifier sans relire plusieurs documents spécialisés.
+
+Ne pas l'utiliser pour inventorier chaque fichier d'un petit dépôt, recopier les rôles standards déjà décrits par PGR ou dupliquer un manifeste/build system qui possède déjà l'information.
+
+## Forme minimale
+
+Le nom et l'emplacement appartiennent au projet destinataire. `docs/rules/FILE_CONTRACTS.md` est un nom possible, pas une convention PGR obligatoire.
+
+Une entrée utile contient au minimum :
+
+```text
+file or family
+responsibility
+modification rule
+```
+
+Lorsque ces informations sont utiles, le projet MAY ajouter :
+
+```text
+source of truth / generated status
+local owner or reference
+validation or synchronization requirement
+```
+
+Une table Markdown convient aux registres structurés :
+
+```markdown
+| Fichier ou famille | Responsabilité | Règle de modification |
+|--------------------|----------------|------------------------|
+| `<path-or-pattern>` | `<rôle durable>` | `<quand/comment modifier>` |
+```
+
+Une liste courte est préférable lorsqu'elle reste plus lisible. La forme n'est pas normative ; la clarté de la responsabilité l'est pour le projet qui choisit d'adopter ce contrat.
+
+## Règles d'adaptation
+
+Lors de l'instanciation :
+
+1. sélectionner uniquement les fichiers ou familles dont le contrat local apporte une information non évidente ;
+2. référencer l'owner détaillé existant au lieu de recopier ses règles ;
+3. regrouper les chemins qui partagent réellement le même contrat plutôt que créer une entrée par fichier ;
+4. distinguer explicitement source de vérité et artefact généré lorsque cette distinction existe ;
+5. supprimer ou fusionner une entrée devenue redondante lorsque son rôle est désormais évident ailleurs.
+
+Le registre SHOULD évoluer lorsqu'une responsabilité ou règle de modification change réellement. Il SHOULD NOT être modifié uniquement parce qu'un nouveau fichier respecte déjà une famille décrite.
+
+## Exemple abstrait
+
+```markdown
+| Fichier ou famille | Responsabilité | Règle de modification |
+|--------------------|----------------|------------------------|
+| `config/*.example` | Décrire les exemples versionnés de configuration locale. | Mettre à jour lorsqu'une option utilisateur versionnée est ajoutée ou retirée ; ne jamais y placer de secret réel. |
+| `generated/**` | Contenir les sorties reconstruisibles produites par la toolchain choisie. | Ne pas modifier manuellement ; régénérer depuis la source de vérité documentée. |
+```
+
+Cet exemple illustre la forme uniquement. Il ne crée aucune règle universelle sur les chemins `config/` ou `generated/`.
+
+## Critère de sortie
+
+Le pattern est utile si un nouveau contributeur peut déterminer plus vite où une responsabilité vit et quand modifier une famille sans devoir maintenir un catalogue parallèle du dépôt.
+
+S'il ajoute davantage de cérémonie que d'information, ne pas l'instancier ou le retirer.