docs: write INTENT.md and rewrite SCOPE.md for Event Bridge architecture

INTENT.md: articulates why activity-core exists, the governing
three-question principle (when/what/where), what it is and is not,
and the design values (markdown-as-definition, rules before instructions,
no task state ownership, publisher-declared governance).

SCOPE.md: rewritten from stale pre-alpha state to reflect WP-0001/0002
completion and the ACT-ADR-001/002/003 architecture. Adds rule/instruction
model, event type registry, task emission adapter, webhook receiver, and
updated current state, terminology, and architecture decision references.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-14 16:56:07 +02:00
parent 617b2420d3
commit 91a9073448
2 changed files with 291 additions and 42 deletions

130
INTENT.md Normal file
View File

@@ -0,0 +1,130 @@
---
domain: capabilities
repo: activity-core
updated: "2026-05-14"
---
# 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 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 emission**: the output of every activation is a set of task creation
requests sent to issue-core via a task emission adapter. activity-core records
the spawn event (what was created, when, referencing the issue-core task ID)
as an audit trail — not as the authoritative task record.
---
## What it is not
| Concern | Owner |
|---|---|
| Task lifecycle (create, assign, track, close) | issue-core |
| Project and initiative management | project-core (future) |
| Repository capability profiling | repo-scoping |
| Cross-domain coordination state | state hub |
| Execution of automatable tasks | Temporal workers (per-repo) |
| 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.
---
## 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 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 — and that is issue-core's job.
**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.