picmakpro/vibeflow-os/vf-update

vf-update — Mise à jour du plugin & des modules

Met à jour VibeFlow en deux couches : (1) le plugin via claude plugin update vibeflow (rafraîchit le cache marketplace ~/.claude/plugins/cache/…), puis (2) les modules installés via l'engine update --all (re-matérialise .claude/skills|agents|rules|scripts). Jamais sans confirmation (ADR-031).

Résolution des scripts (conductor)

0e étape (TGT-04, cible custom `--target`) : avant de tester les trois positions littérales ci-dessous, vérifie si ./.claude/scripts/.vibeflow-target ou $HOME/.claude/scripts/.vibeflow-target existe. Si l'un des deux existe ET que son contenu (un chemin absolu, une seule ligne) diffère de la position candidate elle-même (./.claude ou $HOME/.claude), c'est que ce lab a été posé sous --target : lis ce contenu et utilise-le comme <S>/<S-moteur> réel (<contenu>/scripts/) au lieu de la position littérale. Si le marqueur est absent, ou présent mais identique à la position candidate (cas normal, sans --target), continue directement à la cascade suivante — aucune déviation.

Les scripts vivent dans le dossier scripts/ de conductor. Localise-les dans cet ordre (prends le premier existant) : $HOME/.claude/scripts/ → ./.claude/scripts/ → ${CLAUDE_PLUGIN_ROOT}/conductor/scripts/. Note ce dossier <S> pour les étapes suivantes.

Sonde moteur GSD (best-effort, `<S-moteur>`) : check-gsd-engine.sh et ensure-deps.sh sont des scripts de dev-orchestrator, pas de conductor (D-00 : conductor est mandatory, dev- orchestrator ne l'est pas — un lab non-dev installe le premier sans le second). Ils se cherchent dans la même cascade que <S>, sauf en 3e position — plugin non installé — où le chemin est ${CLAUDE_PLUGIN_ROOT}/dev-orchestrator/scripts/, jamais conductor/scripts/ : les deux premières positions matérialisent tous les scripts à plat dans un même .claude/scripts/ d'un lab installé, mais la 3e position doit pointer vers le module qui porte réellement ces fichiers avant toute install. Note ce dossier <S-moteur>. Absent aux trois positions → silence total (voir étape 1) : la sonde ne doit jamais dégrader le reste du diagnostic.

Étapes

1 — Diagnostic (plugin + moteur GSD, deux volets)

Volet plugin (inchangé) : lance bash <S>/check-plugin-update.sh --print. Parse le JSON {update_available, installed, latest}. latest vaut unknown (réseau KO) → dis-le, propose de réessayer plus tard, stop.

Volet moteur GSD — sonde best-effort <S-moteur>, exécutée avant tout arrêt sur absence de mise à jour du plugin (c'est le point de couture de la phase, D-07) : lance bash <S-moteur>/check-gsd-engine.sh --quiet. Trois branches, exactement :

• Script introuvable (aux trois positions de <S-moteur>) → SILENCE TOTAL : aucune ligne,

aucune mention, aucune dégradation du reste du diagnostic. Un lab non-dev (content, growth, business) installe conductor sans dev-orchestrator et ne doit rien voir. Une erreur d'usage du gate (exit 2) est traitée comme une absence : silence.

• Exit `0` (état legacy, seul cas actionnable) → compose la ligne moteur à partir de la sortie

réelle du gate (jamais une valeur recopiée depuis la doctrine) : « moteur GSD legacy A.B.C → @opengsd/gsd-core à migrer ».

• Exit `3` (INDÉTERMINÉ) → si le gate a imprimé une ligne (sous-cas reliquat [gsd-leftover] :

gsd-core à jour + reliquat legacy détecté), l'affiche dans le diagnostic sans jamais proposer de migration ; s'il n'a rien imprimé (état absent, ou gsd-core propre), ne dit rien.

Fraîcheur du moteur — seulement si le gate de présence est sorti en 3 sur un état gsd-core (propre ou avec reliquat ; un état legacy ne passe jamais par cette sonde, la migration prime) : lance bash <S-moteur>/ensure-deps.sh --check-engine-update (lecture seule, sonde réseau best-effort — npm view, jamais npx). Deux branches, exactement :

• Exit `0` (périmé, seul cas actionnable) → stdout porte une ligne

[gsd-outdated] … A.B.C installé → X.Y.Z publié (plafond ^1) ; compose la ligne moteur à partir des numéros réels de cette sortie : « moteur GSD @opengsd/gsd-core A.B.C → X.Y.Z (dernier ^1 publié) à mettre à jour ».

• Exit `3` (à jour, réseau ou npm KO, VERSION illisible) → silence : ne dit rien, ne propose

rien. Une détection impossible n'est jamais une erreur.

Arrêt combiné : « VibeFlow est à jour (v<installed>) » ne peut sortir seul, suivi du stop, que si le volet moteur n'a produit aucune ligne (silence ou signal non actionnable) et que update_available = false. Dès que le volet moteur a produit la ligne legacy ou la ligne périmé, le message combine les deux volets et le flux continue — même si le plugin est déjà à jour : « plugin à jour (v<installed>), moteur GSD legacy A.B.C → @opengsd/gsd-core à migrer », ou « plugin à jour (v<installed>), moteur GSD @opengsd/gsd-core A.B.C → X.Y.Z à mettre à jour ». Les numéros viennent toujours des sorties réelles de check-plugin-update.sh --print, de check-gsd-engine.sh et de ensure-deps.sh --check-engine-update, jamais de valeurs recopiées depuis la doctrine. Sinon (mise à jour plugin disponible, avec ou sans ligne moteur), continue vers l'étape 2.

2 — Changelog (ce qui a changé)

Montre les changements entre installed et latest, résumés par version en distinguant nouvelle capacité / correctif / changement de doctrine. Source, dans l'ordre de préférence : la table d'historique du README.md du plugin (${CLAUDE_PLUGIN_ROOT}/README.md ou le clone marketplace ~/.claude/plugins/marketplaces/vibeflow-os/README.md), sinon les CHANGELOG.md des modules. Reste factuel, pas de survente.

3 — Confirmation (ADR-031 — jamais d'update sans validation humaine)

Récapitule via AskUserQuestion : « Plugin v<installed> → v<latest> + les modules installés seront mis à jour. Continuer ? ». Si le volet moteur (étape 1) a produit une ligne, ajoute une ligne de plus au récapitulatif : « Moteur GSD legacy A.B.C → @opengsd/gsd-core à migrer. Continuer ? » (ligne legacy) ou « Moteur GSD @opengsd/gsd-core A.B.C → X.Y.Z à mettre à jour. Continuer ? » (ligne périmé). Cette ligne moteur est acceptable ou refusable indépendamment de la ligne plugin et de la ligne modules — un refus n'a aucun effet de bord, et elle n'est jamais ni relancée ni reformulée dans la même session (ADR-031, P-07).

Gère les flags existants de $ARGUMENTS (aucun flag nouveau créé — densité ADR-029) :

• --check → affiche seulement les étapes 1–2, y compris l'état du moteur GSD comme le reste

du diagnostic, ne demande rien, stop.

• --modules-only → saute l'étape 4a (ne touche pas au plugin) et ne propose ni la migration

ni la mise à jour du moteur — son nom borne son périmètre aux modules.

4 — Exécution (après OK)

a. Couche plugin : claude plugin update vibeflow@vibeflow-os. Toujours l'identifiant complet `<plugin>@<marketplace>` : le nom nu (claude plugin update vibeflow) peut échouer par « Plugin not found » quand le cache de catalogue est périmé. Si le CLI claude est absent ou échoue, signale-le, donne la commande manuelle, et — en cas de « not found » persistant — la parade : claude plugin marketplace update vibeflow-os (ou supprimer le cache ~/.claude/plugins/plugin-catalog-cache.json, régénéré au prochain appel). Puis continue en 4b (les modules peuvent quand même être re-matérialisés depuis le cache le plus récent).

b. Couche modules : bash <S>/vf-update-run.sh. Le script localise lui-même le cache le plus récent (indispensable : la session courante garde encore l'ancien ${CLAUDE_PLUGIN_ROOT}) et relance l'engine update --all pour chaque scope ayant un registre. Il rafraîchit aussi le cache du bandeau de mise à jour, ce qui évite qu'il réclame au redémarrage une mise à jour déjà faite. Relaie son résumé.

c. Couche moteur (seulement si la ligne moteur de l'étape 3 a été acceptée) : invoque VF_SCOPE=<scope> bash <S-moteur>/ensure-deps.sh --migrate-engine (ligne legacy) ou VF_SCOPE=<scope> bash <S-moteur>/ensure-deps.sh --upgrade-engine (ligne périmé) et relaie son résumé. Scope obligatoire : si $(git rev-parse --show-toplevel 2>/dev/null || pwd)/.claude/gsd-core/ existe (même racine que ensure-deps.sh, pas le répertoire courant : le skill peut tourner depuis un sous-dossier), <scope> vaut project ; sinon user. Sans ce préfixe, le défaut user pose une seconde copie du moteur dans ~/.claude, qui masque les commandes du projet et touche tous les projets de la machine. Le script re-sonde lui-même le registre et ne relance npx que si le VERSION installé est toujours strictement inférieur au dernier ^1 publié. S'exécute même si la couche plugin (4a) a échoué — les confirmations sont indépendantes. Le skill n'invoque jamais l'installeur amont directement : il route vers ensure-deps.sh, point de vérité unique du scope et du plafond de version (Iron Law 2, plugin/conductor/AGENT.md:114).

d. Modules nouveaux (hors --check) : le résumé de 4b liste les modules du catalogue posé absents du registre et jamais proposés : NOUVEAU_MODULE scope=<s> <module>=<version> deps=<a,b|-> (deps=? : dépendances non calculées, dis-le). Un module posé dans un scope n'est jamais listé dans l'autre ; absent des deux, il apparaît une fois par scope. Jamais posés d'office (ADR-031), confirmation indépendante des autres. Pose une question par module (description lue dans son module.json), 4 questions au plus par appel AskUserQuestion, appels successifs au-delà (10 modules = 3 appels). Options, sans aucune présélectionnée : une par scope listé (user, project) dont la description dit « pose aussi : <deps> » (omise si deps=-), puis « Pas maintenant » (le module ne sera plus proposé). Deux scopes cochés pour un module : repose la question, jamais de double pose. Dès les réponses, pour chaque scope listé (même sans coche) : bash <S>/vf-update-run.sh offer <scope> <modules cochés pour ce scope>. Il calcule les modules présentés avant la pose, pose les cochés (--with-deps) et inscrit les présentés : refusé ou retiré plus tard, un module n'est jamais reproposé ; une pose en échec fait exception : le module est dé-marqué et revient au prochain /vf-update. Si le résumé de 4b porte NOUVEAUX_MODULES_ERREUR scope=<s>, le calcul des modules nouveaux de ce scope a échoué : dis-le à l'humain (la mise à jour, elle, est faite), ne pose rien et n'appelle pas offer pour ce scope. offer sort non nul si une pose échoue, si un nom est refusé ou si un module demandé n'était pas présenté : relaie son message.

5 — Rappel de redémarrage

Termine par : « Modules à jour sur disque. Redémarre Claude Code pour recharger le plugin (commandes, agents) dans sa nouvelle version. » Le plugin lui-même n'est pris en compte qu'au prochain démarrage de session. Si la couche moteur (4c) a tourné, ajoute : une migration ou une mise à jour du moteur pose de nouveaux agents et skills, eux aussi pris en compte seulement au prochain démarrage.

Garde-fous