--- domain: custodian repo: the-custodian updated: "2026-10-19" --- # 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()`) - 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: active coordination and source tooling. `CUST-WP-0071` retains representative pilot acceptance, allocation review and weekly execution; `CUST-WP-0073` is blocked only on the founder-triggered rotation (T05); Consult their task blocks for current gates. `CUST-WP-0079` (daily security flow on a workstation systemd timer, see `infra/security-flow/`), `CUST-WP-0076` and `CUST-WP-0080` are finished; later architecture and hardening work is tracked in `CUST-WP-0081` and `CUST-WP-0082`. Source preparation and owner integration can proceed independently of attended acceptance; a blocked acceptance gate does not imply absent implementation. - Interactive credential isolation (`CUST-WP-0073`; T02 and T04 done 2026-10-20). Codex, Claude Code and Grok Build run in the WSL2 distro `custodian-agents` as `custodian-agt`. They hold only short-lived credentials that the founder issues: a 24h ServiceAccount token (`custodian-agents/custodian-agent`, curated read) and a 12h `agt-custodian` SSH certificate (`permit-pty` only). Privileged actions go through gated-executor on railiance01 under exact founder approval. Evidence is under `docs/evidence/2026-10-20-*`. - Cross-domain work driven from here but owned elsewhere: forge closure (prj-forgejo-org-refactor `ORGREF-WP-0002`; decision record `decisions/forge-visibility-policy.md`) and the SecurityCaseType model (net-kingdom canon `security-case-types_v0.1`, `NK-WP-0048`, with ops-mason `MASON-WP-0010` and ops-warden `WARDEN-WP-0044`). - 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] ``` ```capability type: tool title: Deterministic security work reporting and checkpointed delivery description: scripts/security_flow_report.py classifies repo-backed tasks with dependency and human gates; scripts/security_flow_daily.py synchronizes recorded decisions and delivers changed actionable reports with recipient checkpoints. Dry-run by default; runs daily with --apply from the workstation user timer in infra/security-flow/ (CUST-WP-0079-T03). keywords: [security, workplans, dependencies, reports, checkpoints, scheduling] ``` ```capability type: tool title: Generated-only commit guard description: scripts/check_generated_only_commit.py checks staged changes or commit ranges; make generated-commit-hook preserves existing hook routing. Local enforcement and tests exist; the 2026-10-12 through 2026-10-19 local history audit found no generated-only commits across the 15-repo security estate. CUST-WP-0079-T05 records completed owner-generator adoption and local-history acceptance. keywords: [git, generated, hooks, work-records, validation] ``` ```capability type: tool title: Staged work-record index generation description: make generated-work-records reuses the State Hub renderer on staged Markdown, with explicit repository identity, and stages only WORK-RECORDS.md while refusing unstaged generated-file edits. make generated-work-records-check is read-only. Source adapter and tests are implemented; the shared/local hook supports explicit per-repo adoption, with provider adoption and exact commit receipts tracked in CUST-WP-0079. Owner-specific artifact automation and local-only briefs are recorded in CUST-WP-0079. See docs/staged-work-record-generation.md. keywords: [git, generated, work-records, staged-sources, validation] ``` ```capability type: tool title: Workload allocation reconciliation description: scripts/reconcile_railiance_allocation.py joins railiance-cluster observations with namespace ownership and State Hub release preflight. Supports retained observation input; distinguishes reservation headroom from demand. Representative pilot sizing and unattended weekly assessment remain unverified. keywords: [capacity, allocation, telemetry, ownership, sizing] ``` ```capability type: tool title: Agent supervision evidence summary description: scripts/summarize_agent_supervision.py reports acceptance and verified execution outcomes from an existing identified agent record. Descriptive only; grants no authority, runtime isolation or autopilot promotion. keywords: [agents, supervision, evidence, approvals] ``` ```capability type: tool title: Attended agent credential issuance and denial verification description: docs/changes/CUST-WP-0073/workstation-agents-r4/issue-agent-credentials.sh lets the founder issue an interactive agent a 24h curated-read ServiceAccount token and a 12h permit-pty-only agt-custodian SSH certificate. docs/changes/CUST-WP-0073/credential-boundary-r1/verify_agent_denials.py probes Kubernetes denials from the agent's own account, retries errors and reports granted and undetermined results separately. Attended use only; grants no authority. keywords: [agents, credentials, isolation, rbac, ssh-certificate, verification] ``` These local discovery descriptions are not publication grants. The federated `registry/indexes/capabilities.yaml` deliberately exposes only generic runtime and repository classification tooling. Confidential canon, memory, operational records and estate-specific execution configuration stay outside that boundary. ```capability type: tool title: Retained weekly allocation evidence report description: scripts/weekly_allocation_report.py joins existing cluster, allocation, telemetry and resource-control evidence into an immutable weekly report. It preserves missing measurements, namespace-only aggregates, comparable metric windows and stable recommendation identities. The disabled activity definition still requires accepted input collection, durable executor storage, delivery and recovery before unattended operation. keywords: [capacity, weekly, telemetry, retention, recommendations, resource-control] ``` --- ## 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 `statehub fix-consistency` to keep the dashboard accurate; inspect its generated changes and publication behavior. - `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`.