@milehimikey/em 1.6.1 → 1.7.1

package/.claude/skills/event-modeling/reference/em-dsl.md

@@ -10,20 +10,61 @@ Keep `.em` files focused on **structure**; put deep design in markdown linked vi
 
 ## CLI
 
+<!-- GENERATED:cli:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
 ```bash
-em init [file]                 # scaffold a starter model.em (default: model.em); -f to overwrite
-em render <file> -o out.svg    # render (extension picks format: svg, png, pdf)
-em render <file> --emit-dot    # print the Graphviz DOT instead of rendering
-em render <file> --keep-empty-lanes   # keep the API lane even when empty
-em render <file> --slice "<slice-name>" -o slices/<slug>.svg   # this slice's own diagram
-em watch  <file> -o out.svg    # re-render on every save (file-based)
-em watch  <file> -o out.svg --serve   # + localhost live viewer, instant SSE push-reload (--port N)
-em validate <file>             # check event-modeling rules; exit 0 if only warnings/clean
-em validate <file> --list-issues       # print only open `issue "..."` clauses (slice, element, line, text)
-em validate <file> --list-divergences  # print only `divergence "..."` clauses (slice, element, line, text)
-em validate <file> --list-public       # print only events marked `public` (slice, name, line)
-em validate <file> --fail-on-issues    # opt-in CI gate: exit non-zero while any issue remains open
+em --version                              # print the installed em version
+em init [file]                            # scaffold a starter .em model
+em init [file] -f, --force                # overwrite if the file exists
+em render <file>                          # transpile a model and render it (or emit DOT)
+em render <file> -o, --out <path>         # output path (extension picks the format)
+em render <file> -T, --format <fmt>       # output format (svg, png, pdf, ...)
+em render <file> --slice <name>           # render only this slice, redrawn in its own canonical pattern shape (default out: slices/<kebab-slug>.svg)
+em render <file> --emit-dot               # print the generated DOT instead of rendering
+em render <file> --keep-empty-lanes       # keep the API lane even when empty
+em export <file>                          # export a versioned JSON snapshot of the normalized model
+em export <file> -o, --out <path>         # write to a file instead of stdout
+em diff <old> [new]                       # compare two models structurally (two files, or one file across git revisions)
+em diff <old> [new] --from <rev>          # diff <old> against this git revision instead of a second file
+em diff <old> [new] --to <rev>            # diff against this git revision instead of the current file (requires --from)
+em diff <old> [new] --exit-code           # exit 1 if the models differ, 0 if identical (git-diff convention)
+em diff <old> [new] --json                # print a JSON document instead of the text report (see docs/cli.md)
+em glossary <files>                       # cross-model glossary of terms, with consistency checks across models (see docs/cli.md)
+em glossary <files> --json                # print the full glossary document instead of the text report
+em glossary <files> -o, --out <path>      # write the JSON document to a file instead of stdout (requires --json)
+em glossary <files> --list-conflicts      # print only the conflict lines, no summary
+em glossary <files> --fail-on-conflicts   # exit non-zero if any cross-model term conflicts were found (opt-in — conflicts are warnings and don't block by default)
+em catalog <files>                        # generate a browsable static HTML catalog site over one or more .em models (see docs/cli.md)
+em catalog <files> -o, --out <dir>        # output directory
+em catalog <files> -T, --format <fmt>     # diagram format embedded in the catalog (svg or png)
+em catalog <files> --title <text>         # catalog site title
+em catalog <files> --keep-empty-lanes     # keep the API lane even when empty
+em changelog <file>                       # render a model's git history as a business-readable ledger (see docs/cli.md)
+em changelog <file> --from <rev>          # start the walk at this revision (inclusive)
+em changelog <file> --to <rev>            # end the walk at this revision (inclusive; default HEAD)
+em changelog <file> -o, --out <path>      # write to a file instead of stdout
+em watch <file>                           # re-render on every save
+em watch <file> -o, --out <path>          # output path (extension picks the format)
+em watch <file> -T, --format <fmt>        # output format (svg, png, pdf, ...)
+em watch <file> --keep-empty-lanes        # keep the API lane even when empty
+em watch <file> --serve                   # serve a live viewer with instant push-reload (no polling)
+em watch <file> --port <n>                # port for --serve (default 5173)
+em validate <file>                        # check a model against event-modeling rules
+em validate <file> --list-issues          # print only open `issue` diagnostics (slice, element, line, text)
+em validate <file> --list-divergences     # print only accepted-divergence annotations (slice, element, line, text) — never fails the build
+em validate <file> --list-public          # print only events and views marked `public` (slice, kind, name, line) — an integration-surface audit, never fails the build
+em validate <file> --fail-on-issues       # exit non-zero if the model has any open `issue`s (opt-in — issues are warnings and don't block by default)
+em validate <file> --slice-ready <key>    # readiness gate for one slice (export key): status ready-to-implement, doc resolvable via note binding, zero unchecked Open Questions — exits non-zero if not ready (MIL-87)
+em ledger <file>                          # check slice docs' version: field agrees with their content across two git revisions (opt-in CI check, MIL-89 — never part of `em validate`, see docs/ci.md)
+em ledger <file> --from <rev>             # baseline revision
+em ledger <file> --to <rev>               # compare revision (default: current working tree)
+em ledger <file> --json                   # print a JSON document instead of the text report (see docs/cli.md)
+em skill install                          # copy the event-modeling skill into .claude/skills/event-modeling/
+em skill install -f, --force              # overwrite an existing installation
+em skill sync [path]                      # update the vendored .claude/skills/event-modeling/ copy in [path] to match the installed em package (overwrites unconditionally; local edits are never merged, MIL-93)
+em skill check [path]                     # check the vendored .claude/skills/event-modeling/ copy in [path] for drift against the installed em package; exits non-zero on any mismatch (CI-ready, MIL-93)
+em skill check [path] --json              # print a JSON document instead of the text report (see docs/cli.md)
 ```
+<!-- GENERATED:cli:end -->
 
 Install if missing: `npm i -g @milehimikey/em`. PNG works with no system deps; PDF needs
 `rsvg-convert`.
@@ -57,12 +98,14 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
 |---|---|---|---|---|
 | `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `divergence`, `{ fields }` |
 | `command` | API | state-changing request | — | `note`, `issue`, `divergence`, `{ fields }` |
-| `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `divergence`, `{ fields }` |
+| `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `divergence`, `public`, `{ fields }` |
 | `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `divergence`, `public`, `{ fields }` |
 | `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `divergence`, `{ fields }` |
 
 ### Clauses
-- **Tags:** `@Persona` only on `ui`; `@Context` only on `event`. Undeclared tags auto-create a row.
+- **Tags:** `@Persona` only on `ui`; `@Context` only on `event`. Undeclared tags auto-create a
+  row. Multi-word tags need no quoting — the tag captures everything after `@` to end of line
+  (`ui Ticket Queue @Customer Service` matches `persona Customer Service`).
 - **`from "X"`** on views/automations declares the source(s); names are quoted, comma-separated.
   Matching is case-insensitive and whitespace-normalized. A `from` may never point at an event or
   view that first appears in a LATER slice (forward-only timeline — validation error).
@@ -95,18 +138,26 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   Raises **no** `em validate` warning by design; use `--list-divergences` to audit. `em diff
   --json` carries it forward as `acceptedDivergence` on the affected change/removal entry, so
   `conform` can cite an already-ratified deviation instead of re-flagging it as drift every run.
-- **`public`** (events only): marks this event as part of the published integration surface
-  (e.g. an AsyncAPI contract), as opposed to an internal-only fact. Plain structural flag, no
-  free text and no diagram marker (same posture as `again`). Write it as the last token on the
-  line, optionally right before a trailing `@Context` — `event X @Context public` or
-  `event X public @Context` both work. `em export` carries it as `public: true`/`false`;
-  `em diff` reports a flip as `event marked public`/`event unmarked public`;
-  `em validate --list-public` audits which events are public.
+- **`public`** (events and views): marks the element as part of the published integration
+  surface — a published event contract (e.g. AsyncAPI), or a view whose read API/response
+  shape external consumers depend on — as opposed to an internal-only fact or projection.
+  Plain structural flag, no free text and no diagram marker (same posture as `again`). Write
+  it as the last token on the line; on an event, optionally right before a trailing
+  `@Context` — `event X @Context public` or `event X public @Context` both work. A `public`
+  element is exempt from the unread-event / unconsumed-view warnings (its consumer is outside
+  this model). `em export` carries it as `public: true`/`false`; `em diff` reports a flip as
+  `event marked public`/`event unmarked public` (the entry cites the element's kind, so a
+  view flip reads `view "X"`); `em validate --list-public` audits the whole public surface.
 - **Fields:** `command Place Order { orderId: UUID, items: LineItem[], customerId }` — inline or
   one-per-line. Types are free text (no semantic checking) UNLESS the type string names a
   declared `type` (see Named types below), in which case it resolves to a structured
   reference. Keep these light; full field specs with rules live in the slice doc.
 - **Comments:** `# ...` anywhere outside quotes (full-line or trailing).
+- **Quoted strings:** everything between a `"` and its matching `"` is literal — `{`, `}`, `#`
+  included, never re-interpreted as a field block or comment — so REST path-template
+  placeholders are safe as-is: `issue "PUT v3/widgets/{widgetId}/suspend"`. Escape a literal
+  `"` or `\` inside a string with `\"`/`\\`; no other backslash sequence is special. An
+  unterminated string (missing closing `"`) is a parse error naming the clause it broke in.
 - **`source "url"` on a slice header** (the only slice-level clause — everything above is
   per-element) links the slice back to the ticket/conversation it traces to, e.g.
   `slice "Checkout" source "https://linear.app/team/issue/MIL-60" { ... }`. Exports as
@@ -157,12 +208,12 @@ slice "Open Orders" {
   ui Order List @Customer
 }
 
-# 3. Automation: split across TWO slices (plus the read slice that consumes the event)
+# 3. Automation: read model in the slice before, reaction + command + event together
 slice "Orders To Fulfill" {
   view Orders To Fulfill from "Order Placed"
-  processor Fulfillment Service
 }
-slice "Ship Order" {            # the triggered command goes in the NEXT slice
+slice "Ship Order" {            # reaction, command, and event all share this one slice
+  processor Fulfillment Service from "Orders To Fulfill"
   command Ship Order
   event Order Shipped @Shipping
 }
@@ -172,10 +223,8 @@ slice "Open Orders — shipped" {
 }
 
 # 4a. Translation (external trigger, no durable artifact): external call -> translation -> command -> event
-slice "Carrier Webhook" {
+slice "Confirm Delivery" {
   translation Carrier Adapter         # inbound from outside the model; no internal `from`
-}
-slice "Confirm Delivery" {            # the triggered command goes in the NEXT slice
   command Confirm Delivery
   event Delivery Confirmed @Shipping
 }
@@ -192,9 +241,9 @@ slice "Receive Carrier Event" {           # ingest: persist the raw webhook befo
 }
 slice "Inbound Carrier Events" {
   view Inbound Carrier Events from "Carrier Event Received"   # the persisted inbound queue
-  translation Carrier Adapter
 }
 slice "Acknowledge Carrier Event" {
+  translation Carrier Queue Adapter from "Inbound Carrier Events"   # different producer than 4a's Carrier Adapter, so a distinct name
   command Acknowledge Carrier Event
   event Carrier Event Acknowledged @Shipping
 }
@@ -205,15 +254,15 @@ slice "Inbound Carrier Events — processed" {
 
 # 4c. Translation (internal trigger, durable artifact): read model -> translation -> command -> event
 slice "Accept Quote" {
-  ui Quote Screen @Customer     # every command needs a trigger: a ui, or a reaction before it
+  ui Quote Screen @Customer     # every command needs a trigger: a ui, or a reaction, in this slice
   command Accept Quote
   event Quote Accepted @Quote
 }
 slice "Quotes To Sync" {
   view Accepted Quotes from "Quote Accepted"
-  translation CRM Sync                # reacts to our own state via the read model in this slice
 }
 slice "Record Sync" {
+  translation CRM Sync from "Accepted Quotes"   # reacts to our own state via the read model
   command Record Crm Sync
   event Quote Synced @Quote
 }
@@ -232,8 +281,11 @@ the context/lane whose fact it represents (e.g. `Carrier Event Received @Shippin
 Anti-Corruption-Layer event in DDD) instead of a technical artifact leaking foreign vocabulary
 into the model.
 
-A `translation` (like a `processor`) is a **reaction**: it triggers a command and never carries an
-`event` in its own slice. Same two-slice split as the Automation pattern above.
+A `translation` (like a `processor`) is a **reaction**: it triggers a command in the same slice —
+same shape as the Automation pattern above, and the same shape `ui` already uses in State Change.
+The reaction never records the event directly (there's no `reaction -> event` edge); the command
+it triggers is what records it, and that event happens to live in the reaction's own slice now
+because the command does.
 
 Note the read slice closing each pattern: **every event must be read by some read model**
 (warning 4 below). A command slice is not finished until the slice that projects its event
@@ -268,8 +320,9 @@ slice "Read Quote — created" {
   request/response API call — that's Pattern 1 (State Change) with an API persona, exactly like the
   `Create Quote` slice above.
 - **Internal-only commands and views (no public route) carry no `ui` at all.** They follow the
-  ordinary Automation pattern already documented: the reaction sits in the previous slice, and an
-  internal-only read model is consumed by that reaction, not by a screen or an API query.
+  ordinary Automation pattern already documented: the reaction shares the command's slice, and an
+  internal-only read model is consumed by that reaction (from the slice before), not by a screen
+  or an API query.
 - **Repeat the read model** in every slice where it's read so the timeline flows left-to-right, and
   **prefer `view X again`** for every instance after the first (see Clauses) — **each instance
   carries its own consumer** (the `ui` that reads it, or a reaction), not just the last one. `again`
@@ -291,23 +344,19 @@ slice "Read Quote — created" {
   Keep the read model adjacent to its event, and keep a sub-flow that detours into another context
   together rather than parking it at the end of the model.
 
-### Slice-ordering gotchas (edge inference)
-
-`em` infers cross-slice arrows positionally, so **slice order matters**:
-- A **reaction** (`processor`/`translation` that triggers a command) wires to the command in the
-  **immediately next** slice. So a reaction slice must be *directly* followed by its command slice —
-  don't insert a read slice between them.
-- A read slice whose consumer is a **reaction** (`view` + `processor`/`translation`, no command in
-  the same slice) must **not** be immediately followed by a `command` slice, or the reaction will be
-  mis-wired to that command. Put it after a command+event slice, or before another read/reaction
-  slice instead. (A `ui`-consumed read slice has no such risk — `ui` never wires as a reaction.)
-- A read model fed by an early event (e.g. a queue or to-do view) can't always sit directly after
-  its source event when a reaction must immediately precede its command slice — placing the read
-  later, in narrative order with a longer arrow, is the correct trade-off, not something to force-fix.
-- A `ui` never triggers a reaction — no pattern has a `ui` wired to `processor`/`automation`/
-  `saga`/`translation`, only to `command`. A `ui` left in the reaction's own slice (instead of the
-  read-model or command slice) renders with no outgoing edge, disconnected, and `em validate` now
-  warns on it.
+### Reaction wiring — no positional gotcha
+
+A reaction's command is inferred from **same-slice presence**, exactly like `ui -> command`: put
+`processor`/`translation` in the same slice as the command it triggers, in either order, and `em`
+wires it correctly regardless of what any other slice contains or where it sits in the file. There's
+no adjacency to get right and no reordering hazard — the read model it watches (if any) is named
+explicitly via `from "View"`, resolved by name to the nearest instance at or before its own slice,
+not by position either.
+
+The one thing that still doesn't wire on its own: a `ui` never triggers a reaction — no pattern has
+a `ui` wired to `processor`/`automation`/`saga`/`translation`, only to `command`. A `ui` left in a
+reaction's slice renders with no outgoing edge, disconnected, and `em validate` warns on it — move
+it to the slice that displays the read model, or drop it.
 
 ---
 
@@ -334,22 +383,31 @@ slice "Read Quote — created" {
    (`type Node { child: Node }`, or the same shape across several types). Break the cycle, or
    route the self/mutual reference through an array (`children: Node[]`) if the data is
    genuinely tree-shaped.
+9. **Lineage-ref errors** (slice-doc frontmatter, fs-aware) — a
+   `split-from`/`merged-from`/`superseded-by` ref with malformed `<slice-key>@v<N>` grammar, a
+   self-reference or cycle, a `superseded-by` naming a slice absent from the current model, or
+   a ref naming a version higher than the target's own `version:`. A `split-from`/`merged-from`
+   naming a key absent from the tree is deliberately silent — that's the normal state after a
+   real split/merge (see the four `lineage-*` codes in the table below).
 
 **Warnings (should fix):**
-1. **Automation/translation shares slice with its command** — both `automation`/`processor` and
-   `translation` are reactions; put the triggered command in the *next* slice.
-2. **`ui` shares slice with a reaction, no command** — a `ui` only ever wires to a `command`; no
+1. **Reaction with no command** — a `processor`/`automation`/`saga`/`translation` that triggers
+   nothing. It never records an event itself; add the command it issues in this same slice, or an
+   explicit `arrow` to one elsewhere.
+2. **`ui` shares slice with a reaction** — a `ui` only ever wires to a `command` a person issues; no
    pattern has a `ui` triggering an automation/processor/saga/translation. Left in the reaction's
-   own slice it renders disconnected, with no edge. Move it to the read-model slice, or to the
-   slice with the command this eventually triggers.
-3. **Command with no trigger** — nothing issues it. A command needs a `ui` in its slice, or a
-   reaction (automation/processor/saga/translation) in the slice *before* it. The input-side mirror
-   of (5): a command nothing points at is a write nobody can start.
+   own slice it renders disconnected, with no edge, whether or not that slice also has the
+   reaction's own command. Move it to the slice that displays the read model, or drop it.
+3. **Command with no trigger** — nothing issues it. A command needs a `ui` in its slice, or the
+   reaction (automation/processor/saga/translation) that triggers it, *also* in this slice. The
+   input-side mirror of (5): a command nothing points at is a write nobody can start.
 4. **Command without event** — every command should record at least one event.
 5. **Event nobody reads** — the mirror of (4): recording an event no read model projects is a
    write with no reader. Follow every write slice with the read slice that consumes its event.
-   Counts as read when a `view` names it in `from` (any `again` instance will do), when a
-   fieldless-`from` view sits in its slice, or via an explicit `event -> view` arrow.
+   Counts as read when a `view` names it in `from` (any `again` instance will do), when a view
+   with no `from` of its own sits in its slice, or via an explicit `event -> view` arrow.
+   (Events marked `public` are exempt — their reader is outside the model; same for a
+   `public` view and the no-consumer warning.)
 6. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
 7. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
    (A duplicate `type` name always warns, unlike a duplicate element name — there's no
@@ -364,16 +422,78 @@ slice "Read Quote — created" {
     command in the same slice. Only checked once BOTH the event and at least one same-slice
     command declare `{ fields }`. This is the payoff of the fields feature for slicing rigor:
     once fields are written down, `em validate` checks that data flows forward consistently.
+11. **Event with no producing command** — a fact with no traceable cause; add the command that
+    records it (either order within the slice), or an explicit `arrow` from one.
+12. **Two same-named `translation`s reading different producers** — rename one; fires
+    unconditionally (unlike the duplicate-name warning), since the confusion is in reading
+    the model, not resolving a reference.
+13. **Frontmatter coherence** (slice docs, fs-aware) — `status: implemented` with no
+    `implementedIn` link at all. The re-ratification mismatch (status flipped back while
+    `implementedIn` names the prior PR) is deliberately never flagged — it's the drift
+    signal, not incoherence.
+14. **Doc-join problems** (`em export`/`--slice-ready`) — `binding-missing-file` (a
+    `note "slices/<key>.md"` binding pointing at a file that doesn't exist) and
+    `frontmatter-invalid` (the doc exists but lacks a frontmatter block or a required key).
 
 `divergence "text"` is deliberately NOT in this list — it raises no warning at all, since it
 records a deviation already reasoned through and accepted, not something to fix. Use
 `em validate --list-divergences` to audit them on demand.
 
+### Full rule code reference
+
+Every rule above (and every fs-aware check `em validate` layers on top — lineage, frontmatter
+coherence) has a stable `code`, generated below from the same registry `em` itself validates
+against (`src/model/rules.ts`) — a new rule shows up here the moment it's registered, whether or
+not the prose above has caught up yet. `--slice-ready <key>`-only codes are excluded; see
+`docs/cli.md#em-validate-file` in the
+[em repository](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-validate-file).
+
+<!-- GENERATED:validate-rules:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
+| Code | Severity | Title | Fix |
+|---|---|---|---|
+| `arrow-backward` | error | Backward arrow | Restructure so the target comes later. |
+| `arrow-unresolved-source` | error | Arrow source unresolved | Fix the arrow's source name. |
+| `arrow-unresolved-target` | error | Arrow target unresolved | Fix the arrow's target name. |
+| `binding-missing-file` | warning | Doc binding points at a missing file | Create the slice doc, or fix the `note` path. |
+| `both-ends-of-a-flow/command-no-event` | warning | Command without event | Add the event this command records. |
+| `both-ends-of-a-flow/command-untriggered` | warning | Command with no trigger | Add a `ui` or the reaction that issues it, both in this slice. |
+| `both-ends-of-a-flow/event-unproduced` | warning | Event with no producing command | Add the command that records it, or an explicit arrow from one. |
+| `both-ends-of-a-flow/event-unread` | warning | Event nobody reads | Project it into a view, or reconsider recording it. |
+| `both-ends-of-a-flow/reaction-no-command` | warning | Reaction with no command | Add the command it triggers, in this slice, or an explicit arrow to one. |
+| `both-ends-of-a-flow/ui-unbacked` | warning | `ui` with no read model or command | Add a `view` it displays, or the command it triggers. |
+| `both-ends-of-a-flow/view-unconsumed` | warning | Read model with no consumer | Add a `ui` or reaction that consumes it, or drop this instance. |
+| `connection-legality/illegal-pair` | error | Illegal connection | Only ui→command→event→view→ui and view→reaction→command are legal — the message names the missing step. |
+| `duplicate-element-ref` | warning | Duplicate element ref | Rename the element so its export ref is unique. |
+| `duplicate-name` | warning | Duplicate name | Rename one of the duplicates. |
+| `duplicate-slice-name` | warning | Duplicate slice name | Rename the slice so its export key is unique. |
+| `duplicate-type-name` | warning | Duplicate type name | Rename one of the duplicate `type` declarations. |
+| `duplicate-type-ref` | warning | Duplicate type ref | Rename the type so its export ref is unique. |
+| `fields-completeness/event-field-no-source` | warning | Event field not from a command | Add the field to a command in the slice, or remove it from the event. |
+| `fields-completeness/view-field-no-source` | warning | View field with no source | Add the field to a source event, or remove it from the view. |
+| `frontmatter-coherence-implemented-without-link` | warning | Implemented without a link | Add `implementedIn` once the slice ships. |
+| `frontmatter-invalid` | warning | Invalid or missing frontmatter | Add the required frontmatter keys, or add a frontmatter block. |
+| `grid-collision` | error | Band collision | Split the colliding elements into separate slices. |
+| `lineage-forward-dangling` | error | Dangling forward lineage ref | Fix the key, or remove the stale successor. |
+| `lineage-ref-cycle` | error | Lineage cycle | Break the cycle — a slice can't be its own ancestor. |
+| `lineage-ref-malformed` | error | Malformed lineage ref | Fix the value to `<slice-key>@v<N>`, or remove it. |
+| `lineage-version-impossible` | error | Impossible lineage version | Fix the referenced version, or ratify the target slice first. |
+| `open-issue` | warning | Open issue | Resolve the question, then remove the `issue` clause. |
+| `reaction-from-future-view` | error | Backward timeline (reaction reads a future view) | Declare the view in or before the reaction's slice. |
+| `reaction-from-unresolved` | error | Unknown read-model source | Project the event into a view first, or fix the `from` reference. |
+| `translation-name-collision` | warning | Translation name reused for different producers | Use a distinct name per producer to avoid confusion. |
+| `type-cycle` | error | Cyclic type reference | Break the cycle, or route the self/mutual reference through an array. |
+| `ui-shares-slice-with-automation` | warning | `ui` shares slice with a reaction | Move the `ui` to the slice that displays the read model, or drop it. |
+| `view-again-without-earlier` | error | `again` without an earlier declaration | Declare the view plainly the first time it appears. |
+| `view-from-future-event` | error | Backward timeline (view reads a future event) | Move the source to a later `view X again` instance. |
+| `view-from-unresolved` | error | Unknown event source | Fix the `from` reference to name an existing event. |
+| `view-no-source` | warning | Read model without source | Add `from "Event"`, or place the view in a slice with an event. |
+<!-- GENERATED:validate-rules:end -->
+
 **Design rules that keep models valid:**
 - One element per band per slice (multiple personas/contexts are fine — they're different rows).
 - Every `command` slice includes its `event`. Every `view` has a `from` source.
-- **Every `command` has a trigger.** A `ui` in its slice, or a reaction in the slice *before* it.
-  A command nothing points at is a write nobody can start.
+- **Every `command` has a trigger.** A `ui` in its slice, or the reaction that triggers it, also in
+  its slice. A command nothing points at is a write nobody can start.
 - **Every `event` has a reader.** A command slice isn't finished until the read slice that projects
   its event exists. Reactions don't count — they read views, not events. Pair each write slice with
   its read slice as you go rather than sweeping up dangling events at the end.
@@ -386,16 +506,17 @@ records a deviation already reasoned through and accepted, not something to fix.
   `command → view` (the CQRS violation: an event has to sit between them) and `view → command`
   (a reaction has to sit between them). If you reach for an arrow the patterns don't allow, the
   model is missing an element, not an arrow.
-- Automations **and translations** are always two slices: the reaction (plus its read model, if
-  internally triggered) in one slice, the triggered `command` + its `event` in the next. A
-  translation/automation slice **never contains an `event`** — reactions trigger commands, not
-  events. Externally-triggered reactions start from outside the model (no `from`);
-  internally-triggered ones read a **view** (read model) — `from "X"` must resolve to a view.
+- A reaction (`processor`/`automation`/`saga`/`translation`) shares its slice with the `command` it
+  triggers and that command's `event` — the same shape `ui` already uses in State Change. If it's
+  internally triggered, the **view** (read model) it watches lives in the slice before, named via
+  `from "X"` (which must resolve to a view, never an event directly). Externally-triggered reactions
+  start from outside the model — no `from` at all, and no slice before them.
 - Name everything uniquely and consistently.
 - Events are past tense; commands are imperative; views name the thing shown.
 
-> ⚠️ **Validator blind spot:** `em validate` does **not** flag a translation/automation that emits
-> an event directly (e.g. `translation T` and `event E` in the same slice with no command). It only
-> warns when a reaction shares a slice with a *command*. So enforce the two-slice
-> `reaction → command → event` split **by construction** — never rely on `em validate` to catch a
-> reaction wired straight to an event.
+A reaction that emits an event with no command anywhere between them — `translation T` and
+`event E` in the same slice, nothing issuing it — is exactly what
+`both-ends-of-a-flow/reaction-no-command` (above) catches: any reaction with no `command` in its
+own slice, and no explicit arrow to one, warns. Still route every reaction through a real command
+by construction (`reaction → command → event`) rather than an explicit `arrow "Reaction" -> "Event"`
+— that shape is its own `connection-legality` error (a reaction never records an event itself).

package/.claude/skills/event-modeling/reference/extract.md

@@ -3,8 +3,8 @@
 Read this **before doing any extract work**. It governs the `extract` phase and **overrides
 `methodology.md` step 1's stance** for the duration of extraction: you are capturing how the
 system behaves **today**, not modeling what the business needs. Everything else in the
-methodology — the 4 patterns, the "is it an event?" test, the Socratic stance, the two-slice
-reaction split — still applies.
+methodology — the 4 patterns, the "is it an event?" test, the Socratic stance, the
+reaction-shares-a-slice-with-its-command shape — still applies.
 
 ## Stance override — current-state-only
 
@@ -81,7 +81,7 @@ it is fine to finish a round with `# TBD`s still parked.
   `em render` here.**
 - **R3 — Commands / inputs.** For each event, the request that actually produces it today
   (imperative name), *and what triggers it* — the real screen, or the scheduler/listener that
-  fires it (model that as a reaction in the preceding slice, per R5). Unclear trigger → `# TBD`,
+  fires it (model that as a reaction sharing this same slice, per R5). Unclear trigger → `# TBD`,
   not a plausible guess; expect a *command has nothing that triggers it* warning until R5 fills
   it in, and don't invent a screen to silence it.
 - **R4 — Read models / outputs.** The projections/queries the system actually serves; wire
@@ -91,16 +91,18 @@ it is fine to finish a round with `# TBD`s still parked.
   a **finding about the system**, not a modelling mistake — never invent a reader to silence it
   (that would be desired state). Park it in the Decisions log and carry the warning.
 - **R5 — Boundaries & reactions.** Current automations and integrations as-is: schedulers,
-  listeners, outbound syncs, inbound webhooks. Model each as a reaction with the two-slice
-  `reaction → command → event` split and the slice-ordering rules in `em-dsl.md` — even when
-  the current code wires it as one procedural step (note the as-built shape in the slice's
-  `# TBD`/Decisions if it differs).
+  listeners, outbound syncs, inbound webhooks. Model each as a reaction sharing its slice with
+  the `command` + `event` it triggers (`reaction → command → event`, per `em-dsl.md`) — the
+  read model it watches, if any, lives in the slice before, named via the reaction's own
+  `from`. This matches how the current code usually already reads (scheduler/listener → one
+  procedural step); note any real as-built difference in the slice's `# TBD`/Decisions.
 - **R6 — Gap & TBD reconciliation.** Walk every parked `# TBD` with the user. Resolve only
   what they can confirm **as a current-state fact**; everything else stays parked. Explicitly
   refuse to resolve a TBD by inventing desired behavior.
-- **R7 — Convergence.** Final `em render` + `em validate` (fix errors and warnings; remember
-  the validator's blind spot — check the reaction split by hand). User confirms the model is a
-  faithful picture of today. Mark extraction complete in the state file and hand off.
+- **R7 — Convergence.** Final `em render` + `em validate` (fix errors and warnings — this now
+  catches a reaction wired straight to an event too, via *reaction triggers no command*). User
+  confirms the model is a faithful picture of today. Mark extraction complete in the state file
+  and hand off.
 
 Seven rounds is the default shape, not a quota — collapse rounds for a small system, repeat
 one for a sprawling one. Record any deviation in the Decisions log.
@@ -124,7 +126,8 @@ accepted case, and each one is worth naming explicitly as a finding); every unkn
 `# TBD`; and the user has confirmed the model reflects today's behavior. Then:
 
 1. State file: set phase progress (extraction rounds checked), log the completion decision.
-   Seed `README.md`'s **slice index** (every slice, pattern, status `none`).
+   Seed `README.md`'s **slice index** (every slice, pattern, status "no doc yet" — no slice
+   docs exist until the `slice` phase writes them).
 2. The extracted model **replaces `discover`** — suggest `/event-modeling model` next
    (steps 5-7: swimlanes, patterns, completeness). Desired-state changes belong *after* the
    as-is model is agreed — as normal `model`/`slice` evolution, clearly separated from