generated from coulomb/repo-seed
111 lines
3.8 KiB
Markdown
111 lines
3.8 KiB
Markdown
---
|
|
domain: custodian
|
|
repo: state-hub
|
|
updated: "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:
|
|
|
|
1. **What exists?** Domains, repos, workstreams, tasks, decisions, and tools.
|
|
2. **What changed?** Progress events, lifecycle events, interface changes, and
|
|
synchronization results.
|
|
3. **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.
|
|
|