# leadtech-bmad-mcp — Rollout BMAD

Ce document decrit comment `leadtech-bmad-mcp` est branche dans BMAD et ou en est le rollout.

## Statut actuel : Phase 2 partielle (strict cible)

Etat reel a date :

- workflows BMAD `create-story` et `dev-story` appellent les tools en `strict=true`
- personas `dev.md` traite `blocking_issues` comme hard blockers (override humain explicite requis)
- persona `sm.md` exige un acknowledgement humain avant `ready-for-dev` si `blocking_issues` non vide
- 3 blocages automatiques sont effectivement actifs :
  1. `validate_patch` : "Patch sans fichier source: seulement des artefacts BMAD" (regle hardcodee, toujours active)
  2. `validate_patch` : "Session modifiee sans expiresAt visible dans le diff" (toujours active, meme en advisory)
  3. `validate_plan` : "Plan backend sans reference aux contrats partages" (active via `strict=true` dans `dev-story`)

Le reste des regles `gates.yaml` reste advisory : `backend_request_id`, `backend_auth_guard`, `parallel_dependencies`, `test_strategy`, `tests_visible_in_diff`.

Note de coherence interne a traiter : les `_config/agents/*.customize.yaml` invoquent encore `validate_plan(strict=false)` / `validate_patch(strict=false)`. Les workflows `dev-story` les surchargent en `strict=true` au moment de l'execution.

## Objectif

- injecter la guidance Lead_tech au bon moment
- rendre les gates visibles dans les artefacts BMAD
- bloquer automatiquement uniquement les regles a signal fort et faible ambiguite
- garder advisory tout le reste pour observer les faux positifs avant promotion

## Principe

- **strict cible** sur les 3 regles ci-dessus
- **advisory** sur tout le reste
- la decision finale reste humaine, l'override `blocking_issues` est trace dans `Leadtech MCP Gates`

Le MCP doit servir a :

- bloquer automatiquement les anti-patterns recurrents et chers (artefacts BMAD seuls, sessions sans expiresAt, plan backend sans contracts)
- augmenter le niveau de vigilance sur le reste
- homogeneiser la lecture des patterns et risques
- detecter les cas manifestement fragiles

## Points d'injection BMAD

### 1. Analyst — entree de story

Appel recommande :

```txt
get_guidance(domain, task_type="analysis", story_text=...)
```

Sortie a reporter dans la story :

- patterns a appliquer
- risques a eviter
- docs prioritaires a lire

### 2. Builder — avant implementation

Appel actuel (workflow `dev-story`) :

```txt
validate_plan(domain, plan_text, agent_role="builder", strict=true)
```

Regle :

- `blocking_issues` non vide => HALT, le plan doit etre corrige avant implementation
- override humain possible et obligatoirement trace dans `Leadtech MCP Gates`

### 3. Builder — apres diff

Appel actuel (workflow `dev-story`) :

```txt
validate_patch(domain, diff_text, changed_files, strict=true)
```

Regle :

- `blocking_issues` non vide => HALT, correction obligatoire avant statut `review`
- override humain possible et trace dans `Leadtech MCP Gates`

### 4. Reviewer — revue finale

Appels actuels (customize.yaml `bmm-qa`) :

```txt
emit_checklist(agent_role="reviewer", domain, story_text)
validate_patch(domain, diff_text, changed_files, strict=false)
```

Regle :

- en review QA, on reste advisory (`strict=false`) : les blocages auront deja ete pris cote dev
- un `blocking_issues` qui apparaitrait quand meme impose une justification explicite si la PR/story est acceptee

### 5. Curator — apprentissage (flux humain manuel)

Le role Curator n'a **pas d'agent BMAD dedie**. L'apprentissage est ecrit par les autres agents (dev, qa, architect, sm, pm, ux-designer) qui ont tous une `memory` les poussant a ajouter directement dans `95_a_capitaliser.md` quand un apprentissage emerge.

Le triage est execute periodiquement par l'humain via :

- skill `capitalisation-triage` (`skills/capitalisation-triage/SKILL.md`)
- tool MCP `triage_capitalization()` pour la pre-analyse heuristique
- tool MCP `propose_capitalization(..., dry_run=true)` quand l'humain veut formaliser une entree depuis un agent qui ne l'a pas fait spontanement

## Trace minimale a imposer

Chaque story doit contenir une section courte `Leadtech MCP Gates` avec :

- timestamp
- tools appeles
- resume de `must_do`, `red_flags`, `blocking_issues`
- decision humaine prise

Format minimal :

```txt
Leadtech MCP Gates
- 2026-03-31 16:20
- get_guidance / validate_plan / validate_patch
- blocking_issues: 0
- red_flags: AuthGuard non visible dans le diff
- decision: review demandee avant done
```

## Observabilite a suivre

Sur les prochaines 10 a 20 stories, relever :

- nombre de `blocking_issues` automatiques (par regle)
- nombre de faux positifs constates
- nombre de cas ou le MCP a evite une regression reelle
- nombre d'overrides humains et leur justification
- domaines les plus stables (`backend`, `workflow`, etc.)

Le suivi est tenu dans `80_bmad/observability/phase2_log.md`. Voir `80_bmad/observability/README.md` pour le flux operationnel et les criteres de promotion / retour en arriere.

Objectif de stabilisation de la Phase 2 actuelle :

- faux positifs faibles sur les 3 gates strictes deja actives
- vocabulaire compris par les agents BMAD
- section `Leadtech MCP Gates` remplie de facon reguliere
- overrides humains traces et expliques

## Blocages strictes deja actifs

| Regle | Source | Statut |
| --- | --- | --- |
| `Patch sans fichier source: seulement des artefacts BMAD` | `validate_patch` (hardcode `server.py`) | Actif inconditionnellement |
| `Session modifiee sans expiresAt visible dans le diff` | `validate_patch` / `gates.yaml` `backend_session_expires_at` | Actif inconditionnellement |
| `Plan backend sans reference aux contrats partages` | `validate_plan` / `gates.yaml` `backend_contracts` (`strict_only`) | Actif via workflow `dev-story` (`strict=true`) |

## Candidats a promouvoir en Phase 3

Apres observation des metriques ci-dessus, regles potentiellement promouvables si le signal est suffisamment fiable :

- `backend_request_id` (validate_plan/patch) — passer should_do en blocking si formulation des plans suffisamment standardisee
- `backend_auth_guard` (validate_patch) — passer red_flag en blocking si les extraits de diff couvrent generalement les imports

## Ce qu'il ne faut pas promouvoir trop tot

- warning `requestId` sur texte libre si la formulation du plan/diff est trop partielle
- warning `AuthGuard` sur des extraits de diff incomplets
- suggestions de tests si la story est purement documentaire

## Historique de rollout

1. Phase 1 — advisory only sur toutes les stories backend + workflow (achevee, aucune regle bloquante automatique active)
2. Phase 2 — promotion des 3 blocages stricts ci-dessus (statut actuel)
3. Phase 3 — eventuel elargissement apres observation des faux positifs
