feat(terminology): workplan-first dashboard and retirement backlog (STATE-WP-0069)
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
CI Smoke / container-smoke (push) Successful in 2s

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.
This commit is contained in:
tegwick 2026-07-08 16:08:32 +02:00
parent 4dc69bb8f5
commit b2264d1f06
44 changed files with 382 additions and 253 deletions

View file

@ -6,7 +6,7 @@ title: Dashboard — Technical Reference
The State Hub dashboard is the primary visual interface for the Custodian
ecosystem. It provides live, reactive views of all tracked domains,
workstreams, tasks, decisions, contributions, SBOM data, and agent activity —
workplans, tasks, decisions, contributions, SBOM data, and agent activity —
all sourced from the local FastAPI state service.
---
@ -63,7 +63,7 @@ Current loaders:
| File | API endpoint |
|---|---|
| `summary.json.py` | `/state/summary` |
| `workstreams.json.py` | `/workplans/` |
| `workplans.json.py` | `/workplans/` |
| `contributions.json.py` | `/contributions/` |
| `decisions.json.py` | `/decisions/` |
| `domains.json.py` | `/domains/` |
@ -120,7 +120,7 @@ The dashboard has 30+ pages organised in four navigation groups:
| Page | Route | Purpose |
|---|---|---|
| Overview | `/` | Cross-domain summary — workstream chart, status KPIs, blocking decisions, recent activity |
| Overview | `/` | Cross-domain summary — workplan chart, status KPIs, blocking decisions, recent activity |
| Capabilities | `/capability-requests` | Capability request routing and fulfilment status |
| Contributions | `/contributions` | Upstream contribution Kanban (bug reports, feature requests, upstream PRs) |
| Domains | `/domains` | Per-domain health overview and management |
@ -140,7 +140,7 @@ The dashboard has 30+ pages organised in four navigation groups:
| Repo Sync | `/repo-sync` | Consistency checker results and sync status |
| SBOM | `/sbom` | Software bill of materials — packages, licences, copyleft risk |
### Workstreams section
### Workplans section
| Page | Route | Purpose |
|---|---|---|
@ -173,7 +173,7 @@ Exports shared runtime configuration used by every live-polling page:
### `entity-modal.js`
A lightweight detail overlay for entities. Any table row or card can call
`openEntityModal(entity, type)` to open a full-detail panel without navigating
away from the page. Supports four entity types: `workstream`, `task`, `ep`
away from the page. Supports four entity types: `workplan`, `task`, `ep`
(extension point), and `td` (technical debt).
Also exports `buildEntityTable()` — a function that constructs a consistent,
@ -183,7 +183,7 @@ overflow ellipsis, and native tooltip-on-hover for truncated values.
### `toc-sidebar.js`
Provides `injectTocTop(id, element)` — injects a DOM element into the
Observable Framework table-of-contents sidebar above the page's first section
heading. Used on the Overview and Workstreams pages to embed live KPI infoboxes
heading. Used on the Overview and Workplans pages to embed live KPI infoboxes
directly in the sidebar.
### `doc-overlay.js`
@ -194,12 +194,12 @@ without leaving the current page.
### `help-tip.js`
A custom HTML element (`<help-tip>`) that renders an inline abbreviated label
with an expandable tooltip containing a longer description and a link to the
relevant reference page. Used in the Workstream Health Index card to annotate
relevant reference page. Used in the Workplan Health Index card to annotate
each metric abbreviation.
### `multiselect.js`
A multi-value dropdown filter input compatible with Observable's `Inputs.form()`
reactive pattern. Used on the Workstreams and Tasks pages for domain and status
reactive pattern. Used on the Workplans and Tasks pages for domain and status
filtering.
### `improvement-modal.js`
@ -223,17 +223,17 @@ shows green when the API is reachable and red with a restart command when it
is not. This allows the dashboard to be used as a persistent, always-on monitor
without requiring a page refresh.
### Workstream Health Index (WHI)
### Workplan Health Index (WHI)
The Workstreams page computes a **Workstream Health Index** — a single
The Workplans page computes a **Workplan Health Index** — a single
composite score (0100%) derived from five graph metrics:
| Metric | Abbrev. | Weight | Interpretation |
|---|---|---|---|
| Dependency Density | DD | 30% | Average deps per open workstream; high = tightly coupled |
| Blocked Ratio | BR | 25% | Share of workstreams in a blocked state |
| Single-Point Risk | SPR | 15% | Share of workstreams that others depend on but are not yet complete |
| Parallel Execution Potential | PEP | 20% | Share of workstreams that could start/continue immediately |
| Dependency Density | DD | 30% | Average deps per open workplan; high = tightly coupled |
| Blocked Ratio | BR | 25% | Share of workplans in a blocked state |
| Single-Point Risk | SPR | 15% | Share of workplans that others depend on but are not yet complete |
| Parallel Execution Potential | PEP | 20% | Share of workplans that could start/continue immediately |
| Cross-Domain Dependency Ratio | CDDR | 10% | Share of edges crossing domain boundaries |
A **Cycle Presence Indicator** (CPI) detected via DFS halves the total score
@ -241,17 +241,17 @@ when a dependency cycle is found, since cyclic dependencies cause deadlock.
The index is computed per-domain as well as globally and displayed in the
TOC sidebar as a persistent KPI card.
### Multi-mode workstream chart
### Multi-mode workplan chart
The Overview page renders a horizontal stacked bar chart using `@observablehq/plot`
showing task counts (done / progress / wait / todo) per workstream.
showing task counts (done / progress / wait / todo) per workplan.
A `<select>` dropdown switches between:
- **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
Domains are sorted by most recent workplan activity (most active domain at
the top). Title labels and done/total counters are overlaid directly on the bars.
### Resolve-in-place for blocking decisions
@ -271,14 +271,14 @@ in direct production dependencies.
### Dependency graph
The Dependencies page and the Workstreams page both surface inter-workstream
dependency data. Each workstream card shows the workstreams it depends on
(`↳ depends on`) and the workstreams it blocks (`⊳ blocks`), derived from
The Dependencies page and the Workplans page both surface inter-workplan
dependency data. Each workplan card shows the workplans it depends on
(`↳ depends on`) and the workplans it blocks (`⊳ blocks`), derived from
the `WorkstreamDependency` table.
### Entity modals
Any table row on any list page (workstreams, tasks, extension points, tech debt)
Any table row on any list page (workplans, tasks, extension points, tech debt)
can be clicked to open a detail modal with full field data, dependency lists,
task progress, and timestamps — without a page navigation or a separate detail
route.
@ -309,7 +309,7 @@ needed in the source directory). Typical mark types used across the dashboard:
| Mark | Used for |
|---|---|
| `Plot.barX` | Horizontal stacked task-count bars, SBOM licence distribution |
| `Plot.text` | Workstream title labels and done/total counters overlaid on bars |
| `Plot.text` | Workplan title labels and done/total counters overlaid on bars |
| `Plot.ruleX([0])` | Zero-axis rule on all bar charts |
Charts are rendered as inline SVG and inherit Observable Framework's theme
@ -339,4 +339,4 @@ data and shows the offline error state on each page.
- [Live Data](/docs/live-data) — polling mechanism and offline behaviour in detail
- [Connecting to the Hub](/docs/connecting) — MCP server registration
- [Overview](/docs/overview) — Overview page feature walkthrough
- [Workstreams](/docs/workstreams) — Workstreams page and WHI in depth
- [Workplans](/docs/workstreams) — Workplans page and WHI in depth