activity-core/INTENT.md

---
domain: capabilities
repo: activity-core
updated: "2026-08-23"
---

# 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:

1. **When** — what triggers coordination work? (time, event, or one-off schedule)
2. **What** — given current org context, what work must be created?
3. **Where** — which repo, service, or agent should each work item land?

It does not execute general domain work. It does not track workplan, tracker,
or human task lifecycle. It does not manage projects or campaigns. Those belong
to other systems.

Two narrow runtime mechanisms support the three answers without adding a
fourth responsibility:

- an `ops_run` is a durable delivery record for one automation fire. Its
  open/claim/lease/outcome state is runtime operations data, not a Task,
  Commitment, assignment, or project record; and
- a code-registered **bounded operation** may perform the declared maintenance
  outcome directly only under ACT-ADR-007: fixed/bounded targets, explicit
  mutation intent, operation-specific idempotency/retry rules, routed
  credentials, and mandatory non-secret evidence.

Neither mechanism is permission to accept arbitrary commands, execute agent
loops, edit repositories, or grow task/project semantics here.

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). Optional `ISSUE_SINK_TYPE=rest` projects 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.
- **Runtime delivery**: internal automation work may also be represented by a
  claimable `ops_run`. activity-core owns its delivery lease and normalized
  outcome evidence, while Glas/reins or per-repo workers perform the domain
  work.
- **Bounded operations**: a small code-owned registry permits maintenance whose
  whole purpose is a fixed, reviewable operation such as controlled SBOM ingest,
  package retention, or backup. Context resolution remains read-only; the
  mutation runs in an explicit workflow stage governed by ACT-ADR-007.

---

## 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 |
| General execution of domain work | Glas/reins and per-repo workers claiming `ops_runs` |
| Bounded maintenance operation implementation | activity-core only for ACT-ADR-007 registered operations; otherwise platform owner |
| 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 `railiance`
  domain, 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 bounded, non-secret audit trail of every activation: what triggered
  it, what definition version and context were used, what rules matched, what
  outputs were emitted, and (for instructions) the model, validation result,
  and SHA-256 hash of the rendered prompt. The hash is an integrity reference,
  not storage or guaranteed reconstruction of the raw prompt.

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 work-item state ownership.** activity-core holds spawn audit plus runtime
delivery state for `ops_runs`, not Task/Commitment state. The moment it starts
tracking whether workplan or tracker tasks are assigned, blocked, completed,
dependent, or re-assigned, it has become a task database — that belongs to
issue-core or fleet work-record systems, not here.

**Explicit bounded operations only.** Context adapters read. A mutation may run
only through the ACT-ADR-007 registry and workflow phase; unknown operation
names and incomplete safety declarations fail during definition admission.

**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.