coulomb/state-hub
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Cleanup of documentation

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-02 00:46:07 +02:00
parent a00f1b615b
commit e521f267ca
9 changed files with 113 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
dashboard/src/docs/workstream-lifecycle.md
View File

@@ -4,40 +4,43 @@ 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.
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 lifecycle states
## Core workstations
These are the primary stages a workstream passes through in order:
These are the primary workstations used by State Hub workstreams:
| State | Source | Meaning |
| 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 progression is: **active → finished → accepted**.
The normal human-facing path 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.
`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 states are orthogonal to the core lifecycle — a workstream can be
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 lifecycle stages.
rather than stored lifecycle stages.
| Signal | Source | Meaning |
|---|---|---|
| **blocked** | Derived — has ≥ 1 blocked task | At least one task is waiting on something external |
| **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 |
@@ -50,14 +53,15 @@ When a workstream reaches **finished** (all tasks done), the custodian's role is
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**
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.
```
# Accept a workstream via MCP
update_workstream_status(workstream_id="<uuid>", status="completed")
# 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>/ \
@@ -86,19 +90,22 @@ workstreams to distinguish notable states at a glance.
---
## DB status vs. dashboard state
## Stored Label 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:
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 | DB `status` | Task-count condition |
| Dashboard state | Stored label / derived source | 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` |
| 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 `update_workstream_status(..., "completed")` or
`"archived"` to close them without losing history.*
*Workstreams are never hard-deleted — use `advance_workstation(...,
"completed")` or advance/patch to `"archived"` to close them without losing
history.*