le-mystere-professeur-zacus/specs/AGENT_EXECUTION_PLAN_RUNTIME_SYNC.md

Plan d'execution - Runtime Firmware vers Bundle et Web

Statut

• Etat: draft executable
• Date: 2026-03-01
• Source de verite runtime: hardware/firmware/data/story/scenarios/DEFAULT.json

Objectif

Coordonner les agents et developpeurs pour:

1. synchroniser les artefacts conversationnels sur le runtime firmware,
2. garantir que le frontend consomme les donnees runtime sans hypothese fragile,
3. stabiliser les gates de validation cross-team.

Contraintes

• Ne pas utiliser scenario-ai-coherence/* comme source runtime.
• Ne pas inferrer la logique de transitions depuis des docs narratifs.
• Les IDs de step (STEP_*, SCENE_*, mix) sont contractuels tels qu'exposes par le firmware.

Ordonnancement

1. FW-001 -> 2. SCN-101 -> 3. SCN-102 -> 4. WEB-201 -> 5. WEB-202 -> 6. QA-301

Tickets

FW-001 - Baseline runtime firmware

• Owner: Firmware dev
• Inputs: hardware/firmware/data/story/scenarios/DEFAULT.json
• Travail:

1. Confirmer id, version, initial_step, liste des step_id.
2. Exporter un snapshot runtime horodate dans artifacts/runtime-sync/<date>/.
3. Publier un changelog court des transitions (event_type, event_name, target_step_id).

• Outputs:

1. artifacts/runtime-sync/<date>/DEFAULT.runtime.snapshot.json
2. artifacts/runtime-sync/<date>/transition-index.md

• Definition of done:

1. Snapshot valide JSON.
2. Liste complete des steps et transitions.
3. Diff partage a l'equipe scenario et web.

SCN-101 - Synchronisation du bundle conversationnel

• Owner: Scenario/Content agent
• Inputs:

1. Snapshot FW-001
2. scenario-ai-coherence/zacus_conversation_bundle_v3/scenario_runtime.json

• Travail:

1. Aligner scenario.id, version, initial_step.
2. Aligner l'ordre et le nombre de steps sur le runtime firmware.
3. Conserver les meta narratives hors runtime (boot policy, led policy, etc.) si non contradictoires.

• Outputs:

1. scenario-ai-coherence/zacus_conversation_bundle_v3/scenario_runtime.json aligne firmware
2. note de migration artifacts/runtime-sync/<date>/bundle-sync-notes.md

• Definition of done:

1. Aucun step runtime orphelin.
2. Aucun target vers step inexistant.
3. Validation runtime bundle executee.

SCN-102 - Regeneration coherence visuelle/documentaire

• Owner: Scenario/Content agent
• Inputs:

1. Runtime bundle aligne (SCN-101)
2. FSM source scenario-ai-coherence/zacus_conversation_bundle_v3/fsm_mermaid.md

• Travail:

1. Regenerer la FSM mermaid depuis les transitions runtime.
2. Mettre a jour les sections de docs impactees par initial_step/nombre de steps.
3. Documenter les differences majeures versus version precedente.

• Outputs:

1. scenario-ai-coherence/zacus_conversation_bundle_v3/fsm_mermaid.md
2. artifacts/runtime-sync/<date>/runtime-delta.md

• Definition of done:

1. 1 noeud mermaid par step runtime.
2. 1 edge mermaid par transition runtime.
3. Relecture croisee firmware/scenario signee.

WEB-201 - Alignement contrat API runtime

• Owner: Web dev
• Inputs:

1. Runtime firmware baseline (FW-001)
2. contrat API specs/STORY_RUNTIME_API_JSON_CONTRACT.md

• Travail:

1. Verifier que le parser frontend accepte les IDs mixtes.
2. Retirer toute hypothese de prefixe (STEP_ only).
3. Aligner les actions de controle sur les routes effectivement exposees.

• Outputs:

1. patch frontend d'alignement API (si necessaire)
2. note artifacts/runtime-sync/<date>/web-api-alignment.md

• Definition of done:

1. UI affiche scenario_id et current_step reels.
2. Aucun crash parser sur steps heterogenes.
3. Actions next/unlock/network fonctionnelles selon flavor.

WEB-202 - Tests de contrat

• Owner: Web dev + QA
• Inputs:

1. contrats de payload Story V2/Legacy
2. fixtures runtime issues de FW-001

• Travail:

1. Ajouter fixtures JSON conformes et non conformes.
2. Ajouter tests unitaires parser/status/list.
3. Ajouter tests e2e minimum sur transitions critiques.

• Outputs:

1. fixtures tests/fixtures/runtime-contract/*
2. tests unitaires/e2e de contrat

• Definition of done:

1. cas nominal + cas erreur couverts.
2. build/lint/tests front OK.
3. rapport de couverture de contrat.

QA-301 - Gate integration cross-team

• Owner: QA gatekeeper
• Inputs:

1. livrables FW-001, SCN-101, SCN-102, WEB-201, WEB-202

• Travail:

1. Executer gates scenario/audio/printables.
2. Executer gates frontend (lint/build/unit/e2e).
3. Valider coherence runtime firmware <-> bundle.

• Outputs:

1. artifacts/runtime-sync/<date>/qa-report.md

• Definition of done:

1. toutes gates vertes ou ecarts documentes + action plan.
2. decision GO/NOGO explicite.

Gates minimales a passer

• python3 tools/scenario/validate_scenario.py game/scenarios/zacus_v2.yaml
• python3 tools/scenario/export_md.py game/scenarios/zacus_v2.yaml
• python3 tools/audio/validate_manifest.py audio/manifests/zacus_v2_audio.yaml
• python3 tools/printables/validate_manifest.py printables/manifests/zacus_v2_printables.yaml
• npm --prefix 'frontend-scratch-v2' run lint
• npm --prefix 'frontend-scratch-v2' run build
• importer/exporter YAML + IR Runtime 3 sans perte fonctionnelle

Regle de handoff entre agents

Chaque ticket passe seulement avec ces evidences:

1. diff des fichiers modifies,
2. commande(s) executee(s) + verdict,
3. limites connues et impacts.