the-custodian/SCOPE.md

---
domain: custodian
repo: the-custodian
updated: "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

```capability
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]
```

```capability
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]
```

```capability
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`.