tegwick
b2264d1f06
Add the ranked legacy-interface backlog (T01), rename dashboard navigation and user-facing copy to workplan while preserving wire-compat API keys (T02), and activate the retirement workplan with T01/T02 marked done.
86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
---
|
|
title: Workplan Lifecycle - Reference
|
|
---
|
|
|
|
# Workplan Lifecycle - Reference
|
|
|
|
A workplan 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:
|
|
|
|
```text
|
|
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 workplan
|
|
`status` field.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## 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"}'
|
|
```
|
|
|
|
Workplans are never hard-deleted. Use `finished` for completed
|
|
implementation and `archived` for historical records outside normal planning.
|