generated from coulomb/repo-seed
tegwick
05cc29e50b
Implements the first live layer of the Custodian cognitive infrastructure: PostgreSQL schema, FastAPI REST API, FastMCP stdio server, and Observable Framework telemetry dashboard. - state-hub/: full stack (docker-compose, FastAPI, Alembic, MCP server, dashboard) - 5 DB tables: topics, workstreams, tasks, decisions, progress_events - 11 MCP tools + 5 resources registered in .mcp.json - Observable dashboard: Overview, Workstreams, Decisions, Progress pages - CLAUDE.md: session protocol (get_state_summary / add_progress_event ritual) - ~/.claude/CLAUDE.md: global cross-project reference to the hub - scripts/pull_image.py: WSL2 TLS-resilient Docker image downloader Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
146 lines
6.5 KiB
Markdown
146 lines
6.5 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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
|
|
make api # uvicorn on 127.0.0.1:8000 (docs at /docs)
|
|
make dashboard # Observable preview on :3000
|
|
make check # curl /state/health
|
|
|
|
# Shortcut: db + migrate + api
|
|
make start
|
|
```
|
|
|
|
The MCP server is registered in `.mcp.json` at the repo root. After `make install` creates `.venv`, restart Claude Code for `/mcp` to show `state-hub`.
|
|
|
|
### Docker Setup (WSL2, one-time)
|
|
|
|
```bash
|
|
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. 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()`
|
|
|
|
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
|