mcp: clean tracked artifacts and document rollout

.gitignore

@@ -1,2 +1,13 @@
 .vscode
 .DS_Store
+
+# Python / MCP
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/

README.md

@@ -21,6 +21,8 @@ Lead_tech est un dépôt de **mémoire technique partagée** : patterns validés
 
 Il est conçu pour fonctionner en tandem avec un copilote IA qui le consulte avant de vous répondre, vous évitant de répéter les mêmes erreurs et de re-expliquer votre contexte à chaque session.
 
+Depuis mars 2026, le repo peut aussi exposer cette doctrine sous forme de **serveur MCP sidecar** pour des workflows BMAD. L'objectif n'est pas de remplacer la lecture des Markdown, mais de rendre la consultation, les gates et la capitalisation actionnables par tool call.
+
 ---
 
 ## Comment ça marche — le modèle mental
@@ -138,6 +140,7 @@ Lead_tech/
 ├── 60_playbooks/           # Procédures opérationnelles réutilisables
 ├── 70_templates/           # Modèles de fichiers (CLAUDE.md projet, patches knowledge…)
 ├── 80_bmad/                # Documentation de l'articulation BMAD ↔ Lead_tech
+├── mcp/                    # Serveurs MCP sidecar et prototypes associés
 ├── scripts/                # Automatisations (sync IA, bootstrap projet, secrets…)
 ├── skills/                 # Skills custom pour Claude Code / Codex
 ├── 10_conventions_redaction.md   # Conventions de documentation technique
@@ -151,6 +154,60 @@ Lead_tech/
 
 ---
 
+## MCP Sidecar BMAD
+
+Le prototype actuel vit dans `mcp/leadtech_bmad_mcp/`.
+
+Il expose deux types de primitives :
+
+- **guidance** : retrouver les patterns, risques et docs globaux pertinents pour une story
+- **gates** : valider un plan, un diff, ou la checklist attendue selon le rôle BMAD
+- **capitalisation** : proposer des ajouts dans `95_a_capitaliser.md` et aider au tri
+- **resources** : lire l'index Lead_tech, les docs globaux, les entrées de connaissance, et les projets actifs
+
+Le positionnement visé est volontairement sobre :
+
+- BMAD garde l'orchestration
+- Lead_tech garde la doctrine
+- le MCP sidecar fournit une couche d'interactivité et de contrôle qualité
+
+Voir :
+
+- `80_bmad/integration_mcp_sidecar.md`
+- `mcp/leadtech_bmad_mcp/README.md`
+
+### Niveau de maturité actuel
+
+Ce sidecar est déjà utile pour un **rollout advisory**.
+
+Il est pertinent dès maintenant pour :
+
+- injecter des patterns/risques en entrée de story
+- faire un contrôle "pré-plan" et "post-patch"
+- sécuriser la capitalisation sans donner un accès d'écriture direct à `knowledge/`
+
+Avant un usage plus strict en production, il est recommandé d'ajouter :
+
+- un score de pertinence plus riche que le simple comptage de tokens
+- des gates paramétrables par domaine critique
+- des métadonnées structurées sur les fichiers `knowledge/`
+- une vraie stratégie de versioning et de compatibilité pour les tools MCP
+
+### Roadmap conseillée
+
+1. Stabiliser le contrat MCP actuel.
+   Geler les noms de tools/resources, formaliser leurs inputs/outputs, et documenter les cas limites.
+2. Ajouter des métadonnées structurées à la base de connaissance.
+   Exemple : `domain`, `bucket`, `tags`, `severity`, `applies_to`, `validated_on`, `source_projects`.
+3. Introduire un index de recherche compilé.
+   Un petit pipeline local qui prépare un index JSON/SQLite sera plus robuste et plus rapide qu'un scan Markdown brut à chaque appel.
+4. Distinguer clairement `advisory` et `enforced gates`.
+   Un mode "conseil" pour l'adoption et un mode "blocant" limité à quelques règles à forte valeur.
+5. Journaliser l'usage.
+   Conserver pour chaque story les tools appelés, leurs recommandations, et la décision humaine associée.
+
+---
+
 ## Pour qui ?
 
 - **Devs solos** qui veulent capitaliser leur expérience et ne plus debugger deux fois le même problème

mcp/leadtech_bmad_mcp/.venv/bin/python

@@ -1 +0,0 @@
-python3

mcp/leadtech_bmad_mcp/.venv/bin/python3

@@ -1 +0,0 @@
-/usr/bin/python3

mcp/leadtech_bmad_mcp/.venv/bin/python3.11

@@ -1 +0,0 @@
-python3

mcp/leadtech_bmad_mcp/.venv/lib64

@@ -1 +0,0 @@
-lib

mcp/leadtech_bmad_mcp/.venv/pyvenv.cfg

@@ -1,5 +0,0 @@
-home = /usr/bin
-include-system-site-packages = false
-version = 3.11.2
-executable = /usr/bin/python3.11
-command = /usr/bin/python3 -m venv /srv/helpers/_Assistant_Lead_Tech/mcp/leadtech_bmad_mcp/.venv

mcp/leadtech_bmad_mcp/README.md

@@ -2,12 +2,28 @@
 
 Serveur MCP **sidecar** pour brancher la base Lead_tech dans un workflow BMAD sans remplacer BMAD.
 
+Etat actuel : **prototype exploitable** pour un rollout advisory.
+
 ## Objectif
 
 - BMAD garde l'orchestration (story, roles, statut, handoff).
 - Ce serveur apporte des outils de guidance et de gate qualite.
 - Ecriture controlee: uniquement `95_a_capitaliser.md` et memoire projet (optionnel, avec flag).
 
+## Ce que le serveur fait bien aujourd'hui
+
+- exposer la base Lead_tech en `resources` MCP lisibles par un agent
+- retrouver les patterns/risques les plus probables pour une story
+- appliquer quelques gates transverses deja stabilises dans Lead_tech
+- encapsuler la capitalisation dans un flux plus propre que l'edition manuelle
+
+## Ce qu'il ne faut pas lui demander pour l'instant
+
+- remplacer la lecture humaine complete des docs prioritaires
+- faire du ranking semantique avance
+- ecrire directement dans `knowledge/`
+- prendre la decision finale de merge, de done, ou de capitalisation
+
 ## Tools exposes
 
 - `get_guidance(domain, task_type, story_text?, keywords?, max_items?)`
@@ -24,6 +40,29 @@ Serveur MCP **sidecar** pour brancher la base Lead_tech dans un workflow BMAD sa
 - `leadtech://capitalisation/pending`
 - `leadtech://projects/conf`
 - `leadtech://knowledge/{domain}/{bucket}/{slug}`
+- `leadtech://global/architecture`
+- `leadtech://global/debug`
+- `leadtech://global/conventions`
+
+## Design de securite
+
+- lecture libre sur les fichiers Lead_tech exposes
+- ecriture desactivee par defaut
+- aucune ecriture autorisee dans `knowledge/*`
+- ecriture conditionnelle uniquement sur :
+  - `95_a_capitaliser.md`
+  - `CLAUDE.md` projet
+
+## Integration recommandee dans BMAD
+
+1. Analyst
+   Appeler `get_guidance(...)` a l'entree de story pour injecter patterns, risques et docs a lire.
+2. Builder
+   Appeler `validate_plan(...)` avant implementation puis `validate_patch(...)` apres generation du diff.
+3. Reviewer
+   Appeler `emit_checklist(...)` et, si besoin, relancer `validate_patch(...)` sur le diff final.
+4. Curator
+   Utiliser `propose_capitalization(..., dry_run=true)` puis `triage_capitalization()`.
 
 ## Installation locale
 
@@ -34,6 +73,13 @@ source .venv/bin/activate
 pip install -e .
 ```
 
+Pour le dev local avec tests :
+
+```bash
+pip install -e ".[dev]"
+pytest tests -q
+```
+
 ## Lancement (stdio)
 
 ```bash
@@ -51,3 +97,21 @@ leadtech-bmad-mcp
 ## Mode de branchement BMAD
 
 Voir `80_bmad/integration_mcp_sidecar.md` pour les points d'injection exacts dans le workflow.
+
+## Merge checklist recommandee
+
+Avant de merger cette brique dans `main` :
+
+- supprimer du repo les artefacts locaux (`.venv`, `__pycache__`, `*.pyc`)
+- verifier l'installation sur une machine vierge avec `pip install -e ".[dev]"`
+- lancer `pytest tests -q`
+- confirmer que les tools/resources exposes sont bien ceux attendus par les prompts BMAD
+- documenter la phase de rollout retenue : advisory only ou blocage sur `blocking_issues`
+
+## Upgrades conseilles
+
+- index de recherche compile plutot qu'un scan fichier par fichier
+- metadonnees YAML/front matter dans `knowledge/` pour fiabiliser le ranking
+- schémas MCP formalises et versionnes pour chaque tool
+- logs d'execution par story pour auditer les gates et la decision humaine
+- suites de tests complementaires sur les faux positifs/faux negatifs des regex