@milehimikey/em 1.4.0 → 1.6.0

package/.claude/skills/event-modeling/SKILL.md

@@ -42,19 +42,46 @@ validation rules) before doing real work — they are the source of truth. Templ
   and show the user what changed. Encourage running the live view (`watch`) so a team can follow.
 - **Keep the `.em` structural; put depth in `note` docs.** The diagram holds flow; invariants,
   fields, and scenarios live in `slices/*.md` linked via `note "slices/<name>.md"`.
-- **No UI in headless/API models.** If the system is headless (clients call an API, not screens),
-  use no `ui`/`persona`: writes are `external translation → command → event` (name the inbound
-  adapter for the caller/role); reads are `read model → read translation` (an API query that
-  triggers **no** command — the analog of `view → ui`). **Repeat read models** across slices so the
-  timeline flows left-to-right — put each repeat **right after the event that feeds it**, sourcing
+- **Headless/API models still use `ui`.** If the system is headless (clients call an API, not
+  screens), declare a persona per external caller/role (e.g. `IntegratorAPI`) and treat its `ui`
+  boxes as API calls, not screens: writes are `ui → command → event` and reads are
+  `read model → ui`, exactly like any other State Change/State View slice — no separate trigger
+  slice. `translation` stays reserved for genuine reactions and real external-system boundaries,
+  not a synchronous request/response call. Internal-only commands/views with no public route carry
+  no `ui` at all — they follow the ordinary Automation pattern instead. **Repeat read models**
+  across slices so the timeline flows left-to-right — put each repeat **right after the event that feeds it**, sourcing
   only that one adjacent event, so every arrow is short (a read model far from its source events
-  draws long arrows that look like a forbidden read→read link). Repeats render cleanly — em only
-  warns on a duplicate name that's *referenced* by `from`/`arrow`. Slice order matters: a reaction
-  must be directly followed by its command slice, and a read slice must not be immediately
+  draws a long arrow whose head lands columns away, making the *write* slice read as dangling —
+  keep a sub-flow that detours into another context together, not parked at the end of the model).
+  Declare every instance after the first with
+  **`view X again from "..."`** — `again` instances are exempt from the duplicate-name warning even
+  when referenced, and each reference resolves to the right instance. Slice order matters: a
+  reaction must be directly followed by its command slice, and a read slice must not be immediately
   followed by a command slice (see `em-dsl.md`).
   See `reference/methodology.md` (State View) and `reference/em-dsl.md`.
+- **Never connect two instances of one read model.** The repeat is a timeline device, not a flow:
+  continuity is implied by the shared name, and the events arriving at each instance are what show
+  it changing. An arrow between instances says the read model feeds itself, and is an error.
+- **Every slice is a COMPLETE pattern, never a half-slice.** A State Change is
+  `ui → command → event`; a State View is `event → read model → ui` (or `→ reaction`). So: a
+  command needs something that **triggers** it (the `ui` it's issued from, or the reaction in the
+  slice before it), its event needs a **reader**, and that read model needs a **consumer** of its
+  own. A command nothing points at is a write nobody can start; an event nothing projects is a
+  write nobody can see; a read model nothing displays is information dropped on the floor. Write
+  the whole chain together rather than sweeping up dangling ends later. Reactions don't count as
+  readers of *events* — they read views. **Every instance** of a repeated read model needs its own
+  consumer: if you repeat a view next to an event just to keep the arrow short, bring its screen
+  along, or don't add the instance.
+- **Only six connections are legal:** `ui → command`, `command → event`, `event → read model`,
+  `read model → ui`, `read model → reaction`, `reaction → command`. Reaching for anything else —
+  above all `command → read model` (the CQRS violation) or `read model → command` — means the model
+  is missing an **element**, not an arrow.
 - **Validate continuously.** Run `em validate` and fix errors/warnings as you go (see DSL ref).
-- **Save state at the end of every session** so work resumes cleanly.
+- **Save state at the end of every session** so work resumes cleanly. Also append one line to
+  the Usage log: the phase(s) touched and the `em validate` diagnostic *categories* that fired
+  (rule name only, e.g. "read model nothing consumes" — never the full message or domain
+  content). This is the team's only usage signal today (`docs/usage-data.md`) — keep it cheap
+  and habitual, not a task to skip.
 
 ## Preconditions (run first)
 
@@ -113,16 +140,24 @@ phase applies to field tables, below.
    they aren't re-proposed later. Capture the survivors as a flat list.
 2. **Plot / storyboard (step 2).** Order the events into the narrative. Identify **personas**
    (actors) and the **UI** screens at each step. Add `persona` declarations and `ui` elements.
-   In a **headless/API** model there are no personas or screens — identify the external
-   **callers** at each step instead; they become the inbound write translations and read
-   translations (see `reference/methodology.md`).
+   In a **headless/API** model there are no human personas or screens — identify the external
+   **callers** at each step instead; declare one persona per caller/role, and its `ui` boxes are
+   the API calls (see `reference/methodology.md`).
 3. **Inputs (step 3).** For each event, find the **command** that causes it (imperative name).
-   Form `command → event` slices (State Change pattern).
+   Form `command → event` slices (State Change pattern). Every command needs a **trigger** in the
+   same breath: the screen the user issues it from (a `ui` in the slice), or — for the Automation
+   and Translation patterns — the reaction in the slice before it. A command nothing points at is
+   a write nobody can start. *"Who does this, and where are they when they do it?"*
 4. **Outputs (step 4).** Identify the **read models / views** consumers need and wire them with
-   `from "Event"` (State View pattern). In a **headless/API** model there is no UI — a read model is
-   consumed by an **external read translation** (the API query, triggers no command), and read
-   models are **repeated** in each slice where they're read so the timeline flows (see
-   `reference/methodology.md`).
+   `from "Event"` (State View pattern), each with the screen (or reaction) that consumes it — a
+   read model nothing displays is information dropped on the floor. In a **headless/API** model
+   the consumer is the caller persona's `ui` (the API query) — same as any screen. Read models are
+   **repeated** in each slice where they're read (use `view X again` after the first, each instance
+   with its own consumer) so the timeline flows (see `reference/methodology.md`).
+   **Close the loop before leaving this step:** every event from step 3 must be read by at least one
+   read model. Walk the event list and ask, for each one, *"who looks at this, and what do they do
+   with it?"* An event with no answer is either missing its read model or shouldn't be recorded —
+   both are worth raising with the user rather than leaving dangling.
 
 End of phase: write/refresh the `.em`, render it, update `.event-modeling.md` (steps done,
 decisions, open questions) and `README.md`'s slice index. Tell the user they can stop here and
@@ -164,12 +199,17 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    event).
 2. **Elaborate scenarios — first pass (step 6).** For each slice, capture the happy-path
    Given/When/Then and the obvious invariants as short notes. (The full spec is the `slice` phase.)
-3. **Evaluate completeness (step 7).** Walk the model: every command emits an event, every view
-   has a source, no orphan events, every UI is reachable, automations **and translations** split
-   correctly (each reaction triggers a command — none wired straight to an event). Run
-   `em validate` and resolve all errors and warnings — but check the reaction→command→event split
-   by hand, since `em validate` does **not** flag a translation/automation that emits an event
-   directly (see `reference/em-dsl.md`).
+3. **Evaluate completeness (step 7).** Walk the model: every slice is a **complete** pattern, not a
+   half-slice — **every command has something that triggers it**, every command emits an event,
+   **every event is read by a read model**, **every read model has a consumer**, every view has a
+   source, every UI is reachable, every connection is
+   one of the six legal pairs, and automations **and translations** split correctly (each reaction
+   triggers a command — none wired straight to an event). Run `em validate` and resolve all errors
+   and warnings — but check the reaction→command→event split by hand, since `em validate` does
+   **not** flag a translation/automation that emits an event directly (see `reference/em-dsl.md`).
+   For an unread event, don't just bolt on a view to silence the warning: ask the user who looks at
+   this fact and what they do with it. The honest answers are "here's the read model we missed" or
+   "nobody — so why are we recording it", and both improve the model.
 
 End of phase: render, update state, suggest `/event-modeling slice` to write implementation specs.
 
@@ -181,7 +221,9 @@ timeline). Check `README.md`'s slice index for what's already done.
 This is also where **branch / unhappy-path events** are discovered and added to the model — as a
 slice's alternate/error flows surface (a rejection, removal, cancellation, decline, expiry), add
 the corresponding event/slice to the `.em` and re-render. The happy-path spine from earlier
-phases is the starting point, not the finished event set.
+phases is the starting point, not the finished event set. **Every new event needs its reader too**
+— a rejection or cancellation that nothing projects will warn, and usually the missing piece is
+real (someone has to see that the request was declined).
 
 For each slice:
 1. Hold a Socratic deep-dive to fill every section of `templates/slice.md`: intent, trigger/actor,
@@ -195,12 +237,16 @@ For each slice:
    already defined elsewhere.
 2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name). Record the originating
    need (ticket/conversation link) in the Intent section when one exists.
-3. Wire it into the `.em`: add `note "slices/<slice-name>.md"` to the slice's primary element
+3. Render the slice's own diagram: `em render <model>.em --slice "<slice name>" -o
+   slices/<slice-name>.svg` (kebab-case, matching the doc's filename) — redraws just this slice
+   in its own canonical pattern shape, and add `![Diagram](./<slice-name>.svg)` near the top of
+   the doc, right after the metadata bullet list.
+4. Wire it into the `.em`: add `note "slices/<slice-name>.md"` to the slice's primary element
    (the command for State Change, the view for State View, the processor for Automation, the
    translation for Translation).
-4. Update `README.md`'s slice index — the one canonical slice table (`draft` →
+5. Update `README.md`'s slice index — the one canonical slice table (`draft` →
    `ready-to-implement`, later `implemented` once shipped, with `Implemented in:` filled in).
-5. Re-render and `em validate`.
+6. Re-render and `em validate`.
 
 ## Phase: `conform` — drift check against the codebase
 
@@ -238,11 +284,53 @@ appear the moment you save, with no idle churn between edits.
 `live.html?svg=<model-name>.svg` in a browser. It polls every ~2s and reloads without flicker. No
 editing of `live.html` is needed — the `?svg=` query picks the model.
 
+## Phase: `review` — stakeholder walkthrough
+
+Goal: step a real stakeholder review session through the model slice by slice, one slice
+spotlighted at a time, with any open questions the room raises captured live as `issue "..."`
+red notes.
+
+**Trigger: a real stakeholder review session is on the calendar — a scheduled use, not
+speculation.** Don't propose this phase proactively; it exists for facilitated reviews with
+non-engineer stakeholders in the room, not routine model editing.
+
+Start the same live server as `watch`: `em watch <model-name>.em -o <model-name>.svg --serve`
+(run_in_background). Open the printed URL, click **Review mode** in the header, and share the
+screen. Use Prev/Next (or the left/right arrow keys) to step through slices in declaration
+order — each one pans/zooms into view with everything else dimmed, so the room's attention
+tracks one slice at a time.
+
+**Live capture:** when a stakeholder raises something unresolved, add `issue "..."` to the
+relevant element in the `.em` file and save — exactly the same mechanism as any other issue
+(see `validate` below). The browser updates over the existing SSE push within moments, without
+losing the current slice or resetting review mode.
+
+Wrap-up: run `em validate --list-issues` to sweep everything captured during the session and
+walk each one with the user, same as any open issue. Update the state file's Participants
+section with who attended, and set a `Last stakeholder review:` marker (mirrors `Last
+conformance:`).
+
+End of phase: state file's `Last stakeholder review:` marker updated, every issue captured
+live triaged (resolved on the spot, moved to Open questions / parking lot, or left open on
+purpose). Review doesn't chain to another phase — it's a recurring, scheduled activity like
+`conform`, not a step in the discover → model → slice sequence.
+
 ## Phase: `validate`
 
 Run `em validate <model-name>.em` and walk through each diagnostic with the user, explaining the
-rule (see `reference/em-dsl.md`) and proposing the fix (e.g. split an automation's command into
-the next slice, add a missing `from`, give a command its event). Apply fixes on agreement.
+rule (see `reference/em-dsl.md`) and proposing the fix. Apply fixes on agreement. Common ones:
+
+| Diagnostic | Fix |
+|---|---|
+| automation/translation shares a slice with a command | Split the command into the next slice |
+| **command has nothing that triggers it** | Add the `ui` it's issued from — or, if the system issues it, the reaction in the slice before it. Ask *"who does this, and where are they when they do it?"* |
+| **read model has no consumer** | Add the screen that displays it, or the reaction that watches it. If it's a repeat added only to shorten an arrow and nothing looks at it there, drop the instance |
+| read model has no source | Add the missing `from "Event"` |
+| command produces no event | Give the command its event, or drop the command |
+| **event is not read by any read model** | Add the read slice that projects it — but ask *who looks at this and what do they do with it* first. "Nobody" is a real answer, and then the question is why it's recorded at all |
+| **illegal `arrow` kind pair** | Don't reroute it — the model is missing an element. `command → view` needs the event between them; `view → command` needs a reaction. Between two instances of one read model, just delete the arrow: the repeat needs no connection |
+| `view X again` with no earlier declaration | Declare the view plainly the first time it appears |
+| event feeding an earlier view instance | Add a `view X again` where the event lands and move the source there |
 
 For anything genuinely unresolved rather than a rule violation, prefer `issue "text"` on the
 relevant element over a `# TBD` comment — it shows up as a red marker on the rendered diagram and
@@ -264,9 +352,12 @@ em init <name>.em                          # optional starter scaffold
 em validate <name>.em                      # check rules; exit 0 if clean/warnings only
 em render <name>.em -o <name>.svg          # render (svg/png/pdf by extension)
 em render <name>.em --emit-dot             # inspect generated Graphviz DOT
+em render <name>.em --slice "<slice-name>" -o slices/<slug>.svg   # this slice's own diagram
 em watch <name>.em -o <name>.svg           # re-render on save (run in background)
 em watch <name>.em -o <name>.svg --serve   # + live viewer with instant push-reload (--port N)
+                                            #   click "Review mode" for a slice-by-slice storyboard walkthrough
 ```
 
 Always finish a working session by: re-rendering, running `em validate`, and updating
-`.event-modeling.md` with the current phase/step, decisions, and open questions.
+`.event-modeling.md` with the current phase/step, decisions, open questions, and a Usage log
+entry (phases touched + validate diagnostic categories hit).

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

@@ -102,7 +102,16 @@ For each slice in scope:
      materialized projection in code — a direct event handler with criteria-sourced state is
      the same pattern expressed in the code idiom (extract.md's R5 reaction rules). That is
      NOT structural drift; note the idiom in the evidence log instead of reporting the view
-     as missing.
+     as missing. This is the *general*, idiom-level version of the next bullet — prefer citing
+     an actual `divergence` annotation when the element carries one; fall back to this idiom
+     note only when it doesn't.
+   - **Accepted divergences:** before treating any finding as drift, check whether the
+     relevant canonical element already carries a `divergence "..."` annotation (visible in
+     the `.em`, in `em export --json`'s `divergence` field, or — for a structural finding — as
+     the `acceptedDivergence` field already attached to that `em diff --json` entry, see step
+     3). If it does, this is not a fresh finding to litigate: classify it as **Accepted
+     divergence** (step 4) and cite the annotation text as the evidence. This is the specific,
+     per-element, ratified counterpart to the idiom-level bullet above.
 3. Write what you found into the scratch model (`<model-name>-asis.em`, see below). **Seed the
    scratch model as a copy of the canonical `.em` and replace only the in-scope slices** with
    the as-is picture, leaving out-of-scope slices byte-identical. This is not an optimization:
@@ -112,9 +121,13 @@ For each slice in scope:
    this phase exists to avoid. It also keeps the scratch model compilable (see step 3). Within
    the slices you do rewrite, **reuse the canonical model's slice and element names wherever
    the code genuinely matches them** — the canonical model is the vocabulary anchor. Give a
-   new name only to code behavior the model doesn't cover at all. Record the mapping decision
-   for every element you name this way (e.g. `CartItemAdded` code class ↔ `"Cart Item Added"`
-   model event) so it's auditable, not a silent judgment call. **Match the canonical model's field granularity:** declare `{ fields }`
+   new name only to code behavior the model doesn't cover at all. When you do need a new name,
+   check `em glossary` across sibling `.em` models first (same aid the `extract` phase uses) —
+   if the term already exists elsewhere under a different kind or spelling, that's a signal to
+   reuse the established name rather than mint another synonym for the same concept. Record the
+   mapping decision for every element you name this way (e.g. `CartItemAdded` code class ↔
+   `"Cart Item Added"` model event) so it's auditable, not a silent judgment call. **Match the
+   canonical model's field granularity:** declare `{ fields }`
    in the scratch model only where the canonical model declares them (if the canonical model
    puts fields on commands but not events, so does the scratch model — writing code-derived
    event fields there would flood the diff with `field-added` noise). Schema claims at finer
@@ -135,7 +148,9 @@ what every finding in the report will cite — file paths, not vibes.
 First `em validate <model-name>-asis.em`. `em diff` refuses when either side has validation
 *errors* (warnings are fine), so a scratch model that doesn't compile stops the run cold. The
 usual cause is a slice that depends on one you rewrote incompletely — a `view X again` whose
-first declaration you dropped, or an automation `from` a read model that no longer exists.
+first declaration you dropped, an automation `from` a read model that no longer exists, or an
+`arrow` you wrote joining kinds the patterns don't connect. (An unread event is only a *warning*,
+so it never blocks the diff — and in an as-is scratch model it's expected.)
 Seeding from the canonical model (step 2) prevents this; if it still fails, **fix the scratch
 model and report the failure as a tooling problem in the run metadata — never as drift.** A
 model you couldn't compile is an uncertainty about your own scratch file, not a finding
@@ -145,7 +160,10 @@ Then run `em diff <model-name>.em <model-name>-asis.em --json`. `em`, not you, d
 structurally differs — don't re-derive by eye what the tool already computed. Parse the JSON
 (`docs/cli.md`'s diff section documents the envelope: `diffSchemaVersion`, `counts`, `changes`,
 `removals`, every optional `ChangeEntry` field explicit-`null` when unused) and use it as the
-structural-surface findings directly.
+structural-surface findings directly. Check each entry's `acceptedDivergence` field first: a
+non-null value means `em` itself already found a `divergence` annotation on the canonical
+element behind this entry — that finding is Accepted divergence (step 4), not something to
+re-litigate.
 
 ### 4. Classify
 
@@ -155,6 +173,11 @@ step 2 — sorts into exactly one class:
 - **Real drift** — code evidence contradicts the model or doc.
 - **Model gap** — code evidence shows behavior neither the model nor the doc covers.
 - **Internal inconsistency** — the doc and the `.em` disagree with each other (surface 3 only).
+- **Accepted divergence** — the relevant canonical element carries a `divergence "..."`
+  annotation (cited directly from a structural entry's `acceptedDivergence` field, or from the
+  `.em`/`em export` for a spec/internal finding). This is what the annotation is *for*: a
+  reasoned, ratified deviation stops being re-reported as drift on every run. Cite the
+  annotation text, not fresh judgment — that judgment already happened when it was written.
 - **Extraction uncertainty** — no evidence either way. Never reported as drift or a gap.
 
 Every classification must cite the evidence recorded in step 2 (or the `em diff` entry, for
@@ -167,7 +190,9 @@ Write `conformance/<YYYY-MM-DD>-report.md` in the model directory, from
 ready-to-apply red note — `issue "conformance: <text>"` on the right element, written out in
 the report exactly as it should be pasted into the `.em` — when a model-side marker is the
 right fix; when the fix is purely doc wording (or the finding is an internal inconsistency
-with no clear side to flag), omit the red note and say why instead. **You never edit the
+with no clear side to flag), omit the red note and say why instead. **Never propose a red note
+for a finding already classified Accepted divergence** — report it (so the annotation itself
+stays auditable) but don't ask the user to ratify what's already ratified. **You never edit the
 canonical model or a slice doc unprompted** — walk the report with the user, apply only the
 proposals they approve, then re-render and `em validate`.
 
@@ -226,3 +251,7 @@ whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
 - **Re-deriving what `em diff` already decided** — once you have the JSON, use it; don't
   eyeball the two `.em` files yourself looking for structural differences the tool already
   computed for you.
+- **Re-litigating an accepted divergence** — a non-null `acceptedDivergence` on a diff entry
+  (or a `divergence` annotation on the element behind a spec/internal finding) means this exact
+  question was already reasoned through and ratified. Classify it as Accepted divergence and
+  cite the annotation; don't propose a new red note or re-open the judgment call from scratch.