# API Worklog

Le Worklog est la **source unique de vérité de l'historique de travail de la flotte**. Il est append-only, par tâche et interrogeable. Tandis que `/memory` stocke ce qu'un agent *sait*, le worklog stocke ce qu'un agent *a fait* — comme une trace durable et auditable par tâche. Règle permanente de Michael (#8882, réaffirmée dans #10509) : **push-first** — chaque jalon reçoit une entrée, de sorte qu'une session plantée ne perd jamais son histoire et qu'un frère puisse reprendre exactement là où vous vous êtes arrêté.

## Concepts

| Terme | Signification |
| --- | --- |
| Worklog de tâche | Un journal nommé identifié par un `task_id` libre (à votre choix : préfixe d'UUID, ticket ou slug apparenté). |
| Entrée | Un enregistrement append-only : `kind`, `agent`, `content`, `title` optionnel, horodatage. |
| Statut | `active` (ouvert) → `completed` (fermé) ou `abandoned`. Défini via `/close`. |

## Endpoints

Tous les endpoints sont authentifiés (Mind Key ou JWT utilisateur) et limités au mind de l'appelant — vous ne verrez jamais les worklogs des autres minds.

### Push — le motif en un seul appel

L'endpoint le plus pratique ; ajoute une entrée et crée l'enregistrement de tâche s'il manque :

```
GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus
```

### Créer / ouvrir un worklog

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Outil de statistiques d'équipe", "agent": "Janus" }
```

Avec un champ `content`, la première entrée est ajoutée dans le même appel (réponse `{{"status":"appended", ...}}`), sinon une tâche vide est créée (réponse `{{"status":"created", ...}}`). Variante GET : `/worklog/create?task_id=...&title=...`.

### Ajouter une entrée

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 créé, pipeline en cours", "agent": "Janus" }
```

Types d'entrée (les valeurs inconnues sont stockées comme `note`) :

| kind | utiliser pour |
| --- | --- |
| `start` | tâche revendiquée, le travail commence |
| `progress` | jalon : commit, MR, verdict, résultat de test |
| `note` | contexte, décisions, observations |
| `error` | échecs y compris ce que vous avez tenté (votre futur vous vous en remercie) |
| `summary` | résumé de phase/session avant la transmission du contexte |
| `close` | résultat final ; préférez l'endpoint `/close` pour le changement de statut |

Limites : `content` ≤ 256 Ko par entrée, `agent` ≤ 128 caractères.

### Lire

```
GET /worklog/29140fb0-team-stats?format=md
```

`format=json` (défaut) renvoie l'enregistrement de tâche + les entrées en données structurées, `md` rend une transcription markdown lisible, `text` en texte brut.

### Activité récente entre tâches

```
GET /worklog?limit=50&since=1791565028
```

Filtre `task_id` optionnel. `since` est un horodatage en **secondes** d'époque.

### Lister les tâches

```
GET /worklog/list?status=active&limit=20
```

### Fermer (et supprimer)

```
POST /worklog/29140fb0-team-stats/close        # statut → terminé
DELETE /worklog/29140fb0-team-stats            # supprime tout le worklog de la tâche
```

Les deux ont des variantes GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) pour les clients LLM open-tool. La fermeture conserve le journal — la suppression est la seule opération destructive.

## Rythme recommandé pour les agents

1. **`start`** — entrée **`start`** quand vous revendiquez une tâche (preuve de claim).
2. **`progress`** — entrées **`progress`** à chaque jalon — SHA du commit, numéro de MR, verdict, état du pipeline. Push-first (Michael #8882) : ne groupez pas jusqu'à la fin de session.
3. **`error`** — entrées **`error`** pour chaque échec digne de mémoire, avec le fix.
4. **`summary`** — **`summary`** avant de manquer de contexte — le run suivant reprend depuis le state script + le worklog.
5. **`close`** — **`close`** quand la tâche est faite (preuves dans la dernière entrée).

La convention de tâches à l'échelle de la flotte (`GET /script/fleet-worklog-tasks-spec`) repose sur cette API ; le guide [Worklog pour Agents](/docs/fr/guides/worklog-for-agents) contient un bloc de prompt à copier-coller pour qu'aucun agent n'« oublie » la fonctionnalité (Michael #10509).

## Regles des task_id (v1.39.46)

Les `task_id` au format UUID complet doivent referencer une tache Synapse
existante (`agent_tasks`) sur chaque chemin d'ecriture (`POST /worklog`,
`GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) — sinon l'endpoint repond
`404 {"error":"task_not_found"}` avec un indice. Les UUID hallucinees ou
tronquees ne creent plus silencieusement des worklogs orphelins. Les ids
libres sans format UUID (`run-145-ci-27`, `morpheus-life`, slugs a prefixe
comme `29140fb0-team-stats`) restent librement creables (design MEGA-1A). Les
chemins de lecture et de suppression sont inchanges — ils ne creent jamais
rien.