@geekbeer/minion 3.59.8 → 3.59.10

package/docs/api-reference.md

@@ -1046,14 +1046,54 @@ Claudeへの注入例:
 - Linuxミニオン: `tmux ls | grep '^bt-'` でセッション一覧。WSターミナルからアタッチ可能。
 - Windowsミニオン: `wsl tmux ls | grep '^bt-'` で確認 (or HQ ダッシュボードのターミナル一覧で `wsl-tmux` タイプとして表示)。
 
-ミニオンが自分で参照する用途のためのスプリント API:
+ミニオン用スプリント API (v3.59.9〜):
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/projects/:projectId/sprints` | スプリント一覧 (HQ認証 — ユーザーUI用) |
+| GET | `/api/minion/projects/:projectId/sprints` | 一覧 (`?status=planned\|active\|completed` で絞り込み可) |
+| POST | `/api/minion/projects/:projectId/sprints` | 作成 (作成者は `created_by_minion_id` に記録される) |
+| GET | `/api/minion/projects/:projectId/sprints/:sprintId` | 詳細 |
+| PATCH | `/api/minion/projects/:projectId/sprints/:sprintId` | 更新 (status遷移含む) |
+| DELETE | `/api/minion/projects/:projectId/sprints/:sprintId` | 削除 (`planned` のみ可) |
 
-ミニオンからスプリントを直接作成・遷移させる必要は通常ない (PMロールのユーザーが管理する)。
-状況確認用には標準のタスクAPIで `?sprint_id=<uuid>` を使えば所属タスクが取得できる。
+POST body:
+```json
+{
+  "name": "Sprint 1",       // required
+  "goal": "結合テスト完了"   // optional
+}
+```
+作成時の `status` は常に `planned`。HQダッシュボードで一覧/編集できる。
+
+PATCH body (status 遷移):
+```json
+// planned -> active
+{ "status": "active" }
+// → タスクが1件もないと 422 {"error": "sprint_has_no_tasks"}
+// → DoR 違反 (全タスクに assignee_minion_id + 1件以上の acceptance_criteria が必要) なら
+//    422 {"error": "definition_of_ready_unmet", "violations": [{task_id, title, missing[]}]}
+// → 別の active スプリントが既にあると 409 (active_sprint がエラーに同梱される)
+// 成功時は started_at が自動セットされる
+
+// active -> completed
+{ "status": "completed", "unfinished_tasks_action": "return_to_backlog" }
+// or
+{ "status": "completed", "unfinished_tasks_action": "carry_over" }
+// → carry_over の場合、未完タスクは最新の planned スプリントに移動 (無い場合 422)
+// → return_to_backlog (デフォルト) の場合、未完タスクは sprint_id=null & status='backlog' に戻る
+// 成功時は completed_at が自動セットされる
+```
+
+その他の更新項目 (status と独立に同一PATCHで可):
+- `name` (空文字不可)
+- `goal` (null可)
+
+**重要なルール:**
+- `planned -> active` または `active -> completed` 以外の status 遷移は 400。
+- DELETE は `planned` 状態のみ許可 (`active`/`completed` は不可)。
+- 削除しても紐づくタスクは残る (`sprint_id` だけ NULL になる)。
+
+状況確認用には標準のタスクAPIで `?sprint_id=<uuid>` を使えば所属タスクを取得できる。
 
 ### Project Milestones
 

package/docs/task-guides.md

@@ -702,6 +702,44 @@ curl -X PATCH "$HQ_URL/api/minion/projects/<project-id>/milestones/<m-id>" \
   -d '{"status":"in_progress"}'
 ```
 
+#### 4. スプリント管理 (v3.59.9〜)
+
+スプリントはアジャイル運用の単位で、`planned -> active -> completed` の3状態を持つ。
+1プロジェクトにつき `active` は1つだけ。スプリントを `active` にするとボードタスクの
+自動着手 (`board-task-poller`) が起動する。
+
+```bash
+# 1. プランドスプリントを作成
+curl -X POST "$HQ_URL/api/minion/projects/<project-id>/sprints" \
+  -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"name":"Sprint 1","goal":"MVP のログイン/サインアップ実装完了"}'
+# レスポンスの id を <sprint-id> として控える
+
+# 2. スプリントにタスクをアサイン (タスク作成時 or 更新時)
+curl -X PATCH "$HQ_URL/api/minion/projects/<project-id>/tasks/<task-id>" \
+  -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"sprint_id":"<sprint-id>","acceptance_criteria":[{"id":"...","text":"...","checked":false}]}'
+
+# 3. スプリント開始 (DoR チェックが入る — 全タスクに assignee_minion_id + acceptance_criteria 必須)
+curl -X PATCH "$HQ_URL/api/minion/projects/<project-id>/sprints/<sprint-id>" \
+  -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"status":"active"}'
+# 422 {"error":"sprint_has_no_tasks"} → タスクを1件以上追加してから再試行
+# 422 {"error":"definition_of_ready_unmet","violations":[...]} → violations[] の missing を埋めてから再試行
+
+# 4. スプリント完了 (未完タスクをバックログに戻すか、次の planned スプリントに持ち越す)
+curl -X PATCH "$HQ_URL/api/minion/projects/<project-id>/sprints/<sprint-id>" \
+  -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"status":"completed","unfinished_tasks_action":"return_to_backlog"}'
+# unfinished_tasks_action: "carry_over" にすると最新の planned スプリントへ移動 (無ければ 422)
+```
+
+**スプリント運用のガイドライン:**
+- スプリントを `active` 化する前に、所属タスクが全て **assignee_minion_id を持ち、かつ acceptance_criteria が1件以上** あることを確認する (DoR)。違反タスクは PATCH レスポンスの `violations[]` に列挙される。
+- 既に別のスプリントが `active` だと 409 が返る (`active_sprint` フィールドに既存スプリントが入る)。先にそれを `completed` にする必要がある。
+- DELETE は `planned` 状態のみ可。`active` や `completed` のスプリントは削除できない。
+- スプリント完了時、未完タスクのデフォルト挙動は `return_to_backlog` (status=`backlog`、sprint_id=null)。
+
 ### Engineer ロールの典型操作
 
 #### 1. 自分にアサインされたタスクを取得

package/linux/routes/chat.js

@@ -458,8 +458,11 @@ async function buildContextPrefix(message, context, sessionId, workspaceId, refe
             `  POST   \$HQ_URL/api/minion/projects/${context.projectId}/tasks       # 作成 (body: title, description?, status?, priority?, milestone_id?, sprint_id?, parent_task_id?, assignee_minion_id?, due_date?, acceptance_criteria?)`,
             `  PATCH  \$HQ_URL/api/minion/projects/${context.projectId}/tasks/<id>  # 更新 (status変更で status_changed_at がサーバ自動更新、acceptance_criteria/sprint_id も更新可。AC更新時は既存idを保持)`,
             `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/milestones  # マイルストーン一覧`,
+            `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/sprints     # スプリント一覧 (?status=planned|active|completed で絞り込み可)`,
+            `  POST   \$HQ_URL/api/minion/projects/${context.projectId}/sprints     # 作成 (body: name, goal?) — 初期 status は planned`,
+            `  PATCH  \$HQ_URL/api/minion/projects/${context.projectId}/sprints/<id># 更新 (status遷移: planned→active で DoR 検証、active→completed で unfinished_tasks_action=carry_over|return_to_backlog 指定可)`,
             `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/health      # 健康度サマリ (overdue/stalled/マイルストーン進捗。progress_pct は leaf タスク基準)`,
-            `タスクは5段階Kanban (backlog→todo→doing→review→done)、親子は2階層まで(孫不可)。priority は low|normal|high|urgent (可視化+フィルタ用)。親EPICに milestone_id を付ければ子タスクも進捗に自動反映される。詳細は ~/.minion/docs/api-reference.md の「Project Tasks」「Project Milestones」「Project Health」を参照。`,
+            `タスクは5段階Kanban (backlog→todo→doing→review→done)、親子は2階層まで(孫不可)。priority は low|normal|high|urgent (可視化+フィルタ用)。親EPICに milestone_id を付ければ子タスクも進捗に自動反映される。スプリントは1プロジェクトにつき active=1つだけ、DoR (全タスクに assignee_minion_id + acceptance_criteria) を満たすと active 化可能。詳細は ~/.minion/docs/api-reference.md の「Project Tasks」「Project Milestones」「Project Sprints」「Project Health」を参照。`,
             `取得した内容をもとに回答してください。`
           )
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.59.8",
+  "version": "3.59.10",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/rules/core.md

@@ -33,15 +33,16 @@ Minion
     - **script ノード (v3.54.0〜)** は LLM を使わない決定的処理用。`script_runtime` (`'python'` or `'node'`) と `script_source` を指定。input_data を stdin で JSON 受け取り → output_data を stdout に JSON 出力する規約。outgoing edge に contract を貼れば transform と同じ runtime validation が走る。LLMトークンを節約したい・出力ブレを許容できない定型処理に使う。詳細は `~/.minion/docs/task-guides.md` の「Script ノード」を参照
     - **fan_out の incoming edge に contract を貼る場合**、`fan_out_source` が指すフィールドが contract 内に `type='array'` として宣言されている必要がある（静的検証で弾かれる）
 - **Routine**: ミニオンスコープ。ミニオンローカルの定期タスク。
-- **Project Tasks / Milestones**: プロジェクトスコープ。**人間+ミニオンが共有するタスクボード**(5段階Kanban: `backlog`→`todo`→`doing`→`review`→`done`)とロードマップ(マイルストーン)。ミニオンは `/api/minion/projects/:projectId/{tasks,milestones,health}` で操作可能。
-  - PMロールは朝のチェックで `/health` を叩いて遅延・停滞タスクを把握、ユーザー要望をエピック+子タスクに分解
+- **Project Tasks / Milestones / Sprints**: プロジェクトスコープ。**人間+ミニオンが共有するタスクボード**(5段階Kanban: `backlog`→`todo`→`doing`→`review`→`done`)、ロードマップ(マイルストーン)、アジャイル運用単位(スプリント)。ミニオンは `/api/minion/projects/:projectId/{tasks,milestones,sprints,health}` で操作可能。
+  - PMロールは朝のチェックで `/health` を叩いて遅延・停滞タスクを把握、ユーザー要望をエピック+子タスクに分解、スプリントに割り当てて active 化
   - Engineerロールは `?assignee_minion_id=$MINION_ID` で自分のタスクを取得し、着手時に `status: doing` へ更新(以降 `status_changed_at` がサーバ側で自動更新され、停滞検出に使われる)
   - 親子は2階層のみ(孫タスク禁止)、担当は **ミニオン or 人間** の二択
   - **priority**: `low` / `normal` / `high` / `urgent` (default `normal`)。可視化とフィルタ用途(並び順は `sort_order` が優先)
   - **`milestone_id` は親 EPIC に付ければ配下の子タスクも自動的にその進捗に含まれる**(effective milestone)。子を個別にひもづけ直す必要はない。`/health` は leaf タスク基準で `progress_pct` を算出する
   - **タスク検索**: `?q=<keyword>` でタイトル+説明の部分一致検索(pg_trgm、日本語OK)、`?priority=high,urgent` でカンマ区切り複数指定
+  - **スプリント**: `planned -> active -> completed` の3状態。1プロジェクトにつき `active` は1つだけ。`planned -> active` 遷移時に DoR (全タスクに `assignee_minion_id` + 1件以上の `acceptance_criteria`) を検証し、満たさないと 422 で `violations[]` が返る。`active -> completed` 時は `unfinished_tasks_action` で未完タスクの扱いを選択 (`return_to_backlog` (default) / `carry_over`)
   - **`[task:UUID]` チケットタグ**: HQチャットでユーザーがチケットを指す際に使う形式。受信メッセージに含まれる場合、HQが解決した詳細がプロンプト先頭の「参照チケット」ブロックに同梱される。応答内でチケットへ言及する際にも同タグを使ってよい(HQ側でチップに描画される)
-  - 詳細は `~/.minion/docs/api-reference.md` の「Project Tasks」「Project Milestones」「Project Health」と `~/.minion/docs/task-guides.md` の「プロジェクトタスク管理」を参照
+  - 詳細は `~/.minion/docs/api-reference.md` の「Project Tasks」「Project Milestones」「Project Sprints」「Project Health」と `~/.minion/docs/task-guides.md` の「プロジェクトタスク管理」を参照
 - **Workspace**: ミニオンは複数のワークスペースに所属でき、スキルやプロジェクトはワークスペース単位でスコープされる。チャットセッションもワークスペース別に分離される。所属ワークスペースはハートビートで自動同期され、`hq list workspaces` で確認できる。
 - ミニオンは複数プロジェクトに `pm`、`engineer`、`accountant` として参加できる。
 

package/win/routes/chat.js

@@ -519,8 +519,11 @@ async function buildContextPrefix(message, context, sessionId, workspaceId, refe
             `  POST   \$HQ_URL/api/minion/projects/${context.projectId}/tasks       # 作成 (body: title, description?, status?, priority?, milestone_id?, sprint_id?, parent_task_id?, assignee_minion_id?, due_date?, acceptance_criteria?)`,
             `  PATCH  \$HQ_URL/api/minion/projects/${context.projectId}/tasks/<id>  # 更新 (status変更で status_changed_at がサーバ自動更新、acceptance_criteria/sprint_id も更新可。AC更新時は既存idを保持)`,
             `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/milestones  # マイルストーン一覧`,
+            `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/sprints     # スプリント一覧 (?status=planned|active|completed で絞り込み可)`,
+            `  POST   \$HQ_URL/api/minion/projects/${context.projectId}/sprints     # 作成 (body: name, goal?) — 初期 status は planned`,
+            `  PATCH  \$HQ_URL/api/minion/projects/${context.projectId}/sprints/<id># 更新 (status遷移: planned→active で DoR 検証、active→completed で unfinished_tasks_action=carry_over|return_to_backlog 指定可)`,
             `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/health      # 健康度サマリ (overdue/stalled/マイルストーン進捗。progress_pct は leaf タスク基準)`,
-            `タスクは5段階Kanban (backlog→todo→doing→review→done)、親子は2階層まで(孫不可)。priority は low|normal|high|urgent (可視化+フィルタ用)。親EPICに milestone_id を付ければ子タスクも進捗に自動反映される。詳細は ~/.minion/docs/api-reference.md の「Project Tasks」「Project Milestones」「Project Health」を参照。`,
+            `タスクは5段階Kanban (backlog→todo→doing→review→done)、親子は2階層まで(孫不可)。priority は low|normal|high|urgent (可視化+フィルタ用)。親EPICに milestone_id を付ければ子タスクも進捗に自動反映される。スプリントは1プロジェクトにつき active=1つだけ、DoR (全タスクに assignee_minion_id + acceptance_criteria) を満たすと active 化可能。詳細は ~/.minion/docs/api-reference.md の「Project Tasks」「Project Milestones」「Project Sprints」「Project Health」を参照。`,
             `取得した内容をもとに回答してください。`
           )
         }