4.8 KiB
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 :
<!-- 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 les objectifs et horizons produits réellement engagés. Il ne sert ni de journal quotidien ni de catalogue exhaustif des prereleases. Une version future n'y est pas réservée sans mission réelle.
CHANGELOG.md synthétise les changements utiles aux jalons de release. 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 :
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 et que la suite n'est pas déjà décidée, une revue d'horizon explicite détermine s'il faut engager une prochaine mission, maintenir les domaines futurs non numérotés ou reclasser un DEFER.
La revue n'invente pas un numéro de version uniquement pour assurer la continuité documentaire.
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.
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
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 :
scripts/audit_markdown_headers.py
scripts/audit_markdown_links.py
scripts/audit_markdown_tables.py