tegwick 166aedfa8d feat: add workplan aliases and legacy meter

Adds preferred workplan REST/event surfaces, legacy-meter telemetry and weekly review summaries, documentation/dashboard terminology updates, dashboard API loading fixes, and close-out sync for STATE-WP-0052 and STATE-WP-0054.

2026-06-04 08:25:31 +02:00

2.8 KiB

Raw Blame History

title
Workstream Lifecycle - Reference

Workstream Lifecycle - Reference

A workstream is an information object that occupies a named lifecycle state. The stored status field keeps that state, while the task-flow engine derives which other states are reachable and which exit assertions are blocking movement. Dashboard health filters such as needs_review and stalled are derived labels, not stored lifecycle values.

Stored Lifecycle States

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

Normal progression:

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

Health Labels

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 should not be written into workplan frontmatter or directly into the workstream status field.

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.

Flow Operations

get_flow_state(entity_type="workstream", entity_id="<uuid>")
advance_workstation(entity_type="workstream", 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"}'

Workstreams are never hard-deleted. Use finished for completed implementation and archived for historical records outside normal planning.

2.8 KiB Raw Blame History