SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

Central cognitive infrastructure and coordination hub for seven project domains — provides governance canon and coordinates through the standalone State Hub API/MCP service.

Core Idea

The Custodian repository is the governance substrate: canon, constitution, values, domain charters, workplans, and runtime scaffolding. The operational State Hub service (PostgreSQL + FastAPI + MCP server + Observable dashboard) now lives in the standalone /home/worsch/state-hub repository and acts as episodic memory and coordination layer for work across repos.

In Scope

Canon layer: governance constitution, foundational values, six domain charters/roadmaps
Coordination through the standalone State Hub API: topics, workstreams, tasks, decisions, progress events, contributions, SBOM, goals
MCP session protocol: use the State Hub MCP tools from registered agent sessions
Memory: append-only episodic archive (working notes + immutable event logs)
Agent runtime scaffolding: policies, kaizen agent copies, tool adapters
Cross-domain coordination: dependency tracking, human-intervention flags, next-steps suggestions
Publishing lifecycle events on NATS JetStream (org.statehub.>) so activity-core can react via declarative ActivityDefinitions

Out of Scope

Domain-specific implementation work (Railiance, Markitect, etc. each own their repos)
Financial/legal transactions or external publication
Storing plaintext credentials
Direct writes to canon/ without a human-approved review gate
State Hub implementation work; use /home/worsch/state-hub
Maintenance task creation in response to lifecycle events — that responsibility lives in activity-core (see /home/worsch/state-hub/docs/activity-core-delegation.md). The state hub remains a read model, not a task factory.

Relevant When

Starting or closing any session in a registered domain repo (orientation via get_domain_summary())
Tracking cross-domain decisions, blockers, or workplan progress
Registering a new project into the ecosystem (make register-project)
Consulting governance rules or domain charters
Running the standalone State Hub API locally for MCP connectivity

Not Relevant When

Implementing single-domain features (stay in the domain repo)
Working fully offline with no need for state coordination
Non-custodian ecosystem work (standalone projects, throw-away scripts)

Current State

Status: active
Implementation: ~60% — canon + standalone State Hub operational; RAG/drafting pipelines (Phase 2) not yet started
Stability: stable (versioned Alembic migrations; no breaking API changes since v0.3)
Usage: running daily; 15+ active workstreams across 6 domains; MCP server active in Claude Code

How It Fits

Upstream dependencies: none (sits at the top of the dependency order)
Downstream consumers: all six domains (railiance → markitect → coulomb.social → personhood/foerster → custodian); activity-core consumes state hub lifecycle events on NATS subject org.statehub.> to drive maintenance ActivityDefinitions
Often used with: kaizen-agentic (agent definitions), ops-bridge (remote tunnel connectivity), activity-core (task factory + event bridge)

Terminology

Preferred terms: canon, workstream, topic, progress event, domain
Also known as: "the hub", "state hub"
Potentially confusing terms: "topic" = domain-level grouping (not a chat topic); "decision" = tracked choice point with escalation rules

kaizen-agentic — specialized agent personas callable via MCP from any domain session
ops-bridge — SSH tunnel manager keeping remote agents connected to this hub
activity-core — event-driven task factory tracked as a custodian-domain workstream

Getting Oriented

Start with: CLAUDE.md (session protocol) + README.md (architecture overview)
Key files / directories: canon/ (governance), workplans/ (active Custodian work), state-hub/ (pointer), /home/worsch/state-hub/mcp_server/TOOLS.md (tool reference)
Entry points: cd /home/worsch/state-hub && make api (API); Codex/Claude Code with state-hub MCP registered

Provided Capabilities

type: api
title: MCP tool registration
description: Register and expose new MCP tools to all Claude Code sessions via the state-hub server.
keywords: [mcp, tool, api, registration, server]

type: data
title: Cross-domain state tracking
description: Track workstreams, tasks, decisions, and progress events across all seven project domains.
keywords: [state, tracking, workstream, task, decision, progress]

type: api
title: SBOM and licence reporting
description: Ingest lockfiles from any repo and provide aggregated SBOM and copyleft licence risk reports.
keywords: [sbom, licence, license, dependency, lockfile, copyleft]

Notes

Dependency order for domain sequencing: Railiance → Markitect → Coulomb.social → Personhood/Foerster → Custodian. The consistency checker (cd /home/worsch/state-hub && make fix-consistency REPO=the-custodian) must be run after any workplan changes to keep the dashboard accurate.

5.3 KiB Raw Blame History