# leadtech-bmad-mcp — Plan d'implementation

Ce document sert de **plan de chantier vivant** pour transformer le prototype actuel en MCP propre, stable et exploitable dans BMAD.

Mode d'usage :

- cocher les taches terminees
- mettre a jour le statut des lots en debut/fin de session
- ajouter les decisions structurantes dans `40_decisions_et_archi.md` si besoin
- garder ici le suivi operationnel, pas les longues explications

---

## Vue d'ensemble

| Lot | Objectif | Statut |
| --- | --- | --- |
| Lot 1 | Contrat MCP v1 + metadonnees `knowledge` + compatibilite loader | Termine |
| Lot 2 | Index compile local + branchement de la recherche MCP dessus | Termine |
| Lot 3 | Gates configurables + packaging + rollout BMAD | Termine |

---

## Lot 1 — Contrat v1 et base structuree

### Objectif

Stabiliser le contrat du MCP et preparer un corpus `knowledge/` assez structure pour servir de base au futur index.

### Livrables

- [x] Documenter le contrat MCP v1
- [x] Documenter le format de front matter `knowledge/`
- [x] Ajouter la lecture du front matter dans le loader
- [x] Exposer un champ structure `matched_docs` dans `get_guidance`
- [x] Ajouter des tests sur le parsing des metadonnees
- [x] Annoter un premier noyau de documents critiques

### Noyau pilote vise

- [x] `knowledge/backend/patterns/auth.md`
- [x] `knowledge/backend/patterns/contracts.md`
- [x] `knowledge/backend/patterns/nestjs.md`
- [x] `knowledge/backend/patterns/prisma.md`
- [x] `knowledge/backend/risques/auth.md`
- [x] `knowledge/backend/risques/contracts.md`
- [x] `knowledge/backend/risques/nestjs.md`
- [x] `knowledge/backend/risques/prisma.md`
- [x] `knowledge/frontend/patterns/navigation.md`
- [x] `knowledge/frontend/patterns/tests.md`
- [x] `knowledge/frontend/risques/navigation.md`
- [x] `knowledge/frontend/risques/tests.md`
- [x] `knowledge/workflow/risques/story-tracking.md`

### Reste a faire avant cloture complete du lot

- [x] Verifier si `knowledge/backend/patterns/prisma.md` doit aussi entrer dans le noyau pilote
- [x] Verifier si `knowledge/frontend/risques/tests.md` doit aussi entrer dans le noyau pilote
- [x] Faire un commit de cloture explicite du Lot 1

### Critere de fin

- le contrat v1 est stable
- un noyau representatif de docs critiques est structure
- la recherche MCP sait exploiter les metadonnees sans casser le comportement existant

---

## Lot 2 — Index compile local

### Objectif

Remplacer le scan Markdown a la volee par un index local plus rapide, plus fiable et plus facile a faire evoluer.

### Taches

- [x] Definir le format de l'index (JSON d'abord)
- [x] Creer un script de build d'index
- [x] Indexer les docs `knowledge/*`
- [x] Indexer les docs globaux `10_*`, `40_*`, `90_*`
- [x] Prevoir un mode fallback si l'index n'existe pas
- [x] Rebrancher `search_knowledge()` sur l'index
- [x] Rebrancher `search_global_docs()` sur l'index
- [x] Ajouter des tests d'integration sur un mini corpus indexe

### Livrables attendus

- `src/leadtech_bmad_mcp/indexer.py`
- un artefact d'index local regenerable (`.leadtech_mcp_index.json`)
- documentation de rebuild

### Critere de fin

- les tools de recherche utilisent d'abord l'index
- le fallback texte brut reste disponible pour ne pas bloquer le dev
- le rebuild est documente et teste

---

## Lot 3 — Gates configurables et industrialisation

### Objectif

Sortir les regles du code dur, rendre l'installation reproductible, puis cabler proprement le rollout BMAD.

### Taches

- [x] Extraire les gates dans une config versionnee
- [x] Distinguer advisory et blocking dans la config
- [x] Ajouter des tests sur les faux positifs/faux negatifs des gates
- [x] Stabiliser l'installation `pip install -e ".[dev]"`
- [x] Ajouter une doc machine vierge / quickstart
- [x] Preparer un rollout BMAD advisory
- [x] Definir 2-3 blocages stricts seulement apres validation

### Livrables attendus

- `config/gates.yaml`
- `docs/quickstart_dev_local.md`
- `docs/rollout_bmad_advisory.md`

### Critere de fin

- modifier une regle ne demande plus un patch Python
- une autre machine peut installer et lancer le serveur sans bricolage
- BMAD sait quand appeler quels tools et comment interpreter leur sortie

---

## Journal de progression

### 2026-03-31

- Lot 1 demarre
- contrat `mcp_v1.md` ajoute
- convention `knowledge_metadata.md` ajoutee
- loader front matter ajoute
- `matched_docs` ajoute a `get_guidance`
- noyau pilote annote sur backend, frontend et workflow
- Lot 2 implemente
- index JSON local `.leadtech_mcp_index.json` ajoute au design
- `search_knowledge()` et `search_global_docs()` relis d'abord sur l'index avec fallback scan
- script `leadtech-bmad-build-index` ajoute
- tests d'integration indexes ajoutes
- commit explicite de cloture Lot 1 + Lot 2: `bafc872`
- Lot 3 demarre
- gates textuelles extraites dans `config/gates.yaml`
- distinction advisory / blocking portee par la config
- chargeur `gates.py` ajoute avec override `LEADTECH_GATES_CONFIG`
- couverture de tests gates et serveur etendue
- install `pip install -e ".[dev]"` reverifiee sur venv propre
- quickstart local ajoute
- procedure de rollout BMAD advisory ajoutee
- shortlist de 3 blocages stricts recommandes documentee

---

## Regles de maintenance de ce plan

- un lot passe a `Termine` uniquement quand son critere de fin est satisfait
- une case ne se coche pas si le code est seulement commence
- si un arbitrage durable apparait, l'inscrire aussi dans `40_decisions_et_archi.md`
