pgr/docs/rules/300-DOCUMENTATION.md

<!-- file: docs/rules/300-DOCUMENTATION.md -->
<!-- version: 4 -->

# Documentation rules

## Scope

Ce document définit les règles communes de documentation gouvernée par PGR : rôle des documents, taxonomie, révision interne des fichiers, distinction entre documents vivants et snapshots historiques, conservation et suppression.

La documentation doit réduire le coût de compréhension et de reprise du projet. Elle MUST NOT devenir une duplication systématique du code, des manifests ou de l'historique de release.

## Responsabilités documentaires

Chaque type de document doit conserver une responsabilité claire.

### Root `README.md`

Le `README.md` racine présente le projet et fournit l'onboarding et la navigation de premier niveau.

Il SHOULD rester concis et pointer vers les documents spécialisés plutôt que recopier leurs contenus.

### `docs/000-README.md`

`docs/000-README.md` est l'index principal de la collection documentaire lorsqu'un projet possède une documentation structurée sous `docs/`.

Il décrit l'organisation documentaire et les points d'entrée utiles ; il MUST NOT devenir un second README produit ou un journal de release.

Un sous-ensemble documentaire MAY utiliser son propre `000-README.md` lorsqu'un index local améliore réellement la navigation.

### README local

Un `README.md` local à un composant, module ou répertoire décrit la responsabilité et les informations d'entrée propres à ce composant.

Il SHOULD NOT recopier la documentation globale qui reste mieux possédée ailleurs.

### `USAGE.md`

Lorsqu'il existe, `USAGE.md` est un guide d'utilisation durable et autant que possible indépendant d'une version précise.

Il peut contenir exemples, scénarios, contraintes opérationnelles et contrats d'utilisation. Il MUST NOT servir de changelog, de preuve de validation, de résumé de prerelease ou de history de tranche.

### `RULES.md`

`RULES.md` est le point d'entrée normatif du projet. Il présente la hiérarchie et les règles fondamentales et renvoie vers les familles détaillées lorsque celles-ci existent.

Il SHOULD NOT devenir un fichier monolithique contenant toutes les règles spécialisées.

### `ROADMAP.md`

`ROADMAP.md` décrit la trajectoire macro **engagée** du projet : objectifs de versions, grandes étapes et ordre fonctionnel attendu. Elle n'est ni un catalogue de toutes les possibilités futures, ni une obligation de prévoir arbitrairement plusieurs versions à l'avance.

Il MUST NOT devenir un journal des prereleases ou recopier les histories de tranche. Une idée, une étude ou une possibilité encore spéculative reste chez son owner tant qu'une décision suffisante ne justifie pas son entrée dans la trajectoire engagée.

Lorsqu'un projet utilise des statuts de roadmap, la convention PGR est :

```text
( ) planned
(x) completed
(d) deferred
(c) cancelled
```

Une autre convention MAY être adoptée par un projet si elle est explicitement définie et cohérente.

Une roadmap à horizon fini est valide. Le projet MUST NOT inventer un numéro de version, un objectif ou un engagement uniquement pour éviter que la roadmap se termine.

### Revue d'horizon

Une revue d'horizon est une activité de gouvernance qui décide si la trajectoire macro connue doit être étendue, maintenue volontairement ouverte, mise en pause ou considérée accomplie. Elle n'est pas une nouvelle phase SemVer.

Une revue SHOULD être planifiée lorsque l'un des signaux suivants devient pertinent :

- la release courante ou la suivante est la dernière entrée engagée de la roadmap alors que le projet doit continuer ;
- un jalon important change ce qu'il est raisonnable de planifier ensuite ;
- plusieurs ideas/studies ou décisions récentes peuvent modifier la trajectoire ;
- les hypothèses qui fondaient les versions futures ont été invalidées par le travail réel.

La revue MAY avoir lieu dans une tranche de la release courante ou dans une session stratégique séparée. Une session séparée ne change pas `VERSION` par elle-même.

Une revue d'horizon produit l'un des résultats utiles suivants :

- **étendre** `ROADMAP.md` avec des objectifs suffisamment décidés ;
- **laisser l'horizon ouvert** et enregistrer le déclencheur ou le moment de la prochaine revue ;
- **différer/mettre en pause** une trajectoire sans fabriquer de remplaçant ;
- **constater l'accomplissement** de l'objectif macro si aucune suite n'est nécessaire.

Le plan actif SHOULD indiquer si une telle revue est nécessaire avant sa fermeture et où elle aura lieu.

### `CHANGELOG.md`

`CHANGELOG.md` décrit les changements utiles aux utilisateurs ou intégrateurs d'une release.

Par défaut, les tranches `alpha` et `beta` ne doivent pas créer de bruit de changelog simplement parce qu'elles existent. Une RC MAY préparer l'entrée de release et la stable la finalise.

Un projet MAY documenter des prereleases publiquement distribuées lorsque cela apporte une information réelle aux consommateurs.

### Objectifs

Un document sous `docs/objectives/` décrit la mission durable, les objectifs, contraintes et non-objectifs du projet.

Il MUST NOT être remplacé par `ROADMAP.md` : les objectifs expliquent pourquoi le projet existe et ce qu'il cherche à garantir ; la roadmap décrit comment sa trajectoire est découpée.

## Registre local de contrats de fichiers ou familles

Un projet MAY maintenir un registre local lorsque plusieurs fichiers ou familles durables ont des responsabilités, sources de vérité ou règles de modification qui ne sont pas suffisamment évidentes depuis leur nom, leur écosystème ou leurs owners existants.

Ce registre est un outil de désambiguïsation, pas un inventaire exhaustif de l'arborescence. Il MUST NOT être créé uniquement pour recopier les rôles déjà définis par PGR, un manifeste, une toolchain ou une documentation locale plus appropriée. Un petit projet dont les responsabilités sont déjà claires SHOULD ne pas créer ce document.

Chaque entrée utile SHOULD identifier au minimum :

- le fichier, motif de chemin ou famille concernée ;
- sa responsabilité durable ;
- la règle ou le déclencheur pertinent de modification.

Selon le besoin, une entrée MAY aussi préciser une source de vérité, le caractère généré/versionné, un owner local ou une validation associée. Ces champs supplémentaires ne doivent être ajoutés que s'ils réduisent réellement une ambiguïté.

Le nom, l'emplacement et la forme du registre appartiennent au projet destinataire. PGR n'impose ni `FILE_CONTRACTS.md`, ni une table Markdown, ni un catalogue de chaque fichier. Une liste courte, une table ou une autre forme lisible sont équivalentes si le contrat reste explicite.

Lorsqu'un owner existant possède déjà la règle détaillée, le registre SHOULD le référencer plutôt que dupliquer son contenu. Il est mis à jour lorsque le contrat d'une famille change réellement ; l'ajout d'un fichier conforme à une famille déjà décrite ne force pas une nouvelle entrée.

[`../templates/004-FILE_FAMILY_CONTRACTS.md`](../templates/004-FILE_FAMILY_CONTRACTS.md) fournit un pattern documentaire court pour les projets qui choisissent d'adopter ce registre.

## Taxonomie documentaire

La taxonomie doit rester sémantique et proportionnée. Les familles communes comprennent notamment :

```text
docs/rules/
docs/objectives/
docs/ideas/
docs/studies/
docs/architecture/
docs/plans/
docs/validation/
docs/development/
docs/testing/
docs/operations/
docs/reference/
docs/formats/
```

Ces répertoires ne sont créés que lorsqu'ils possèdent un contenu réel.

Un répertoire générique tel que `misc/` SHOULD NOT devenir la destination par défaut des documents dont la responsabilité n'a pas été déterminée.

Une technologie ou un projet MAY introduire des familles supplémentaires lorsqu'elles représentent une responsabilité documentaire stable.

## Idées, études et décisions

Une idée est une possibilité non engagée. Elle ne doit pas être présentée comme une décision ou une promesse de roadmap.

Une étude existe lorsqu'un choix réel doit être comparé ou démontré. Elle SHOULD expliciter la question, les contraintes, les options pertinentes, les observations et la décision ou conclusion lorsqu'elle existe.

Si une décision est déjà imposée par une contrainte explicite et qu'aucune alternative réelle n'est ouverte, une étude artificielle SHOULD NOT être créée uniquement pour respecter un processus.

Les décisions durables doivent ensuite être reflétées dans l'architecture, les règles, objectifs ou autres documents vivants qui possèdent réellement ce contrat.

La maturation typique MAY suivre :

```text
idea
  ↓
study
  ↓
decision durable / architecture / règle
  ↓
roadmap ou plan lorsqu'un engagement de réalisation existe
  ↓
implementation
```

Toutes les possibilités n'ont pas à parcourir cette chaîne. Une idée ou une étude MAY être rejetée, différée, superseded ou rester inconclusive. Une conclusion `retained` ne crée pas automatiquement une promesse de roadmap : le passage vers `ROADMAP.md` exige encore une décision d'engagement macro explicite.

## Documents vivants et snapshots historiques

PGR distingue :

```text
living document
→ décrit l'état ou le contrat courant et évolue lorsque cet état change réellement

historical snapshot
→ enregistre un état, une décision ou une preuve à un instant donné
```

Exemples de documents généralement vivants :

```text
README.md
RULES.md
ROADMAP.md
docs/000-README.md
PROJECT_PROFILE
validation matrix
architecture courante
```

Exemples de snapshots généralement historiques après livraison/commit :

```text
delta
history
handoff livré
étude conclue conservée comme preuve
release/publish record
```

Un snapshot historique MUST NOT être réécrit silencieusement pour correspondre à l'état courant. Une correction factuelle importante doit être explicite et préserver la traçabilité utile.

Un document vivant SHOULD être mis à jour lorsqu'un changement rend son contenu réellement obsolète ; il ne doit pas être modifié à chaque tranche uniquement pour créer une trace d'activité.

## Header `file` / `version`

Pour les formats texte qui acceptent naturellement des commentaires, PGR SHOULD utiliser un header interne de la forme :

```text
file: relative/path
version: N
```

La syntaxe de commentaire dépend du format. Pour Markdown :

```html
<!-- file: docs/example.md -->
<!-- version: 1 -->
```

Dans le dépôt PGR, `README.md`, `RULES.md`, `ROADMAP.md`, `CHANGELOG.md` et les fichiers Markdown gouvernés sous `docs/`, `deltas/`, `history/` et `prompts/` MUST placer ces deux commentaires sur leurs deux premières lignes. Le `file` MUST être le chemin relatif depuis la racine du dépôt et `version` MUST être un entier positif sans zéro initial. `scripts/audit_markdown_headers.py` contrôle mécaniquement ces deux champs pour les chemins explicitement sélectionnés. Ce contrôle ne juge ni le contenu du document, ni si le numéro de révision a réellement été incrémenté lors d'un changement.

`file` identifie le chemin relatif canonique du fichier.

`version` est une révision interne du fichier. Elle est indépendante de `VERSION`, de SemVer produit, des versions de protocole, de schema ou de package.

La révision interne MUST être incrémentée lorsqu'un fichier subit une modification réelle gouvernée ou un déplacement qui modifie son chemin canonique. Elle SHOULD NOT être incrémentée pour une opération de formatage strictement mécanique qui ne modifie aucun contenu gouverné.

Lors d'un déplacement, le header `file` MUST être mis à jour vers le nouveau chemin.

Les formats stricts ou formats dans lesquels un tel header serait invalide MUST NOT recevoir de champ artificiel uniquement pour satisfaire cette convention. La provenance ou révision est alors portée ailleurs si nécessaire.

## Noms et ordre documentaire

Les noms de fichiers doivent refléter leur responsabilité. Les suffixes vagues ou chronologiques tels que `new`, `old`, `final2` SHOULD NOT être utilisés comme mécanisme de versionnement.

Un préfixe numérique MAY être utilisé pour stabiliser la navigation d'une collection documentaire lorsqu'un ordre est utile. Le numéro organise la lecture ; il ne constitue pas un identifiant normatif de règle.

## Conservation, suppression et remplacement

Une documentation historique utile SHOULD être conservée lorsqu'elle explique une décision, une migration ou permet une reprise fiable.

Un document MAY être supprimé lorsqu'il est devenu nuisible, réellement obsolète, redondant ou explicitement superseded. Lorsque la suppression n'est pas évidente, le changement SHOULD identifier la raison et le remplacement éventuel.

PGR MUST NOT imposer la conservation infinie de contenu sans valeur de preuve ou de reprise.

## Langues et traductions

Le choix de langue appartient au projet et doit rester cohérent avec ses règles locales.

Pour PGR lui-même, la nomenclature technique, les chemins, identifiants et le code restent en anglais tandis que les explications normatives sont en français.

PGR MUST NOT créer d'arborescence `fr/`, `en/`, `de/` ou équivalente dans son dépôt principal. Une traduction intégrale éventuelle appartient à un dépôt distinct tel que `pgr-en`, `pgr-de` ou `pgr-ar`.

## Documentation proportionnée

Un document SHOULD exister lorsqu'il possède une responsabilité durable, une décision, une preuve ou une information de reprise qui ne serait pas mieux portée ailleurs.

PGR MUST NOT imposer :

- un document vide pour satisfaire une structure théorique ;
- une copie de la même information dans plusieurs fichiers sans propriétaire clair ;
- un document de décision lorsqu'aucune décision n'est réellement ouverte ;
- une mise à jour documentaire purement cérémonielle à chaque tranche.

La documentation est une aide au développement et à la maintenance, pas une fin en soi.