the-custodian/roadmap/state-hub-v0.2/PLAN.md

---
title: "State Hub v0.2 — Decisions, Suggestions & Dependencies"
domain: custodian
workstream_slug: state-hub-v0.2
status: active
created: 2026-02-25
---

# State Hub v0.2 — Decisions, Suggestions & Dependencies

## Purpose

Evolve the State Hub from a cross-domain state tracker to an active coordination layer.

Three additions:
1. **Design boundary clarity** — formalise the "observation + 2 write exceptions" model across all integration surfaces
2. **Workstream dependency graph** — track, query, and visualise how workstreams depend on each other across domains
3. **Suggesting Next Steps** — surface contextual next-action suggestions derived from hub state (post-decision unlocks, unblocked dependencies, high-priority open tasks)

## Design Boundary

The State Hub is a **read model** with exactly two bounded write operations:

| Use Case | Rationale |
|---|---|
| **Resolving Decisions** | Decisions are cross-cutting artefacts; their resolution must propagate to all parties watching a domain, not just the project file |
| **Suggesting Next Steps** | Bridge between hub overview and domain action; the hub surfaces what, where, and why — the domain owns the how |

All other write operations (`create_workstream`, `create_task`) are **bootstrapping utilities** (First Session Protocol), not general-purpose project management. Formal work structure — requirements, workplans, milestones — belongs in domain repos.

### What is out of scope

The **Custodian as acting agent** (LLM-powered autonomous reasoning and tool use) is a separate concern and a separate workstream (`custodian-agent-runtime`). It will:
- Be built on top of markitect's `llm-shared-library` (llm-connect), not on Claude Code
- Not live in the-custodian repo directly — the repo provides its State Hub environment, not its runtime
- Only begin after markitect/llm-shared-library reaches a stable installable state

---

## Stages

### S0 — Design Boundary Cleanup

Establish the "observation + 2 exceptions" principle in all integration surfaces before adding new write operations.

| # | Task | Priority |
|---|------|----------|
| S0.1 | Update TOOLS.md, project CLAUDE.md template, and global CLAUDE.md to reflect the observation model and two write use cases | medium |
| S0.2 | Mark `create_workstream` / `create_task` MCP tools and CLI commands as "bootstrap-only" with a note pointing to the domain as the authoritative source | medium |

---

### S1 — Workstream Dependency Graph

Add a directed dependency graph to the schema: workstream A *depends on* workstream B means B must reach a certain state before A can fully proceed.

**Schema addition:** `WorkstreamDependency(id, from_workstream_id, to_workstream_id, description, created_at)` — directed edge, FK-constrained, no soft-delete (hard delete is safe here as it removes a constraint, not information).

| # | Task | Priority |
|---|------|----------|
| S1.1 | DB model + Alembic migration for `WorkstreamDependency` | high |
| S1.2 | API: `POST /workstreams/{id}/dependencies/`, `GET /workstreams/{id}/dependencies/`, `DELETE /workstreams/{id}/dependencies/{dep_id}` | high |
| S1.3 | Enrich `/state/summary` → `open_workstreams[]` with `depends_on` and `blocks` lists | high |
| S1.4 | MCP tools: `create_dependency(from_ws_id, to_ws_id, description?)`, `list_dependencies(workstream_id?)` | medium |
| S1.5 | Dashboard workstreams page: show depends-on and blocks lists on each workstream card | medium |

---

### S2 — Suggesting Next Steps

Derive contextual next-action suggestions from resolved decisions, newly unblocked dependencies, and high-priority open tasks. Suggestions are read-only — they point to where work should happen, they don't create it.

**Suggestion schema (derived, not persisted):**
```json
{
  "type": "unblocked_task | resolved_decision | dependency_cleared",
  "domain": "markitect",
  "workstream_id": "...",
  "workstream_title": "LLM Adapter Layer",
  "message": "D1 resolved → S2.1 (create package scaffold) is now the highest-priority open task",
  "project_path": "/home/worsch/markitect_project",
  "task_id": "...",
  "task_title": "S2.1 — Resolve D1 and create package scaffold"
}
```

| # | Task | Priority |
|---|------|----------|
| S2.1 | API: `GET /state/next_steps` — derive suggestions from current hub state (recently resolved decisions → open tasks in same workstream; cleared dependencies → first open task in now-unblocked workstream) | high |
| S2.2 | Enrich `get_state_summary()` response with `next_steps` list | high |
| S2.3 | MCP tool: `get_next_steps()` — returns suggestions with domain, workstream, task, project_path, and a plain-language message | high |
| S2.4 | Dashboard overview: "What's next?" section — cards per suggestion with domain badge and link context | medium |

---

### S3 — Integration & Validation

| # | Task | Priority |
|---|------|----------|
| S3.1 | Seed known inter-domain dependencies: `custodian-agent-runtime` ← `markitect/llm-shared-library`; `railiance` as infrastructure dependency for all deployment-bound workstreams | medium |
| S3.2 | End-to-end test: resolve a decision → confirm next_steps surfaces correct task → confirm Claude in domain picks it up via `get_next_steps()` in session start | medium |
| S3.3 | Update all registered project CLAUDE.mds to include `get_next_steps()` call in session start protocol | low |

---

## Dependencies

- S1.1 blocks all of S1 and all of S2 (summary enrichment needs the dependency data)
- S0 has no blockers — can start immediately
- This workstream has no external dependencies (the State Hub is self-contained)
- The `custodian-agent-runtime` workstream depends on this workstream reaching S1 completion and on `markitect/llm-shared-library` reaching a stable installable state

## Known Decisions

None open at the time of writing.