From 9ff8887480fbd28761b9265c1198298fd3f58724 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 18 May 2026 16:55:54 +0200 Subject: [PATCH] Refresh agent instruction files --- AGENTS.md | 274 ++++++++++++++++++++++++------------------------------ CLAUDE.md | 199 ++------------------------------------- 2 files changed, 133 insertions(+), 340 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1092007..2a3fa67 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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//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": "", + "task_id": "" + }' ``` -## 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/" \ + -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/" \ + -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 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= - ``` +## 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-.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-.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: "" # 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: "" # 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/`) diff --git a/CLAUDE.md b/CLAUDE.md index 2f12e03..1e568e8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 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= - ``` - - **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