@eventmodelers/cli 2.0.1 → 2.0.3

package/stacks/supabase-react/templates/.claude/skills/build-state-change/SKILL.md

@@ -71,8 +71,9 @@ Extract:
 - **screens[]** — the actor `SCREEN` element(s) that trigger this command, if any. Empty when the
   command has no UI trigger (rare — build the component from fields alone in that case, skip Step
   2).
-- **specifications[]** — GWT scenarios; treat as acceptance criteria for the component's business
-  logic (e.g. "given empty `email`, submit is disabled").
+- **specifications[]** and **storylines[]** (optional) — GWT scenarios / board walkthroughs. These
+  describe how the slice should **behave** — read them in full (Step 3a) to understand the outcomes
+  and states the UI must present. The business logic itself lives in the backend; the UI does not implement it.
 
 > **Comments**: each element carries `comments: string[]` (board comments) — read them as
 > implementation hints, and resolve consumed ones via
@@ -80,6 +81,10 @@ Extract:
 
 ## Step 2 — Read the screen, and especially its marks
 
+> **Gated by `ui-baseline check`** (build prompt, `lib/prompt.md`, Step 4): do this step when the verdict
+> is `SCREEN_CHANGED`, `NO_BASELINE` or `UNKNOWN` — and then also diff the existing JSX against the fetched
+> screen and adjust the UI to it. On `UNCHANGED` skip it.
+
 `slice.json`'s `screens[]` entries only carry `id`/`title`/`fields[]`/`description` (fields already
 scoped to this slice) — not the actual markup. Fetch the live node to get that:
 
@@ -132,19 +137,76 @@ lane concept, so the frontend path isn't a strict 1:1 mirror of it. `CommandTitl
 **Markup**: translate the blueprint HTML from Step 2 into JSX **1:1** — same tags, same classes
 (the screen's `cssFrameworks` framework), same layout and copy. This is not a redesign; the screen *is*
 the design. Only change what must become dynamic:
-- A field's example value becomes that input's controlled `value`.
+- A field's example value becomes that input's **initial/default** `value` only for what the user is
+  *entering* (a new-record form). Anything the screen *displays* about an existing entity (names,
+  titles, current selection, existing tags, list rows) is **not** static — see "Data binding" below.
 - An element repeated for a `cardinality: "List"` field becomes a `.map()` over that field.
 - `class`/`style`/structure otherwise stay exactly as drawn — except the board's own mark plumbing:
   drop every `data-em-mark-id` attribute and `em-mark`/`em-mark-<hex>` class (they only draw the
   highlight outline on the canvas; the app never ships it).
 - The classes only render correctly if the screen's CSS framework (`cssFrameworks`) is loaded in the app — see Step 7 (styles); don't hand-write CSS to compensate.
 
+**Data binding — mockup text is sample data, not copy.** The example values drawn in a screen are
+placeholders from the model. Before translating, classify every piece of text/value in the fragment:
+*label/copy* (headings like "Tags", button captions, placeholders — keep verbatim) vs. *data* (a person's
+name, a role/organisation line, a pre-selected dropdown value, dropdown options, existing list rows,
+badges, counts, dates). For each *data* item find its source in `slice.json` / the model — the
+`readmodels[]` whose fields carry it, or the command's own `fields[]` — and render it from there.
+**Never hardcode a data value from the mockup into JSX.**
+
+**Find the screen's data sources on the board, not just in `slice.json`.** A screen is often shown by
+one slice but fed by a read model that belongs to *another* slice (e.g. the Contact Details screen
+sits in the Assign Tag slice, yet its contact data comes from the Contact List read model via an edge
+READMODEL → SCREEN). `slice.json` only lists this slice's own elements, so also call
+`mcp__eventmodelers__get_connected_nodes { boardId, nodeId: <screen.id> }` and take every READMODEL
+wired into the screen. Each one is a data source for the displayed values; look up its fields in that
+read model's slice (`.build-kit/.slices/*/*/slice.json`, or `get_node`). A list read model feeding a
+detail screen (`Contact List[]` → one contact) means: query it filtered by the entity id the page
+gets from the route (match the id field, e.g. `contactId` / the command's `recordId`) and render that
+row. If the source read model's slice isn't built, still type and wire against its fields (TODO), do
+not substitute the mockup's values.
+
+- Data comes from a read model (query component of the same page/screen, via `queryReadModel` /
+  `getReadModel`) → bind it to that data (props from the parent that fetched it, or fetch it here
+  when this component owns that read). If that read-model slice is not built yet, wire the component
+  against the typed shape and leave a `// TODO(<read model title>)` — do not paste the example in.
+- Select/dropdown *options* come from a read model (e.g. the customer list), never from the
+  options drawn in the mockup; the *selected* value comes from the entity's own read model.
+- The only legitimate static content is label/copy and `VITE_DATA_MODE=mock` samples in `samples/*.json`.
+- Self-check before finishing: grep the component for the mockup's example strings (e.g. the person's
+  name, organisation, tag text). Any hit outside `samples/` is a bug.
+
 **Props**: exactly `command.fields[]`, typed per each field's `type` (`String`→`string`,
 `Boolean`→`boolean`, `Int`/`Long`→`number`, etc. — `subfields[]` become a nested object type),
 respecting `optional`. Add two callback props: `onSuccess?: (result: TResponse) => void` and
 `onError?: (error: ApiError) => void`. **No other inputs** — no context/store reads, no fetching
 inside the component. All business data the component needs arrives via props from its parent.
 
+### Step 3a — Read the scenarios to understand behavior (not to implement rules)
+
+**Business logic lives in the backend. The UI never re-implements it.** Do not copy a scenario's
+rules (preconditions, limits, uniqueness, state checks) into the component as validation or guards —
+the backend decides, and a duplicated rule drifts the moment the model changes.
+
+Read every entry in `specifications[]` (and the beat runs in `storylines[]` containing this command)
+to understand **how the component should behave around the command**: what the user is trying to
+accomplish, what outcomes exist, and what each outcome must look like. Use them to decide:
+
+| Scenario shows | What it tells the UI |
+|---|---|
+| `when` this command → `then` EVENT(s) | the success outcome: what to confirm or reset after `postCommand` resolves, and what `onSuccess` hands the parent |
+| `when` this command → `then` an error / rejection (e.g. "already reserved") | the failure outcomes that exist: render each as its own readable message from the `ApiError` the backend returns — not one generic failure. The backend decides *whether* it fails; the UI only shows it |
+| `optional` fields, fields that vary between scenarios | which inputs are required vs. optional in the form (mirror the flags, no invented rules) |
+| `given` events before the command | context for what the user was doing — background to understand the flow, not logic to reproduce |
+| a `STORYLINE_NOTE` beat | background only |
+
+Rules:
+- Understand, don't implement: no business validation, no precondition checks, no computed outcomes
+  in the component. Only presentation: states (idle/submitting/success/error), required-vs-optional
+  inputs, and showing what the backend returns.
+- If a scenario's outcome needs a UI state the markup doesn't show, add the minimal state and note
+  the scenario in a one-line comment (e.g. `// spec: "already reserved" → backend 409 shown inline`).
+
 **Default — keep the logic in the component.** For an ordinary command (one form, one submit
 action, which is most of them) local state and the `postCommand` call live directly inside the
 component. This is the common case and needs nothing more:
@@ -211,9 +273,10 @@ is driven entirely by props, each sample is a **full set of prop values** — th
 renders this component in isolation (a `src/pages/` composition, or ad hoc while developing) to
 spread as props, e.g. `<ReserveBike {...sample1} onSuccess={...} />`.
 
-Add `sample-1.json` for the ordinary case (`command.fields[].example` values); add more numbered
-ones for other scenarios `specifications[]` calls out (an edge case, an `optional` field omitted,
-...). As in `build-state-view`, the same number across different components' samples is meant to
+Add `sample-1.json` for the ordinary case (`command.fields[].example` values); add a numbered
+sample for **each** scenario in `specifications[]` that changes what the component does (an invalid
+input that blocks submit, an `optional` field omitted, a precondition that disables the trigger).
+Take the values from the scenario's own example data. As in `build-state-view`, the same number across different components' samples is meant to
 represent one coherent scenario across the app, not an arbitrary per-component index.
 
 ## Step 5 — Context/Provider, only if the marked fragment needs shared local state
@@ -290,6 +353,13 @@ how many pages this app needs — not one page per slice.
      content there, passing whatever props it declares. Only substitute positions whose slice
      component already exists; leave any not-yet-built slice's marked area as the mockup's static
      placeholder until that slice is built and this step runs again for it.
+   - **Unmarked/unbuilt regions are not an excuse to hardcode data.** Static placeholder is only for
+     label/copy. A displayed data value (e.g. the contact's name and "role · organisation" line, the
+     selected organisation and the organisation dropdown options) must be bound to the read model that
+     carries it — if that read model's component exists (e.g. the contact list/details read), fetch
+     through it and pass the values down; if not, type the prop and leave a `// TODO(<read model>)`.
+     Never paste the mockup's example (or a slice's `samples/sample-1.json`) into the page as the
+     data. The page reads the entity id from the route/query param.
    - The page owns threading shared inputs (route/query params, the current session, etc.) down as
      props to each slice component — a slice component still only knows its own declared props, not
      the rest of the page or its siblings.
@@ -348,6 +418,8 @@ After writing the hook/component (and context/page/base page, if any), confirm:
   time, the provisional `/api/mock/...` path noted in a comment (Step 1).
 - At least one numbered sample exists under this slice's `samples/` folder, shaped exactly like
   this component's props.
+- Every scenario outcome (success, each named failure) has a rendered state, and **no business rule
+  from a scenario was re-implemented in the component** — the backend owns it.
 - If a screen was read in Step 2, the rendered JSX matches the marked (or whole, if unmarked)
   HTML fragment structurally — no invented buttons/fields the mockup didn't show, nothing from
   the mockup silently dropped.

package/stacks/supabase-react/templates/.claude/skills/build-state-view/SKILL.md

@@ -67,10 +67,13 @@ Extract:
        a Slice" step 6) — the built, mocked component still needs a real table/view before it's done,
        so don't flip it to `Done`.
   - `description` — implementation hints (filtering rules, sort order, business meaning).
-- **UI contract (read)** — the backend slice's published `GET` contract: look it up as described in
+- **UI contract (read)** — **not used for a read model backed by a table, which is the normal case on this
+  stack: that is always read directly with `queryReadModel`, even when the backend published a `GET`
+  contract.** Only when `slice.json` says the read model is not a persisted table (a computed view, an
+  external source) does the backend's published `GET` contract apply: look it up as described in
   the `ui-contract` skill ("How the UI build kit looks the contract up" — the `## UI Contract` entry in
-  `slice.json` `notes[]`; parse only its `ui-contract` block — an OpenAPI operation). **When present it
-  is the specification and you build the call from it** — it overrides `apiEndpoint` and the table read:
+  `slice.json` `notes[]`; parse only its `ui-contract` block — an OpenAPI operation). **In that case it
+  is the specification and you build the call from it** — it overrides `apiEndpoint`:
   - fetch with `getReadModel(buildPath('<contract path>', { <path params> }), { <query params> }, samples)`
     from `src/lib/api.ts` — path and query `parameters` exactly as the contract names them, never a
     guessed URL, never `supabase.from(...)`;
@@ -84,14 +87,19 @@ Extract:
   `readmodel.apiEndpoint` (table/view name) + `fields[]` via `queryReadModel` — and note the assumption
   as a code comment.
 - **screens[]** — the actor `SCREEN` element(s) that display this data, if any (see Step 2).
-- **specifications[]** — GWT scenarios/storyline; treat as acceptance criteria (e.g. "given no
-  active reservation, show an empty state").
+- **specifications[]** and **storylines[]** (optional) — GWT scenarios / board walkthroughs. These
+  describe how the slice should **behave** — read them in full (Step 3a) to understand the outcomes
+  and states the UI must present. The business logic itself lives in the backend; the UI does not implement it.
 
 > **Comments**: as in `build-state-change` — resolve consumed ones via the same node-comment
 > endpoint.
 
 ## Step 2 — Read the screen, and especially its marks
 
+> **Gated by `ui-baseline check`** (build prompt, `lib/prompt.md`, Step 4): do this step when the verdict
+> is `SCREEN_CHANGED`, `NO_BASELINE` or `UNKNOWN` — and then also diff the existing JSX against the fetched
+> screen and adjust the UI to it. On `UNCHANGED` skip it.
+
 Identical to `build-state-change` Step 2 — fetch the live screen node
 (`mcp__eventmodelers__get_node`), find this slice's marked fragment in `meta.pages`/`meta.marks`
 (or the whole page if unmarked), and treat it as the blueprint. The same `learn-styleguide` note
@@ -112,16 +120,39 @@ multi-read-model component.
 **Markup**: same rule as `build-state-change` — translate the blueprint from Step 2 1:1 into JSX;
 the mockup is the design, not a starting point for a redesign.
 
+**Data binding — the whole point of a read-model component.** Every *data* value in the mockup (names,
+role/organisation lines, selected values, dropdown options, list rows, badges, counts, dates) is a
+sample taken from the model's examples; it must be rendered from the queried data, mapped from
+`readmodel.fields[]` — keep only label/copy (headings, button captions, placeholders) verbatim.
+Check where each displayed value comes from before writing JSX: a field of this read model → bind it;
+a field of another read model on the same screen → it arrives as a prop from the parent that fetched
+it (or a sibling read-model component), never from the mockup. List rows are a `.map()` over the
+fetched rows, not the rows drawn. Self-check: grep the component for the mockup's example strings;
+any hit outside `samples/` means hardcoded data — fix it.
+
+**Find the screen's data sources on the board, not just in `slice.json`.** A screen is often shown by
+one slice but fed by a read model that belongs to *another* slice (e.g. the Contact Details screen
+sits in the Assign Tag slice, yet its contact data comes from the Contact List read model via an edge
+READMODEL → SCREEN). `slice.json` only lists this slice's own elements, so also call
+`mcp__eventmodelers__get_connected_nodes { boardId, nodeId: <screen.id> }` and take every READMODEL
+wired into the screen. Each one is a data source for the displayed values; look up its fields in that
+read model's slice (`.build-kit/.slices/*/*/slice.json`, or `get_node`). A list read model feeding a
+detail screen (`Contact List[]` → one contact) means: query it filtered by the entity id the page
+gets from the route (match the id field, e.g. `contactId` / the command's `recordId`) and render that
+row. If the source read model's slice isn't built, still type and wire against its fields (TODO), do
+not substitute the mockup's values.
+
+
 **Props**: whatever the component needs to *scope* its query (e.g. `customerId`) — passed in from
 its parent, never read from a global store. The queried data itself is **not** a prop — the
 component fetches it.
 
-**With a UI contract (Step 1)**: call `getReadModel(buildPath(path, pathParams), queryParams, samples)`
+**With a UI contract (Step 1, non-table read models only)**: call `getReadModel(buildPath(path, pathParams), queryParams, samples)`
 from `src/lib/api.ts` inside the component instead of the `queryReadModel` snippet below — same
 effect shape (`useEffect` → loading / empty / error / data), but each documented non-2xx response
 (`ApiError.status`) maps to its own state. Never a raw `fetch`.
 
-**Default (no contract) — call `queryReadModel` from `src/lib/api.ts` inside the component**. Never
+**Default (a table-backed read model — always, unless the contract case above applies) — call `queryReadModel` from `src/lib/api.ts` inside the component**. Never
 `supabase.from(...)` directly, never a raw `fetch`:
 
 ```tsx
@@ -182,6 +213,26 @@ export function ActiveReservationView({ customerId }: ActiveReservationViewProps
 }
 ```
 
+### Step 3a — Read the scenarios to understand behavior (not to implement rules)
+
+**Business logic lives in the backend (the projection). The UI never re-derives it** — no
+recomputing totals, statuses or membership from events; render what the read model holds.
+
+Read every entry in `specifications[]` (and the READMODEL beats in `storylines[]`) to understand
+**what the read model looks like in different situations and how the component should present each**:
+
+| Scenario shows | What it tells the UI |
+|---|---|
+| `then` read model is empty (`expectEmptyList` / no rows) | an **empty state** must exist, distinct from loading and error |
+| the same field takes different values across scenarios (e.g. status `open` → `closed`) | each value needs a sensible presentation (label, badge, shown/hidden actions) — presentation only |
+| rows appear/disappear between scenarios | the component renders whatever rows the read model returns; it does not decide which belong |
+| row order visible across scenarios | hint for `order`/sort on the query, if the read model doesn't already guarantee it |
+| a `STORYLINE_NOTE` beat | background only |
+
+Rules:
+- Understand, don't implement: presentation of what the backend provides, nothing more.
+- Cite the scenario behind a non-obvious state in a one-line comment.
+
 Select fields explicitly by name rather than `select('*')`. Map each field's `name` to its actual
 column name — check the paired backend stack's migrations if the naming convention (e.g. camelCase
 vs. snake_case) isn't obvious rather than guessing; if genuinely unclear, use `request-feedback`.
@@ -202,7 +253,9 @@ otherwise; use `null`/`[]` for a sample meant to exercise the empty/background s
 
 Add at least one sample (`sample-1.json`) covering the ordinary case from
 `readmodel.fields[].example` values; add more numbered ones for whatever other scenarios this
-read model's `specifications[]` call out (e.g. an empty result, a second customer's data). The
+read model's `specifications[]` show — **one sample per distinct scenario outcome**, using the
+scenario's own example values (an empty result, each status a row can take, a second customer's
+data). The
 same number across *different* components' `samples/` folders is meant to represent one coherent
 scenario across the whole app (e.g. every component's `sample-2.json` together tell the story of
 "a long-time customer") — keep that in mind when choosing what a given number represents, rather
@@ -230,7 +283,7 @@ one page per slice.
    one place allowed to import across slice folders. Translate the screen's whole, unmarked
    `meta.pages` markup into JSX (the page-level layout), and at each `data-em-mark-id` position
    render that mark's owning slice's component (only for slices already built; leave the rest as
-   the mockup's static content until they are). The page threads shared inputs down as props; a
+   the mockup's static content until they are). Static placeholder content is label/copy only — displayed data (names, selections, options, rows) is bound to its read model, never the mockup's examples or a sample file. The page threads shared inputs down as props; a
    slice component still only knows its own declared props. Update only this slice's marked
    position if the page file already exists.
 
@@ -289,8 +342,8 @@ leaves it alone.
   slice.json.
 - At least one numbered sample exists under this slice's `samples/` folder, shaped exactly like
   `queryReadModel`'s return value.
-- The component renders a sensible empty/background state, distinct from loading/error, when the
-  data is `null`/`[]`.
+- Every scenario situation (empty, each distinct field value) has a rendered presentation, and the
+  component re-derives nothing the read model already holds.
 - If a screen was read in Step 2, the rendered JSX matches the marked (or whole, if unmarked) HTML
   fragment structurally.
 - Nothing in this slice's folder is imported from another slice's folder, and nothing outside it

package/stacks/supabase-react/templates/build-kit/CLAUDE.md

@@ -28,7 +28,7 @@ not attempt to build it, flag it via `request-feedback` instead.
 2. Maintain clear separation of concerns within each slice
 3. Headers, auth, `fetch`, and Supabase table access live exclusively in `src/lib/api.ts` — a
    slice component never imports `src/lib/supabase.ts` itself, never calls `fetch`, and never
-   calls `supabase.from(...)` directly; when the backend slice published a UI contract (`ui-contract` skill, `slice.json` `notes[]`) the slice is built *from* it — path, parameters, body and every error response — and falls back to `apiEndpoint`/`fields[]` only when none exists; it calls `postCommand`/`getReadModel`/`queryReadModel` and only contains
+   calls `supabase.from(...)` directly; a table-backed read model is always read directly with `queryReadModel` (the backend's `GET` contract is ignored for it); when the backend slice published a UI contract (`ui-contract` skill, `slice.json` `notes[]`) for a *write* or a non-table read, the slice is built *from* it — path, parameters, body and every error response — and falls back to `apiEndpoint`/`fields[]` only when none exists; it calls `postCommand`/`getReadModel`/`queryReadModel` and only contains
    business logic (validation, request-body shaping, response handling)
 4. A command's/read-model's screen markup (`meta.pages` on its actor HTML_SCREEN node, scoped to
    this slice's `meta.marks` when the screen is shared) is the visual blueprint — translate it into
@@ -122,9 +122,10 @@ When asked to build a slice, always follow this flow:
    - **`AUTOMATION`** → not this stack's job (no UI counterpart) — invoke `request-feedback`
      rather than building it; it belongs to whichever backend stack is installed alongside this one
 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.
-5. Run `npm run build` and `npm run lint` (both must pass clean), then the slice's own tests only, if any exist.
-6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done` — **unless** the
+4. **UI baseline gate**: run `npx @eventmodelers/cli ui-baseline check` first and act only on its verdict — `UNCHANGED` means skip all UI work; `NO_BASELINE`/`UNKNOWN` mean one full screen diff and every `codeGen.uiPrompts` entry; `CHANGED` names the elements that changed, were added or removed (work on exactly those) and flags `SCREEN_CHANGED` (re-fetch the screen node and adjust the components to it), `ELEMENTS_CHANGED` (diff slice.json against the code) and `PROMPTS_CHANGED` (apply the printed prompts). Details in `lib/prompt.md`, Step 4. After the checks pass and before committing, run `ui-baseline record`.
+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 — specifications are read (Step 3a of the build skill) to understand how the UI should behave and present outcomes; the business logic lives in the backend and is not re-implemented here. No invented fields — if it is not in slice.json, it must not be in the code.
+6. Run `npm run build` and `npm run lint` (both must pass clean), then the slice's own tests only, if any exist.
+7. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done` — **unless** the
    matching build skill flagged a missing `apiEndpoint` and already marked the slice `Blocked`
    (Step 1 exception above); in that case, commit as normal but leave the status `Blocked`.
 

package/stacks/supabase-react/templates/build-kit/lib/AGENT.md

@@ -43,4 +43,4 @@ These files are always up to date — read them directly before invoking any ski
 - The `boardId` and `organizationId` from each payload provide full context — pass them to skills.
 - Node events use `node:created`, `node:changed`, `node:deleted` — always POST to `/api/org/:orgId/boards/:boardId/nodes/events`.
 - Slice metadata (title, status) lives on the SLICE_BORDER node under `meta.sliceStatus` and `meta.title`.
-- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard, not a bug. It means another agent already claimed the slice. Treat it as `ALREADY_IN_STATUS`, skip that slice, and move on to the next `Handover` one instead of erroring out. This applies to queued tasks only: when the task request names the slice to build, the run loop owns its status — never call `/update-slice-status` there.
+- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard, not a bug. It means another agent already claimed the slice. Treat it as `ALREADY_IN_STATUS`, skip that slice, and move on to the next `Waiting` one instead of erroring out. This applies to queued tasks only: when the task request names the slice to build, the run loop owns its status — never call `/update-slice-status` there.

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

@@ -9,9 +9,9 @@ The structure defined in the Project-Skills is relevant.
 You work within **exactly ONE context at a time** — the one named in `.build-kit/.slices/current_context.json` (the runner picks it).
 
 - **ONLY** look for and build slices inside `.build-kit/.slices/<currentContext>/`.
-- **NEVER** read, scan, or build slices from any other context directory, even if it has "Handover" slices, and even if the current context has no work left.
-- A "Handover" slice in a *different* context is **NOT yours to build**. Ignore it completely.
-- If the current context has no "Handover" slice, you are **done for this iteration** — reply `<promise>NO_TASKS</promise>` and stop. Do not go looking elsewhere. The runner moves `current_context.json` on to the next context with Handover work between iterations — never change it yourself.
+- **NEVER** read, scan, or build slices from any other context directory, even if it has "Waiting" slices, and even if the current context has no work left.
+- A "Waiting" slice in a *different* context is **NOT yours to build**. Ignore it completely.
+- If the current context has no "Waiting" slice, you are **done for this iteration** — reply `<promise>NO_TASKS</promise>` and stop. Do not go looking elsewhere. The runner moves `current_context.json` on to the next context with Waiting work between iterations — never change it yourself.
 
 ## Your Task
 
@@ -19,8 +19,8 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 1. Read `.build-kit/.slices/current_context.json` to find the active context name, then read `.build-kit/.slices/<contextName>/index.json`. Every item in status "handover" is a task.
 2. Read `.build-kit/AGENTS.md` **if it exists** — the project's accumulated learnings, generated from what earlier builds recorded. If the slice's `slice.json` has a `lastAttempt`, an earlier attempt at it failed: read its `reason`, `lastReply`, `branch` and `changed`, and do not repeat what failed.
 3. Make sure you are on the right branch "feature/<slicename>", if unsure, start from main.
-5. Your slice is the one the task request names (the run loop picked the highest priority slice with status "Handover"); it becomes your PRD. The run loop has already claimed it — its status is "InProgress" in index.json and on the board. Build that slice and do not call `update-slice-status`: the run loop owns the slice's status on the board.
-   **IMPORTANT: Only work on the slice named in the task request. Never switch to another slice, whatever its status. If the task request names no slice and no slice has status "Handover" in the current context, reply with:**
+5. Your slice is the one the task request names (the run loop picked the highest priority slice with status "Waiting"); it becomes your PRD. The run loop has already claimed it — its status is "InProgress" in index.json and on the board. Build that slice and do not call `update-slice-status`: the run loop owns the slice's status on the board.
+   **IMPORTANT: Only work on the slice named in the task request. Never switch to another slice, whatever its status. If the task request names no slice and no slice has status "Waiting" in the current context, reply with:**
    <promise>NO_TASKS</promise> and stop immediately. Do not work on other slices and do not switch to another context.
 6. Pick the slice definition from `.build-kit/.slices/<contextName>/<folder>/slice.json` as defined in the prd. Never work on more than one slice per iteration.
 7. A slice can define additional prompts as codegen/backendPrompt. Any additional prompts defined in backend are hints for the implementation of the slice and have to be taken into account.
@@ -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.
@@ -90,12 +100,12 @@ A Slice is not complete if specifications are missing or can't be executed.
 
 ## Stop Condition
 
-**After completing ONE slice, always stop — regardless of whether more slices are in Handover.** The ralph loop will invoke you again for the next slice. Never chain multiple slices in one iteration.
+**After completing ONE slice, always stop — regardless of whether more slices are in Waiting.** The ralph loop will invoke you again for the next slice. Never chain multiple slices in one iteration.
 
 If the slice was completed and committed successfully, reply with:
 <promise>DONE</promise>
 
-If no slice has status "Handover" in the current context, reply with:
+If no slice has status "Waiting" in the current context, reply with:
 <promise>NO_TASKS</promise>
 (Do NOT switch to another context to find work — stop here.)
 

package/stacks/supabase-react/templates/build-kit/lib/kit.json

@@ -1,3 +1,3 @@
 {
-  "pickupStatus": "Handover"
+  "pickupStatus": "Waiting"
 }

package/stacks/supabase-react/templates/build-kit/lib/prompt.md

@@ -38,13 +38,13 @@ Run `/load-slice sliceId=<payload.sliceId>` to fetch full slice details (title,
 
 Inspect the `sliceStatus` in the payload:
 
-#### `Handover` — build the slice
+#### `Waiting` — build the slice
 
 This is the build trigger. Setting `InProgress` and building are one atomic step:
 
 1. Immediately call `/update-slice-status` to set the slice to `InProgress` on the board.
 
-   **Claim conflict**: if this call reports the slice is already in `InProgress` (or any status other than `Handover`), another agent already claimed it first — this is expected, not an error. Say so in your reply, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.
+   **Claim conflict**: if this call reports the slice is already in `InProgress` (or any status other than `Waiting`), another agent already claimed it first — this is expected, not an error. Say so in your reply, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.
 
 2. Run `/load-slice sliceId=<payload.sliceId>` to fetch the full slice, then read the slice definition from `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json`. The runner keeps a `slice.json` fresh from a summary endpoint, so a file holding only `id`, `title`, `status` and `sliceType` is that stub, not an empty slice — never conclude a slice has no elements from it. Only if the full fetch itself returns no commands/events/read models/fields is the slice actually empty.
 
@@ -56,7 +56,34 @@ 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.
 
-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.
+   **UI baseline gate** — before touching any code, run `npx @eventmodelers/cli ui-baseline check`. It
+   compares the board's node hashes (the slice's screen and every element) and `codeGen.uiPrompts` with
+   what was recorded after the last UI build, and decides what this build has to do:
+   - `UNCHANGED` — nothing on the board changed since the last UI build. Skip all UI work; do not
+     re-fetch or diff the screen. Only now is "no code changes needed" a valid outcome.
+   - `NO_BASELINE` — no UI build recorded yet (first build, or the slice predates the baseline). Do one
+     full screen diff (below), apply every UI prompt.
+   - `UNKNOWN` — the board could not be read. Treat it as `NO_BASELINE`; never as `UNCHANGED`.
+   - `CHANGED` — it also lists, per element, what changed, was added or was removed since the last recorded
+     build (e.g. `changed: Contact Details (screen), Assign Tag (command)`). Work on exactly those nodes
+     and leave what matches alone. Act on the parts it flags:
+     - `SCREEN_CHANGED`: re-fetch the live screen node (`get_node`, its `meta.pages` / `meta.marks`) —
+       never trust the JSX already in the repo — and diff the existing component(s) against the marked
+       (or whole, if unmarked) HTML: tags, classes, layout, copy, fields/buttons added, removed or
+       reordered, and `cssFrameworks`. Edit the components (and `src/pages/<ScreenTitle>.tsx`, for this
+       slice's marked position only) until they match 1:1 and update `samples/`. Keep what already
+       matches; do not regenerate the slice from scratch.
+     - `ELEMENTS_CHANGED`: diff slice.json against the code field by field (fields,
+       `apiEndpoint`/UI contract) and fix every drift.
+     - `PROMPTS_CHANGED`: apply the UI prompts it prints — each is an instruction the user typed on the
+       board for this slice's UI (e.g. "adjust the UI to the new layout!") — to the component(s) and
+       screen markup. Name each prompt and the change you made for it in your final reply.
+
+   When the UI work is done and the checks in step 6 pass, run `npx @eventmodelers/cli ui-baseline record`
+   **before committing**, so `ui-baseline.json` is committed with the slice. Never record without having
+   done the work the verdict asked for.
+
+5. **Verify against slice.json**: first check where every displayed value comes from — screen examples are samples, so names, selections, options and list rows must be bound to the read model (grep the components for the mockup's example strings; hits outside `samples/` are hardcoded data and must be fixed). Then cross-check the implementation — every command field, event field, and specification in slice.json must appear in the code — specifications are read (Step 3a of the build skill) to understand how the UI should behave and present outcomes; the business logic itself lives in the backend and is not re-implemented here. No invented fields — if it is not in slice.json, it must not be in the code.
 
 6. Run `npm run build` and `npm run lint` (both must pass clean) — plus the slice's own tests only, if any exist.
 
@@ -108,6 +135,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/umadb/templates/build-kit/CLAUDE.md

@@ -59,9 +59,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/umadb/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/umadb/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**.