coulomb/the-custodian
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refresh agent instruction files

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 16:55:54 +02:00
parent 5d478cf746
commit 9ff8887480
2 changed files with 133 additions and 340 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
AGENTS.md
View File

@@ -1,190 +1,162 @@
# AGENTS.md
# The Custodian — Agent Instructions
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
## Repo Identity
## What This Repository Is
**Purpose:** Transgenerational cognitive infrastructure and central coordination hub for all domains. Houses the state-hub (PostgreSQL + FastAPI + MCP + dashboard), governance canon, workplans, and agent session memory.
**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 and now lives in the standalone repo at `/home/worsch/state-hub`.
**Domain:** custodian
**Repo slug:** the-custodian
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `THE-WP-`
## 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
## State Hub Integration
memory/ # Operational logs — append-only, never silently rewritten
working/ # Session notes (scoped, time-bounded)
episodic/ # Immutable event archive
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
there is no MCP server for Codex agents.
state-hub/ # Pointer only; service source lives at /home/worsch/state-hub
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
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)
### Orient at session start
```bash
cd /home/worsch/state-hub
# Offline brief — works without hub connection
cat .custodian-brief.md
# One-time setup
cp .env.example .env # edit POSTGRES_PASSWORD
make install # uv sync → installs Python deps
# Active workstreams for this domain
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
| python3 -m json.tool
# 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
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=the-custodian&unread_only=true" \
| python3 -m json.tool
```
The MCP server runs as a persistent SSE service (`make mcp-http`, port 8001). Registered at user scope via `Codex mcp add-json -s user state-hub '{"type":"sse","url":"http://127.0.0.1:8001/sse"}'`. Restart the MCP server independently — no Codex restart needed.
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Docker Setup (WSL2, one-time)
### Log progress (required at session close)
```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
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workstream_id": "<uuid>",
"task_id": "<uuid>"
}'
```
## Session Protocol (MANDATORY)
Omit `workstream_id` / `task_id` when not applicable.
Every Codex session in this repository must follow this ritual:
### Update task status
**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
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "in_progress"}'
# values: todo | in_progress | done | blocked
```
**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:
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
2. Check inbox: `GET /messages/?to_agent=the-custodian&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check blocked tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses to reflect progress
2. Log: `POST /progress/` with a summary of what changed
3. Note for the custodian operator: after workplan file changes, run from
`~/state-hub`:
```bash
cd /home/worsch/state-hub && make test
make fix-consistency REPO=the-custodian
```
Requires postgres running (`make db`) and `custodian_test` database to exist.
Create it once with: `psql -U custodian -c "CREATE DATABASE custodian_test"`
Lifecycle movement is now flow-aware: use `get_flow_state()` to inspect
reachable workstations and `advance_workstation()` to move workstreams,
tasks, contributions, or capability requests when the target workstation's
requisite assertions are satisfied. Direct status updates remain available
for bootstrap, compatibility, and file-backed consistency syncs.
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:
```bash
git -C <repo_path> pull --ff-only
cd /home/worsch/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.
This syncs task status from files into the hub DB.
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:
```bash
cd /home/worsch/state-hub && make fix-consistency-remote REPO=<slug>
```
## Workplan Convention (ADR-001)
**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:
```bash
cd /home/worsch/state-hub && make fix-consistency-here REPO_PATH=/path/to/repo
```
This also auto-registers `host_paths[hostname]` so subsequent runs need no override.
Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files.
**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.
**File location:** `workplans/THE-WP-NNNN-<slug>.md`
Rule of thumb:
- **Workplan file will be written → file first, then `fix-consistency`**
- **No workplan file (bootstrap / first-session only) → `create_workstream()` is fine**
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-THE-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
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.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
this only for low-risk work completed directly; create a normal workplan for
anything needing analysis, design, approval, dependencies, or multiple phases.
## Governance Constraints
**Frontmatter:**
These rules are defined in `canon/constitution/custodian_constitution_v0.1.md` and must be respected:
```yaml
---
id: THE-WP-NNNN
type: workplan
title: "..."
domain: custodian
repo: the-custodian
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit
---
```
**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
Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**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
**Task block format** (one per `##` section):
**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
```
## Task Title
## Canon Promotion Workflow
` ` `task
id: THE-WP-NNNN-T01
status: todo | in_progress | done | blocked
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
1. Custodian proposes a change (patch or PR)
2. Run gates: attribution, consistency, clarity, sensitivity, reversibility
3. Human approves and merges
Task description text.
```
All canon changes must carry provenance metadata. Episodic memory is append-only.
Status progression: `todo` → `in_progress` → `done` (or `blocked`)
## 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
To create a new workplan:
1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=the-custodian`
(or send a message to the hub agent via `POST /messages/`)

199
CLAUDE.md
View File

@@ -1,190 +1,11 @@
# CLAUDE.md
# The Custodian — Claude Code Instructions
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 and now lives in the standalone repo at `/home/worsch/state-hub`.
## 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/ # Pointer only; service source lives at /home/worsch/state-hub
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 /home/worsch/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)
```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. 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:
```bash
cd /home/worsch/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"`
Lifecycle movement is now flow-aware: use `get_flow_state()` to inspect
reachable workstations and `advance_workstation()` to move workstreams,
tasks, contributions, or capability requests when the target workstation's
requisite assertions are satisfied. Direct status updates remain available
for bootstrap, compatibility, and file-backed consistency syncs.
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:
```bash
git -C <repo_path> pull --ff-only
cd /home/worsch/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:
```bash
cd /home/worsch/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:
```bash
cd /home/worsch/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
@SCOPE.md
@.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md
@.claude/rules/first-session.md
@.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
@.claude/rules/agents.md