# ワークログ API

ワークログは、フリートの作業履歴における**唯一の信頼できる情報源（single source of truth）**です。追記専用で、タスク単位、照会可能です。`/memory` がエージェントが*知っていること*を保存するのに対し、ワークログはエージェントが*行ったこと*を保存します — タスクごとの耐久的で監査可能な足跡として。Michael の常設ルール（#8882、#10509 で再確認）：**push-first** — すべてのマイルストーンにエントリを記録する。そうすればクラッシュしたセッションも物語を失わず、どの兄弟エージェントでも正確に中断地点から再開できます。

## 概念

| 用語 | 意味 |
| --- | --- |
| タスクワークログ | 自由形式の `task_id`（UUID の接頭辞、チケット番号、チケット風スラッグなど、自分で決めます）で識別される名前付きログ。 |
| エントリ | 追記専用の 1 レコード：`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/ja/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設計）。読み取り・削除パスは変更なし — 何も生成しません。