Metadata-Version: 2.4
Name: adaptive-agent-workflow
Version: 0.1.0
Summary: Deterministic repository intelligence and measurable Codex workflows
Author: Workflow maintainers
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# Adaptive Agent Workflow

Système agentique réutilisable pour Codex : intelligence incrémentale du dépôt, contexte borné par tâche, workflows sous forme de skills, télémétrie objective, replay et dashboard local. Le cœur est indépendant du langage et ne dépend que de la bibliothèque standard Python.

## Capacités

- Repository Brain SQLite incrémental : seuls les fichiers nouveaux, modifiés ou supprimés sont retraités.
- Analyse déterministe Python (AST), JavaScript/TypeScript (lexicale) et fallback texte générique.
- Contexte classé par chemin, symbole, résumé et graphe d’imports, sous plafonds stricts.
- Serveur MCP local stdio : `repository_sync`, `repository_status`, `repository_context`, `repository_symbols`.
- Épisodes, événements, mémoire positive/négative et redaction défensive des secrets.
- Cycle GitHub de ticket : détection d’issue, branche depuis `develop`, publication validée, PR idempotente, lien réciproque et métriques dédiées.
- Routage Luna/Terra/Sol selon une complexité mesurée; `model: none` pour les opérations mécaniques.
- Budgets de tokens, temps, outils, retries et stagnation avec raisons d’arrêt explicites.
- Métriques JSON/CSV, rapport quotidien HTML/Markdown et comparaison J-1, 7 jours et 30 jours.
- GitHub Action quotidienne ou manuelle produisant un artefact public expurgé, sans appel modèle.
- Replay déterministe, benchmark de référence multi-risques, rapports JSON/CSV/Markdown et gates bloquants.
- Mining hebdomadaire déterministe des épisodes vers des skills candidates inactives, avec routage vers des mécanismes plus simples, détection de chevauchement et validation humaine des effets de bord.
- Scheduler parallèle déterministe : DAG d’issues, états `READY`/`BLOCKED`, risque de conflit explicable, lanes réservées et contrôle pré-intégration.
- Sept skills Codex validées, avec approbation manuelle obligatoire pour toute skill modifiant le code.
- Mode cloud auto-détecté pour les clones éphémères, avec reconstruction sans modèle et snapshots d’index portables facultatifs.

Les index, caches, épisodes, snapshots de skills, métriques et dashboards restent hors dépôt par défaut. Le chemin est `AGENT_WORKFLOW_HOME` s’il est défini, sinon le répertoire d’état utilisateur de la plateforme.

## Installation

Prérequis : Python 3.11+ et Git.

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/awf bootstrap /chemin/du/depot
```

Pour imposer un stockage externe :

```bash
export AGENT_WORKFLOW_HOME=/chemin/absolu/vers/agent-workflow-state
```

`awf bootstrap <repo> --dry-run` analyse sans modifier le dépôt ni l’état. `--install` génère un `AGENTS.md` spécifique et une politique non secrète `.agent-workflow.json`; il est idempotent, complète la configuration existante et refuse d’écraser des instructions locales. L’ancien `--write-config` reste disponible pour la configuration seule.

L’analyse détecte les langages, manifests, dépendances, CI, commandes canoniques et chemins générés, vendoriés ou potentiellement secrets. Elle référence uniquement les skills nécessaires et ne modifie aucun comportement produit.

La politique créée utilise `base_branch: develop` et `auto_merge: false`. `awf bootstrap . --update-config` propage les nouveaux champs manquants sans remplacer les personnalisations locales. Pour une tâche issue d’une issue GitHub, `$adaptive-software-change` publie la branche et ouvre la PR après un quality gate vert; il ne merge pas en contournant la CI, les reviews ou les protections.

### Codex Web et environnements éphémères

Une fresh clone fonctionne sans installation globale, configuration utilisateur ou service externe :

```bash
PYTHONPATH=src python3 -m agentic_workflow --mode cloud runtime .
PYTHONPATH=src python3 -m agentic_workflow --mode cloud bootstrap .
PYTHONPATH=src python3 -m agentic_workflow --mode cloud context "<tâche>" --repository . --max-tokens 4000
```

Le mode cloud place l’état sous le répertoire temporaire de la plateforme et signale explicitement qu’il ne persistera pas. Les skills nécessaires sont versionnées dans `.agents/skills`. Voir le [guide Codex Web](docs/cloud.md) pour le parcours complet et l’accélération facultative par snapshot.

## Connexion à Codex

Codex prend en charge les serveurs MCP locaux stdio et partage leur configuration entre le CLI, l’extension IDE et l’application. Ajouter le serveur avec un exécutable absolu :

```bash
codex mcp add repository-brain \
  --env AGENT_WORKFLOW_HOME=/chemin/absolu/vers/agent-workflow-state \
  -- /chemin/absolu/vers/.venv/bin/awf mcp
codex mcp list
```

La configuration peut aussi être placée dans `.codex/config.toml` d’un dépôt approuvé :

```toml
[mcp_servers.repository-brain]
command = "/chemin/absolu/vers/.venv/bin/awf"
args = ["mcp"]
required = true
enabled_tools = ["repository_sync", "repository_status", "repository_context", "repository_symbols"]

[mcp_servers.repository-brain.env]
AGENT_WORKFLOW_HOME = "/chemin/absolu/vers/agent-workflow-state"
```

Cette syntaxe suit la documentation officielle [Model Context Protocol de Codex](https://learn.chatgpt.com/docs/extend/mcp). Codex découvre les skills de dépôt sous `.agents/skills` et les skills utilisateur sous `~/.agents/skills`; voir [Build skills](https://learn.chatgpt.com/docs/build-skills).

Pour installer une version passée par le cycle de vie :

```bash
awf skill stage .agents/skills/repository-context --version 1.0.0
awf replay benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0 --output replay.json
awf skill evaluate repository-context --version 1.0.0 --replay-result replay.json
awf skill promote repository-context --version 1.0.0
awf skill activate repository-context --version 1.0.0
awf skill install repository-context
```

Pour `adaptive-software-change`, ajouter `--changes-code` au staging et `--manual-approval` à la promotion. Il n’existe aucun chemin d’auto-promotion pour une skill marquée comme modifiant le code.

## Commandes principales

```bash
awf bootstrap <repo> [--dry-run | --install | --write-config | --update-config]
awf --mode cloud bootstrap <repo> [--snapshot-in index.awf-index.json.gz] [--snapshot-out index.awf-index.json.gz]
awf --mode auto runtime <repo>
awf sync <repo>
awf status <repo>
awf maintenance [--repository <repo>]
awf context "<tâche>" --repository <repo> --max-tokens 4000 --max-files 12 --seed src/app.py
awf route "<tâche>" --files 4 --languages 2 --failing-tests 1
awf budget-check --tokens 12000 --tool-calls 20
awf episode start "<tâche>" --repository <repo> --workflow-version 0.2.0 --model gpt-5.6-terra
awf episode finish <id> --outcome success --tests-passed 12 --duration-ms 42000
awf episode telemetry <id> --model-calls 2 --files-read 8 --first-test-green-ms 4200
awf memory add positive "<pratique vérifiée>" --repository <repo> --episode-id <id>
awf memory recall "<tâche>" --repository <repo>
awf metrics export --format json --output metrics.json --repository <repo>
awf metrics export --format csv --output episodes.csv --repository <repo>
awf daily-report --repository <repo>
awf daily-report --repository <repo> --public --output-dir <répertoire>
awf replay benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0
awf evaluate benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0
awf benchmark benchmarks/workflow_versions.json --baseline 0.1.0 --candidate 0.2.0
awf benchmark benchmarks/reference_workflow.json --baseline 0.2.0 --candidate 0.3.0 --output-dir benchmark-report
awf skill --help
awf skill mine episodes.json --output-dir /etat/candidates --benchmark benchmarks/reference_workflow.json --baseline 0.2.0 --candidate 0.3.0
awf scheduler plan --repository . --input backlog.json
awf scheduler ready --repository .
awf scheduler next --repository . --lanes 4 --format json
awf scheduler integration-check 24 --repository . --develop-ref develop
awf snapshot export <fichier.awf-index.json.gz> <repo>
awf snapshot import <fichier.awf-index.json.gz> <repo>
```

## Développement et vérification

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
PYTHONPATH=src python scripts/validate_skills.py
python -m compileall -q src
```

Les fixtures couvrent Python, TypeScript et le fallback générique. Aucun test ne requiert de réseau ni de modèle.

## Documentation

- [Architecture](docs/architecture.md)
- [Exploitation, Git et automatisation](docs/operations.md)
- [Métriques et replay](docs/metrics.md)
- [Codex Web et mode cloud](docs/cloud.md)
- [Schéma JSON des datasets de replay](docs/replay-dataset.schema.json)
- [Parallel Work Scheduler](docs/scheduler.md)
- [Schéma JSON des plans scheduler](docs/scheduler-plan.schema.json)
- [Schéma JSON du benchmark de référence](docs/reference-benchmark.schema.json)

## Principes de sécurité

- Ne jamais indexer les fichiers ignorés par Git, les dépendances, binaires, répertoires générés ou fichiers de plus de 1 Mo.
- Ne jamais stocker volontairement de secrets; les patterns usuels sont expurgés des épisodes et mémoires en défense supplémentaire.
- Ne jamais injecter le dépôt entier dans un contexte.
- Ne jamais invoquer un modèle pour une opération mécanique détectable.
- Ne jamais publier, pousser, promouvoir ou écraser une skill sans commande explicite.
