Add Decisions and Workstreams reference docs with heading help wiring
- Remove residual constitution footnote from progress page header - Create src/docs/decisions.md: types, statuses, resolution history chart, filter bar, card anatomy, Decision Health KPI, escalation protocol - Create src/docs/workstreams.md: status distribution chart, filter bar, table columns, dependency graph, create/update patterns - Wire withDocHelp(h1) on Decisions and Workstreams pages pointing to new docs - Add both pages to Reference nav section in observablehq.config.js Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
110
state-hub/dashboard/src/docs/workstreams.md
Normal file
110
state-hub/dashboard/src/docs/workstreams.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Workstreams — Reference
|
||||
---
|
||||
|
||||
# Workstreams — Reference
|
||||
|
||||
A workstream is a bounded unit of work within a topic. It carries a status, an optional owner and due date, and belongs to exactly one of the six project domains. The Workstreams page gives you a filtered, visual overview of all active work and the dependency graph between workstreams.
|
||||
|
||||
---
|
||||
|
||||
## Status Distribution chart
|
||||
|
||||
A horizontal bar chart showing the count of workstreams in each status for the current filter selection. Updates immediately as filters change.
|
||||
|
||||
| Status | Meaning |
|
||||
|---|---|
|
||||
| **active** | Work in progress or ready to start |
|
||||
| **blocked** | Waiting on something outside the workstream — see Dependencies |
|
||||
| **completed** | Done |
|
||||
| **archived** | Closed without completion; no longer relevant |
|
||||
|
||||
---
|
||||
|
||||
## Filter bar
|
||||
|
||||
| Filter | Effect |
|
||||
|---|---|
|
||||
| **Domain** | Multi-select — show only workstreams from selected domains |
|
||||
| **Status** | Multi-select — show only workstreams with selected statuses |
|
||||
| **Owner** | Text substring match on the owner field (case-insensitive) |
|
||||
|
||||
Leaving a filter empty means "show all". All three filters combine with AND logic. Filters persist across polls — selections are not lost when the page refreshes live data.
|
||||
|
||||
The six domains are: `custodian`, `railiance`, `markitect`, `coulomb_social`, `personhood`, `foerster_capabilities`.
|
||||
|
||||
---
|
||||
|
||||
## All Workstreams table
|
||||
|
||||
| Column | Source |
|
||||
|---|---|
|
||||
| Title | Workstream title |
|
||||
| Domain | Derived from the parent topic |
|
||||
| Status | Current workstream status |
|
||||
| Owner | Assigned person (or `—` if unset) |
|
||||
| Due | Target completion date (or `—`) |
|
||||
| Updated | Last modification timestamp |
|
||||
|
||||
Up to 20 rows displayed; paginate for more.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
The Dependencies section shows workstreams that have at least one `depends_on` or `blocks` relationship. Each card displays:
|
||||
|
||||
- **Workstream title** and current status badge
|
||||
- **↳ depends on** — workstreams that must complete before this one can proceed
|
||||
- **⊳ blocks** — workstreams that are waiting on this one
|
||||
|
||||
Dependencies are created via the MCP server:
|
||||
|
||||
```
|
||||
create_dependency(
|
||||
from_workstream_id = "<uuid>", # the one that depends
|
||||
to_workstream_id = "<uuid>", # the prerequisite
|
||||
description = "needs auth before API can be built"
|
||||
)
|
||||
```
|
||||
|
||||
If no dependency edges exist for the current filter, the section shows an empty-state message.
|
||||
|
||||
---
|
||||
|
||||
## Creating workstreams
|
||||
|
||||
Via MCP:
|
||||
|
||||
```
|
||||
create_workstream(
|
||||
topic_id = "<uuid>",
|
||||
title = "Build user authentication",
|
||||
description = "JWT-based auth, refresh tokens, middleware",
|
||||
status = "active",
|
||||
owner = "Bernd",
|
||||
due_date = "2026-04-01"
|
||||
)
|
||||
```
|
||||
|
||||
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"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating workstream status
|
||||
|
||||
```
|
||||
update_workstream_status(workstream_id="<uuid>", status="completed")
|
||||
```
|
||||
|
||||
Valid transitions: `active` → `blocked` / `completed` / `archived`; `blocked` → `active`; `completed` → `archived`.
|
||||
|
||||
---
|
||||
|
||||
*Workstreams are never hard-deleted — use `archived` to close them without losing history.*
|
||||
Reference in New Issue
Block a user