@eventmodelers/cli 1.0.19 → 1.0.21

package/README.md

@@ -94,8 +94,9 @@ Use skills in Claude Code with `/skill-name`:
 | `/update-slice-status` | Update slice status on the board |
 | `/load-slice` | Persist board slices to disk (backend stacks) |
 | `/build-state-change`, `/build-state-view`, `/build-automation`, `/build-webhook` | Implement a slice's command/view/automation/webhook (backend stacks) |
+| `/request-feedback` | Post a QUESTION comment and mark a slice `Blocked` when it's genuinely ambiguous (backend stacks) |
 
-Which skills install depends on the chosen stack — see `stacks/<name>/templates/.claude/skills/`. `/connect`, `/learn-eventmodelers-api`, and `/update-slice-status` have no stack-specific content and install into every stack from `shared/skills/` instead.
+Which skills install depends on the chosen stack — see `stacks/<name>/templates/.claude/skills/`. `/connect`, `/learn-eventmodelers-api`, `/update-slice-status`, and `/request-feedback` have no stack-specific content and install into every stack from `shared/skills/` instead.
 
 ## Everyday commands
 
@@ -346,7 +347,7 @@ npx @eventmodelers/cli uninstall --modeling-kit      # remove .agent-modeling-ki
 
 ### Adding a stack
 
-Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`) work the same way via `shared/skills/` — a new stack gets them for free without copying anything; add a skill there only once it needs a stack-specific fork.
+Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`, `request-feedback`) work the same way via `shared/skills/` — a new stack gets them for free without copying anything; add a skill there only once it needs a stack-specific fork.
 
 Once your `init --build-kit` scaffold (see above) works against a real backend, promote it to a first-class stack:
 

package/cli.js

@@ -1413,6 +1413,22 @@ async function runModeling(kitDir, projectDir, verbose = false) {
 
   const channelName = `org:${cfg.organizationId}`;
   const realtime = await createRealtimeAdapter(cfg, realtimeToken);
+
+  let lastTokenRefreshAt = 0;
+  async function refreshRealtimeToken(reason) {
+    // Guard against hammering the token endpoint: a rejected channel retries every
+    // ~14s on its own, so without this a bad token would trigger a refresh call per retry.
+    if (Date.now() - lastTokenRefreshAt < 5000) return;
+    lastTokenRefreshAt = Date.now();
+    try {
+      realtimeToken = await getRealtimeToken();
+      await realtime.setAuth(realtimeToken);
+      log(`token refreshed (${reason})`);
+    } catch (err) {
+      log(`token refresh failed (${reason}): ${err.message}`);
+    }
+  }
+
   realtime.subscribe(
     channelName,
     {
@@ -1429,19 +1445,19 @@ async function runModeling(kitDir, projectDir, verbose = false) {
     (status) => {
       log(`channel "${channelName}": ${status}`);
       if (status === 'SUBSCRIBED') drain().catch((err) => log(`initial drain error: ${err.message}`));
+      // A bad/stale token otherwise sits in realtime-js's own rejoin-retry loop until the
+      // next scheduled refresh below — up to 10 minutes of failed joins. Refresh immediately
+      // instead of waiting on the clock.
+      if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
+        refreshRealtimeToken(status).catch(() => {});
+      }
     },
   ).catch((err) => {
     log(`realtime subscribe failed, prompts won't be pushed live: ${err.message}`);
   });
 
-  setInterval(async () => {
-    try {
-      realtimeToken = await getRealtimeToken();
-      await realtime.setAuth(realtimeToken);
-      log('token refreshed');
-    } catch (err) {
-      log(`token refresh failed: ${err.message}`);
-    }
+  setInterval(() => {
+    refreshRealtimeToken('scheduled').catch(() => {});
   }, 10 * 60 * 1000);
 
   const ping = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/skills/request-feedback/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: request-feedback
+description: Post a QUESTION comment on a slice and mark it Blocked when the slice's requirements are genuinely ambiguous, contradictory, or missing something a decision depends on. This is an escalation path, not a routine step — reach for it only when you cannot proceed without guessing.
+---
+
+# Request Feedback
+
+> **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
+
+Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
+
+---
+
+## When to use this skill — the exception, not the rule
+
+Building a slice is normally unambiguous: `slice.json` names every command field, event field, and
+GWT scenario, and the matching build skill (`build-state-change`, `build-state-view`,
+`build-automation`, ...) tells you exactly how to turn that into code. **Read `slice.json` fully, and
+read the build skill's own instructions and reference docs, before ever concluding something is
+missing.** Most slices need none of this.
+
+Only invoke `request-feedback` when, after that reading, a decision the implementation depends on
+still cannot be made without guessing — for example:
+
+- A business rule mentioned in `description`/`comments`/`notes` isn't backed by any field, event, or
+  `specifications[]` scenario, so there's no way to encode it.
+- Two fields, or a field and an `idAttribute` flag, contradict each other about what the slice is
+  supposed to do.
+- A `specifications[]` scenario references a prior event or state that no command/event in this slice
+  (or its declared dependencies) actually produces.
+- The slice depends on another slice, screen, or read model that doesn't exist yet and it's unclear
+  whether one should be created, or the dependency was meant to point elsewhere.
+
+**Do not use this skill for:**
+- Implementation-detail choices the build skill's own instructions already answer (e.g. package
+  naming, file layout, which annotation to use) — those aren't ambiguity in the slice, they're just
+  reading the skill more carefully.
+- Style or naming preferences with no functional consequence — pick the reasonable option and move on.
+- "This would be nice to confirm" — if you *can* proceed correctly from what `slice.json` says, proceed.
+
+When in doubt, prefer finishing the slice over escalating. Escalating on every minor uncertainty
+defeats the purpose — it should be rare enough that a `Blocked` slice reliably means "a human needs to
+look at this," not "the agent didn't feel like deciding."
+
+**When this skill does apply: do not guess and build anyway.** Post the question and stop work on this
+slice for this run — do not implement your best interpretation first. A wrong guess encoded into
+working, tested, committed code is harder to catch and undo than an unbuilt slice waiting for an
+answer.
+
+---
+
+## Step 1 — Parse arguments
+
+From `$ARGUMENTS` or the calling skill's context, extract:
+
+| Field | How to find it | Default |
+|-------|---------------|---------|
+| `sliceName` or `sliceId` | the slice being worked on | **required** — one of the two |
+| `question` | the specific ambiguity or missing piece, phrased as a question | **required** |
+| `author` | author identifier string | `agent` |
+
+## Step 2 — Resolve the slice's node id
+
+Prefer MCP:
+
+```
+mcp__eventmodelers__list_slices { "boardId": "<BOARD_ID>" }
+```
+
+**Fallback (no MCP):**
+
+```bash
+curl -s \
+  -H "x-token: <TOKEN>" \
+  -H "x-board-id: <BOARD_ID>" \
+  -H "x-user-id: request-feedback-skill" \
+  "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/slicedata/slices"
+```
+
+Find the slice whose `title` matches `sliceName` (case-insensitive), or whose `id` matches `sliceId`.
+If no match is found, stop and list the available slice titles so the caller can pick one. Save the
+matched slice's `id` as `SLICE_NODE_ID` and its current `status` as `CURRENT_STATUS`.
+
+## Step 3 — Post the QUESTION comment
+
+Prefer MCP:
+
+```
+mcp__eventmodelers__add_comment { "boardId": "<BOARD_ID>", "nodeId": "<SLICE_NODE_ID>", "text": "<question>", "type": "QUESTION", "author": "<author>" }
+```
+
+**Fallback (no MCP):**
+
+```bash
+curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<SLICE_NODE_ID>/comments" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"<question>","type":"QUESTION","author":"<author>"}'
+```
+
+Response: `201 {"id":"<commentId>"}`. Save it as `COMMENT_ID` — the calling skill may want to reference
+it later once the question is answered.
+
+Write `<question>` so a human reading it cold understands the gap without re-reading the slice
+themselves: name the slice, name the specific field/rule/scenario in question, and say what's missing
+or contradictory — not just "please clarify this slice."
+
+## Step 4 — Mark the slice Blocked
+
+Prefer MCP:
+
+```
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "Blocked" }
+```
+
+Also mark the slice 'blocked' locally in the index.json if possible.
+
+**Fallback (no MCP)** — send a `node:changed` event to update the `sliceStatus` field in the
+SLICE_BORDER node's meta directly:
+
+```bash
+curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
+  -H "Content-Type: application/json" \
+  -H "x-token: <TOKEN>" \
+  -H "x-board-id: <BOARD_ID>" \
+  -H "x-user-id: request-feedback-skill" \
+  -d '[{
+    "id": "<new-random-uuid>",
+    "eventType": "node:changed",
+    "nodeId": "<SLICE_NODE_ID>",
+    "boardId": "<BOARD_ID>",
+    "timestamp": <Date.now()>,
+    "changedAttributes": ["sliceStatus"],
+    "meta": {
+      "sliceStatus": "Blocked"
+    }
+  }]'
+```
+
+If `CURRENT_STATUS` was already `Blocked`, this step is a no-op — don't treat that as an error, and
+don't retry. It just means someone (possibly this same agent, on an earlier prompt) already flagged it.
+
+## Step 5 — Stop and report
+
+Do not continue implementing the slice after this. Report back to whoever invoked this skill:
+
+```
+Requested feedback on slice "<sliceName>" (<SLICE_NODE_ID>)
+Question posted: "<question>"
+Status: <CURRENT_STATUS> → Blocked
+```
+
+Then stop work on this slice for this run. If the caller has other, unrelated slices queued, it may
+move on to those — but this specific slice stays untouched until the question is answered and the
+slice is moved out of `Blocked`.

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

@@ -415,8 +415,6 @@ than fabricating an assertion.
 
 ## References
 
-- [Stateless Automation Example](references/automation-test-example.md) — Complete Java test example
-- [Automation with Read Model Example](references/automation-with-read-model-test-example.md) — Multi-command test
 - [Feature Flag Patterns](references/feature-flag-patterns.md) — `@ConditionalOnProperty` and alternatives
 
 ---

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

@@ -7,8 +7,7 @@ description: >
   (long-running, durable, multi-step processes) instead of plain @EventHandler automations.
   Determines WHICH slices need a Workflow, then implements them using the AF5 Workflow engine.
   Use when: (1) given a set of automation slice.json definitions, decide which ones should be
-  Workflows; (2) user asks to "convert automation to workf
-  low", "implement as workflow",
+  Workflows; (2) user asks to "convert automation to workflow", "implement as workflow",
   or "use Axon Workflow for this slice"; (3) a slice has multi-step logic, needs to wait for
   external input/approval, requires compensation/rollback, or spans significant time.
   NOTE: AF5 Workflows are in Preview — APIs may change; not intended for production use yet.

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

@@ -121,8 +121,16 @@ public static final String {TAG_CONSTANT} = "idField";
 ## Step 3: Decision-model entity
 
 Package-private, mutable field(s) — **not** an immutable `State` record with free-standing
-`decide()`/`evolve()` static methods. One boolean/value field per fact the command handler's rule
-check needs, nothing else.
+`decide()`/`evolve()` static methods.
+
+**Derive the field(s) from this slice's `specifications[]` (Step 0), not from the event's shape.**
+Each GWT scenario's `given`/`then` pair states the one decision the command handler must make and the
+prior fact that decision depends on — that fact is the field. Re-read the scenarios before naming
+fields: a "given no prior activity" / "given already {X}" pair means one boolean flag for {X}; a
+scenario that discriminates on a value (not just presence/absence) means a value field holding that
+value, not a boolean. Add exactly one field per fact a scenario actually branches on — an event can
+carry several fields, but the entity only needs the ones a `specifications[]` scenario checks. Do not
+add a field just because the corresponding event happens to carry that data.
 
 ```java
 package {basePackage}.slices.{context}.{slicename};
@@ -312,6 +320,8 @@ in all three places:
 - `META-INF/additional-spring-configuration-metadata.json` — add a `{"name": "...", "type":
   "java.lang.Boolean", "description": "..."}` entry
 
+See [references/feature-flag-patterns.md](references/feature-flag-patterns.md) for the full pattern.
+
 This flag is irrelevant to the Step 7 test below — that test never boots Spring, so
 `@ConditionalOnProperty` never runs.
 

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

@@ -42,6 +42,13 @@ When starting to work on a slice, invoke the `update-slice-status` skill with `I
 **CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
 **ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
 
+**If, at any point below, the slice's requirements are genuinely ambiguous, contradictory, or missing
+a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke the
+`request-feedback` skill with the specific question; it posts the question as a comment on the slice
+and marks it `Blocked`, and you then stop work on this slice for this run. This is an escalation path,
+not a routine step — read `slice.json` and the matching build skill's own instructions fully first;
+most slices are fully specified and need none of this.
+
 When asked to build a slice, always follow this flow:
 
 1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.

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

@@ -48,6 +48,17 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 18. append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 19. Finish the iteration.
 
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set earlier), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
 ## Progress Report Format
 
 APPEND to progress.txt (never replace, always append):

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

@@ -48,6 +48,8 @@ Inspect the `sliceStatus` in the payload:
 
 This is the build trigger. Setting `InProgress` and building are one atomic step:
 
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked` (superseding the `InProgress` set in step 1), then drop this task without finishing the build. This is an escalation path, not a routine step — most slices are fully specified.
+
 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 `Planned`), another agent already claimed it first — this is expected, not an error. Log it in `progress.txt`, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.

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

@@ -32,6 +32,13 @@ When starting to work on a slice, invoke the `update-slice-status` skill with `I
 **CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
 **ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
 
+**If, at any point below, the slice's requirements are genuinely ambiguous, contradictory, or missing
+a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke the
+`request-feedback` skill with the specific question; it posts the question as a comment on the slice
+and marks it `Blocked`, and you then stop work on this slice for this run. This is an escalation path,
+not a routine step — read `slice.json` and the matching build skill's own instructions fully first;
+most slices are fully specified and need none of this.
+
 When asked to build a slice, always follow this flow:
 
 1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.

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

@@ -91,6 +91,17 @@ Use the skills available in `.claude/skills/` to interact with the board.
 
 After completing a task, remove it from the array and write the updated array back to `.build-kit/tasks.json`. If the array is now empty, write `[]`.
 
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set earlier), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
 ## Progress Report Format
 
 APPEND to `progress.txt` (never replace):

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

@@ -38,6 +38,17 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 17. Append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 18. Finish the iteration.
 
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set in step 5), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
 ## Progress Report Format
 
 APPEND to progress.txt (never replace, always append):

package/stacks/cratis-csharp/templates/build-kit/CLAUDE.md

@@ -9,6 +9,13 @@ and follow the conventions distilled in
 `.build-kit/.claude/skills/_shared/cratis-conventions.md`. **The shipped example slice
 under `SomeModule/SomeFeature/` is the concrete pattern to copy** — match its structure exactly.
 
+**If a slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need in
+order to proceed — do not guess, and do not build anyway.** Invoke the `request-feedback` skill with
+the specific question; it posts the question as a comment on the slice and marks it `Blocked`, and you
+then stop work on this slice for this run. This is an escalation path, not a routine step — read
+`slice.json` and the matching build skill's own instructions fully first; most slices are fully
+specified and need none of this.
+
 ## Structure (learn from `SomeModule/SomeFeature/`)
 
 ```

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

@@ -73,6 +73,17 @@ implementing.
 until the backend compiles**. Always: Backend → `dotnet build` → Specs → Frontend → Composition.
 Never implement a slice's frontend before its backend builds.
 
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set earlier), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
 ## Progress Report Format
 
 APPEND to `progress.txt` (never replace):

package/stacks/cratis-csharp/templates/build-kit/lib/prompt.md

@@ -48,6 +48,8 @@ Inspect the `sliceStatus` in the payload:
 
 This is the build trigger. Setting `InProgress` and building are one atomic step:
 
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked` (superseding the `InProgress` set in step 1), then drop this task without finishing the build. This is an escalation path, not a routine step — most slices are fully specified.
+
 1. Immediately call `/update-slice-status` to set the slice to `InProgress` on the board.
 
 2. Read the slice definition from `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json` (written by `/load-slice`).

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-identifying-outputs/SKILL.md

@@ -384,6 +384,16 @@ After the step is done, **every SCREEN and every AUTOMATION on the board must be
 
 > **Placement rule**: A read model must be placed in a column that already contains a SCREEN or AUTOMATION it serves. Do not place read models in columns with no screen or automation — doing so creates orphaned read models that will never have a consumer.
 
+### Pull field mappings from Step 3 — they are the spec, not a guess
+
+**Do not re-derive read model needs from a screen's title or description alone, and do not rely on the orchestrator's phase-summary handoff for this** — if you arrived here via `eventmodeling-orchestrating-event-modeling`, the handoff after Step 3 is a short hand-written prose summary (`.trogonai/interviews/.../EVENTMODELING.md`), not the actual field data. It will not reliably carry the per-field mappings forward. Go back to the board itself:
+
+For every SCREEN node, fetch it directly (`get_node`/`get_nodes`, never from memory) and read its `meta.fields`. Step 3 already required every field to carry a `mapping`, and for view fields that mapping is already in the exact form `"<ReadModelTitle>.<fieldName>"` — recorded specifically so this step doesn't have to re-guess it.
+
+- **Group the screen's fields by the `<ReadModelTitle>` already named in their `mapping`.** That grouping — not a fresh read of the screen's visuals — is the read model's title and field list. Build the READMODEL node from it directly.
+- If a field's `mapping` names a read model that isn't `"<CommandTitle>.<fieldName>"` or `"session:..."` or `"derived:..."`, it is a read-model reference — treat it as a requirement, not a suggestion.
+- A screen with no fields, or with fields that carry no read-model-shaped mapping, is **not** evidence that it needs no read model. Re-check it against the three rules above (view screen / automation / command screen showing prior state) before concluding it's the rare blank-form exception — and say explicitly why it qualifies.
+
 ### Field data lineage — the `mapping` attribute on READMODEL fields
 
 Every field on a READMODEL must carry a `mapping` that says exactly which event (or command) field it is projected from. Use one of these forms:
@@ -582,6 +592,16 @@ After `place-element` returns the READMODEL node ID, create the arrows that comp
 
 Skip a connection silently if the target cell is empty. Log each created arrow: `→ connected EVENT→READMODEL "OrderPlaced"→"OrderStatusView"`, `→ connected READMODEL→SCREEN "OrderStatusView"→"Order Status Screen"`, or `→ connected READMODEL→AUTOMATION "OrderStatusView"→"Fulfillment Processor"`.
 
+### Mandatory per-node verification (run before declaring this step done)
+
+Do not declare Step 5 complete on the strength of the read models you happened to design. Instead, **re-fetch every SCREEN and AUTOMATION node on the board** (`get_nodes` per type — don't rely on the list built earlier in this step, the board may have moved on) and check each one individually:
+
+1. Does it now have an incoming `READMODEL → SCREEN` or `READMODEL → AUTOMATION` connection?
+2. If not — is it a provably blank creation form with no prior state? State the reason in one line (e.g. `"Register Account" screen: blank form, no prior state — exempt`).
+3. If it's neither connected nor exempt, it is an **unresolved gap**. Fix it now: design the missing read model (pulling from its `meta.fields`/`mapping` as above) and wire the connection. Do not move to Step 6 with an unresolved gap silently carried forward — either fix it or explicitly flag it to the user as accepted debt.
+
+List the result of this pass (connected / exempt / fixed) for every screen and automation checked — this list is the evidence the orchestrator's Step 5 gate ("every screen data need is satisfied by a read model") actually holds, not just an assumption.
+
 After all read models, screens, automations, and connections are in place, present the Read Model Catalog summary as text to the user.
 
 ---
@@ -694,8 +714,8 @@ Identify UI needs without event sources:
 
 ### Read Model Design
 - [ ] **Typical pattern applied**: most screens follow `READ MODEL → SCREEN → COMMAND → EVENT`
-- [ ] **Every SCREEN from storyboarding is connected to at least one read model** (via `READMODEL → SCREEN`); only blank creation forms may be exempt
-- [ ] **Every AUTOMATION from storyboarding is connected to at least one read model** (via `READMODEL → AUTOMATION`)
+- [ ] **Every SCREEN from storyboarding is connected to at least one read model** (via `READMODEL → SCREEN`); only blank creation forms may be exempt — verified via the mandatory per-node pass above, not assumed
+- [ ] **Every AUTOMATION from storyboarding is connected to at least one read model** (via `READMODEL → AUTOMATION`) — same per-node verification
 - [ ] **No read model is placed without a connected SCREEN or AUTOMATION consumer**
 - [ ] Every read model has clear purpose
 - [ ] Every data field has event source

package/stacks/modeling-kit/templates/.claude/skills/html-screen/SKILL.md

@@ -79,6 +79,8 @@ This skill only has a `pages`/`backgroundColor` field to send (no separate marks
 
 Apply these only to the specific element(s) the request describes — don't guess at additional areas to call out.
 
+**Marked screens and field scoping**: when the same underlying screen is rendered multiple times as separate nodes — once per slice, each with a different mark/highlight calling out a different part of the UI — scope each node's `meta.fields` (Step 5 below) to only the data inside that node's highlighted area, not the full screen. Three slice-specific screen nodes sharing one visual base should end up with three different, narrower field lists, each matching what that node's mark calls out.
+
 ## Step 4 — Render the pages
 
 **Updating an existing node** (`nodeId` was given) — always sends the **complete** pages array, not just the changed/new entry:
@@ -133,7 +135,54 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/html-screen-nodes/$N
 
 Expect `204 No Content` on success from either curl call.
 
-## Step 5 — Report back
+## Step 5 — Define field data lineage (mandatory)
+
+Every screen — new or updated — needs `meta.fields`: one entry per piece of data the screen displays or captures, each with a `mapping` naming where that data comes from. A screen with only a title and no fields is an empty placeholder from a data-lineage standpoint, even if the mockup itself looks complete.
+
+| Field type | `mapping` | Example |
+|---|---|---|
+| User types a value, sent as a command | `"<CommandTitle>.<fieldName>"` | `"ReserveBike.bikeId"` |
+| Read from session | `"session:<fieldName>"` | `"session:customerId"` |
+| Displayed data, sourced from a read model | `"<ReadModelTitle>.<fieldName>"` | `"ActiveReservationView.status"` |
+| Calculated/formatted only for display | `"derived:<expression>"` | `"derived:formatDuration(durationMinutes)"` |
+
+Name the read model even if it doesn't exist as a board node yet — this skill only renders the screen, it does not create READMODEL nodes or connections (that's `eventmodeling-identifying-outputs` or `place-element`, if the model is taken that far). But naming the source is **not optional**: a screen displaying data should almost never have a field with no mapping. If you can't say which read model a displayed field comes from, that's a sign the model is missing something — not a reason to skip the field.
+
+If this node is one of several sharing the same visual base with different marks/highlights (see "Marked screens and field scoping" above), only list the fields that fall inside *this* node's highlighted area — not every field the shared screen shows.
+
+Set `cardinality` too (`"Single"` unless the field is a repeated/list value), then push the fields onto the node:
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]'
+```
+
+## Step 6 — Report back
 
 Tell the user:
 - The node ID that was created or updated

package/stacks/modeling-kit/templates/.claude/skills/storyboard/SKILL.md

@@ -35,6 +35,9 @@ Before making any API calls, plan all N screens. For each screen, decide:
 - `screenTitle` — human-readable name (e.g. "Enter Credentials")
 - `pages` (default) — one or more complete HTML/CSS fragments for this screen (see "HTML page design" below), or `elements` — a minimal list of grid elements (see "Sketch path" below, aim for 5–8 elements) **only** when the sketch path applies for this storyboard
 - `visualDescription` — a prose description of the screen's visual layout and content (2–4 sentences) that lets someone who cannot see the image understand what is shown: what UI sections appear, what text/labels are visible, where buttons and inputs are placed, and the overall purpose of the screen
+- `fields` — one entry per piece of data this screen displays or captures, each with a `mapping` naming its source (see "Field data lineage" in Step 5b below). Plan this alongside the visuals, not as an afterthought — every displayed value needs a named source.
+
+If several screens in this storyboard share the same visual base but each highlights a different part of it (e.g. one shared mockup, marked up differently per slice), scope each screen's `fields` to only the data inside *that* screen's highlighted area — not the full shared mockup. Different highlight, different (narrower) field list.
 
 Then **create one task per screen** using TaskCreate, naming each task after the screen title. This gives you a visible queue of work. Create the screens directly after each task has been planned.
 
@@ -257,6 +260,44 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/image-nodes/$SCREEN_
 
 Pass the already-computed `actorCellId` directly as `cellId` in either path. Expect success (MCP: `created: true`; curl: `204`). On failure, read the validation error, fix the payload, and retry once before reporting failure.
 
+### Step 5b(ii) — Set field data lineage (mandatory)
+
+Push the `fields` planned in Step 2 onto the node with a `node:changed` call. Every field needs a `mapping`:
+
+| Field type | `mapping` | Example |
+|---|---|---|
+| User types a value, sent as a command | `"<CommandTitle>.<fieldName>"` | `"ReserveBike.bikeId"` |
+| Displayed data, sourced from a read model | `"<ReadModelTitle>.<fieldName>"` | `"ActiveReservationView.status"` |
+| Calculated/formatted only for display | `"derived:<expression>"` | `"derived:formatDuration(durationMinutes)"` |
+
+Name the read model even if it doesn't exist as a board node yet — this skill only creates SCREEN/HTML_SCREEN nodes, never READMODEL nodes or connections. But naming the source is **not optional**: a screen displaying data should almost never have a field with no mapping. Set `cardinality` too (`"Single"` unless it's a repeated/list value).
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<SCREEN_NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [ /* planned fields */ ] }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<SCREEN_NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [ /* planned fields */ ] }
+  }]'
+```
+
 ### Step 5c — Mark the task complete
 
 After the node and sketch succeed, mark the task for this screen as completed using TaskUpdate.

package/stacks/modeling-kit/templates/.claude/skills/storyboard-screen/SKILL.md

@@ -129,7 +129,52 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$NODE_ID/sket
 
 Expect `204 No Content` on success.
 
-## Step 5 — Report back
+## Step 5 — Define field data lineage (mandatory)
+
+Every screen — new or updated — needs `meta.fields`: one entry per piece of data the screen displays or captures, each with a `mapping` naming where that data comes from. A screen with only a title and no fields is an empty placeholder from a data-lineage standpoint, even once the wireframe is rendered.
+
+| Field type | `mapping` | Example |
+|---|---|---|
+| User types a value, sent as a command | `"<CommandTitle>.<fieldName>"` | `"ReserveBike.bikeId"` |
+| Read from session | `"session:<fieldName>"` | `"session:customerId"` |
+| Displayed data, sourced from a read model | `"<ReadModelTitle>.<fieldName>"` | `"ActiveReservationView.status"` |
+| Calculated/formatted only for display | `"derived:<expression>"` | `"derived:formatDuration(durationMinutes)"` |
+
+Name the read model even if it doesn't exist as a board node yet — this skill only renders the screen, it does not create READMODEL nodes or connections. But naming the source is **not optional**: a screen displaying data should almost never have a field with no mapping. If you can't say which read model a displayed field comes from, that's a sign the model is missing something — not a reason to skip the field.
+
+Set `cardinality` too (`"Single"` unless the field is a repeated/list value), then push the fields onto the node:
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]'
+```
+
+## Step 6 — Report back
 
 Tell the user:
 - The node ID that was updated

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

@@ -35,6 +35,13 @@ When starting to work on a slice, invoke the `update-slice-status` skill with `I
 **CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
 **ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
 
+**If, at any point below, the slice's requirements are genuinely ambiguous, contradictory, or missing
+a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke the
+`request-feedback` skill with the specific question; it posts the question as a comment on the slice
+and marks it `Blocked`, and you then stop work on this slice for this run. This is an escalation path,
+not a routine step — read `slice.json` and the matching build skill's own instructions fully first;
+most slices are fully specified and need none of this.
+
 When asked to build a slice, always follow this flow:
 
 1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.

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

@@ -42,6 +42,17 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 18. append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 19. Finish the iteration.
 
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set earlier), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
 ## Progress Report Format
 
 APPEND to progress.txt (never replace, always append):

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

@@ -48,6 +48,8 @@ Inspect the `sliceStatus` in the payload:
 
 This is the build trigger. Setting `InProgress` and building are one atomic step:
 
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked` (superseding the `InProgress` set in step 1), then drop this task without finishing the build. This is an escalation path, not a routine step — most slices are fully specified.
+
 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 `Planned`), another agent already claimed it first — this is expected, not an error. Log it in `progress.txt`, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.

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

@@ -35,6 +35,13 @@ When starting to work on a slice, invoke the `update-slice-status` skill with `I
 **CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
 **ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
 
+**If, at any point below, the slice's requirements are genuinely ambiguous, contradictory, or missing
+a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke the
+`request-feedback` skill with the specific question; it posts the question as a comment on the slice
+and marks it `Blocked`, and you then stop work on this slice for this run. This is an escalation path,
+not a routine step — read `slice.json` and the matching build skill's own instructions fully first;
+most slices are fully specified and need none of this.
+
 When asked to build a slice, always follow this flow:
 
 1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.

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

@@ -42,6 +42,17 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
  18. append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 19. Finish the iteration.
 
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set earlier), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
 ## Progress Report Format
 
 APPEND to progress.txt (never replace, always append):

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

@@ -48,6 +48,8 @@ Inspect the `sliceStatus` in the payload:
 
 This is the build trigger. Setting `InProgress` and building are one atomic step:
 
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked` (superseding the `InProgress` set in step 1), then drop this task without finishing the build. This is an escalation path, not a routine step — most slices are fully specified.
+
 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 `Planned`), another agent already claimed it first — this is expected, not an error. Log it in `progress.txt`, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.