@eventmodelers/cli 1.0.36 → 1.0.38

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

@@ -10,6 +10,8 @@ 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.
 
 ## Board Context
@@ -23,16 +25,7 @@ mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "COMMAND" }
 mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "READMODEL" }
 ```
 
-**Fallback (no MCP):**
-```bash
-# All nodes (events, commands, read models, screens)
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Board Context".
 
 Use these results as the source of truth for the completeness check.
 
@@ -48,115 +41,13 @@ After the analysis, use the `handle-comment` skill to post findings on relevant
 Perform comprehensive completeness check:
 
 ### 1. Field Origin & Destination Matrix
-For every field in every event, verify source and use:
-
-```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
-```
+For every field in every event, verify its origin (a command, a calculation, or the system) and every destination that consumes it (other events, read models, external systems), marking each field's status as complete or a gap. A full worked example (Order domain) is in `references/examples.md`.
 
 ### 2. Check All Commands
-Verify every command input is captured:
-
-```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 
-```
+Verify every command input is captured somewhere in the resulting event, whether directly or implicitly. A full worked example is in `references/examples.md`.
 
 ### 3. Check All Read Models
-Verify read models have all needed data:
-
-```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 
-```
+Verify every field a read model displays is sourced from a connected event. A full worked example is in `references/examples.md`.
 
 ### 4. Check Slice Coverage
 
@@ -171,322 +62,40 @@ Or, to get the full SLICE_BORDER nodes (with `columnId`) the same way as the cur
 mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "SLICE_BORDER" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=SLICE_BORDER"
-```
-
-Cross-reference each COMMAND/READMODEL node's column against the `columnId` of the SLICE_BORDER nodes:
-
-```text
-Column: CreateOrder (COMMAND)
-Slice defined? Yes — "Place Order"
-Status: Covered
-
-Column: OrderStatusView (READMODEL)
-Slice defined? No
-Status: Missing slice — flag as gap
+**Fallback (no MCP):** see `references/api-fallback.md` — "4. Check Slice Coverage".
 
-Column: ConfirmOrder (COMMAND, linkedTo set — copy of the original in another column)
-Slice defined? N/A — linked copy, exempt
-Status: Skip
-```
+Cross-reference each COMMAND/READMODEL node's column against the `columnId` of the SLICE_BORDER nodes, flagging any column with no matching slice as a gap (skipping linked copies, which are exempt). A full worked example is in `references/examples.md`.
 
 ### 5. Check Event Stream Completeness
 Verify no "missing" events:
 
-```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 
-```
+Walk the full timeline scenario end-to-end (creation through terminal state) checking for missing events, and separately verify that alternative/branch paths (cancellations, failures, compensations) are also represented. A full worked example is in `references/examples.md`.
 
 ### 6. Check System Boundaries
 Verify each system owns events:
 
-```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 
-```
+For each system/bounded context, verify it owns a coherent, non-overlapping set of events, and that any processor it runs only reacts to events it's entitled to. A full worked example is in `references/examples.md`.
 
 ### 7. Define Workflow Step Contracts
 Each workflow step is a contract between the previous step and the next. Document preconditions and postconditions:
 
-```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.
+Treat each workflow step as a contract: document its preconditions (what must already be true, usually the previous step's postcondition) and its postconditions (what event now exists and which fields it carries), so a later step — or a different team — can build against the contract without waiting on the implementation. A full worked example (a three-step Order contract chain) is in `references/examples.md`.
 
---- 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).
-```
-
-**Why Contracts Matter for Parallel Development**:
-```text
-Team A: Works on CreateOrder (Step 1)
-  → Knows postcondition: OrderCreated with specific fields
-  → Knows other teams depend on this
-
-Team B: Works on ConfirmOrder (Step 2)
-  → Can start immediately, doesn't wait for Step 1 implementation
-  → Just needs to know: "I expect OrderCreated event with these fields"
-  → Writes tests that mock the OrderCreated event
-  → When Step 1 is done, tests pass immediately
-
-Team C: Works on AuthorizePayment (Step 3)
-  → Can start immediately
-  → Expects: OrderConfirmed event with these fields
-  → When Step 2 is done, tests pass immediately
-
-Result: 3 teams working in parallel instead of waiting sequentially!
-```
+**Why contracts matter for parallel development**: a team can start building the next step immediately against the previous step's postcondition (mocking the event it depends on), instead of waiting for that step's implementation to finish. See `eventmodeling-orchestrating-event-modeling`'s linked `project-planning-with-event-modeling.md` reference for the fully worked example and the resulting flat cost curve.
 
 ### 8. Check Field Traceability
 Matrix of all fields origin → destination:
 
-```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 
-```
+Build a matrix of every field crossing Event / Command / Read Model / Processor, confirming each field's presence is accounted for across the whole model. A full worked example is in `references/examples.md`.
 
 ### 9. Identify Gaps
 Document any missing pieces:
 
-```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
-```
+For each candidate gap, check whether the data already exists elsewhere in the model before treating it as missing, and record which gaps were fixed versus which remain outstanding. A full worked example is in `references/examples.md`.
 
 ## Output Format
 
-Present as:
-
-```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.
-```
+Older versions of this skill wrote the completeness check as a markdown report rather than posting comments on board nodes — that legacy template is kept in `references/examples.md` for reference only; the actual output mechanism is the `handle-comment`-based comment posting described in "Board Context" above.
 
 ## Quality Checklist
 
@@ -548,10 +157,6 @@ The model is **complete** when:
 | **False duplicate** | Two nodes share a title | Check `data.linkedTo` on both before reporting — a linked copy is intentional, not a gap |
 | **Missing slice** | COMMAND/READMODEL column with no SLICE_BORDER | Define a slice for that column (unless it's a linked copy) |
 
-## Reference Documentation
-
-- **[Security Analysis with Event Modeling](references/security-analysis-with-event-modeling.md)** — How to use the field traceability matrix and data flow visibility from this step to conduct a systematic security review: identifying trust boundaries, privilege escalation paths, and data exposure risks across the event model.
-
 ## Next Steps
 
 If completeness check passes:

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

@@ -0,0 +1,22 @@
+# Checking Completeness — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## Board Context
+
+```bash
+# All nodes (events, commands, read models, screens)
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
+```
+
+## 4. Check Slice Coverage
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=SLICE_BORDER"
+```