tegwick
ca8a09ed04
Makes the state hub an event publisher so activity-core can drive
maintenance automation declaratively via ActivityDefinitions, rather
than the hub creating tasks itself.
- api/events/: lazy JetStream publisher + EventEnvelope mirroring
activity-core's contract; no-op when NATS_URL unset, fire-and-forget
with logged failures so publishing never breaks an API request.
- Wired publishers on the five v1.0 lifecycle events:
org.statehub.repo.registered (POST /repos/)
org.statehub.workstream.completed (PATCH /workstreams/* on transition)
org.statehub.decision.resolved (POST /decisions/*/resolve)
org.statehub.domain.goal.activated (POST /domain-goals/*/activate)
org.statehub.task.stale (scripts/cleanup_stale_tasks.py)
- docs/nats-event-subjects.md: subject naming convention + catalog.
- docs/cron-migration.md: design stub for replacing custodian-sync
systemd timer and cleanup-stale cron with ActivityDefinitions
(depends on activity-core WP-0003).
- docs/activity-core-delegation.md: protocol, invariants, cutover plan.
- SCOPE.md: declares activity-core as downstream event consumer and
restates that the state hub stays a read model, not a task factory.
Workplan: workplans/CUST-WP-0040-state-hub-nats-activity-core-integration.md
242 tests pass.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
130 lines
5.1 KiB
Markdown
130 lines
5.1 KiB
Markdown
# 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, a live state-tracking API, and MCP integration for cross-domain agent sessions.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
The Custodian is both an **operational system** (State Hub: PostgreSQL + FastAPI + MCP server + Observable dashboard) and a **governance substrate** (canon: constitution, values, domain charters). It acts as episodic memory and coordination layer so that work across multiple repos remains visible, tracked, and aligned with long-term intent.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- Canon layer: governance constitution, foundational values, six domain charters/roadmaps
|
|
- State Hub API: topics, workstreams, tasks, decisions, progress events, contributions, SBOM, goals
|
|
- MCP server: exposes state-hub tools to Claude Code sessions hub-wide
|
|
- 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
|
|
- Maintenance task *creation* in response to lifecycle events — that responsibility lives in activity-core (see `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 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 + 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
|
|
|
|
---
|
|
|
|
## Related / Overlapping
|
|
|
|
- `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: `state-hub/` (live API + MCP), `canon/` (governance), `workplans/` (active work), `state-hub/mcp_server/TOOLS.md` (tool reference)
|
|
- Entry points: `cd state-hub && make api` (API); Claude Code with state-hub MCP registered
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
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]
|
|
```
|
|
|
|
```capability
|
|
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]
|
|
```
|
|
|
|
```capability
|
|
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 (`make fix-consistency REPO=the-custodian`) must be run after any workplan changes to keep the dashboard accurate.
|