From e7f615be38221e97270d3bb6182805e394fe126e Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 18 Aug 2026 10:27:29 +0200 Subject: [PATCH] docs: realign WP-0029 and boundaries with canon and nexus owners 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. --- .claude/rules/repo-boundary.md | 26 ++++- .claude/rules/stack-and-commands.md | 24 +++-- INTENT.md | 29 ++++-- SCOPE.md | 48 +++++---- .../ACTIVITY-WP-0026-ops-run-claim-queue.md | 4 +- .../ACTIVITY-WP-0029-hub-port-alignment.md | 97 +++++++++++++++---- 6 files changed, 163 insertions(+), 65 deletions(-) diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index 5086826..ecaf3f8 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -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 - diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index dc53ac6..0c5b04f 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,19 +1,25 @@ ## Stack - -- **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 ``` diff --git a/INTENT.md b/INTENT.md index ff5cb6c..d80c2c5 100644 --- a/INTENT.md +++ b/INTENT.md @@ -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. --- diff --git a/SCOPE.md b/SCOPE.md index ea1883b..de2789f 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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. --- diff --git a/workplans/ACTIVITY-WP-0026-ops-run-claim-queue.md b/workplans/ACTIVITY-WP-0026-ops-run-claim-queue.md index 30f5e72..209e4da 100644 --- a/workplans/ACTIVITY-WP-0026-ops-run-claim-queue.md +++ b/workplans/ACTIVITY-WP-0026-ops-run-claim-queue.md @@ -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 diff --git a/workplans/ACTIVITY-WP-0029-hub-port-alignment.md b/workplans/ACTIVITY-WP-0029-hub-port-alignment.md index cb29423..2119d7c 100644 --- a/workplans/ACTIVITY-WP-0029-hub-port-alignment.md +++ b/workplans/ACTIVITY-WP-0029-hub-port-alignment.md @@ -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"