Files

tegwick f85c5e4d49 feat(capability-requests): add cross-domain capability catalog and request routing

Introduces a capability catalog (CUST-WP-0022) so domains can advertise what
they provide and agents can request capabilities from other domains with
auto-routing, lifecycle tracking, and task-unblocking on completion.

- New models: CapabilityCatalog, CapabilityRequest with full lifecycle
  (requested → accepted → in_progress → ready_for_review → completed/rejected/withdrawn)
- Migration i6d7e8f9a0b1: capability_catalog + capability_requests tables
- Router /capability-catalog and /capability-requests with accept/status endpoints
- 7 new MCP tools: register_capability, list_capabilities, request_capability,
  accept_capability_request, update_capability_request_status,
  list_capability_requests, get_capability_request
- StateSummary gains open_capability_requests count
- Dashboard: capability-requests.md page + docs/capabilities.md + docs/scope.md
- SCOPE.md: three seed capabilities documented (MCP registration, state tracking, SBOM)
- scope.template: Provided Capabilities section with example block
- scripts/ingest_capabilities.py + make ingest-capabilities[/-all] targets

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

2026-03-19 21:07:50 +01:00

4.6 KiB

Raw Blame History

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 six 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

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

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)
Often used with: kaizen-agentic (agent definitions), ops-bridge (remote tunnel connectivity), activity-core (task factory)

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: 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

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 six 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 (make fix-consistency REPO=the-custodian) must be run after any workplan changes to keep the dashboard accurate.

4.6 KiB Raw Blame History