From 80ff5e61283bc6d26bbd62c3e1c12ca5f101c812 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 17 May 2026 21:37:02 +0200 Subject: [PATCH] docs: clarify state hub intent --- INTENT.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 19 +++++----- SCOPE.md | 10 ++--- 3 files changed, 125 insertions(+), 14 deletions(-) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..483d1ac --- /dev/null +++ b/INTENT.md @@ -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. + diff --git a/README.md b/README.md index 32b8221..4672023 100644 --- a/README.md +++ b/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. --- diff --git a/SCOPE.md b/SCOPE.md index c3e63ae..3540ccf 100644 --- a/SCOPE.md +++ b/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