@ -127,7 +127,7 @@ The Goals page groups everything by domain:
Workplans carry an optional `repo_goal_id` field. Setting it traces *why* a workplan exists — which specific repo goal it contributes to. This connection is currently recorded in the DB but is not yet visualised in the Workplans page.
To set the link when creating a workplan through the preferred API, pass `repo_goal_id`. To update an existing one, use `PATCH /workplans/{id}/` with `{"repo_goal_id": "<uuid>"}`. The legacy `create_workstream` tool is removed and `/workstreams/{id}` returns 410; use `create_workplan` and `/workplans/{id}`.
To set the link when creating a workplan through the preferred API, pass `repo_goal_id`. To update an existing one, use `PATCH /workplans/{id}/` with `{"repo_goal_id": "<uuid>"}`. Legacy `create_workstream` and `/workstreams/{id}/` callers remain compatibility-supported while they are metered.
| 2026-09-04 17:21:25.339 | Claude agent, fluid-telegram | Task query with legacy `workstream_id`, targeting `f2373858-c932-5a4d-81b6-db9a3595135a` | Actual command in session history; within four seconds of meter last_seen 17:21:29.173850. Strong correlation, not request-ID proof. AGENTS.md now prescribes canonical query and `X-StateHub-Component: fluid-telegram` |
| 2026-08-29 12:57:27.083 | Claude agent, ops-warden | Task query with legacy `workstream_id`, targeting `ae3ff76f-883d-5e2f-b6aa-144d61e8fdef` | Actual command in session history. AGENTS.md now prescribes canonical query and `X-StateHub-Component: ops-warden` |
The near-term executable surface is therefore **A1 + A2, not 165 items**, and
A2 is the only slice with a proven adapter.
**A3 is not the low-blast-radius first cut this plan originally recommended** —
it is the least ready slice in Wave A. The recommendation is withdrawn.
**Do not build the register surface in State Hub.** New register capability here
would be new permanent ownership in the component being retired, which
`policies/retirement-freeze.md` makes inadmissible. A3/A4/A5 need a
`repo-manager` workplan; RMGR-WP-0004 (standards conformance) and RMGR-WP-0005
(registrar consolidation) do not cover them.
### Owner readiness refresh (2026-08-31)
The original readiness table is retained above as planning history. Current
workplan status changes which owners can receive a slice, but it does not count
as State Hub cutover evidence by itself:
| Owner | Current owner evidence | State Hub cutover consequence |
| --- | --- | --- |
| `repo-manager` | RMGR-WP-0005 finished deterministic identifier migration; RMGR-WP-0008 finished register/classification surfaces | Receiving-side identity and register gates are satisfied; each State Hub writer/read switch still needs its own parity and rollback receipt. |
| `hub-core` | HUB-WP-0005 finished and its production runtime owns all declared hub-core route/writer groups with exercised rollback | Receiving runtime is available; B1-B5 are not complete until State Hub caller/route switches and counts are evidenced. |
| `activity-core` | ACTIVITY-WP-0029 finished schedule, sweep, interaction-event, and execution-boundary work | The launch-request defect is retired; remaining C-slice caller switches still require explicit evidence. |
| `ops-hub` | OPS-WP-0003 finished; owner package and implemented conformance profile pass | D1 receiving-side gate is satisfied. State Hub route/caller switch, count parity, rollback, and writer authorization remain cutover evidence. |
| `fin-hub` | FIN-WP-0003 remains `proposed`; 0/3 tasks done | D2 cannot move. Do not implement the fabric authority contract here. |
| `archive` | 2026-08-31 central meter: 6 newly retired, 9 legacy, 0 candidates | E2/E4 remain gated; live callers and volume-scaled quiet windows prohibit retirement. |
Accordingly, `STATE-WP-0079-T04` is waiting on the missing owner workplans,
the still-unrecorded State Hub route-switch receipts, and explicit production
writer-cutover authorization. `T05` waits on fresh central meter evidence, and
`T06` cannot begin while State Hub remains the healthy, active `railiance01`
primary.
## Adapter mechanism
Wave A reuses the dual-run strangler proven in RMGR-WP-0002/0003 rather than
| D3 | `the-custodian` | `kaizen-agents` (2) | 2 | none — can go anytime |
D3 is two MCP tools with no dependants; take it opportunistically.
## Wave E — retire (42 items)
| Slice | Capability | Items | Gate |
| --- | --- | --- | --- |
| A1 registry / 27 | Repo Manager observation/scaffolding; STATE-WP-0081 and 0086 establish forge-derived projection | `rmgr sync` verified pushed commit `74a3b22` on primary/railiance01 in the preceding session | Inventory remaining registry callers per endpoint. Keep current projection while proving the owner read; do not restore checkout mutation in central |
| A2 work records / 59 | RMGR-WP-0008 implements file-backed workplan, intake, decision, dependency and task mutations; RMGR-WP-0005 identifiers finished | Repository files + `rmgr sync` are the current write convention. Two ad-hoc task-filter callers identified and guidance corrected in this review | Work-record caller inventory and per-kind writer receipts still required. Revert source commit and reconcile for a reviewed rollback; no second file authority |
| A3 registers / 49 | RMGR-WP-0008 register spine; **SBOM Nexus** is the current SBOM product owner | Live State Hub config uses Nexus for both SBOM reads/writes. Direct Nexus licence and snapshot reads return 200. Two more compatibility interfaces retired in the meter September 5 | Other registers need individual caller/parity receipts. Preserve SBOM history; remaining `/sbom/` traffic and retained compatibility handlers prevent deleting the whole router |
| A4 work/repo UI / 22 | hub-core projection + UI clients; RMGR-ADR-003 excludes a Repo Manager dashboard | No complete State Hub UI redirect receipt established | First prove backing reads; rollback redirects to the retained UI |
| A5 topic spine / 8 | Published Repo Manager classification contract, accepted by HUB-WP-0004 | No complete State Hub caller-switch receipt established | Prove deployed consumer contract and parity; retain source-backed classification projection |
| B1 catalogs / 34 | HUB-WP-0004/0005 receiving architecture and `/api/v2` absorption | Completion covers the Core Hub route groups, not every State Hub capability/registry route | Map each State Hub catalog to a deployed endpoint and migration receipt |
| B2 messaging/interface log / 22 | Shared `hub_core.routers.messages` exists; State Hub interface log is a separate family | Live Hub Core OpenAPI has **no `/messages` or `/interface-changes`**. `/api/v2/interaction-events` exists but is not asserted equivalent | **Next bounded read slice:** STATE-WP-0079-T08. Owner must expose/identify the message read contract and history projection before a parity run or switch. Retain current reads/writer |
| B3 telemetry / 32 | Shared `hub_core.routers.progress` exists; token/software catalogs need separate mappings | Live Hub Core OpenAPI has **no `/progress` or `/token-events`** | Owner runtime assembly/mapping plus historical identity/count parity; writer exclusivity and rollback receipts remain necessary |
| B4 projection/policy / 20 | HUB-WP-0004/0005; policy publication belongs to policy-nexus | State Hub still serves its projection routes; no full family receipt established | Map individual projections and policy publication; retain source/runtime boundaries and current reads |
| B5 hub UI / 17 | Hub Core runtime/console exists | Core Hub absorption does not establish replacement of State Hub dashboard pages | Prove A4/B1–B4 data contracts before redirect; retain UI rollback |
| C1 execution / 13 | ACTIVITY-WP-0029 finished; Activity Core owns scheduling/ops_run | STATE-WP-0079 records launch-request rejection (410), replacement semantics, and corrected unconsumed requests | Verify every remaining execution caller uses the owner contract. Do not revive the obsolete launch queue for rollback |
| C2 jobs / 5 | ACTIVITY-WP-0029 finished; scheduler is Activity Core, reconciliation engine is Repo Manager | Receiving/sweep handoffs recorded in owner workplan | Attach remaining per-job deployment and caller receipts; keep scheduler ownership distinct from work-record authority |
| D1 service catalog / 11 | OPS-WP-0003 finished; reviewed packages and `/api/v2` conformance gate | Owner contract completion established; State Hub family-switch receipt still missing | Compare catalog identities and UI bindings; preserve current reads until switched |
| D2 Fabric / 10 | **railiance-fabric** authority, FIN-WP-0003 consumer gate | August 31 dual-read import: 131 nodes/117 edges; green hash/count/provenance checks, rollback and roll-forward exercised | Hosted runtime/persistence/auth/freshness remains RAIL-FAB-WP-0028 (`proposed`). Keep retained import rollback; do not claim the local authority is a hosted production receiver |
| D3 kaizen / 2 | the-custodian, original two-tool disposition | No fresh removal/delegation receipt collected in this review | Locate current tools/consumers and owner contract before removal |
| E1 suggestions / 17 | Archived history in the-custodian | STATE-WP-0079 records eight read routes at 410, six MCP tools removed, dashboard removed | Completed surface removal; tables retained for final dump |
| E2 legacy workplans / 13 | Preferred `/workplans` routes and `workplan_id` parameters | Workstream REST handlers return 410 and meter rejected calls. Task query alias still accepted | Seven legacy meter records remain after today's two SBOM retirements; observe volume-scaled quiet periods and complete T07 attribution |
| E3 UI feedback / 1 | State Hub until cutover | Feedback still needed during transition | T06 zero-normal-traffic gate; do not confuse it with retired suggestions |
| E4 meter / 9 | State Hub until all other retirement evidence complete | Eight retired / seven legacy interfaces, zero current candidates after September 5 action | Retire last, after the remaining interfaces and final evidence are closed |
description: Coordinate repository-backed work through State Hub REST or optional MCP, including canonical workplan reads, inbox checks, task status sync, and progress logging.
description: Use when coordinating with Custodian State Hub: orienting with domain summaries, checking agent inbox messages, updating workplan-backed task status, recording decisions/progress, or batching task status sync through MCP/REST without re-discovering tool schemas.
---
# State Hub Coordination
@ -11,32 +11,21 @@ work structure in the hub when a workplan file is the canon.
## Session Flow
1. Prefer REST/`statehub` for Codex. Verify `/state/health` identifies the expected
primary, then read `/workplans/` with repo/topic filters. MCP is opt-in; use
`get_domain_summary(domain_slug)` when enabled.
1. Orient with `get_domain_summary(domain_slug)` when working inside one domain
repo. Use `get_state_summary()` only for cross-domain/custodian-wide work.
2. Check inbox with `get_messages(to_agent=<repo-slug>, unread_only=true)`.
Mark acted-on messages with `mark_message_read(message_id)`.
3. During work, edit the workplan file first. Use `workplan_id` in API payloads
and task queries; legacy `workstream_id` is accepted only for compatibility.
3. During work, edit the workplan file first. Mirror task/workstream status to
the hub at checkpoints.
4. Prefer `bulk_update_task_statuses(...)` for checkpoint syncs with multiple
task updates. Use `update_task_status(...)` for one-off changes.
5. Close with one concise progress event. After committing workplan file changes,
run `uv run --project ~/repo-manager rmgr sync --path . --push`. Reserve
`statehub fix-consistency` for a separate deep audit.
5. Close with one concise `add_progress_event(...)`, then run the repo's
`make fix-consistency REPO=<repo-slug>` command when workplan files changed.
6. If finishing a workplan with leftovers: create **residual** work records
first (intake with `origin: residual` + `origin_ref: <WP-id>`, or a child
workplan). Residual is a role, not a kind; do not leave backlog only in
finished-file prose or `SCOPE.md`. Canon: work-record-types § Residuals.
## Canonical reads and caller attribution
Use `GET /workplans/{id}` and `GET /tasks/?workplan_id=<id>`.
The `/workstreams/` REST routes return 410 and the `create_workstream` MCP tool
has been removed. Create repository-owned records in files before syncing.
For direct HTTP calls, send `X-StateHub-Component: <repo-slug>` so a remaining
legacy call can be attributed to its caller. Do not replace authoritative
`state_hub_workstream_id` frontmatter fields; those are a separate file contract.