# 워크로그 API

워크로그는 플릿 작업 이력의 **단일 진실 공급원**입니다. append-only이며 태스크별로 조회할 수 있습니다. `/memory`가 에이전트가 *아는 것*을 저장한다면, 워크로그는 에이전트가 *한 것*을 저장합니다 — 태스크별 내구성 있고 감사 가능한 흔적으로. Michael의 상설 규칙(#8882, #10509에서 재확인): **push-first** — 모든 마일스톤에 엔트리를 남깁니다. 그러면 죽은 세션도 자기 이야기를 잃지 않고, 어떤 형제 에이전트든 정확히 멈춘 지점에서 이어갈 수 있습니다.

## 개념

| 용어 | 의미 |
| --- | --- |
| 태스크 워크로그 | 자유 형식의 `task_id`(UUID 접두사, 티켓, 티켓 스타일 슬러그 등 직접 선택)로 식별되는 이름 있는 로그. |
| 엔트리 | append-only 레코드 하나: `kind`, `agent`, `content`, 선택적 `title`, 타임스탬프. |
| 상태 | `active`(열림) → `completed`(닫힘) 또는 `abandoned`. `/close`로 설정. |

## 엔드포인트

모든 엔드포인트는 인증(Mind Key 또는 사용자 JWT)이 필요하고 호출자의 마인드로 스코프됩니다 — 다른 마인드의 워크로그는 절대 보이지 않습니다.

### 푸시 — 단일 호출 패턴

가장 편리한 엔드포인트; 엔트리를 추가하고 없으면 태스크 레코드를 만듭니다:

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

### 워크로그 생성 / 열기

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "팀 통계 도구", "agent": "Janus" }
```

`content` 필드를 넣으면 같은 호출에서 첫 엔트리가 추가됩니다(응답 `{{"status":"appended", ...}}`). 그렇지 않으면 빈 태스크가 생성됩니다(응답 `{{"status":"created", ...}}`). GET 변형: `/worklog/create?task_id=...&title=...`.

### 엔트리 추가

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 생성, 파이프라인 실행 중", "agent": "Janus" }
```

엔트리 종류(알 수 없는 값은 `note`로 저장됨):

| kind | 사용처 |
| --- | --- |
| `start` | 태스크 청구, 작업 시작 |
| `progress` | 마일스톤: 커밋, MR, 판정, 테스트 결과 |
| `note` | 맥락, 결정, 관찰 |
| `error` | 시도한 내용을 포함한 실패(미래의 당신이 감사해할 것) |
| `summary` | 컨텍스트 인계 전 페이즈/세션 요약 |
| `close` | 최종 결과; 상태 변경은 `/close` 엔드포인트 권장 |

제한: `content` 엔트리당 최대 256 KB, `agent` 최대 128자.

### 읽기

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

`format=json`(기본값)은 태스크 레코드 + 엔트리를 구조화된 데이터로, `md`는 사람이 읽기 좋은 markdown 기록으로, `text`는 일반 텍스트로 반환합니다.

### 태스크 전체의 최근 활동

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

선택적 `task_id` 필터. `since`은 에포크 **초** 타임스탬프입니다.

### 태스크 목록

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

### 닫기 (및 삭제)

```
POST /worklog/29140fb0-team-stats/close        # 상태 → 완료
DELETE /worklog/29140fb0-team-stats            # 전체 태스크 워크로그 제거
```

둘 다 GET 변형이 있습니다(``/worklog/:task_id/close``, `/worklog/:task_id/delete`) — open-tool LLM 클라이언트용. 닫아도 로그는 유지됩니다 — 삭제만이 유일한 파괴적 작업입니다.

## 에이전트를 위한 권장 리듬

1. **`start`** — 태스크를 청구할 때 **`start`** 엔트리(청구 증거).
2. **`progress`** — 모든 마일스톤마다 **`progress`** 엔트리 — 커밋 SHA, MR 번호, 판정, 파이프라인 상태. push-first(Michael #8882): 세션 끝까지 몰아두지 마세요.
3. **`error`** — 기억할 가치가 있는 모든 실패에 **`error`** 엔트리, 수정 내용과 함께.
4. **`summary`** — 컨텍스트가 다 되기 전에 **`summary`** — 다음 런이 state 스크립트 + 워크로그에서 이어갑니다.
5. **`close`** — 태스크가 끝나면 **`close`**(마지막 엔트리에 증거).

플릿 전체 태스크 컨벤션(`GET /script/fleet-worklog-tasks-spec`)은 이 API 위에 구축되었습니다. 에이전트 가이드 [에이전트를 위한 워크로그](/docs/ko/guides/worklog-for-agents)에 복사-붙여넣기용 프롬프트 블록이 있어 어떤 에이전트도 이 기능을 "잊지" 않습니다(Michael #10509).

## task_id 규칙 (v1.39.46)

완전한 UUID 형식의 `task_id`는 모든 쓰기 경로
(`POST /worklog`, `GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`)에서 기존 Synapse 작업
(`agent_tasks`)을 참조해야 합니다 — 그렇지 않으면 엔드포인트는 힌트와 함께
`404 {"error":"task_not_found"}`로 응답합니다. 이제 환각되거나 잘린 UUID가
조용히 고아 worklog 작업을 만들지 않습니다. UUID 형식이 아닌 자유 id
(`run-145-ci-27`, `morpheus-life`, `29140fb0-team-stats` 같은 접두사 슬러그)
는 계속 자유롭게 만들 수 있습니다(MEGA-1A 설계). 읽기·삭제 경로는 변경
없음 — 절대 아무것도 만들지 않습니다.