Accept ACT-ADR-005 and open ACTIVITY-WP-0026 for ops_run claim queue.
Split ops runs (claimable DB) from development work records (repo + State Hub), ban default Forgejo queueing for automation, and stack WP-0026 with rein-aharness and issue-core follow-ups. Forgejo-only forge language; no Gitea product path.
This commit is contained in:
parent
747d63a993
commit
d1e24348c3
4 changed files with 422 additions and 10 deletions
191
docs/adr/adr-005-ops-runs-vs-dev-work-records.md
Normal file
191
docs/adr/adr-005-ops-runs-vs-dev-work-records.md
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
---
|
||||
id: ACT-ADR-005
|
||||
type: architecture-decision-record
|
||||
title: "Ops runs vs development work records — claim queue and plane split"
|
||||
status: accepted
|
||||
decided_by: Bernd Worsch
|
||||
date: "2026-08-03"
|
||||
scope: cross-repo
|
||||
affects:
|
||||
- activity-core
|
||||
- rein-aharness
|
||||
- state-hub
|
||||
- issue-core
|
||||
- domain repos (Binky, freedom-intelligence, …)
|
||||
tags:
|
||||
- architecture
|
||||
- activity-core
|
||||
- ops-run
|
||||
- work-records
|
||||
- rein-aharness
|
||||
- issue-core
|
||||
- forgejo
|
||||
supersedes_notes: >
|
||||
Clarifies ACTIVITY-WP-0022 sink practice and G2 executor gap from
|
||||
ACTIVITY-WP-0023. Does not reverse WP-0022 (no default external tracker issues).
|
||||
---
|
||||
|
||||
# ACT-ADR-005: Ops runs vs development work records
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted** (2026-08-03).
|
||||
|
||||
## Context
|
||||
|
||||
The fleet has two healthy patterns that were forced into one vague “task” idea:
|
||||
|
||||
1. **Development / coordination work** — structured workplans and tasks as
|
||||
**repo files**, indexed by **State Hub** on **coulombcore** (`fix-consistency`,
|
||||
UUIDv7 write-back). This matches ADR-001 and
|
||||
`work-record-types_v0.1.md` and is how humans and coding agents ship product.
|
||||
|
||||
2. **Operations / scheduled automation** — activity-core Temporal schedules
|
||||
(when / what / where), rein-aharness execution (how), completion events
|
||||
(idempotence). Instances of “today’s FI brief” or “this prune fire” are
|
||||
**ephemeral runs**, not multi-day workplan bodies.
|
||||
|
||||
Practice collapsed (2) into broken paths:
|
||||
|
||||
| Path | Failure |
|
||||
| ---- | ------- |
|
||||
| Emit `activity_task_spawn` progress only | Append-only; **not claimable**; schedule can “succeed” while nothing runs |
|
||||
| `ISSUE_SINK_TYPE=rest` → issue-core → Forgejo | Spam + 503s; issue-core INTENT forbids origin of fleet work |
|
||||
| Host systemd timers dual-clocked with Temporal | Shadow scheduler; weak self-healing |
|
||||
|
||||
issue-core’s **correct** role is a **connector facade** over external trackers
|
||||
(Forgejo, GitHub, Jira, …) so agents need not know each backend. It is **not**
|
||||
the origin of work records and **not** the default internal ops queue.
|
||||
**Gitea is out of scope** for this fleet; the self-hosted forge is **Forgejo**.
|
||||
|
||||
Canon already allows a DB-only exception for “runtime operations data (logs,
|
||||
metrics, run histories, token events)” (`work-record-types_v0.1.md`). This ADR
|
||||
names that exception for **ops runs**.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Two planes for “work,” one vocabulary for people
|
||||
|
||||
| Plane | Artefact | Home | Lifecycle |
|
||||
| ----- | -------- | ---- | --------- |
|
||||
| **A — Development / coordination** | Work records (`workplan`, `task`, `intake`, …) | Repo files + State Hub (coulombcore) | File-backed, reviewable, multi-day |
|
||||
| **B — Recurrence control** | Activity definitions + Temporal schedules | activity-core (railiance) | Git definitions; DB schedule state |
|
||||
| **C — Ops execution** | **`ops_run`** (runtime claim object) | **activity-core DB + claim API** | open → claimed → succeeded \| failed \| expired |
|
||||
| **D — External collab** | Tracker issues | **issue-core** optional projection to **Forgejo** (and others) | Never default for internal automation |
|
||||
|
||||
Coding agents orient on **Plane A** via State Hub.
|
||||
Automation orients on **Planes B+C**.
|
||||
Humans outside the fleet may see **Plane D** only when deliberately projected.
|
||||
|
||||
### 2. activity-core owns the ops_run claim queue
|
||||
|
||||
When a definition emits a TaskSpec for internal fleet work:
|
||||
|
||||
1. Write **`ops_run`** row (durable, claimable) with idempotency key
|
||||
(e.g. `fi-daily:2026-08-04` for once-per-day briefs).
|
||||
2. Optionally dual-write `activity_task_spawn` progress for existing observers.
|
||||
3. Do **not** open a Forgejo issue.
|
||||
4. Do **not** create a workplan task file for that day’s fire.
|
||||
|
||||
Claim API (sketch; implement in ACTIVITY-WP-0026):
|
||||
|
||||
- `POST /ops-runs/claim` — lease next open run matching labels / worker id
|
||||
- `POST /ops-runs/{id}/complete` — succeeded + completion metadata
|
||||
- `POST /ops-runs/{id}/fail` — failed + retry policy
|
||||
- `GET /ops-runs?state=open` — operator visibility
|
||||
|
||||
activity-core remains **when / what / where** only: it does **not** run
|
||||
domain LLM sessions or hold tenant git credentials.
|
||||
|
||||
### 3. rein-aharness owns how (approach selection + execute)
|
||||
|
||||
- Continuous **claim loop** (service / Deployment), not dual wall-clock timers
|
||||
as source of truth.
|
||||
- Host systemd timers become **break-glass** after cutover.
|
||||
- **Approach selection** at claim time (minimal table v1):
|
||||
|
||||
| Labels / definition family | Approach |
|
||||
| -------------------------- | -------- |
|
||||
| mail / mail-intake | deterministic adapter (+ optional triage) |
|
||||
| research-brief / fi-daily | structured llm-connect (`fi-research-brief`) |
|
||||
| binky rhythm | structured llm-connect (`brief-daily`) |
|
||||
| agent-session | persona + tool profile session |
|
||||
| unknown | refuse; do not invent |
|
||||
|
||||
- Success posts **domain completion event** (e.g. `fi_daily_brief`) so
|
||||
resolvers set `due=false`, and closes the `ops_run`.
|
||||
|
||||
### 4. State Hub remains the work-record read model
|
||||
|
||||
- Stays on **coulombcore**; railiance peers via edge relay / ops-bridge.
|
||||
- May **project** open/failed ops runs for fleet ops UI (read-only), but is
|
||||
**not** the claim authority.
|
||||
- Development workplans/tasks continue file + `fix-consistency` only.
|
||||
|
||||
### 5. issue-core is Forgejo (and multi-tracker) facade only
|
||||
|
||||
- **Forgejo** is the self-hosted forge; do not plan for **Gitea** as a product.
|
||||
- Optional **project / link** of an existing work-record UUID to an external
|
||||
issue when collaboration needs it.
|
||||
- Authenticated `POST /issues/` means “create/link **external** tracker work,”
|
||||
never “spawn fleet automation.”
|
||||
- Internal automation **must not** use issue-core as the ops claim queue unless
|
||||
a future design adds an **internal-only** backend with projection **hard-off**
|
||||
for automation labels — out of scope unless a later ADR says otherwise.
|
||||
|
||||
### 6. Promotion path ops → dev
|
||||
|
||||
When an ops run discovers multi-day product work (e.g. “collect Kimi K3 under
|
||||
new quota”), the executor or human **promotes** an `intake` / workplan in the
|
||||
domain repo (Plane A). Ops runs never become permanent fake workplans.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Self-healing recurrence: schedule → claimable row → claim → complete/fail.
|
||||
- Aligns issue-core INTENT with practice; stops Forgejo spam path.
|
||||
- Keeps activity-core thin; keeps rein-aharness as sole session/credential shell.
|
||||
- Preserves the good dev loop (files + State Hub).
|
||||
|
||||
### Negative / cost
|
||||
|
||||
- New schema + API + migrator in activity-core.
|
||||
- rein-aharness must leave issue-core-only poll as primary for ops.
|
||||
- Temporary dual-write and dual timers until cutover proven.
|
||||
|
||||
### Non-goals
|
||||
|
||||
- Replacing workplans for development.
|
||||
- Running domain briefs inside activity-core workers.
|
||||
- Global `ISSUE_SINK_TYPE=rest` to Forgejo.
|
||||
- Gitea support or migration paths.
|
||||
|
||||
## Topology
|
||||
|
||||
```text
|
||||
coulombcore: State Hub + work-record registry
|
||||
railiance: activity-core (Temporal + ops_run queue)
|
||||
rein-aharness (claim loop + approach + llm-connect)
|
||||
domain checkouts
|
||||
forgejo: optional external collab via issue-core projection only
|
||||
```
|
||||
|
||||
## Implementation stack
|
||||
|
||||
| Workplan | Owner | Role |
|
||||
| -------- | ----- | ---- |
|
||||
| ACTIVITY-WP-0026 | activity-core | ops_run schema, claim API, emit path, dual-write |
|
||||
| REIN-A-0002 | rein-aharness | claim loop, approach table, FI/Binky cutover |
|
||||
| ISSUE-WP-0006 | issue-core | Forgejo-only language; projection boundary; no ops queue |
|
||||
| STATE-WP-0078 | state-hub | Read projection of ops_run for ops UI (optional consume) |
|
||||
|
||||
## References
|
||||
|
||||
- `docs/recurring-automations-playbook.md`
|
||||
- `docs/task-emission-consumer-contract.md`
|
||||
- `docs/issue-core-emission-boundary.md`
|
||||
- ACTIVITY-WP-0022, ACTIVITY-WP-0023 (G2)
|
||||
- `the-custodian/canon/standards/work-record-types_v0.1.md`
|
||||
- `issue-core/INTENT.md` (work-record boundary)
|
||||
- `state-hub/docs/cluster-operating-model.md` (coulombcore primary)
|
||||
|
|
@ -1,11 +1,17 @@
|
|||
# Recurring automations playbook — activity-core as the organizer
|
||||
|
||||
**Audience:** operators and coding agents adding or fixing recurring work
|
||||
**Principle:** activity-core answers **when / what / where** only. It does **not** execute.
|
||||
**Principle:** activity-core answers **when / what / where** only. It does **not** execute.
|
||||
**Architecture decision:** [ACT-ADR-005](adr/adr-005-ops-runs-vs-dev-work-records.md) —
|
||||
ops runs (claimable DB) vs development work records (repo files + State Hub).
|
||||
**Implementation stack:** ACTIVITY-WP-0026 · REIN-A-0002 · ISSUE-WP-0006 · STATE-WP-0078.
|
||||
|
||||
This is the org standard. Prefer this path over workstation cron, ad-hoc shell
|
||||
timers, or “I’ll remember to run it.”
|
||||
|
||||
**Self-hosted forge:** **Forgejo** only (not Gitea). External tickets via
|
||||
issue-core projection — never as the default ops claim queue.
|
||||
|
||||
---
|
||||
|
||||
## The three layers (do not collapse them)
|
||||
|
|
@ -86,15 +92,19 @@ kubectl -n activity-core exec deploy/actcore-worker -- python3 -c '...' # descr
|
|||
|
||||
Ops UI: `activity.coulomb.social` → automations status / trigger (SSO).
|
||||
|
||||
### C. Executor (rein-aharness)
|
||||
### C. Executor (rein-aharness) — target vs interim
|
||||
|
||||
1. Prefer a **named rein-aharness command** for the domain work
|
||||
(e.g. `brief-daily`, `fi-research-brief`) using **llm-connect**, not Claude CLI on railiance01
|
||||
2. Install **railiance user-systemd timer** in the domain repo
|
||||
(`scripts/railiance-rhythm/`) that calls rein-aharness
|
||||
3. Timer should sit **just after** the activity-core cron (due check already
|
||||
enforced by completion events on re-run)
|
||||
4. On success, post the **domain completion event** so the resolver sets `due=false`
|
||||
**Target (ACT-ADR-005 / REIN-A-0002):** continuous **claim loop** on
|
||||
`ops_run` rows from activity-core; approach table selects adapter
|
||||
(`fi-research-brief`, `brief-daily`, mail-scan, …).
|
||||
|
||||
**Interim (until WP-0026 + REIN-A-0002 cutover):** railiance user-systemd
|
||||
timer may call rein-aharness wall-clock — **break-glass / dual-clock**, not
|
||||
cadence authority.
|
||||
|
||||
1. Prefer a **named rein-aharness command** + **llm-connect**, not Claude CLI on railiance01
|
||||
2. On success, post the **domain completion event** so the resolver sets `due=false`
|
||||
3. Close the **ops_run** (when claim queue is live)
|
||||
|
||||
### D. Prove the loop
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue