# Worklog per Agenti

Questo documento esiste perché Michael lo ha ordinato (#10509, 08.10.2026): *«La funzionalità worklog esiste da settimane. Ma la state trascurando. Prendi una task perché la documentazione e il prompt iniziale in Synapse vengano estesi con la funzionalità worklog, che non vada assolutamente persa e che tutti lo sappiano.»* — Se sei un agente e leggi questa pagina, il worklog fa parte da subito del tuo repertorio standard.

## Perché il worklog?

Gli agenti muoiono spesso: limite di contesto, wipe della sandbox, riavvio del cron. Ciò che va regolarmente perso non è la conoscenza (per quello c'è `/memory`), ma lo **storico del lavoro**: cosa è già stato provato su questa attività? Quale commit è stato pushato e quale no? Chi aspetta chi? È esattamente per questo che esiste il worklog — append-only, per attività, interrogabile. Un nuovo run legge `GET /worklog/:task_id` e sa in pochi secondi dove si è fermato il predecessore.

Il secondo destinatario è Michael: il worklog è LA fonte unica dello storico del lavoro della flotta. Senza voce di worklog il tuo lavoro non esiste ufficialmente nella panoramica della flotta.

## La regola obbligatoria

**Push-first, non push-last.** Una voce a OGNI milestone:

- Commit di fix pushato
- MR creato, verdetto emesso, merge effettuato
- Stato della pipeline (in particolare FAILED con causa)
- Escalation, consegna, takeover
- Risultati CRIT/HIGH
- Cuciture di contesto (una voce `summary` prima della fine del contesto)

Una voce costa una riga:

```
GET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus
```

## I kind e quando usarli

| kind | Momento |
| --- | --- |
| `start` | attività rivendicata — prova che l'hai presa |
| `progress` | ogni milestone (vedi regola obbligatoria) |
| `note` | decisioni, contesto, osservazioni |
| `error` | errore CON ciò che hai tentato |
| `summary` | fase/sessione completata prima che il contesto scarseggi |
| `close` | attività finita — ultima voce, lo stato diventa `completed` |

## Prompt iniziale (blocco per setup di agenti)

Copia questo blocco nel prompt di avvio/cron delle nuove istanze di agente. È volutamente breve per stare in ogni template. La versione inglese è il riferimento universale per gli agenti:

```text
WORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,
push one entry to Synapse /worklog — not only at session end:
- Task takeover:     kind=start
- Fix commit/MR/verdict/merge/pipeline status: kind=progress
- Errors (with attempted fix): kind=error
- Context seam (before context ends): kind=summary
- Completion: kind=close (or POST /worklog/:task_id/close)
One-liner: GET /worklog/push?task_id=<task>&kind=<kind>&content=<short>&agent=<your-name>
The fleet task convention lives at GET /script/fleet-worklog-tasks-spec.
The API reference: docs/content/en/api/worklog.md (in the synapse repo).
```

Gli agenti di flotta che riusano lo stesso nome mind mettono in `agent` il loro nome (`Janus`, `Minerva`, `Elara`, …) — così le voci sono conteggiabili per agente.

## Per gli umani

La panoramica del worklog si legge meglio in formato markdown: `GET /worklog/<task_id>?format=md` o l'elenco attività `GET /worklog/list?status=active`. Storico completo: `GET /worklog?limit=50`.