the-custodian/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repository Is

The Custodian is a transgenerational cognitive infrastructure — a local-first, sovereignty-preserving agent system for co-creating and stewarding knowledge across six project domains. v0.1 is a governance and schema skeleton; state-hub/ is the first live implementation layer.

Repository Structure

canon/                    # Curated, reviewable knowledge substrate (identity lives here)
  constitution/           # Custodian governance rules (v0.1)
  values/                 # Foundational principles (9 values)
  projects/               # Six domain charters, concept seeds, roadmaps
    custodian/            # Master agent system (includes full_circle_map)
    railiance/            # DevOps & infrastructure reliability
    markitect/            # Knowledge artifact management
    coulomb.social/       # Co-creation marketplace experiment
    personhood/           # Rights/obligations framework
    foerster-capabilities/ # Agency capability taxonomy

memory/                   # Operational logs — append-only, never silently rewritten
  working/                # Session notes (scoped, time-bounded)
  episodic/               # Immutable event archive

state-hub/                # Live state service (PostgreSQL + FastAPI + MCP + dashboard)
  api/                    # FastAPI app (models, schemas, routers)
  mcp_server/             # FastMCP stdio server for Claude Code
  migrations/             # Alembic migrations
  dashboard/              # Observable Framework telemetry dashboard
  infra/                  # docker-compose.yml (postgres + optional pgadmin)
  scripts/                # seed.py — inserts 6 canonical topics

runtime/                  # Agent runtime scaffolding (policies, prompts, tool adapters)
infra/                    # Deployment, backups, encryption scaffolding
eval/                     # Policy and regression test placeholders

Each project under canon/projects/ follows a consistent three-file pattern:

• project_charter_v0.1.md — purpose, problem statement, scope, success criteria
• concepts_seed_v0.1.md — ten foundational concepts for the domain
• roadmap_v0.1.md — multi-phase implementation plan

Build / Test / Lint

State Hub (primary active service)

cd state-hub

# One-time setup
cp .env.example .env          # edit POSTGRES_PASSWORD
make install                  # uv sync → installs Python deps

# Docker (requires Docker Engine — see Docker Setup below)
make db                       # start postgres on 127.0.0.1:5432
make migrate                  # alembic upgrade head
make seed                     # insert 6 canonical topics

# Run services (each restarts the service if already running)
make api                      # db + migrate + uvicorn on 127.0.0.1:8000
make dashboard                # Observable preview on :3000
make check                    # curl /state/health

The MCP server runs as a persistent SSE service (make mcp-http, port 8001). Registered at user scope via claude mcp add-json -s user state-hub '{"type":"sse","url":"http://127.0.0.1:8001/sse"}'. Restart the MCP server independently — no Claude Code restart needed.

Docker Setup (WSL2, one-time)

sudo apt-get update && sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
sudo service docker start

Session Protocol (MANDATORY)

Every Claude Code session in this repository must follow this ritual:

On session start:

1. Call get_state_summary() via the state-hub MCP tool for orientation
2. Check the agent inbox: get_messages(to_agent="hub", unread_only=True) — mark read and act on any messages
3. Note any blocking decisions or blocked tasks before starting work

On session close (before ending):

1. Call add_progress_event() to log what was done, decided, or discovered
2. If new tasks were identified, create them with create_task()
3. If decisions were made, record them with record_decision()
4. If API routers or models were changed, run the test suite as a gate:

   cd state-hub && make test
   

   Requires postgres running (make db) and custodian_test database to exist. Create it once with: psql -U custodian -c "CREATE DATABASE custodian_test"
5. If any workplan files were written or modified this session, run:

   cd state-hub && make fix-consistency REPO=the-custodian
   

   This syncs task blocks → DB and updates task statuses. Without this step, the "Open Workstreams by Domain" chart will show 0 progress even for completed work.

Workplan ↔ DB sync rule (prevents ghost workstreams): When creating a new workstream backed by a workplan file, always write the file first, then run make fix-consistency — never call create_workstream() / create_task() manually for file-backed work. Calling the MCP bootstrap tools before the file exists creates a "ghost" workstream that the consistency checker cannot see (it has repo_id=null). The checker then creates a second workstream from the file, and the ghost stays active forever showing false partial progress.

Rule of thumb:

• Workplan file will be written → file first, then fix-consistency
• No workplan file (bootstrap / first-session only) → create_workstream() is fine

The state hub is the episodic memory of this system. A session that produces no progress events is invisible to future sessions and to Bernd.

Governance Constraints

These rules are defined in canon/constitution/custodian_constitution_v0.1.md and must be respected:

Allowed without explicit approval:

• Draft documents, plans, and structured artifacts
• Read/search canon and approved repositories
• Propose canon updates as PRs/patches (not direct writes)
• Run consistency checks and produce status reports
• Create working-memory notes and summarize sessions

Never permitted (v0.1 hard limits):

• Financial transactions, purchases, payments
• Legal commitments or external representations
• External publication under Bernd's identity
• Storing secrets or credentials in plaintext
• Writing directly to canon/ without a human-approved review gate

Must escalate to the human when:

• Actions affect money, legal status, security, or external reputation
• Instructions conflict with values or the constitution
• Uncertain about consent, especially for sensitive or family-scoped data

Canon Promotion Workflow

1. Custodian proposes a change (patch or PR)
2. Run gates: attribution, consistency, clarity, sensitivity, reversibility
3. Human approves and merges

All canon changes must carry provenance metadata. Episodic memory is append-only.

Document Conventions

• All artifacts use YAML frontmatter + Markdown
• Versioned filenames: artifact_name_v0.1.md
• Cross-project integration is tracked in canon/projects/custodian/full_circle_map_v0.1.md
• The dependency order is: Railiance → Markitect → Coulomb.social → Personhood/Foerster → Custodian

Key Design Principles

From canon/values/foundational_values_v0.1.md:

• Local-first, degrade-gracefully — no vendor lock-in; can operate offline
• Auditability and reversibility — explicit gates; proposals precede changes
• Safety by design — Custodian is co-creator, not authority; humans approve irreversible decisions
• Targeted information processing — narrow, high-leverage work rather than general intelligence
• Long timescale stewardship — designed for multi-year and eventual multi-generational continuity