@eventmodelers/cli 1.0.37 → 1.0.38

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 event-sourced CQRS models against 17 architectural checks across 7 phases. Identifies anti-patterns and confirms compliance with event sourcing principles. Use when reviewing event models for production 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 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)."
 allowed-tools:
   - Write
   - Bash
@@ -10,25 +10,26 @@ allowed-tools:
 
 > **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 it has completed. Consult `learn-eventmodelers-api` only if you need to look up a specific endpoint or field this file doesn't cover — don't load it eagerly.
 
+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, how each is named, and the anti-patterns to reject, so this step doesn't restate them.
+
 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-sourced CQRS event model against 17 architectural checks across 7 phases. Identifies anti-patterns and confirms compliance with event sourcing principles.
+**Purpose**: Validate any event model against 12 structural checks across 6 phases. Identifies notation anti-patterns and confirms the model is internally consistent.
 
 **Applies To**: Any domain - e-commerce, banking, SaaS, marketplace, healthcare, etc.
 
 **When to Use**:
-- After completing Step 2 (Event Plot) of the 11-step event modeling workflow, as an early structural check
-- Alongside Step 9 (Validate), as the optional production-readiness pass before declaring model complete
-- When reviewing an existing event model for production readiness
-- When suspicious of architectural issues in event design
+- After completing Step 2 (Event Plot) of the event modeling workflow, as an early structural check
+- Alongside Step 9 (Validate), as an optional second pass before declaring the model complete
+- When reviewing an existing event model
+- When suspicious of structural issues in the model
 
 **What It Does**:
 1. Reads current board state (EVENT, COMMAND, READMODEL nodes) as input
-2. Systematically applies 17 validation checks across 7 phases
-2. Identifies violations of event sourcing principles (domain-agnostic)
-3. Flags anti-patterns (calculations as events, non-entity streams, etc.)
+2. Systematically applies 12 validation checks across 6 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 stream independence and business rule enforcement
+5. Confirms every event and command traces cleanly
 6. Returns pass/fail verdict with evidence
 
 ---
@@ -53,52 +54,45 @@ Use the board nodes as the model input. After the checklist, use `handle-comment
 
 ## Validation Phases (Domain-Agnostic)
 
-### Phase 1: Event Stream & Command Handler State Validation (4 checks)
-- Check 1.1: Each event belongs to exactly one stream
-- Check 1.2: Each command handler owns its own [CommandHandler]State class
-- Check 1.3: No hard dependencies between command handlers (orchestrated via events only)
-- Check 1.4: Each command is issued by exactly one thing — no COMMAND node has more than one inbound SCREEN/AUTOMATION edge
+### Phase 1: Event & Command Ownership Validation (2 checks)
+- Check 1.1: Each event belongs to exactly one entity/timeline
+- Check 1.2: Each command is issued by exactly one thing — no COMMAND node has more than one inbound SCREEN/AUTOMATION edge
 
-**Anti-pattern to catch**: Sharing state across handlers or treating state as persistent aggregate; a command wired from two issuers — auto-connect itself now guards against this (see `learn-eventmodelers-api` §3), so a double-issuer command found on the board is most likely a manual `set_connection` call or an edge left over from before that guard existed, not a fresh auto-connect artifact
+**Anti-pattern to catch**: a command wired from two issuers — auto-connect itself now guards against this (see `learn-eventmodelers-api` §3), so a double-issuer command found on the board is most likely a manual `set_connection` call or an edge left over from before that guard existed, not a fresh auto-connect artifact
 
 ### Phase 2: Event Quality Validation (3 checks)
 - Check 2.1: Events represent domain facts, not calculations
 - Check 2.2: Event data is immutable after creation
 - Check 2.3: Event names use past tense (what actually happened)
 
-**Anti-pattern to catch**: Storing computed/aggregated data as events
+**Anti-pattern to catch**: storing computed/aggregated data as an event
 
 ### Phase 3: Read Model vs Event Distinction (2 checks)
-- Check 3.1: Each read model is NOT an event stream
-- Check 3.2: Read model has natural query pattern
+- Check 3.1: Each read model is NOT an event timeline
+- Check 3.2: Read model has a natural query pattern
 
-**Anti-pattern to catch**: Confusing projections/calculations with domain facts
+**Anti-pattern to catch**: confusing projections/calculations with domain facts
 
 ### Phase 4: Business Rules Validation (2 checks)
-- Check 4.1: Constraints enforced in command handler decision logic (encapsulated in [CommandHandler]State)
-- Check 4.2: Event preconditions are explicit (what state must exist before command is valid)
+- Check 4.1: Every command's preconditions are documented explicitly
+- Check 4.2: Event preconditions are explicit (what must already be true before a command is valid)
 
-**Anti-pattern to catch**: Business rules scattered across handlers or encoded in event stream structure
+**Anti-pattern to catch**: business rules scattered across the model or left implicit ("obviously can't ship an unconfirmed order")
 
 ### Phase 5: Data Traceability (1 check)
 - Check 5.1: Input → Event → Read Model traceability is complete
 
-**Anti-pattern to catch**: Command inputs that disappear or read model fields without source
-
-### Phase 6: Event Flow Validation (1 check)
-- Check 6.1: No impossible event sequences (state machine is sound)
-
-**Anti-pattern to catch**: Events that can occur in invalid state combinations
+**Anti-pattern to catch**: command inputs that disappear, or read model fields without a source
 
-### Phase 7: Stream Independence (1 check)
-- Check 7.1: Each stream can be versioned/restored independently
+### Phase 6: Event Flow Validation (2 checks)
+- Check 6.1: No impossible event sequences (the slice-transition flow is sound)
+- Check 6.2: No event belongs to more than one entity's timeline — an event that seems to span two entities usually means a naming or boundary mistake, not a shared fact
 
-**Anti-pattern to catch**: Hard dependencies between streams
+**Anti-pattern to catch**: events that can occur in invalid combinations; a "shared" event quietly coupling two entities together
 
-### Final Questions (3 checks)
-- Question 1: Could an architect unfamiliar with this domain understand the model in 15 minutes?
-- Question 2: Could you change your core algorithm/calculation without changing event history?
-- Question 3: Could this be implemented in your target technology stack (e.g., TypeScript + PostgreSQL)?
+### 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?
 
 ---
 
@@ -108,7 +102,7 @@ The skill returns a validation report with:
 
 ### For Each Check
 ```
- Check 1.2: Stream Root is Business Entity, Not Calculation
+ Check 1.2: Command Issued by Exactly One Thing
 Status: PASS
 Evidence: [Specific examples from your model]
 ```
@@ -116,7 +110,7 @@ Evidence: [Specific examples from your model]
 ### Anti-Patterns Identified (if any)
 ```
 CRITICAL: [Anti-pattern description]
-Problem: [Why it violates event sourcing]
+Problem: [Why it violates event modeling principles]
 Violates: [Which checks fail]
 Fix: [Recommended action]
 ```
@@ -124,7 +118,6 @@ Fix: [Recommended action]
 ### Final Verdict
 ```
 Status:  PASS (or  PASS WITH WARNINGS or  FAIL)
-Implementation Ready: YES (or NO - fix issues first)
 Confidence: [percentage]
 ```
 
@@ -145,100 +138,65 @@ CalculationPerformed {
 - ReadModel: MetricView (recalculated from events)
 ```
 
-**Why**: Calculations change multiple times as source data changes. Events are immutable.
+**Why**: Calculations change as source data changes. Events are immutable.
 
-### 2. Shared vs Handler-Owned State
+### 2. Command With Multiple Issuers
 
-The DDD-aggregate anti-pattern — one shared state class used by every handler — versus the correct pattern of one minimal, handler-owned state class per command. See `eventmodeling-designing-event-models`'s "Core Architectural Rule" for the full worked example (`OrderAggregate` vs. per-command state).
-
-**Why**: Each handler is a micro-slice. Separate state classes maintain isolation, enable parallel teams, prevent merge conflicts.
-
-### 3. Circular Dependencies
-```
- ANTI-PATTERN:
-StreamA → EventA → affects
-StreamB → EventB → affects
-StreamA (circular!)
-
- CORRECT:
-StreamA → EventA → Event Bus
-StreamB → EventB → Event Bus
-ReadModels ← consume (one-way only)
-No feedback loops
-```
+A command is never issued by more than one thing — a COMMAND with 2+ inbound SCREEN/AUTOMATION edges hides which actor is actually responsible. See `place-element`'s Step 7c for the full check-and-fix mechanics (which edge to keep, how to remove the rest).
 
-**Why**: Circular dependencies make the system hard to reason about and test.
+**Why**: Each command represents one specific trigger's decision to act — collapsing two triggers onto one command node usually means either a naming/slice-boundary mistake or a stray manual/pre-existing edge (auto-connect itself now guards against fresh occurrences — see `learn-eventmodelers-api` §3).
 
-### 4. Persistent State vs Ephemeral State
+### 3. An Event Shared Across Entities
 ```
  ANTI-PATTERN:
-Treat [CommandHandler]State as persistent entity
-- Save SubmitReviewState to database after command
-- Load it again next time
-- Result: Duplicates event sourcing, loses audit trail
+EntityA → EventA → also placed on EntityB's timeline
 
  CORRECT:
-Reconstruct [CommandHandler]State on-demand
-- Load events from stream
-- Replay via evolve() to rebuild state
-- Process command, emit outcome events
-- Discard state (it's ephemeral, not persisted)
+EntityA → EventA (on EntityA's timeline only)
+EntityB reacts to EventA via a read model/automation, it doesn't own it
 ```
 
-**Why**: State is derived from events, never stored. Events are source of truth. This enables consistent replay, audit trails, and time-travel debugging.
-
-### 5. Command With Multiple Issuers
-
-A command is never issued by more than one thing — a COMMAND with 2+ inbound SCREEN/AUTOMATION edges hides which actor is actually responsible. See `place-element`'s Step 7c for the full check-and-fix mechanics (which edge to keep, how to remove the rest).
-
-**Why**: Each command represents one specific trigger's decision to act — collapsing two triggers onto one command node usually means either a naming/slice-boundary mistake or a stray manual/pre-existing edge (auto-connect itself now guards against fresh occurrences — see `learn-eventmodelers-api` §3).
+**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.
 
 ---
 
 ## Questions to Ask During Validation
 
-**For each event stream**:
-1. "Do all events in this stream share the same identity (streamId)?"
-2. "Could these events occur in any order, or is sequence important?"
-3. "Is every event in this stream an immutable fact that actually happened?"
+**For each entity's timeline**:
+1. "Do all events on this timeline belong to the same entity?"
+2. "Could these events occur in any order, or does sequence matter?"
+3. "Is every event on this timeline an immutable fact that actually happened?"
 
-**For each command handler**:
-1. "Does this handler own its own [CommandHandler]State class?"
-2. "Is the state ephemeral (reconstructed per command, not persisted)?"
-3. "Can I trace the state reconstruction: events → evolve() → decision?"
+**For each command**:
+1. "Are its preconditions written down, not just assumed?"
+2. "Does it produce an event, or document why it's rejected?"
 
 **For each read model**:
 1. "Is this calculated from events via a projection?"
 2. "Does it answer a specific query need?"
-3. "Could its data change due to new events or state changes?"
-
-**For system architecture**:
-1. "Does each command handler operate independently (communicate via events only)?"
-2. "Could I run two handlers' code in parallel without merge conflicts?"
-3. "Are the only shared artifacts the event definitions?"
+3. "Could its data change due to new events?"
 
 ---
 
 ## Success Criteria
 
  **Model is validated when**:
-- All 17 checks pass (or have documented workarounds)
+- All 12 checks pass (or have documented workarounds)
 - No critical anti-patterns identified
-- All 3 final questions answer YES
-- Event sourcing principles clearly upheld
-- Ready to proceed to code generation
+- Both final questions answer YES
+- Event modeling principles are clearly upheld
 
  **Model needs fixes when**:
 - Any check fails with clear evidence
 - Anti-patterns identified with specific violations
-- Final questions have NO answers
+- A final question has a NO answer
 - Fixes are straightforward and targeted
 
  **Model should be redesigned when**:
 - Multiple phases fail
-- Architectural assumptions are fundamentally flawed
+- Structural assumptions are fundamentally flawed
 - Anti-patterns are systemic and pervasive
-- Would require rewriting core event structure
+- Would require rewriting the core event timeline
 
 ---
 
@@ -248,25 +206,13 @@ A command is never issued by more than one thing — a COMMAND with 2+ inbound S
 When you see something like "CalculationDone" or "ReviewRatingUpdated":
 - Ask: "Is this immutable and caused by a user/system action?"
 - If NO → It's a read model, not an event
-- Fix: Remove from events, create read model projection instead
-
-### Pattern: Shared vs Isolated State
-When you see "ReviewAggregate" used by multiple handlers:
-- Ask: "Could SubmitReviewHandler and ApproveReviewHandler work on separate files?"
-- If NO → State classes aren't properly isolated
-- Fix: Create SubmitReviewState and ApproveReviewState, each handler owns one
-
-### Pattern: Persistent vs Ephemeral State
-When state is saved to database after a command:
-- Ask: "Is this state only needed during command processing?"
-- If YES → It's ephemeral, reconstruct from events instead
-- Fix: Load events, replay via evolve(), process command, discard state
+- Fix: Remove from events, create a read model projection instead
 
 ### Pattern: Data That Doesn't Trace
 When a read model field appears without source:
 - Ask: "Where did this come from?"
-- If no event source → Add event or remove field
-- If sourced from calculation → Verify it's in projection, not event
+- If no event source → Add the event or remove the field
+- If sourced from a calculation → Verify it's in the read model, not the event
 
 ---
 
@@ -285,19 +231,19 @@ Step 3-8: Storyboard, Inputs, Outputs, Conway's Law, Scenarios, Completeness
   ↓
 Step 9: Validate (eventmodeling-validating-event-models)
   ↓
-→ RUN eventmodeling-validating-event-models-checklist again (production-readiness pass)
+→ RUN eventmodeling-validating-event-models-checklist again (final structural pass)
   ↓
-PASS → Step 10: Slice, Step 11: Document Reasoning → Code generation
+PASS → Step 10: Slice, Step 11: Document Reasoning
 FAIL → Fix identified issues
 ```
 
-Running the checklist after Step 2 prevents wasting time on later steps if core events are flawed.
+Running the checklist after Step 2 prevents wasting time on later steps if the core events are flawed.
 
 ---
 
 ## Checklist Questions by Domain
 
-The skill applies the same 17 checks regardless of domain. Here's how to think about it in different contexts:
+The skill applies the same 12 checks regardless of domain. Here's how to think about it in different contexts:
 
 **E-commerce domain**:
 - Events: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped
@@ -321,26 +267,26 @@ The principle is the same across all domains: **immutable facts as events, calcu
 
 ## Tips for Best Results
 
-1. **Be specific**: List actual event names, command handler names, and state classes from your model
-2. **Reference your documentation**: Link to or quote from your step 1-7 documents and micro-slice plans
-3. **Provide context**: Explain what your domain is and how handlers will be parallelized
-4. **Ask follow-ups**: If a check flags an issue, ask "How do I fix this specifically?" or "Can this handler be isolated?"
-5. **Iterate**: Run again after making fixes to confirm all checks pass and handlers are properly isolated
+1. **Be specific**: List actual event and command names from your model
+2. **Reference your documentation**: Link to or quote from your step 1-7 documents
+3. **Provide context**: Explain what your domain is
+4. **Ask follow-ups**: If a check flags an issue, ask "How do I fix this specifically?"
+5. **Iterate**: Run again after making fixes to confirm all checks pass
 
 ## Quality Checklist
 
-- [ ] All 17 checks evaluated — no check skipped without documented justification
-- [ ] Every FAIL result includes the specific event, handler, or stream that violated the check
+- [ ] All 12 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
-- [ ] All 3 final architectural questions answered YES before declaring model ready for implementation
+- [ ] Both final questions answered YES before declaring the model ready
 - [ ] Any FAIL result has a recommended fix, not just a problem statement
 
 ---
 
 ## Related Skills
 
-- **eventmodeling-orchestrating-event-modeling**: Main skill coordinating the 11-step event modeling process
+- **eventmodeling-orchestrating-event-modeling**: Main skill coordinating the full event modeling process
 - **eventmodeling-brainstorming-events**: Extract events from requirements (Step 1)
 - **eventmodeling-plotting-events**: Sequence events chronologically (Step 2)
 - **eventmodeling-designing-event-models**: Design your complete event model
@@ -350,6 +296,5 @@ The principle is the same across all domains: **immutable facts as events, calcu
 
 ## Validation Checklist Reference
 
-The 17-point checklist is defined in the **Validation Phases** section above.
+The 12-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/place-element/SKILL.md

@@ -196,9 +196,23 @@ Cell IDs are always `<rowId>-<columnId>` — no cell array search needed.
 
 **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.
 
+**One COMMAND / READMODEL / SCREEN / AUTOMATION per column — server-enforced, not just a heuristic.** Unlike the EVENT rule above (which this skill has to check for itself), the server itself rejects a second `COMMAND`, `READMODEL`, `SCREEN`/`HTML_SCREEN`, or `AUTOMATION` landing in a column that already has one of that type — across *every* row of the relevant lane (`interaction` for COMMAND/READMODEL, `actor` for SCREEN/AUTOMATION), not only the exact target cell. A board can have several separate `interaction` or `actor` rows, so the target cell itself can be empty and the placement will still fail with a `ValidationError` ("Column already has a … node … — only one … is allowed per column"). Treat that rejection exactly like a same-cell conflict in the table below — insert a new column rather than retrying the same one.
+
 **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 `cells` array you already fetched in Step 3 via `get_node` (`projection: "cells"`) 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):
+**Fastest path**: use the `cells` array you already fetched in Step 3 via `get_node` (`projection: "cells"`) 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. Also scan it for the column-wide conflict from the rule above: any entry with `colId === columnId` and `nodeType === elementType` (for COMMAND/READMODEL/SCREEN/AUTOMATION) means the column is occupied even though `CELL_ID` itself is free. This avoids an extra round-trip, but can be stale if a column was just created in Step 5 — re-fetch first in that case.
+
+**No direct MCP equivalent** for querying by cell/column: `get_nodes` only filters by `type`. The REST API does support it directly though — `GET /nodes` takes `cellId` **or** `colId`, both requiring `timelineId`:
+
+```bash
+# Same-cell occupancy — returns [] if empty, or [nodeRecord] if occupied
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID&timelineId=$TIMELINE_ID"
+
+# Column-wide occupancy (any row) — optionally add &type=READMODEL to narrow to one element type
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?colId=$COLUMN_ID&timelineId=$TIMELINE_ID"
+```
+
+Use this REST call (see the curl fallback below) when you don't already have fresh `timelineData` loaded, instead of re-fetching the whole chapter node just to check occupancy.
 
 **Fallback (no MCP):** see `references/api-fallback.md` — "Step 6 — Check cell occupancy".
 

package/stacks/modeling-kit/templates/.claude/skills/place-element/references/api-fallback.md

@@ -55,10 +55,20 @@ Response: `{ "columnId": "<uuid>", "index": <n>, "totalColumns": <n> }`
 
 ## Step 6 — Check cell occupancy
 
+`GET /nodes` takes `cellId` **or** `colId`, both requiring `timelineId` — no need to re-fetch and parse the whole chapter node just for this:
+
 ```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID"
+# Same-cell occupancy — [] if empty, [nodeRecord] if occupied
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID&timelineId=$TIMELINE_ID"
+
+# Same-column occupancy, across every row of the timeline — add &type=<elementType> to narrow
+# (the server enforces one COMMAND/READMODEL/SCREEN/HTML_SCREEN/AUTOMATION per column even when
+# the target cell itself is empty — see SKILL.md)
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?colId=$COLUMN_ID&timelineId=$TIMELINE_ID"
 ```
 
+If you already have fresh `timelineData` loaded from Step 3, reading its `cells` array directly (sparse — an entry only exists once something has been placed there) avoids the extra round-trip; use the calls above otherwise, or when `timelineData` might be stale (e.g. a column was just created).
+
 ## Step 6 — Insert a column at a specific index (conflict resolution)
 
 No relative-insertion equivalent over REST (unlike MCP's `afterNodeId`) — compute the index by hand: