tegwick
e7f615be38
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.
6.9 KiB
| domain | repo | updated |
|---|---|---|
| capabilities | activity-core | 2026-08-18 |
INTENT
This file explains why activity-core exists — the problem it solves, the principle that governs its boundaries, and what it must never become.
Why it exists
As the Coulomb organization grows — more repositories, services, deployments, and domains — coordination work that used to happen informally in one person's head needs a structural home. Recurring maintenance tasks (dependency scans, SBOM audits, consistency checks) get forgotten or implemented as bespoke cron jobs scattered across services. Cross-domain events (a new repo registered, a CVE published, a deployment completed) need coordinated responses that no single repo is positioned to own.
activity-core exists so that the Coulomb org can respond to what is happening in a structured, auditable, and automation-ready way — without Bernd being the manual coordination layer.
The governing principle
activity-core answers three questions and only three:
- When — what triggers coordination work? (time, event, or one-off schedule)
- What — given current org context, what work must be created?
- Where — which repo, service, or agent should each work item land?
It does not execute the work. It does not track task lifecycle. It does not manage projects or campaigns. Those belong to other systems.
This constraint is intentional and load-bearing. An orchestrator that also stores task state, manages project phases, or executes work becomes a God object — the thing everything depends on and nobody can safely change. activity-core stays small and focused by refusing those responsibilities.
What it is
activity-core is the org-wide Event Bridge for the Coulomb organization.
It is an event loop governed by declarative rules and LLM instructions:
- Event sources: cron schedules, one-off future datetimes, NATS domain events (from the state hub, Gitea, Temporal, and other publishers), and inbound webhooks from external systems.
- Context resolution: before evaluating what to create, activity-core resolves current org state — repository profiles from repo-scoping, domain state from the state hub, and other context adapters.
- Rules and instructions: deterministic rules (Python-like expression DSL, evaluated by a sandboxed AST walker) handle cases where the right action is fully specifiable. LLM instructions handle cases where human-like judgement is needed to decide what tasks are appropriate. Both are defined as markdown files, co-located with their intent and debugging guidance (see ACT-ADR-002, ACT-ADR-003).
- Task / outcome emission: activations emit task specs and/or reports via a
configured sink. Internal fleet findings default to State Hub progress
(
activity_task_spawn) so they do not silently create Forgejo issues (ACTIVITY-WP-0022). OptionalISSUE_SINK_TYPE=restprojects to issue-core when an external tracker issue is intentionally desired. activity-core records the spawn event as an audit trail — not as the authoritative task record. Downstream executors (per-repo workers, agent-harness) perform the work.
What it is not
| Concern | Owner |
|---|---|
| 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 |
| Execution of domain work | per-repo workers / rein-aharness claiming ops_runs |
| Event broker infrastructure | NATS (org infrastructure) |
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.
What it enables
When activity-core is in place, Bernd can:
- Define a rule once — "every Monday, scan all Python repos for dependency drift and create a task for each one" — and trust it will run without manual intervention.
- Register an instruction — "when a new repo is registered in the
railiancedomain, determine the appropriate onboarding tasks based on its profile and domain standards" — and have an LLM agent make that judgement reproducibly. - Set up a one-off reminder — "on 2026-09-01, create a review task for the Q3 architecture retrospective" — without managing a separate reminder system.
- Observe a complete audit trail of every activation: what triggered it, what rules matched, what tasks were created, and (for instructions) what prompt and model produced the output.
The Coulomb org gains structured, auditable automation that scales with the number of repos and domains without scaling the coordination burden on Bernd.
Design values
Markdown-as-definition. Event types, ActivityDefinitions, and task templates are markdown files checked into repositories. Intent, schema, logic, and debugging notes live together. Agents and humans can read, write, and review them without specialist tooling.
Rules before instructions. Deterministic rules are always preferred over LLM instructions when the condition is fully expressible. Instructions are reserved for genuine judgement cases. This keeps most automation fast, cheap, testable, and auditable.
No task state ownership. activity-core holds a spawn audit trail, not task state. The moment it starts tracking whether tasks are complete, blocked, or re-assigned, it has become a task database — that belongs to issue-core or fleet work-record systems, not here.
Safe sinks for internal findings. Automated internal coordination must not default to silent Forgejo/Gitea issues. Prefer State Hub progress / work-record intake; reserve issue-core REST for explicit external projection.
Publisher-declared event governance. Producers of org events register their event types by committing definition files. Curator review is a configurable gate per environment — never a permanent bottleneck.