From 91874eb4136f4672896952192f33e15fac075d05 Mon Sep 17 00:00:00 2001
From: claudemb <claudemb@thinkoff.local>
Date: Sat, 20 Jun 2026 09:18:36 +0200
Subject: [PATCH] docs: task-lifecycle spec (permanent-team orchestration, no
 create-team API)

Petrus (2026-06-20): task lifecycle + lead/worker + monitor + completion
summaries over the PERMANENT roster; no create-team API. Defines the Task
object, statuses (open/in_progress/blocked/done/cancelled), daemon /tasks API
(ether's lane), CodeWatch monitor + completion-summary surface (claudeMB),
and the link to the control-plane action-system. Shared contract both lanes
build to. Inspired by michelhelsdingen/ensemble, controlled via CodeWatch.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/task-lifecycle.md | 81 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 docs/task-lifecycle.md

diff --git a/docs/task-lifecycle.md b/docs/task-lifecycle.md
new file mode 100644
index 0000000..04763e1
--- /dev/null
+++ b/docs/task-lifecycle.md
@@ -0,0 +1,81 @@
+# Task lifecycle (permanent-team orchestration)
+
+**Direction (Petrus, 2026-06-20):** implement team lifecycle, lead/worker, task
+monitor, and completion summaries — but **no create-team API**. We have a
+permanent roster (petrus, @claudeMB, @claudemm, @ether, @codex/@codexmb), so the
+lifecycle is over **tasks**, not over creating/disbanding teams. Inspired by
+`michelhelsdingen/ensemble`, but controlled through CodeWatch and backed by IAK
+typed actions + receipts (see `docs/codewatch-control-plane.md`).
+
+## Model
+
+A **Task** is one unit of work assigned across the permanent roster.
+
+```jsonc
+{
+  "id": "tsk_<short>",            // daemon-assigned
+  "title": "Garageland Shopify import",
+  "detail": "Import 3,492 products as drafts once the store + token exist",
+  "lead": "@claudeMB",           // one agent (or @petrus) accountable
+  "workers": ["@ether"],          // 0+ contributing agents
+  "status": "open",              // see statuses below
+  "room": "thinkoff-development", // where updates/receipts post
+  "created_by": "@petrus",
+  "created_at": "<iso>",
+  "updated_at": "<iso>",
+  "updates": [                     // append-only progress log
+    { "at": "<iso>", "by": "@claudeMB", "text": "catalog transformed; awaiting store" }
+  ],
+  "actions": ["<action nonce>"],  // typed action-requests spawned by this task (control-plane)
+  "summary": null                 // completion summary, set on done
+}
+```
+
+### Statuses
+
+`open` -> `in_progress` -> (`blocked` <->) -> `done` | `cancelled`
+
+- `open`: created, lead assigned, not started.
+- `in_progress`: lead/workers actively on it.
+- `blocked`: waiting on a human step (payment, token, file-pick, approval) or an
+  external dependency. Record what it's blocked on in `updates`.
+- `done`: finished; `summary` set.
+- `cancelled`: dropped; `summary` records why.
+
+## Daemon API (IAK — ether's lane)
+
+```
+POST   /tasks                 { title, detail, lead, workers, room }      -> { id, ...task }
+GET    /tasks                 [?status=]                                  -> [task]
+GET    /tasks/{id}                                                        -> task
+PATCH  /tasks/{id}            { status?, lead?, workers?, update? }       -> task   (update appends to log)
+POST   /tasks/{id}/complete   { summary }                                 -> task   (status=done)
+```
+
+- The daemon is authoritative for task state + the append-only update log.
+- Status changes and completion **post to `room`** (so the team + petrus see them),
+  and emit a CodeWatch-renderable card (action: open task / view monitor).
+- A task may spawn typed actions via `/actions/request`; those receipts attach to
+  the task's `actions[]` so the monitor shows the full chain.
+
+## CodeWatch surface (mine — @claudeMB)
+
+- **Task monitor**: a list of active tasks (title, lead, workers, status badge,
+  last update, age). Tap a task -> detail (the update log + any action receipts).
+- **Completion summary**: when a task hits `done`, CodeWatch shows the summary card
+  (what was done, by whom, receipts) in the room and in the monitor.
+- Reads `GET /tasks` / `GET /tasks/{id}` (degrades to empty until the daemon ships,
+  same pattern as the agents list).
+
+## Lane split
+
+- **IAK daemon (ether):** the `/tasks` registry + state + append-only log + room
+  posting on transitions + completion summaries.
+- **CodeWatch (claudeMB):** the task-monitor UI + completion-summary cards + a thin
+  task-request helper (mirror of `scripts/action-request.mjs`) to open/update tasks.
+- **Shared:** this schema is the contract; both build to it.
+
+## Explicitly NOT building
+
+- **create-team / disband API** — the roster is permanent; ensemble's ephemeral
+  team spawn/disband doesn't apply. (Revisit only if ad-hoc sub-teams are ever needed.)