# Worklog-API

De worklog is de **enige bron van waarheid voor de werkgeschiedenis van de vloot**. Hij is append-only, per taak en doorzoekbaar. Waar `/memory` opslaat wat een agent *weet*, slaat de worklog op wat een agent *heeft gedaan* — als duurzaam, controleerbaar spoor per taak. Michaels permanente regel (#8882, bevestigd in #10509): **push-first** — elke mijlpaal krijgt een entry, zodat een gecrashte sessie nooit haar verliest verliest en elk broertje/zusje precies verder kan waar jij stopte.

## Concepten

| Term | Betekenis |
| --- | --- |
| Taakworklog | Een benoemd log geïdentificeerd door een vrij `task_id`-veld (jouw keuze: UUID-prefix, ticket of ticket-achtige slug). |
| Entry | Eén append-only record: `kind`, `agent`, `content`, optionele `title`, timestamp. |
| Status | `active` (open) → `completed` (gesloten) of `abandoned`. Ingesteld via `/close`. |

## Endpoints

Alle endpoints zijn geauthenticeerd (Mind Key of gebruikers-JWT) en begrensd tot de mind van de aanroeper — je ziet nooit de worklogs van andere minds.

### Push — het één-aanroep-patroon

Handigste endpoint; voegt een entry toe en maakt het taakrecord aan als het ontbreekt:

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

### Worklog aanmaken / openen

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Teamstatistiek-tool", "agent": "Janus" }
```

Met een `content`-veld wordt de eerste entry in dezelfde aanroep toegevoegd (antwoord `{{"status":"appended", ...}}`), anders wordt een lege taak aangemaakt (antwoord `{{"status":"created", ...}}`). GET-variant: `/worklog/create?task_id=...&title=...`.

### Een entry toevoegen

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

Entry-soorten (onbekende waarden worden als `note` opgeslagen):

| kind | gebruik voor |
| --- | --- |
| `start` | taak geclaimd, werk begint |
| `progress` | mijlpaal: commit, MR, verdict, testresultaat |
| `note` | context, beslissingen, observaties |
| `error` | fouten inclusief wat je probeerde (je toekomstige ik zegt dank) |
| `summary` | fase/sessie-samenvatting vóór contextoverdracht |
| `close` | eindresultaat; gebruik de `/close`-endpoint voor de statusflip |

Limieten: `content` ≤ 256 KB per entry, `agent` ≤ 128 tekens.

### Lezen

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

`format=json` (standaard) geeft het taakrecord + entries als gestructureerde data, `md` rendert een leesbare markdown-transcriptie, `text` platte tekst.

### Recente activiteit over taken heen

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

Optioneel `task_id`-filter. `since` is een epoch-timestamp in **seconden**.

### Takenlijst

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

### Sluiten (en verwijderen)

```
POST /worklog/29140fb0-team-stats/close        # status → voltooid
DELETE /worklog/29140fb0-team-stats            # verwijdert de volledige taakworklog
```

Beide hebben GET-varianten (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) voor open-tool LLM-clients. Sluiten bewaart het log — verwijderen is de enige destructieve operatie.

## Aanbevolen ritme voor agenten

1. **`start`** — **`start`**-entry bij het claimen van een taak (claim-bewijs).
2. **`progress`** — **`progress`**-entries bij elke mijlpaal — commit-SHA, MR-nummer, verdict, pipeline-status. Push-first (Michael #8882): niet stappelen tot sessie-einde.
3. **`error`** — **`error`**-entries voor elke fout die het onthouden waard is, met de fix.
4. **`summary`** — **`summary`** voordat je context opraakt — de volgende run pakt verder van state script + worklog.
5. **`close`** — **`close`** als de taak af is (bewijs in de laatste entry).

De vlootbrede taakconventie (`GET /script/fleet-worklog-tasks-spec`) bouwt op deze API; de gids [Worklog voor Agenten](/docs/nl/guides/worklog-for-agents) bevat een copy-paste promptblok zodat geen enkele agent de functie "vergeet" (Michael #10509).

## Task-ID-regels (v1.39.46)

`task_id`s in volledig UUID-formaat moeten op elk schrijfpad
(`POST /worklog`, `GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) naar een bestaande
Synapse-taak (`agent_tasks`) verwijzen — anders antwoordt de endpoint met
`404 {"error":"task_not_found"}` incl. hint. Hallucinated of afgekapte
UUID's creeren zo geen stille orphan-worklogs meer. Vrije, niet-UUID-ids
(`run-145-ci-27`, `morpheus-life`, prefix-slugs zoals `29140fb0-team-stats`)
blijven vrij aanmaakbaar (MEGA-1A-design). Lees- en verwijderpaden zijn
ongewijzigd — ze maken nooit iets aan.