skills/business-analyst/references/execution-contract.md

# Contrat d’exécution portable — v1.3.0

Ce contrat gouverne tous les rapports. Le framework du module reste l’unique autorité méthodologique.

## 1. Capability check bloquant

Avant la recherche, établis uniquement à partir des outils réellement disponibles :

```yaml
capabilities:
  web_search: AVAILABLE | MISSING
  notion_read: AVAILABLE | MISSING
  notion_write: AVAILABLE | MISSING
  notion_fetch: AVAILABLE | MISSING
  external_database: AVAILABLE | MISSING
```

Ne déduis jamais une capacité du texte de la demande ou de la présence du plugin. Utilise le profil `notion-investment-os` seulement si lecture, écriture et fetch Notion sont réellement disponibles. Utilise `external-database` seulement si l’adaptateur expose écriture et readback. Sinon utilise `conversation`. Si l’utilisateur exige un provider indisponible, retourne `BLOCKED_CAPABILITY` et nomme la capacité manquante.

## 2. États autorisés

Le run progresse sans saut :

`CAPABILITY_CHECK → IDENTITY → RESEARCH → ANALYSIS → EVIDENCE_GATE → RENDER → PERSISTENCE → COMPLETE`.

Statuts analytiques : `COMPLETE`, `PARTIAL`, `FAILED`, `BLOCKED_INPUT`, `BLOCKED_CAPABILITY`.
Persistance : `NOT_REQUIRED`, `VERIFIED`, `FAILED`.
Page : `Draft`, `Validated`, `Superseded`.

Un état n’est atteint que lorsque son résultat existe. Ne produis jamais un reçu, un hash, un identifiant de page, un timestamp d’adaptateur ou un statut PASS qui n’a pas été retourné par un outil. Sans outil de hash, n’utilise aucun hash.

## 3. Identité

Résous nom légal, ticker, classe, marché, devise et, si utile, ISIN depuis une source officielle ou faisant autorité consultée pendant le run. Une ambiguïté bloque la recherche lourde et déclenche une seule question. Une Company minimale peut être créée uniquement après résolution non ambiguë.

## 4. Evidence Ledger avant rédaction

Cherche réellement chaque donnée factuelle utilisée. Construis d’abord un registre interne :

| ID | Claim exacte | Valeur | Période / as_of | URL | Consulté le | Locator | Extrait probant |
|---|---|---:|---|---|---|---|---|

Règles :

- toute valeur factuelle visible renvoie à un ID du ledger ;
- toute dérivation enregistre formule, entrées sourcées, unité et résultat ;
- une URL sans extrait ne constitue pas une preuve ;
- chaque preuve fraîche porte `provenance: collected_this_run`; une baseline héritée sert à la continuité, jamais à prouver une donnée fraîche ;
- les derniers résultats exigent une recherche d’une publication plus récente ;
- le prix exige instrument, place, devise, type, `as_of`, `retrieved_at` et source ;
- une donnée non prouvée est retirée ou rend le rapport `PARTIAL` ; elle ne devient jamais « non vérifiée » dans un rapport déclaré complet.

## 5. Evidence gate et rendu

Avant affichage ou écriture, vérifie le rapport contre le ledger :

- identité cohérente ;
- chaque chiffre factuel possède sa référence `[E:id]` ;
- chaque calcul possède sa référence `[D:id]` et se recalcule depuis ses entrées ;
- aucune citation orpheline ;
- aucun `**gras**`, `__gras__`, `*italique*`, `_italique_` ni balise HTML d’emphase dans une zone humaine ;
- titres, listes et tableaux inclus ;
- code et payload technique exclus du texte humain.

Utilise le formatage natif de l’adaptateur. Termine le rapport par des sources lisibles avec URL, période, date de consultation et extrait. Le modèle peut déclarer le résultat analytique du contrôle, mais ne fabrique aucune preuve technique d’exécution.

## 6. Persistance

### Conversation

Aucune écriture. Utilise `persistence_status: NOT_REQUIRED` et fournis le rapport, le handoff et un export structuré.

### Adaptateur disponible

Pour chaque module, dans cet ordre strict :

1. créer ou reprendre la page du même `(Run ID, module)` en `Draft` ;
2. écrire le rapport, le ledger utile et le handoff ;
3. appeler le readback réel de l’adaptateur ;
4. comparer les champs et le texte effectivement renvoyés avec le payload envoyé ;
5. seulement si la comparaison réussit, passer à `Validated` puis relire ;
6. mettre à jour `Current` puis relire la Company ;
7. si une ancienne Current existe, la passer à `Superseded` puis la relire.

La preuve de chaque mutation est la sortie réelle de l’outil correspondant. Une réponse reformulée par le modèle n’est pas un readback. Toute absence ou divergence donne `persistence_status: FAILED`, interdit `Current` et interdit le statut global `COMPLETE`. Un seul essai de compensation sûre est autorisé après un échec Current.

## 7. Handoff et clôture

Chaque handoff porte `contract_version: 1.3.0`, `plugin_version: 1.3.0`, Run ID, module, identité, période, conclusion, confiance, gaps et données nécessaires au module suivant. `score` reste `null` pour Earnings Review, Short, Portfolio Fit et Memo CIO.

Le RUN RECEIPT expose les capacités observées, les étapes atteintes, les IDs de preuves, les sorties d’outils de persistance pertinentes et les gaps. Il ne transforme jamais une affirmation du modèle en preuve.

Un module est `COMPLETE` seulement si son Evidence Ledger et son Evidence Gate sont complets. Un run persistant est `COMPLETE` seulement après readback réel de toutes les pages et relations Current attendues.