# API de Worklog

O Worklog é a **fonte única de verdade para o histórico de trabalho da frota**. É append-only, por tarefa e consultável. Enquanto `/memory` guarda o que um agente *sabe*, o worklog guarda o que um agente *fez* — como um rasto duradouro e auditável por tarefa. Regra permanente de Michael (#8882, reafirmada em #10509): **push-first** — cada marco recebe uma entrada, assim uma sessão caída nunca perde a sua história e qualquer irmão pode continuar exatamente onde parou.

## Conceitos

| Termo | Significado |
| --- | --- |
| Worklog de tarefa | Um registo nomeado identificado por um `task_id` livre (à sua escolha: prefixo UUID, ticket ou slug tipo ticket). |
| Entrada | Um registo append-only: `kind`, `agent`, `content`, `title` opcional, carimbo de tempo. |
| Estado | `active` (aberto) → `completed` (fechado) ou `abandoned`. Definido via `/close`. |

## Endpoints

Todos os endpoints são autenticados (Mind Key ou JWT de utilizador) e delimitados à mind do chamador — nunca verá os worklogs de outras minds.

### Push — o padrão de chamada única

O endpoint mais conveniente; acrescenta uma entrada e cria o registo de tarefa se faltar:

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

### Criar / abrir um worklog

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Ferramenta de estatísticas de equipa", "agent": "Janus" }
```

Com um campo `content`, a primeira entrada é acrescentada na mesma chamada (resposta `{{"status":"appended", ...}}`); caso contrário, é criada uma tarefa vazia (resposta `{{"status":"created", ...}}`). Variante GET: `/worklog/create?task_id=...&title=...`.

### Acrescentar uma entrada

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 criado, pipeline a correr", "agent": "Janus" }
```

Tipos de entrada (valores desconhecidos são guardados como `note`):

| kind | usar para |
| --- | --- |
| `start` | tarefa reivindicada, o trabalho começa |
| `progress` | marco: commit, MR, veredicto, resultado de teste |
| `note` | contexto, decisões, observações |
| `error` | falhas incluindo o que tentou (o seu eu futuro agradece) |
| `summary` | resumo de fase/sessão antes da entrega de contexto |
| `close` | resultado final; prefira o endpoint `/close` para mudar o estado |

Limites: `content` ≤ 256 KB por entrada, `agent` ≤ 128 caracteres.

### Ler

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

`format=json` (predefinição) devolve o registo de tarefa + entradas como dados estruturados, `md` apresenta uma transcrição markdown legível, `text` texto simples.

### Atividade recente entre tarefas

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

Filtro opcional `task_id`. `since` é um carimbo de tempo epoch em **segundos**.

### Listar tarefas

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

### Fechar (e apagar)

```
POST /worklog/29140fb0-team-stats/close        # estado → concluído
DELETE /worklog/29140fb0-team-stats            # remove todo o worklog da tarefa
```

Ambos têm variantes GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) para clientes LLM open-tool. Fechar mantém o log — apagar é a única operação destrutiva.

## Ritmo recomendado para agentes

1. **`start`** — entrada **`start`** ao reivindicar uma tarefa (prova do claim).
2. **`progress`** — entradas **`progress`** em cada marco — SHA do commit, número do MR, veredicto, estado do pipeline. Push-first (Michael #8882): não acumule até ao fim da sessão.
3. **`error`** — entradas **`error`** para cada falha que valha a pena lembrar, com a correção.
4. **`summary`** — **`summary`** antes de ficar sem contexto — o run seguinte retoma do state script + worklog.
5. **`close`** — **`close`** quando a tarefa está feita (provas na última entrada).

A convenção de tarefas de toda a frota (`GET /script/fleet-worklog-tasks-spec`) constrói-se sobre esta API; o guia [Worklog para Agentes](/docs/pt/guides/worklog-for-agents) contém um bloco de prompt copiar-colar para que nenhum agente "esqueça" a funcionalidade (Michael #10509).

## Regras de task_id (v1.39.46)

`task_id`s em formato UUID completo devem referenciar uma tarefa Synapse
existente (`agent_tasks`) em cada caminho de escrita (`POST /worklog`,
`GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) — caso contrario o endpoint
responde `404 {"error":"task_not_found"}` com uma dica. UUIDs alucinadas ou
truncadas nao criam mais worklogs orfaos em silencio. Ids livres sem formato
UUID (`run-145-ci-27`, `morpheus-life`, slugs com prefixo como
`29140fb0-team-stats`) continuam livremente criaveis (design MEGA-1A). Os
caminhos de leitura e exclusao permanecem inalterados — nunca criam nada.