From bd6e16394af59d6bea7fdd99b57641ba729d1d6c Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Fri, 27 Feb 2026 08:53:43 +0100
Subject: [PATCH] chore: mark llm-shared-library workstream completed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All 9 tasks done (S1.1–S3.2). llm-connect is now a standalone
installable package at /home/worsch/llm-connect, integrated into
state-hub as its first consumer (S3.1, commit 444b35d).

Also tracks workstream-kpi.md spec (previously untracked).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 dashboard/src/docs/workstream-kpi.md | 381 +++++++++++++++++++++++++++
 1 file changed, 381 insertions(+)
 create mode 100644 dashboard/src/docs/workstream-kpi.md

diff --git a/dashboard/src/docs/workstream-kpi.md b/dashboard/src/docs/workstream-kpi.md
new file mode 100644
index 0000000..217721e
--- /dev/null
+++ b/dashboard/src/docs/workstream-kpi.md
@@ -0,0 +1,381 @@
+
+# Workstream Health Index (WHI)
+
+## Introduction & Requirements Specification
+
+**Status:** Draft
+**Purpose:** Define a quantitative KPI for structural health, coupling, and flow efficiency of workstreams
+**Scope:** Program-level coordination across domains and within domains
+**Primary Audience:** Project leads, system architects, program management, AI orchestration agents
+
+---
+
+## 1. Problem Statement
+
+Modern complex initiatives consist of multiple concurrent workstreams distributed across teams and domains. Ideally, workstreams should be:
+
+* Independently executable
+* Minimally coupled
+* Parallelizable
+* Robust against delays in other streams
+
+In practice, dependencies emerge due to:
+
+* Architectural constraints
+* Resource limitations
+* Organizational structure
+* Poor decomposition of work
+* Hidden prerequisite relationships
+
+Excessive coupling leads to:
+
+* Blocking states
+* Cascading delays
+* Increased coordination overhead
+* Reduced throughput
+* Fragile timelines
+* Circular waiting situations (deadlocks)
+
+Traditional project metrics (e.g., completion %, velocity, burn-down) do not capture **structural health** of the work graph.
+
+Therefore, a dedicated metric is required to assess:
+
+> **How well the program structure supports parallel execution and stable progress.**
+
+---
+
+## 2. Conceptual Model
+
+Workstreams form a **directed dependency graph**:
+
+* Nodes = workstreams
+* Edges = prerequisite relationships
+* Status = operational state
+* Domains = logical grouping
+
+Health is determined by:
+
+1. Structural coupling (how many dependencies exist)
+2. Operational blocking (how many streams cannot proceed)
+3. Concentration of risk (single points of failure)
+4. Parallel execution potential
+5. Cross-domain entanglement
+6. Presence of cycles (deadlocks)
+
+---
+
+## 3. Definition: Workstream Health Index (WHI)
+
+The **Workstream Health Index (WHI)** is a composite KPI representing the overall coordination efficiency and structural soundness of the workstream network.
+
+WHI is normalized to a value in the range:
+
+[
+0 \le WHI \le 1
+]
+
+Where:
+
+* **1.0 = ideal independence**
+* **0.0 = severe systemic dysfunction**
+
+WHI must be computed for:
+
+* Entire program
+* Each domain (intra-domain)
+* Cross-domain interactions
+
+---
+
+## 4. Base Metrics
+
+WHI aggregates the following primary indicators.
+
+---
+
+### 4.1 Dependency Density (DD)
+
+**Purpose:** Measure structural coupling introduced during planning.
+
+[
+DD = \frac{\text{Number of dependency edges}}{\text{Number of active + blocked workstreams}}
+]
+
+Interpretation:
+
+* Low DD → decomposed, parallelizable work
+* High DD → tightly coupled system
+
+Completed and archived streams are excluded because they no longer constrain progress.
+
+---
+
+### 4.2 Blocked Ratio (BR)
+
+**Purpose:** Measure immediate operational impact of dependencies.
+
+[
+BR = \frac{\text{Blocked workstreams}}{\text{Active + Blocked workstreams}}
+]
+
+Interpretation:
+
+* BR ≈ 0 → flow is unobstructed
+* High BR → large portion of work cannot proceed
+
+---
+
+### 4.3 Single-Point Risk (SPR)
+
+**Purpose:** Detect concentration of blocking power.
+
+[
+SPR = \frac{\text{Max number of dependents on one incomplete workstream}}{\text{Active + Blocked}}
+]
+
+High SPR indicates fragile structure where one delay propagates widely.
+
+---
+
+### 4.4 Parallel Execution Potential (PEP)
+
+**Purpose:** Estimate how much work can proceed immediately.
+
+A workstream is eligible if:
+
+* Status = active
+* All dependencies are completed
+
+[
+PEP = \frac{\text{Eligible active workstreams}}{\text{Active + Blocked}}
+]
+
+---
+
+### 4.5 Cross-Domain Dependency Ratio (CDDR)
+
+**Purpose:** Measure architectural entanglement between domains.
+
+[
+CDDR = \frac{\text{Dependencies crossing domain boundaries}}{\text{Total dependencies}}
+]
+
+High values indicate loss of modularity.
+
+---
+
+### 4.6 Cycle Presence Indicator (CPI)
+
+**Purpose:** Detect circular dependencies (deadlocks).
+
+CPI =
+
+* 0 → no cycles
+* 1 → at least one cycle detected
+
+Any cycle indicates structural invalidity of the dependency graph.
+
+---
+
+## 5. WHI Aggregation Formula
+
+Recommended weighted model:
+
+[
+WHI =
+0.30 \cdot (1 - DD_{norm}) +
+0.25 \cdot (1 - BR) +
+0.15 \cdot (1 - SPR) +
+0.20 \cdot PEP +
+0.10 \cdot (1 - CDDR)
+]
+
+If CPI = 1 (cycle present):
+
+[
+WHI = WHI \times 0.5
+]
+
+This penalty ensures deadlocks strongly degrade health.
+
+---
+
+### Normalization of DD
+
+Because DD is unbounded, normalize using a saturation threshold:
+
+[
+DD_{norm} = \min\left(1, \frac{DD}{DD_{critical}}\right)
+]
+
+Recommended:
+
+[
+DD_{critical} = 1.0
+]
+
+Meaning: one dependency per workstream is considered heavily coupled.
+
+---
+
+## 6. Aggregation Across Domains
+
+WHI must be computed at three levels:
+
+### 6.1 Intra-Domain WHI
+
+Using only workstreams and dependencies within the domain.
+
+Purpose:
+
+* Evaluate domain autonomy
+* Identify internal planning issues
+
+---
+
+### 6.2 Cross-Domain WHI
+
+Using only dependencies crossing domains.
+
+Purpose:
+
+* Assess integration complexity
+* Identify architectural entanglement
+
+---
+
+### 6.3 Global WHI
+
+Computed on the full graph.
+
+---
+
+## 7. Health States
+
+### 🟢 GREEN — Healthy Structure
+
+**Condition:** Workstreams are largely independent and flow is stable.
+
+Recommended thresholds:
+
+* WHI ≥ 0.75
+* BR ≤ 0.20
+* DD ≤ 0.5
+* SPR ≤ 0.25
+* No cycles
+* PEP ≥ 0.6
+
+Interpretation:
+
+* Parallel execution effective
+* Delays localized
+* Planning adequate
+
+No intervention required.
+
+---
+
+### 🟠 ORANGE — Optimizable Coupling
+
+**Condition:** Dependencies introduce noticeable coordination cost but system remains viable.
+
+Trigger if ANY of:
+
+* 0.50 ≤ WHI < 0.75
+* 0.20 < BR ≤ 0.40
+* 0.5 < DD ≤ 1.0
+* 0.25 < SPR ≤ 0.40
+* PEP between 0.3 and 0.6
+* High cross-domain dependencies (> 0.4)
+
+Interpretation:
+
+* Parallelism reduced
+* Timeline sensitive to delays
+* Replanning likely beneficial
+
+Recommended action:
+
+> Review decomposition and dependency structure.
+
+---
+
+### 🔴 RED — Critical Coupling / Structural Failure
+
+**Condition:** Systemic blockage or high fragility.
+
+Trigger if ANY of:
+
+* WHI < 0.50
+* BR > 0.40
+* DD > 1.0
+* SPR > 0.40
+* PEP < 0.30
+* CPI = 1 (cycle present)
+* Large clusters of mutually blocked streams
+
+Interpretation:
+
+* Serial execution dominates
+* High coordination overhead
+* Cascading delays likely
+* Timeline unreliable
+
+Required action:
+
+> Immediate optimization at the planning layer.
+
+---
+
+## 8. Circular Dependency Handling
+
+Circular dependencies are treated as critical defects because they imply:
+
+* No feasible execution order
+* Deadlock or hidden assumptions
+* Planning inconsistency
+
+Detection must use graph cycle detection (e.g., DFS or topological sort failure).
+
+---
+
+## 9. Recommended Usage
+
+WHI should be used for:
+
+* Program governance dashboards
+* Planning reviews
+* Architecture decisions
+* Early risk detection
+* Automated orchestration systems
+* AI-assisted planning tools
+
+WHI is **not** a performance metric for individuals.
+
+---
+
+## 10. Design Principles
+
+The metric system is designed to be:
+
+* Domain-agnostic
+* Scalable
+* Resistant to gaming
+* Actionable
+* Explainable via drilldown
+* Compatible with automated systems
+* Suitable for long-lived programs
+
+---
+
+## 11. Summary
+
+The Workstream Health Index provides a quantitative measure of how effectively an organization structures work for parallel execution and stable progress.
+
+It captures both:
+
+* Structural design quality
+* Operational flow conditions
+
+By combining graph properties with status information, WHI enables proactive management of coordination complexity.
+