tegwick
25b4dd07f5
- Migration b4c5d6e7f8a9: adds needs_human (bool) + intervention_note (text) to tasks - API: needs_human filter on GET /tasks/; 422 if flagged without note - 3 MCP tools: flag_for_human, clear_human_flag, list_human_interventions - Dashboard: interventions.md with amber cards and "Mark done" button - Policy router + workstream DoD policy (workstream-dod.md) - Workstream lifecycle docs page + workplan CUST-WP-0010 - CLAUDE.md: add step 4 (run fix-consistency after workplan writes) - consistency_check.py: promote C-11 unlinked tasks from INFO to WARN Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
---
|
|
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.*
|