pgr/docs/rules/300-DOCUMENTATION.md

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

# 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 du projet : objectifs de versions, grandes étapes et ordre fonctionnel attendu.

Il MUST NOT devenir un journal des prereleases ou recopier les histories de tranche.

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.

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

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

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