diff --git a/40_decisions_et_archi.md b/40_decisions_et_archi.md index 9a851fb..909413b 100644 --- a/40_decisions_et_archi.md +++ b/40_decisions_et_archi.md @@ -31,6 +31,7 @@ Dernière mise à jour : 2026-03-12 - [Single source of truth des contrats — schémas runtime partagés (Zod) + z.infer (No-DTO)](#decision-contrats-sso-zod) - [User views — User public par défaut + MeUser explicite](#decision-user-views) - [Mono-tenant déployable vs SaaS multi-tenant](#decision-mono-tenant-deployable) +- [Rollout MCP Lead_tech dans BMAD — Phase 2 partielle (strict ciblé)](#decision-mcp-rollout-phase-2) ### 2. Infra @@ -336,6 +337,47 @@ Pour un projet dont la cible est constituée de clients indépendants qui veulen --- + + +## Rollout MCP Lead_tech dans BMAD — Phase 2 partielle (strict ciblé) + +- Date : 2026-05-07 +- Statut : Accepted +- Périmètre : global / outillage agents + +### Contexte + +Le serveur `leadtech-bmad-mcp` (sidecar BMAD) a été conçu pour un rollout en 3 phases : Phase 1 advisory only, Phase 2 blocages stricts ciblés, Phase 3 élargissement. À l'origine (`docs/rollout_bmad_advisory.md`), la Phase 1 devait durer 10 à 20 stories pour observer les faux positifs avant toute promotion. + +À l'inspection (audit santé du chantier `mcp_v1`), l'implémentation réelle est en avance sur la doc : les workflows BMAD `dev-story` et `create-story` appellent les tools en `strict=true`, et les personas `dev.md` et `sm.md` traitent `blocking_issues` comme hard blockers nécessitant override humain. La doc rollout disait l'inverse. + +### Options envisagées + +- **Aligner l'implémentation sur la doc** : revert workflows à `strict=false`, retirer les HALT des personas. Reste en pure Phase 1. +- **Aligner la doc sur l'implémentation** : déclarer Phase 2 partielle, lister précisément les blocages stricts actifs, et garder le reste en advisory. +- **Voie médiane** : créer une Phase 1.5 transitoire avec critères chiffrés de promotion. + +### Décision + +Aligner la doc sur l'implémentation : **déclarer Phase 2 partielle** avec 3 blocages stricts actifs et le reste en advisory. + +### Justification + +- Les 3 blocages effectivement actifs (artefacts BMAD seuls, sessions sans expiresAt, plan backend sans contracts) sont **précisément les 3 candidats Phase 3 de la doc d'origine** — donc le saut Phase 1 → Phase 2 reflète une décision de fond cohérente. +- Le signal de ces 3 règles est fort et la formulation textuelle est faiblement ambiguë. +- Override humain explicite préservé sur tout `blocking_issues`, donc pas de blocage rigide. +- Coût d'observation Phase 1 considéré comme dépensable a posteriori sur les 10-20 prochaines stories. + +### Conséquences + +- `docs/rollout_bmad_advisory.md` reflète la Phase 2 partielle et liste les 3 blocages actifs avec leurs sources (hardcode `server.py` + `gates.yaml`). +- `80_bmad/integration_mcp_sidecar.md` aligné sur le même statut. +- Statut `mcp_v1.md` et `mcp/leadtech_bmad_mcp/README.md` ajustés. +- Incohérence interne résiduelle à traiter : les `_config/agents/*.customize.yaml` invoquent encore `strict=false`, surchargés par les workflows en `strict=true`. À aligner si besoin de cohérence stricte. +- Observabilité Phase 2 : suivi du nombre de blocages, faux positifs, overrides humains sur les 10-20 prochaines stories avant éventuelle Phase 3. + +--- + ## 2. Infra diff --git a/80_bmad/integration_mcp_sidecar.md b/80_bmad/integration_mcp_sidecar.md index 933b155..74ba4aa 100644 --- a/80_bmad/integration_mcp_sidecar.md +++ b/80_bmad/integration_mcp_sidecar.md @@ -18,26 +18,31 @@ Ce document decrit le cablage du serveur MCP `leadtech-bmad-mcp` dans BMAD. - `Gates de validation` 2. Pre-implementation (Builder) -- Appel: `validate_plan(domain, plan_text, agent_role="builder")` -- Regle: pas d'implementation tant que `blocking_issues` n'est pas vide. +- Appel: `validate_plan(domain, plan_text, agent_role="builder", strict=true)` +- Regle: HALT si `blocking_issues` non vide, override humain trace. 3. Post-patch (Builder) -- Appel: `validate_patch(domain, diff_text, changed_files)` -- Resultat ajoute au Dev Agent Record. +- Appel: `validate_patch(domain, diff_text, changed_files, strict=true)` +- Regle: HALT avant statut `review` si `blocking_issues` non vide. +- Resultat ajoute au Dev Agent Record et a `Leadtech MCP Gates`. 4. Review (Reviewer) - Appel: `emit_checklist(agent_role="reviewer", domain, story_text)` +- Appel: `validate_patch(domain, diff_text, changed_files, strict=false)` (advisory, le blocage a deja eu lieu cote dev). - Option: relancer `validate_patch` sur le diff final de PR. 5. Cloture et apprentissage (Curator) - Appel: `propose_capitalization(...)` en `dry_run=true` par defaut. - Revue periodique: `triage_capitalization()`. -## Mode de rollout recommande +## Statut de rollout -- Phase 1: advisory only (aucun blocage automatique) -- Phase 2: blocage sur `blocking_issues` uniquement -- Phase 3: rules strictes sur domaines critiques (backend auth/contracts/sessions) +- Phase 1 (advisory only): achevee. +- Phase 2 (3 blocages stricts cibles): **statut actuel**. + - `validate_patch`: patch sans fichier source = artefacts BMAD seuls. + - `validate_patch`: sessions sans expiresAt visible. + - `validate_plan`: plan backend sans reference aux contrats partages. +- Phase 3 (elargissement): a evaluer apres observation des faux positifs sur 10 a 20 stories. Documents operationnels associes : diff --git a/mcp/leadtech_bmad_mcp/README.md b/mcp/leadtech_bmad_mcp/README.md index 76e5a3a..165785c 100644 --- a/mcp/leadtech_bmad_mcp/README.md +++ b/mcp/leadtech_bmad_mcp/README.md @@ -2,7 +2,7 @@ Serveur MCP **sidecar** pour brancher la base Lead_tech dans un workflow BMAD sans remplacer BMAD. -Etat actuel : **prototype exploitable** pour un rollout advisory. +Etat actuel : **Phase 2 partielle** — 3 blocages stricts cibles actifs sur les workflows `dev-story` et `create-story`, advisory sur le reste. Voir `docs/rollout_bmad_advisory.md`. Documents de référence phase 1 : diff --git a/mcp/leadtech_bmad_mcp/docs/mcp_v1.md b/mcp/leadtech_bmad_mcp/docs/mcp_v1.md index f75bcd5..55ff532 100644 --- a/mcp/leadtech_bmad_mcp/docs/mcp_v1.md +++ b/mcp/leadtech_bmad_mcp/docs/mcp_v1.md @@ -18,7 +18,7 @@ Objectif : - Nom logique : `leadtech-bmad-mcp` - Version de contrat : `v1` -- Statut : advisory-first +- Statut : Phase 2 partielle — 3 blocages stricts cibles + advisory sur le reste (voir `rollout_bmad_advisory.md`) ## Outils v1 diff --git a/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md b/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md index 9830fea..e4ae28a 100644 --- a/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md +++ b/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md @@ -1,25 +1,41 @@ -# leadtech-bmad-mcp — Rollout BMAD advisory +# leadtech-bmad-mcp — Rollout BMAD -Ce document decrit comment brancher `leadtech-bmad-mcp` dans BMAD sans introduire de blocage automatique au demarrage. +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 -- observer les faux positifs avant d'activer des blocages stricts +- bloquer automatiquement uniquement les regles a signal fort et faible ambiguite +- garder advisory tout le reste pour observer les faux positifs avant promotion ## Principe -Phase de depart : +- **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` -- **advisory only** -- aucune story ne s'arrete automatiquement sur la seule base du MCP -- la decision finale reste humaine +Le MCP doit servir a : -Le MCP doit d'abord servir a : - -- augmenter le niveau de vigilance -- homogeniser la lecture des patterns et risques +- 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 @@ -40,43 +56,43 @@ Sortie a reporter dans la story : ### 2. Builder — avant implementation -Appel recommande : +Appel actuel (workflow `dev-story`) : ```txt -validate_plan(domain, plan_text, agent_role="builder", strict=false) +validate_plan(domain, plan_text, agent_role="builder", strict=true) ``` -Regle advisory : +Regle : -- les `blocking_issues` sont traces mais ne bloquent pas encore automatiquement -- le Builder doit repondre explicitement a chaque point dans son plan ou son Dev Agent Record +- `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 recommande : +Appel actuel (workflow `dev-story`) : ```txt -validate_patch(domain, diff_text, changed_files, strict=false) +validate_patch(domain, diff_text, changed_files, strict=true) ``` -Regle advisory : +Regle : -- ajouter un resume dans le Dev Agent Record -- si `blocking_issues` apparait, le statut cible doit devenir `review`, pas `done` +- `blocking_issues` non vide => HALT, correction obligatoire avant statut `review` +- override humain possible et trace dans `Leadtech MCP Gates` ### 4. Reviewer — revue finale -Appels recommandes : +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 advisory : +Regle : -- un `blocking_issues` n'est pas un veto automatique -- mais il impose une justification explicite si la PR/story est acceptee +- 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 @@ -107,39 +123,37 @@ Leadtech MCP Gates - decision: review demandee avant done ``` -## Observabilite a suivre pendant la phase advisory +## Observabilite a suivre -Sur 10 a 20 stories, relever : +Sur les prochaines 10 a 20 stories, relever : -- nombre de `blocking_issues` -- nombre de faux positifs +- 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.) -Objectif de sortie de phase advisory : +Objectif de stabilisation de la Phase 2 actuelle : -- faux positifs faibles sur les gates promues +- 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 stricts recommandes apres validation +## Blocages strictes deja actifs -Ne promouvoir en strict que des regles avec signal fort et faible ambiguite. +| 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`) | -### Blocage strict 1 +## Candidats a promouvoir en Phase 3 -- `validate_patch` : `Patch sans fichier source: seulement des artefacts BMAD.` -- Pourquoi : signal tres fort, directement aligne avec `story-tracking.md` +Apres observation des metriques ci-dessus, regles potentiellement promouvables si le signal est suffisamment fiable : -### Blocage strict 2 - -- `validate_patch` : `Session modifiee sans expiresAt visible dans le diff.` -- Pourquoi : gate backend precise, issue recurrente et couteuse - -### Blocage strict 3 - -- `validate_plan` : `Plan backend sans reference aux contrats partages.` -- Pourquoi : aligne avec la regle contracts-first, utile surtout sur monorepos TS fullstack +- `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 @@ -147,9 +161,8 @@ Ne promouvoir en strict que des regles avec signal fort et faible ambiguite. - warning `AuthGuard` sur des extraits de diff incomplets - suggestions de tests si la story est purement documentaire -## Sequence recommandee +## Historique de rollout -1. phase advisory sur toutes les stories backend + workflow -2. promotion du blocage strict `bmad-only artifacts` -3. promotion du blocage strict `sessions sans expiresAt` -4. promotion eventuelle du blocage `contracts-first` si le contexte repo le justifie +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