coulomb/prj-state-hub-retirement
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Seed State Hub retirement project

Browse source
This commit is contained in:
tegwick 2026-08-09 16:36:17 +02:00
parent 5852f184a1
commit bd2b6dc94e
9 changed files with 581 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored Normal file
View file

@ -0,0 +1,5 @@
# state-hub: track .claude/rules
# Claude Code local state (track shared rules; ignore machine-specific files)
.claude/*
!.claude/rules/
!.claude/rules/*.md

26
.repo-classification.yaml Normal file
View file

@ -0,0 +1,26 @@
repo_classification:
standard: Repo Classification Standard
version: "1.0"
classified_at: "2026-08-09"
classified_by: human
category: project
domain: infotech
secondary_domains:
- agents
capability_tags:
- platform
- orchestration
- coordination
- governance
business_stake:
- technology
- execution
- intelligence
business_mechanics:
- coordination
- control
- adaptation
notes: >-
Temporary prj-flavor repository coordinating hub-core consolidation,
Repo Manager establishment, information-architecture work, and complete
State Hub retirement. Archive when GOAL.md retirement gates are met.

222
AGENTS.md Normal file
View file

@ -0,0 +1,222 @@
# prj-state-hub-retirement — Agent Instructions
## Repo Identity
**Purpose:** Temporary cross-repository project for consolidating hub-core,
establishing Repo Manager and the HelixForge information architecture, and
retiring State Hub with accepted evidence.
**Domain:** infotech
**Repo slug:** prj-state-hub-retirement
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `SHR-WP-`
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and
the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge
adds severe call latency; the full administrative MCP surface remains available
to clients that need it.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
| Optional local edge relay | http://127.0.0.1:18080 |
When an operator has enabled the edge relay, set API_BASE to the relay URL.
Queueable writes return an explicit queued receipt if the central hub is
unreachable. Treat that as pending local evidence, then ask the operator to run
statehub outbox status/replay after connectivity returns.
Codex workspace-write sandboxes need network access enabled to reach the host's
loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex`
and restart Codex. The canonical REST health endpoint is `/state/health`, not
`/health`. If a sandboxed loopback probe fails, retry it with escalated execution
before declaring State Hub unavailable; a managed Codex permission profile may
still enforce isolated networking. Experimental MCP can be enabled explicitly
with `make -C ~/state-hub configure-codex WITH_MCP=1`.
### Orient at session start
```bash
# Offline brief — works without hub connection
cat .custodian-brief.md
# Active workplans for this domain
curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=prj-state-hub-retirement&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Log progress (required at session close)
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workplan_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workplan_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe)
2. Check inbox: `GET /messages/?to_agent=prj-state-hub-retirement&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses to reflect progress
2. If finishing a workplan: hand off **residuals** as live work records first
(intake with `origin: residual` + `origin_ref: <WP-id>`, or a next workplan /
decision / engagement). Do not park leftovers only in prose or `SCOPE.md`.
Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
3. Log: `POST /progress/` with a summary of what changed (name handoff ids)
4. After workplan file changes, run:
```bash
statehub fix-consistency
```
Coding agents should run this directly; ask the operator only if the CLI or
State Hub API is unavailable. This syncs task status from files into the hub DB.
---
Before requesting credentials or access, use `warden route find "<need>" --json`.
Never record secret values in project files, State Hub, workplans, evidence, or
chat.
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
## Project protocol
This is a temporary project repository. It has `GOAL.md`, not `INTENT.md`.
At session start, read in this order:
1. `GOAL.md` — outcome, invariants, success gates, and retirement conditions.
2. `SCOPE.md` — project authority and implementation boundaries.
3. `history/2026-08-09-genesis.md` — architectural lineage.
4. `workplans/SHR-WP-0001-foundation.md` and any later active workplans.
Implementation remains in the affected functional repositories. This project
owns architecture, decisions, sequencing, dependencies, migration ledgers,
risks, gates, and consolidated evidence. Link child workplans by stable ID; do
not copy their task lists here.
The project is complete only when every `GOAL.md` retirement condition has
accepted evidence and all residual work has a live owner outside this repo.
---
## Workplan Convention (ADR-001)
Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files.
**File location:** `workplans/SHR-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-SHR-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
this only for low-risk work completed directly; create a normal workplan for
anything needing analysis, design, approval, dependencies, or multiple phases.
**Frontmatter:**
```yaml
---
id: SHR-WP-NNNN
type: workplan
title: "..."
domain: infotech
repo: prj-state-hub-retirement
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # fix-consistency — do not edit (legacy field name; workplan UUID)
---
```
Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Terminology:** workplan is the fleet term; `workstream` appears only in legacy
API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Task block format** (one per `##` section):
```
## Task Title
` ` `task
id: SHR-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
**Residuals when finishing:** actionable leftovers become live work records
before `status: finished` — usually an intake (`origin: residual`,
`origin_ref: SHR-WP-NNNN`) or a spawned workplan. Residual is a *role*,
not a kind. Fleet list lives on State Hub, not in `SCOPE.md`.
To create a new workplan:
1. Write the file following the format above
2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or
State Hub API is unavailable.

88
GOAL.md Normal file
View file

@ -0,0 +1,88 @@
---
repo: prj-state-hub-retirement
repo_flavor: project
project_status: active
started: "2026-08-09"
reviewed: "2026-08-09"
---
# Project goal
## Outcome
Establish a coherent HelixForge information architecture and hub framework that
can replace State Hub without losing repository authority, coordination
history, operational evidence, or agent usability.
The project will:
1. consolidate the deployed `core-hub` runtime into the surviving `hub-core`
repository and retire `core-hub`;
2. define hub-core as the cross-domain identity, addressing, interaction,
messaging, projection, telemetry, policy-integration, and domain-extension
framework;
3. establish `repo-manager` as the repository representation, agent-role,
indexing, reconciliation, and governed-control component;
4. define an implementable Orthogonal Architecture extension model for domain
hubs;
5. assign every State Hub capability, API, dataset, and consumer to one explicit
destination or retirement decision;
6. migrate consumers and historical evidence without creating competing
authorities; and
7. retire State Hub completely.
## Architectural invariants
- Repositories remain valid and usable independently of HelixForge.
- Repository-owned files and Git history remain authoritative for
repository-owned records.
- Repo Manager combines repository observation and governed control.
- Cross-entity communication belongs to hub-core, not Repo Manager.
- Domain hubs represent domains or orthogonal aspects; infrastructure
components are not called hubs merely because they support the framework.
- Specialized services retain execution and data authority behind explicit
contracts.
- Message transport, durable interaction, work commitments, knowledge, and
telemetry remain distinct information kinds with correlated identities.
- Migration is incremental and evidence-backed; no big-bang rewrite.
## Success gates
The project goal is achieved only when all of the following are true:
- A canonical information model defines entities, relations, events, signals,
messages, conversations, requests, work, decisions, knowledge, and telemetry.
- A versioned hub/domain-extension contract implements the relevant Orthogonal
Architecture concepts and has a conformance suite.
- Hub-core contains the production runtime, contracts, SDK, extension registry,
and compatibility surface required by active consumers.
- Production traffic formerly served by `core-hub` runs from the consolidated
hub-core implementation; the old repository is archived.
- Repo Manager represents repositories end to end, including file-backed work
records, consistency, agent roles, change events, and governed mutations.
- Every State Hub route, model, dataset, background job, MCP tool, dashboard,
and known consumer has a recorded keep/move/replace/retire disposition.
- All retained State Hub capabilities operate through their new owners with
compatibility, data-count, provenance, authorization, and failure-mode tests.
- State Hub receives no normal reads or writes during an agreed stabilization
window.
- Backup, restore, rollback, and historical-query evidence has been accepted.
- State Hub is stopped and its repository and final data are archived read-only.
## Project retirement
This repository is temporary. It can be retired when:
1. every success gate above has accepted evidence;
2. all unfinished residuals have live owners and work records outside this
repository;
3. project decisions and final architecture have been promoted to their durable
canonical repositories;
4. child workplans are finished, cancelled with rationale, or handed off;
5. the final project report identifies the deployed revisions, migrations,
archived assets, remaining operational obligations, and rollback expiry;
6. the repository is marked completed and made read-only after a final
consistency and link check.
Retirement means archival, not deletion. The repository remains available as
the provenance record for why and how State Hub was replaced.

11
README.md
View file

@ -1,3 +1,12 @@
# prj-state-hub-retirement # prj-state-hub-retirement
Projectmanagement repository for replacing state-hub with the new hub-core based infrastructure of Orthogonal Architecture Framework conforman domain-hubs. Temporary project repository for replacing State Hub with a consolidated
hub-core information and interaction framework, Repo Manager, and
Orthogonal-Architecture-conformant domain hubs.
The project is governed by [GOAL.md](GOAL.md). Its background, boundaries, and
first delivery plan are recorded in [history/2026-08-09-genesis.md](history/2026-08-09-genesis.md),
[SCOPE.md](SCOPE.md), and [SHR-WP-0001](workplans/SHR-WP-0001-foundation.md).
This repository is designed to be retired when the goal and retirement gates
are satisfied.

51
SCOPE.md Normal file
View file

@ -0,0 +1,51 @@
# Scope
## Project authority
This repository owns the cross-repository project goal, target architecture,
decisions, sequencing, dependency map, migration ledger, risks, acceptance
gates, and consolidated evidence for State Hub retirement.
It does not own the production implementations being changed.
## Participating repositories
Initial participants include:
- `hub-core`
- `core-hub`
- `state-hub`
- `repo-manager`
- `activity-core`
- `issue-core`
- `the-custodian`
- `ops-hub`
- `fin-hub`
- identity, authorization, audit, and knowledge components as their boundaries
are resolved
## In scope
- Repository-flavor and temporary-project conventions.
- HelixForge information architecture and authority model.
- Orthogonal Architecture extension contracts and conformance.
- Core-hub-to-hub-core consolidation and cutover.
- Repo Manager foundation and State Hub repository-capability extraction.
- State Hub capability, data, consumer, and integration inventory.
- Cross-repository implementation sequencing and acceptance gates.
- Compatibility adapters, migration evidence, rollback, and retirement.
## Out of scope
- Hosting production implementation code in this project repository.
- Replacing child-repository workplans with duplicate project tasks.
- Becoming a permanent portfolio database, message system, or knowledge store.
- Rewriting specialized services whose authority remains valid.
- Deleting historical repositories or evidence.
## Work-record rule
The project records milestones, dependencies, gates, decisions, and cross-repo
acceptance. Each participating repository owns its implementation workplan and
evidence. Project records link those workplans by stable identifier rather than
copying their task lists.

17
WORK-RECORDS.md Normal file
View file

@ -0,0 +1,17 @@
# Work Records — prj-state-hub-retirement
> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
> stage 3). Do not edit by hand — edit the source file/block listed for
> each record and re-run fix-consistency to refresh this index. Archived
> workplans are omitted; closed decisions/intakes/engagements stay listed
> so recently-resolved work is still visible. [auto]
| Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- |
| workplan | SHR-WP-0001 | proposed | — | workplans/SHR-WP-0001-foundation.md |
| task | SHR-WP-0001-T01 | todo | — | workplans/SHR-WP-0001-foundation.md |
| task | SHR-WP-0001-T02 | todo | — | workplans/SHR-WP-0001-foundation.md |
| task | SHR-WP-0001-T03 | todo | — | workplans/SHR-WP-0001-foundation.md |
| task | SHR-WP-0001-T04 | todo | — | workplans/SHR-WP-0001-foundation.md |
| task | SHR-WP-0001-T05 | todo | — | workplans/SHR-WP-0001-foundation.md |
| task | SHR-WP-0001-T06 | todo | — | workplans/SHR-WP-0001-foundation.md |

53
history/2026-08-09-genesis.md Normal file
View file

@ -0,0 +1,53 @@
# Project genesis
**Recorded:** 2026-08-09
## Starting condition
State Hub had grown from a useful repository-backed work coordination service
into a broad system containing development records, messages, progress,
capability workflows, service and third-party catalogs, telemetry, execution
controls, and cross-domain projections. The breadth made orientation and
authority boundaries increasingly difficult.
An earlier architecture proposed domain hubs around a shared framework and an
Orthogonal Architecture Standard. The second-generation Inter-Hub runtime was
implemented in Haskell/IHP but proved operationally too specialized. A
third-generation Python/FastAPI `core-hub` replacement was deployed, while
generic primitives were extracted into a separate `hub-core` library.
This successfully retired the Haskell production path, but left three problems:
- `core-hub` and `hub-core` split one conceptual framework across confusingly
named repositories;
- the Orthogonal Architecture Standard remained mostly documentary rather than
an executable extension and information model; and
- State Hub retained a large mixture of repository, cross-domain, and
domain-specific responsibilities.
## Direction established
The project begins from the following direction:
- consolidate `core-hub` into `hub-core` and make hub-core the surviving
cross-domain framework and runtime;
- build domain hubs through explicit extension contracts rather than a mesh of
direct service dependencies;
- keep specialized authorities such as identity, authorization, scheduling,
issues, audit, and finance behind delegated ports;
- create Repo Manager as the complete repository integration boundary;
- move cross-entity communication and information flow into hub-core and its
supporting components; and
- retire State Hub completely once every capability and consumer has an
evidence-backed disposition.
## Why a project repository
The work spans many repositories and changes their relationships. No single
functional repository should own the transformation plan. This repository is
therefore the first proposed `prj-` repository flavor: a temporary,
outcome-oriented coordination and provenance surface.
It owns the project goal and gates while implementation remains local to the
affected repositories. When the outcome is achieved and durable decisions have
moved to their permanent homes, this repository is archived.

109
workplans/SHR-WP-0001-foundation.md Normal file
View file

@ -0,0 +1,109 @@
---
id: SHR-WP-0001
type: workplan
title: "Project foundation and architecture baseline"
domain: infotech
repo: prj-state-hub-retirement
status: proposed
owner: codex
topic_slug: state-hub-retirement
created: "2026-08-09"
updated: "2026-08-09"
state_hub_workstream_id: "8498db77-cbe1-48ff-b7f0-03b933f0aa8a"
---
# Project foundation and architecture baseline
## Goal
Establish the durable project conventions, evidence inventories, architecture
decisions, and child-repository workplan map required before implementation
migration begins.
## Confirm the project-repository convention
```task
id: SHR-WP-0001-T01
status: todo
priority: high
state_hub_task_id: "528ed9c9-57a6-4f44-b1cf-9d2c1a5cbca4"
```
Define the `prj-` repository flavor, lifecycle, required files, authority
boundary, and archive procedure in the Custodian canon. Confirm that project
repositories use `GOAL.md` rather than durable-product `INTENT.md`.
## Inventory State Hub
```task
id: SHR-WP-0001-T02
status: todo
priority: high
state_hub_task_id: "f19351e4-c922-417c-bcc7-746a2cd7fe52"
```
Produce machine-readable inventories of State Hub routes, models, migrations,
jobs, MCP tools, dashboard views, datasets, callers, and operational
dependencies. Give every item an initial owner and keep/move/replace/retire
disposition.
## Define the information architecture
```task
id: SHR-WP-0001-T03
status: todo
priority: high
state_hub_task_id: "65e522c7-2550-4187-a308-a23a2bae7615"
```
Define canonical entities and relations plus the distinct semantics of events,
signals, messages, conversations, requests, work, decisions, knowledge, and
telemetry. Specify correlation, authority, provenance, sensitivity, retention,
cost attribution, and transformation rules.
## Define the hub and extension architecture
```task
id: SHR-WP-0001-T04
status: todo
priority: high
state_hub_task_id: "90e8350a-8a1c-4f46-a545-69c9cf00e6d1"
```
Revise the Orthogonal Architecture material into an implementable hub-core and
domain-extension contract. Define domain hubs, functional components,
authoritative services, projections, adapters, and conformance requirements.
## Establish the child-workplan map
```task
id: SHR-WP-0001-T05
status: todo
priority: high
state_hub_task_id: "1fc9da32-14ed-46b6-a965-b2477414df78"
```
Create or identify local implementation workplans in `repo-manager`,
`hub-core`, `core-hub`, `state-hub`, and other affected repositories. Record
dependencies and project gates without duplicating their tasks here.
## Baseline migration and retirement acceptance
```task
id: SHR-WP-0001-T06
status: todo
priority: medium
state_hub_task_id: "d793f242-999c-47ad-86f2-6d972cc20b84"
```
Record baseline row counts, callers, availability expectations, recovery paths,
and historical-evidence requirements. Turn the success and retirement clauses
in `GOAL.md` into executable or evidence-backed gates.
## Acceptance
- [ ] The `prj-` flavor has a durable canonical definition.
- [ ] State Hub has a complete disposition inventory.
- [ ] The information and extension architectures are reviewable.
- [ ] Each implementation stream has one local owner and workplan.
- [ ] Migration and retirement gates have measurable evidence requirements.