mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-05-18 08:18:15 +02:00
docs(mcp-rollout): align rollout doc with Phase 2 partielle reality
Audit santé du chantier mcp_v1 a montré un écart entre la doc rollout (advisory only) et l'implémentation réelle (workflows dev-story et create-story en strict=true, personas dev.md et sm.md avec hard-blocker sur blocking_issues). Décision : aligner la doc sur l'implem. Changements : - rollout_bmad_advisory.md : réécrit pour décrire la Phase 2 partielle avec les 3 blocages stricts effectivement actifs (artefacts BMAD seuls, sessions sans expiresAt, plan backend sans contracts). - integration_mcp_sidecar.md : points d'injection mis à jour avec strict=true sur dev, advisory sur QA, statut Phase 2. - mcp_v1.md et README.md : statut 'advisory-first' / 'prototype' → 'Phase 2 partielle'. - 40_decisions_et_archi.md : nouvel ADR retraçant le choix. Note : les customize.yaml invoquent encore strict=false, surchargés par les workflows. Cohérence interne à traiter dans un prochain commit si besoin.
This commit is contained in:
Claude
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user