From a7b96919a6c2697ed5b99f62eca571690a2bf789 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 7 May 2026 08:06:04 +0000 Subject: [PATCH] feat(observability): scaffold Phase 2 tracking for Leadtech MCP rollout Met en place le squelette d'observabilite pour suivre le rollout Phase 2 partielle sur les 10-20 prochaines stories BMAD. Trois fichiers dans 80_bmad/observability/ : - README.md : flux operationnel + criteres de promotion vers Phase 3 + criteres de retour en arriere vers Phase 1 - template_releve_story.md : modele a copier-coller par story - phase2_log.md : log cumulatif (tableau recap + compteurs par regle + notes detaillees) Suivi tenu a la main pour l'instant. Une automatisation (script qui scanne les sections 'Leadtech MCP Gates' dans les stories des projets de _projects.conf) sera consideree apres 10 stories releves manuellement, si le format est juge stable. rollout_bmad_advisory.md reference le nouveau dossier dans sa section Observabilite. --- 80_bmad/observability/README.md | 49 ++++++++++++++ 80_bmad/observability/phase2_log.md | 51 +++++++++++++++ .../observability/template_releve_story.md | 65 +++++++++++++++++++ .../docs/rollout_bmad_advisory.md | 2 + 4 files changed, 167 insertions(+) create mode 100644 80_bmad/observability/README.md create mode 100644 80_bmad/observability/phase2_log.md create mode 100644 80_bmad/observability/template_releve_story.md diff --git a/80_bmad/observability/README.md b/80_bmad/observability/README.md new file mode 100644 index 0000000..bed0b83 --- /dev/null +++ b/80_bmad/observability/README.md @@ -0,0 +1,49 @@ +# Observabilite Leadtech MCP — Phase 2 partielle + +Ce dossier sert a tracer l'observation des gates Leadtech MCP sur les stories BMAD reelles, pour decider : + +- de l'extension du strict a d'autres gates (Phase 3) +- du retour en arriere si un gate produit trop de faux positifs +- de l'ajustement de `gates.yaml` ou des regles hardcodees dans `server.py` + +## Fichiers + +- `phase2_log.md` — log cumulatif des stories observees (tableau recap + notes detaillees) +- `template_releve_story.md` — modele a copier-coller dans `phase2_log.md` pour chaque nouvelle story + +## Quand alimenter + +Pour chaque story BMAD qui declenche au moins un appel `validate_plan` ou `validate_patch` strict : + +1. Copier le template `template_releve_story.md` +2. Le coller dans `phase2_log.md` sous la section "Notes detaillees" +3. Remplir au fur et a mesure (entree story / fin de dev / fin de review) +4. A la cloture, reporter la ligne synthese dans le tableau recap en tete de `phase2_log.md` + +## Criteres de promotion vers Phase 3 + +Avant de promouvoir un gate advisory en blocant strict, attendre que les criteres suivants soient atteints sur au moins **10 stories** dans le domaine concerne : + +- **Faux positifs** : < 10% des declenchements +- **Vrai positifs** : au moins 1 cas ou le gate a evite une regression reelle +- **Stabilite formulation** : pas de cas ou la regle declenche sur un texte ambigu (extrait partiel, formulation libre) +- **Comprehension agent** : pas de cas ou l'agent BMAD a mal interprete le `blocking_issue` (ex: tente de contourner via reformulation) + +Candidats a la promotion (cf. `mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md`) : + +- `backend_request_id` (validate_plan / validate_patch) +- `backend_auth_guard` (validate_patch) + +## Criteres de retour en arriere (Phase 1) + +Si un gate strict actif produit : + +- **> 30% de faux positifs** sur 5 stories consecutives, OU +- **> 50% d'overrides humains non justifies**, OU +- **un blocage durable** d'un projet sans valeur ajoutee + +→ retirer le `strict_only: true` correspondant dans `gates.yaml` (ou retirer la regle hardcodee de `server.py`) et documenter le retour en arriere dans `40_decisions_et_archi.md`. + +## Pas d'automatisation pour l'instant + +Le log est tenu a la main par l'humain. Une automatisation (script qui scanne les sections `Leadtech MCP Gates` dans les stories des projets de `_projects.conf`) sera consideree apres 10 stories releves manuellement, si le format est juge stable. diff --git a/80_bmad/observability/phase2_log.md b/80_bmad/observability/phase2_log.md new file mode 100644 index 0000000..a54c8b3 --- /dev/null +++ b/80_bmad/observability/phase2_log.md @@ -0,0 +1,51 @@ +# Log Phase 2 partielle — Leadtech MCP + +Suivi cumulatif des stories qui ont declenche au moins un gate Leadtech MCP en mode strict. + +## Statut + +- **Phase** : 2 partielle (strict cible) +- **Demarree le** : 2026-05-07 +- **Stories observees** : 0 / 10 minimum avant evaluation Phase 3 +- **Derniere mise a jour** : 2026-05-07 + +## Tableau recap + +| # | Date | Projet | Story | Domaine | Tools strict | Blocking | Faux+ | Vrai+ | Override | Decision | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| _ | _ | _ | _ | _ | _ | _ | _ | _ | _ | _ | + +_(aucune story observee pour l'instant)_ + +Legendes : + +- **Tools strict** : tools appeles en `strict=true` (ex: `validate_plan`, `validate_patch`) +- **Blocking** : nombre de `blocking_issues` automatiques declenches +- **Faux+** : nombre de blocking_issues juges faux positifs apres analyse humaine +- **Vrai+** : nombre de blocking_issues qui ont evite une regression reelle +- **Override** : oui / non +- **Decision** : accepted | overridden | rejected + +## Compteurs par regle (auto-mise-a-jour manuelle) + +| Regle | Source | Declenchements | Faux+ | Vrai+ | Status | +| --- | --- | --- | --- | --- | --- | +| Patch sans fichier source: artefacts BMAD seuls | `server.py` hardcode | 0 | 0 | 0 | strict actif | +| `backend_session_expires_at` | `gates.yaml` | 0 | 0 | 0 | strict actif | +| `backend_contracts` | `gates.yaml` strict_only | 0 | 0 | 0 | strict actif via dev-story | +| `backend_request_id` (plan) | `gates.yaml` | 0 | 0 | 0 | advisory (candidat Phase 3) | +| `backend_request_id` (patch) | `gates.yaml` | 0 | 0 | 0 | advisory (candidat Phase 3) | +| `backend_auth_guard` | `gates.yaml` | 0 | 0 | 0 | advisory (candidat Phase 3) | +| `parallel_dependencies` | `gates.yaml` | 0 | 0 | 0 | advisory | +| `test_strategy` | `gates.yaml` | 0 | 0 | 0 | advisory | +| `tests_visible_in_diff` | `gates.yaml` strict_only | 0 | 0 | 0 | advisory | + +## Notes detaillees + +_(coller ici un releve par story, en utilisant `template_releve_story.md`. Les plus recentes en haut.)_ + +--- + + + +--- diff --git a/80_bmad/observability/template_releve_story.md b/80_bmad/observability/template_releve_story.md new file mode 100644 index 0000000..0aec6b8 --- /dev/null +++ b/80_bmad/observability/template_releve_story.md @@ -0,0 +1,65 @@ +# Releve story — — + +> Modele a copier-coller dans `phase2_log.md` sous la section "Notes detaillees", puis remplir au fur et a mesure. + +## Contexte + +- **Date debut** : +- **Date cloture** : +- **Projet** : +- **Story** : +- **Domaine** : `backend` | `frontend` | `ux` | `n8n` | `product` | `workflow` +- **Agents intervenus** : analyst, sm, dev, qa, ... + +## Tools MCP appeles + +| Tool | Mode | Quand | +| --- | --- | --- | +| `get_guidance` | advisory | entree story (analyst / sm) | +| `validate_plan` | strict=true | avant impl (dev) | +| `validate_patch` | strict=true | apres diff (dev) | +| `validate_patch` | strict=false | review (qa) | +| `emit_checklist` | n/a | review (qa) | + +## Findings auto agreges + +- `blocking_issues` : (count: N) +- `red_flags` : (count: N) +- `must_do` cles : +- `should_do` cles : +- `matched_docs` les plus utiles : <2-3 paths> + +## Evaluation humaine + +### Faux positifs + +Pour chaque blocking_issue ou red_flag declenche a tort : + +- **Regle** : +- **Pourquoi faux positif** : +- **Action** : aucune | reformulation suggeree | escalade vers gates.yaml + +### Vrais positifs (regression evitee) + +Pour chaque blocking_issue qui aurait laisse passer un bug : + +- **Regle** : +- **Description** : + +### Override humain + +- **Override applique ?** : oui / non +- **Sur quelle regle** : +- **Justification** : + +### Decision finale + +- accepted as-is +- overridden (justifie ci-dessus) +- rejected (story revue avant cloture) + +## Apprentissage + +- **A capitaliser ?** oui / non +- **Si oui, ref dans `95_a_capitaliser.md`** : +- **Cible visee** : `knowledge///.md` ou `40_decisions_et_archi.md` ou `90_debug_et_postmortem.md` diff --git a/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md b/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md index 36c899c..bbf92f0 100644 --- a/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md +++ b/mcp/leadtech_bmad_mcp/docs/rollout_bmad_advisory.md @@ -134,6 +134,8 @@ Sur les prochaines 10 a 20 stories, relever : - 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