# Worklog-API

Worklogen är **den enda sanna källan för flottans arbetshistorik**. Den är append-only, per uppgift och sökbar. Medan `/memory` lagrar vad en agent *vet*, lagrar worklogen vad en agent *gjort* — som ett hållbart, granskbart spår per uppgift. Michaels stående regel (#8882, bekräftad i #10509): **push-first** — varje milstolpe får en post, så att en kraschad session aldrig förlorar sin historia och vilket syskon som helst kan fortsätta exakt där du slutade.

## Begrepp

| Term | Betydelse |
| --- | --- |
| Uppgiftsworklog | En namngiven logg identifierad av ett fritt `task_id` (ditt val: UUID-prefix, ärende-ID eller ärendelik slug). |
| Post | En append-only-post: `kind`, `agent`, `content`, valfri `title`, tidsstämpel. |
| Status | `active` (öppen) → `completed` (stängd) eller `abandoned`. Sätts via `/close`. |

## Endpoints

Alla endpoints är autentiserade (Mind Key eller användar-JWT) och avgränsade till anroparens mind — du ser aldrig andra minders workloggar.

### Push — mönstret med ett anrop

Den bekvämaste endpointen; lägger till en post och skapar uppgiftsposten om den saknas:

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

### Skapa / öppna en worklog

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

Med ett `content`-fält läggs den första posten till i samma anrop (svar `{{"status":"appended", ...}}`), annars skapas en tom uppgift (svar `{{"status":"created", ...}}`). GET-variant: `/worklog/create?task_id=...&title=...`.

### Lägga till en post

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 skapad, pipeline kör", "agent": "Janus" }
```

Posttyper (okända värden lagras som `note`):

| kind | används för |
| --- | --- |
| `start` | uppgift tagen, arbetet börjar |
| `progress` | milstolpe: commit, MR, utlåtande, testresultat |
| `note` | kontext, beslut, iakttagelser |
| `error` | fel inklusive vad du försökte (ditt framtida jag tackar) |
| `summary` | fas/sessionssammanfattning före kontextöverlämning |
| `close` | slutresultat; använd `/close`-endpointen för statusbytet |

Gränser: `content` ≤ 256 KB per post, `agent` ≤ 128 tecken.

### Läsa

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

`format=json` (standard) returnerar uppgiftsposten + poster som strukturerad data, `md` renderar en läsbar markdown-transkription, `text` ren text.

### Senaste aktivitet över uppgifter

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

Valfritt `task_id`-filter. `since` är en epoch-tidsstämpel i **sekunder**.

### Lista uppgifter

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

### Stänga (och radera)

```
POST /worklog/29140fb0-team-stats/close        # status → slutförd
DELETE /worklog/29140fb0-team-stats            # tar bort hela uppgiftens worklog
```

Båda har GET-varianter (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) för open-tool LLM-klienter. Stängning bevarar loggen — radering är den enda destruktiva operationen.

## Rekommenderad rytm för agenter

1. **`start`** — **`start`**-post när du tar en uppgift (bevis på claim).
2. **`progress`** — **`progress`**-poster vid varje milstolpe — commit-SHA, MR-nummer, utlåtande, pipeline-status. Push-first (Michael #8882): inte bunta till sessionsslutet.
3. **`error`** — **`error`**-poster för varje fel värt att minnas, med fixen.
4. **`summary`** — **`summary`** innan kontexten tar slut — nästa run återupptar från state script + worklogen.
5. **`close`** — **`close`** när uppgiften är klar (bevis i den sista posten).

Flottövergripande uppgiftskonvention (`GET /script/fleet-worklog-tasks-spec`) bygger på detta API; guiden [Worklog för agenter](/docs/sv/guides/worklog-for-agents) innehåller ett kopiera-klistra-promptblock så att ingen agent "glömmer" funktionen (Michael #10509).

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

`task_id`:s i fullt UUID-format maste pa varje skrivvag (`POST /worklog`,
`GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) referera en befintlig
Synapse-uppgift (`agent_tasks`) — annars svarar endpointen
`404 {"error":"task_not_found"}` med en ledtrad. Hallucinerade eller
avkapade UUID skapar inte langre tyst foraldlösa worklog-uppgifter. Fria,
icke-UUID-id:n (`run-145-ci-27`, `morpheus-life`, prefix-slugs som
`29140fb0-team-stats`) kan fortfarande skapas fritt (MEGA-1A-design).
Las- och raderingsvagar ar oforandrade — de skapar aldrig nagot.