coulomb/activity-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: realign WP-0029 and boundaries with canon and nexus owners
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details

Browse source 
Review ACTIVITY-WP-0029 against info-tech-canon, policy-nexus, and
State Hub retirement: activity-core keeps schedule and ops_run;
repo-manager owns consistency; hub-core owns progress ports.
Mark WP-0026 finished. Refresh INTENT, SCOPE, and repo-boundary.
This commit is contained in:
tegwick 2026-08-18 10:27:29 +02:00
parent 3a8fe6585a
commit e7f615be38
6 changed files with 163 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

26
.claude/rules/repo-boundary.md
View file

@ -1,8 +1,24 @@
## Repo boundary ## Repo boundary
This repo owns **activity-core** only. It does not own: This repo owns **activity-core** only: when / what / where — schedules,
ActivityDefinitions, rule/instruction evaluation, ops_run claim queue, and
bounded declared side-effects.
It does not own:
- Task / work-item vocabulary → `info-tech-canon` (Task Model)
- Responsibility / accountability / org roles → `info-tech-canon` (Organization Model)
- Policy *content* (canon, ADRs) → owning repo files
- Policy *publication* → `policy-nexus` (`policy.coulomb.social`)
- Regulatory intake / interpretation → `risk-nexus`
- Repo registry, C-rule consistency, work-record index → `repo-manager`
- Messages, progress projections, hub ports → `hub-core`
- Temporary compatibility routes → `state-hub` until STATE-WP-0079 retirement
- Issue lifecycle / external tracker mapping → `issue-core`
- AuthN / directory → `key-cape` / identity
- AuthZ decisions → `flex-auth`
- SSH certificates → `ops-warden` (`warden sign` only)
- Secrets / API keys → OpenBao (`railiance-platform`); route via `warden route`
- Tunnels → `ops-bridge`
- Domain work execution → per-repo workers / `rein-aharness` claiming ops_runs
<!-- TODO: List what belongs in adjacent repos, e.g.:
- SSH key management → railiance-infra/
- State hub code → state-hub/
-->

24
.claude/rules/stack-and-commands.md
View file

@ -1,19 +1,25 @@
## Stack ## Stack
<!-- TODO: Fill in language, frameworks, and key dependencies --> - **Language:** Python 3.11+
- **Language:** - **Key deps:** Temporal, FastAPI, SQLAlchemy/asyncpg, NATS, Alembic, Pydantic
- **Key deps:** - **Runtime:** railiance01 k3s (`activity-core` namespace); workstation CLI via `activity`
## Dev Commands ## Dev Commands
```bash ```bash
# TODO: Fill in the standard commands for this repo # Install / CLI
uv sync
make install-cli
# Install dependencies # Tests
make test
# Run tests # Definitions and schedules
make sync-activity-definitions
make sync-schedules
make sync-event-types
# Lint / type check # Status (local is degraded without prod DB; use prod helper for live)
make automation-status SINCE=sunday
# Build / package (if applicable) make prod-automation-status SINCE=sunday
``` ```

29
INTENT.md
View file

@ -1,7 +1,7 @@
--- ---
domain: capabilities domain: capabilities
repo: activity-core repo: activity-core
updated: "2026-07-21" updated: "2026-08-18"
--- ---
# INTENT # INTENT
@ -78,17 +78,28 @@ It is an event loop governed by declarative rules and LLM instructions:
| Concern | Owner | | Concern | Owner |
|---|---| |---|---|
| Task lifecycle (create, assign, track, close) | issue-core / work-record connectors (not default for internal findings) | | Task / work-item *semantics* (Task, Commitment, TaskState) | info-tech-canon (Task Model) |
| Project and initiative management | project-core (future) | | Who may act, who is responsible / accountable | info-tech-canon (Organization Model) |
| Policy *content* (canon, ADRs) | Owning repo; local files are source of truth |
| Policy *publication* (stable URLs, currency) | policy-nexus |
| Regulatory intake / interpretation | risk-nexus |
| Task lifecycle (assign, track, close) | issue-core / work-record connectors (not default for internal findings) |
| Repo registry, file↔index consistency, work-record index | repo-manager |
| Messages, progress projections, hub ports | hub-core (surviving runtime; core-hub absorbed via CORE-WP-0010) |
| Mixed coordination read model (until retirement) | state-hub (STATE-WP-0079 strangler; not a permanent peer) |
| Project and initiative management | `prj-*` repos + GOAL.md |
| Repository capability profiling | repo-scoping | | Repository capability profiling | repo-scoping |
| Cross-domain coordination state | state hub | | Execution of domain work | per-repo workers / rein-aharness claiming ops_runs |
| Execution of automatable tasks | Temporal workers (per-repo) |
| Event broker infrastructure | NATS (org infrastructure) | | Event broker infrastructure | NATS (org infrastructure) |
activity-core does not compete with the state hub — it extends it. The state activity-core does not compete with those owners. It **schedules and evaluates**;
hub is a read model of what is and has been; activity-core is the automation it reads org context and emits work or evidence into the owner that already has
layer that reacts to that state and creates new work. The state hub delegates that responsibility. State Hub is a compatibility read model on the way out
maintenance automation to activity-core by publishing lifecycle events on NATS. (`prj-state-hub-retirement`), not the permanent place coordination state lives.
Layout orientation for this repo itself follows the InfoTechCanon Repository
Layout recommendation (`INTENT` vs `SCOPE`, work in `workplans/`). Policy that
governs other repos is not published from here.
--- ---

48
SCOPE.md
View file

@ -1,7 +1,7 @@
--- ---
domain: capabilities domain: capabilities
repo: activity-core repo: activity-core
updated: "2026-07-21" updated: "2026-08-18"
--- ---
# SCOPE # SCOPE
@ -137,22 +137,20 @@ task execution. It must not expand into an unbounded ops executor.
--- ---
## Current State (2026-07-21) ## Current State (2026-08-18)
### Status ### Status
Production on **railiance01** (`activity-core` namespace). Recent finished Production on **railiance01** (`activity-core` namespace). Product work through
workplans: ACTIVITY-WP-0028 is finished. G2 (executor gap) is closed in-repo by
**ACT-ADR-005** + **ACTIVITY-WP-0026** (ops_run claim queue).
| WP | Outcome | Open work (SBOM catch-up parked — CUST-WP-0062 / ACTIVITY-WP-0030):
| --- | --- |
| ACTIVITY-WP-0018 | Own-infra automation status CLI |
| ACTIVITY-WP-0019 | Automation inventory targets |
| ACTIVITY-WP-0020 | Weekly Forgejo package prune **enabled**; first apply 38 deletes |
| ACTIVITY-WP-0021 | Prod reliability: state-hub sink, log_run-before-emit, schedule harden, DB probes, prod status path |
| ACTIVITY-WP-0006/0008 | Marked finished historically; enablement evidence has moved |
Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo). | WP | Status | Role |
| --- | --- | --- |
| **ACTIVITY-WP-0029** | ready | S5 of State Hub retirement: retarget sweeps/sinks/execution to repo-manager and hub-core |
| ACTIVITY-WP-0030 | proposed / parked | Daily bounded SBOM catch-up; wait on sbom-nexus |
### Live posture (railiance01) ### Live posture (railiance01)
@ -205,7 +203,7 @@ Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo
| Gap | Severity | Notes | | Gap | Severity | Notes |
| --- | --- | --- | | --- | --- | --- |
| **G1. Sink default vs INTENT “emit to issue-core”** | High (policy) | INTENT names issue-core as the task landing zone. Practice and work-record canon push **State Hub / repo work records** for internal findings. WP-0022 owns policy; code already supports `state-hub` / `null` / `rest`. | | **G1. Sink default vs INTENT “emit to issue-core”** | High (policy) | INTENT names issue-core as the task landing zone. Practice and work-record canon push **State Hub / repo work records** for internal findings. WP-0022 owns policy; code already supports `state-hub` / `null` / `rest`. |
| **G2. Executor gap** | High (value) → **in progress** | Disposition: **ACT-ADR-005** + **ACTIVITY-WP-0026** (ops_run claim queue) + **REIN-A-0002** (claim loop). Do not use issue-core/Forgejo as default ops queue (WP-0022). Host timers interim only. | | **G2. Executor gap** | Closed (in-repo) | **ACT-ADR-005** + **ACTIVITY-WP-0026** (ops_run claim queue). Claim loop remains **REIN-A-0002**. Do not use issue-core/Forgejo as default ops queue (WP-0022). |
| **G3. Side-effect resolvers** | Medium | Forgejo prune `apply: true` runs platform deletes inside a context resolver. Allowed only as declared, gated side-effect; needs clearer SCOPE language (above) and operator refresh of live-images protection. | | **G3. Side-effect resolvers** | Medium | Forgejo prune `apply: true` runs platform deletes inside a context resolver. Allowed only as declared, gated side-effect; needs clearer SCOPE language (above) and operator refresh of live-images protection. |
| **G4. Review queue** | Medium | `review_required` remains metadata-only; no downstream review queue. | | **G4. Review queue** | Medium | `review_required` remains metadata-only; no downstream review queue. |
| **G5. TaskExecutorWorkflow stub** | Low | Disabled unless `ACTIVITY_CORE_ENABLE_TASK_EXECUTOR_STUB` (WP-0023-T08). | | **G5. TaskExecutorWorkflow stub** | Low | Disabled unless `ACTIVITY_CORE_ENABLE_TASK_EXECUTOR_STUB` (WP-0023-T08). |
@ -214,6 +212,7 @@ Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo
| **G8. Live-images hygiene** | Medium (ops) | Multi-cluster `live-images-all.txt` must be refreshed after deploys or prune can delete live tags (incident 2026-07-21, restored). `scripts/refresh_live_images.sh` (T04). | | **G8. Live-images hygiene** | Medium (ops) | Multi-cluster `live-images-all.txt` must be refreshed after deploys or prune can delete live tags (incident 2026-07-21, restored). `scripts/refresh_live_images.sh` (T04). |
| **G9. Evidence federation** | Low | Progress often lands on railiance01 edge/hub; workstation primary hub may not show the same feed without tunnel/outbox health. | | **G9. Evidence federation** | Low | Progress often lands on railiance01 edge/hub; workstation primary hub may not show the same feed without tunnel/outbox health. |
| **G10. API external access** | Done | WP-0025 finished: Traefik + Authelia SSO for ops + Temporal UI; LLDAP `activity-core-operators` (NK-WP-0021); port-forward break-glass only. | | **G10. API external access** | Done | WP-0025 finished: Traefik + Authelia SSO for ops + Temporal UI; LLDAP `activity-core-operators` (NK-WP-0021); port-forward break-glass only. |
| **G11. State Hub as permanent target** | High (retirement) | Sweeps, progress sinks, and `/execution/*` still assume State Hub. **ACTIVITY-WP-0029** retargets to repo-manager + hub-core. Do not add new State Hub authorities. |
### Drift risks ### Drift risks
@ -234,14 +233,18 @@ Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo
↓ ↓
[activity-core] Event type registry · rules · instructions · context resolvers [activity-core] Event type registry · rules · instructions · context resolvers
↓ ↓
[IssueSink: rest | state-hub | null] → issue-core or State Hub progress [IssueSink: rest | state-hub | null] → issue-core or hub-core progress (State Hub until cutover)
[report/evidence sinks] → State Hub / working memory [report/evidence sinks] → hub-core / working memory
[ops_run claim queue] → rein-aharness / per-repo executors
[bounded shell side-effects] → platform tools (e.g. package prune) [bounded shell side-effects] → platform tools (e.g. package prune)
``` ```
- **Upstream**: NATS, Temporal, PostgreSQL, State Hub, repo-scoping, llm-connect. - **Upstream**: NATS, Temporal, PostgreSQL, repo-manager / hub-core (State Hub
- **Downstream**: issue-core (optional), State Hub, platform tools, future until retirement), repo-scoping, llm-connect.
per-repo executors / agent-harness. - **Downstream**: issue-core (optional), hub-core progress, platform tools,
rein-aharness / per-repo executors claiming ops_runs.
- **Orientation (not runtime)**: info-tech-canon (task/org/governance
vocabulary), policy-nexus (publication of ADRs/canon — not authored here).
- **Ops**: railiance01 k3s; workstation status via SSH helper. - **Ops**: railiance01 k3s; workstation status via SSH helper.
--- ---
@ -260,11 +263,16 @@ Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo
## Related / Overlapping ## Related / Overlapping
- `info-tech-canon` — task / organization / governance vocabulary; repository layout.
- `policy-nexus` — publishes ADRs/canon; does not author them.
- `repo-manager` — repo registry, consistency engine, work-record index.
- `hub-core` — messages, progress projections, extension ports (core-hub absorbed later).
- `state-hub` — compatibility read model until STATE-WP-0079 retirement.
- `issue-core` — task connector / external tracker mapping (not fleet work-record origin). - `issue-core` — task connector / external tracker mapping (not fleet work-record origin).
- `repo-scoping`, State Hub / the-custodian, `llm-connect`, `agent-harness`. - `repo-scoping`, `llm-connect`, `rein-aharness`.
- `railiance-platform` — Forgejo package prune tool and credential lanes. - `railiance-platform` — Forgejo package prune tool and credential lanes.
- `ops-warden` — credential routing (not secret vending for non-SSH). - `ops-warden` — credential routing (not secret vending for non-SSH).
- `project-core` (future), `ops-bridge` tunnels. - `ops-bridge` tunnels.
--- ---

4
workplans/ACTIVITY-WP-0026-ops-run-claim-queue.md
View file

@ -4,12 +4,12 @@ type: workplan
title: "Ops run claim queue — durable claimable work for scheduled automation" title: "Ops run claim queue — durable claimable work for scheduled automation"
domain: infotech domain: infotech
repo: activity-core repo: activity-core
status: done status: finished
owner: grok owner: grok
topic_slug: activity-core topic_slug: activity-core
priority: high priority: high
created: "2026-08-03" created: "2026-08-03"
updated: "2026-08-03" updated: "2026-08-18"
depends_on: [] depends_on: []
related: related:
- ACT-ADR-005 - ACT-ADR-005

97
workplans/ACTIVITY-WP-0029-hub-port-alignment.md
View file

@ -4,18 +4,23 @@ type: workplan
title: "Hub port and schedule alignment for State Hub retirement" title: "Hub port and schedule alignment for State Hub retirement"
domain: infotech domain: infotech
repo: activity-core repo: activity-core
status: proposed status: ready
owner: codex owner: grok
topic_slug: infotech topic_slug: infotech
created: "2026-08-09" created: "2026-08-09"
updated: "2026-08-09" updated: "2026-08-18"
parent_project: prj-state-hub-retirement parent_project: prj-state-hub-retirement
parent_workplan: SHR-WP-0001 parent_workplan: SHR-WP-0001
stream: S5
related: related:
- ACTIVITY-WP-0015 - ACTIVITY-WP-0015
- ACTIVITY-WP-0017 - ACTIVITY-WP-0017
- ACTIVITY-WP-0026
- HUB-WP-0004 - HUB-WP-0004
- RMGR-WP-0001
- STATE-WP-0079 - STATE-WP-0079
- CORE-WP-0010
- SHR-ARCH-HUB-0001
state_hub_workstream_id: "1b18849c-db3a-40a0-8f22-7af7fd4dbcfc" state_hub_workstream_id: "1b18849c-db3a-40a0-8f22-7af7fd4dbcfc"
--- ---
@ -23,11 +28,52 @@ state_hub_workstream_id: "1b18849c-db3a-40a0-8f22-7af7fd4dbcfc"
## Goal ## Goal
Align activity-core sweeps, sinks, and execution with **hub-core ports** and Align activity-core **schedules, sinks, and the execution-queue boundary** with
**repo-manager** ownership so State Hub is no longer the permanent target for the post–State Hub owners so this repo stays the Event Bridge (when / what /
automation. where) and does not absorb work that now has a clearer home.
## Map current State Hub / core-hub callers Reviewed 2026-08-18 against `prj-state-hub-retirement` (SHR-ARCH-HUB-0001,
SHR-INV-0001, child-workplan map S5), `repo-manager` INTENT,
`info-tech-canon` (Task / Organization / Governance / Repository Layout),
and `policy-nexus` INTENT.
## Responsibility map
activity-core **owns** schedule fire, rule/instruction evaluation, bounded
declared side-effects, spawn/run evidence, and the **ops_run claim queue**
(ACTIVITY-WP-0026). It does not own the things it currently *calls*.
| Concern | Owner | activity-core role |
| --- | --- | --- |
| Cron / event / one-shot fire | **activity-core** | Authority |
| Ops-run claim / lease | **activity-core** | Authority (not a task database) |
| Work-item semantics (Task, Commitment, TaskState) | **info-tech-canon** | Consume vocabulary; do not redefine |
| Who is responsible / accountable | **info-tech-canon** Organization Model | Do not invent org roles here |
| Policy *content* (canon, ADRs) | Owning repo | Local files stay source of truth |
| Policy *publication* | **policy-nexus** | Do not publish or host policy |
| Regulatory interpretation | **risk-nexus** | Out of scope |
| Repo registry, file↔index consistency, work-record index | **repo-manager** | Schedule the sweep; do not own C-rules |
| Messages, progress projections, hub ports | **hub-core** (surviving runtime) | Sink / consume after HUB-WP-0004 |
| core-hub `/api/v2` | **CORE-WP-0010** → absorbed into hub-core | Temporary dual-run only |
| Issue projection | **issue-core** | Optional `ISSUE_SINK_TYPE=rest` |
| State Hub routes used today | **STATE-WP-0079** strangler | Compatibility until cutover |
Naming: **hub-core** is the surviving framework *and* runtime
(SHR-ARCH-HUB-0001). **core-hub** is the current production host to be
archived. Do not treat them as interchangeable, and do not add permanent
authorities on State Hub.
Inventory split that T02 must honour (`job:consistency-sweep-remote-all`):
activity-core **stays the executor**; the reconciliation engine **moves** to
repo-manager (`route:POST:/consistency/sweep/remote-all`, disposition `move`).
T04 is a **replace** of State Hub `/execution/*` onto activity-core. That is
**schedule / launch / ops_run** ownership, not workplan file authority (repos)
and not task lifecycle (issue-core / work records / ITC Task Model).
Out of this workplan: SBOM catch-up (CUST-WP-0062 / ACTIVITY-WP-0030, parked).
## Map current State Hub / hub-core callers
```task ```task
id: ACTIVITY-WP-0029-T01 id: ACTIVITY-WP-0029-T01
@ -36,8 +82,12 @@ priority: high
state_hub_task_id: "03021be2-5d60-455b-9c9c-b8681d65911c" state_hub_task_id: "03021be2-5d60-455b-9c9c-b8681d65911c"
``` ```
Inventory schedules, sinks, and context resolvers that call State Hub or core-hub Inventory schedules, sinks, and context resolvers that call State Hub or
APIs; tag each with target port (`port.schedule`, interaction sink, work index). core-hub APIs. For each caller record: current URL, SHR-INV item if any,
**target owner** (table above), and target port when HUB-WP-0004 has named it
(`port.schedule` is ours to consume, not to invent in hub-core).
Do not retarget a caller to activity-core just because we schedule it.
## Retarget consistency sweep ## Retarget consistency sweep
@ -48,20 +98,25 @@ priority: high
state_hub_task_id: "f8107e2b-ab1f-4a3b-9348-8d5dcfb647b4" state_hub_task_id: "f8107e2b-ab1f-4a3b-9348-8d5dcfb647b4"
``` ```
Plan and implement retarget of remote consistency sweep from State Hub-only Keep the activity-core schedule. Point the remote sweep at **repo-manager**
endpoints to repo-manager (or dual-run adapter) without losing C-rule coverage. (or the existing State Hub dual-run adapter until RMGR cutover) without losing
C-rule coverage. RMGR-WP-0001 is finished; do not re-implement consistency
inside this repo.
## Align ops evidence sink ## Align ops evidence sink
```task ```task
id: ACTIVITY-WP-0029-T03 id: ACTIVITY-WP-0029-T03
status: todo status: wait
priority: medium priority: medium
state_hub_task_id: "3fbadbfe-9107-4869-b53f-3b9b46e0555a" state_hub_task_id: "3fbadbfe-9107-4869-b53f-3b9b46e0555a"
``` ```
Ensure interaction-event sink follows consolidated hub-core runtime after Wait on **HUB-WP-0004** (ports still `proposed`) and the CORE-WP-0010
CORE-WP-0010 / HUB-WP-0004 cutover; update smokes. absorption path. Interaction-event / progress evidence follows the
**hub-core** runtime, not a permanent core-hub or State Hub host. Update
smokes when the port exists. Until then, keep the State Hub beachhead
(ACTIVITY-WP-0015) as the compatibility sink.
## Execution queue boundary ## Execution queue boundary
@ -72,12 +127,14 @@ priority: medium
state_hub_task_id: "a34b42c3-8a08-482b-936f-14675ee254ca" state_hub_task_id: "a34b42c3-8a08-482b-936f-14675ee254ca"
``` ```
Clarify workplan launch/execution ownership vs State Hub execution routes Document the contract first, then replace State Hub `/execution/*` callers
(inventory: replace → activity-core). Implement or document port contract. with activity-core (ops_run / launch), matching SHR-INV
`workplan-execution-queue`. Explicit non-goals: repo-manager work-record
index, issue-core lifecycle, ITC Task Model types, policy-nexus publication.
## Acceptance ## Acceptance
- [ ] Caller map complete - [ ] Caller map lists owner + current URL for every State Hub / core-hub call
- [ ] Sweep retarget plan or implementation evidenced - [ ] Sweep still fires from activity-core and hits repo-manager (or dual-run)
- [ ] Ops evidence sink aligned to hub-core - [ ] Evidence sink plan names hub-core as the permanent host; T03 stays wait until that port exists
- [ ] Execution boundary documented/implemented - [ ] Execution boundary is written so `/execution/*` cannot be read as "activity-core owns tasks"