docs: track design docs, plans, audits, coordination infrastructure, handoffs

- 21 docs/*.md: audits, design notes, deployment plans, checklists, memos
- Coordination: ROLES, runbooks (DGX reboot, Lea live), patches, registre, syntheses, systemd, QG template
- Handoffs: 6 Codex handoff documents + README + template

docs/DESIGN_OVMF_AUTOREPAIR_VM_2026-06-20.md

@@ -0,0 +1,59 @@
+# Design — Auto-réparation OVMF de la VM Léa (gap G2, reprise non-assistée)
+
+- `Auteur`: Claude (infra)
+- `Date`: 2026-06-20 ~03:15 CEST
+- `Statut`: **PROPOSITION / design read-only** — à appliquer après revue Dom (garde-fou : aucun changement service prod sans Dom).
+- `Référence`: post-mortem `docs/POSTMORTEM_PANNE_SECTEUR_DGX_2026-06-20.md` (gap G2).
+
+## 1. Problème
+
+Une coupure brutale corrompt `OVMF_VARS.fd` (NVRAM UEFI) → la VM boucle dans TianoCore/Windows Boot Manager. Le 2026-06-20, blocage 02:07→02:18 jusqu'à intervention manuelle de Codex (restore OVMF connu-bon + TPM frais). En clinique sans technicien, ce blocage serait **permanent**.
+
+## 2. Pourquoi le service ne s'auto-répare pas aujourd'hui
+
+`~/.config/systemd/user/win11-arm-lea.service` :
+- `Restart=on-failure` — **inopérant** : en boucle TianoCore, QEMU **ne sort pas** (process « running » à 99 % CPU). Aucun échec → aucun restart.
+- `ExecStartPre` efface `tpm2-00.permall` (TPM frais à chaque boot) **mais pas `OVMF_VARS.fd`** → un OVMF corrompu **survit aux restarts** → boucle permanente.
+
+## 3. Détecteur fiable
+
+Le **guest agent QEMU** (`windows-11-arm-lea-agent.sock`) ne répond **que** si Windows a réellement booté. En boucle firmware, il ne répond jamais. Signature d'échec = *pas de réponse guest-agent après N min* **+** *CPU QEMU élevé*. (Plus robuste qu'une analyse framebuffer ; v1 suffisante.)
+
+## 4. Design proposé (2 briques + garde-fous)
+
+### Brique A — Snapshot « known-good » après boot sain
+Watchdog compagnon (lancé en `ExecStartPost=... &` ou service apparié `vm-health-watchdog.service`) :
+1. Fenêtre de boot (0→~6 min), poll guest-agent toutes les 30 s (`guest-ping` via socket agent).
+2. **Guest-agent répond** → boot sain : copie atomique `OVMF_VARS.fd` → `OVMF_VARS.fd.known-good`, écrit sentinel `boot-ok`, log horodaté. C'est le point de restauration.
+
+### Brique B — Détection boucle + restauration auto
+Si à T+6 min le guest-agent **ne répond toujours pas** ET CPU QEMU > 80 % (signature boucle) :
+1. Écrit sentinel `boot-failed`.
+2. Archive l'OVMF suspect : `OVMF_VARS.fd` → `OVMF_VARS.fd.failed-<ts>` (convention déjà utilisée par Codex).
+3. Restaure `OVMF_VARS.fd.known-good` → `OVMF_VARS.fd`.
+4. Arrête le QEMU en boucle firmware. **Sûr** : aucun OS n'a booté (guest-agent jamais monté) → pas de risque de corruption Windows (≠ règle « jamais kill un Windows booté », qui ne s'applique pas ici).
+5. systemd relance (`Restart=on-failure` se déclenche enfin) avec le bon OVMF.
+
+### Garde-fous (anti-mauvais comportement)
+- **Pas de known-good** (1er boot, jamais eu de boot sain) → ne PAS restaurer ; log + alerte, comportement actuel conservé.
+- **Compteur d'essais** : max 2 auto-restaurations consécutives (sentinel compteur). Au-delà → stop + alerte (évite la boucle restore→échec→restore si le known-good est lui aussi mauvais).
+- **Faux positifs** : Windows peut booter lentement → fenêtre 6–8 min + double critère (guest-agent ET CPU). Réglable.
+- **TPM** : on garde l'effacement `tpm2-00.permall` existant (évite le hang TPM) ; l'auto-réparation OVMF est complémentaire.
+- **Idempotence** : nettoyage des sentinels en début de cycle.
+
+## 5. Points d'intégration (à valider Dom avant écriture)
+
+- `win11-arm-lea.service` : ajouter `ExecStartPre` de garde (si `boot-failed` + known-good → restaurer avant lancement) et `ExecStartPost` qui lance le watchdog.
+- Nouveau script `vm-health-watchdog.sh` (briques A+B) dans `~/quickemu-win11-arm-lea/`.
+- Optionnel : `vm-health-watchdog.service` (PartOf=win11-arm-lea.service) plutôt qu'un `&`, pour un cycle de vie propre.
+
+## 6. Plan de test (sans risque, sur la VM labo)
+
+1. Boot sain → vérifier création `OVMF_VARS.fd.known-good` + sentinel `boot-ok`.
+2. Simuler corruption (copier l'`OVMF_VARS.fd.failed-powercut-20260620-021854` archivé sur le live) → vérifier détection à T+6 min, archivage, restauration, restart, boot sain.
+3. Vérifier le compteur d'essais (corrompre aussi le known-good) → stop + alerte, pas de boucle infinie.
+4. Mesurer le temps total de reprise auto (cible < 10 min sans intervention).
+
+## 7. Décision attendue (Dom)
+
+GO/NO-GO sur l'écriture + le réglage de la fenêtre (6 vs 8 min) et du mécanisme d'alerte (log seul ? message coordination ? mail ?). Application supervisée, un changement / un test, après ton réveil.