generated from coulomb/repo-seed
Complete workplan state model cleanup
This commit is contained in:
@@ -244,7 +244,8 @@ The Overview page renders a horizontal stacked bar chart using `@observablehq/pl
|
||||
showing task counts (done / in progress / blocked / todo) per workstream.
|
||||
A `<select>` dropdown switches between:
|
||||
|
||||
- **Status modes**: active, accepted, finished, blocked, stalled, oldies
|
||||
- **Lifecycle modes**: proposed, ready, active, blocked, backlog, finished, archived
|
||||
- **Health modes**: needs review, stalled
|
||||
- **Time modes**: last 1h, 24h, 7d, 30d, today, this week, this month
|
||||
|
||||
Domains are sorted by most recent workstream activity (most active domain at
|
||||
|
||||
@@ -4,7 +4,7 @@ title: Dependencies — Reference
|
||||
|
||||
# Dependencies — Reference
|
||||
|
||||
The Dependencies page shows the directed dependency graph between active
|
||||
The Dependencies page shows the directed dependency graph between open
|
||||
workstreams — which workstreams are waiting on others to reach a satisfactory
|
||||
state before they can fully proceed.
|
||||
|
||||
@@ -13,7 +13,7 @@ state before they can fully proceed.
|
||||
## What is a dependency edge?
|
||||
|
||||
A dependency edge **A → B** means workstream A cannot fully proceed until
|
||||
workstream B is in a satisfactory state (typically `completed` or `archived`).
|
||||
workstream B is in a satisfactory state (typically `finished` or `archived`).
|
||||
|
||||
Edges are used to model real sequencing constraints: for example, a shared
|
||||
library must reach a stable release before downstream domains can build on it.
|
||||
@@ -36,7 +36,7 @@ Each row shows:
|
||||
| **→** | Direction arrow |
|
||||
| **Blocked-by domain** | Domain of the prerequisite workstream |
|
||||
| **Blocked-by workstream** | Title of the workstream that must complete first |
|
||||
| **Status** | Current status of the prerequisite (green = active, grey = completed) |
|
||||
| **Status** | Current status of the prerequisite (green = active, grey = finished/archived) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -48,7 +48,7 @@ Four metric cards:
|
||||
|
||||
| Card | Meaning |
|
||||
|------|---------|
|
||||
| **Active Workstreams** | Count of non-completed, non-archived workstreams |
|
||||
| **Active Workstreams** | Count of active/blocked execution workstreams |
|
||||
| **Blocking Decisions** | Pending decisions with status `open` or `escalated` — orange border if > 0 |
|
||||
| **Blocked Tasks** | Click to expand the list with blocking reasons |
|
||||
| **Events Today** | Progress events created on today's date |
|
||||
|
||||
@@ -39,7 +39,7 @@ These types are used by the State Hub's built-in write operations:
|
||||
| Type | When emitted |
|
||||
|---|---|
|
||||
| `workstream_created` | A new workstream was registered |
|
||||
| `workstream_status_changed` | Workstream moved to active / blocked / completed / archived |
|
||||
| `workstream_status_changed` | Workstream moved between canonical lifecycle states |
|
||||
| `workstation_advanced` | Flow-aware movement via `advance_workstation()` succeeded |
|
||||
| `task_created` | A new task was added to a workstream |
|
||||
| `task_status_changed` | Task moved to todo / in_progress / blocked / done / cancelled |
|
||||
|
||||
@@ -92,7 +92,7 @@ cd ~/ralph-workplan && ./install.sh --uninstall
|
||||
---
|
||||
id: WP-0001
|
||||
title: "Build a thing"
|
||||
status: active
|
||||
status: ready
|
||||
---
|
||||
|
||||
Optional description.
|
||||
@@ -120,7 +120,7 @@ priority: medium
|
||||
|-------|--------|-------------|
|
||||
| `id` | string | Unique workplan identifier |
|
||||
| `title` | string | Human-readable name |
|
||||
| `status` | `active` \| `done` \| `paused` | Workplan lifecycle state |
|
||||
| `status` | `proposed` \| `ready` \| `active` \| `blocked` \| `backlog` \| `finished` \| `archived` | Workplan lifecycle state |
|
||||
|
||||
**Task block fields:**
|
||||
|
||||
@@ -144,7 +144,7 @@ status: in_progress → status: done (when verified complete)
|
||||
When every task is `done`, Claude also updates the frontmatter:
|
||||
|
||||
```
|
||||
status: active → status: done
|
||||
status: active -> status: finished
|
||||
```
|
||||
|
||||
The loop detects this on the next iteration and stops.
|
||||
|
||||
@@ -72,7 +72,7 @@ autonomously. No human interaction is needed unless the agent has a question.
|
||||
|
||||
The [Repos](/repos) page shows each repo's integration status. An **integrating**
|
||||
badge appears on repos with an active Repo Integration workstream. The badge
|
||||
clears when the workstream is marked completed.
|
||||
clears when the workstream is marked finished.
|
||||
|
||||
---
|
||||
|
||||
@@ -120,8 +120,8 @@ repo agent should:
|
||||
primary near-term work; register the workstream in the hub via MCP
|
||||
4. Execute T3 — ingest the SBOM so the repo appears green on the Repos page
|
||||
5. Execute T4 — a quick scan for obvious EPs/TDs; defer if nothing obvious
|
||||
6. Mark each task `done` in the hub as completed
|
||||
7. Mark the Repo Integration workstream `completed`
|
||||
6. Mark each task `done` in the hub
|
||||
7. Mark the Repo Integration workstream `finished`
|
||||
8. Log a progress event summarising the integration
|
||||
|
||||
The agent should resolve each task independently and in order. It does not
|
||||
|
||||
@@ -73,13 +73,13 @@ Detects concentration of blocking power. High SPR means one delay propagates wid
|
||||
### PEP — Parallel Execution Potential
|
||||
|
||||
```
|
||||
PEP = active workstreams with all deps completed / (active + blocked)
|
||||
PEP = ready or active workstreams with all deps finished / (ready + active + blocked)
|
||||
```
|
||||
|
||||
Estimates how much work can proceed right now. A workstream is eligible if its
|
||||
stored workstation label is `active` and the flow/dependency checks report no
|
||||
stored workstation label is `ready` or `active` and the flow/dependency checks report no
|
||||
unmet dependency assertion; practically, every workstream it depends on has
|
||||
reached `completed` or `archived`.
|
||||
reached `finished` or `archived`.
|
||||
|
||||
| PEP | Warning |
|
||||
|---|---|
|
||||
@@ -147,7 +147,7 @@ The domain breakdown is shown when at least two domains have active workstreams.
|
||||
| Symptom | Action |
|
||||
|---|---|
|
||||
| High DD | Decompose tightly coupled workstreams; remove unnecessary dependencies |
|
||||
| High BR | Unblock workstreams — resolve the blocking condition, or mark dependency as completed if done |
|
||||
| High BR | Unblock workstreams — resolve the blocking condition, or mark dependency as finished if done |
|
||||
| High SPR | Split the bottleneck workstream into independent deliverables |
|
||||
| Low PEP | Complete prerequisite workstreams or re-sequence work |
|
||||
| High CDDR | Refactor cross-domain dependencies into shared contracts or invert the dependency |
|
||||
|
||||
@@ -143,11 +143,11 @@ High SPR indicates fragile structure where one delay propagates widely.
|
||||
|
||||
A workstream is eligible if:
|
||||
|
||||
* Status = active
|
||||
* All dependencies are completed
|
||||
* Status = ready or active
|
||||
* All dependencies are finished or archived
|
||||
|
||||
[
|
||||
PEP = \frac{\text{Eligible active workstreams}}{\text{Active + Blocked}}
|
||||
PEP = \frac{\text{Eligible ready or active workstreams}}{\text{Ready + Active + Blocked}}
|
||||
]
|
||||
|
||||
---
|
||||
@@ -378,4 +378,3 @@ It captures both:
|
||||
* Operational flow conditions
|
||||
|
||||
By combining graph properties with status information, WHI enables proactive management of coordination complexity.
|
||||
|
||||
|
||||
@@ -1,111 +1,86 @@
|
||||
---
|
||||
title: Workstream Lifecycle — Reference
|
||||
title: Workstream Lifecycle - Reference
|
||||
---
|
||||
|
||||
# Workstream Lifecycle — Reference
|
||||
# Workstream Lifecycle - Reference
|
||||
|
||||
A workstream is an information object that occupies a named workstation. The
|
||||
stored `status` field keeps the current workstation label, while the
|
||||
task-flow engine derives which other workstations are reachable and which exit
|
||||
assertions are blocking movement. The dashboard "Workstreams by Domain" chart
|
||||
exposes stored and derived states as selectable filters so attention can be
|
||||
directed to the right workstreams at the right time.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Core workstations
|
||||
## Stored Lifecycle States
|
||||
|
||||
These are the primary workstations used by State Hub workstreams:
|
||||
|
||||
| Workstation | Source | Meaning |
|
||||
| State | Source | Meaning |
|
||||
|---|---|---|
|
||||
| **active** | DB `status = active` | Work is in progress or ready to start |
|
||||
| **finished** | Derived — no open tasks | All tasks are done, but no explicit review has taken place yet |
|
||||
| **accepted** | DB `status = completed` | Custodian and human have reviewed the workstream, quality checks passed, and it is formally signed off |
|
||||
| **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 |
|
||||
|
||||
The normal human-facing path is: **active → finished → accepted**.
|
||||
|
||||
`accepted` is the only state that requires an explicit action. It is reached by
|
||||
advancing the workstream to the `completed` workstation after deliberate
|
||||
review, not by task counts alone. This makes it a reliable anchor: anything in
|
||||
`finished` but not yet in `accepted` is work that still needs a quality pass.
|
||||
|
||||
---
|
||||
|
||||
## Attention signals
|
||||
|
||||
These signals are orthogonal to the core workstation — a workstream can be
|
||||
`active` and `stalled` at the same time. They serve as health indicators
|
||||
rather than stored lifecycle stages.
|
||||
|
||||
| Signal | Source | Meaning |
|
||||
|---|---|---|
|
||||
| **blocked** | Derived — unmet exit assertion or blocked task | Work cannot currently leave its workstation; inspect `blocked_reasons` |
|
||||
| **stalled** | Derived — `updated_at` > 7 days ago, has both done and open tasks | Work started but activity has stopped; needs a nudge |
|
||||
| **oldies** | Derived — `created_at` > 7 days ago, zero done tasks | Workstream is old and nothing has been completed yet; may need re-evaluation |
|
||||
|
||||
---
|
||||
|
||||
## The acceptance quality gate
|
||||
|
||||
When a workstream reaches **finished** (all tasks done), the custodian's role is to:
|
||||
|
||||
1. Review the deliverables against the workstream's stated purpose and scope
|
||||
2. Check for missing tests, documentation, or follow-up issues
|
||||
3. Create tasks for any gaps found — this moves the workstream back to **active**
|
||||
4. Once satisfied, advance to the `completed` workstation — this marks it as **accepted**
|
||||
|
||||
This pattern ensures that "done" and "accepted" are distinct signals.
|
||||
`finished` is a fact about task counts; `accepted` is a statement of quality.
|
||||
Normal progression:
|
||||
|
||||
```text
|
||||
backlog -> proposed -> ready -> active -> finished -> archived
|
||||
\ \
|
||||
\ -> blocked -> active
|
||||
-> backlog
|
||||
```
|
||||
# Inspect and accept a workstream via MCP
|
||||
get_flow_state(entity_type="workstream", entity_id="<uuid>")
|
||||
advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="completed")
|
||||
|
||||
# Or via REST
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```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="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:
|
||||
|
||||
```bash
|
||||
curl -X PATCH http://127.0.0.1:8000/workstreams/<uuid>/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"status": "completed"}'
|
||||
-d '{"status": "finished"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Time-based filters
|
||||
|
||||
The chart also supports time-window filters that cut across all lifecycle states:
|
||||
|
||||
| Filter | Shows workstreams where… |
|
||||
|---|---|
|
||||
| **last 1 hour** | `updated_at` or `created_at` within the last 60 minutes |
|
||||
| **last 24 hours** | … within the last 24 hours |
|
||||
| **last 7 days** | … within the last 7 days |
|
||||
| **last 30 days** | … within the last 30 days |
|
||||
| **today** | … since midnight today |
|
||||
| **this week** | … since Monday of the current week |
|
||||
| **this month** | … since the 1st of the current month |
|
||||
|
||||
In time-based views, workstream labels are **bold** for accepted and blocked
|
||||
workstreams to distinguish notable states at a glance.
|
||||
|
||||
---
|
||||
|
||||
## Stored Label Vs. Dashboard State
|
||||
|
||||
The DB stores a single `status` field on each workstream. Treat it as the
|
||||
current workstation label. The dashboard maps this alongside flow-engine
|
||||
results, dependency assertions, and task-count data to produce the richer set
|
||||
of filter states:
|
||||
|
||||
| Dashboard state | Stored label / derived source | Condition |
|
||||
|---|---|---|
|
||||
| active | `status = active` | — |
|
||||
| accepted | `status = completed` | — |
|
||||
| finished | task counts | `todo + in_progress + blocked = 0` |
|
||||
| blocked | flow result / task counts | `exit_blocked = true` or `blocked ≥ 1` |
|
||||
| stalled | task counts + timestamp | `done ≥ 1` and `open ≥ 1` and `updated_at > 7d ago` |
|
||||
| oldies | task counts + timestamp | `done = 0` and `open ≥ 1` and `created_at > 7d ago` |
|
||||
|
||||
*Workstreams are never hard-deleted — use `advance_workstation(...,
|
||||
"completed")` or advance/patch to `"archived"` to close them without losing
|
||||
history.*
|
||||
Workstreams are never hard-deleted. Use `finished` for completed
|
||||
implementation and `archived` for historical records outside normal planning.
|
||||
|
||||
@@ -20,14 +20,17 @@ as filters change.
|
||||
|
||||
| Workstation | Meaning |
|
||||
|---|---|
|
||||
| **active** | Work in progress or ready to start |
|
||||
| **proposed** | Plan exists, but needs review against current repo state |
|
||||
| **ready** | Reviewed and ready to execute |
|
||||
| **active** | Work is in progress |
|
||||
| **blocked** | Stored blocker label; the State Hub can also derive blocked state from unmet exit assertions |
|
||||
| **completed** | Formally accepted after custodian review (shown as **accepted** in the overview chart) |
|
||||
| **archived** | Closed without completion; no longer relevant |
|
||||
| **backlog** | Intentionally parked for later |
|
||||
| **finished** | Implementation is complete |
|
||||
| **archived** | Closed historical record |
|
||||
|
||||
See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full task-flow
|
||||
model including derived states (finished, stalled, oldies) and assertion-based
|
||||
blocking.
|
||||
model including derived health labels (`needs_review`, `stalled`) and
|
||||
assertion-based blocking.
|
||||
|
||||
---
|
||||
|
||||
@@ -91,7 +94,7 @@ create_workstream(
|
||||
topic_id = "<uuid>",
|
||||
title = "Build user authentication",
|
||||
description = "JWT-based auth, refresh tokens, middleware",
|
||||
status = "active",
|
||||
status = "ready",
|
||||
owner = "human",
|
||||
due_date = "2026-04-01"
|
||||
)
|
||||
@@ -102,7 +105,7 @@ Via REST:
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/workstreams/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"topic_id": "<uuid>", "title": "…", "status": "active"}'
|
||||
-d '{"topic_id": "<uuid>", "title": "…", "status": "ready"}'
|
||||
```
|
||||
|
||||
---
|
||||
@@ -111,7 +114,7 @@ curl -X POST http://127.0.0.1:8000/workstreams/ \
|
||||
|
||||
```
|
||||
get_flow_state(entity_type="workstream", entity_id="<uuid>")
|
||||
advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="completed")
|
||||
advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="finished")
|
||||
```
|
||||
|
||||
Movement is flow-aware: the task-flow engine evaluates the target
|
||||
|
||||
Reference in New Issue
Block a user