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 <noreply@anthropic.com>
This commit is contained in:
29
.kaizen/agents/scope-analyst/memory.md
Normal file
29
.kaizen/agents/scope-analyst/memory.md
Normal file
@@ -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.
|
||||
169
SCOPE.md
169
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(<slug>)`)
|
||||
- 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`.
|
||||
|
||||
130
history/20260621-SCOPE.md
Normal file
130
history/20260621-SCOPE.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user