generated from coulomb/repo-seed
docs: establish state hub baseline
This commit is contained in:
203
.gitignore
vendored
203
.gitignore
vendored
@@ -1,176 +1,41 @@
|
|||||||
# ---> Python
|
# Local configuration and secrets
|
||||||
# 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
|
|
||||||
.env
|
.env
|
||||||
.venv
|
.env.*
|
||||||
|
!.env.example
|
||||||
|
.claude/
|
||||||
|
|
||||||
|
# Python runtime and caches
|
||||||
|
.venv/
|
||||||
env/
|
env/
|
||||||
venv/
|
venv/
|
||||||
ENV/
|
__pycache__/
|
||||||
env.bak/
|
**/__pycache__/
|
||||||
venv.bak/
|
*.py[cod]
|
||||||
|
*.pyo
|
||||||
# Spyder project settings
|
*.pyd
|
||||||
.spyderproject
|
.pytest_cache/
|
||||||
.spyproject
|
|
||||||
|
|
||||||
# Rope project settings
|
|
||||||
.ropeproject
|
|
||||||
|
|
||||||
# mkdocs documentation
|
|
||||||
/site
|
|
||||||
|
|
||||||
# mypy
|
|
||||||
.mypy_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/
|
.ruff_cache/
|
||||||
|
.coverage
|
||||||
|
.coverage.*
|
||||||
|
htmlcov/
|
||||||
|
|
||||||
# PyPI configuration file
|
# Build/package output
|
||||||
.pypirc
|
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
72
AGENTS.md
Normal 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
62
README.md
@@ -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
48
SCOPE.md
Normal 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
24
workplans/README.md
Normal 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.
|
||||||
Reference in New Issue
Block a user