3.8 KiB
domain, repo, updated
| domain | repo | updated |
|---|---|---|
| custodian | state-hub | 2026-05-17 |
INTENT
This file explains why State Hub exists, where its authority begins and ends, and why it is now separate from the-custodian.
Why it exists
State Hub exists because the Custodian ecosystem needs a live, queryable, auditable memory of work: domains, repositories, workstreams, tasks, decisions, progress events, lifecycle state, and operational telemetry.
Files are excellent for canon, workplans, and provenance. They are less ergonomic as the live coordination surface for agents, dashboards, API clients, and cross-repo automation. State Hub gives those actors a local-first service that can answer "what is happening now?" without replacing the governance record that lives in the-custodian.
The governing principle
State Hub is the readable state and coordination service for the ecosystem.
It should answer:
- What exists? Domains, repos, workstreams, tasks, decisions, and tools.
- What changed? Progress events, lifecycle events, interface changes, and synchronization results.
- What needs attention? Blockers, human interventions, repo health, and dashboard-visible drift.
It should not become the canon, the task factory, the identity authority, or a general application platform. When State Hub detects facts, it records and exposes them; when new work must be spawned from events, that responsibility belongs to activity-core or a human-approved workflow.
What it is
State Hub is the local-first operational state service for Custodian.
It contains:
- PostgreSQL persistence and Alembic migrations
- FastAPI endpoints for topics, repos, workstreams, tasks, decisions, progress, capabilities, contributions, SBOM, TPSC, and related coordination records
- FastMCP tools for agent access
- Observable dashboard pages for human inspection
- consistency tooling that syncs repo-backed workplan files into live state
- task-flow evaluation and policies for lifecycle movement
- operational docs, tests, local infra, and prompts for running the service
What it is not
| Concern | Owner |
|---|---|
| Canon, values, constitution, and domain charters | the-custodian |
| Event-triggered maintenance task creation | activity-core |
| General task lifecycle backend outside Custodian workplans | issue-core |
| Repository capability profiling and SCOPE generation | repo-scoping |
| Network connectivity/tunnel management | ops-bridge |
| External publication, contracts, payments, or legal authority | Human approval only |
State Hub can reference these systems and expose their status, but it should not absorb their core responsibilities.
What it enables
When State Hub is doing its job, Bernd and agents can:
- start a session with current cross-domain state instead of stale local memory
- see active workstreams, tasks, blockers, decisions, and recent progress in one place
- sync workplan files into database-backed dashboard views without ghost workstreams
- access the same coordination state through REST, MCP, CLI, and dashboard
- keep operational state local, inspectable, and recoverable
Design values
Local-first operations. The service runs on local infrastructure and binds to loopback by default.
Files remain authoritative where they should. Repo-backed workplans are written as files first, then synchronized into the database.
Append-only progress. Progress events record what happened and are not silently rewritten.
Degrade gracefully. The dashboard and tools should make partial state visible rather than fail opaquely when one component is unavailable.
Narrow authority. State Hub coordinates and exposes state; it does not make irreversible human decisions or become the owner of every adjacent system.