ia_dev/README.md

# ia_dev

Dépôt de pilotage par l'IA pour les projets : **équipe d'agents IA** dont le code et les définitions sont dans ia_dev, lancés de façon centralisée pour tous les projets configurés (lecoffreio, enso, algo, etc.) ; ils agissent sur ces projets, pas sur ia_dev. Objectif : une équipe autonome couvrant la **documentation**, le **code** (correctifs, évolutions), le **ticketing** (issues Gitea, mails), le **devops** (push, déploiement, branches), la **sécurité** et la **qualité** (lint, règles).

**Principe** : ia_dev est un **dépôt autonome** (usage unique : standalone). La config par projet est dans `projects/<id>/conf.json` ; l'id projet est résolu par **MAIL_TO** (adresse « to » des mails) ou **AI_AGENT_TOKEN** (token des requêtes). Voir `projects/README.md`.

## Usage (standalone)

- **Racine d'exécution** : tous les scripts sont lancés depuis la **racine de ia_dev** (ce dépôt). L'id projet est résolu uniquement par **MAIL_TO** ou **AI_AGENT_TOKEN** (voir `projects/README.md`).
- **Config** : dans `projects/<id>/conf.json`, les champs `project_path`, `build_dirs`, `deploy.scripts_path`, `deploy.deploy_script_path`, `deploy.secrets_path`, `version.package_json_paths` sont des **chemins absolus** (vers les dépôts des projets). Les champs `mail.imap_bridge_env` et `git.token_file` sont **relatifs à la racine de ia_dev**. Le répertoire `.secrets` à la racine de ia_dev contient `token` et `gitea-issues/agent-loop.env`, `gitea-issues/imap-bridge.env`.

Voir `projects/README.md` pour le schéma de configuration et les exemples.

## Agents et domaines

Les **agents** ont leur **code et définitions** dans ia_dev (`.cursor/agents/`, `.cursor/rules/`) et sont **lancés de façon centralisée** depuis ce dépôt pour **tous les projets**. Ils sont **dédiés aux projets configurés** (lecoffreio, enso, algo, etc.) : ils agissent sur ces projets (doc, code, déploiement, ticketing), pas sur ia_dev. ia_dev est uniquement le projet qui porte leurs définitions et d'où on les invoque.

Chaque agent indique où se trouve la doc : **projets gérés** → `projects/<id>/docs` ; **ia_dev** → `projects/ia_dev/docs`.

| Domaine | Agents / composants |
|---------|---------------------|
| **Doc** | `docupdate` ; `projects/ia_dev/docs/` (GITEA_ISSUES_SCRIPTS_AGENTS, TICKETS_SPOOL_FORMAT, WORKFLOWS_AND_COMPONENTS) ; migration wiki (`gitea-issues/wiki-migrate-docs.sh`). |
| **Code** | `fix`, `evol`, `code`, `fix-search` ; workflow correctifs/évolutions (fix-search → fix → push-by-script ; evol + code). |
| **Ticketing** | `gitea-issues-process`, `agent-loop` ; spooler `projects/<id>/data/issues` ; scripts `gitea-issues/` (issues Gitea, mails, boucle récupération/traitement) ; hook `.cursor/hooks/remonter-mails.sh`. |
| **IA notaire (ai_working_help)** | `notary-ai-loop`, `notary-ai-process` ; API `ai_working_help/server.js` (POST enqueue, GET response) ; spooler `projects/<id>/data/notary-ai/{pending,responded}` ; scripts `ai_working_help/notary-ai/` (list-pending, write-response). |
| **DevOps** | `push-by-script`, `deploy-by-script`, `deploy-pprod-or-prod`, `branch-align-by-script-from-test`, `change-to-all-branches` ; scripts `deploy/` (pousse.sh, scripts_v2, alignement branches). |
| **Sécurité / Qualité** | Règles `.cursor/rules/` ; pas de secrets en dur (`.secrets`, config par projet) ; `fix-lint` ; clôture obligatoire (`.cursor/rules/cloture-evolution.mdc`) pour tous les agents. |

Référence détaillée scripts et agents : `projects/ia_dev/docs/GITEA_ISSUES_SCRIPTS_AGENTS.md`. Index de la doc ia_dev : `projects/ia_dev/docs/README.md`.

## Répertoire d'exécution (standalone)

Tous les scripts sont invoqués depuis la **racine de ia_dev** (ce dépôt).

- **deploy/** : scripts qui **déploient les projets configurés** (lecoffreio, enso, algo, etc.) dans leurs répertoires, pas ia_dev. Ils utilisent les chemins absolus de `projects/<id>/conf.json` pour agir sur chaque projet.
- **gitea-issues/** : **logs** et **data** (spooler tickets) par projet sous `projects/<id>/logs/` et `projects/<id>/data/issues/` (id résolu par MAIL_TO ou AI_AGENT_TOKEN).
- **ai_working_help/** : API (server.js) et scripts `notary-ai/` ; spooler par projet sous `projects/<id>/data/notary-ai/{pending,responded}`. Doc : `ai_working_help/docs/notary-ai-api.md`.

## Scripts centralisés (deploy/)

Les scripts dans `deploy/` **déploient et versionnent les projets configurés** (lecoffreio, enso, algo, etc.) dans leurs répertoires — ils ne déploient pas ia_dev. À lancer depuis la racine de ia_dev. Chaque script accepte en option un **project_id** en premier argument (ou `--project <id>` pour pousse.sh) pour cibler le projet ; sinon le projet est résolu par MAIL_TO ou AI_AGENT_TOKEN. Les chemins absolus dans `projects/<id>/conf.json` indiquent où se trouve chaque projet et ses scripts de déploiement.

**Orchestration générique (métier dans le dépôt cible)** :

- **deploy.sh** : point d’entrée `./deploy/deploy.sh <project_id> <env> [options…]` — exporte `IA_PROJECT_ID`, puis exécute **orchestrator.sh** (même contrat que les scripts ci-dessous qui invoquent l’orchestrateur lorsque `IA_PROJECT_ID` est défini).
- **orchestrator.sh** : lit `deploy.hooks.phases` dans `conf.json` (chemins relatifs à `repository_root`) ; si `phases` est vide, exécute `deploy.deploy_script_path`. Le métier (Prisma, systemd, build distant, etc.) reste dans les scripts du projet.
- **run-project-hooks.sh** : délègue à **orchestrator.sh** (alias pour compatibilité avec les anciennes invocations).

- **bump-version.sh** : lit `projects/<id>/conf.json` (version.package_json_paths, version.splash_app_name) et met à jour VERSION + package.json du **projet configuré**. Invocation : `./deploy/bump-version.sh [project_id] <version> [message]` depuis la racine de ia_dev.
- **deploy-by-script-to.sh** : checkout branche cible (pprod|prod), sync origin, exécute `deploy/scripts_v2/deploy.sh` du **projet configuré** (chemin dans conf), puis revient sur test. Invocation : `./deploy/deploy-by-script-to.sh [project_id] <pprod|prod>`.
- **pousse.sh** : build check, commit, push. Invocation : `./deploy/pousse.sh [project_id|--project <id>] [--remote <remote>] [--bump-version]` avec le message de commit sur STDIN.
- **branch-align.sh** : aligne origin/test, origin/pprod, origin/prod. Invocation : `./deploy/branch-align.sh [project_id] <env>`.
- **change-to-all-branches.sh** : aligne les branches puis déploie test. Invocation : `./deploy/change-to-all-branches.sh [project_id]`.
- **deploy/_lib/** : bibliothèque partagée pour les scripts de déploiement. Les `deploy/scripts_v2/` de chaque projet peuvent s'y lier (symlink) pour réutiliser cette lib.