SDEG Kernel — le code comme modèle du domaine

1. Intention

Le projet vise un système de développement logiciel génératif. Son postulat : le besoin utile n'est jamais donné à l'avance — il se découvre par itération. Le logiciel n'est pas la réponse à une spécification ; il est le moyen d'éprouver une hypothèse de valeur.

La posture épistémique est herméneutique : chaque cycle de conception est une lecture du besoin, qui modifie la compréhension du besoin lui-même. L'objectif n'est pas la conformité à un cahier des charges, mais l'obtention rapide d'une solution minimale utilisable et utile, dont l'usage révèle la prochaine question.

Pour soutenir cette démarche, le noyau sdeg-kernel fait trois choses :

1. Il matérialise le domaine en code. La machine d'états (schema.js) est la définition exécutable du cycle de décision. Lire le code, c'est lire le modèle.
2. Il sépare strictement ce qui est décidé de ce qui est en cours. Tout artefact est soit LIVING (mutable), soit COLD (figé). Une porte franchie gèle le passé ; on n'y revient pas, on ouvre un nouveau grain.
3. Il délègue la production à l'IA, garde la décision à l'humain. Les agents produisent les artefacts, le CLI fait avancer les états. Seul un humain déclenche une transition.

2. Vue d'ensemble du kernel

Le kernel est un petit outil Node.js (~1 200 lignes, sans dépendance externe) qui combine trois briques :

Arborescence

sdeg-kernel/
├── sdlc/                  ← noyau déterministe
│   ├── schema.js            machine d'états (SSOT)
│   ├── validators.js        12 validateurs purs
│   ├── evaluator.js         moteur de verdict (GO / NEEDS-REVIEW / NO-GO)
│   ├── sdlc.js              CLI — seul mutateur d'état
│   ├── frontmatter.js       parser YAML minimal
│   ├── install-hooks.js     installeur git pre-commit
│   ├── SDLC.md              doc humaine de la machine
│   └── __tests__/           58 tests (node:test)
├── .github/
│   ├── agents/            ← 1 mode agent "Coach"
│   └── prompts/           ← 16 assistants spécialisés
├── meta/
│   └── template-eo.md       modèle d'Étude d'Opportunité
├── scripts/               ← hooks PowerShell (session, safety)
├── docs/
│   ├── specs/               specs d'implémentation (ex : vague 3)
│   └── as-is/               cette description (modèle as-is)
├── README.md · GUIDE.html · LICENSE

3. Le domaine, tel qu'il est nommé

Le kernel distingue trois types d'objets et cinq méta-états. C'est la totalité du vocabulaire formel.

Types d'objets (schema.js:TYPES)

La filiation est obligatoire descendante et vérifiée à la création par le CLI (sdlc.js:PARENT_RULES, ligne 276). Un objet en statut terminal (TERMINE, PIVOTED, LIVRE, ARCHIVED, VALIDE) ne peut plus servir de parent à un nouvel objet.

Méta-états (schema.js:META)

4. La machine d'états

Chaque type a son propre graphe de statuts. Les arêtes (transitions) portent le nom de la porte décisionnelle, les prérequis humains, les artefacts gelés, et — optionnellement — des invariants et checks exécutables.

Business Epic — 10 statuts

NOT_STARTED ──P1──▶ REVUE_BUSINESS ──P2──▶ CADRAGE_EN_COURS ──P3──▶ FABRICATION_MVP
                                                                       │
                                                                       ▼
                                                      REVUE_MVP ──P10──▶ TERMINE
                                                           ├─────────▶ PERSEVERE ──▶ (nouveau cycle)
                                                           └─────────▶ PIVOTED
       BLOCKED et ARCHIVED accessibles depuis la plupart des statuts intermédiaires.

Feature — 8 statuts

NOT_STARTED ──P4──▶ ANALYSE ──P4-DOR──▶ PRET_FABRICATION ──Sprint──▶ FABRICATION
                                                                         │
                                                                         ▼
                                                           VALIDATION ──P8──▶ PRET_LIVRAISON
                                                                                   │
                                                                                   ▼
                                                                       DEPLOIEMENT ──P9──▶ LIVRE

Récit — 8 statuts

NOT_STARTED ──P5-start──▶ AFFINAGE ──P5-DOR──▶ PRET_DOR ──▶ DEV ──P6-PR──▶ DEV_TERMINE
                                                                                   │
                                                                                   ▼ Démo PO
                                                                       VALIDATION ──P6-DoD──▶ VALIDE
                                                                              │
                                                                              └───▶ DEV (defect)

La liste complète se trouve en annexe. Les transitions sont définies dans schema.js:TRANSITIONS (lignes 105-536). Chaque entrée a la forme :

{
  gate:          "P4-DOR — DOR Feature",
  preconditions: [ ... liste humaine ... ],   // checklist affichée au move
  freeze:        [ ... ],                     // libellés des artefacts gelés
  invariants:    [ { kind, id, ...params } ], // vérifications parent-enfant
  checks:        [ { kind, id, path, ... } ], // vérifications fichiers
}

5. Portes et verdicts

Une transition est évaluée en trois temps par evaluator.js:evaluateGate :

1. Construire le contexte (buildContext) : résoudre parent et enfants dans le registre.
2. Exécuter les invariants puis les checks dans l'ordre, chacun via son validateur (runOne).
3. Agréger les résultats et calculer un verdict (computeVerdict).

Règle de verdict

État de couverture (après vague 3)

14 / 42 portes automatisées à ce jour.

6. La bibliothèque de validateurs

Les validateurs sont des fonctions pures (spec, ctx) → CheckResult. Ils ne mutent rien, ne font pas d'appel réseau, lisent uniquement le système de fichiers. Ils sont enregistrés dans l'objet VALIDATORS (validators.js:246).

Checks fichier

Checks frontmatter (YAML en tête de fichier)

Invariants parent-enfant

Deux utilitaires clés

• interpolate(template, obj) — substitue {id}, {type}… dans un chemin, l'id étant forcé en minuscule.
• safeResolve(projectRoot, relPath) — résout un chemin relatif et renvoie { abs, inside, relPath }. Depuis la vague 3, un chemin hors projet ne jette plus d'erreur : les validateurs retournent warn (verdict NEEDS-REVIEW), l'humain arbitre via move --force.

7. CLI et registre

sdlc/sdlc.js est le seul mutateur d'état autorisé. Toute modification directe de sdlc-registry.json est une violation (le hook git pre-commit détecte les incohérences).

Commandes

Traces persistées

.product/
├── sdlc-registry.json              état courant + history[] par objet
└── .events/
    └── YYYY-MM-DD-sdlc-<id>-<to>.md   un fichier par transition, commité

Chaque entrée d'history contient : from, to, date, gate, message, frozen[], forced, et — si la porte était automatisée — un checks_snapshot[] complet avec le verdict.

8. La boucle IA / déterministe

Le kernel orchestre deux régimes de travail qui ne se remplacent pas :

┌──────────────── DÉTERMINISTE ─────────────────┐
│  sdlc.js (état)   schema.js (forme)           │
│  evaluator.js (verdict)  hooks (rituels)      │
│                                               │
│   · impose la forme                           │
│   · garde la mémoire                          │
│   · bloque si incohérence                     │
└────────────────────┬──────────────────────────┘
                     │  fournit le contexte
                     ▼
┌──────────────── GÉNÉRATIF (IA) ───────────────┐
│  coach-emergent (orchestrateur)               │
│  16 #assistants (producteurs d'artefacts)     │
│                                               │
│   · explore le besoin                         │
│   · rédige l'artefact LIVING                  │
│   · ne fait JAMAIS avancer un état            │
└───────────────────────────────────────────────┘

Conséquence pratique : l'IA écrit dans les fichiers .md du projet (EHS, LBC, story…). Le CLI lit ces fichiers via les validateurs, calcule un verdict, et seul un humain décide de faire bouger le statut.

Ce partage est intentionnel. La génération rapide par l'IA crée la matière de l'hypothèse ; la machine d'états crée la forme de la décision. L'un sans l'autre, ça dérape vers soit un bureaucratie sans substance, soit un flot d'idées sans traçabilité.

9. Lecture pour audit et conformité

Cette section est un parcours de revue. Chaque étape identifie un fichier, ce qu'on y cherche, et un critère de conformité.

10. Perspectives — ce qu'on observe, sans rien changer

Cette section décrit les tensions visibles dans le code tel qu'il est. Elle ne propose pas de correction ; elle rend lisible ce que le modèle actuel fait vivre.

10.1 — Héritage lexical d'une gouvernance d'entreprise

Les portes s'appellent P1 à P10, avec des prérequis comme « Décision COMEX tracée », « Enveloppe budgétaire confirmée par sponsor », « PI planning », « accord homologation ». Ce vocabulaire suppose un contexte d'organisation structuré (sponsor, COMEX, filière pilote, architecture d'entreprise). Dans un contexte différent — équipe autonome, produit émergent, cycle court — certaines portes sont vides de sens, d'autres manquent.

10.2 — Granularité fixe BE / FE / US

La hiérarchie est imposée à 3 niveaux obligatoires avec filiation stricte (PARENT_RULES). Pour un produit naissant où la valeur n'est pas encore découpée en PIs, cette structure force un habillage artificiel. À l'inverse, pour un système complexe, elle peut être trop plate (pas de notion de composant, de capability, de thème).

10.3 — 10 portes, ~42 transitions, 14 automatisées

Le ratio est significatif : un tiers des portes sont réellement exécutables. Les deux autres tiers sont des checklists humaines, utiles pour guider mais sans garde-fou machine. Ce déséquilibre reflète une hypothèse implicite : la plupart des décisions ne sont pas mécanisables. C'est peut-être vrai, peut-être le signe qu'il manque des invariants encore non formulés.

10.4 — Tension entre « minimal utile » et « 10 portes »

L'intention du système est d'aboutir vite à une solution minimale utilisable. Le chemin le plus court dans la machine d'états pour livrer une FE est :
BE.NOT_STARTED → REVUE_BUSINESS → CADRAGE_EN_COURS → FABRICATION_MVP
puis pour une FE : NOT_STARTED → ANALYSE → PRET_FABRICATION → FABRICATION → VALIDATION → PRET_LIVRAISON → DEPLOIEMENT → LIVRE,
soit 10+ transitions humaines avant un premier déploiement. La rapidité recherchée est donc pour l'instant tributaire de la discipline humaine à ne pas sur-instrumenter les premières itérations.

10.5 — L'IA produit, l'humain décide, mais le modèle du besoin est à l'humain

Les assistants IA (16 prompts spécialisés) couvrent la production (rédiger une EHS, découper en features, écrire une story TDD). Aucun n'est chargé de remettre en cause l'hypothèse, de proposer un grain différent, ou de détecter une incohérence épistémique. La boucle herméneutique — lecture du besoin qui modifie la compréhension du besoin — repose entièrement sur l'humain et sur le Coach.

10.6 — COLD irréversible, donc tout nouveau cycle est coûteux

La règle LIVING/COLD est forte : un artefact gelé ne se modifie pas. Si la compréhension du besoin change, il faut ouvrir un nouveau grain (pivot, persévère, nouvelle BE). Cela protège la traçabilité, mais rend chaque pivot coûteux en fichiers, en références, en registre. Un mode fork d'artefact ou un mécanisme de cycle N+1 explicite n'existe pas aujourd'hui ailleurs que dans la transition REVUE_MVP → PERSEVERE → FABRICATION_MVP.

Annexe A — Fichiers du kernel

Annexe B — Toutes les transitions

BE — Business Epic

FE — Feature

US — Récit