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
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
<!-- TODO: Fill in language, frameworks, and key dependencies -->
- **Language:**
- **Key deps:**
- **Language:** Python 3.11+
- **Key deps:** Temporal, FastAPI, SQLAlchemy/asyncpg, NATS, Alembic, Pydantic
- **Runtime:** railiance01 k3s (`activity-core` namespace); workstation CLI via `activity`
## Dev Commands
```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
# Build / package (if applicable)
# Status (local is degraded without prod DB; use prod helper for live)
make automation-status SINCE=sunday
make prod-automation-status SINCE=sunday
```

29
INTENT.md
View file

@ -1,7 +1,7 @@
---
domain: capabilities
repo: activity-core
updated: "2026-07-21"
updated: "2026-08-18"
---
# INTENT
@ -78,17 +78,28 @@ It is an event loop governed by declarative rules and LLM instructions:
| Concern | Owner |
|---|---|
| Task lifecycle (create, assign, track, close) | issue-core / work-record connectors (not default for internal findings) |
| Project and initiative management | project-core (future) |
| Task / work-item *semantics* (Task, Commitment, TaskState) | info-tech-canon (Task Model) |
| 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 |
| Cross-domain coordination state | state hub |
| Execution of automatable tasks | Temporal workers (per-repo) |
| Execution of domain work | per-repo workers / rein-aharness claiming ops_runs |
| Event broker infrastructure | NATS (org infrastructure) |
activity-core does not compete with the state hub — it extends it. The state
hub is a read model of what is and has been; activity-core is the automation
layer that reacts to that state and creates new work. The state hub delegates
maintenance automation to activity-core by publishing lifecycle events on NATS.
activity-core does not compete with those owners. It **schedules and evaluates**;
it reads org context and emits work or evidence into the owner that already has
that responsibility. State Hub is a compatibility read model on the way out
(`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
repo: activity-core
updated: "2026-07-21"
updated: "2026-08-18"
---
# 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
Production on **railiance01** (`activity-core` namespace). Recent finished
workplans:
Production on **railiance01** (`activity-core` namespace). Product work through
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 |
| --- | --- |
| 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 work (SBOM catch-up parked — CUST-WP-0062 / ACTIVITY-WP-0030):
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)
@ -205,7 +203,7 @@ Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo
| 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`. |
| **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. |
| **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). |
@ -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). |
| **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. |
| **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
@ -234,14 +233,18 @@ Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo
↓
[activity-core] Event type registry · rules · instructions · context resolvers
↓
[IssueSink: rest | state-hub | null] → issue-core or State Hub progress
[report/evidence sinks] → State Hub / working memory
[IssueSink: rest | state-hub | null] → issue-core or hub-core progress (State Hub until cutover)
[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)
```
- **Upstream**: NATS, Temporal, PostgreSQL, State Hub, repo-scoping, llm-connect.
- **Downstream**: issue-core (optional), State Hub, platform tools, future
per-repo executors / agent-harness.
- **Upstream**: NATS, Temporal, PostgreSQL, repo-manager / hub-core (State Hub
until retirement), repo-scoping, llm-connect.
- **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.
---
@ -260,11 +263,16 @@ Open product/policy workplan: **ACTIVITY-WP-0022** (IssueSink no-default-Forgejo
## 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).
- `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.
- `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"
domain: infotech
repo: activity-core
status: done
status: finished
owner: grok
topic_slug: activity-core
priority: high
created: "2026-08-03"
updated: "2026-08-03"
updated: "2026-08-18"
depends_on: []
related:
- 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"
domain: infotech
repo: activity-core
status: proposed
owner: codex
status: ready
owner: grok
topic_slug: infotech
created: "2026-08-09"
updated: "2026-08-09"
updated: "2026-08-18"
parent_project: prj-state-hub-retirement
parent_workplan: SHR-WP-0001
stream: S5
related:
- ACTIVITY-WP-0015
- ACTIVITY-WP-0017
- ACTIVITY-WP-0026
- HUB-WP-0004
- RMGR-WP-0001
- STATE-WP-0079
- CORE-WP-0010
- SHR-ARCH-HUB-0001
state_hub_workstream_id: "1b18849c-db3a-40a0-8f22-7af7fd4dbcfc"
---
@ -23,11 +28,52 @@ state_hub_workstream_id: "1b18849c-db3a-40a0-8f22-7af7fd4dbcfc"
## Goal
Align activity-core sweeps, sinks, and execution with **hub-core ports** and
**repo-manager** ownership so State Hub is no longer the permanent target for
automation.
Align activity-core **schedules, sinks, and the execution-queue boundary** with
the post–State Hub owners so this repo stays the Event Bridge (when / what /
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
id: ACTIVITY-WP-0029-T01
@ -36,8 +82,12 @@ priority: high
state_hub_task_id: "03021be2-5d60-455b-9c9c-b8681d65911c"
```
Inventory schedules, sinks, and context resolvers that call State Hub or core-hub
APIs; tag each with target port (`port.schedule`, interaction sink, work index).
Inventory schedules, sinks, and context resolvers that call State Hub or
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
@ -48,20 +98,25 @@ priority: high
state_hub_task_id: "f8107e2b-ab1f-4a3b-9348-8d5dcfb647b4"
```
Plan and implement retarget of remote consistency sweep from State Hub-only
endpoints to repo-manager (or dual-run adapter) without losing C-rule coverage.
Keep the activity-core schedule. Point the remote sweep at **repo-manager**
(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
```task
id: ACTIVITY-WP-0029-T03
status: todo
status: wait
priority: medium
state_hub_task_id: "3fbadbfe-9107-4869-b53f-3b9b46e0555a"
```
Ensure interaction-event sink follows consolidated hub-core runtime after
CORE-WP-0010 / HUB-WP-0004 cutover; update smokes.
Wait on **HUB-WP-0004** (ports still `proposed`) and the CORE-WP-0010
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
@ -72,12 +127,14 @@ priority: medium
state_hub_task_id: "a34b42c3-8a08-482b-936f-14675ee254ca"
```
Clarify workplan launch/execution ownership vs State Hub execution routes
(inventory: replace → activity-core). Implement or document port contract.
Document the contract first, then replace State Hub `/execution/*` callers
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
- [ ] Caller map complete
- [ ] Sweep retarget plan or implementation evidenced
- [ ] Ops evidence sink aligned to hub-core
- [ ] Execution boundary documented/implemented
- [ ] Caller map lists owner + current URL for every State Hub / core-hub call
- [ ] Sweep still fires from activity-core and hits repo-manager (or dual-run)
- [ ] Evidence sink plan names hub-core as the permanent host; T03 stays wait until that port exists
- [ ] Execution boundary is written so `/execution/*` cannot be read as "activity-core owns tasks"