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

---
title: Workplan Lifecycle — Reference
---

# Workplan Lifecycle — Reference

A **workplan** is a work-record kind: a structured, dependency-bearing body of
work. In State Hub it is an information object whose current position is the
stored `status` field. The task-flow engine can derive which other positions
are reachable and which exit assertions are blocking movement.

Umbrella vocabulary: [Work Records](/docs/work-records).
File convention: ADR-001 / [Workplans](/docs/workstreams).

The product term is **workplan**. **Workstream** remains a legacy compatibility
name in some fields (notably frontmatter `state_hub_workstream_id`) and
historical URLs; it refers to the same entity.

**Quality vs lifecycle:** `status=ready` or `status=finished` is process state.
Implementation-readiness and completion quality are separate assessments —
[DoR](/policy/work-item-dor) (`DoR-Ok` / `DoR-Failed`) and
[DoD](/policy/workstream-dod) (`DoD-Ok` / `DoD-Failed`). A finished workplan
without DoD-Ok is allowed quality debt. See
`docs/work-record-quality-gates.md`.

---

## Stored lifecycle states

| State | Source | Meaning |
|---|---|---|
| **proposed** | `status = proposed` | Plan exists, but must be reviewed against current repo state |
| **ready** | `status = ready` | Plan has been reviewed and is ready to execute |
| **active** | `status = active` | Work is in progress |
| **blocked** | `status = blocked` | Work cannot proceed until a dependency, decision, or input clears |
| **backlog** | `status = backlog` | Intentionally parked so it stays out of current work views |
| **finished** | `status = finished` | Implementation is complete |
| **archived** | `status = archived` | Historical record outside normal planning and execution |

These values are the canonical set for workplan frontmatter, the workplan API,
consistency checks, and dashboard status filters.

Normal progression (informal path; the flow definition may constrain moves):

```text
backlog -> proposed -> ready -> active -> finished -> archived
                    \          \
                     \          -> blocked -> active
                      -> backlog
```

Flow definition: `flows/workplan.yaml` (`entity_type: workplan`). Notable
assertions in the live definition:

- Entering **finished** requires all child tasks in `done` or `cancel`.
- **blocked** / leaving **active** can depend on dependency workplans reaching
  `finished` or `archived`.

**Residuals on finish (process, not a flow assertion yet):** before
`status: finished`, any intentional leftover work must be captured as a **live
work record** (intake with `origin: residual` + `origin_ref: <this-WP-id>`, or
a spawned child workplan / decision / engagement / register entry). Prose in
the finished file is narrative only — not the fleet backlog. See
[Work Records — Residuals](/docs/work-records#residuals-role-not-kind) and
fleet canon `work-record-types_v0.1.md` § Residuals.

---

## Health labels (not stored status)

| Label | Source | Meaning |
|---|---|---|
| **needs_review** | Ready-review metadata + git diff | A `ready` workplan may be stale because relevant files changed since review |
| **stalled** | Task counts + timestamp | Work started, but there has been no meaningful progress after the threshold |

`needs_review` and `stalled` can appear beside lifecycle states. They are not
written into workplan frontmatter `status` and are not workplan lifecycle
values.

---

## Ready review metadata

Ready workplans may include optional frontmatter:

```yaml
reviewed_at: "YYYY-MM-DD"
reviewed_by: "human-or-agent"
reviewed_against_commit: "<git-sha>"
context_paths:
  - "path/or/glob"
```

If `reviewed_against_commit` differs from `HEAD`, State Hub checks
`context_paths` when present. Relevant changes produce the derived
`needs_review` label. Automatic demotion from `ready` to `proposed` is guarded
behind explicit tooling, not done silently.

---

## Relation to tasks and intakes

| Relation | What happens today |
|----------|--------------------|
| **Tasks** | Own lifecycle (`wait` / `todo` / `progress` / `done` / `cancel`). Starting real work (`todo` → `progress`) can activate a parent workplan that is still in `proposed`, `ready`, or `backlog`. |
| **Intake promotion** | A routed intake can be promoted into a new workplan (or task/decision/engagement) via `scripts/promote_intake.py` / `statehub promote-intake`. The intake closes as `promoted` with `promoted_to` set to the new canonical id. |
| **File backing** | Workplans originate as repo files; the hub indexes them. Manual hub-only create tools exist for bootstrap; steady-state structure is file → `fix-consistency`. |

---

## Flow operations

```text
get_flow_state(entity_type="workplan", entity_id="<uuid>")
advance_workstation(entity_type="workplan", entity_id="<uuid>", target_workstation="finished")
```

Direct status patching still exists for bootstrap and compatibility work:

```bash
curl -X PATCH http://127.0.0.1:8000/workplans/<uuid>/ \
  -H "Content-Type: application/json" \
  -d '{"status": "finished"}'
```

Preferred list/update routes are under `/workplans/`. Some older
`/workstreams/` aliases were retired (410) or remain metered; see
`docs/workplan-terminology-transition.md`.

Workplans are not hard-deleted in normal operation. Use `finished` for
completed implementation and `archived` for historical records outside normal
planning.

---

*Workstation* in API/tool names means the current lifecycle label of an
information object — for workplans that label is the `status` field.