feat(dashboard): nav restructure, full context-help coverage, 11 new ref docs

Navigation:
- New order: Overview · Todo · Domains · Repos · Workstreams (collapsible,
  open:false, with atomic sub-entries: Decisions, Tasks, Debt, Extends,
  Dependencies) · Contributions · SBOM · Progress · Reference (collapsible)
- Reference section gains path:/reference landing page; all 18 doc pages
  listed in nav (alphabetical) and in reference.md table

New pages:
- todo.md — Internal / Ecosystem / Third-party todo classification
- dependencies.md — dependency edge table derived from state/summary
- reference.md — Reference landing page with full doc index

New reference doc pages (11):
  contributions, debt, dependencies, domains, extensions, overview,
  repos, tasks, todo + reference (meta) already added previously

doc-overlay.js — lazy bubblehelp tooltip:
- _titleCache Map + _fetchDocTitle(docPath): on first hover of any ?
  button, fetches the target doc page, parses <h1>, sets btn.title
- Native browser tooltip appears exactly on the ? circle on subsequent hover

Context-help wired on all 14 dashboard pages:
- h1 withDocHelp added to: index, todo, domains, repos, tasks, techdept,
  extensions, dependencies (contributions/workstreams/decisions/sbom/
  progress/reference were already wired)
- domains.md + repos.md: added missing withDocHelp import and live-data link
- tasks/techdept/extensions: removed duplicate _h1 const that caused
  SyntaxError: Identifier '_h1' has already been declared

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-01 23:46:26 +01:00
parent 70c8e3cd51
commit 947c2e8824
22 changed files with 1468 additions and 25 deletions

View File

@@ -0,0 +1,90 @@
---
title: Dependencies — Reference
---
# Dependencies — Reference
The Dependencies page shows the directed dependency graph between active
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 `completed` 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 = completed) |
---
## 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**.