pedroknigge/documentation-manager

Gestionnaire de documentation

Connaissance vivante du projet pour les humains et les agents IA. Le code est la source de vérité pour le comment et pour savoir si une affirmation est vraie. AGENTS.md + docs/ capturent le quoi, le pourquoi, les décisions et les plans — mais ne remplacent jamais le code lorsqu'ils sont en désaccord.

Règles fondamentales

1. Privilégiez AGENTS.md comme hub. Si agents.md existe déjà, utilisez-le. Si seul CLAUDE.md existe, soit étendez-le avec un index de documentation, soit ajoutez AGENTS.md et faites des liens croisés — ne créez pas trois hubs concurrents.
2. Chaque document généré/mis à jour utilise des liens Markdown relatifs vers le hub et les documents associés.
3. Ne supprimez jamais de connaissances durables sans raison ; préférez des notes Remplacé par sur les ADR.
4. Ne validez pas automatiquement les commits ni les pushs. Laissez git à l'utilisateur.
5. Rédigez le contenu généré dans la langue de l'utilisateur (ou la langue dominante du dépôt). Ce corps de compétence est en anglais pour la compatibilité de l'écosystème.
6. Privilégiez la précision et l'utilité plutôt que le volume. Ensemble de base d'abord ; documentation optionnelle à la demande.
7. Intention d'abord (au niveau projet). Classez l'Intention : intégrer | auditer | from-zero (et hybride optionnel). Voir Étape 0. Non requis pour une fonctionnalité/plan/synchronisation pure.
8. Le code l'emporte en cas de conflit. Les affirmations documentaires qui échouent à la vérification structurelle sont marquées Contredites/Manquantes — n'inventez pas de code pour correspondre aux documents ; corrigez ou signalez le document.
9. Intégration d'abord (quand Intention=intégrer). Documentation mature → index + lacunes + liens canoniques ; pas de réécriture parallèle de la vision produit/exigences/ADR. Voir adopter-intégrer.
10. Une autorité par sujet. Chaque sujet a un document canonique ; tout le reste crée des liens.
11. Matrice de couverture sur projet adopter/from-zero. Les surfaces produit (navigation, ModuleId, package) apparaissent comme documentées / liées / lacune.
12. Atomicité des fonctionnalités. Un slug ≈ un ModuleId ou un contexte délimité. Les regroupements = index + enfants.
13. Taxonomie des statuts. references/status-taxonomy.md.
14. Bac à sable opt-in / from-zero première classe. Sortie: sandbox:chemin quand l'utilisateur le demande (test/, etc.). Bannière du hub du bac à sable non-SSOT + plan de promotion.
15. Pilote automatique de fonctionnalité (v1.5 / v2). Simple « nouvelle fonctionnalité X » / « documenter X » → la compétence choisit plan vs pack fonctionnalité, applique les non-écritures par défaut, définit le Type (nouvelle fonctionnalité | spike | epic | refonte). Pont d'implémentation (placement / stubs) uniquement sur opt-in (« implémenter », « stubs », « scaffold ») — par défaut documentation seule + indication d'une ligne. Voir modes.md §3 et implementation-bridge.md.
16. Mode plan (v1.3+). Les idées de fonctionnalités nouvelles atterrissent dans docs/plans/<slug>/, pas dans un pack d'implémentation factice ni un bootstrap complet de projet. Promouvoir vers docs/features/<slug>/ quand le code est réel (pas seulement des stubs).
17. Pont ArkGate (v1.4). Si ArkGate est détecté (ark.config.json, ark-check, .ark/, compétences ark) ou si l'utilisateur vient de terminer une porte, exécutez le sous-flux pont : enrichir l'inventaire à partir du contrat ; après passage de porte → synchronisation / audit ciblé ; violations résiduelles → marquer les affirmations Contredites/Partielles — ne réécrivez jamais les documents pour excuser une architecture brisée. Pas d'Ark → pas d'opération. Les indications de placement dans le pont d'implémentation réutilisent les couches Ark lorsqu'elles sont détectées. Voir arkgate-bridge.md et modes.md §9.
18. Tableau de bord des connaissances (v1.6). Vue HTML statique optionnelle des plans/fonctionnalités/affirmations (scripts/generate-docs-dashboard.sh → docs/audit/generated/dashboard.html). Markdown est SSOT ; HTML est gitignoré, vue seule. Proposer après un audit une fois ou sur demande « tableau de bord ». Voir knowledge-dashboard.md et modes.md §10.
19. Durcissement de la compétence (v1.7). Mainteneurs : exécutez validate-skill.sh + test-skill-hardening.sh avant la publication. Agents : détectez l'installation/version via skill-discovery.md ; suggérez une réinstallation quand obsolète (pas de correctif automatique silencieux).
20. Package v2.0. Complète la ligne ×10 : capacités 1.4–1.7 plus suivi via docs/adoption-matrix.md. Le socle d'installation minimal reste 2.0.0 ; polyglotte 2.1.0 ; monorepo 2.2.0 ; équipe 2.3.0 ; Pont complété 2.4.0 ; la ligne actuelle est 2.5.0+ (Système d'exploitation de la connaissance premier incrément vers ×100 — affirmations vivantes + audit CI ; pas un second ×10).
21. Détection de pile polyglotte (v2.1 Tranche A / skill 2.1.0). Lors de la découverte de projet (intégrer / auditer / from-zero / adopter), détectez la pile à partir du système de fichiers (package.json, pyproject.toml, go.mod, …) via skill-discovery.md Détection de pile polyglotte (ou scripts/detect-stack.sh). Utilisez Inventaire par pile et Guide de disposition de documentation par pile — ne supposez pas Node/TS. N'inventez jamais de ModuleIds/points de terminaison pour des frameworks sans preuve de code. Voir modes.md §0.3.
22. Hubs monorepo (v2.2 Tranche B). Détectez les arbres multi-packages (pnpm-workspace.yaml, espaces de travail package.json, go.work, répertoires multi-packages) via skill-discovery.md Hubs monorepo (ou scripts/detect-packages.sh). Le hub racine est une carte + Index de packages, pas un dump ; la couverture multi-package marque les packages lacune ; non-écritures de packages par défaut lors de l'indexation de la racine uniquement. Voir modes.md §0.4.
23. Gouvernance d'équipe (v2.3 Tranche C). docs/team/ optionnel avec propriétaires + notes d'approbation (style dernière approbation). Créer vs lier selon team-governance.md ; le hub lie l'Équipe sans devenir un wiki RH ; intégration d'abord — ajouter une équipe ne doit pas réécrire la vision produit / exigences / ADR. Pas de moteur CODEOWNERS ni BPM. Voir modes.md §11.
24. Télémétrie de template (v2.4 Tranche D). Registre local opt-in pour les lacunes de template/compétence UX uniquement (template-telemetry.md ; scripts/template-telemetry.sh). Désactivée par défaut ; n'envoyez jamais de sources/secrets/URLs de dépôt ; réseau jamais ; sans opération en environnement isolé quand l'opt-in est désactivé. Voir modes.md §12.
25. Affirmations vivantes + audit structurel CI (v2.5 / premier incrément du Système d'exploitation de la connaissance). Les matrices d'audit utilisent les affirmations vivantes v0 : anchor.path / anchor.symbol optionnel / anchor.hash optionnel, severity (critical | normal), verdicts inchangés. Matrice d'abord (audit-template.md) ; procédure living-claims.md ; câblage ADR-0001. Le score de vérité reste indicatif (heuristique du tableau de bord) ; local isolé scripts/audit-claims.sh / exemple CI docs-audit est la porte (échec sur Contredit critique). Pas de SaaS. Voir modes.md §6 / §13.

Étape 0 — Détecter le périmètre, le mode et l'intention

Périmètre (requis) :

Périmètre	Quand	Focus de sortie
projet	Produit entier / « documentation pour le projet »	Hub + documentation projet (selon Intention)
fonctionnalité	Fonctionnalité/module nommé avec du code (ou pack de rafraîchissement)	docs/features/<slug>/ + lien hub
plan	Nouvelle fonctionnalité / epic nommé avant ou sans code solide	docs/plans/<slug>/ + lien hub
hybride	Fonctionnalité/plan quand pas encore de hub	Pack ou plan + hub minimal

Mode (requis) :

Mode	Signaux
bootstrap	Greenfield, pas de hub/docs, ou Intention from-zero sur vide/mince
adopter	Code existe ; docs minces/manquantes ou Intention intégrer
auditer	« auditer les docs », « docs vs code », dérive, valider les affirmations
plan	« nouvelle fonctionnalité », « plan », « epic », « allons construire X » sans code
fonctionnalité	Documenter une fonctionnalité/module qui a (ou est) du code
synchroniser	Diff / PR / mise à jour des docs pour un changement ; post-porte quand Ark vient de passer
feuille de route	Planifier la version / rafraîchir la liste des epics

Intention (requis pour le travail au niveau projet uniquement) :

Intention	Signaux utilisateur (exemples)	Comportement
intégrer	« améliorer les docs », « ordonner », « synchroniser le hub », améliorer mature	adopter-intégrer (ou complet si mince) ; pré-audit optionnel si dérive suspectée
auditer	« auditer », « les docs mentent-elles ? », « docs vs code », « valider les chemins »	Inventaire du code + matrice d'affirmations uniquement (puis passer la main)
from-zero	« tout nouveau », « de zéro », « génère des docs dans test/ », « KB complète dans dossier X »	Base de connaissances complète ; préférer le bac à sable si chemin donné ; déduit du code ; anciennes docs = hypothèse uniquement

Inférence (ne pas trop demander) :

• « nouvelle fonctionnalité X » / « new feature X » / « je veux ajouter X » → Pilote automatique de fonctionnalité (plan si pas de code, fonctionnalité si code ; Type à partir de la formulation). Intention = n/a
• « implémente X » / « génère des stubs » / « scaffold X » → pilote automatique Étape A si nécessaire + Pont d'implémentation opt-in (code uniquement si stubs demandés)
• « génère toute la documentation dans test/ » → Intention : from-zero | Sortie : sandbox:test/
• Dépôt mature + « améliore / intègre / indexe » → Intention : intégrer
• « auditer les docs » / « code vs docs » → Intention : auditer
• Travail de projet ambigu avec docs/ existant → demander une fois : intégrer | auditer | from-zero
• Surface unique nommée → ne jamais demander à l'utilisateur de lister les non-écritures ou de choisir des dossiers
• « after ark-check » / « post-gate docs » / porte vient de s'exécuter + intention de docs → synchroniser ou auditer avec Pont ArkGate
• « tableau de bord » / « docs HTML » / « rapport de connaissances » → générer le Tableau de bord des connaissances (knowledge-dashboard.md)
• « propriétaires » / « qui est propriétaire » / « docs équipe » / « notes d'approbation » / « docs/team » → Gouvernance d'équipe (team-governance.md ; modes §11)
• « télémétrie de template » / « télémétrie opt-in » / « enregistrer lacune de template » → Télémétrie de template uniquement si l'utilisateur opte (template-telemetry.md ; modes §12) ; désactivée par défaut
• « affirmations vivantes » / « score de vérité » / « docs CI » / « échec sur Contredit » → Affirmations vivantes + porte CI locale (living-claims.md ; modes §13)

Maturité (quand pertinent) : mince | mixte | mature — voir modes.md.

Si le périmètre/mode reste ambigu après inférence, demander une fois. Charger les procédures depuis references/modes.md.

Annoncer avant d'écrire :

Périmètre : <x> | Mode : <y> | Intention : <intégrer|auditer|from-zero|n/a> | Variante : <complet|intégrer|pont-arkgate|n/a> | Maturité : <…|n/a> | Sortie : <racine|sandbox:chemin> | Pile : <node-ts|python|go|mixte|inconnu|n/a> | Monorepo : <oui|non|n/a> | ArkGate : <aucun|détecté> | Slug : <slug|n/a>

En mode intégrer, lister les non-écritures (inclure les non-écritures de packages quand index racine monorepo seulement). En mode auditer, lister le chemin de la matrice et les principales contradictions. En mode from-zero + bac à sable, inclure le plan de promotion. En mode plan ou fonctionnalité, lister le chemin + non-écritures par défaut. En mode Pont ArkGate, lister les signaux et la synchronisation post-porte vs audit-enrichissement. Au niveau projet, inclure la Pile et le Monorepo de la découverte.

Disposition recommandée

racine-du-projet/
├── AGENTS.md
└── docs/
    ├── product-vision.md      # bootstrap / from-zero / adopter-complet
    ├── requirements.md
    ├── architecture.md
    ├── roadmap.md
    ├── team/                  # v2.3 gouvernance d'équipe (optionnel)
    │   ├── OWNERS.md
    │   └── approval-notes.md
    ├── audit/                 # Intention auditer (optionnel)
    │   └── claims-matrix.md   # colonnes affirmations vivantes v0
    ├── adr/                   # ADR de package / projet (optionnel)
    ├── plans/<slug>/          # v1.3 mode plan (pré-code / epic)
    │   └── README.md
    ├── decisions/
    └── features/<slug>/       # packs de fonctionnalités adossés au code

Documents de support uniquement lorsque justifiés (sauf from-zero, qui peut créer un ensemble de base minimal complet).

Matrice des artefacts (résumé)

Artefact	from-zero / bootstrap	intégrer (mature)	auditer	plan	fonctionnalité	synchroniser
Hub	créer	étendre / indexer	mettre à jour statut optionnel	lier Plans	lier	si nécessaire
Documents narratifs de base	oui	pas de réécriture	non (lecture seule)	non	non	si impact
Matrice de couverture	oui	requis	partie de l'inventaire	ligne optionnelle	ligne	mise à jour
Matrice d'affirmations	optionnelle pré	recommandé si dérive	requis	n/a	ciblé si audit	si dérive
Plans docs/plans/	n/a	n/a	n/a	requis	lier si existe	si impact
Packs de fonctionnalités	domaines clés	lacunes / entrées	non (sauf demande)	non (jusqu'à promotion)	requis	si impact
Équipe docs/team/	si propriétaires connus	créer/lier si demandé	non	n/a	n/a	si impact
Arbre complet parallèle	bac à sable ok	interdit à la racine	n/a	n/a	n/a	n/a

Workflow (tous les modes)

1. Étape 0 — périmètre, mode, Intention (si projet), maturité/variante, Sortie, slug ; détecter les signaux ArkGate quand pertinent ; détecter la Pile et le Monorepo pour le travail projet (skill-discovery.md Polyglotte + Hubs monorepo).
2. Découvrir le code d'abord — inventaire conscient de la pile ; si monorepo, Index de packages + inventaire par package ; arbre, manifestes, points d'entrée, exemples de tests. Ensuite les docs (si existantes). Pour les fonctionnalités nommées, rechercher cette surface d'abord. Si Ark détecté, enrichir l'inventaire selon arkgate-bridge.md.
3. Si audit ou docs existent et Intention est intégrer/from-zero avec dérive suspectée : exécuter la réconciliation (modes.md § Audit, audit-template.md). Post-porte → transfert pont (modes.md §9).
4. Planifier les fichiers — crée/met à jour et non-écritures (par défaut pour fonctionnalité/plan).