989806a1c7
CUST-WP-0064 through CUST-WP-0068 are finished; C-30 flagged the previous active-workplan sentence as stale.
206 lines
8.9 KiB
Markdown
206 lines
8.9 KiB
Markdown
---
|
|
domain: custodian
|
|
repo: the-custodian
|
|
updated: "2026-08-23"
|
|
---
|
|
|
|
# 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, no open workplans.** `CUST-WP-0064` through
|
|
`CUST-WP-0068` are finished. The active registry is 120 classified
|
|
repositories; `make classification-check` is the convergence gate. Residual
|
|
`CUST-IN-0015` tracks a later SBOM catch-up `no-checkout` regression.
|
|
- Business platform enablement (`CUST-WP-0058`, finished 2026-07-10):
|
|
DR-1/2/3 resolved (instance-per-client tenancy; coulomb.social as
|
|
standalone app; app-local identity), business-app service contract
|
|
accepted (`canon/standards/business-app-service-contract_v0.1.md`),
|
|
client-hub scoped, delivery lane validated (vergabe-teilnahme conformance
|
|
snapshot). Open cross-repo handoffs: cnpg backups (railiance-apps,
|
|
**HIGH**), tenant keying + runbook (vergabe-teilnahme), FIN-WP-0002
|
|
(fin-hub), CLNT-WP-0001 (core-hub), coulomb.social rebuild seed
|
|
(`docs/coulomb-social-rebuild-seed.md`).
|
|
- Recent closeouts (archived 2026-07-08): `CUST-WP-0025` FOS hub bootstrap
|
|
(identity, hub-core extraction, Core Hub ops lane, fin-hub MVP);
|
|
`CUST-WP-0054` workstation independence; `CUST-WP-0051` infrastructure
|
|
metaplan. Ecosystem Haskell retirement (`CORE-WP-0007`) closed the last
|
|
Inter-Hub rollback gate — production `hub.coulomb.social` is Core Hub only.
|
|
- Implementation: substantial. Canon + memory + ADR-001 workplan conventions
|
|
established; State Hub primary on railiance01 (`state-hub` repo); service
|
|
inventory and cutover coupling docs current under `docs/` and `ops/`.
|
|
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 via State Hub MCP/REST; new implementation
|
|
work lands in domain repos (`core-hub`, `state-hub`, `fin-hub`, etc.), not here.
|
|
- Domains coordinated: dynamic — query `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, workplan, 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`.
|