the-custodian/SCOPE.md

# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Central cognitive infrastructure and coordination hub for six project domains — provides governance canon, a live state-tracking API, and MCP integration for cross-domain agent sessions.

---

## Core Idea

The Custodian is both an **operational system** (State Hub: PostgreSQL + FastAPI + MCP server + Observable dashboard) and a **governance substrate** (canon: constitution, values, domain charters). It acts as episodic memory and coordination layer so that work across multiple repos remains visible, tracked, and aligned with long-term intent.

---

## In Scope

- Canon layer: governance constitution, foundational values, six domain charters/roadmaps
- State Hub API: topics, workstreams, tasks, decisions, progress events, contributions, SBOM, goals
- MCP server: exposes state-hub tools to Claude Code sessions hub-wide
- Memory: append-only episodic archive (working notes + immutable event logs)
- Agent runtime scaffolding: policies, kaizen agent copies, tool adapters
- Cross-domain coordination: dependency tracking, human-intervention flags, next-steps suggestions

---

## Out of Scope

- Domain-specific implementation work (Railiance, Markitect, etc. each own their repos)
- Financial/legal transactions or external publication
- Storing plaintext credentials
- Direct writes to `canon/` without a human-approved review gate

---

## Relevant When

- Starting or closing any session in a registered domain repo (orientation via `get_domain_summary()`)
- Tracking cross-domain decisions, blockers, or workplan progress
- Registering a new project into the ecosystem (`make register-project`)
- Consulting governance rules or domain charters
- Running the State Hub API locally for MCP connectivity

---

## Not Relevant When

- Implementing single-domain features (stay in the domain repo)
- Working fully offline with no need for state coordination
- Non-custodian ecosystem work (standalone projects, throw-away scripts)

---

## Current State

- Status: active
- Implementation: ~60% — canon + state-hub operational; RAG/drafting pipelines (Phase 2) not yet started
- Stability: stable (versioned Alembic migrations; no breaking API changes since v0.3)
- Usage: running daily; 15+ active workstreams across 6 domains; MCP server active in Claude Code

---

## How It Fits

- Upstream dependencies: none (sits at the top of the dependency order)
- Downstream consumers: all six domains (railiance → markitect → coulomb.social → personhood/foerster → custodian)
- Often used with: kaizen-agentic (agent definitions), ops-bridge (remote tunnel connectivity), activity-core (task factory)

---

## Terminology

- Preferred terms: canon, workstream, topic, progress event, domain
- Also known as: "the hub", "state hub"
- Potentially confusing terms: "topic" = domain-level grouping (not a chat topic); "decision" = tracked choice point with escalation rules

---

## Related / Overlapping Repositories

- `kaizen-agentic` — specialized agent personas callable via MCP from any domain session
- `ops-bridge` — SSH tunnel manager keeping remote agents connected to this hub
- `activity-core` — event-driven task factory tracked as a custodian-domain workstream

---

## Getting Oriented

- Start with: `CLAUDE.md` (session protocol) + `README.md` (architecture overview)
- Key files / directories: `state-hub/` (live API + MCP), `canon/` (governance), `workplans/` (active work), `state-hub/mcp_server/TOOLS.md` (tool reference)
- Entry points: `cd state-hub && make api` (API); Claude Code with state-hub MCP registered

---

## Notes

Dependency order for domain sequencing: Railiance → Markitect → Coulomb.social → Personhood/Foerster → Custodian. The consistency checker (`make fix-consistency REPO=the-custodian`) must be run after any workplan changes to keep the dashboard accurate.
feat(CUST-WP-0017): scope-analyst agent + SCOPE.md template + coverage T01: copy agent-scope-analyst.md to the-custodian/agents/ T02: add scope.template, prepend @SCOPE.md to claude-md.template, update register_project.sh to write SCOPE.md stub on new registration, add scope-analyst row to TOOLS.md T03: SCOPE.md for the-custodian itself Workplan: CUST-WP-0017 registered in state-hub Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-03-17 23:10:30 +01:00			`# SCOPE`

			`> This file helps you quickly understand what this repository is about,`
			`> when it is relevant, and when it is not.`
			`> It is intentionally lightweight and may be incomplete.`

			`---`

			`## One-liner`

			`Central cognitive infrastructure and coordination hub for six project domains — provides governance canon, a live state-tracking API, and MCP integration for cross-domain agent sessions.`

			`---`

			`## Core Idea`

			`The Custodian is both an operational system (State Hub: PostgreSQL + FastAPI + MCP server + Observable dashboard) and a governance substrate (canon: constitution, values, domain charters). It acts as episodic memory and coordination layer so that work across multiple repos remains visible, tracked, and aligned with long-term intent.`

			`---`

			`## In Scope`

			`- Canon layer: governance constitution, foundational values, six domain charters/roadmaps`
			`- State Hub API: topics, workstreams, tasks, decisions, progress events, contributions, SBOM, goals`
			`- MCP server: exposes state-hub tools to Claude Code sessions hub-wide`
			`- Memory: append-only episodic archive (working notes + immutable event logs)`
			`- Agent runtime scaffolding: policies, kaizen agent copies, tool adapters`
			`- Cross-domain coordination: dependency tracking, human-intervention flags, next-steps suggestions`

			`---`

			`## Out of Scope`

			`- Domain-specific implementation work (Railiance, Markitect, etc. each own their repos)`
			`- Financial/legal transactions or external publication`
			`- Storing plaintext credentials`
			- Direct writes to `canon/` without a human-approved review gate

			`---`

			`## Relevant When`

			- Starting or closing any session in a registered domain repo (orientation via `get_domain_summary()`)
			`- Tracking cross-domain decisions, blockers, or workplan progress`
			- Registering a new project into the ecosystem (`make register-project`)
			`- Consulting governance rules or domain charters`
			`- Running the State Hub API locally for MCP connectivity`

			`---`

			`## Not Relevant When`

			`- Implementing single-domain features (stay in the domain repo)`
			`- Working fully offline with no need for state coordination`
			`- Non-custodian ecosystem work (standalone projects, throw-away scripts)`

			`---`

			`## Current State`

			`- Status: active`
			`- Implementation: ~60% — canon + state-hub operational; RAG/drafting pipelines (Phase 2) not yet started`
			`- Stability: stable (versioned Alembic migrations; no breaking API changes since v0.3)`
			`- Usage: running daily; 15+ active workstreams across 6 domains; MCP server active in Claude Code`

			`---`

			`## How It Fits`

			`- Upstream dependencies: none (sits at the top of the dependency order)`
			`- Downstream consumers: all six domains (railiance → markitect → coulomb.social → personhood/foerster → custodian)`
			`- Often used with: kaizen-agentic (agent definitions), ops-bridge (remote tunnel connectivity), activity-core (task factory)`

			`---`

			`## Terminology`

			`- Preferred terms: canon, workstream, topic, progress event, domain`
			`- Also known as: "the hub", "state hub"`
			`- Potentially confusing terms: "topic" = domain-level grouping (not a chat topic); "decision" = tracked choice point with escalation rules`

			`---`

			`## Related / Overlapping Repositories`

			- `kaizen-agentic` — specialized agent personas callable via MCP from any domain session
			- `ops-bridge` — SSH tunnel manager keeping remote agents connected to this hub
			- `activity-core` — event-driven task factory tracked as a custodian-domain workstream

			`---`

			`## Getting Oriented`

			- Start with: `CLAUDE.md` (session protocol) + `README.md` (architecture overview)
			- Key files / directories: `state-hub/` (live API + MCP), `canon/` (governance), `workplans/` (active work), `state-hub/mcp_server/TOOLS.md` (tool reference)
refactor(makefile): rename backend → api, fold raw uvicorn target in The old bare `api` target (uvicorn only) is subsumed into the new `api` target (db + postgres-wait + migrate + fuser-restart + uvicorn). Updated all doc references and cleaned up duplicate entries left by the rename. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-03-18 23:20:45 +01:00			- Entry points: `cd state-hub && make api` (API); Claude Code with state-hub MCP registered
feat(CUST-WP-0017): scope-analyst agent + SCOPE.md template + coverage T01: copy agent-scope-analyst.md to the-custodian/agents/ T02: add scope.template, prepend @SCOPE.md to claude-md.template, update register_project.sh to write SCOPE.md stub on new registration, add scope-analyst row to TOOLS.md T03: SCOPE.md for the-custodian itself Workplan: CUST-WP-0017 registered in state-hub Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-03-17 23:10:30 +01:00
			`---`

			`## Notes`

			Dependency order for domain sequencing: Railiance → Markitect → Coulomb.social → Personhood/Foerster → Custodian. The consistency checker (`make fix-consistency REPO=the-custodian`) must be run after any workplan changes to keep the dashboard accurate.