state-hub/workplans/CUST-WP-0003-whi-kpi-card.md

---
id: CUST-WP-0003
type: workplan
title: "State Hub v0.4 — Workstream Health Index (WHI) KPI Card"
domain: custodian
repo: state-hub
status: finished
owner: custodian
topic_slug: custodian
state_hub_workstream_id: 9cc32158-2f5c-4ef6-9713-aacce4623d5e
created: "2026-02-26"
updated: "2026-06-04"
---

# 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 `dashboard/src/workstreams.md`; no API or schema changes
required.

## Context

The WHI formula and metric definitions are specified in
`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: done
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: done
priority: high
```

In `dashboard/src/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: done
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: done
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: done
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: done
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: done
priority: high
```

Build the `_whiBox` element in `dashboard/src/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: done
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: done
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`.

## Implementation Evidence - 2026-06-04

This workplan was stale: the WHI implementation already existed in the current
State Hub dashboard worktree, but all tasks were still marked `todo`.

Evidence reviewed:

- `dashboard/src/workstreams.md` derives dependency edges from `/state/deps`,
  computes DD, BR, SPR, PEP, CDDR, CPI, the weighted WHI score, and per-domain
  intra-domain WHI breakdown.
- The Workplans page injects the WHI KPI card through
  `injectTocTop("whi-kpi-box", _whiBox)` and wires
  `withDocHelp(_whiBox, "/docs/workstream-health-index")`.
- The card shows the global score, health label, submetric rows, cycle alert,
  and domain breakdown.
- `dashboard/src/docs/workstream-health-index.md` documents the metric,
  thresholds, formula, CPI penalty, domain breakdown, and improvement actions.
- `dashboard/src/reference.md` and `dashboard/observablehq.config.js` include
  the Workstream Health reference page.
- Verification:
  - `npm test` in `dashboard/` passed: 11 tests.
  - `npm run build` in `dashboard/` passed: 61 pages built, including
    `/workstreams` and `/docs/workstream-health-index`, with 49 links
    validated.

All CUST-WP-0003 tasks are therefore complete and the workplan is finished.