docs: add roadmap for CI + anchor aliases

docs/ROADMAP.md

@@ -0,0 +1,157 @@
+# ROADMAP — CI (Gitea Actions Synology) + Ancrages (aliases build-time)
+
+But : permettre à un successeur de reprendre sans rien deviner.
+Ce document décrit :
+- l’état stable actuel (baseline)
+- les invariants à ne pas casser
+- les prochaines étapes “mission principale” (ancrages primaires robustes + CI durable)
+- la méthode de debug rapide
+
+---
+
+## 0) État actuel (baseline VALIDÉE)
+
+### CI (Gitea Actions)
+- ✅ Job dans un container Node 22 (conforme `engines`)
+- ✅ Checkout **sans actions GitHub**, depuis `workflow/event.json`
+- ✅ Zéro `apt-get` dans le workflow
+- ✅ `npm ci` + build + tests anchors + validation schema aliases
+- ✅ Injection d’aliases au postbuild confirmée en logs
+
+### Runner (DS220+)
+- ✅ `container.network: host` dans `/data/config.yaml` du runner
+- ✅ `NODE_OPTIONS=--dns-result-order=ipv4first` passé aux containers de job
+- ✅ `--add-host=gitea.archicratie.trans-hands.synology.me:192.168.1.20`
+
+Raison : le DNS du bridge Docker (127.0.0.11) est instable sur cette infra → EAI_AGAIN / ESERVFAIL (npm, debian).
+
+Référence : `docs/CI-BASELINE.md` + `docs/CI-WORKFLOW.md` + `docs/HANDOFF-SESSION.md`.
+
+---
+
+## 1) Invariants (NE PAS “optimiser”)
+
+Ces points sont des garde-fous. Si on les retire, on revient aux mêmes pannes.
+
+1) Runner :
+- garder `container.network: host` (tant que l’infra DNS bridge n’est pas corrigée)
+- garder `-e NODE_OPTIONS=--dns-result-order=ipv4first`
+
+2) Workflow :
+- ne pas réintroduire `apt-get`
+- ne pas dépendre de `actions/checkout@...`
+- garder un container Node 22 tant que `package.json engines` impose `>=22 <23`
+
+3) Ancrages :
+- le fichier canonique : `src/anchors/anchor-aliases.json`
+- injection build-time : `scripts/inject-anchor-aliases.mjs`
+- test anchors : `scripts/check-anchors.mjs`
+- validation schema aliases : `scripts/check-anchor-aliases.mjs`
+
+---
+
+## 2) Mission principale (raccrochage)
+
+Objectif “métier” :
+- préserver les liens profonds (ancrages) malgré l’édition (déplacements, insertions, corrections)
+- éviter les résolutions “par index” (fragiles)
+- rendre la migration d’ancrages **déterministe, versionnée, testée**
+
+Traduction technique :
+- quand un `newId` remplace un `oldId`, on versionne `oldId -> newId` **par page**
+- au build, on injecte un alias DOM invisible portant l’ancien `id` avant l’élément ciblé
+
+---
+
+## 3) Prochains jalons (ordre recommandé)
+
+### Jalons A — Verrouillage qualité (court terme, “béton”)
+A1) CI : prouver l’injection (pas seulement “build ok”)
+- ajouter un test qui parcourt `src/anchors/anchor-aliases.json` et vérifie dans `dist/<route>/index.html` :
+  - présence de `<span id="oldId" ...>`
+  - présence de l’élément `id="newId"`
+  - et idéalement : alias placé “juste avant” la cible (proximité)
+
+A2) CI : interdire les IDs en double (risque SEO/DOM)
+- dans les pages `dist`, détecter les doublons d’attribut `id="..."`
+
+A3) CI : artefacts / logs actionnables
+- quand un test échoue : afficher `route`, `oldId`, `newId`, extrait HTML et ligne
+
+### Jalons B — Ergonomie éditeur (moyen terme)
+B1) `apply-ticket.mjs` : renforcer le mode `--alias`
+- si un paragraphe est remplacé : écrire l’alias automatiquement
+- si conflit : message clair “oldId déjà mappé / newId introuvable”
+
+B2) `check-anchors.mjs` : suggestion d’aliases
+- lorsqu’il détecte “removed X / added Y” avec même préfixe `p-8-...`
+- générer une proposition, option `--write-aliases` (ou sortie patch)
+
+### Jalons C — Robustesse long terme (ops)
+C1) Runner : réduire le risque “host network”
+- isoler le runner sur LAN (réseau dédié/pare-feu)
+- limiter les labels/queues aux repos nécessaires
+- documenter comment restaurer `/data/config.yaml`
+
+C2) Versionner les décisions
+- tout changement CI/runner : documenté dans `docs/` + commit (pas de “magic fix” non tracé)
+
+---
+
+## 4) Procédure standard (dev -> PR -> merge)
+
+### Ajouter/modifier du contenu
+1) modifier les sources (docx/import etc.)
+2) si des IDs de paragraphes changent :
+   - appliquer `scripts/apply-ticket.mjs --alias` si possible
+   - sinon éditer `src/anchors/anchor-aliases.json` (par route)
+
+### Vérifier en local
+- `npm test`
+- ou au minimum :
+  - `npm run build`
+  - vérifier injection : `grep -n "para-alias" dist/<route>/index.html`
+
+### PR & merge
+- une PR = un ticket logique
+- CI doit passer
+- merge seulement quand anchors + aliases sont cohérents
+
+---
+
+## 5) Debug express (quand ça casse)
+
+### CI échoue “DNS / npm”
+Symptômes typiques :
+- `EAI_AGAIN`, `ESERVFAIL`, `Temporary failure resolving`
+Actions :
+1) vérifier runner config : `/data/config.yaml` contient bien `network: host`
+2) vérifier job container : logs montrent `network="host"`
+3) smoke test NAS :
+   - `docker run --rm --network host mcr.microsoft.com/devcontainers/javascript-node:22-bookworm bash -lc "npm ping --registry=https://registry.npmjs.org"`
+
+### CI échoue “EBADENGINE”
+- Node pas 22 → corriger l’image du job (Node 22)
+
+### CI échoue “MODULE_NOT_FOUND scripts/...”
+- fichier non commité
+- `git status --porcelain` puis `git add/commit/push`
+
+### Injection d’alias absente
+- vérifier que `postbuild` appelle bien `inject-anchor-aliases.mjs`
+- vérifier que `src/anchors/anchor-aliases.json` respecte le schéma (par route)
+
+---
+
+## 6) Définition de “DONE” (quand on peut dire “mission accomplie”)
+
+1) CI stable sur 30+ runs consécutifs (push + PR + merge)
+2) Toute modification de paragraphes qui casse des anchors produit :
+   - soit un alias automatique via tooling
+   - soit un échec CI explicite (avec patch proposé)
+3) Aliases injectés testés (preuve dans dist) + pas de doublons d’IDs
+4) Documentation à jour (baseline + décisions + procédures)
+
+---
+
+Fin.