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 seven 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. Read .custodian-brief.md if it exists — offline-safe orientation that works without MCP
2. Call get_state_summary() via the state-hub MCP tool for richer cross-domain context (if the MCP call fails, the brief is sufficient to begin work)
3. Check the agent inbox: get_messages(to_agent="hub", unread_only=True) — mark read and act on any messages
4. 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, first ensure the local copy is up to date, then run the consistency sync:

   git -C <repo_path> pull --ff-only
   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.

   The checker now enforces two safety rules for multi-machine workflows:

   • C-15 (no-regress): if the DB task status is already ahead of the file (e.g. marked done on CoulombCore), the file is written back to match DB rather than regressing the DB to the stale file value.
   • C-16 (pull gate): if the local repo is behind its remote tracking branch, --fix is skipped entirely. A C-15 warning is normal when CoulombCore has progressed tasks — it means writeback is keeping files in sync.

   For repos where work runs on a remote machine, prefer the combined target:

   cd state-hub && make fix-consistency-remote REPO=<slug>
   

   On a machine where the checkout path differs from what's in the DB, use --here to auto-detect the slug from the git root-commit fingerprint:

   cd state-hub && make fix-consistency-here REPO_PATH=/path/to/repo
   

   This also auto-registers host_paths[hostname] so subsequent runs need no override.

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