[P2] Sortir les décisions durables du code vers des ADR

[stephrobert]

Contexte

Plusieurs modules portent un raisonnement d'architecture dans leurs commentaires,
et c'est très supérieur à du code opaque : locking.py explique pourquoi
flock plutôt qu'un fichier sentinelle et pourquoi le fichier n'est jamais
supprimé ; pyproject.toml explique pourquoi ansible-core est déclaré
explicitement ; templates/cloud-init/README.md explique pourquoi les paquets du
premier boot ne bloquent pas.

Le problème n'est pas leur présence, c'est leur place : ce sont des décisions
d'architecture, pas des explications de ligne. Elles rendent les fichiers longs,
et surtout elles ne se retrouvent pas quand on cherche « pourquoi ce choix ».

Décisions candidates, déjà écrites quelque part

Décision	Où elle vit aujourd'hui
deux runtimes (shell, vm), les providers sont dessous	CLAUDE.md, commentaires
verrou par dépôt en flock, fichier jamais supprimé	locking.py
ansible-core déclaré explicitement malgré ses 100 Mo	pyproject.toml
images amont mutables assumées	templates/terraform/README.md
paquets du premier boot non bloquants	templates/cloud-init/README.md
le journal en anglais, l'interface traduite	test_journal_en_anglais.py
--json est un contrat, distinct de schema_version	docs/machine-output.*
jeu de règles Ruff explicite plutôt qu'implicite	pyproject.toml

Critères d'acceptation

• docs/decisions/ accueille une ADR par décision, au format court :
  contexte, décision, conséquences, ce qui l'inverserait.
• Le code renvoie à l'ADR (# Voir ADR-0002) au lieu de porter le
  raisonnement complet — la trace reste, le fichier respire.
• Le raisonnement n'est pas résumé en le déplaçant : ces textes valent
  par leur précision, et plusieurs citent des mesures qu'on ne retrouvera
  pas.
• Les décisions prises depuis (le renversement des fixtures, l'état dégradé
  d'un lab sans moteur) rejoignent le répertoire, sans quoi il naîtra déjà
  incomplet.

Lié à #200 : les invariants disent ce qui est vrai, les ADR disent pourquoi
on a choisi ça. Les deux se renvoient l'un à l'autre.

---

Relevé en confrontant au code une analyse externe du dépôt, le 2026-08-24.