@eventmodelers/cli 1.0.45 → 1.0.47

package/stacks/supabase/templates/build-kit/lib/checks/20-append-only-migrations.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+// supabase/migrations/V{n}__*.sql may only be ADDED, never modified or deleted —
+// migrations are append-only; a fix belongs in a new migration, not an edit to
+// an old one.
+
+const MIGRATION_PATTERN = /^supabase\/migrations\/V\d+__.*\.sql$/;
+
+module.exports = {
+  name: 'append-only-migrations',
+  run(ctx) {
+    const violations = [];
+    for (const { status, path: p } of ctx.changes) {
+      if (!MIGRATION_PATTERN.test(p)) continue;
+      if (status !== 'A') {
+        violations.push({ path: p, reason: 'existing migrations are append-only; add a new V{n} file instead of editing this one' });
+      }
+    }
+    return violations;
+  },
+};

package/stacks/supabase/templates/build-kit/lib/checks/30-test-file-present.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+// A slice commit that adds/changes a command handler, projection, or processor
+// must also include a *.test.ts for that slice — catches the agent skipping the
+// matching build skill's test step (build-state-change Step 4 / build-state-view
+// Step 5 / build-automation's DeciderSpecification tests).
+
+const { execSync } = require('child_process');
+
+const IMPLEMENTATION_FILE = /^src\/slices\/([^/]+)\/([^/]+)\/(?:[A-Za-z0-9]+Command|[A-Za-z0-9]+Projection|processor(?:-[A-Za-z0-9]+)?)\.ts$/;
+
+module.exports = {
+  name: 'test-file-present',
+  run(ctx) {
+    const sliceDirs = new Set();
+    for (const { path: p } of ctx.changes) {
+      const m = IMPLEMENTATION_FILE.exec(p);
+      if (m) sliceDirs.add(`src/slices/${m[1]}/${m[2]}`);
+    }
+    if (sliceDirs.size === 0) return [];
+
+    let tracked = [];
+    try {
+      tracked = execSync('git ls-files -- src/slices', { cwd: ctx.repoRoot, encoding: 'utf8' })
+        .split('\n')
+        .filter(Boolean);
+    } catch {
+      // best-effort — fall through with whatever's staged
+    }
+    const known = new Set([...tracked, ...ctx.changes.map((c) => c.path)]);
+
+    const violations = [];
+    for (const dir of sliceDirs) {
+      const hasTest = [...known].some((f) => f.startsWith(`${dir}/`) && f.endsWith('.test.ts'));
+      if (!hasTest) {
+        violations.push({
+          path: dir,
+          reason: 'no *.test.ts found for this slice — command handlers/projections/processors need test coverage',
+        });
+      }
+    }
+    return violations;
+  },
+};

package/stacks/supabase/templates/build-kit/lib/checks/40-no-invented-fields.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+// Heuristic: flags a field name used in a slice's Command/ReadModel type literal
+// that doesn't appear anywhere in that slice's own slice.json. Not a real
+// TS/schema-aware check (no parser dependency) — it regex-extracts the fields
+// declared inside `Command<'Name', { ... }, ...>` and `type XReadModel = { ... }`
+// literals, so unusual formatting (nested object/array field types, nonstandard
+// generics) can slip past undetected. It only ever adds violations for fields it
+// is confident about; when slice.json can't be found/parsed for a slice, that
+// slice's files are skipped entirely rather than guessed at.
+
+const fs = require('fs');
+const path = require('path');
+const { findSliceJson, normalize } = require('../util/find-slice.cjs');
+
+const COMMON_ALLOWED = new Set(
+  ['id', 'userId', 'correlationId', 'causationId', 'streamName', 'type', 'data', 'metadata', 'createdAt', 'updatedAt', 'timestamp'].map(normalize),
+);
+
+const TYPE_LITERALS = [
+  /(?:Command|Event)<\s*'[^']+'\s*,\s*{([^}]*)}/g,
+  /type\s+[A-Za-z0-9_]+ReadModel\s*=\s*{([^}]*)}/g,
+];
+
+const FIELD_LINE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\??\s*:/gm;
+
+function collectDeclaredFields(node, out) {
+  if (Array.isArray(node)) {
+    for (const item of node) collectDeclaredFields(item, out);
+  } else if (node && typeof node === 'object') {
+    if (typeof node.name === 'string' && ('type' in node || 'optional' in node)) {
+      out.add(normalize(node.name));
+    }
+    for (const key of Object.keys(node)) collectDeclaredFields(node[key], out);
+  }
+}
+
+module.exports = {
+  name: 'no-invented-fields',
+  run(ctx) {
+    const bySlice = new Map(); // "context/SliceName" -> { context, sliceName, files: [] }
+
+    for (const { path: p } of ctx.changes) {
+      if (!p.endsWith('.ts') || p.endsWith('.test.ts')) continue;
+      const m = /^src\/slices\/([^/]+)\/([^/]+)\//.exec(p);
+      if (!m) continue;
+      const key = `${m[1]}/${m[2]}`;
+      if (!bySlice.has(key)) bySlice.set(key, { context: m[1], sliceName: m[2], files: [] });
+      bySlice.get(key).files.push(p);
+    }
+
+    const violations = [];
+
+    for (const { context, sliceName, files } of bySlice.values()) {
+      const slice = findSliceJson(ctx.repoRoot, context, sliceName);
+      if (!slice) continue; // can't verify — don't block
+
+      const declared = new Set();
+      collectDeclaredFields(slice, declared);
+      if (declared.size === 0) continue; // slice.json shape not recognized — don't block
+
+      for (const file of files) {
+        let content;
+        try {
+          content = fs.readFileSync(path.join(ctx.repoRoot, file), 'utf8');
+        } catch {
+          continue; // deleted/unreadable — nothing to check
+        }
+
+        for (const pattern of TYPE_LITERALS) {
+          pattern.lastIndex = 0;
+          let typeMatch;
+          while ((typeMatch = pattern.exec(content))) {
+            FIELD_LINE.lastIndex = 0;
+            let fieldMatch;
+            while ((fieldMatch = FIELD_LINE.exec(typeMatch[1]))) {
+              const raw = fieldMatch[1];
+              const norm = normalize(raw);
+              if (COMMON_ALLOWED.has(norm) || declared.has(norm)) continue;
+              violations.push({
+                path: file,
+                reason: `field "${raw}" is not declared anywhere in slice.json for this slice — check for an invented field`,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/supabase/templates/build-kit/lib/checks/50-spec-coverage.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+// Heuristic: a slice's *.test.ts must have at least as many `it(...)` blocks as
+// slice.json has `specifications[]` entries. Doesn't verify each spec is
+// actually tested (that would need matching scenario content, not just count),
+// just that nobody's silently short a test case. Skipped (not blocked) when
+// slice.json can't be found or has no specifications[] array.
+
+const fs = require('fs');
+const path = require('path');
+const { findSliceJson } = require('../util/find-slice.cjs');
+
+const TEST_FILE = /^src\/slices\/([^/]+)\/([^/]+)\/[^/]+\.test\.ts$/;
+const IT_BLOCK = /\bit(?:\.(?:only|skip))?\s*\(/g;
+
+module.exports = {
+  name: 'spec-coverage',
+  run(ctx) {
+    const violations = [];
+
+    for (const { path: p } of ctx.changes) {
+      TEST_FILE.lastIndex = 0;
+      const m = TEST_FILE.exec(p);
+      if (!m) continue;
+      const [, context, sliceName] = m;
+
+      const slice = findSliceJson(ctx.repoRoot, context, sliceName);
+      if (!slice || !Array.isArray(slice.specifications) || slice.specifications.length === 0) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(path.join(ctx.repoRoot, p), 'utf8');
+      } catch {
+        continue; // deleted — nothing to check
+      }
+
+      const specCount = slice.specifications.length;
+      const itCount = (content.match(IT_BLOCK) || []).length;
+
+      if (itCount < specCount) {
+        violations.push({
+          path: p,
+          reason: `slice.json declares ${specCount} specification(s) but this test file only has ${itCount} it(...) block(s)`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/supabase/templates/build-kit/lib/checks/90-tsc-build.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+// The project must still typecheck after the slice change. Uses the project's
+// own `typescript` devDependency via `npx tsc --noEmit` — no new dependency,
+// but it does mean this check needs node_modules already installed (same
+// prerequisite `npm run build` already has).
+
+const { execSync } = require('child_process');
+
+module.exports = {
+  name: 'tsc-build',
+  skipIfAlreadyFailing: true, // slow — don't bother once the commit is rejected already
+  run(ctx) {
+    try {
+      execSync('npx tsc --noEmit', { cwd: ctx.repoRoot, stdio: 'pipe' });
+      return [];
+    } catch (err) {
+      const output = String(err.stdout || err.message || '').trim().split('\n').slice(0, 20).join('\n');
+      return [{ path: '(tsc --noEmit)', reason: `TypeScript build failed:\n${output}` }];
+    }
+  },
+};

package/stacks/supabase/templates/root/.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Installed via setup-env.sh (`git config core.hooksPath .githooks`), so this file
+# is versioned and shared by every clone instead of living only in .git/hooks/.
+set -e
+
+repo_root=$(git rev-parse --show-toplevel)
+script="$repo_root/.build-kit/lib/check-commit-scope.cjs"
+
+if [ -f "$script" ]; then
+  node "$script"
+fi

package/stacks/supabase/templates/root/package.json

@@ -7,7 +7,8 @@
     "dev": "node --env-file=.env --require ts-node/register server.ts",
     "build": "tsc",
     "start": "NODE_ENV=production node --env-file=.env --require ts-node/register server.ts",
-    "test": "tsx --test 'src/**/*.test.ts'"
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "check:scope": "node .build-kit/lib/check-commit-scope.cjs"
   },
   "dependencies": {
     "@event-driven-io/emmett": "^0.42.1-alpha.1",

package/stacks/supabase/templates/root/setup-env.sh

@@ -50,4 +50,10 @@ FLYWAY_PASSWORD=${DB_PASSWORD}
 EOF
 
 echo ""
-echo ".env created successfully."
+echo ".env created successfully."
+
+if [ -f .githooks/pre-commit ] && git rev-parse --git-dir >/dev/null 2>&1; then
+  chmod +x .githooks/pre-commit 2>/dev/null || true
+  git config core.hooksPath .githooks
+  echo "Configured git to use .githooks/ (slice commit-scope guard)."
+fi

package/stacks/umadb/templates/.claude/skills/build-automation/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: build-automation
+authors:
+  - Martin Dilger
+description: >
+  Implement automation slices (Event → Command) that react to events off the shared
+  EventDispatcher subscription and dispatch a command by calling its command handler directly, in
+  this project's one established pattern. Automations can be stateless (direct event-to-command
+  mapping) or carry a private read model (to look up data needed for command construction). Use
+  when implementing a new automation / event-to-command reactor from a slice.json event model in
+  this project. There is exactly one supported style — do not offer alternatives.
+---
+
+# UmaDB — Automation Slice
+
+An automation reacts to an event by dispatching a command. In Event Modeling: the **orange**
+stripe. There are two kinds:
+
+- **Stateless**: direct event-to-command mapping — no stored state needed. Grounded in the
+  `AutoSubscribeToDefaultCourseProcessor` slice (test in
+  `AutoSubscribeToDefaultCourseProcessorTest`) — verified, compiled and passing under `mvn test`,
+  including end-to-end against a real `umadb/umadb:0.7.5` server (`UmaDbContainerIntegrationTest`):
+  a real `CustomerRegistered` event, delivered by the real `EventDispatcher` subscription, really
+  causes a real `SubscribeToCourse` command to be handled and its event really appended.
+- **With private read model**: needs data NOT in the trigger event itself (e.g. iterating over all
+  entities matching a category). Same shape as `build-state-change`'s Decision-with-fold pattern,
+  applied to a private in-memory model instead of a Query/replay — documented below by direct
+  analogy, not separately proven against a compiled example in this session; verify it compiles and
+  its tests pass before considering it done, the same as any other slice.
+
+There is no separate command-bus abstraction in this project (unlike Axon's
+`CommandDispatcher`/`CommandGateway` split) — an automation dispatches by calling the target
+command handler's `handle(...)` method directly, since it's just another Spring bean and the call
+is in-process either way.
+
+## Step 0: Discover Target Project Conventions
+
+> **Comments & description**: each element carries a `comments: string[]` array (board comments)
+> and a `description` field — use them as implementation hints, and resolve consumed comments via
+> `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+Read the target project's `.build-kit/CLAUDE.md` and explore existing slices.
+
+**Determine `{basePackage}`** — every path below is rooted at
+`{basePackage}.slices.{context}.automation.{slicename}`. Resolve `{basePackage}` as documented in
+`.build-kit/CLAUDE.md`.
+
+## Step 1: Understand the Input
+
+Extract these elements from slice.json (or whatever Event Modeling artifact is given):
+
+| Element                | What to extract                                                        |
+|-------------------------|-------------------------------------------------------------------------|
+| **Trigger event**      | Which event triggers the automation, and which condition filters it     |
+| **Target command**     | Which command to dispatch, with what properties                         |
+| **Mapping logic**      | How event properties map to command properties                          |
+| **Read model needed?** | Does the automation need data NOT in the trigger event itself?          |
+
+If the slice details include `## Scenarios (GWTs)`, use them to derive test cases. GWT format for
+automations: `Given (events) → Then (command | NOTHING)`. Events in Given include read-model-
+building events first, trigger event last.
+
+`slice.json` may also carry an optional `storylines[]` array — see the "Storyline-Derived Tests"
+section under Step 4 for how a trigger-event beat in one of these can add a supplementary test.
+
+**If requirements are unclear, invoke `/request-feedback` rather than guessing** — see
+`.build-kit/CLAUDE.md`'s escalation rule.
+
+## Step 2: Ensure Events Exist
+
+All events the automation reacts to, and the target command it dispatches, must already exist. If
+they don't, create the event first following `build-state-change` Step 2, and the target command's
+whole slice following `build-state-change` in full (a command never exists without its slice).
+
+## Step 3: Implement the Automation
+
+### Stateless Automation
+
+New automation slices live under `src/main/java/.../slices/{context}/automation/{slicename}/`.
+
+```java
+package {basePackage}.slices.{context}.automation.{slicename};
+
+import io.umadb.client.Event;
+import {basePackage}.eventstore.EventCodec;
+import {basePackage}.eventstore.SliceEventListener;
+import {basePackage}.slices.{context}.events.{TriggerEvent};
+import {basePackage}.slices.{context}.{targetslicename}.{TargetCommand}Command;
+import {basePackage}.slices.{context}.{targetslicename}.{TargetCommand}CommandHandler;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Component;
+
+@Component
+@ConditionalOnProperty(prefix = "slices.{context}.automation", name = "{slicename}.enabled")
+public class {AutomationName}Processor implements SliceEventListener {
+
+    private final {TargetCommand}CommandHandler targetCommandHandler;
+
+    public {AutomationName}Processor({TargetCommand}CommandHandler targetCommandHandler) {
+        this.targetCommandHandler = targetCommandHandler;
+    }
+
+    @Override
+    public boolean supports(String eventType) {
+        return {TriggerEvent}.TYPE.equals(eventType);
+    }
+
+    @Override
+    public void onEvent(Event event) {
+        react(EventCodec.fromEvent(event, {TriggerEvent}.class));
+    }
+
+    /** Called directly (no client, no dispatcher) by this class's own test - see Step 4. */
+    public void react({TriggerEvent} event) {
+        if (!shouldReact(event)) {
+            return;
+        }
+        targetCommandHandler.handle(new {TargetCommand}Command(event.field1() /*, mapped fields */));
+    }
+
+    private boolean shouldReact({TriggerEvent} event) {
+        return true; // replace with the actual condition from slice.json, if any
+    }
+}
+```
+
+**Idempotency**: `EventDispatcher` may redeliver a trigger event after an application restart (see
+its Javadoc on quickstart-level checkpointing) — a re-dispatched command is safe as long as the
+target command handler's own Decision already no-ops a repeat (verified: re-subscribing to the same
+course a second time is rejected by `SubscribeToCourseDecision.alreadySubscribedToThisCourse`, not
+by anything in the automation itself). Don't add your own idempotency guard in the automation
+unless the target command handler genuinely can't provide one — check that first.
+
+### Automation with Read Model
+
+When the automation needs data not in the trigger event, add a private in-memory model — never
+reuse another slice's read model.
+
+```java
+@Component
+@ConditionalOnProperty(prefix = "slices.{context}.automation", name = "{slicename}.enabled")
+public class {AutomationName}Processor implements SliceEventListener {
+
+    // Private read model, indexed by entity id - belongs to this automation only
+    private final Map<String, {AutomationName}Entry> store = new ConcurrentHashMap<>();
+
+    private final {TargetCommand}CommandHandler targetCommandHandler;
+
+    public {AutomationName}Processor({TargetCommand}CommandHandler targetCommandHandler) {
+        this.targetCommandHandler = targetCommandHandler;
+    }
+
+    @Override
+    public boolean supports(String eventType) {
+        return {SetupEvent}.TYPE.equals(eventType) || {TriggerEvent}.TYPE.equals(eventType);
+    }
+
+    @Override
+    public void onEvent(Event event) {
+        if (event.type().equals({SetupEvent}.TYPE)) {
+            onSetup(EventCodec.fromEvent(event, {SetupEvent}.class));
+        } else if (event.type().equals({TriggerEvent}.TYPE)) {
+            react(EventCodec.fromEvent(event, {TriggerEvent}.class));
+        }
+    }
+
+    // Phase 1 - build the private read model from setup events
+    public void onSetup({SetupEvent} event) {
+        store.put(event.entityId(), new {AutomationName}Entry(event.entityId(), event.filterField()));
+    }
+
+    // Phase 2 - trigger: dispatch a command per matching entry
+    public void react({TriggerEvent} event) {
+        store.values().stream()
+                .filter(entry -> entry.filterField().equals(event.filterValue()))
+                .forEach(entry -> targetCommandHandler.handle(new {TargetCommand}Command(entry.entityId() /*, other fields */)));
+    }
+
+    record {AutomationName}Entry(String entityId, String filterField) {}
+}
+```
+
+Key rules:
+
+- **Two branches in one `onEvent`**: one builds the private model (`onSetup`), one reacts
+  (`react`) — `supports` must answer true for both event types.
+- Since `EventDispatcher` delivers events sequentially in position order to every listener on a
+  single subscription thread (see its Javadoc), there is no concurrent-mutation race between
+  `onSetup` and `react` to guard against here the way a multi-threaded processing group would need
+  to — `ConcurrentHashMap` is a safety margin, not a requirement.
+- **Private read model belongs to this automation only** — never share it with another slice.
+
+## Step 4: Implement Tests
+
+**Stateless automations** — pure unit test with a mocked target command handler (Mockito):
+
+```java
+package {basePackage}.slices.{context}.automation.{slicename};
+
+import {basePackage}.slices.{context}.events.{TriggerEvent};
+import {basePackage}.slices.{context}.{targetslicename}.{TargetCommand}Command;
+import {basePackage}.slices.{context}.{targetslicename}.{TargetCommand}CommandHandler;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+
+@ExtendWith(MockitoExtension.class)
+class {AutomationName}ProcessorTest {
+
+    @Mock
+    private {TargetCommand}CommandHandler targetCommandHandler;
+
+    private {AutomationName}Processor processor;
+
+    @BeforeEach
+    void setUp() {
+        processor = new {AutomationName}Processor(targetCommandHandler);
+    }
+
+    @Test
+    @DisplayName("given trigger event with condition met, then command dispatched")
+    void happyPath() {
+        processor.react(new {TriggerEvent}("entity-1" /*, fields that meet condition */));
+
+        verify(targetCommandHandler).handle(new {TargetCommand}Command("entity-1" /*, expected fields */));
+    }
+
+    @Test
+    @DisplayName("given trigger event with condition not met, then no command dispatched")
+    void conditionNotMet() {
+        processor.react(new {TriggerEvent}("entity-1" /*, fields that do NOT meet condition */));
+
+        verifyNoInteractions(targetCommandHandler);
+    }
+}
+```
+
+If Mockito's inline mock maker reports a Byte Buddy / JDK-version incompatibility when mocking a
+project class (seen on very recent JDKs, harmless), add
+`-Dnet.bytebuddy.experimental=true` to the surefire `<argLine>` in `pom.xml` — this affects only
+Mockito's own bytecode generation, not the code under test.
+
+**Automations with read model** — call `onSetup`/`react` directly, same mocked-handler style, setup
+events before trigger events:
+
+```java
+processor.onSetup(new {SetupEvent}("entity-1", "filter-A"));
+processor.onSetup(new {SetupEvent}("entity-2", "filter-B"));
+
+processor.react(new {TriggerEvent}("filter-A"));
+
+verify(targetCommandHandler).handle(new {TargetCommand}Command("entity-1" /*, fields */));
+verifyNoMoreInteractions(targetCommandHandler);
+```
+
+### Test Cases to Cover
+
+**Stateless automations:**
+1. Condition met → expected command dispatched
+2. Condition not met → no command dispatched
+
+**Automations with read model:**
+1. Setup + trigger with matching filter → command dispatched for matching entries only
+2. Setup + trigger with non-matching filter → no command dispatched
+3. Temporal ordering: setup before trigger vs. setup after trigger → only entries that existed at
+   trigger time receive a command
+
+### Mapping GWT Scenarios to Tests
+
+| GWT Element | Test Code |
+|---|---|
+| Event in Given | `processor.react(new Event(...))` (or `onSetup(...)` for a setup event) |
+| Multiple events in Given | multiple calls — setup events first, trigger last |
+| Command in Then | `verify(targetCommandHandler).handle(eq(expectedCommand))` |
+| NOTHING in Then | `verifyNoInteractions(targetCommandHandler)` |
+
+### Storyline-Derived Tests (Optional)
+
+`slice.json` may also carry a `storylines[]` array — narrated walkthroughs with an ordered
+`elements[]` "beats" sequence (EVENT/COMMAND/READMODEL/...). This is a secondary, supplementary
+source; `specifications[]` above stays the primary and default source of test cases. Most slices
+have no `storylines[]` — skip silently when there's nothing relevant.
+
+Find a beat whose `type` is `EVENT` immediately followed by a `COMMAND` beat this automation
+dispatches. That pair is a ready-made test: `given` = the cumulative preceding `EVENT` beats
+(setup events) through the trigger beat, `then` = `verify(targetCommandHandler).handle(eq(...))`
+built from the command beat's fields — same shape as the "Mapping GWT Scenarios to Tests" row
+above, just sourced from the storyline instead of `specifications[]`.
+
+If the beat following the trigger event isn't a COMMAND this automation dispatches, don't force a
+test — leave it undocumented rather than fabricating an assertion.
+
+## References
+
+- [Feature Flag Patterns](references/feature-flag-patterns.md) — `@ConditionalOnProperty`, wired the same as `build-state-change`
+
+## Final Verification: Does the Implementation Match slice.json?
+
+Before marking this slice as `Done`, verify the implementation against slice.json:
+
+- [ ] The trigger event in the processor matches the trigger event in slice.json exactly
+- [ ] The command dispatched matches the target command defined in slice.json
+- [ ] All fields mapped from trigger event to command come from the event fields defined in slice.json — no invented mappings
+- [ ] Every GWT scenario in `specifications[]` maps to a test case in the test class
+- [ ] If `storylines[]` is present: every trigger-EVENT→target-COMMAND beat pair for this automation has a storyline test — or was deliberately skipped as untraceable
+- [ ] No filtering conditions were invented — all conditions come from slice.json `description` or `comments`
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code

package/stacks/umadb/templates/.claude/skills/build-automation/references/feature-flag-patterns.md

@@ -0,0 +1,42 @@
+# Feature Flag Patterns
+
+This project's one supported approach: `@ConditionalOnProperty` on the command handler and REST
+controller (**not** on the Decision class - verified against the `RegisterCustomer` and
+`SubscribeToCourse` slices, neither of which puts the annotation on its decision-model class).
+Read slices (`build-state-view`) are never feature-flagged - only write and automation slices are.
+Examples use a generic `Ordering` bounded context.
+
+## Annotation on slice components
+
+```java
+// Command handler
+@ConditionalOnProperty(prefix = "slices.ordering.write", name = "placeorder.enabled")
+@Component
+public class PlaceOrderCommandHandler { ... }
+
+// REST controller (if applicable)
+@ConditionalOnProperty(prefix = "slices.ordering.write", name = "placeorder.enabled")
+@RestController
+public class PlaceOrderRestController { ... }
+```
+
+## `application.properties` (main — enable by default)
+
+```properties
+slices.ordering.write.placeorder.enabled=true
+slices.ordering.automation.notifycustomeronorder.enabled=true
+```
+
+## `application.properties` (test — disable by default)
+
+```properties
+slices.ordering.write.placeorder.enabled=false
+slices.ordering.automation.notifycustomeronorder.enabled=false
+```
+
+This only matters for tests that boot a Spring context (`@SpringBootTest`). The
+`InMemoryUmaDbClient` unit-test pattern in
+[umadb-query-patterns.md](umadb-query-patterns.md) never boots Spring, so these properties don't
+affect it either way - a Testcontainers-based end-to-end test (see `build-state-view`'s reference)
+overrides them back to `true` for itself via `@DynamicPropertySource`, since it's the one test that
+does need the real beans wired.