docs(agents): align change-to-all-branches and deploy-by-script with test-first pprod/prod replay

.cursor/agents/change-to-all-branches.md

@@ -1,7 +1,7 @@
 ---
 name: change-to-all-branches
 model: inherit
-description: Uniquement en test, lance /push-by-script puis deploy/change-to-all-branches.sh (alignement + déploiement test).
+description: Uniquement en test, lance /push-by-script puis deploy/change-to-all-branches.sh (alignement + déploiement test). Correctifs applicatifs sur test ; si contexte pprod/prod, voir deploy-pprod-or-prod (section corrections).
 ---
 
 ## Preparer au maximum à l'aide d'outils et de scripts
@@ -43,13 +43,15 @@ En tant qu'agent, avant de solliciter l'ia, regarde ce que tu peux scripter (imp
 
 **Rôle de l’agent :** vérifier que la branche locale est test (sinon retour 1), fournir le message de commit (via /push-by-script), lancer le script, contrôler la sortie et le code de retour. **Rôle du script :** exécution déterministe (vérif branche test, `branch-align.sh test`, orchestrateur ou `deploy.sh test --no-sync-origin` ; flags métier uniquement via `$SECRETS_BASE/test/deploy.conf` ; journalisation toujours `./logs/deploy_*.log`). Préparation OS cible : agent **`/setup-host`** + `deploy/scripts_v2/run-setup-host.sh`, pas `deploy.sh`.
 
+**Branche applicative test-first (obligatoire) :** Toute correction de code, configuration ou documentation dans le **dépôt applicatif** (`repository_root` dans `projects/<id>/conf.json`) pendant l’exécution de cet agent doit être réalisée sur la branche locale **test**. Avant toute modification : si le dépôt applicatif n’est pas sur **test**, exécuter **`git checkout test`** (ou équivalent validé projet). **Interdit** : committer un correctif **uniquement** sur **pprod** ou **prod** depuis cet agent. Si l’échec ou le contexte provient d’une phase **pprod**/**prod** (correctifs identifiés après déploiement ou analyse sur ces branches), appliquer la procédure **Corrections découvertes sur pprod ou prod** dans `.cursor/agents/deploy-pprod-or-prod.md` : correctifs sur **test**, puis **rejouer** le workflow complet depuis l’étape 2 de cet agent dans ce flux (**`/change-to-all-branches`** inclus dans **`/deploy-pprod-or-prod`**), sans court-circuiter l’alignement **test → pprod → prod**.
+
 **Focus qualité et résolution de problèmes :**
 
 - **Qualité :** Ne lancer le script qu'après un push-by-script réussi (message structuré, CHANGELOG à jour, build OK). En cas d'échec de push-by-script, traiter la cause (message manquant, build en échec, etc.) avant de continuer.
 
 - **Résolution de problèmes :** Si change-to-all-branches.sh échoue (alignement ou déploiement), analyser la sortie pour identifier la cause ; appliquer la correction puis relancer sans demander validation (boucle corriger → pousser → relancer). Ne s'arrêter que si la correction n'est pas possible sans instruction utilisateur.
 
-- **Boucle corriger-et-retenter (obligatoire) :** En cas d'échec du script (code de sortie non nul), 1) identifier la cause dans la sortie et/ou logs/deploy_*.log (ex. erreur TypeScript, lint, migration, SSH) ; 2) appliquer la correction dans le code du projet cible (dépôt indiqué par projects/`<id>`/conf.json) ; 3) committer et pousser via /push-by-script (ou ./deploy/pousse.sh [project_id]) avec un message décrivant le correctif ; 4) relancer ./deploy/change-to-all-branches.sh [project_id]. Répéter jusqu'à succès ou jusqu'à un blocage nécessitant instruction utilisateur (ex. erreur infra non corrigeable par l'agent). Ne pas se contenter de rapporter l'échec sans corriger et retenter.
+- **Boucle corriger-et-retenter (obligatoire) :** En cas d'échec du script (code de sortie non nul), 1) identifier la cause dans la sortie et/ou logs/deploy_*.log (ex. erreur TypeScript, lint, migration, SSH) ; 2) appliquer la correction dans le code du projet cible (dépôt indiqué par projects/`<id>`/conf.json) **sur la branche test** du dépôt applicatif (voir **Branche applicative test-first** ci-dessus) ; 3) committer et pousser via /push-by-script (ou ./deploy/pousse.sh [project_id]) avec un message décrivant le correctif ; 4) relancer ./deploy/change-to-all-branches.sh [project_id]. Répéter jusqu'à succès ou jusqu'à un blocage nécessitant instruction utilisateur (ex. erreur infra non corrigeable par l'agent). Ne pas se contenter de rapporter l'échec sans corriger et retenter.
 
 - **Échec npm sur le serveur (ENOENT, ENOTEMPTY, node_modules) :** Si la sortie ou les logs (logs/deploy_*.log) contiennent une erreur npm liée à node_modules (ex. ENOENT, ENOTEMPTY, mkdir node_modules/…, npm error enoent). Il s'agit d'un problème d'environnement sur le serveur de déploiement, pas du code. **Correction automatique** : ne pas modifier le code ; relancer **une fois** ./deploy/change-to-all-branches.sh [project_id] (sans refaire /push-by-script : les branches sont déjà alignées). Le script distant deploy/scripts_v2/remote/deploy-app.sh effectue désormais un retry après `rm -rf node_modules` lors de chaque npm ci ; la relance lance un nouveau déploiement qui bénéficie de cette logique. Si l'échec persiste après cette unique relance, documenter la sortie et les logs (fichier deploy_*.log, extraits d'erreur npm) et s'arrêter — intervention manuelle ou infra requise (espace disque, droits, npm cache).
 

.cursor/agents/deploy-by-script.md

@@ -1,6 +1,6 @@
 ---
 name: deploy-by-script
-description: Lance le déploiement scripts_v2 sur l'environnement courant (branche locale), après vérification du suivi des branches ; métier via deploy.conf ; sortie vers logs/deploy_*.log.
+description: Lance le déploiement scripts_v2 sur l'environnement courant (branche locale), après vérification du suivi des branches ; correctifs applicatifs sur test d'abord ; si pprod/prod, rejouer /deploy-pprod-or-prod ; métier via deploy.conf ; logs/deploy_*.log.
 model: inherit
 is_background: false
 ---
@@ -33,13 +33,17 @@ En tant qu'agent, avant de solliciter l'ia, regarde ce que tu peux scripter (imp
 
 Cet agent lance le déploiement pour **l'environnement courant** (nom de la branche locale) via le script scripts_v2. **Rôle de l'agent :** vérifier le contexte (branche = env cible), lancer le script, contrôler la sortie et le code de retour, synthèse et clôture. **Rôle du script :** exécution et orchestration sûre (suivi branches, sync, log, déploiement).
 
+**Corrections applicatives : branche test d'abord (obligatoire) :** Si une correction de **code**, **configuration** ou **documentation** du dépôt applicatif (`repository_root` dans `projects/<id>/conf.json`) est nécessaire après un échec ou une analyse pendant un déploiement :
+- **Branche locale du dépôt applicatif = test** : appliquer la correction sur **test**, committer/pousser selon les règles du projet, puis relancer le déploiement adapté (cet agent si l’env reste **test**).
+- **Branche locale = pprod ou prod** : **interdit** de traiter le correctif comme un commit **uniquement** sur **pprod**/**prod**. **`git checkout test`** sur le dépôt applicatif, appliquer la correction, puis **rejouer le flux officiel** vers l’environnement visé : exécuter intégralement **`/deploy-pprod-or-prod`** (cible **pprod** ou **prod**) conformément à `.cursor/agents/deploy-pprod-or-prod.md`, en particulier la section **Corrections découvertes sur pprod ou prod** (**`/change-to-all-branches`** puis **`deploy-by-script-to`**). Ne pas se limiter à relancer **seulement** le script de déploiement local sur **pprod**/**prod** après un fix hors **test**.
+
 **Focus qualité et résolution de problèmes :**
 - **Qualité :** Vérifier que la branche courante correspond à l'environnement cible avant de lancer le script. Ne pas déployer depuis un état non poussé ou non aligné sans l'avoir vérifié.
 - **Résolution de problèmes :** Si le script sort en erreur, analyser la sortie (et le fichier log dans `logs/` si présent) pour identifier la cause (git, SSH, déploiement, migrations, build, lint, TypeScript) ; appliquer la correction puis relancer le script (boucle corriger → pousser → relancer). Ne s'arrêter que si la correction n'est pas possible sans instruction utilisateur.
 
-- **Boucle corriger-et-retenter (obligatoire) :** En cas de code de sortie non nul, 1) identifier la cause dans la sortie et/ou logs/deploy_*.log ; 2) appliquer la correction dans le code du projet cible ; 3) committer et pousser via push-by-script si des fichiers ont été modifiés ; 4) relancer le script de déploiement. Répéter jusqu'à succès ou blocage nécessitant instruction utilisateur. Ne pas se contenter de rapporter l'échec sans corriger et retenter.
+- **Boucle corriger-et-retenter (obligatoire) :** En cas de code de sortie non nul, 1) identifier la cause dans la sortie et/ou logs/deploy_*.log ; 2) appliquer la correction dans le code du projet cible en respectant **Corrections applicatives : branche test d'abord** (ci-dessus) ; 3) committer et pousser via push-by-script si des fichiers ont été modifiés et que le flux le permet ; si la branche applicative était **pprod**/**prod**, enchaîner **`/deploy-pprod-or-prod`** au lieu d’un simple relancement isolé sur cette branche ; 4) relancer le déploiement approprié. Répéter jusqu'à succès ou blocage nécessitant instruction utilisateur. Ne pas se contenter de rapporter l'échec sans corriger et retenter.
 
-- **Logs et corrections :** Toujours consulter la sortie du script et le fichier logs/deploy_*.log après exécution. En cas d'échec, utiliser ces logs pour identifier la cause, appliquer les corrections (code, config, doc, scripts), committer et pousser les changements via push-by-script si des fichiers ont été modifiés, puis relancer le script de déploiement jusqu'à succès ou blocage nécessitant instruction utilisateur.
+- **Logs et corrections :** Toujours consulter la sortie du script et le fichier logs/deploy_*.log après exécution. En cas d'échec, utiliser ces logs pour identifier la cause, appliquer les corrections (code, config, doc, scripts) en respectant **Corrections applicatives : branche test d'abord**, committer et pousser via push-by-script si des fichiers ont été modifiés (ou enchaîner **`/deploy-pprod-or-prod`** si **pprod**/**prod**), puis relancer le déploiement ou le workflow complet jusqu'à succès ou blocage nécessitant instruction utilisateur.
 
 **Horodatage et contexte** : appliquer intégralement le bloc défini dans `.cursor/rules/cloture-evolution.mdc` (début et fin d'exécution, lancement et retour des sub-agents).
 
@@ -62,12 +66,12 @@ Le script fait alors automatiquement : suivi des branches origin, sync de la bra
 
 ## 2. Contrôle et résolution de problèmes
 
-- Vérifier que le script a bien été invoqué (branche courante = environnement cible). En cas de code de sortie non nul, consulter la sortie et le log (logs/deploy_*.log), identifier la cause, appliquer les corrections nécessaires, committer et pousser via push-by-script si des fichiers ont été modifiés, puis **relancer immédiatement** le script. Répéter jusqu'à succès. Ne pas relancer sans avoir corrigé uniquement si la correction n'est pas possible sans instruction utilisateur.
+- Vérifier que le script a bien été invoqué (branche courante = environnement cible). En cas de code de sortie non nul, consulter la sortie et le log (logs/deploy_*.log), identifier la cause, appliquer les corrections nécessaires selon **Corrections applicatives : branche test d'abord**, committer et pousser via push-by-script si des fichiers ont été modifiés (ou enchaîner **`/deploy-pprod-or-prod`** si l’env applicatif était **pprod**/**prod**), puis **relancer** le script ou le workflow complet. Répéter jusqu'à succès. Ne pas relancer sans avoir corrigé uniquement si la correction n'est pas possible sans instruction utilisateur.
 
 ## 3. Après l'exécution
 
 - Si le script sort avec 0 : rapporter le succès.
-- Si le script sort avec un code non nul : consulter les logs (sortie + logs/deploy_*.log), identifier la cause, appliquer les corrections, mettre à jour git (push-by-script) si nécessaire, puis relancer. Rapporter la cause identifiée et la résolution ; ne pas relancer sans correction ou instruction utilisateur si la correction n'a pas pu être faite.
+- Si le script sort avec un code non nul : consulter les logs (sortie + logs/deploy_*.log), identifier la cause, appliquer les corrections selon **Corrections applicatives : branche test d'abord**, mettre à jour git (push-by-script) ou enchaîner **`/deploy-pprod-or-prod`** si l’env applicatif était **pprod**/**prod**, puis relancer le flux adapté. Rapporter la cause identifiée et la résolution ; ne pas relancer sans correction ou instruction utilisateur si la correction n'a pas pu être faite.
 
 ## 4. Lint min. 5 avant clôture (obligatoire)