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

---
title: Workstream Lifecycle — Reference
---

# Workstream Lifecycle — Reference

A workstream is an information object that occupies a named workstation. The
stored `status` field keeps the current workstation label, while the
task-flow engine derives which other workstations are reachable and which exit
assertions are blocking movement. The dashboard "Workstreams by Domain" chart
exposes stored and derived states as selectable filters so attention can be
directed to the right workstreams at the right time.

---

## Core workstations

These are the primary workstations used by State Hub workstreams:

| Workstation | 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 human-facing path is: **active → finished → accepted**.

`accepted` is the only state that requires an explicit action. It is reached by
advancing the workstream to the `completed` workstation after deliberate
review, not by task counts alone. 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 signals are orthogonal to the core workstation — a workstream can be
`active` and `stalled` at the same time. They serve as health indicators
rather than stored lifecycle stages.

| Signal | Source | Meaning |
|---|---|---|
| **blocked** | Derived — unmet exit assertion or blocked task | Work cannot currently leave its workstation; inspect `blocked_reasons` |
| **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, advance to the `completed` workstation — 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.

```
# Inspect and accept a workstream via MCP
get_flow_state(entity_type="workstream", entity_id="<uuid>")
advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="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.

---

## Stored Label Vs. Dashboard State

The DB stores a single `status` field on each workstream. Treat it as the
current workstation label. The dashboard maps this alongside flow-engine
results, dependency assertions, and task-count data to produce the richer set
of filter states:

| Dashboard state | Stored label / derived source | Condition |
|---|---|---|
| active | `status = active` | — |
| accepted | `status = completed` | — |
| finished | task counts | `todo + in_progress + blocked = 0` |
| blocked | flow result / task counts | `exit_blocked = true` or `blocked ≥ 1` |
| stalled | task counts + timestamp | `done ≥ 1` and `open ≥ 1` and `updated_at > 7d ago` |
| oldies | task counts + timestamp | `done = 0` and `open ≥ 1` and `created_at > 7d ago` |

*Workstreams are never hard-deleted — use `advance_workstation(...,
"completed")` or advance/patch to `"archived"` to close them without losing
history.*