@eventmodelers/cli 1.0.32 → 1.0.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "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/eventmodeling-elaborating-scenarios/SKILL.md

@@ -13,31 +13,40 @@ allowed-tools:
 
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
-## Storylines — an On-Demand Alternative to GWT Scenarios (Experimental)
-
-**By default, this skill always produces GWT scenarios.** Storylines are a separate, experimental
-artifact — only build one when the user's request explicitly asks for a "storyline", "walkthrough",
-or "narrative". Never generate a storyline as a side effect of ordinary scenario elaboration.
-
-**Exception — the mandatory read-model scenario pass** (see the "Per read model" section of the Quality Checklist below): when the user's request already frames read-model coverage as open to either form — e.g. "add scenarios for the read models, GWT or storylines", or the orchestrating skill's Step 7 gate, which requires exactly that — the explicit-ask condition is satisfied at that request level, not per read model. Within that pass, decide GWT vs. storyline **per read model** based on domain fit (does this read model's row genuinely walk through multiple states worth narrating?), not by asking again for every individual read model and not by defaulting to GWT for all of them just because that's the baseline elsewhere in this skill. Outside that pass — an ad-hoc "write scenarios for X" with no mention of storylines — the strict on-demand rule above still applies unchanged.
-
-A GWT scenario asserts one isolated transition: a single precondition, a single action, a single
-resulting outcome. A storyline instead narrates one specific use case as an ordered sequence of
-**beats**, where the *same* element (usually a read model) is walked through multiple states across
-one flow — something no single GWT scenario can express, since GWT only ever asserts one
-before/after pair at a time.
+## GWT vs. Storyline — Decision Rule
+
+A GWT scenario asserts one isolated transition (one precondition → one action → one outcome). A
+storyline instead narrates one use case as an ordered sequence of **beats**, walking the *same*
+element (usually a read model) through multiple states in one flow — something no single GWT can
+express.
+
+**Commands: always GWT.** A command has no state progression to narrate — it validates one
+input against one state and either succeeds or is rejected. Never write a storyline for a command.
+
+**Read models: storyline when the read model goes through a series of clear state transitions
+driven by events; GWT otherwise.** Decide this **per read model**, not once for the whole pass:
+does replaying this read model's actually-connected event(s) more than once produce an interesting
+accumulated/changed state worth narrating? A single event type recurring with different data counts
+just as much as a multi-event lifecycle — e.g. `AccountFunded($40)` then `AccountFunded($70)`
+walking a balance from $40 to $110 is a genuine storyline driver. **Todo lists are a prime
+candidate**: an item appears when opened and disappears when completed, which is exactly the kind
+of state progression a storyline is for — as is any read model whose rows accumulate, update, or
+get removed across a sequence of events (balances, counters, statuses). Yes → storyline. No →
+GWT-only. Make this call before drafting any payload — a batch pass that reuses one schema for
+every command *and* every read model is a sign the per-read-model judgment got skipped.
+
+Even where a read model gets a storyline, still write GWTs for the specific scenarios the
+storyline doesn't cover — validation failures, cross-context sourcing, or any transition outside
+the narrated flow. Storyline and GWT are complementary, not exclusive: the storyline covers the
+narrated lifecycle, GWT covers everything else about that read model.
 
 **Example** — a customer-activation walkthrough of a Todos read model:
-1. **Beat 1** — the Todos read model, starting empty.
-2. **Beat 2** — after a `CustomerRegistered` event, the same Todos read model now shows one entry
-   (an "activate your account" todo).
-3. **Beat 3** — after a `CustomerActivated` event, the same Todos read model is empty again (the
-   todo was completed and removed).
+1. **Beat 1** — Todos read model, empty.
+2. **Beat 2** — after `CustomerRegistered`, Todos shows one entry ("activate your account").
+3. **Beat 3** — after `CustomerActivated`, Todos is empty again (todo completed and removed).
 
-Three separate GWT scenarios could each assert one of those transitions in isolation, but a
-storyline threads all three together as one narrated walkthrough of the read model's lifecycle —
-useful for a stakeholder-facing walkthrough of a use case, not for exhaustive GWT coverage. Keep
-producing ordinary Given/When/Then scenarios for everything else.
+A storyline threads all three beats into one walkthrough; three separate GWTs could each assert one
+transition but not the lifecycle.
 
 ### Storyline data shape
 
@@ -275,6 +284,14 @@ Work through each question with the domain in mind. If the answer is "that situa
 
 ## Workflow
 
+### 0. Decide GWT vs. storyline for every READMODEL — before drafting any scenario payload
+
+Apply the decision test from "GWT vs. Storyline — Decision Rule" above to every READMODEL on the
+board (or in scope). Produce a visible artifact — one line per READMODEL, "yes → storyline" or
+"no → GWT-only" with a one-clause reason — before writing the first scenario payload, not as a
+checklist review after. Deciding this list up front is what stops a batch pass from silently
+collapsing into one reused schema for every command and read model alike.
+
 For each command and view, write scenarios in Given-When-Then format:
 
 ### 1. Command Scenarios (Given-When-Then)
@@ -812,7 +829,7 @@ After posting, tell the user:
 - [ ] **Every READMODEL on the board has at least one view scenario** — GWT (`given`: source EVENTs, `when`: empty, `then`: the READMODEL) or a storyline. A model with dozens of command scenarios and 0 read-model scenarios is not a complete Step 7 — it's easy to walk away thinking coverage is thorough because the command side looks exhaustive, so check the read-model side explicitly before reporting this step done.
 - [ ] **Population scenario** — the view shows correct data after its source event(s)
 - [ ] **Removal/update scenario, where applicable** — a row disappears or changes (`expectEmptyList: true` for list-type views) after an event that supersedes it (expiry, return, archival, withdrawal, status change, etc.). `EVENT → READMODEL` is exempt from column ordering **only when the read model already feeds an AUTOMATION** (`READMODEL → AUTOMATION` edge; see `learn-eventmodelers-api` §3 and `eventmodeling-orchestrating-event-modeling`'s "No backward arrows") — a later event connecting back to an earlier-placed todo-list read model is normal for that accumulator shape, so add the connection if it's missing rather than assuming the scenario is impossible. If the read model has no automation to feed, the backward connection is rejected — by Step 5 this should already have been modeled the forward way (see `eventmodeling-identifying-outputs` Step 5g's copy pattern: a new read model + screen copy in the later event's column, never a link back). If it wasn't, write the scenario against that forward-placed copy rather than the original. Only skip this scenario, with a documented gap (TASK comment), when the superseding event genuinely lives in a different chapter.
-- [ ] **GWT vs. storyline decided per read model, not applied uniformly** — reach for a storyline wherever the *same* read model row genuinely walks through multiple states worth narrating; the rest of the read models in the same model may be correctly GWT-only. Don't default to one format for every read model just because it worked for the first one, and don't judge "multiple states" by counting *distinct connected event types* — that undercounts real candidates. **A single event type recurring with different data is just as valid a storyline driver as several different event types**: `AccountFunded($40)` then `AccountFunded($70)` walking a balance read model from $40 to $110 is exactly as strong a storyline as a multi-event lifecycle. In practice this means almost every list/aggregate read model qualifies — a titles list growing from one row to two as the same `TitleAdded`-shaped event recurs, a dashboard's counters incrementing as the same `CopyAdded` event recurs, are both genuine storylines, not "just" GWT territory. Ask "does replaying this read model's *actually connected* event(s) more than once produce an interesting accumulated/changed state?" — not "how many different event types feed this."
+- [ ] **GWT vs. storyline decided per read model, not applied uniformly** — apply the decision test from "GWT vs. Storyline — Decision Rule" above to each read model individually; some may qualify for a storyline while the rest of the same model are correctly GWT-only. Don't default to one format for every read model just because it worked for the first one.
 - [ ] **No redundancy or contradiction between a read model's GWT scenarios and its storyline** — if both exist for the same read model, read the storyline's beats before finalizing the GWTs. A GWT that asserts the same state a beat already shows is redundant (delete it); a GWT written without tracing the same causal sequence the storyline encodes can end up asserting something the storyline's beats actually contradict (e.g. claiming two entities coexist in a view when the storyline correctly shows one superseding the other) — delete or fix it, never leave a contradiction on the board.
 - [ ] **Cross-context read models handled honestly** — if a read model's true source events live in a different chapter, `given` can't reference them (same-timeline-only, like connections); write the scenario with an empty `given` and say so explicitly in the scenario title, rather than silently omitting the scenario or fabricating a same-timeline event that isn't the real source
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-orchestrating-event-modeling/SKILL.md

@@ -56,6 +56,16 @@ Two distinct checks, both required, and neither is satisfied by having done it o
 
 After both checks, a read model may still be wide because one or more of its fields have irreducible, genuinely-single-field fan-in — that is an outcome you document (per "Documenting decisions inline" above, naming the specific field and why), not a category ("roll-up component") you assign to the node up front and stop checking. Re-run this evaluation on every read model at every step that touches it, including ones a prior step already looked at — a field added or a screen re-scoped later can introduce exactly the bundling problem this heuristic exists to catch.
 
+### Recognizing a dedicated business event behind a derived condition
+
+This is a **business-modeling decision, not a technical one** — it is not triggered by a read model's fan-in count and is not a fix for anything the >3-events heuristic flags. A read model landing on wide fan-in is at most a symptom that might prompt you to ask the question below; it is never the reason to answer it one way or the other, and the question is worth asking regardless of how many events are involved.
+
+The question to ask is simply: **is this fact worth a new event?** A derived condition — "is this available right now," "has this moved to its next stage," etc. — is worth its own event when it's a fact a domain expert would recognize and name in its own right (not just "some field I compute"), and when that fact is valuable to a later step in the process — another automation would react to it, a different bounded context would want to subscribe to it, some downstream process needs to trigger off of it. If both hold, it deserves to exist as its own dedicated event — e.g. "the copy was marked available" — not just as derived read-model logic recomputed from several other events.
+
+When that's the case, model it as its own event, produced via the same todo-list + automation translation pattern Step 5b uses for external integrations, but triggered internally by whichever raw events can produce that outcome. If the condition is purely for display, with nothing downstream that would ever act on it, it stays a plain read-model projection — no new event needed, no matter how many raw events feed it or how wide the resulting fan-in looks.
+
+**Only fold together causes that are genuinely redundant for the same outcome — never causes that carry distinct business meaning.** A derived condition's causes typically split into two groups: several distinct events that all mean the *same* thing from the business's point of view (e.g. `CopyReservationReleased`, `CopyReturned`, and `CopyReturnedFromRepair` all mean "the copy is available again"), and several distinct events that each mean something the business still wants told apart (e.g. `CopyReserved` → Reserved, `CopyCheckedOut` → CheckedOut, `CopySentForRepair` → UnderRepair, `CopyReportedLost` → Lost, `CopyWithdrawn` → Withdrawn). Only the first group is safe to consolidate — a dedicated event like `CopyMarkedAvailable` collapses "N different reasons, same outcome" into one reusable signal without losing information. Collapsing the second group into something like a generic `CopyMarkedUnavailable` would erase the *why*, which some downstream consumer may actually need — leave those as separate events and direct connections, even though the read model's fan-in then stays wider than the fully-consolidated ideal. That remaining fan-in is not a failure of anything — it means those events are each individually meaningful, not synonymous with each other, and collapsing them would have been the actual modeling mistake.
+
 ### No unplaced elements (0,0 nodes)
 
 After each step that creates elements (Steps 1–5), scan for any nodes that have no cell reference and are stranded at the default canvas position (0,0). These arise when `node:created` is called without `cellId`.

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

@@ -239,6 +239,8 @@ Cell IDs are always `<rowId>-<columnId>` — no cell array search needed.
 
 **One EVENT per column (hard rule).** A column represents a single moment in the timeline. When `elementType` is `EVENT`, an occupied column means occupied *at all* — even if the existing EVENT sits in a different swimlane row (e.g. a different system under Conway's Law). Never place two EVENT nodes in the same column just because they're in different swimlanes. Before treating the column as available, check `cells` for **every** row whose `type === "swimlane"`, not only `targetRow` — if any of those cells already holds an EVENT node, treat the column as occupied and insert a new column immediately after (see the table below), not the target column itself.
 
+**Same swimlane for events emitted by the same command.** When one command emits more than one event, each event still gets its own column (per the hard rule above), but all of them belong in the *same* swimlane row, placed in adjacent columns immediately after the command. Do not scatter a command's sibling events across different swimlane rows — one command producing multiple events is one system doing multiple things in sequence, not several systems reacting independently.
+
 **Check if the cell is already occupied.**
 
 **No direct MCP equivalent**: `get_nodes` only filters by `type`, not `cellId` — there is no MCP tool that filters nodes by cell. Instead, use the `meta.timelineData.cells` you already fetched in Step 3 via `get_node` on the chapter/timeline node: `cells` is a sparse array, so a `nodeId` absent from the entry for `CELL_ID` means the cell is empty. Only fall back to the curl call below if you haven't already loaded `timelineData` (e.g. MCP wasn't used in Step 3 either):