Merge pull request 'chore: <résumé clair de la modif>' (#189) from chore/xxx-20260303-221031 into main

Reviewed-on: #189

.gitea/workflows/deploy-staging-live.yml

@@ -47,48 +47,53 @@ jobs:
 
           node --input-type=module <<'NODE'
           import fs from "node:fs";
+
           const ev = JSON.parse(fs.readFileSync(process.env.EVENT_JSON, "utf8"));
           const repoObj = ev?.repository || {};
+
           const cloneUrl =
             repoObj?.clone_url ||
             (repoObj?.html_url ? (repoObj.html_url.replace(/\/$/,"") + ".git") : "");
           if (!cloneUrl) throw new Error("No repository clone_url/html_url in event.json");
 
           const defaultBranch = repoObj?.default_branch || "main";
-          const sha =
+
+          // Push-range (most reliable for change detection)
+          const before = String(ev?.before || "").trim();
+          const after =
             (process.env.GITHUB_SHA && String(process.env.GITHUB_SHA).trim()) ||
-            ev?.after ||
-            ev?.sha ||
-            ev?.head_commit?.id ||
-            ev?.pull_request?.head?.sha ||
-            "";
+            String(ev?.after || ev?.sha || ev?.head_commit?.id || ev?.pull_request?.head?.sha || "").trim();
 
           const shq = (s) => "'" + String(s).replace(/'/g, "'\\''") + "'";
+
           fs.writeFileSync("/tmp/deploy.env", [
             `REPO_URL=${shq(cloneUrl)}`,
             `DEFAULT_BRANCH=${shq(defaultBranch)}`,
-            `SHA=${shq(sha)}`
+            `BEFORE=${shq(before)}`,
+            `AFTER=${shq(after)}`
           ].join("\n") + "\n");
           NODE
 
           source /tmp/deploy.env
           echo "Repo URL:       $REPO_URL"
           echo "Default branch: $DEFAULT_BRANCH"
-          echo "SHA:            ${SHA:-<empty>}"
+          echo "BEFORE:         ${BEFORE:-<empty>}"
+          echo "AFTER:          ${AFTER:-<empty>}"
 
           rm -rf .git
           git init -q
           git remote add origin "$REPO_URL"
 
-          if [[ -n "${SHA:-}" ]]; then
-            git fetch --depth 1 origin "$SHA"
+          # Checkout AFTER (or default branch if missing)
+          if [[ -n "${AFTER:-}" ]]; then
+            git fetch --depth 50 origin "$AFTER"
             git -c advice.detachedHead=false checkout -q FETCH_HEAD
           else
-            git fetch --depth 1 origin "$DEFAULT_BRANCH"
+            git fetch --depth 50 origin "$DEFAULT_BRANCH"
             git -c advice.detachedHead=false checkout -q "origin/$DEFAULT_BRANCH"
-            SHA="$(git rev-parse HEAD)"
-            echo "SHA='$SHA'" >> /tmp/deploy.env
-            echo "Resolved SHA: $SHA"
+            AFTER="$(git rev-parse HEAD)"
+            echo "AFTER='$AFTER'" >> /tmp/deploy.env
+            echo "Resolved AFTER: $AFTER"
           fi
 
           git log -1 --oneline
@@ -96,61 +101,97 @@ jobs:
       - name: Gate — decide SKIP vs HOTPATCH vs FULL rebuild
         env:
           INPUT_FORCE: ${{ inputs.force }}
+          EVENT_JSON: /var/run/act/workflow/event.json
         run: |
           set -euo pipefail
           source /tmp/deploy.env
 
           FORCE="${INPUT_FORCE:-0}"
 
-          # liste fichiers touchés (utile pour copier les médias)
-          CHANGED="$(git show --name-only --pretty="" "$SHA" | sed '/^$/d' || true)"
-          printf "%s\n" "$CHANGED" > /tmp/changed.txt
+          # Lire before/after du push depuis event.json (merge-proof)
+          node --input-type=module <<'NODE'
+          import fs from "node:fs";
+          const ev = JSON.parse(fs.readFileSync(process.env.EVENT_JSON, "utf8"));
+          const before = ev?.before || "";
+          const after  = ev?.after  || ev?.sha || "";
+          const shq = (s) => "'" + String(s).replace(/'/g, "'\\''") + "'";
+          fs.writeFileSync("/tmp/gate.env", [
+            `EV_BEFORE=${shq(before)}`,
+            `EV_AFTER=${shq(after)}`
+          ].join("\n") + "\n");
+          NODE
 
-          echo "== changed files =="
-          echo "$CHANGED" | sed -n '1,260p'
+          source /tmp/gate.env
 
-          # 0) Forçage manuel
-          if [[ "$FORCE" == "1" ]]; then
-            echo "GO=1" >> /tmp/deploy.env
-            echo "MODE='full'" >> /tmp/deploy.env
-            echo "✅ force=1 -> MODE=full (rebuild+restart)"
-            exit 0
+          BEFORE="${EV_BEFORE:-}"
+          AFTER="${EV_AFTER:-}"
+          if [[ -z "${AFTER:-}" ]]; then
+            AFTER="${SHA:-}"
           fi
 
-          # 1) Détection des classes de changements
+          echo "Gate ctx: BEFORE=${BEFORE:-<empty>} AFTER=${AFTER:-<empty>} FORCE=${FORCE}"
+
+          # Produire une liste CHANGED fiable :
+          # - si BEFORE/AFTER valides -> git diff before..after
+          # - sinon fallback -> diff parent1..after ou show after
+          CHANGED=""
+          Z40="0000000000000000000000000000000000000000"
+
+          if [[ -n "${BEFORE:-}" && "${BEFORE}" != "${Z40}" ]] \
+             && git cat-file -e "${BEFORE}^{commit}" 2>/dev/null \
+             && git cat-file -e "${AFTER}^{commit}"  2>/dev/null; then
+            CHANGED="$(git diff --name-only "${BEFORE}" "${AFTER}" || true)"
+          else
+            P1="$(git rev-parse "${AFTER}^" 2>/dev/null || true)"
+            if [[ -n "${P1:-}" ]] && git cat-file -e "${P1}^{commit}" 2>/dev/null; then
+              CHANGED="$(git diff --name-only "${P1}" "${AFTER}" || true)"
+            else
+              CHANGED="$(git show --name-only --pretty="" "${AFTER}" | sed '/^$/d' || true)"
+            fi
+          fi
+
+          printf "%s\n" "${CHANGED}" > /tmp/changed.txt
+
+          echo "== changed files (first 200) =="
+          sed -n '1,200p' /tmp/changed.txt || true
+
+          # Flags
           HAS_FULL=0
           HAS_HOTPATCH=0
 
-          # FULL si build-impacting (zéro surprise)
-          if echo "$CHANGED" | grep -qE '^(src/content/|src/anchors/|src/pages/|scripts/)'; then
+          # FULL si build-impacting (ce que tu veux : content/anchors/pages/scripts)
+          if grep -qE '^(src/content/|src/anchors/|src/pages/|scripts/)' /tmp/changed.txt; then
             HAS_FULL=1
           fi
 
-          # HOTPATCH si annotations/media
-          if echo "$CHANGED" | grep -qE '^(src/annotations/|public/media/)'; then
+          # HOTPATCH si annotations/media touchés
+          if grep -qE '^(src/annotations/|public/media/)' /tmp/changed.txt; then
             HAS_HOTPATCH=1
           fi
 
-          echo "Gate flags: HAS_FULL=$HAS_FULL HAS_HOTPATCH=$HAS_HOTPATCH"
+          echo "Gate flags: HAS_FULL=${HAS_FULL} HAS_HOTPATCH=${HAS_HOTPATCH}"
 
-          # 2) Décision (priorité au FULL)
-          if [[ "$HAS_FULL" == "1" ]]; then
-            echo "GO=1" >> /tmp/deploy.env
-            echo "MODE='full'" >> /tmp/deploy.env
+          # Décision
+          if [[ "${FORCE}" == "1" ]]; then
+            GO=1
+            MODE="full"
+            echo "✅ force=1 -> MODE=full (rebuild+restart)"
+          elif [[ "${HAS_FULL}" == "1" ]]; then
+            GO=1
+            MODE="full"
             echo "✅ build-impacting change -> MODE=full (rebuild+restart)"
-            exit 0
-          fi
-
-          if [[ "$HAS_HOTPATCH" == "1" ]]; then
-            echo "GO=1" >> /tmp/deploy.env
-            echo "MODE='hotpatch'" >> /tmp/deploy.env
+          elif [[ "${HAS_HOTPATCH}" == "1" ]]; then
+            GO=1
+            MODE="hotpatch"
             echo "✅ annotations/media change -> MODE=hotpatch"
-            exit 0
+          else
+            GO=0
+            MODE="skip"
+            echo "ℹ️ no relevant change -> skip deploy"
           fi
 
-          echo "GO=0" >> /tmp/deploy.env
-          echo "MODE='skip'" >> /tmp/deploy.env
-          echo "ℹ️ no deploy-relevant change -> skip deploy"
+          echo "GO=${GO}" >> /tmp/deploy.env
+          echo "MODE='${MODE}'" >> /tmp/deploy.env
 
       - name: Toolchain sanity + resolve COMPOSE_PROJECT_NAME
         run: |

docs/OPS-DEPLOYMENT.md

@@ -25,6 +25,19 @@ Objectif : déployer une nouvelle version du site sur le NAS (DS220+) sans jamai
 
 ➡️ Déploiement = `docs/DEPLOY_PROD_SYNOLOGY_DS220.md` (procédure détaillée, à jour).
 
+## Mise à jour (2026-03-03) — Gate CI de déploiement (SKIP / HOTPATCH / FULL) + preuves A/B
+
+La procédure de déploiement “vivante” est désormais pilotée par **Gitea Actions** via le workflow :
+- `.gitea/workflows/deploy-staging-live.yml`
+
+Ce workflow décide automatiquement :
+- **FULL** (rebuild + restart blue + green) dès qu’un changement impacte le build (ex: `src/content/`, `src/pages/`, `scripts/`, `src/anchors/`, etc.)
+- **HOTPATCH** (patch JSON + copie media) quand le changement ne concerne que `src/annotations/` et/ou `public/media/`
+- **SKIP** sinon
+
+Les preuves et la procédure de test reproductible A/B sont documentées dans :
+➡️ `docs/runbooks/DEPLOY-BLUE-GREEN.md` → section “CI Deploy gate (merge-proof) + Tests A/B + preuve alias injection”.
+
 ## Schéma (résumé, sans commandes)
 
 - Ne jamais toucher au slot live.

docs/OPS_COCKPIT.md

@@ -202,4 +202,33 @@ docker compose logs --tail=200 web_blue
 docker compose logs --tail=200 web_green
 
 # Si tu veux suivre en live :
-docker compose logs -f web_green
+docker compose logs -f web_green
+
+
+## Historique synthétique (2026-03-03) — Stabilisation CI/CD “zéro surprise”
+
+### Problème initial observé
+- Déploiement parfois lancé en “hotpatch” alors qu’un rebuild était nécessaire.
+- Sur merge commits, la détection de fichiers modifiés pouvait être ambiguë.
+- Résultat : besoin de `force=1` manuel pour éviter des incohérences.
+
+### Correctif appliqué
+- Gate CI rendu **merge-proof** :
+  - lecture de `BEFORE` et `AFTER` depuis `event.json`
+  - calcul des fichiers modifiés via `git diff --name-only BEFORE AFTER`
+
+- Politique de décision stabilisée :
+  - FULL auto dès qu’un changement impacte build/runtime (content/pages/scripts/anchors/etc.)
+  - HOTPATCH auto uniquement pour annotations/media
+
+### Preuves
+- Test A (touch src/content) :
+  - Gate flags: HAS_FULL=1 HAS_HOTPATCH=0 → MODE=full
+- Test B (touch src/annotations) :
+  - Gate flags: HAS_FULL=0 HAS_HOTPATCH=1 → MODE=hotpatch
+
+### Audit post-déploiement (preuves côté NAS)
+- 8081 + 8082 répondent HTTP 200
+- `/para-index.json` + `/annotations-index.json` OK
+- Aliases injectés visibles dans HTML via `.para-alias` quand alias présent
+

docs/runbooks/DEPLOY-BLUE-GREEN.md

@@ -199,4 +199,125 @@ Ne jamais modifier dist/ “à la main” sur NAS.
 
 Si un hotfix prod est indispensable : documenter et backporter via PR Gitea.
 
-Le canonical dépend du build : PUBLIC_SITE doit être injecté (voir runbook ENV-PUBLIC_SITE).
+Le canonical dépend du build : PUBLIC_SITE doit être injecté (voir runbook ENV-PUBLIC_SITE).
+
+## 10) CI Deploy (Gitea Actions) — Gate SKIP / HOTPATCH / FULL (merge-proof) + preuves
+
+Cette section documente le comportement **canonique** du workflow :
+- `.gitea/workflows/deploy-staging-live.yml`
+
+Objectif : **zéro surprise**.
+On ne veut plus “penser à force=1”.
+Le gate doit décider automatiquement, y compris sur des **merge commits**.
+
+### 10.1 — Principe (ce que fait réellement le gate)
+
+Le job `deploy` calcule les fichiers modifiés entre :
+- `BEFORE` = commit précédent (avant le push sur main)
+- `AFTER`  = commit actuel (après le push / merge sur main)
+
+Puis il classe le déploiement dans un mode :
+
+- **MODE=full**
+  - rebuild image + restart `archicratie-web-blue` (8081) + `archicratie-web-green` (8082)
+  - warmup endpoints (para-index, annotations-index, pagefind.js)
+  - vérification canonical staging + live
+
+- **MODE=hotpatch**
+  - rebuild d’un `annotations-index.json` consolidé depuis `src/annotations/**`
+  - patch direct dans les conteneurs en cours d’exécution (blue+green)
+  - copie des médias modifiés `public/media/**` vers `/usr/share/nginx/html/media/**`
+  - smoke sur `/annotations-index.json` des deux ports
+
+- **MODE=skip**
+  - pas de déploiement (on évite le bruit)
+
+⚠️ Important : le mode “hotpatch” **ne rebuild pas** Astro.
+Donc toute modification de contenu, routes, scripts, anchors, etc. doit déclencher **full**.
+
+### 10.2 — Matrice de décision (règles officielles)
+
+Le gate définit deux flags :
+- `HAS_FULL=1` si changement “build-impacting”
+- `HAS_HOTPATCH=1` si changement “annotations/media only”
+
+Règle de priorité :
+1) Si `HAS_FULL=1` → **MODE=full**
+2) Sinon si `HAS_HOTPATCH=1` → **MODE=hotpatch**
+3) Sinon → **MODE=skip**
+
+#### 10.2.1 — Changements qui déclenchent FULL (build-impacting)
+
+Exemples typiques (non exhaustif, mais on couvre le cœur) :
+- `src/content/**` (contenu MD/MDX)
+- `src/pages/**` (routes Astro)
+- `src/anchors/**` (aliases d’ancres)
+- `scripts/**` (tooling postbuild : injection, index, tests)
+- `src/layouts/**`, `src/components/**`, `src/styles/**` (rendu et scripts inline)
+- `astro.config.mjs`, `package.json`, `package-lock.json`
+- `Dockerfile`, `docker-compose.yml`, `nginx.conf`
+- `.gitea/workflows/**` (changement infra CI/CD)
+
+=> On veut **full** pour garantir cohérence et éviter “site partiellement mis à jour”.
+
+#### 10.2.2 — Changements qui déclenchent HOTPATCH (sans rebuild)
+
+Uniquement :
+- `src/annotations/**` (shards YAML)
+- `public/media/**` (assets média)
+
+=> On veut hotpatch pour vitesse et éviter rebuild NAS.
+
+### 10.3 — “Merge-proof” : pourquoi on ne lit PAS seulement `git show $SHA`
+
+Sur un merge commit, `git show --name-only $SHA` peut être trompeur selon le contexte.
+La méthode robuste est :
+- utiliser `event.json` (Gitea Actions) pour récupérer `before` et `after`
+- calculer `git diff --name-only BEFORE AFTER`
+
+C’est ce qui rend le gate **merge-proof**.
+
+### 10.4 — Tests de preuve A/B (reproductibles)
+
+Ces tests valident le gate sans ambiguïté.
+But : vérifier que le mode choisi est EXACTEMENT celui attendu.
+
+#### Test A — toucher `src/content/...` (FULL auto)
+
+1) Créer une branche test
+2) Modifier 1 fichier dans `src/content/` (ex : ajouter une ligne de commentaire non destructive)
+3) PR → merge dans `main`
+4) Vérifier dans `deploy-staging-live.yml` :
+
+Attendus :
+- `Gate flags: HAS_FULL=1 HAS_HOTPATCH=0`
+- `✅ build-impacting change -> MODE=full (rebuild+restart)`
+- Les étapes FULL (blue puis green) s’exécutent réellement
+
+#### Test B — toucher `src/annotations/...` uniquement (HOTPATCH auto)
+
+1) Créer une branche test
+2) Modifier 1 fichier sous `src/annotations/**` (ex: un champ comment, ts, etc.)
+3) PR → merge dans `main`
+4) Vérifier dans `deploy-staging-live.yml` :
+
+Attendus :
+- `Gate flags: HAS_FULL=0 HAS_HOTPATCH=1`
+- `✅ annotations/media change -> MODE=hotpatch`
+- Les étapes FULL sont “skip” (durée 0s)
+- L’étape HOTPATCH s’exécute réellement
+
+### 10.5 — Preuve opérationnelle côté NAS (2 URLs + 2 commandes)
+
+But : prouver que staging+live servent bien les endpoints essentiels (et que le déploiement n’a pas “fait semblant”).
+
+#### 10.5.1 — Deux URLs à vérifier (staging et live)
+
+- Staging (blue) : `http://127.0.0.1:8081/`
+- Live (green)  : `http://127.0.0.1:8082/`
+
+#### 10.5.2 — Deux commandes minimales (zéro débat)
+
+```bash
+curl -fsSI http://127.0.0.1:8081/ | head -n 1
+curl -fsSI http://127.0.0.1:8082/ | head -n 1

src/annotations/archicrat-ia/chapitre-3/p-1-60c7ea48.yml

@@ -7,5 +7,4 @@ paras:
         label: Gitea
         kind: (livre / article / vidéo / site / autre) Site
         ts: 2026-03-02T20:01:55.858Z
-        fromIssue: 172
-# testB: hotpatch-auto gate proof
+        fromIssue: 172#

src/content/archicrat-ia/chapitre-3.mdx

@@ -11,8 +11,6 @@ summary: ""
 source:
   kind: docx
   path: "sources/docx/archicrat-ia/Chapitre_3—Philosophies_du_pouvoir_et_Archicration-pour_une_topologie_differenciee_des_regimes_regulateurs-version_officielle.docx"
-
-<!-- testA: full-auto gate proof -->
 ---
 Ce chapitre se tient à un point nodal de notre essai-thèse : il ouvre un espace d’exploration systématique des formes conceptuelles et philosophiques à travers lesquelles le pouvoir se configure comme régime de régulation. Il ne s’agit pas ici de revenir une nouvelle fois sur les fondements de l’autorité, ni d’interroger la légitimité politique au sens classique du terme, ni même d’enquêter sur la genèse des institutions. L’ambition est autre, structurelle, transversale, morphologique, elle tentera d’arpenter, à même les dispositifs, les pensées, les théorisations et les expériences, les modalités différentiées par lesquelles s’instaurent, s’éprouvent et se disputent les formes de régulation du vivre-ensemble.