Orchestrateur minimal

1Objectif et périmètre

L'étape 2 construit le premier harnais fonctionnel de bout en bout : une demande initiale entre, et des artefacts amont validés (cahier des charges, spécifications, architecture) sortent, enregistrés dans le registre avec traçabilité complète.

1.1 Objectifs

• Prouver le mécanisme central du harnais : cohérence et traçabilité entre artefacts, avant d'étendre aux autres phases.
• Disposer d'une boucle agentique générique (principe 4 de la V3) réutilisable par tous les agents futurs.
• Valider le registre (étape 1) en conditions réelles : métadonnées, statuts, dépendances, historique.
• Mettre en place le point de contrôle humain PC1 (validation du périmètre et du budget) et l'escalade en cas de conflit ou d'échec.

1.2 Inclus dans cette étape

1.3 Hors périmètre (étapes ultérieures)

• Agents Design, Backlog, Code, Tests, Déploiement, Exploitation, Documentation, Décommissionnement (étapes 4→8).
• Interface web, API REST, multi-projets, industrialisation (étape 9).
• Résolution de conflits complète et gestion des échecs avancée — seuls les mécanismes de base sont inclus (retry 2× + escalade).

2Architecture de l'orchestrateur minimal

Le périmètre de l'étape 2 se concentre sur le flux amont : Cadrage → PC1 → Spécifications → Architecture. L'orchestrateur est un simple moteur séquentiel : chaque agent s'exécute, publie dans le registre, puis laisse la main.

2.1 Principe de fonctionnement

1. Réception — l'orchestrateur reçoit la demande initiale (fichier YAML/JSON) et crée le projet dans le registre.
2. Agent Cadrage — génère note d'opportunité, cahier des charges, analyse des risques, estimation ; publie en brouillon, puis passe en en_revue après garde-fous.
3. PC1 — l'orchestrateur suspend le flux ; l'humain approuve, rejette ou amende. Seule l'approbation débloque la suite.
4. Agent Spécifications — génère les specs fonctionnelles puis techniques à partir du cahier des charges validé.
5. Agent Architecture — génère architecture, ADR, modèle de données, choix technologiques à partir des specs.
6. Clôture d'étape — l'orchestrateur régénère la matrice de traçabilité minimale et présente le bilan.

3Composants

3.1 Orchestrateur minimal

• Entrée : commande CLI helios run <demande.yaml> + commandes de contrôle helios approve|reject|amend.
• Séquencement : moteur séquentiel simple (aucun parallélisme à ce stade) qui respecte les dépendances déclarées du registre.
• Registre : opérations de base — create, transition, impact (liste des avals), status.
• Garde-fous : après chaque génération, vérifie (a) conformité au référentiel configuré, (b) présence des métadonnées obligatoires, (c) cohérence terminologique avec les artefacts amont (mots-clés du glossaire).
• Reprise : 2 tentatives (retry) en cas d'échec, puis escalade humaine avec rapport.
• Journalisation : chaque transition est écrite dans l'historique append-only de l'artefact.

3.2 Registre minimal

• Contenu : dépôt Git, arborescence artefacts/<famille>/<type>/ (ex. artefacts/archi/adr/0001-...).
• Métadonnées : base SQLite registre.db, tables artefacts, transitions, dependances, garde_fous — conformes au schéma étape 1.
• Types actifs à ce stade : cadrage.*, spec.*, archi.*, plus config.referentiels et transverse.matrice-tracabilite (dérivée).
• Empreintes : chaque version publiée est horodatée et empreintée (SHA-256) — décision D2.

3.3 Boucle agentique générique

Tous les agents de l'étape 2 partagent la même boucle (principe 4 de la V3), implémentée une seule fois :

4Contrats des trois agents

Chaque agent est défini par un contrat : mission, entrées, sorties, référentiels, garde-fous spécifiques. Le contrat est injecté dans le prompt de l'agent (exigence V3 section 4) et stocké dans le registre comme configuration.

4.1 Agent Cadrage agent:cadrage

4.2 Agent Spécifications agent:specifications

4.3 Agent Architecture agent:architecture

5Séquencement et flux détaillé

Le flux complet de l'étape 2, avec les transitions de statut à chaque étape :

5.1 Propagation d'une modification amont

Scénario de test obligatoire : après validation, le sponsor amende le cahier des charges (transition valide → brouillon sur cadrage.cahier-des-charges). L'orchestrateur doit :

1. Marquer les avals comme impactés : spec.fonctionnelles, spec.techniques, puis archi.* (propagation transitive).
2. Repasser les avals en brouillon (règle R2).
3. Proposer la régénération ciblée : specs puis archi, dans l'ordre des dépendances.
4. Re-soumettre à PC1/PC3 uniquement si le périmètre ou le budget change.

6Point de contrôle humain PC1

PC1 valide le périmètre et le budget (gouvernance V3, section 8). Il s'agit de la première suspension humaine du harnais : c'est ici que se joue la crédibilité du dispositif — l'humain doit vraiment lire, pas cocher.

6.1 Commandes

6.2 Aide à la lecture (anti-formalité)

Pour éviter la dérive « l'humain valide sans lire » (V3 section 8), l'orchestrateur fournit avec chaque artefact soumis :

• un résumé exécutif (3-5 lignes) : périmètre retenu, budget, risques majeurs ;
• les hypothèses et les points ouverts ;
• la différence avec la version précédente si amendement ;
• les garde-fous passés (conformité référentiel, couverture des exigences).

7Pile technique et structure du dépôt

7.1 Pile retenue

7.2 Structure du dépôt

helios/
├── cli.py                  # commandes run/approve/reject/amend/status/regenerate
├── orchestrateur.py        # séquencement, retry, escalade, impact
├── boucle_agent.py         # boucle générique : contexte → plan → génération → auto-vérif → publication
├── registre/
│   ├── git_store.py          # écriture contenu (Git)
│   ├── sqlite_store.py       # métadonnées, transitions, dépendances
│   └── machine_etats.py      # statuts + transitions (annexe A V3)
├── agents/
│   ├── cadrage.py
│   ├── specifications.py
│   └── architecture.py
├── garde_fous.py          # conformité référentiel, cohérence terminologique, couverture
├── referentiels.yaml      # config type ↔ référentiel (étape 1, section 6)
├── tests/                  # pytest : machine à états, registre, garde-fous, orchestration
└── artefacts/             # dépôt Git des contenus, par famille
    ├── cadrage/  spec/  archi/  transverse/

7.3 Modèle de données SQLite (sous-ensemble étape 2)

artefacts(id TEXT PK, type TEXT, version TEXT, statut TEXT,
          auteur TEXT, cree_le TEXT, modifie_le TEXT, valide_le TEXT,
          valide_par TEXT, contenu TEXT, empreinte TEXT, tags TEXT)
transitions(id INTEGER PK, artefact_id TEXT FK, de TEXT, vers TEXT,
             le TEXT, par TEXT, commentaire TEXT)   -- append-only
dependances(artefact_id TEXT FK, lien TEXT, cible TEXT)  -- derive_de / conforme_a / valide_par
garde_fous(artefact_id TEXT FK, verif TEXT, resultat TEXT, detail TEXT)

8Scénario de bout en bout (jeu de test)

Le scénario de validation de l'étape 2, exécuté en conditions réelles avec un petit projet fictif :

8.1 Projet de test : « Gestion de budget personnel »

9Critères de complétude de l'étape 2

L'étape 2 est considérée terminée lorsque :

• C1 — Le scénario de bout en bout (section 8) passe intégralement, y compris amendement et propagation d'impact.
• C2 — Les trois agents produisent des artefacts conformes à leurs contrats (section 4), vérifiés par les garde-fous.
• C3 — Le registre (Git + SQLite) implémente le schéma de l'étape 1 : métadonnées complètes, historique append-only, dépendances déclarées.
• C4 — PC1 et PC3 sont opérationnels (approve/reject/amend) et journalisent qui/quand/commentaire.
• C5 — La matrice de traçabilité minimale est régénérée mécaniquement et couvre les liens exigences → specs → archi.
• C6 — La suite pytest du harnais couvre : machine à états, registre, garde-fous, orchestration (≥ 90 % de couverture sur ces modules).
• C7 — Un README d'installation et d'utilisation du harnais minimal existe (Diátaxis : guide).

10Décisions à valider

Ce livrable introduit des choix de conception à confirmer avant implémentation (point de contrôle humain de l'étape 2).

Validation — 1 août 2026. Décisions D6 → D10 toutes validées par Hugues (point de contrôle humain de l'étape 2). Les choix retenus sont signalés en gras dans le tableau ci-dessous. Ce document passe au statut Validé — l'implémentation de l'étape 2 démarre.