# 👁️ Argus — QA Orchestrator Persona

> *"Celui aux cent yeux qui voit ce que d'autres ne voient pas"*

Argus est un système de persona IA spécialisé en test et qualité logicielle, construit sur le framework **CRAFT/TOON**. Il orchestre une constellation d'agents spécialisés et maintient une mémoire structurée à 5 niveaux.

## Architecture

```
argus.persona.yaml          # Persona CRAFT/TOON (v0.10.0)
mcp_server/                 # Serveur MCP — expose Argus aux clients IA
├── server.py               # 4 tools : query_memory, get_risk_analysis, 
│                           #           get_testing_strategy, record_analysis
├── memory_reader.py        # Accès lecture à la mémoire YAML
├── data_dir.py             # Résolution du répertoire de données
└── defaults/               # Données par défaut (base de connaissances)
    ├── semantic/            # 46 patterns, 62 heuristiques, 8 profils
    └── deliverables/        # Templates (test plan, matrice, charte)
memory/                     # Système de mémoire à 5 niveaux
├── working/                # Mémoire de travail (session)
├── episodic/               # Historique (analyses, décisions, incidents, exécutions)
├── semantic/               # Connaissances apprises (patterns, heuristiques, ISTQB)
├── projects/               # Profils par projet
└── relational/             # Graphe d'associations
schemas/                    # JSON Schemas (Draft-07) pour validation
scripts/                    # Scripts d'installation (hooks Git)
tests/                      # Suite de validation & tests (330 tests)
```

## Installation

### Option 1 — Via pip (recommandé)

```bash
pip install argus-qa
```

Au premier lancement, Argus crée automatiquement `~/.argus/` avec la base de connaissances par défaut (46 patterns de défauts, 62 heuristiques de test, 8 profils de contexte).

### Option 2 — Depuis les sources (développement)

```bash
git clone https://github.com/argus-qa/argus.git
cd argus
pip install -e ".[dev]"
```

### Répertoire de données

| Priorité | Source | Usage |
|----------|--------|-------|
| 1 | `ARGUS_DATA_DIR` (env var) | Tests, setups custom |
| 2 | `./memory/` dans le CWD | Mode dev (clone git) |
| 3 | `~/.argus/memory/` | Installation pip (défaut) |

## Prérequis

- Python 3.11+
- Dépendances : `pip install -r requirements.txt`

## Démarrage rapide

```bash
# Installer les dépendances
pip install -r requirements.txt

# Installer le hook pre-commit (5 validations automatiques)
.\scripts\install-hooks.ps1

# Lancer la suite de tests complète
python -m pytest tests/ -v

# Exécuter le cycle cognitif (scan mémoire)
python tests/cognitive_cycle.py
```

## Validation

Le projet dispose d'un pipeline de validation à 5 couches, exécuté automatiquement via le hook pre-commit :

| Étape | Script | Description |
|-------|--------|-------------|
| 1 | `tests/validate_yaml.py` | Syntaxe YAML |
| 2 | `tests/sync_counters.py` | Synchronisation index/compteurs |
| 3 | `tests/validate_references.py` | Références croisées inter-fichiers |
| 4 | `tests/validate_encoding.py` | Détection BOM/mojibake |
| 5 | `tests/sync_schemas.py` | Cohérence enums JSON Schema |

Scripts additionnels :
- `tests/validate_schemas.py` — Validation YAML contre JSON Schemas
- `tests/validate_risk_scoring.py` — Validation du scoring de risque

## Cycle cognitif

Le système maintient sa mémoire via un cycle en 3 phases :

1. **Consolidation** — Transforme les épisodes récurrents en connaissances sémantiques
2. **Decay** — Applique un oubli progressif aux connaissances non utilisées (grâce : 60j, taux : 0.05/mois, seuil : 0.2)
3. **Reflection** — 12 health checks (cohérence, complétude, fraîcheur, équilibre)

```bash
python tests/cognitive_cycle.py              # Scan (dry-run)
python tests/cognitive_cycle.py --apply      # Appliquer les corrections
python tests/cognitive_cycle.py --phase decay # Une seule phase
```

## CI/CD

GitHub Actions (`.github/workflows/validate.yml`) exécute la validation complète sur chaque push/PR :
- Branches : `main`, `develop`
- Matrice Python : 3.11, 3.12, 3.13
- 6 étapes de validation + suite pytest complète

## Mémoire

Voir [memory/README.md](memory/README.md) pour la documentation détaillée du système de mémoire.

## Serveur MCP

Argus expose ses capacités via le [Model Context Protocol](https://modelcontextprotocol.io/) (MCP). N'importe quel client compatible (VS Code, Claude Desktop, Cursor…) peut s'y connecter.

### Tools disponibles

| Tool | Description |
|------|-------------|
| `query_memory` | Interrogation de la mémoire (patterns, heuristiques, analyses, stats…) |
| `get_risk_analysis` | Analyse de risque sur un extrait de code ou diff |
| `get_testing_strategy` | Recommandation de stratégie de test selon le contexte |
| `record_analysis` | Enregistrement d'une analyse en mémoire épisodique |

### Lancement

```bash
# Via la commande installée par pip
argus-mcp

# Ou via le module Python
python -m mcp_server
```

### Configuration VS Code

Ajouter dans le fichier `.vscode/mcp.json` de n'importe quel projet :

```json
{
  "servers": {
    "argus": {
      "type": "stdio",
      "command": "argus-mcp"
    }
  }
}
```

### Configuration Claude Desktop

Ajouter dans `claude_desktop_config.json` :

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

## Sécurité

- Les données utilisateur sont stockées localement dans `~/.argus/` et ne sont jamais transmises
- Le serveur MCP fonctionne en transport stdio (local uniquement)
- Les entrées sont validées (taille, rate limiting, path traversal)
- Les dépendances sont plafonnées pour prévenir les attaques supply chain

## Avertissement

Argus est un outil d’aide à l’analyse qualité. Il **ne remplace pas** un audit de sécurité
professionnel et ne garantit pas la détection exhaustive des défauts. Utilisez-le comme
couche complémentaire dans votre processus de test, jamais comme unique source de vérité.

## Licence

[MIT](LICENSE)
