Jah Messenger : un cahier des charges, un swarm d'agents, dix vagues

TL;DR

Le 30 septembre, FG a posé quatorze demandes (urgences, prototypes, idées à garder) et une question : comment les faire exécuter en parallèle par plusieurs agents, livrer vite, et déployer sans couper la partie ?

La réponse est dans la pull request #88 (fusionnée) : 22 fiches de lot, un tableau urgence / priorité / importance / temps / ordre, dix vagues d'intégration, un cahier des charges (le bloc à copier en tête) et neuf mini-prompts numérotés pour que chaque agent n'ait à lire que sa parcelle — donc zéro collision. L'orchestration est lancée : 10 jalons et 22 tickets GitHub existent (#89 à #110), un par lot.

Le principe : du plus rapide au plus lent, une vague après l'autre, et à chaque lot : handoff → fusion → release → déploiement en maintenance → article léger. Tu es prévenu à chaque étape, en commençant par les plus petites.

1. Comment lire ce document

Trois niveaux, comme un escalier :

1. En haut (§4) : le cahier des charges complet, écrit pour un gros modèle. C'est lui qui décrit tout, tranche, et écrit les fiches techniques. Il se copie-colle tel quel.
2. Au milieu (§5–§7) : les mini-prompts et la carte qui dit à chaque agent lequel lire. Un agent léger ne lit que son prompt et sa fiche : il n'a pas besoin du reste.
3. En bas (§8–§11) : le pas à pas pour toi, les notifications, et le pipeline technique (worktree, tests, release, déploiement, article).

2. Ce qui est en jeu, en une image

   ARCHITECTE            ── Cursor (Grok 4.6) : une fiche technique par lot
   (P0)                     docs/plans/technique/<ID>.md (fichiers exacts, signatures, tests)
        │
        ▼
   SWARM D'AGENTS        ── un agent = un lot = un worktree = une branche = une PR
   (Cursor Composer 2.5,    chacun avec SON mini-prompt numéroté
    Cursor Grok 4.6,        test rouge d'abord → code → Handoff → PR
    DeepSeek v4.1 flash)
        │
        ▼
   CLÔTUREUR (P4)        ── fusion → STATUS + CHANGELOG → release → déploiement en maintenance
        │                   → vérification /readyz → article léger sur le blog
        ▼
   UNE VAGUE LIVRÉE      ── puis la suivante, du plus rapide au plus lent
   (l'orchestrateur P8 mène tout ça, jalons et tickets à l'appui)

3. Les règles non négociables (la constitution du dépôt)

Elles priment sur tout le reste, dans cet ordre : sécurité et vie privée → charte de jeu → contraintes techniques → le reste.

• Cinq dépendances runtime, pas une de plus (pas d'Electron, pas de bibliothèque tierce).
• Un agent = un worktree = une branche = un lot. Jamais deux agents dans le même dossier.
• Un seul rédacteur de STATUS.md et des CHANGELOG par vague : le clôtureur.
• Une PR = un critère, et une case ne se coche qu'avec sa ligne Preuve : test/… › nom du test, le test vu rouge d'abord.
• Aucun rouge masqué (|| true, exit 0, continue-on-error, seuil baissé).
• Le gros modèle écrit, les petits exécutent. Un agent qui a besoin de « tout le contexte » est mal affecté.

4. Le cahier des charges (bloc à copier — pour l'architecte, Cursor Grok 4.6)

C'est le seul texte long de la chaîne. Il produit, pour chaque lot, la fiche technique que les agents légers consommeront.

Rôle : architecte technique de la vague Jah Messenger du 30/09/2026.
Dépôt : d:\GitRepos\JahMessenger (branche hotfix/2026-09-30-vague-urgences, PR #88, base main).
Agent cloud : tu peux OUVRIR une PR ; tu ne peux PAS fusionner ; tu ne pousses JAMAIS de tag.
Tu n'écris PAS de code de production. Tu produis des fiches techniques.

1) LIS, dans cet ordre
   - docs/plans/hotfix-2026-09-30.md : décisions D1–D11, tableau urgence/priorité/importance/
     temps/ordre, vagues V0–V9, périmètre exclusif, migrations réservées (0022 V1, 0023 V2,
     0024 V3, 0025 H6, 0027 W1), capacités des agents, boucle par lot.
   - docs/plans/lots/README.md et docs/plans/technique/README.md
   - docs/plans/lots/00-demande-initiale.md  (la demande de FG et ses réponses = contrat produit)
   - les 22 fiches docs/plans/lots/<ID>-*.md, puis le code cité et .agents/RULES.md,
     .agents/CHARTER.md, .agents/UI.md, .agents/TESTS.md

2) MISSION A — VALIDER LE PLAN
   Rends une section « Validation » : contradictions, imprécisions, dépendances oubliées, risques
   de collision entre lots d'une même vague, numéros de migration, et ce qui manque pour qu'un
   agent puisse implémenter sans toi. Si tu corriges une fiche de lot, dis-le explicitement.

3) MISSION B — ÉCRIRE LES FICHES TECHNIQUES
   Pour CHAQUE lot (S1, H1, H5a, C1, H7a, H7b, H2, H3, H4, H6, H8, H9, M1, G1, W1, W2, W4, V1,
   V2, T1, V3, W3), crée docs/plans/technique/<ID>.md avec exactement :
   - Design : ce qu'on ajoute, où, et pourquoi c'est la plus simple des solutions correctes (§0).
   - Fichiers : chemins exacts à créer/modifier + signatures (nom, entrée, sortie).
   - Schéma : colonnes / contrainte / trame / message s'il y en a.
   - Tests : fichier, nom du cas, ce qu'il prouve (test rouge d'abord) + ligne
     « Preuve : test/… › … ».
   - Risque principal + la garde-fou qui le couvre.
   - Ordre d'implémentation : 3 à 6 étapes courtes.
   - Rappel des « Fichiers exclusifs » et de ce qui est HORS lot.
   - Si la fiche de lot est impossible ou ambiguë : section « Écart à la fiche de lot ».

4) MISSION C — LA LISTE DES MINI-PROMPTS
   Ajuste docs/plans/prompts-agents.md : P0 (toi), P1 (implémenteur), P2 (Cursor multitâche),
   P3 (audit Telegram), P4 (clôtureur : fusion + release + article), P5 (contrôle qualité),
   P6 (implémenteur léger : peu de contexte, tests ciblés seulement), P7 (carte lot -> prompt ->
   agent). Chaque prompt doit être court, autonome, avec : rôle, ce qu'il lit, ce qu'il produit,
   sa branche, son périmètre exclusif, ses interdits.

5) LIVRABLE + PR
   Ouvre une PR vers main : « docs(technique): fiches techniques des 22 lots + mini-prompts ».
   Corps = section « Validation » + table lot -> prompt -> agent + liste des fichiers produits +
   ce que le clôtureur (P4) devra faire après fusion. Ne fusionne pas.

6) INTERDITS
   Toucher src/, ui/, test/, migrations/, STATUS.md, CHANGELOG*.md, README.md, SPEC.md ;
   fusionner une PR ; pousser un tag ; lancer une release ; prendre un numéro de migration hors
   de la liste réservée ; élargir le périmètre d'un lot ; assouplir la sécurité (§8 prime) ;
   ajouter une dépendance runtime.

7) CONTRAINTES DURES À RESPECTER DANS CHAQUE FICHE
   - 5 deps runtime ; vanilla ESM, zéro build ; fichiers <= 600 lignes.
   - ui/modules/msn/conversation.mjs est à 556/600 : toute mécanique de fenêtre va dans un
     NOUVEAU fichier (window-drag.mjs).
   - ui/sw.js (liste ASSETS), ui/modules/dom.mjs (APP_STYLES), ui/index.html, ui/manifest.json :
     ajouts ALPHABÉTIQUES uniquement.
   - Action admin sensible : SENSITIVE + ré-auth + audit, et un test de REFUS par route.
   - Un test rouge vu d'abord ; une case ne se coche qu'avec sa ligne Preuve.
   - Migration : NNNN_nom.sql + .down.sql, tables STRICT, recopie de table si on modifie un CHECK.
   - Le mode Matrix ne transporte JAMAIS de contenu réel (vie privée, §8).

5. Les mini-prompts (le swarm n'a besoin que de sa parcelle)

Le prompt P6, pour les agents légers

Ils n'ont pas besoin de beaucoup de contexte : juste le cahier des charges et leur parcelle.

Lot <ID> — Jah Messenger. Tu es un implémenteur léger : périmètre serré, tests ciblés.

Ce que tu lis (RIEN D'AUTRE) :
1. docs/plans/technique/<ID>.md   ← le cahier des charges : fichiers, signatures, tests, ordre.
2. docs/plans/lots/<ID>-*.md      ← les « Fichiers exclusifs » et le « Hors lot ».
3. Les fichiers de code cités par la fiche technique.

Ce que tu fais :
1. git switch main && git pull ; git worktree add .worktrees/<id> -b <type>/<id>.
2. Suis l'ordre d'implémentation (3 à 6 étapes) de la fiche technique.
3. Écris le test nommé D'ABORD, vois-le rouge, puis code.
4. Vérifie UNIQUEMENT : npm run lint ; npm test (ou node --test <ton fichier>) ;
   npm run check:quick si le lot touche plusieurs domaines.
   Ne lance PAS la suite E2E complète : elle tourne en CI sur ta PR.
5. Ajoute « ## Handoff » dans docs/plans/lots/<ID>-*.md (fait / preuve / reste / pièges).
6. Ouvre UNE PR vers main. Corps = la ligne Preuve + le lien vers la fiche technique +
   les commandes lancées et leur résultat.

Interdits : sortir des « Fichiers exclusifs » ; ajouter une dépendance ; refactoriser « au
passage » ; toucher STATUS/CHANGELOG sans instruction explicite de la fiche technique.
Si la fiche technique est muette : choisis la solution la plus simple, note-le dans le Handoff,
ne demande pas d'arbitrage.

6. La carte : quel agent fait quoi (et ce qu'il a le droit de faire)

Claude est retiré de la vague (décision du 30/09 au soir) : plus d'agent cloud. Cursor et DeepSeek ont les trois droits — ouvrir, fusionner, taguer.

7. Les 22 lots, du plus rapide au plus lent

P0 production cassée · P1 urgent FG · P2 important · P3 souhaité.

Les dix vagues

Les deux derniers lots, en clair

• G1 — l'aide dans le jeu. Le guide habitant, le tutoriel et l'aide cessent d'être un fichier qu'il faut aller chercher : ils deviennent un panneau consultable dans Jah, ouvert depuis le bureau, depuis le monde (bouton et touche H) et depuis chaque fenêtre. Une seule source de vérité pour les textes, accessible au clavier et en Grand confort.
• W4 — projeter pour tout le monde. Pendant une soirée, n'importe qui peut projeter : sur le mur de la salle, au-dessus de la salle et au-dessus du village. Deux habillages : le mode Matrix (bribes de mots et d'émotes qui défilent, volontairement illisibles — une ambiance, pas une information) et le mode Kikoo (pour un message que l'auteur projette volontairement). Et un bouton retour dedans pour tout arrêter. Le serveur ne transporte jamais de contenu : un identifiant, un mode, une surface.

8. Pas à pas, du plus petit au plus grand

À faire dans cet ordre. Chaque case produit une notification (§9) et, à partir de l'étape 6, une release.

Ou plus simple encore : donne le prompt P8 (orchestrateur) à Cursor Grok 4.6 — il enchaîne les étapes 3 à 7 sans te demander de valider entre les sous-étapes, et tu es notifié par les tickets.

Un lot = un cycle complet :

1. l'agent lit son mini-prompt (P1 ou P6) et sa fiche technique ;
2. il crée son worktree et sa branche, écrit le test rouge, puis code ;
3. il remplit le ## Handoff dans sa fiche de lot et ouvre une PR ;
4. le clôtureur (P4) fusionne, met à jour STATUS.md et les CHANGELOG, release, déploie (le déploiement passe tout seul en mode maintenance grâce à S1), vérifie /readyz, puis publie un article léger sur le blog.

9. Être prévenu à chaque mise à jour (dès la plus petite)

Trois mécanismes, à mettre en place une fois :

1. Un ticket GitHub par lot, un jalon par vague — ✅ déjà créés : jalons V0…V9, tickets #89 → #110 (un par lot, rattaché à son jalon). Tu reçois une notification à l'ouverture, à chaque commentaire et à la fermeture de chaque ticket — c'est-à-dire lot par lot, dans l'ordre du tableau. C'est le réglage le plus fin, et il ne coûte rien.
   • Jalon V0, V1, … V9 ; tickets S1, H1, H5a, … rattachés à leur jalon.
2. Les notifications du dépôt. Dans GitHub : Watch → Custom → Releases + Pull requests + Issues. Tu es prévenu de chaque PR ouverte/fusionnée et de chaque release publiée. Active aussi Participating and @mentions pour être sûr de recevoir les demandes d'arbitrage.
3. La veille automatique déjà en place. Le dépôt interroge le site toutes les deux heures (veille.yml) : si le live tombe, une alerte part. Rien à configurer.

Bonus, si tu veux le voir dans l'éditeur : l'extension GitHub Pull Requests affiche les PR et leurs statuts dans la barre latérale de VS Code.

Le rythme des notifications suit exactement le rythme du travail : deux demi-journées pour V0, puis les quatre urgences, puis une vague à la fois. Rien ne part en silence.

10. Toutes les ressources

Le pipeline, en commandes

# Un agent : son lot, son dossier, sa branche
git switch main && git pull
git worktree add .worktrees/<id> -b <type>/<id>

# Il vérifie (tests ciblés pour un agent léger)
npm run lint && npm test
npm run check:quick        # tests liés au diff
npm run check:pr           # batterie complète, si interface / monde / trames

# Le clôtureur
npm run check:pr
npm run release -- alpha
git push origin HEAD --follow-tags
# → workflow Release : image GHCR → déploiement (maintenance automatique) → /readyz

# L'article léger (dépôt du blog)
node build-index.mjs
node scripts/verify-counts.mjs --fix
node scripts/post.mjs devblog/posts/vfjah/<fichier>.md --live

11. En cas de hotfix : ce qu'on vérifie quand même

La CI et le déploiement prennent du temps, et en hotfix un défaut mineur qui passe n'est pas grave — mais on ne livre pas à l'aveugle :

• toujours : npm run lint vert, tests unitaires et d'intégration verts, et /readyz qui répond la version attendue après déploiement ;
• toujours : la ligne Preuve : du lot existe (le test rouge a été vu) ;
• on peut sauter temporairement : la suite E2E complète, les captures, un article — à faire juste après, dans la même vague ;
• jamais : masquer un rouge, cocher une porte R2, éditer une migration déjà fusionnée, ou toucher la sécurité (§8) sans relecture.

Le garde-fou du déploiement reste entier : image sondée avant publication, retour arrière automatique si la sonde échoue, et maintenance levée même sur le chemin d'échec (lot S1).

12. Trois choses à trancher

1. La « baie de brassage » (blog.vfg.lol/baie-de-brassage, la carte des services, ports et tuyaux) est le prérequis du lot Telegram. Elle est trouvée ; il reste à la lire.
2. L'accès en lecture au dépôt originel et à l'état du bot Telegram sur le serveur — sinon l'audit reste sur pièces.
3. Qui fusionne les lots sensibles : V1 (rôles et superadmin), V2 (villages), V3 (village PTR). Proposition : toi.

13. En une phrase

On ne demande plus aux agents d'« avancer sur Jah » : le gros modèle écrit le cahier des charges, chaque agent léger reçoit un lot, un dossier, une branche, un test rouge et une preuve, et chaque vague se termine par un handoff, une fusion, une release en maintenance, et un article — dans l'ordre du plus rapide au plus lent.