From e57be41026d9638d67c1633be39566dfec4e87e7 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 21 Jun 2026 16:16:09 +0200 Subject: [PATCH] Rebuild SCOPE.md from current repo reality; archive stale version Archive the out-of-date SCOPE.md to history/20260621-SCOPE.md and rebuild it via the kaizen scope-analyst persona, grounded in INTENT.md (the newer boundary authority), the repo tree, and the live list_domains() result. Fixes: - Stop conflating this repo with the standalone State Hub service: reframe Provided Capabilities to governance canon / session protocol / append-only memory (state-tracking, SBOM, MCP-tool-registration belong to /state-hub). - Add missing boundary owners issue-core and repo-scoping to Out of Scope. - Replace the self-contradictory 6/7 domain count with a pointer to the live list (14 active as of 2026-06-21). - Add updated frontmatter for freshness tracking. Also records the scope-analyst agent memory for future runs. Co-Authored-By: Claude Opus 4.8 --- .kaizen/agents/scope-analyst/memory.md | 29 +++++ SCOPE.md | 169 +++++++++++++++++-------- history/20260621-SCOPE.md | 130 +++++++++++++++++++ 3 files changed, 273 insertions(+), 55 deletions(-) create mode 100644 .kaizen/agents/scope-analyst/memory.md create mode 100644 history/20260621-SCOPE.md diff --git a/.kaizen/agents/scope-analyst/memory.md b/.kaizen/agents/scope-analyst/memory.md new file mode 100644 index 0000000..1e474a1 --- /dev/null +++ b/.kaizen/agents/scope-analyst/memory.md @@ -0,0 +1,29 @@ +--- +agent: scope-analyst +last_updated: "2026-06-21" +session_count: 1 +--- + +# scope-analyst memory + +## Accumulated Findings + +### the-custodian (2026-06-21) +- **Central boundary decision:** the-custodian is the *governance/continuity + substrate*, NOT the State Hub service. The service (DB/API/MCP/dashboard) lives + at `/home/worsch/state-hub`; `the-custodian/state-hub/` is only a pointer. Any + SCOPE that claims state-tracking / SBOM / MCP-tool-registration as this repo's + own "Provided Capabilities" is conflating the two — the prior SCOPE did exactly + that. New SCOPE reframes capabilities to governance canon / session protocol / + append-only memory. +- **Authoritative boundary source:** `INTENT.md` (updated 2026-05-17) has the + cleanest "What it is not" ownership table — state-hub, activity-core, issue-core, + repo-scoping, domain repos, human-approval. SCOPE was missing issue-core and + repo-scoping; now added. +- **Domain count is dynamic, do NOT hard-code.** Live `list_domains()` returned + 14 active on 2026-06-21. Old SCOPE said 6/7 (and was self-contradictory). README + still says "seven"/"six" — also stale. Treat `list_domains()` as authoritative. +- Prior stale SCOPE archived to `history/20260621-SCOPE.md`. + +## Session Log +2026-06-21 · the-custodian · Rebuilt SCOPE.md from repo+INTENT+live domains; archived stale version; fixed state-hub/custodian conflation and domain-count drift. diff --git a/SCOPE.md b/SCOPE.md index 299fd59..fe43d38 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,3 +1,9 @@ +--- +domain: custodian +repo: the-custodian +updated: "2026-06-21" +--- + # SCOPE > This file helps you quickly understand what this repository is about, @@ -8,123 +14,176 @@ ## One-liner -Central cognitive infrastructure and coordination hub for seven project domains — provides governance canon and coordinates through the standalone State Hub API/MCP service. +Governance and continuity substrate for a local-first, multi-domain agent ecosystem — owns canon, memory, workplans, and agent runtime scaffolding; coordinates through the standalone State Hub service rather than hosting it. --- ## Core Idea -The Custodian repository is the **governance substrate**: canon, constitution, values, domain charters, workplans, and runtime scaffolding. The operational State Hub service (PostgreSQL + FastAPI + MCP server + Observable dashboard) now lives in the standalone `/home/worsch/state-hub` repository and acts as episodic memory and coordination layer for work across repos. +The Custodian holds the long-lived **meaning, boundaries, and continuity** of the +ecosystem: constitution, values, standards, domain charters, roadmaps, episodic +memory, and repo-backed workplans. It is the stewardship layer that keeps the +system coherent across tool changes, repo splits, and agent sessions. + +It deliberately keeps a **small operational surface**. Operational subsystems — +most notably the State Hub (PostgreSQL + FastAPI + MCP + dashboard) — live in +their own repositories and are referenced here only as integration pointers. +`the-custodian/state-hub/` is now a pointer; the service source is at +`/home/worsch/state-hub`. --- ## In Scope -- Canon layer: governance constitution, foundational values, six domain charters/roadmaps -- Coordination through the standalone State Hub API: topics, workstreams, tasks, decisions, progress events, contributions, SBOM, goals -- MCP session protocol: use the State Hub MCP tools from registered agent sessions -- 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 -- Publishing lifecycle events on NATS JetStream (`org.statehub.>`) so activity-core can react via declarative ActivityDefinitions +- Canon: constitution, foundational values, standards, domain charters, concept + seeds, roadmaps (`canon/`) — human-gated, proposal-then-review writes only +- Memory: append-only working notes and immutable episodic event logs (`memory/`) +- Workplans: repo-backed `CUST-WP-NNNN` plans for Custodian-owned coordination + work, per ADR-001 (file originates work, then the hub indexes it) (`workplans/`) +- Agent runtime scaffolding: policies, prompts, tool adapters, kaizen agent + copies (`runtime/`, `agents/`) +- Session protocol: how agents orient, coordinate, and hand off via the State + Hub MCP/REST surface (`.claude/rules/`, `.custodian-brief.md`) +- Cross-domain governance: tracking decisions, provenance, and human-intervention + gates; surfacing next steps from the read model +- Integration pointers and docs for adjacent services (hub-core extraction, + ops-hub catalog, activity-core delegation) (`docs/`, `state-hub/README.md`) --- ## 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 -- State Hub implementation work; use `/home/worsch/state-hub` -- Maintenance task *creation* in response to lifecycle events — that responsibility lives in activity-core (see `/home/worsch/state-hub/docs/activity-core-delegation.md`). The state hub remains a **read model**, not a task factory. +- **Live State Hub implementation** — migrations, dashboard, tests, API/MCP + source. Owned by `/home/worsch/state-hub`. +- **Event-triggered maintenance task creation** — owned by `activity-core`. The + hub is a read model, not a task factory. +- **General task lifecycle backend** — owned by `issue-core`. +- **Repository capability profiling** — owned by `repo-scoping`. +- **Domain-specific products and experiments** — each domain owns its own repo. +- **External publication, contracts, payments, legal authority** — human approval + only; never automated here. +- Storing plaintext credentials, or direct writes to `canon/` without a 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 standalone State Hub API locally for MCP connectivity +- Starting or closing a session in any registered domain repo (orientation via + `get_domain_summary()`) +- Consulting governance rules, the constitution, values, or a domain charter +- Tracking cross-domain decisions, blockers, provenance, or workplan progress +- Registering a new project into the ecosystem (`custodian register-project`) +- Preserving durable, reviewable memory of why something was decided --- ## 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) +- Implementing a single-domain feature — stay in that domain's repo +- Hacking on State Hub internals — go to `/home/worsch/state-hub` +- Throwaway scripts or non-ecosystem standalone work --- ## Current State -- Status: active -- Implementation: ~60% — canon + standalone 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 +- Status: active — stable governance substrate, in daily use +- Implementation: substantial. Canon + memory + workplan conventions established; + State Hub operational (in its own repo); RAG-over-canon and drafting pipelines + (roadmap Phase 1) not yet started +- Stability: stable — canon changes are review-gated; memory is append-only +- Usage: daily, across the ecosystem; State Hub MCP active in agent sessions +- Domains coordinated: dynamic — 14 active as of 2026-06-21 (canon, capabilities, + citation_evidence, coulomb_social, custodian, helix_forge, inter_hub, markitect, + netkingdom, personhood, railiance, stack, vergabe_teilnahme, whynot). Query the + live list with `list_domains()` rather than trusting a hard-coded count. --- ## 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); **activity-core** consumes state hub lifecycle events on NATS subject `org.statehub.>` to drive maintenance ActivityDefinitions -- Often used with: kaizen-agentic (agent definitions), ops-bridge (remote tunnel connectivity), activity-core (task factory + event bridge) +- Upstream dependencies: none — sits at the top of the dependency order +- Downstream consumers: all tracked domains rely on its canon, session protocol, + and coordination conventions +- Often used with: + - `state-hub` — the operational read model / coordination service it points to + - `activity-core` — event-driven task factory consuming hub lifecycle events + - `issue-core` — task lifecycle backend + - `repo-scoping` — repository capability profiling + - `kaizen-agentic` — specialized agent personas callable via MCP + - `ops-bridge` — SSH tunnel manager for remote agent connectivity --- ## 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 +- Preferred terms: canon, workstream, workplan, topic, progress event, domain +- Also known as: "the hub" (loosely) — but the *service* is the State Hub repo; + this repo is the governance substrate +- Potentially confusing terms: + - "topic" = domain-level grouping, not a chat topic + - "decision" = tracked choice point with escalation rules + - "State Hub" = the standalone service repo, **not** this directory tree --- -## Related / Overlapping +## 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 +- `state-hub` — operational service (DB/API/MCP/dashboard); the most common + confusion point. This repo coordinates *through* it but does not own it. +- `activity-core` — overlaps on "what work should happen next"; owns the + *creation* of maintenance tasks (custodian only describes/coordinates). +- `issue-core` — task lifecycle backend; do not reimplement task storage here. +- `repo-scoping` — capability profiling; do not reimplement here. +- `kaizen-agentic` — source of agent personas mirrored under `agents/`. --- ## Getting Oriented -- Start with: `CLAUDE.md` (session protocol) + `README.md` (architecture overview) -- Key files / directories: `canon/` (governance), `workplans/` (active Custodian work), `state-hub/` (pointer), `/home/worsch/state-hub/mcp_server/TOOLS.md` (tool reference) -- Entry points: `cd /home/worsch/state-hub && make api` (API); Codex/Claude Code with state-hub MCP registered +- Start with: `INTENT.md` (why this repo exists + boundary table), then + `CLAUDE.md` → `.claude/rules/` (session protocol), then `README.md` +- Key files / directories: `canon/` (governance), `memory/` (continuity), + `workplans/` (CUST-WP plans), `runtime/`, `state-hub/README.md` (pointer) +- Entry points: `cat .custodian-brief.md` (offline-safe orientation); + `get_domain_summary("custodian")` (MCP); State Hub service at + `/home/worsch/state-hub` (`make api`) --- ## Provided Capabilities ```capability -type: api -title: MCP tool registration -description: Register and expose new MCP tools to all Claude Code sessions via the state-hub server. -keywords: [mcp, tool, api, registration, server] +type: reference +title: Governance canon +description: Constitution, foundational values, standards, and per-domain charters/roadmaps that define what matters and what is permitted across the ecosystem. +keywords: [canon, governance, constitution, values, charter, standards] +``` + +```capability +type: process +title: Session protocol and cross-domain orientation +description: Conventions for how agents orient, coordinate, and hand off via the State Hub, including ADR-001 workplan origination and human-gated review. +keywords: [session, orientation, protocol, workplan, adr-001, coordination] ``` ```capability type: data -title: Cross-domain state tracking -description: Track workstreams, tasks, decisions, and progress events across all seven project domains. -keywords: [state, tracking, workstream, task, decision, progress] -``` - -```capability -type: api -title: SBOM and licence reporting -description: Ingest lockfiles from any repo and provide aggregated SBOM and copyleft licence risk reports. -keywords: [sbom, licence, license, dependency, lockfile, copyleft] +title: Append-only memory and provenance +description: Durable, reviewable working notes and immutable episodic logs preserving decisions and session continuity over long timescales. +keywords: [memory, provenance, episodic, continuity, decisions] ``` --- ## Notes -Dependency order for domain sequencing: Railiance → Markitect → Coulomb.social → Personhood/Foerster → Custodian. The consistency checker (`cd /home/worsch/state-hub && make fix-consistency REPO=the-custodian`) must be run after any workplan changes to keep the dashboard accurate. +- This repo intentionally avoids reabsorbing runtime code. If a subsystem grows a + runtime, tests, and a deployment surface, it should move to its own repo and + report back through the State Hub and workplans (see `INTENT.md` → design values). +- After any workplan change, run `cd /home/worsch/state-hub && make + fix-consistency REPO=the-custodian` to keep the dashboard accurate. +- `README.md` still references "seven project domains" / "six domain charters" — + stale relative to the live 14-domain list; treat `list_domains()` as authoritative. +- Prior SCOPE.md (stale, conflated this repo with the State Hub service) is + archived at `history/20260621-SCOPE.md`. diff --git a/history/20260621-SCOPE.md b/history/20260621-SCOPE.md new file mode 100644 index 0000000..299fd59 --- /dev/null +++ b/history/20260621-SCOPE.md @@ -0,0 +1,130 @@ +# 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 seven project domains — provides governance canon and coordinates through the standalone State Hub API/MCP service. + +--- + +## Core Idea + +The Custodian repository is the **governance substrate**: canon, constitution, values, domain charters, workplans, and runtime scaffolding. The operational State Hub service (PostgreSQL + FastAPI + MCP server + Observable dashboard) now lives in the standalone `/home/worsch/state-hub` repository and acts as episodic memory and coordination layer for work across repos. + +--- + +## In Scope + +- Canon layer: governance constitution, foundational values, six domain charters/roadmaps +- Coordination through the standalone State Hub API: topics, workstreams, tasks, decisions, progress events, contributions, SBOM, goals +- MCP session protocol: use the State Hub MCP tools from registered agent sessions +- 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 +- Publishing lifecycle events on NATS JetStream (`org.statehub.>`) so activity-core can react via declarative ActivityDefinitions + +--- + +## 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 +- State Hub implementation work; use `/home/worsch/state-hub` +- Maintenance task *creation* in response to lifecycle events — that responsibility lives in activity-core (see `/home/worsch/state-hub/docs/activity-core-delegation.md`). The state hub remains a **read model**, not a task factory. + +--- + +## 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 standalone 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 + standalone 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); **activity-core** consumes state hub lifecycle events on NATS subject `org.statehub.>` to drive maintenance ActivityDefinitions +- Often used with: kaizen-agentic (agent definitions), ops-bridge (remote tunnel connectivity), activity-core (task factory + event bridge) + +--- + +## 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 + +- `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: `canon/` (governance), `workplans/` (active Custodian work), `state-hub/` (pointer), `/home/worsch/state-hub/mcp_server/TOOLS.md` (tool reference) +- Entry points: `cd /home/worsch/state-hub && make api` (API); Codex/Claude Code with state-hub MCP registered + +--- + +## Provided Capabilities + +```capability +type: api +title: MCP tool registration +description: Register and expose new MCP tools to all Claude Code sessions via the state-hub server. +keywords: [mcp, tool, api, registration, server] +``` + +```capability +type: data +title: Cross-domain state tracking +description: Track workstreams, tasks, decisions, and progress events across all seven project domains. +keywords: [state, tracking, workstream, task, decision, progress] +``` + +```capability +type: api +title: SBOM and licence reporting +description: Ingest lockfiles from any repo and provide aggregated SBOM and copyleft licence risk reports. +keywords: [sbom, licence, license, dependency, lockfile, copyleft] +``` + +--- + +## Notes + +Dependency order for domain sequencing: Railiance → Markitect → Coulomb.social → Personhood/Foerster → Custodian. The consistency checker (`cd /home/worsch/state-hub && make fix-consistency REPO=the-custodian`) must be run after any workplan changes to keep the dashboard accurate.