<divclass="wrap"><header><divclass="eyebrow"><span>ACT-ADR-002</span><spanclass="stat">accepted · accepted-2</span><span>activity-core</span><span>reviewed 2026-05-14</span><span>generated from canonical source — do not edit</span></div><h1>Markdown-as-Definition Format for Event Types and ActivityDefinitions</h1><pclass="sub">Source: <code>activity-core · docs/adr/adr-002-definition-format.md · b72fdb5452bff51a867a0316edb994723b35f268</code></p><pclass="sub">Review due: 2026-11-14</p></header><divclass="layout"><navclass="rail"aria-label="Sections"><ol><li><ahref="#status"><spanclass="n">·</span>Status</a></li><li><ahref="#context"><spanclass="n">·</span>Context</a></li><li><ahref="#decision"><spanclass="n">·</span>Decision</a></li><li><ahref="#consequences"><spanclass="n">·</span>Consequences</a></li><li><ahref="#alternatives-considered"><spanclass="n">·</span>Alternatives Considered</a></li><li><ahref="#related"><spanclass="n">·</span>Related</a></li></ol></nav><main><sectionid="status"><h2>Status</h2>
<p>Event type schemas and ActivityDefinition rules need to be understood and authored by three distinct audiences simultaneously: humans reviewing and debugging automation, agents creating and modifying definitions at runtime, and machines parsing and evaluating them. Traditional approaches split these concerns — schemas go in JSON Schema or YAML, documentation goes in a wiki, logic goes in code — and they drift apart. A bug in a rule requires cross-referencing three places to understand intent, check the schema, and read the condition.</p>
<p>The Custodian ecosystem already uses markdown files with YAML frontmatter as the authoritative format for workplans, ADRs, SCOPE.md, and INTENT.md — all understood by humans and agents without additional tooling. The same pattern should apply here.</p>
</section>
<sectionid="decision"><h2>Decision</h2>
<p><strong>Event type definitions and ActivityDefinitions are markdown files</strong> where machine- parseable structure (frontmatter YAML and fenced definition blocks) is embedded within human-readable narrative. Intent, schema, logic, and debugging notes live in one file.</p>
<h3>Event Type Definition Files</h3>
<p><strong>Location</strong>: <code>event-types/{namespace}.{event-name}.md</code> within the activity-core repo (or a registered event-types registry repo if volumes justify separation).</p>
Guidance for agents and humans writing rules against this event type:
- Which attributes are safe for instruction prompts (trusted fields)
- Common misuses or gotchas
- Related events that are often used together
## Debugging
What to check when an activity that subscribes to this event does not fire:
- How to verify the event was published (NATS subject, log entry)
- How to inspect the event payload in the registry
- Common schema validation failures</pre>
<h3>Attribute Types</h3>
<p>The type system for event attributes is intentionally small:</p>
<divclass="scroll"><table><thead><tr><th>Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>string</code></td><td>UTF-8 string</td></tr><tr><td><code>integer</code></td><td>64-bit signed integer</td></tr><tr><td><code>float</code></td><td>64-bit float</td></tr><tr><td><code>boolean</code></td><td>true / false</td></tr><tr><td><code>datetime</code></td><td>ISO 8601 UTC string in payload, parsed to datetime in evaluator</td></tr><tr><td><code>uuid</code></td><td>String in payload, validated as UUID v4</td></tr><tr><td><code>string[]</code></td><td>JSON array of strings</td></tr><tr><td><code>integer[]</code></td><td>JSON array of integers</td></tr><tr><td><code>object</code></td><td>Freeform JSON object — cannot be used in rule conditions; instruction-only</td></tr></tbody></table></div>
<p><code>object</code> type attributes are available to instructions but excluded from rule conditions deliberately — rules must be deterministic and schema-validatable.</p>
<h3>ActivityDefinition Files</h3>
<p><strong>Location</strong>: <code>activity-definitions/{slug}.md</code> within the repo that owns the automation. For org-wide automations: <code>activity-core/activity-definitions/</code>. For domain-specific automations: <code>{domain-repo}/activity-definitions/</code>.</p>
References to task template files used in rule actions. Each template is a
separate markdown file under `tasks/` that defines the task title, description
template, default labels, and default assignee logic.
- `tasks/sbom-initial-scan.md`
- `tasks/generate-scope-md.md`
## Notes
Operational notes, edge cases, and context that does not fit elsewhere.
## Debugging
Checklist for when this ActivityDefinition fires but produces unexpected output:
1. Was the triggering event published with the correct type and attributes?
2. Do the rule conditions evaluate as expected? (Use `make eval-rule` with a fixture)
3. Is issue-core reachable and configured for the target domain?
4. For instructions: check the audit log for the model response and output validation result.
## Change History
- v1.0 (2026-05-14): Initial definition</pre>
<h3>Governance model</h3>
<p>The <code>governance</code> field on an event type definition determines how the registry runtime handles it:</p>
<divclass="scroll"><table><thead><tr><th>Value</th><th>Behaviour</th></tr></thead><tbody><tr><td><code>publisher-declared</code></td><td>Accepted immediately on publish; no review required</td></tr><tr><td><code>curated</code></td><td>Held in <code>pending</code> state until a curator approves via registry API</td></tr></tbody></table></div>
<p>The runtime checks the <strong>environment's curator gate configuration</strong> — not just the file's governance field. An environment configured with <code>curator_gate: disabled</code> treats all event types as <code>publisher-declared</code> regardless of the field value. An environment with <code>curator_gate: required</code> treats all event types as <code>curated</code> regardless of the field value. The field is the publisher's declared preference; the environment config is the enforcement point.</p>
<p>This means:</p>
<ul><li><strong>Dev / integration</strong>: <code>curator_gate: disabled</code> — developers and agents iterate freely; new event types take effect immediately.</li><li><strong>Staging / production</strong>: <code>curator_gate: required</code> — all new event types queue for curator review before the runtime accepts events of that type.</li></ul>
<h3>File as source of truth</h3>
<p>Following CUST-ADR-001 (Workplans as Repository Artefacts), definition files are the canonical source of truth. The activity-core runtime indexes them into its database on startup and via a sync command. The database is a queryable cache, not the origin. A definition deleted from the filesystem is disabled at next sync.</p>
<h3>Task Templates</h3>
<p>Task templates are separate markdown files (<code>tasks/{slug}.md</code>) referenced from ActivityDefinition action blocks. They define:</p>
<pre>---
id: tasks/sbom-initial-scan
type: task-template
---
# Task: Run Initial SBOM Scan
## Title template
`Run SBOM scan — {target_repo}`
## Description template
Initial SBOM scan required for newly registered repository `{target_repo}`.
<p>This keeps task content editable separately from the routing logic in ActivityDefinitions.</p>
</section>
<sectionid="consequences"><h2>Consequences</h2>
<ul><li>A new <code>event-types/</code> directory in activity-core (and eventually a shared registry) holds all org event type definitions.</li><li>A new <code>activity-definitions/</code> directory in activity-core holds org-wide automations.</li><li>Domain repos may hold their own <code>activity-definitions/</code> for domain-specific automations, scanned by activity-core at sync time.</li><li>The runtime requires a parser for the <code>rule</code> and <code>instruction</code> fenced blocks.</li><li>SCOPE.md for activity-core must be updated to list these directories.</li></ul>
<p><strong>Pure JSON Schema for event types, separate wiki for docs</strong>: rejected — documentation and schema diverge immediately; agents must cross-reference two systems to author a rule correctly.</p>
<p><strong>OpenAPI / AsyncAPI specification</strong>: rejected — those formats are excellent for API and broker documentation but not designed for co-locating operational intent and debugging guidance. They are also less readable for non-specialists.</p>
<p><strong>Code-only (Python dataclasses for event schemas, Python functions for rules)</strong>: rejected — requires code deployment for any definition change; agents cannot modify definitions without write access to the codebase; non-technical stakeholders cannot review or understand automation policies.</p>
</section>
<sectionid="related"><h2>Related</h2>
<ul><li>ACT-ADR-001 — Event Bridge Architecture</li><li>ACT-ADR-003 — Rule vs. Instruction model and DSL</li><li>CUST-ADR-001 — Workplans as repository artefacts</li></ul>
