state-hub/INTENT.md

---
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.

## Retirement status

State Hub is a legacy service in active retirement planning. It remains
operational during the migration, but it is not the target home for new
cross-domain capabilities.

The replacement program is coordinated in
`/home/worsch/prj-state-hub-retirement`, whose `GOAL.md` defines the migration
and retirement gates. Repository representation, file-backed record indexing,
consistency reconciliation, and governed repository changes are moving toward
`/home/worsch/repo-manager`. Cross-domain identity, communication, interaction,
state projections, telemetry, and domain-extension composition are moving
toward the consolidated `hub-core` framework.

Until the retirement gates are met, State Hub remains authoritative only where
the current contracts and repository-backed workflows require it. Changes made
during this period should preserve compatibility, enable extraction, reduce
scope, or address operational risk; they should not establish new permanent
architectural ownership here.

---

## 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.

**Sanctioned writes** (STATE-WP-0061): besides `resolve_decision` and progress
events, the hub may persist gated needs as `Suggestion` records, bump demand
`relevance`, vet/decline/promote them into real tasks, and project WSJF ranking
as a read model for daily triage.

---

## Ecosystem position

State Hub is the **dev coordination layer** in the three-repo hub stack:

| Repo | Role |
| --- | --- |
| `hub-core` | Shared library imported by State Hub |
| `state-hub` | This service — workplans, tasks, dev MCP |
| `core-hub` | Production framework at `hub.coulomb.social` |

Canon: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`

---

## 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.