# Argus MCP — Documentation de Référence

> **Version** : 0.10.0 · **Protocole** : MCP (stdio) · **15 outils** · **2 ressources** · **7 agents**

---

## Table des matières

- [Vue d'ensemble](#vue-densemble)
- [Installation & Configuration](#installation--configuration)
  - [VS Code (Copilot)](#vs-code-copilot)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
- [Les 15 outils MCP](#les-15-outils-mcp)
  - [🔍 Lecture & Analyse](#-lecture--analyse)
    - [query_memory](#query_memory)
    - [get_risk_analysis](#get_risk_analysis)
    - [get_testing_strategy](#get_testing_strategy)
    - [get_memory_health](#get_memory_health)
  - [📝 Écriture épisodique](#-écriture-épisodique)
    - [record_analysis](#record_analysis)
    - [record_decision](#record_decision)
    - [record_incident](#record_incident)
    - [record_execution](#record_execution)
  - [🧠 Écriture sémantique](#-écriture-sémantique)
    - [record_pattern](#record_pattern)
    - [record_heuristic](#record_heuristic)
  - [⚙️ Cycle cognitif](#️-cycle-cognitif)
    - [run_cognitive_cycle](#run_cognitive_cycle)
  - [🧪 Aide au test](#-aide-au-test)
    - [generate_test_scaffold](#generate_test_scaffold)
    - [get_test_cases](#get_test_cases)
  - [🔒 Audit de sécurité](#-audit-de-sécurité)
    - [audit_code_security](#audit_code_security)
  - [⚡ Audit de performance](#-audit-de-performance)
    - [audit_code_performance](#audit_code_performance)
- [Ressources MCP](#ressources-mcp)
- [Agents spécialisés](#agents-spécialisés)
- [Architecture mémoire](#architecture-mémoire)
  - [Mémoire sémantique](#mémoire-sémantique)
  - [Mémoire épisodique](#mémoire-épisodique)
  - [Mémoire relationnelle](#mémoire-relationnelle)
  - [Profils de contexte](#profils-de-contexte)
- [Cycle cognitif — Détails](#cycle-cognitif--détails)
  - [Phase 1 — Consolidation](#phase-1--consolidation)
  - [Phase 2 — Decay (oubli contrôlé)](#phase-2--decay-oubli-contrôlé)
  - [Phase 3 — Reflection](#phase-3--reflection)
- [Limites & Politiques de sécurité](#limites--politiques-de-sécurité)
- [Exemple de workflow complet](#exemple-de-workflow-complet)
- [Tableau récapitulatif](#tableau-récapitulatif)

---

## Vue d'ensemble

Argus est un **orchestrateur QA** qui maintient une mémoire structurée
(patterns de défauts, heuristiques de test, analyses épisodiques, profils de
contexte) et expose des outils via le protocole **MCP (Model Context Protocol)**.

Il fournit :
- **Analyse de risques** basée sur 46 patterns de défauts
- **Stratégies de test** guidées par 62 heuristiques (incluant ISTQB)
- **Scaffolding de tests** unitaires et de composants
- **Audit de sécurité** statique (28 règles, 11 domaines, multi-langage)
- **Audit de performance** statique (30 règles, 10 domaines, multi-ressource)
- **Mémoire évolutive** via un cycle cognitif (consolidation, oubli, réflexion)
- **7 agents spécialisés** (BDD, TDD, sécurité, performance, accessibilité, SEO, orchestration)

---

## Installation & Configuration

### VS Code (Copilot)

Dans `.vscode/mcp.json` :

```json
{
  "servers": {
    "argus": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "${workspaceFolder}/../Argus"
    }
  }
}
```

### Claude Desktop

Dans `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "argus": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/chemin/vers/Argus"
    }
  }
}
```

### Cursor

Dans `.cursor/mcp.json` :

```json
{
  "mcpServers": {
    "argus": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/chemin/vers/Argus"
    }
  }
}
```

---

## Les 15 outils MCP

### 🔍 Lecture & Analyse

---

#### `query_memory`

> **Interroger la mémoire Argus** — recherche libre dans toutes les sections.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `section` | string | ✅ | Section à interroger (voir valeurs ci-dessous) |
| `query` | string | — | Recherche textuelle (nom, description, catégorie) |
| `category` | string | — | Filtre par catégorie (ex : `security`, `api`) |
| `min_confidence` | float | — | Seuil de confiance minimum (0.0–1.0) |
| `limit` | int | — | Résultats max (1–1000, défaut : 100) |
| `offset` | int | — | Offset de pagination |

**Sections disponibles** : `patterns` · `heuristics` · `analyses` · `decisions` · `incidents` · `executions` · `projects` · `profiles` · `associations` · `stats` · `index`

**Exemple** :
```
query_memory(section="patterns", category="security", min_confidence=0.7)
```

---

#### `get_risk_analysis`

> **Analyser les risques d'un code** — croise le code source ou un diff contre les 46 patterns de défauts.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `code_or_diff` | string | ✅ | Code source ou diff unifié (max 500 Ko) |
| `context_profile` | string | — | Profil applicatif : `CTX-GENERIC` · `CTX-FINTECH` · `CTX-ECOMMERCE` · `CTX-HEALTH` · `CTX-SAAS` · `CTX-IOT` |
| `file_path` | string | — | Chemin du fichier analysé (pour contexte) |

**Retour** : niveau de risque global (`critical` / `high` / `medium` / `low`), score max, patterns détectés avec stratégies de prévention.

**Exemple** :
```
get_risk_analysis(
  code_or_diff="def login(req): query = f\"SELECT * FROM users WHERE ...\"",
  context_profile="CTX-SAAS",
  file_path="auth/views.py"
)
```

---

#### `get_testing_strategy`

> **Recommander une stratégie de test** — croise les heuristiques et patterns selon le changement.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `change_description` | string | ✅ | Description du changement |
| `change_type` | string | — | `feature` · `bugfix` · `refactoring` · `performance` · `security` · `dependency_update` · `config` |
| `context_profile` | string | — | Profil applicatif (défaut : `CTX-GENERIC`) |
| `components_affected` | list[str] | — | Composants impactés (ex : `["auth", "payment"]`) |

**Retour** : types de tests recommandés, heuristiques applicables, patterns de risque associés.

**Exemple** :
```
get_testing_strategy(
  change_description="Refactoring du module d'authentification",
  change_type="security",
  context_profile="CTX-SAAS",
  components_affected=["auth", "database"]
)
```

---

#### `get_memory_health`

> **Diagnostic de santé mémoire** — lance les 12 contrôles de la phase Reflection.

*Aucun paramètre requis.*

**Retour** : statistiques globales (nombre de patterns, heuristiques, épisodes), résultats par catégorie (cohérence, complétude, fraîcheur, équilibre, connectivité), recommandations.

---

### 📝 Écriture épisodique

---

#### `record_analysis`

> **Enregistrer une analyse** dans la mémoire épisodique.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `title` | string | ✅ | Titre de l'analyse |
| `findings` | list[dict] | ✅ | Résultats (max 50) — voir structure ci-dessous |
| `project` | string | — | Identifiant projet (défaut : `external`) |
| `trigger` | string | — | `manual_request` · `PR_merge` · `incident_response` |
| `scope_type` | string | — | `file` · `PR` · `directory` · `full_project` |
| `scope_reference` | string | — | Référence du scope (chemin, n° PR…) |
| `verdict` | string | — | `approved` · `approved_with_caveats` · `rejected` |

**Structure d'un finding** :
| Champ | Type | Requis | Description |
|-------|------|:------:|-------------|
| `title` | string | ✅ | Titre du finding |
| `risk_level` | string | ✅ | `critical` · `high` · `medium` · `low` |
| `category` | string | ✅ | Catégorie |
| `description` | string | ✅ | Description |
| `recommendation` | string | ✅ | Recommandation |
| `related_patterns` | list[str] | — | IDs patterns (ex : `["PAT-SEC-001"]`) |
| `related_heuristics` | list[str] | — | IDs heuristiques |
| `confidence` | float | — | 0.0–1.0 |

**Retour** : `ANL-YYYYMMDD-NNN`

---

#### `record_decision`

> **Enregistrer une décision** dans la mémoire épisodique.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `title` | string | ✅ | Titre |
| `context` | string | ✅ | Contexte menant à la décision |
| `decision` | string | ✅ | Décision prise |
| `rationale` | string | ✅ | Justification |
| `project` | string | — | Identifiant projet |
| `alternatives` | list[str] | — | Alternatives considérées |
| `risks` | list[str] | — | Risques identifiés |
| `tags` | list[str] | — | Tags libres |

**Retour** : `DEC-YYYYMMDD-NNN`

---

#### `record_incident`

> **Enregistrer un incident** dans la mémoire épisodique.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `title` | string | ✅ | Titre |
| `severity` | string | ✅ | `P0` · `P1` · `P2` · `P3` · `P4` |
| `description` | string | ✅ | Description détaillée |
| `project` | string | — | Identifiant projet |
| `root_cause` | string | — | Cause racine identifiée |
| `matched_patterns` | list[str] | — | IDs patterns Argus (ex : `["PAT-SEC-001"]`) |
| `resolution` | string | — | Résolution appliquée ou planifiée |
| `tags` | list[str] | — | Tags libres |

**Retour** : `INC-YYYYMMDD-NNN`

---

#### `record_execution`

> **Enregistrer une exécution de tests** dans la mémoire épisodique.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `suite` | string | ✅ | Nom de la suite (ex : `unit-tests`, `e2e-checkout`) |
| `total` | int | ✅ | Tests exécutés |
| `passed` | int | ✅ | Tests réussis |
| `failed` | int | ✅ | Tests échoués |
| `project` | string | — | Identifiant projet |
| `skipped` | int | — | Tests sautés |
| `duration_seconds` | float | — | Durée totale |
| `failures` | list[dict] | — | Détails : `test_name`, `error`, `matched_patterns` |
| `tags` | list[str] | — | Tags libres |

**Retour** : `EXC-YYYYMMDD-NNN`

---

### 🧠 Écriture sémantique

---

#### `record_pattern`

> **Enregistrer un pattern de défaut** dans la mémoire sémantique.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `name` | string | ✅ | Nom du pattern |
| `category` | string | ✅ | Voir catégories ci-dessous |
| `severity_typical` | string | ✅ | `critical` · `high` · `medium` · `low` |
| `description` | string | ✅ | Description du pattern |
| `confidence` | float | — | 0.0–1.0 (défaut : 0.7) |
| `indicators` | list[str] | — | Indicateurs textuels |
| `code_patterns` | list[str] | — | Exemples de code |
| `prevention_strategy` | list[str] | — | Stratégies de prévention |
| `related_owasp` | string | — | Référence OWASP (ex : `A03:2021`) |
| `related_cwe` | string | — | Référence CWE (ex : `CWE-89`) |

**Catégories** : `null_safety` · `concurrency` · `async` · `security` · `performance` · `regression` · `api` · `data_integrity` · `error_handling` · `requirements` · `functional` · `accessibility` · `seo` · `ui`

**Retour** : `PAT-{CAT}-NNN`

---

#### `record_heuristic`

> **Enregistrer une heuristique de test** dans la mémoire sémantique.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `name` | string | ✅ | Nom de l'heuristique |
| `category` | string | ✅ | Voir catégories ci-dessous |
| `action` | string | ✅ | Action recommandée |
| `condition` | string | — | Condition d'applicabilité |
| `confidence` | float | — | 0.0–1.0 (défaut : 0.7) |
| `priority` | string | — | `always` · `high_priority` · `when_applicable` · `optional` |
| `rationale` | string | — | Justification |
| `related_patterns` | list[str] | — | IDs patterns liés |

**Catégories** : `selection` · `prioritization` · `coverage` · `automation` · `flaky_detection` · `api_testing` · `security_testing` · `accessibility_testing` · `istqb_black_box` · `istqb_white_box` · `istqb_experience` · `istqb_levels` · `istqb_risk`

**Retour** : `HEU-{CAT}-NNN`

---

### ⚙️ Cycle cognitif

---

#### `run_cognitive_cycle`

> **Lancer le cycle cognitif** — orchestre consolidation, oubli contrôlé et réflexion.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `phase` | string | — | `all` · `consolidation` · `decay` · `reflection` (défaut : `all`) |
| `apply` | bool | — | `true` = appliquer les changements, `false` = scan uniquement (défaut : `false`) |

**Retour** : rapport structuré — timestamp, mode (scan/apply), rapport de chaque phase (durée, statut, métriques), statut global : `HEALTHY` · `ACTIONS_NEEDED` · `ISSUES_FOUND` · `ERROR`.

**Exemple** :
```
# D'abord un scan pour prévisualiser
run_cognitive_cycle(phase="all", apply=false)

# Puis application si satisfait
run_cognitive_cycle(phase="all", apply=true)
```

---

### 🧪 Aide au test

---

#### `generate_test_scaffold`

> **Générer un squelette de fichier de test** pour le code source fourni.

Analyse le code pour extraire fonctions, classes et dépendances, puis génère un scaffold complet avec imports, fixtures/mocks, et tests structurés (happy path, edge cases, erreurs). Les cas limites sont déduits des paramètres et des patterns de défauts Argus.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `code` | string | ✅ | Code source à tester (fonction, classe, module) |
| `language` | string | — | `python` · `javascript` · `typescript` · `java` · `csharp`. Auto-détecté si omis |
| `test_framework` | string | — | `pytest` · `unittest` · `vitest` · `jest` · `junit5`. Défaut selon le langage |
| `file_path` | string | — | Chemin du fichier source (pour générer les imports) |

**Retour** : JSON contenant le scaffold de test complet et les métadonnées d'analyse (fonctions détectées, dépendances, patterns Argus applicables).

**Exemple** :
```
generate_test_scaffold(
  code="def calculate_discount(price, percentage): ...",
  language="python",
  test_framework="pytest"
)
```

---

#### `get_test_cases`

> **Recommander les cas de test** à écrire pour un composant ou une fonctionnalité.

Croise la description du comportement avec les heuristiques de test, les patterns de défauts et le profil de contexte Argus pour produire une liste priorisée de cas de test : happy path, cas limites (BVA), cas d'erreur, cas de sécurité.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `description` | string | ✅ | Description du comportement à tester |
| `code` | string | — | Code source du composant (enrichit l'analyse) |
| `context_profile` | string | — | Profil applicatif (défaut : `CTX-GENERIC`) |
| `component_type` | string | — | `function` · `class` · `api_endpoint` · `ui_component` · `hook` · `middleware` (défaut : `function`) |

**Retour** : liste structurée de cas de test JSON avec ID, catégorie, priorité (P0–P3), description et conditions.

**Exemple** :
```
get_test_cases(
  description="Fonction de calcul de réduction appliquant un pourcentage au prix total",
  context_profile="CTX-ECOMMERCE",
  component_type="function"
)
```

---

### 🔒 Audit de sécurité

---

#### `audit_code_security`

> **Audit de sécurité statique** — 28 règles, 11 domaines, multi-langage.

Applicable à tout type de projet (backend, CLI, bibliothèque, API, desktop, mobile, IoT, scripts), pas uniquement le web. Chaque finding est lié à un CWE et au defect pattern Argus correspondant.

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `code` | string | ✅ | Code source à auditer |
| `file_path` | string | — | Chemin du fichier (pour contexte) |
| `severity_threshold` | string | — | Seuil minimum : `critical` · `high` · `medium` · `low` (défaut) |
| `domains` | list[str] | — | Domaines à auditer (défaut : tous) |

**11 domaines** :

| Domaine | Description | Exemples |
|---------|-------------|----------|
| `injection` | Injection de code/données | SQL, OS command, eval, SSTI, path traversal |
| `secrets` | Secrets & données sensibles | Credentials hardcodés, logs sensibles, mode debug |
| `deserialization` | Désérialisation dangereuse | pickle, yaml.load, marshal, unserialize |
| `cryptography` | Cryptographie faible | MD5/SHA1, random non-crypto, clés hardcodées |
| `access_control` | Contrôle d'accès | Permissions fichiers, auth manquante |
| `error_handling` | Gestion d'erreurs | Exceptions larges, stack traces exposées |
| `data_validation` | Validation des entrées | Entrées non validées, ReDoS |
| `resource_safety` | Sécurité des ressources | Ressources non fermées, tmp files |
| `concurrency` | Concurrence | Race conditions, TOCTOU |
| `supply_chain` | Chaîne d'approvisionnement | Imports dangereux, deps non vérifiées |

**Retour** : rapport JSON — findings (id, domaine, sévérité, titre, description, CWE, localisation, remédiation, pattern Argus lié), statistiques par sévérité et domaine.

**Exemple** :
```
audit_code_security(
  code="password = 'admin123'\nquery = f'SELECT * FROM users WHERE pass={password}'",
  severity_threshold="medium",
  domains=["injection", "secrets"]
)
```

---

### ⚡ Audit de performance

---

#### `audit_code_performance`

> **Audit de performance statique** — 30 règles, 10 domaines, multi-ressource.

Détecte les anti-patterns de performance, propose des refactorisations concrètes et identifie les gaspillages de ressources (CPU, mémoire, I/O).

| Paramètre | Type | Requis | Description |
|-----------|------|:------:|-------------|
| `code` | string | ✅ | Code source à auditer |
| `file_path` | string | — | Chemin du fichier (pour contexte) |
| `impact_threshold` | string | — | Seuil minimum : `high` · `medium` · `low` (défaut) |
| `domains` | list[str] | — | Domaines à auditer (défaut : tous) |
| `resources` | list[str] | — | Filtrer par ressource : `cpu` · `memory` · `io` (défaut : toutes) |

**10 domaines** :

| Domaine | Description | Exemples |
|---------|-------------|----------|
| `algorithmic_complexity` | Complexité algorithmique | Boucles O(n²), tris redondants, recherches linéaires |
| `memory_efficiency` | Efficacité mémoire | Concaténation en boucle, chargement RAM complet, copies inutiles |
| `io_efficiency` | Efficacité I/O | N+1 queries, I/O sync en async, pagination manquante |
| `cpu_efficiency` | Efficacité CPU | Regex en boucle, memoization manquante, busy-waiting |
| `data_structures` | Structures de données | list comme queue, lookups répétés |
| `concurrency` | Concurrence | GIL + threads CPU, await séquentiel |
| `resource_management` | Gestion des ressources | Logging excessif, fuites de ressources |
| `serialization` | Sérialisation | Round-trips JSON/pickle redondants |
| `initialization` | Initialisation | Calculs lourds à l'import |
| `exception_overhead` | Coût des exceptions | Exceptions pour le contrôle de flux |

**Retour** : rapport JSON — findings (id, domaine, impact, titre, description, pourquoi c'est coûteux, refactoring proposé, ressource impactée, estimation du gain), statistiques par impact et domaine.

**Exemple** :
```
audit_code_performance(
  code="results = []\nfor item in large_list:\n    results.append(process(item))",
  impact_threshold="medium",
  resources=["cpu", "memory"]
)
```

---

## Ressources MCP

Les ressources sont accessibles en lecture seule via le protocole MCP.

| URI | Description |
|-----|-------------|
| `argus://persona` | Persona complète Argus (framework CRAFT/TOON) — rôle, ton, expertise |
| `argus://memory/stats` | Statistiques globales de la mémoire (JSON) — compteurs, dates, santé |

---

## Agents spécialisés

Les agents sont des modes conversationnels spécialisés fournis par Argus. Ils utilisent les outils MCP avec des workflows prédéfinis.

| Agent | Spécialité | Outils principaux utilisés |
|-------|-----------|---------------------------|
| **BDDCoach** | BDD — Gherkin, Given/When/Then, feature files, Cucumber, living documentation | `get_test_cases`, `get_testing_strategy` |
| **TDDCoach** | TDD — Red-Green-Refactor, test design, test doubles, mocking, coverage, SOLID | `generate_test_scaffold`, `get_test_cases` |
| **WebSecurityScanner** | Sécurité web — OWASP Top 10, XSS, CSRF, headers HTTP, sessions | `audit_code_security`, `get_risk_analysis` |
| **PerformanceAuditor** | Performance web — Core Web Vitals, LCP, INP, CLS, Lighthouse, bundles | `audit_code_performance` |
| **AccessibilityChecker** | Accessibilité — WCAG 2.1, a11y, clavier, contraste, ARIA, focus | `get_risk_analysis`, `query_memory` |
| **SEOChecker** | SEO technique — meta tags, JSON-LD, sitemap, crawlability, indexation | `query_memory` |
| **WebAuditOrchestrator** | Audit complet — orchestre Security, Performance, Accessibility et SEO | Tous les outils d'audit |

---

## Architecture mémoire

```
memory/
├── _index.yaml                    # Index global (compteurs, dates)
├── semantic/                      # Connaissances persistantes
│   ├── defect_patterns.yaml       #   46 patterns de défauts
│   ├── testing_heuristics.yaml    #   62 heuristiques de test
│   ├── context_profiles.yaml      #   8 profils de contexte
│   ├── technology_knowledge.yaml  #   Base technologique
│   └── istqb_knowledge.yaml       #   Référentiel ISTQB
├── episodic/                      # Expérience brute
│   ├── analyses/                  #   ANL-YYYYMMDD-NNN.yaml
│   ├── decisions/                 #   DEC-YYYYMMDD-NNN.yaml
│   ├── incidents/                 #   INC-YYYYMMDD-NNN.yaml
│   ├── executions/                #   EXC-YYYYMMDD-NNN.yaml
│   └── evolution_log.yaml         #   Journal d'évolution
├── relational/
│   └── associations.yaml          #   Liens composant → défaut
├── projects/                      # Fiches projet
│   └── *.yaml
├── working/                       # Sessions de travail temporaires
└── deliverables/                  # Templates de livrables
    ├── _template_test_plan.yaml
    ├── _template_exploratory_charter.yaml
    └── _template_traceability_matrix.yaml
```

### Mémoire sémantique

La mémoire sémantique contient les connaissances généralisées :

- **46 patterns de défauts** (`PAT-{CAT}-NNN`) — catégorisés par domaine (security, api, performance…), avec indicateurs, code patterns, sévérité, stratégies de prévention, références OWASP/CWE
- **62 heuristiques de test** (`HEU-{CAT}-NNN`) — organisées par type (selection, prioritization, ISTQB…), avec conditions, actions, priorité, rationale
- **8 profils de contexte** — `CTX-GENERIC`, `CTX-FINTECH`, `CTX-ECOMMERCE`, `CTX-HEALTH`, `CTX-SAAS`, `CTX-IOT`, `CTX-BA-QA`, `CTX-WEBAPP` — chacun définit les risques amplifiés, les patterns critiques et les heuristiques prioritaires

### Mémoire épisodique

Les épisodes sont enregistrés par les outils `record_*` et exploités par le cycle cognitif :

| Type | Préfixe | Contenu |
|------|---------|---------|
| Analyses | `ANL-` | Résultats d'audits, findings, verdict |
| Décisions | `DEC-` | Choix techniques, justifications, alternatives |
| Incidents | `INC-` | Bugs trouvés, sévérité, cause racine, patterns matchés |
| Exécutions | `EXC-` | Résultats de runs de tests, métriques, échecs |

### Mémoire relationnelle

Liens `composant → type de défaut` découverts par la consolidation. Permettent de prédire les risques par composant.

### Profils de contexte

Chaque profil amplifie les risques spécifiques à son domaine :

| Profil | Risques amplifiés |
|--------|-------------------|
| `CTX-FINTECH` | Calculs financiers, conformité, audit trail, chiffrement |
| `CTX-ECOMMERCE` | Paiement, stock, panier, promotions |
| `CTX-HEALTH` | Données patient, conformité, anonymisation |
| `CTX-SAAS` | Multi-tenancy, rate limiting, authentication |
| `CTX-IOT` | Connectivité, firmware, ressources limitées |
| `CTX-GENERIC` | Profil neutre, aucune amplification |
| `CTX-BA-QA` | Business analysis, exigences, traçabilité |
| `CTX-WEBAPP` | XSS, CSRF, sessions, CSP, headers HTTP |

---

## Cycle cognitif — Détails

Le cycle cognitif transforme l'expérience brute (épisodes) en connaissance structurée.
Il suit trois phases **dans un ordre strict** :

```
Consolidation ──▶ Decay ──▶ Reflection
```

### Phase 1 — Consolidation

Parcourt les épisodes et :
- Identifie les patterns/heuristiques référencés
- Extrait de nouveaux candidats patterns
- Découvre des associations composant → défaut
- **Renforce la confiance** des connaissances confirmées

| Signal | Boost de confiance |
|--------|--------------------|
| Correspondance avec un incident | +0.03 |
| Référencé dans une analyse | +0.02 |
| Heuristique appliquée | +0.01 |

### Phase 2 — Decay (oubli contrôlé)

Applique un déclin de confiance sur les connaissances inactives :

- **Période de grâce** : aucun decay si utilisé dans les 60 derniers jours
- **Catégories protégées** : `security` et `critical` ne déclinent jamais
- **Incidents critiques** : patterns liés à des P0/P1 protégés
- **Taux réduit** : patterns avec occurrences > 0 → 0.02/mois au lieu de 0.05
- **Seuil de suppression** : confiance < 0.20 → candidat au retrait

| Catégorie | Taux/mois | Catégorie | Taux/mois |
|-----------|-----------|-----------|-----------|
| performance | 0.03 | regression | 0.06 |
| data_integrity | 0.03 | ui | 0.07 |
| error_handling | 0.04 | seo | 0.06 |
| api | 0.04 | functional | 0.05 |
| accessibility | 0.03 | requirements | 0.05 |
| concurrency | 0.03 | async | 0.04 |
| null_safety | 0.04 | *(défaut)* | 0.05 |

### Phase 3 — Reflection

Exécute **12 contrôles de santé** regroupés en 5 catégories :

| Catégorie | Nb | Contrôles |
|-----------|----|-----------|
| **Cohérence** | 3 | Sync compteurs index ↔ fichiers, validité des références croisées |
| **Complétude** | 4 | Couverture des types d'épisodes, population relationnelle, champs requis |
| **Fraîcheur** | 3 | Consolidation récente, backlog ≤ 5 épisodes, items conf. < 0.40 |
| **Équilibre** | 2 | Diversité catégorielle (≥ 3 catégories), ratio connaissance/expérience |
| **Connectivité** | 1 | Détection de cycles dans les associations |

---

## Limites & Politiques de sécurité

| ID | Politique | Valeur |
|----|-----------|--------|
| SEC-001 | Anti-ReDoS | Timeout sur les regex, patterns pré-compilés |
| SEC-002 | Anti-OOM | Max 500 Ko par entrée de code, 1000 résultats max |
| SEC-003 | Rate limiting analyses | 100 analyses par jour |
| SEC-004 | Findings cap | Max 50 findings par analyse |
| SEC-005 | Rate limiting sémantique | 200 enregistrements patterns/heuristiques par jour |
| SEC-006 | Path traversal | Validation des chemins, restriction au data dir |
| SEC-007 | File locking | Verrouillage des écritures concurrentes |
| SEC-008 | Rate limiting épisodique | 100 enregistrements épisodiques par jour |

**Constantes de configuration** (définies dans `mcp_server/engines/config.py` et `mcp_server/app.py`) :

| Constante | Valeur | Description |
|-----------|--------|-------------|
| `MAX_CODE_INPUT_SIZE` | 500 000 | Taille max du code en entrée (caractères) |
| `MAX_FINDINGS_COUNT` | 50 | Max findings par analyse |
| `MAX_DAILY_ANALYSES` | 100 | Analyses par jour |
| `MAX_DAILY_RECORDS` | 200 | Écritures sémantiques par jour |
| `MAX_DAILY_EPISODES` | 100 | Écritures épisodiques par jour |
| `DECAY_RATE` | 0.05/mois | Taux de decay de base |
| `DECAY_RATE_REINFORCED` | 0.02/mois | Taux pour items renforcés |
| `DECAY_THRESHOLD` | 0.20 | Confiance min avant retrait |
| `DECAY_GRACE_DAYS` | 60 | Période de grâce sans decay |
| `LOW_CONFIDENCE` | 0.40 | Seuil d'alerte confiance faible |
| `CRITICAL_THRESHOLD` | 15.0 | Score de risque « critical » |
| `HIGH_THRESHOLD` | 8.0 | Score de risque « high » |

---

## Exemple de workflow complet

### 1. Diagnostiquer la mémoire

```
get_memory_health()
→ Rapport de santé : 46 patterns, 62 heuristiques, contrôles par catégorie
```

### 2. Analyser un code suspect

```
get_risk_analysis(
  code_or_diff: "def login(req): query = f\"SELECT * ...\"",
  context_profile: "CTX-SAAS"
)
→ Niveau: critical, PAT-SEC-001 (injection SQL) détecté
```

### 3. Obtenir une stratégie de test

```
get_testing_strategy(
  change_description: "Refactoring auth pour ORM",
  change_type: "security",
  components_affected: ["auth", "database"]
)
→ Tests de sécurité, intégration, régression recommandés
```

### 4. Générer un scaffold de test

```
generate_test_scaffold(
  code: "def calculate_discount(price, pct): ...",
  language: "python"
)
→ Fichier de test complet avec fixtures, happy path, edge cases
```

### 5. Obtenir les cas de test détaillés

```
get_test_cases(
  description: "Calcul de réduction sur le panier",
  context_profile: "CTX-ECOMMERCE",
  component_type: "function"
)
→ Liste priorisée : TC-001 happy path, TC-002 boundary 0%, TC-003 boundary 100%...
```

### 6. Auditer la sécurité

```
audit_code_security(
  code: "password = 'admin123'",
  severity_threshold: "medium"
)
→ SEC-SECRETS-001: credentials hardcodés (CWE-798), remédiation proposée
```

### 7. Auditer la performance

```
audit_code_performance(
  code: "for x in list1:\n  for y in list2:\n    ...",
  resources: ["cpu"]
)
→ PERF-ALGO-001: O(n²), refactoring avec dict/set proposé
```

### 8. Enregistrer les résultats

```
record_analysis(title: "Audit sécurité auth", findings: [...], verdict: "rejected")
→ ANL-20260329-001

record_incident(title: "SQL injection prod", severity: "P1", ...)
→ INC-20260329-001
```

### 9. Lancer le cycle cognitif

```
run_cognitive_cycle(phase: "all", apply: false)  # Preview
run_cognitive_cycle(phase: "all", apply: true)   # Apply
→ Consolidation: PAT-SEC-001 renforcé (+0.05), Decay: 0 items, Reflection: HEALTHY
```

---

## Tableau récapitulatif

| # | Outil | Catégorie | Description courte |
|---|-------|-----------|-------------------|
| 1 | `query_memory` | Lecture | Interroger la mémoire (patterns, heuristiques, épisodes…) |
| 2 | `get_risk_analysis` | Analyse | Analyser les risques d'un code via 46 patterns |
| 3 | `get_testing_strategy` | Analyse | Recommander une stratégie de test |
| 4 | `get_memory_health` | Diagnostic | Diagnostic de santé mémoire (12 contrôles) |
| 5 | `record_analysis` | Épisodique | Enregistrer une analyse |
| 6 | `record_decision` | Épisodique | Enregistrer une décision |
| 7 | `record_incident` | Épisodique | Enregistrer un incident |
| 8 | `record_execution` | Épisodique | Enregistrer une exécution de tests |
| 9 | `record_pattern` | Sémantique | Enregistrer un pattern de défaut |
| 10 | `record_heuristic` | Sémantique | Enregistrer une heuristique de test |
| 11 | `run_cognitive_cycle` | Cognitif | Lancer le cycle (consolidation/decay/reflection) |
| 12 | `generate_test_scaffold` | Test | Générer un squelette de tests |
| 13 | `get_test_cases` | Test | Recommander les cas de test |
| 14 | `audit_code_security` | Sécurité | Audit statique — 28 règles, 11 domaines |
| 15 | `audit_code_performance` | Performance | Audit statique — 30 règles, 10 domaines |
