System Modification Documentation — Politique Permanente

Déclencheur

Toute modification système importante (installation, config, service, réseau, sécurité, suppression) DOIT produire 8 artefacts obligatoires avant d’être considérée comme terminée.

Artefacts Obligatoires

Contenu du Change Log (Artefact 1)

Chaque entrée contient :

• Date (ISO 8601)
• Machine (MX / VPS-vmi2802045)
• Auteur (Hermès / utilisateur)
• Quoi (description précise de la modification)
• Pourquoi (motivation, issue, ticket)
• Commandes exactes exécutées (reproductibles)
• État avant / État après (fichiers, services, ports)

Contenu du Plan de Rollback (Artefact 2)

• Sauvegarde : copie .bak.$(date +%Y%m%d_%H%M%S) de chaque fichier modifié
• SCRIPTS : script shell idempotent qui restaure l’état antérieur
• Procédure manuelle : étapes déterministes si le script échoue
• Vérification : comment confirmer que le rollback a réussi

Format du Guide Utilisateur (Artefact 3 — Diátaxis How-to)

• Orienté tâche : “Pour faire X, exécutez Y”
• Langage simple, étapes numérotées
• Exemples concrets avec sorties attendues
• Sections : Prérequis → Étapes → Vérification → Exemples

Format du Guide Admin (Artefact 4 — Runbook SRE)

• Procédure déterministe d’installation/maintenance
• Reproductible à l’identique depuis un état vierge
• Commandes exactes, chemins, variables d’environnement
• Sections : Provisioning → Installation → Configuration → Démarrage → Maintenance

Format du Troubleshooting (Artefact 5 — Playbook SRE)

Tableau : Symptôme | Cause probable | Résolution

Format de l’Explication (Artefact 6 — Diátaxis Explanation)

• Comment ça marche (architecture)
• Pourquoi ces choix techniques
• Alternatives considérées et écartées
• Conséquences de la modification

Format de la Fiche de Référence (Artefact 7)

• Versions exactes (logicielles, dépendances)
• Chemins absolus (fichiers, configs, logs)
• Ports (interne/externe)
• Variables d’environnement (sans secrets)
• Services concernés (noms systemd/Docker)

Format Dépendances & Risques (Artefact 8)

• Dépendances ascendantes (ce dont dépend le système)
• Dépendances descendantes (ce qui dépend de ce système)
• Risques identifiés (probabilité + impact)
• Mitigations en place
• Prérequis oubliés ou sous-estimés

Contraintes

1. Aucun secret en clair dans les logs ou guides (clés, mots de passe, tokens)
2. Chaque artefact horodaté et rattaché à la machine sans ambiguïté
3. Stocker dans ~/.hermes/skills/<nom-tache>/, versionner dans Git, synchroniser hors-machine (rclone)
4. Afficher un résumé dans le dashboard avec le chemin des artefacts complets
5. Format idempotent et reproductible ; privilégier les scripts aux actions improvisées
6. Respecter la hiérarchie de fiabilité (FAIT VÉRIFIÉ > INFÉRENCE > HYPOTHÈSE)

Journalisation Transversale (shared_log.md)

En plus du changelog local à la tâche, chaque modification DOIT journaliser une entrée dans ~/shared_log.md :

[DATE] | [MACHINE] | Hermès | [brève description] | [STATUT] | [HASH_GIT]

Cette entrée sert de registre chronologique transversal entre toutes les tâches et les deux machines (MX + VPS), indépendant des dossiers skills/.

Fichiers Associés

Ce skill est livré avec :

Méthode d’Application — Workflow Complet

Étapes à suivre pour chaque modification système :

1. SNAPSHOT : copie .bak.$(date +%Y%m%d_%H%M%S) de chaque fichier modifié
2. STORE dans ~/.hermes/skills/<nom-tache>/{changelog,rollback,docs}/
3. WRITE les 8 artefacts (utiliser les templates comme base, adapter au contexte)
4. COMMIT : git add -A && git commit -m "DOCS: <nom-tache> - artefacts 8/8"
5. LOG : ajouter une entrée dans ~/shared_log.md
6. RÉSUMÉ : afficher le tableau de bord avec tous les chemins

Critère de Succès

En lisant ces seuls artefacts après une réinstallation ou un incident, je dois pouvoir reproduire, comprendre, dépanner et annuler la modification sans rien deviner.

Pipeline Automatisé de Documentation (log-all)

Toute exécution de commande système, cron, agent, ou compilation DOIT être journalisée via le pipeline log-all. Ce système — absorbé du skill system-doc-log — journalise chaque action dans un registre central et synchronise automatiquement avec Google Sheets.

Workflow

1. Chaque action passe par scripts/log-all.sh "<catégorie>" "<action>" "<détails>" "succès|échec"

2. Le script génère un JSON au format registre dans ~/central/modifications/ pour chaque entrée

3. scripts/sync-registre.py :

   • Lit les .json dans ~/central/modifications/
   • Alimente le fichier unifié Markdown ~/central/registre-systeme.md
   • Synchronise vers Google Sheets (onglet “Registre” ou “raw”)

Références et supports

Journalisation Obligatoire

Sont soumis au pipeline :

• Exécutions de commandes système (install, désinstall, config)
• Lancements de cron jobs (planifiés ou manuels)
• Appels d’API distants (Google Sheets, Notion, cloud)
• Compilations et résultats de build
• Résultats des agents autonomes

Format minimal : [YYYY-MM-DD HH:MM:SS] [CATÉGORIE] ACTION — RÉSULTAT

Capture Proactive de Connaissances en Session

Absorbé du skill guide-capture.

Quand une information échangée en session a une valeur durable (survit à la session en cours), proposer proactivement à l’utilisateur de la sauvegarder comme guide de référence.

Déclencheurs — quand proposer la sauvegarde

Proposer systématiquement si l’information concerne :

Ne PAS proposer pour :

• Réponses factuelles ponctuelles
• Commandes one-shot sans valeur répétable
• Informations déjà dans un guide existant

Formule à utiliser

“Cette information a une valeur durable. Tu veux que je la sauvegarde comme guide dans ~/Bureau/guides-terminal-distant/ ?”

Si oui : créer le fichier .md avec un titre pertinent et numérotation séquentielle (vérifier le dernier numéro dans le dossier).

Emplacement des guides

~/Bureau/guides-terminal-distant/
├── 01-linux-vers-vps.md
├── 02-wsl-vers-vps.md
├── ...
└── 07-agents-tmux-bonnes-pratiques.md

Relation avec les 8 artefacts

Les guides capturés ici sont plus légers que les 8 artefacts obligatoires : ils capturent une connaissance (souvent procédurale), pas une modification (qui nécessite traçabilité complète). Les deux sont complémentaires.