the-custodian/workplans/CUST-WP-0043-state-hub-repo-extraction.md

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

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
CUST-WP-0043	workplan	State Hub Repo Extraction	custodian	the-custodian	completed	custodian	custodian	high	43	2026-05-17	2026-05-17	01fc91e6-7e4a-4eda-8322-e40a0c6c7cf7

CUST-WP-0043 - State Hub Repo Extraction

Goal

Untangle state-hub/ from the-custodian and make /home/worsch/state-hub the standalone source repository for the State Hub service before continuing State Hub implementation work such as CUST-WP-0042.

The intended end state is:

• the-custodian owns canon, governance, memory, agent runtime scaffolding, and cross-domain coordination documents.
• state-hub owns the live service: FastAPI app, MCP server, migrations, dashboard, scripts, policies, task-flow engine, tests, and operational docs.
• State Hub itself knows about the new state-hub repo path, so future workplans can live with the service they modify.
• The recently generated workplan CUST-WP-0042 - Workplan State Model Cleanup can be executed against the standalone state-hub repository instead of the embedded directory.

Context

/home/worsch/state-hub currently exists only as a repo-seed stub with a README, license, .gitignore, and Git metadata. The live implementation still resides under the-custodian/state-hub/.

This creates three forms of coupling:

• Source coupling: implementation code is versioned inside the governance repo.
• Operational coupling: Make targets, MCP registration, dashboard paths, and consistency sync assume state-hub/ is a subdirectory of the-custodian.
• Planning coupling: State Hub workplans, including CUST-WP-0042, are currently file-backed from the-custodian/workplans/ even when they primarily modify State Hub internals.

This workplan is deliberately narrower than the broader FOS hub extraction in CUST-WP-0025: it extracts the existing State Hub into its own repo first. The generic hub-core extraction and any future dev-hub rename remain separate architecture work.

Scope

In scope:

• Move the existing State Hub implementation into /home/worsch/state-hub.
• Preserve useful Git history where practical.
• Exclude generated or environment-local directories such as .venv/, dashboard/node_modules/, dashboard/dist/, __pycache__/, and .pytest_cache/.
• Register or update the state-hub repo in State Hub with the local path.
• Update session guidance, runbooks, Make targets, and MCP/API path references so agents and humans know where State Hub work now lives.
• Re-home State Hub workplans so future implementation work is file-backed from the standalone repo.

Out of scope:

• Extracting the generic hub-core package.
• Renaming State Hub to Dev Hub.
• Changing the State Hub lifecycle/status model itself; that belongs to CUST-WP-0042.
• Changing production deployment topology beyond path and repo ownership.

Extraction Boundary Inventory

Inventory captured on 2026-05-17 against /home/worsch/the-custodian/state-hub and target stub /home/worsch/state-hub.

Move To state-hub

These paths are tracked service source or service-owned operations assets and should become authoritative in /home/worsch/state-hub:

Path	Handling
.dockerignore	Move; revisit because current Docker context excludes tests, docs, and infra.
.env.example	Move; remains the safe config template.
Dockerfile	Move; update build context references after extraction.
Makefile	Move; becomes the primary State Hub command surface.
README.md	Move/merge with standalone repo baseline README.
alembic.ini	Move.
api/	Move; FastAPI app, models, schemas, routers, event publisher.
custodian_cli.py	Move; update any repo-root assumptions.
dashboard/observablehq.config.js	Move.
dashboard/package.json	Move.
dashboard/package-lock.json	Move.
dashboard/src/	Move; dashboard source and data loaders.
docs/	Move; State Hub operational and architecture docs.
flows/	Move; task-flow definitions.
infra/	Move; local Postgres compose and infra docs.
mcp_server/	Move; MCP server and tool reference.
migrations/	Move; Alembic migration environment and versions.
policies/	Move; repo DoI and workstream DoD policies.
prompts/	Move; State Hub prompt assets.
pyproject.toml	Move; Python package/dependency definition.
scripts/	Move; consistency, registration, SBOM, token, image, and repo-sync tooling.
task_flow_engine/	Move; embedded flow evaluator package.
tests/	Move; keep in repo even though Docker image currently excludes it.
uv.lock	Move; required for reproducible uv sync.

Keep In the-custodian

These remain Custodian-owned after extraction:

Path	Handling
canon/, memory/, runtime/, root workplans/	Stay in the-custodian; not part of State Hub service source.
Root AGENTS.md, CLAUDE.md, .custodian-brief.md, SCOPE.md	Stay, but update to point State Hub code work at /home/worsch/state-hub.
workplans/CUST-WP-0043-state-hub-repo-extraction.md	Stay as the bridge plan until extraction is complete.
workplans/CUST-WP-0042-workplan-state-model-cleanup.md	Re-home or bridge after standalone repo registration; do not duplicate blindly.
state-hub/	Remove or replace with a small pointer only after standalone verification passes.

Regenerate Locally

These paths are useful locally but should not be copied as source:

Path	Handling
.venv/	Regenerate with make install / uv sync.
dashboard/node_modules/	Regenerate with the dashboard package manager install.
dashboard/dist/	Regenerate via Observable build/preview.
dashboard/src/.observablehq/	Regenerate as Observable cache.
.pytest_cache/	Regenerate from test runs.
**/__pycache__/, *.pyc	Regenerate from Python execution.

Discard / Do Not Copy

These are local, sensitive, or machine-specific:

Path	Handling
.env	Do not copy; secrets/local config stay local.
.claude/settings.local.json	Do not copy; machine/user-local Claude settings.
kubectl	Do not copy unless later proven to be a tracked intentional helper; currently ignored and machine-local.

Target Stub State

/home/worsch/state-hub currently contains only .git/, .gitignore, LICENSE, and a repo-seed README. It needs a service-specific baseline before the implementation move:

• README that identifies State Hub as the live FastAPI/MCP/dashboard service.
• AGENTS.md with the State Hub session protocol.
• SCOPE.md for repo discovery and capability registration.
• A workplans/ directory or explicit decision about the repo-local workplan prefix before re-homing CUST-WP-0042.
• A tightened .gitignore that keeps uv.lock, docs, infra, and tests trackable while excluding runtime/build/cache/secrets.

Tasks

T01 - Inventory Extraction Boundary

id: CUST-WP-0043-T01
status: done
priority: high
state_hub_task_id: "1d1e1cd6-96ac-4840-9c11-2867ada1116d"

Create an inventory of everything under the-custodian/state-hub/ and classify each path as:

• move to state-hub
• keep in the-custodian
• regenerate locally
• discard as generated/cache output

Done when the inventory names the handling for API, MCP server, migrations, dashboard, infra, scripts, tests, docs, policies, prompts, and task-flow engine.

T02 - Prepare Standalone Repo Baseline

id: CUST-WP-0043-T02
status: done
priority: high
state_hub_task_id: "24ad0bf0-e11d-4a16-9c00-0f9cca6d208f"

Turn /home/worsch/state-hub from repo-seed stub into a proper service repo baseline before moving code:

• replace the seed README with State Hub-specific orientation
• add AGENTS.md/session protocol for State Hub work
• add SCOPE.md
• decide the repo-local workplan prefix for future State Hub plans
• ensure .gitignore excludes local environments, dependency installs, build output, caches, and secrets

Done when a fresh agent can open /home/worsch/state-hub and understand what the repo owns before any implementation code is copied.

T03 - Move Implementation With History-Aware Strategy

id: CUST-WP-0043-T03
status: done
priority: high
state_hub_task_id: "fe1faa7b-fa19-4d08-b12f-b67bbe5d6774"

Move the implementation from the-custodian/state-hub/ into the standalone repo using a strategy that preserves useful history where possible. Candidate approaches:

• git subtree split from the-custodian/state-hub/ into the new repo
• git filter-repo into a temporary extraction branch, then merge into the stub
• a clean copy only if history preservation is not worth the migration risk

Do not migrate generated or local-only content:

• .venv/
• dashboard/node_modules/
• dashboard/dist/
• __pycache__/
• .pytest_cache/
• local .env files or credentials

Done when /home/worsch/state-hub contains the service implementation and has a clean Git status other than intentional new extraction commits.

T04 - Decouple The Custodian Repository

id: CUST-WP-0043-T04
status: done
priority: high
state_hub_task_id: "92c6ee06-c256-4526-9bc4-6f2b1b0f5d8e"

Remove the-custodian/state-hub/ as an owned implementation tree after the standalone repo is verified. Leave only intentional integration surface in the-custodian, such as:

• documentation pointing to /home/worsch/state-hub
• optional proxy Make targets if they remain useful
• session guidance that says State Hub code work belongs in the standalone repo

Done when there is a single authoritative implementation tree and the-custodian no longer looks like it owns State Hub source code.

T05 - Register State Hub Repo In State Hub

id: CUST-WP-0043-T05
status: done
priority: high
state_hub_task_id: "5dd3547c-69b3-4760-83a7-f0783053a572"

Connect /home/worsch/state-hub to State Hub as a managed repo in the custodian domain.

Use the file-first rule for repo-backed workplans. If new workplan files are created in the standalone repo, write them before running consistency sync or registration tooling so no ghost workstreams are created.

Done when State Hub repo metadata resolves the local host path for /home/worsch/state-hub, and fix-consistency --here or the equivalent repo sync can discover the repo without path overrides.

T06 - Re-home State Hub Workplans

id: CUST-WP-0043-T06
status: done
priority: high
state_hub_task_id: "1c537901-1013-43e0-81c6-9c29ed4f7dd2"

Move State Hub implementation workplans to the standalone repo once it is registered. The first priority is the recently generated CUST-WP-0042 - Workplan State Model Cleanup.

The migration should preserve existing State Hub IDs where appropriate and avoid creating duplicate workstreams. If the consistency engine cannot safely move an existing file-backed workstream across repos, record the limitation and use the least confusing transition path:

• keep the old file as an archived pointer, or
• create a new State Hub-local continuation plan that references the old workstream explicitly

Done when future agents can work on the State Hub state-model cleanup from the standalone repo without editing the-custodian/state-hub/.

T07 - Update Operational Wiring

id: CUST-WP-0043-T07
status: done
priority: high
state_hub_task_id: "626faa5e-314b-445b-b86b-f11014473ad5"

Update path-sensitive wiring after extraction:

• Make targets and scripts that run API, MCP, migrations, tests, dashboard, or consistency sync
• MCP registration examples and local config patchers
• dashboard/data path references
• docs and runbooks that mention the-custodian/state-hub
• deployment or container build contexts
• NATS/activity-core delegation docs if they name repo-local paths

Done when local development and agent session startup use the standalone repo path and no longer assume the embedded path.

T08 - Verification Gate

id: CUST-WP-0043-T08
status: done
priority: high
state_hub_task_id: "4571d9fd-0513-406e-ad4e-284e39f16ac5"

Run verification from the standalone repo:

• Python test suite
• Alembic migration check
• API health check
• MCP server smoke test
• dashboard smoke test if frontend dependencies are available
• consistency sync for both affected repos

Done when the standalone repo can run the same service checks that previously ran from the-custodian/state-hub/, and the Custodian dashboard shows the new repo/workplan state accurately.

T09 - Handoff To State Hub State-Model Work

id: CUST-WP-0043-T09
status: done
priority: medium
state_hub_task_id: "72b737f8-6caa-4a36-9113-f05c4fab2738"

After extraction is verified, resume CUST-WP-0042 from the standalone state-hub repo. Before implementation starts:

• confirm the workplan paths point at the new repo layout
• confirm state_hub_workstream_id and task IDs still refer to the intended workstream/tasks
• update any acceptance criteria that assumed the embedded path
• record a progress event linking this extraction workplan to the resumed state-model cleanup work

Done when CUST-WP-0042 is ready to execute in the extracted repository.

Build Order

T01 -> T02 -> T03 -> T08
              T03 -> T04 -> T07 -> T08
T02 -> T05 -> T06 -> T09
T08 -> T09

CUST-WP-0042 should not receive implementation edits until T06 and T08 are complete, because its changes should land in the standalone state-hub repo.

Acceptance Criteria

• /home/worsch/state-hub is the authoritative State Hub implementation repo.
• the-custodian no longer owns a live copy of State Hub implementation code.
• State Hub repo metadata knows the standalone repo path on this host.
• New State Hub workplans can be synced from the standalone repo without ghost workstreams.
• Existing active State Hub work, especially CUST-WP-0042, has a clear and non-duplicating handoff path into the standalone repo.
• Local API, MCP, migration, dashboard, test, and consistency workflows are verified after extraction.

Risks And Guardrails

• Do not delete the embedded implementation until the standalone repo passes the verification gate.
• Do not copy secrets, local virtualenvs, dependency installs, or generated frontend output into the new repo.
• Do not call create_workstream() or create_task() manually for migrated file-backed workplans before the files exist in their final repo.
• Prefer a reversible transition: keep an archived pointer or temporary bridge doc in the-custodian until State Hub work has clearly moved.