coulomb/state-hub
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: establish state hub baseline

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-17 18:54:57 +02:00
parent 6b71c8835e
commit 66df41c48c
5 changed files with 238 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
.gitignore vendored
View File

@@ -1,176 +1,41 @@
# ---> Python
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .python-version
# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock
# UV
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
#uv.lock
# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock
# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
# Local configuration and secrets
.env
.venv
.env.*
!.env.example
.claude/
# Python runtime and caches
.venv/
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
__pycache__/
**/__pycache__/
*.py[cod]
*.pyo
*.pyd
.pytest_cache/
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
# Ruff stuff:
.ruff_cache/
.coverage
.coverage.*
htmlcov/
# PyPI configuration file
.pypirc
# Build/package output
build/
dist/
*.egg-info/
# Dashboard dependencies and generated output
dashboard/node_modules/
dashboard/dist/
dashboard/src/.observablehq/
dashboard/.observablehq/
# Local tools and machine-specific binaries
kubectl
# OS/editor noise
.DS_Store
Thumbs.db
.idea/
.vscode/

72
AGENTS.md Normal file
View File

@@ -0,0 +1,72 @@
# AGENTS.md
This repository is the standalone home for the Custodian State Hub service.
## Session Start
1. Read this file and `SCOPE.md`.
2. Read `.custodian-brief.md` if present.
3. If the State Hub API is reachable, query the local hub for orientation:
- `GET http://127.0.0.1:8000/state/summary`
- `GET http://127.0.0.1:8000/messages/?to_agent=hub&unread_only=true`
4. Mark relevant inbox messages read after acting on them.
5. Check `git status --short` before editing.
If the API is not reachable, continue from local files. The repo must remain
usable offline.
## Repository Boundary
State Hub owns:
- FastAPI app, models, schemas, routers, migrations
- MCP server and tool reference
- Observable dashboard
- consistency, registration, SBOM, token, image, and repo-sync scripts
- task-flow engine and flow definitions
- State Hub operational docs, tests, policies, prompts, and infra
The Custodian governance repo owns:
- canon, constitution, values, memory, and broad cross-domain governance
- bridge workplans that coordinate extraction from the old embedded layout
Do not write governance canon directly from this repo.
## Build And Test
After the implementation move, the expected command surface is:
```bash
make install
make db
make migrate
make test
make api
make mcp-http
make dashboard
```
When API routers, models, migrations, or consistency logic change, run the
relevant tests before closing the session. Prefer `make test` when the database
test prerequisites are available.
## Workplans
Use `workplans/` for State Hub-local workplans. New workplans should use:
```text
SHUB-WP-0001
```
For migrated Custodian-hosted plans, preserve existing `state_hub_workstream_id`
and task IDs when safe. Never call `create_workstream()` or `create_task()`
manually for a file-backed workplan before the file exists in this repo.
## Session Close
1. Add a progress event through State Hub if the API is reachable.
2. Run consistency sync for this repo once it is registered.
3. Record any decisions that change repo ownership, state model, API contracts,
or deployment topology.
4. Leave the worktree clear or explicitly report remaining uncommitted changes.

62
README.md
View File

@@ -1,3 +1,61 @@
# repo-seed
# State Hub
A git repository template to bootstrap coulomb projects from.
State Hub is the live coordination service for the Custodian ecosystem:
PostgreSQL persistence, FastAPI API, FastMCP server, Observable dashboard,
consistency tooling, and repo/workplan synchronization.
This repository is the standalone home for the service. It replaces the former
embedded implementation at:
```text
/home/worsch/the-custodian/state-hub
```
## Current Extraction State
The repo is being prepared by `CUST-WP-0043 - State Hub Repo Extraction`.
During extraction:
- The live implementation still exists in `the-custodian/state-hub/`.
- This repo owns the standalone baseline and will become authoritative after
the implementation move and verification gate.
- State Hub implementation work should land here once registration and
workplan re-homing are complete.
## Stack
| Layer | Technology | Default endpoint |
|-------|------------|------------------|
| Database | PostgreSQL | `127.0.0.1:5432` |
| API | FastAPI + SQLAlchemy async | `127.0.0.1:8000` |
| MCP | FastMCP SSE | `127.0.0.1:8001/sse` |
| Dashboard | Observable Framework | `127.0.0.1:3000` |
| CLI | `custodian` Python entry point | local shell |
## Expected Commands After Implementation Move
```bash
cp .env.example .env
make install
make db
make migrate
make seed
make api
make mcp-http
make dashboard
make test
```
## Workplans
New State Hub-local workplans should use the prefix:
```text
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.

48
SCOPE.md Normal file
View File

@@ -0,0 +1,48 @@
# SCOPE
## One-Liner
State Hub is the local-first coordination service for Custodian workstreams,
tasks, decisions, progress events, repo metadata, MCP tooling, and dashboard
telemetry.
## In Scope
- State Hub FastAPI service
- PostgreSQL schema and Alembic migrations
- FastMCP server and tool reference
- Observable dashboard
- repo registration and consistency synchronization
- task-flow engine and flow definitions
- SBOM, contribution, capability, TPSC, DoI, token, and interface-change tracking
- State Hub tests, operational docs, policies, prompts, and local infra
## Out Of Scope
- Custodian canon and constitution content
- non-State-Hub domain implementation work
- external publication or legal/financial commitments
- plaintext secrets
- 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
This repo is being established as the standalone State Hub home under
`CUST-WP-0043`. Until the extraction verification gate passes, the prior live
implementation remains at:
```text
/home/worsch/the-custodian/state-hub
```
After verification, this repository becomes the authoritative implementation
tree and the embedded copy should be removed or replaced with a pointer.
## Workplan Convention
New State Hub-local workplans use `SHUB-WP-####`.
Migrated legacy State Hub workplans may temporarily retain `CUST-WP-####`
identifiers when preserving existing State Hub workstream and task IDs is the
least confusing path.

24
workplans/README.md Normal file
View File

@@ -0,0 +1,24 @@
# State Hub Workplans
New workplans in this repository use:
```text
SHUB-WP-0001-short-title.md
```
Workplan frontmatter should include:
```yaml
id: SHUB-WP-0001
type: workplan
title: "Short Title"
domain: custodian
repo: state-hub
status: active
owner: custodian
topic_slug: custodian
```
During extraction, legacy `CUST-WP-*` plans may be bridged or migrated with
their existing `state_hub_workstream_id` values. Write files first, then run
State Hub consistency sync after this repo is registered.