chore(workplan): stub CUST-WP-0040 state hub NATS / activity-core integration

Workplan for delegating maintenance automation from the state hub to activity-core via NATS JetStream. Covers NATS publisher wiring, subject schema, lifecycle event emission, cron migration stubs, and delegation protocol docs. Hub workstream: d8ac100b-a844-46a5-9684-415df0d32539 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-14 18:12:29 +02:00
parent 49f329af82
commit ee63051a50
1 changed files with 170 additions and 0 deletions
--- a/workplans/CUST-WP-0040-state-hub-nats-activity-core-integration.md
+++ b/workplans/CUST-WP-0040-state-hub-nats-activity-core-integration.md
@@ -0,0 +1,170 @@
+---
+id: CUST-WP-0040
+type: workplan
+domain: custodian
+repo: the-custodian
+status: active
+state_hub_workstream_id: d8ac100b-a844-46a5-9684-415df0d32539
+tasks:
+  - id: T01
+    title: Connect state hub event publisher to NATS JetStream
+    state_hub_task_id: c4bfa299-0000-0000-0000-000000000000
+    status: todo
+  - id: T02
+    title: Define NATS subject schema for state hub lifecycle events
+    state_hub_task_id: 2ae236a4-0000-0000-0000-000000000000
+    status: todo
+  - id: T03
+    title: Implement state hub lifecycle events as NATS EventEnvelopes
+    state_hub_task_id: ccb5a3fb-0000-0000-0000-000000000000
+    status: todo
+  - id: T04
+    title: Migrate state hub maintenance crons to activity-core ActivityDefinitions (design stub)
+    state_hub_task_id: 933b2a80-0000-0000-0000-000000000000
+    status: todo
+  - id: T05
+    title: Document state hub → activity-core delegation protocol
+    state_hub_task_id: b261d4b8-0000-0000-0000-000000000000
+    status: todo
+  - id: T06
+    title: Update SCOPE.md to reflect activity-core delegation
+    state_hub_task_id: 356682e6-e608-4f58-b418-cdef2b9435f2
+    status: todo
+created: "2026-05-14"
+---
+
+# CUST-WP-0040: State Hub NATS / Activity-Core Integration
+
+## Purpose
+
+The Custodian State Hub currently runs bespoke maintenance cron jobs and
+ad-hoc event handling internally. With activity-core established as the
+org-wide Event Bridge, the state hub should delegate maintenance automation
+to activity-core by publishing lifecycle events on NATS JetStream — rather
+than implementing task creation itself.
+
+This workplan makes the state hub an event *publisher* and removes it from
+the task-generation business. The result: maintenance automations are governed
+by ActivityDefinitions in activity-core (auditable, rule-based, testable)
+rather than scattered cron code in the-custodian.
+
+## Context
+
+- **activity-core** (WP-0003 in progress): event loop that receives NATS events
+  and evaluates rules/instructions to create tasks in issue-core.
+- **State hub**: tracks domain state, workstreams, decisions, and progress events.
+  It knows when things happen (repo registered, workstream completed, stale task).
+- **The gap**: the state hub knows about org events but has no way to publish them
+  to NATS so that activity-core can react. This workplan closes that gap.
+
+See: `docs/adr/adr-001-event-bridge-architecture.md` in activity-core for the
+delegation protocol design.
+
+## Scope
+
+**In scope:**
+- NATS JetStream publisher client in the state hub
+- EventEnvelope schema for state hub lifecycle events
+- NATS subject naming convention for state hub events
+- Design stub for migrating existing maintenance crons to ActivityDefinitions
+- Protocol documentation
+
+**Out of scope:**
+- activity-core rule/instruction implementation (lives in activity-core WP-0003)
+- Removing existing state hub crons before activity-core is ready (sequencing risk)
+- project-core (future)
+
+## Tasks
+
+### T01 — Connect state hub event publisher to NATS JetStream
+
+Add a NATS JetStream publisher client to the state hub. It should:
+- Connect to the NATS server on startup (use existing NATS config pattern)
+- Expose a `publish_event(envelope: EventEnvelope)` function
+- Be disabled/no-op when `NATS_URL` is not set (for environments without NATS)
+- Log publish success/failure with event ID
+
+**Key file**: `state_hub/events/nats_publisher.py` (new)
+
+### T02 — Define NATS subject schema for state hub lifecycle events
+
+Document and agree on the NATS subject naming convention for state hub events.
+Proposed pattern: `org.statehub.{noun}.{verb}` — e.g.:
+- `org.statehub.repo.registered`
+- `org.statehub.workstream.completed`
+- `org.statehub.task.stale`
+- `org.statehub.domain.goal.activated`
+
+Write the subject schema as a section in `docs/nats-event-subjects.md`.
+Cross-reference with activity-core's event-types registry.
+
+### T03 — Implement state hub lifecycle events as NATS EventEnvelopes
+
+Wire the NATS publisher into state hub write operations. Candidate events:
+- `org.statehub.repo.registered` — when a repo is registered in the hub
+- `org.statehub.workstream.completed` — when a workstream status → completed
+- `org.statehub.task.stale` — periodic check, tasks not updated in 14+ days
+
+Each event must conform to the EventEnvelope schema defined in activity-core's
+event type registry. Write a stub event type definition file in activity-core
+at `event-types/org.statehub.repo.registered.md` (or coordinate with the
+activity-core agent to do so).
+
+### T04 — Migrate state hub maintenance crons to activity-core ActivityDefinitions (design stub)
+
+**Design stub only — not yet implemented.**
+
+List the existing maintenance cron jobs in the state hub codebase. For each:
+- Identify the equivalent ActivityDefinition trigger (cron expression, event type)
+- Draft the rule/instruction that would replace the cron logic
+- Note any context sources required (state hub API, repo-scoping)
+- Flag blockers (e.g., activity-core WP-0003 phase not yet complete)
+
+Output: a markdown table in this workplan and/or in `docs/cron-migration.md`.
+
+### T05 — Document state hub → activity-core delegation protocol
+
+Write `docs/activity-core-delegation.md` explaining:
+- Why state hub delegates maintenance automation to activity-core
+- Which lifecycle events the state hub publishes and why
+- How activity-core ActivityDefinitions react (cross-reference WP-0003)
+- What remains in the state hub vs. what moves to ActivityDefinitions
+- Operational checklist: what to verify when a maintenance cron is being migrated
+
+### T06 — Update SCOPE.md to reflect activity-core delegation
+
+Update the state hub's SCOPE.md (or write one if missing):
+- Add activity-core as a downstream consumer of state hub lifecycle events
+- Clarify that maintenance task creation moves to activity-core
+- Note that the state hub remains the authoritative *read model* (not a task factory)
+
+## Build Order
+
+```
+T01 (NATS publisher) → T03 (wire events)
+T02 (subject schema) → T03
+T03 → T04 (migration stub, requires events to exist)
+T04 → T05 (docs, requires migration list)
+T06 (independent — SCOPE.md update)
+```
+
+## Completion Criteria
+
+1. State hub publishes at least one lifecycle event type to NATS on relevant writes
+2. Subject naming convention documented and agreed with activity-core team
+3. Migration stub completed — all existing crons listed with ActivityDefinition drafts
+4. Delegation protocol documented
+5. SCOPE.md updated
+
+## Notes
+
+- **Sequencing**: complete T01–T03 before activity-core WP-0003 is done, so the
+  first ActivityDefinitions that consume state hub events can be tested end-to-end.
+- **No removal yet**: do not remove existing state hub crons until activity-core
+  ActivityDefinitions are validated in staging. Run both in parallel initially.
+- The state hub must never write directly to activity-core's database — only via NATS.
+
+## Change History
+
+- v0.1 (2026-05-14): Stub created by activity-core agent during WP-0003 planning.
+  Local agent to flesh out and implement.