---
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.*