Files

T

gilles 0fbca06d3d docs: roadmap tâches 1.9-8 (briefs, gates de validation, designs tâche 2) + plans d'implémentation

Cartographie complète (liste_taches/coherence_taches), briefs tacheN + gates
validation_tacheN, design tâche 2 (docs/design/tache2/), specs/plans jalon 1-2
et tâche 1.9/2 (Phase 1, Phase 2, SJ-0→3). Validations consignées (1.9 ✅, 2-8 🟡).

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

2026-06-05 19:50:25 +02:00

13 KiB

Raw Permalink Blame History

Protocole de validation — Tâche 4 (scripts post-install et installateurs)

Type : grille de validation. Utilisée après la mission décrite dans tache4.md. But : vérifier que les profils/scripts post-install sont complets, non interactifs, sûrs, versionnables et compatibles JSON. Gate obligatoire : cette validation doit être passée avant implémentation de nouveaux scripts. Rappel : la tâche 4 est une mission design scripts/contrats, pas d'implémentation.

0. Quand lancer cette validation

La mission tache4.md est annoncée terminée.
Le catalogue de profils/scripts est produit.
Les JSON d'entrée/sortie sont spécifiés.

1. Discipline & périmètre

Aucun script de production ajouté/modifié.
Aucun curl | sh opaque validé sans justification.
Aucun secret en clair dans variables, logs, rapports ou MCP.
Les scripts sont prévus en templates versionnés sur disque.
Tout script est non interactif.

2. Profils minimum

bootstrap_root.
identity_network.
base_tools sans vim.
network_tools avec nmap classé admin local contrôlé.
dev_git.
sharing avec Samba/NFS/mDNS/wsdd2.
docker_official.
home_automation.
dev_tools.
embedded_esp_platformio.
terminal_customization.

3. Hardware, OS et métriques

machine_probe spécifié.
machine_metrics_simple spécifié.
apt_repositories spécifié.
firmware_tools spécifié.
gpu_drivers spécifié.
benchmark_tools spécifié.
Les scripts dépendent du couple OS/type machine.
Les drivers/firmware/benchmark ne sont pas installés par défaut.

4. Manifestes et champs UI

Chaque profil possède id, label, description, risque, fields, defaults, validations.
Cocher un profil déplie les champs obligatoires.
Le bouton run reste désactivé si les champs requis sont invalides.
Preview template prévue avec masquage secrets.
Les décisions manquantes produisent human_interaction_required, pas un blocage SSH.

5. Cycle d'exécution

precheck.
install.
configure.
initialize.
verify.
report JSON.
Les sauvegardes de fichiers système sont prévues avant modification.
Reboot/reconnexion sont signalés et intégrés à reboot_verified.

6. JSON et erreurs

JSON d'entrée défini.
JSON résultat défini.
Liste paquets/services/fichiers modifiés incluse.
Taxonomie erreurs présente.
Les logs bruts sont archivés, les lignes importantes réduites.

7. Verdict

✅ Accepté : scripts/profils prêts à planifier.
🟡 Accepté avec réserves : profils à compléter.
❌ Rejeté : interactivité SSH, secrets, risques non validés ou JSON absent.

8. Notes de validation

Date : 2026-06-05 — Gilles Soulier (orchestrateur, validation déléguée)

Verdict global : 🟡 Accepté avec réserves

Le design est solide dans ses fondements : non-interactivité, JSON canonique, profils minimum, cycle precheck/install/configure/initialize/verify/report, taxonomie d'erreurs, secrets exclus. Les réserves ci-dessous sont mineures et n'invalident pas la mise en planification, sous réserve qu'elles soient traitées avant ou pendant l'implémentation.

Résultat case par case

Section 1 — Discipline & périmètre

Aucun script de production ajouté/modifié. Confirmé : la tâche est design seul.
Aucun curl | sh opaque validé sans justification. §6 exige URL officielle, checksum si disponible, confirmation. Note : rustup, nvm, uv sont pré-autorisés par leur liste en §14 — ce statut devrait être rendu explicite dans la spec (note « installateur pré-autorisé justifié »).
Aucun secret en clair. §6 + §12 clairs.
Templates versionnés sur disque. §6 + §13 checklist.
Tout script non interactif. §2 + §13.

Section 2 — Profils minimum

bootstrap_root — §3.
identity_network — §3 avec variables JSON.
base_tools sans vim — §3, explicitement listé.
network_tools avec nmap classé admin local contrôlé — §3, classé "outil réseau d'administration pour découverte locale", distinction security_audit/security_lab présente.
dev_git — §3.
sharing avec Samba/NFS/mDNS/wsdd2 — §3 + §5 exemples JSON complets.
docker_official — §3, modélisé comme installateur externe officiel.
home_automation — §4.
dev_tools — §4.
embedded_esp_platformio — §4, groupes dialout/plugdev, règles udev.
terminal_customization — §8, variables UI + JSON retour.

Section 3 — Hardware, OS et métriques

machine_probe spécifié — §3, JSON de sortie complet avec recommendations.
machine_metrics_simple spécifié — §3, JSON de sortie complet, non destructif.
apt_repositories spécifié — §3, analyse puis action séparée validée.
firmware_tools spécifié — §3, règles VM/bare-metal/Proxmox.
gpu_drivers spécifié — §3, sous-profils nvidia/amd/intel/intel_arc, séquence en trois étapes.
benchmark_tools spécifié — §3, confirmation explicite, rapport JSON, optionnel.
Scripts dépendent du couple OS/type machine — §3 machine_probe détecte virtualization/raspberryPi/proxmoxHost, §13 checklist.
Drivers/firmware/benchmark non installés par défaut — §3 ("optionnels et jamais installés par défaut"), §12 définition de terminé.

Section 4 — Manifestes et champs UI

Chaque profil possède id, label, description, risque, fields, defaults, validations. Coquille corrigée : le manifeste JSON exemple §2 ne comportait pas description, defaults, validations — ajoutés lors de la présente revue.
[~] Cocher un profil déplie les champs obligatoires. Comportement UI non décrit dans tache4.md. Relève principalement de la tâche 3 (formulaires) ; la tâche 4 ne fixe que les champs déclarés dans le manifeste. Acceptable dans le périmètre tâche 4.
[~] Bouton run désactivé si champs requis invalides. Non mentionné dans tache4.md. Relève de la tâche 3. Acceptable.
Preview template avec masquage secrets. §6 "prévisualisable" + principe "sans secret en clair". La formulation explicite "masquage secrets lors de la preview" est absente mais découlée du principe général. Réserve légère : à formuler explicitement lors de l'implémentation.
human_interaction_required plutôt que blocage SSH. §10 taxonomie d'erreurs, présent.

Section 5 — Cycle d'exécution

precheck — §2 + §7.
install — §2 + §7.
configure — §2 + §7.
initialize — §2 + §7.
verify — §2 + §7.
report JSON — §2 + §9.
Sauvegardes de fichiers système avant modification. §6 "rollback ou sauvegarde quand un fichier système est modifié" + §8 terminal_customization backupFiles dans JSON retour.
[~] Reboot/reconnexion signalés et intégrés à reboot_verified. requiresReboot/requiresRelogin présents dans le JSON de retour. Réserve : la confirmation post-reboot (reboot_verified) — c'est-à-dire le booléen attestant que la machine a redémarré et est de nouveau joignable — n'est pas explicitement nommée. §3 identity_network mentionne "reboot vérifié si nécessaire" mais le champ JSON correspondant est absent du modèle canonique §9. À ajouter.

Section 6 — JSON et erreurs

JSON d'entrée défini — §3 variables UI identity_network, §5 Samba/NFS, §8 terminal.
JSON résultat défini — §2, §3, §5, §8, §9 champs communs.
Liste paquets/services/fichiers modifiés incluse — §5 packagesInstalled/filesChanged/services, §9.
Taxonomie erreurs présente — §10, 16 codes distincts.
Logs bruts archivés, lignes importantes réduites — §9 "Le log brut reste archivé. Hermes/MCP ne reçoivent que le JSON réduit et les lignes importantes."

Réserves majeures (à traiter avant ou en début d'implémentation)

R1 — Destination BDD des résultats machine_probe et machine_metrics_simple non spécifiée La tâche 4 ne mentionne pas explicitement que le JSON de sortie de machine_probe alimente machine_hardware et que machine_metrics_simple alimente machine_metrics_latest (tables définies dans tache1.9.md §9). Cette liaison doit être documentée dans les livrables sous docs/ avant que la tâche 5 (exécution backend) ne commence à router ces résultats.

R2 — Champ reboot_verified absent du JSON canonique §9 Le JSON commun de §9 contient requiresReboot (intention) mais pas de champ attestant que le reboot a effectivement été vérifié. Le cycle identity_network exige "reboot vérifié" — le contrat JSON doit porter ce champ (ex. rebootVerified: boolean | null).

R3 — Installateurs curl | sh (rustup, nvm, uv) non explicitement justifiés dans la spec Ces installateurs sont listés dans §4 et §14 mais la spec ne les désigne pas formellement comme "pré-autorisés avec justification documentée" conformément à la règle §6. La liste des installateurs autorisés avec leurs URLs officielles et la stratégie de vérification (checksum interne rustup-init, hash nvm/install.sh via GitHub release) devrait apparaître dans un tableau dans les livrables docs/.

R4 — Masquage des secrets lors de la preview template non formulé Le principe "sans secret en clair" est global mais la preview de template (§6 "prévisualisable") ne précise pas comment les variables sensibles (password, token) sont masquées dans l'affichage UI. À formaliser explicitement dans la spec des installateurs externes.

Réserves mineures (à noter, non bloquantes)

Le manifeste JSON exemple §2 ne contenait pas description, defaults, validations — corrigé lors de la présente revue.
Le backup path §8 terminal_customization comportait une date figée en dur — corrigé lors de la présente revue (remplacé par {{backupDate}}).
iotop dans base_tools : sur certaines distributions récentes ce paquet requiert le kernel avec CONFIG_TASK_IO_ACCOUNTING ou peut s'appeler différemment. Non bloquant au niveau design mais à anticiper lors de l'implémentation avec un fallback.
La distinction des trois niveaux nmap (network_tools / security_audit / security_lab) est bien documentée dans §3 et §4. Elle devrait être reprise dans le manifeste de chaque profil concerné (champ risk + note UI d'avertissement pour security_lab).

Coquilles corrigées dans tache4.md

§2 manifeste JSON : ajout de "description", "defaults": {}, "validations": [] pour correspondre au gate §4 qui exige ces trois champs dans chaque manifeste de profil.
§8 terminal_customization, JSON retour backupFiles : date figée 20260605 remplacée par le placeholder Mustache {{backupDate}} pour indiquer que la valeur est dynamique à l'exécution.

Cohérence inter-tâches

Tâche 2 (moteur templates) : tache4.md s'appuie correctement sur Mustache + templates versionnés sur disque, conforme à tache2.md. Aucun moteur parallèle créé. OK.
Tâche 1.9 (BDD) : tables install_profiles, install_recipes, install_recipe_versions, machine_profile_state, script_variables_presets, machine_hardware, machine_metrics_latest sont bien définies dans tache1.9.md §9. La liaison explicite depuis tache4.md vers ces tables est manquante (réserve R1 ci-dessus).
Tâche 3 (formulaires UI) : les comportements "déplier champs" et "désactiver bouton run" relèvent de tache3.md et ne sont pas à spécifier dans tache4.md. Frontière correcte.
Tâche 5 (exécution) : les JSON d'entrée/sortie définis dans tache4.md constituent les contrats que tache5 devra respecter pour le routage et le stockage. Dépendance correctement identifiée en §15.
client.ts / templates APT existants : le modèle d'exécution (sudo -S, base64, marqueurs ===SU:XXX===, non interactif) est cohérent avec les conventions. Les scripts post-install de tache4 doivent émettre les marqueurs de section appropriés ou un JSON terminal en remplacement — la spec tache4 choisit le JSON terminal, ce qui est cohérent avec l'intention d'évolution décrite dans tache2 (JSON-in-shell).

Conclusion

Le design tache4.md est prêt à entrer en planification d'implémentation sous réserve du traitement des quatre réserves majeures ci-dessus, en priorité R1 (liaison BDD) et R2 (champ reboot_verified), qui sont nécessaires pour que la tâche 5 puisse router correctement les résultats.

13 KiB Raw Permalink Blame History