# Worklog-API

Das Worklog ist die **alleininge Quelle für die Fleet-Arbeits-Historie**:
append-only, pro Task, abfragbar. Während `/memory` speichert, was ein Agent
*weiß*, speichert das Worklog, was er *getan* hat. Michaels Dauerregel
(#8882, bekräftigt #10509): **Push-first** — jeder Meilenstein bekommt einen
Eintrag, damit ein gestorbener Run seine Geschichte nicht verliert und jeder
Geschwister exakt dort weitermacht, wo du aufgehört hast.

## Begriffe

| Begriff | Bedeutung |
| --- | --- |
| Task-Worklog | Ein benanntes Log, identifiziert über eine freie `task_id` (z. B. UUID-Präfix, Ticket-Slug). |
| Eintrag | Append-only Datensatz: `kind`, `agent`, `content`, optional `title`, Zeitstempel. |
| Status | `active` (offen) → `completed` (geschlossen) oder `abandoned`. |

## Endpunkte

Alle Endpunkte sind authentifiziert (Mind Key oder User-JWT) und auf den
aufrufenden Mind gescoped — fremde Worklogs sind nicht lesbar.

### Push — das Einzeiler-Muster

Der bequemste Endpunkt; hängt einen Eintrag an und legt die Task-Worklog bei
Bedarf an:

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

### Worklog anlegen

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Team-Statistik-Tool", "agent": "Janus" }
```

Mit `content`-Feld wird der erste Eintrag direkt im selben Aufruf angehängt
(Antwort `{"status":"appended", ...}`), sonst entsteht ein leerer Task
(`{"status":"created", ...}`). GET-Variante: `/worklog/create?task_id=...`.

### Eintrag anhängen

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 erstellt, Pipeline läuft", "agent": "Janus" }
```

Arten (unbekannte Werte werden als `note` gespeichert):

| kind | Verwendung |
| --- | --- |
| `start` | Task geclaimt, Arbeit beginnt |
| `progress` | Meilenstein: Commit, MR, Verdict, Testergebnis |
| `note` | Kontext, Entscheidungen, Beobachtungen |
| `error` | Fehler inkl. Fix-Versuch |
| `summary` | Phasen-/Session-Zusammenfassung vor Kontextübergabe |
| `close` | Endergebnis; Status-Wechsel lieber über `/close` |

Limits: `content` ≤ 256 KB je Eintrag, `agent` ≤ 128 Zeichen.

### Lesen

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

`format=json` (Standard) liefert Task + Einträge strukturiert, `md` ein
lesbares Markdown-Protokoll, `text` reinen Text.

### Letzte Aktivität über Tasks hinweg

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

Optionaler `task_id`-Filter. `since` ist ein Epoch-**Sekunden**-Zeitstempel.

### Tasks listen

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

### Schließen und Löschen

```
POST /worklog/29140fb0-team-stats/close        # Status -> completed
DELETE /worklog/29140fb0-team-stats            # Worklog des Tasks entfernen
```

Beide haben GET-Varianten (`/worklog/:task_id/close`, `/worklog/:task_id/delete`)
für Open-Tool-LLM-Clients. Schließen behält das Log — Löschen ist die einzige
destruktive Operation.

## Empfohlener Rhythmus für Agenten

1. **`start`** beim Claim (Übernahme-Beweis).
2. **`progress`** bei jedem Meilenstein — Commit-SHA, MR-Nummer, Verdict,
   Pipeline-Status. Push-first (Michael #8882): nicht bis zum Sessionende stapeln.
3. **`error`** für jeden erinnerungswürdigen Fehler, mit Fix.
4. **`summary`** vor dem Kontext-Ende — der nächste Run setzt aus State-Script
   + Worklog exakt fort.
5. **`close`** bei Abschluss (Beweis im letzten Eintrag).

Die Fleet-Konvention (`GET /script/fleet-worklog-tasks-spec`) baut auf dieser
API auf; der Agenten-Guide [Worklog für Agenten](/docs/de/guides/worklog-for-agents)
enthält den Copy-Paste-Prompt-Baustein, damit kein Agent das Feature mehr
übersehen kann (Michael #10509).

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

Voll-UUID-foermige `task_id`s muessen auf jedem schreibenden Pfad
(`POST /worklog`, `GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) einen existierenden
Synapse-Task (`agent_tasks`) referenzieren — sonst antwortet der Endpunkt
mit `404 {"error":"task_not_found"}` inkl. Hinweis. Damit erzeugen
halluzinierte oder trunkierte UUIDs keine stillen Orphan-Worklogs mehr.
Freie, nicht-UUID-Ids (`run-145-ci-27`, `morpheus-life`, Praefix-Slugs wie
`29140fb0-team-stats`) bleiben frei erstellbar (MEGA-1A-Design). Lese- und
Loeschpfade sind unveraendert — sie erzeugen nie etwas.