@milehimikey/em 1.3.0 → 1.5.0

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

@@ -5,11 +5,13 @@ description: >-
   the 7 steps of Event Modeling and the 4 patterns (State Change, State View, Automation,
   Translation), and produce implementation-ready slice design documents. Use when the user wants
   to event-model a business process or system, do event modeling / event storming, design slices,
-  build or edit an `.em` model, run the em tool, or extract / reverse-engineer a current-state
-  event model from an existing system or codebase (event-driven or legacy/procedural). Works in
-  resumable phases via an argument: `discover` (steps 1-4, greenfield), `extract` (current-state
-  model of an existing system), `model` (steps 5-7), `slice` (deep slice specs), plus `watch` and
-  `validate`. With no argument it resumes from the saved state file.
+  build or edit an `.em` model, run the em tool, extract / reverse-engineer a current-state
+  event model from an existing system or codebase (event-driven or legacy/procedural), or check
+  a ratified model for drift against the codebase that implements it. Works in resumable phases
+  via an argument: `discover` (steps 1-4, greenfield), `extract` (current-state model of an
+  existing system), `model` (steps 5-7), `slice` (deep slice specs), `conform` (drift check
+  against the codebase), plus `watch` and `validate`. With no argument it resumes from the saved
+  state file.
 ---
 
 # Event Modeling with `em`
@@ -46,11 +48,31 @@ validation rules) before doing real work — they are the source of truth. Templ
   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
   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.
 
@@ -78,13 +100,19 @@ validation rules) before doing real work — they are the source of truth. Templ
   README.md                # overview + slice index (from templates/model-readme.md)
   .event-modeling.md       # resumable state (from templates/state.md)
   slices/<slice-name>.md   # one rich slice doc per slice (from templates/slice.md)
+  conformance/<date>-report.md
+                           # conform-phase reports (from templates/conformance-report.md)
+  <model-name>-asis.em     # conform-phase scratch model, regenerated per run — git-ignore this
 ```
 
 When creating a new model, scaffold the directory and copy the templates in (filling the
 placeholders). Copy `live.html` **verbatim** — it takes the SVG name from its URL query
 (`live.html?svg=<model-name>.svg`), so there's nothing to edit. You may use `em init` for a
 starter `.em`, but usually you'll build it up from the discovery conversation instead. Fill
-template placeholders — never leave `{{...}}` in delivered files.
+template placeholders — never leave `{{...}}` in delivered files. The `conformance/` directory
+and `<model-name>-asis.em` only appear once the `conform` phase runs; add the pattern `*-asis.em`
+to the repository's `.gitignore` the first time one is created (see `reference/conform.md`) —
+it's scratch, never committed.
 
 ---
 
@@ -109,12 +137,20 @@ phase applies to field tables, below.
    **callers** at each step instead; they become the inbound write translations and read
    translations (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
+   `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 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`).
+   models are **repeated** in each slice where they're read (use `view X again` after the first) 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
@@ -156,12 +192,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.
 
@@ -173,7 +214,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,
@@ -194,6 +237,29 @@ For each slice:
    `ready-to-implement`, later `implemented` once shipped, with `Implemented in:` filled in).
 5. Re-render and `em validate`.
 
+## Phase: `conform` — drift check against the codebase
+
+Goal: check a **ratified** model (and its slice docs) against the codebase that implements it,
+and report where they've drifted — advisory only, never a gate, never an unprompted edit.
+
+**Read `reference/conform.md` before doing any conform work** — it carries the full flow
+(scope, evidence-first verification, `em diff --json`, classification, report) and the
+stance guardrails (evidence-first, uncertainty is never drift, propose-don't-edit). It reuses
+`extract`'s sourcing/mode rules for reading the target codebase rather than duplicating them.
+
+In short: for each in-scope slice, gather code evidence *before* comparing to the model or doc;
+write the as-is picture into a scratch model (`<model-name>-asis.em`, reusing the canonical
+model's names wherever the code matches them); run `em diff <model-name>.em
+<model-name>-asis.em --json` and let `em` decide the structural deltas; classify every finding
+(real drift / model gap / internal inconsistency / uncertainty) with cited evidence; write
+`conformance/<date>-report.md` with proposed `issue "conformance: …"` red notes; apply only the
+proposals the user ratifies, then re-render and validate; update the state file's
+`Last conformance:` marker.
+
+End of phase: state file's `Last conformance:` marker updated, Decisions log entry if any
+proposals were applied. Conform doesn't chain to another phase — it's a recurring loop, run
+again whenever the codebase has moved.
+
 ## Phase: `watch` — live team view
 
 **Recommended (instant push, no polling):** start the watcher with `--serve` in the background:
@@ -210,8 +276,19 @@ editing of `live.html` is needed — the `?svg=` query picks the model.
 ## 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

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

@@ -0,0 +1,230 @@
+# Conform Phase — Drift Detection Against the Codebase
+
+Read this **before doing any conform work**. It governs the `conform` phase: checking a
+**ratified** model (and its slice docs) against the codebase that is supposed to implement it,
+and reporting where they've drifted apart. Conform reuses `extract`'s sourcing/mode rules
+(`reference/extract.md`) for reading the target codebase rather than duplicating them — the
+difference is what you do with what you find: extract *builds* a model from the code; conform
+*compares* code evidence against a model that already exists.
+
+## Stance — advisory-only, evidence-first
+
+- **Advisory-only.** Conform never gates anything and never edits the canonical model or a
+  slice doc on its own initiative. It proposes; the user ratifies. There is no such thing as
+  an auto-applied conformance fix.
+- **Evidence-first, not model-first.** For every slice you check, gather code evidence —
+  handler/event/projection/endpoint sites, invariant-enforcement sites, scenario-test sites —
+  **before** you compare anything to the model or doc. Read the doc and model first to know
+  *what to look for*, but write down what the code actually shows before you judge whether it
+  matches. Anchoring bias is the failure mode this rule exists to block: "the model says X" is
+  never allowed to substitute for "the code shows X at `path/to/File.kt:42`".
+- **Uncertainty is never drift.** If you can't find evidence either way — the code path is
+  unclear, the test is ambiguous, you ran out of budget — that's an **uncertainty**, reported
+  in its own section, never folded into a drift or gap finding. A false positive here is worse
+  than a missed one; it's what burns the loop's credibility.
+- **Anchored, not blind.** You read the canonical model's vocabulary before walking the code,
+  and you reuse its slice/element names wherever the code genuinely matches them. This trades
+  some independence for precision: naming a scratch model's elements from scratch (blind
+  extraction) would report wholesale slice add/remove noise from naming alone the moment your
+  synonym for an existing element doesn't match the model's — the exact false-drift failure
+  mode this phase exists to avoid. The guardrail against anchoring bias is the evidence-first
+  rule above, not independence from the model's vocabulary.
+
+## Preconditions
+
+1. A canonical `.em` model with a state file (`.event-modeling.md`), reachable the same way the
+   SKILL.md preconditions locate it.
+2. The model should be ratified for the slices you're about to check — `slice` docs at
+   `implemented` (or the status the user says corresponds to shipped code) for whichever slices
+   are in scope. Checking a `draft` or `ready-to-implement` slice against code is a wasted walk;
+   tell the user and skip it rather than reporting "drift" against a doc nobody built to yet.
+3. The codebase to check: the state file's **Existing system refs** (populated during
+   `extract`, if this model came from one) or ask the user for the repo path if not set. Record
+   it if missing. In a headless/scheduled run with no user to ask, default to the repository
+   the model lives in (if it contains the implementation) and state that assumption in the
+   report's run metadata.
+4. Confirm `em --version` works (same check as every other phase) — you'll run `em diff`. The
+   phase needs `em diff --json`; if the flag errors as unknown, the installed `em` predates it
+   — say so and stop rather than falling back to eyeballing the two models.
+
+## The three conformance surfaces
+
+The model isn't just the `.em` — slice docs carry the detailed spec (field tables with rules,
+named invariants, Given/When/Then scenarios). Conform checks all three surfaces that can drift:
+
+| Surface | What drifts | Who checks | How |
+|---|---|---|---|
+| **Structural** — `.em` ↔ code | slices/elements/fields/flow | `em` (deterministic) | `em diff --json` on canonical vs. an as-is scratch model |
+| **Spec** — slice doc ↔ code | field rules not enforced, named invariants (`INV-*`) without enforcement/test sites, GWT scenarios without test sites | you (judgment) | per-slice evidence walk: each checkable claim in the doc mapped to a code/test site by name (`INV-CHK-4` → its enforcement site + its test) |
+| **Internal** — slice doc ↔ `.em` | the doc's header metadata (Pattern, Status) or its Command/Event/Read Model sections and field tables disagreeing with the model's own elements/fields | you (judgment, v1) | cross-check the doc's structured sections against the slice's model elements |
+
+The internal surface is deterministically checkable in principle (structured doc sections +
+`{ fields }` blocks) — promoting it to an `em validate` rule is a natural follow-up; file it as
+its own issue rather than growing this phase's scope. For now it's agent judgment, same as spec.
+
+**Internal inconsistency is its own class, not drift.** When a doc and the `.em` disagree with
+each other, neither one is "the code" — you don't know which is stale. Report it as internal
+inconsistency and let the user decide which side is right; don't guess by treating one as
+authoritative.
+
+## Flow
+
+### 1. Scope
+
+Default: **diff-scoped.** Read the state file's `Last conformance:` marker (date + target-repo
+revision). If it's set, run `git diff --name-only <recorded-revision>..HEAD` from the target
+repo's root to list the changed paths (`git log` alone prints commit subjects, not paths), then
+map those paths to slices (via each slice doc's known code locations, `Implemented in:` links,
+or a quick Grep if those are stale) — that's your in-scope set. If the marker reads `never`
+(first run) or the user passes `--full`, scope is every `implemented` slice.
+
+Cost containment here is cadence, not a trigger condition — diff-scoped-by-default is what
+keeps a recurring conform run cheap; don't invent a smarter trigger.
+
+### 2. Anchored, evidence-first verification (per in-scope slice)
+
+For each slice in scope:
+
+1. Read the slice's **doc** (`slices/<slice-name>.md`) alongside its elements in the `.em`.
+   This tells you the vocabulary to anchor on and the claims to check — not the answer.
+2. Walk the code and **record evidence before comparing**:
+   - **Structural:** the handler, event class(es), projection(s), endpoint(s) that implement
+     this slice.
+   - **Spec:** for every named invariant (`INV-*`) in the doc, its enforcement site and its
+     test site (by name/path, both or neither — a half-found invariant is an uncertainty, not
+     a pass). Scenarios are budgeted: map Given/When/Then scenarios to individual test sites
+     when the in-scope slice count is small (roughly ≤5) or the user asks for that depth;
+     otherwise record slice-level scenario-test presence and say so in the report — per-scenario
+     mapping across a full model roughly doubles the walk. Where the doc doesn't name
+     invariants/scenarios individually, fall back to slice-level test presence (some vs. none)
+     rather than inventing IDs the doc never gave you.
+   - **Legitimate non-materialized views:** an automation's watched view may have no
+     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.
+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:
+   `em diff` matches slices by name, so a scratch model containing *only* the in-scope slices
+   reports every other canonical slice as `slice-removed` plus one `element-removed` per
+   element — a phantom-removal flood on every diff-scoped run, which is the exact false drift
+   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 }`
+   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
+   granularity than the `.em` declares — e.g. event fields documented only in a slice doc's
+   table — are checked on the **spec surface** against the doc, not smuggled into the
+   structural diff.
+4. Cross-check the doc's header metadata and Command/Event/Read Model sections against the
+   slice's actual `.em` elements and fields for the internal surface — this doesn't need code
+   evidence, just doc-vs-`.em` reading. Narrative sections (Intent, Open Questions, notes)
+   count too when the contradiction is unambiguous — a stale sentence that flatly contradicts
+   the `.em` is an internal inconsistency; a vague or interpretable one is not a finding.
+
+Do this for every in-scope slice before moving on to diffing. The evidence you record here is
+what every finding in the report will cite — file paths, not vibes.
+
+### 3. Deterministic diff
+
+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, 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
+against the codebase.
+
+Then run `em diff <model-name>.em <model-name>-asis.em --json`. `em`, not you, decides what
+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.
+
+### 4. Classify
+
+Every finding — structural deltas from step 3, plus spec- and internal-surface findings from
+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).
+- **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
+structural findings) — a finding with no citation isn't ready to report.
+
+### 5. Report + proposals
+
+Write `conformance/<YYYY-MM-DD>-report.md` in the model directory, from
+`templates/conformance-report.md`. For a real-drift or model-gap finding, propose a
+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
+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`.
+
+End of run: update the state file's `Last conformance:` marker, exact format:
+
+```
+- **Last conformance:** YYYY-MM-DD @ <target-repo revision> — report: conformance/YYYY-MM-DD-report.md
+```
+
+The revision is the one you just diffed against, so the next run's scope starts from here —
+step 1 parses this line, so keep the format exact. If any proposals were ratified and applied,
+log a Decisions entry noting what changed and why.
+
+## Conventions
+
+- **Scratch model:** `<model-name>-asis.em`, written **next to** the canonical model (same
+  directory as `.event-modeling.md`). Always seeded as a copy of the canonical model with only
+  the in-scope slices rewritten (step 2), never built up from nothing. It's regenerated every
+  conform run — add the pattern `*-asis.em` to the repository's `.gitignore` (create the entry
+  if there isn't one) so it never gets committed.
+- **Report location:** `conformance/<YYYY-MM-DD>-report.md` in the model directory. One file
+  per run; don't overwrite a prior date's report.
+- **Red note wording:** `issue "conformance: <what's wrong, plainly>"` — plain enough that
+  whoever ratifies it later understands the claim without re-reading the report.
+- **Naming/matching rules:** same past-tense-event / imperative-command / thing-shown-view
+  naming discipline as the rest of the skill (`methodology.md`'s Socratic stance) — you're
+  matching code to existing names here, not inventing new ones except for genuinely uncovered
+  behavior.
+
+## Completion & handoff
+
+Conform is complete when: every in-scope slice has been walked (step 2), the scratch model has
+been diffed (step 3), every finding is classified with cited evidence (step 4), the report is
+written (step 5), the state file's `Last conformance:` marker is updated, and the user has seen
+the report and said which proposals (if any) to apply. Applied proposals get re-rendered and
+re-validated before you call the run done.
+
+Conform doesn't chain to another phase automatically — it's a recurring loop, not a step in
+building the model. Suggest running it again next time the target codebase has moved, at
+whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
+
+## Anti-patterns
+
+- **Blind extraction** — deriving the as-is scratch model with no sight of the canonical
+  model's vocabulary. Loses the anchor and produces naming-driven false drift.
+- **A scratch model holding only the in-scope slices** — `em diff` reads every omitted
+  canonical slice as removed, so a diff-scoped run drowns in phantom removals. Seed from the
+  canonical model and rewrite only the slices you walked.
+- **Reporting uncertainty as drift** — "I couldn't find the enforcement site" is an
+  uncertainty, never a finding against the model.
+- **Editing the model or a slice doc without ratification** — conform proposes; the user
+  applies. No exceptions, even for an "obviously correct" fix.
+- **Treating scenario/test absence as a build failure** — a missing test site is a spec-surface
+  finding to report and classify, not a reason to stop the run or block anything. Conform is
+  advisory; there's no gate here.
+- **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.

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

@@ -64,9 +64,10 @@ arrow From Element -> To Element    # explicit cross-slice edge (overrides infer
 - **`again`** (views only): `view <Name> again [from "Event", …]` declares a later instance of an
   already-declared read model — the forward-only device for a view that evolves as later events
   land. Instances are ONE logical view: the first declaration owns the `note` binding; each
-  instance's `from` lists only the NEW events landing at that point (not cumulative); instances are
-  linked left-to-right with a continuity arrow; a reaction (`from "View"`) reads the nearest
-  instance at-or-before its own slice. `again` with no earlier declaration is a validation error.
+  instance's `from` lists only the NEW events landing at that point (not cumulative); a reaction
+  (`from "View"`) reads the nearest instance at-or-before its own slice. Instances are NEVER
+  connected to one another — continuity is implied by the shared name, and the events reaching each
+  instance are what show the view changing. `again` with no earlier declaration is a validation error.
   Use `again` (not a plain repeated `view` name) whenever the view is referenced by a
   `from`/`arrow` — plain repeats are only warning-free while unreferenced.
 - **`note "path.md"`** on ANY element links a markdown doc. Relative to the `.em` file. Renders as
@@ -106,7 +107,7 @@ slice "Open Orders" {
   ui Order List @Customer
 }
 
-# 3. Automation: split across TWO slices
+# 3. Automation: split across TWO slices (plus the read slice that consumes the event)
 slice "Orders To Fulfill" {
   view Orders To Fulfill from "Order Placed"
   processor Fulfillment Service
@@ -115,6 +116,10 @@ slice "Ship Order" {            # the triggered command goes in the NEXT slice
   command Ship Order
   event Order Shipped @Shipping
 }
+slice "Open Orders — shipped" {
+  view Open Orders again from "Order Shipped"   # every event needs a reader
+  ui Order List @Customer                       # ...and every read model needs a consumer
+}
 
 # 4a. Translation (external trigger): external input -> translation -> command -> event
 slice "Carrier Webhook" {
@@ -124,8 +129,17 @@ slice "Confirm Delivery" {            # the triggered command goes in the NEXT s
   command Confirm Delivery
   event Delivery Confirmed @Shipping
 }
+slice "Open Orders — delivered" {
+  view Open Orders again from "Delivery Confirmed"
+  ui Order List @Customer
+}
 
 # 4b. Translation (internal trigger): read model -> translation -> command -> event
+slice "Accept Quote" {
+  ui Quote Screen @Customer     # every command needs a trigger: a ui, or a reaction before it
+  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
@@ -134,40 +148,66 @@ slice "Record Sync" {
   command Record Crm Sync
   event Quote Synced @Quote
 }
+slice "Accepted Quotes — synced" {
+  view Accepted Quotes again from "Quote Synced"
+  ui Sync Status @Customer
+}
 ```
 
 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.
 
+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
+exists. Reactions don't count — they read *views*, not events.
+
 ### Headless / API systems (no UI) & repeated read models
 
 When the system is headless (no UI — clients call an API), drop `ui`/`persona` entirely:
 
+A slice body is always multi-line — there is **no one-line `slice "X" { … }` form**, and writing
+one is a parse error (`'slice' is not valid inside a slice`).
+
 ```em
 # Write: external translation -> command -> event (name the inbound adapter for the caller/role)
-slice "Create Quote (request)" { translation SalesRep BU Create Quote }
-slice "Create Quote"           { command Create Quote  event QuoteCreated @Quote }
+slice "Create Quote (request)" {
+  translation SalesRep BU Create Quote
+}
+slice "Create Quote" {
+  command Create Quote
+  event QuoteCreated @Quote
+}
 
-# Read: event(s) -> read model -> READ translation (the external caller's API query, replaces UI)
-slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation SalesRep BU Read Quote }
+# Read: event(s) -> read model -> READ translation (the external caller's API query, replaces UI).
+# This slice is also what makes QuoteCreated a *read* event — without it the model warns.
+slice "Read Quote — created" {
+  view Quote from "QuoteCreated"
+  translation SalesRep BU Read Quote
+}
 ```
 
 - A **read translation triggers no command** (it returns data outbound) — it is the headless analog
   of `view → ui`, *not* a reaction. Only *reaction* translations/processors trigger commands. A read
   slice has no `command` and no `event`, so `em validate` stays quiet about it.
-- **Repeat the read model** in every slice where it's read so the timeline flows left-to-right.
-  Recurring `view`/`translation` names **render cleanly and stay warning-free** as long as nothing
-  references the repeated name via `from`/`arrow` (the duplicate-name warning fires only for a
-  *referenced* duplicate, resolving to the first). **Wire each event to a read model exactly once:**
-  a repeated instance's `from` lists only the **new** events since the previous instance (not
-  cumulative), or the event draws a duplicate arrow to the same read model at every repeat. (An
-  event may still feed several *different* read models, once each.) When a repeated view **must be
-  referenced** — e.g. a reaction reads it via `from` — declare its later instances with
-  `view X again` instead (see Clauses); instances resolve properly and draw continuity arrows.
+- **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). `again` instances are
+  exempt from the duplicate-name warning even when referenced, and each reference resolves to the
+  right instance — a plain repeat only stays warning-free while nothing references it by name, and
+  resolves to the *first* declaration when something does. **Wire each event to a read model exactly
+  once:** a repeated instance's `from` lists only the **new** events since the previous instance
+  (not cumulative), or the event draws a duplicate arrow to the same read model at every repeat. (An
+  event may still feed several *different* read models, once each.)
+- **Instances are never joined to one another.** No arrow between two instances of one read model,
+  ever — an explicit one is a validation error. The repeat is a timeline device: continuity is
+  implied by the shared name, and the events arriving at each instance are what show it changing.
 - **Keep arrows span-1: put each repeat right after its feeding event.** Place a read-model instance
-  immediately after the event that updates it, sourcing only that single adjacent event. A read
-  model far from its source events draws long arrows that cross the read-model row and read as
-  read→read (an Event Modeling violation) — repeat the read model next to each event instead.
+  immediately after the event that updates it, sourcing only that single adjacent event. The
+  renderer routes a long arrow *around* intervening boxes rather than through them, so it no longer
+  reads as a forbidden read→read link — but distance is still a real problem: the arrowhead lands
+  columns away from the event that produced it, so **the write slice reads as dangling**, as if
+  nothing consumed its event. You have to trace a line across the diagram to see the connection.
+  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)
 
@@ -197,20 +237,33 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
    there), a reaction reading a view before any instance of it exists, or an explicit backward
    `arrow`.
 6. **`again` without an earlier declaration** — declare the view plainly the first time it appears.
+7. **Illegal connection** — an `arrow` joining kinds the patterns don't connect. Only
+   `ui -> command`, `command -> event`, `event -> view`, `view -> ui`, `view -> reaction`, and
+   `reaction -> command` are allowed. A command straight to a view is the CQRS violation (an event
+   has to sit between them); a view straight to a command needs a reaction between them; and two
+   instances of one view are never connected at all. Inferred edges are always legal, so this only
+   ever fires on a hand-written `arrow`.
 
 **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. **Command without event** — every command should record at least one event.
-3. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
-4. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
-5. **Open issue** — an element carries `issue "text"`; resolve the question, then remove the
+2. **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 (4): a command nothing points at is a write nobody can start.
+3. **Command without event** — every command should record at least one event.
+4. **Event nobody reads** — the mirror of (3): 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.
+5. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
+6. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
+7. **Open issue** — an element carries `issue "text"`; resolve the question, then remove the
    clause. `em validate --list-issues` prints just these; `--fail-on-issues` (opt-in) makes CI
    fail while any remain open.
-6. **View field with no source** — a `view` field whose name matches no field on any instance
+8. **View field with no source** — a `view` field whose name matches no field on any instance
    of its source events. Only checked once BOTH the view and at least one source event declare
    `{ fields }`.
-7. **Event field not from a command** — an `event` field whose name matches no field on any
+9. **Event field not from a command** — an `event` field whose name matches no field on any
    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.
@@ -218,6 +271,20 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
 **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 `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.
+- **Every `view` has a consumer.** A `ui` in its slice, a reaction watching it, or (headless) a read
+  translation. Every *instance* of a repeat, not just the last — a bare `view X again` slice is a
+  half-slice, not a State View.
+- **Only six connections are legal**, and only these are ever inferred:
+  `ui → command`, `command → event`, `event → view`, `view → ui`, `view → reaction`,
+  `reaction → command`. Anything else in an explicit `arrow` is an error — above all
+  `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