Aller au contenu

Une preuve non versionnée n'est pas une preuve

Cette page explique pourquoi l'outillage qui prouve la Definition of Done d'une étape a quitté var/claude/ pour infra/dod/, versionné et testé — et pourquoi il n'a pas atterri dans tests/, qui semblait pourtant sa place naturelle.

Pour les gestes, voir Definition of Done : castor dod:check, dod:tls et dod:clean, leurs options et leurs verdicts.

Ce qu'une Definition of Done demande

La règle du projet est qu'une case cochée porte la commande jouée et sa sortie. Une case cochée sans sortie observée est un échec de lot. C'est la même exigence que celle qui structure le confinement — vérifier l'effet, jamais la configuration — transposée à l'échelle d'une étape entière : le proxy filtre-t-il vraiment, deux worktrees tiennent-ils vraiment en parallèle, un wt:destroy laisse-t-il vraiment zéro résidu.

Mais une exigence de preuve porte sur autre chose que le fait d'avoir mesuré une fois. Une preuve n'a de valeur que si elle est rejouable : par quelqu'un d'autre, sur un autre poste, six mois plus tard, après trois refactors de l'infrastructure. Sans cela, on n'a pas prouvé que le système tient — on a montré qu'il tenait, ce jour-là, sur cette machine.

Ce qui s'est passé

L'outillage de preuve de l'étape 10 vivait sous var/claude/etape10/. var/ est gitignoré : ces scripts n'étaient donc pas versionnés, pas partagés entre worktrees, et couverts par aucun test.

Le 2026-09-18, l'inventaire a été fait. Quatre des six scripts de preuve avaient disparu :

Script perdu Ce qu'il prouvait
dod-container.sh Le volet conteneur de la DoD — 14 cases.
c9-check.sh La case 29.
prod-smoke.sh La case 30 — build de l'image de production.
host/2*.sh Les sondes des lots 4 à 8.

Les preuves qu'ils ont produites restent vraies pour leur run daté. Personne ne peut plus les refaire. Une case de DoD qui n'est plus rejouable n'est pas « déjà validée » : elle est non vérifiable, ce qui est le statut d'une case qui n'a jamais été jouée — la différence ne se voit simplement plus.

Les deux survivants — le volet hôte et la sonde TLS — sont donc versionnés dans infra/dod/, avec le script de nettoyage qui les accompagne, et exposés en cibles Castor. Ce n'est pas une promotion cosmétique : c'est ce qui les fait exister ailleurs que dans le dossier de travail d'un poste.

Le KO explicite plutôt que le message opaque

infra/dod/check.sh référence toujours prod-smoke.sh, qui n'existe plus. Deux traitements étaient possibles, et le choix est délibéré : la case 30 rend un KO qui nomme la cause — « prod-smoke.sh a été PERDU avec var/claude — la case 30 n'est plus rejouable » — au lieu d'un « script attendu introuvable » qu'on prendrait pour un défaut d'installation, qu'on chercherait à réparer, et dont on conclurait au bout d'une heure qu'il faut réécrire le script.

Une dette qui se présente comme une panne coûte le temps qu'on passe à la diagnostiquer. Une dette qui se nomme se replanifie.

Pourquoi infra/dod/ et pas tests/

C'est la question qui vient immédiatement : ce sont des vérifications, tests/ existe, l'affaire semble entendue. Elle ne l'est pas, et pour une raison qui tient en une phrase : ces sondes ne tourneront jamais en intégration continue.

Trois obstacles, dont aucun n'est contournable par de l'effort :

  • pas de Docker-in-Docker dans les runners du projet — or les sondes pilotent le démon Docker de l'hôte ;
  • pas de worktrees en CI, qui travaille sur un checkout unique et jetable ;
  • elles détruisent des stacks, ce qui n'a pas sa place dans une pipeline partagée.

Les ranger sous tests/ aurait laissé croire l'inverse. C'est le genre de mauvais signal qui se paie deux fois : une première quand quelqu'un les ajoute à une suite et fait rougir la CI, une seconde quand on les en retire en concluant qu'elles sont « fragiles ». infra/ dit ce qu'elles sont : de l'outillage d'infrastructure, lancé à la main depuis un terminal hôte, à un moment choisi.

La contrepartie est assumée et nommée : une sonde hors CI est une sonde que rien n'oblige à rester verte. C'est précisément pourquoi ses gardes, elles, sont testées.

Le versionnement rend l'outillage testable

C'est le gain le moins visible et probablement le plus important. Tant que ces scripts vivaient sous var/, plus de deux mille lignes de Bash n'avaient aucune couverture — y compris les parties qui suppriment des choses.

Versionnés, ils deviennent adressables par une suite de tests. tests/Bash/dod/ en compte 59 cas, qui ne portent ni sur Docker ni sur les worktrees — rien de tout cela n'est exécutable dans un conteneur de test — mais sur les gardes qui décident avant toute action, et sur les fonctions pures de infra/dod/lib.sh. La façade PHP (castor/dod.php) est couverte séparément par tests/Unit/Castor/Dod/DodTasksTest.php.

Ce déplacement du périmètre de test n'est pas un repli : c'est là que se trouve le risque. castor dod:clean détruit sans demander ; castor dod:check compose des chemins de rm -rf à partir de --wt-a et --wt-b. Une garde de portée qui accepterait dod-a/../.. rendrait le répertoire parent du dépôt, avec le dépôt principal et tous les worktrees dedans. Vérifier qu'un nom de worktree est bien un nom et pas un chemin vaut, ici, beaucoup plus cher que de vérifier qu'une sonde sait compter des conteneurs.

Deux précautions du harnais méritent d'être connues, parce qu'elles découlent du même raisonnement : check.sh n'est jamais invoqué avec un PATH complet — il est réduit à bash, dirname, git et sed, si bien qu'aucun test ne peut atteindre docker ni castor wt:up, même par accident. Et les sources sont résolues depuis $BATS_TEST_DIRNAME, jamais /app/… : en CI, /app est une copie figée de l'image de dev, dépourvue des fichiers neufs de la branche.

Ce qui reste sous var/

Rien de tout cela ne revient sur l'arbitrage rendu pour var/claude lui-même : les specs de lots, les scripts de ship et les rapports restent hors du dépôt, parce que ce sont des artefacts liés à un ticket, périmés à sa clôture (cf. Pourquoi l'agent pousse lui-même, et ce qui le retient).

La ligne de partage n'est pas « artefact d'agent » contre « code du produit », elle est ailleurs : ce qui atteste d'un run reste sous var/, ce qui permet de refaire le run est versionné. Les deux moitiés se croisent dans le même lot — les sondes montent dans infra/dod/, et leur journal descend explicitement dans var/dod/check-<horodatage>.log. Déposer ce journal à côté du script aurait laissé à chaque run un fichier non suivi dans l'arbre de travail, porteur de chemins de $HOME, de noms de conteneurs et de l'inventaire des worktrees — soit exactement l'accident que ce déplacement supprime, réintroduit en sens inverse.

Voir aussi