@milehimikey/em 1.8.0 → 1.9.0

package/.claude/skills/{event-modeling → event-modeling-conform}/reference/conform.md

@@ -3,7 +3,8 @@
 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
+(the `event-modeling-discover` skill's `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.
 
@@ -33,7 +34,7 @@ difference is what you do with what you find: extract *builds* a model from the
 ## Preconditions
 
 1. A canonical `.em` model with a state file (`.event-modeling.md`), reachable the same way the
-   SKILL.md preconditions locate it.
+   shared preconditions locate it — see `../../event-modeling-shared/reference/operating-principles.md`.
 2. The slices you're about to check should be **implemented** — docs at `status: 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 — ratified or
@@ -57,11 +58,19 @@ named invariants, Given/When/Then scenarios). Conform checks all three surfaces
 |---|---|---|---|
 | **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 frontmatter (`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** — slice doc ↔ `.em` | the doc's frontmatter `pattern:` or its Command/Event/Read Model sections and field tables disagreeing with the model's own elements/fields | `em` (deterministic) | `em validate`'s `doc-model-*` diagnostics, unconditionally in the default list |
+
+The internal surface is deterministically checked by `em validate` itself (MIL-124) — four
+diagnostics, always on, no flag needed: `doc-model-pattern-mismatch` (frontmatter `pattern:` vs.
+the model's own classification), `doc-model-element-not-in-model` / `doc-model-element-not-in-doc`
+(the doc's Command/Event/Read Model markers vs. the slice's actual elements, each direction), and
+`doc-model-field-mismatch` (a matched Command/Event's field table vs. the model's `{ fields }`
+block). Run `em validate <model-name>.em --json` and read each entry's `code`/`refs`/`message`
+(`docs/validation.md#doc-model-consistency` documents exactly what each one checks and
+when it stays silent — every rule is declare-gated, so a thin/draft doc doesn't nag); consume it
+the same way step 3 below consumes `em diff --json` — parse the structured findings, don't
+re-derive them by eye. Fold any that fire for an in-scope slice into that slice's internal-surface
+findings for step 4's classification, citing the diagnostic directly as the evidence.
 
 **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
@@ -171,11 +180,13 @@ For each slice in scope:
    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.
+4. Read the in-scope slice's `doc-model-*` findings straight off the `em validate --json` run
+   from precondition 4 (or re-run it here) — no code evidence needed, `em` already did the
+   doc-vs-`.em` comparison for frontmatter `pattern:` and the Command/Event/Read Model rosters
+   and field tables. The only judgment left on this surface is narrative sections `em validate`
+   can't parse (Intent, Open Questions, notes): count a contradiction here too when it's
+   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.
@@ -229,7 +240,7 @@ 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
+`../../event-modeling-shared/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
@@ -253,6 +264,21 @@ the marker (nobody ratified the outcome), so the next run re-walks the same span
 `docs/ci.md`. If any proposals were ratified and applied, log a Decisions entry noting what
 changed and why.
 
+**Superseding the report you just walked (MIL-164).** Once the user has ruled on this run's
+findings, also run:
+
+```
+em conform-supersede <model-name>.em conformance/YYYY-MM-DD-report.md --as-of <target-repo revision> --findings <spec>
+```
+
+— stamping the report with a "superseded as of `<rev>`" banner so a later reader who finds it
+(a search hit, a bookmark, a link from an old PR description) sees immediately that its
+file:line citations describe an ancestor of the current model, not its current state. This is
+what keeps a superseded report an honest piece of history rather than a silently-misleading
+current view. `<spec>` names the finding number(s) this run's ruling covers (e.g. `"1-3"`); if
+only some findings were ruled on this session, run it again later with the remaining numbers —
+each call adds its own stamp rather than overwriting the last.
+
 ## Conventions
 
 - **Scratch model:** `<model-name>-asis.em`, written **next to** the canonical model (same

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

@@ -0,0 +1,139 @@
+---
+name: event-modeling-design
+em-version: 1.9.0
+description: >-
+  Use when structuring a draft event model into swimlanes and the four patterns (State Change,
+  State View, Automation, Translation), evaluating a model's structural completeness, or writing
+  implementation-ready deep slice documents (field tables, invariants, Given/When/Then scenarios,
+  error flows) for a model that already has its happy-path spine. Drives `em`'s model and slice
+  phases — the core modeling work between discovery and implementation.
+---
+
+# Event Modeling — model & slice
+
+You are facilitating the core modeling work: turning a draft happy-path spine into a
+structurally complete, validated model, and then a deep implementation-ready spec per slice.
+Your job is to **extract an accurate model from the user through Socratic questioning** — never
+to invent the domain. You drive the `em` CLI to render the model live, and you produce
+implementation-ready slice docs.
+
+Read `../event-modeling-shared/reference/operating-principles.md` (preconditions, project
+layout, the Socratic/validation discipline every phase follows) and
+`../event-modeling-shared/reference/methodology.md` (the 7 steps + 4 patterns) before doing real
+work — they are the source of truth. Run the preconditions there first: this phase expects a
+draft model already exists (from `event-modeling-discover`'s `discover` or `extract` phase).
+
+## Phase: `model` — steps 5-7
+
+Goal: a structurally complete, **validated** model with correct patterns and swimlanes.
+
+1. **Swimlanes & patterns (step 5).** Group events into **contexts** (bounded contexts /
+   aggregates) — ask which events share a consistency boundary and who owns them. Classify each
+   slice as one of the 4 patterns. **Share the slice between every automation or translation and
+   the command it triggers** (the reaction — processor/translation — together with the command
+   and event it produces; the read model it watches, if any, stays in the slice before). A
+   translation or automation is a reaction: it **triggers a command and never records an event
+   directly**. Add `translation` slices for external inputs (externally triggered: external →
+   translation → command → event, no slice before) and for the system reacting to its own state
+   (internally triggered: read model in the slice before → translation → command → 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
+   below.)
+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 every automation **and** translation triggers a command (none
+   wired straight to an event, none with no command at all). Run `em validate` and resolve all
+   errors and warnings — it catches a reaction wired straight to an event too now (see
+   `../event-modeling-shared/reference/em-dsl.md`), so a clean run covers this case.
+   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 (`em state set-phase slice`), continue with the `slice` phase
+below to write implementation specs.
+
+## Phase: `slice` — deep slice documents
+
+Goal: implementation-ready specs. Go slice by slice (let the user pick order, or follow the
+timeline). Check `README.md`'s Slices table for what's already done (run `em slice index
+<model-name>.em` first if it looks stale).
+
+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. **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:
+0. **Check for re-ratification first.** If `slices/<slice-name>.md` already exists with
+   `status: implemented`, this is a re-ratification, not fresh authoring: hold a Socratic
+   deep-dive on what changed (same rigor as step 1, scoped to the delta), update whichever
+   sections actually changed, then express the change as the `## Delta` section — fixed heading,
+   `### Added`/`Modified`/`Removed`/`Renamed` Requirement blocks each carrying its own scenarios
+   (see `../event-modeling-shared/templates/slice.md` and
+   `docs/slice-doc-schema.md#delta-section-grammar-and-lifecycle`)
+   — **overwriting** whatever the section held before, never appending to it. Then continue at
+   step 2 to bump `version` and flip `status` back to `ready-to-implement`, leaving
+   `implementedIn` naming the prior version's PR (intended drift signal, not a bug — see the
+   schema doc). Otherwise, this is first-time authoring: continue at step 1.
+1. Hold a Socratic deep-dive to fill every section of `../event-modeling-shared/templates/slice.md`:
+   intent, trigger/actor,
+   command + field table (types & rules), event(s) + payload (mark immutable facts), invariants
+   (give each a stable ID), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
+   alternate/error flows (retries, idempotency, compensations), non-functional requirements
+   (security/authz, PII/compliance, performance/SLA), read models affected, open questions. Park
+   anything unresolved rather than guessing. If the slice lives in an existing codebase, Grep/Read
+   adjacent real sources (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling
+   contexts) before finalizing field names/types or invariants — don't guess a shape that's
+   already defined elsewhere.
+2. **First-time authoring:** scaffold the doc mechanically rather than hand-writing the
+   frontmatter — `em slice new "<slice name>" --pattern <state-change|state-view|automation|
+   translation> --swimlane "<Persona> → <Context>" --wire <model>.em` writes `slices/<slice-name>.md`
+   (kebab-cased to match, via the same slugging `em` uses everywhere else) with the canonical
+   `schemaVersion`/`pattern`/`swimlane`/`status: draft`/`version: 1` frontmatter — exactly the
+   five keys `em export` and the readiness gate require, no more — and the `# Slice:` heading +
+   diagram-image stub already in place. `--wire` also inserts the `note
+   "slices/<slice-name>.md"` line straight into the `.em`, onto the slice's primary element (the
+   command for State Change, the view for State View, the processor for Automation, the
+   translation for Translation), matched by export key — see step 4 for when it refuses instead.
+   Both `--pattern` and `--swimlane` are required; an invalid `--pattern` is refused with the
+   valid choices listed. Never hand-type this block, and never fall back to a placeholder
+   pattern/swimlane to dodge the flags. Then fill in every judgment section below the stub from
+   step 1 (Intent, Command, Event(s), Invariants, Scenarios, ...) — the doc's prose is still
+   entirely hand-authored, only the frontmatter/heading scaffold and the `.em` wiring are
+   mechanized. Record the originating need (ticket/conversation link) in the Intent section when
+   one exists. When this doc exists because of a split, merge, or rename, add the matching
+   lineage key(s) by hand (`split-from`/`merged-from`/`superseded-by`, `<slice-key>@v<N>` grammar
+   — see `docs/slice-doc-schema.md` for the full schema; `em validate` catches a malformed one
+   after the fact, see the `lineage-*` rules below).
+   **Re-ratification (step 0):** the doc already exists, so `em slice new` doesn't apply here
+   (it refuses to overwrite an existing file without `--force`, and forcing would blow away the
+   doc's authored body) — run `em slice reratify <model>.em <slice-key>` instead: it bumps
+   `version` and flips `status` back to `ready-to-implement` in the existing frontmatter,
+   clearing any stale `ratifiedBy:`/`ratifiedOn:` from the prior version so a follow-up
+   `em slice ratify --by <name>` (if the team records that) applies cleanly.
+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 and the `![Diagram]` stub
+   `em slice new` already wrote) — redraws just this slice in its own canonical pattern shape.
+4. Confirm it's wired into the `.em`: `em slice new --wire` (step 2) already inserted the `note
+   "slices/<slice-name>.md"` line onto the slice's primary element's own declaration line — it
+   only ever edits that one line, and only when doing so is unambiguous, so it refuses (writing
+   NEITHER the doc nor the `.em` edit) rather than guess when the slice has zero or more than one
+   candidate element of the primary kind, or when that line already carries a `note` clause. On a
+   refusal, re-run step 2 without `--wire` — it prints the exact line to add, paste it onto the
+   slice's primary element by hand.
+5. Run `em slice index <model-name>.em` to regenerate `README.md`'s Slices table — the one
+   canonical slice index — from the model and the doc frontmatter you just wrote (status,
+   `implementedIn` once shipped). Never hand-edit the table; it's a generated block.
+6. Re-render and `em validate`.
+
+When a slice is **ratified** — a human flips its `status` to `ready-to-implement` with every
+open question resolved — it's ready to hand to an implementer. Confirm with
+`em validate <model>.em --slice-ready <key>`, and point whoever (or whatever) implements it
+at the `event-modeling-implement` skill.
+
+End of phase: every slice that should exist has a doc, `README.md`'s Slices table is current,
+and the model validates clean. Suggest `event-modeling-implement` for each ratified slice.

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

@@ -0,0 +1,89 @@
+---
+name: event-modeling-discover
+em-version: 1.9.0
+description: >-
+  Use when starting a brand-new event model from scratch — greenfield discovery: brainstorming
+  past-tense events, storyboarding the happy path, finding the commands and read models — or when
+  extracting a current-state model from an EXISTING codebase or system (event-driven or
+  procedural). Drives `em`'s discover and extract phases; produces a draft or as-is `.em` model
+  ready for the model/slice phases (`event-modeling-design`).
+---
+
+# Event Modeling — discover & extract
+
+You are facilitating the start of an Event Modeling session. Your job is to **extract an
+accurate model from the user through Socratic questioning** — never to invent the domain. You
+drive the `em` CLI to render the model live.
+
+Read `../event-modeling-shared/reference/operating-principles.md` (preconditions, project
+layout, the Socratic/validation discipline every phase follows) and
+`../event-modeling-shared/reference/methodology.md` (the 7 steps + 4 patterns) before doing real
+work — they are the source of truth. Run the preconditions there first.
+
+**Existing system?** Use the `extract` phase below. **New feature inside an existing codebase,
+not a whole-system extraction?** Stay in `discover`, but before locking in command/event names,
+Grep/Read adjacent real sources (OpenAPI specs, DB migrations, existing DTOs/event classes in
+sibling contexts) rather than guessing conventions — same check the `slice` phase applies to
+field tables (`event-modeling-design`).
+
+## Phase: `discover` — steps 1-4
+
+Goal: a draft model of events, storyboard, commands, and views. Loose is OK; structure comes next.
+
+1. **Brainstorm events (step 1).** Ask the user to name everything that happens, as past-tense
+   facts. Probe for missed state changes. For each candidate, apply the **"is it an event?"
+   test** (`methodology.md` step 1 — the "would this wake the CEO at 3am" heuristic):
+   reject derived values (belong in a read model) and telemetry/activity (not business state).
+   Don't silently drop rejections — park them in the state file's Decisions log with why, so
+   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 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 `methodology.md`).
+3. **Inputs (step 3).** For each event, find the **command** that causes it (imperative name).
+   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 that triggers it, also in this slice. 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), 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 `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 — run `em state set-phase model` rather than hand-editing `Current
+phase:`), and run `em slice index <model-name>.em` to seed `README.md`'s Slices table (every
+slice already reads "no doc yet" — no slice docs exist until the `slice` phase writes them).
+Tell the user they can stop here and resume with `/event-modeling` (or invoke
+`event-modeling-design` directly).
+
+## Phase: `extract` — current-state model of an existing system
+
+Goal: a faithful **current-state** model extracted from an existing system — the as-is sibling
+of `discover` (it replaces discover; the model then proceeds to `model` as usual, in
+`event-modeling-design`).
+
+**Read `reference/extract.md` before doing any extract work** — it carries a stance override
+that inverts methodology step 1 (capture how the system behaves *today*; never model desired
+state).
+
+- Two source modes, detected from the system itself and confirmed with the user:
+  **event-driven** (an event vocabulary already exists — schemas, topics, handlers) and
+  **procedural/monolith** (no event vocabulary — synthesize candidate events from behavior
+  and docs).
+- Converge via a ~7-round confirm-and-clarify loop (one concern per round; render from round 2,
+  validate from round 4 — see the playbook).
+- **Current-state-only:** park unknowns as `# TBD` comments in the `.em`, mirrored in the state
+  file's Open Questions — never guess intended design.
+
+End of phase: validated as-is model; state file updated (source mode, rounds, decisions; `em
+state set-phase model` for `Current phase:`); run `em slice index <model-name>.em` to seed
+`README.md`'s Slices table; then hand off to `event-modeling-design` (steps 5-7).

package/.claude/skills/{event-modeling → event-modeling-discover}/reference/extract.md

@@ -23,8 +23,9 @@ reaction-shares-a-slice-with-its-command shape — still applies.
 
 ## Setup
 
-1. Run the SKILL.md preconditions (tool check, model location). If no model exists yet, run
-   `em scaffold <model-name>` (see SKILL.md's "Project layout this skill creates").
+1. Run the shared preconditions (tool check, model location) — see
+   `../../event-modeling-shared/reference/operating-principles.md`. If no model exists yet, run
+   `em scaffold <model-name>` (see that doc's "Project layout this skill creates").
 2. **Agree the scope line first**: which system, which part, what's out of bounds. Write it to
    the state file's Session inputs.
 3. Record in the state file: `Source mode` (after detection, below) and

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

@@ -0,0 +1,40 @@
+---
+name: event-modeling-implement
+em-version: 1.9.0
+description: >-
+  Use when building a single ratified event-modeling slice (status: ready-to-implement) into
+  merged, tested code — the one phase where the agent builds rather than facilitates. Gates on
+  readiness, treats the slice doc as the read-only spec, surfaces gaps instead of deciding them
+  silently, and requires tests traceable to the doc's invariants and scenarios.
+---
+
+# Event Modeling — implement
+
+Goal: turn a single `ready-to-implement` slice into merged, verified code — the one phase where
+the agent builds rather than facilitates.
+
+**Read `reference/implement.md` before doing any implement work and follow it as the
+contract.** In short: gate on `em validate <model>.em --slice-ready <key>` (stop and hand
+back if it fails — never edit the doc to make the gate pass); treat the slice doc as the
+spec (read-only, except the merge-time `status`/`implementedIn` flip); surface every gap to
+the user instead of deciding it silently; cover every `INV-<MNEMONIC>-n` and every scenario with
+tests; in spec-kit projects, allocate via em-sdd-bridge (redirect mode) and never run
+`/speckit.specify`.
+
+That contract applies to any implementing agent, whether or not the session started from
+`/event-modeling` — `em contract` prints it to stdout with no `.claude/` awareness required, for
+an agent that can run a shell but isn't Claude Code.
+
+If the project ships pattern-specific implementation skills (for example an Axon/DCB skill set
+keyed on a slice doc's `pattern:` frontmatter), route by the slice's pattern and follow those —
+`reference/implement.md` §2 explains where that hand-off happens.
+
+Preconditions (tool check, model location) are the same as every other phase — see
+`../event-modeling-shared/reference/operating-principles.md` — but this phase additionally
+requires the target slice to already be ratified; if it isn't, stop and say so rather than
+starting on unratified work.
+
+End of phase: PR merged, slice doc flipped to `status: implemented` with `implementedIn`
+filled, `em slice index <model-name>.em` run to refresh `README.md`'s Slices table. Implement
+doesn't chain to another phase — run it once per ratified slice; `event-modeling-conform`'s
+`conform` phase later checks the result against the model.

package/.claude/skills/{event-modeling → event-modeling-implement}/reference/implement.md

@@ -126,7 +126,7 @@ resolves the doc via the same note-binding join `--slice-ready` uses, is idempot
 with the same URL, and refuses (never silently overwrites) if the doc is already `implemented`
 with a different URL. Prefer it over hand-editing the doc's frontmatter.
 
-Then, if the project keeps a model README (from `templates/model-readme.md`), run
+Then, if the project keeps a model README (from `../../event-modeling-shared/templates/model-readme.md`), run
 `em slice index <model-name>.em` so its generated Slices table reflects the new status and
 link — never hand-edit that table. The `implementedIn` link is what the `conform` phase later
 uses to anchor drift-checking — leaving it empty blinds the loop.
@@ -179,6 +179,7 @@ everything a spec holds. Don't introduce an intermediate spec document of your o
 
 Implementation isn't the end of the slice's story. On a cadence — or whenever someone asks —
 the `conform` phase checks implemented slices against the code, using the `implementedIn` link
-you recorded, and reports drift for humans to rule on (see `reference/conform.md`). Your two
+you recorded, and reports drift for humans to rule on (see the `event-modeling-conform` skill's
+`reference/conform.md`). Your two
 duties to that future loop are already behind you if you followed this doc: an accurate
 lifecycle flip, and zero silent decisions.

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

@@ -0,0 +1,58 @@
+---
+name: event-modeling-review
+em-version: 1.9.0
+description: >-
+  Use when starting em's live browser viewer (`em watch --serve`) so a team can watch a model
+  update in real time, or facilitating a SCHEDULED stakeholder walkthrough that steps through
+  slices one at a time in Review mode, capturing anything the room raises live as `issue "..."`
+  red notes. Drives `em`'s watch and review phases.
+---
+
+# Event Modeling — watch & review
+
+## Phase: `watch` — live team view
+
+Start the watcher with `--serve` in the background:
+`em watch <model-name>.em -o <model-name>.svg --serve` (run_in_background). It re-renders on every
+save and pushes an instant reload to the browser over Server-Sent Events. Tell the user to open the
+URL it prints (e.g. `http://localhost:5173/?svg=<model-name>.svg`) and share their screen — updates
+appear the moment you save, with no polling and no idle churn between edits.
+
+The viewer navigates like a map — drag to pan, scroll/pinch to zoom, **Fit** to reset — and its
+**Review mode** steps through slices one at a time (see the `review` phase below). A save that
+fails to render never blanks the shared screen: the last good diagram stays up, an error banner
+explains what went wrong, and the viewer recovers on its own at the next successful render.
+
+## 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 `event-modeling-conform`
+uses for any other issue. 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 run `em state set-review <date>` to set the `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.
+
+Preconditions (tool check, model location) are the same as every other phase — see
+`../event-modeling-shared/reference/operating-principles.md`.