refactor(event-governance): author rule packs under agent/event-rules

bgagent · bgagent · commit 7eaf8d778da4 · 2026-07-09T11:08:49.000-05:00
Move the event-rules asset tree (schema, packs, parity fixtures) from contracts/ to agent/event-rules/, alongside agent/workflows/ — one asset tree, one authoring UX, and the natural source for the future RegistryService (#246). The agent runtime never loads these files (it receives resolved event_rules on the TaskRecord), so only the three file consumers move: the CDK pack resolver (bundle-time import), the CLI --fixture loader, and the Python + TS parity/evaluator tests. Dual-plane parity is unchanged — the CDK-resolved rules remain the single source both planes consume. Repoints resolver import, CLI fixture path, four test fixture paths, blueprint schema comment, and EVENT_GOVERNANCE.md (+ Starlight mirror).
diff --git a/agent/event-rules-parity/README.md b/agent/event-rules-parity/README.md
@@ -5,7 +5,7 @@ Golden-file vectors shared by:
 - `agent/tests/test_event_rules_parity.py` (Python evaluator)
 - `cdk/test/handlers/shared/event-rules-parity.test.ts` (TypeScript evaluator)
 
-Fixtures live under `contracts/event-rules/fixtures/` and are referenced by
+Fixtures live under `agent/event-rules/fixtures/` and are referenced by
 basename from this parity contract.
 
 Design reference: `docs/design/EVENT_GOVERNANCE.md` (issue #230).
diff --git a/agent/event-rules/README.md b/agent/event-rules/README.md
@@ -0,0 +1,29 @@
+# Event governance rules
+
+Event rule packs, schema, and cross-language parity fixtures for event-driven
+governance (issue #230). Authored here alongside `agent/workflows/` — one asset
+tree, one authoring UX. The related event-catalog and policy-decision schemas
+stay under the repo-root `contracts/` tree.
+
+## Layout
+
+| Path | Purpose |
+|------|---------|
+| `schema.json` | JSON Schema for event rule packs |
+| `packs/*.json` | Versioned rule packs pinned by `Blueprint.security.eventRulePack` |
+| `fixtures/` | Golden fixtures for Python + TypeScript evaluator parity |
+
+## Consumers
+
+| Caller | Path | Reads |
+|--------|------|-------|
+| `cdk/src/handlers/shared/event-rule-pack-resolver.ts` | Bundles `packs/*.json` at build time (future `RegistryService.resolve`) | packs |
+| `cdk/test/.../event-rule-evaluator.test.ts`, `event-rules-parity.test.ts` | TypeScript evaluator + parity | fixtures |
+| `agent/tests/test_event_rules_parity.py`, `test_event_governance_evaluator.py` | Python evaluator + parity | fixtures |
+| `cli/src/commands/rules.ts` | `bgagent rules eval --fixture` | fixtures |
+
+The agent runtime does **not** read these files: it receives already-resolved
+`event_rules` frozen on the TaskRecord at submit time, so both evaluation planes
+consume one source (the CDK-resolved rules).
+
+Design reference: [EVENT_GOVERNANCE.md](../../docs/design/EVENT_GOVERNANCE.md).
diff --git a/agent/event-rules/fixtures/aggregate-cost-cancel.json b/agent/event-rules/fixtures/aggregate-cost-cancel.json
diff --git a/agent/event-rules/fixtures/aggregate-turn-count-escalate.json b/agent/event-rules/fixtures/aggregate-turn-count-escalate.json
diff --git a/agent/event-rules/fixtures/async-notify-pr.json b/agent/event-rules/fixtures/async-notify-pr.json
diff --git a/agent/event-rules/fixtures/observe-repo-setup.json b/agent/event-rules/fixtures/observe-repo-setup.json
diff --git a/agent/event-rules/packs/platform-default-v1.json b/agent/event-rules/packs/platform-default-v1.json
diff --git a/agent/event-rules/schema.json b/agent/event-rules/schema.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://abca.dev/contracts/event-rules/schema.json",
+  "$id": "https://abca.dev/agent/event-rules/schema.json",
   "title": "EventRulePack",
   "type": "object",
   "required": ["rules"],
diff --git a/agent/tests/test_event_governance_evaluator.py b/agent/tests/test_event_governance_evaluator.py
@@ -7,7 +7,7 @@
 
 from event_governance.evaluator import match_rules, parse_rules
 
-FIXTURES = Path(__file__).resolve().parents[2] / "contracts" / "event-rules" / "fixtures"
+FIXTURES = Path(__file__).resolve().parents[1] / "event-rules" / "fixtures"
 
 
 def _load_fixture(name: str) -> dict:
diff --git a/agent/tests/test_event_rules_parity.py b/agent/tests/test_event_rules_parity.py
@@ -9,7 +9,7 @@
 
 from event_governance.evaluator import match_rules, parse_rules
 
-FIXTURES = Path(__file__).resolve().parents[2] / "contracts" / "event-rules" / "fixtures"
+FIXTURES = Path(__file__).resolve().parents[1] / "event-rules" / "fixtures"
 
 
 def _fixture_paths() -> list[Path]:
diff --git a/cdk/src/constructs/blueprint.ts b/cdk/src/constructs/blueprint.ts
@@ -45,7 +45,7 @@ const REPO_CONFIG_CR_TIMEOUT_MINUTES = 5;
 /** TTL (days) applied to a RepoConfig row on blueprint delete before cleanup. */
 const REMOVED_REPO_TTL_DAYS = 30;
 
-/** Inline event governance rule (issue #230). Schema: contracts/event-rules/schema.json */
+/** Inline event governance rule (issue #230). Schema: agent/event-rules/schema.json */
 export interface BlueprintEventRule {
   readonly id: string;
   readonly on: string;
diff --git a/cdk/src/handlers/shared/event-rule-pack-resolver.ts b/cdk/src/handlers/shared/event-rule-pack-resolver.ts
@@ -20,14 +20,15 @@
 /**
  * Resolve event rules from inline config and registry pack pins (#230 Phase 3).
  *
- * Until the agent asset registry (#246) ships, packs are loaded from
- * ``contracts/event-rules/packs/*.json`` at bundle time. The resolver
- * interface matches the future ``RegistryService.resolve('event-rule-pack')``.
+ * Packs are authored alongside workflows under ``agent/event-rules/packs/*.json``
+ * and bundled into the resolver at build time. Until the agent asset registry
+ * (#246) ships, this file IS the registry; the resolver interface matches the
+ * future ``RegistryService.resolve('event-rule-pack')`` so the swap is local.
  */
 
 import type { EventRule, EventRulePackRef } from './event-governance-types';
 import { parseEventRules } from './event-rule-evaluator';
-import platformDefaultPack from '../../../../contracts/event-rules/packs/platform-default-v1.json';
+import platformDefaultPack from '../../../../agent/event-rules/packs/platform-default-v1.json';
 
 interface PackFile {
   readonly pack_id?: string;
diff --git a/cdk/test/handlers/shared/event-rule-evaluator.test.ts b/cdk/test/handlers/shared/event-rule-evaluator.test.ts
@@ -21,8 +21,8 @@
  * Event rule evaluator tests (issue #230).
  */
 
-import aggregateFixture from '../../../../contracts/event-rules/fixtures/aggregate-cost-cancel.json';
-import observeFixture from '../../../../contracts/event-rules/fixtures/observe-repo-setup.json';
+import aggregateFixture from '../../../../agent/event-rules/fixtures/aggregate-cost-cancel.json';
+import observeFixture from '../../../../agent/event-rules/fixtures/observe-repo-setup.json';
 import type { EventRule } from '../../../src/handlers/shared/event-governance-types';
 import {
   buildPolicyDecisionMetadata,
diff --git a/cdk/test/handlers/shared/event-rules-parity.test.ts b/cdk/test/handlers/shared/event-rules-parity.test.ts
@@ -21,7 +21,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { matchEventRules, parseEventRules } from '../../../src/handlers/shared/event-rule-evaluator';
 
-const FIXTURE_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'contracts', 'event-rules', 'fixtures');
+const FIXTURE_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'agent', 'event-rules', 'fixtures');
 
 interface FixtureFile {
   description?: string;
diff --git a/cli/src/commands/rules.ts b/cli/src/commands/rules.ts
@@ -34,7 +34,7 @@ interface FixtureFile {
 
 function loadFixture(name: string): FixtureFile {
   const repoRoot = path.resolve(__dirname, '../../..');
-  const fixturePath = path.join(repoRoot, 'contracts/event-rules/fixtures', `${name}.json`);
+  const fixturePath = path.join(repoRoot, 'agent/event-rules/fixtures', `${name}.json`);
   return JSON.parse(fs.readFileSync(fixturePath, 'utf8')) as FixtureFile;
 }
 
@@ -86,7 +86,7 @@ export function makeRulesCommand(): Command {
   rules
     .command('eval')
     .description('Evaluate a golden fixture locally')
-    .requiredOption('--fixture <name>', 'Fixture basename under contracts/event-rules/fixtures/')
+    .requiredOption('--fixture <name>', 'Fixture basename under agent/event-rules/fixtures/')
     .option('--output <format>', 'Output format (text or json)', 'text')
     .action((opts: { fixture: string; output: string }) => {
       const fixture = loadFixture(opts.fixture);
diff --git a/contracts/event-rules/README.md b/contracts/event-rules/README.md
diff --git a/docs/design/EVENT_GOVERNANCE.md b/docs/design/EVENT_GOVERNANCE.md
@@ -36,7 +36,7 @@ Each rule has:
 | `mode` | `observe_only` or `enforce` |
 | `evaluation` | `sync` (in-agent) or `async` (stream consumer) |
 
-Schema: `contracts/event-rules/schema.json`.
+Schema: `agent/event-rules/schema.json`.
 
 ### 1.3 Sync evaluation
 
@@ -81,6 +81,8 @@ Blueprint `security.eventRules` — array of rules persisted in RepoTable, froze
 
 Blueprint `security.eventRulePack: { id, version }` resolves from agent asset registry. Inline rules merge as overrides; pack rules take precedence unless overridden per-rule.
 
+Packs are authored under `agent/event-rules/packs/*.json`, alongside `agent/workflows/` — one asset tree, one authoring UX, validated against `agent/event-rules/schema.json`. Today the CDK resolver bundles these at build time (`resolveEventRules`); its interface matches the future `RegistryService.resolve('event-rule-pack')`, so the registry swap is local to the resolver. The agent runtime never loads pack files — it receives already-resolved `event_rules` frozen on the TaskRecord at submit time, which keeps the sync/async evaluators reading one source.
+
 ---
 
 ## 4. Checkpoints
diff --git a/docs/src/content/docs/architecture/Event-governance.md b/docs/src/content/docs/architecture/Event-governance.md
@@ -40,7 +40,7 @@ Each rule has:
 | `mode` | `observe_only` or `enforce` |
 | `evaluation` | `sync` (in-agent) or `async` (stream consumer) |
 
-Schema: `contracts/event-rules/schema.json`.
+Schema: `agent/event-rules/schema.json`.
 
 ### 1.3 Sync evaluation
 
@@ -85,6 +85,8 @@ Blueprint `security.eventRules` — array of rules persisted in RepoTable, froze
 
 Blueprint `security.eventRulePack: { id, version }` resolves from agent asset registry. Inline rules merge as overrides; pack rules take precedence unless overridden per-rule.
 
+Packs are authored under `agent/event-rules/packs/*.json`, alongside `agent/workflows/` — one asset tree, one authoring UX, validated against `agent/event-rules/schema.json`. Today the CDK resolver bundles these at build time (`resolveEventRules`); its interface matches the future `RegistryService.resolve('event-rule-pack')`, so the registry swap is local to the resolver. The agent runtime never loads pack files — it receives already-resolved `event_rules` frozen on the TaskRecord at submit time, which keeps the sync/async evaluators reading one source.
+
 ---
 
 ## 4. Checkpoints

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"$schema": "https://json-schema.org/draft/2020-12/schema",`
`3`		`- "$id": "https://abca.dev/contracts/event-rules/schema.json",`
	`3`	`+ "$id": "https://abca.dev/agent/event-rules/schema.json",`
`4`	`4`	`"title": "EventRulePack",`
`5`	`5`	`"type": "object",`
`6`	`6`	`"required": ["rules"],`