One Ring — Guide d'utilisation¶

Vue d'ensemble¶

Le One Ring orchestre N workflows /gov en parallèle. Tout tient dans un seul workspace cmux — Terre du Milieu — avec un onglet par agent. Tu pilotes tout depuis ton iPhone via Signal.

iPhone (Signal)  ←→  Mac (One Ring supervision)  ←→  cmux "🏔️ Terre du Milieu"

🏔️ Terre du Milieu (workspace unique)
├── 💍 One Ring        (tab — bash supervision)
├── 🔮 Palantír        (tab — claude veille)
├── ⚔️ PD-103          (tab — claude /gov)
├── ⚔️ PD-285          (tab — claude /gov)
├── 🔨 Forgeron PD-103 (tab — /forge post-merge, si pipeline rouge)
├── 📜 Scribe          (tab — /doc recherche + envoi PJ Signal)
└── ...

Polling adaptatif : 5s quand des Ringbearers sont actifs, 30s au repos. Notifications cmux : les escalades allument un anneau de notification sur le tab du Ringbearer. Isolation : le reste de cmux reste libre pour d'autres usages.

Comment ça marche¶

1. Le One Ring renomme le workspace courant en "🏔️ Terre du Milieu" et son tab en "💍 One Ring"
2. Chaque Ringbearer crée un nouveau tab ⚔️ PD-XXX dans le même workspace
3. Le One Ring attend le prompt ❯ puis envoie /gov PD-XXX projet
4. Le Ringbearer exécute le workflow en autonomie (le skill /gov reprend là où Jira en est)
5. La supervision scrape le pane (polling adaptatif : 5s actif / 30s idle) :
6. Détecte le step courant (grep "Step N" / "Gate N")
7. Détecte les pickers ("Enter to select") → extrait la question + options → Signal + notification cmux
8. Détecte le prompt ❯ idle (sans "esc to interrupt") → extrait le contexte → Signal
9. Réconcilie avec Jira — si Done, ferme automatiquement le Ringbearer
10. Tu reçois la question/escalade sur Signal (et l'anneau de notification cmux s'allume)
11. Le One Ring injecte ta réponse dans la session du Ringbearer (navigation picker automatique pour les numéros)
12. Le Ringbearer continue

Prérequis¶

1. cmux (recommandé) ou tmux (fallback)¶

cmux est un terminal macOS natif avec notifications, onglets verticaux et Socket API. Le One Ring détecte automatiquement le backend disponible.

# cmux (recommandé) — terminal natif avec notifications
brew tap manaflow-ai/cmux && brew install --cask cmux
# Ouvrir cmux, puis dans Settings → Socket → "Allow all local processes"

# tmux (fallback si cmux absent)
which tmux || brew install tmux

2. Broker claude-peers (une seule fois)¶

# Vérifier que le broker tourne
curl -s http://localhost:7899/
# Doit répondre: "claude-peers broker"

# Si pas de réponse, lancer le broker
cd /Users/loic/.nvm/versions/node/v20.19.5/lib/node_modules/claude-peers
export PATH="$HOME/.bun/bin:$PATH"
bun broker.ts &

Le broker se lance aussi automatiquement via la config MCP (.mcp.json) quand Claude Code démarre.

3. Signal (une seule fois)¶

signal-cli est lié au +33646133327 (device "One Ring (MacBook)"). Pour vérifier :

signal-cli -a +33646133327 send -m "test" +33646133327
# Tu dois recevoir "test" dans Notes perso sur Signal

Si le lien est expiré :

signal-cli link -n "One Ring (MacBook)" > /tmp/signal-link.txt 2>&1 &
sleep 5
URI=$(head -1 /tmp/signal-link.txt)
qrencode -t PNG -o /tmp/signal-qr.png "$URI"
open /tmp/signal-qr.png
# Scanner le QR depuis Signal → Paramètres → Appareils liés

Démarrage du One Ring¶

1. Lancer cmux (l'app macOS) — les Ringbearers apparaîtront comme des workspaces dans la sidebar.

2. Lancer la supervision depuis n'importe quel terminal :

cd /Users/loic/Developpement/ProbatioVault/ProbatioVault-ia-governance
bash scripts/gov-lord.sh supervision

Le One Ring : - Détecte le backend (cmux si disponible, sinon tmux) - Vérifie qu'aucun autre One Ring ne tourne (verrou .gov-lord.lock) - S'enregistre au broker claude-peers - Démarre le polling Signal + broker (5s si Ringbearers actifs, 30s sinon) - Affiche en temps réel : [SIGNAL ←] messages reçus, [SIGNAL →] messages envoyés

Un seul One Ring peut tourner à la fois. Si tu relances, tu verras :

❌ Un One Ring est déjà actif (PID: 12345). Un seul One Ring autorisé.
   Pour forcer : rm .gov-lord.lock

Le verrou est nettoyé automatiquement à la fermeture (Ctrl+C, fermeture terminal, crash).

2. Lancer des Ringbearers — depuis la session One Ring ou depuis Signal :

/gov-lord start PD-285 backend
/gov-lord start PD-286 app
/gov-lord start PD-287

Ou depuis Signal sur ton iPhone :

start PD-285 backend
start PD-286 app
start PD-287

Si le projet est omis, le One Ring tente de le déduire depuis Jira. Sinon il te demande de préciser.

Chaque start : 1. Vérifie les gardes (format, quota, pas de doublon) 2. Crée un onglet ⚔️ PD-XXX dans le workspace Terre du Milieu 3. Lance claude interactif avec le system prompt Ringbearer 4. Attend que le prompt ❯ apparaisse (~10-15s) 5. Envoie /gov PD-XXX projet 6. Le workflow tourne en autonomie

3. Piloter depuis l'iPhone — tout passe par Signal (tape help pour voir les commandes).

Commandes Signal¶

Tu peux piloter le One Ring entièrement depuis Signal :

Les commandes sont insensibles à la casse. Les messages sans destinataire sont routés vers le Palantír si aucun Ringbearer n'est actif.

Flux d'escalade complet¶

Ringbearer PD-287 bloqué (question PO en step 0)
  │
  ├─ Affiche un picker ou attend au prompt ❯
  │
  ├─ Supervision scrape le pane tmux → détecte le blocage
  │
  ├─ One Ring → Signal : "🚨 PD-287 attend ta réponse : [question + options]"
  │
  ├─ Sovereign répond sur Signal : "1" ou "Continuer avec un stub"
  │
  ├─ One Ring → lord_term_send_text dans la session du Ringbearer
  │
  └─ Ringbearer reçoit l'input et continue le workflow

La communication passe par l'abstraction lord-terminal.sh (cmux Socket API ou tmux capture-pane + send-keys).

Observer un Ringbearer en direct¶

# Avec cmux : ouvrir le workspace "🏔️ Terre du Milieu", cliquer sur l'onglet ⚔️ PD-XXX

# Avec tmux (fallback) :
tmux attach -t "⚔️ PD-285"
# Détacher sans arrêter : Ctrl+B puis D

Palantír (veille tech)¶

Le Palantír est une session Claude Code persistante dédiée à l'analyse de veille tech. Elle démarre automatiquement avec le One Ring et se relance si elle crashe.

veille https://example.com/article       → analyse l'article
veille https://url1 https://url2         → analyse plusieurs articles
veille <texte d'un post>                 → analyse un texte brut
kill palantir                            → tue la session (relancée au cycle suivant)

La session est interactive — le Palantír te donne son avis, tu peux discuter, enchaîner les articles dans la même session.

Les messages Signal sans destinataire (pas de commande, pas de PD-XXX) sont routés vers le Palantír si aucun Ringbearer n'est actif.

# Observer le Palantír : cliquer sur l'onglet 🔮 Palantír dans cmux

Terminal log (pour le REX)¶

Chaque session (Ringbearer et Palantír) enregistre tout ce qui s'affiche dans le terminal via tmux pipe-pane :

• data/sessions/PD-XXX-terminal.log — log complet du Ringbearer
• data/sessions/palantir-terminal.log — log complet du Palantír

Ces logs capturent les erreurs rattrapées silencieusement, les retries, les anomalies — tout ce qui ne remonte pas dans session.jsonl. Utilisés au REX pour capitaliser.

# Consulter le terminal log complet
/gov-lord fulllog PD-XXX

FSM des Ringbearers¶

STARTING → RUNNING → PAUSED → RUNNING
                   → ESCALATED → RUNNING (après respond)
                   → COMPLETED (terminal)
                   → CRASHED → RESTARTING → RUNNING
                                          → DEAD (terminal, 2 restarts max)
                   → ABORTED (terminal, arrêt manuel)
         → START_FAILED (terminal, lancement échoué)

Fichiers clés¶

Limites actuelles (v2)¶

1. Max 5 Ringbearers par défaut — configurable via LORD_MAX_RINGBEARERS (pas de limite technique dure)
2. cmux Socket API — nécessite cmux lancé avec socket mode "Allow all". Fallback tmux automatique si cmux absent.
3. Pas de Channel protocol — un Signal Channel plugin existe (mcp-signal/signal-channel.ts) mais les pickers TUI de Claude Code ne sont pas pilotables via Channel. En attente d'un flag --text-mode d'Anthropic.
4. signal-cli lent — chaque envoi prend ~2-3s (JVM cold start). Passer à signal-cli daemon mode pour production.
5. Signal filtre par sender — seuls les messages du numéro configuré sont traités. Si le sender et le One Ring ont le même numéro (Notes perso), les conversations tierces sont ignorées.

Dépannage¶

Le broker ne répond pas¶

curl -s http://localhost:7899/
# Si vide, relancer
cd /Users/loic/.nvm/versions/node/v20.19.5/lib/node_modules/claude-peers
export PATH="$HOME/.bun/bin:$PATH"
bun broker.ts &

Signal ne fonctionne plus¶

signal-cli -a +33646133327 listAccounts
# Si erreur, re-lier (voir section Prérequis)

Un Ringbearer est DEAD¶

/gov-lord status
# Relancer manuellement
/gov-lord start PD-XXX projet

"Un One Ring est déjà actif"¶

cat .gov-lord.lock
ps -p $(cat .gov-lord.lock) -o pid,command | head -2
# Si le process est mort
rm .gov-lord.lock
bash scripts/gov-lord.sh supervision

Un Ringbearer est bloqué¶

# Voir ce qu'il fait : cliquer sur l'onglet ⚔️ PD-XXX dans cmux
# Ou via Signal : view PD-XXX

# Forcer un restart
/gov-lord stop PD-XXX
/gov-lord start PD-XXX projet

L'état est corrompu¶

cp .gov-lord-state.json .gov-lord-state.json.bak
echo '{"ringbearers":{},"sovereign_channel":"signal","supervision_interval_s":10}' > .gov-lord-state.json

Exemple de session complète¶

# 1. Terminal dédié — démarrer le One Ring
cd /Users/loic/Developpement/ProbatioVault/ProbatioVault-ia-governance
bash scripts/gov-lord.sh supervision
# → 💍 One Ring to rule them all.

# 2. Depuis Signal sur iPhone
start PD-285 backend     # → ✅ Ringbearer PD-285 démarré
start PD-286 app         # → ✅ Ringbearer PD-286 démarré
status                   # → 🔔 One Ring — 2 stories

# ... les stories avancent en autonomie ...
# ... escalade reçue sur Signal ...

# 3. Répondre à l'escalade depuis Signal
PD-285: Utiliser le stub, tracer STUB: PD-52

# 4. Suivre l'avancement
status                   # → PD-285 Step 3 RUNNING, PD-286 Step 1 RUNNING
gate PD-285              # → Gate 3 v1: RESERVE (7.875/10)
jira PD-285              # → Statut Jira: GATE SPEC

# 5. Observer un Ringbearer en direct (cliquer sur l'onglet dans cmux)
# Ou : view PD-285 via Signal

# 6. Arrêter
stop PD-286              # → 🛑 PD-286 arrêté
# Ctrl+C dans le terminal One Ring
# → 🌋 The Ring has been destroyed. Sauron is defeated.