sasedev-knowledge/docs/rules/300-DOCUMENTATION.md

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

# Documentation locale Knowledge

## Langue et identités

Les noms techniques, chemins, fichiers, crates, identifiants et code sont en anglais. La documentation normative et explicative principale est en français.

Chaque fichier Markdown gouverné par Knowledge commence par :

```text
<!-- file: <chemin relatif exact> -->
<!-- version: <entier positif> -->
```

La révision documentaire augmente lorsqu'un contenu réel du fichier change ; elle n'est pas un compteur global de release et ne doit pas être synchronisée mécaniquement avec `VERSION`.

## Rôle des documents racine

`README.md` est une entrée de projet : identité, état utile, démarrage et liens vers les owners. Il ne devient pas une copie complète des règles ou de l'architecture.

`RULES.md` est l'entrée normative locale et renvoie vers les owners détaillés sous `docs/rules/`.

`ROADMAP.md` décrit la release en cours et un horizon borné des prochaines releases. Il distingue explicitement une mission engagée d'une version d'horizon encore révisable ; l'horizon sert à ordonner les dépendances et à préparer la suite sans transformer chaque intention en engagement irrévocable. Il ne sert ni de journal quotidien ni de catalogue exhaustif des prereleases.

`CHANGELOG.md` synthétise les changements réellement acquis d'une release. Il n'est normalement pas rédigé au démarrage ou pendant le cadrage alpha à partir d'intentions : une entrée candidate est préparée vers les phases de stabilisation, lorsque l'implémentation et les histories permettent de décrire ce qui existe effectivement, puis finalisée avant la promotion stable. Les fixes et essais alpha internes ne sont pas transformés en catalogue exhaustif lorsque leur détail appartient déjà aux deltas/histories.

`docs/000-README.md` indexe la documentation durable et fournit le chemin de lecture principal.

## Familles documentaires

Knowledge distingue :

```text
RULES / docs/rules   contrat normatif local
docs/architecture   architecture et décisions structurantes
docs/studies        analyse avant décision ou réconciliation
docs/plans          pilotage vivant d'une release multi-tranches
docs/validation     matrices, critères et contrats de preuve
docs/templates      patterns locaux réutilisables
prompts              handoff versionné d'ouverture d'une release
deltas               contrat d'une tranche à appliquer
history              résultat réellement observé d'une tranche
```

Un delta/history ne remplace pas la documentation durable. Une décision structurante acquise finit chez son owner durable lorsqu'elle doit gouverner la suite.

## Documents vivants et historiques

`RULES.md`, `docs/rules/`, l'architecture, la roadmap et un plan actif sont des documents vivants : ils évoluent lorsque leur contrat actuel change.

`deltas/`, `history/` et les prompts de releases passées sont historiques après commit. Ils ne sont pas réécrits uniquement pour se conformer à une nouvelle convention apparue plus tard.

Une étude terminée peut rester historique tout en étant référencée depuis la décision durable qu'elle a permis d'établir.

## Plans

Un plan actif contient au minimum, lorsque pertinent : statut/sources, mission, état acquis/questions ouvertes, scope, hors-scope, stratégie de validation, trajectoire prévisionnelle, déclencheurs de REPLAN, clôture/transition et revue d'horizon.

Les phases prévisionnelles se trouvent sous `## Trajectoire prévisionnelle` et utilisent des headings `###`.

Le plan est mis à jour lorsqu'une hypothèse de pilotage devient fausse, pas pour recopier chaque sortie de commande. Les preuves détaillées appartiennent aux histories.

## Revue d'horizon

Lorsqu'une release approche de sa stabilisation, une revue d'horizon explicite réévalue la release suivante et, autant que les dépendances sont suffisamment connues, au moins les deux releases d'horizon qui la suivent. Elle peut engager la prochaine mission, réordonner ou scinder un horizon, maintenir un domaine non numéroté ou reclasser un `DEFER`.

Une version marquée comme horizon n'est pas encore une promesse de scope : son numéro et sa mission peuvent changer à la revue suivante. La roadmap doit néanmoins donner assez de visibilité pour que la release en cours soit développée dans une trajectoire produit cohérente plutôt qu'en isolation.

## Prompts de nouvelle session

Un prompt normal Knowledge repart de la stable Knowledge, de son rapport post-tag lorsqu'il existe, puis du prompt versionné local. Il vérifie les artefacts Knowledge locaux avant de préparer la tranche suivante.

Le prompt de la release suivante est normalement rédigé pendant les dernières phases de la release courante, après sa revue d'horizon. Il fait partie du handoff livré par la stable courante. Les identifiants post-tag qui n'existent pas encore lors de sa rédaction ne sont pas inventés : la session suivante les reçoit dans son texte d'introduction et les vérifie contre l'archive et le rapport réellement publiés.

Il MUST NOT demander de rechercher ou charger PGR ou un autre référentiel externe, sauf lorsque cette release contient explicitement une réévaluation/adoption de ce référentiel.

Le pattern local est [`../templates/001-NEW_SESSION_PROMPT.md`](../templates/001-NEW_SESSION_PROMPT.md).

## Templates

Les templates locaux sont des patterns adaptables, pas des documents normatifs à recopier aveuglément. L'owner normatif reste la règle locale correspondante ; un template sert à réduire les omissions lors de la création d'un nouvel artefact.

## Liens, tables et audits

Les liens Markdown locaux doivent pointer vers des cibles existantes. Les tables source doivent rester syntaxiquement cohérentes. Les arbres générés (`.git`, `node_modules`, `target`, `builds`) n'appartiennent pas au corpus documentaire gouverné.

Les audits Markdown locaux sont read-only :

```text
scripts/audit_markdown_headers.py
scripts/audit_markdown_links.py
scripts/audit_markdown_tables.py
```