the-custodian/SCOPE.md

domain, repo, updated

domain	repo	updated
custodian	the-custodian	2026-07-08

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

Governance and continuity substrate for a local-first, multi-domain agent ecosystem — owns canon, memory, workplans, and agent runtime scaffolding; coordinates through the standalone State Hub service rather than hosting it.

---

Core Idea

The Custodian holds the long-lived meaning, boundaries, and continuity of the ecosystem: constitution, values, standards, domain charters, roadmaps, episodic memory, and repo-backed workplans. It is the stewardship layer that keeps the system coherent across tool changes, repo splits, and agent sessions.

It deliberately keeps a small operational surface. Operational subsystems — most notably the State Hub (PostgreSQL + FastAPI + MCP + dashboard) — live in their own repositories and are referenced here only as integration pointers. the-custodian/state-hub/ is now a pointer; the service source is at /home/worsch/state-hub.

---

In Scope

• Canon: constitution, foundational values, standards, domain charters, concept seeds, roadmaps (canon/) — human-gated, proposal-then-review writes only
• Memory: append-only working notes and immutable episodic event logs (memory/)
• Workplans: repo-backed CUST-WP-NNNN plans for Custodian-owned coordination work, per ADR-001 (file originates work, then the hub indexes it) (workplans/)
• Agent runtime scaffolding: policies, prompts, tool adapters, kaizen agent copies (runtime/, agents/)
• Session protocol: how agents orient, coordinate, and hand off via the State Hub MCP/REST surface (.claude/rules/, .custodian-brief.md)
• Cross-domain governance: tracking decisions, provenance, and human-intervention gates; surfacing next steps from the read model
• Integration pointers and docs for adjacent services (hub-core extraction, ops-hub catalog, activity-core delegation) (docs/, state-hub/README.md)

---

Out of Scope

• Live State Hub implementation — migrations, dashboard, tests, API/MCP source. Owned by /home/worsch/state-hub.
• Event-triggered maintenance task creation — owned by activity-core. The hub is a read model, not a task factory.
• General task lifecycle backend — owned by issue-core.
• Repository capability profiling — owned by repo-scoping.
• Domain-specific products and experiments — each domain owns its own repo.
• External publication, contracts, payments, legal authority — human approval only; never automated here.
• Storing plaintext credentials, or direct writes to canon/ without a review gate.

---

Relevant When

• Starting or closing a session in any registered domain repo (orientation via get_domain_summary(<slug>))
• Consulting governance rules, the constitution, values, or a domain charter
• Tracking cross-domain decisions, blockers, provenance, or workplan progress
• Registering a new project into the ecosystem (custodian register-project)
• Preserving durable, reviewable memory of why something was decided

---

Not Relevant When

• Implementing a single-domain feature — stay in that domain's repo
• Hacking on State Hub internals — go to /home/worsch/state-hub
• Throwaway scripts or non-ecosystem standalone work

---

Current State

• Status: stable maintenance — governance substrate in daily ecosystem use; no open CUST-WP workplans in this repo (queue complete as of 2026-07-08)
• Implementation: substantial. Canon + memory + workplan conventions established; State Hub operational on railiance01 (see state-hub repo); workstation independence and fleet realignment finished (CUST-WP-0054 archived); RAG-over-canon and drafting pipelines (roadmap Phase 1) not yet started
• Stability: stable — canon changes are review-gated; memory is append-only
• Usage: daily, across the ecosystem; State Hub MCP in agent sessions; new implementation work typically lands in domain repos or state-hub, not here
• Domains coordinated: dynamic — query the live list with list_domains() rather than trusting a hard-coded count

---

How It Fits

• Upstream dependencies: none — sits at the top of the dependency order
• Downstream consumers: all tracked domains rely on its canon, session protocol, and coordination conventions
• Often used with:
  • state-hub — the operational read model / coordination service it points to
  • activity-core — event-driven task factory consuming hub lifecycle events
  • issue-core — task lifecycle backend
  • repo-scoping — repository capability profiling
  • kaizen-agentic — specialized agent personas callable via MCP
  • ops-bridge — SSH tunnel manager for remote agent connectivity

---

Terminology

• Preferred terms: canon, workstream, workplan, topic, progress event, domain
• Also known as: "the hub" (loosely) — but the service is the State Hub repo; this repo is the governance substrate
• Potentially confusing terms:
  • "topic" = domain-level grouping, not a chat topic
  • "decision" = tracked choice point with escalation rules
  • "State Hub" = the standalone service repo, not this directory tree

---

Related / Overlapping Repositories

• state-hub — operational service (DB/API/MCP/dashboard); the most common confusion point. This repo coordinates through it but does not own it.
• activity-core — overlaps on "what work should happen next"; owns the creation of maintenance tasks (custodian only describes/coordinates).
• issue-core — task lifecycle backend; do not reimplement task storage here.
• repo-scoping — capability profiling; do not reimplement here.
• kaizen-agentic — source of agent personas mirrored under agents/.

---

Getting Oriented

• Start with: INTENT.md (why this repo exists + boundary table), then CLAUDE.md → .claude/rules/ (session protocol), then README.md
• Key files / directories: canon/ (governance), memory/ (continuity), workplans/ (CUST-WP plans), runtime/, state-hub/README.md (pointer)
• Entry points: cat .custodian-brief.md (offline-safe orientation); get_domain_summary("custodian") (MCP); State Hub service at /home/worsch/state-hub (make api)

---

Provided Capabilities

type: reference
title: Governance canon
description: Constitution, foundational values, standards, and per-domain charters/roadmaps that define what matters and what is permitted across the ecosystem.
keywords: [canon, governance, constitution, values, charter, standards]

type: process
title: Session protocol and cross-domain orientation
description: Conventions for how agents orient, coordinate, and hand off via the State Hub, including ADR-001 workplan origination and human-gated review.
keywords: [session, orientation, protocol, workplan, adr-001, coordination]

type: data
title: Append-only memory and provenance
description: Durable, reviewable working notes and immutable episodic logs preserving decisions and session continuity over long timescales.
keywords: [memory, provenance, episodic, continuity, decisions]

---

Notes

• This repo intentionally avoids reabsorbing runtime code. If a subsystem grows a runtime, tests, and a deployment surface, it should move to its own repo and report back through the State Hub and workplans (see INTENT.md → design values).
• After any workplan change, run cd /home/worsch/state-hub && make fix-consistency REPO=the-custodian to keep the dashboard accurate.
• README.md still references "seven project domains" / "six domain charters" — stale relative to the live 14-domain list; treat list_domains() as authoritative.
• Prior SCOPE.md (stale, conflated this repo with the State Hub service) is archived at history/20260621-SCOPE.md.