# leadtech-bmad-mcp — Contrat v1

Ce document fige le **contrat fonctionnel v1** du sidecar MCP Lead_tech.

Objectif :

- stabiliser ce que le serveur promet aux agents BMAD
- éviter les changements de payload implicites
- préparer les itérations suivantes (index compilé, gates configurables) sans casser les prompts existants

## Positionnement

- BMAD garde l'orchestration
- Lead_tech garde la doctrine et la validation humaine
- le MCP sidecar fournit une couche outillée de lecture, guidance, gate qualité, et capitalisation

## Version fonctionnelle

- Nom logique : `leadtech-bmad-mcp`
- Version de contrat : `v1`
- Statut : Phase 2 partielle — 3 blocages stricts cibles + advisory sur le reste (voir `rollout_bmad_advisory.md`)

## Outils v1

### `get_guidance(domain, task_type, story_text?, keywords?, max_items?)`

Rôle :
- retrouver les patterns, risques et docs globaux pertinents pour une story

Entrées :
- `domain` : `backend | frontend | ux | n8n | product | workflow`
- `task_type` : `analysis | implementation | review | debug | architecture`
- `story_text` : texte libre
- `keywords` : liste de mots-clés optionnelle
- `max_items` : entier optionnel

Sortie :
- `must_do[]`
- `should_do[]`
- `red_flags[]`
- `blocking_issues[]`
- `references[]`
- `confidence`
- `gates[]`

Règle :
- advisory par défaut
- pas d'écriture

### `validate_plan(domain, plan_text, agent_role?, strict?)`

Rôle :
- vérifier qu'un plan BMAD couvre les gates Lead_tech les plus importantes

Règle :
- `strict=true` peut produire des `blocking_issues`
- `strict=false` reste advisory

### `validate_patch(domain, diff_text, changed_files?, strict?)`

Rôle :
- contrôler un diff par rapport à des gates Lead_tech

Règle :
- détecte les signaux faibles, pas une preuve formelle de conformité
- un résultat vide ne remplace jamais une review humaine

### `emit_checklist(agent_role, domain, story_text?)`

Rôle :
- produire une checklist opérationnelle par rôle BMAD

### `propose_capitalization(project_name, target_file, why, proposal, dry_run?)`

Rôle :
- préparer une entrée `FILE_UPDATE_PROPOSAL` pour `95_a_capitaliser.md`

Règle :
- `dry_run=true` par défaut
- écriture réelle uniquement si `LEADTECH_MCP_ALLOW_WRITE=1`

### `triage_capitalization(project_filter?, max_entries?)`

Rôle :
- analyser les entrées du buffer de capitalisation

Statut :
- heuristique, non décisionnaire

### `route_to_project_memory(project_name, section, content, dry_run?)`

Rôle :
- router un apprentissage de portée projet vers le `CLAUDE.md` du projet

Règle :
- écriture réelle uniquement si `LEADTECH_MCP_ALLOW_WRITE=1`

## Resources v1

- `leadtech://index`
- `leadtech://capitalisation/pending`
- `leadtech://projects/conf`
- `leadtech://knowledge/{domain}/{bucket}/{slug}`
- `leadtech://global/architecture`
- `leadtech://global/debug`
- `leadtech://global/conventions`

## Payload commun

Les tools de guidance et de validation retournent un payload homogène :

```json
{
  "must_do": [],
  "should_do": [],
  "red_flags": [],
  "blocking_issues": [],
  "confidence": "MEDIUM",
  "references": [],
  "matched_docs": [],
  "gates": []
}
```

## Niveaux de sévérité

- `must_do` : action attendue fortement recommandée
- `should_do` : amélioration ou vérification utile
- `red_flags` : signal de risque ou d'incertitude
- `blocking_issues` : empêche la progression en mode strict

## Confiance

- `HIGH`
- `MEDIUM`
- `LOW`

Règle :
- la confiance exprime la qualité du matching heuristique, pas la vérité terrain

## Références

`references[]` contient :

```json
{
  "path": "/abs/path/doc.md",
  "reason": "Match patterns score=7"
}
```

Règle :
- toujours renvoyer des chemins absolus si possible
- référencer la source, pas uniquement un résumé

## Matched docs

`matched_docs[]` expose les meilleurs documents remontés par le moteur de guidance.

Structure cible v1 :

```json
{
  "path": "/abs/path/doc.md",
  "bucket": "patterns",
  "title": "Backend — Patterns : NestJS",
  "score": "12",
  "severity": "medium",
  "applies_to": "analysis, implementation, review, debug",
  "tags": "nestjs, guards, auth, redis, quota",
  "read_uri": "leadtech://knowledge/backend/patterns/nestjs"
}
```

Règle :
- champ informatif, non bloquant
- utile pour les agents qui veulent afficher ou prioriser explicitement les docs remontés

## Erreurs

Conventions v1 :

- tool de lecture : lever une erreur explicite si ressource introuvable
- tool d'écriture : retourner un objet `{ "error": "..." }` si écriture désactivée ou cible introuvable
- ne jamais écrire dans `knowledge/*`

## Sécurité d'écriture

Écritures autorisées uniquement vers :

- `95_a_capitaliser.md`
- `CLAUDE.md` projet

Écritures interdites :

- `knowledge/*`
- `10_*`
- `40_*`
- `90_*`

## Compatibilité BMAD

Ce contrat v1 est pensé pour :

- enrichir une story à l'entrée
- bloquer certains cas en pre-implémentation ou post-patch
- tracer la décision humaine dans la story

Les prompts BMAD doivent considérer ce contrat comme stable tant qu'un document `v2` n'existe pas.
