the-custodian/state-hub/dashboard/src/docs/workstream-lifecycle.md

title

title
Workstream Lifecycle — Reference

Workstream Lifecycle — Reference

A workstream moves through a defined lifecycle from creation to sign-off. The dashboard "Workstreams by Domain" chart exposes these states as selectable filters so attention can be directed to the right workstreams at the right time.

---

Core lifecycle states

These are the primary stages a workstream passes through in order:

State	Source	Meaning
active	DB status = active	Work is in progress or ready to start
finished	Derived — no open tasks	All tasks are done, but no explicit review has taken place yet
accepted	DB status = completed	Custodian and human have reviewed the workstream, quality checks passed, and it is formally signed off

The normal progression is: active → finished → accepted.

accepted is the only state that requires an explicit action — it is set after a deliberate review, not automatically. This makes it a reliable anchor: anything in finished but not yet in accepted is work that still needs a quality pass.

---

Attention signals

These states are orthogonal to the core lifecycle — a workstream can be active and stalled at the same time. They serve as health indicators rather than lifecycle stages.

Signal	Source	Meaning
blocked	Derived — has ≥ 1 blocked task	At least one task is waiting on something external
stalled	Derived — updated_at > 7 days ago, has both done and open tasks	Work started but activity has stopped; needs a nudge
oldies	Derived — created_at > 7 days ago, zero done tasks	Workstream is old and nothing has been completed yet; may need re-evaluation

---

The acceptance quality gate

When a workstream reaches finished (all tasks done), the custodian's role is to:

1. Review the deliverables against the workstream's stated purpose and scope
2. Check for missing tests, documentation, or follow-up issues
3. Create tasks for any gaps found — this moves the workstream back to active
4. Once satisfied, set status = completed via MCP or API — this marks it as accepted

This pattern ensures that "done" and "accepted" are distinct signals. finished is a fact about task counts; accepted is a statement of quality.

# Accept a workstream via MCP
update_workstream_status(workstream_id="<uuid>", status="completed")

# Or via REST
curl -X PATCH http://127.0.0.1:8000/workstreams/<uuid>/ \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

---

Time-based filters

The chart also supports time-window filters that cut across all lifecycle states:

Filter	Shows workstreams where…
last 1 hour	updated_at or created_at within the last 60 minutes
last 24 hours	… within the last 24 hours
last 7 days	… within the last 7 days
last 30 days	… within the last 30 days
today	… since midnight today
this week	… since Monday of the current week
this month	… since the 1st of the current month

In time-based views, workstream labels are bold for accepted and blocked workstreams to distinguish notable states at a glance.

---

DB status vs. dashboard state

The DB stores a single status field on each workstream. The dashboard maps this alongside derived task-count data to produce the richer set of filter states:

Dashboard state	DB status	Task-count condition
active	active	—
accepted	completed	—
finished	any	todo + in_progress + blocked = 0
blocked	any	blocked ≥ 1
stalled	any	done ≥ 1 and open ≥ 1 and updated_at > 7d ago
oldies	any	done = 0 and open ≥ 1 and created_at > 7d ago

Workstreams are never hard-deleted — use update_workstream_status(..., "completed") or "archived" to close them without losing history.