From 66df41c48c9c5b2ae3d1a8cbbb3d38c7c4855728 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 17 May 2026 18:54:57 +0200 Subject: [PATCH] docs: establish state hub baseline --- .gitignore | 203 ++++++++------------------------------------ AGENTS.md | 72 ++++++++++++++++ README.md | 62 +++++++++++++- SCOPE.md | 48 +++++++++++ workplans/README.md | 24 ++++++ 5 files changed, 238 insertions(+), 171 deletions(-) create mode 100644 AGENTS.md create mode 100644 SCOPE.md create mode 100644 workplans/README.md diff --git a/.gitignore b/.gitignore index 36b13f1..d51c04a 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f347172 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md index fcd7b8f..baffdbb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,61 @@ -# repo-seed +# State Hub -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +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. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..8f0a566 --- /dev/null +++ b/SCOPE.md @@ -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. diff --git a/workplans/README.md b/workplans/README.md new file mode 100644 index 0000000..f43a33c --- /dev/null +++ b/workplans/README.md @@ -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.