state-hub/dashboard/src/docs/dependencies.md

---
title: Dependencies — Reference
---

# Dependencies — Reference

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.

---

## 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 `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.
The Custodian's dependency order is:

```
Railiance → Markitect → Coulomb.social → Personhood / Foerster → Custodian
```

---

## Edge table

Each row shows:

| Column | Meaning |
|--------|---------|
| **Depends-on domain** | Domain of the dependent workstream (the one waiting) |
| **Depends-on workstream** | Title of the workstream that has the dependency |
| **→** | 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 = finished/archived) |

---

## KPI sidebar card

Shows the total number of edges and the number of distinct workstreams involved
in at least one dependency relationship.

---

## Registering a dependency

Via MCP:

```
create_dependency(
  from_workstream_id = "<uuid of dependent>",
  to_workstream_id   = "<uuid of prerequisite>",
  description        = "Cannot build auth layer until shared-library API is stable"
)
```

Via REST:

```bash
curl -X POST http://127.0.0.1:8000/workstreams/<from_id>/dependencies/ \
  -H "Content-Type: application/json" \
  -d '{"to_workstream_id": "<to_id>", "description": "..."}'
```

To list dependencies for a workstream:

```
list_dependencies(workstream_id="<uuid>")
```

---

## Cycle detection

The Workstream Health Index (WHI) includes a **Cycle Penalty Index (CPI)**
metric that detects circular dependencies using depth-first search. If CPI = 1,
a cycle exists and the WHI is penalised by 50%. The WHI KPI card on the
[Workstreams](/workstreams) page will display a cycle alert.

---

## Data source

Dependency edges are derived from the `depends_on` arrays on `open_workstreams`
in `GET /state/summary`. Polls every **15 seconds**.