generated from coulomb/repo-seed
docs: clarify state hub intent
This commit is contained in:
110
INTENT.md
Normal file
110
INTENT.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
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.
|
||||
|
||||
19
README.md
19
README.md
@@ -11,16 +11,17 @@ the former embedded implementation at:
|
||||
/home/worsch/the-custodian/state-hub
|
||||
```
|
||||
|
||||
## Current Extraction State
|
||||
## Extraction State
|
||||
|
||||
The repo is being prepared by `CUST-WP-0043 - State Hub Repo Extraction`.
|
||||
The extraction workplan `CUST-WP-0043 - State Hub Repo Extraction` is complete.
|
||||
|
||||
During the extraction window:
|
||||
Current state:
|
||||
|
||||
- The implementation has been imported here with subtree history.
|
||||
- `CUST-WP-0042` has been re-homed into this repository.
|
||||
- The old embedded tree in `the-custodian` should remain only as a pointer once
|
||||
the verification gate passes.
|
||||
- The old embedded tree in `the-custodian` remains only as a pointer.
|
||||
- This repository is authoritative for State Hub code, docs, tests, dashboard,
|
||||
migrations, scripts, policies, and State Hub-local workplans.
|
||||
|
||||
## Workplans
|
||||
|
||||
@@ -30,10 +31,10 @@ New State Hub-local workplans should use the prefix:
|
||||
SHUB-WP-0001
|
||||
```
|
||||
|
||||
Legacy Custodian-hosted State Hub plans, such as `CUST-WP-0042`, may be carried
|
||||
over with their existing State Hub IDs or bridged by a new `SHUB-WP-*`
|
||||
continuation plan. Do not create duplicate workstreams manually; write the
|
||||
workplan file first, then run consistency sync after this repo is registered.
|
||||
Legacy Custodian-hosted State Hub plans, such as `CUST-WP-0042`, may retain
|
||||
their existing IDs when that preserves State Hub workstream/task continuity.
|
||||
Do not create duplicate workstreams manually; write the workplan file first,
|
||||
then run consistency sync.
|
||||
|
||||
---
|
||||
|
||||
|
||||
10
SCOPE.md
10
SCOPE.md
@@ -26,17 +26,17 @@ telemetry.
|
||||
- generic hub-core extraction unless a dedicated workplan owns it
|
||||
- renaming State Hub to Dev Hub unless a dedicated workplan owns it
|
||||
|
||||
## Current Extraction Note
|
||||
## Extraction Note
|
||||
|
||||
This repo is being established as the standalone State Hub home under
|
||||
`CUST-WP-0043`. The implementation has been imported here from:
|
||||
This repo is the standalone State Hub home. It was extracted under
|
||||
`CUST-WP-0043` from:
|
||||
|
||||
```text
|
||||
/home/worsch/the-custodian/state-hub
|
||||
```
|
||||
|
||||
After verification, this repository is authoritative and the embedded copy in
|
||||
`the-custodian` should be removed or replaced with a pointer.
|
||||
This repository is authoritative for State Hub implementation work. The
|
||||
embedded path in `the-custodian` is now a pointer only.
|
||||
|
||||
## Workplan Convention
|
||||
|
||||
|
||||
Reference in New Issue
Block a user