docs: consignes tâche 2 (design moteur templates) + gate de validation

tache2.md: mission design/investigation, périmètre strict, clôture obligatoire.
validation_tache2.md: grille de validation, gate avant toute phase de dev.
amelioration.md: retour d'usage (séparation terminal entre machines).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -8,3 +8,6 @@ reports/*
 # Dépôts de référence (git imbriqués) — inspiration uniquement, gérés séparément
 linux-update-dashboard/
 nas-ops/
+
+# Clé de session dev (jamais commitée)
+.dev-session-key.txt

amelioration.md

@@ -0,0 +1,2 @@
+- dans l onglet terminal, il n y a pas de separation franche entre 2 machines distincte ou totalement separe? 
+- dans le champ host on peut mettre ip ou nostname .local ou .home ?

tache2.md

@@ -0,0 +1,139 @@
+# Consigne de dev — Moteur de templates de mise à jour (investigation & brainstorming)
+
+> **Type** : mission d'**investigation + brainstorming + design** (PAS d'implémentation).
+> **Destinataire** : un agent de développement autonome (Claude Code ou équivalent), sans contexte préalable du projet.
+> **Langue** : français.
+> **Livrable final attendu** : un (ou plusieurs) document(s) de design/spec prêts à passer en plan d'implémentation — pas de code de production à ce stade.
+
+---
+
+## 0. Comment aborder cette mission
+
+Tu travailles dans le dépôt `system_update`. **Commence par lire** ces fichiers (ils contiennent tout le contexte) :
+
+- `CLAUDE.md` — règles du projet (sécurité, langue, architecture, rôle d'Hermes/MCP).
+- `deep-research-report(7).md` — étude d'architecture (contrats JSON canoniques, flux, sémantique APT/Docker, réduction déterministe pour LLM).
+- `docs/superpowers/specs/2026-06-04-jalon1-tranche-verticale-apt-design.md` — ce qui est déjà construit (jalon 1).
+- `ajout.md` — périmètre du volet Hermes et du serveur MCP.
+- Code existant à étudier (le jalon 1 est en prod, validé sur Debian + Ubuntu réels) :
+  - `templates/apt/` — `check.sh.tpl`, `full-upgrade.sh.tpl`, `reboot.sh.tpl` (convention actuelle des templates).
+  - `server/templates/render.ts` (rendu Mustache), `server/templates/aptReduce.ts` (réducteur de lignes).
+  - `server/services/aptParse.ts` (parsing de la sortie APT), `server/services/refresh.ts`, `server/services/execute.ts`.
+  - `server/ssh/client.ts` (exécution SSH : sudo -S, script en base64, streaming).
+  - `shared/types.ts` (types JSON canoniques `UpdateSnapshot`, `ExecutionResult`).
+- Dépôts de référence (lecture seule, **inspiration et non copie** — vérifier les licences, `linux-update-dashboard` est en AGPL-3.0) :
+  - `nas-ops/` — scripts Bash JSON-friendly : `nas-system-update`, `nas-system-upgrade`, `nas-docker-pull`, `nas-docker-up`, `nas-docker-prune`. **La meilleure référence pour cette mission.**
+  - `linux-update-dashboard/` — orchestration web SSH multi-machines.
+
+**Méthode imposée** : utilise le workflow superpowers — `brainstorming` (explorer, poser des questions une à une), puis `writing-plans` plus tard. Ici, arrête-toi au **design/spec validé**. Ne code pas le moteur final dans cette mission.
+
+> ### ⛔ Périmètre strict — ne pas déborder
+> Tu travailles **exclusivement sur cette tâche 2** (le design du moteur de templates décrit ici).
+> - **N'implémente pas** le code de production, ne refactore pas l'existant, ne touche pas au jalon 1 ni au jalon 2 (polish design system) en cours.
+> - **Ne démarre aucun autre chantier** non listé dans ce document, même s'il te paraît utile : note-le comme suggestion dans tes livrables, mais ne l'exécute pas.
+> - Si une question dépasse le cadre de la tâche 2, **liste-la et arrête-toi** plutôt que d'élargir le périmètre.
+> - En cas de doute sur le périmètre, **demande** plutôt que de présumer.
+
+> ### 📝 Clôture obligatoire
+> **À la fin de ta mission, mets à jour ce fichier `tache2.md`** : ajoute une section **« État d'avancement / Ce qui a été fait »** en bas, récapitulant — les livrables produits (avec chemins), les décisions prises, les questions tranchées, ce qui reste ouvert, et les sous-jalons recommandés. Ce fichier doit refléter l'état réel de la mission une fois terminée.
+
+---
+
+## 1. Contexte produit (résumé)
+
+Webapp de mise à jour distante de machines Linux (Debian, Ubuntu, Proxmox, Raspberry Pi OS) + Docker Compose, pilotée par **SSH agentless**. Le jalon 1 a prouvé l'ossature sur un cas minimal : ajout machine → refresh APT → tuile → `full-upgrade`/`reboot` avec terminal live → rapport Markdown archivé.
+
+**Principe directeur** : la logique métier « comment mettre à jour » vit dans des **templates shell versionnés sur disque** (esprit `nas-ops`), rendus en Mustache et poussés en SSH. Le backend orchestre, parse les sorties en **JSON canonique**, archive logs + rapports. Hermes (copilote IA, via serveur MCP) **analyse** les JSON mais **n'exécute jamais** de SSH et **ne reçoit jamais de secret**.
+
+**Conventions techniques actuelles à respecter / questionner** :
+- Les templates émettent des marqueurs de section `===SU:XXX===` ; le backend extrait les sections et parse en TS (`aptParse.ts`).
+- Exécution : `LC_ALL=C`, `DEBIAN_FRONTEND=noninteractive`, script entier lancé sous `sudo -S` (mot de passe sur stdin), encodé base64 pour éviter le quoting.
+- Réduction déterministe des logs **avant** tout envoi à un LLM (`aptReduce.ts` : ne garde que `Inst/Conf/Remv/Err/E:/W:/dpkg:/reboot-required`).
+- Deux messages JSON canoniques : **snapshot de disponibilité** (ce qui *sera* appliqué) et **résultat d'exécution** (ce qui *a été* appliqué). Voir `shared/types.ts` et le rapport.
+
+---
+
+## 2. Objectif de la mission
+
+Concevoir (investigation + design, pas implémentation) le **moteur de templates de mise à jour complet** et les **contrats de données** associés, couvrant cinq axes :
+
+### Axe A — Templates APT complets et OS-aware
+Concevoir l'inventaire et le contenu des templates pour : `update` (refresh index, déjà partiellement là), `upgrade`, `full-upgrade`, `dist-upgrade`, `clean`, `autoremove`, plus `reboot`/`reboot-check`.
+- Clarifier la **sémantique exacte** de chaque commande (s'appuyer sur le manpage APT cité dans le rapport) : `upgrade` n'enlève/installe pas de paquets, `dist-upgrade`/`full-upgrade` gèrent les changements de dépendances, `clean` vide le cache, `autoremove` retire les dépendances inutiles.
+- **Profils par OS** : Debian, Ubuntu, Proxmox (`apt update` puis `apt dist-upgrade`, dépôts pve), Raspberry Pi OS. Le moteur doit être *profile-aware*, pas du collage de commandes. Proposer un mécanisme de profils + overrides par machine.
+- Gérer le **proxy APT** (apt-cacher-ng) : modes direct / temporaire à l'exécution / persistant dans `/etc/apt/apt.conf.d/`.
+
+### Axe B — Capture des mises à jour *prévues* et *appliquées* (pour Hermes)
+- **Avant** : produire le snapshot des updates disponibles (paquets, versions courante→cible, origine, reboot requis). Déjà amorcé pour `full-upgrade` simulé ; étendre et fiabiliser.
+- **Après** : produire un résultat d'exécution avec le **diff réel avant/après** (paquets effectivement modifiés, versions finales, erreurs résiduelles, reboot requis après coup).
+- Définir comment ces données alimentent **Hermes** : déduplication par empreinte fonctionnelle (`os_family + package + from + to + origin`), lignes importantes seulement, log brut archivé à part. Réfléchir au format consommable par le serveur MCP.
+
+### Axe C — Gestion des erreurs
+- Taxonomie des erreurs APT/dpkg : lock occupé, dépôt injoignable, conflit de paquets, `dpkg --configure -a` requis, espace disque, clé GPG, etc.
+- Stratégie : codes de sortie normalisés, capture des lignes d'erreur pertinentes, statut `ok|warning|error`, conseils de remédiation (sans auto-réparation dangereuse non validée).
+- Robustesse : idempotence, reprise, opérations longues qui survivent à une coupure SSH (le jalon 1 prévoyait `nohup` + fichier exit-code — à généraliser ou non, à trancher).
+
+### Axe D — Docker Compose
+Concevoir les templates/contrats pour : **scan** des stacks Compose, `pull`, `up -d` (avec `--remove-orphans`), `down`, **prune des images inutilisées** (`docker image prune` / `system prune`, en distinguant le sûr du destructif).
+- Détection des stacks : via labels des conteneurs en cours (`com.docker.compose.project.working_dir`, comme `nas-ops`) **et** fallback par scan des **répertoires Compose déclarés depuis le frontend** (stacks non démarrées).
+- Détection des updates d'image : comparer les IDs/digests avant/après `pull` ; lire les labels de version/source quand ils existent. JSON compact listant uniquement les conteneurs réellement concernés.
+- Étendre les schémas JSON canoniques au volet `docker` (le rapport en donne un exemple).
+- Sécurité du `prune` : exiger une validation explicite côté webapp (action destructive).
+
+### Axe E — Scripts personnalisés (post-install, installation de paquets)
+- Modèle pour des **scripts custom versionnés** : installation de paquets ad hoc, hooks **post-install**, configuration réseau, etc.
+- Overrides par machine, variables de contexte, prévisualisation avant exécution (`preview_template`).
+- Garde-fous : validation opérateur, pas de secret dans les scripts, traçabilité (rapport + log).
+
+---
+
+## 3. Questions d'investigation à trancher
+
+Produire des réponses argumentées (MVP recommandé / alternatives / risques) pour :
+
+1. **JSON-in-shell vs parsing-in-TS** : `nas-ops` produit le JSON dans le script ; le jalon 1 parse en TS. Quelle stratégie pour la suite ? (cohérence, testabilité, robustesse multi-OS). Trancher et justifier.
+2. **Structure des profils OS** : fichiers de templates par profil ? héritage/override ? convention de nommage et d'arborescence sous `templates/`.
+3. **Capture avant/après** : comment obtenir un diff fiable des paquets réellement appliqués (parser `apt-get` ? interroger dpkg ? snapshot dpkg avant/après ?).
+4. **Contrats JSON** : quelles extensions exactes à `UpdateSnapshot` et `ExecutionResult` (`shared/types.ts`) pour Docker, erreurs, scripts custom ? Proposer les types.
+5. **Idempotence & opérations longues** : généraliser l'exécution détachée (`nohup` + exit-code) ? Comment suivre la progression et reprendre ?
+6. **Sécurité Docker `prune` / scripts custom** : où placer la barrière de validation, comment éviter toute fuite de secret vers Hermes/MCP.
+7. **Surface MCP** : quels nouveaux outils/contrats exposer à Hermes pour ces capacités (cf. `list_templates`, `preview_template`, `run_action`…), en gardant la surface minimale.
+
+---
+
+## 4. Livrables attendus de cette mission
+
+À produire sous `docs/` (proposer l'emplacement), en français :
+
+1. **Inventaire des templates** (APT + Docker + custom) : nom, rôle, OS ciblés, variables, marqueurs de sortie, sémantique.
+2. **Contenu proposé** des templates clés (au moins en pseudo-shell réaliste), cohérent avec la convention `===SU:XXX===` existante.
+3. **Schémas JSON canoniques étendus** (snapshot + résultat) couvrant APT, Docker, erreurs, scripts custom — avec règles de déduplication et de réduction pour Hermes.
+4. **Taxonomie des erreurs** + stratégie de gestion et de remédiation.
+5. **Modèle des profils OS et des overrides par machine.**
+6. **Modèle des scripts personnalisés** (post-install, install paquets) avec garde-fous.
+7. **Note de sécurité** : ce qui ne doit jamais atteindre Hermes/MCP, validations requises pour les actions destructives.
+8. **Découpage en sous-jalons** implémentables indépendamment (chacun = un cycle spec → plan → implémentation), avec ordre recommandé.
+
+---
+
+## 5. Contraintes (non négociables)
+
+- **Sécurité** : aucun secret (mot de passe, sudo, token, clé) ne transite vers Hermes/MCP ni dans un prompt LLM ; jamais de secret en clair dans logs/UI/retours. Actions destructives (prune, down, reboot, dist-upgrade) → validation explicite côté webapp.
+- **Réduction déterministe** avant tout appel LLM ; log brut complet archivé séparément.
+- **Templates versionnés sur disque** (éditables depuis le frontend mais sauvegardés comme ressources de projet, revues Git) ; pas de commandes critiques uniquement en base.
+- **OS profile-aware** ; ne pas casser le jalon 1 existant (Debian/Ubuntu refresh + full-upgrade + reboot fonctionnent en prod).
+- **Esprit du projet** : le backend orchestre, les scripts shell portent la logique métier, le JSON canonique est le langage commun frontend/MCP/Hermes.
+- Rester dans une **surface MCP minimale** et des fichiers à responsabilité unique.
+
+---
+
+## 6. Définition de « terminé » pour cette mission
+
+- Tous les axes A→E couverts par un design argumenté.
+- Les 7 questions d'investigation tranchées (MVP/alternatives/risques).
+- Les livrables de la §4 rédigés et cohérents entre eux.
+- Un découpage en sous-jalons priorisé, prêt à passer en `writing-plans`.
+- Aucune implémentation de production livrée (cette mission s'arrête au design validé).
+- Le fichier `tache2.md` mis à jour avec la section « État d'avancement / Ce qui a été fait » (cf. clôture obligatoire ci-dessus).
+
+> **Étape suivante (hors de cette mission)** : tes livrables seront passés au crible de `validation_tache2.md` (grille de validation + gate). **Aucune phase de développement ne démarre tant que ce gate n'est pas ✅ Accepté.** Conçois donc tes livrables pour qu'ils soient vérifiables contre cette grille (complétude, périmètre respecté, cohérence et intégration avec l'appli existante, non-régression).

validation_tache2.md

@@ -0,0 +1,93 @@
+# Protocole de validation — Tâche 2 (moteur de templates de mise à jour)
+
+> **Type** : grille de validation. Utilisée par l'agent orchestrateur (Claude Code principal) **après** qu'un agent sous-traitant a rendu la mission décrite dans `tache2.md`.
+> **But** : vérifier que les livrables de la tâche 2 sont complets, respectent le périmètre, et **s'intègrent correctement à l'application existante** sans rien casser.
+> **⚠️ Gate obligatoire** : cette validation doit être **passée AVANT toute phase de développement**. Tant que le verdict n'est pas ✅ Accepté, **aucune implémentation des livrables de la tâche 2 ne démarre** (ni par l'agent sous-traitant, ni par l'orchestrateur). Le design est figé et validé d'abord ; le code vient après.
+> **Rappel** : la tâche 2 est une mission de **design/investigation** (pas d'implémentation). On valide donc des **documents de design/spec**, pas du code de production. Les vérifications de non-régression servent uniquement à confirmer que l'existant n'a pas été touché.
+
+---
+
+## 0. Quand lancer cette validation
+- La mission `tache2.md` est annoncée terminée.
+- Le fichier `tache2.md` a bien été mis à jour avec sa section « État d'avancement / Ce qui a été fait » (clôture obligatoire).
+- Les livrables de design sont présents sous `docs/` (ou l'emplacement proposé par l'agent).
+
+Si l'un de ces points manque → **rejet immédiat**, renvoyer à l'agent.
+
+---
+
+## 1. Discipline & périmètre (l'agent n'a pas débordé)
+Vérifier via `git status` / `git diff` et lecture des commits :
+- [ ] **Aucun code de production modifié ou ajouté** : pas de changement sous `server/`, `client/`, `shared/`, `templates/`, ni dans les configs (`package.json`, `tsup.config.ts`, `vite.config.ts`, etc.). Seuls des fichiers `docs/**` et `tache2.md` doivent avoir changé.
+- [ ] **Jalon 1 et jalon 2 intacts** : aucun fichier de ces jalons touché.
+- [ ] Aucun autre chantier démarré hors du périmètre de `tache2.md` (les idées hors-scope doivent figurer comme *suggestions*, pas comme du travail réalisé).
+- [ ] Les dépôts de référence (`linux-update-dashboard/`, `nas-ops/`) n'ont pas été copiés tels quels dans le code (respect licence AGPL).
+
+> Si du code de production a été écrit → **rejet** : la mission devait s'arrêter au design.
+
+---
+
+## 2. Complétude des livrables
+Confronter au § « Livrables attendus » et aux 5 axes de `tache2.md` :
+
+**Axes couverts :**
+- [ ] Axe A — Templates APT (update, upgrade, full-upgrade, dist-upgrade, clean, autoremove, reboot) avec sémantique clarifiée et **profils OS** (Debian/Ubuntu/Proxmox/RPi) + gestion proxy apt-cacher-ng.
+- [ ] Axe B — Capture des updates **prévus** (snapshot) et **appliqués** (diff avant/après), consommable par Hermes (déduplication + réduction).
+- [ ] Axe C — Taxonomie des erreurs + stratégie de gestion/remédiation.
+- [ ] Axe D — Docker : scan, pull, up, down, **prune images inutilisées**, détection des stacks (labels + fallback répertoires déclarés), JSON compact.
+- [ ] Axe E — Scripts personnalisés (post-install, install paquets) + overrides par machine + garde-fous.
+
+**Livrables (§4 de tache2.md) :**
+- [ ] Inventaire des templates.
+- [ ] Contenu proposé des templates clés (pseudo-shell réaliste, convention `===SU:XXX===`).
+- [ ] Schémas JSON canoniques étendus (snapshot + résultat, APT + Docker + erreurs + custom).
+- [ ] Taxonomie des erreurs.
+- [ ] Modèle des profils OS + overrides.
+- [ ] Modèle des scripts personnalisés.
+- [ ] Note de sécurité.
+- [ ] Découpage en sous-jalons priorisé.
+
+**Questions d'investigation (§3) :**
+- [ ] Les 7 questions sont tranchées, chacune avec MVP recommandé / alternatives / risques.
+
+> Tout livrable ou question manquant → **renvoi pour complément**.
+
+---
+
+## 3. Cohérence & intégration avec l'application existante
+C'est le cœur de la validation : le design doit **s'emboîter** avec ce qui existe.
+
+- [ ] **Types JSON** : les extensions proposées sont compatibles avec `shared/types.ts` (`UpdateSnapshot`, `ExecutionResult`). Les ajouts sont **rétro-compatibles** (champs optionnels, pas de rupture du jalon 1). Vérifier qu'un snapshot/exécution du jalon 1 resterait valide.
+- [ ] **Convention des templates** : les templates proposés suivent la convention existante (marqueurs `===SU:XXX===`, `LC_ALL=C`, exécution sous `sudo -S`, sortie parsable). Cohérent avec `templates/apt/*.tpl`, `server/templates/render.ts`, `server/services/aptParse.ts`.
+- [ ] **Parsing** : la stratégie retenue (JSON-in-shell vs parsing-TS) est explicite, justifiée, et compatible avec `server/services/` ou propose une migration claire sans casser le refresh/upgrade actuels.
+- [ ] **Couche SSH** : le design réutilise `server/ssh/client.ts` (pas de nouveau mécanisme d'exécution non justifié) ; opérations longues/détachées traitées de façon cohérente.
+- [ ] **Frontière Hermes/MCP** : aucun secret n'atteint Hermes/MCP ; la surface MCP reste minimale ; les données envoyées au LLM passent par la réduction déterministe (`aptReduce.ts` ou équivalent étendu).
+- [ ] **Sécurité** : actions destructives (prune, down, reboot, dist-upgrade) exigent une validation explicite côté webapp ; pas de secret en clair (logs/UI/MCP).
+- [ ] **Profils OS** : le mécanisme proposé n'invalide pas le comportement Debian/Ubuntu prouvé en prod au jalon 1.
+- [ ] **Découpage en sous-jalons** : chaque sous-jalon est implémentable indépendamment et produit un logiciel testable (compatible avec le workflow spec → plan → implémentation).
+
+---
+
+## 4. Non-régression (l'existant tourne toujours)
+Confirmer que rien n'a été cassé (puisque la mission ne devait pas toucher le code) :
+- [ ] `rtk pnpm check` → 0 erreur TypeScript.
+- [ ] `rtk pnpm test` → suite verte (au moins les tests du jalon 1, + jalon 2 s'il est mergé).
+- [ ] `rtk pnpm build` → `dist/index.js` + `dist/client` produits.
+- [ ] Les flux prouvés du jalon 1 (ajout machine, refresh APT, full-upgrade, reboot, rapport) restent inchangés dans le code.
+
+> Une régression ici signifie que l'agent a touché au code malgré la consigne → **rejet**.
+
+---
+
+## 5. Verdict
+Rédiger une conclusion explicite :
+- **✅ Accepté** : tous les blocs cochés. → On peut enchaîner sur `writing-plans` pour le 1ᵉʳ sous-jalon recommandé.
+- **🟡 Accepté avec réserves** : livrables complets mais points de design à ajuster → lister les corrections, renvoyer pour itération courte.
+- **❌ Rejeté** : périmètre débordé, code de production écrit, livrables incomplets, ou incohérence majeure avec l'appli → renvoyer à l'agent avec les points bloquants précis.
+
+Consigner le verdict (date, blocs en échec, actions de suite) en bas de ce fichier ou dans un commit dédié.
+
+---
+
+## 6. Notes de validation (à remplir au moment de la revue)
+> _(Section laissée vide ; à compléter lors de la validation effective : date, verdict, points relevés, décisions.)_