the-custodian/workplans/CUST-WP-0025-fos-hub-bootstrap.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CUST-WP-0025	workplan	FOS Hub Bootstrap — Identity, Hub Extraction, Ops Hub, Fin Hub	infotech	the-custodian	active	custodian	custodian	2026-03-20	2026-06-27	293a74fe-a85a-4ad6-8933-23d52a72fe8b

FOS Hub Bootstrap — Identity, Hub Extraction, Ops Hub, Fin Hub

Goal

Progress the Custodian from FOS maturity Level 1 (Single-Hub Emergence) toward Level 3 (Core Federation) by:

1. Finalizing shared identity infrastructure (NetKingdom SSO)
2. Extracting a generic reusable hub-core package from state-hub
3. Renaming state-hub to dev-hub and transitioning all repos
4. Creating the ops-hub for runtime operations coordination
5. Building the fin-hub with railiance-as-a-service as first monetization path

Context

The state-hub has matured through 24 completed workplans (62 workstreams, 573 tasks) but remains a monolithic single hub mixing dev-coordination, governance, and generic infrastructure. Per FOS §13.1, this risks becoming the "Mega-Hub" anti-pattern.

Two standards govern the architecture:

• FOS (Federated Organisation Standard): organizational recursion via domain hubs
• OAS (Orthogonal Architecture Standard): compute substrate via 6 dimensions

Together they form a complete cybernetic stack: FOS gives the viable organization, OAS gives the viable infrastructure.

Key Decisions

Decision	Choice	Rationale
Hub-core packaging	Separate pip-installable package	Clean separation, versioned independently, each hub depends via uv
Phase sequencing	Parallel start (Phase 1 + 2)	Identity and extraction run concurrently; auth bolted on later
Ops Hub location	New standalone repo	FOS separation principle — each hub independently deployable
First monetization	Railiance-as-a-service	Package OAS infra stack as managed/consultancy for EU SMEs

Phase 1 — Identity Infrastructure

Goal: Finalized user-id infrastructure so all future hubs share one SSO plane. Repos: net-kingdom, railiance-cluster, railiance-platform Runs in parallel with Phase 2.

T01 — Complete NK-WP-0001: Keycloak + privacyIDEA on k3s

id: CUST-WP-0025-T01
status: cancel
priority: high
state_hub_task_id: "f55078b6-7fa3-49ab-be30-37db622d64c9"

Complete the SSO/MFA platform deployment. Keycloak as OIDC provider with privacyIDEA for MFA, running on the k3s cluster. This is the identity foundation for all hubs and services.

Cross-reference: net-kingdom NK-WP-0001.

2026-06-27 sequencing update: cancelled as an obsolete prerequisite. NK-WP-0001 is archived and superseded by the KeyCape/Authelia/LLDAP lightweight stack, NK-WP-0012 IAM Profile v0.2, and the proposed NK-WP-0011 expanded-mode Keycloak federation lane. FOS bootstrap should not wait for this old Keycloak path.

T02 — Complete NK-WP-0002: Local identity bootstrap

id: CUST-WP-0025-T02
status: done
priority: high
state_hub_task_id: "0d7792f7-5695-4e1a-9726-b9661d5e7108"

Implement lightweight file-based OIDC server for dev/sandbox/bootstrap scenarios where the full Keycloak cluster is unavailable. Enables local development of hub services without cluster dependency.

Cross-reference: net-kingdom NK-WP-0002.

2026-06-27 sequencing update: marked done. NK-WP-0002 is complete: local-identity file store, Keycloak export, minimal localhost OIDC provider, permissions hardening, audit log, and docs are all delivered.

T03 — IAM Profile integration test

id: CUST-WP-0025-T03
status: todo
priority: medium
state_hub_task_id: "e9894ac9-add3-45a6-9893-ea67c6e5e260"

Prove a FastAPI service can authenticate via NetKingdom OIDC end-to-end. Write a minimal test service + integration test that:

• Obtains a token via OIDC/PKCE flow
• Calls a protected endpoint
• Validates token claims (sub, roles, expiry)

This test becomes the template for hub-core auth middleware.

2026-06-27 sequencing update: this remains the real open identity gate, but it should target the current NetKingdom IAM Profile v0.2 contract and either local-identity or KeyCape lightweight issuer, not the archived NK-WP-0001 Keycloak path.

T04 — Canon standard: IAM Profile specification

id: CUST-WP-0025-T04
status: done
priority: medium
state_hub_task_id: "69acc880-394b-478a-94f0-476c9cbc1bc6"

Document the OIDC contract as canon/standards/iam-profile_v0.1.md:

• Discovery endpoint structure
• Required claims and scopes
• Token lifecycle (access + refresh)
• Hub-to-hub service account pattern
• Human override / emergency access

Phase 2 — Hub Extraction & Dev Hub Rename

Goal: Extract generic hub-core package; rename state-hub to dev-hub. Repo: the-custodian (governance and workplan), /home/worsch/state-hub (authoritative source), /home/worsch/hub-core (new target repo) Runs in parallel with Phase 1.

Current repo reality (2026-06-06): CUST-WP-0043 completed the State Hub repo extraction, so this repository now keeps only the state-hub/README.md pointer. Phase 2 implementation work must read and refactor the standalone /home/worsch/state-hub checkout, while this workplan keeps the coordination record in the-custodian.

Extraction Boundary

Generic hub-core (~17 MCP tools, ~6 models, ~6 routers):

• Models: Domain, AgentMessage, CapabilityCatalog, CapabilityRequest, ManagedRepo, TPSC*, ProgressEvent (generic event_types)
• Routers: domains, repos, messages, capability_requests, tpsc, policy
• MCP tools: orientation, messaging, capability routing, repo management, TPSC/GDPR, DoI

Dev-hub-specific (~51 MCP tools, ~12 models):

• Topics, workstreams, tasks, decisions, dependencies, EP/TD, contributions, SBOM, goals, DoI cache, kaizen agents, consistency checker

T05 — Create hub-core package

id: CUST-WP-0025-T05
status: done
priority: high
state_hub_task_id: "04bf480c-8847-4a89-a4f2-e7c5fc51088d"

Create /home/worsch/hub-core as a standalone repo with pyproject.toml (uv-managed). Extract from /home/worsch/state-hub:

• Generic SQLAlchemy models (Domain, AgentMessage, CapabilityCatalog, CapabilityRequest, ManagedRepo, TPSC*, ProgressEvent)
• Generic Pydantic schemas
• Generic FastAPI routers (domains, repos, messages, capability_requests, tpsc, policy)
• Alembic migration templates for core schema
• Shared utilities (slug resolution, pagination, trailing-slash normalization)

Implementation start (2026-06-06): reviewed the standalone State Hub source and captured the first extraction boundary in docs/hub-core-extraction-boundary.md. Several candidate "generic" models still reference dev-hub tables (topics, workstreams, tasks, decisions), so the initial package slice should start with base DB primitives, domains, repos, messages, TPSC catalog/snapshots, and adapter seams for progress and capability requests rather than a blind file copy.

Implementation slice 2 (2026-06-06): expanded /home/worsch/hub-core with router factory functions for domains, repos, messages, TPSC, and policy lookup. The factories receive the host hub's get_session dependency instead of binding to State Hub globals, preserving the package boundary for future hubs. Verification currently covers package compilation, SQLAlchemy metadata registration, and router factory construction.

Implementation slice 3 (2026-06-06): added hub-core shared utilities for slug normalization, pagination, repo path resolution, and trailing-slash path normalization. Added Alembic migration templates plus an initial core schema migration covering domains, managed repos, agent messages, capability catalog, and TPSC tables. Hub-core verification now covers package compilation, router construction, registered metadata, and utility behavior.

Implementation slice 4 (2026-06-06): added progress event and capability request adapter seams to /home/worsch/hub-core. The core progress event uses generic subject_refs JSON instead of dev-hub foreign keys, and capability requests use JSON request/fulfillment context fields instead of workstream/task columns. This keeps hub-core reusable while giving State Hub a migration path for its dev-specific references.

Completed package slice (2026-06-07): added the remaining generic REST router factories for progress events and capability catalog/request lifecycle. With models, schemas, routers, Alembic templates, and shared utilities present in /home/worsch/hub-core, T05 is complete enough for T06 MCP base-server work and T08 State Hub import refactoring to begin.

T06 — Hub-core FastMCP base server

id: CUST-WP-0025-T06
status: done
priority: high
state_hub_task_id: "6b49d94a-b1ea-4507-a8a3-e27c1a918491"

Add a base MCP server class to hub-core that provides the ~17 generic tools:

• Orientation: get_state_summary, get_domain_summary, list_domains
• Messaging: send_message, get_messages, mark_message_read, reply_to_message
• Capability routing: register_capability, list_capabilities, request_capability, accept_capability_request, update_capability_request_status, list_capability_requests, get_capability_request
• Repo management: register_repo, update_repo_path, list_domain_repos
• TPSC/GDPR: register_service, list_services, ingest_tpsc_tool, get_gdpr_report
• DoI: check_repo_doi, get_doi_summary

Domain-specific hubs inherit and add their own tools.

Implementation start (2026-06-07): added HubCoreMCPServer in /home/worsch/hub-core as a thin FastMCP wrapper over hub-core REST endpoints. The base class registers generic tools for domains, messages, capability catalog/requests, repos, TPSC, and progress.

Completed MCP slice (2026-06-07): added the remaining orientation tools (get_state_summary, get_domain_summary), DoI passthrough tools (check_repo_doi, get_doi_summary), and FOS §10 risk/alert read tools to HubCoreMCPServer. The DoI evaluator still remains host-hub-owned, but the generic MCP contract now exposes the required DoI tools.

T07 — FOS §10 risk and alert tools

id: CUST-WP-0025-T07
status: done
priority: medium
state_hub_task_id: "5a54af24-f7cb-451f-874f-66bd6979ab07"

Add get_risks() and get_alerts() to hub-core, formalizing existing ProgressEvent patterns. Define canonical event_type values:

• risk_surfaced, risk_mitigated, risk_escalated
• alert_raised, alert_acknowledged, alert_resolved

This completes the FOS §10 cross-hub contract.

Completed (2026-06-07): added canonical FOS §10 event constants to hub_core.events, exposed /progress/risks and /progress/alerts filtered views, and registered matching get_risks / get_alerts MCP tools. Hub-core tests cover the event contract, router views, and MCP tool registration.

T08 — Refactor state-hub to import from hub-core

id: CUST-WP-0025-T08
status: done
priority: high
state_hub_task_id: "daf1d8ac-b55a-4692-b359-2671ddf6fc8a"

Refactor the standalone /home/worsch/state-hub codebase:

• Replace generic models/routers/schemas with imports from hub-core
• Keep dev-specific code (topics, workstreams, tasks, decisions, etc.) in state-hub
• Ensure all existing tests pass with the new import structure
• Update pyproject.toml to depend on hub-core

Completed 2026-06-22: child workplan CUST-WP-0048 finished. Generic schemas, routers, capability write callbacks, and MCP composition now import from hub-core. State Hub regression: 426 tests. Deferred couplings documented in docs/hub-core-extraction-boundary.md (ProgressEvent FK mapping, optional workplan column → JSON migration). Phase 2 proceeds to dev-hub rename (T09+).

T09 — Rename MCP server state-hub to dev-hub

id: CUST-WP-0025-T09
status: done
priority: high
state_hub_task_id: "2148a804-7d6a-4e26-b1a8-08da24929c88"

Rename across all integration points:

• /home/worsch/state-hub/mcp_server/server.py: name="state-hub" → "dev-hub"
• ~/.claude/CLAUDE.md: 3 locations (registration commands, references)
• /home/worsch/state-hub/scripts/register_project.sh: validation checks
• /home/worsch/state-hub/scripts/patch_mcp_cwd.py: config checks
• /home/worsch/state-hub/custodian_cli.py: config checks
• /home/worsch/state-hub/scripts/project_rules/session-protocol.template: template text
• /home/worsch/state-hub/api/main.py: service metadata response

Completed 2026-06-22: MCP server identifier is dev-hub; legacy state-hub accepted during transition. Global ~/.claude/CLAUDE.md registration section updated.

T10 — MCP config migration script

id: CUST-WP-0025-T10
status: done
priority: medium
state_hub_task_id: "5953f129-089d-4d90-bbe5-f86da4eac1bf"

Create /home/worsch/state-hub/scripts/migrate_mcp_config.py that:

• Reads ~/.claude.json
• Renames mcpServers["state-hub"] to mcpServers["dev-hub"]
• Preserves all other settings
• Backs up original file before writing

Completed 2026-06-22: scripts/migrate_mcp_config.py plus unit tests in tests/test_mcp_registration.py. Local ~/.claude.json migrated.

T11 — Regenerate domain repo rule files

id: CUST-WP-0025-T11
status: done
priority: medium
state_hub_task_id: "7b41766b-f97f-4e9f-9f3c-c0937edb355f"

After template update, regenerate .claude/rules/session-protocol.md for all registered domain repos:

• railiance-infra, railiance-cluster, railiance-platform
• railiance-enablement, railiance-apps
• net-kingdom, markitect, coulomb.social
• personhood, foerster-capabilities

Completed 2026-06-22: scripts/update_agent_instruction_files.py regenerated session-protocol and related rule files for 66 local repos.

T12 — Full test suite and consistency check

id: CUST-WP-0025-T12
status: done
priority: high
state_hub_task_id: "e55ae544-3cea-485e-80d5-a9696ef97b96"

Gate: all of the following must pass before Phase 2 is considered complete:

• cd /home/worsch/state-hub && make test — full test suite
• make fix-consistency REPO=the-custodian — workplan ↔ DB sync
• make check-consistency-all — all registered repos
• Manual smoke test: start dev-hub MCP server, run get_domain_summary from a domain repo

Completed 2026-06-22: state-hub 434 tests pass; fix-consistency passes. check-consistency-all completes with pre-existing assessment-fail items in a few repos (unrelated to dev-hub rename); no new automation errors introduced.

Phase 3 — Ops Hub

Goal: Runtime operations coordination per FOS §7.3. Depends on: Phase 2 (hub_core available), Phase 1 (identity for service auth). Repo: core-hub for replacement runtime; the-custodian for coordination; standalone ops-hub is deferred until post-cutover need is proven.

Inventory-first implementation slice (2026-06-05): CUST-WP-0047 carves out the minimum useful part of T14/T16/T18 before the replacement runtime is fully proven: a repo-owned service inventory contract, an initial service/location/evidence seed, and the handoff path for Inter-Hub widgets and activity-core probes. After the Core Hub reset, these artifacts feed Core Hub ops evidence first; a separate ops-hub repo should ingest them only if a post-cutover service boundary is proven useful.

Inter-Hub bootstrap access lane (2026-06-17): CUST-WP-0049 extracts the repeatable authenticated bootstrap routine needed to finish ops-hub production activation without leaking keys into agent sessions: ops-hub owns the helper, ops-warden owns the short-lived SSH certificate envelope, and operator secret custody remains outside Git.

Core Hub reset (2026-06-27): CUST-WP-0052 supersedes the Inter-Hub-first implementation direction for future work. T13-T19 below have been rewritten around Core Hub: API-first replacement contracts, CLI helpers second, deployed evidence and cutover gates, and a rebuilt whynot-aligned operator UI third. Keep Haskell Inter-Hub as legacy compatibility or rollback evidence, not the preferred implementation target.

T13 — Open Core Hub replacement lane

id: CUST-WP-0025-T13
status: done
priority: high
state_hub_task_id: "2c6d1429-a67a-4f66-84d1-cb32ffdb890f"

Replace the old immediate standalone ops-hub repo scaffold with a Core Hub-owned replacement lane.

The replacement lane must keep the FOS intent of runtime operations coordination while using the current implementation order:

• Core Hub API resources and compatibility/evidence smokes first;
• thin operator CLI wrappers second;
• web UI rebuild third, after API/CLI parity is stable.

Completed 2026-06-27: Core Hub workplan CORE-WP-0008 finished as the API-first execution counterpart, and Custodian recorded the replacement evidence handoff in docs/core-hub-replacement-evidence.md. This task is complete as a reframe/open-lane task; it does not claim production cutover is complete.

T14 — Define Core Hub ops evidence contract and read-model gaps

id: CUST-WP-0025-T14
status: todo
priority: medium
state_hub_task_id: "0e811e9b-23a5-49f9-979e-cd1c5dcd937f"

Define the Core Hub-owned operations evidence contract that replaces the old standalone ops-specific model list.

The contract should reconcile:

• CUST-WP-0047 service inventory and current evidence vocabulary;
• Core Hub hubs, manifests, widgets, API consumers, and interaction events;
• activity-core probe metadata and core-hub-interaction-event sink output;
• migration runs, deployment records, outcome signals, and cutover evidence;
• non-secret custody rules for key prefixes, hashes, routes, and evidence ids.

Known Core Hub API/read-model gaps to resolve before UI expansion:

• a protected migration-run read route such as /api/v2/migration-runs;
• non-deferred deployment/outcome evidence routes where needed;
• a mapping from service inventory ids to Core Hub widgets/events.

Done when Core Hub has a workplan or spec that names the API resources, record shape, evidence event vocabulary, and migration path from the existing Custodian inventory artifacts.

T15 — Core Hub operator CLI parity

id: CUST-WP-0025-T15
status: done
priority: medium
state_hub_task_id: "3fdd1f61-4c8e-4614-898b-df7a9aa4a514"

Replace the old MCP-first ops tool plan with API and CLI parity first.

Required CLI surface:

• deployed Core Hub smoke evidence;
• ops-hub bootstrap/status checks;
• migration bundle validate/import;
• cutover readiness summary from non-secret evidence reports.

Completed 2026-06-27: CORE-WP-0008-T05 added make operator-cli and scripts/core_hub_cli.py with wrappers around the same Core Hub API behavior used by tests and smokes. Any MCP surface should consume these proven APIs later rather than becoming the first implementation path.

T16 — Deployed ops evidence and activity-core smokes

id: CUST-WP-0025-T16
status: wait
priority: high
state_hub_task_id: "702849c5-b253-4ede-afa7-0ab4f81e49a5"

Run the production-like Core Hub evidence smokes that replace the old direct Railiance infrastructure integration task.

Minimum evidence:

• make deployed-smoke or make operator-cli CLI_ARGS="deployed-smoke ..." against a real Core Hub staging URL;
• deployed activity-core Core Hub sink smoke with approved runtime token and widget mapping;
• non-secret report fields only: run id, hub/manifest/API-consumer ids, key prefixes, widget/event ids, counts, statuses, and containment booleans;
• State Hub progress note linking the evidence and naming any remaining gates.

Blocked until an approved CORE_HUB_BASE_URL, operator/runtime token custody path, and activity-core widget mapping are available. This task can close or supersede CUST-WP-0047-T05 and CUST-WP-0049-T06 only after deployed Core Hub evidence exists or an explicit supersede decision is recorded.

T17 — Core Hub, dev-hub, and cutover decision coupling

id: CUST-WP-0025-T17
status: wait
priority: medium
state_hub_task_id: "b99a3ed8-440b-4e28-88f5-495de7276f66"

Replace the old ops-hub-to-dev-hub protocol task with Core Hub replacement coupling and cutover decision records.

Minimum scope:

• Core Hub readiness summary from deployed smoke, migration import, activity-core sink, and optional legacy Inter-Hub reference evidence;
• State Hub progress/decision records that state whether legacy Inter-Hub fallback remains required;
• compatibility notes for consumers that still expect Inter-Hub /api/v2;
• rollback and Haskell retirement gates kept explicit.

Blocked until CORE-WP-0005 staging import, dual-run smokes, and cutover readiness evidence exist. Do not unblock CORE-WP-0007 Haskell retirement from local-only evidence.

T18 — Core Hub operator UI first screens

id: CUST-WP-0025-T18
status: todo
priority: medium
state_hub_task_id: "5b6cea8b-3982-49be-bacf-7269a3d2104e"

Replace the old Observable Framework dashboard task with the Core Hub operator UI rebuild backlog.

Initial UI work should implement only the first operator-critical screens:

• readiness overview;
• registry explorer;
• evidence stream;
• migration/cutover state;
• action-required gates;
• access metadata as a support panel, not a broad expansion area.

Use whynot-design tokens/components wherever practical and preserve make visual-check style desktop/mobile, no-overlap, text-overflow, protected route, and non-secret assertions. Start implementation from Core Hub docs/specs/operator-ui-rebuild-backlog.md, not from old Inter-Hub screens.

T19 — Ops-hub MCP server registration decision

id: CUST-WP-0025-T19
status: cancel
priority: medium
state_hub_task_id: "f033c80e-4ebb-49cf-8987-20c9b2ff4c13"

Cancel the old immediate registration of a standalone ops-hub MCP server.

The preferred replacement path is Core Hub API first and operator CLI second. Register a separate ops-hub MCP server only if post-cutover usage proves that a separate service boundary is still useful. Until then, State Hub progress and Core Hub API/CLI evidence are the coordination surfaces.

Phase 4 — Business Model & Fin Hub

Goal: First monetization via railiance-as-a-service + resource viability hub. Depends on: Phase 3 (multi-hub pattern proven).

T20 — Business model canvas: railiance-as-a-service

id: CUST-WP-0025-T20
status: todo
priority: medium
state_hub_task_id: "55db0560-2733-481d-adba-b72c3839ba45"

Define the offering:

• Target: EU SMEs needing sovereign, GDPR-compliant DevOps infrastructure
• Core: managed k3s cluster + observability + GitOps + backup
• Differentiator: VSM-based organizational architecture, not just infra
• Pricing tiers: self-hosted (open-source), managed, fully operated
• Document as canon/projects/railiance/business-model-canvas_v0.1.md

T21 — Canon: Bootstrap Protocol document

id: CUST-WP-0025-T21
status: todo
priority: medium
state_hub_task_id: "ce54d3fc-140e-49be-a181-779abc434d4e"

Address FOS blindspot #2 (bootstrapping & initial capital):

• Seed funding strategy and minimum viable budget
• MVP scope definition (what must exist before first customer)
• First 3 mandated roles: Constitutional Steward, Technical Operator, Financial Allocator
• Revenue threshold for role formalization
• Document as canon/constitution/bootstrap-protocol_v0.1.md

T22 — Create fin-hub repo from hub-core scaffold

id: CUST-WP-0025-T22
status: todo
priority: low
state_hub_task_id: "670757d8-305d-4736-9056-e79a150114b1"

Create fin-hub repo with same scaffold pattern as ops-hub. Register under custodian domain.

T23 — Fin-specific models

id: CUST-WP-0025-T23
status: todo
priority: low
state_hub_task_id: "8ebffb3f-0dbb-4672-b4e9-928992c41cf4"

Define SQLAlchemy models for:

• Budget: domain, period, allocated, committed, spent
• Commitment: type (subscription/contract/salary), amount, cadence, start/end
• BurnRate: domain, period, actual_spend, projected_spend
• RunwayProjection: current_balance, monthly_burn, months_remaining, alert_threshold
• TokenSpend: provider (anthropic/openai), model, tokens_in, tokens_out, cost, session_id

T24 — Fin-hub implementation: cost tracking + runway

id: CUST-WP-0025-T24
status: todo
priority: low
state_hub_task_id: "405f81d3-dec5-4154-a1b8-a3af344a0cc4"

Implement:

• Cloud cost ingestion (manual CSV import initially, OpenCost integration later)
• Anthropic API token spend tracking (parse billing exports)
• HostEurope server cost tracking
• Runway calculator with burn-rate projection
• Budget alerts when projected runway drops below threshold

T25 — Cross-hub coupling: fin-hub connections

id: CUST-WP-0025-T25
status: todo
priority: low
state_hub_task_id: "90a41790-7290-4145-b89f-88bf491d7652"

Implement FOS §9 cross-hub coupling:

• fin→dev: resource pressure signals (budget alerts surface in dev-hub)
• fin→ops: infrastructure cost attribution (per-service cost view)
• fin→canon: viability alerts (runway below threshold escalates to System 5)

T26 — Pricing and packaging: railiance-as-a-service MVP

id: CUST-WP-0025-T26
status: todo
priority: low
state_hub_task_id: "e17ef269-e349-44cc-ab14-6c57b43199b1"

Concrete pricing:

• Define 3 tiers with feature matrix
• Create landing page content
• Define onboarding workflow (customer → provisioned k3s + monitoring)
• Legal: GmbH implications, liability, SLA framework
• First customer acquisition strategy