docs: residual handoff in hub docs, AGENTS, and templates
Align agent close/workplan finish with fleet residual convention (live work records, origin residual + origin_ref). Reference pages for work-records and intakes; session and workplan templates updated.
This commit is contained in:
parent
b5747d1104
commit
f8bd74e27e
10 changed files with 480 additions and 30 deletions
|
|
@ -1,30 +1,39 @@
|
|||
---
|
||||
title: Workplan Lifecycle - Reference
|
||||
title: Workplan Lifecycle — Reference
|
||||
---
|
||||
|
||||
# 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.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Stored Lifecycle States
|
||||
## 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 |
|
||||
| **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 |
|
||||
|
||||
Normal progression:
|
||||
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
|
||||
|
|
@ -33,22 +42,37 @@ backlog -> proposed -> ready -> active -> finished -> archived
|
|||
-> 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
|
||||
## 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 should
|
||||
not be written into workplan frontmatter or directly into the workplan
|
||||
`status` field.
|
||||
`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 review metadata
|
||||
|
||||
Ready workplans may include optional frontmatter:
|
||||
|
||||
|
|
@ -67,7 +91,17 @@ behind explicit tooling, not done silently.
|
|||
|
||||
---
|
||||
|
||||
## Flow Operations
|
||||
## 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>")
|
||||
|
|
@ -82,5 +116,15 @@ curl -X PATCH http://127.0.0.1:8000/workplans/<uuid>/ \
|
|||
-d '{"status": "finished"}'
|
||||
```
|
||||
|
||||
Workplans are never hard-deleted. Use `finished` for completed
|
||||
implementation and `archived` for historical records outside normal planning.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue