@eventmodelers/cli 1.0.38 → 1.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "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/stacks/modeling-kit/templates/.claude/skills/analyze-existing-model/SKILL.md

@@ -119,6 +119,15 @@ Do not flag gaps that are clearly intentional (e.g. a slice named "Internal" wit
 
 Check whether any EVENT, COMMAND, or READMODEL appears in zero slices (present on the board but not wired into any slice boundary). If the slicedata API does not expose this directly, skip this check and note it.
 
+### 5f — Structural shapes
+
+Check the element graph gathered in Step 4 against the four shapes defined in `eventmodeling-core-rules`'s **Structural Shapes** section (the bed, left chair, right chair, shelf) — read that section for the full definitions and thresholds; this step only covers how to report them here.
+
+- **The bed** is a real anti-pattern — always report every instance found (a SCREEN wired to more than one COMMAND), by slice/screen name.
+- **The left chair, right chair, and shelf** are candidates — only report an instance if, after reasoning about the actual events/fields/scenarios involved, the count still looks like it's doing more than one job in this domain. Don't report a raw count crossing the threshold on its own.
+
+This is a read-only structural read like the rest of Step 5 — report findings, never fix them here.
+
 ---
 
 ## Step 6 — Report to the user
@@ -172,6 +181,13 @@ Total: <n> slices
 
 ---
 
+### Structural Shapes
+<always list every "the bed" instance found — screen name + the commands it fans into>
+<list a left chair/right chair/shelf instance only if it held up after reasoning about the domain>
+(none) if nothing found
+
+---
+
 ### Summary
 <2–4 sentences: overall model maturity, the most important gap or risk, one concrete suggestion>
 ```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-core-rules/SKILL.md

@@ -69,6 +69,7 @@ Slices are not placed directly — they're **derived** from a completed model. E
   - Invalid: `OrderSummaryProjector`, `InvoiceListRepository` — implementation detail leaking into the model
 - Optional — nothing requires a READMODEL to exist for a COMMAND or a downstream consumer.
 - Never drives COMMAND validation directly — a COMMAND is checked against its own documented preconditions, not a read model.
+- **List-shaped read models**: when the whole READMODEL represents multiple rows (each row shaped by its defined fields), not a single projected record, set `meta.listElement: true` on the node itself — this is a node-level flag, distinct from a field's own `cardinality: "List"` (a single field holding multiple values). Every todo-list read model (see `eventmodeling-designing-automation-chains`) is list-shaped and always gets `listElement: true`; the same applies to any other READMODEL whose query naturally returns a set of rows (e.g. `ProductList`, `InvoiceList`). `eventmodeling-elaborating-scenarios` reads this flag to decide whether a scenario needs row-level `examples`/`expectEmptyList` instead of a single accumulated result.
 
 ### SCREEN
 - Represents what a user sees and can act on.
@@ -151,6 +152,15 @@ Question any step that exists only because of the system — a loading spinner,
 - **Technical events**: `ApiCalled`/`ResponseReceived` describe machinery, not an outcome — find the business fact underneath.
 - **Calculated events**: an event whose value is recomputed as source data changes (a running total, an average) is a READMODEL, not an EVENT.
 
+## Structural Shapes
+
+Beyond the local anti-patterns above, four recurring **connection shapes** are worth checking whenever the model's wiring is visible — a fan-out or fan-in count crossing a rough threshold. Only one is a real anti-pattern regardless of context; the other three are **candidates** — worth checking against the business context, not automatically wrong. Reason about the actual events/fields/scenarios involved before flagging a candidate; if the domain justifies the count, it's not a violation. These are internal shorthand names for spotting the shape — never surface "bed", "left chair", "right chair", or "shelf" in anything shown to a business stakeholder (a board comment, a report); describe the concern in plain terms instead.
+
+- **The bed (real anti-pattern — always flag)** — one SCREEN wired to more than one COMMAND. A screen is where the user has already committed to one decision, so it should trigger exactly one command; wiring several to it means the choice is being made somewhere invisible to the model.
+- **The left chair (candidate)** — one COMMAND resulting in more than two EVENTs. May mean the command is doing more than one job, or it may be a single business outcome that legitimately fans out. Check whether the outcomes always happen together or could happen independently before treating it as a concern.
+- **The right chair (candidate)** — one READMODEL built from more than three EVENTs. May mean the view is answering more than one question at once, or it may be one coherent picture that genuinely needs that many sources. Check whether the fields shown belong to a single thing the user is checking before treating it as a concern.
+- **The shelf (candidate)** — one slice with noticeably more SCENARIOs than the others on the same timeline (a rough outlier, not a fixed threshold — compare against the typical count for that timeline). May mean the step is quietly covering ground that belongs to a separate step, or it may just be genuinely more complex. Check what the extra scenarios actually cover before treating it as a concern.
+
 ## Flow & Causality
 
 Model causality, not strict sequence:
@@ -178,5 +188,6 @@ Before treating a model as done, verify:
 - [ ] Every COMMAND traces back to a SCREEN (user decision) or AUTOMATION (system reaction)
 - [ ] The timeline starts with a state-view or an automation reacting to an event — not a bare COMMAND
 - [ ] No two `state-change`/`state-change` slices are chained without a new trigger between them
+- [ ] No SCREEN is wired to more than one COMMAND (the bed — see Structural Shapes)
 
 This is the fast pass — the full, deeper check is `eventmodeling-validating-event-models-checklist`.

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-designing-automation-chains/SKILL.md

@@ -69,6 +69,8 @@ A todo-list read model's fields describe the pending item — the identity it's
 
 Every field must set a `mapping` per `eventmodeling-identifying-outputs`'s field data lineage rules (`"<EventTitle>.<fieldName>"`, `"latest:..."`, `"aggregate:..."`, `"derived:..."`), and `"cardinality"` (`"Single"` unless the field genuinely holds a list).
 
+A todo-list read model is always list-shaped — it's a queue of pending items, never a single record — so it always gets **`meta.listElement: true`** on the node itself (see `eventmodeling-core-rules`'s READMODEL section). This is a node-level flag separate from any field's own `cardinality`.
+
 ## Placement — todo-list READMODEL, one column before its automation
 
 The todo-list read model goes in the interaction lane, **one column before** its automation (actor lane) — the automation's own column already holds the COMMAND it issues, so the read model can never share that column.
@@ -85,14 +87,14 @@ mcp__eventmodelers__place_element {
   "columnIndex": <automationColumnIndex - 1>
 }
 ```
-Then set `meta.fields` on the returned node id:
+Then set `meta.fields` and `meta.listElement: true` on the returned node id:
 ```
 mcp__eventmodelers__submit_node_events {
   "boardId": "<BOARD_ID>",
   "events": [{
     "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<returned-node-id>",
     "boardId": "<BOARD_ID>", "timestamp": 1234567890,
-    "meta": {"type": "READMODEL", "title": "NotificationsToSend", "fields": [...]}
+    "meta": {"type": "READMODEL", "title": "NotificationsToSend", "fields": [...], "listElement": true}
   }]
 }
 ```
@@ -145,4 +147,5 @@ List the result (connected / chain-resolved) for every automation checked — th
 - [ ] Every **worker**-stage todo-list read model's opening and closing events are identified, including the automation's own resulting event as a closing event
 - [ ] Every **translation**-stage todo-list read model has an opening event (the external EVENT) and **no closing event at all** — no backward arrow from its own internal EVENT back to its own todo list
 - [ ] No todo-list read model uses a `status` field instead of list membership
+- [ ] Every todo-list read model has `meta.listElement: true` set on the node
 - [ ] Every todo-list read model sits one column before its automation, never sharing its column

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-elaborating-scenarios/SKILL.md

@@ -386,7 +386,7 @@ Pass `compact: true` — you already hold every scenario object you sent, so the
 
 ### Step 4b — List-type readmodel scenario fields
 
-When `then` contains a READMODEL whose `listElement` property is `true`, add two fields **at the scenario level** (not inside `then`):
+When `then` contains a READMODEL whose `listElement` property is `true` — set on the node when it was created, per `eventmodeling-core-rules`'s READMODEL section and `eventmodeling-identifying-outputs`/`eventmodeling-designing-automation-chains` — add two fields **at the scenario level** (not inside `then`):
 
 **`examples`** — one object per expected row, keyed by the readmodel's snake_case field names. Without this the spec node renders with no expected output and the scenario is unverifiable.
 

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

@@ -222,6 +222,8 @@ Set the field's `generated` property according to this table. Fields projected d
 
 Every field must also set `"cardinality"` — use `"Single"` unless the field genuinely holds a list of values (e.g. line items, a collection projected from multiple events), in which case use `"List"`. Default to `"Single"` when unsure. Include only the fields the consuming SCREEN or AUTOMATION actually displays or needs — do not add speculative fields; enrich later via `/attributes`.
 
+If the READMODEL itself represents a set of rows rather than a single record — e.g. `InvoiceList`, `ProductList` — also set `meta.listElement: true` on the node (see `eventmodeling-core-rules`'s READMODEL section). This is separate from a field's `cardinality`: `listElement` says the whole read model is a list of elements shaped by its defined fields, `cardinality: "List"` says one field on an otherwise-single-record read model holds multiple values.
+
 ```json
 {
   "type": "READMODEL",
@@ -259,7 +261,7 @@ mcp__eventmodelers__place_element {
   "columnIndex": <consumerScreenColumnIndex>  // or <automationColumnIndex - 1> for an AUTOMATION consumer
 }
 ```
-Then set `meta.fields` (with `mapping`/`generated`/`cardinality`) on the returned node id:
+Then set `meta.fields` (with `mapping`/`generated`/`cardinality`) — and `meta.listElement: true` if this read model is list-shaped — on the returned node id:
 ```
 mcp__eventmodelers__submit_node_events {
   "boardId": "<BOARD_ID>",

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models-checklist/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eventmodeling-validating-event-models-checklist
-description: "Validate an event model against 12 structural checks across 6 phases. Identifies notation anti-patterns and confirms the model is internally consistent. Use when reviewing an event model for readiness or after completing event modeling steps. Do not use for: reviewing incomplete or in-progress models (use eventmodeling-validating-event-models), or for elaborating new scenarios (use eventmodeling-elaborating-scenarios)."
+description: "Validate an event model against 13 structural checks across 7 phases. Identifies notation anti-patterns and confirms the model is internally consistent. Use when reviewing an event model for readiness or after completing event modeling steps. Do not use for: reviewing incomplete or in-progress models (use eventmodeling-validating-event-models), or for elaborating new scenarios (use eventmodeling-elaborating-scenarios)."
 allowed-tools:
   - Write
   - Bash
@@ -14,7 +14,7 @@ This step applies the shared element rules in **`eventmodeling-core-rules`** —
 
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
-**Purpose**: Validate any event model against 12 structural checks across 6 phases. Identifies notation anti-patterns and confirms the model is internally consistent.
+**Purpose**: Validate any event model against 13 structural checks across 7 phases. Identifies notation anti-patterns and confirms the model is internally consistent.
 
 **Applies To**: Any domain - e-commerce, banking, SaaS, marketplace, healthcare, etc.
 
@@ -26,7 +26,7 @@ Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect`
 
 **What It Does**:
 1. Reads current board state (EVENT, COMMAND, READMODEL nodes) as input
-2. Systematically applies 12 validation checks across 6 phases
+2. Systematically applies 13 validation checks across 7 phases
 3. Identifies notation anti-patterns (calculations modeled as events, events mixed into the wrong entity's timeline, etc.)
 4. Verifies read model/event distinction
 5. Confirms every event and command traces cleanly
@@ -90,6 +90,14 @@ Use the board nodes as the model input. After the checklist, use `handle-comment
 
 **Anti-pattern to catch**: events that can occur in invalid combinations; a "shared" event quietly coupling two entities together
 
+### Phase 7: Structural Shape Validation (2 checks)
+- Check 7.1: No SCREEN is wired to more than one COMMAND
+- Check 7.2: Fan-out/fan-in outliers (a command with 2+ resulting events, a read model built from 3+ events, a slice with markedly more scenarios than its neighbors) have been reasoned about against the business context, not flagged on count alone
+
+See `eventmodeling-core-rules`'s **Structural Shapes** section for the full definitions ("the bed", "left chair", "right chair", "shelf") and their thresholds — this phase doesn't restate them.
+
+**Anti-pattern to catch**: Check 7.1 catches "the bed" — a screen fanning into multiple commands hides where the user's actual decision is made; this is a real anti-pattern, always fail it. Check 7.2 catches "the left chair" / "the right chair" / "the shelf" — these are candidates, not automatic fails: only report an outlier if the specific events/fields/scenarios involved still look like they're doing more than one job once you've checked them against the domain.
+
 ### Final Questions (2 checks)
 - Question 1: Could a modeler unfamiliar with this domain understand the model in 15 minutes?
 - Question 2: Could the business rule/calculation behind a read model change without rewriting event history?
@@ -158,6 +166,19 @@ EntityB reacts to EventA via a read model/automation, it doesn't own it
 
 **Why**: An event belongs to the story of exactly one entity. If a second entity needs to react to it, that's a read model or automation reading it — not the same event living on two timelines.
 
+### 4. A Screen Fanning Into Multiple Commands ("the bed")
+```
+ ANTI-PATTERN:
+Screen → Command A
+       → Command B
+       → Command C
+
+ CORRECT:
+Screen → Command A only (one screen, one decision)
+```
+
+**Why**: A screen represents the moment a user has already committed to one decision. Wiring it to several commands hides where that choice actually gets made — see `eventmodeling-core-rules`'s **Structural Shapes** section for this and the three related fan-out/fan-in candidates ("left chair", "right chair", "shelf").
+
 ---
 
 ## Questions to Ask During Validation
@@ -181,7 +202,7 @@ EntityB reacts to EventA via a read model/automation, it doesn't own it
 ## Success Criteria
 
  **Model is validated when**:
-- All 12 checks pass (or have documented workarounds)
+- All 13 checks pass (or have documented workarounds)
 - No critical anti-patterns identified
 - Both final questions answer YES
 - Event modeling principles are clearly upheld
@@ -243,7 +264,7 @@ Running the checklist after Step 2 prevents wasting time on later steps if the c
 
 ## Checklist Questions by Domain
 
-The skill applies the same 12 checks regardless of domain. Here's how to think about it in different contexts:
+The skill applies the same 13 checks regardless of domain. Here's how to think about it in different contexts:
 
 **E-commerce domain**:
 - Events: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped
@@ -275,7 +296,7 @@ The principle is the same across all domains: **immutable facts as events, calcu
 
 ## Quality Checklist
 
-- [ ] All 12 checks evaluated — no check skipped without documented justification
+- [ ] All 13 checks evaluated — no check skipped without documented justification
 - [ ] Every FAIL result includes the specific event, command, or entity that violated the check
 - [ ] Anti-patterns identified by name with the exact model element that triggered the flag
 - [ ] Final verdict is one of: PASS / PASS WITH WARNINGS / FAIL — no ambiguous outcomes
@@ -296,5 +317,5 @@ The principle is the same across all domains: **immutable facts as events, calcu
 
 ## Validation Checklist Reference
 
-The 12-point checklist is defined in the **Validation Phases** section above.
+The 13-point checklist is defined in the **Validation Phases** section above.
 Each check includes the anti-pattern to catch and questions to ask when evaluating your model.

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

@@ -7,6 +7,8 @@ description: Business analyst exploration of an event model board. Reads all sli
 
 > **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
 
+This step applies the shared element rules in **`eventmodeling-core-rules`** — read it once per session if you haven't already; it defines what a COMMAND/EVENT/READMODEL/SCREEN/AUTOMATION is, the anti-patterns to reject, and the four Structural Shapes (Category I below), so this step doesn't restate them.
+
 You are a **sharp business analyst** reviewing an event model. You don't know the domain yet — you're seeing it fresh. Your job is to read the model, understand the intended flows, and ask the hard questions that developers and domain experts tend to overlook because they're too close to the problem.
 
 You're not reviewing code. You're reviewing **business logic**: flows, edge cases, error paths, missing constraints, and real-world messiness that the happy path ignores.
@@ -94,14 +96,14 @@ Every question and every summary theme must be written in plain business languag
 - **Do not assume** notifications (welcome email, verification, webhook) are missing just because they aren't modelled. They may belong to a different slice or context not yet built. Only ask if the model explicitly implies a notification is needed but nothing wires to it.
 
 ### Category I: Structural shapes
-This category is about the **shape of the model**, not any one flow's business logic — it needs the edge/relationship data and per-slice scenario counts gathered across *all* slices in Step 2, so run it once after all slices are loaded, not per-slice. Check the full element graph for these four known shapes. Each still gets a business-worded question, per the language rule — never say "bed", "left-chair", "right-chair", or "shelf" in a comment; those are your internal names for spotting the shape, not vocabulary for the board.
+This category is about the **shape of the model**, not any one flow's business logic — it needs the edge/relationship data and per-slice scenario counts gathered across *all* slices in Step 2, so run it once after all slices are loaded, not per-slice. Check the full element graph against the four shapes defined in `eventmodeling-core-rules`'s **Structural Shapes** section (the bed, left chair, right chair, shelf) — read that section for what each shape is, its threshold, and which one is an always-flag anti-pattern vs. a context-dependent candidate; this section only covers how to word and post the finding once you've decided it holds up.
 
-Only one of these four is an actual anti-pattern — invalid regardless of context. The other three are **candidates**: a count crossing the rough threshold means "worth checking against the business context," not "wrong." Never raise a candidate off the count alone — reason about the specific events/fields/scenarios involved first, and only post if, in this domain, the count still looks like it's doing more than one job. If the context justifies it, drop it silently.
+Never raise a candidate off the count alone — reason about the specific events/fields/scenarios involved first, and only post if, in this domain, the count still looks like it's doing more than one job. If the context justifies it, drop it silently. Each still gets a business-worded question, per the language rule — never say "bed", "left chair", "right chair", or "shelf" in a comment; those are internal names for spotting the shape, not vocabulary for the board.
 
-- **The bed (real anti-pattern — always flag)** — one screen wired to more than one command. A screen is where the user has already committed to one decision, so it should trigger exactly one command; wiring several to it means the choice is being made somewhere invisible to the model. Flag this directly and confidently, not as a soft maybe — still in plain business language, but assertive: "This screen lets someone trigger more than one action from the same place — should this be split into separate steps or buttons so it's clear which one they're choosing?"
-- **The left chair (candidate)** — one command resulting in more than two events. May mean the command is doing more than one job, or it may be a single business outcome that legitimately fans out. Check whether the outcomes always happen together or could happen independently before asking. Example, only if it holds up: "When this action succeeds, do all of these things always happen together, or could some happen without the others?"
-- **The right chair (candidate)** — one read model built from more than three events. May mean the view is answering more than one question at once, or it may be one coherent picture that genuinely needs that many sources. Check whether the fields shown belong to a single thing the user is checking before asking. Example, only if it holds up: "Is this screen answering one question for the user, or several different ones bundled together?"
-- **The shelf (candidate)** — one slice with noticeably more scenarios than the others on the same timeline (a rough outlier, not a fixed threshold — compare against the typical count for that timeline). May mean the step is quietly covering ground that belongs to a separate step, or it may just be genuinely more complex. Check what the extra scenarios actually cover before asking. Example, only if it holds up: "This step has a lot more cases than the ones around it — is that because it's really doing more, or because it's covering something that should be its own step?"
+- **The bed** — flag directly and confidently, not as a soft maybe — still in plain business language, but assertive: "This screen lets someone trigger more than one action from the same place — should this be split into separate steps or buttons so it's clear which one they're choosing?"
+- **The left chair** — only if it holds up: "When this action succeeds, do all of these things always happen together, or could some happen without the others?"
+- **The right chair** — only if it holds up: "Is this screen answering one question for the user, or several different ones bundled together?"
+- **The shelf** — only if it holds up: "This step has a lot more cases than the ones around it — is that because it's really doing more, or because it's covering something that should be its own step?"
 
 Each of these four is inherently about a relationship or cluster of elements, so whichever you do raise always gets a drawing per Step 4.2 in addition to its comment — a group loop around the elements involved, or an arrow if the concern is specifically about one edge among several.