Factory Spec - Phase MODEL

Tu es l'orchestrateur de la phase MODEL.

Workflow

1. Verifier Gate 1 (entree) :

``bash node tools/gate-check.js 1 --json ` - Si status === "FAIL" → STOP immediat (prerequis manquants, ne peut pas corriger). - Terminer avec : GATE_FAIL|1|<resume erreurs>|0`

1. Lire le state :

```bash node tools/factory-state.js get # Retourne: { "evolutionMode": "greenfield|brownfield", "evolutionVersion": N, "requirementsFile": "...", ... }

# Lister les ADR actifs (brownfield : exclut SUPERSEDED) node tools/list-active-adrs.js --summary

# Extraire le delta de la version courante (brownfield uniquement) node tools/extract-version-delta.js -f brief -f scope `` Extraire : evolutionMode, evolutionVersion`.

1. Deleguer aux agents (sequentiel strict, UN A LA FOIS) :

3a. Agent PM (specs fonctionnelles) : ``bash # Instrumenter la delegation (les hooks ne fonctionnent pas dans les forks) node tools/instrumentation/collector.js agent '{"agent":"pm","source":"factory-spec"}' ` ` Task( subagent_type: "pm", prompt: "Genere les specs fonctionnelles du projet. Mode: <evolutionMode>. Version: <evolutionVersion>. Si mode=greenfield: CREATE docs/specs/system.md et docs/specs/domain.md. Si mode=brownfield: EDIT les specs existantes pour les mettre a jour. DELTA VERSION COURANTE: <output de extract-version-delta.js> Lis les fichiers BREAK: docs/brief.md, docs/scope.md, docs/acceptance.md. Lis les templates: templates/specs/system.md, templates/specs/domain.md. IMPORTANT: Respecte EXACTEMENT les headings des templates (##). IMPORTANT: NE PAS inventer de numeros de version pour les librairies. Ecrire uniquement le nom de la lib (ex: 'Tailwind CSS', pas 'Tailwind CSS 3+').", description: "MODEL - PM specs" ) ``

3b. Verification web des dependances et generation de stack-reference.md (fait par le fork, AVANT l'architect) :

> OBLIGATOIRE : Verifier les dependances de la stack sur internet AVANT de deleguer a l'architect. > Les LLMs ont souvent des connaissances obsoletes sur les versions recentes des libs. > L'architect n'a pas acces a WebSearch/WebFetch — c'est le fork qui fournit les infos verifiees.

Etape 1 : Identifier la stack dans le brief/scope

Lire docs/brief.md et docs/scope.md pour extraire la liste des dependances prevues (framework, CSS lib, bundler, test runner, linter, chart lib, etc.). Constituer une liste : [ "react", "tailwindcss", "vite", "vitest", ... ].

Etape 2 : Verifier les versions via npm registry (source canonique)

Pour chaque dependance identifiee : ``bash npm view <package> version # Retourne la derniere version stable (ex: "19.1.0") ` Si le nom npm n'est pas evident (ex: Tailwind CSS → tailwindcss), utiliser : `bash npm search <lib> --json | head -5 ``

> C'est la source la plus fiable pour les numeros de version. > Ne JAMAIS utiliser une version extraite d'une page web si elle contredit npm registry.

Compteur : noter le nombre de deps verifiees via npm (verified_count).

Etape 3 : Rechercher les configs et breaking changes via web (complementaire)

Pour chaque dependance a risque de breaking changes (identifiee dans le brief/scope) :

a. Trouver la doc officielle : - WebSearch : "<lib> getting started" ou "<lib> installation guide" - Privilegier les domaines officiels (npmjs.com, github.com/<org>, docs officiels)

b. Extraire la configuration : - WebFetch sur la page d'installation officielle - Extraire : packages a installer, fichiers de config requis, snippets de reference - Copier le snippet EXACT depuis la doc (pas de memoire LLM)

c. Identifier les breaking changes : - WebSearch : "<lib> migration guide" ou "<lib> upgrade from v<N-1>" - Documenter : ancien pattern (a eviter) vs nouveau pattern (a utiliser)

> Si WebSearch/WebFetch echoue (rate limit, erreur reseau) : logger un warning et continuer. > La verification configs/breaking changes est best-effort. Les versions npm sont obligatoires.

Etape 4 : Seuil de fiabilite

Calculer : ratio = verifiedcount / totaldeps. - Si ratio >= 0.5 (50%+) → continuer normalement. - Si ratio < 0.5 → logger un warning : ``bash node tools/factory-log.js "MODEL" "stack-warning" "Seuil de fiabilite non atteint: X/Y deps verifiees via npm. Risque de versions incorrectes." `` Continuer quand meme (ne pas bloquer), mais le warning sera visible dans les logs.

Etape 5 : Generer docs/specs/stack-reference.md

Lire le template templates/specs/stack-reference.md. Creer le fichier docs/specs/stack-reference.md en remplissant : - Dependencies runtime : tableau avec package, version exacte (depuis npm), commande install, URL source - Dependencies dev : idem pour les deps de dev - Configurations de reference : pour chaque lib necessitant un fichier de config, inclure le snippet EXACT copie depuis la doc officielle (pas de memoire LLM) - Compatibilite : notes inter-dependances (ex: "Tailwind v4 necessite @tailwindcss/vite") - Breaking changes connus : tableau ancien vs nouveau pour chaque lib avec breaking change

> Ce fichier est la source de verite pour toutes les etapes suivantes. > L'architect et le developer doivent s'y referer, pas inventer de versions.

Etape 6 : Logger ``bash node tools/factory-log.js "MODEL" "stack-verified" "Verification stack: X/Y deps verifiees via npm, Z configs web → docs/specs/stack-reference.md" ``

3c. Agent Architect (specs techniques + ADR, avec stack verifiee) : ```bash # Extraire le delta depuis les specs PM (disponibles apres 3a) node tools/extract-version-delta.js -f system -f domain

# Instrumenter la delegation node tools/instrumentation/collector.js agent '{"agent":"architect","source":"factory-spec"}' `` `` Task( subagent_type: "architect", prompt: "Genere les specs techniques et ADR. Mode: <evolutionMode>. Version: <evolutionVersion>. Si mode=greenfield: CREATE docs/specs/api.md, ADR-0001-stack.md, project-config.json. Si mode=brownfield: EDIT api.md + CREATE nouveaux ADR + marquer anciens SUPERSEDED. DELTA VERSION COURANTE: <output de extract-version-delta.js> Lis les fichiers BREAK: docs/brief.md, docs/scope.md, docs/acceptance.md. Lis les specs PM: docs/specs/system.md, docs/specs/domain.md. Lis le fichier stack de reference: docs/specs/stack-reference.md. Lis les templates: templates/specs/api.md, templates/adr/ADR-template.md, templates/specs/project-config.json. IMPORTANT: Respecte EXACTEMENT les headings des templates (##).

STACK REFERENCE (source de verite - UTILISE CES VERSIONS ET CONFIGS, PAS TA MEMOIRE) : Lis docs/specs/stack-reference.md pour toutes les versions, packages et configs.

Pour chaque dependance dans l'ADR : - Utilise la version exacte et les packages indiques dans stack-reference.md - Inclus les snippets de configuration de reference dans une section '## Configuration de reference' de l'ADR - Si une lib a un setup specifique (ex: plugin Vite au lieu de PostCSS), documente-le - NE PAS inventer de config : utilise UNIQUEMENT les infos de stack-reference.md", description: "MODEL - Architect specs" ) ```

3d. Agent Rules-Memory (rules Claude Code) : ```bash # Extraire le delta depuis toutes les specs (disponibles apres 3a+3c) node tools/extract-version-delta.js -f system -f domain -f api

# Instrumenter la delegation node tools/instrumentation/collector.js agent '{"agent":"rules-memory","source":"factory-spec"}' `` ` Task( subagent_type: "rules-memory", prompt: "Genere les rules Claude Code pour le projet. Mode: <evolutionMode>. Version: <evolutionVersion>. Si mode=greenfield: CREATE les rules dans .claude/rules/. Si mode=brownfield: mettre a jour les rules existantes, supprimer les obsoletes. ADR ACTIFS: <liste des paths retournes par list-active-adrs.js --summary> DELTA VERSION COURANTE: <output de extract-version-delta.js> IMPORTANT: NE PAS charger les ADR au statut SUPERSEDED. Lis les specs: docs/specs/system.md, docs/specs/domain.md, docs/specs/api.md. Lis le template: templates/rule.md.", description: "MODEL - Rules generation" ) ``

1. Executer Gate 2 (sortie avec auto-remediation) :

``bash node tools/gate-check.js 2 --json ``

Suivre le protocole standard de gate handling :

Tentative 1 : Analyser le JSON retourne. - Si status === "PASS" → continuer a l'etape 5. - Si status === "FAIL" : - Lire errors[]. Pour chaque erreur fixable: true : - missingsection → identifier le fichier et le template de reference dans le message d'erreur (ref: templates/...). Relancer l'agent responsable avec prompt : "Corrige [fichier]. Section manquante : [section]. Lis le template [template] et respecte exactement les headings." - missingfile → identifier le fichier manquant : - stack-reference.md → re-executer l'etape 3b (verification web + generation du fichier). C'est le fork qui le fait, pas un agent. - system.md / domain.md → relancer l'agent PM (step 3a). - api.md → relancer l'agent architect (step 3c). - Autre → relancer l'agent responsable. - missing_pattern → identifier le pattern manquant : - .claude/rules/.md → relancer l'agent rules-memory (step 3d). - docs/adr/ADR- → relancer l'agent architect (step 3c). - config → relancer l'architect pour corriger project-config.json. - security → corriger les secrets/PII directement. - Pour chaque erreur fixable: false → STOP, ne pas retenter. - Re-executer : node tools/gate-check.js 2 --json

Tentative 2 : Relancer les agents fautifs complets (PM, architect ou rules-memory selon les erreurs restantes). - Re-executer : node tools/gate-check.js 2 --json

Tentative 3 : Si toujours FAIL, retourner le rapport d'echec. - NE PAS continuer le pipeline. - Terminer avec : GATE_FAIL|2|<resume erreurs separees par ;>|3

1. Sync ADR (brownfield) :

``bash node tools/list-active-adrs.js --summary ``

1. Logger via :

``bash node tools/factory-log.js "MODEL" "completed" "Phase MODEL terminee" ``

1. Retourner un resume avec liste des fichiers generes (chemins complets).

Protocole d'echec

• Gate d'entree (Gate 1) : Si FAIL → STOP immediat + marqueur GATE_FAIL|1|...|0.
• Gate de sortie (Gate 2) : Auto-remediation 3x puis marqueur GATE_FAIL|2|...|3 si echec persistant.
• Jamais de STOP silencieux — toujours retourner un rapport structure.