Aller au contenu

Skill implementer-lot

Référence technique des choix internes du skill Claude Code implementer-lot, qui exécute les lots d'une étape Kirexo précédemment cadrée par analyser-etape. Là où analyser-etape crée l'issue parente, les work-items GitLab et les branches Git, implementer-lot consomme ce cadrage : il écrit le code de production d'un lot, enchaîne les vérifs préalables, délègue aux sous-agents reviewer / test-writer / doc-writer, puis lance ship-lot.sh (commit unique + push + glab mr create --auto-merge ciblant la branche parente) qui dérive branches et iids depuis output.json et délègue au template ship.sh. Le main Claude poll ensuite la MR jusqu'à merged, en s'aidant de ScheduleWakeup pour les attentes longues. En cas d'échec auto-merge, le skill catégorise automatiquement le type d'échec (impl vs runner) et tente une relance bornée (1 par catégorie, 2 au total) via fix-amend.sh ou retry-failed-jobs.sh. Une rétro opt-in (Étape F) clôture optionnellement le run : sur acceptation de l'utilisateur, le sous-agent skill-improver analyse les transcripts du run et produit des propositions d'amélioration ciblées du SKILL.md, des scripts bin/ et des agents sollicités. Cette page documente le comment : structure et indexation d'output.json, résolution de la branche parente, gardes de ship.sh, asymétries de l'API GitLab, pièges du polling, codes retour, contraintes du cache prompt côté Anthropic, mapping failure_reason → catégorie, design de la boucle d'amélioration récursive. Le quoi vit dans .claude/skills/implementer-lot/SKILL.md. Le pourquoi de la délégation Claude est décrit dans l'explication Workflow des agents Claude.

Pour qui

  • Le développeur qui maintient les scripts du skill (corrections, évolutions).
  • Le main Claude lorsqu'il diagnostique un échec d'auto-merge ou un timeout de polling.

Pour quoi

  • Comprendre pourquoi le polling est borné à 5 min avant de basculer sur ScheduleWakeup(1200s).
  • Retrouver les champs JSON consommés par wait-merge.sh et diag-mr.sh (et l'asymétrie PascalCase / snake_case avec analyser-etape).
  • Lire la table d'interprétation des detailed_merge_status GitLab sans avoir à plonger dans la doc upstream.
  • Lire la table de mapping failure_reason → catégorie utilisée par categorize-failure.sh, et les choix de conception derrière la stratégie de relance (quotas séparés, --amend --no-edit, retry job par job).
  • Comprendre pourquoi output.json est indexé positionnellement, ce qu'un lot manquant y produit, et à quoi sert add-lot.sh.
  • Retrouver ce que ship.sh valide avant d'agir (liste de fichiers) et ce qu'il relit après (drapeau d'auto-merge), plutôt que de le déduire d'un code retour.
  • Éviter de réintroduire un piège déjà résolu (encodage du chemin projet, wrapper bash gl(), codes retour du wait-merge, | head -1 sous pipefail).
  • Comprendre la stratégie de boucle d'amélioration récursive bornée portée par la rétro skill-improver : pourquoi opt-in, pourquoi un sous-agent dédié, pourquoi un patch à la fois.

Scripts livrés

Tous vivent dans .claude/skills/implementer-lot/bin/ et sont invoqués depuis le SKILL.md :

Script Args Rôle Codes retour
preflight.sh <n> Vérifie l'étape (Étapes/étape<n>.md + front-matter), output.json, les specs task-NN-<slug>.md, la branche courante (main ou parente), la disponibilité de glab dans le conteneur php. 0 OK / 1 KO
fetch-issue.sh <iid> Récupère le contenu vivant d'un work-item de lot (description courante + commentaires humains, notes système filtrées) en markdown sur stdout. Source de vérité du contenu d'un lot (cf. § dédié). Mode STRICT : aucune retombée sur le .md local. 0 OK / 1 introuvable ou GitLab KO
check-lot-state.sh <n> <k> Pour le lot k, retourne sur stdout un JSON {branch, mr_iid, mr_state} permettant de vérifier que les lots antérieurs sont mergés avant de démarrer. 0 toujours
add-lot.sh <n> <titre> <slug> <description.md> Effet remote. Ajoute un lot correctif ad hoc à une étape déjà analysée : crée le work-item enfant (via analyser-etape/bin/create-task.sh, parent lu dans .parent.gid), l'ajoute à .tasks[] d'output.json avec son slug (écriture atomique), et installe la spec sous var/claude/etape<n>/task-NN-<slug>.md. Refuse un slug non kebab-case ou déjà pris (cf. § dédié). 0 OK / 1 fichier requis absent, .parent.gid absent, slug déjà pris ou échec de création / 2 usage ou <n>/slug invalide
sync-parent.sh <n> [<k>] Résout la branche parente via la lib partagée (cf. § dédié), fetch origin, et travaille sur origin/<parente> — la parente n'est jamais sortie. Si <k> (numéro de lot, 1-based) est fourni : dérive la branche de lot <task_iid>-<slug> depuis output.json, la crée depuis origin/<parente> si elle n'existe pas (sinon la récupère en local ou en suivi d'origin), puis la rebase sur origin/<parente> (auto-stash, --abort propre sur conflit). Laisse HEAD sur la branche de lot. Une ref locale de parente en retard est signalée sur stderr, sans bloquer. Sortie stdout : JSON {parent_branch, task_branch} (task_branch vide si <k> omis). 0 OK / 1 parente introuvable ou ambiguë, origin/<parente> absente après fetch, conflit de rebase ou lot hors bornes
ship-lot.sh <n> <k> <commit-msg-file> <mr-body-file> <files> Wrapper de ship d'un lot : dérive la branche de lot (source), la branche parente (cible), task_iid et parent_iid depuis output.json, puis appelle le template ship.sh en lui passant ETAPE=<n> LOT=<k> (marqueur Étape <n> - lot <k>). Le modèle ne fournit donc que message de commit, body MR et liste de fichiers — aucun nom de branche ni iid à construire. La branche parente est résolue par la même lib partagée que sync-parent.sh : ici l'enjeu est une MR ouverte vers la mauvaise cible. 0 OK / 1 lot hors bornes, branche parente introuvable ou ambiguë, ou échec de ship.sh (liste de fichiers invalide, auto-merge non armé)
wait-merge.sh <mr_iid> Poll glab mr view <iid> --output json toutes les 15 s pendant 5 min max. 0 merged / 2 closed / 3 toujours opened (timeout) / 4 erreur réseau ou glab KO
diag-mr.sh <mr_iid> Diagnostic markdown lisible humain : état, pipeline, liste des jobs CI échoués avec leur failure_reason, interprétation du detailed_merge_status, conflits, discussions ouvertes, et une section « Catégorisation » avec verdict impl / runner / mixed / unknown. 0 toujours, sortie sur stdout
categorize-failure.sh <mr_iid> Pendant machine-parsable de diag-mr.sh. Émet un JSON {mr_iid, pipeline_id, category, runner_jobs, impl_jobs} consommé par la stratégie de relance (étape D du SKILL). C'est ce script — pas diag-mr.sh — que le main Claude pipe dans jq pour décider de générer fix-amend.sh ou retry-failed-jobs.sh. 0 toujours, 1 si MR introuvable
detect-twig.sh <base-ref> Garde binaire « faut-il une vidéo de démo ? ». Diff three-dot (<base-ref>...HEAD) filtré --diff-filter=ACMRT sur la pathspec *.twig : ne compte que les templates introduits ou modifiés par le lot, jamais ceux que la branche parente a reçus entre-temps, ni les suppressions pures. Rend la liste des chemins concernés, pour aider à rédiger le scénario. Convention grep-like : 0 ≥ 1 .twig touché (liste sur stdout) / 1 aucun / 2 usage ou ref invalide
preship.sh <parent-branch> Pré-vol d'hermétisme de l'environnement de test, avant le push. Sort tout de suite si le diff du lot ne touche aucun service externe. Sinon, vérifie que l'env test neutralise le réseau — MAILER_DSN=null://, transports Messenger en sync:// ou in-memory:// — dans .env.test, .env.test.local et l'éventuel dossier de configuration Symfony propre à l'environnement test (le dépôt n'en a pas : la surcharge passe par les blocs when@test des fichiers de config/packages/). Puis lance castor ci:local comme gate final. 0 OK / 1 usage ou env non hermétique
check-test-artifacts.sh (aucun) Refuse le commit si un fichier de test stagé est un parasite de debug. Deux critères sur les tests/**/*.php de l'index : nom en *Dump* / *ZZ* / *Debug* / *Diag* (insensible à la casse), ou absence de TestCase (un fichier sous tests/ qui ne dérive d'aucun TestCase est suspect). Appelé par ship.sh après le git add, avant le commit. 0 propre / 1 parasite détecté
mr-status.sh <mr_iid> État synthétique d'une MR de lot, en une ligne : merged <sha-court> → <target>, opened <detailed_merge_status> → <target> ou closed → <target>. Remplace le trio verbeux (glab mr view --output json | jq, git log, git ls-tree) relu intégralement à la reprise d'un run. Lecture seule. 0 toujours
wait-pipeline.sh <mr_iid> [interval_s] (défaut 20) Poll silencieux de la pipeline d'une MR : n'écrit rien tant qu'elle tourne, et ne sort qu'à l'état terminal. En succès, une ligne. En échec, pour chaque job échoué : son nom, un extrait filtré de sa trace (tail -15 des lignes d'erreur) et le lien de téléchargement des artefacts. À lancer de préférence en tâche de fond, pour libérer le contexte pendant la CI. 0 succès / 1 échec, annulation ou skip
rearm-merge.sh <mr_iid> Ré-arme merge_when_pipeline_succeeds par un PUT sur l'API REST (projects/:id, résolu par glab depuis le dépôt courant). Nécessaire après un force-push : fix-amend.sh désarme l'auto-merge côté GitLab, et la MR resterait opened CI verte sans que rien ne le signale. Attend que la MR sorte de checking / preparing / unchecked — et d'une lecture vide, traitée comme un état non décidable — avant d'appeler, faute de quoi GitLab rend 405. Relit ensuite l'état au lieu de conclure sur le code retour du PUT (cf. § dédié) ; state == merged compte comme un succès. 0 armé et vérifié (ou MR déjà mergée) / 1 usage, ou drapeau non posé après relecture — l'état relu et les dernières lignes de la réponse GitLab sont affichés
close-task.sh <task_iid> Ferme le work-item du lot après le merge de sa MR. Nécessaire parce qu'une MR de lot cible la branche parente, et que GitLab ne ferme une issue automatiquement que sur un merge dans la branche par défaut : la tâche resterait ouverte, et le gate de /cloturer-etape exige toutes les tâches enfants fermées. Idempotent. 0 fermée (ou déjà fermée) / 1 usage ou échec glab

close-task.sh prend le task_iid, pas le numéro de lot

La signature est close-task.sh <task_iid>. Passer le numéro de lot ferme un objet GitLab qui n'a rien à voir — ou rend 404. L'iid se récupère dans output.json.

Les deux scripts de diagnostic sont volontairement distincts : diag-mr.sh est destiné à être restitué tel quel dans le chat (markdown), categorize-failure.sh à être consommé par du code (JSON stable). Garder les deux évite à diag-mr.sh d'avoir un mode --json qui doublerait son code et le rendrait plus fragile.

Les scripts générés par le skill (un dossier par lot, sous var/claude/etape<n>/lot-<k>/) :

Fichier Rôle Quand généré
commit-msg.txt Sujet impératif (type(scope): …) + corps du commit unique du lot. Ne contient ni le marqueur Étape X - lot Y ni l'entête Tâche #T · Ticket #P : ces métadonnées sont injectées automatiquement par ship.sh (cf. § Conventions GitLab injectées). À la création MR (C.10)
mr-body.md Description de la MR (résumé + checklist des délégations + lien spec + lien issue parente). Ne contient pas l'entête de navigation Tâche #T · Ticket #P : le template ship.sh la préfixe automatiquement. À la création MR (C.10)
mr.json {iid, source, target} de la MR créée — iid numérique, source et target les noms de branche. Écrit par ship.sh (donc via ship-lot.sh) uniquement si les arguments [etape] et [lot] sont fournis, seul cas où le chemin lot-<k>/ est connu. Relu par le main Claude à l'étape C.11 pour récupérer l'iid. Pas de champ url : il n'est jamais écrit. Après lancement de ship-lot.sh, une fois la MR créée
retry-state.json {mr_iid, impl_attempts, runner_attempts} — état persistant des tentatives de relance (cf. § Stratégie de relance). À la création MR (C.10), incrémenté à D.3 et D.4
fix-amend.sh git add <fichiers corrigés> + git commit --amend --no-edit + castor audit + git push --force-with-lease. Préserve le mono-commit du lot. À D.3 (échec impl)
retry-failed-jobs.sh Boucle glab api projects/<encoded>/jobs/<job_id>/retry --method POST sur les seuls jobs en échec runner. À D.4 (échec runner)

output.json : un inventaire indexé positionnellement

var/claude/etape<n>/output.json est la source de vérité partagée par les trois skills de la chaîne. Sa forme :

{
  "parent": { "iid": 202, "url": "…", "gid": "gid://gitlab/WorkItem/…" },
  "tasks": [
    { "iid": 203, "url": "…", "gid": "gid://gitlab/WorkItem/…", "slug": "fondation-utilisateur" }
  ]
}

Le numéro de lot n'est pas stocké : c'est une position. /implementer-lot <n> <k> lit .tasks[k-1], et tous les scripts en dérivent le reste — branche de lot <task_iid>-<slug>, spec task-NN-<slug>.md, dossier lot-<k>/, cible de close-task.sh.

Ce qu'un lot manquant produit

Un lot créé après le cadrage (/analyser-etape) — un correctif, un incident, un oubli — n'est pas dans .tasks[] tant que rien ne l'y ajoute. L'absence ne déclenche aucune erreur : elle décale l'index. Deux conséquences mesurées sur l'étape 10, où les lots 27 à 33 n'ont jamais été inscrits :

  • Décalage silencieux au ship. ship-lot.sh <n> <k> lit .tasks[k-1] : si un lot manque en amont, le contenu du lot k part dans la branche et la MR du lot k+1. Rien ne proteste — les deux existent, les deux sont valides.
  • Gate de clôture aveugle. check-etape-complete.sh (skill cloturer-etape) n'interroge que ce qui figure dans output.json. Un lot absent n'est pas interrogé, donc ne bloque rien : la clôture du 2026-09-18 a été déclarée complète en ignorant dix lots (#231 à #240).

Le second point est traité côté cloturer-etape par une garde de complétude qui compare output.json aux enfants réels du ticket parent (cf. la référence du skill). Le premier est traité ici, en amont : un lot ad hoc ne s'ajoute plus à la main.

Ajouter un lot ad hoc : add-lot.sh

bash .claude/skills/implementer-lot/bin/add-lot.sh <n> <titre> <slug> <description.md>

Le script fait les trois gestes qui, séparés, se perdent :

  1. crée le work-item enfant rattaché au ticket parent, via create-task.sh du skill analyser-etape — le gid du parent est lu dans .parent.gid d'output.json, pas dans un parent.json (spécificité du workspace ticket, inexistante côté étape) ;
  2. l'ajoute à .tasks[] avec son slug, par une écriture atomique (fichier temporaire puis mv) : un output.json tronqué serait pire que l'absence du lot, tous les scripts du skill en dépendant ;
  3. installe la spec en var/claude/etape<n>/task-NN-<slug>.md, où NN est l'index obtenu après l'ajout. Ce n'est pas une commodité : preflight.sh exige une spec pour chaque entrée de .tasks[], et une spec manquante fait échouer le préflight de tous les lots de l'étape, pas seulement du nouveau. L'appelant ne peut pas pré-positionner NN, qu'il ne connaît pas.

Deux refus en amont, avant tout effet distant :

  • slug non kebab-case (^[a-z0-9][a-z0-9-]*$) → sortie 2. Le slug dérive un nom de branche : un / ou un .. y produirait une ref invalide — ou, pire, une ref valide mais inattendue ;
  • slug déjà porté par un lot de l'étape → sortie 1. Cette garde ne prévient aucune collision technique (branche <iid>-<slug> et spec task-NN-<slug>.md restent distinctes d'un lot à l'autre) : elle prévient l'ambiguïté humaine, et celle des résolutions par motif (<iid>-*, task-*-<slug>.md) — exactement ce qui a coûté cher sur la branche parente de l'étape 10.

En cas d'échec après la création du work-item (écriture d'output.json impossible), le script affiche l'objet JSON reçu et la marche à suivre : sans lui, le work-item serait orphelin et introuvable autrement qu'en fouillant GitLab.

add-lot.sh a un effet remote

Il crée un objet GitLab. Même règle que ship-lot.sh : en run mono-lot, c'est l'utilisateur qui le lance ; en run multi-lots, le main Claude peut le lancer lui-même (exception CLAUDE.md « Actions à effet remote = script obligatoire »). Ce n'est pas une modification de spec — celles-ci restent interdites — mais un ajout : le nouveau lot se traite ensuite comme n'importe quel lot.

Résolution de la branche parente : une lib partagée qui refuse de deviner

output.json ne stocke pas le slug du parent — seulement parent.iid. La branche parente doit donc être devinée depuis le motif <iid>-*, et cette devinette a produit deux défauts, aujourd'hui fermés dans une source unique : .claude/skills/_shared/bin/lib-parent-branch.sh, fonction resolve_parent_branch <parent_iid> <numero_etape> [--allow-remote].

Consommateurs : implementer-lot/bin/preflight.sh, sync-parent.sh, ship-lot.sh, et côté clôture cloturer-etape/bin/preflight.sh et ensure-parent-mr.sh.

Défaut Symptôme Parade dans la lib
git for-each-ref … \| head -1 sous set -o pipefail head ferme le tuyau, git meurt sur SIGPIPE, le script sort en 141 sans un mot. Invisible tant que l'énumération tient dans le tampon de tube — donc indétectable sur un petit dépôt. Aucun tuyau : mapfile sur une substitution de processus.
Motif <iid>-* trop large Les correctifs de fin d'étape se branchent sur l'iid du ticket parent : six branches 202-* coexistaient sur l'étape 10. head -1 retenait la première par ordre alphabétique — jamais la bonne. Paliers successifs <iid>-etape-<n>-* → <iid>-etape-* → <iid>-*, tous épuisés en local avant de regarder origin ; et refus explicite (code 1 + liste des candidates) si plusieurs subsistent.

Le refus est le point important : un script qui devine est pire qu'un script qui s'arrête. Une parente mal résolue fait, selon l'appelant, exiger un préflight sur une branche de correctif d'une ligne, rebaser un lot sur le mauvais tronc, ou ouvrir la MR du lot vers la mauvaise cible.

--allow-remote : pourquoi le local d'abord, toujours

L'option étend la recherche à refs/remotes/origin/ quand rien n'est trouvé en local — implementer-lot peut tourner sur un checkout où la parente n'a jamais été matérialisée. L'ordre d'épuisement des paliers reste local-d'abord : sans cela, un <iid>-etape-<n>-* distant l'emporterait sur la parente locale, alors que c'est le checkout local qui porte le travail.

La parente n'est jamais sortie

sync-parent.sh ne fait plus git checkout <parente> + git pull --ff-only. Depuis que le projet vit en worktrees parallèles, la parente est presque toujours attachée au dépôt principal, et git refuse alors de la sortir ailleurs :

fatal: '202-etape-10-…' is already used by worktree at '/…/kirexo'

L'ancienne séquence rendait donc le script inutilisable depuis un worktree — c'est-à-dire depuis le seul endroit où les lots sont implémentés. À la place : git fetch origin <parente>, qui met à jour la remote-tracking sans toucher à l'arbre de travail, puis tout se rebase sur origin/<parente>. C'est correct que la parente soit attachée ou non.

Corollaire à connaître : la ref locale de la parente peut être en retard (elle n'avance que si quelqu'un fait un pull dans le dépôt principal). Ce n'est plus une cause d'échec — l'ancien pull --ff-only sortait en 1 sur une divergence. C'est désormais une ligne d'information sur stderr, et origin/ fait foi.

Template canonique .claude/skills/implementer-lot/bin/ship.sh

Le template ship.sh factorise la séquence commit → push → MR → auto-merge : ~80 lignes identiques entre lots, et concentre l'injection des conventions GitLab. Il n'est plus reproduit ni généré inline par lot — il est désormais invoqué par le wrapper ship-lot.sh, qui dérive ses arguments (branche de lot, branche parente, task_iid, parent_iid) depuis output.json à partir du seul numéro de lot. Le modèle n'a donc plus de nom de branche ni d'iid à construire. Toutes les sorties glab du template sont réduites au strict minimum (jq -r / >/dev/null) pour ne pas polluer le contexte du main Claude avec un dump d'objet MR.

Signature

La signature du template est inchangée ; seul son point d'appel a évolué (auparavant un ship.sh généré par lot, désormais ship-lot.sh) :

bash .claude/skills/implementer-lot/bin/ship.sh <branch> <target> <commit-msg-file> <mr-desc-file> <files> [etape] [lot] [task_iid] [parent_iid]
Position Argument Obligatoire Rôle
1 <branch> oui Branche source du lot (doit être la branche courante, vérifiée par le script).
2 <target> oui Branche cible de la MR (la branche parente, jamais main).
3 <commit-msg-file> oui Fichier message de commit (commit-msg.txt). Sa 1re ligne sert aussi de titre de MR.
4 <mr-desc-file> oui Fichier description de MR (mr-body.md).
5 <files> oui Liste des chemins du lot, séparés par des espaces, entre guillemets. Validée avant tout geste (cf. § ci-dessous), puis stagée explicitement (git add -- "${FILE_LIST[@]}"), jamais git add -A.
6 [etape] non Numéro d'étape, pour le marqueur Étape X - lot Y.
7 [lot] non Numéro de lot, pour le marqueur Étape X - lot Y.
8 [task_iid] non IID du work-item de tâche, pour l'entête Tâche #T · Ticket #P.
9 [parent_iid] non IID du ticket parent, pour l'entête Tâche #T · Ticket #P.

Les arguments 6 à 9 sont optionnels (rétrocompatibilité avec les appels antérieurs). En pratique, ship-lot.sh les renseigne systématiquement à partir du numéro de lot, activant les trois conventions ci-dessous — et conditionnant l'écriture de mr.json, qui a besoin de [etape] et [lot] pour connaître son chemin.

Ce que ship.sh valide avant d'agir

$FILES est une chaîne libre rédigée par le modèle. Elle est validée avant castor audit, qui coûte plusieurs dizaines de secondes, et avant tout geste git :

Contrôle Verdict Raison
Liste vide après découpage échec (1) ${5:?} ne rejette que la chaîne vide, pas " ". Sans garde, git add -- sans pathspec rend 0 en disant « Nothing specified », et l'échec n'arrive qu'au commit — après l'audit.
Un élément est un répertoire échec (1) Un répertoire ajoute tout son contenu récursivement, fichiers non suivis compris : c'est git add -A déguisé, ce que l'en-tête du script interdit explicitement. La garde était documentée, pas implémentée.
Un élément n'est ni sur le disque ni suivi par git échec (1) Chemin faux, typo, fichier supprimé hors index.
Un fichier modifié ou neuf absent de la liste avertissement, pas d'arrêt Le modèle peut légitimement laisser un fichier de côté — mais plus jamais en silence. Le 2026-09-18, un lot est parti sans les 2 061 lignes de scripts que son code invoquait.

Deux détails d'implémentation qui ne sont pas du style :

  • set -f + expansion nue, jamais read -r -a. Le splitting sur l'IFS est voulu, le globbing non : set -f neutralise l'expansion de * et [ par bash avant que les chemins n'atteignent git. read aurait été le piège inverse — il lit une ligne, donc un $FILES construit par git diff --name-only ou cat files.txt (deux formes présentes dans ce dépôt) serait tronqué à son premier fichier, en silence, et la boucle de validation ne verrait qu'une entrée donc ne protesterait pas.
  • git status --porcelain -uall pour le contrôle par l'effet. Sans -uall, git replie les répertoires non suivis (?? Étapes/ au lieu des fichiers dedans) : le contrôle comparerait un répertoire à une liste de fichiers et crierait au loup à chaque lot créant un dossier. Un avertissement qui se déclenche à tort est un avertissement qu'on apprend à ignorer.

Un chemin contenant une espace n'est pas shippable — dette assumée

Le contrat de l'argument 5 est « chemins séparés par des espaces » : une espace dans un chemin n'y est pas représentable. Le découpage le sépare en deux, et le ship s'arrête proprement à la validation (chemin inexistant), avant tout geste. Changer de délimiteur toucherait les deux SKILL.md et tous les appelants : c'est une dette connue, pas un oubli.

check-test-artifacts.sh est désormais réellement appelé

Son en-tête annonçait « Appelé par ship.sh avant le commit » depuis toujours, mais aucun appelant n'existait : la garde était morte dans les deux skills. Elle est branchée après le git add (elle lit git diff --cached), donc après castor audit — qu'on paie pour rien quand elle refuse. Son critère serait calculable plus tôt, sur la liste de fichiers ; le déplacer impose de réécrire un script dupliqué dans les deux skills. Angle mort désormais actif : son pathspec tests/**/*.php ne matche pas un fichier posé à la racine de tests/.

Vérification par l'effet : l'auto-merge est relu, pas déduit

GitLab accepte le PUT …/merge_requests/<iid>/merge et répond 200 alors que le drapeau n'est pas posé, notamment quand la MR n'est pas encore dans un état décidable. Conclure sur le code retour laisse une MR ouverte indéfiniment, CI verte, sans que rien ne le signale — vécu le 2026-09-18, avec un ✓ auto-merge armé affiché sur un drapeau à false.

ship.sh relit donc l'état après le PUT :

ARMED="$(glab api "projects/:id/merge_requests/$IID" 2>/dev/null \
  | jq -r 'if .state == "merged" then "merged" else (.merge_when_pipeline_succeeds // false | tostring) end' || true)"
  • true ou merged → message de succès, code 0. merged compte : la pipeline peut avoir fini entre le PUT et la relecture.
  • tout le reste → message explicite ⚠ … l'auto-merge N'EST PAS armé, la commande de rattrapage (rearm-merge.sh <iid>), et sortie en 1. Le lot n'est pas « shippé » tant que le drapeau n'est pas posé.

rearm-merge.sh applique la même règle sur son propre PUT, et affiche l'état relu (${ETAT:-illisible}) plus les dernières lignes de la réponse GitLab quand il échoue — l'ancien >/dev/null 2>&1 rendait un message d'erreur applicatif indiscernable d'un succès.

|| true sur les substitutions glab — ce n'est pas de la négligence

Sous set -euo pipefail, une substitution de commande qui échoue tue le script sur place. Après le commit et le push, cela veut dire mourir sans un mot : le sosie exact du | head -1 sorti en 141. Les substitutions glab de la fin de ship.sh traitent donc une valeur vide (IID illisible → message + 1 ; detailed_merge_status vide → on patiente, comme sur checking) plutôt que de disparaître.

Conventions GitLab injectées par ship.sh

Ces métadonnées sont injectées automatiquement par le template — à coût token nul au runtime, et jamais rédigées par le main Claude. commit-msg.txt et mr-body.md ne doivent donc pas les contenir : les y mettre à la main produirait un doublon.

1. Assignation systématique à cpereira

La MR créée est assignée via glab mr create --assignee "$ASSIGNEE", où ASSIGNEE="${GITLAB_ASSIGNEE:-cpereira}". Par défaut cpereira, surchargeable par la variable d'environnement GITLAB_ASSIGNEE. C'est la même convention que celle appliquée par analyser-etape (ticket parent, tâches) et cloturer-etape (MR parente) — cf. analyser-etape et cloturer-etape.

2. Marqueur Étape X - lot Y dans le titre

Si <etape> et <lot> sont fournis, le template insère le marqueur Étape X - lot Y dans la 1re ligne du commit, après le type(scope): conventionnel :

feat(scope): sujet impératif du lot
        ↓  (ship.sh … <X> <Y> …)
feat(scope): Étape X - lot Y — sujet impératif du lot

L'insertion est faite en bash pur (pas de sed) pour éviter les soucis d'UTF-8/locale sur le tiret cadratin —. Si la 1re ligne n'a pas de : (pas de préfixe conventionnel), le marqueur est mis en préfixe. Le titre enrichi sert à la fois de message de commit (git commit -F) et de titre de MR (--title), garantissant leur cohérence. Le corps du commit (lignes 2+) reste inchangé.

3. Entête de navigation Tâche #T · Ticket #P

Si <task_iid> et <parent_iid> sont fournis, le template préfixe la description de MR par une ligne :

Tâche #<task_iid> · Ticket #<parent_iid>

GitLab transforme automatiquement les #N en liens croisés vers le work-item de tâche et le ticket parent. Le corps de mr-body.md est concaténé tel quel à la suite. L'entête n'est ajoutée que si les deux IID sont fournis.

Source de vérité d'un lot : fetch-issue.sh (mode STRICT)

Avant d'implémenter un lot (Étape C.2 du SKILL.md), le main Claude ne lit pas seulement le fichier local var/claude/etape<n>/task-NN-<slug>.md : il récupère le contenu vivant du work-item GitLab via fetch-issue.sh <task-iid>. Le script imprime sur stdout, en markdown, la description courante du work-item suivie des commentaires humains (notes système filtrées : liaisons hiérarchiques, changements de label, etc. sont exclues — seules les notes rédigées par un humain portent une intention sur la tâche).

Pourquoi le live plutôt que le fichier local

Le task-NN-<slug>.md est le snapshot de cadrage posé par analyser-etape comme description du work-item. Mais entre le cadrage et l'implémentation, un humain peut avoir :

  • amendé la description du work-item directement dans l'UI GitLab ;
  • ajouté un commentaire qui précise, corrige ou réoriente un point du lot.

Coder sur le seul fichier local reviendrait à ignorer ces ajustements. fetch-issue.sh capture l'état réel au moment de l'implémentation. Le fichier local reste la référence stable lue par les sous-agents (reviewer, test-writer) ; en cas de divergence, le contenu vivant prime.

Pourquoi le mode STRICT (pas de retombée locale)

Si GitLab est injoignable ou l'iid introuvable, fetch-issue.sh sort en 1 et le skill s'arrête — il ne retombe jamais sur le .md local. C'est un choix défensif : un fallback silencieux ferait coder sur une base potentiellement périmée sans signal. Mieux vaut un arrêt net (réseau / glab à réparer) qu'une implémentation menée sur une spec obsolète.

Lecture pure, autorisée inline

fetch-issue.sh n'a aucun effet remote : glab issue view (description + titre) et glab api .../notes (commentaires) sont des GET, classés en lecture pure par CLAUDE.md (« Hors périmètre — exécution inline autorisée »). Le main Claude le lance donc directement, contrairement aux scripts à effet remote (ship-lot.sh, fix-amend.sh) réservés à l'utilisateur en mono-lot. Le wrapper gl() (cf. ci-dessous) le rend portable hôte ↔ conteneur de worktree.

glab mr view --output json

Champs consommés par wait-merge.sh et diag-mr.sh

docker compose exec -T php glab mr view <iid> -R shaurifr/kirexo --output json renvoie un objet en snake_case (contrairement à glab work-items consommé par analyser-etape, cf. ci-dessous). Les champs utilisés par le skill :

Champ JSON Type Utilisation
state string : opened / merged / closed / locked Décide du code retour de wait-merge.sh.
detailed_merge_status string (enum, cf. table ci-dessous) Interprété par diag-mr.sh pour expliquer pourquoi une MR opened ne merge pas.
has_conflicts bool Flag direct pour le diagnostic « conflit Git non résolu ».
draft bool Repère les MR encore en brouillon (auto-merge bloqué).
user_notes_count int Présence de commentaires humains à examiner avant un retry.
head_pipeline.status string : success / failed / running / pending / canceled / skipped Statut de la pipeline de tête.
head_pipeline.web_url string Lien direct vers la pipeline dans le rapport de diagnostic.
head_pipeline.id int Sert à requêter les jobs échoués via glab api projects/.../pipelines/<id>/jobs.

Asymétrie PascalCase ↔ snake_case (déjà documentée pour analyser-etape)

glab work-items create --output json renvoie du PascalCase (IID, WebURL, ID). glab issue create --output json et glab mr view --output json renvoient du snake_case classique (iid, web_url, id). Ne pas réutiliser un jq qui marche pour l'un sur l'autre — implementer-lot ne touche que des MR et des issues, donc tout est en snake_case côté ce skill.

Encodage du chemin projet pour glab api

Quand diag-mr.sh doit basculer sur glab api pour récupérer les jobs CI échoués, le chemin de projet (shaurifr/kirexo) doit être encodé URL — le / devient %2F. Le skill utilise le bash builtin de substitution plutôt qu'un sed :

PROJECT_PATH="shaurifr/kirexo"
PROJECT_ENC="${PROJECT_PATH//\//%2F}"   # "shaurifr%2Fkirexo"
glab api "projects/${PROJECT_ENC}/pipelines/<id>/jobs?scope[]=failed"

Avantages : pas de sous-processus, pas de quoting fragile, pas de dépendance à sed (déjà installé, mais le builtin est plus rapide et lit mieux).

Wrapper bash gl() (glab natif vs docker compose exec)

Les scripts du skill définissent en tête un wrapper :

gl() {
  if command -v glab >/dev/null 2>&1; then
    glab "$@"
  else
    docker compose exec -T php glab "$@"
  fi
}

Raison : glab est installé dans le conteneur php (prérequis CLAUDE.md), pas sur l'hôte par défaut. Le wrapper rend les scripts portables hôte ↔ conteneur de worktree. -T désactive l'allocation TTY pour rester compatible avec une exécution depuis Claude Code (sans TTY).

Polling court vs ScheduleWakeup

Pourquoi 5 min de polling max dans wait-merge.sh

Côté Anthropic, le cache prompt a un TTL de 5 minutes : tant qu'on relance un appel dans cette fenêtre, on paye un cache hit (≈ 10 % du tarif standard). Au-delà, le cache expire et le prochain appel coûte plein tarif (cache miss).

Le skill exploite cette césure :

  • Attente courte (≤ 5 min) → polling actif dans la session via wait-merge.sh (15 s d'intervalle, 20 itérations max). Le cache reste chaud, le coût marginal de chaque tour de boucle est négligeable.
  • Attente longue (> 5 min) → on ne paie pas un cache miss pour rester planté à attendre. Mieux vaut sortir de la session, libérer le cache, et reprendre frais via ScheduleWakeup(delaySeconds: 1200, reason: "...", prompt: "/implementer-lot <n> <k>-<z>"). 1200 s = 20 min : couvre une pipeline CI normale (build + tests + E2E ≈ 8-15 min) avec marge.

Au réveil, le skill re-exécute le préflight (Étape B vérifiera que les lots déjà mergés sont skip), donc le cycle est idempotent.

Codes retour normalisés de wait-merge.sh

Trois codes distincts pour les MR non-mergées, et c'est volontaire — chaque code déclenche une action différente côté main Claude :

Code Sens Action côté skill
0 state == "merged" Succès, passer au lot suivant.
2 state == "closed" MR fermée sans merge → diagnostic obligatoire (diag-mr.sh) et question utilisateur. Pas de retry auto.
3 state == "opened" toujours après 5 min Attente longue → ScheduleWakeup + sortie de session. Pas un échec, juste « pas encore ».
4 Erreur réseau, glab indisponible, JSON malformé Diagnostic + arrêt. Probablement un souci d'environnement, pas de la MR.

Fusionner 2 et 3 en un seul code « pas merged » serait une régression : un closed n'est jamais une attente, c'est un échec définitif qui demande l'attention humaine ; un opened après timeout est juste un signal pour basculer sur ScheduleWakeup. Fusionner 3 et 4 casserait aussi l'arbre de décision (un timeout normal n'est pas une erreur).

Interprétation du detailed_merge_status

Le champ detailed_merge_status de l'API GitLab v4 (/api/v4/projects/.../merge_requests/<iid>) est plus fin que merge_status et explique précisément ce qui bloque une MR opened. Table des valeurs interprétées par diag-mr.sh :

Valeur Interprétation Action conseillée
mergeable La MR est prête, GitLab va tenter le merge. Si elle reste dans cet état, c'est souvent l'auto-merge en cours. Patienter, c'est le cas nominal pendant la fenêtre d'auto-merge.
ci_must_pass La pipeline n'a pas (encore) atteint success. Vérifier head_pipeline.status. Si failed → diagnostic des jobs échoués. Si running / pending → attendre.
conflict Conflit Git avec la branche cible. has_conflicts == true. Rebase manuel sur la branche parente. Pas de force-push auto.
discussions_not_resolved Au moins un thread de review reste ouvert. Repérer via user_notes_count + lien MR. Décision humaine.
draft_status MR encore en brouillon (draft == true). glab mr update --ready côté utilisateur.
not_approved Le projet exige N approbations et le seuil n'est pas atteint. N/A sur ce projet (pas de règle d'approbation côté shaurifr/kirexo), à surveiller si on en ajoute.
blocked_status Une autre MR doit être mergée d'abord (dépendance déclarée). Pas utilisé sur ce projet, l'ordre des lots est porté par l'invariant skill, pas par GitLab.
need_rebase La branche source est en retard sur la cible et le projet exige un fast-forward. git pull --rebase origin <parent-branch> + git push.
checking GitLab est en train de calculer le statut de merge. Transitoire, repoller dans 15 s.
preparing Idem, plus tôt dans le cycle. Transitoire.
unchecked GitLab n'a pas (encore) lancé le check. Transitoire, force un check via glab mr view (effet de bord du GET).

diag-mr.sh produit un rapport markdown structuré qui cite la valeur exacte du detailed_merge_status et la ligne d'interprétation associée. C'est ce rapport que le main Claude restitue à l'utilisateur en cas d'auto-merge KO.

Stratégie de relance auto-merge

Quand wait-merge.sh retourne 3 avec une pipeline failed (ou un detailed_merge_status bloquant), le skill tente une relance bornée plutôt que d'escalader immédiatement au user. Cette page documente les choix de conception ; le déroulé fonctionnel est en § D du SKILL.md.

Mapping failure_reason → catégorie

L'API GitLab v4 expose, pour chaque job en échec listé via glab api projects/<id>/pipelines/<pid>/jobs?scope=failed, un champ failure_reason (enum). Le script categorize-failure.sh applique la table de correspondance suivante :

failure_reason Catégorie Cause typique
runner_system_failure runner Le runner GitLab a planté avant ou pendant le job (souci hyperviseur, OOM système, perte de connexion).
stuck_or_timeout_failure runner Aucun runner disponible pour prendre le job dans la fenêtre allouée (file d'attente saturée, label de runner absent).
job_execution_timeout runner Le job a dépassé son timeout global GitLab — pas une erreur de code, mais une enveloppe infra trop courte.
script_failure (et tout le reste) impl Le script du job a renvoyé un code non nul. C'est le cas nominal d'un test qui plante, d'un phpstan qui sort en erreur, d'un cs:fix qui détecte un fichier non conforme.

Quand runner_jobs et impl_jobs sont tous deux non vides sur la même pipeline, la catégorie devient mixed et l'impl est traitée en priorité — un bug de code reste un bug de code, même si un runner a aussi flanché à côté. Le runner pourra être retenté ensuite si l'amend ne suffit pas.

unknown est réservé au cas dégénéré où la pipeline est failed mais qu'aucun job n'a de failure_reason exploitable (situation rare : on escalade au user sans tenter de relance).

none signifie « pas de jobs échoués sur la pipeline de tête » : la MR ne merge pas pour une autre raison (conflit Git, discussions_not_resolved, brouillon, etc.), et la relance CI ne servirait à rien.

Pourquoi des quotas séparés impl / runner plutôt qu'un compteur global

Le skill plafonne impl_attempts ≤ 1, runner_attempts ≤ 1 et impl + runner ≤ 2. Un compteur global unique aurait été plus simple à coder, mais aurait deux défauts :

  • Une rafale de problèmes d'infra peut masquer un vrai bug. Si trois runner_system_failure consécutifs consomment un quota global de 3, le skill pourrait ne plus avoir le droit de tenter un fix-amend.sh quand un script_failure apparaît au quatrième tour. À l'inverse, isoler le runner garantit qu'un problème infra n'épuise jamais la capacité de réagir à un bug.
  • L'inverse est aussi vrai. Si on a déjà tenté un fix-amend.sh (impl), et qu'un runner plante ensuite, c'est un signal infra indépendant qui mérite sa propre tentative — pas un signe que « la MR est mauvaise ».

Les deux quotas restent à 1 chacun (et la somme à 2) : au-delà, le coût de continuer à essayer automatiquement dépasse la valeur d'attendre une décision humaine.

Pourquoi git commit --amend --no-edit + git push --force-with-lease

Plutôt qu'un nouveau commit « fix: …» ajouté par-dessus.

  • Préserver le mono-commit du lot. L'invariant projet est « un lot = un commit de production ». Un fix poussé en commit séparé casserait l'invariant et obligerait le merge à faire un squash, ce que la mémoire utilisateur interdit (Jamais de squash automatique GitLab). --amend --no-edit réécrit le commit du lot en gardant son sujet et son corps initiaux : le titre de MR, le contenu de commit-msg.txt et le commit poussé restent cohérents.
  • --force-with-lease plutôt que --force. Un --force brut écraserait n'importe quel état distant, y compris une branche qui aurait reçu des commits entre-temps (par ex. via un push concurrent, ou si la MR a été mergée pendant qu'on préparait l'amend). --force-with-lease compare la ref locale connue à celle du remote et refuse le push si elles divergent — le skill échoue alors proprement plutôt que de détruire silencieusement du travail.

Pourquoi retry job par job (et pas la pipeline entière)

Sur catégorie runner, retry-failed-jobs.sh itère sur les id listés dans categorize-failure.sh > .runner_jobs[].id et appelle glab api projects/<encoded>/jobs/<id>/retry --method POST pour chacun. Plusieurs raisons d'éviter un retry de toute la pipeline (glab api projects/<id>/pipelines/<pid>/retry) :

  • Ne pas re-déclencher les jobs déjà OK. Une pipeline Kirexo enchaîne cs:fix, phpstan, lint, schema:validate, test:unit, test:e2e. Si seul test:e2e a sauté sur un stuck_or_timeout_failure, retenter test:unit et tous les jobs amont est du gâchis CI (temps, coût, file d'attente runners).
  • Ne compter qu'une seule tentative runner même si plusieurs jobs ont sauté. L'incrément runner_attempts += 1 est unique par appel à D.4, quel que soit le nombre de jobs retentés en lot. Un retry de pipeline brouillerait ce compte.
  • Garder une trace fine côté GitLab. Un retry de pipeline crée une nouvelle pipeline complète et masque l'historique du job d'origine. Un retry par job conserve l'identité du job dans l'historique de la pipeline et facilite l'analyse post-mortem (« quel job a sauté combien de fois, sur quel runner »).

Pourquoi pas de relance sur wait-merge.sh codes 2 et 4

Le mapping est volontairement asymétrique :

  • Code 2 (state == "closed") — la MR a été fermée. Cela peut venir d'un humain (revue qui refuse le lot, décision de redécouper), de GitLab (rare, mais possible sur certaines configurations de protection), ou d'une action externe. Le CI n'a rien à voir avec ce signal : retenter quoi que ce soit reviendrait soit à rouvrir la MR sans comprendre pourquoi elle a été fermée, soit à ouvrir une nouvelle MR identique. Les deux sont des décisions de produit qui demandent l'attention humaine.
  • Code 4 (erreur réseau ou glab KO) — on ne sait même pas dans quel état est la MR. Toute action automatique (relance CI, amend, force-push) serait prise en aveugle. La seule action sûre est de remonter le diagnostic et d'attendre un environnement réseau / glab fonctionnel.

Codes 0 et 3 sont, eux, des signaux exploitables : 0 est un succès, 3 est une attente où l'on a accès à un état complet de la MR (detailed_merge_status, head_pipeline.status, liste des jobs) pour décider intelligemment.

Rétro opt-in et skill-improver

Après la clôture du lot (Étape E), avant de rendre la main, le main Claude pose une question fermée : « Tu veux une rétro pour améliorer ce skill (SKILL.md, scripts bin/, agents sollicités) sur la base du run ? (oui / non) ». Sur oui, délégation au sous-agent skill-improver ; sur non, fin de session immédiate. Cette section documente les choix de design de cette boucle d'amélioration récursive bornée.

Pourquoi opt-in et pas auto

La rétro a un coût non négligeable : lecture des transcripts .jsonl du run (potentiellement plusieurs Mo), analyse des cycles de délégation, génération du rapport. Sur un run sans surprise — pas de cycle reviewer / test-writer > 1, pas de relance auto-merge, pas d'escalade utilisateur, pas de correction inline — l'analyse renvoie peu de propositions à fort impact et la dépense de tokens n'est pas justifiée.

Imposer la rétro à chaque run reviendrait à payer ce coût même pour les lots triviaux qui passent en ligne droite. À l'inverse, désactiver la rétro par défaut prive le skill du retour d'expérience le plus précieux : celui pris « à chaud », juste après le run, sans rejouer mentalement les frictions des jours plus tard.

L'opt-in en fin de session est le bon compromis : l'utilisateur sait à ce moment-là s'il y a eu friction (relances, corrections, escalades) ou si le run s'est déroulé proprement, et décide en connaissance de cause.

Pourquoi un sous-agent dédié et pas inline

Trois raisons motivent la délégation à skill-improver plutôt qu'une analyse inline par le main Claude :

  1. Isolation du contexte main. Après plusieurs lots, le contexte du main Claude est déjà chargé (specs, code édité, sorties de vérifs, échanges utilisateur). Y empiler la lecture des transcripts .jsonl et l'analyse statistique grèverait le budget restant — alors que la rétro n'a pas besoin de ce contexte applicatif.
  2. Lecture de fichiers volumineux sans pollution. Les transcripts .jsonl peuvent dépasser plusieurs Mo et contenir des extraits de code copiés-collés au fil du run. Un sous-agent peut les lire dans son propre contexte, isoler les signaux pertinents (frictions, répartition tokens), et restituer un rapport condensé.
  3. Éviter le biais d'auto-jugement. Le main Claude qui vient de produire le run n'est pas le mieux placé pour critiquer son propre déroulé : il aurait tendance à rationaliser les frictions plutôt qu'à les pointer froidement. Un agent dédié, instruit pour repérer corrections user, cycles reviewer / test-writer > 1, refus hook et escalades, applique le même filtre quel que soit le contenu du run.

Le pattern est symétrique à celui utilisé par cloturer-etape, qui délègue lui aussi son introspection à un sous-agent dédié plutôt que de la faire faire au main.

Format du rapport

Le skill-improver produit un seul fichier markdown : var/claude/skill-improvements/<YYYY-MM-DD>-<skill-name>-etape<n>.md (suffixe -NN si un rapport existe déjà pour la même date et la même étape, p. ex. -02). Structure imposée :

  1. Synthèse — 2 à 5 lignes : verdict global du run (fluide / quelques frictions / nombreuses frictions), nombre de propositions, gain estimé cumulé.
  2. Répartition tokens — postes consommateurs (contexte initial, lectures de fichiers, recherches Grep / Glob, sous-agents avec noms, commandes shell, génération des livrables), en estimation grossière à ~100 %.
  3. Frictions observées — liste factuelle, chaque ligne renvoyant à un horodatage ou un message des transcripts (corrections user, refus hook, cycles reviewer répétés, escalades, etc.).
  4. Propositions classées par impact — 3 à 7 patches concrets, ordre d'impact décroissant. Chaque proposition contient : cible fichier (chemin + lignes), diff unified propre, gain estimé (tokens / latence / frictions évitées), raison (lien explicite avec la friction observée au § 3), risque.

Le rapport est restitué tel quel par le main Claude qui présente ensuite chaque proposition une par une.

Périmètre strict des cibles

Le skill-improver peut proposer des patches uniquement sur :

  • .claude/skills/<skill>/SKILL.md
  • .claude/skills/<skill>/bin/*.sh
  • .claude/agents/<agent>.md — uniquement pour les agents réellement sollicités pendant le run (lus dans les transcripts), pas les autres.

Hors périmètre : CLAUDE.md (global et projet), projet.md, .claude/settings.json, les hooks .claude/hooks/, le code de production sous src/, les tests sous tests/, la doc Diátaxis sous docs/. La raison est défensive : ces fichiers concentrent les invariants structurants du projet (règles d'architecture, permissions de tools, garde-fous de délégation). Une proposition automatique qui les modifierait sans contrôle humain renforcé pourrait casser les patterns de tous les autres skills et sous-agents. Pour amender un de ces fichiers, l'utilisateur passe par une demande explicite séparée, pas par la rétro d'un skill.

Pourquoi patches un par un (et pas un diff global)

Le main Claude présente les propositions une par une dans l'ordre du rapport (impact décroissant), avec pour chacune le choix appliquer / passer / amender. Trois raisons :

  • Alignement avec la mémoire utilisateur « découverte itérative > cadrage initial exhaustif ». L'utilisateur préfère filtrer en cycles courts plutôt que valider un gros bloc en bloc. Un diff global force un choix tout-ou-rien qui ne laisse pas la place à l'amendement.
  • Permettre d'amender à mi-parcours sans tout rejeter. Une proposition peut être pertinente sur l'intention mais imparfaite sur le diff (libellé maladroit, condition trop large, oubli d'un cas). Le mode amender permet d'ajuster puis de re-présenter sans perdre la proposition entière.
  • Détecter les effets de bord entre patches. Deux propositions peuvent toucher la même section et se contredire si elles sont appliquées ensemble en aveugle. Le mode un-par-un permet au main Claude de signaler les collisions au fur et à mesure.

Mise à jour du rapport post-validation

Une fois la boucle terminée, le main Claude met à jour le fichier rapport : chaque proposition est annotée selon le verdict de l'utilisateur :

  • (appliquée) — patch écrit tel quel.
  • (amendée et appliquée) — patch ajusté avant écriture, le diff final remplace le diff initial dans le rapport.
  • (passée) — proposition refusée, conservée dans le rapport avec la mention.

Le fichier reste sous var/claude/skill-improvements/ comme historique de décisions. Utilité concrète : lors d'un futur run de rétro sur le même skill, le skill-improver peut lire les rapports précédents (mêmes chemins) et éviter de re-proposer un patch déjà passé pour une raison qui n'a pas changé — ou au contraire revenir dessus si le contexte a évolué.

Garde-fous

Deux garde-fous bornent ce que le skill-improver peut proposer :

  • Pas de patch qui contredit CLAUDE.md. Si une proposition lèverait un invariant projet (mono-commit par lot, lot ≤ 5 fichiers PHP de prod, ordre des vérifs cs:fix → phpstan → lint → schema:validate), l'agent doit la signaler comme telle et ne pas la proposer. Le rapport peut mentionner la friction observée mais sans patch automatique.
  • Signalement des changements de signature inter-fichiers. Si une proposition modifie la signature d'un script bin/<x>.sh (nom, ordre d'arguments, code retour), elle doit aussi proposer la mise à jour du SKILL.md qui l'appelle — un patch isolé sur un script casserait la cohérence avec le déroulé du SKILL.md. L'agent émet alors deux propositions liées dans le rapport, à appliquer ensemble.

Couverture de tests des scripts

Ces scripts décident à la place du modèle : sur quelle branche un skill travaille, quels fichiers partent dans un commit, si une étape peut être clôturée, si un lot ad hoc est correctement inscrit. Jusqu'au 2026-09-19, un seul des 32 scripts de la chaîne (analyser-etape, implementer-lot, cloturer-etape, _shared) était couvert : detect-twig.sh.

tests/Bash/skills-lot/ en compte désormais 88 cas, joués par castor test:bash (cf. Exécuter les tests) :

Fichier Couvre
parent_branch.bats resolve_parent_branch de _shared/bin/lib-parent-branch.sh — fonction pure sur des refs git, dans un dépôt jetable
ship_liste_fichiers.bats la validation de $FILES de implementer-lot/bin/ship.sh, arrêtée sur un stub castor
check_etape_complete.bats la garde de complétude de cloturer-etape/bin/check-etape-complete.sh, glab stubbé par des fichiers JSON
add_lot.bats implementer-lot/bin/add-lot.sh, create-task.sh stubbé

Trois contraintes de conception y sont documentées dans tests/Bash/skills-lot/README.md et valent d'être connues avant d'y ajouter un cas : chemins relatifs à $BATS_TEST_DIRNAME (jamais /app/…, figé dans l'image CI et dépourvu des fichiers neufs d'une branche) ; PATH réduit à chaque invocation, de sorte qu'aucun test ne puisse atteindre glab, git push, castor audit ou docker compose même par accident ; dépôt git jetable dans $BATS_TEST_TMPDIR, puisque ship.sh et add-lot.sh font cd "$(git rev-parse --show-toplevel)".

Le SIGPIPE n'apparaît qu'au-delà du tampon de tube

Le défaut … | head -1 sous pipefail est invisible tant que git finit d'écrire avant que head ne ferme. Un test qui se contenterait de deux ou trois refs serait vert sur le code défectueux. parent_branch.bats construit donc 3 000 refs et vérifie que l'énumération dépasse 64 KiB avant d'affirmer quoi que ce soit sur le code de sortie.

Invariants préservés par le skill

Le skill garantit un petit nombre d'invariants fonctionnels, dont chacun a une mécanique technique qui le porte :

Ordre strict des lots — vérité côté GitLab, pas local

Avant de démarrer un lot k, le skill lance check-lot-state.sh <n> <j> pour chaque j < k. Le script interroge la branche distante et la MR distante via glab : mr_state != "merged" → arrêt. Aucun fichier de state local n'est consulté. Conséquence : on peut interrompre / reprendre / changer de machine, l'ordre est porté par GitLab.

Pas de merge vers main

Le glab mr create du template ship.sh (invoqué par ship-lot.sh) cible systématiquement la branche parente, jamais main. La fusion <parent-branch> → main est réservée à la clôture d'étape (/cloturer-etape, hors périmètre de ce skill). Côté permissions, .claude/settings.json dénie déjà git push origin main au main Claude — double tour.

Mono-commit par lot, préservé même après relance

Chaque lot fusionne sur la branche parente sous la forme d'un seul commit, dont le sujet et le corps sont ceux écrits dans commit-msg.txt. Cet invariant est porté techniquement par :

  • le template ship.sh (invoqué par ship-lot.sh) qui fait un unique git commit -F commit-msg.txt (jamais une suite de commits).
  • fix-amend.sh qui, en cas de relance impl, utilise git commit --amend --no-edit — le message original est préservé, l'historique de la branche tâche reste à un commit.
  • git push --force-with-lease qui propage l'amend sans tolérer une divergence distante (cf. section « Stratégie de relance auto-merge »).

Conséquence : pas besoin de squash au merge (mémoire utilisateur : Jamais de squash automatique GitLab), et l'historique de <parent-branch> reste lisible — un commit par lot, dans l'ordre.

Pas d'écriture de tests ni de doc par le main Claude

Le hook guard-delegation.sh refuse tout Write du main Claude dans tests/ ou docs/. La seule porte d'entrée légitime est la délégation à test-writer (obligatoire après tout fichier PHP de prod modifié) ou doc-writer (obligatoire si impact UX). Voir hooks-claude.md pour les détails.

Effets remote uniquement via ship-lot.sh lancé par l'utilisateur

En mono-lot, le main Claude ne lance jamais ship-lot.sh lui-même. Il propose un lien cliquable et attend la confirmation utilisateur. C'est la règle CLAUDE.md « Actions à effet remote = script obligatoire » : git push, glab mr create, tout payload publié doit pouvoir être relu avant publication (les commit-msg.txt / mr-body.md sont écrits et visibles avant le lancement). La conséquence pratique : aucun push ni MR n'est créé sans une action humaine explicite, même quand l'outil est techniquement autorisé dans .claude/settings.json. Exception — en run multi-lots (range <x>-<z> ou set complet), CLAUDE.md autorise le main Claude à lancer lui-même ship-lot.sh pour enchaîner les lots sans interruption manuelle ; la relecture du payload reste assurée et castor audit tourne avant chaque push.

skill-improver n'écrit qu'à un seul endroit

Le sous-agent skill-improver n'écrit jamais en dehors de var/claude/skill-improvements/. Les patches sur le SKILL.md, les scripts bin/ ou les agents sollicités sont appliqués par le main Claude après validation utilisateur, jamais par l'agent lui-même. Techniquement, le sous-agent ne reçoit que les tools Read, Glob, Grep, Bash et Write — et le Write est restreint par convention au seul dossier var/claude/skill-improvements/. Conséquence : aucune modification du skill, des scripts ou des agents ne peut survenir sans relecture humaine du diff, ce qui protège la cohérence du framework de skills même quand la rétro propose une refonte large.

Voir aussi

  • .claude/skills/implementer-lot/SKILL.md — description fonctionnelle du skill (invocation, déroulé étape par étape, erreurs à signaler).
  • ../../.claude/agents/skill-improver.md — sous-agent invoqué par l'Étape F (rétro opt-in) : périmètre, tools, format du rapport, garde-fous.
  • Skill analyser-etape — le pendant amont : cadrage d'étape, création des work-items, asymétries glab work-items ↔ glab issue.
  • Hooks Claude Code — guard-delegation.sh (qui peut écrire où), count-prod-php.sh (quota 5 fichiers PHP de prod), stop-checklist.sh (checklist de fin de tâche).
  • Workflow des agents Claude — pourquoi le main Claude délègue à reviewer, test-writer, doc-writer, et pourquoi implementer-lot enchaîne ces délégations dans un ordre fixe.