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

title

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.