tegwick
fec05dcb5d
Resolves all orphan-workstream FAIL findings from validate_repo_adr.
The custodian domain now passes 47/47 checks (0 warn, 0 fail).
Files written:
CUST-WP-0001 custodian-agent-runtime (2 tasks: 1 done, 1 todo)
CUST-WP-0002 contribution-tracking-sbom (15 tasks, v0.5 scope
reductions annotated inline)
CUST-WP-0003 whi-kpi-card (9 tasks)
CUST-WP-0004 ep-td-tracking (10 tasks: 4 done, 6 todo)
All files cross-reference state_hub_workstream_id and
state_hub_task_id for future sync reconciliation.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
187 lines
6.2 KiB
Markdown
187 lines
6.2 KiB
Markdown
---
|
|
id: CUST-WP-0003
|
|
type: workplan
|
|
title: "State Hub v0.4 — Workstream Health Index (WHI) KPI Card"
|
|
domain: custodian
|
|
status: active
|
|
owner: custodian
|
|
topic_slug: custodian
|
|
state_hub_workstream_id: 9cc32158-2f5c-4ef6-9713-aacce4623d5e
|
|
created: "2026-02-26"
|
|
updated: "2026-02-28"
|
|
---
|
|
|
|
# State Hub v0.4 — Workstream Health Index (WHI) KPI Card
|
|
|
|
## Summary
|
|
|
|
Implement the Workstream Health Index (WHI) — a composite structural-health
|
|
KPI — as a live card injected into the TOC sidebar of the Workstreams
|
|
dashboard page. All six metrics are computable client-side from data
|
|
already fetched by `workstreams.md`; no API or schema changes required.
|
|
|
|
## Context
|
|
|
|
The WHI formula and metric definitions are specified in
|
|
`state-hub/dashboard/src/docs/workstream-kpi.md`. This workplan covers
|
|
only the implementation of that spec as running dashboard code.
|
|
|
|
The six base metrics:
|
|
- **DD** — Dependency Density: edge count / open workstream count
|
|
- **BR** — Blocked Ratio: blocked workstreams / open count
|
|
- **SPR** — Single Point of Risk: max inbound edges / open count
|
|
- **PEP** — Progression Enablement Proportion: ready-to-start workstreams
|
|
- **CDDR** — Cross-Domain Dependency Ratio: cross-domain edges / total edges
|
|
- **CPI** — Cycle Penalty Indicator: 1 if any cycle detected, 0 otherwise
|
|
|
|
WHI formula: `0.30*(1-DDnorm) + 0.25*(1-BR) + 0.15*(1-SPR) + 0.20*PEP + 0.10*(1-CDDR)`
|
|
CPI penalty: `WHI = WHI * 0.5` if CPI=1.
|
|
|
|
## Tasks
|
|
|
|
### P1 — Verify dependency edge fields in open_workstreams
|
|
|
|
```task
|
|
id: CUST-WP-0003-T01
|
|
state_hub_task_id: 243646e0-b77a-41e7-ac51-82c5828e63d2
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Confirm that `summary.open_workstreams[].depends_on[]` and `blocks[]`
|
|
each carry `workstream_id`, `workstream_slug`, and `workstream_title`.
|
|
Verify these fields are sufficient to build a complete directed dependency
|
|
graph client-side without additional API calls. (Already verified during
|
|
workplan design — open_workstreams is the confirmed data source.)
|
|
|
|
### P2.1 — Build directed dependency graph from openWs + completedIds
|
|
|
|
```task
|
|
id: CUST-WP-0003-T02
|
|
state_hub_task_id: 6dbef71f-d2d7-44ee-abb8-279dbaeec505
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
In `workstreams.md`: derive `completedIds = new Set` of IDs of workstreams
|
|
with status completed. Build an adjacency list: for each entry in openWs,
|
|
map workstream id → array of `depends_on[].workstream_id`. Build reverse
|
|
map (prerequisite id → list of dependent ids) for SPR computation. Also
|
|
build `idToDomain` map from `data[]` for CDDR.
|
|
|
|
### P2.2 — Implement DFS cycle detection (CPI)
|
|
|
|
```task
|
|
id: CUST-WP-0003-T03
|
|
state_hub_task_id: f0d5c107-6029-4ad0-af00-645d35ce7db0
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Implement a DFS-based topological sort over the dependency adjacency list.
|
|
Detect back edges using visited / inStack colour sets. Return `CPI = 1`
|
|
if any cycle found, `CPI = 0` otherwise. Only nodes in openWs participate
|
|
(completed/archived workstreams excluded). Edge case: isolated nodes (no
|
|
deps, no dependents) are valid and never form cycles.
|
|
|
|
### P2.3 — Compute DD, BR, SPR, PEP, CDDR
|
|
|
|
```task
|
|
id: CUST-WP-0003-T04
|
|
state_hub_task_id: 6da60567-cc46-4a32-9855-b07bafe2faeb
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Using the graph from P2.1:
|
|
- `DD`: totalEdges / openCount, where totalEdges = openWs.flatMap(w=>w.depends_on).length
|
|
- `BR`: openWs.filter(w=>w.status==="blocked").length / openCount
|
|
- `SPR`: max inbound-edge count across prerequisite workstreams in openWs / openCount
|
|
- `PEP`: openWs.filter(w=>active && all depends_on are in completedIds).length / openCount
|
|
- `CDDR`: crossDomainEdges / totalEdges (edge with different domain endpoints); 0 if no edges
|
|
|
|
### P2.4 — WHI formula: normalisation + CPI penalty
|
|
|
|
```task
|
|
id: CUST-WP-0003-T05
|
|
state_hub_task_id: 29b2dbbd-5d60-49b6-ae84-3dbf22167df7
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Implement the weighted aggregation:
|
|
```
|
|
DDnorm = min(1, DD / 1.0) // DD_critical = 1.0
|
|
WHI = 0.30*(1-DDnorm) + 0.25*(1-BR) + 0.15*(1-SPR) + 0.20*PEP + 0.10*(1-CDDR)
|
|
if CPI === 1: WHI = WHI * 0.5
|
|
```
|
|
Clamp to [0, 1]. Return `{whi, dd, ddNorm, br, spr, pep, cddr, cpi, openCount, edgeCount}`.
|
|
Factor into `computeWHI(nodes, edges, idToDomain)` for reuse in per-domain scope.
|
|
|
|
### P2.5 — Per-domain WHI breakdown
|
|
|
|
```task
|
|
id: CUST-WP-0003-T06
|
|
state_hub_task_id: 8ce5ef74-5eb8-4259-9b11-dde13bf84a89
|
|
status: todo
|
|
priority: medium
|
|
```
|
|
|
|
For each domain present in openWs, compute a domain-scoped WHI:
|
|
- `domainNodes = openWs.filter(w => idToDomain[w.id] === domain)`
|
|
- `domainEdges = domainNodes.flatMap(w => w.depends_on.filter(d => idToDomain[d.workstream_id] === domain))`
|
|
- `result = computeWHI(domainNodes, domainEdges, idToDomain)`
|
|
|
|
Store as `[{domain, whi, br, pep, cpi, openCount}]`. Skip domains with
|
|
`openCount === 0`.
|
|
|
|
### P3 — WHI KPI card UI
|
|
|
|
```task
|
|
id: CUST-WP-0003-T07
|
|
state_hub_task_id: 91efba5c-3be2-4bfe-b5ef-1b261e9423f2
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Build the `_whiBox` element in `workstreams.md` (mirrors `_kpiBox` in
|
|
`decisions.md`):
|
|
- Card title: "Workstream Health"
|
|
- Main WHI value with health state label: GREEN ≥ 0.75 / ORANGE ≥ 0.50 / RED < 0.50
|
|
- Sub-metric rows for DD, BR, SPR, PEP, CDDR with individual warning colours
|
|
- Cycle alert row (red ⚠) when CPI=1
|
|
- Domain breakdown: compact rows with domain name + coloured score
|
|
- Empty state if openCount=0 or no edges
|
|
|
|
Inject via `injectTocTop("whi-kpi-box", _whiBox)`. Wire
|
|
`withDocHelp(_whiBox, "/docs/workstream-health-index")`.
|
|
|
|
### P4.1 — Create src/docs/workstream-health-index.md
|
|
|
|
```task
|
|
id: CUST-WP-0003-T08
|
|
state_hub_task_id: 4c898472-e4ae-49a2-b6cd-7aa1a3c7604a
|
|
status: todo
|
|
priority: medium
|
|
```
|
|
|
|
Reference documentation for the WHI KPI card. Cover: purpose, all six
|
|
metrics (formula + interpretation), WHI aggregation formula with CPI
|
|
penalty, DD normalisation, health state thresholds, domain breakdown,
|
|
cycle detection, and how to improve a poor score. Update
|
|
`workstream-kpi.md` to link to this doc.
|
|
|
|
### P4.2 — Wire withDocHelp and add to Reference nav
|
|
|
|
```task
|
|
id: CUST-WP-0003-T09
|
|
state_hub_task_id: 20976663-7ac9-4909-8029-a479190f52ff
|
|
status: todo
|
|
priority: low
|
|
```
|
|
|
|
Confirm `withDocHelp(_whiBox, "/docs/workstream-health-index")` is wired
|
|
(from P3). Add `{ name: "Workstream Health", path: "/docs/workstream-health-index" }`
|
|
to the Reference pages array in `observablehq.config.js`. Verify
|
|
Reference nav renders correctly in `npm run dev`.
|