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. File convention: ADR-001 / Workplans.

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 (DoR-Ok / DoR-Failed) and 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):

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 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:

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

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:

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.