@eventmodelers/cli 1.0.36 → 1.0.38

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-checking-completeness/references/examples.md

@@ -0,0 +1,397 @@
+# Checking Completeness — Worked Examples
+
+These are conceptual worked examples (Order/Payment domain) illustrating the completeness-check reasoning this skill applies — useful for understanding the reasoning, but the actual mechanics live in the numbered Workflow sections of the main SKILL.md (reading board state and posting `TASK`/`QUESTION` comments via `handle-comment`), not in writing a document like this.
+
+## 1. Field Origin & Destination Matrix
+
+```text
+Event: OrderCreated
+
+Field: orderId
+Origin: Generated by system (UUID)
+Destinations:
+     OrderConfirmed event (references)
+     OrderStatusView (displays)
+     OrderListView (displays)
+     OrderShipped event (references)
+Status:  Complete
+
+Field: customerId
+Origin: CreateOrder command (from UI)
+Destinations:
+     OrderStatusView (displays)
+     OrderListView (displays)
+     Inventory System (knows who ordered)
+Status:  Complete
+
+Field: items[]
+Origin: CreateOrder command (user selects)
+Destinations:
+     OrderStatusView (displays)
+     Inventory System (what to reserve)
+     Fulfillment System (what to ship)
+Status:  Complete
+
+Field: total
+Origin: Calculated from items[] and unit prices
+Destinations:
+     OrderStatusView (displays)
+     OrderListView (displays)
+     PaymentSystem (amount to charge)
+     Accounting (for reconciliation)
+Status:  Complete
+
+Field: shippingAddress
+Origin: CreateOrder command (user enters)
+Destinations:
+     OrderStatusView (displays)
+     Fulfillment System (where to ship)
+     Carrier (delivery address)
+Status:  Complete
+
+Field: createdAt
+Origin: System timestamp when event created
+Destinations:
+     OrderStatusView (displays)
+     OrderListView (displays)
+     Metrics (average order age)
+Status:  Complete
+```
+
+## 2. Check All Commands
+
+```text
+Command: CreateOrder
+Input: customerId, items[], shippingAddress
+   customerId → OrderCreated.customerId
+   items[] → OrderCreated.items
+   shippingAddress → OrderCreated.shippingAddress
+Status: All inputs captured 
+
+Command: ConfirmOrder
+Input: orderId, paymentMethod
+   orderId → OrderConfirmed.orderId (implicit)
+   paymentMethod → OrderConfirmed.paymentMethod
+Status: All inputs captured 
+
+Command: AuthorizePayment
+Input: orderId, paymentId, authCode
+   orderId → PaymentAuthorized.orderId (implicit)
+   paymentId → PaymentAuthorized.paymentId
+   authCode → PaymentAuthorized.authCode
+Status: All inputs captured 
+```
+
+## 3. Check All Read Models
+
+```text
+ReadModel: OrderStatusView
+Needs to display:
+     orderId ← OrderCreated
+     customerId ← OrderCreated
+     status ← OrderConfirmed, PaymentAuthorized, etc.
+     items ← OrderCreated
+     total ← OrderCreated
+     createdAt ← OrderCreated
+     confirmedAt ← OrderConfirmed
+     paymentId ← PaymentAuthorized
+     paymentMethod ← OrderConfirmed
+     shipmentId ← OrderShipped
+     trackingNumber ← OrderShipped
+Status: All fields sourced 
+
+ReadModel: OrderListView
+Needs to display:
+     orderId ← OrderCreated
+     customerId ← OrderCreated
+     total ← OrderCreated
+     status ← OrderConfirmed, OrderCancelled, etc.
+     createdAt ← OrderCreated
+Status: All fields sourced 
+```
+
+## 4. Check Slice Coverage
+
+```text
+Column: CreateOrder (COMMAND)
+Slice defined? Yes — "Place Order"
+Status: Covered
+
+Column: OrderStatusView (READMODEL)
+Slice defined? No
+Status: Missing slice — flag as gap
+
+Column: ConfirmOrder (COMMAND, linkedTo set — copy of the original in another column)
+Slice defined? N/A — linked copy, exempt
+Status: Skip
+```
+
+## 5. Check Event Stream Completeness
+
+```text
+Scenario: Order from creation to delivery
+
+Timeline:
+1. OrderCreated  (from CreateOrder command)
+2. OrderConfirmed  (from ConfirmOrder command)
+3. PaymentAuthorized  (from AuthorizePayment processor command)
+4. InventoryReserved  (from ReserveInventory processor command)
+5. OrderShipped  (from CreateShipment processor command)
+6. DeliveryConfirmed  (from MarkDelivered processor command)
+
+Missing events? None identified 
+
+Alternative paths:
+- OrderCancelled  (can happen after OrderCreated or OrderConfirmed)
+- PaymentFailed  (can happen during PaymentAuthorized)
+- RefundInitiated  (can happen after PaymentFailed or OrderCancelled)
+
+Status: All paths covered 
+```
+
+## 6. Check System Boundaries
+
+```text
+Order System
+Events: OrderCreated, OrderConfirmed, OrderCancelled 
+Processor: None (triggers other systems)
+Status: Clean ownership 
+
+Payment System
+Events: PaymentAuthorized, PaymentFailed, PaymentRefunded 
+Processor: PaymentAuthorizer (listens to OrderConfirmed)
+Status: Clean ownership 
+
+Inventory System
+Events: InventoryReserved, InventoryReleased 
+Processor: InventoryReserver (listens to PaymentAuthorized)
+Status: Clean ownership 
+
+Fulfillment System
+Events: OrderShipped, DeliveryConfirmed 
+Processor: ShipmentCreator (listens to InventoryReserved)
+Status: Clean ownership 
+
+Notification System
+Events: None (no persistence, info-only)
+Processor: Notifier (listens to all events)
+Status: Cross-cutting concern 
+```
+
+## 7. Define Workflow Step Contracts
+
+```text
+Workflow Step 1: CreateOrder (Step Owns: Order Creation)
+
+Preconditions (what must exist before this step):
+    - Customer must exist
+    - Products must exist in catalog
+    - User must be authenticated
+
+Postconditions (what exists after this step):
+    - OrderCreated event exists
+    - Event contains: orderId, customerId, items, total, shippingAddress, createdAt
+
+Contract: Any system can assume if these postconditions are true,
+            the order has been properly created through this step.
+
+--- Workflow Step 2: ConfirmOrder (Step Owns: Order Confirmation)
+
+Preconditions (depends on Step 1 postcondition):
+    - OrderCreated event must exist ( from Step 1 contract)
+    - Customer must select payment method
+
+Postconditions (what exists after this step):
+    - OrderConfirmed event exists
+    - Event contains: orderId, paymentMethod, confirmedAt
+
+Contract: Any system can assume if these postconditions are true,
+            the order has been properly confirmed.
+
+--- Workflow Step 3: AuthorizePayment (Step Owns: Payment Authorization)
+
+Preconditions (depends on Step 2 postcondition):
+    - OrderConfirmed event must exist ( from Step 2 contract)
+    - Payment method must be valid
+
+Postconditions (what exists after this step):
+    - PaymentAuthorized event exists
+    - Event contains: paymentId, authCode, amount
+
+Contract: Once this postcondition is true, next steps can proceed
+            without re-checking payment (trust the contract).
+```
+
+## 8. Check Field Traceability
+
+```markdown
+| Field | Event | Command | Read Model | Processor |
+|-------|-------|---------|-----------|-----------|
+| orderId | OrderCreated | - | All views | All |
+| customerId | OrderCreated | CreateOrder | OrderStatusView | - |
+| items | OrderCreated | CreateOrder | List/Status views | Inventory |
+| total | OrderCreated | - | List/Status views | - |
+| paymentId | PaymentAuthorized | AuthorizePayment | StatusView | Inventory |
+| shipmentId | OrderShipped | CreateShipment | StatusView | Notification |
+| trackingNumber | OrderShipped | - | TrackingView | Notification |
+
+Status: All fields traceable 
+```
+
+## 9. Identify Gaps
+
+```text
+Analysis: Are there any missing fields?
+  - Estimated delivery date?
+    → Need to add to OrderShipped event
+    → Can be calculated from carrier
+    → Add to ShipmentTrackingView
+
+  - Cancellation reason?
+    → Already in OrderCancelled event 
+
+  - Payment failure reason?
+    → Already in PaymentFailed event 
+
+  - Refund status?
+    → Need to track in RefundInitiated event
+    → Add to PaymentStatusView
+
+Actions taken:
+   Add estimatedDelivery to OrderShipped
+   Add refundStatus to PaymentStatusView
+   Add refundInitiatedAt to OrderStatusView
+```
+
+## Legacy markdown-document format (superseded — kept for reference only)
+
+Older versions of this skill wrote the completeness check as a markdown report. The actual mechanism today is reading board state and posting `TASK`/`QUESTION` comments via `handle-comment` (see "Board Context" in the main SKILL.md) — this template is kept only so the shape of the information (what a complete completeness report covers) stays documented somewhere.
+
+```markdown
+# Completeness Check: [Domain Name]
+
+## Workflow Step Contracts
+
+### Step 1: CreateOrder
+
+**Preconditions**:
+- Customer exists in system
+- Products exist in catalog
+
+**Postconditions**:
+- OrderCreated event exists with fields: [list]
+
+**Teams that depend on this contract**: [All downstream teams]
+
+---
+
+### Step 2: ConfirmOrder
+
+**Preconditions** (depends on Step 1):
+- OrderCreated event exists 
+
+**Postconditions**:
+- OrderConfirmed event exists with fields: [list]
+
+--- [Continue for each workflow step]
+
+---
+
+## Field Traceability Matrix
+
+### Events
+
+| Event | Field | Origin | Destinations | Status |
+|-------|-------|--------|-------------|--------|
+| OrderCreated | orderId | System | ConfirmOrder, Views |  |
+| OrderCreated | customerId | CreateOrder | All views |  |
+| OrderCreated | items | CreateOrder | Inventory, Views |  |
+| OrderCreated | total | Calculated | Views, Payment |  |
+| OrderConfirmed | paymentId | AuthorizePayment | Views, Accounting |  |
+| OrderShipped | trackingNumber | Carrier | TrackingView |  |
+
+---
+
+## System Ownership Verification
+
+### Order System
+- Events owned: OrderCreated, OrderConfirmed, OrderCancelled
+- Completeness:  All order lifecycle events present
+
+### Payment System
+- Events owned: PaymentAuthorized, PaymentFailed, PaymentRefunded
+- Completeness:  All payment states covered
+
+---
+
+## Command → Event Verification
+
+| Command | Input | Event | Captured |
+|---------|-------|-------|----------|
+| CreateOrder | customerId, items, address | OrderCreated |  |
+| ConfirmOrder | paymentMethod | OrderConfirmed |  |
+| AuthorizePayment | paymentId, authCode | PaymentAuthorized |  |
+
+---
+
+## Slice Coverage
+
+| Column | Node | Has Slice? | Status |
+|--------|------|-----------|--------|
+| 1 | CreateOrder (COMMAND) | Yes — "Place Order" |  |
+| 2 | OrderStatusView (READMODEL) | No |  Missing slice |
+| 3 | ConfirmOrder (COMMAND, linked copy) | N/A |  Exempt (linkedTo set) |
+
+---
+
+## Read Model Coverage
+
+### OrderStatusView
+- All relevant event data included
+- All user display needs met
+- All processor decision fields present
+
+### OrderListView
+- Summary fields captured
+- Filtering/sorting fields present
+- Linked to OrderStatusView for details
+
+---
+
+## Gap Analysis
+
+### Issues Found
+1. Estimated delivery date missing
+   - Fix: Add to OrderShipped event
+   - Type: DateTime (ISO 8601)
+   - Source: Calculated from carrier API
+   - Status: Will add in next iteration
+
+2. Refund tracking incomplete
+   - Fix: Add RefundInitiated event timestamp
+   - Fix: Add refund status to PaymentStatusView
+   - Status: Will add in next iteration
+
+### No Critical Gaps
+- All events properly sourced
+- All command inputs captured
+- All read models have data
+- Event flow complete
+- System boundaries clear
+
+---
+
+## Readiness Assessment
+
+**Overall Completeness**: 95%
+
+**Blockers**: None
+
+**Ready for Code Generation**:  YES
+
+**Minor Improvements**:
+- Add estimated delivery date (non-blocking)
+- Enhance refund tracking (non-blocking)
+
+**Recommendation**: Proceed to code generation phase.
+```

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

@@ -0,0 +1,182 @@
+---
+name: eventmodeling-core-rules
+description: Shared, foundational rules for every event-modeling step — what a COMMAND/EVENT/READMODEL/SCREEN/AUTOMATION is, how each is named, and the anti-patterns to reject. Not a step of its own — referenced upfront by every other eventmodeling-* skill instead of each restating its own copy. Do not use standalone.
+---
+
+# Event Modeling — Core Rules
+
+These rules apply to every step of event modeling, regardless of which step's SKILL.md you're currently following. Read this once per session — a step's own file only states what's specific to that step, not these fundamentals.
+
+## Modes
+
+Which step you're in sets the posture — don't mix them.
+
+- **Modeling Mode** — `brainstorming-events`, `plotting-events`, `storyboarding-events`, `identifying-inputs`, `identifying-outputs`, `designing-automation-chains`, `elaborating-scenarios`, `translating-external-events`: explore and build. Capture the process as completely as you can. A naming slip or an incomplete precondition is something to flag and move past, not a reason to stall the whole step — don't over-correct early.
+- **Critic Mode** — `validating-event-models`, `validating-event-models-checklist`, `checking-completeness`, `wdyt`, `optimizing-stream-design`: review what's already there. Apply every rule in this file strictly. Surface every violation, gap, and inconsistency — don't soften a finding because the model "mostly works." Post findings as comments (`handle-comment`) rather than silently fixing them, unless the step explicitly says to fix.
+
+Don't mix them in one pass: a modeling step is not the place to run a full rules audit, and a critic step is not the place to quietly add missing structure on the model's behalf instead of flagging it.
+
+## Lanes — What Lives Where
+
+Every column on a timeline has (at most) four rows, and each element type belongs in exactly one:
+
+| Lane type | Elements allowed | What it represents |
+|---|---|---|
+| `actor` | SCREEN, AUTOMATION | Who or what initiates — a human via a screen, or a system via an automation |
+| `interaction` | COMMAND, READMODEL | The business intent going in (COMMAND), or the query result coming out (READMODEL) |
+| `swimlane` | EVENT | The business fact recorded — which system/entity's own story this event belongs to |
+| `spec` | SCENARIO | The Given/When/Then behavior spec for this column's COMMAND or READMODEL |
+
+An EVENT never shares a column with another EVENT even across different swimlane rows — one column is one moment in time. See `place-element` for the full placement mechanics; this table is only "what belongs where," not "how to place it."
+
+## Slices
+
+A **slice** is the thinnest possible vertical cut through the model — exactly one COMMAND, one READMODEL, or one AUTOMATION's command, never combined:
+
+```
+state-change slice = SCREEN/AUTOMATION → COMMAND → EVENT(s)
+state-view slice   = EVENT(s) → READMODEL → SCREEN/AUTOMATION
+automation slice   = EVENT(s) → AUTOMATION → COMMAND → EVENT(s)
+```
+
+A slice never mixes a COMMAND and a READMODEL — those are two different slice types (`state-change` and `state-view`), even when they belong to the same feature. Slices are independently deployable and only communicate with each other via events.
+
+Slices are not placed directly — they're **derived** from a completed model. Every COMMAND on the board implies a `state-change` slice, every READMODEL implies a `state-view` slice, every AUTOMATION implies an `automation` slice. `eventmodeling-slicing-event-models` makes that implicit structure explicit on the board once modeling is done; it never invents a slice that isn't already implied by an element that's there.
+
+## Elements
+
+### EVENT
+- Represents a business fact that already happened.
+- Naming: past tense, business language.
+  - Valid: `OrderPlaced`, `PaymentAuthorized`, `UserRegistered`
+  - Invalid: `SidebarOpened`, `RequestCompleted`, `ApiCalled` — these describe machinery or UI state, not business facts
+- Immutable — never modify or delete an event once created; a correction is a new event, not an edit.
+- Contains only captured facts. No computed or derived values — those belong in a READMODEL.
+
+### COMMAND
+- Represents business intent — what an actor wants to do.
+- Can be rejected; only succeeds if its documented preconditions hold.
+- Naming: imperative, business language.
+  - Valid: `PlaceOrder`, `ConfirmPayment`, `CancelSubscription`
+  - Invalid: `LoadOrders`, `FetchData`, `OpenDialog` — these are queries or UI-only actions, not business intent
+- Issued by exactly one SCREEN or AUTOMATION — never two. See `place-element`'s Step 7c for the mechanical check/fix; this rule is stated here, the fix lives there.
+- Produces one or more EVENTs on success, or is rejected with no event.
+
+### READMODEL
+- A projection built from events, shaped for a specific query.
+- Naming: noun phrase, business language, named for the data — not the machinery that produces it.
+  - Valid: `OrderSummary`, `InvoiceList`
+  - 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.
+
+### SCREEN
+- Represents what a user sees and can act on.
+- Naming: what a user would call it, not its internals.
+  - Valid: `Dashboard`, `OrderOverviewPage`
+  - Invalid: `OrderOverviewComponent`, `ProjectorView`
+
+### AUTOMATION
+- Represents an automated actor — a processor, scheduler, or system reacting to events.
+- Naming: what it does, in business language.
+  - Valid: `BillingScheduler`, `InventoryReserver`
+  - Invalid: `OrderServiceHandler` — implementation-flavored, not a business actor's name
+
+## Causality
+
+- Every EVENT traces to the COMMAND that produced it.
+- Every COMMAND traces to the SCREEN or AUTOMATION that issued it — exactly one.
+- A process starts with a read (SCREEN + READMODEL) or an AUTOMATION reacting to an existing EVENT — never with an unmotivated COMMAND.
+
+## Role Catalog
+
+Every event model needs one, established before brainstorming events (it's the first mandatory step) — without it, downstream steps have no way to say *who* does what:
+
+- **Human roles** (Customer, Seller, Admin...) and **system actors** (Payment Gateway, Scheduler...), each with: a name in domain language, a one-line description, its key actions, and what it explicitly cannot do.
+- No COMMAND may be attributed to a generic "User" — it must name a specific role or actor from the catalog.
+- Every COMMAND is issued by exactly one role/actor (this is the same rule as the COMMAND single-issuer rule above, stated from the Role Catalog's side).
+- Every human role needs at least one COMMAND and one READMODEL — a role in the catalog that never acts and never sees anything is decorative, not modeled.
+
+See `eventmodeling-brainstorming-events` for how the catalog is built, `eventmodeling-identifying-inputs` for attributing commands to it, and `eventmodeling-validating-event-models` for re-checking it holds once the model is complete.
+
+## Field Lineage
+
+Every field on a COMMAND or READMODEL must carry a `mapping` that traces it back to where its value actually comes from — user input, the session, a prior event's field, a derived/computed value, or an external webhook payload. **A field with no mapping is a gap, not a detail to fill in later.**
+
+See `eventmodeling-identifying-inputs` for the full COMMAND mapping vocabulary and `eventmodeling-identifying-outputs` for the READMODEL equivalent — this rule only states that every field must have one, not the mapping syntax itself.
+
+## Connections Read Forward
+
+A connection either goes **downward within the same column** (actor → interaction → swimlane → spec) or **forward to a later column** — never backward (right-to-left). This is why elements that belong together — a SCREEN and the READMODEL it queries, a SCREEN/AUTOMATION and the COMMAND it issues, a COMMAND and the EVENT it produces — should share a column whenever possible: the moment they don't, a backward arrow becomes a real risk.
+
+When an element's natural column is already occupied by something else, insert a new column immediately before or after (whichever keeps every connection forward) rather than wiring across the gap. See `place-element` for the mechanical insertion rules and each step's own placement section for where "before" vs. "after" applies.
+
+## Translation Chain
+
+An AUTOMATION reacting to an event from another system — external (a webhook/API) or second-swimlane (another team's own timeline) — needs a two-stage shape, never a direct reaction:
+
+```
+external EVENT → todo-list READMODEL → translation AUTOMATION + COMMAND → internal EVENT → worker automation's own todo list
+```
+
+- The external/second-swimlane EVENT opens only a *translation* automation's todo list — never a *worker* automation's todo list directly.
+- A translation automation's own todo list is opened by that external event and is never closed — it doesn't track "done," it only relays.
+- Its resulting COMMAND produces the internal EVENT the domain actually works with — that's the moment external data becomes a business fact in this domain's own language, ready for a worker automation (or anything else) to react to.
+
+Every AUTOMATION, translation or worker, needs its own todo-list READMODEL (opened by triggering events, closed by completion events) — no "pure relay" exemption. See `eventmodeling-designing-automation-chains` for the todo-list pattern and board placement mechanics, and `eventmodeling-translating-external-events` for mapping the external payload's raw fields to the internal EVENT's domain fields (correlation, idempotency, duplicate handling).
+
+## Open Questions vs. Decided Failures
+
+Two different things are easy to conflate, and conflating them corrupts completeness checking:
+
+- **Open question** — something genuinely undecided. Post it as a `QUESTION`-type comment (`handle-comment`) on the relevant node. It stays open until someone actually answers it — resolving means answering, not deleting the comment.
+- **Decided failure** — a rejection or error case whose behavior is already decided (e.g. "payment fails → reject, no event"). Model it as a SCENARIO with `expectError: true` and an `errorDescription` (see `eventmodeling-elaborating-scenarios`), never as a comment. It's permanent, specified behavior, not something waiting on an answer.
+
+A decided failure left as a lingering `QUESTION` comment looks unresolved when it isn't. When counting completeness (`eventmodeling-checking-completeness`), only a genuinely unanswered `QUESTION` counts as a gap — a decided failure path needs its `expectError` scenario, not a comment standing in for one.
+
+## Offline-First Thinking
+
+Model the business process as it would work without any software first, then translate to elements:
+
+- How would this work manually, with people, on paper?
+- Who acts, and what triggers each action?
+- What information do they need before they can act?
+
+Question any step that exists only because of the system — a loading spinner, a cache refresh, a session check is not a business step and does not belong on the timeline. This is the discipline behind the Anti-Patterns below; the anti-patterns are what it looks like when this principle is skipped.
+
+## Anti-Patterns
+
+- **Data-loading commands**: `LoadOrders`/`FetchData` are queries, not business intent — model as a READMODEL, not a COMMAND.
+- **UI-interaction events**: `SidebarOpened`/`ButtonClicked` are UI state, not business facts — don't model them unless the business genuinely cares.
+- **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.
+
+## Flow & Causality
+
+Model causality, not strict sequence:
+
+- A timeline starts with a **state-view** (READMODEL feeding a SCREEN) or an **automation** reacting to an EVENT already on the board — never with an unmotivated COMMAND.
+- Every COMMAND must be traceable to a trigger: a SCREEN (a user decision) or an AUTOMATION (a system reaction).
+- A `state-change` slice must not follow another `state-change` slice without a trigger in between (a new SCREEN or AUTOMATION) — two COMMANDs in a row with nothing issuing the second one is a gap, not a shortcut.
+
+Valid transitions between slices:
+- state-view → state-change
+- state-change → state-view
+- state-change → automation
+- automation → state-change
+- automation → state-view
+
+## Quick Self-Check
+
+Before treating a model as done, verify:
+
+- [ ] Every EVENT is past tense and describes a business fact, not machinery or UI state
+- [ ] Every COMMAND is imperative business intent, not a data-loading query
+- [ ] Every READMODEL is named for its data, not its implementation
+- [ ] No EVENT holds a computed/aggregated value — that belongs in a READMODEL
+- [ ] Every COMMAND has exactly one issuer (one inbound SCREEN or AUTOMATION edge)
+- [ ] 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
+
+This is the fast pass — the full, deeper check is `eventmodeling-validating-event-models-checklist`.