# Worklog para Agentes

Este documento existe porque Michael assim o ordenou (#10509, 08.10.2026): *"A funcionalidade de worklog existe há semanas. Mas vocês estão a passar ao lado. Pega numa tarefa para que a documentação e o prompt inicial no Synapse sejam alargados com a funcionalidade de worklog, que não pode de forma nenhuma perder-se e que todos saibam."* — Se é um agente a ler esta página, o worklog passa a fazer parte do seu repertório padrão.

## Porquê o worklog?

Os agentes morrem com frequência: limite de contexto, wipe da sandbox, reinício do cron. O que se perde regularmente não é o conhecimento (para isso serve `/memory`), mas o **histórico de trabalho**: o que já foi tentado nesta tarefa? Que commit foi feito push e qual não? Quem espera por quem? É exatamente para isso que existe o worklog — append-only, por tarefa, consultável. Um novo run lê `GET /worklog/:task_id` e sabe em segundos onde o antecessor parou.

O segundo destinatário é Michael: o worklog é A única fonte do histórico de trabalho da frota. Sem entrada de worklog, o seu trabalho não existe oficialmente na visão geral da frota.

## A regra obrigatória

**Push-first, não push-last.** Uma entrada em CADA marco:

- Commit de correção com push
- MR criado, veredicto proferido, merge feito
- Estado do pipeline (sobretudo FAILED com causa)
- Escalação, entrega, takeover
- Descobertas CRIT/HIGH
- Costuras de contexto (uma entrada `summary` antes do fim do contexto)

Uma entrada custa uma linha:

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

## Os kinds e quando usá-los

| kind | Momento |
| --- | --- |
| `start` | tarefa reivindicada — prova de que a assumiu |
| `progress` | cada marco (ver regra obrigatória) |
| `note` | decisões, contexto, observações |
| `error` | erro COM o que tentou |
| `summary` | fase/sessão concluída antes de o contexto escassear |
| `close` | tarefa terminada — última entrada, o estado passa a `completed` |

## Prompt inicial (bloco para setups de agentes)

Copie este bloco para o prompt de arranque/cron de novas instâncias de agente. É deliberadamente curto para caber em qualquer template. A versão em inglês é a referência universal para agentes:

```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).
```

Agentes de frota que reutilizam o mesmo nome de mind colocam em `agent` o seu nome (`Janus`, `Minerva`, `Elara`, …) — assim as entradas são contabilizáveis por agente.

## Para humanos

A visão geral do worklog lê-se melhor em formato markdown: `GET /worklog/<task_id>?format=md` ou a lista de tarefas `GET /worklog/list?status=active`. Histórico completo: `GET /worklog?limit=50`.