PD-293 — Orchestration contractuelle multi-stories “One Ring” via claude-peers et controle mobile (v2 corrigee)¶

1. Objectif¶

La User Story PD-293 permet a un Sovereign (humain) de piloter, depuis une session unique (One Ring), jusqu'a 5 Ringbearers executant chacun un workflow /gov PD-XXX [projet], avec :

• supervision consolidee des stories,
• remontee et traitement des escalades bloquantes,
• pilotage a distance via /remote-control (iPhone/Safari),
• separation stricte des responsabilites (One Ring route, Ringbearers executent).

2. Perimetre / Hors perimetre¶

Inclus¶

• Orchestration multi-stories par une session One Ring unique.
• Commandes /gov-lord : start, status, stop, escalade, respond, pause, resume.
• Protocole de messagerie Ringbearer ↔ One Ring (types, validation, routage, dedoublonnage).
• Detection de disparition/crash d'un Ringbearer et signalement au Sovereign.
• Affichage consolide de l'etat de N stories.
• Controle mobile du One Ring via /remote-control.
• Persistance locale d'un etat consolide minimal .gov-lord-state.json.

Exclu¶

• Toute modification du workflow /gov existant.
• Toute execution metier/projet par le One Ring (lecture code, ecriture fichier, build, tests, Jira, GitLab, Vault).
• Communication directe Ringbearer ↔ Ringbearer.
• Application iOS native dediee.
• Mutualisation/partage de credentials entre sessions.
• Etat ESCALADE_EXPIRED en v1 (hors perimetre, evolution future).

3. Definitions¶

4. Invariants (non negociables)¶

4.1 Notes de coherence etats¶

• En v1, aucun etat ESCALADE_PENDING n'est defini.
• En v1, aucun etat ESCALADE_EXPIRED n'est defini (hors perimetre, evolution future).

4.2 Commandes /gov-lord normatives¶

• /gov-lord start <story_id> <project_code> [--idempotency-key <key>]
• /gov-lord status [--story <story_id>]
• /gov-lord escalade [--story <story_id>]
• /gov-lord respond <story_id> <reponse> [--idempotency-key <key>]
• /gov-lord pause <story_id> [--reason <texte>] [--idempotency-key <key>]
• /gov-lord resume <story_id> [--idempotency-key <key>]
• /gov-lord stop <story_id> [--reason <texte>] [--idempotency-key <key>]

5. Flux nominaux¶

5.1 Modele de donnees canonique (referentiel unique)¶

Regles globales normatives¶

1. La regex story_id est la source de verite unique (pas de contrainte textuelle de longueur independante).
2. Ordre de precedance dedoublonnage:
3. si idempotency_key deja vue avec payload identique: retour deterministe sans effet secondaire,
4. si idempotency_key deja vue avec payload different: rejet de conflit,
5. sinon validation/pilotage normal par story_id.
6. Ordre de gardes pour start (et seulement start) : quota -> doublon idempotence -> validation format complete.
7. Pour stop/respond/pause/resume : doublon idempotence -> validation format complete (garde quota non applicable).

Parametres numeriques contractuels¶

SLA temporels (transitions)¶

5.2 Machine d'etats Ringbearer (avec transitions retour)¶

Etats officiels v1: STARTING, RUNNING, ESCALADED, PAUSED, DONE, ABORTED, CRASHED, START_FAILED.

• STARTING :
• Autorisees : STARTING->RUNNING, STARTING->START_FAILED
• Regle STARTING->RUNNING : peer detecte et premiere liveness valide recue avant first_liveness_timeout.
• Regle STARTING->START_FAILED : start_detection_timeout depasse ou peer detecte mais aucune liveness valide dans la fenetre.
• RUNNING :
• Autorisees : RUNNING->ESCALADED, RUNNING->PAUSED, RUNNING->DONE, RUNNING->ABORTED, RUNNING->CRASHED
• ESCALADED :
• Autorisees : ESCALADED->RUNNING (apres PO_RESPONSE valide), ESCALADED->ABORTED, ESCALADED->CRASHED
• Retour couvert : RUNNING<->ESCALADED
• PAUSED :
• Autorisees : PAUSED->RUNNING (resume), PAUSED->ABORTED, PAUSED->CRASHED
• Retour couvert : RUNNING<->PAUSED
• DONE (terminal) : DONE->* INTERDITE.
• ABORTED (terminal) : ABORTED->* INTERDITE.
• CRASHED (terminal) : CRASHED->* INTERDITE.
• START_FAILED (terminal) : START_FAILED->* INTERDITE.

Checklist machine a etats : - [x] Chaque etat a ses transitions sortantes autorisees/interdites. - [x] Chaque etat terminal declare explicitement -> * : INTERDITE. - [x] Couverture par invariants INV-293-09 et INV-293-10. - [x] Aucune reference a ESCALADE_PENDING ou ESCALADE_EXPIRED en etats v1.

5.3 Flux metier¶

1) start : garde quota -> idempotence -> validation format ; creation d'un Ringbearer si autorise.
2) start post-apparition : premiere verification de liveness obligatoire avant passage RUNNING.
3) status : consolidation de l'etat de tous les Ringbearers observes/attendus.
4) escalade : affichage de la file bloquante FIFO a traiter par le Sovereign.
5) respond : injection d'une decision humaine sur la plus ancienne escalade ouverte de la story cible (FIFO intra-story).
6) pause : gel intentionnel (RUNNING->PAUSED) sans perte de contexte.
7) resume : reprise (PAUSED->RUNNING) si gardes valides.
8) stop : arret intentionnel de la story (->ABORTED selon transitions autorisees).
9) Supervision continue : detection d'absence peer en <= 2 cycles et signalement CRASHED.
10) Reconnexion broker : tentative de reconnexion exponentielle bornee (1s, 2s, 4s, 8s, 10s max), mode degrade explicite tant que indisponible, reprise automatique des polls a la reconnexion.

5.4 Format de persistance .gov-lord-state.json (schema minimal v1)¶

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "GovLordState",
  "type": "object",
  "required": ["version", "updated_at", "stories", "escalade_queue", "idempotency_cache"],
  "properties": {
    "version": { "type": "string", "const": "1.0" },
    "updated_at": { "type": "string", "format": "date-time" },
    "broker": {
      "type": "object",
      "required": ["status", "last_seen_at"],
      "properties": {
        "status": { "type": "string", "enum": ["UP", "DEGRADED", "DOWN"] },
        "last_seen_at": { "type": "string", "format": "date-time" }
      },
      "additionalProperties": false
    },
    "stories": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["story_id", "project_code", "state", "peer_id", "last_seen_at"],
        "properties": {
          "story_id": { "type": "string", "pattern": "^PD-[0-9]{1,4}$" },
          "project_code": { "type": "string", "enum": ["backend", "app", "site", "infra", "doc", "formal", "pixel-governance", "ia-governance"] },
          "state": { "type": "string", "enum": ["STARTING", "RUNNING", "ESCALADED", "PAUSED", "DONE", "ABORTED", "CRASHED", "START_FAILED"] },
          "peer_id": { "type": "string", "minLength": 1, "maxLength": 128 },
          "last_seen_at": { "type": "string", "format": "date-time" },
          "current_escalade_id": { "type": ["string", "null"] }
        },
        "additionalProperties": false
      }
    },
    "escalade_queue": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["escalade_id", "story_id", "created_at", "text", "status"],
        "properties": {
          "escalade_id": { "type": "string", "minLength": 1, "maxLength": 128 },
          "story_id": { "type": "string", "pattern": "^PD-[0-9]{1,4}$" },
          "created_at": { "type": "string", "format": "date-time" },
          "text": { "type": "string", "minLength": 1, "maxLength": 2000 },
          "status": { "type": "string", "enum": ["OPEN", "ANSWERED", "CLOSED"] }
        },
        "additionalProperties": false
      }
    },
    "idempotency_cache": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["key", "command", "story_id", "payload_hash", "result_hash", "expires_at"],
        "properties": {
          "key": { "type": "string", "pattern": "^[A-Za-z0-9:_-]{16,80}$" },
          "command": { "type": "string", "enum": ["start", "stop", "respond", "pause", "resume"] },
          "story_id": { "type": "string", "pattern": "^PD-[0-9]{1,4}$" },
          "payload_hash": { "type": "string", "minLength": 8, "maxLength": 128 },
          "result_hash": { "type": "string", "minLength": 8, "maxLength": 128 },
          "expires_at": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

5bis. Diagrammes (si applicable)¶

Diagramme d'etat (>= 3 etats)¶

stateDiagram-v2
    [*] --> STARTING
    STARTING --> RUNNING: peer detecte + first liveness OK
    STARTING --> START_FAILED: timeout demarrage ou liveness KO

    RUNNING --> ESCALADED: message ESCALADE
    ESCALADED --> RUNNING: message PO_RESPONSE valide

    RUNNING --> PAUSED: commande PAUSE
    PAUSED --> RUNNING: commande RESUME

    RUNNING --> DONE: WORKFLOW_DONE
    RUNNING --> ABORTED: commande ABORT/STOP
    ESCALADED --> ABORTED: commande ABORT/STOP
    PAUSED --> ABORTED: commande ABORT/STOP

    RUNNING --> CRASHED: peer disparu (>2 polls)
    ESCALADED --> CRASHED: peer disparu (>2 polls)
    PAUSED --> CRASHED: peer disparu (>2 polls)

    DONE --> [*]
    ABORTED --> [*]
    CRASHED --> [*]
    START_FAILED --> [*]

Diagramme de sequence (>= 2 services)¶

sequenceDiagram
    participant S as Sovereign
    participant O as One Ring
    participant B as Broker
    participant R as Ringbearer

    S->>O: "/gov-lord start PD-293 ia-governance"
    O->>O: Gardes start: quota -> idempotence -> format
    O->>B: list_peers()
    B-->>O: peers[]
    O->>R: demande demarrage story_id=PD-293
    R->>B: register_peer(summary_text)
    R-->>O: STATUS_UPDATE (first liveness)
    O->>O: STARTING->RUNNING

    R->>O: ESCALADE{story_id, escalade_text, timestamp}
    O->>O: enqueue FIFO escalade_queue
    O-->>S: notification escalade la plus ancienne

    S->>O: "/gov-lord respond PD-293 <reponse>"
    O->>R: PO_RESPONSE{story_id, escalade_text=<reponse>}
    R-->>O: STATUS_UPDATE (reprise RUNNING)

    S->>O: "/gov-lord pause PD-293"
    O->>R: PAUSE
    S->>O: "/gov-lord resume PD-293"
    O->>R: RESUME

6. Cas d'erreur¶

6.1 Format de log de rejet (normatif)¶

Chaque rejet de validation/message doit produire une ligne JSON (JSONL) avec champs obligatoires:

{
  "timestamp": "2026-03-30T10:15:30Z",
  "peer_id": "peer-abc-123",
  "message_type": "ESCALADE",
  "reason": "story_id invalide (regex ^PD-[0-9]{1,4}$)",
  "story_id": "PD-99999",
  "event": "MESSAGE_REJECTED"
}

Champs obligatoires minimum: timestamp, peer_id, message_type, reason.

7. Criteres d'acceptation (testables)¶

8. Scenarios de test (Given / When / Then)¶

• T-01 Start nominal
  Given quota disponible et broker operationnel, When start PD-XXX, Then etat RUNNING avant timeout et apres first liveness valide.

• T-02 Limite capacite
  Given 5 actifs, When start 6e story, Then rejet explicite sans nouveau peer.

• T-03 Escalade bloquante
  Given story en RUNNING, When message ESCALADE, Then story en ESCALADED jusqu'a PO_RESPONSE.

• T-04 Reponse escalade
  Given story ESCALADED, When respond valide, Then retour RUNNING et reprise observable.

• T-05 Commande hors scope
  Given One Ring actif, When demande lecture/ecriture/build/Jira, Then blocage explicite sans execution.

• T-06 Crash detection
  Given peer present puis absent > 2 cycles, When cycle de supervision, Then etat CRASHED + alerte en <=20s (defaut).

• T-07 Idempotence commande
  Given idempotency_key deja traitee, When repetition meme payload, Then meme resultat sans doublon d'action.

• T-08 Mobile control (manuel)
  Given session One Ring accessible mobile, When status/escalade/respond/pause/resume, Then memes resultats fonctionnels que desktop.

• T-09 Pause/Resume
  Given story en RUNNING, When pause puis resume, Then transitions RUNNING->PAUSED->RUNNING observees.

• T-10 Multi-escalade FIFO
  Given 3 escalades ouvertes pour une story, When respond est emis 3 fois, Then traitement dans l'ordre d'arrivee sans remplacement.

• T-11 Reconnexion broker
  Given broker indisponible puis restaure, When boucle de retries, Then mode degrade puis reprise automatique et reconciliation.

9. Hypotheses explicites¶

10. Points a clarifier¶

10.1 Contraintes techniques (stack projet cible)¶

• Projet cible de l'artefact : ProbatioVault-ia-governance.
• Stack reelle constatee : Shell (Bash) + Markdown + YAML/JSON de configuration + outillage Python.
• Dependance externe : claude-peers-mcp@^1.x (npm) comme composant d'integration.
• Contrainte de conformite : One Ring reste une couche d'orchestration textuelle, sans logique applicative projet.

10.2 Questions ouvertes¶

References¶

• Epic : Reference epique non fournie dans l'entree (donnee manquante).
• JIRA : PD-293
• Repos concernes : ProbatioVault-ia-governance (orchestrateur), plus repos cibles des stories (backend, app, infra, site, etc.).
• Documents associes : Besoin PD-293 (texte fourni), claude-peers-mcp (github.com/louislva/claude-peers-mcp).