tegwick
e410d44959
Root cause of the 501-commit pile-up in inter-hub: fix_repo() created
git commits (brief updates, T03 writebacks) but never pushed them, so
the 15-minute timer accumulated local commits indefinitely. Once real
development landed on remote the repos diverged with no self-healing path.
Changes
-------
repo_sync.py (new module)
Extracts all git lifecycle primitives: pull_ff, push_ff,
count_remote_ahead (C-16 input), count_local_ahead (C-17/T04 input).
Module docstring documents the push-seal invariant and stable state.
consistency_check.py
- Imports primitives from repo_sync; thin _detect_behind_remote wrapper
preserves backward compat for existing callers and tests.
- C-17 backlog guard: if local has unpushed commits from a prior failed
push, retry before making more; skip all writes if push still fails.
- T04 push seal: unconditional push_ff() at end of every fix_repo() run.
- _report_needs_action: ahead_of_remote param so repos with unpushed
backlogs are not silently skipped as "clean" by fix_all_remote().
- Domain-slug fallback: brief no longer degrades to "(unknown)" when all
workplans are completed — falls back to any workstream for domain context.
- Service switched from --all --fix to --remote --all (pulls before
fixing, skips already-clean repos).
push-seal.md (new)
Capability documentation: the problem, the invariant, all three checks
(C-16/C-17/T04), stable-state description, API reference, and test map.
test_repo_sync.py (new, 32 tests)
Full coverage of all four primitives via real git repos (tmp_path).
Includes C-17 scenario, push-seal invariant, and four end-to-end
loop-stability tests.
test_consistency_check.py
Four new _report_needs_action cases for the ahead_of_remote parameter.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Confidential and Proprietary. Authorized Use Only. Subject to NDA & Contractual Penalty.
The Custodian
Transgenerational Cognitive Infrastructure — a local-first, sovereignty-preserving agent system for co-creating and stewarding knowledge across seven project domains.
The Custodian acts as co-creator and steward, not authority. Humans approve all irreversible decisions. The system is designed to still be coherent decades from now.
Architecture
the-custodian/
├── canon/ # Curated, reviewable knowledge substrate
│ ├── constitution/ # Governance rules (v0.1)
│ ├── values/ # Nine foundational principles
│ └── projects/ # Six domain charters, concept seeds, roadmaps
├── memory/ # Operational logs — append-only, never rewritten
│ ├── working/ # Session notes (scoped, time-bounded)
│ └── episodic/ # Immutable event archive
├── state-hub/ # Live state service (the operational brain)
│ ├── api/ # FastAPI (PostgreSQL-backed REST + /state/summary)
│ ├── mcp_server/ # FastMCP stdio — Claude Code's native interface
│ ├── migrations/ # Alembic schema migrations
│ ├── dashboard/ # Observable Framework telemetry dashboard
│ ├── infra/ # docker-compose.yml (postgres + optional pgadmin)
│ └── scripts/ # seed.py, register_project.sh, custodian CLI
├── runtime/ # Agent runtime scaffolding (policies, prompts, adapters)
├── infra/ # Deployment, backups, encryption scaffolding
└── eval/ # Policy and regression test placeholders
The dependency chain across domains runs bottom-up:
Railiance → Markitect → Coulomb.social → Personhood / Foerster → Custodian
(ops) (canon) (interaction) (rights/agency) (integration)
Project Domains
| Domain | Purpose | Topic ID |
|---|---|---|
| Custodian | Master agent system; integrates all layers | cee7bedf-2b48-46ef-8601-006474f2ad7a |
| Railiance | Sovereign DevOps and operational reliability | ca369340-a64e-442e-98f1-a4fa7dc74a38 |
| Markitect | Knowledge artifact management: authoring, versioning, retrieval | 5571d954-0d30-4950-980d-7bcaaad8e3e2 |
| Coulomb.social | Co-creation marketplace and governance experiment | 36c7421b-c537-4723-bf75-42a3ebc6a1dc |
| Personhood | Rights and obligations framework for mixed-intelligence societies | 084430ab-c630-48dc-9e1d-d07d1e8fce3c |
| Foerster Capabilities | Agency capability taxonomy (Foerster's Non-Trivial Machines) | 64418556-3206-457a-ba29-6884b5b12cf3 |
Each domain has three canon artifacts under canon/projects/<domain>/:
project_charter_v0.1.md— purpose, problem, scope, success criteriaconcepts_seed_v0.1.md— ten foundational conceptsroadmap_v0.1.md— multi-phase implementation plan
State Hub — Quick Start
The State Hub is the live operational layer: a PostgreSQL database, a FastAPI REST service, an MCP server for Claude Code, and an Observable dashboard.
Prerequisites
- Docker Engine (WSL2: see
CLAUDE.md→ Docker Setup) - Python 3.12+ with
uv(pip install uv) - Node.js 18+ (for dashboard only)
First-time setup
cd state-hub
cp .env.example .env # set POSTGRES_PASSWORD
make install # uv sync → Python deps + custodian CLI in .venv
make install-cli # symlink custodian to ~/.local/bin
make db # start postgres on 127.0.0.1:5432
make migrate # alembic upgrade head
make seed # insert 6 canonical topics
make api # uvicorn on 127.0.0.1:8000
API docs: http://127.0.0.1:8000/docs
Health check: make check
Shortcut
make api # db + migrate + api (restarts if already running)
Dashboard
cd state-hub
make dashboard # Observable Framework dev server on :3000
Connecting a Project
Any repository can be registered as a Custodian project in one command:
cd /path/to/your-project
custodian register-project --domain railiance
This will:
- Verify the API is running
- Look up the topic ID for the domain
- Check that the MCP server is registered in
~/.claude.json - Write a
CLAUDE.mdinto the project root - Post a progress event to the State Hub
Domain is auto-detected from project_charter_v*.md frontmatter if --domain is omitted.
custodian status # health + summary totals + blocking decisions
custodian register-project # full registration from cwd
Claude Code Integration
The state-hub MCP server is registered at user scope in ~/.claude.json.
It exposes 11 tools and 5 resources directly in every Claude Code session.
Session protocol (enforced via ~/.claude/CLAUDE.md):
- Start:
get_state_summary()— orientation snapshot - End:
add_progress_event()— append to the immutable log
Tool reference: state-hub/mcp_server/TOOLS.md
If the MCP server is missing from a session: check ~/.claude/CLAUDE.md → MCP Server Registration.
Governance
The constitution (canon/constitution/custodian_constitution_v0.1.md) defines hard boundaries:
The Custodian may without approval:
- Draft documents, plans, and structured artifacts
- Read/search canon and approved repositories
- Propose canon updates as PRs/patches (never direct writes)
- Create working-memory notes and session summaries
Never permitted (v0.1):
- Financial transactions or legal commitments
- External publication under Bernd's identity
- Storing secrets/credentials in plaintext
- Writing directly to
canon/without a review gate
Must escalate when:
- Actions affect money, legal status, security, or external reputation
- Instructions conflict with values or the constitution
- Consent is unclear, especially in family-scoped data
Canon Promotion Workflow
Custodian proposes → run gates (attribution, consistency, clarity, sensitivity, reversibility)
→ human approves → merge
All canon changes carry provenance metadata. Episodic memory is append-only.
Roadmap
| Phase | Focus | Status |
|---|---|---|
| 0 | Canon + constitution + State Hub v0.1 | done |
| 1 | RAG over canon, drafting pipelines, consistency checks | planned |
| 2 | Stewardship automation (health checks, drift detection) | planned |
| 3 | Sovereign appliance (local inference on dedicated hardware) | future |
| 4 | Family custodianship (consent model, vault, succession) | future |
Key Design Principles
- 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 over general intelligence
- Long timescale stewardship — designed for multi-year and eventual multi-generational continuity