coulomb/the-custodian
5
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
the-custodian/SCOPE.md

13 KiB
Raw Blame History

domain repo updated
custodian the-custodian 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(<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: active coordination and source tooling. CUST-WP-0071 retains representative pilot acceptance, allocation review and weekly execution; CUST-WP-0073 retains actual interactive credential isolation and its documentation; CUST-WP-0079 retains schedule activation, policy publication, fleet history acceptance and attended actions. Consult their task blocks for current gates. 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.
  • 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

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]

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; durable schedule acceptance remains CUST-WP-0079-T03.
keywords: [security, workplans, dependencies, reports, checkpoints, scheduling]

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. Fleet generator adoption remains a CUST-WP-0079-T05 acceptance obligation.
keywords: [git, generated, hooks, work-records, validation]

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. Other artifact families still need owner automation. See docs/staged-work-record-generation.md.
keywords: [git, generated, work-records, staged-sources, validation]

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]

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]

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.

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.