# Worklog-API
SUMMARY: Append-only, pro Task geführte Worklogs für Agenten-Teams — dokumentiere jeden Arbeitsschritt, abfragbar nach Task, Agent, Art und Zeit.

KEY CONTEXT:
Auth: Mind Key (oder User-JWT). Alle Endpunkte mind-scoped über den aufrufenden Mind/User.
Push (1 Aufruf): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus
Task-Worklog anlegen: POST /worklog { task_id, title? }  (content? -> erster Eintrag direkt)
Eintrag anhängen: POST /worklog/:task_id { kind, content, agent?, title? }  (GET-Variante: /worklog/:task_id/append)
Lesen: GET /worklog/:task_id?format=json|md|text
Letzte Einträge: GET /worklog?limit=50&since=<epoch sek>&task_id=
Tasks listen: GET /worklog/list?status=active|completed|all&limit=20
Schließen: POST /worklog/:task_id/close  (GET-Variante existiert)
Löschen: DELETE /worklog/:task_id  (GET-Variante existiert)
kinds: start | progress | note | error | summary | close (unbekannt -> note)
Limits: content max 256 KB je Eintrag; agent max 128 Zeichen; task_id [a-zA-Z0-9._/-] max 256.
Fleet-Regel (Michael #8882/#10509): POST /worklog bei JEDEM Meilenstein — nicht erst am Sessionende.
UUID-Task-IDs: Append/Create/Close antwortet 404 (task_not_found), wenn zur UUID kein Synapse-Task (agent_tasks) existiert. Freie Slugs bleiben frei erstellbar. (v1.39.46)

Worklog-API
Das Worklog ist die alleininge Quelle für die Fleet-Arbeits-Historie:
append-only, pro Task, abfragbar. Während  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  (z. B. UUID-Präfix, Ticket-Slug). |
| Eintrag | Append-only Datensatz: , , , optional , Zeitstempel. |
| Status |  (offen) →  (geschlossen) oder . |
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:
[CODE BLOCK]
Worklog anlegen
[CODE BLOCK]
Mit -Feld wird der erste Eintrag direkt im selben Aufruf angehängt
(Antwort ), sonst entsteht ein leerer Task
(). GET-Variante: .
Eintrag anhängen
[CODE BLOCK]
Arten (unbekannte Werte werden als  gespeichert):
| kind | Verwendung |
| --- | --- |
|  | Task geclaimt, Arbeit beginnt |
|  | Meilenstein: Commit, MR, Verdict, Testergebnis |
|  | Kontext, Entscheidungen, Beobachtungen |
|  | Fehler inkl. Fix-Versuch |
|  | Phasen-/Session-Zusammenfassung vor Kontextübergabe |
|  | Endergebnis; Status-Wechsel lieber über  |
Limits:  ≤ 256 KB je Eintrag,  ≤ 128 Zeichen.
Lesen
[CODE BLOCK]
 (Standard) liefert Task + Einträge strukturiert,  ein
lesbares Markdown-Protokoll,  reinen Text.
Letzte Aktivität über Tasks hinweg
[CODE BLOCK]
Optionaler -Filter.  ist ein Epoch-Sekunden-Zeitstempel.
Tasks listen
[CODE BLOCK]
Schließen und Löschen
[CODE BLOCK]
Beide haben GET-Varianten (, )
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.  beim Claim (Übernahme-Beweis).
2.  bei jedem Meilenstein — Commit-SHA, MR-Nummer, Verdict,
   Pipeline-Status. Push-first (Michael #8882): nicht bis zum Sessionende stapeln.
3.  für jeden erinnerungswürdigen Fehler, mit Fix.
4.  vor dem Kontext-Ende — der nächste Run setzt aus State-Script
   + Worklog exakt fort.
5.  bei Abschluss (Beweis im letzten Eintrag).
Die Fleet-Konvention () baut auf dieser
API auf; der Agenten-Guide Worklog für Agenten
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 s muessen auf jedem schreibenden Pfad
(, , ,
) einen existierenden
Synapse-Task () referenzieren — sonst antwortet der Endpunkt
mit  inkl. Hinweis. Damit erzeugen
halluzinierte oder trunkierte UUIDs keine stillen Orphan-Worklogs mehr.
Freie, nicht-UUID-Ids (, , Praefix-Slugs wie
) bleiben frei erstellbar (MEGA-1A-Design). Lese- und
Loeschpfade sind unveraendert — sie erzeugen nie etwas.