@eventmodelers/cli 2.0.1 → 2.0.3

package/shared/scaffold/supabase/template/web/src/lib/api.ts.tmpl

@@ -0,0 +1,226 @@
+import { supabase } from './supabase';
+
+/**
+ * Common API client — the ONLY place that knows about base URLs, auth headers,
+ * correlation/causation tracing, and how to reach Supabase tables. Slice components
+ * must never call `fetch` directly, read the Supabase session, or import
+ * `./supabase` themselves — they call `postCommand`/`queryReadModel` and handle only
+ * the request/response shape their command/read model defines.
+ *
+ * Every call here has two implementations: a real one (Supabase) and a mock one that
+ * serves a numbered sample instead. This is what makes every slice component testable
+ * in isolation — flip `VITE_DATA_MODE` to `mock` and every read/write in the app is
+ * served from `samples/sample-<VITE_MOCK_SAMPLE>.json` files instead of a live backend.
+ */
+
+export const API_BASE = import.meta.env.VITE_API_BASE ?? '';
+
+/** `true` when reads/writes should be served from samples instead of Supabase/the backend. */
+export function isMockMode(): boolean {
+  return import.meta.env.VITE_DATA_MODE === 'mock';
+}
+
+/** Which numbered sample set is active in mock mode, e.g. `"1"`, `"2"`. */
+export function activeMockSample(): string {
+  return import.meta.env.VITE_MOCK_SAMPLE ?? '1';
+}
+
+async function getAuthHeaders(json = true): Promise<Record<string, string>> {
+  const {
+    data: { session },
+  } = await supabase.auth.getSession();
+
+  return {
+    // multipart bodies must leave Content-Type unset so the browser adds the boundary
+    ...(json ? { 'Content-Type': 'application/json' } : {}),
+    Authorization: session ? `Bearer ${session.access_token}` : '',
+    'x-correlation-id': crypto.randomUUID(),
+    'x-causation-id': crypto.randomUUID(),
+  };
+}
+
+/** 501 means the endpoint is modeled but its slice is not built yet (distinct from a 404 for a wrong URL). */
+export const NOT_BUILT_MESSAGE = 'This feature is not built yet.';
+
+function errorMessage(status: number, payload: { error?: string; message?: string } | undefined): string {
+  if (status === 501) return NOT_BUILT_MESSAGE;
+  return (payload && (payload.error || payload.message)) || `Request failed with status ${status}`;
+}
+
+/** True when an error from this module means "modeled, but its slice is not built yet" (HTTP 501). */
+export function isNotBuilt(err: unknown): boolean {
+  return err instanceof ApiError && err.status === 501;
+}
+
+export class ApiError extends Error {
+  status: number;
+  body: unknown;
+
+  constructor(message: string, status: number, body?: unknown) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * POST a command to `path` (taken verbatim from the command's API description in
+ * slice.json — never invented) with `body` as the JSON payload. Resolves with the
+ * parsed JSON response, or throws `ApiError` on a non-2xx response.
+ *
+ * In mock mode this never hits the network — it resolves with `{ ok: true }` so a
+ * command component can be exercised (submitting/success states) fully offline.
+ */
+export async function postCommand<TResponse = unknown>(
+  path: string,
+  body: unknown,
+): Promise<TResponse> {
+  if (isMockMode()) {
+    return { ok: true } as TResponse;
+  }
+
+  const headers = await getAuthHeaders();
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  const payload = await res.json().catch(() => undefined);
+
+  if (!res.ok) {
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+
+  return payload as TResponse;
+}
+
+/**
+ * POST a multipart/form-data command (e.g. one carrying a file) to `path`. Same contract as
+ * `postCommand`: resolves with the parsed JSON response, throws `ApiError` on a non-2xx
+ * response, and resolves with `{ ok: true }` locally in mock mode.
+ */
+export async function postForm<TResponse = unknown>(
+  path: string,
+  body: FormData,
+): Promise<TResponse> {
+  if (isMockMode()) {
+    return { ok: true } as TResponse;
+  }
+
+  const headers = await getAuthHeaders(false);
+  const res = await fetch(`${API_BASE}${path}`, { method: 'POST', headers, body });
+
+  const payload = await res.json().catch(() => undefined);
+
+  if (!res.ok) {
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+
+  return payload as TResponse;
+}
+
+export interface ReadModelParams {
+  /** `readmodel.apiEndpoint`, verbatim — the Postgres table/view name. */
+  table: string;
+  /** Column names to select, comma-separated (never `'*'`). */
+  select: string;
+  /** Simple equality filters, e.g. `{ customer_id: customerId }`. */
+  filters?: Record<string, unknown>;
+  /** `true` for a single-row read model (`.maybeSingle()`), `false` for a list. */
+  single?: boolean;
+}
+
+/**
+ * Read a read model's data — `params.table` via Supabase in the real implementation,
+ * or `samples[activeMockSample()]` in mock mode. `samples` is this component's own
+ * `samples/sample-*.json` map (see the component for how it's built); every read model
+ * component supplies its own, `queryReadModel` never reaches into a slice folder itself.
+ */
+export async function queryReadModel<T>(
+  params: ReadModelParams,
+  samples?: Record<string, T>,
+): Promise<T> {
+  if (isMockMode()) {
+    return mockSample(samples, `table "${params.table}"`);
+  }
+
+  let query = supabase.from(params.table).select(params.select);
+  for (const [column, value] of Object.entries(params.filters ?? {})) {
+    query = query.eq(column, value);
+  }
+
+  const { data, error } = params.single ? await query.maybeSingle() : await query;
+  // A read-model table that does not exist yet means its slice is not built: same 501 as the backend fallback.
+  if (error && (error.code === '42P01' || error.code === 'PGRST205')) throw new ApiError(NOT_BUILT_MESSAGE, 501, error);
+  if (error) throw new ApiError(error.message, 500, error);
+  return data as T;
+}
+
+/**
+ * GET a read model from a backend query route, e.g. `/api/query/orderlist-collection` —
+ * for read models whose table has RLS on with no policies (kept off Supabase's Data API),
+ * so `queryReadModel` would only ever see an empty result. Resolves with the parsed JSON
+ * response, or throws `ApiError` on a non-2xx response; mock-aware like `queryReadModel`.
+ */
+export async function getReadModel<T>(path: string, samples?: Record<string, T>): Promise<T> {
+  if (isMockMode()) {
+    return mockSample(samples, `"${path}"`);
+  }
+
+  const headers = await getAuthHeaders();
+  const res = await fetch(`${API_BASE}${path}`, { method: 'GET', headers });
+
+  const payload = await res.json().catch(() => undefined);
+
+  if (!res.ok) {
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+
+  return payload as T;
+}
+
+async function fetchFile(path: string): Promise<Blob> {
+  const headers = await getAuthHeaders(false);
+  const res = await fetch(`${API_BASE}${path}`, { method: 'GET', headers });
+  if (!res.ok) {
+    const payload = await res.json().catch(() => undefined);
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+  return res.blob();
+}
+
+/**
+ * GET a binary file (e.g. a generated PDF) from `path` with auth headers and open it in a new
+ * browser tab. In mock mode nothing is fetched; the call just resolves.
+ */
+export async function openFile(path: string): Promise<void> {
+  if (isMockMode()) return;
+
+  const url = URL.createObjectURL(await fetchFile(path));
+  window.open(url, '_blank');
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+/**
+ * GET a file (e.g. a template logo) from `path` with auth headers and return a blob URL for an
+ * `<img src>`, which would send no bearer token itself. The caller revokes it with
+ * `URL.revokeObjectURL`. In mock mode nothing is fetched; resolves with `null`.
+ */
+export async function fileUrl(path: string): Promise<string | null> {
+  if (isMockMode()) return null;
+
+  return URL.createObjectURL(await fetchFile(path));
+}
+
+function mockSample<T>(samples: Record<string, T> | undefined, source: string): T {
+  const n = activeMockSample();
+  const sample = samples?.[n];
+  if (sample === undefined) {
+    throw new Error(
+      `Mock mode is on (VITE_MOCK_SAMPLE=${n}) but no sample-${n}.json exists for ${source} — add one under this component's samples/ folder.`,
+    );
+  }
+  return sample;
+}

package/shared/scaffold/supabase/template/web/src/main.tsx.tmpl

@@ -0,0 +1,13 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+__CSS_IMPORT__
+import { BrowserRouter } from 'react-router-dom'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>,
+)

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -646,7 +646,7 @@ Create a complete slice (1 column + its nodes automatically placed).
     interaction?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
     swimlane?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
   }
-  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Waiting' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
 }
 ```
 
@@ -673,7 +673,7 @@ Create a standalone SLICE_BORDER node spanning an **existing** column. Unlike th
 {
   columnId: string   // id of an existing column on this timeline
   title: string      // slice title — always taken from this field, never derived
-  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Waiting' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
   data?: Record<string, unknown>   // optional node.data payload
   meta?: Record<string, unknown>   // optional extra meta fields (type, colId, title are always set explicitly and cannot be overridden here)
 }
@@ -847,8 +847,8 @@ How much each slice of one context has been reworked — read-only, derived from
 for it.
 
 A slice's rework is read from its own SLICE_BORDER history. Going backwards means a step down the progress order
-(Created → Ready → Planned → Assigned → InProgress → Handover → Review → Done), or reaching `Blocked` from
-`Handover`/`Review`/`Done`;
+(Created → Ready → Planned → Assigned → InProgress → Waiting → Review → Done), or reaching `Blocked` from
+`Waiting`/`Review`/`Done`;
 `Informational` is never scored. `reopens` counts transitions leading away from `Done`, `changes` counts writes to the
 slice itself. This says nothing about edits to the elements inside a slice.
 

package/shared/skills/ui-contract/SKILL.md

@@ -18,7 +18,7 @@ records that as a contract — the endpoint's **OpenAPI operation**, one per sli
 
 ## When
 
-**Only when handover is on** — the task request's `Handover: on|off` line (authoritative; the runner resolves `run --handover` over the project setting), else `"handover": true` in `.eventmodelers/config.json`. With handover **off/unset**, do nothing: publish no contract, write no `## UI Contract` section, and finish the slice as `Done` (Step 4). The contract exists only for the UI kit that picks up `Handover` slices.
+**Only when handover is on** — the task request's `Handover: on|off` line (authoritative; the runner resolves `run --handover` over the project setting), else `"handover": true` in `.eventmodelers/config.json`. With handover **off/unset**, do nothing: publish no contract, write no `## UI Contract` section, and finish the slice as `Done` (Step 4). The contract exists only for the UI kit that picks up `Waiting` slices.
 
 At the end of building a slice, **after** the endpoint exists (so the contract describes the real
 route, not the plan), before the final commit:
@@ -99,7 +99,7 @@ every MARKDOWN node of the slice's column as a plain string in `slice.json` `not
 `outline` / `fields` / `specs` projections leave `notes` out). The UI build kit therefore needs no
 extra file and no board call.
 
-## Step 4 — Completion status: `Handover` instead of `Done`
+## Step 4 — Completion status: `Waiting` instead of `Done`
 
 A slice with a UI is only finished once the UI kit has built its half. Whether this build kit hands
 over is decided per run, in this order: the task request's `Handover: on|off` line (authoritative — the
@@ -107,11 +107,11 @@ runner resolves `run --handover` over the project setting), else `"handover": tr
 `.eventmodelers/config.json` (saved by `init --handover` / `eventmodelers config --handover on|off`).
 
 - **On** — the build kit's "set the slice to `Done`" for a STATE_VIEW / STATE_CHANGE slice means
-  **`Handover`** instead: after the contract is published and the commit/merge succeeded. Where the build
-  kit's prompt says to call `update-slice-status` (a queued task), set `Handover` through it,
+  **`Waiting`** instead: after the contract is published and the commit/merge succeeded. Where the build
+  kit's prompt says to call `update-slice-status` (a queued task), set `Waiting` through it,
   mirrored in the local `index.json`. For a run-loop build (the task request names the slice), record it
-  with `npx @eventmodelers/cli slice-status Handover` — the run loop pushes it to the board; do not call
-  `update-slice-status`. The UI kit claims `Handover` slices and sets `Done` when its UI is built.
+  with `npx @eventmodelers/cli slice-status Waiting` — the run loop pushes it to the board; do not call
+  `update-slice-status`. The UI kit claims `Waiting` slices and sets `Done` when its UI is built.
 - **Off / unset** — nothing changes: `Done`.
 - Automations and translations have no UI → always `Done`.
 

package/shared/skills/update-slice-status/SKILL.md

@@ -26,7 +26,7 @@ Valid status values (case-sensitive):
 | `Ready` | Modeling is done — specified and ready to be planned for implementation |
 | `Planned` | Work is planned — queued for the backend build kit |
 | `InProgress` | Work is actively in progress |
-| `Handover` | Backend built and its UI contract published (`## UI Contract` in the slice's markdown note) — queued for the UI build kit |
+| `Waiting` | Backend built and its UI contract published (`## UI Contract` in the slice's markdown note) — queued for the UI build kit |
 | `Review` | Ready for review |
 | `Done` | Completed |
 | `Blocked` | Blocked by something |

package/stacks/axon/templates/build-kit/CLAUDE.md

@@ -53,9 +53,10 @@ When asked to build a slice, always follow this flow:
    - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
    - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
 3. Invoke the matching skill and follow its instructions completely. Do not deviate.
-4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
-5. Run quality checks (`./mvnw compile -q`, then the slice tests only).
-6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
+4. **Baseline gate**: run `npx @eventmodelers/cli build-baseline check --scope backend` first and act only on its verdict — `UNCHANGED` means nothing on the board changed since the last recorded build: do not rebuild, just run the slice's tests and finish; `NO_BASELINE`/`UNKNOWN` mean one full field-by-field diff of slice.json against the code; `CHANGED` lists exactly which elements changed, were added or removed — diff and fix only those. After the checks pass and before committing, run `build-baseline record --scope backend`. A screen or UI prompt change never triggers a backend build.
+5. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
+6. Run quality checks (`./mvnw compile -q`, then the slice tests only).
+7. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Waiting`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.
 

package/stacks/axon/templates/build-kit/lib/backend-prompt.md

@@ -42,7 +42,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
     If the tests for the slice are not yet named predictably, run `./mvnw test -q` and check for failures.
 15. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge ( update
     first )
-16. Record the outcome with `npx @eventmodelers/cli slice-status Done` — not by editing index.json, and do not call `update-slice-status`: the run loop pushes the status to the board when your turn ends. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to record is `Handover`, not `Done` — see the `ui-contract` skill, Step 4. A slice you could not finish needs no status: leave it as it is and the run loop discards the attempt.
+16. Record the outcome with `npx @eventmodelers/cli slice-status Done` — not by editing index.json, and do not call `update-slice-status`: the run loop pushes the status to the board when your turn ends. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to record is `Waiting`, not `Done` — see the `ui-contract` skill, Step 4. A slice you could not finish needs no status: leave it as it is and the run loop discards the attempt.
 17. Record any reusable learning you have not recorded yet (see **Recording Learnings**).
 18. If an entry in `.build-kit/AGENTS.md` turned out wrong or obsolete, retract it (see **Recording Learnings**).
 19. Finish the iteration.
@@ -64,6 +64,16 @@ npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 - `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
 - One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
+### Recording Info
+
+Something that is **not** a reusable learning — you cannot change something and why, a decision you took, a note for whoever reads the board — is an info, not a learning. Never leave it only in your reply:
+
+```
+npx @eventmodelers/cli info "<one terse line>" --kind limitation|decision|note
+```
+
+It is recorded as an event and posted as a comment on the slice you are building (`--slice <id>` to name another). Reusable knowledge stays a `learn`.
+
 ## Update AGENTS.md Files
 
 Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:

package/stacks/axon/templates/build-kit/lib/prompt.md

@@ -58,6 +58,20 @@ This is the build trigger. Setting `InProgress` and building are one atomic step
 
 4. Invoke the matching skill and follow its instructions **completely**. Do NOT implement the slice manually.
 
+   **Baseline gate** — before touching any code, run `npx @eventmodelers/cli build-baseline check --scope backend`.
+   It compares the board's node hashes of every element of the slice (commands, events, read models,
+   processors, specifications, ...) with what was recorded after the last successful build:
+   - `UNCHANGED` — nothing on the board changed. Do not rebuild or re-diff; run the slice's tests and
+     finish. Only now is "no code changes needed" a valid outcome.
+   - `NO_BASELINE` / `UNKNOWN` — no recorded build, or the board could not be read: do one full
+     field-by-field diff of slice.json against the code (never treat `UNKNOWN` as `UNCHANGED`).
+   - `CHANGED` — it lists the elements that changed, were added or were removed. Diff slice.json
+     against the code for exactly those and fix every drift; leave what matches alone.
+
+   When the checks pass, run `npx @eventmodelers/cli build-baseline record --scope backend` **before
+   committing**, so `ui-baseline.json` is committed with the slice. Never record without having done the
+   work the verdict asked for. Screens and UI prompts are not this kit's business and never trigger a build.
+
 5. **Verify against slice.json**: Cross-check the implementation — every command field, event field, and specification in slice.json must appear in the code. No invented fields — if it is not in slice.json, it must not be in the code.
 
 6. Run quality checks:
@@ -98,6 +112,16 @@ npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 - `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
 - One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
+### Recording Info
+
+Something that is **not** a reusable learning — you cannot change something and why, a decision you took, a note for whoever reads the board — is an info, not a learning. Never leave it only in your reply:
+
+```
+npx @eventmodelers/cli info "<one terse line>" --kind limitation|decision|note
+```
+
+It is recorded as an event and posted as a comment on the slice you are building (`--slice <id>` to name another). Reusable knowledge stays a `learn`.
+
 ## Important
 
 - Process **one task per iteration**.

package/stacks/blank/templates/build-kit/CLAUDE.md

@@ -43,9 +43,10 @@ When asked to build a slice, always follow this flow:
    - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
    - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
 3. Invoke the matching skill and follow its instructions completely. Do not deviate.
-4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
-5. Run quality checks (TODO: this stack's build + test commands), then the slice tests only.
-6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
+4. **Baseline gate**: run `npx @eventmodelers/cli build-baseline check --scope backend` first and act only on its verdict — `UNCHANGED` means nothing on the board changed since the last recorded build: do not rebuild, just run the slice's tests and finish; `NO_BASELINE`/`UNKNOWN` mean one full field-by-field diff of slice.json against the code; `CHANGED` lists exactly which elements changed, were added or removed — diff and fix only those. After the checks pass and before committing, run `build-baseline record --scope backend`. A screen or UI prompt change never triggers a backend build.
+5. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
+6. Run quality checks (TODO: this stack's build + test commands), then the slice tests only.
+7. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Waiting`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.
 

package/stacks/blank/templates/build-kit/lib/backend-prompt.md

@@ -32,7 +32,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 12. Only when `handover` is on (the task's `Handover: on` line), invoke the `ui-contract` skill for STATE_VIEW / STATE_CHANGE slices; with handover off skip this step (publishes the UI Contract section to the slice's feedback-lane markdown node)
 13. Run quality checks — TODO: your stack's build command, TODO: your stack's test command (slice-scoped only; do not run all tests).
 14. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge (update first)
-15. Record the outcome with `npx @eventmodelers/cli slice-status Done` — not by editing index.json, and do not call `update-slice-status`: the run loop pushes the status to the board when your turn ends. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to record is `Handover`, not `Done` — see the `ui-contract` skill, Step 4. A slice you could not finish needs no status: leave it as it is and the run loop discards the attempt.
+15. Record the outcome with `npx @eventmodelers/cli slice-status Done` — not by editing index.json, and do not call `update-slice-status`: the run loop pushes the status to the board when your turn ends. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to record is `Waiting`, not `Done` — see the `ui-contract` skill, Step 4. A slice you could not finish needs no status: leave it as it is and the run loop discards the attempt.
 16. Record any reusable learning you have not recorded yet (see **Recording Learnings**).
 17. If an entry in `.build-kit/AGENTS.md` turned out wrong or obsolete, retract it (see **Recording Learnings**).
 18. Finish the iteration.
@@ -54,6 +54,16 @@ npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 - `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
 - One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
+### Recording Info
+
+Something that is **not** a reusable learning — you cannot change something and why, a decision you took, a note for whoever reads the board — is an info, not a learning. Never leave it only in your reply:
+
+```
+npx @eventmodelers/cli info "<one terse line>" --kind limitation|decision|note
+```
+
+It is recorded as an event and posted as a comment on the slice you are building (`--slice <id>` to name another). Reusable knowledge stays a `learn`.
+
 ## Update AGENTS.md Files
 
 Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files — API patterns/conventions, gotchas, dependencies between files, testing approaches, configuration/environment requirements.

package/stacks/blank/templates/build-kit/lib/prompt.md

@@ -56,6 +56,20 @@ This is the build trigger. Setting `InProgress` and building are one atomic step
 
 4. Invoke the matching skill and follow its instructions **completely**. Do NOT implement the slice manually.
 
+   **Baseline gate** — before touching any code, run `npx @eventmodelers/cli build-baseline check --scope backend`.
+   It compares the board's node hashes of every element of the slice (commands, events, read models,
+   processors, specifications, ...) with what was recorded after the last successful build:
+   - `UNCHANGED` — nothing on the board changed. Do not rebuild or re-diff; run the slice's tests and
+     finish. Only now is "no code changes needed" a valid outcome.
+   - `NO_BASELINE` / `UNKNOWN` — no recorded build, or the board could not be read: do one full
+     field-by-field diff of slice.json against the code (never treat `UNKNOWN` as `UNCHANGED`).
+   - `CHANGED` — it lists the elements that changed, were added or were removed. Diff slice.json
+     against the code for exactly those and fix every drift; leave what matches alone.
+
+   When the checks pass, run `npx @eventmodelers/cli build-baseline record --scope backend` **before
+   committing**, so `ui-baseline.json` is committed with the slice. Never record without having done the
+   work the verdict asked for. Screens and UI prompts are not this kit's business and never trigger a build.
+
 5. **Verify against slice.json**: cross-check the implementation — every command field, event field, and specification in slice.json must appear in the code. No invented fields — if it is not in slice.json, it must not be in the code.
 
 6. Run quality checks (TODO: your stack's build + test commands — slice-scoped tests only, not the full suite).
@@ -98,6 +112,16 @@ npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 - `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
 - One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
+### Recording Info
+
+Something that is **not** a reusable learning — you cannot change something and why, a decision you took, a note for whoever reads the board — is an info, not a learning. Never leave it only in your reply:
+
+```
+npx @eventmodelers/cli info "<one terse line>" --kind limitation|decision|note
+```
+
+It is recorded as an event and posted as a comment on the slice you are building (`--slice <id>` to name another). Reusable knowledge stays a `learn`.
+
 ## Important
 
 - Process **one task per iteration**.

package/stacks/classic/templates/build-kit/CLAUDE.md

@@ -48,11 +48,12 @@ When asked to build a slice, always follow this flow:
    - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
    - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
 4. Invoke the matching skill and follow its instructions completely. Do not deviate.
-5. **Verify against slice.json**: After the skill completes, check that every command field, event field, read model field and specification in slice.json has its counterpart in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
-6. Run the quality checks from `.build-kit/ARCHITECTURE.md` (build/compile, then only the tests this slice touched).
-7. If checks pass, make sure the slice's row in the Slice map is added/updated and commit with `feat: [Slice Name]`.
-8. Invoke `/record-evidence` — it writes the implementation evidence (element → code mapping, files, specification → test mapping, seams, assumptions, commit) as a markdown note into the slice's column, in the chapter's `Implementation` feedback lane.
-9. Set slice status to `Done`.
+5. **Baseline gate**: run `npx @eventmodelers/cli build-baseline check --scope backend` first and act only on its verdict — `UNCHANGED` means nothing on the board changed since the last recorded build: do not rebuild, just run the slice's tests and finish; `NO_BASELINE`/`UNKNOWN` mean one full field-by-field diff of slice.json against the code; `CHANGED` lists exactly which elements changed, were added or removed — diff and fix only those. After the checks pass and before committing, run `build-baseline record --scope backend`. A screen or UI prompt change never triggers a backend build.
+6. **Verify against slice.json**: After the skill completes, check that every command field, event field, read model field and specification in slice.json has its counterpart in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
+7. Run the quality checks from `.build-kit/ARCHITECTURE.md` (build/compile, then only the tests this slice touched).
+8. If checks pass, make sure the slice's row in the Slice map is added/updated and commit with `feat: [Slice Name]`.
+9. Invoke `/record-evidence` — it writes the implementation evidence (element → code mapping, files, specification → test mapping, seams, assumptions, commit) as a markdown note into the slice's column, in the chapter's `Implementation` feedback lane.
+10. Set slice status to `Done`.
 
 After you are done, automatically run the tests for the slice that was edited.
 

package/stacks/classic/templates/build-kit/lib/backend-prompt.md

@@ -36,7 +36,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 13. Run the quality checks listed in `.build-kit/ARCHITECTURE.md` — build/compile, then only the tests touched by this slice (do not run all tests).
 14. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge (update first)
 15. Invoke `/record-evidence` to write the implementation evidence (element → code mapping, files, specification → test mapping, seams, assumptions, commit) as a note into the slice's column, in the chapter's `Implementation` feedback lane.
-16. Record the outcome with `npx @eventmodelers/cli slice-status Done` — not by editing index.json, and do not call `update-slice-status`: the run loop pushes the status to the board when your turn ends. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to record is `Handover`, not `Done` — see the `ui-contract` skill, Step 4. A slice you could not finish needs no status: leave it as it is and the run loop discards the attempt.
+16. Record the outcome with `npx @eventmodelers/cli slice-status Done` — not by editing index.json, and do not call `update-slice-status`: the run loop pushes the status to the board when your turn ends. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to record is `Waiting`, not `Done` — see the `ui-contract` skill, Step 4. A slice you could not finish needs no status: leave it as it is and the run loop discards the attempt.
 17. Record any reusable learning you have not recorded yet (see **Recording Learnings**).
 18. If an entry in `.build-kit/AGENTS.md` turned out wrong or obsolete, retract it (see **Recording Learnings**).
 19. Finish the iteration.
@@ -58,6 +58,16 @@ npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 - `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
 - One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
+### Recording Info
+
+Something that is **not** a reusable learning — you cannot change something and why, a decision you took, a note for whoever reads the board — is an info, not a learning. Never leave it only in your reply:
+
+```
+npx @eventmodelers/cli info "<one terse line>" --kind limitation|decision|note
+```
+
+It is recorded as an event and posted as a comment on the slice you are building (`--slice <id>` to name another). Reusable knowledge stays a `learn`.
+
 ## Update AGENTS.md Files
 
 Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files — API patterns/conventions, gotchas, dependencies between files, testing approaches, configuration/environment requirements.

package/stacks/classic/templates/build-kit/lib/prompt.md

@@ -58,6 +58,20 @@ This is the build trigger. Setting `InProgress` and building are one atomic step
 
 5. Invoke the matching skill and follow its instructions **completely**. Do NOT implement the slice manually.
 
+   **Baseline gate** — before touching any code, run `npx @eventmodelers/cli build-baseline check --scope backend`.
+   It compares the board's node hashes of every element of the slice (commands, events, read models,
+   processors, specifications, ...) with what was recorded after the last successful build:
+   - `UNCHANGED` — nothing on the board changed. Do not rebuild or re-diff; run the slice's tests and
+     finish. Only now is "no code changes needed" a valid outcome.
+   - `NO_BASELINE` / `UNKNOWN` — no recorded build, or the board could not be read: do one full
+     field-by-field diff of slice.json against the code (never treat `UNKNOWN` as `UNCHANGED`).
+   - `CHANGED` — it lists the elements that changed, were added or were removed. Diff slice.json
+     against the code for exactly those and fix every drift; leave what matches alone.
+
+   When the checks pass, run `npx @eventmodelers/cli build-baseline record --scope backend` **before
+   committing**, so `ui-baseline.json` is committed with the slice. Never record without having done the
+   work the verdict asked for. Screens and UI prompts are not this kit's business and never trigger a build.
+
 6. **Verify against slice.json**: cross-check the implementation — every command field, event field, and specification in slice.json must appear in the code. No invented fields — if it is not in slice.json, it must not be in the code.
 
 7. Run the quality checks listed in `.build-kit/ARCHITECTURE.md` (build/compile, then only the tests touched by this slice — not the full suite).
@@ -102,6 +116,16 @@ npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 - `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
 - One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
+### Recording Info
+
+Something that is **not** a reusable learning — you cannot change something and why, a decision you took, a note for whoever reads the board — is an info, not a learning. Never leave it only in your reply:
+
+```
+npx @eventmodelers/cli info "<one terse line>" --kind limitation|decision|note
+```
+
+It is recorded as an event and posted as a comment on the slice you are building (`--slice <id>` to name another). Reusable knowledge stays a `learn`.
+
 ## Important
 
 - Process **one task per iteration**.

package/stacks/kurrent/templates/build-kit/CLAUDE.md

@@ -87,13 +87,14 @@ When asked to build a slice, always follow this flow:
    - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
    - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
 3. Invoke the matching skill and follow its instructions completely. Do not deviate.
-4. **Verify against slice.json**: After the skill completes, check that every command field, event field,
+4. **Baseline gate**: run `npx @eventmodelers/cli build-baseline check --scope backend` first and act only on its verdict — `UNCHANGED` means nothing on the board changed since the last recorded build: do not rebuild, just run the slice's tests and finish; `NO_BASELINE`/`UNKNOWN` mean one full field-by-field diff of slice.json against the code; `CHANGED` lists exactly which elements changed, were added or removed — diff and fix only those. After the checks pass and before committing, run `build-baseline record --scope backend`. A screen or UI prompt change never triggers a backend build.
+5. **Verify against slice.json**: After the skill completes, check that every command field, event field,
    and specification in slice.json appears in the implementation. No invented fields — if it is not in
    slice.json, it must not be in the code. This applies even when the slice was previously `Done` and
    reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff
    slice.json against the code field by field and update the code to match every change.
-5. Run quality checks (`./mvnw compile -q`, then the slice tests only).
-6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
+6. Run quality checks (`./mvnw compile -q`, then the slice tests only).
+7. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Waiting`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.